PCA9685 Debug Panel

Web-based remote control panel for debugging PCA9685 servo drivers on robots.

⚠️ Security Notice: By default, this tool starts with no authentication. For shared networks, use --auth-token <token> to require a shared secret for write operations (POST/DELETE). The token is sent over unencrypted HTTP and has no brute-force protection — use on trusted networks only. Never expose the panel to the public internet.

中文文档

Vedio Demonstration

Description

A lightweight web panel (similar to FTC Dashboard) that runs on your robot and lets you control PCA9685-driven servos from any browser over Wi‑Fi. Supports per-channel angle control with calibration, live device status monitoring, and workspace save/load — so you can tune and debug servos without touching code.

Why? Adjusting servo angles on a robot usually means SSH + manual scripts. This panel gives you a visual UI in the browser with sliders, real-time feedback, and configuration persistence across restarts.

Installing / Getting started

Prerequisites

• Python 3.10+
• A Raspberry Pi (or similar) with I²C enabled and connected to PCA9685, or any machine for UI-only development (mock mode)

Quick setup

Using Pip

# Install from PyPI
pip install pca9685-debugging-panel

# Start the server
pca9685-panel --host 0.0.0.0 --port 8080

From GitHub Releases

Each release includes a pre-built .whl file as an attachment. Download it and install directly:

pip install pca9685_debugging_panel-0.2.0-py3-none-any.whl
pca9685-panel --host 0.0.0.0 --port 8080

Then open http://<robot-ip>:8080 in your browser.

From source

git clone https://github.com/xiaokai-lyk/PCA9685-debugging-panel.git
cd PCA9685-debugging-panel
uv sync
python main.py

On first launch a config.json file is created automatically with default values (I²C address 0x40, 50 Hz, 600–2400 µs pulse range).

Running on a desktop (no hardware)

Use the --mock flag to skip hardware initialisation entirely — all APIs work, the UI is fully interactive, and no real hardware is required for frontend development:

pca9685-panel --mock

Protecting write operations

To require a shared secret token for all write operations (POST/DELETE), use the --auth-token flag:

pca9685-panel --auth-token my-secret-token

The browser will show a login overlay; enter the same token to unlock the panel. Read operations (status, channel polling, SSE events) remain public so you can still monitor the device without authentication.

Developing

Project structure

PCA9685-debugging-panel/
├── backend/
│   ├── app.py              # FastAPI entry point (REST + SSE)
│   ├── pca9685.py          # PCA9685 driver (real hardware + optional mock mode)
│   ├── config_store.py     # JSON configuration persistence
│   └── schemas.py          # Pydantic request/response models
├── frontend/
│   ├── index.html          # Single-page UI
│   ├── app.js              # SSE connection, REST calls, state management
│   └── styles.css          # Dark theme, responsive grid
├── config.json             # Auto-generated runtime configuration
├── main.py                 # Convenience launcher
├── plan.md                 # Architecture & design decisions
└── pyproject.toml          # Project metadata & dependencies

API overview

Interactive docs available at http://<host>:8080/docs (Swagger UI).

Features

• 16-channel servo grid — angle slider / duty-cycle slider per channel, with live pulse-width display
• Per-channel calibration — map your own angle‑to‑pulse ranges for each servo
• Real-time status — device online/offline indicator with heartbeat via SSE
• Frequency control — adjustable 40–400 Hz PWM frequency
• Workspace save/load — export the full configuration (calibration, names, settings) as a JSON file; import it later or on a different robot
• Restart persistence — config.json survives reboots so your last setup is restored automatically
• Mock mode — run with --mock flag for UI development & testing without hardware
• Dark theme — responsive layout, works on desktop and mobile browsers

Configuration

config.json (auto-managed)

This file is written automatically when settings change — no manual editing needed.

Workspace file (user-managed)

Exported via the UI or GET /api/workspace/export. Contains the same fields plus full per-channel data (calibration, names, current positions). Can be imported on another machine to replicate a setup.

Troubleshooting

Device stays offline — "Hardware init failed: No module named 'RPi'"

This may happen when you are NOT using Raspberry Pi OS.

The Adafruit Blinka library cannot find the GPIO driver for your Raspberry Pi.

# Recommended
pip install rpi-lgpio

# For older OS (not recommended, may involve the compilation of C extensions)
pip install RPi.GPIO

Offline — Hardware init faile2d: No I2C device at address: 0x40

Your PCA9685 might be at a different address. Scan the bus:

sudo apt-get install i2c-tools
i2cdetect -y 1

If it's all -- in the result, please check if the device connection is correct. Make sure the connection is correct and then re-scan.

Then update the address in config.json or via the Settings modal in the UI.

Contributing

If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are welcome.

For major changes, open an issue first to discuss what you would like to change.

Links

• Repository: https://github.com/xiaokai-lyk/PCA9685-debugging-panel
• Issue tracker: https://github.com/xiaokai-lyk/PCA9685-debugging-panel/issues
• Related projects:
  • Adafruit CircuitPython PCA9685
  • FTC Dashboard

Licensing

The code in this project is licensed under the Apache License, Version 2.0.