Skip to content

Telemetry

Kontakt.io Telemetry Packet contains data from sensors available on some beacons. Because of that it can be enabled only on certain beacons: Beacon Pro BP16-3, Asset Tag S18-3, Smart Beacon SB18-3, Heavy Duty Beacon HD18-3, Tough Beacon TB18-2, Card Tag CT18-3, Bracelet Tag BT18-3, Bracelet Tag BT19-4 and Universal Tag 19-1.

This packet is connectable and uses the same MAC address as Kontakt.io Secure Profile, Location and Scan Response packets 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, each containing different pieces of telemetry 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 (varies depending on a 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

Packet configuration

By default Kontakt.io Telemetry Packet contain data only from a subset of possible sources. However, the content of this packet can be easily adjusted to better suits needs of a particular deployment. In order to do that a user needs to send a POST /config/create request to Kontakt.io API, specifying a list of Telemetry fields that a beacon should broadcast in the telemetryFields parameter.

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, some of the most common and related values and parameters might be grouped into a single field.

Important

All multibyte values are little-endian.

The default structure of a Telemetry packet for each beacon (as of Spring 2019) 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
Bracelet Tag S18-3 1st packet Grouped fields: System health, Accelerometer, Sensors
Bracelet 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
Tough Beacon TB18-2 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 Telemetry packets can change, either by users directly configuring beacons differently on their own, or by Kontakt.io switching to different defaults in future firmware versions.

Some of the fields presented below are can not be enabled by end-users. Before making your purchasing decision, please get in touch with our Sales Team to discuss your requirements. Please also make sure that you have the latest available firmware for your beacons to get access to the maximum number of options.

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

Each of these fields can be separately turned on or off by including or omitting it in the telemetryFields parameter for the POST /config/create request to Kontakt.io API.

Acceleration

API name: RAW_ACCELEROMETER

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

API name: MOVEMENT_THRESHOLD_EVENT

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. UInt16
3 0x39 Continuation

Double tap

API name: DOUBLE_TAP_EVENT

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. UInt16
3 0xA0 Continuation

Light level

API name: 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

API name: 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

API name: 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

API name: 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

Button click counter

API name: IDENTIFIED_BUTTON_CLICK

Byte offset Default/sample value Description
0 0x04 Field length in bytes (including identifier) - 4 bytes
1 0x11 Field identifier - button click counter
2 0x06 Button click counter. UInt8
3 0x5B Seconds since the last button click event. Saturates on 0xFFFF. UInt16
4 0xA0 Continuation

UTC Time

API name: 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

API name: HUMIDITY

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

Precise temperature

API name: TEMPERATURE_16_BITS

Byte offset Default/sample value Description
0 0x03 Field length in bytes (including identifier) - 3 bytes
1 0x13 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

Movement counter

API name: MOVEMENT_EVENT

Byte offset Default/sample value Description
0 0x04 Field length in bytes (including identifier) - 4 bytes
1 0x16 Field identifier - movement/free-fall
2 0x06 Movement counter. UInt8
3 0x30 Seconds since the last movement event. Saturates on 0xFFFF. UInt16
4 0x39 Continuation