Pinball CTL

Homebrew Pinball Control Platform

Configure hardware, author gameplay, and run displays from one interface.

Pinball CTL combines a Raspberry Pi authoring/orchestration layer with an ESP32-S3 real-time runtime layer. You map hardware, build rules, author scoring and lighting, and manage media displays from a browser UI, then sync to ESP for deterministic runtime behavior.

Raspberry Pi 5 ESP32-S3 Rules + Scoring + Lighting + Media Browser-first workflows Safety-gated output control

Why Pinball CTL

Built to close the gap for homebrew builders.

This project was created because many existing pinball control tools feel cumbersome and non-intuitive for amateur builders.

As a software engineer, the goal here is to bridge that gap: provide a clearer workflow, a more approachable interface, and practical module structure so builders can move from wiring to playable behavior faster.

How It Works

Author on Pi, execute on ESP.

  1. Discover and map components in Hardware.
  2. Build behaviour in Rules and Scoring.
  3. Design visual feedback in Lighting and Media.
  4. Save and sync compiled state to ESP/runtime.
  5. Monitor health, logs, and revisions from Dashboard and Logs.

The Pi is your authoring and orchestration surface. The ESP enforces real-time behaviour and safety constraints at runtime.

In practice, this means you edit and validate configuration in the web UI, then sync those changes to the device layer in a controlled way.

This split helps you iterate quickly during development while preserving predictable machine behavior during live operation.

Footnote: you can develop and iterate on macOS, then deploy the same project configuration to Raspberry Pi for production runtime.

Browser UI
→
Pi Services
→
Bridge
→
ESP Runtime

Key Modules

Distilled feature set for builders and operators.

Rules

Event-driven gameplay logic with triggers, conditions, and actions. Button pressed, fire a flipper and play a sound.

  • Grouped trigger/condition logic
  • Validation and unsaved-change protection
  • Rules sync status visibility

Playfield

Visual table authoring and simulation workflows for placement, interaction, and fast validation.

  • Stage tab for visual editing and inspector controls
  • Options tab for dimensions and layout actions
  • Keyboard/event testing before live deployment

Scoring

Purpose-built points authoring for baseline awards, progressive ramps, and combos.

  • Base Points, Scoring Rules, Combos tabs
  • Hardware and event source modes
  • Runtime-friendly scoring behavior

Media

Video/overlay scene authoring with display-targeted runtime and kiosk launch controls.

  • Stage, Library, Displays, Runtime tabs
  • Overlay composition and playback preview
  • Fullscreen and small-window launch modes

Hardware

Physical I/O mapping with explicit function assignment and safe-state controls for reliable machine behavior.

  • Friendly names and logical function mapping
  • PIN safe defaults for boot/fault handling
  • Save and sync workflow for deterministic runtime mapping

ESPLink and Firmware

Device connectivity and firmware management for keeping the ESP runtime current and verifiable.

  • USB link status and serial diagnostics
  • Firmware package visibility and deployment flow
  • Runtime version checks and maintenance workflow

Lighting

Scene authoring with Stage and Fixtures tabs, including timeline/pattern workflows and sync to ESP.

  • Scene targeting and cast control
  • Preview-first authoring loop
  • Revision-aware sync flow

Audio

Cue-based playback system for assets, outputs, and runtime audio diagnostics.

  • Library, Cues, Outputs, and Usage Map tabs
  • Routing by output target and bus
  • Runtime visibility for active/orphan playback

Settings and Logs

Installation-level configuration, backup/restore workflows, and runtime diagnostics.

  • Settings and Import/Export tabbed configuration
  • Project migration via export/import bundles
  • Logs module for troubleshooting and visibility

Service Log

Maintenance and service history tracking for machine operations and handover visibility.

  • Record service actions and outcomes
  • Track maintenance history over time
  • Support operational continuity for teams

Safety and Reliability

Conservative by design for real machines.

  • ESP runtime enforces output safety and guards.
  • Rules and sync workflows surface explicit status and failures.
  • Unsaved-change prompts reduce accidental data loss.
  • Dashboard provides a single operational health view.
  • Logs and module runtime tabs support fast troubleshooting.

Requirements

What you need to run Pinball CTL.

Core Hardware

  • Raspberry Pi 5 (host services + web UI)
  • ESP32-S3 (real-time I/O runtime)
  • USB serial connection between Pi and ESP

Access

  • Modern browser on local network
  • Optional Wi-Fi onboarding and remote access
  • Display outputs for media kiosk workflows

Runtime Dependencies

  • Bridge process and Pi services running
  • Chromium runtime for media display mode
  • Installed tooling visible in Dashboard Dependencies

Getting Started ...

Flash Raspberry Pi OS, install Pinball CTL from Git, run `pinballctl`, then open the web UI and start configuring.

  1. Flash Raspberry Pi OS (64-bit) to SD card using Raspberry Pi Imager.
  2. Boot the Pi and connect via SSH or keyboard/monitor.
  3. Install tools and create a Python virtual environment.
  4. Install Pinball CTL from Git and verify with `pinballctl --version`.
  5. Start with `pinballctl start`, then open `http://<pi-ip>:8888` in your browser.
sudo apt update && sudo apt install -y python3-venv python3-pip git
mkdir -p ~/pinballctl && cd ~/pinballctl
python3 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install \"git+https://github.com/VineCode/pinballctl.git@vX.Y.Z\"
pinballctl start
GitHub Back to Top