8 binary flags (byte bits)
Last updated
Last updated
Even though encoding data into separate bits as boolean values is not unusual, we wanted to have it explained here because API 6 uses this quite a lot - some downlink register values can carry a lot of data in a single byte, and its 8 bits. This is the general explanation:
As you know, one byte has eight bits. On one end, there is the LSB (Least significant bit) and on the other, the MSB (Most significant bit) - in our firmware, the MSB is always on the left.
Example: The decimal value 149 is 10010101 in binary (128+0+0+16+0+4+0+1=149).
In order to know this, you have to define which bit is the MSB (and the LSB). In our case, the first bit on the left is the MSB: 10010101 - this means that the sequence of decimal values (128, 64, 32, 16, 8, 4, 2, 1) is represented by the bits from left to right. If the first bit on the left was the LSB and not the MSB, the order would be the inverted and the value of the byte 10010101 would be 169 (1+0+0+8+0+32+0+128=169).
Using the binary flags encoding, some bytes can control up to 8 different boolean settings (on/off), one per each bit. There are several downlink registers and uplink messages that are encoded this way (you can find them all in the API 6 table). This allows 256 possible combinations of settings.
Best shown on a few examples:
Example 1: Heartbeat 1 settings register 0x08. Complex settings for heartbeats 1 in a single byte.
For example, the value 0x20 (32 in decimal and 00100000 in binary) will request a downlink with every heartbeat 1.
Example 2: Appended payload mask register 0x0D. This single byte value will define what data will appended to certain events (from 0x00 to 0x7F).
For example, the value 0xC0 (192 in decimal and 11000000 in binary) will tell the device to append voltage and temperature with applicable events. Some of the data can be longer than just one byte and some appended bytes will hold more information that just a single value (bit 3).
Example 3: Device control presets register 0x56. This register controls several unrelated settings with a single byte value - from LED indication to enabling sensor-triggered mode-independent events.
For example, the value 0x11 (17 in decimal and 00010001 in binary) will limit the downlink receiving LED indication pattern to 10s and at the same time will allow logistic mode events to be sent in every mode.
Bit
Set to 0
Set to 1
7
Heartbeat time period is not reset by other events sent from the device
Heartbeat time period is reset by other events sent from the device (to save the battery)
6
Heartbeats sent while armed only
Heartbeats sent regardless of device state
5
Uplink only heartbeat message
Heartbeat message requests standard downlink
4
Uplink only heartbeat message
Heartbeat message requests downlink with world time to sync the internal clock
3
Standard 3 frames transmitted
Only one frame message will be sent
2
(empty)
(empty)
1
(empty)
(empty)
0
(empty)
(empty)
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
(empty)
0
(empty)
Bit
Set to 0
Set to 1
7
Default short press LED indication
Short press LED indication limited to 1,5s
6
Arming and disarming confirmed by LED
Arming and disarming NOT confirmed by LED
5
Default arming LED pattern is default
Slow Arming LED pattern - same as in sleep mode
4
Uplink only heartbeat message
Downlink receiving LED indication limited to 10s
3
Standard 3 frames transmitted
Reed pipeline message sent every 5 reed switches
2
(empty)
(empty)
1
(empty)
(empty)
0
Logistic mode events (0x20, 0x21, 0x22) sent in logistic modes only
Logistic mode events (0x20, 0x21, 0x22) sent in every mode