D2Sphere Key / Value Mapping Parser Specification

Introduction

Devices send key-value data in the format described here.

These data, even if following some special format definitions, come in in a typeless form. To visualize these data in the frontend, one of the key features of the mapping engine is to define the underlying format of the incoming data, e.g. key1="1.23" would suggest the type DOUBLE as the mapping type inside a mapping definition. Attaching a human readable name is another benefit from the mapping. So properly named in the mapping definition a key as e.g. _temp could be mapped to a more readable form as temperature.

The most interesting feature comes in with the description of an optional formula, which can convert any incoming values and formats on-the-fly to more meaningful values. The underlying framework used for these calculations is mXparser. D2Sphere uses a more or less the complete subset out of these features, even that some format restrictions come into place.

Specification

• The outgoing key can be named differently from the incoming one, e.g. _accl_x vs. formula $[N(0)]_accl$ * 10;
• Incoming values need to be encapsulated inside $-signs to avoid clashes with predefined mXparser keywords
• Incoming values need to be marked with a type, as there are [N]-number, [H]-hex, [B]-Boolean
• Parts of vector values can be accessed by adding brackets followed by an index to the format description, e.g. [N(0)] or [H(1)]

Restrictions

Even if the incoming value (or parts of it in case of a vecotr) can be used more than once inside the same formula, there is currently no support for different incoming values inside one formula!

Examples

incoming key: _temp (contains values in numerical format, e.g. 1.230)
outgoing key: _temp
outgoing name: Temperature
outgoing type: Double
Unit: °C
formula:

incoming key: _accl (contains values in the format e.g. [0.1, 1.1, 0.5])
outgoing key: _accl_sum
outgoing name: Acceleration (resulting)
outgoing type: Double
Unit: g
formula:

sqrt($[N(0)]_accl$^2+$[N(1)]_accl$^2+$[N(2)]_accl$^2)

incoming key: _ble_temp (contains values in hexadecimal format e.g. A2F8)
outgoing key: _ble_temp_puck
outgoing name: Temperature PUCK
outgoing type: Double
Unit: °C
formula:

if(($[H]_ble_B00BDB_temp$@&H.00FF) < H.0080 , ((($[H]_ble_B00BDB_temp$@&H.00FF)@<<8)+(($[H]_ble_B00BDB_temp$@&H.FF00)@>>8))/100 , ((($[H]_ble_B00BDB_temp$@&H.00FF)@<<8)+(($[h]_ble_B00BDB_temp$@&H.FF00)@>>8)-H.FFFF)/100)

$<sfal.data key1='value1' key2='value2' keyX='valueX'>" CRLF
$GPRMC CRLF (optional)
$ .... CRLF (optional)
$<end> CRLF