Hooks
Mock only
A hook is a local extension of a policy node: gate releases, correct residual actions, or observe lifecycle events without changing the policy implementation. Hooks are mock only; this example is not a validated tactile detector.
1. Write a local hook
Save this file next to the robot configuration, or in an installed package. The example assumes gripper counts increase toward open. Replace its image-mean condition with a task-specific detector before hardware validation. step may return None for unchanged input.
# .roboloom/<robot>/release_gate.py
from collections.abc import Sequence
import numpy as np
from roboloom.errors import ConfigError
from roboloom.hooks import Hook, HookSpec, Requirements, StepContext
class ReleaseGate(Hook):
def __init__(self, joints: Sequence[str], max_image_mean: float = 80):
self.joints = tuple(joints)
self.max_image_mean = max_image_mean
def requirements(self) -> Requirements:
return Requirements(
observe=(
"observation.state",
"observation.images.digit_left",
"observation.images.digit_right",
),
writes=self.joints,
sources=("policy", "teleop"),
on_error="hold",
)
def bind(self, spec: HookSpec) -> None:
if any(
spec.units[spec.names.index(j)] != "dynamixel_count" for j in self.joints
):
raise ConfigError("this example assumes counts increasing toward open")
def step(self, action: np.ndarray, ctx: StepContext) -> np.ndarray:
observed_state = ctx.observation["observation.state"]
left = ctx.observation["observation.images.digit_left"]
right = ctx.observation["observation.images.digit_right"]
# Mock demonstration only: replace with your validated tactile detector.
allow = (
bool(np.isfinite(observed_state).all())
and max(float(left.mean()), float(right.mean())) < self.max_image_mean
)
for joint in self.joints:
if joint not in ctx.names:
continue
i = ctx.index(joint)
if not allow and action[i] > ctx.state[i]:
action[i] = ctx.held[i]
ctx.note(allow_release=allow)
return action
def make(joints: Sequence[str], max_image_mean: float = 80) -> ReleaseGate:
return ReleaseGate(joints, max_image_mean)
2. Claim writes in YAML
Enable both DIGIT sensors in the robot configuration, then add the hook to the policy node. observe keys must come from followers or the node’s observe: sources. For policy-only operation, narrow sources to [policy] and omit teleop:.
# Add to nodes/policy_teleop.yaml (its teleop: controllers stay configured).
observe: [camera, digit_left, digit_right]
hooks:
- factory: release_gate:make
kwargs:
joints: [follower.r_arm_grip, follower.l_arm_grip]
max_image_mean: 80
writes: [follower.r_arm_grip, follower.l_arm_grip]
sources: [policy, teleop]
on_error: hold
budget_ms: 3
name: release_gate
3. Contribute a hook from a policy
An optional policy.hooks() -> Sequence[Hook] is called after policy.bind(spec). Return your hook instances there. A writing contribution requires the explicit YAML claim below; missing claims refuse loading and print these two entry lines. Contributions occupy that slot; without it, observe-only contributions go first.
hooks:
- from: policy
writes: [follower.r_arm_grip, follower.l_arm_grip]
4. Check the mock run
- Validate the configuration with
roboloom validate <robot> --with policy --with policy_teleop --mock. - Launch a mock policy episode and try takeover and handback. Steps run only during an episode; plain joint teleop/record nodes keep hooks disabled.
- Inspect
hook_ms,hook_max_ms,hook_errors,hook_over,filteredand the per-hook episode-end log (ms,max_ms,errors,over,changed,notes). - Check
action.filteredin the dataset. It is float32[1], OR over all commands/followers in a row, and exists only when YAML has nonempty hookwrites.
See configuration tables, Python API, and where hooks run.