Payload Format
Uplink Payload Data Format#
The payload is consisting of several commands in a Type-Length-Value (TLV) format. The first byte is consisting of Type (bits [7:4]), defining the command, and Length (bits [3:0]), the length of the arguments in bytes. If the Length bits are 0xF (binary 1111), the command has its length specified in bits [5:0] of the second byte.
| Number | Name | Length | Description |
|---|---|---|---|
| 0 | Param value | >=2 | Response to the "Get params" command. The first byte is the param number, the rest are the value. |
| 1 | Sensor data | >=1 | Sensor data. |
| 2 | Battery level | 1 | Battery level in 10mV steps from 2V (0 = 2V, 255 = 4.55V). |
| 3 | Battery Percent | 1 | Battery level in percent (0 to 100). |
| 4 | Event data | >=1 | Event data |
Sensor Data#
Sensor data consists of a byte signifying the sensor type, and zero or more bytes of sensor data. The defined types and corresponding data formats are:
| Number | Name | Length | Description |
|---|---|---|---|
| 0 (0x00) | unknown | 0 | No data. |
| 1 (0x01) | gps | 1 or 11 | GPS coordinates. |
| 2 (0x02) | temp | 1 or 2 or 4 | Temperature in degrees Celsius. |
| 3 (0x03) | humi | 1 or 2 or 4 | Relative humidity in %RH. |
| 4 (0x04) | pressure | 4 | Barometric pressure in hPa. |
| 5 (0x05) | pm10 | 4 | PM10 Concentration in μg/m3. |
| 6 (0x06) | pm2.5 | 4 | PM2.5 Concentration in μg/m3. |
| 7 (0x07) | tvoc | 4 | VOC Concentration in ppb. |
| 8 (0x08) | no2 | 4 | Nitrogen Dioxide Concentration in ppm. |
| 9 (0x09) | co2 | 4 | Carbon Dioxide Concentration in ppm. |
| 10 (0x0a) | airFlow | 4 | Air Flow Rate (Wind Speed) in m/s. |
| 11 (0x0b) | voltage | 1 or 2 or 4 | Voltage in V. |
| 12 (0x0c) | current | 1 or 2 or 4 | Electric Current in A. |
| 13 (0x0d) | power | 1 or 2 or 4 | Electric Power in W. |
| 14 (0x0e) | powerUsage | 4 | Electric energy usage in kWh. |
| 15 (0x0f) | waterUsage | 4 | Water usage in Kilolitres. |
| 16 (0x10) | speed | 4 | Movement Speed in m/s. |
| 17 (0x11) | rotation | 4 | Rotational speed in RPM. |
| 18 (0x12) | counter | 4 | A generic counter in a 32-bits unsigned value. |
| 19 (0x13) | digital | 1 | A generic digital value. 0: Low or OFF, 1: High or ON, -1 Unknown or Invalid. |
| 20 (0x14) | percent | 1 | A generic value in percent. |
| 21 (0x15) | powerFactor | 2 or 4 | Power factor for AC power system. Value range from 0 to 1. |
| 22 (0x16) | accel | 4 | Acceleration in g. |
| 23 (0x17) | distance | 4 | Distance in m. |
| 254 (0xfe) | uplinkPower | 1 | Exact value of TX Power in dBm. |
GPS data format#
When data length is 1
| Offset | Length | Description |
|---|---|---|
| 0 | 1 | Indicates whether the node has moved since last GPS fix. Possible values are: 0: Node is stable since last GPS fix 1: Node has moved, or has not received a GPS fix since boot; waiting for GPS fix |
When data length is 11
| Offset | Length | Description |
|---|---|---|
| 0 | 1 | $GPGGA Position Fix Indicator. Possible values are: 0 Fix not available or invalid 1 GPS SPS Mode, fix valid 2 Differential GPS, SPS Mode, fix valid 6 Dead Reckoning Mode, fix valid |
| 1 | 4 | Latitude in 32-bits floating point number (IEEE 754). Positive is north, negative is south. |
| 5 | 4 | Longitude in 32-bits floating point number (IEEE 754). 0 at the Prime Meridian to positive eastward and negative westward. |
| 9 | 2 | Altitude above geoid mean sea level in decimeters (0.1m), as unsigned 16-bits integer (uint16_t) in big endian. |
Data format for 1 byte value#
It is a signed 8-bits integer (int8_t), giving the range between -128 and +127.
// Decodingif (offset_0 > 0x7f) { value = ((offset_0 ^ 0xff) + 1) * -1;}else { value = offset_0;}Data format for 2 bytes value#
It is a signed 16-bits fixed point number. Offset 0 is the sign bit and integer part. Offset 1 is the fractional part.
// Decoding in Javascriptlet raw_value = (offset_0 << 8) | offset_1;if (raw_value > 0x7fff) { value = ((raw_value ^ 0xffff) + 1) * -1;}else { value = raw_value;}value = value / 256;Data format for 4 bytes value#
It is a 32-bits floating point number (IEEE 754). Offset 0 is the MSB.
For example, a value of 54.12 will has a 32-bits value of 0x42587ae1.
The payload will become <0x42><0x58><0x7a><0xe1>.
// Decoding in Javascriptlet raw_value = (offset_0 << 24) | (offset_1 << 16) | (offset_2 << 8) | offset_3;let v_temp = new DataView(new ArrayBuffer(4))v_temp.setUint32(0, raw_value)value = v_temp.getFloat32(0)The NAN (Not A Number) (0x7fc00000), means the sensor value is unknown or invalid.
Event Data#
Event data is information about change that occurs at a point in time. A event will contain the type value and additional event data.
| Number | Name | Length | Description |
|---|---|---|---|
| 0 (0x00) | unknown | 0 | No data. |
| 11 (0x0b) | opened | 1 | The unit is opened by a user. Data is the user ID. |
| 12 (0x0c) | specialOpened | 0 | The unit is opened in a special way. For example, a key or button. |
| 13 (0x0d) | forceOpened | 0 | The unit is opened in a abnormal way. |
Downlink Payload Data Format#
Payload is consisting of several commands in a Type-Length-Value (TLV) format. The first byte is consisting of Type (bits [7:4]), defining the command, and Length (bits [3:0]), the length of the arguments in bytes. If the Length bits are 0xF (binary 1111), the command has its length specified in bits [5:0] of the second byte.
| Number | Name | Length | Description |
|---|---|---|---|
| 0 | Get params | 1 | Get parameter described by first byte. |
| 1 | Set params | >=2 | Set parameter described by first byte to the value specified in the rest of the message. |
| 2 | Reboot | 0 | Reboot the node immediately. |
| 3 | Reboot/upgrade | 1 | Reboot the node after the specified timeout; optionally turn BLE and SUOTA on for upgrades. The argument is as follows:bit [7]:0: just reboot1: BLE onbits [6:3]: Reservedbits [2:0]: Timeout0: TBD1: 5 minutes2: 15 minutes3: 30 minutes4: 1 hour5: 2 hours6: 4 hours7: TBD |
| 4 | Set Controls | >=1 | Set a value to the control. For example, turn on/off a digital output. |
Parameters#
| Number | Name | Length | Description |
|---|---|---|---|
| 0 | deveui | 6 | DevEUI-48 and BLE MAC address (MSBF) Only for DevKit. Please don't use it at final product. |
| 1 | appeui | 8 | AppEUI-64 (MSBF) Only for DevKit. Please don't use it at final product. |
| 2 | appkey | 16 | AppKey (write-only) Only for DevKit. Please don't use it at final product. |
| 3 | period | 1 | Sensor period |
| 4 | sf | 1 | Minimal LoRa Spread Factor (valid values: 7-12) |
| 5 | version | 2 | Version number. 01 00 => V1.0 |
Parameters 0, 1, 2 and 4 are actualized after reboot.
Sensor period is as follows:
| Number | Period |
|---|---|
| 0 | Default |
| 1 | 10 sec |
| 2 | 30 sec |
| 3 | 1 min |
| 4 | 2 min |
| 5 | 5 min |
| 6 | 10 min |
| 7 | 30 min |
| 8 | 1 hour |
| 9 | 2 hours |
| 10 | 5 hours |
| 11 | 12 hours |
Controls#
Controls are used for the user to change a value or state of the device. The control data consists of a byte signifying the data type, and zero or more bytes of the data. The defined types and corresponding data formats are:
| Number | Name | Length | Description |
|---|---|---|---|
| 0 (0x00) | unknown | 0 | No data. |
| 19 (0x13) | digital | 1 | A generic digital value. 0: Low or OFF, 1: High or ON. |
| 20 (0x14) | percent | 1 | A generic value in percent. |