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 layout authoring for component placement, sizing, alignment, and keyboard mapping.

  • Stage tab for visual editing and inspector controls
  • Options tab for dimensions and layout actions
  • Keyboard mapping for component-level trigger shortcuts
  • Components panel for hardware grouping and quick selection
  • Inspector panel with per-component detail and tuning fields
  • Scale/rotation and color tuning for precise table layout design

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
  • Target scenes to identifies displays. e.g. Backboard or in table
  • Runtime visibility for active sessions and control actions
  • Asset-driven workflow from upload to live display launch

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

Installation-level configuration and project migration workflows.

  • Project and system configuration
  • Import/Export tab for project backup and restore
  • Centralized machine-wide settings management

Logs

Runtime diagnostics and event visibility for fast troubleshooting.

  • Web, Bridge, ESP Raw, and Events log sources
  • Tail, refresh, download, and purge controls
  • Keyword filtering and line controls

Configuration Integrity Check

Cross-module dependency validation with targeted and bulk orphan cleanup.

  • All, OK, Errors, and Unused status tabs
  • Per-row resolve and Resolve All workflows
  • Formatted cleanup report with changed artifacts

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

Live Preview

Read-only runtime emulator for validating real-time table behavior and display output from one view.

  • Live stage reacts to incoming hardware events and rule outputs
  • Right-click component context menu to fire available trigger actions
  • Combined button action option for PRESSED + RELEASED testing
  • Right column display cards render active media runtime scenes live
  • Live score updates are reflected on media overlays during gameplay
  • Sound cues are played in response to configured rule/event actions
  • Keyboard shortcuts from Playfield keymap are available for fast testing

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