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

<table data-header-hidden><thead><tr><th width="157"></th><th></th></tr></thead><tbody><tr><td><strong>Bit</strong></td><td><strong>Set to 1</strong></td></tr><tr><td><strong>7</strong></td><td>Voltage is sent</td></tr><tr><td><strong>6</strong></td><td>Temperature is sent</td></tr><tr><td><strong>5</strong></td><td>Accelerometer data is sent</td></tr><tr><td><strong>4</strong></td><td>MAC address is sent</td></tr><tr><td><strong>3</strong></td><td>Three boolean values and humidity data is sent</td></tr><tr><td><strong>2</strong></td><td>Magnetometer data is sent</td></tr><tr><td><strong>1</strong></td><td>2nd temperature from NTC</td></tr><tr><td><strong>0</strong></td><td>Specific boolean values (4 bits for external switches A and B)</td></tr></tbody></table>

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*](https://ask.simplehw.eu/kb/simple-api-6-generation/api-6-encoding_23396515).

### **Accelerometer data**

Accelerometer data is appended in **three bytes**. You can find more about the way it’s encoded [*here*](https://ask.simplehw.eu/kb/simple-api-6-generation/api-6-encoding_23396515/page-6)*.*

### **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.

***

##