Skip to content

Payload

General applications

To help developers to speedup the development process, we have published a javascript example of our payload decoder on GitHub. This example code supports the decoding of all available sensordata.

Notations

Value Description
xb X number of bits required, e.g., 3b=3 bits required
xB X number of bytes required, e.g., 3B=3 bytes required
bx Bit number x, e.g., b9=9th bit from right
Bx Byte number x, e.g., B9=9th byte from left (except for the action content bytes, as those start counting from zero starting at the right)
0x19 Notation for one byte. Equal to 0d25
0b11 Notation for two bits. Equal to 0d3
0d19 Notation for the decimal value 19
LSB Least significant bit = b0 = bit at the right
MSB Nost significant bit, bit to the left
0xXX Can be any byte. 0xXXXX = can be any two bytes
0bxx Can be any two bits. 0bxxxx = can be any four bits
Bx..By All bytes from Bx to and including By
0bx..0by All bits from bit x to and including bit y
| | Concatenation sign, e.g., 0x1234 = 0x12 | | 0x34

Uplink message contents are dynamic, depending on the ioTracker configuration, but combined in a single uplink message for efficiency and timing reasons. Every uplink message is constructed as described in the following sub-sections.

B0 B1 B2 B3..B?
Uplink header (2b) Package content (3b) Uplink reason (3b) CRC Last received downlink (1B) Battery status (1B) Optional bytes depending on header and package content

The uplink header is 2 bits. If the value of the header is 0b00 this means the 6 LSBs of byte B0 are defines as “package content” field and “uplink reason” field. Future header values can have different meaning of the 6 LSBs of byte B0, but are allowed to also include these fields. Bytes B1 (“CRC last received download”) and B2 (“Battery status”) are always included, regardless of the uplink header or content.

Note: contrary to the notation of the least significant bit (b0), B0 represents the most significant byte of the uplink message.

The first 2 bits of the uplink header define the use of the next 6 bits in the header.

Value Description Application
0b00 Default uplink header Default and compact header
0b01 Action response header B3 this payload is the action to an downlink action

Package content field

Bits in the "package content” field define which information is included in the package and thus how long the package is. The bits in the “package content” field mark if the specific content is available in the payload. The content in the payload is in the same sequential order as the package content bits.

Bit position Description
b5 0
b4 Uplink contains on-board sensors (precise temperature, precise light)
b3 Uplink contains GPS data

The uplink reason used in the header.

Bit position Description
b2 0
b1 Device movement detected since previous uplink
b0 Button pressed has commenced

The ioTracker 3 Pro adds 12 or 14 bytes in front of the payload data.

Version Header IMEI Fcnt AcT Signal_power Payload
0xFF 0x01 8B 2B 1B 1B ..
uint8_t uint8_t uint64_t uint16_6 uint8_t uint8_t ..

Extra information

  • Version header is added and consists of a start byte 0xFF to identify the version versus the IMEI field. It includes a byte with the payload version number so breaking changes can be identified.

  • IMEI is the IMEI of the cellular module.

  • Fcnt is similar to LoRa, 16 bit counter which rolls over. The Every time the ioTracker reboots the counter is set to 0.

  • AcT and signal_power are added to the payload by default, but can be configured in the cellular config. See 8.3. for the “COPS” command, where it defines the Radio Access Technology (AcT) and signal power (CSQ) of the received signal. See the U-Blox SARA-R4 AT Commands Manual (Chapter 7.3 and 7.5) for more info.

Battery status

