Crate clankers 

clankeRS — Rust SDK for robotics

Train in PyTorch. Deploy in Rust. Replay-test against real robot logs.

This crate is the umbrella facade. Most applications depend only on this package and import prelude for everyday node code.

Quick start — a robot node

use clankers::prelude::*;

#[clankers::node]
async fn main(ctx: RobotContext) -> RobotResult<()> {
    let _node = RobotNode::new(ctx.node_name().as_str()).await?;
    Ok(())
}

Quick start — optimized inference

Model is the main inference API. Bind zero-copy TensorView inputs and read named outputs. See ml for the full surface.

use clankers::ml::OnnxRuntimeBackend;
use clankers::prelude::*;
use clankers_tensor::{DType, Layout, Shape, TensorView};

let mut model = Model::builder()
    .backend(OnnxRuntimeBackend::default())
    .load("models/policy.onnx")?;

let image_shape = Shape::from([1, 64, 64, 3]);
let image = TensorView::from_slice(
    &[0u8; 64 * 64 * 3],
    DType::U8,
    &image_shape,
    Layout::Contiguous,
)?;
let state_shape = Shape::from([1, 12]);
let state = TensorView::from_f32(&[0.0f32; 12], &state_shape)?;

let outputs = model.run_named([("image", image), ("state", state)])?;
let _action = outputs.get("action");

Module guide

Module	When to use it
prelude	One import for nodes, inference, pub/sub, and replay tests
ros2	Sim pub/sub — RobotNode, ImageMsg, DetectionArray
ml / Model	Load ONNX models, run inference (start here)
tensor	TensorView, ImageTensor preprocessing
data	MCAP inspect, replay, compare
recording	McapRecorder — tape node I/O to MCAP (record_mcap)
testing	ReplayContext and replay assertions
inference	Power-user InferenceEngine and backends
runtime	RobotRuntime metrics and tracing helpers
geometry	TfBuffer frame lookups, Isometry, Pose, Twist

Workspace crates

The facade re-exports these focused crates (each has its own docs.rs page): clankers-core, clankers-ros2, clankers-tensor, clankers-ml, clankers-data, clankers-testing, clankers-geometry, clankers-runtime, clankers-macros.

Install the CLI separately: cargo install clankers-cli.

Re-exports

pub use recording::run_with_recording;

pub use recording::McapRecorder;

pub use recording::RecordingPlan;

pub use recording::RecordingSummary;

Modules

backend

Inference backends and the tensor specs / capabilities they report.

data

geometry

Rigid-body geometry and frame lookups: TfBuffer, Isometry, Pose, TransformStamped, Twist.

inference

Lower-level inference runtime used by Model.

ml

prelude

Common imports for clankeRS robot nodes.

recording

MCAP recording of node I/O, driven by [logging] record_mcap in clankeRS.toml.

ros2

runtime

tensor

testing

Structs

AggregatedInferenceStats

Aggregated per-frame inference accounting across a replay run.

ClankeRSConfig

Full clankeRS project configuration from clankeRS.toml.

Detection

Single 2D detection.

DetectionArray

Array of detections (vision_msgs/Detection2DArray simplified).

ImageInput

A zero-copy borrow of an ImageMsg as a U8 tensor of shape [height, width, channels] (HWC).

ImageMsg

Simplified sensor_msgs/Image representation.

ImageTensor

Image tensor with robotics preprocessing helpers.

InferenceEngine

Lower-level inference runtime used by Model.

InferenceStats

What a single inference run cost.

InspectReport

Summary of an MCAP file’s contents.

Isometry

A rigid-body transform: rotation followed by translation.

LatencyStats

Latency percentile statistics.

McapLog

Read-only handle to an MCAP log file.

Model

A loaded clankeRS model backed by the optimized inference runtime.

ModelBuilder

ModelValidator

NamedOutputs

Outputs from a named inference run, keyed by each tensor’s model output name.

Pose

An Isometry in a coordinate frame, at a point in time.

Publisher

QosProfile

ROS 2 QoS profile helpers.

Replay

Replay engine that feeds MCAP messages in timestamp order.

ReplayContext

Context for replay-based tests.

ReplayResult

ReplayTestResult

RobotContext

Runtime context for a clankeRS node.

RobotNode

ROS 2 robot node handle.

RobotRuntime

RuntimeMetrics

Shape

A concrete tensor shape: an ordered list of dimension sizes.

StateInput

A zero-copy borrow of an f32 slice as an F32 tensor of a chosen shape.

Subscriber

Tensor

An owned, contiguous tensor with an 8-byte-aligned backing Buffer.

TensorView

A borrowed, read-only tensor.

TfBuffer

A time-indexed tree of coordinate frames.

TfBufferConfig

Tuning for TfBuffer.

Timestamp

Nanosecond-precision robot timestamp.

TopicName

Strongly typed ROS topic name.

TransformStamped

An Isometry between two coordinate frames, at a point in time.

Twist

Linear and angular velocity, matching geometry_msgs/Twist.

ValidationReport

Enums

ConfiguredEngine

A loaded engine plus its backend kind, for callers that select the backend from config at runtime.

InferenceError

An error raised while building or running an InferenceEngine.

ModelBackendKind

A model backend name from clankeRS.toml ([model.*].backend).

ModelEngine

The loaded, optimized inference runtime behind a Model.

RobotError

RuntimeBackend

Backend selection for ModelBuilder::backend.

TfError

Errors raised by geometry construction and frame lookups.

Functions

assert_dropped_messages

assert_max_latency

assert_no_panics

assert_topic_exists

engine_from_model_config

Build an InferenceEngine from a ModelConfig and model source.

inject_message

Inject a message into the sim bus (used by replay).

noop_engine_from_config

Build a NoopBackend engine that mirrors a real model’s tensor specs.

onnx_engine_from_config

Build an ONNX Runtime engine with config-driven warmup and device settings.

Type Aliases

RobotResult

Attribute Macros

node

Marks an async function as a clankeRS robot node entry point.

replay_test

Marks a test function as a replay-based test using an MCAP fixture path.