MAKIINASDK

GuidesRobot and arm controlConnect in Python

Connect from Python

Open a session with the hardware on your PC, a robot in your fleet, or a robot on your LAN, and close it cleanly.

Every script starts by opening a session, and the session hands you a Robot object. There are three ways to open one, depending on where the hardware is. After that the object works the same way, so a script written against an arm on your desk runs unchanged against a robot in another building.

Connect to the hardware on your PC

Python
from makiina.robot import Robot

robot = Robot.connect_local()
print(robot.parts)                  # ["right_arm"]
print(robot.model.joint_names())    # ["J01-R", "J02-R", ..., "J06-R"]

connect_local() starts a robot server on your PC. The server looks at every USB CAN adapter, asks each board which arm and joint it is, builds the robot from the answers and starts streaming. The call returns once the first joint state has arrived, usually in a few seconds. robot.local is True, and robot.disconnect() stops the server again.

Only one program can own an adapter. If the Robot Console has a session with the arm, click Exit there first.

To use only some of your adapters, name them. The channel is the adapter's serial number, which the console shows on the arm's row:

Python
robot = Robot.connect_local(adapters=[{"interface": "candle", "channel": "207137C04845500F2:0"}])

If the connection does not come up within 30 seconds, the error says so and the server's log is in logs/<name>-server.log inside the kit, where <name> is your PC's name.

Connect to a robot in your fleet

Python
from makiina.robot import Robot

robot = Robot.connect("acme-robot-02")

connect() signs in to your MAKIINA account, offers a session to the robot, and returns when the robot is live and its state is flowing. The cloud only introduces your PC and the robot to each other. After that, control and video go directly between them: over the LAN if you share one (robot.status["path"] says lan), otherwise through a hole punched in both firewalls (p2p), and through MAKIINA's relay (relay) only when no direct route exists. One operator drives a robot at a time: a second session is refused while one runs.

Your credentials come from, in this order:

  1. email= and password= arguments to connect(),
  2. the MAKIINA_EMAIL and MAKIINA_PASSWORD environment variables (the arguments and the variables work only for an account without two step sign in),
  3. the sign in saved by the command line tool or the Robot Console:
Shell
.venv\Scripts\python.exe -m makiina.cloud.makiina_cli login you@example.com     # Windows
.venv/bin/python -m makiina.cloud.makiina_cli login you@example.com             # Linux

The tool asks for your password, and for your two step code when two step sign in is on. It keeps only the sign in tokens, in ~/.makiina/token.json, readable by you only; with the keyring package installed they go to your system's keyring instead. makiina_cli robots lists your robots and makiina_cli logout ends the sign in. On a desk computer the saved sign in is the better choice; the environment variables suit scripts on a server.

Leave the robot name out if your account has one robot. Pass receive_cameras=False when you only need control and state; the session then skips the video channels. A robot with a head streams its cameras in full resolution unless you ask for the foveated mode with video_layout="head" (See what the robot sees).

List your robots without connecting

Python
from makiina.cloud import Fleet

fleet = Fleet.login()
for r in fleet.robots():
    print(r["name"], r["online"], r["status"], r["active_session"])

robots() makes one request and returns each robot's name, whether it is online, its status (idle, in a session, in maintenance), who holds a session, when it was last seen, and what hardware its last discovery found.

Connect to a robot on your LAN without the cloud

For a bench with no internet or no account, start the robot's side by hand on its head Pi, over SSH, pointed at your PC, then listen for it:

Shell
bash ~/repos/core/server/run_client.sh 192.168.1.20   # on the head Pi: your PC's address
Python
robot = Robot.connect_direct(listen_port=8766)

This gives you control and state only. The camera streams need the multiplexer that the robot's cloud agent manages, so sensors.get_camera_frames() stays empty in a direct session. For latency there is no reason to choose it: connect() already runs directly over the LAN when it can.

Check what you are connected to

Python
robot.parts             # ["left_arm", "right_arm", "head"]
robot.capabilities      # grippers, streams and features the robot offers
robot.ping_ms           # round trip, measured on the robot's echo
robot.status            # link state and network path

A single arm, an arm with a gripper camera, and the full robot all use the same API; what differs is which parts and streams they report.

Close the session

Python
robot.control.stop()        # stop commanding: the robot holds its pose
robot.safety.torque_off()   # optional: release the motors (the arm sags)
robot.disconnect()

disconnect() closes the link and, for a session on your PC, stops the robot server. It does not change what the motors do, so turn the torque off first if the robot should go limp. If your script crashes without disconnecting, each joint goes on to its last target and holds there. After 30 seconds without commands the robot server shuts down and the session ends, and the arm still holds (What happens if your script dies).

Several arms, several sessions

Each call opens its own session with its own limits and its own server. To run two arms from one PC as two independent sessions, give each one its adapter, and the second one its own port and its own log file:

Python
right = Robot.connect_local(adapters=[{"interface": "candle", "channel": "207137C04845500F2:0"}])
left = Robot.connect_local(adapters=[{"interface": "candle", "channel": "2081367A394550182:0"}],
                           port=8771, server_output="left-server.log")

Without server_output both servers write logs/<name>-server.log, and the second one empties the first one's log as it starts.

Run two arms on one PC also shows how to drive both as one robot.

The older entry point

Scripts written for earlier versions use makiina.arm.Arm.connect(). It still works and returns the same kind of object as Robot.connect_local(), but not with your settings:

Python
import makiina.arm

arm = makiina.arm.Arm.connect()             # settings folder arm-auto

With no arguments it reads one calibrated arm off one adapter. On Linux it looks on can0 unless you pass interface="candle". It then runs on robot-calibrations/arm-auto/, not on your PC's folder, and writes that folder again from the defaults at every call. So the limits and gains you keep (Keep settings for good) do not apply, an edit in arm-auto is gone at the next call, and the log is logs/arm-auto-server.log. For your own settings, use Robot.connect_local().