Connect from Python

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

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:

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.

Connect to a robot in your fleet

from makiina.robot import Robot

robot = Robot.connect("head-10")

connect() signs in to MAKIINA Cloud, 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, otherwise through a hole punched in both firewalls, and through the cloud's relay only if neither works.

Your credentials come from, in this order:

1. email= and password= arguments to connect(),
2. the MAKIINA_EMAIL and MAKIINA_PASSWORD environment variables,
3. the login saved by the command line tool:

.venv\Scripts\python.exe -m makiina.cloud.makiina_cli login you@example.com

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.

List your robots without connecting

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, pointed at your PC, then listen for it:

bash server/run_client.sh 192.168.1.20        # on the robot, your PC's address

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

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

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, the robot stops by itself after 30 seconds without commands.

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 another port:

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

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:

import makiina.arm

arm = makiina.arm.Arm.connect()             # same as Robot.connect_local()