Skip to content

Concepts

The nodes, configuration, units, Session and episode states that make the rest of these docs easier to read. The keys are listed in Configuration.

Nodes

A configuration is a set of nodes, one per role. Each node runs as its own process in a dora-rs dataflow and reads the configuration itself.

Role (key in config.yaml) What it does Examples
inputs reads the device a person moves Rakuda-mini (leader), Pika Sense
controllers turns an input or a policy into follower targets joint, policy, pose_ik
followers moves its motors to the targets and reports its state Rakuda2, PiPER, Pika Gripper
sensors captures observations RealSense, DIGIT, audio
recorder aligns every node's output to dataset rows and saves them LeRobotDataset
session takes operations (start, stop, save, …) and passes them on to the nodes the operator screen, roboloom session
trackers, estimators pose tracking, external-force estimation Lighthouse, effort
flowchart LR
  subgraph flow["dora dataflow"]
    I["inputs"] --> C["controllers"]
    C --> F["followers"]
    F --> C
    X["sensors"] --> R["recorder"]
    F --> R
    I --> R
    N["session"] -.-> C
    N -.-> R
  end
  S["Session<br/>screen, CLI, Python"] --> N
  R --> D[("LeRobotDataset")]

How the configuration is put together

Each robot has one .roboloom/<robot>/config.yaml. Node settings live in separate files under nodes/ and are combined into one configuration at launch, in this order.

flowchart TB
  A["config.yaml<br/>a node file per role"] --> B["launch options<br/>--with applies set:"]
  B --> C["extends<br/>layered on a base node file"]
  C --> D["experiment file<br/>configs/roboloom/name.yaml"]
  D --> E["loaded configuration"]
  M["mock.yaml<br/>SET_ values with --mock"] -.-> E
Mechanism What it does Details
Launch options (options) replace, add or remove node files; add a suffix to the dataset name when the recording changes Launch options
extends write only what differs from a base node file extends
Experiment file gather the policy, options, output, task and length in one file Experiment files
mock.yaml stand-ins for SET_... values, used with mock devices only Unset values and mock

Units

  • The followers and inputs declare the unit of their joint positions. Rakuda2 and the Rakuda-mini use raw Dynamixel position counts (dynamixel_count); PiPER uses rad.
  • Commands carry their unit, and a follower refuses a command in another unit.
  • max_speed and home.tolerance are in the follower's unit (per second) wherever they are written.
  • observation.state and action are recorded in the follower's unit. A policy returns its targets in the same unit.

Details are in Units.

Session

Session is the Python class that starts the dataflow and sends the episode operations. The CLI and the operator screen are thin layers over it.

Entry point Example
Operator screen uv run roboloom run
Another terminal uv run roboloom session save
Python Session.launch("rakuda2", options=["gravity"])

The API is in Session; the operations are in run operations.

Episode states

The recorder takes an episode through these states. The recorder row of the operator screen shows the current one.

stateDiagram-v2
  [*] --> idle
  idle --> recording: start
  recording --> stopped: stop
  stopped --> saving: save
  saving --> idle: saved
  stopped --> idle: discard
  recording --> idle: discard
  • While stopped, the next start is refused until you choose save or discard. It is refused while saving too.
  • stop holds the follower. It does not turn the torque off.

A joint controller driven by a leader has its own states, apart from the episode. start is refused while it is aligning.

stateDiagram-v2
  [*] --> waiting_input
  waiting_input --> aligning: difference above tolerance
  waiting_input --> following: difference within tolerance
  aligning --> following: difference within tolerance
  following --> input_stale: input stopped
  input_stale --> aligning: input back
  following --> follower_fault: FAULT, ESTOP
  follower_fault --> aligning: after recovery
  • While aligning, the screen shows the joint difference (worst_joint, worst_diff). Move the leader to the follower.
  • A policy controller goes loading → ready → running and back to ready on stop (When a policy fails).