MQTT Real-Time Data API

General

The Koherent Grid MQTT API is used for subscribing to real-time data from Koherent Grids using the MQTT protocol.

Authentication

Authentication is required to subscribe to any MQTT topics included in this documentation. Basic authentication is used, meaning that the client has to provide a valid username and password when subscribing to a topic.

Client IDs

The client ID is an identifier used by MQTT for identifying individual subscribers. The id has to be a globally unique string, with a maximum length of 256 characters.

Topics

Depending on the Grid configuration, one or more of the topics described below will be available for subscription.

Position data v0 [deprecated]

warning

This topic is deprecated and will be removed in a future release. Please use the below v1 instead.

v0/measurement/<target_id>

Position data v1

v1/position/<target_id>

Subscribe to measurement data describing a target's position, orientation and the respective error estimates.

The + wildcard can be used for receiving data for all available targets:

v1/position/+

Data format

Field	Type	Data type	Description
timestamp	required	string	The time of the measurement (ISO 8601 timestamp)
x	required	float64	Target x coordinate in meters
y	required	float64	Target y coordinate in meters
z	required	float64	Target z coordinate in meters
yaw	required	float64	Target yaw angle in degrees
pitch	required	float64	Target pitch angle in degrees
roll	required	float64	Target roll angle in degrees
error_x	required	float64	Target x coordinate error estimate in meters
error_y	required	float64	Target y coordinate error estimate in meters
error_z	required	float64	Target z coordinate error estimate in meters
error_yaw	required	float64	Target yaw angle error estimate in degrees
error_pitch	required	float64	Target pitch angle error estimate in degrees
error_roll	required	float64	Target roll angle error estimate in degrees

Data example

{
    "timestamp": "2023-08-27T13:04:57.950255286Z",
    "x": 20.08106231689453,
    "y": -4.077945709228516,
    "z": 0.578690528869289,
    "yaw": 180.0592245782578,
    "pitch": -0.189548754785755,
    "roll": 10.07396251629481,
    "error_x": 0.000022246194930630736,
    "error_y": 0.00007646845915587619,
    "error_z": 0.00024494959507137537,
    "error_yaw": 0.0016238032660330646,
    "error_pitch": 0.0024387806479353458,
    "error_roll": 0.004775759538868442
}

Distance data

v1/distance/<target_id>

Subscribe to distance measurement data.

The + wildcard can be used for receiving data for all available target distances:

v1/distance/+

Data format

Field	Type	Data type	Description
timestamp	required	string	The time of the measurement (ISO 8601 timestamp)
d	required	float64	The distance in meters
error_d	required	float64	The distance error estimate in meters

Data example

{
    "timestamp": "2025-01-27T09:24:20.053378266Z",
    "d": 12.828408363174582,
    "error_d": 0.00031422923099173184
}

Examples

Python

Subscribing to measurement data with Python using the Paho MQTT client.

Install the Paho client with:

pip3 install paho-mqtt~=2.1.0

note

A Python version >= 3.8 is required.

from paho.mqtt import client as mqtt_client
from paho.mqtt.enums import CallbackAPIVersion
from time import time

client = mqtt_client.Client(
    client_id=f"example-client-{round(time())}", 
    callback_api_version=CallbackAPIVersion.VERSION2
)
client.username_pw_set("<username>", "<password>")
client.connect("<api_host>", <api_port>)

def on_message(client, userdata, msg):
    print(f"[{msg.topic}]: {msg.payload.decode()}")

def on_connect(client, userdata, flags, rc, props):
    client.subscribe("v1/position/+")

def on_disconnect(client, userdata, flags, rc, props):
    if rc != 0:
        print(f"Unexpected disconnect (reason code: {rc})")
        print("Attempting auto-reconnect")

client.on_message = on_message
client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.loop_forever()

C++

Subscribing to measurement data with C++ using the Paho MQTT client.

#include <iostream>
#include <chrono>
#include <sstream>
#include "mqtt/client.h"


int main() {
    auto now = std::chrono::system_clock::now();
    auto nowSec = std::chrono::system_clock::to_time_t(now);
    std::stringstream clientId;
    clientId << "example-client-" << nowSec;

    mqtt::client cli("<api_host>:<api_port>", clientId.str());
    auto connOpts = mqtt::connect_options_builder()
        .user_name("<username>")
        .password("<password>")
        .finalize();
    cli.connect(connOpts);
    cli.subscribe("v1/position/+", 0);

    while (true) {
        auto msg = cli.consume_message();
        if (msg) {
            std::cout << "[" << msg->get_topic() << "]: " << msg->to_string() << std::endl;
        }
    }

    return 0;
}

Go

Subscribing to measurement data with Go using the Paho MQTT client

Install the Paho client with: go get github.com/eclipse/paho.mqtt.golang

package main

import (
    "fmt"
    "os"
    "os/signal"
    "time"

    mqtt "github.com/eclipse/paho.mqtt.golang"
)

func main() {
    clientID := fmt.Sprintf("example-client-%d", time.Now().Unix())
    opts := mqtt.NewClientOptions()
    opts.AddBroker("tcp://<api_host>:<api_port>")
    opts.SetClientID(clientID)
    opts.SetUsername("<username>")
    opts.SetPassword("<password>")
    client := mqtt.NewClient(opts)
    if token := client.Connect(); token.Wait() && token.Error() != nil {
        fmt.Println(token.Error())
        return
    }

    token := client.Subscribe("v1/position/+", 0, onMessage)
    token.Wait()

    c := make(chan os.Signal, 1)
    signal.Notify(c, os.Interrupt)
    <-c
}

func onMessage(c mqtt.Client, msg mqtt.Message) {
    fmt.Printf("[%s]: %s\n", msg.Topic(), msg.Payload())
}