Metadata-Version: 2.4
Name: candlesdk
Version: 1.5.2
Summary: Python package for controlling MD-based actuators
Author-Email: MAB Robotics <support@mabrobotics.pl>
Maintainer-Email: MAB Robotics <support@mabrobotics.pl>
License-Expression: MIT
License-File: LICENSE.txt
License-File: THIRD_PARTY_NOTICES.txt
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Requires-Dist: cmake
Description-Content-Type: text/markdown

# CANdle-SDK

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
[![Latest release](https://img.shields.io/github/v/release/mabrobotics/CANdle-SDK?label=release)](https://github.com/mabrobotics/CANdle-SDK/releases/latest)
[![Docs](https://img.shields.io/badge/docs-MD80%20x%20CANdle-orange)](https://mabrobotics.github.io/MD80-x-CANdle-Documentation/CANdle-SDK/intro.html#candlesdk)

**CANdle-SDK** is the official C++ and Python toolkit from [MAB Robotics](https://www.mabrobotics.pl/) for configuring, testing, and controlling:

- [**MD** motor controllers](https://www.mabrobotics.pl/product-page/md80-motor-controller) — compact brushless servo drives for legged and mobile robots
- [**CANdle** / **CANdle HAT**](https://www.mabrobotics.pl/motion-control/candle-series) — USB/SPI-to-CAN-FD dongles that connect up to 16 devices to a PC or single-board computer
- [**PDS** (Power Distribution System)](https://www.mabrobotics.pl/product-page/pds-power-distribution-system) — modular power management and monitoring for mobile robots

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](docs/candletool.png)
- **mdgui** — a graphical tool for tuning MD motion control gains
![mdgui](docs/mdgui.png)

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](https://mabrobotics.github.io/MD80-x-CANdle-Documentation/CANdle-SDK/intro.html#candlesdk)

---

## 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](#install-candletool--mdgui) |
| Control MD/PDS from Python | [Python quick start](#python-quick-start) |
| Build CANdle-SDK yourself | [Building from source](#building-from-source) |
| Use CANdle-SDK in my own project | [Use CANdle-SDK in your project](#use-candle-sdk-in-your-project) |

---

## Install candletool & mdgui

Prebuilt installers for both apps are published on the [Releases page](https://github.com/mabrobotics/CANdle-SDK/releases/latest) — 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](https://github.com/mabrobotics/CANdle-SDK/releases/latest) and run it.

<details>
<summary>Swap default USB driver manually (only if the installer's automatic driver setup fails)</summary>

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

1. Download and run [Zadig](https://github.com/pbatard/libwdi/releases/download/v1.5.0/zadig-2.8.exe)
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

</details>

### Linux

Download the `.deb` package matching your architecture (x86_64, arm64, or armhf) from [Releases](https://github.com/mabrobotics/CANdle-SDK/releases/latest), then install it:

```bash
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](#building-from-source) directly.

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

```bash
python3 -m venv .venv
source .venv/bin/activate   # on Windows: .venv\Scripts\activate
pip install candlesdk
```

```python
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](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](#get-the-source) instructions below, then, with `candlesdk` installed and your hardware connected, run:

```bash
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](#install-candletool--mdgui) or [Python quick start](#python-quick-start) instead.

### Get the source

```bash
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

```bash
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](#install-candletool--mdgui) above.

### Build

#### Linux

Using the build script:

```bash
./launch/buildForLinux.sh
```

Or build manually:

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

Or using Docker (x86_64 only; see [installing Docker on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)):

```bash
./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:
> ```bash
> cd build
> sudo make install_rules
> ```

#### Windows

Natively, from PowerShell:

```powershell
./launch/buildForWindows.bat
```

Or cross-compile from Linux using Docker:

```bash
./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](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.:

```bash
./build/examples/md_impedance
```

### Building the Python module from source

Most users should just `pip install candlesdk` — see [Python quick start](#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:

```bash
./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:

```bash
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
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](https://mabrobotics.github.io/MD80-x-CANdle-Documentation/CANdle-SDK/intro.html#candlesdk).

## License

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