A complete LED matrix controller and animation system for the Raspberry Pi Pico using MicroPython and a web-based UI. This project allows you to send commands and animations to a 32x8 LED matrix display over serial using a modern, responsive web interface.
- Web UI built with Flask and HTML/JS
- Select serial device from dropdown (backend-driven)
- Multiple animated effects:
- Matrix Rain
- Fire simulation
- Plasma, Waves, Scanner
- Bouncing Balls
- Pong game
- Clock display (12/24h, blinking colon, with/without seconds)
- Scrolling text
- Brightness and speed controls
- Custom text support
- Tested on Raspberry Pi Pico
-
Inspired by the WOPR LED Enclosure project: https://www.printables.com/model/1167457-1u-rack-mount-wopr-leds-enclosure
-
Hardware driver via
max7219.py: https://github.com/mcauser/micropython-max7219 -
Guide for wiring and setup: MicrocontrollersLab - MAX7219 with Pi Pico
- Raspberry Pi Pico (with MicroPython installed)
- MAX7219 8x8 LED Matrix (4 modules recommended, e.g. 32x8)
- Jumper wires, breadboard
Raspberry Pi Pico pinout diagram (with MAX7219 wiring)
┌╌ LED (GP25)
┆ ┏━━━━┓
┌─────┃ ┃─────┐
UART0 TX | I2C0 SDA | SPI0 RX | GP0 | 01│● ┆ ┗━━━━┛ ●│40 | VBUS <─── MAX7219 VCC
UART0 RX | I2C0 SCL | SPI0 CSn | GP1 | 02│● ⏄ ●│39 | VSYS
GND | 03│■ ■│38 | GND <─── MAX7219 GND
I2C1 SDA | SPI0 SCK | GP2 | 04│● ╭─╮ ●│37 | 3V3_EN
I2C1 SCL | SPI0 TX | GP3 | 05│● │ │ ●│36 | 3V3(OUT)
UART1 TX | I2C0 SDA | SPI0 RX | GP4 | 06│● ╰─╯ ●│35 | | ADC_VREF
UART1 RX | I2C0 SCL | SPI0 CSn | GP5 | 07│● ●│34 | GP28 | ADC2
GND | 08│■ ■│33 | GND | AGND
I2C1 SDA | SPI0 SCK | GP6 | 09│● ┌─────┐ ●│32 | GP27 | ADC1 | I2C1 SCL
I2C1 SCL | SPI0 TX | GP7 | 10│● │ │ ●│31 | GP26 | ADC0 | I2C1 SDA
UART1 TX | I2C0 SDA | SPI1 RX | GP8 | 11│● │ │ ●│30 | RUN
UART1 RX | I2C0 SCL | SPI1 CSn | GP9 | 12│● └─────┘ ●│29 | GP22
GND | 13│■ ■│28 | GND
I2C1 SDA | SPI1 SCK | GP10 | 14│● ●│27 | GP21 | | I2C0 SCL
I2C1 SCL | SPI1 TX | GP11 | 15│● ●│26 | GP20 | | I2C0 SDA
UART0 TX | I2C0 SDA | SPI1 RX | GP12 | 16│● ●│25 | GP19 | SPI0 TX | I2C1 SCL
UART0 RX | I2C0 SCL | SPI1 CSn | GP13 | 17│● ●│24 | GP18 | SPI0 SCK | I2C1 SDA
GND | 18│■ ■│23 | GND
I2C1 SDA | SPI1 SCK | GP14 | 19│● ●│22 | GP17 | SPI0 CSn | I2C0 SCL | UART0 RX
I2C1 SCL | SPI1 TX | GP15 | 20│● ● ■ ● ●│21 | GP16 | SPI0 RX | I2C0 SDA | UART0 TX
└────────────────┘
┆ ┆ ┆
┆ ┆ └╌ SWDIO
┆ └╌╌╌ GND
└╌╌╌╌╌ SWCLK
MAX7219 ↔ Pico Wiring Summary:
──────────────────────────────
VCC → VBUS (Pin 40)
GND → GND (Pin 38 or 3 or 8 or 13 or 18 or 23 or 28 or 33)
DIN → GP3 (Pin 5) — SPI0 TX
CS → GP5 (Pin 7) — SPI0 CSn
CLK → GP2 (Pin 4) — SPI0 SCK
- Flash MicroPython firmware to the Raspberry Pi Pico
- Use Thonny to:
- Upload
main.pyandmax7219.pyto the Pico - Set
main.pyas the startup script
- Upload
- Open Thonny’s serial terminal to view logs or test input commands
- Clone this repo on your desktop machine
- Install dependencies (Python 3.x)
pip install flask pyserial
- Run the web controller:
python clients/web/server.py
- Visit
http://localhost:5000in your browser - Select a serial port, click connect, and send effects!
For a production setup that starts automatically on boot:
- Clone this repo and navigate to the project directory
- Run the installation script as root:
sudo ./install.sh
- The service will be installed and started automatically
- Visit
http://localhost:5123orhttp://YOUR_IP:5123in your browser
Service Management:
# Check service status
sudo systemctl status picopixels-server
# Start/stop/restart service
sudo systemctl start picopixels-server
sudo systemctl stop picopixels-server
sudo systemctl restart picopixels-server
# View live logs
sudo journalctl -u picopixels-server -f
# Update the service (run from project directory)
sudo picopixels-updateFeatures of the service installation:
- Runs as dedicated
picopixelsuser with minimal privileges - Automatically starts on system boot
- Includes security hardening
- Easy update mechanism
- Proper logging via systemd journal
start <effect>– Start looping animationstop– Stop current animation<effect>– Run effect once (e.g.test,border,on,off)brightness <0-15>– Set brightnessspeed <ms>– Set speed of animationtext <message>– Set scrolling textclock [12/24] [seconds/noseconds] [blink/noblink]help– Show command list
The enclosure was designed using FreeCAD The Pi Pico holder was downloaded from Raspberry Pi Pico Case