Skip to content

Leader

Status: hardware-verified

Hardware-verified Collection with the Rakuda2 leader (standard and gravity-compensated) is checked on hardware. Locking joints (law: position), cross-joint compensation (couplings) and their combinations are Mock only. Force feedback is Mock only (paused).

For Rakuda2 teleoperation, the leader node in inputs (device type: rakuda_mini, the Rakuda-mini arm) reads joint positions, and the joint node in controllers converts them into follower targets. The leader has the follower's joint names and unit, so each follower joint follows the leader joint of the same name; nothing else has to be written.

type: joint
input: leader
followers: [follower]
alignment_tolerance: 300
max_speed: 2048
command_deadline_ms: 100
input_timeout_ms: 150

leader is the node's role in the configuration and type names the device. To use another arm as the leader, change only type.

These are the values from the distributed template. Set them after checking the robot's range of motion, communication cycle, and stopping behavior.

Key Meaning
alignment_tolerance Allowed joint difference between leader and follower before following begins and before every episode start (counts); start is refused above it
joints Optional. Left out: each follower joint follows the input joint of the same name (the input must have every follower joint). Written: one {leader, follower, sign, offset} per follower joint, in the follower's order, for other names, flipped directions (sign: -1) or offsets (target = leader × sign + offset). A leader whose gear ratio or unit differs from the follower's (a GELLO-style leader read in counts for an arm in rad) adds scale (a positive number) to every joint: target = sign × scale × leader + offset. With a scale on every joint the input's unit may differ from the follower's (offset, max_speed and alignment_tolerance are in the follower's unit). Not together with force feedback (feedback)
unit Optional. The input's and the follower's unit must be the same (Rakuda2: dynamixel_count); when written it must equal both
max_speed Upper limit on the rate of change of the target (follower unit/s; counts/s on Rakuda2)
followers The followers it drives; a joint controller drives exactly one
command_deadline_ms Validity period of commands sent to the follower
input_timeout_ms Time until leader input is judged stale
follower_timeout_ms Time until the follower's state is judged stale (default 150). It then stops following and sends no command until it has re-aligned

When aligning appears on screen, align the leader with the follower while watching the displayed joint differences. Run start <task> once it is following. If the input is stale, the state becomes input_stale, and following does not continue without new input.

The leader trigger is configured with law: spring, and gravity compensation with law: gravity_comp. These are motor control laws executed by the leader node itself. On hardware, run them in the Session / CLI dataflow. InProcessSession.from_yaml() does not accept a leader that executes control laws.

The concrete setup is in Rakuda2 Quick start.

Supported robots

Robot Input Status Example
Rakuda2 Rakuda-mini (rakuda_mini) Hardware-verified Rakuda2 controllers

Lock leader joints

In a file built on the active nodes/leader.yaml or nodes/leader_gravity.yaml (extends), or in control of that file itself, move the joints to lock into a law: position group. For example, replace the template's body group with these two groups to leave the torso free and lock neck yaw and pitch. Keep the arm and trigger groups. In older configurations where the torso and head belong to hand, remove these three joints from hand. Every joint must belong to exactly one group.

control:
  - group: body
    law: free
    joints: [torso_yaw]
  - group: fixed_head
    law: position
    joints: [head_yaw, head_pitch]
  # Keep the existing arm and trigger groups below.

position writes the measured pose immediately before enabling torque, then enables only the selected joints. It does not move to an old Goal Position. Since the leader receives no external targets, it holds that pose. Locking begins when the Session launches, continues when stop ends collection, and releases on estop, release, or quit. Align the leader joints to be locked with the follower before launching.

The motors need position control and the corresponding bus APIs. The Operating Mode is read back and must match position (3 on Rakuda2); a mismatch prevents torque enable. If a change is needed, stop the dataflow, support the robot, and use the existing roboloom commission leader (add --with when a launch option selects the leader). Setting torque: false in nodes/follower.yaml does not disable leader locking.

Configure joint compensation

couplings in nodes/controller.yaml adds another follower joint's measured displacement to a target after the joint mapping, signs, and offsets. The default is [] (disabled). For Rakuda2 torso yaw and neck yaw, when equal count changes represent rotations in the same direction, use:

couplings:
  - joint: head_yaw
    source: torso_yaw
    scale: -1.0
    reference: 2048
    lead_ms: 70
head target = head target mapped from the leader
            - (current follower torso position + torso velocity × lead_ms - reference)

reference is the torso position (counts) at which the head target mapped from the leader is used unchanged. Set it to the position where the torso faces forward. For example, a torso rotation of +100 counts from reference adds -100 counts to the head target. Combined with joint locking above, this compensates for torso rotation while the leader's neck stays fixed. If the leader's neck is free, compensation is added to the operator's head input.

  • joint and source name follower joints. Self-coupling, unknown joints, repeated joint entries, and nonfinite scale values are rejected when loading the configuration.
  • The reference is a configured constant, not the pose at alignment. Alignment accepts differences within alignment_tolerance, so a reference taken at that moment would offset the head by that difference for the whole session. Re-alignment and leader restarts keep the same reference.
  • Alignment compares the compensated head target with the follower's head. If the follower camera starts far from forward, head_yaw exceeds the tolerance and the controller stays aligning. Align the follower camera heading with the leader's neck before launch.
  • Using measured torso position rather than its target avoids commanding the neck ahead of a torso that has not caught up. Existing speed limits and follower-side range, deadline, and jump checks still apply after compensation.
  • joint, source, scale, and reference are all required.
  • lead_ms (optional, default 0, 0–500) is how far ahead the target looks along the measured torso velocity. The neck motor trails its target under position control, so the camera lags while the torso moves. On Rakuda2, the camera error while turning the torso at up to 69°/s (up to 4.6°) was almost fully explained by torso velocity × about 70 ms (correlation 0.99, recording of 2026-10-27), so the example uses 70. Too large a value makes the neck overshoot. Without velocity from the robot, no lead is added.
  • This is linear compensation between specified joints. It does not stabilize the full camera orientation, use IMU feedback, or compensate for base rotation. It assumes parallel axes and correct signs and unit ratios. On another robot, set scale to account for axis signs and unit ratios. Speed limits, travel limits, and tracking lag leave errors in camera direction.
  • It applies to type: joint teleoperation, not policy-controller outputs. Joint names are not embedded in the implementation, so other robots' joint controllers can use it too.

Joint locking and compensation have been verified with mock buses and controllers. Hardware direction, travel, and tracking accuracy remain unverified. Existing .roboloom/ directories are not updated automatically; copy the examples into the active YAML files.

Move to an initial pose (home)

The home command moves the leader and the follower slowly to a saved initial pose, so that every episode starts from the same pose. One second after arriving, the leader returns to its normal laws (gravity compensation and breakaway hold), so you can take it and start operating.

1. Save a pose. Put the follower in the pose you want, then run this with the dataflow stopped. Each name becomes poses/<follower>/<name>.yaml, and any number of poses can be saved. An existing name is not overwritten without --force. The file records the follower it was saved on and does not load on another one (so a left-arm pose is never used on the right arm). With several followers, name the follower: capture-pose left ready.

uv run roboloom capture-pose ready

To put the follower in the pose, teleoperate it and quit with hold (exit with the follower holding), or move it by hand after release. capture-pose only reads the follower's positions and moves nothing. Opening the bus runs the usual startup checks.

2. Choose the pose in the controller YAML.

home:
  pose: ../poses/follower/ready.yaml   # one of the saved poses
  max_speed: 200              # counts/s (about 18°/s); a limit that keeps the move slow
  tolerance: 30               # reached when every joint is this close (required; follower unit)
  timeout_s: 30

Current-mode groups of a gravity-compensated leader need a spring that pulls them to the pose. Without it, the configuration is rejected when loaded.

- group: right_arm
  law: gravity_comp
  # ...
  homing:
    kp_mA_per_count: 0.5      # current per count of difference from the target
    max_mA: 40                # limit on the spring's current; the total with gravity stays within max_current_mA

3. Move. Type home on the operator screen (also roboloom session home, or Session.home() from Python). The controller row shows the pose in use as home pose: ready.yaml. During the move, the robot and leader rows show progress, then reached.

  • All joints move on a smooth speed profile and arrive at the same time. Even the farthest joint never exceeds max_speed.
  • The follower moves through the same range and speed checks as normal commands. stop and estop interrupt the move.
  • How a leader joint is moved depends on its control law:
  • Current control (gravity_comp): the homing spring (capped) is added to gravity compensation.
  • Position control (e.g. a locked neck): the target follows the pose; after the move the lock target is that pose.
  • free: only when the motor is in a position mode, torque is on during the move and turns off again after arriving. Otherwise the joint is not moved, and the screen says so.
  • Trigger spring: not moved.
  • Static friction can stop a current-controlled joint's spring short of the pose. Joints farther than tolerance are shown after arriving as short (yellow) with their difference in counts. Whether an episode may start is decided by the usual alignment check (alignment_tolerance). If the differences are large, raise kp_mA_per_count or max_mA.
  • A follower counts as reached once its measured joints are all within tolerance after the move; until then it is settling. If a joint is still out after 2 s, it is short (red) with the joint and its difference: Session.home() (including record --home) fails and start is refused. For a joint that sags under its weight, support it or review tolerance, then run home again.
  • The leader target is computed by inverting the controller's joint map (signs and offsets) and couplings. After arriving, the leader–follower difference is close to 0.
  • home is refused while recording or following (after start), and start is refused while moving home.
  • Keep your hands off the arms while they move. estop, release and quit make the leader limp as before.

This is verified with mock buses and the mock dataflow. Behaviour on hardware has not been verified.

Receive force feedback (not verified on hardware)

When a current-mode group (gravity_comp, impedance) has feedback:, its joints receive, as current, the external force on the follower that the controller returns. This has not been verified on hardware.

- group: right_arm
  law: gravity_comp
  # ... existing gravity_model, tuning, range, etc.
  feedback:
    max_mA: 20
    ramp_s: 0.3
    kd: 0.0

The controller's feedback.gain selects the joints that receive it. The feedback is added to the output of gravity compensation and the rest, then clipped at max_current_mA; the gate opens and closes over ramp_s. Estop, release and quit set it to 0 at once. For the keys and the safety mechanisms, see "Force feedback" in Configuration; for the Rakuda2 combination, see "Bilateral" in Rakuda2.