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
ScriptedOperatorwith 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 withload_config(..., options=..., mock=...)and pass that. plan_commission,watchdog_test, andgravity_checkrefuse 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 |
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 |
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 |
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 |
current_mA |
float
|
The current it was pushed with. |
readings |
dict[str, object]
|
The registers read before and after the silence ( |
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.