Copper

Copper 是一个用户友好的机器人框架，旨在创建快速可靠的机器人。Copper 对于机器人来说，就像游戏引擎对于游戏一样。

• 简单：Copper 提供了一个高级配置系统和自然的 Rust-first API。

• 快速：Copper 使用 Rust 的零成本抽象和数据导向方法，在通用硬件上实现亚微秒级延迟，避免执行期间的堆分配。

• 可靠：Copper 利用 Rust 的所有权、类型系统和并发模型来最小化错误并确保线程安全。

• 面向产品：Copper 旨在通过生成非常可预测的运行时来避免后期阶段的基础设施集成问题。

[!注意] Copper 目前仍处于 早期开发/alpha 阶段，API 可能会发生变化。我们正在寻找贡献者帮助我们构建最好的机器人框架。如果您感兴趣，请加入我们 Gitter 或提交问题。

技术概述

Copper 是一个数据导向的运行时，具有以下关键组件：

• 任务图： 如 RON 所述，它配置了系统的拓扑结构，指定哪些任务进行通信，并设置节点和消息的类型。

• 运行时生成器：该组件根据图的元数据决定执行计划。它在执行期间预分配一个“Copper 列表”，以最大化顺序内存访问。

• 零拷贝数据记录：记录任务之间的所有消息，不复制数据，确保高效的记录。

• 快速结构化日志记录：在编译时索引和内部化日志字符串，避免运行时字符串构建，确保高速文本日志记录。

已经实现了哪些功能？

1. 基本任务生命周期接口：应该相对稳定，以便您开始贡献新的算法、传感器和执行器。
2. 运行时生成：功能正常，但非常简单；这只是一个BFS类型的执行。
3. 日志读取器 & 结构化日志读取器：可以导出数据，目前是Rust调试格式。
4. 简单/最小化驱动器包含：这些更多是为了展示如何实现自己的

类别	类型		描述	仓库名
传感器	Lidar		Velodyne/Ouster VLP16	cu_vlp16
	IMU		WitMotion WT901	cu_wt901
执行器	GPIO		Raspberry Pi	cu_rp_gpio
	伺服		Lewansoul伺服总线（LX-16A等）	cu_lewansoul

缺少哪些功能？我们计划接下来实现什么？

很多！如果您对这些项目中的任何一个感兴趣，并想贡献力量，请随时联系我们！

以下是我们计划接下来实施的一些功能（按优先级顺序）

• 确定性日志回放：由于运行时以确定性的方式生成，我们需要添加钩子来将消息注入到现有的运行时。
• 并行铜列表：今天铜是单线程的；这应该可以允许多个铜列表同时执行，没有竞争。
• 分批处理：由于各种传感器的输出频率差异很大，我们需要能够以丢弃/算法策略（平均最大值等）将消息分批处理。今天这可以在用户端实现，但很痛苦。
• 监控：我们需要一个并行系统，可以监听监控消息并相应地采取行动。
• 分布式铜：目前，我们只能创建一个进程。我们需要为每个子系统正确地进行RPC筛选铜列表。
• ROS接口：构建一对接收器和发送器以连接到现有的ROS系统，帮助用户逐步迁移他们的基础设施。
• 模块化配置：随着使用铜构建的机器人的复杂性增加，用户将需要构建“变体”机器人，而无需复制整个RON文件。
• 类似“PGO”的调度：将以前的日志运行传递给运行时生成器，以允许它做出更好的调度决策。

所以我们才刚刚开始，但即将到来许多酷炫的功能！

为急于开始的铜项目

您可以从存储库中现有的模板生成项目。它会交互式地询问您想要选择的名字。

cargo install cargo-generate
git clone https://github.com/copper-project/copper-rs
cd copper-rs/templates
cargo cunew [path_where_you_want_your_project_created]
    🤷   Project Name:

有关更多信息，请参阅copper-templates。

铜应用程序是什么样的？

以下是一个RON中的任务图的简单示例

