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