Telemetry Data Model

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/kontaktio/main/json-schema/kontaktio-telemetry-schema.json",
  "title": "Telemetry Data Model",
  "description": "Telemetry data varies by product model and configured settings.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kontaktio-telemetry-api-openapi.yml#/components/schemas/Telemetry",
  "type": "object",
  "properties": {
    "content": {
      "type": "array",
      "uniqueItems": true,
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "trackingId": {
            "type": "string",
            "minLength": 1,
            "description": "Tracking Id."
          },
          "timestamp": {
            "type": "string",
            "minLength": 1,
            "description": "Timestamp when telemetry was received by Kio Cloud."
          },
          "beaconTimestamp": {
            "type": "string",
            "minLength": 1,
            "description": "Telemetry timestamp from beacon."
          },
          "gatewayTimestamp": {
            "type": "string",
            "minLength": 1,
            "description": "Telemetry timestamp from gateway."
          },
          "cloudTimestamp": {
            "type": "string",
            "minLength": 1,
            "description": "Timestamp when telemetry comes to Kontakt.io cloud."
          },
          "accelerometerSensitivity": {
            "type": "number",
            "description": "Accelerometer sensitivity.\n\nThe accelerometer sensitivity represents the scale in which the following numbers are given. A sensitivity of 16 means that the numbers are in 16 mg units, or 0.016g.\n\nTo decode a triple [0, 1, 64] with sensitivity 16.:\n\nX component is just 0\n\nY component is -1 * 16 mg = -0.016g\n\nZ component is 64 * 16mg = 1.024g\n\nSo the raw vector [0, -1, 64] gets multiplied by 0.016g and the resulting vector is: [0, -0.016, 1.024] g.016g."
          },
          "accelerometerX": {
            "type": "number",
            "description": "Accelerometer in X axis. "
          },
          "accelerometerY": {
            "type": "number",
            "description": "Accelerometer in Y axis."
          },
          "accelerometerZ": {
            "type": "number",
            "description": "Accelerometer in Z axis."
          },
          "batteryLevel": {
            "type": "number",
            "description": "Device battery level in percentage (%)."
          },
          "channel": {
            "type": "number",
            "description": "Channel."
          },
          "clickCounter": {
            "type": "number",
            "description": "Click counter for default button (BLUE button)."
          },
          "secondButtonClickCounter": {
            "type": "number",
            "description": "Click counter for second button (RED button)."
          },
          "humidity": {
            "type": "number",
            "description": "Humidity reading in percentage (%)."
          },
          "lightIntensity": {
            "type": "number",
            "description": "Light intensity in percentage (%)"
          },
          "rssi": {
            "type": "number",
            "description": "RSSI in dB"
          },
          "movementCounter": {
            "type": "number",
            "description": "Movement counter."
          },
          "sourceId": {
            "type": "string",
            "minLength": 1,
            "description": "Source Id."
          },
          "temperature": {
            "type": "number",
            "description": "Temperature reading in Celsius."
          },
          "airQuality": {
            "type": "number",
            "description": "Index 0 to 255. The higher the value, the worse the air pollution."
          },
          "roomNumber": {
            "type": "number",
            "description": "Room number detected by device sensor."
          },
          "numberOfPeopleDetected": {
            "type": "number",
            "description": "Detected number of people in the room (count)."
          },
          "secondsSincePeopleDetection": {
            "type": "number",
            "description": "Time since last detection in seconds."
          },
          "timeSinceClick": {
            "type": "number",
            "description": "Time since click."
          },
          "timeSinceDoubleTap": {
            "type": "number",
            "description": "Time since double click."
          },
          "timeSinceMovement": {
            "type": "number",
            "description": "Time since movement."
          },
          "timeSinceTap": {
            "type": "number",
            "description": "Time since tap."
          },
          "firmware": {
            "type": "string",
            "minLength": 1,
            "description": "Firmware version of scanned device."
          },
          "model": {
            "type": "number",
            "description": "Scanned device version number."
          },
          "txPowerDbm": {
            "type": "number",
            "description": "Transmission Power (in dBm) of a scanned device."
          },
          "uniqueId": {
            "type": "string",
            "minLength": 1,
            "description": "Unique identifier (id) of a scanned device."
          },
          "calibratedRssi1m": {
            "type": "number",
            "description": "Calibrated RSSI value at 1 meter from a scanned device."
          },
          "calibratedRssi0m": {
            "type": "number",
            "description": "Calibrated RSSI value at 0 meters from a scanned device."
          },
          "moving": {
            "type": "boolean",
            "description": "Flag showing whether device is currently in motion."
          },
          "eddystoneNamespace": {
            "type": "string",
            "minLength": 1,
            "description": "Namespace value from Eddystone UID frame."
          },
          "eddystoneInstanceId": {
            "type": "string",
            "minLength": 1,
            "description": "Instance ID value from Eddystone UID frame."
          },
          "eddystoneEphemeralId": {
            "type": "string",
            "minLength": 1,
            "description": "Ephemeral value from Eddystone EID frame."
          },
          "iBeaconProximity": {
            "type": "string",
            "minLength": 1,
            "description": "Proximity UUID value from iBeacon frame."
          },
          "iBeaconMajor": {
            "type": "number",
            "description": "Major value from iBeacon frame."
          },
          "iBeaconMinor": {
            "type": "number",
            "description": "Minor value from iBeacon frame."
          }
        },
        "required": [
          "trackingId",
          "timestamp",
          "beaconTimestamp",
          "gatewayTimestamp",
          "cloudTimestamp"
        ]
      }
    }
  }
}