Quickstart

Ship your first mission in five minutes

Install, define a mission with phases and telemetry, see it land in the dashboard. No hardware required — works against a local sim, your real robot, or anything in between.

1

Install the SDK

Python 3.10+ supported. The package is on PyPI.
Bashpip install robotrace-sdk
2

Run the platform locally

Clone the repo and start the stack with Docker Compose. This brings up the API server (8080), the worker, the dashboard (3000), and an embedded ClickHouse + Postgres. The default dev credentials (rt-pk-dev-default / rt-sk-dev-default) work out of the box.
Bashgit clone https://github.com/FaultLine-labs/rosp.git
cd rosp
docker compose up -d
3

Send your first mission

A mission wraps a unit of work; phases break it into stages; telemetry flows under each phase; decisions and scores capture what happened and how well. This single script exercises the full SDK surface for a typical mission.
Pythonfrom robotrace import RoboTrace, Pose3D, Battery

rt = RoboTrace(
    host="http://localhost:8080",
    public_key="rt-pk-dev-default",   # dev defaults — replace in prod
    secret_key="rt-sk-dev-default",
    device_id="my-first-robot",
    device_type="amr",
    manufacturer="Acme",
    model="MK1",
    environment="simulation",
)

with rt.mission("patrol-aisle-3", tags=["patrol", "shift-A"]) as mission:
    mission.decision(
        name="route_planned",
        model="dijkstra_v1",
        input={"waypoints": 4},
        output={"path_length_m": 18.4},
        confidence=0.99,
    )
    with mission.phase("traverse") as phase:
        for x, y in [(0, 0), (5, 0), (5, 5), (0, 5)]:
            phase.log("robot/pose", Pose3D(x=x, y=y, z=0,
                                            qx=0, qy=0, qz=0, qw=1))
            phase.log("sensors/battery",
                      Battery(voltage=24.0, soc=92.0))
    mission.score("cycle_time_seconds", 32.4)
    mission.score("success", True)

rt.flush()
rt.shutdown()
4

See it in the dashboard

The mission, phases, decisions, scores, and time-series telemetry are all visible immediately. Each mission carries a trace_id that ties together multi-device traces.
Bash# See your mission in the dashboard:
open http://localhost:3000/missions

# Or query the API directly:
curl -u rt-pk-dev-default:rt-sk-dev-default \
     http://localhost:8080/api/v1/missions
5

Plug in a real adapter

The SDK ships nine reference adapters: ROS 2 / ROSP, VDA 5050, MQTT, Open-RMF, OPC-UA, MoveIt, Isaac Sim, CARLA, and MAVLink converters. Wrap any of them in RoboTraceMiddleware to auto-tag every mission with the adapter that produced it.
Pythonfrom robotrace import RoboTrace
from robotrace.integrations.rosp import RoboTraceMiddleware
from robotrace.integrations.rosp.adapter import RospAdapter   # or vda5050, mqtt, ...

rt = RoboTrace(host="http://localhost:8080", ...)

async with RoboTraceMiddleware(rt, RospAdapter(...)) as adapter:
    # adapter.feed_*() — emits typed telemetry via RoboTrace
    # Missions opened here auto-tag adapter:rosp
    pass

Next steps