Skip to main content

CANdle-SDK

License: MIT Latest release Docs

CANdle-SDK is the official C++ and Python toolkit from MAB Robotics for configuring, testing, and controlling:

The SDK includes two ready-to-use apps for working with your hardware without writing any code:

  • candletool — a command-line tool for configuring, calibrating, and diagnosing devices candletool
  • mdgui — a graphical tool for tuning MD motion control gains mdgui

It also provides C++ and Python libraries so you can build your own applications on top of the same drivers.

📖 Full documentation: MD80 x CANdle Documentation


Getting started

Pick the path that matches what you want to do:

I want to... Go to
Configure and test my hardware, no coding required Install candletool & mdgui
Control MD/PDS from Python Python quick start
Build CANdle-SDK yourself Building from source
Use CANdle-SDK in my own project Use CANdle-SDK in your project

Install candletool & mdgui

Prebuilt installers for both apps are published on the Releases page — no build tools or source checkout required.

Windows

Download the latest candletool-<version>-Windows-<arch>.exe and/or mdgui-<version>-Windows-<arch>.exe installer from Releases and run it.

Swap default USB driver manually (only if the installer's automatic driver setup fails)

Install the WinUSB driver for CANdle (one-time setup per PC):

  1. Download and run Zadig
  2. Options -> List All Devices
  3. Select MD USB-TO-CAN from the dropdown menu
  4. Change the driver type to libusb-win32
  5. Click Replace Driver and wait for it to finish

Linux

Download the .deb package matching your architecture (x86_64, arm64, or armhf) from Releases, then install it:

sudo apt install ./candletool_<version>_<arch>.deb
sudo apt install ./mdgui_<version>_<arch>.deb

Once installed, run candletool --help to get started, or launch mdgui from your applications menu.


Python quick start

The Python bindings are published on PyPI as candlesdk — no compiler or source checkout needed.

Performance note: the Python bindings wrap the C++ library and carry some overhead, so they don't match its performance. For high-frequency control loops or other performance-critical applications, use the C++ library directly.

On some systems (e.g. recent Debian/Ubuntu) pip refuses to install system-wide, so installing into a virtual environment may be required:

python3 -m venv .venv
source .venv/bin/activate   # on Windows: .venv\Scripts\activate
pip install candlesdk
import pyCandle as pc

candle = pc.attachCandle(pc.CANdleDatarate_E.CAN_DATARATE_1M, pc.busTypes_t.USB)
md_id = pc.discoverMDs(candle)[0]
md = pc.MD(md_id, candle)

if md.init() == pc.MD_Error_t.OK:
    md.zero()
    md.setMotionMode(pc.MotionMode_t.IMPEDANCE)
    md.enable()
    # ... your control loop ...
    md.disable()

Running the Python examples

Ready-to-run scripts covering both MD and PDS control are in examples/py:

Script Description
md_impedance.py Finds the first MD on the bus and moves it 5 rad from its current position in impedance mode, printing position and torque.
md_register_access.py Reads and writes MD registers by name (integer and float), using the type-specific readRegister* / writeRegister* functions.
md_status.py Reads all MD status registers and decodes them into named flags with decodeMDStatus, like candletool md info.
pds_basic.py Discovers a PDS, lists its modules and reads the status of power stages, brake resistors and isolated converters.

Grab the folder (or the whole repo) with the git clone instructions below, then, with candlesdk installed and your hardware connected, run:

python3 examples/py/md_impedance.py

Building from source

This section is for developers building the C++ library, candletool, or mdgui themselves — e.g. to modify the SDK or to target a platform without prebuilt packages. If you just want to configure hardware or write Python code, see Install candletool & mdgui or Python quick start instead.

Get the source

git clone https://github.com/mabrobotics/CANdle-SDK.git
cd CANdle-SDK
git submodule update --init --recursive

Note: a zipped download of the repository will not work, since it relies on git submodules.

Prerequisites

Linux

sudo apt install build-essential git cmake libusb-1.0-0-dev

Windows

Building requires w64devkit, which can be downloaded and configured automatically by the build script below.

You'll also need the WinUSB driver for CANdle — see the driver setup steps in Install candletool & mdgui above.

Build

Linux

Using the build script:

./launch/buildForLinux.sh

Or build manually:

mkdir build && cd build
cmake ..
make -j6

Or using Docker (x86_64 only; see installing Docker on Ubuntu):

./launch/runDockerForLinux86-64.sh

Note: you'll also need to install udev rules so CANdle can be used over libUSB from userspace (no sudo required afterwards). This is a one-time setup per PC, and may require a restart to take effect:

cd build
sudo make install_rules

Windows

Natively, from PowerShell:

./launch/buildForWindows.bat

Or cross-compile from Linux using Docker:

./launch/runDockerForWindows.sh

Both produce a build/ directory containing the candlelib library and, by default, the candletool, mdgui, and example binaries.

C++ examples

Example programs demonstrating MD and PDS usage are in examples/cpp:

Example Description
app_template Starting point for your own application: discovers all MDs and PDSes and periodically prints MD position/velocity and PDS bus voltage.
md_impedance Finds the first MD on the bus and moves it 5 rad from its current position in impedance mode.
md_register_access Reads and writes MD registers, including several registers in one request.
md_status Reads all MD status registers and prints the decoded flags, like candletool md info.
mdco_speed_loop Runs an MD over CANopen in Cyclic Sync Velocity mode for 10 s, printing its position.
pds_ping_and_status Discovers a PDS and reads control board status, bus voltage, shutdown time, battery levels and connected modules.
pds_power_stage Configures and enables a PDS power stage (OCD, temperature limit) with a bound brake resistor and reads its status.
pds_braking_resistor Configures a PDS brake resistor's temperature limit and reads its status and temperature.
pds_isolated_converter Configures and enables a PDS isolated converter (OCD, temperature limit) and reads its output voltage and current.

The PDS examples (except pds_ping_and_status) expect a PDS with CAN ID 100 and modules in the sockets defined at the top of each file. Each file builds into its own executable as part of the normal build above; run one directly from the build output, e.g.:

./build/examples/md_impedance

Building the Python module from source

Most users should just pip install candlesdk — see Python quick start. Build it yourself only if you need an unreleased change or a platform not covered by the published wheels.

Dependencies are listed inside pyproject.toml. To build a wheel for the current system, run python -m build inside the repository with your preferred Python binary.

To build wheels for multiple libc/Python version combinations at once, use:

./launch/pythonBuildWheel.sh

Then install the wheel matching your platform, e.g. python -m pip install ./dist/candlesdk-1.5.0-cp310-cp310-linux_x86_64.whl for CPython 3.10, glibc, x86-64.


Use CANdle-SDK in your project

The recommended way to consume CANdle-SDK from another C++ project is as a git submodule:

git submodule add git@github.com:mabrobotics/CANdle-SDK.git
git submodule update --init --recursive

Then link against the candle target (built from candlelib) in your own CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)

