Reference

Everything here is importable from menlo.asimov unless a module is named. menlo.__version__ is the distribution version. Units are metres per second, radians per second, radians, degrees Celsius.

The LiveKit identity is sdk-<credential id>-<host>-<6 random hex>; robot.info.endpoint reads room@url as <identity> on livekit and host:8850 + room@url as <identity> on hybrid. Two sessions with the same label evict each other.

None resolves the robot from the environment, else the saved robot. limits here wins over MENLO_LIMITS, which wins over the saved robot's limits, which win over Limits().

Attach on "udp", "hybrid" or "livekit"; mode may be left out when the config names one or can reach only one. Returns once the first State has arrived and its protocol version matches. Raises ConnectError before touching the network when the config lacks what the mode needs, naming the menlo robots add command that fixes it. media_timeout bounds the wait for camera, microphone and speaker tracks. require_state=False returns as soon as the connection is open. persist=True, or MENLO_PERSIST=1, saves the robot after a successful connect with a ManagerConfig. close() then connect() again to switch modes.

open(*, timeout=5.0, allow_version_skew=False, require_state=True) does the same over a Transport passed to the constructor. RuntimeError on an open robot.

preflight reads the latest state, sends nothing and never raises for a robot condition. stand() runs it for "stand", balance() from STAND and set_velocity() for "move", set_joints() and trajectory() for "trajectory", before they send; see Verbs. armed is True in MOVE and in STAND once the robot has been upright (gravity z below -0.87) for 0.5 s since STAND began; False in DAMP or before; None with no state, closed, in UNKNOWN, or in STAND with no gravity.

Problem(code, message, blocking); str() is code: message. The codes and their meaning are in Check Before You Move. The thresholds: state older than 0.5 s is stale, battery below 20 %, a joint at or above 60 °C, armed means gravity z below -0.87 for 0.5 s.

Each returns a Sent. The robot reports no per-command verdict: Sent.outcome stays None and wait_outcome() returns Unknown in every mode. Read the effect from robot.get_state().

set_velocity, stand, balance from STAND, set_joints and trajectory run preflight() for their action before they send. A passing check reads one cached sample and adds no delay. A blocking problem that clears on its own (no_state, stale_state, not_armed, or DAMP still reported just after a stand()) is waited out for up to timeout seconds; any other raises NotReadyError at once, a latched fault RobotFaultedError, and nothing is sent. balance in MOVE and damp are never checked.

Walk in MOVE. Checks "move": from STAND it raises NotReadyError (wrong_mode; balance() it first), from DAMP the same (stand() it first), and nothing is sent; a stale_state is waited out up to timeout (5 s by default). Clamped to limits; re-sent at 10 Hz until balance(), another verb, close(), or duration seconds pass, when zero is sent. wait defaults to True: block until the hold has ended and its zero has gone out, or another verb took over; that needs a duration, else ValueError. wait=False returns once sent and keeps the velocity until the next command, or until duration. hold=False sends exactly one packet and holds nothing, for a loop that clocks its own commands; the check is made once, as in trajectory(), and duration or wait=True with it is a ValueError. ValueError on a non-finite value or a non-positive duration. See Move the Robot.

Zero velocity: the robot is in MOVE and the walking policy balances it in place. In MOVE, never checked; it ends any velocity hold and sends zero, so this is how a walk ends. In STAND, checks "move" first, waiting up to timeout for not_armed to clear, then sends zero velocity, which puts the robot in MOVE; with wait, returns once the robot reports MOVE, WaitTimeoutError when the whole call passes timeout. In DAMP, FAULT_DAMP or UNKNOWN it raises NotReadyError (RobotFaultedError for a latched fault) and sends nothing. Not an emergency stop.

Put the robot in STAND: the actuators hold the standing pose, without a balance loop. Checks "stand": from MOVE it raises NotReadyError (wrong_mode) and sends nothing, since a free-standing robot tips over. Sends STAND once and, with wait, returns when the robot reports STAND and is armed; WaitTimeoutError when the whole call passes timeout, RobotFaultedError when a fault latches meanwhile. wait=False returns once sent. Ends a running set_joints() and a held velocity.

Every actuator compliant now. A standing robot folds to the ground. Never checked: DAMP is sent whatever the robot's state. With wait, returns once the robot reports DAMP or FAULT_DAMP, WaitTimeoutError after timeout. Not an emergency stop.

Checks "trajectory" (MOVE or an armed STAND; a stale pose is waited out), then interpolates from the last reported pose to positions over duration, clocking trajectory() setpoints from a thread at hz, then holds the target until another verb. Any verb from any thread ends it before its next setpoint leaves. wait=True blocks until every joint is within tolerance rad, WaitTimeoutError otherwise. An ankle target more than 0.02 rad past the firmware's limits (0.35 rad pitch, 0.1 rad roll) is a ValueError before anything is sent. timeout bounds the whole call; left None, the check may wait 5 s and the target duration + 2 s. See Control Joints.

One setpoint, radians, firmware order; clock these yourself or use set_joints. Checks "trajectory" once, with no delay when it passes, so a loop at 50 Hz can call this. When the robot is not ready it raises NotReadyError at once and sends nothing; pass timeout to wait that long instead. ValueError unless len(positions) == info.dof, or when only one of kp and kd is given. A gain of 0 is not "no gain": the firmware substitutes its damping constants, so the joint does not hold a position. None applies the robot's per-joint gain table. The robot enters DAMP 2 s after the last setpoint.

