Setup
roboloom.setup は,計測と設定の手順(EEPROM,零点,可動域,重力,姿勢,卓上試験)を Python から呼ぶ API です.使い方の例のあとに,docstring から生成した説明(英語)を載せます.
使い方
- 計測の本体は,結果を dataclass で返し,失敗を例外で知らせます.
ConfigError:設定の誤り.SetupError:計測の前提を満たさない,精度が足りない.HardwareError:torqueが入っているなど,機器の状態が合わない.Cancelled:確認が拒否された.何も書いていない.- 人の操作が要る場面は,
Operatorに問い合わせます. - 腕を支える,姿勢を置く,Enter を押す,など.
- CLI は
TerminalOperatorを渡します. - scriptや試験では
ScriptedOperatorに答えを並べて渡せます. - 設定を取る関数は,path,機体名,読み込み済みの
RobotConfigのどれでも受け取ります.optionやmodeを選ぶときは,load_config(..., options=..., mock=...)で読み込んでから渡します. plan_commission,watchdog_test,gravity_checkは,mockの設定を拒否します.
各手順に対応するcommandは 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) # 確認してから書く
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%}")
# 重力補償の調整を,画面なしで(例:値を順に試す自動化)
tuning = setup.open_tuning(gravity, "leader", "right_arm")
try:
tuning.start()
tuning.key("]") # 選んだ関節の gain +0.1
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.
零点と可動域
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.
重力
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.
姿勢
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.
卓上試験
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.
操作者
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.