rover_nexus_core

rover_nexus_core is the Rust library crate that defines the message types used to talk to the robot agent and get a robot onto the fleet manager. It is the single source of truth for the wire format — both the Cap'n Proto binary encoding and the JSON encoding — for communication between robotic vehicles (rovers, drones, etc.) and the fleet-management server.

The robot↔server hop is SecureLink v2: raw QUIC+mTLS, with each Cap'n Proto (or JSON) payload framed by a single-byte MessageClass envelope (src/wire_envelope.rs). On-device messaging between the robot software and the agent that relays to the server is still local Zenoh pub/sub.

If you are integrating a robot, this crate (and the docs linked below) is what you build against.

Two communication planes

Data plane — the messages your robot software exchanges with the on-robot agent, which relays them to/from the fleet manager. Your robot software talks to the agent, not the server directly:

• UplinkMsg (robot software → agent → server): telemetry and status — motion, status, faults, events, mission run status, reported shapes/objects, system health, usage, capabilities, settings, etc.
• InternalCommand (server → agent → robot software): commands — set mode, go-to, velocity, stop/resume, invoke service, mission commands, spatial features and directives, setting updates, teleop, etc. On the agent channel each command is wrapped in a NexusCommand carrying a per-command UUID.

Control plane — transport/health signals handled by the agent, not the robot software (their own MessageClass lanes on the QUIC link — Heartbeat, HeartbeatAck, Ack):

• AgentTelemetry (Heartbeat, RobotAck) and HeartbeatAck.

There are also request/response message pairs for fetching stored state: features, spatial directives, and settings.

Safety note: there is intentionally no remote e-stop command. Emergency stop is a physical safety function and must not be triggered over the wire. Use Stop for a remote pause/halt; robots still report their physical e-stop state on StatusTelemetry.estop.

Documentation

Start with USAGE.md for Rust

Build & test

cargo build   # runs build.rs, which compiles schema/*.capnp into generated code
cargo test    # runs the roundtrip serialization tests

Prerequisite: the Cap'n Proto compiler (capnp) must be installed on the build machine (e.g. apt install capnproto). Everything else is pulled in via Cargo.

How the code is organized

rover_nexus_core/
├── schema/                  # Cap'n Proto schemas — source of truth for the binary wire format
│   ├── messages.capnp
│   ├── features_query.capnp
│   ├── spatial_directives_query.capnp
│   └── settings_query.capnp
├── build.rs                 # Compiles schema/*.capnp at build time
└── src/
    ├── core_model.rs        # Rust domain types (UplinkMsg, InternalCommand, NexusCommand, …)
    ├── internal_model.rs    # Control-plane types (AgentTelemetry, Heartbeat, RobotAck, …)
    ├── wire_envelope.rs     # SecureLink v2 MessageClass envelope + JsonMessage (QUIC framing)
    ├── features_query.rs    # Feature query request/response types
    ├── spatial_directives_query.rs
    ├── settings_query.rs
    ├── states.rs            # On-robot state helpers
    ├── system_health.rs     # SystemHealth::collect() — reads CPU/mem/disk/temp/wifi
    ├── capnp_messages.rs            # Hand-written Cap'n Proto <-> Rust glue (serialize/deserialize)
    ├── capnp_features_query.rs
    ├── capnp_spatial_directives_query.rs
    └── capnp_settings_query.rs

The flow is: schema/*.capnp → (compiled by build.rs) → generated Builder/Reader code → wrapped by the hand-written capnp_*.rs glue → exposed as serialize_* / deserialize_* functions over the Rust domain types in core_model.rs and friends. See AGENTS.md for the full pipeline and the complete list of public serialization functions.

Serialization conventions

• Encodings: Cap'n Proto for the binary wire format; JSON (via serde) as an alternative text encoding. Both are generated from the same Rust types.
• Naming: Rust uses snake_case; Cap'n Proto and JSON use camelCase (serde applies #[serde(rename_all = "camelCase")]).
• Time: wall-clock timestamps are i64 milliseconds since the Unix epoch, suffixed _ms / Ms (e.g. unixTimeMs). There is no nanosecond representation. Durations are suffixed _s (seconds) or _ms.
• Enums: externally tagged in JSON — { "variantName": <data> }, with unit variants as the bare string "variantName".
• Optional fields (Cap'n Proto): modeled with a companion hasFieldName bool (e.g. hasBattery, hasVelocity).

License

Licensed under the Apache License, Version 2.0. Copyright 2026 Rottinghaus Dynamics. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.