Skip to content

Data Streams

Data Streams are MQTT streams of data collected by Kontakt.io or some 3rd party Gateways. Currently this data is available in several forms that are results of iterations of this product prompted by customer feedback. As of now we don't have any plans to completely turn off any of them, but for new projects we strongly suggest sticking with our recommended streams.

/stream/:uniqueId/all

Returns an object including all telemetry data broadcasted by a single beacon. Please keep in mind that a capacity of a single BLE advertising packet is limited, so it's possible a beacon may broadcast more than one Telemetry Packet, each containing different types of data. A single message from this stream will only contain data from a single packet, so subsequent messages can have completely different structures, with different data types.

Apart from Telemetry Packet data, this stream also includes data from Location Packet.

Messages can include any of the key-value pairs mentioned in the description of the deprecated (legacy) streams below as well as any new data that we might add in the future to Telemetry and/or Location Packet.

Important

This topic provides data only from a single device. Since a typical deployment usually uses hundredths or thousands of tags, getting all data requires a subscription to a separate topic for each beacon. Because of that lease keep in mind to subscribe to each topic within the same connection to MQTT broker to guarantee the best performance and stability.

telemetry/:companyId

Similarly to /stream/:uniqueId/all this stream provides complete Telemetry data, but in this case data comes from all detected beacons belonging to all accounts from User's Company. Contrary to the previous stream, all Telemetry data from a single beacon is aggregated into a one message. Additionally, detected devices are reported only once every 30 seconds, unless one of the broadcasted values changes, except time-based values, like timestamp or lastDoubleTap.

Apart from Telemetry Packet data, this stream also includes data from Location Packet.

Messages can include any of the key-value pairs mentioned in the description of the deprecated (legacy) streams below as well as any new data that we might add in the future to Telemetry Packet.

/stream/:uniqueId/location

Provides information from Location Packets broadcasted by a given beacon

{
    "sourceId": "etAfCw",
    "trackingId": "WsO1Tr",
    "rssi": -89,
    "txPower": -8,
    "moving": false,
    "channel": 37,
    "timestamp": 1554276390000,
    "distance": 4.72251958192618
}
Key Value
timestamp Unix epoch timestamp of the scan
sourceId ID of the Gateway that has made the scan
trackingId ID of the detected device - Unique ID, if it's a Kontakt.io beacon or MAC address, for all other type of devices
rssi RSSI in dBm
txPower Transmission power in dBm
moving Boolean indicating whether the detected device is moving (true) or not (false)
channel BLE advertising channel on which a given packet was broadcasted
distance Estimated distance from the scan source to the detected device in meters

Note

Due to the nature of the Location frame (the fact that it broadcast only on a single BLE channel), the accuracy of the distance value should be better than the one from Presence streams, although it should still be considered an estimation.

Legacy streams

There are two groups of Legacy streams, that due to the evolution of Kontakt.io products are not flexible enough to handle new types of data or require a lot of work to provide meaningful insights. Because of that we no longer recommend basing new projects on these solutions.

The Presence stream returns data about beacons detected by a single or a group of Gateways.

Each Telemetry stream is identified by it's topic, which is constructed using this schema: /stream/:uniqueId/:streamType. :uniqueId should be replaced with an actual Unique ID of a beacon with Kontakt.io Telemetry Frame enabled and the :streamType takes one of four values: health, accelerometer, sensor, button or all.

Presence

  • /presence/stream/:receiverId – for data from a single Gateway
  • /stream/:venueId/presence – for data from all Gateways assigned to a single Location (Venue)
