Control laws (control)
control: in the node YAML of a leader (rakuda_mini) or a follower (rakuda2_follower) chooses a control law per joint group. The same laws serve leaders and followers. This page lists the keys of each law, and the keys of a follower's limits and a controller's home. For how to use them, see the Leader configuration examples and Gravity compensation.
Keys of every group
control: is a list of groups. Every joint belongs to exactly one group, and group names are unique. A group takes only the keys its law reads; any other key is refused at load.
| Key | Type | Default | Unit | Description |
|---|---|---|---|---|
group |
text | required | — | Group name; extends lays a group over the base's group of the same name |
law |
text | required | — | One of free, position, current_position, spring, gravity_comp, impedance |
joints |
list of text | required | — | The group's joints |
feedback |
mapping | — | — | Takes force feedback (below); current-mode laws only (gravity_comp, impedance) Mock only |
A law fixes its operating mode (the Dynamixel Operating Mode). On Rakuda2 a registers.operating_mode in the YAML that contradicts it is refused.
law |
Operating mode | Current mode |
|---|---|---|
free |
none (torque off) | — |
position |
position | — |
current_position |
current-based position | — |
spring |
current-based position | — |
gravity_comp |
current | yes |
impedance |
current | yes |
On hardware, a node with a current-mode group needs bus_watchdog_ms.
free
Torque off, for a leader joint moved by hand. No keys besides the common ones.
position
Moves to the target; without a target it keeps the last goal. On a leader it holds the pose it had when torque turned on (a locked joint). No keys besides the common ones.
current_position
Current-based position control: the goal current is the torque limit. With target it becomes a spring back to that position.
| Key | Type | Default | Unit | Description |
|---|---|---|---|---|
goal_current_mA |
number or one per joint | required | mA | Goal current (the torque limit); on hardware at most the EEPROM registers.current_limit |
target |
number or one per joint | — | joint unit | A fixed target; when set, the input's target is not used |
spring
A return spring for a hand-operated joint, such as a leader's gripper trigger. The joint is held at rest in current-based position mode; pushing it away meets a force that grows with the displacement, capped by goal_current_mA, so the operator can always overpower it.
| Key | Type | Default | Unit | Description |
|---|---|---|---|---|
rest |
number or one per joint | required | joint unit | Position it returns to |
goal_current_mA |
number or one per joint | required | mA | Cap of the returning force; on hardware at most the EEPROM registers.current_limit |
Keys of current-mode laws
The keys gravity_comp and impedance read. The output ramps in over ramp_s and is clipped per joint to max_current_mA. A joint that moves too fast or leaves its range counts as a runaway, and the node goes limp.
| Key | Type | Default | Unit | Description |
|---|---|---|---|---|
max_current_mA |
number or one per joint | required | mA | Cap of the output current |
max_velocity |
number | required | count/s | A joint faster than this is a runaway |
range |
list of [min, max] per joint, or a file path |
required | count | Range of motion; a path names the file roboloom measure-travel writes |
range_margin |
number | 100 |
count | Margin outside range that is not yet a runaway |
barrier_mA_per_count |
number | 0.5 |
mA/count | Current that pushes back outside range |
gravity_model |
path | — | — | Gravity model (output of roboloom identify-gravity), relative to the node file's directory |
gravity_gain |
number or one per joint | 1.0 with a gravity model, else 0.0 |
— | Gain of the gravity term |
tuning |
path | — | — | Tuned values written by roboloom tune-gravity (gravity_gain, hold_mA, hold_kp); setting those keys inline as well is refused |
kd |
number or one per joint | 0.0 |
mA/(count/s) | Damping |
ramp_s |
number | 1.0 |
s | Time from torque on to the full output |
homing |
{kp_mA_per_count, max_mA} |
— | mA/count, mA | The spring that pulls the joint along a home move; required on a leader's current-mode groups when its controller has home |
gravity_comp
A hand-guided joint that does not fall: current = gain × g(q) − kd × velocity plus the range barrier. With hold_mA above 0, a spring of hold_kp pulls the joint to an anchor, never harder than hold_mA; pushed harder, the anchor slides along with the hand (it acts like friction).
Besides the keys of current-mode laws it reads the following. gravity_model is required.
| Key | Type | Default | Unit | Description |
|---|---|---|---|---|
hold_mA |
number or one per joint | 0.0 |
mA | Cap of the holding force; 0 does not hold |
hold_kp |
number | 1.0 |
mA/count | Stiffness of the holding spring |
impedance Mock only
Joint impedance around the target: kp (q* − q) − kd × velocity + gain × g(q). It is not validated on hardware, so on hardware it needs allow_unvalidated: true.
Besides the keys of current-mode laws it reads the following.
| Key | Type | Default | Unit | Description |
|---|---|---|---|---|
kp |
number or one per joint | required | mA/count | Stiffness |
allow_unvalidated |
boolean | false |
— | true lets it start on hardware |
Taking force feedback (feedback) Mock only
feedback: on a leader's current-mode group (gravity_comp, impedance) makes its joints take the feedback a controller sends. Position-mode groups and free cannot have it. For the path and the controller's side see the controller's feedback.
| Key | Type | Default | Unit | Description |
|---|---|---|---|---|
max_mA |
number or one per joint | required | mA | Limit of the feedback alone |
ramp_s |
number | 0.3 |
s | Time the gate takes to open or close |
kd |
number or one per joint | 0.0 |
mA/(count/s) | Damping added while the feedback is on |
- group: right_arm
law: gravity_comp
# ...
feedback:
max_mA: 20 # limit of the feedback alone (a per-joint list also works)
ramp_s: 0.3 # time the gate takes to open or close (default 0.3)
kd: 0.0 # damping added while the feedback is on, mA/(count/s) (default 0)
Every tick, the leader adds the following to the law's output, then clips the sum at max_current_mA.
gate × (clip(received current, ±max_mA) − kd × velocity)
gate is a value from 0 to 1. It moves toward 1 over ramp_s while the controller asks for the feedback and the message is within its deadline (deadline_ms), and toward 0 otherwise. It never jumps. Estop, release, quit, going limp, and a detected runaway set it to 0 at once. Joints that take feedback are checked for runaway (max_velocity, out of range) even with gravity gain 0. tune-gravity and gravity-check run without feedback. On hardware, roboloom checks max_mA ≤ max_current_mA. The leader status shows gate, the feedback current per joint (mA) and the number received under feedback; the trace (<leader name>_trace.npz) keeps it as feedback_mA.
The feedback current stays inside the same max_current_mA and EEPROM Current Limit as gravity compensation, so near the limit it is clipped. Raising the Current Limit also raises the force left on the arm if the host stops (an XC330 does not stop its current when the Bus Watchdog fires).
Range and speed limits (limits)
A follower's limits is its per-joint safety check: every joint, in order, by name. Every command of a controller passes this check. An experiment file cannot change it.
| Key | Type | Default | Unit | Description |
|---|---|---|---|---|
name |
text | required | — | Joint name, in the follower's joint order |
min |
number | required | follower unit | Lower position bound (min < max); targets outside the range are clipped to it |
max |
number | required | follower unit | Upper position bound |
max_speed |
number | required | follower unit/s | Targets beyond it are clipped; keep it above the controller's max_speed (Units) |
max_jump |
number | required | follower unit | A command farther than this from the last target sent is rejected |
Home pose (home)
A controller's home: is the saved pose that the home command (infer --home, Session.home(), Move home on the screen) moves to. Save poses with roboloom capture-pose <name>, into poses/<follower>/<name>.yaml.
| Key | Type | Default | Unit | Description |
|---|---|---|---|---|
pose |
path | required | — | The saved pose, relative to the node file's directory (e.g. ../poses/follower/ready.yaml) |
max_speed |
number | required | follower unit/s | Speed of the move; at most the controller's max_speed |
tolerance |
number | required | follower unit | How close counts as arrived |
timeout_s |
number | 30 |
s | How long to wait for arrival |
Where it goes depends on the controller.
| Controller | Form |
|---|---|
joint |
home: {pose, max_speed, tolerance}; the leader moves to the matching pose too, and its current-mode groups need homing |
policy |
home: {pose, ...} with one follower, {follower: {pose, ...}} with several (followers left out stay) |
pose_ik |
{follower: {pose, ...}} |
parts |
Not available (nor on its inner controllers) |
Example
# part of a leader's node YAML
control:
- group: right_arm
law: gravity_comp
joints: [r_arm_sh_pitch1, r_arm_sh_roll, r_arm_sh_pitch2, r_arm_el_yaw, r_arm_wr_roll, r_arm_wr_yaw]
gravity_model: ../calibration/gravity_right.yaml
tuning: ../calibration/gravity_tuning_right.yaml
max_current_mA: [150, 150, 100, 100, 60, 60]
max_velocity: 3000
range: ../calibration/travel_right.yaml
homing: {kp_mA_per_count: 0.5, max_mA: 40}
- group: trigger
law: spring
joints: [r_arm_grip, l_arm_grip]
rest: 2500
goal_current_mA: 30
bus_watchdog_ms: 500