project(myCandleProject)

add_subdirectory(CANdle-SDK) # added as a submodule
add_executable(myCandleProject main.cpp)
target_link_libraries(myCandleProject candle)

Documentation

For more information check out our documentation page here.

License

CANdle-SDK is released under the MIT License. Bundled third-party components are listed with their licenses in THIRD_PARTY_NOTICES.txt.

Metadata

Release files for candlesdk 1.5.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for candlesdk 1.5.2
File Size Uploaded Provenance Actions
candlesdk-1.5.2.tar.gz 99.8 MB Without provenance Details for candlesdk-1.5.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for candlesdk 1.5.2
File Actions
candlesdk-1.5.2-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details for candlesdk-1.5.2-cp314-cp314-win_amd64.whl
candlesdk-1.5.2-cp314-cp314-manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.28+ x86-64 Details for candlesdk-1.5.2-cp314-cp314-manylinux_2_28_x86_64.whl
candlesdk-1.5.2-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for candlesdk-1.5.2-cp313-cp313-win_amd64.whl
candlesdk-1.5.2-cp313-cp313-manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.28+ x86-64 Details for candlesdk-1.5.2-cp313-cp313-manylinux_2_28_x86_64.whl
candlesdk-1.5.2-cp312-cp312-manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64 Details for candlesdk-1.5.2-cp312-cp312-manylinux_2_28_x86_64.whl
candlesdk-1.5.2-cp311-cp311-manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64 Details for candlesdk-1.5.2-cp311-cp311-manylinux_2_28_x86_64.whl
candlesdk-1.5.2-cp310-cp310-manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64 Details for candlesdk-1.5.2-cp310-cp310-manylinux_2_28_x86_64.whl