The battery level definition is identical to the official LoRaWAN specification (https://loraalliance.org/lorawan-for-developers). The reason for having the battery status communicated as part of the payload, is that the battery status otherwise should be obtained via a LoRa MAC command (for the ioTrackers which feature LoRaWAN communication), which costs an extra downlink and uplink message. The battery level byte (Battery) reported is encoded as follows:

Value Description
0d1..0d254 The battery level, 1 being at minimum and 254 being at maximum
0d255 The end-device is connected to an external power source

Onboard sensors package content

Onboard sensor package content indicates which specific sensor data is present in the uplink message. If any of the onboard sensor package content bit is enabled, then b4 of the header is automatically also enabled.

Bit position Sensor Description
b0 Temperature int16_t 0,01C / LSB
b1 Light 4b exponent (0..11), 12b unsigned
b2 Accelerometer current int16 X,Y,Z (6 bytes) (signed)
b3 Accelerometer max int16 (highest value any axis) (signed) (probably only positive values due to filtering)
b4 WiFi positioning Status 8b, n(6B mac)
b5 Uplink reason b3 Indicate a double or long- click
b6 External sensors External sensors added
b7 Another sensor package content byte is added

Optional onboard sensors package content B1

Bit position Sensor Description
b0 Bluetooth scanning Status 8b, n(RSSI + Type, 4b mac)
b1..b6 RFU
b7 Another sensor package content byte is added

Temperature

2 bytes in total, where the temperature information (int16_t 0,01C / LSB ) is represented in degrees Celsius.
Example:

0x075F
=
18,87 degrees Celsius

Light

2 bytes in total, where the light information (4b unsigned exponent [b15..b12], 12b unsigned lux [b11..b0]) represents data to come to the measured light in lux when using the following formula:

0d0.01 * (0d2^exponent) * lux
Example:
0x44A0
=
0d0.01 * (0d2^0x4) * 0x4A0
=
189.44 lux

Accelerometer current

6 bytes total, where the X, Y and Z axis information, where each axis’ measures g-force in milli-g (mg) is represented by a 16b signed value (1mg/LSB).
Example:

0x000004000020
=
0x0000 || 0x0400 || 0x0020
=
0 mg on x-axis || 1024 mg on y-axis || 32 mg on z-axis

Accelerometer max

4 bytes total, where the most significant byte represents the maximum milli-g measured since previous uplink message and the least significant byte the maximum milli-g measures since the previous x uplinks, where x is a value which can be configured in the Accelerometer sensor configuration (see Section 8.10) and each bye is a signed value (1mg/LSB).
Example (where x = 16):

0x00600c80
=
0x0060 || 0x0c80
=
0d96 || 0d3200
=
96 mg max since previous uplink || 3.2 g max of all previous 16 uplinks

WiFi

Onboard Wi-Fi scan results Package content contains the identified Wi-Fi Access Points (APs) nearby the ioTracker. Only when the ioTracker has moved since previous uplink, it scans for WiFi APs and adds it to the uplink payload.

Note: When GPS is active and data is included in the payload, no WiFi data is included because of limitations in the payload

The firmware is configured by default to send details of up to five Wi-Fi access points. For higher precision in Wi-Fi based positioning, depending on the Wi-Fi configuration, an additional 1 or 2 uplink message with the next 1 to 5 APs (with lower RSSI than previous 5 APs) may be sent when the ioTracker becomes stationary. Meaning, a total of three uplinks could be sent, each of which contains information of 5 APs, e.g., uplink 1 contains AP 1 to 5, uplink 2 contains AP 6 to 10 and uplink 3 contains AP 11 to 15.

WiFi status byte

Bit position D Description
b0..b2 0d2 Number of access points: 0..7
b3..b4 0d0 0 WiFi successful
1 WiFi failed (chip/power)
2 No access points found
b5 0d1 Signal strength added after mac address
b6.b7 RFU

Each Wi-Fi access point consists of 6B MAC-address, and optionally corresponding signal strength. Sorted from high to low signal strength. Signal strength is an (always negative) signed char.

Example:

0x233c77e632e25baf3e77e632e25caf4c9efffe2fc5a2
=
WiFi status byte || WiFi AP details
=
0x23 || 0x3c77e632e25baf3e77e632e25caf4c9efffe2fc5a2
=
WiFi RSSI included, 3 WiFi mac addresses found || 0x3c77e632e25baf3e77e632e25caf4c9efffe2fc5a2
=
Wi-Fi RSSI included, 3 Wi-Fi mac addresses found ||
3c:77:e6:32:e2:5b with RSSI 0xAF (=-0d81) ||
3e:77:e6:32:e2:5c with RSSI 0xAF (=-0d81) ||
4c:9e:ff:fe:2f:c5 with RSSI 0xA2 (=-0d94)

Bluetooth scan results package content

The Bluetooth scan results package content contains the identified Bluetooth Low Energy beacons nearby the ioTracker.

Bit position D Description
b0..b2 0d2 Number of beacons in this message: 0..7
b3..b4 0d0 0: BT successful
1: BT failed (chip/power)
2: No beacons found
3: RFU
b5..b6 0d0 Add slot info:
0 : 1B for result status + rssi + 6b data
1 : 1B for result status + rssi + full data
2 : 2B for result + slot + rssi + (4B for iBeacon and AltBeacon, 6B for Eddystone)
b7 RFU

b5 = 0 -> 1B Result status + RSSI

Bit position D Description Application
b0..b1 0d0 Beacon type:
0: iBeacon
1: Eddystone
2: AltBeacon
3: RFU
iBeacon (16B UUID + 2B major + 2B minor)
Eddystone (10B namespace + 6B instance)
AltBeacon (16B id1 + 2B id2 + 2B id3)
b2..b7 0d0 RSSI = 27 - ([0..63] * 2) Internally rounded down (lsb removed)

If configured the “Calibrated reference power” information from the beacon is subtracted from this data. The ioTracker should then report 0dB at 1 meter.

b5 = 1 -> 2B Result status + Slot + RSSI

Bit position D Description Application
b0..b1 0d2 Beacon type:
0: iBeacon
1: Eddystone
2: AltBeacon
3: RFU
iBeacon (16B UUID + 2B major + 2B minor)
Eddystone (10B namespace + 6B instance)
AltBeacon (16B id1 + 2B id2 + 2B id3)
b2..b4 0d0 Slot match Indicates to which slot the data matches
b5..b7 RFU
b8..b13 0d0 RSSI = 27 – ([0..63] * 2) Internally rounded down (lsb removed)

If configured the “Calibrated reference power” information from the beacon is subtracted to this data. The ioTracker should than report 0dB at 1 meter.
b14..b15 RFU

RSSI calculation in the ioTracker
Each beacon packet includes the data how strong it is transmitting. With the help of this data we can correct the result so that a strong transmitting beacon is not perceived closer than a weak transmitting beacon. If b15 of the Bluetooth scan configuration is set, the ioTracker will combine and correct the received RSSI with the “calibrated reference power” value the beacon reports and the ioTracker receive sensitivity.

With correction enabled (b15 ) the:

Reported RSSI
=
RSSImeasured - BeaconReferenceRSSI + ioTracker calibration correction

If everything is configured correctly the ioTracker should report around the same beacon RSSI as a calibrated phone. A calibrated beacon typically reports an RSSI of -58 at 1 meter.

You should now take extra care of how to configure your beacons. If you set their transmit power to -10dB (e.g., to save power), then also update the field for calibrated power (see Section 8.13) at 1m 10dB lower. e.g. from -58 to -68.

Take precaution setting up an Eddystone beacon, as it is calibrated at 0 centimetre instead of 1 meter. The value in the reference field is 41dB higher compared to an iBeacon. The ioTracker corrects these 41dB already. If you perceive erroneous results, you can disable this function and the raw received RSSI is reported.

GPS

The GPS uplink is included in Uplink payload data when the GPS package content bit is set. The GPS content has a size of 19 bytes.

Byte position Type Description Decimals Example Unit
B1 uint8_t Navigation status (0 = no fix) 0 3
B2..B5 int 32b Latitude of the device in degrees range [−90..90] 7 514498915
B6..B9 int 32b Longitude of the device in degrees range [−180..180] 7 60531326
B10..B11 uint16_t altRef; // altitude above user datum ellipsoid 1 543 m
B12 uint8_t hAcc; // horizontal accuracy estimate 0 58 m
B13 uint8_t vAcc; // vertical accuracy estimate 0 61 m
B14..B15 uint16_t sog; // speed over ground 1 0 km/h
B16..B17 uint16_t cog; // course over ground 1 1588 degrees
B18 uint8_t hdop; // HDOP, Horizontal Dilution of Precision 1 12
B19 uint8_t numSvs; // number of satellites used in the navigation solution 0 9

Attention: latitude and longitude are signed.

For some GPS session ending Navstat 0 is replaced with Navstat 20..25 to give more information about why the GPS session has stopped.

Navstat

Nr Code Description GPS data/Coordinates valid
0 NF No Fix No
1 DR Dead Reckoning only Yes
2 G2 Stand-alone 2D Yes
3 G3 Stand-alone 3D Yes
4 D2 Differential 2D Yes
5 D3 Differential 3D Yes
6 RK GPS + DR Yes
7 TT Time only Yes
20 GPS delayed due to battery No
21 GPS terminated due to battery No
22 GPS terminated due to no initial fix No
23 GPS terminated due to lost fix No
24 GPS terminated due to moving timer No
25 GPS terminated due to static timer No

For example: if the device is inside and cannot get a GPS fix, it will try 5 minutes to get a fix, and then report the GPS data with Navstat 22.

Example 1: 0x03 XX XX (button pressed, moved, no temperature, the rest disabled.)

Packet Description Application
2b Uplink header
0b00
Default uplink header
3b Package content
0b000
No on-board sensor data included
3b Uplink reason
0b011
Button pressed (0b001) and moved (0b010) <- XOR'ed
1B CRC
0xXX
Any CRC
1B Battery status
0xXX
Any battery status

Example 2: 0x13 XX XX 0307D 01343 (button pressed, moved, precise temperature and light data included, the rest disabled.)

Packet Description Application
2b Uplink header
0b00
Default uplink header
3b Package content
0b010
Onboard sensor data included
3b Uplink reason
0b011
Button pressed (0b001) and moved (0b010) <- XOR'ed
1B CRC
0xXX
Any CRC
1B Battery status
0xXX
Any battery status
1B Onboard sensor package content
0x03
Temperature included (0b000000001) and light included (0b00000010) <- XOR'ed
2B Temperature data
0x07D0
20 degrees Celsius (int16_t 0,01C / LSB)
2B Light data
0x1343
0d0.01 * (0d2^0x1) * 0x343 = 16.70 lux (4b exponent (15..12), 12b unsigned (11..0))

Example 3: 0x13 00 F9 1F 07D0 1343 000004000020 00600C80 23 3C77E632E25BAF3E77E632E25CAF4C9EFFFE2FC5A2 (button pressed, moved, precise temperature, light and WiFi data included.)

Packet Description Application
2b Uplink header
0b00
Default uplink header
3b Package content
0b010
Onboard sensor data (precise temp and precise light) and GPS data included
3b Uplink reason
0b011
Button pressed (0b001) and moved (0b010) <- XOR'ed
1B CRC
0x00
00 CRC
1B Battery status
0xF9
249 ~= 98%
1B Onboard sensor package content
0x1F
Temperature included (0b000000001), light included (0b00000010), accelerometer current included (0b00000100), accelerometer max included (0b00001000), WiFi included (0b00010000) <- XOR'ed
2B Temperature data
0x07D0
20 degrees Celsius (int16_t 0,01C / LSB)
2B Light data
0x1343
0d0.01 * (0d2^0x1) * 0x343 = 16.70 lux (4b exponent (15..12), 12b unsigned (11..0))
6B Accelerometer current data
0x000004000020
0x0000 | | 0x0400 | | 0x0020 = 0 mg on x-axis | | 1024 mg on y-axis | | 32 mg on z-axis
2B Accelerometer max data
0x00600C80
0x0060 | | 0x0c80 = 0d96 | | 0d3200 = 96 mg max since previous uplink | | 3.2 g max of all previous 16 uplinks
1B 0x23 WiFi RSSI included, 3 Wi-Fi mac addresses found
21B 0x3C77E632E25BAF3E77E632E25CAF4C9EFFFE2FC5A 3C:77:E6:32:E2:5B with RSSI of (0xAF=-81)
3E:77:E6:32:E2:5C with RSSI of (0xAF=-81)
4C:9E:FF:FE:2F:C5 with RSSI of (0xA2=-94)

Example 4: 0x1B DD 64 1F 075F 44A0 000004000020 00600C80 00031EAB10B0039C7275031F1315000400002705 (button pressed, moved, precise temperature, light and GPS data included.)

Packet Description Application
2b Uplink header
0b00
Default uplink header
3b Package content
0b011
Onboard sensor data (precise temp and precise light) and GPS data included
3b Uplink reason
0b011
Button pressed (0b001) and moved (0b010) <- XOR'ed
1B CRC
0xDD
DD CRC
1B Battery status
0x64
0d100 ~= 40% (100/254)
1B Onboard sensor package content
0x1F
Temperature included (0b000000001), light included (0b00000010), accelerometer current included (0b00000100), accelerometer max included (0b00001000), WiFi included (0b00010000) <- XOR'ed
2B Temperature data
0x075F
18,87 degrees Celsius (int16_t 0,01C / LSB)
2B Light data
0x44A0
0d0.01 * (0d2^0x4) * 0x4A0 = 189.44 lux (4b exponent (15..12), 12b unsigned (11..0))
6B Accelerometer current data
0x000004000020
0x0000 | | 0x0400 | | 0x0020 = 0 mg on x-axis | | 1024 mg on y-axis | | 32 mg on z-axis
2B Accelerometer max data
0x00600C80
0x0060 | | 0x0c80 = 0d96 | | 0d3200 = 96 mg max since previous uplink | | 3.2 g max of all previous 16 uplinks
1B GPS data
0x03 1EAB10B0 039C7275 031F 13 15 0004 0000 27 05
1B Navstat = 0x03 = ok/got a GPS fix correctly
4B LAT = 0x1eab10b0 = 51.4527408
4B LON = 0x039c7275 = 6.0584565
2B 0x039c7275 = 6.0584565 = 0x031f = 79.9m
1B horizontal accuracy m = 0x13 = 19 m
1B vertical accuracy m = 0x15 = 21 m
2B speed over ground = 0x0004 = 0.4 km/h
2B course over ground = 0x0000 = 0 degree
1B hdop = 0x27 = 3.9
1B #satellites found = 0x05 = 5 satellites