SDK 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 is a report of the facts. It reads the latest state, sends nothing, never waits and never raises for a robot condition. action is "stand", "move" (balance() and set_velocity()) or "trajectory" (set_joints() and trajectory()). Only the blocking codes, which all mean no live state, stop a command; 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. Blocking: not_connected, no_state, stale_state. Information, which nothing in the SDK acts on: faulted (the alerts that latched DAMP, named), alerts (active firmware alerts, named) and not_armed (move from STAND before the arming hold). The codes and their meaning are in What the SDK Reports. State older than 0.5 s is stale; armed means gravity z below -0.87 for 0.5 s. The SDK holds no joint temperature or battery threshold: write your own rule, as in Write Your Own Guard.

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

Every verb is sent in any robot mode, and the firmware decides what it does. The robot mode, a latched fault, an alert, a joint temperature or the battery never stop one. The one refusal is no live state: set_velocity, stand, balance outside MOVE, set_joints and trajectory read one cached sample before they send, which adds no delay on a live stream. Without one (no_state, stale_state) they wait up to timeout, then raise NotReadyError with nothing sent. After a STAND sent moments ago whose report has not arrived, they wait up to 1 s for that report, then send anyway. A closed Robot raises NotConnectedError, a lost link LinkLostError and a protocol version mismatch ProtocolMismatchError, at once. balance in MOVE and damp are sent at once. A wait that sees a latched fault after the command was sent raises RobotFaultedError with .sent set.

Walk. Sent in any robot mode: in MOVE the robot walks; in an armed STAND it enters MOVE; in DAMP the robot drops it. Without live state it waits up to timeout (5 s by default), then raises NotReadyError with nothing sent. 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 live-state 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 it is sent at once; it ends any velocity hold and sends zero, so this is how a walk ends. Outside MOVE it sends zero velocity as soon as there is live state, without waiting for arming. From an armed STAND that puts the robot in MOVE; with wait, it returns once the robot reports MOVE, and raises WaitTimeoutError when the whole call passes timeout, saying so when the robot was not armed. From DAMP it raises WaitTimeoutError at once: "the robot is in DAMP: stand() first". RobotFaultedError when the wait sees a latched fault. Not an emergency stop.

Put the robot in STAND: the actuators hold the standing pose, without a balance loop. Sent from any robot mode. From MOVE, hang the robot from its gantry hook or seat it on a stool or bench first: 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, so hang it from its gantry hook or seat it on a stool or bench first. Sent at once, whatever the robot's state. With wait, returns once the robot reports DAMP or FAULT_DAMP, WaitTimeoutError after timeout. Not an emergency stop: in an emergency use the E-Stop in Asimov Manager, or cut power at the battery unit.

Sent in any robot mode; the firmware follows a trajectory in MOVE or an armed STAND. Waits for live state first (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 live-state 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. Sent in any robot mode. Checks for live state once, with no delay on a live stream, so a loop at 50 Hz can call this. On a stale stream 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 means there was no live state to send against (no_state or stale_state) within the command's timeout; nothing was sent. A closed Robot raises NotConnectedError, a lost link LinkLostError, a protocol version mismatch ProtocolMismatchError. It reads not ready to <action>: <message> (<code>); <fix>, with (waited <t> s) appended when the command waited. RobotFaultedError is raised by a wait that saw a latched fault after the command went out; 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. A robot whose participant attribute asimov.commands_track is "1" also reads a commands data track from each client: the SDK sends a non-zero velocity and a trajectory there, and Asimov Edge orders it against the topic by sequence number, dropping a setpoint older than a command it already took. 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.