Every wait reads the robot's own report, checks for a fault before its predicate, and refuses to succeed on a stale stream. stand(), balance(), damp() and set_joints(wait=True) wait this way for their own effect.

Blocks until predicate(state) is true and returns that first State. Raises WaitTimeoutError (the message names the robot mode and the age of the last sample), StateStaleError when the stream goes quiet for stale_after, and RobotFaultedError when a fault latches. stale_after defaults to link_timeout. A wait for one robot mode is wait_until(lambda s: s.mode is Mode.MOVE).

Robot is a context manager; __exit__ calls close().

Refusal (IntEnum): UNSPECIFIED, FW_DAMPED, FAULT_DAMPED, GATE, UNSUPPORTED_SOURCE, BAD_LENGTH, EMPTY_TRAJECTORY, NON_FINITE, PARSE, UNKNOWN_COMMAND, UNKNOWN_MODE, SHUTTING_DOWN, NO_CAMERA, NOT_ACTIVE, UNRECOGNIZED; retryable property; Refusal.from_wire().

Joint(name, pos, vel, current, temp): vel, current and temp are None when the robot did not report them. Alert(id, severity, value, threshold, source_id, first_set_us=0) with critical (severity == 0) and name. Battery(voltage_v, current_a, soc_percent, max_cell_temp_c, protection: BatteryProtection) with charging and protecting; BatteryProtection is an IntFlag.

RobotInfo(transport, endpoint, dof, joint_names, protocol_version, limits, capabilities) with joint_index(name), has(capability) and a readable str().

Limits(vx=0.4, vy=0.4, vyaw=0.8): the defaults are the firmware caps (0.4 m/s, 0.4 m/s, 0.8 rad/s). Limits.parse("0.3,0.3,0.6"). Negative or non-finite values raise ValueError.

Frame(width, height, encoding, data, stride_bytes, key_frame, frame_id, timestamp_ns, sequence) with shape, age_s, to_numpy(), to_jpeg(quality=85). AudioChunk(sample_rate_hz, channels, samples_per_channel, encoding, data, stream_id, timestamp_ns, sequence) with duration_s, to_numpy(). Clip(frames, audio, started_at) with duration_s, fps, save_wav(path) -> Path, save_frames(dir), save_mp4(path, *, fps=None) -> Path, frames_as_numpy(). numpy, Pillow and OpenCV are needed only at the call that uses them, and named in the ImportError.

~/.menlo/robots.toml (MENLO_HOME moves it), 0600 in a 0700 directory.

Environment: MENLO_ROBOT, MENLO_MODE, MENLO_UDP_HOST, MENLO_MANAGER_URL, MENLO_CREDENTIAL, MENLO_LIMITS, MENLO_HOME, MENLO_PERSIST. MENLO_MANAGER_URL and MENLO_CREDENTIAL go together; one alone is a ConnectError. Environment wins over the saved robot and is not merged with it. See Command Line.

UdpTransport(host, *, command_port, state_bind, state_source), LiveKitTransport(url, room, *, token, media_timeout, connect_timeout), HybridTransport(host, *, livekit_url, room, token, command_port, state_bind, ...). All implement Transport; a ConnectionConfig builds the right one for the mode. LiveKitTransport.identity and .room read back what the token claimed.

NotReadyError reads not ready to <action>: <message> (<code>); <fix>. ..., with (waited <t> s) appended when a transient problem did not clear in time; nothing was sent. RobotFaultedError is raised by a command's check with nothing sent, and by a wait after a command went out, when sent is set. WaitTimeoutError.sent is the command whose effect did not arrive. Caller mistakes are builtins: ValueError (non-finite velocity, limit or duration, wrong trajectory length, a lone kp or kd, an unknown connection mode), KeyError (unknown joint name), RuntimeError (open() on an open robot). A mode the config cannot reach raises ConnectError.

Robot is synchronous and thread-safe. Callbacks run on the transport thread, the one that delivers state: keep them short. robot.damp() from a callback, such as on_alert damping on an alert, sends DAMP and returns at once. The other commands that wait for the robot, and wait_until(), raise RuntimeError there with nothing sent; pass wait=False, or call them from your own thread.

menlo.asimov.robots.ASIMOV_1_BIPED_JOINTS is the 25-actuator order of the Asimov 1 biped firmware profile, chosen by the reported joint count. menlo.asimov.robots.PROTOCOL_VERSION is the protocol version the SDK was built against; connect() compares it with what the robot echoes and raises ProtocolMismatchError on a difference.

Commands on udp go to port 8850 and state arrives on 8851, each datagram one bare asimov.io.RobotCommand or RobotState. On livekit, commands are data messages on the commands topic and state is the state data track. Every command carries protocol_version = 1, a sequence number and timestamp_us. UDP commands are not authenticated; the SDK credential and its role apply to the LiveKit room: every command on livekit, and the camera and audio on hybrid. Without the SDK and the livekit_raw/ examples speak it with the livekit and asimov-protocol packages alone.