Open Road Code

Interface documentation

ZeroMQ messaging interfaces.

What Open Road Code publishes, what it commands, where each message goes, and the IDD that defines the contract.

At a glance

Two patterns. One IPC layer.

Live state uses PUB/SUB so many consumers can listen independently. Operations that need a definite answer use REQ/REP.

Services
↓
PUB/SUBlive state
REQ/REPcommands
broker:5556 → :5557
navigation:5560
PUB
Publishers connecttcp://127.0.0.1:5556

Navigation, vehicle, guidance, and future telemetry producers.

SUB
Subscribers connecttcp://127.0.0.1:5557

UIs, loggers, diagnostics, and any other state consumer.

REQ
Navigation commandstcp://127.0.0.1:5560

Direct service endpoint for acknowledged operations.

PUB / SUB

Telemetry topics

Multipart messages contain a UTF-8 topic followed by a versioned JSON payload.

POSITIONmaster

openroad.navigation.position

Absolute position, altitude, speed, course, GNSS fix, and satellite metadata.

Producer
Navigation service
Publisher
NavigationStatePublisher
View Position State IDD →
MOTIONmaster

openroad.navigation.motion

Heading, ground speed, vertical speed, turn rate, and motion-cache state.

Producer
Navigation service
View Message Bus IDD →
ATTITUDEmaster

openroad.navigation.attitude

Fused heading, pitch, and roll orientation.

Producer
Navigation service
View Message Bus IDD →
IMUmaster

openroad.navigation.imu

Acceleration, linear acceleration, and angular-velocity XYZ vectors.

Producer
Navigation service
View Message Bus IDD →
VEHICLEmaster

openroad.vehicle.state

Normalized engine, speed, throttle, pressure, temperature, fuel, airflow, and voltage telemetry.

Producer
Automotive service
Publisher
VehicleStatePublisher
View Vehicle State IDD →
GUIDANCEnavigation_zmq

route_guidance.state

Route progress, remaining distance, maneuvers, off-route state, and completion.

Producer
Navigation session
Publisher
RouteGuidancePublisher
View Route Guidance IDD →
Telemetry envelope and contract rules

Physical quantities use SI units, normalized quantities use 0.0..1.0, unavailable nullable values are explicit null, and consumers remain independent of the physical or simulated producer.

{
  "version": 1,
  "timestamp": {"seconds": 1787337000, "nanoseconds": 123456000},
  "source": "producer-name",
  "data": {}
}

REQ / REP

Navigation commands

Commands bypass the telemetry broker and go directly to the service that owns the operation.

COMMANDnavigation_zmq

navigation.calibrate_stationary

Runs stationary IMU calibration and returns an explicit success or failure.

Arguments
sample_count, sample_interval_s
Owner
Navigation service
View Command Service IDD →
COMMANDnavigation_zmq

navigation.reset_heading

Resets the navigation heading reference to a requested heading.

Arguments
heading_deg, default 0.0
Owner
Navigation service
View Command Service IDD →
COMMANDnavigation_zmq

navigation.route.calculate

Calculates a route and returns distance, duration, route shape, and maneuvers.

Arguments
origin · destination · travel mode
Modes
AUTO · BICYCLE · PEDESTRIAN · MOTORCYCLE
View Command Service IDD →
Example request and response

Request

{
  "command": "navigation.route.calculate",
  "arguments": {}
}

Response

{
  "ok": true,
  "message": "Route calculated",
  "data": {}
}

Failures use the same response shape with ok: false and a human-readable reason.

Ownership

Where the pieces live

messaging/contracts/

Topics, codecs, validators, decoders, and publisher helpers.

messaging/zeromq/

Endpoints, broker, publisher, subscriber, and transport primitives.

services/navigation/

Navigation state production and command semantics.

services/automotive/

Vehicle acquisition and normalized vehicle-state publication.

docs/idd/

Normative domain interface definitions.

docs/messaging/

Bus topology, framing, lifecycle, configuration, and extension rules.

Why Open Road Code uses both patterns

PUB/SUB is intentionally decoupled: dashboards, loggers, diagnostics, and web UIs can all observe state without the producer knowing they exist.

REQ/REP represents operations. Calibration, heading reset, and route calculation need validation, a definite result, and timeout behavior.