Appended payload

With a lot of uplink messages (events), you can receive various data from the device. We call this feature Appended payload. Thanks to this, you can receive battery voltage, temperature, data from the accelerometer and the magnetometer, one MAC address, three boolean values, and humidity data. the Appended payload can only be sent with events from 0x00 to 0x7F (incl. heartbeats).

Introduction

All events in API 6 have a hex symbol assigned. If this hex symbol is below 0x80 (so 0x00 to 0x7F), appended payload can be added to the uplink message. You cannot use this feature with the rest of the events because they are usually sent with other data such as MAC addresses and the appended payload data would not fit in the 12 bytes one uplink payload is limited to.

Appended payload configuration (downlink)

You can opt to have battery voltage, temperature, data from the accelerometer and the magnetometer, one MAC address, three boolean values and humidity data sent to you as appended payload.

You configure the exact data you want to receive by a single register value. The register hex is 0x0D. If the value of this register is not 0x00 (and is set up correctly), the desired appended payload will be sent with every event <0x80.

Please note that if you configure appended payload but use a user mode that sends events from 0x80 and up (most WiFi modes), you will not receive any appended data!

The 8 binary flags (bits) of this the 0x0D register value modify the following:

Bit	Set to 1
7	Voltage is sent
6	Temperature is sent
5	Accelerometer data is sent
4	MAC address is sent
3	Three boolean values and humidity data is sent
2	Magnetometer data is sent
1	2nd temperature from NTC
0	Specific boolean values (4 bits for external switches A and B)

You cannot set all of the bits to 1 at once because of the format the data is appended in. For Ex. one MAC address will always take up 6 bytes of the payload.

Example: You want to receive temperature and data from the accelerometer when an event is triggered. You will set the Appended payload register (0x0D) to value 0x60 (0110000). This will also be the uplink mask.

Appended payload parsing (uplink)

Every uplink message (with few exceptions) starts with a mode byte which is then followed by an event byte. If you’ve chosen to have appended payload sent to you, the third byte will be what we call Appended payload mask. The uplink mask byte is identical to the downlink Appended payload register value byte, which means you can use the table above to parse the mask. The bytes that follow the mask come in the same order as the bits from left (bit 7 - MSB) to right (bit 0 - LSB) - voltage first and magnetometer data last.

The mask will tell you how to parse the following bytes. You can receive up to 9 bytes of appended payload in one single uplink message. Make sure to read the descriptions below so you know how many bytes are sent for each bit. Because it’s tricky - it’s not always that only one byte is sent in the appended payload!

Voltage

Battery voltage is appended as a single byte. The first four bits (from the MSB 7 to bit 4) tell you what the whole number of the voltage value is and the last four bits (from bit 3 to LSB 0) tell you the decimal.

Example: The value 0x30 is received - this means 3.0V on the battery. Easy peasy.

Temperature

Temperature is appended in a single byte and it’s encoded in SimpleTemp.

Accelerometer data

Accelerometer data is appended in three bytes. You can find more about the way it’s encoded here.

MAC address

One MAC address is appended in six bytes. Each byte represents one MAC number.

Boolean & humidity

Boolean values and relative humidity data are appended in a single byte. The first three bits (from the MSB 7 to bit 5) are boolean values with the following meaning:

Bit 7 - reed contact is switched on because a magnet is nearby (yes or no, 1 or 0) Bit 6 - light % is over the predefined light threshold (yes or no, 1 or 0) Bit 5 - should downlink with a timestamp to sync the internal clock be requested (yes or no, 1 or 0)

The following five bits (from bit 4 to LSB 0) will give you a decimal value from 0 to 25 which you then multiply by 4 and get the relative air humidity percentage.

Magnetometer data

Implemented in a similar way the accelerometer data is useless. No point in using this feature - it will not be, however, removed because we are not changing anything in new firmware revisions that are not a bug.

---