Troubleshooting

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. The adapter is not plugged in, it does not run candleLight firmware, or, on Linux, your user may not open it. 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.

The row says the adapter is in use. Another program holds it: a notebook, a script that did not disconnect, or a second 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.

Two arms on one bus. The console sees two of every joint and refuses to build a robot. Give each arm its own adapter.

A session does not start

connect_local() times out. Read logs/<name>-server.log. 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 adapters=[{"interface": "candle", "channel": "<serial>:0"}].

connect() to a fleet robot fails to sign in. Check the email and password, or sign in again with python -m makiina.cloud.makiina_cli login you@example.com; a saved login expires after a while.

The robot is in a session. Someone else is connected. If that session was left behind, End session on the robot's row in the fleet list closes it.

The robot is in maintenance. Calibrate or Firmware is open on it. Sessions start again when that tool closes.

A robot says Robot incomplete

The fleet list and the cockpit show Robot incomplete when a part of the robot did not answer when it started, for example left arm incomplete: J4 not answering. 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.

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.

Video and the 3D view

The camera feeds stay dark. The session was opened with receive_cameras=False, the robot has no head, or, in a checkout, the native core is not built (native/build.ps1 or native/build.sh). The gripper cameras alone can be missing while the rest works; they come from a second computer on the robot.

The streams blink. Changing the camera settings or the fovea mode restarts the robot's camera pipelines. They come back within seconds.

The 3D view is empty and Go neutral says there is no named pose. The robot's model did not load. In a checkout, the meshes arrive as Git LFS files: run git lfs install and git lfs pull.

solve_ik or get_ee_poses raises. The kinematic twin needs the native core; see the dark feeds 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' or No Python at .... The .venv folder points at a Python that moved or was deleted. 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

Send the server log (logs/<name>-server.log), the firmware versions from the Firmware page, and the output of this with your question:

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