# The CharlieBoard

[![Software: MIT](https://img.shields.io/badge/software-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Hardware: CERN-OHL-S](https://img.shields.io/badge/hardware-CERN--OHL--S-0053A1.svg)](https://ohwr.org/project/cernohl/wikis/Documents/CERN-OHL-version-2)
[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![Hardware: Raspberry Pi](https://img.shields.io/badge/hardware-Raspberry%20Pi%20Zero%202W-C51A4A.svg)](https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/)
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/tomunderwood99/CharlieBoard/issues)

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](hardware/images/hardware_carousel.gif)

## 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](https://api-v3.mbta.com/)

For hardware assembly instructions, see the [Hardware Assembly Guide](docs/hardware_assembly_guide.md).

Run the following commands to install and initialize the display.

```bash
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](docs/cli.md) 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](docs/nginx_reverse_proxy_setup.md).

**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

| Component | Notes |
|-----------|-------|
| Raspberry Pi Zero 2W | Main controller |
| WS2812B LEDs | Custom PCB (\~\$120 for 5) or LED strips (\~\$20) |
| 5V 4A Power Supply | Powers Pi and LEDs |
| MicroSD Card (16GB+) | For OS and software |
| Display Enclosure | Picture 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](docs/bill_of_materials.md) for detailed pricing and sourcing.

## Documentation

| Guide | Description |
|-------|-------------|
| [Quick Start Guide](deployment/quick_start/QUICK_START_GUIDE.md) | Step-by-step setup walkthrough |
| [Terminal CLI](docs/cli.md) | Change settings from SSH without the web UI |
| [Complete Setup Guide](docs/complete_setup_guide.md) | Detailed manual configuration |
| [Bill of Materials](docs/bill_of_materials.md) | Hardware pricing and sourcing |
| [Hardware Assembly](docs/hardware_assembly_guide.md) | PCB assembly instructions |
| [Operations & Troubleshooting](docs/operations_and_troubleshooting.md) | Maintenance and problem solving |
| [Transit System Adaptation](docs/transit_system_adaptation_guide.md) | Adapt for other transit systems |
| [Map Making with QGIS](docs/map_making_with_qgis.md) | Create custom transit maps ([example project](https://drive.google.com/drive/folders/1vFNIh-ThJNZXUUT2JSJMrOyUVWq9bhA2?usp=drive_link)) |

## 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).

## License

This repository uses two licenses:

| Scope | License | Full text |
|-------|---------|-----------|
| **Software** (Python, scripts, configs, docs outside `hardware/`, and everything except the `hardware/` tree) | [MIT License](https://opensource.org/licenses/MIT) | [LICENSE](LICENSE) |
| **`hardware/`** (PCB designs, KiCad projects, Gerbers, and related production files in this directory) | [CERN Open Hardware Licence v2 — Strongly Reciprocal (CERN-OHL-S)](https://ohwr.org/project/cernohl/wikis/Documents/CERN-OHL-version-2) | [LICENSE-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

<details>
<summary>Disclaimers & Attributions</summary>

### 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](https://api-v3.mbta.com/)
- **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.
</details>

## Support

- Check the [Operations and Troubleshooting Guide](docs/operations_and_troubleshooting.md)
- Review logs: `sudo journalctl -u mbta_display -n 100`
- Open an issue on GitHub with your Pi model, OS version, and error details
- [MBTA V3 API Documentation](https://api-v3.mbta.com/) · [Raspberry Pi GPIO Pinout](https://pinout.xyz/) · [Adafruit NeoPixel Guide](https://learn.adafruit.com/adafruit-neopixel-uberguide)