Ball-Balancing Robot

An educational Raspberry Pi ball-balancing robot that uses camera vision and PID control to keep a ball centered on a platform tilted by servos.

This repository contains executable files that Robotheca doesn't check. Only run them if you trust the creator.

Which files (2 scripts)

3D preview converted from github.com/I-M-Robotics-Lab/Ball-Balancing-Robot at d06e5fd, under GPL-3.0-only. View the original files from GitHub (715 KB) (opens in a new tab)

What it can do

Written by Robotheca from the project's documents.

Balances a ball on a tilting platform using real-time camera vision feedback.
Runs a PID control loop at roughly 60 Hz frame capture, 50 Hz vision processing, and servo actuation.
Provides a curses-based HMI over SSH with jog controls and calibration tools.
Runs headless: video preview is disabled automatically while the control loop keeps working.
Uses JSON-driven configuration, with calibration values saved to config/calibration.json.

This repository has no parts list Robotheca can read yet.

The creator's steps, each with its instructions.

The guide appears here as you scroll.

Guide by @I-M-Robotics-Lab (README.md), under GPL-3.0-only.

Notes written by Robotheca from the project's documents.

Buildable with some effort

How complete the published files are for rebuilding this robot, measured by Robotheca at commit d06e5fd. It isn't a rating of the robot.

3D and CAD files20/20
2 printable parts (STL, 3MF), 8 CAD source files.
Robot description0/15
No URDF.
Add a URDF: the robot can then be seen in 3D and tried in the browser.
Parts list0/20
No parts list in the repository or linked.
Most points to gain: Link to your parts list, or add it to the repository (a CSV or a Markdown table) with quantities, prices and where to buy each part.
Software10/15
Code in this repository, instructions to install or run it.
Say which software framework it uses (ROS 2, LeRobot, Arduino…).
Documentation15/15
README of 4,262 characters with 2 pictures; 10 build steps.
Simulation0/5
No simulation files.
Add a simulation model (MuJoCo, Gazebo, Webots or Isaac).
Licenses10/10
Hardware: GPL-3.0-only; software: GPL-3.0-only.

Written by Robotheca from the project's documents.

Flash Raspberry Pi OS (Bookworm recommended) with Raspberry Pi Imager, enable SSH, and configure WiFi and user if needed.
Enable I2C with raspi-config, reboot, and confirm the PCA9685 with i2cdetect -y 1.
Run bash scripts/install.sh to install Python dependencies, system libraries, OpenCV, and the libcamera stack.
Launch the HMI with the hmi command to capture zero pose and set X/Y offsets, saving calibration values.
Start the control loop with bash scripts/run_runtime.sh; press q to exit, which disarms servos and closes the camera.

Robotheca doesn't review code. Read it before running it.

Every file of the project: code, CAD, electronics, guides, at commit d06e5fd.

Questions and improvements go to the creator's repository.