Skip to content

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.

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
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

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

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 miro Insight 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 intensity 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: Reserved
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: Reserved
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 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 intensity 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

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: Reserved
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, 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: Reserved
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 intensity 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