Skip to content

Robot safety

Action envelopes, a shadow simulation, approvals through the executor, an e-stop and a deadman watchdog, for robots in simulation. Guide: Gate a robot.

agent_adapter.robotics

Safe robot actions: envelopes, a shadow simulation, approvals and an e-stop (simulation first).

RobotGate turns a RobotPort into executor tools. MujocoSim (extra mujoco) is imported from agent_adapter.robotics.mujoco_sim.

ActionSpec

Bases: BaseModel

The envelope a robot works in without a person, and the hard limits beyond it.

Inside workspace, max_speed and max_force a command runs. Outside them it needs an approval, unless it breaks a hard limit (hard_*, keep_out) or the command rate: then it is blocked and no approval can run it. Unset hard limits leave approval as the only ceiling; keep-out zones always block, also when a simulated path only passes through one. A speed below min_speed (default: a thousandth of max_speed) and a move that would take longer than max_duration seconds are blocked too.

slowest_speed property

The lowest speed a move may use: min_speed, or a thousandth of max_speed.

Box

Bases: BaseModel

An axis-aligned box in metres, from corner lo to corner hi.

crosses(start, end)

True when the straight segment from start to end touches the box (slab test).

CallbackRobot

A RobotPort from your own functions: an rclpy publisher, a LeRobot robot, a driver.

The callbacks may be sync or async, except reset, which is sync. After stop, execute refuses until reset(). Nothing here imports ROS or LeRobot.

Command

Bases: BaseModel

One robot command: a move of the end effector, or a grip.

Deadman

Calls on_lost once when beat() has not been called for timeout seconds.

Heartbeats should come from the operator or the controlling process, never from the model: a model that can beat can be told to keep beating.

KinematicSim

SimPort: the end effector moves in a straight line at the commanded speed.

RobotGate

Puts a robot behind an ActionSpec, a SimPort shadow and the executor's approvals.

Inside the envelope a command runs. Outside it, the tool's confirm rule asks the executor's approval port; there is no other approval path. A command that breaks a hard limit, enters a keep-out zone in simulation, exceeds the rate, or arrives while the e-stop is latched or the heartbeat is lost is blocked, also when that happens while the command is being simulated. estop() never needs the executor, an approval or a free slot. Cancelling a running motion call stops the robot and latches the e-stop.

latched property

Why the e-stop is latched, or None when the robot may move.

add_tools(registry, *, prefix='')

Register move_to, grip, estop and reset_estop on registry.

check(command) async

The gate's verdict for a command now: its envelope, the gate state, its simulation.

deadman(timeout) async

Arm a deadman: no heartbeat() for timeout seconds triggers estop().

estop(reason='estop') async

Latch the e-stop and stop the robot. No executor, approval or lock involved.

heartbeat()

An operator or controlling-process heartbeat for the deadman watchdog.

reset()

Release the e-stop (the reset_estop tool asks a person first).

RobotPort

Bases: Protocol

A robot (or a stand-in) the gate sends commands to.

stop halts motion now. It must be safe to call at any time, more than once, and while execute is still running: execute then returns early. After a stop, execute should refuse until an optional reset() (no arguments, sync), which the gate calls when a person releases the e-stop.

SimPort

Bases: Protocol

Runs a command in simulation first; returns the end effector's path.

simulate(start, command, spec) async

The simulated path from start; an empty path for a command that does not move.

SimRobot

RobotPort stand-in that moves a point in real time, one control tick at a time.

stop wakes the control loop at once and latches: execute refuses until reset(). log keeps every command the robot accepted; halted_at is the clock time the last motion ended.

Verdict dataclass

What the gate does with a command, and why.

Waypoint

Bases: BaseModel

One sample of a simulated path: where the end effector is at time t (s).

judge(spec, command)

Judge a command on its own arguments: the part an approval can cover.

judge_path(spec, start, path)

Judge a simulated path against keep-out zones and hard limits (never approvable).

agent_adapter.robotics.gate

agent_adapter.robotics.gate re-exports, documented under the canonical path: RobotGate.

agent_adapter.robotics.spec

Action envelopes: what a robot command may do alone, with approval, or never.

Action = Literal['run', 'approve', 'block'] module-attribute

Point = tuple[float, float, float] module-attribute

Also exported here, documented under the canonical path: ActionSpec, Box, Command, Verdict, Waypoint, judge, judge_path.

agent_adapter.robotics.ports

agent_adapter.robotics.ports re-exports, documented under the canonical path: CallbackRobot, RobotPort, SimPort.

agent_adapter.robotics.kinematic

A built-in kinematic simulator and a simulated robot: no physics engine, no hardware.

MAX_WAYPOINTS = 100000 module-attribute

straight_line(start, target, speed, dt, *, max_steps=MAX_WAYPOINTS)

Constant-speed samples every dt seconds from start to target (the last is exact).

Raises:

Type Description
ValueError

the path needs more than max_steps waypoints.

Also exported here, documented under the canonical path: KinematicSim, SimRobot.

agent_adapter.robotics.watchdog

agent_adapter.robotics.watchdog re-exports, documented under the canonical path: Deadman.

agent_adapter.robotics.mujoco_sim

MuJoCo shadow simulator (extra mujoco): the path comes from physics, not a straight line.

GANTRY_XML = '\n<mujoco model="agent_adapter_gantry">\n <option timestep="0.002" gravity="0 0 0"/>\n <worldbody>\n <body name="ee">\n <joint name="x" type="slide" axis="1 0 0" damping="30"/>\n <joint name="y" type="slide" axis="0 1 0" damping="30"/>\n <joint name="z" type="slide" axis="0 0 1" damping="30"/>\n <geom type="sphere" size="0.02" mass="0.5"/>\n <site name="ee"/>\n </body>\n </worldbody>\n <actuator>\n <position joint="x" kp="400"/>\n <position joint="y" kp="400"/>\n <position joint="z" kp="400"/>\n </actuator>\n</mujoco>\n' module-attribute

MujocoSim

SimPort on MuJoCo: servos chase a setpoint that moves at the commanded speed.

The default model is a gantry. A model of your own needs the same layout: the first three position actuators drive x, y and z slide joints at qpos 0-2, and a site named site marks the end effector. Overshoot and lag show up in the path the gate checks.

agent_adapter.robotics.ros2

ROS 2 robot port: velocity commands on a cmd_vel topic, position from a pose topic.

rclpy comes from a ROS 2 install, not from PyPI. Defaults fit turtlesim.

ROS2Robot

RobotPort for a ROS 2 mobile base driven by geometry_msgs/Twist velocity commands.

Our Point maps to the robot's x and y in the pose topic's frame; z is fixed (z=) and a target with another z is refused. A move turns towards the target, then drives with linear.x never above the command's speed, until it is within tolerance metres; its final heading is not controlled. Missing pose updates for pose_timeout seconds or a move that overruns its deadline stops the robot with a ToolError.

stop publishes a zero twist at once and latches: execute refuses until reset(). Without node= it opens its own rclpy context, node and spin thread (close() ends them); with node= you spin that node yourself. A grip runs grip= or is refused.

close()

Stop the spin thread and shut down the context this robot opened (if any).

wait_for_pose(timeout=5.0) async

Wait for the first pose message; raises ToolError after timeout seconds.

odometry_pose(msg)

nav_msgs/msg/Odometry to (x, y, heading): the yaw of its orientation quaternion.

turtlesim_pose(msg)

turtlesim/msg/Pose to (x, y, heading).