MAKIINASDK

Get startedInstall

Install the SDK

Download the kit for your PC from your MAKIINA account, unzip it and run setup, and give your USB CAN adapter its driver on Windows.

The SDK comes as a kit: one folder with Python and every package the SDK uses. At the end of this page the kit has a .venv folder at the top, the Actuator Console and Robot Console are ready to open, and import makiina works in any script.

With new hardware, pick your system in Choose your system as well. An actuator or single arm kit needs the SDK from its first step. A dual arm system needs it for its first session, after you have cabled the robot and added it to your account; installing the kit earlier does no harm.

Download the kit

The kit comes as one zip per platform, named after its version and the platform: makiina-sdk-<version>-windows-x64.zip, makiina-sdk-<version>-linux-x64.zip or makiina-sdk-<version>-linux-arm64.zip. Each is about 100 MB. It runs on:

  • Windows 10 or 11, x64.
  • Linux x64 with glibc 2.34 or newer, such as Ubuntu 22.04 or Debian 12 and later.
  • Linux ARM64 with glibc 2.28 or newer, such as Ubuntu 20.04, Debian 10, Raspberry Pi OS (64 bit) or a Jetson with JetPack 5 and later.

ldd --version prints the glibc version of a Linux machine. On an older one, setup stops because a part of the kit has no build for it.

You download it from your MAKIINA account:

  1. Sign in at cloud.makiina.com/account. Without an account, choose CREATE AN ACCOUNT there. Then open the link in the mail MAKIINA Cloud sends you and press CONFIRM MY EMAIL ADDRESS on the page it opens: opening the link alone does not confirm the address. You need the confirmed address later, to add a robot to your account.
  2. Open SDK in the menu at the top.
  3. Under Download the SDK, press GET DOWNLOAD LINK on the row of your platform, then DOWNLOAD NOW. Each row also shows the version, the size and the SHA256 checksum of its zip.

The link works for 24 hours, in a browser or with curl, for anyone who has it. To fetch the kit on another computer, such as a Linux machine without a desktop, press COPY LINK and use it there:

Shell
curl -f -o makiina-sdk.zip "<the link>"

With -f, curl saves nothing when the link fails: it ends with The requested URL returned error: 410 for a link older than 24 hours, or 404 for a link that is not valid.

The public download page lists the kits too. Their rows say Sign in to download and lead to the same SDK page.

Set up the kit

  1. Unzip it into a new folder with a short path, such as C:\makiina on Windows: right-click the zip, choose Extract All and type that folder in place of the one it offers. Windows allows 260 characters for a file's path, and some files setup installs have long names, so a kit deep in a folder such as a Documents folder on OneDrive can make setup fail. The zip holds one folder, such as makiina-kit-windows: that is the kit folder.
  2. Run setup: double-click setup.bat on Windows, or run ./setup.sh on Linux. It creates .venv from the Python runtime in the kit and installs the SDK and everything it needs into it, offline, in about a minute. Nothing is installed outside the kit folder. It ends with setup done: .venv is ready; a double-clicked setup.bat keeps its window open until you press a key.
  3. Start the console: double-click RobotConsole.bat, or run ./robot_console.sh. It runs setup for you if .venv is missing, then opens http://127.0.0.1:8726 in your browser. Keep its window open while you use the console: closing the window stops the console.

On Windows, the SDK's native core needs the Microsoft Visual C++ Redistributable (x64), which most PCs have already. Without it, setup and the console's pages work, but no session starts, with an arm on your PC or with a robot: Control in the console, Robot.connect() and Robot.connect_local() stop with an error that names makiina.dll. Microsoft's installer for it is vc_redist.x64.exe.

.venv works only in the place where setup created it. If you move or rename the kit folder, delete its .venv folder, then run setup again (or start the console, which runs setup when .venv is missing).

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

Shell
.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. Notebook.bat (or ./notebook.sh) opens the arm quickstart notebook in the browser instead; the first time it installs Jupyter into .venv, which needs internet once. The quickstart notebooks in examples/ do some things these pages do not: read the list under What is in the kit before you run one with hardware.

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

