Install the SDK

There are two ways to get the SDK. The kit is a folder with everything in it, Python included, and is the right choice for any machine that drives MAKIINA hardware. A checkout of the repository is for working on the SDK itself. Both end the same way: a .venv folder at the top, the Robot Console one double-click away, and import makiina working in any script.

Set up the kit

The kit comes as one zip per platform: makiina-kit-windows.zip, makiina-kit-linux-x64.zip or makiina-kit-linux-arm64.zip, about 100 MB each.

1. Unzip it anywhere you like.
2. Run setup.bat on Windows or ./setup.sh on Linux. It creates .venv from the Python runtime in the box and installs the SDK into it, offline, in about ten seconds.
3. Start the console with RobotConsole.bat or ./robot_console.sh. It runs setup for you if .venv is missing, then opens http://127.0.0.1:8726 in your browser.

If you move the folder later, run setup again. A Python environment remembers where it was created, and setup is how it learns the new place.

From here on the kit is an ordinary Python project. Run scripts with its Python:

.venv\Scripts\python.exe my_script.py           # Windows
.venv/bin/python my_script.py                   # Linux

To work in notebooks, open the kit folder in VS Code or Cursor and pick the .venv kernel; the quickstart notebooks are in examples/. Notebook.bat (or ./notebook.sh) opens the arm quickstart in the browser instead; the first time it installs Jupyter into .venv, which needs internet once.

The SDK is installed in editable mode: import makiina.arm is the arm/ folder inside the kit, so you can read every part of it and change it.

What is in the kit

Linux

Your user needs permission to open the USB CAN adapter. Add a udev rule and plug the adapter in again:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1d50", MODE="0666"' | sudo tee /etc/udev/rules.d/99-candle.rules

The kit includes a fast CAN path for your CPU. It needs passwordless sudo for modprobe, ip and chrt; without it a Python daemon takes over, and without any adapter the SDK falls back to plain python-can. Everything works either way, only latency differs. If the zip lost the executable bits, chmod +x *.sh.

Use a candleLight adapter

The SDK talks to MAKIINA drives through USB CAN adapters running candleLight firmware. The adapters that come with MAKIINA hardware already do. If you use your own, make sure it runs candleLight.

The adapter's serial number is also its name in the SDK: interface="candle", channel="<serial>:0".

Set up a checkout

Use a checkout when you work on the SDK itself. You need Git with Git LFS (the robot meshes are LFS files; install it before cloning) and, on Windows, the Visual Studio 2022 C++ build tools for the native core.

On Windows, setup.bat at the root does the rest: it installs uv if needed, pulls the LFS files, creates .venv with Python 3.12, installs the repository into it, and builds the native core. Run it again after you pull to rebuild.

On Linux and macOS:

uv venv .venv --python 3.12
uv pip install -e ".[dev,arm,webui]"
./native/build.sh

The native core adds end effector kinematics and camera decoding. Without it the console still runs and joint control works, but camera streams and the IK features stay off.

Run everything with the checkout's own Python, .venv\Scripts\python.exe or .venv/bin/python. A bare python is usually some other interpreter that has never heard of makiina.

Optional parts

The package keeps its dependencies small (numpy and requests) and adds the rest by extra:

Check the installation

With the adapter plugged in:

from makiina.actuator import list_channels

print(list_channels())      # one entry per USB CAN adapter

An empty list with an adapter plugged in means the adapter does not run candleLight firmware, another program holds it, or on Linux the udev rule is missing.

To try the console with no hardware at all, start it in demo mode:

RobotConsole.bat --demo

Seven simulated drives appear under On this PC. The maintenance tools work on them; a Control session needs real hardware.