Skip to content

Setup

roboloom.setup runs the measurement and setup steps (EEPROM, zeros, travel, gravity, poses, bench tests) from Python. Usage examples come first, followed by the descriptions generated from the docstrings.

Usage

  • The measurement functions return results as dataclasses and report failures as exceptions.
  • ConfigError: configuration error.
  • SetupError: measurement preconditions not met, or insufficient accuracy.
  • HardwareError: device state does not match, e.g. torque is enabled.
  • Cancelled: confirmation was declined. Nothing has been written.
  • Steps that need human action query an Operator.
  • Supporting the arm, placing a pose, pressing Enter, etc.
  • The CLI passes a TerminalOperator.
  • In scripts and tests, you can pass a ScriptedOperator with a list of answers.
  • Functions that take a configuration accept a path, a robot name, or a loaded RobotConfig. To choose options or the mode, load it with load_config(..., options=..., mock=...) and pass that.
  • plan_commission, watchdog_test, and gravity_check refuse a mock configuration.

The command for each step is in CLI.

from roboloom import setup
from roboloom.operator import TerminalOperator

op = TerminalOperator()
from roboloom import load_config

gravity = load_config("rakuda2", options=["gravity"])
plan = setup.plan_commission(gravity, "leader")
for line in plan.lines():
    print(line)
setup.apply_commission(plan, op)  # write after confirmation

fit = setup.identify_gravity(
    ".roboloom/rakuda2/calibration/leader_right.yaml",
    ".roboloom/rakuda2/calibration/gravity_right.yaml",
    op,
    collect=True,
)
for joint in fit.joints:
    print(joint.joint, f"{joint.explained:.0%}")
# tune gravity compensation without the screen (e.g. automation that tries values in turn)
tuning = setup.open_tuning(gravity, "leader", "right_arm")
try:
    tuning.start()
    tuning.key("]")  # gain +0.1 for the selected joint
    for _ in range(120):
        tuning.step()
        time.sleep(tuning.period_s)
    print([(r.joint, r.gain, r.sent_mA) for r in tuning.rows()])
finally:
    tuning.close()

EEPROM

roboloom.setup.plan_commission(config, node)

Read the node's EEPROM and list the values that differ from its configuration.

roboloom.setup.apply_commission(plan, operator)

Write the plan after the operator confirms; returns how many values were written (each write is read back by the driver). Refuses while any of the motors is torqued.

roboloom.setup.CommissionPlan dataclass

The EEPROM values of a node that differ from its configuration (plan_commission); lines() lists them, apply_commission writes them.

Attributes:

Name Type Description
node str

The node's name.

port str

Its bus.

ids list[int]

The motor IDs read.

changes list[RegisterChange]

One RegisterChange per register to write (joint, register, current and target raw values); empty when the EEPROM already matches.

lines()

One line per change: joint: register current -> target.

Zeros and travel

roboloom.setup.calibrate_joints(calibration, operator, joints=None)

Record zero counts while the operator holds the arm at the URDF zero pose. Read-only on the bus; writes the zeros to the calibration file and marks it unconfirmed.

roboloom.setup.Calibration

Joint map for gravity identification: motor IDs, URDF joints, zero counts and directions.

open_bus(*, limp=True)

The arm's bus; with limp, refuse while any joint is torqued (the operator moves it).

roboloom.setup.measure_travel(calibration, out, operator, min_span=200, period_s=1 / 30)

Record each output joint's min/max counts while the operator moves the limp arm, until operator.finished(). Read-only on the bus; writes out only if every joint moved.

roboloom.setup.Travel dataclass

Each joint's lowest and highest raw count seen by measure_travel, saved at path.

Attributes:

Name Type Description
port str

The arm's bus.

joints dict[str, tuple[int, int]]

Joint -> (lowest, highest) raw count seen.

path Path

Where the travel was saved.

lines()

The result as the CLI prints it, one line per item.

Gravity

roboloom.setup.identify_gravity(calibration, out, operator, *, data=None, collect=False, delta=30, max_rms_mA=15.0)

Optionally collect new poses (torques the arm, after the operator confirms), then fit the model to every pose in data (default: next to out, as .npz) and save it to out.

roboloom.setup.collect_holding_currents(calibration, data_path, operator, delta=30, settle_s=0.7, samples=10)

Per pose, hold each output joint after approaching from below and from above, and append the holding currents to data_path (npz). The operator moves the arm between poses and answers q to finish. Returns the next pose number.

roboloom.setup.fit_gravity(calibration, data_path, out, max_rms_mA=15.0, holdout_every=4)

Fit and save the gravity model; refuses (SetupError, with the report) when the data contradicts the calibration or the fit is not good enough.

roboloom.setup.GravityFit dataclass

The fitted gravity model saved at path (identify_gravity, fit_gravity): per-joint fits, the report lines and its warnings.

Attributes:

Name Type Description
path Path

The saved gravity model.

joints list[JointFit]

