MAKIINASDK

ReferenceTroubleshooting

Troubleshooting

What to do when the console lists nothing, a session does not start, the robot will not move, or the video stays dark or breaks up.

Find the symptom, then work down its list. Most problems come from power, cables, or another program holding an adapter.

The console lists no arm

On this PC says no USB CAN adapter plugged in. The adapter is not plugged in, it has no driver on this Windows PC yet, it does not run candleLight firmware, or, on Linux, your user may not open it. On Windows, an adapter under Other devices in Device Manager needs the steps of Give the adapter its driver on Windows. On Linux, add the udev rule from Install the SDK and plug it in again.

The adapter is listed but no boards answered. The arm is off or its CAN cable is loose. Check the 24 V supply and both ends of the cable, then click Rescan.

On this PC says could not look. Another program holds the adapter: a notebook, a script that did not disconnect, the Actuator Console, or a second Robot Console. Close it. An adapter has one owner at a time.

The row says boards without a unit. The boards do not know which arm they belong to. That happens with drives that were never calibrated as an arm, or after a board was replaced. See Calibration and firmware.

The Actuator Console finds nothing on Linux, or Actuator(...) says no socketcan channels found or Network is down. Both use the Linux CAN interface can0 unless you name the USB path. Start the console with --interface candle and pass interface="candle" in Python, or bring can0 up as in Install the SDK.

Two arms on one bus. A session still tells the arms apart, but Calibrate and Firmware find no arm on that bus and ask you to pick one, and a board of one arm can share its CAN id with a board of the other. Give each arm its own adapter (Two arms on one bus).

A session does not start

An error names makiina.dll (Windows). It says Could not find module '...\makiina.dll' (or one of its dependencies), in Python as a FileNotFoundError and in the console when you press Control. The PC lacks the Microsoft Visual C++ Redistributable (x64), which the SDK's native core needs, so no session starts, neither with an arm on your PC nor with a robot. Install vc_redist.x64.exe and connect again.

connect_local() times out. Read logs/<name>-server.log, where <name> is your PC's name (arm-auto for Arm.connect()), or the file you gave as server_output. The usual causes are an adapter held by another program, a board that stopped answering, or a Robot Console session still open.

AmbiguousChannelError. Several adapters are plugged in and the call did not say which one. Pass channel="<serial>:0" to Actuator or Arm.connect. Robot.connect_local() takes every adapter; adapters=[{"interface": "candle", "channel": "<serial>:0"}] limits it.

connect() to a fleet robot fails to sign in. Check the email and password, or sign in again with the command line tool (Connect from Python has the line for Windows and Linux); a saved sign in expires after a while. With two step sign in on your account, a password alone cannot sign in: sign in once with the command line tool, which asks for the code, and leave the email and password out.

RobotError: this account has no robots, or no robot with that name. The robot is not in an organization you belong to. Add it with the claim code from its card (Add the robot to your account), or ask an owner of its organization to invite you. With several robots, name the one you want: Robot.connect("acme-robot-02").

The robot is offline. The robot is off or not on a network that reaches the internet. See The robot shows OFFLINE.

The robot is in use. Someone else is in a session with it, and the message names them. Only one session runs on a robot at a time. If that session was left behind, End session on the robot's row in the fleet list closes it; the person who opened it and the owners and admins of the robot's organization can do that.

The robot is in maintenance. Calibrate or Firmware is open on it, its cameras are being calibrated, or a software update is running. Sessions start again when that is done.

A robot says ROBOT INCOMPLETE

A part of the robot did not answer when it started. Its row in the fleet list stays Idle, its status reads ROBOT INCOMPLETE with the part under it, for example left arm incomplete: J4 not answering., and the cockpit shows the same in a ROBOT INCOMPLETE banner. A part usually goes missing because its USB CAN adapter dropped off or a board stayed dark. Switch the robot and the arms fully off, reconnect all three USB CAN adapters, switch everything on again, and connect again.

The robot does not move

Nothing happens at all. The session is not armed. In the console, flip ARM on. In code, the first motion command arms the session; after control.stop() you need another one.

