MAKIINASDK

Referencemakiina.robot

makiina.robot

Every method of the Robot object and its namespaces, for an arm on your PC and a robot anywhere.

Python
from makiina.robot import Robot, RobotError, names

One 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.

ArgumentMeaning
adapters[{"interface": "candle", "channel": "<serial>:0"}, ...] to use only these adapters; default every adapter
identitya 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)
portloopback port of the server; a second session on the same PC needs its own
timeout_show long to wait for the server to start and report the first state
action_rate_hzhow often commands are sent
on_statusa function that receives progress messages
server_outputpath 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.

ArgumentMeaning
robotrobot name or id; None picks the only robot of the account
cloudan already signed-in makiina.cloud.CloudClient
email, passwordcredentials; 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_urlanother cloud endpoint; default MAKIINA_CLOUD_URL or the built-in one
receive_camerasFalse for a session without video
timeout_show long to wait for the robot to answer and report its first state
action_rate_hzhow often commands are sent
allow_relay, force_relayuse the cloud relay when no direct path works, or always
on_statusa function that receives progress messages
video_layoutthe 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

MemberWhat it is
disconnect()ends the session; stops the local server; safe to call twice; with Robot.connect(...) as robot: calls it at the end
localTrue when the server runs on this PC
parts["right_arm"], ["left_arm", "right_arm", "head"]; empty until the first state
capabilitieswhat the robot offers: grippers, streams, features
statuslink state and network path
ping_msround trip, measured on the robot's echo of your clock
state_timestampthe robot clock time of the newest state, in seconds
boot_phasethe robot's boot progress; None once it is up
video_layoutthe 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.

CallReturns
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.

CallReturns
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.

CallDoes
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.

Modestereo_cam_left, stereo_cam_rightstereo_cam_left_fovea, stereo_cam_right_fovea
"full", full res (the default)each camera's whole picture, 2304 x 1296, 56 frames per secondwindows your PC cuts out of the full pictures at the gaze
"head", foveateda 1152 x 648 context picture of each camerawindows 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.

CallDoes
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

CallDoes
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.

CallDoes
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

CallReturns
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.