Skip to main content

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.

NumberNameLengthDescription
0Param value>=2Response to the "Get params" command. The first byte is the param number, the rest are the value.
1Sensor data>=1Sensor data.
2Battery level1Battery level in 10mV steps from 2V (0 = 2V, 255 = 4.55V).
3Battery Percent1Battery level in percent (0 to 100).
4Event data>=1Event 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:

NumberNameLengthDescription
0 (0x00)unknown0No data.
1 (0x01)gps1 or 11GPS coordinates.
2 (0x02)temp1 or 2 or 4Temperature in degrees Celsius.
3 (0x03)humi1 or 2 or 4Relative humidity in %RH.
4 (0x04)pressure4Barometric pressure in hPa.
5 (0x05)pm104PM10 Concentration in μg/m3.
6 (0x06)pm2.54PM2.5 Concentration in μg/m3.
7 (0x07)tvoc4VOC Concentration in ppb.
8 (0x08)no24Nitrogen Dioxide Concentration in ppm.
9 (0x09)co24Carbon Dioxide Concentration in ppm.
10 (0x0a)airFlow4Air Flow Rate (Wind Speed) in m/s.
11 (0x0b)voltage1 or 2 or 4Voltage in V.
12 (0x0c)current1 or 2 or 4Electric Current in A.
13 (0x0d)power1 or 2 or 4Electric Power in W.
14 (0x0e)powerUsage4Electric energy usage in kWh.
15 (0x0f)waterUsage4Water usage in Kilolitres.
16 (0x10)speed4Movement Speed in m/s.
17 (0x11)rotation4Rotational speed in RPM.
18 (0x12)counter4A generic counter in a 32-bits unsigned value.
19 (0x13)digital1A generic digital value.
0: Low or OFF, 1: High or ON, -1 Unknown or Invalid.
20 (0x14)percent1A generic value in percent.
21 (0x15)powerFactor2 or 4Power factor for AC power system.
Value range from 0 to 1.
254 (0xfe)uplinkPower1Exact value of TX Power in dBm.

GPS data format#

When data length is 1

OffsetLengthDescription
01Indicates 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

OffsetLengthDescription
01$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
14Latitude in 1/1000 of minutes, as little-endian int32. Positive is north, negative is south. To get the value in degrees, divide by 600000.
54Longitude in 1/1000 of minutes, as little-endian int32. Positive is east, negative is west. To get the value in degrees, divide by 600000.
92Altitude above geoid mean sea level in decimeters (0.1m), as little-endian int16.

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.

NumberNameLengthDescription
0 (0x00)unknown0No data.
11 (0x0b)opened1The unit is opened by a user. Data is the user ID.
12 (0x0c)specialOpened0The unit is opened in a special way. For example, a key or button.
13 (0x0d)forceOpened0The 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.

NumberNameLengthDescription
0Get params1Get parameter described by first byte.
1Set params>=2Set parameter described by first byte to the value specified in the rest of the message.
2Reboot0Reboot the node immediately.
3Reboot/upgrade1Reboot 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
4Set Controls>=1Set a value to the control. For example, turn on/off a digital output.

Parameters#

NumberNameLengthDescription
0deveui6DevEUI-48 and BLE MAC address (MSBF)
Only for DevKit. Please don't use it at final product.
1appeui8AppEUI-64 (MSBF)
Only for DevKit. Please don't use it at final product.
2appkey16AppKey (write-only)
Only for DevKit. Please don't use it at final product.
3period1Sensor period
4sf1Minimal LoRa Spread Factor (valid values: 7-12)
5version2Version number.
01 00 => V1.0

Parameters 0, 1, 2 and 4 are actualized after reboot.

Sensor period is as follows:

NumberPeriod
0Default
110 sec
230 sec
31 min
42 min
55 min
610 min
730 min
81 hour
92 hours
105 hours
1112 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:

NumberNameLengthDescription
0 (0x00)unknown0No data.
19 (0x13)digital1A generic digital value.
0: Low or OFF, 1: High or ON.
20 (0x14)percent1A generic value in percent.