Skip to content

Enabling and configuring the Telemetry Packet

Kontakt.io Telemetry packet is a proprietary Bluetooth advertising packet responsible for transmitting sensor readings to Gateways GW17-2 and other 3rd party BLE scanners. This packet is not enabled by default, so in order to start collecting telemetry data it needs to be turned on manually. Alternatively, per customer's request Kontakt.io can provide preconfigured beacons with this packet turned on right out of the box.

Configuration via API

Enabling Telemetry packet uses the same process as any other beacon configuration changes. First step requires creating a pending configuration with new settings. Currently Telemetry-related settings are available only via Kontakt.io Management API. They are editable through the standard endpoint for creating new configs - POST /config/create. Support in Kontakt.io Panel at the moment is limited only to turning on and off the Telemetry packet.

Turning on the Telemetry packet

The first step is to set packets parameter of your POST /config/create request to a list of packets that a beacon should broadcast. Kontakt.io Telemetry packet uses KONTAKT_TLM label in Kontakt.io API. For example, if we want our beacon to broadcast iBeacon and Kontakt.io Telemetry packets, we would use this value for packets parameter: IBEACON,KONTAKT_TLM.

By default, once enabled, Telemetry packet contains data from light sensor and thermometer, as well as raw acceleration values from all three axes and information about the time since last movement detection event.

Monitored axes

Once enabled the accelerometer will start reporting acceleration values from all three axes. However, if there is a need to limit these measurements, each axis can be enabled and disabled at will. It happens by setting accelerometer.features parameter to a list of desired axes and accelerometer events. Default value is: ACCELEROMETER,X_AXIS,Y_AXIS,Z_AXIS,MOVE_DETECTION.

Accelerometer range and sensitivity

The accelerometer used in Kontakt.io beacons has an adjustable sensitivity resolution. This parameter has a direct correlation to the measurement range:

Sensitivity Range
16 mɡ -2 ɡ to +2 ɡ
32 mɡ -4 ɡ to +4 ɡ
64 mɡ -8 ɡ to +8 ɡ
128 mɡ -16 ɡ to +16 ɡ

Note: g stands for standard acceleration due to gravity.

The sensitivity is configured through accelerometer.sensitivity parameter. Acceptable values are 16, 32, 64 and 128.

Acceleration values reported by beacons and Location Engine are in units defined by the sensitivity. It means that in order to get acceleration represented in standard gravity, the reported values for each axes need to be multiplied by the sensitivity.

For example, a stationary Beacon Pro with accelerometer.sensitivity parameter set to 16, that is laid flat, should report acceleration value on the Z axis around 63. It means that a standard gravity is 63 × 16 = 1008 mg ≈ 1 g.

Event detection

Apart from reporting raw values, Kontakt.io beacons can detect certain acceleration-based events and report time (in seconds) since they've happened. Each of these events have their own fully customizable parameters, that allow to fine-tune them according to ones needs, but we also provide predefined presets for a quick start with this new feature.

Move detection event

Move event is triggered if on any of the enabled axes acceleration value exceeds a Move threshold (accelerometer.move.threshold in mg) for a time longer or equal to a Move duration time period (accelerometer.move.duration in ms).

Double tap detection event

Double tap event is triggered if on any of the enabled axes acceleration value exceeds a Double tap threshold (accelerometer.doubleTap.threshold in mg) twice, each for time period shorter than Double tap time limit (accelerometer.doubleTap.timeLimit in ms), with time gap between them greater than Double tap time latency (accelerometer.doubleTap.timeLatency in ms) but less than Double tap time latency + Double tap time window (accelerometer.doubleTap.timeWindow in ms). When this event is detected, the LED on a beacon blinks (LED can't be disabled).

Enabling event detection

To enable event detection the config needs to include the MOVE_DETECTION and/or DOUBLE_TAP_DETECTION entries in the value for the accelerometer.features parameter.

Presets

Since the number of settings, values they can be set to, and all possible combinations of them, here are some recommended presets, that should be a good starting points for using Event Detection. Instead of providing all parameters, just set accelerometer.preset to one of the preset name, available below.

You can also see the actual settings behind these presets in the Accelerometer Presets article. These presets can be a good starting point for further experimentation and fine-tuning.

Move detection

  • MOVEMENT - Basic movement. Detects when a beacon was moved in any way.
  • FREE_FALL - Free fall. Detects when a beacon was in a free fall (e.g. was dropped or fell from the mounting point it was attached to).

Double tap detection

  • DOUBLE_TAP - Detects when a beacon was tapped twice.

Mixed events

It's possible to combine Double tap detection with Movement detection

  • DOUBLE_TAP_AND_MOVEMENT - Basic movement and Double tap
  • DOUBLE_TAP_AND_FREE_FALL - Free fall and Double tap

High-pass filter

In order to make event detection more reliable, accelerometer signals are processed with a high-pass filter. It helps with removal of the constant elements of the signal - gravity acceleration and signal noise.

High-pass filter by default affects only event detection. It's possible to turn the filtering on and off for each type of events separately, using the accelerometer.highPass.moveDetection and accelerometer.highPass.doubleTapDetection parameters, as well as use it for raw accelerometer data by setting accelerometer.highPass.accelerometerData to true. However, please keep in mind that the filter is configured just once and the same configuration applies to all typed of event detections and data.

Additional notes

Power consumption. Enabling accelerometer impacts battery life, but the number of accelerometer-based features that's used does not change it.

Sampling frequency. The frequency is set to 25 Hz. It is not configurable.

Signal noise. The strength of the noise typically equals to ±2 sensitivity units for a stationary mounted beacon, e.g. ±32 mg for 2 g range.

Next step – Reading the Telemetry data

Telemetry packets are detected by Kontakt.io Gateways and forwarded to Location Engine. Getting this data from Location Engine is described in this article: Monitoring Location Engine data