コンテンツにスキップ

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 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.

零点と可動域

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 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.

姿勢

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 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.

操作者

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.