(
    tasks: [
        (
            id: "src",                   // this is a friendly name
            type: "FlippingSource",      // This is a Rust struct name for this task see main below
        ),
        (
            id: "gpio",                  // another task, another name
            type: "cu_rp_gpio::RPGpio",  // This is the Rust struct name from another crate
            config: {                    // You can attach config elements to your task
                "pin": 4,
            },
        ),
    ],
     cnx: [
        // Here we simply connect the tasks telling to the framework what type of messages we want to use. 
        (src: "src",  dst: "gpio",   msg: "cu_rp_gpio::RPGpioMsg"),
    ],    

然后在您的main.rs中

// Your application will be a struct that will hold the runtime, loggers etc.
// This proc macro is where all the runtime generation happens. You can see the code generated by the macro at
// compile time.
#[copper_runtime(config = "copperconfig.ron")]  // this is the ron config we just created.
struct MyApplication {}

// Here we define our own Copper Task
// It will be a source flipping a boolean
pub struct FlippingSource {
    state: bool,
}

// You need to provide at least "new". But you have other hooks in to the Lifecycle you can leverage 
// to maximize your opportunity to not use resources outside of the critical execution path: for example start, stop, 
// pre_process, post_process etc...
impl CuTaskLifecycle for FlippingSource {
    fn new(_config: Option<&copper::config::NodeInstanceConfig>) -> CuResult<Self>
    where
        Self: Sized,
    {
        Ok(Self { state: true })
    }
}

// We implement the CuSrcTask trait for our task as it is a source / driver (with no internal input from Copper itself).
impl CuSrcTask for FlippingSource {
    type Output = RPGpioMsg;

    // Process is called by the runtime at each cycle. It will give:
    // 1. the reference to a monotonic clock
    // 2. a mutable reference to the output message (so no need to allocate of copy anything)
    // 3. a CuResult to handle errors
    fn process(&mut self, clock: &RobotClock, output: &mut CuMsg<Self::Output>) -> CuResult<()> {
        self.state = !self.state;   // Flip our internal state and send the message in our output.
        output.payload = RPGpioMsg {
            on: self.state,
            creation: clock.now().into(),
        };
        Ok(())
    }
}


fn main() {

    // Copper uses a special log format called "unified logger" that is optimized for writing. It stores the messages between tasks 
    // but also the structured logs and telemetry.
    // A log reader can be generated at the same time as the application to convert this format for post processing.
  
    let logger_path = "/tmp/mylogfile.copper";
    
    // This basic setup is a shortcut to get you running. If needed you can check out the content of it and customize it. 
    let copper_ctx =
        basic_copper_setup(&PathBuf::from(logger_path), true).expect("Failed to setup logger.");
        
    // This is the struct logging implementation tailored for Copper.
    // It will store the string away from the application in an index format at compile time.
    // and will store the parameter as an actual field.
    // You can even name those: debug!("This string will not be constructed at runtime at all: my_parameter: {} <- but this will be logged as 1 byte.", my_parameter = 42);  
    debug!("Logger created at {}.", logger_path); 
    
    // A high precision monotonic clock is provided. It can be mocked for testing. 
    // Cloning the clock is cheap and gives you the exact same clock.
    let clock = copper_ctx.clock;  
    
    debug!("Creating application... ");
    let mut application =
        MyApplication::new(clock.clone(), copper_ctx.unified_logger.clone())
            .expect("Failed to create runtime.");
    debug!("Running... starting clock: {}.", clock.now());  // The clock will be displayed with units etc. 
    application.run().expect("Failed to run application.");
    debug!("End of program: {}.", clock.now());
}

但这是一个非常简单的任务示例，请参阅lifecycle以获得对任务生命周期的更完整解释。

应用程序部署

有关更多信息，请参阅部署页面。

与ROS相比，它有何优势或不同之处？

性能

在示例目录中，我们有2个等效的应用程序。一个是用C++为ROS编写的，另一个是用Rust和铜移植的。

examples/cu_caterpillar
examples/ros_caterpillar

您可以在桌面或带有GPIO的RPi上运行它们，应该会看到几个数量级的性能差异。

铜被设计为以性能为首要考虑。与游戏引擎不同，我们使用面向数据的方法来最小化延迟并最大化吞吐量。

安全性

由于铜是用Rust编写的，它设计为内存安全和线程安全。它还被设计为易于使用并避免常见的陷阱。

随着我们在这个项目上的进展，我们计划实施越来越多的预警措施，帮助您避免复杂系统中可能发生的“千刀割喉”现象。