# 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](https://zenoh.io/)
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:
- **`RobotUplinkMsg`** (robot software → agent → server): telemetry and status —
global/local motion, status, faults, mission run status, reported
features/objects, system health, usage, capabilities, allowed commands,
settings, etc.
- **`RobotCommand`** (server → agent → robot software): commands — set mode,
navigate-to, velocity, pause/resume, invoke service, mission commands, spatial
features and directives, setting updates, teleop, agent text, 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 `Pause` for a remote pause/halt; robots still *report* their
> physical e-stop state on `StatusTelemetry.estop`.
## Documentation
| [USAGE.md](USAGE.md) | Rust quick start — add the dependency, build/parse `RobotUplinkMsg`/`RobotCommand`, JSON & Cap'n Proto helpers, full variant lists. |
| [CHANGELOG.md](CHANGELOG.md) | Notable changes, including breaking changes and migration notes. |
| [AGENTS.md](AGENTS.md) | Architecture guide — the code-generation pipeline, what to edit where, and the full public serialization API. Useful for contributors and coding agents. |
Start with **USAGE.md** for Rust
## Build & test
```bash
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 (RobotUplinkMsg, RobotCommand, NexusCommand, …)
├── spatial_types.rs # Geometry/spatial types (GeoPose, LocalPose, Pose, SpatialData, …)
├── 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](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](LICENSE). 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.