Folder or fileWhat it is
RobotConsole.bat, robot_console.shstart the Robot Console
ActuatorConsole.bat, actuator_console.shstart the Actuator Console, for single actuators on a USB CAN adapter
setup.bat, setup.shcreate .venv and install the SDK into it
actuator/, arm/, robot/, cloud/, console/, server/ and the restthe makiina package, one folder per part
KIT_README.mdnotes on the kit (see below)
examples/quickstart notebooks for an actuator, an arm and a robot (read the list below before you run them), and robot_getting_started.py, a first session with a robot that never moves it
models/the robot models the 3D twin uses
docs/the SDK's own notes in plain markdown: the robot, the actuator, the API, the protocol and more (see below)
robot-calibrations/created the first time an arm connects to this PC: one folder named after your PC with the settings of the arms you drive here (Keep settings for good). Arm.connect() with no name uses a folder of its own, arm-auto, and writes it again at every call. A dual arm system keeps its settings on the robot
runtime/ (Windows) or runtime.tar.gz (Linux), wheels/what setup builds .venv from; on Linux setup unpacks runtime.tar.gz into runtime/ first. Leave them alone
LICENSE, LICENSE-MAKIINA.mdthe MAKIINA License 1.0, the license of MAKIINA's own files in the kit
THIRD-PARTY.txt, licenses/, sources/the third party parts of the kit, their licenses and the source of the LGPL ones

KIT_README.md, the notes in docs/ and the notebooks in examples/ come with the SDK's source code, and some of their steps are MAKIINA's own factory steps. Where they differ from these pages, follow these pages:

  • An arm from MAKIINA arrives calibrated and with its firmware. Skip their first steps for a new arm (firmware, then calibrate and zero). MAKIINA also makes a dual arm system's SD cards and calibrates its cameras: docs/sd-card.md is a factory step.
  • They call the zero pose "the arm stretched straight out". It is the folded pose of Put the unit at its zero pose.
  • The arm quickstart notebook sets a torque fraction of 0.8 and a speed limit of 150 rad/s, whatever its comments say. Run the two lines of Set the limits first in place of that cell; with them its 0.75 s moves to neutral and to zero run at no more than 1.0 rad/s.
  • Its free mode cells call torque_off() and then torque_on(). After its motion cells, torque_on() drives the arm back to its old targets at the full current limit. After a hand move, start a new session instead (Hold, release, and let go). Its max_current_small reaches J4 to J6, never the gripper.
  • KIT_README.md connects with makiina.arm.Arm.connect(). Use Robot.connect_local() as these pages do: with no name, Arm.connect() ignores the settings you keep (The older entry point).
  • The robot quickstart notebook connects to head-10, a robot of MAKIINA's: put your robot's name there. The kit comes from your account, not from the download page the notebook names. The dataset converter and the LeRobot integration its recording cells mention are not in the kit (Record demonstrations).
  • A moved kit folder needs its .venv deleted before setup runs again (Set up the kit).
  • Linux needs the versions under Download the kit.
  • A new account confirms its email address with CONFIRM MY EMAIL ADDRESS on the page the mail's link opens.
  • The USB CAN adapters from MAKIINA come with their firmware, and the tool the notes name for an adapter is not in the kit. On Windows, give the adapter its driver with the steps below.
  • Two arms on one bus do form one robot in a session; give each arm its own adapter anyway, for the reasons in Run two arms.
  • A dual arm system's updates and SSH keys start from its pages in the Robot Console on your PC (Update the software, Add your SSH keys). Its card carries no device code, the Software page has no confirm button for an older version yet, and the SSH switch is called Remove the MAKIINA keys when I add mine.
  • The VR app downloads from your account's SDK page, like the kit.

Give the adapter its driver on Windows