One arm moves, the other does not. In the console, that arm's L or R chip gates it off. Click the chip.

It moves, but very slowly. The velocity limit is low. set_max_joint_velocity is in rad/s at the joint; 0.5 to 1.0 is slow and visible, the console's slider goes up to 12.

It stops short or feels weak. The torque fraction is low, or a joint is pushing against something. The current column in Joint states shows which joint is working hardest. The arms also ship with current limits below what their actuators can give (8 A at J1 to J3, 5 A at J4 to J6); Tune the joints raises them.

A joint turns the wrong way. Its direction on the board is wrong, usually after a board was replaced. Run the wizard's Direction step (Calibration and firmware).

RobotError names an unknown joint. The message lists the robot's joints. A single arm has only one side: J01-R to J06-R or J01-L to J06-L.

The robot moves when you do not expect it

It jumps back to an earlier pose. It was moved by hand, and the session still had its old targets. Start a new session after a hand move (Hold, release, and let go).

It is stronger than the torque fraction. Torque on gave the motors their full current limit for the rest of the session, or a current limit was pushed on Tuning. Start a new session and set the limits first.

A joint goes on after STOP or after you let go of the stick. A joint goes on to the target it already has. To stop at once, click Torque off or switch the arm off (Arm the robot, and stop it).

Video and the 3D view

The camera feeds stay dark. The session was opened with receive_cameras=False, or the robot has no head. The gripper cameras alone can be missing while the rest works; they come from a second computer on the robot. One camera that stays dark while the others work missed its start: see A camera shows no picture.

The head pictures are 1152 x 648, not 2304 x 1296. The robot streams foveated. Either you asked for it (video_layout="head", or foveated on the console's Head video switch), or the robot runs older software that has only the foveated mode (Update the robot software), or full res failed to start on the robot and it went back to foveated. sensors.get_video_layout_status() and the console's camera settings say which.

The streams blink. Switching Head video between full res and foveated, applying the camera parameters, and, in the foveated mode, changing the Fovea size restart the robot's camera streams. They come back within seconds. A bitrate change does not restart them.

The picture breaks up. A packet was lost on the network. In full res your PC asks the robot to repair the head pictures, and they are whole again within a few frames. In the foveated mode, and on the gripper cameras, the damage stays until the robot's regular refresh, for up to about 10 s. When it happens often, connect the robot and your PC with cables rather than Wi-Fi, lower the bitrate, and stay in full res: at the robot's starting bitrates both modes send the same.

The 3D view is empty and Go neutral says there is no named pose. The robot's model did not load. The models are in the kit's models folder: unzip the kit again into a new folder, run setup there and connect again. If the view stays empty, write to MAKIINA support at sales@makiina.com.

solve_ik or get_ee_poses raises kinematic twin unavailable. The robot's model did not load, as with the empty 3D view above.

Drives and firmware

get_actuator_parameters() returns an error for a joint. That drive's firmware is older than 2.04, which cannot report its settings. Update it on the Firmware page.

A setting did not change. The drive may have clamped it. Read it back with get_actuator_parameters(keys=[...]) to see the value it runs.

FOC failed after a firmware update. The board has the wrong motor preset. Choose the right one on the Firmware page and press Preset only.

Python environment

No module named 'encodings', No Python at ..., or setup fails after you moved the kit folder. The .venv folder points at a Python that moved or was deleted. Delete .venv and run setup again.

setup FAILED after Could not install packages due to an OSError on Windows. The kit folder's path is too long for Windows. Move the kit to a short folder such as C:\makiina, delete .venv and run setup again.

ModuleNotFoundError: makiina. The script ran with another Python. Run it with .venv\Scripts\python.exe (Windows) or .venv/bin/python (Linux).

Ask for help

Write to sales@makiina.com with your question, the server log (logs/<name>-server.log), the firmware versions from the Firmware page, for a robot the version on its Software page, and the output of this:

Python
from makiina.actuator import list_channels
print(list_channels())