One JointFit per joint (joint, rank, holdout_rms_mA, train_rms_mA, current_std_mA, and explained: the share of the measured current's variance the model explains).

report list[str]

Poses used, directions, per-joint lines and warnings.

warnings property

The report lines that are warnings.

lines()

The result as the CLI prints it, one line per item.

roboloom.setup.gravity_check(config, node, group, operator, poses=3, scales=(1.0, 0.0))

Objective A/B: at the same pose, release the arm once per scale of the configured gains (default: as configured, then 0) and compare how far and how fast each joint moves. A negative scale pushes the other way: it tells a wrong sign from too little current.

roboloom.setup.release_trial(device, law, gains, settle_s, watch_s, period_s, sleep=time.sleep, signal=lambda: None)

Enable law with gains, call signal when the operator should let go, and watch the arm for watch_s. Torque is off again afterwards; a runaway stops the trial early.

roboloom.setup.GravityCheck dataclass

What gravity_check measured: one row per pose, scale and joint; lines() is the table the CLI prints, trace the saved samples.

Attributes:

Name Type Description
rows list[CheckRow]

One CheckRow per pose, scale and joint (position, model and sent current, drift in counts after letting go, peak velocity).

trace Path | None

The file of saved samples, if any.

stopped list[str]

Why trials ended early (a runaway or the watchdog).

lines()

The result as the CLI prints it, one line per item.

roboloom.setup.open_tuning(config, node, group)

A live tuning session for one gravity_comp group; the other groups stay limp. Saving writes the group's tuning: file. Close the session when done.

roboloom.setup.TuningSession

Live gravity-compensation tuning of one gravity_comp group (open_tuning).

Call start() to torque the arm, then step() once per period_s; key() applies the operator's keys (gain, hold, compare, resume, save), rows() gives each joint's measured, model and sent currents, and close() turns the torque off.

start()

Torque the arm and start compensating (refused after an emergency stop).

step(now_ns=None)

One control tick: read the joints and send the compensation current.

close()

Torque off and close the bus (unsaved changes are dropped).

key(key)

Apply one key; returns a message for the operator, if any.

rows()

One row per tuned joint: gain, hold, and the measured, model and sent currents.

emergency()

Permanent latch, distinct from a recoverable safety STOPPED state.

mark_saved(saved)

Changes made during a write must remain dirty.

save()

Synchronous API; the operator backend uses detached snapshots instead.

Poses

roboloom.setup.capture_pose(config, name, *, follower=None, force=False)

Read a follower's positions and save them as pose name.

follower: which follower node (may be omitted when the robot has only one). Moves nothing: the bus opens with the follower's usual startup checks, positions are read, and the bus closes. The dataflow must not be running (it owns the bus); pose the follower by teleoperation (then quit with hold) or by hand after release. Every joint must be inside the follower's limits. Returns the written file.

Bench tests

roboloom.setup.check_hold(config, follower, operator, tolerance, seconds=10.0)

Bench test (torques the follower): hold the follower's pose, stop commanding it for up to seconds and measure how far it moves.

Only for a follower whose model declares unattended: unknown, on hardware, with torque. After the operator confirms, offers to write the measured unattended (holds when no joint moved more than tolerance, in the follower's unit, and the motors stayed enabled; else torque_off) to its YAML, then to turn its torque off.

roboloom.setup.hold_trial(follower, bus, seconds, tolerance, sleep=time.sleep, clock=time.monotonic)

Hold for HOLD_BEFORE_S, stop writing (torque stays on), then watch for up to seconds, stopping early once a joint moved beyond tolerance. The motors are left as they ended up; the caller decides whether to release them.

roboloom.setup.HoldResult dataclass

What check_hold saw while the follower was left alone: the largest drift per joint and, from it, the follower's unattended trait.

Attributes:

Name Type Description
follower str

The follower tested.

unit str

Its unit.

seconds float

How long it was watched (shorter when it moved away).

tolerance float

The largest change still counted as holding.

drift dict[str, float]

The largest change per joint while left alone.

enabled list[bool] | None

The motors' enable state at the end, when the bus reports it.

worst property

The joint that moved most, and how far.

holds property

No joint moved more than tolerance and the motors stayed enabled.

unattended property

The trait to record: holds or torque_off.

lines()

The result as the CLI prints it, one line per item.

roboloom.setup.watchdog_test(config, node, joint, operator, current_mA=30.0)

Bench test (torques the motor): push joint of the Dynamixel node node with current_mA in current mode, stop sending and check that the Bus Watchdog (bus_watchdog_ms) stops it. Refuses a mock configuration.

roboloom.setup.watchdog_trial(bus, current_mA, period_ms, sleep=time.sleep)

Push one current-mode motor with current_mA, go silent, and read what the motor did.

bus holds exactly one motor. Returns readings before and after the silence; the motor is left with zero goal current, torque off and the watchdog cleared.

roboloom.setup.WatchdogResult dataclass

What watchdog_test read before and after going silent: whether the Bus Watchdog fired and the motor stopped (passed).

Attributes:

Name Type Description
joint str

The joint pushed.

period_ms float

The node's bus_watchdog_ms.

current_mA float

The current it was pushed with.

readings dict[str, object]

The registers read before and after the silence (watchdog_trial).

fired property

The Bus Watchdog register shows that it fired.

stopped property

The current after the silence fell below 30% of the pushed current.

passed property

The watchdog fired and the motor stopped.

lines()

The result as the CLI prints it, one line per item.

Operator

roboloom.operator.Operator

Bases: Protocol

The person at the robot, asked by setup steps and by Session before the arms go limp: confirmations, prompts and progress lines.

confirm(message)

Ask before torquing a motor or writing EEPROM; False cancels.

prompt(message)

Wait until the operator is ready (e.g. the arm is in a pose); returns what they typed.

notify(message)

One line of information, e.g. "let go now".

progress(message)

A live line that replaces the previous one, e.g. spans while measuring travel.

finished()

Non-blocking: has the operator ended an open-ended step (Enter in a terminal)?

roboloom.operator.TerminalOperator

An Operator in a terminal: confirmations need yes, prompts wait for Enter.

roboloom.operator.ScriptedOperator

Answers given up front. prompts are returned in order (then ""); finish_after is how many finished polls return False first. Every message is kept in log.