An open-source 12-DoF quadruped robot that I design and build on my own.
How it works · Examples · Discord · Contributing
To build the robot, start with the Bill of Materials and the specifications on the Chroma website.
Requires Python 3.12 and uv (or pip).
git clone https://github.com/Mowibox/chromapi
cd chromapi
uv sync --all-extras # or: pip install -e ".[all]"The audio extra enables sounds on the robot and the sim extra installs MuJoCo for simulation.
from chromapi.chromapi import Chromapi
with Chromapi(backend="mujoco", launch_viewer=True) as robot:
robot.wake_up()
robot.walk_distance(0.3) # [m]
robot.rest()More in examples/: dance.py, walk.py and gamepad.py. Each runs on the robot, or in MuJoCo with --sim.
On the Raspberry Pi, once the motherboard firmware is flashed:
chromapi motors setup # interactive: set each servo's ID, one servo at a time
chromapi calibrate servos --all # find each servo's center from its mechanical stops (lift the robot first)
chromapi calibrate imu # measure the IMU board tilt, robot still on a level floor
chromapi health # what is wrong with the robot, and what to do about it
chromapi version # SDK, firmware and bridge protocol versionschromapi --help lists every command (python -m chromapi works too).
The same code then runs on the robot with Chromapi(backend="hardware"), which talks to the motherboard over UART communication.
| Resource | Description | Location | Status |
|---|---|---|---|
| 📋 Bill of Materials | Complete hardware, electronics, and 3D printed parts list to build Chromapi from scratch. | Chroma Website | Available |
| 💻 Software API | Python control framework, hardware interfaces, and kinematic solvers. | /src/chromapi |
Work in Progress |
| 📐 CAD Model | 3D Mechanical design and robot assembly workspace. | Onshape Document | Available |
| 📖 Documentation | Specifications, design notes and communication protocol. | Chroma Website | Available |
| 🛠️ Hardware Utilities | chromapi command: health check, servo setup and calibration tools. |
/src/chromapi/utils |
Available |
| 🤖 Simulation Models | URDF and MJCF models for MuJoCo simulation. | /src/chromapi/model |
Available |
| ⚡ Electronics | Custom PCB files, schematics, and low-level firmware. | chromapi_motherboard repository |
Available |
 |
| Ousmane THIONGANE |
This project has been made possible thanks to the sponsors listed below. Their contributions in manufacturing, assembly, and prototyping have greatly accelerated the development of Chromapi.
Huge thanks to everyone who gave me feedback on the Chromapi's design, shared ideas, or simply took the time to brainstorm with me. This project wouldn't be where it is today without your help!
Contributions are always welcome!
- Report Issues: Found an error or have a feature request? Create a new issue here.
- Fix Bugs & Add Features: Find out where you can lend a hand by checking out existing issues.
Before opening a pull request, don't forget to run the linters and unit tests: uv run ruff check . && uv run mypy && uv run pytest.
By submitting a contribution, you agree that it is published under the license of the part it belongs to.
This repository is multi-licensed:
| Part | Path | License |
|---|---|---|
| Software (Python SDK, tools, tests, scripts, Raspberry Pi setup) | /src, /tests, /scripts, /deploy |
Apache 2.0 |
| Robot description (URDF, MJCF, configuration files) | /src/chromapi/model |
Apache 2.0 |
3D meshes (.stl, .part) |
/src/chromapi/model/*/assets |
CC BY-NC-SA 4.0 |
| Documentation and media (README, images, GIFs) | /assets, this README |
CC BY-NC-SA 4.0 |
Third-party content keeps its own license: meshes of off-the-shelf parts (Raspberry Pi 4, IMX219 camera, Noctua NF-A4x10 fan, WS2812B ring, 18650 battery, speaker, microswitch, power switch, connectors, screws) come from their respective manufacturers. The ENSEA and PCBWay logos in /assets are trademarks of their respective owners.