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 incoming vector values can be accessed by adding brackets followed by an index to the format description

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