clankers 0.1.2

clankeRS is a Rust SDK for robotics teams on ROS 2 and PyTorch. Build memory-safe robot nodes, run ONNX inference in Rust, replay MCAP logs in tests, and ship with confidence — without replacing your existing stack.

Install

# Cargo.toml
clankers = "0.1"

cargo add clankers

Requirements: Rust stable. First build downloads the ONNX Runtime binary automatically (network required).

For scaffolding and tooling, install the CLI separately (clankers new bundles templates — no clone required):

cargo install clankers-cli

Quick example

A minimal perception node: subscribe to camera frames, run ONNX with zero-copy inputs, publish detections.

use clankers::prelude::*;

#[clankers::node]
async fn perception(ctx: RobotContext) -> RobotResult<()> {
    let model_cfg = ctx.model_config("detector")?;
    let model_path = ctx.resolve_path(&model_cfg.path);
    let mut model = ModelBuilder::from_config(&model_cfg, model_path)?.build()?;
    let input_name = model.engine().input_specs()[0].name.clone();

    let node = RobotNode::new(ctx.node_name().as_str()).await?;
    let mut images = node
        .subscribe::<ImageMsg>("/camera/image_raw", QosProfile::sensor_data())
        .await?;
    let detections_pub = node
        .publish::<DetectionArray>("/detections", QosProfile::default())
        .await?;

    while let Some(frame) = images.next().await {
        let tensor = ImageTensor::from_ros_msg(&frame)?
            .resize(224, 224)?
            .normalize_imagenet()?
            .to_nchw()?;

        let shape = tensor.nchw_shape();
        let view = tensor.as_nchw_view(&shape)?;
        let outputs = model.run_named([(input_name.as_str(), view)])?;

        detections_pub
            .publish(DetectionArray {
                stamp_nanos: Timestamp::now().as_nanos(),
                frame_id: frame.frame_id.clone(),
                detections: vec![/* map model output → Detection */],
            })
            .await?;
    }
    Ok(())
}

Replay-test against a recorded MCAP log:

use clankers::prelude::*;

#[clankers::replay_test("tests/fixtures/camera_log.mcap")]
async fn camera_log_replays_cleanly(ctx: ReplayContext) -> RobotResult<()> {
    let result = ctx.run_replay(|_msg| async { Ok(()) }).await?;
    assert_no_panics(&result)?;
    assert_topic_exists(&result, "/camera/image_raw")?;
    Ok(())
}

What you get

One dependency pulls in the full SDK surface:

The workflow

  PyTorch model
       │
       ▼
   ONNX export ──► reference outputs (offline)
       │
       ▼
  Rust ONNX inference (clankers-ml)
       │
       ▼
  MCAP replay test (clankers-testing)
       │
       ▼
  deploy as a ROS 2 node

Honest scope (v0.1.2)

• Sim pub/sub works out of the box — no ROS 2 install required for development and tests.
• Real DDS / rclrs is available from the GitHub repo as colcon packages under ros2/ (ROS 2 Humble). It does not ship through this crate.
• APIs are early — expect changes before v1.0.

Learn more

• Installation
• Getting started
• ROS 2 integration
• Model validation
• MCAP replay testing

License

MIT — see LICENSE.