Payload Format
Codec
A complete LoRaWAN payload codec with examples can be found in the downloads section.
Overview
The payload of up and downlink messages consists of an arbitrary number of data structs (DS) of different types and lengths.
| DS 1 | DS 2 | ... | DS n |
|---|---|---|---|
Each data struct is a combination of a header and the actual data payload:
| L | T | payload |
|---|---|---|
The header consists of two fields:
| Field | Description |
|---|---|
| L | Length of data struct, 1 byte, not including the length byte itself |
| T | Data struct type, 1 byte |
Data Encoding
Signed integers use two’s complement for encoding.
Important
Unless otherwise noted, payloads will use little endian data encoding.
Uplink and downlink messages overview
Important
- All uplinks are sent on LoRaWAN port 15.
- All downlinks must be sent on LoRaWAN port 3.
Note
The size noted in this overview table is the absolute number of bytes sent. The lenght of the data structure, contained in the length field of the message header, is a byte less of the size of the message, as it doesn't account for the byte of the length field itself.
| Uplink message | ID | Size |
|---|---|---|
| Report Interval | 0x11 | 4 |
| Temperature and humidity data | 0x01 | 2 + 3*N |
| CO2 data | 0x02 | 2 + 2*N |
| IAQ data | 0x0F | 2 + 2*N |
| Pressure data | 0x10 | 2 + 3*N |
| Light intensity data | 0x14 | 4 |
| Door alarm | 0x0B | 10 |
| Door alarm cleared | 0x0C | 8 |
| Door status | 0x0D | 9 |
| Common settings | 0x05 | 7 |
| CO2 settings | 0x06 | 8 |
| Door settings | 0x0E | 10 |
| Blind ADR setting | 0x16 | 3 |
| Conditional transmission settings | 0x15 | 8 |
| Light measurement setting | 0x17 | 3 |
| Battery voltage | 0x09 | 4 |
| Firmware Hash | 0x0A | 6 |
| Downlink message | ID | Size |
|---|---|---|
| Common configuration | 0x87 | 7 |
| Door configuration | 0x86 | 10 |
| Blind ADR profile configuration | 0x89 | 3 |
| CO2 configuration | 0x81 | 8 |
| Conditional transmission configuration | 0x88 | 8 |
| Light measurement configuration | 0x8A | 3 |
| Reset | 0x84 | 7 |
Uplinks
Important
All uplinks are sent on LoRaWAN port 15.
Report Interval
Measurement data can be accumulated by the sensor sent out as multiple values in one message. As there is no timestamp information within the message, only the time of last measurement is known. It is equal to the timestamp of the message. To be able to calculate the timestamps of older messages, the measurement interval has to be known by the decoder. This can either be a static configuration or it can be enabled on the device to report the current interval with every measurement message.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x03) | uint8 |
| 1 | 1 | Message type (0x11) | uint8 |
| 2 | 2 | measurement interval in sec | uint16 |
Note
This message is only supported in firmware version 1.6.0 and newer
Temperature and humidity data
The temperature and humidity data message type is used to upload a number of sensor measurement values. Message length is dependent on the number of accumulated measurements: \(L = 1 + 3 * N\_{meas}\)
Single Measurement
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x03) | uint8 |
| 1 | 1 | Message type (0x01) | uint8 |
| 2-3 | 2 | Temperature in 0.01 °C | int16 (two’s complement) |
| 4 | 1 | Humidity in 0.5 % | uint8 |
Multiple measurements
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x03) | uint8 |
| 1 | 1 | Message type (0x01) | uint8 |
| 2-4 | 3 | Measurement 1 | see below |
| 5-7 | 3 | Measurement 2 | see below |
| ... | ... | ... | ... |
| \(3*N-1\) to \(3*N+1\) | 3 | Measurement \(N\) | see below |
The number of values per message is depending on the sensor configuration. The oldest measurement value is transmitted first. The last value is taken just before transmission. To be able to compute the timestamps of all the measurements included in the message, the report interval flag must be set in the general settings, so that the measurement interval is included in the message.
Important
In case of sensor failure, a single measurement will have the payload 0xFFFFFF
CO2 data
The CO2 data message type is used to upload a number of CO2 measurement values. Message length is dependent on the number of accumulated measurements: \(L = 1 + 2 * N\_{meas}\)
Single CO2 measurement
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length \(L\) | uint8 |
| 1 | 1 | Message type (0x02) | uint8 |
| 2-3 | 2 | CO2 concentration in ppm | uint16 |
Multiple CO2 measurements
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length \(L\) | uint8 |
| 1 | 1 | Message type (0x02) | uint8 |
| 2-3 | 2 | Measurement 1 | see below |
| 4-5 | 2 | Measurement 2 | see below |
| ... | ... | ... | ... |
| \(2*N\) to \(2*N+1\) | 2 | Measurement \(N\) | see below |
The number of values per message is depending on the sensor configuration. The oldest measurement value is transmitted first. The last value is taken just before transmission. To be able to compute the timestamps of all the measurements included in the message, the report interval flag must be set in the general settings, so that the measurement interval is included in the message.
Important
In case of sensor failure, a single measurement will have the payload 0x0000
IAQ data
The IAQ data message type is used to upload a number of VOC measurements which are converted to an IAQ index. Message length is dependent on the number of accumulated measurements: \(L = 1 + 2 * N\_{meas}\)
See the IAQ sensor description for details on how to interpret these values.
Single IAQ measurement
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length \(L\) | uint8 |
| 1 | 1 | Message type (0x0F) | uint8 |
| 2-3 | 2 | IAQ index and accuracy: Bits 0-13 = IAQ index Bits 14-15 = IAQ accuracy |
uint16 |
Multiple IAQ measurements
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length \(L\) | uint8 |
| 1 | 1 | Message type (0x0F) | uint8 |
| 2-3 | 2 | Measurement 1 | see below |
| 4-5 | 2 | Measurement 2 | see below |
| ... | ... | ... | ... |
| \(2*N\) to \(2*N+1\) | 2 | Measurement \(N\) | see below |
The number of values per message is depending on the sensor configuration. The oldest measurement value is transmitted first. The last value is taken just before transmission. To be able to compute the timestamps of all the measurements included in the message, the report interval flag must be set in the general settings, so that the measurement interval is included in the message.
Important
In case of sensor failure, a single measurement will have the payload 0xffff
Pressure data
The pressure data message type is used to upload a number of sensor measurement values. Message length is dependent on the number of accumulated measurements: \(L = 1 + 3 * N\_{meas}\)
Single pressure measurement
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length \(L\) | uint8 |
| 1 | 1 | Message type (0x10) | uint8 |
| 2-4 | 3 | Pressure in Pa | uint24 (unit: hPa) |
Multiple pressure measurements
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length \(L\) | uint8 |
| 1 | 1 | Message type (0x10) | uint8 |
| 2-4 | 3 | Measurement 1 | uint24 (unit: hPa) |
| 5-7 | 3 | Measurement 2 | uint24 (unit: hPa) |
| ... | ... | ... | ... |
| \(3*N-1\) to \(3*N+1\) | 3 | Measurement \(N\) | uint24 (unit: hPa) |
The number of value pairs per message is depending on the sensor configuration. The oldest measurement value is transmitted first. The last value is taken just before transmission. To be able to compute the timestamps of all the measurements included in the message, the report interval flag must be set in the general settings, so that the measurement interval is included in the message.
Important
In case of sensor failure, a single measurement will have the payload 0xFFFFFFFF
Light intensity measurement
From LBM Firmware version >= 1.2.2
The light intensity data message is used to send light intensity data values. Newer miroInsight Lux devices can measure light intensity either through the PV cell or with a dedicated light sensor. This is to help assess the light exposure of a location/orientation at installation and across different seasons or times of day. Note that at the moment light measurements are NOT accumulated, only the last measured (just before sending) light intesisty is sent.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length \(L\) | uint8 |
| 1 | 1 | Message type (0x14) | uint8 |
| 2-3 | 2 | Light measurement in lux | uint16 |
Door alarm
The door alarm message is sent when the Hall-sensor does not sense a magnet close to it for longer than alarm time.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x09) | uint8 |
| 1 | 1 | Message type (0x0B) | uint8 |
| 2-5 | 4 | Door open counter | uint32 |
| 6-7 | 2 | Alarm counter | uint16 |
| 8-9 | 2 | Alarm time in seconds | uint16 |
Door alarm cleared
The door alarm-cleared message is sent when the Hall-sensor does sense a magnet close to it after an alarm has been issued.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x07) | uint8 |
| 1 | 1 | Message type (0x0C) | uint8 |
| 2-5 | 4 | Door open counter | uint32 |
| 6-7 | 2 | Alarm counter | uint16 |
Door status
The door status message is sent when the every door status time.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x08) | uint8 |
| 1 | 1 | Message type (0x0D) | uint8 |
| 2-5 | 4 | Door open counter | uint32 |
| 6-7 | 2 | Alarm counter | uint16 |
| 8 | 1 | Alarm status | bool |
Common settings
This uplink will transmit the common device settings related uplink interval and retransmissions. It happens right after the sensor has joined a network and when the settings have been changed through a downlink. It will always be transmitted as a confirmed message. Retransmissions happen immediately after the NACK has been received.
Some parameters are only available in firmware release > 1.6.0. Message type is the same across all firmware versions. The message will differ in sice
Common settings for firmware 1.6.0 and newer
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x06) | uint8 |
| 1 | 1 | Message type | uint8 |
| 2-3 | 2 | Measurement interval in seconds | uint16 |
| 4 | 1 | Send cycle | uint8 |
| 5 | 1 | Flags: Bit 7 = Confirmed uplinks (0 = off, 1 = on) Bit 6 = LED (0 = off, 1 = on) Bit 5 = ADR (0 = off, 1 = on) Bit 4: Cont. VOC measurement Bit 3: Report Interval Bit 2-0: RFU |
bitfield |
| 6 | 1 | Number of retransmissions: Bit 7-4: RFU Bit 3-0: Number of retransmission |
bitfield |
Note
- ADR on: actually means that ADR is network controlled, i.e. the LoRaWAN network is responsible for telling the device how to adjust the data rate (spreading factor)
- ADR off: the device uses a so called blind ADR profile to decide how to adapt the data rate (spreading factor)
- The type of blind ADR profile that shall be used by the device can now be specified as a setting, see Blind ADR Profile setting description ADR Profile setting.
Common settings for firmware older than 1.6.0
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x05) | uint8 |
| 1 | 1 | Message type (0x05) | uint8 |
| 2-3 | 2 | Measurement interval in seconds | uint16 |
| 4 | 1 | Send cycle | uint8 |
| 5 | 1 | Flags and number of retransmissions, combination of: Bit 7 = Confirmed uplinks (0 = off, 1 = on) Bit 6 = LED (0 = off, 1 = on) Bit 5 = ADR (0 = off, 1 = on) Bit 4: Cont. VOC measurement Bit 3-0: Number of retransmission |
bitfield |
CO2 settings
This uplink will transmit the current device settings related to the CO2 sensor. It happens right after a device equipped with a CO2 sensor has joined a network and when the settings have been changed through a downlink. It will always be transmitted as a confirmed message. Retransmissions happen immediately after the NACK has been received.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x07) | uint8 |
| 1 | 1 | Message type (0x06) | uint8 |
| 2-3 | 2 | DPRECATED, can be ignored (0x0000) | - |
| 4-5 | 2 | CO2 subsamples | uint16 |
| 6-7 | 2 | ABC calibration period in hours | uint16 |
Door settings
This uplink will transmit the current device settings related to the door sensor. It happens right after the sensor has joined a network and when the settings have been changed through a downlink. It will always be transmitted as a confirmed message. Retransmissions happen immediately after the NACK has been received.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x09) | uint8 |
| 1 | 1 | Message type (0x0E) | uint8 |
| 2-3 | 2 | Alarm time in seconds | uint16 |
| 4-5 | 2 | Hall debounce in milliseconds | uint16 |
| 6-9 | 1 | Door status time in seconds | uint32 |
BlindADRProfile setting
From LBM Firmware version >= 1.2.2
This uplink transmits the current configured blind ADR profile that the device will use in case the ADR settings flag is set to off. See the ADR Profile setting description.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x02) | uint8 |
| 1 | 1 | Message type (0x16) | uint8 |
| 2 | 1 | Blind ADR Profile byte | uint8 |
Conditional transmission settings
From LBM Firmware version >= 1.2.2
This uplink transmits the current configured conditional transmission thresholds. The conditional transmission settings are explained here: settings.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x07) | uint8 |
| 1 | 1 | Message type (0x21) | uint8 |
| 2-3 | 2 | Conditional tx CO2 threshold | uint6 |
| 4-5 | 2 | Conditional tx temp threshold | uint6 |
| 6-7 | 2 | Conditional tx hum threshold | uint6 |
Light measurement setting
From LBM Firmware version >= 1.2.2
This uplink transmits the current configured interval with which light intesity is measured and sent. The interval unit is not time but multiples of the send cycle. Meaning, if the light interval is set to 0, the light intesity data is sent with every measurement uplink (every send cycle), if it is set to 1, light data will be sent every second send cycle, and so on. See settings.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x02) | uint8 |
| 1 | 1 | Message type (0x17) | uint8 |
| 2 | 1 | Light interval value | uint8 |
Battery voltage
The battery voltage message reports the voltage measured by the microcontroller. It is reported in 10 mV.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x03) | uint8 |
| 1 | 1 | Message type (0x09) | uint8 |
| 2-3 | 2 | Battery voltage in 0.01 V | uint16 |
Firmware Hash
The firmware hash message is sent once after successfully joining the network. The hash value can be used to identify the current firmware version of the device.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x05) | uint8 |
| 1 | 1 | Message type (0x0A) | uint8 |
| 2-5 | 4 | Firmware hash | uint32 |
Downlinks
Downlink messages are used to change the configuration of the device. They use the same general payload format as uplinks.
Important
All downlinks must be sent on the LoRaWAN port 3!
Common configuration
The common configuration message type is used to set the basic configuration such as the measurement interval and s end cycle.
Some parameters are only available in firmware release > 1.6.0. For compatibility reasons, a new configuration message has been added.
Common configuration
Common configuration for firmware version 1.6.0 and newer.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x06) | uint8 |
| 1 | 1 | Message type (0x87) | uint8 |
| 2-3 | 2 | Measurement interval in seconds | uint16 |
| 4 | 1 | Send | uint8 |
| 5 | 1 | Flags: Bit 7 = Confirmed uplinks (0 = off, 1 = on) Bit 6 = LED (0 = off, 1 = on) Bit 5 = ADR (0 = off, 1 = on) Bit 4: Continuous VOC Bit 3: Report Interval Bit 2-0: RFU (send as 0) |
bitfield |
| 6 | 1 | Bit 7-4: RFU (send as 0), Bit 3-0: Number of retransmissions |
Example: 0x06878403032803
- 0x06: length
- 0x87: type
- 0x8403: interval 15min (0x8403 converted from little endian to 0x0384 in decimal is 900 seconds converted to 15 minutes)
- 0x03: Send cycle
- 0x28: flags (no confirmations, LED off, ADR on, continuous VOC off, report interval on)
- 0x03: 3 retransmissions
Legacy common configuration
Common configuration for firmware version older than 1.6.0.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x05) | uint8 |
| 1 | 1 | Message type (0x80) | uint8 |
| 2-3 | 2 | Measurement interval in seconds | uint16 |
| 4 | 1 | Send cycle | uint8 |
| 5 | 1 | Flags and number of retransmissions: Bit 7 = Confirmed uplinks (0 = off, 1 = on) Bit 6 = LED (0 = off, 1 = on) Bit 5 = ADR (0 = off, 1 = on) Bit 4: Continuous VOC Bit 3-0 = Number of retransmissions as uint4 |
bitfield |
CO2 configuration
This downlink will configure the current device settings related to the CO2 sensor if one is available on the device.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x07) | uint8 |
| 1 | 1 | Message type (0x81) | uint8 |
| 2-3 | 2 | DEPRECATED, can be ignored (0x0000) | - |
| 4-5 | 2 | CO2 subsamples | uint16 |
| 6-7 | 2 | ABC calibration period in hours | uint16 |
Reset
This downlink will reset the device with delay. Device will reset after reset delay seconds if magic number matches
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x06) | uint8 |
| 1 | 1 | Message type (0x84) | uint8 |
| 2-5 | 4 | Magic number 0xF98BD419 | uint32 |
| 6 | 1 | Reset delay in seconds | uint8 |
Door sensor configuration
This downlink will configure the door sensor.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x09) | uint8 |
| 1 | 1 | Message type (0x86) | uint8 |
| 2-3 | 2 | Alarm time in seconds | uint16 |
| 4-5 | 2 | Hall sensor debounce time in milliseconds | uint16 |
| 6-9 | 2 | Door sensor status report interval in seconds | uint32 |
Blind ADR profile configuration
From LBM Firmware version >= 1.2.2
This downlink configures the blind ADR profile used by the device in case the ADR setting flag is set to off. See the blind ADR profile setting for a more detailed explanation.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x02) | uint8 |
| 1 | 1 | Message type (0x89) | uint8 |
| 2 | 1 | Blind ADR profile byte | uint8 |
Conditional transmission configuration
From LBM Firmware version >= 1.2.2
This downlink will configure the threshold for the conditional data uplink. See the conditional transmission settings for a detailed explanation of these settings.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x07) | uint8 |
| 1 | 1 | Message type (0x88) | uint8 |
| 2-3 | 2 | CO2 threshold in ppm (65535: disable) | uint16 |
| 4-5 | 2 | Temperature threshold in degrees (300: disable) | int16 |
| 6-7 | 2 | Relative Humidity in % (100: disable) | uint16 |
Light measurement configuration
From LBM Firmware version >= 1.2.2
This downlink configures the interval with which light intensity is measured and sent. The interval unit is not time but multiples of the send cycle. Meaning, if the light interval is set to 0, the light intesity data is sent with every measurement uplink (every send cycle), if it is set to 1, light data will be sent every second send cycle, and so on. See settings.
| Byte | Size | Description | Format |
|---|---|---|---|
| 0 | 1 | Message length (0x02) | uint8 |
| 1 | 1 | Message type (0x8A) | uint8 |
| 2 | 1 | Interval in multiples of send cycles | uint8 |