[
    {
        "timestamp": 1518074427,
        "sourceId": "zYwiz",
        "trackingId": "JPjL",
        "rssi": -101,
        "proximity": "FAR",
        "scanType": "BLE",
        "deviceAddress": "f2:54:3e:76:5a:6e",
        "distance": 5.982267064262634
    },
    {
        "timestamp": 1518074426,
        "sourceId": "zYwiz",
        "trackingId": "03:97:15:87:ac:d7",
        "rssi": -79,
        "proximity": "NEAR",
        "scanType": "BLE",
        "deviceAddress": "03:97:15:87:ac:d7",
        "distance": 3.1064292267626348
    }
]
Key Value
timestamp Unix epoch timestamp of the scan
sourceId ID of the Gateway that has made the scan
trackingId ID of the detected device - Unique ID, if it's a Kontakt.io beacon or MAC address, for all other type of devices
rssi RSSI in dBm
proximity Estimated proximity zone. Possible values are IMMEDIATE, NEAR and FAR.
scanType Type of radio used for the scan. Possible values are BLE and WIFI.
deviceAddress MAC address of the detected device
distance Estimated distance from the scan source to the detected device in meters

Note

The distance value is only an estimation based on a relatively simple comparison between detected RSSI and a reference RSSI set for a given beacon. Please be aware that it might not be highly accurate in all deployments.

Basic Telemetry

Attention

When Telemetry streams were first introduced, the Telemetry data available from Kontakt.io devices was relatively simple and limited. Due to significant improvements and additions to Telemetry Packets the original streams can't scale to handle the new data. Because of that we recommend using the /stream/:uniqueId/all whenever possible.

We don't have any immediate plans to turn off access to the streams described below, but please keep in mind they are officially marked as deprecated.

/stream/:uniqueId/health

Data about beacon's battery life and RTC.

{
    "deviceUtcTime": 1503297853,
    "batteryLevel": 56,
    "externalPower": false,
    "sourceId": "GTw1a",
    "rssi": -89
}
Key Value
deviceUtcTime Unix Epoch timestamp generated by beacon's RTC.
batteryLevel Estimated percentage of remaining battery power. null if externalPower is true.
externalPower Boolean indicating whether a beacon is powered via external source (true) or internal batteries (false).
sourceId Unique ID of a Gateway that has detected the Telemetry data.
rssi Strength of the detected signal in dBm

/stream/:uniqueId/accelerometer

Information about raw accelerometer readings and accelerometer-based events.

{
    "sensitivity": 16,
    "x": 0,
    "y": -30,
    "z": 5,
    "lastDoubleTap": 120,
    "lastThreshold": 15,
    "sourceId": "GTw1a",
    "rssi": -89
}
Key Value
sensitivity Accelerometer's sensitivity setting (in mg).
x Acceleration value on X axis (in units defined by sensitivity, more information here).
y Acceleration value on Y axis (in units defined by sensitivity, more information here).
z Acceleration value on Z axis (in units defined by sensitivity, more information here).
lastDoubleTap Number of seconds since the last Double Tap Event. Possible values are in range from 0 to 65535. Value 65535 means that Double Tap detection is either disabled or this type of event hasn't occurred yet.
lastThreshold Number of seconds since the last Movement (either Basic or Free Fall) Event. Possible values are in range from 0 to 65535. Value 65535 means that Movement detection is either disabled or this type of event hasn't occurred yet.
sourceId Unique ID of a Gateway that has detected the accelerometer data.
rssi Strength of the detected signal in dBm

/stream/:uniqueId/sensor

Readings from sensors other than the accelerometer.

{
    "lightLevel": 56,
    "temperature": 26,
    "sourceId": "GTw1a",
    "rssi": -89
}
Key Value
lightLevel Brightness level. Possible values are in range from 0 to 100. Value 255 means a beacon is not equipped with a light level sensor.
temperature Temperature in °C.
sourceId Unique ID of a Gateway that has detected the sensor data.
rssi Strength of the detected signal in dBm

/stream/:uniqueId/button

Information about button press events from button-equipped beacons.

{
    "sourceId": "GTw1a",
    "lastSingleClick": 26
}
Key Value
sourceId Unique ID of a Gateway that has detected the button press event.
lastSingleClick Number of seconds since the the button press event.