The Kontakt.io Telemetry packet contains data from sensors. The packet is connectable and uses the same MAC address as the Kontakt.io Secure Profile, Location, and Scan Response packets.
Due to the limited space in a single Bluetooth advertising packet, the quantity 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.
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 |
|
Data length (varies depending on a fields number and their length) |
|
1 |
|
Data type – Service data |
|
2 |
|
Kontakt.io UUID |
|
3 |
|
Kontakt.io UUID |
|
4 |
|
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 |
Note
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.
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 Device Management API specifying a list of Telemetry fields that a beacon should broadcast in the telemetryFields parameter.
Each piece of telemetry data might be represented by its own field. However, to conserve space in the Bluetooth advertising packet some of the most common and related values and parameters may be grouped into a single field.
Important
All multibyte values are little-endian
The default structure of a Telemetry packet is presented in the following table.
|
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 below fields cannot be enabled by an end user. Before making your purchasing decision, get in touch with our Sales Team to discuss your requirements. To get access to the maximum number of options be sure that your beacons have the latest available firmware.
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 6 bytes |
|
1 |
|
Field identifier - system health |
|
2 |
|
Unix timestamp from onboard RTC (in UTC). |
|
3 |
|
Continuation |
|
4 |
|
Continuation |
|
5 |
|
Continuation |
|
6 |
|
Battery level in percentages. |
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 9 bytes |
|
1 |
|
Field identifier - accelerometer |
|
2 |
|
Accelerometer sensitivity. Unit: mg/digit. UInt8 |
|
3 |
|
Raw acceleration value for the X axis, filtered with a lowpass filter. Int8 |
|
4 |
|
Raw acceleration value for the Y axis, filtered with a lowpass filter. Int8 |
|
5 |
|
Raw acceleration value for the Z axis, filtered with a lowpass filter. Int8 |
|
6 |
|
Seconds since the last double tap event. Saturates on |
|
7 |
|
Continuation |
|
9 |
|
Seconds since the last movement/free fall event. Saturates on |
|
10 |
|
Continuation |
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 Device Management API.
API name: RAW_ACCELEROMETER
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 5 bytes |
|
1 |
|
Field identifier - acceleration |
|
2 |
|
Accelerometer sensitivity. Unit: mg/digit. UInt8 |
|
3 |
|
Raw acceleration value for the X axis, filtered with a lowpass filter. Int8 |
|
4 |
|
Raw acceleration value for the Y axis, filtered with a lowpass filter. Int8 |
|
5 |
|
Raw acceleration value for the Z axis, filtered with a lowpass filter. Int8 |
API name: MOVEMENT_THRESHOLD_EVENT
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 3 bytes |
|
1 |
|
Field identifier - movement/free-fall |
|
2 |
|
Seconds since the last double tap event. Saturates on |
|
3 |
|
Continuation |
API name: DOUBLE_TAP_EVENT
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 3 bytes |
|
1 |
|
Field identifier - double tap |
|
2 |
|
Seconds since the last double tap event. Saturates on |
|
3 |
|
Continuation |
API name: LIGHT_LEVEL
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 2 bytes |
|
1 |
|
Field identifier - light level |
|
2 |
|
Light sensor percentage (0-100), |
API name: TEMPERATURE
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 2 bytes |
|
1 |
|
Field identifier - temperature |
|
2 |
|
Temperature in °C. Int8 |
API name: BATTERY
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 2 bytes |
|
1 |
|
Field identifier - battery |
|
2 |
|
Battery level in percentages. |
API name: BUTTON_CLICK
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 3 bytes |
|
1 |
|
Field identifier - button click |
|
2 |
|
Seconds since the last button click event. Saturates on |
|
3 |
|
Continuation |
API name: IDENTIFIED_BUTTON_CLICK
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 4 bytes |
|
1 |
|
Field identifier - button click counter |
|
2 |
|
Button click counter. UInt8 |
|
3 |
|
Seconds since the last button click event. Saturates on |
|
4 |
|
Continuation |
API name: UTC_TIME
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 5 bytes |
|
1 |
|
Field identifier - UTC time |
|
2 |
|
Unix timestamp from onboard RTC (in UTC). |
|
3 |
|
Continuation |
|
4 |
|
Continuation |
|
5 |
|
Continuation |
API name: IDENTIFIED_BUTTON_CLICK
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 4 bytes |
|
1 |
|
Field Identifier - Click ID |
|
2 |
|
Index of current click. Wraps around. Used to identify each click, and how many times the panic button was pressed. uint8 |
|
3 |
|
Seconds since the last Click event. Click event is specified in Button Specification Behavior. Saturates on 0xFFFF value. uint16 |
|
4 |
|
Continuation |
API name: HUMIDITY
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 2 bytes |
|
1 |
|
Field identifier - Humidity |
|
2 |
|
Humidity percentage between |
API name: TEMPERATURE_16_BITS
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 3 bytes |
|
1 |
|
Field identifier - Precise Temperature |
|
2 |
|
Temperature as a 8.8 fixed point integer. To get the temperature in °C, divide by 256.0. Int16 |
|
3 |
|
Continuation |
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 2 bytes |
|
1 |
|
Field identifier - BleChannel |
|
2 |
|
BLE advertising channel, one of {37, 38, 39}. Zero if adv on all channels; uint8 |
API name: MOVEMENT_EVENT
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 4 bytes |
|
1 |
|
Field identifier - movement/free-fall |
|
2 |
|
Movement counter. UInt8 |
|
3 |
|
Seconds since the last movement event. Saturates on |
|
4 |
|
Continuation |
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 5 bytes |
|
1 |
|
Field identifier - Air Pressure |
|
2 |
|
Pressure in Pa (1/100 mbar) Example given for 100628 Pa. The encoding is a little-endian _float32_ |
|
3 |
|
Continuation |
|
4 |
|
Continuation |
|
5 |
|
Continuation |
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 3 bytes |
|
1 |
|
Field identifier - Detection |
|
2 |
|
Seconds since last PIR detection. Saturates at 0xFFFF; uint16 |
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 5 bytes |
|
1 |
|
Field identifier - Click id |
|
2 |
|
Click id on button 1; uint8 |
|
3 |
|
Click id on button 2; uint8 |
|
4 |
|
Time since last click on any of the buttons. Saturates at 0xFFFF; uint16 |
|
5 |
|
Continuation |
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 10 bytes |
|
1 |
0x1d |
Field identifier |
|
2 |
|
MAC address; uint8[6] |
|
4 |
|
Continuation |
|
5 |
|
Continuation |
|
6 |
|
Continuation |
|
7 |
|
Continuation |
|
8 |
|
Continuation |
|
9 |
|
RSSI average; int8 |
|
10 |
|
RSSI standard deviation; uint8_t |
|
11 |
|
RSSI count - number of scans; uint8_t |
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 10 bytes |
|
1 |
|
Field identifier |
|
2 |
|
MAC address; uint8[6] |
|
3 |
|
Continuation |
|
4 |
|
Continuation |
|
5 |
|
Continuation |
|
6 |
|
Continuation |
|
7 |
|
Continuation |
|
8 |
|
Measured distance in [cm]; unt16_t |
|
9 |
|
Continuation |
|
10 |
|
Accuracy 0-100%; uin8_t |
|
Byte offset |
Default/sample value |
Description |
|---|---|---|
|
0 |
|
Field length in bytes (including identifier) - 3 bytes |
|
1 |
|
Field identifier |
|
2 |
|
Gas type, from the table below; uint8_t |
|
3 |
|
Signed, 16-bit PPM concentration, can be a positive PPM, or a difference from baseline; int16_t |
|
4 |
|
Continuation |
Table 2. Gas ID table
|
Gas Id |
Description |
Units |
|---|---|---|
|
0x00 |
Generic |
ppm |
|
0x01 |
Carbon Monoxide |
ppm |
|
0x02 |
Ethanol |
ppm |
|
0x03 |
Volatile Organic Compounds |
ppm |
|
0x04 |
PM 1.0 |
ug/m3 |
|
0x05 |
PM 2.5 |
ug/m3 |
|
0x06 |
PM 10.0 |
ug/m3 |
|
0x06 |
Carbon Dioxide |
ppm |
|
0x08 |
Gas resistance |
㏀ |