Referencemakiina.robot
makiina.robot
Every method of the Robot object and its namespaces, for an arm on your PC and a robot anywhere.
from makiina.robot import Robot, RobotError, namesOne class, Robot, for the hardware on your PC and for robots anywhere. The guides show these calls in use; this page lists them all.
Open a session
Robot.connect_local(*, adapters=None, identity=None, side=None, port=8770, timeout_s=30.0, action_rate_hz=90.0, on_status=None, server_output=None)
Starts a robot server on this PC, on its USB CAN adapters, and returns once joint state flows. robot.local is True; disconnect() stops the server.
| Argument | Meaning |
|---|---|
adapters | [{"interface": "candle", "channel": "<serial>:0"}, ...] to use only these adapters; default every adapter |
identity | a folder name under robot-calibrations/ or a path; default this PC's own folder, created the first time |
side | "left" or "right" for an arm whose boards do not say which side they are (old firmware) |
port | loopback port of the server; a second session on the same PC needs its own |
timeout_s | how long to wait for the server to start and report the first state |
action_rate_hz | how often commands are sent |
on_status | a function that receives progress messages |
server_output | path of the server log; default logs/<identity>-server.log |
Robot.connect(robot=None, *, cloud=None, email=None, password=None, base_url=None, receive_cameras=True, timeout_s=60.0, action_rate_hz=90.0, allow_relay=True, force_relay=False, on_status=None, video_layout="full")
Signs in to MAKIINA Cloud, offers a session to a robot of your account and returns when it is live. The cloud only introduces your PC and the robot: video and control then flow directly between them, or through MAKIINA's relay when no direct path works.
| Argument | Meaning |
|---|---|
robot | robot name or id; None picks the only robot of the account |
cloud | an already signed-in makiina.cloud.CloudClient |
email, password | credentials; default MAKIINA_EMAIL and MAKIINA_PASSWORD, then the sign in saved by the command line tool; an account with two step sign in needs the saved sign in |
base_url | another cloud endpoint; default MAKIINA_CLOUD_URL or the built-in one |
receive_cameras | False for a session without video |
timeout_s | how long to wait for the robot to answer and report its first state |
action_rate_hz | how often commands are sent |
allow_relay, force_relay | use the cloud relay when no direct path works, or always |
on_status | a function that receives progress messages |
video_layout | the head camera mode: "full" (full res, the default) or "head" (foveated); see Head cameras |
Robot.connect_direct(listen_port=8766, *, timeout_s=120.0, action_rate_hz=90.0, on_status=None)
Waits for a robot on your LAN that you started by hand, pointed at this PC, with no cloud involved. Control and state only; no camera frames.
makiina.arm.Arm.connect(config=None, *, interface=None, channel=None, port=..., ...)
The older entry point for an arm on this PC. The same kind of object as connect_local(); config is a folder name under robot-calibrations/. With config=None it reads one calibrated arm off one adapter, through default_interface() unless you name interface: on Linux that is can0, so pass interface="candle" for the USB path. It then runs on robot-calibrations/arm-auto/, which it writes again from the defaults at every call, not on your PC's folder: settings you keep there do not apply, and the log is logs/arm-auto-server.log.
The session
| Member | What it is |
|---|---|
disconnect() | ends the session; stops the local server; safe to call twice; with Robot.connect(...) as robot: calls it at the end |
local | True when the server runs on this PC |
parts | ["right_arm"], ["left_arm", "right_arm", "head"]; empty until the first state |
capabilities | what the robot offers: grippers, streams, features |
status | link state and network path |
ping_ms | round trip, measured on the robot's echo of your clock |
state_timestamp | the robot clock time of the newest state, in seconds |
boot_phase | the robot's boot progress; None once it is up |
video_layout | the head camera mode you asked for; sensors.get_video_layout() says what the robot streams |
console_tail() | the robot server's recent log lines |
sensors
Everything measured. Reads return at once.
| Call | Returns |
|---|---|
get_joints(by="wire") | joint positions in rad; by="part" for part names |
get_joints_timed() | {joint: (rad, time measured)}, robot clock |
get_velocities() | rad/s per joint |
get_currents() | A per joint |
get_grippers() | gripper finger joints |
get_ee_poses() | {arm: 4x4} gripper poses in metres, from the measured joints |
get_ee_triggers() | the last trigger sent per gripper, 0 before the first |
get_head(), get_head_velocity(), get_head_current() | the head's yaw (rad), velocity and current |
get_gaze() | the fovea centres you last asked for |
camera_names() | the streams this robot offers |
get_camera_frames() | {stream: HxWx3 RGB array}, newest frame of each; in full res the two fovea frames are windows your PC cuts out of the full pictures |
get_camera_frames_and_metas() | {stream: (RGB array, meta)}: each frame with its fovea window (crop), the head pose and its timing |
get_camera_frame_metas() | the metas alone |
get_video_layout() | the head camera mode the robot streams now: "full" or "head" |
get_video_layout_status() | "starting", "preparing", "streaming" or "failed: <why>"; None from a robot with older software |
model
The kinematic twin. Nothing here moves the robot.
| Call | Returns |
|---|---|
joint_names() | joint names in the robot's order |
ee_names() | ["right_arm", "left_arm"] |
get_joint_limits() | the limits of each joint, rad |
named_poses() | {"zero": {...}, "neutral": {...}} |
compute_ee_poses(joints) | gripper poses of any joint configuration |
solve_ik(poses, seed_joints=None, iterations=100) | the joints that reach {arm: 4x4}; out of reach gives the closest reachable configuration |
urdf_xml(), urdf_dir() | the robot's model and the folder of its meshes |
control
The first motion call arms the session.
| Call | Does |
|---|---|
set_joints_absolute(joints) | targets in rad; joints you do not name keep theirs |
set_joints_relative(deltas) | adds to the current targets, rad |
set_ee_poses_absolute(poses, iterations=100) | gripper poses {arm: 4x4}, solved into joint targets |
set_ee_poses_relative(deltas, iterations=100) | new = delta @ current, in the world frame |
set_ee_triggers(triggers) | gripper closure, 0 open to 1 closed, by gripper name; a gripper you do not name goes to 0 and opens |
set_head(position) | head yaw in rad, positive to the right |
set_gaze(gazes) | fovea centres [rx, ry, lx, ly] in 0 to 1, right camera then left; works while disarmed |
set_gaze_method(method) | "HeadsetOrientation" (640 x 640 foveas) or "EyeTrackingCombined" (320 x 320); in the foveated mode the streams restart |
set_video_layout(layout) | "full" or "head"; the head camera streams restart |
get_commanded_joints() | the targets being sent |
set_actuator_parameters(params) | live drive settings; "key" for every joint, "<joint>/key" for one |
get_actuator_parameters(timeout=3.0, keys=None) | the settings every drive runs, read from the boards |
set_video_bitrate(kbps) | full res: the bitrate of each head camera's picture, kbit/s, kept by the robot |
set_video_bitrates(context=None, fovea=None) | foveated: the context and fovea bitrates, kbit/s, kept by the robot |
request_video_refresh(channels=None) | full res: ask the robot to repair the head pictures now (the link asks by itself when a picture is lost); in the foveated mode the robot ignores it, and a damaged picture waits for the regular refresh, up to about 10 s |
set_camera_params(params) | ae_enable, exposure_time (us), analogue_gain, sharpness, in both modes; the streams restart |
set_console_stream(enabled, hz=2.0) | turn the stream of the robot server's log into console_tail() off or on; it is on until you turn it off |
stop() | disarm: send no new targets until the next command; a joint on its way finishes its move, then holds |
Head cameras
The head streams its two cameras in one of two modes. Your code is the same in both: the stream names, the fovea sizes and the gaze calls do not change.
| Mode | stereo_cam_left, stereo_cam_right | stereo_cam_left_fovea, stereo_cam_right_fovea |
|---|---|---|
"full", full res (the default) | each camera's whole picture, 2304 x 1296, 56 frames per second | windows your PC cuts out of the full pictures at the gaze |
"head", foveated | a 1152 x 648 context picture of each camera | windows the robot cuts out of each camera's 2304 x 1296 picture at the gaze and streams |
A fovea is 640 x 640, or 320 x 320 with "EyeTrackingCombined". It centres on the gaze and stops at the edges of the picture. In full res it is the same size and in the same place as the robot's fovea, and changing the gaze method changes only the window your PC cuts. A robot with older software streams foveated whatever you ask. See what the robot sees shows the calls in use.
safety
Applied on the robot's side. A session starts every motor at its full current and speed limits, so set these caps before the first motion command.
| Call | Does |
|---|---|
set_torque_fraction(fraction) | caps every joint's current at a fraction (0 to 1) of its limit; no effect after torque_on() in the same session |
set_max_joint_velocity(rad_s) | caps every joint's speed, rad/s at the joint |
torque_on() | every motor at its full current limit, for the rest of the session; disarmed, the arm holds where it is, armed, it drives back to the targets it had |
torque_off() | release the motors; the arm sags |
reboot_robot() | restart the computer of a robot in your fleet. Support the arms and call torque_off() first: the robot sends no torque off of its own, and each drive holds its last target, although the docstring says the motors de-energise. Not for a session on your PC |
set_actuator_parameters with any max_current key or max_velocity writes that value to the drives and replaces these limits (Tune safely).
actuation
| Call | Does |
|---|---|
get_frequency() | the rate commands are sent at, Hz |
set_frequency(hz) | change it |
recording
Flags for a session recorder; the robot itself records nothing.
| Call | Does |
|---|---|
start(subtask=None) | recording on, both arms engaged |
stop() | recording off |
mark_demo() | start the next demonstration |
set_subtask(subtask) | the task label from now on |
set_trackings(trackings) | per-arm engagement, [right, left]; a span with both off splits episodes |
names
| Call | Returns |
|---|---|
names.part_name("J01-R") | "right_J1" |
names.wire_name("right_J1") | "J01-R" |
names.is_part_name(s) | whether s is a part name |
Errors
RobotError for an unknown joint name (the message lists the valid ones), a call before the session is up, a twin that is not available, a robot that does not answer, or a sign in that Robot.connect could not make. makiina.cloud.CloudError for a session the cloud refuses: the robot is offline, in maintenance, or in use by someone else.