Enabling and configuring the Telemetry Packet
Kontakt.io Telemetry packet is a proprietary Bluetooth advertising packet responsible for transmitting sensor readings to Gateways GW16-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 all 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 basic settings like 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
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.
Customizing the Telemetry packet content
POST /config/create endpoint allows to customize the content that should be broadcasted in Telemetry packets. It's possible through
telemetryFields property where you specify a list of sensor values that should be included in a broadcast. To learn more about possible options, please refer to Telemetry packet specification in the Hardware section.
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 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:
|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
Acceleration values reported by beacons and Data Streams 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.
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
DOUBLE_TAP_DETECTION entries in the value for the
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.
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.
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
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.doubleTapDetection parameters, as well as use it for raw accelerometer data by setting
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.
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 Data Streams. Getting this data from Data Streams is described in this article: Monitoring Data Streams