Total release size: 108.3 MB

Release files / candlesdk-1.5.2.tar.gz

Download URL candlesdk-1.5.2.tar.gz
Size 99.8 MB
Tags Source
SHA-256 checksum
How to use checksums
c97a0d7a734f06ed7542344b57e483365bb3792d8d46be614b2660c474c62a7e
BLAKE2b-256 checksum
How to use checksums
fde4adfddde07d382a421ae788e28bdea0c6eee78ec875f90bb681d292273527
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / candlesdk-1.5.2-cp314-cp314-win_amd64.whl

Download URL candlesdk-1.5.2-cp314-cp314-win_amd64.whl
Size 774.3 kB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
e9ada3e8ba361c6d2f5ea34795e8f701e133acb1376160d7be615493520b45b1
BLAKE2b-256 checksum
How to use checksums
cb3bcc41792da8340157198cc47e79c3800e1e0d1134706f08b6472afcee0765
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / candlesdk-1.5.2-cp314-cp314-manylinux_2_28_x86_64.whl

Download URL candlesdk-1.5.2-cp314-cp314-manylinux_2_28_x86_64.whl
Size 1.4 MB
Tags CPython 3.14 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
56d897693f36d07453b0bee4f65333286c51d301ac06cd0eef74788c3c4b64ad
BLAKE2b-256 checksum
How to use checksums
29cb6df433c6b8f064e1f8ef8bc8d87567f127ef092f02c0355169d981fa924a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / candlesdk-1.5.2-cp313-cp313-win_amd64.whl

Download URL candlesdk-1.5.2-cp313-cp313-win_amd64.whl
Size 749.4 kB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
66d1f01efea9f23163c5dda77c8080c3cdfe5a580a0ecb5bc5c3b0baedb79232
BLAKE2b-256 checksum
How to use checksums
5652e720779103f1eb13201f9c6b04a2d5a91833ebd4b382166e4b624b08fc05
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / candlesdk-1.5.2-cp313-cp313-manylinux_2_28_x86_64.whl

Download URL candlesdk-1.5.2-cp313-cp313-manylinux_2_28_x86_64.whl
Size 1.4 MB
Tags CPython 3.13 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
ef86880f3cdee8d0666cae34d2400f1726026e36d16d83418cfb47d4c04bc9c9
BLAKE2b-256 checksum
How to use checksums
a618cf3ed30fee9fbba271a4c647c493ef2b9fc60fd75e68fff8f3000d284dc2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / candlesdk-1.5.2-cp312-cp312-manylinux_2_28_x86_64.whl

Download URL candlesdk-1.5.2-cp312-cp312-manylinux_2_28_x86_64.whl
Size 1.4 MB
Tags CPython 3.12 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
a78f5ce1722b1ebf83b58ca264fc3c3264431db3c3c32d7bf7be4c0ab483bcc4
BLAKE2b-256 checksum
How to use checksums
b0b3ab67c7c7a68b845ec87150fc0d525f380e169f3f7ce0249d8672a470c063
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / candlesdk-1.5.2-cp311-cp311-manylinux_2_28_x86_64.whl

Download URL candlesdk-1.5.2-cp311-cp311-manylinux_2_28_x86_64.whl
Size 1.4 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
0e7dcff91f364d8e04c5b686c537380216ce5f832a8122f1276b0711a20fd82a
BLAKE2b-256 checksum
How to use checksums
ff5f2d4bc8086452d7c2233b5639d71672ce81c125ac82b8dfac5994a8efdc13
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Release files / candlesdk-1.5.2-cp310-cp310-manylinux_2_28_x86_64.whl

Download URL candlesdk-1.5.2-cp310-cp310-manylinux_2_28_x86_64.whl
Size 1.4 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
e832c9410c5dc802593b964727cc3d7a77f4bc49313626df495f481dfcdd9d88
BLAKE2b-256 checksum
How to use checksums
811b5813e8efa49c35ee77ad43a5cabbee829556669b6c1a53ff88b19c7b51c4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

Security for candlesdk 1.5.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page