Skip to content

Telemetry

Kontakt.io Telemetry Packet contains data from sensors available on some beacons. Because of that it can be broadcasted only by Beacon Pros, Bluetooth Tags S18-3, Bluetooth Beacon SB18-3 and Bluetooth Beacons HD18-3.

This packet is connectable and uses the same MAC address as Kontakt.io Secure Profile and Scan Response packet on nRF52-based beacons.

Due to the limited space in a single Bluetooth advertising packet and a large number of possible sensors, and therefore data they produce, in some circumstances beacons can broadcast more than one Telemetry Packet containing different data.

General structure

The actual content of Kontakt.io Telemetry Packet varies depending on available and enabled sensors and functionality. Nonetheless, each packet should have a similar structure as to what is presented below - telemetry header and one or more data fields:

Byte offset Default/sample value Description
0 0x08 Data length – 8 bytes (varies depending on fields number and their length)
1 0x16 Data type – Service data
2 0x6A Kontakt.io UUID
3 0xFE Kontakt.io UUID
4 0x03 Payload identifier - Telemetry v1
5 xx Field #1 length in bytes (including identifier)
6 xx Field #1 identifier
7 xx Field #1 payload 1st byte
8 xx Field #1 payload 2nd byte
9 xx Field #1 payload 3rd byte
10 xx Field #2 length in bytes (including identifier)
11 xx Field #2 identifier
12 xx Field #2 payload 1st byte
13 xx Field #2 payload 2nd byte
14 xx Field #2 payload 3rd byte
15 xx Field #2 payload 4th byte

Info

  • Total reserved bytes for advertisement overhead in a single packet is 3 + 5 = 8 bytes (flags, service overhead)
  • Bytes available for telemetry data (field headers and payloads) in a single packet is 23

Telemetry fields

Each piece of the telemetry data might be represented by its own field. However, in order to conserve the space in the Bluetooth advertising packet, related values and parameters might be grouped into a single field.

Important

All multibyte values are little-endian.

The structure of a Telemetry packet for each beacon (as of Autumn 2018) is presented in the table below:

Beacon Packet Structure
Beacon Pro BP16-3 Single packet Grouped fields: System health, Accelerometer, Sensors
Asset Tag S18-3 1st packet Grouped fields: System health, Accelerometer, Sensors
Asset Tag S18-3 2nd packet Singular field: Button click
Card Tag S18-3 1st packet Grouped fields: System health, Accelerometer, Sensors
Card Tag S18-3 2nd packet Singular field: Button click
Smart Beacon SB18-3 Single packet Grouped fields: System health, Accelerometer, Sensors
Heavy Duty Beacon HD18-3 Single packet Grouped fields: System health, Accelerometer, Sensors

Warning

When implementing a Kontakt.io Telemetry packet parser, it should not rely on a position of a particular field in a packet. It should be able to recognize and parse each field separately, since the structure of a Telemetry packet might change.

Grouped fields

System health (beacon)

Byte offset Default/sample value Description
0 0x06 Field length in bytes (including identifier) - 6 bytes
1 0x01 Field identifier - system health
2 0x5A Unix timestamp from onboard RTC (in UTC). -1 if not applicable. Int32
3 0x8A Continuation
4 0xBF Continuation
5 0x3D Continuation
6 0x64 Battery level in percentages. 0xFF if not applicable (external power supplied). UInt8

Accelerometer

Byte offset Default/sample value Description
0 0x09 Field length in bytes (including identifier) - 9 bytes
1 0x02 Field identifier - accelerometer
2 0x20 Accelerometer sensitivity. Unit: mg/digit. UInt8
3 0x3F Raw acceleration value for the X axis, filtered with a lowpass filter. Int8
4 0x81 Raw acceleration value for the Y axis, filtered with a lowpass filter. Int8
5 0x8C Raw acceleration value for the Z axis, filtered with a lowpass filter. Int8
6 0x30 Seconds since the last double tap event. Saturates on 0xFFFF. 0xFFFF might also represent disabled state. UInt8
7 0x39 Continuation
9 0x5B Seconds since the last movement/free fall event. Saturates on 0xFFFF. 0xFFFF might also represent disabled state. UInt8
10 0xA0 Continuation

Sensors

Byte offset Default/sample value Description
0 0x03 Field length in bytes (including identifier) - 3 bytes
1 0x05 Field identifier - sensors
2 0x41 Light sensor percentage (0-100), 0xFF if not applicable. UInt8
3 0x91 Temperature in °C. Int8

Singular fields

Acceleration

Byte offset Default/sample value Description
0 0x05 Field length in bytes (including identifier) - 5 bytes
1 0x06 Field identifier - acceleration
2 0x20 Accelerometer sensitivity. Unit: mg/digit. UInt8
3 0x3F Raw acceleration value for the X axis, filtered with a lowpass filter. Int8
4 0x81 Raw acceleration value for the Y axis, filtered with a lowpass filter. Int8
5 0x8C Raw acceleration value for the Z axis, filtered with a lowpass filter. Int8

Movement/Free-fall

Byte offset Default/sample value Description
0 0x03 Field length in bytes (including identifier) - 3 bytes
1 0x07 Field identifier - movement/free-fall
2 0x30 Seconds since the last double tap event. Saturates on 0xFFFF. 0xFFFF might also represent disabled state. UInt8
3 0x39 Continuation

Double tap

Byte offset Default/sample value Description
0 0x03 Field length in bytes (including identifier) - 3 bytes
1 0x08 Field identifier - double tap
2 0x5B Seconds since the last double tap event. Saturates on 0xFFFF. 0xFFFF might also represent disabled state. UInt8
3 0xA0 Continuation

Light level

Byte offset Default/sample value Description
0 0x02 Field length in bytes (including identifier) - 2 bytes
1 0x0A Field identifier - light level
2 0x41 Light sensor percentage (0-100), 0xFF if not applicable. UInt8

Temperature

Byte offset Default/sample value Description
0 0x02 Field length in bytes (including identifier) - 2 bytes
1 0x0B Field identifier - temperature
2 0x91 Temperature in °C. Int8

Battery

Byte offset Default/sample value Description
0 0x02 Field length in bytes (including identifier) - 2 bytes
1 0x0C Field identifier - battery
2 0x64 Battery level in percentages. 0xFF if not applicable (external power supplied). UInt8

Button click

Byte offset Default/sample value Description
0 0x03 Field length in bytes (including identifier) - 3 bytes
1 0x0D Field identifier - button click
2 0x5B Seconds since the last button click event. Saturates on 0xFFFF. UInt8
3 0xA0 Continuation

UTC Time

Byte offset Default/sample value Description
0 0x05 Field length in bytes (including identifier) - 5 bytes
1 0x0F Field identifier - UTC time
2 0x5A Unix timestamp from onboard RTC (in UTC). -1 if not applicable. Int32
3 0x8A Continuation
4 0xBF Continuation
5 0x3D Continuation

Humidity

Byte offset Default/sample value Description
0 0x03 Field length in bytes (including identifier) - 3 bytes
1 0x12 Field identifier - Humidity
2 0x5A Humidity percentage between 0 and 100. UInt8

Precise Temperature

Byte offset Default/sample value Description
0 0x04 Field length in bytes (including identifier) - 4 bytes
1 0x0F Field identifier - Precise Temperature
2 0x5A Temperature as a 8.8 fixed point integer. To get the temperature in °C, divide by 256.0. Int16
3 0x8A Continuation