Windows does not install a driver for the USB CAN adapter by itself, so On this PC says no USB CAN adapter plugged in until you give it one. Do it once for each adapter on each Windows PC that drives it; Windows remembers it for that adapter. You need an administrator account on the PC.

  1. Plug the adapter in. Device Manager lists it under Other devices as canable2 gs_usb, with a yellow mark.

  2. Register the adapter for the SDK. Right-click Start and open Terminal (Admin) (Windows PowerShell (Admin) on Windows 10). Paste this line and press Enter. It prints a few lines and changes nothing but the adapter's own settings:

    PowerShell
    Get-PnpDevice -PresentOnly | Where-Object InstanceId -like 'USB\VID_1D50&PID_606F&MI_00\*' | ForEach-Object { New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Enum\$($_.InstanceId)\Device Parameters" -Name DeviceInterfaceGUIDs -PropertyType MultiString -Value '{c15b4308-04d3-11e6-b3ea-6057189e6443}' -Force }
  3. Give it the WinUSB driver. In Device Manager, right-click canable2 gs_usb and choose Update driver, then Browse my computer for drivers, then Let me pick from a list of available drivers on my computer. Choose Universal Serial Bus devices and press Next, choose WinUsb Device in both lists and press Next, then Yes. The driver comes with Windows.

  4. Unplug the adapter and plug it in again. It now shows under Universal Serial Bus devices as WinUsb Device, and Rescan on On this PC finds it.

With several adapters, plug them all in before step 2: the line covers every adapter that is plugged in. Step 3 is once for each of them.

Linux

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

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

The Robot Console and Robot.connect_local() open the adapter through this USB path. The Actuator Console, Actuator(...) and Arm.connect() use the Linux CAN interface (socketcan) unless you name the USB path, so for them either pass --interface candle to the Actuator Console and interface="candle" in Python, or bring the adapter up as can0 at 1 Mbit/s each time you plug it in:

Shell
sudo ip link set can0 up type can bitrate 1000000

A session can also use a faster CAN path from the kit: a small native program at real-time priority. It needs passwordless sudo, and on ARM64 glibc 2.34 or newer. Without passwordless sudo the session uses plain python-can. With it, on ARM64 with an older glibc, a session start waits about 5 s for the program, then uses 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. On Windows every adapter also needs its driver, once on each PC (above).

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

Check the installation

With an arm or an actuator plugged in through its USB CAN adapter:

Python
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 has no driver on this Windows PC yet, it 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 from a terminal in the kit folder. On Windows, click the address bar of the kit folder in File Explorer, type powershell and press Enter:

Shell
.\RobotConsole.bat --demo         # Windows
./robot_console.sh --demo         # Linux

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

A dual arm system plugs into your network, not into your PC, so the check for it comes later: the robot shows up under Fleet once it is in your account. From Python, sign in once and run the first session example of the kit, which connects, prints what it finds and never moves the robot:

Shell
.venv\Scripts\python.exe -m makiina.cloud.makiina_cli login you@example.com     # Windows
.venv\Scripts\python.exe examples\robot_getting_started.py                      # Windows
.venv/bin/python -m makiina.cloud.makiina_cli login you@example.com             # Linux
.venv/bin/python examples/robot_getting_started.py                              # Linux

Get the VR app

The MAKIINA VR app for Meta Quest is on the same SDK page of your account, under Download the VR app, as MAKIINA Teleop for Meta Quest. Press GET DOWNLOAD LINK there: the link to its APK file works for 24 hours.

For a Windows PC, the same page has MAKIINA Teleop for Windows: unzip it into a folder and run MAKIINA Teleop.exe. It works with any OpenXR headset, for example a Meta Quest over Quest Link, and needs no developer mode.

Put the headset in developer mode, once. Meta offers developer mode only to a Meta account that belongs to a developer team on the Meta Horizon Developer Dashboard and is verified there with a mobile number or a payment method. Then install the APK with Meta Quest Developer Hub, or with adb:

Shell
adb install -r <the APK file>

In the headset, sign in with the same account. To sign in with a code instead, press SIGN IN WITH A CODE: open cloud.makiina.com/account/device on your phone or PC, signed in, enter the code the app shows, press CONTINUE, then APPROVE. Use the VR app has every step.

Go on with your system

Pick your system in Choose your system and follow its path from the box to the first move.