Skip to content

Telemetry

The Kontakt.io Telemetry packet contains data from sensors available on select beacon models.

Compatible product models

Beacon models Beacon Tag models
Beacon Pro BP16-3 Asset Tag S18-3
Smart Beacon SB18-3 Card Tag CT18-3
Heavy Duty Beacon HD18-3 Bracelet Tag BT18-3
Tough Beacon TB18-2 Bracelet Tag BT19-4
Universal Tag 19-1

The Telementry 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 the amount of data produced, in some circumstances beacons can broadcast more than one Telemetry Packet, each containing different pieces of telemetry data.

General packet structure

The actual content of a Kontakt.io Telemetry packet varies depending on the 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 a Kontakt.io Telemetry packet contains data only from a subset of possible sources. However the content of this packet can be easily adjusted to better suit the needs of a particular deployment. In order to do that, a user needs to send a POST /config/create request to the 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 is presented in the table below:

Beacon type Packet Structure
Without a button Single packet Grouped fields: System health, Accelerometer, Sensors
With a button 1st packet Grouped fields: System health, Accelerometer, Sensors
2nd packet Singular field: Button click

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