copper-project/copper-rs

Copper 运行时与 SDK – 基于 Rust 的机器人任务引擎

是什么 – Copper 是一个 Rust 库和运行时，允许你以 静态 任务图（用人类可读的 RON 格式编写）的形式描述机器人的控制逻辑。该图被编译为高度优化、零分配的执行器，可运行在从桌面 Linux 系统到裸金属微控制器的任何设备上。机器人运行期间，Copper 会将所有消息、时间戳和状态记录到一个单一的 .copper 日志中，之后可进行确定性回放，用于调试或分析。

为何重要 – 机器人软件常面临延迟峰值、非确定性行为，以及在仿真、Linux 和嵌入式目标之间迁移代码的困难。Copper 通过以下方式解决这些痛点：

• 静态、编译时连接 – 整个控制流水线在编译时就已知，使 Rust 编译器有机会消除开销。
• 实时优先执行 – 热路径不进行任何分配，且为数据导向设计，这对紧密控制回路至关重要。
• 确定性回放 – 每次运行均可精确重现，使调试变得容易得多。
• 跨平台 – 同一代码库可在 Linux/macOS、单板计算机（如 Raspberry Pi）以及片上微控制器（STM32 等）上运行。
• 互操作性 – 可通过 Zenoh 与 ROS 2 通信，并提供 Python 绑定以支持高层工具。

核心组件

组件	作用
copperconfig.ron	静态任务图（源、任务、汇）的声明式描述。
#[copper_runtime] 宏	在编译时生成连接图的具体运行时。
cu29 crate（在 crates.io 上）	执行图、记录日志并提供回放 API 的核心运行时库。
cargo-cunew 模板工具	生成新 Copper 项目（创建 src/main.rs、src/tasks.rs、justfile 等）。
just 辅助命令	用于可视化图、检查生成的调度、回放日志的命令。
遥测支持	通过 UDP 将实时任务数据流式传输到地面站，并可在本地重建确定性孪生体。

典型工作流程

1. 声明 – 编写 copperconfig.ron 文件，列出节点（源、处理任务、汇）及其连接方式。
2. 生成 – 应用 #[copper_runtime] 属性；Cargo 构建专用执行器。
3. 运行 – 在目标硬件上执行；执行器以零分配方式处理消息。
4. 记录 – 所有活动保存至 *.copper 日志。
5. 检查 – 使用提供的工具或 Rust API 回放日志、导出数据或可视化时间线。

快速入门 – 安装稳定版 Rust 工具链后，执行以下命令：

cargo install cargo-cunew
cargo cunew hello_copper   # 创建一个启动项目
cd hello_copper
cargo run                  # 运行示例并生成日志

生成的项目包含一个简单的源→任务→汇流水线、一个 justfile（包含快捷命令如 just graph、just sched、just replay），以及可选的裸金属模板。

运行环境 – README 列出了对 Linux、macOS、Raspberry Pi 等 SBC 以及裸金属微控制器（如 STM32H7）的支持。同一二进制文件可编译为 WebAssembly，用于浏览器演示（参见 BalanceBot 和 Flight-Controller 演示）。

社区与资源 –

• 书籍与文档 – 完整的 Copper 书籍、docs.rs 上的 API 文档，以及运行时概述。
• 示例 – 一系列可直接运行的机器人演示（平衡小车、四轴飞行器飞控等）。
• 扩展 – 编解码、ZED 相机、ViTFly 推理等 crate 位于同一工作区中。
• 支持 – Discord、GitHub Discussions 和贡献指南。

总结 – Copper 是一个生产级、以 Rust 为先的框架，用于构建确定性、实时的机器人控制，连接仿真、Linux 和嵌入式环境，同时提供内置日志记录和回放功能。