The CharlieBoard

July 9, 2026 · View on GitHub

Software: MIT Hardware: CERN-OHL-S Python Version Hardware: Raspberry Pi Contributions Welcome

An open-source LED display system for the MBTA that runs on Raspberry Pi Zero 2W with WS2812B LEDs. Features real-time transit data visualization, web control interface, and geographically accurate station mapping. PCBs for the Red, Orange, and Blue line are live! Green line in progress :)

CharlieBoard Display

Quick Start

Prerequisites:

  • Raspberry Pi Zero 2W with Debian Trixie 64-bit Lite
  • WS2812B LED strip or custom PCB
  • WiFi (configured during pi setup)
  • SSH enabled (RPI Connect recommended)
  • MBTA API key

For hardware assembly instructions, see the Hardware Assembly Guide.

Run the following commands to install and initialize the display.

sudo apt update && sudo apt install -y git python3-pip

cd ~
git clone --filter=blob:none --sparse https://github.com/tomunderwood99/CharlieBoard.git

cd CharlieBoard
git sparse-checkout set --no-cone '/*' '!hardware'

chmod +x deployment/quick_start/setup_mbta_controller.sh

# Optional: use flags to set custom recovery wifi settings:
# --with-wifi-helper
# --ap-ssid "CustomWifiName"
# --ap-password "YourStrongPassword"

sudo ./deployment/quick_start/setup_mbta_controller.sh

The setup script will prompt for your MBTA API key and various setting inputs. After completion, access the web interface at http://your-hostname.local:8000 on your local network. Settings can be changed from the web interface or from the command line using the charlieboard command. See the CLI reference for details.

Optional enhancement: Set up a reverse proxy to access the web interface at http://hostname.local without the port number. See the nginx reverse proxy setup guide.

Note: The sparse-checkout excludes the hardware/ directory (PCB design files) to speed up cloning. This setting persists across future git pull operations. If you need the hardware files, run: git sparse-checkout disable

Features

  • Real-time Transit Data: Live vehicle positions, occupancy, and speed data
  • Geographically Accurate: Stations are marked on a real map
  • Web Control Interface: Remote control from any device on your network
  • Customizable Display: Adjustable brightness, colors, and display hours
  • Reliable Operation: Automatic recovery, health monitoring, and maintenance

Hardware

ComponentNotes
Raspberry Pi Zero 2WMain controller
WS2812B LEDsCustom PCB (~$120 for 5) or LED strips (~$20)
5V 4A Power SupplyPowers Pi and LEDs
MicroSD Card (16GB+)For OS and software
Display EnclosurePicture frame or custom case

Total Cost: $50–180 depending on LED choice

Complete PCB design files (Gerber + KiCad) are available in hardware/PCB Production/. See the Bill of Materials for detailed pricing and sourcing.

Documentation

GuideDescription
Quick Start GuideStep-by-step setup walkthrough
Terminal CLIChange settings from SSH without the web UI
Complete Setup GuideDetailed manual configuration
Bill of MaterialsHardware pricing and sourcing
Hardware AssemblyPCB assembly instructions
Operations & TroubleshootingMaintenance and problem solving
Transit System AdaptationAdapt for other transit systems
Map Making with QGISCreate custom transit maps (example project)

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Test on Raspberry Pi Zero 2W hardware
  4. Commit your changes (git commit -m 'Add amazing feature')
  5. Push and open a Pull Request

Follow existing code style, update documentation for new features, and add comments for complex logic. Contributions to software are under the MIT License; contributions to hardware/ design files are under CERN-OHL-S, as described in License.

License

This repository uses two licenses:

ScopeLicenseFull text
Software (Python, scripts, configs, docs outside hardware/, and everything except the hardware/ tree)MIT LicenseLICENSE
hardware/ (PCB designs, KiCad projects, Gerbers, and related production files in this directory)CERN Open Hardware Licence v2 — Strongly Reciprocal (CERN-OHL-S)LICENSE-CERN-OHL-S

Third-party materials bundled under hardware/ may carry their own licenses (see notices in those subfolders).

Copyright © 2025 Thomas Underwood

Disclaimers & Attributions

AI Assistance

This project was developed with the assistance of AI coding tools. All code has been reviewed, tested, and validated on actual hardware.

Data Sources

This project uses data from:

  • MBTA and MassDOT – Transit data via MBTA V3 API
  • MassGIS – Geographic and mapping data

All data is provided "as is" without warranties. This project is not affiliated with, endorsed by, or sponsored by MBTA, MassDOT, MassGIS, or the Commonwealth of Massachusetts.

Support