OpenJugglePlate

English | 简体中文 | 繁體中文

An open-source standalone ping-pong ball balancing and juggling robot with top-view vision, Linux SBC high-level control, and STM32 real-time motion control.

Table of Contents

• OpenJugglePlate
  • Table of Contents
  • What This Project Is
  • What It Tries To Do
  • What This First Version Focuses On
  • Current Status
  • Repository Structure
  • Quick Start
    • 1. Clone The Repository
    • 2. Read The Project Overview
    • 3. Pick A Workstream
    • 4. If You Want To Contribute
    • 5. If You Want To Build Along Early
  • Contributing
  • Safety Note
  • License

What This Project Is

This repository is the public home of the OpenJugglePlate project. The long-term goal is to make it a complete open-source robotics repository with:

• project documentation
• hardware design files
• firmware for STM32
• software for a Linux SBC such as Orange Pi, Raspberry Pi, or an RK3588-class board
• reproducible BOM and assembly guidance

At the moment, this is still an early-stage public build log and project skeleton rather than a finished machine release.

What It Tries To Do

OpenJugglePlate is focused on one object only: a standard 40 mm ping-pong ball.

The first practical version aims to:

• bring the ball back to the center of the plate
• keep it stable on the plate
• transition from plate balancing into controlled bouncing
• sustain continuous juggling

The implementation is intentionally narrow so the first public machine can be realistic and reproducible. That means V1 is built around:

• single top-view vision
• Linux SBC + STM32
• a 3-actuator parallel platform
• stepper motors

What This First Version Focuses On

The first public version is mainly focused on:

• one target object: a standard 40 mm ping-pong ball
• one practical sensing path: single top-view vision
• one pragmatic compute split: Linux SBC + STM32
• one reproducible motion platform: 3-actuator parallel platform

That also means V1 is intentionally not trying to do everything at once. For now, it does not aim to cover:

• multiple ball types or arbitrary objects
• automatic ball pickup or reload
• brushless primary actuation
• reinforcement learning as the baseline controller

Current Status

Planning / prototyping

Right now the repository is focused on:

• public project structure
• documentation
• reference collection
• contribution workflow
• early subsystem placeholders

The actual hardware, firmware, and Linux SBC software will be added incrementally as the prototype moves forward.

Repository Structure

.
|-- .github/                  # Issue templates, PR template, CI, Pages workflows
|-- firmware/                 # STM32 real-time control side
|-- hardware/                 # CAD, mechanics, BOM, assembly side
|-- software/                 # Linux SBC vision and high-level control side
|-- README.md                 # English project overview
|-- README.zh-CN.md           # Simplified Chinese overview
|-- README.zh-TW.md           # Traditional Chinese overview
|-- CONTRIBUTING.md
|-- CODE_OF_CONDUCT.md
|-- SECURITY.md
|-- LICENSE
`-- NOTICE

Notes:

• The public repository is organized so hardware, firmware, and software can evolve in parallel.
• Some local planning material is intentionally kept private and is not part of the public repository.

Quick Start

1. Clone The Repository

git clone https://github.com/Zw-awa/OpenJugglePlate.git
cd OpenJugglePlate

2. Read The Project Overview

Start with:

• README.md
• hardware/README.md
• firmware/README.md
• software/README.md

3. Pick A Workstream

• Interested in mechanics: start in hardware/
• Interested in embedded control: start in firmware/
• Interested in vision and high-level control: start in software/

4. If You Want To Contribute

Read:

• CONTRIBUTING.md
• Issue templates
• SUPPORT.md

5. If You Want To Build Along Early

Be aware that this repository is still in planning/prototyping mode. Expect subsystem details and BOM choices to evolve as the first machine is built.

Contributing

Contributions across mechanics, firmware, vision, controls, docs, and reproducibility are welcome. Start with CONTRIBUTING.md.

For large changes, open an issue first so the project can keep the hardware and software assumptions coherent.

Safety Note

This repository targets a moving electromechanical prototype. Even low-cost prototypes can throw balls, pinch fingers, or damage parts if driven outside their safe envelope. Treat all motion, power, and tuning work as hardware safety work.

License

This project is licensed under the Apache License 2.0. Copyright 2026 Zw-awa. Additional attribution details are recorded in NOTICE.