copper-project/copper-rs

Copper Runtime & SDK – Rust‑based robot task engine

What it is – Copper is a Rust library and runtime that lets you describe a robot’s control logic as a static task graph (written in the human‑readable RON format). The graph is compiled into a highly‑optimized, zero‑allocation executor that can run on anything from a desktop Linux box to a bare‑metal microcontroller. While the robot runs, Copper records all messages, timestamps and state into a single .copper log that can later be replayed deterministically for debugging or analysis.

Why it matters – Robotics software often struggles with latency spikes, nondeterministic behaviour, and the difficulty of moving code between simulation, Linux, and embedded targets. Copper solves these pain points by:

• Static, compile‑time wiring – the whole control pipeline is known at compile time, giving the Rust compiler a chance to eliminate overhead.
• Realtime‑first execution – the hot path allocates nothing and is data‑oriented, which is crucial for tight control loops.
• Deterministic replay – every run can be reproduced exactly, making debugging far easier.
• Cross‑platform – the same codebase runs on Linux/macOS, single‑board computers (e.g., Raspberry Pi) and on‑chip microcontrollers (STM32, etc.).
• Interoperability – can talk to ROS 2 via Zenoh, and provides Python bindings for higher‑level tooling.

Key components

Component	Role
copperconfig.ron	Declarative description of the static task graph (sources, tasks, sinks).
#[copper_runtime] macro	Generates the concrete runtime that wires the graph at compile time.
cu29 crate (on crates.io)	The core runtime library that executes the graph, records logs, and provides replay APIs.
cargo-cunew template tool	Scaffolds new Copper projects (creates src/main.rs, src/tasks.rs, a justfile, etc.).
just helpers	Commands for visualising the graph, inspecting the generated schedule, and replaying logs.
Telemetry support	Streams live task data over UDP to a ground‑station and can reconstruct a deterministic twin locally.

Typical workflow

1. Declare – Write a copperconfig.ron file that lists the nodes (sources, processing tasks, sinks) and how they connect.
2. Generate – Apply the #[copper_runtime] attribute; Cargo builds a specialised executor.
3. Run – Execute on the target hardware; the executor processes messages with zero allocations.
4. Record – All activity is saved to *.copper logs.
5. Inspect – Use the provided tools or the Rust API to replay the log, export data, or visualise timing.

Getting started – Install the stable Rust toolchain, then:

cargo install cargo-cunew
cargo cunew hello_copper   # creates a starter project
cd hello_copper
cargo run                  # runs the example and produces a log

The generated project includes a simple source→task→sink pipeline, a justfile with shortcuts (just graph, just sched, just replay), and optional bare‑metal scaffolding.

Where it runs – The README lists support for Linux, macOS, SBCs like Raspberry Pi, and bare‑metal microcontrollers (e.g., STM32H7). The same binary can be compiled to WebAssembly for a browser demo (see the BalanceBot and Flight‑Controller demos).

Community & resources –

• Book & docs – Full‑length Copper book, API docs on docs.rs, and a runtime overview.
• Examples – A collection of ready‑to‑run robot demos (balance bot, quadcopter flight controller, etc.).
• Extensions – Codec, ZED camera, and ViTFly inference crates live in the same workspace.
• Support – Discord, GitHub Discussions, and contribution guidelines.

Bottom line – Copper is a production‑grade, Rust‑first framework for deterministic, realtime robot control that bridges simulation, Linux, and embedded environments while offering built‑in logging and replay capabilities.