API reference¶
The classes exported from strands_robots, and the subpackages that hold the rest of the API.
from strands_robots import Robot, Simulation, Policy, Body, Description, Observation, Action, JointState, Pose
These are the main classes. Import the rest from their subpackages:
| Subpackage | Holds |
|---|---|
strands_robots.mesh |
Mesh, authority |
strands_robots.robot.safety |
RequestRefused |
strands_robots.recording |
Dataset recording |
strands_robots.dashboard |
Dashboard |
strands_robots.policy |
Perturb, LeRobot policies |
Robot¶
Bases: DeviceVerbs
A body in a world (sim=, or Simulation.default()) or on a bus (port=/driver=): same verbs.
is_real
instance-attribute
¶
supports_position_hold
instance-attribute
¶
tool
property
¶
This robot as a strands agent tool, generated from its rpcs (imports strands on first use).
set_pose ¶
Teleport (sim only). A hardware robot raises; its twin can still be teleported.
set_gains ¶
PD gains of this body's actuators, action_keys order (sim, or a driver that sends gains per command).
observe ¶
One read of the body; t is the capture time on the robot's clock.
gate ¶
gate(action: Action, *, confirmed: bool = False, approved_run: bool = False, **kw: Any) -> np.ndarray
The operator gate for commands from an agent tool or dashboard (robot.gate; measured/source).
act ¶
Write targets for THIS body and advance its world (a real body: its twin's) one control step.
seconds: reach the pose instead, ramping there from the measured one over that long (robot.reach).
Returns what the body reports after (one read); a run loop calls command instead.
command ¶
The run loop's write, no read: full targets checked as act checks them (NaN/inf or a wrong
length refused, clipped into the limits) before the body, then the world advances.
calibrate ¶
Read (or, at the arm, record) the bus calibration: LeRobot's calibration JSON, unchanged.
coerce ¶
Any accepted Action -> full targets in action_keys order (see robot.targets.coerce).
stop ¶
End the background run: its result, or its error raised once; None when nothing runs.
Simulation¶
Bases: _SceneOps
One world. Owns time. Holds many robots. Simulation() is MuJoCo, headless; Simulation.default() is
the process-wide world every Robot joins when it is given none.
backend
instance-attribute
¶
backend: Backend = cls(physics=physics, headless=headless, device=device, num_envs=num_envs, render_size=render_size)
tool
property
¶
This world as a strands agent tool, generated from its public verbs (imports strands on first use).
default
classmethod
¶
The world a Robot attaches to when none is given: MuJoCo, headless, created on first use.
control_step ¶
Advance exactly one control step (physics.substeps physics steps) unless time is manual.
manual_time ¶
Inside: robot.act() only writes targets; the caller steps the world.
editing ¶
Batch scene edits into one rebuild on exit (on newton a new scene shape compiles kernels). A block that fails, in its body or in its rebuild, restores the scene and robots as they were; step, render and set_pose outside a block flush pending edits first.
reset ¶
Every body back to its spawn state, or to keyframe where a robot has one.
run ¶
run(policies: Mapping[str | Robot, PolicyLike | Callable[[Observation], Any]], *, hz: float | None = None, seconds: float | None = None, steps: int | None = None, instruction: str | None = None, units: str | None = 'auto') -> dict[str, RunResult]
Drive N robots in lock-step (robot id -> policy spec): each observes and acts, then the world steps once.
pose ¶
Where a robot base, an object or a robot link ("so101/gripper") is now: position m, quat w,x,y,z.
describe ¶
Robots (spawn frame, live pose, links), objects where they are now, cameras, physics, time; JSON-safe.
Policy¶
Base class: override act; units and requirements say what the policy speaks and needs.
Optional hooks the run loop honours: attach(robot) before step one (connect, admit, load),
detach() after the last step, realtime (pace in wall time even in a sim), hz and
needs_observation (the loop renders the cameras only for a step that answers True), gains
(kp, kd), start_pose (where its episodes begin, in the policy's units — a mapping or a full
vector — reached over start_seconds, default 3, before step one). The loop reads them once before
step one; a hook of the wrong type is a TypeError.
act ¶
The action for this observation, or None to hold: the run loop writes nothing that tick, the body
keeps its last target, and the tick is a RunResult.holds entry — never a deadline miss.
needs_observation ¶
Whether the next act looks at the observation's images; the default looks on every step.
requirements ¶
Cameras/state this policy needs; the default needs nothing specific.
Description¶
A robot model resolved to a file plus the facts a world or a bus needs about it.
limits
class-attribute
instance-attribute
¶
joint_labels
class-attribute
instance-attribute
¶
spawn_position
class-attribute
instance-attribute
¶
describe ¶
JSON-safe summary (what an agent tool and the dashboard read).
load
classmethod
¶
Resolve a registry name, alias, robot_descriptions name or MJCF/URDF path.
Observation, JointState, Pose¶
What a body reports at time t: joints, base pose, camera images and per-body extras.
== compares every field by value (images and extras too); hash reads t, joints and pose.
Positions/velocities/efforts for a named set of joints (SI: rad, rad/s, N·m). A value: ==, hash.
A rigid pose in the world frame: position (m) and orientation as a unit quaternion (w, x, y, z).
A floating body also reports its twist: linear_velocity (world frame, m/s) and angular_velocity
(body frame, rad/s — what a gyro mounted on the base reads). Fixed bases and drivers leave both None.