Copper Runtime & SDK

🤖&nbsp&nbsp&nbsp&nbsp Copper is to robots what a game engine is to games - build, run, and replay your entire robot deterministically.

Why Copper

🦀 Rust-first – ergonomic & safe

⚡ Sub-microsecond latency – zero-alloc, data-oriented runtime

⏱️ Deterministic replay – every run, bit-for-bit identical

🧠 Interoperable with ROS2 – bridges via Zenoh opening the path for a progressive migration.

🪶 Runs anywhere – from Linux servers to bare-metal RP2350

📦 Built to ship – one stack from simulation to production ### Example Applications | Flying | Driving | Swimming | Spacefaring | |:--:|:--:|:--:|:--:| | | | | | ### Technical Overview Copper is a deterministic and data-oriented Robot SDK with these key components: * **Task Graph**: Configures the system's topology, specifies inter-task communication paths, and sets types for nodes and messages. The Task Graph is generated in [RON](https://github.com/ron-rs/ron), * **Runtime Generator**: Creates an execution plan based on the Task Graph's metadata. It preallocates a "Copper List" to maximize sequential memory access during execution. * **Zero-Copy Data Logging**: Records all messages between tasks without copying data, ensuring efficient logging and perfect determinism. * **Fast Structured Logging**: Interns and indexes logging strings at compile time, avoiding runtime string construction and ensuring high-speed textual logging. ### You don't have a real robot yet? Try it in our minimalistic sim environment! [](https://youtu.be/kC6sGRZUxLE) Here is a Copper-based robot in action in a Bevy simulation environment! The realistic sim is created using [Bevy](https://crates.io/crates/bevy) (A Rust Game Engine) and [Avian3d](https://crates.io/crates/avian3d) (Physics Engine in Rust). On your mac or linux machine (x86-64 or Arm) just run ... ```bash $ cargo install cu-rp-balancebot $ balancebot-sim ``` ... to try it locally. The source code for this demo is available in the [examples/cu_rp_balancebot](examples/cu_rp_balancebot) directory. ### Supported Platforms You can deploy and run Copper on those platforms:        ### ... but we also support baremetal! On the embedded side, we do have a reference platform you can create from readily available components or you can get from us already made, feel free to inquire: info@copper-robotics.com More info about baremetal development with Copper [here](https://github.com/copper-project/copper-rs/wiki/Baremetal-Development) ### Features provided with the SDK 1. **Task interface and Lifecycle**: Traits you can use to implement new algorithms, sensors, and actuators. 2. **Runtime generation**: Generates a scheduling at compile time for your robot. 3. **Log reader**: You can export the logs generated by Copper to any format supported by Rust Serde. 4. **Structured log reader**: Debug logs are indexed and string interned at compile time for maximum efficiency. 5. **Components**: We have a growing number of drivers, algorithms and standard interfaces. If you have implemented a new component, ping us and we will add it to the list below! 6. **log replay / resim**: You can deterministically replay/resim a log. You will get the exact same result as a real log on the robot or from the sim. 7. **Simulation**: We have a simple simulation environment to test your robot. Test your robot before the hardware is built and try out your robot the first time without risking a real crash. With a growing list of readily available [Components](https://github.com/copper-project/copper-rs/wiki/Available-Components). ## Get Started File truncated at 100 lines [see the full file](https://github.com/copper-project/copper-rs/tree/master/README.md)

Contributing to Copper-rs

First off, thank you for considering contributing to Copper-rs! We welcome contributions from everyone. This document provides guidelines for contributing to the project.

Getting Started

Prerequisites

• Rust: Ensure you have a recent stable Rust toolchain installed. You can install it using rustup.

    curl --proto '=https' --tlsv1.2 -sSf [https://sh.rustup.rs](https://sh.rustup.rs) | sh
    

• cargo-nextest: For running tests efficiently.

    cargo install cargo-nextest
    

• Platform-Specific Dependencies: Depending on your operating system and the features you intend to work with, you might need additional dependencies. Refer to the Continuous Integration Setup section below for details extracted from our CI workflow. For Ubuntu 22.04, please checkout our Dockerfile.

Building the Project

To build the project, navigate to the root directory and run:

cargo build --workspace

For a release build, use:

cargo build --release --workspace

Running Tests

We use cargo-nextest for running tests. To run all unit tests:

cargo nextest run --workspace --all-targets

To run tests including specific features (matching the CI ‘debug’ mode non-CUDA features):

cargo nextest run --workspace --all-targets --features macro_debug,mock,perf-ui,image,kornia,python,gst,faer,nalgebra,glam,debug_pane,bincode

Contribution Workflow

1. Fork the Repository: Create your own fork of the copper-rs repository on GitHub.

2. Clone Your Fork: Clone your forked repository to your local machine.

    git clone https://github.com/YOUR_USERNAME/copper-rs.git
    cd copper-rs
    

1. Create a Branch: Create a new branch for your changes. Choose a descriptive branch name. ex: yang/chore/beta_clippy , gbin/feat/soa , gbin/fix/balancebot_sim .

    git checkout -b user/feat/description
    

1. Make Changes: Implement your feature or fix the bug. Write clear and concise code.

2. Run Checks: Before committing, ensure your code adheres to the project’s standards:
   • Formatting: cargo fmt --all -- --check
   • Clippy Lints: cargo clippy --workspace --all-targets -- --deny warnings
   • Tests: cargo nextest run --workspace --all-targets (run with relevant features if applicable)
   • Typos: Ensure you run a spell checker. We use typos --config .config/_typos.toml .
3. Commit and push Changes: Commit your changes with clear and descriptive commit messages. (Consider using Conventional Commits)

    git add .
    git commit -m "feat: new feature"
    git push user/feat/description
    

1. Create a Pull Request: Open a pull request (PR) from your branch to the master branch of the main copper-rs repository. Provide a clear description of your changes in the PR.

Dependency Management

We keep our dependencies minimal and up-to-date.

We use

``` to identify and remove unused dependencies. Before submitting a PR, please run:

1. Install 
```cargo-machete

cargo install cargo-machete

1. Run cargo-machete to find unused dependencies:

cargo machete --with-metadata

1. Handling False Positives

cargo-machete is not perfect. If it incorrectly flags a necessary dependency (e.g., required by a feature flag or build script), add it to the ignored list in the relevant Cargo.toml file:

```toml [package.metadata.cargo-machete]

Explain why the dependency is needed despite not being directly used in code.

e.g. “Required for X feature” or “Used in build.rs”

File truncated at 100 lines see the full file