Building your own interactive Twitch LED matrix might sound intimidating, but I promise it's much easier than it looks! We are just going to take it one simple step at a time. No engineering degree required.
1. The Parts List
Here is everything you need to get started:
- Raspberry Pi 3B+ or 4: (Note: The software isn't compatible with the Pi 5, as far as I know). A 1GB or 2GB model will work perfectly. Grab one here. (Tip: If you are lucky enough to live near a MicroCenter, check there first-they often have them on sale!)
- MicroSD Card: An 8GB or 16GB card is plenty of space. Link here.
- MicroSD Card Reader: You'll need a way to plug the MicroSD card into your PC. If your computer doesn't have a built-in slot, grab a cheap USB adapter like this one.
- Adafruit RGB Matrix Bonnet: This is the "brain" that connects the Pi to the screen. Get it here. (Note: Even if it shows a jumper pre-installed in the picture, it usually comes without one).
- RGB LED Matrix Panels: This guide uses two 64x32 pixel panels. I used the 4mm pitch panels from Adafruit. Link here.
- 5V Power Supply: A 10 Amp supply is plenty for 2 to 4 panels. The Matrix uses a 5.5x2.1mm plug. This is the exact one I use (I’ve easily powered 6 panels with it!).
- Solder and Soldering Iron: Just for one tiny, easy connection. Basic kit here.
2. Hardware Assembly & Soldering
The Easy Solder Mod
- Solder a small wire (jumper) between pins 4 and 18 on the Matrix Bonnet. This gives your screen much better brightness, less flickering, and smoother colors. It's super simple!
Putting it Together
- Plug one end of the gray ribbon cable (it came with your LED panels) into the RGB Matrix Bonnet. It can only be inserted one way, notice the cutout in the plastic or the bump out on the plug.
- Grab the red and black power wires. Cut off the pre-attached plastic connectors on the ends. Make sure you leave the white plugs attached.
- Strip a little bit of the plastic sheathing off the ends to expose the bare wire.
- Connect the Red wire to the (+) Pos terminal on the Matrix Bonnet.
- Connect the Black wire to the (-) Neg terminal on the Matrix Bonnet. Mine are both a little long in these photos, I went back and snipped them shorter. I just wanted to show them clearly. When you put yours in, you should make sure the copper wire is fully inserted.
- Carefully line up the pins on the Raspberry Pi with the Matrix Bonnet and gently press them together. Important: Don't press them completely flush—leave a tiny gap for airflow so your Pi stays cool and not to bend the pins.
- Connect your boards together. There are some basic 3D print files you can find that will work as brackets/feet for your boards. Found Here. I found 1 inch hinges worked great for me, as I was able to then use those hinges to screw it to a wood box frame I made. If you are using a single board, skip this step.
- Next you will need to connect the ribbon cables and the white plugs from the power cables to your board(s). Note the connectors all only connect one way. When plugging multiple displays together, look for the arrow on the back of the board, they will indicate which way the connectors should run. The first ribbon cable from the Raspberry Pi should be plugged into the first arrow of your panels (if multiple panels connected), starting opposite of the pointy end of the arrow (like the photo below).
3. Preparing the Software
Download the Imager
Go to the official Raspberry Pi Software Page and download the Imager program for your computer: Download Here. Install it on your computer.
Flash the MicroSD Card
In this step, we will be flashing the MicroSD card with the Raspberry Pi software, so that it can then be coded from our computer. (In my example, I will be using my Raspberry Pi 4B to show the walk through).
- Plug your MicroSD card into your computer using whatever method you chose from the previous parts list (directly into an SD card reader slot if you have one or via an adaptor).
- Open the Raspberry Pi Imager program you just downloaded.
- CHOOSE DEVICE: Select your specific Raspberry Pi model. Click Next.
- CHOOSE OS: Go to Raspberry Pi OS (Other) > Select Raspberry Pi OS Lite (64-bit). (We only need the text terminal, not the full desktop visual environment). Click Next.
- CHOOSE STORAGE: Select your MicroSD card. Click Next.
Your Custom & "Secret" Wi-Fi Settings
- Customization Tab: Hostname, name it something easy. (I use
twitchmatrix). Click Next. - Make sure your Localization is set to your information. Click Next.
- Set a Username and Password. Make the username the exact same as your hostname (
twitchmatrix) to keep things simple. Create a password you'll remember using only letters and numbers. Click Next. - Set your Wi-Fi up by carefully typing in your exact home Wi-Fi name (SSID) and password. Click Next.
- Remote Access: Check "Enable SSH (Use password authentication)". This allows you to remotely access the Pi board (making changes to the display) from another computer on your network. Click Next.
- Raspberry Pi Connect is NOT required for this, so leave it unchecked and Click Next.
- Your final page should look similar to this one. Click Write.
- Wait for the Prompt Timer and Click I Understand, Erase and Write.
- Wait for the process to finish, how long it takes depends on your computer.
- Wait for the Verification.
- Once Complete you should receive a message similar to this. Click Finish.
Once it finishes loading, take the MicroSD card out of the computer (or adaptor) and insert the MicroSD card into your Raspberry Pi (little slot on the bottom of the board). The contacts of the MicroSD card will be facing the Bottom of the Raspberry Pi board. Plug the power cord into the wall and the barrel plug into the RGB Matrix Bonnet's Power Plug. Give it about 2 minutes to boot up and connect to your Wi-Fi automatically.
4. Connecting & Installing Drivers
Now we are going to remotely control the Pi right from your computer. When using PowerShell and changing code, a keyboard with a 10 key and arrow keys will make it much easier (personal lesson learned using my 60% keyboard)
- Open PowerShell (if you are on Windows) or Terminal (if you are on Mac). (Can be found by clicking your start button then searching for PowerShell)
- Type
ssh twitchmatrix@twitchmatrix.local(or replace "twitchmatrix" with whatever Username and Hostname you chose). Press Enter. - Type YES to accept the security prompt (Fingerprint). Press Enter.
- Type the password you created. Press Enter. (You won't see anything being typed when typing the password)
- Congratulations! You are now controlling your Raspberry Pi. Anytime you need to change something, you will need to open the PowerShell and Login this same way. It won't ask for the fingerprint after the first time. So make sure you remember your hostname/username/password.
Install the Matrix Library
- Copy and paste this exact command into your terminal window and hit ENTER:
wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/rgb-matrix.sh- Then Copy and Paste. Press Enter.
sudo bash rgb-matrix.sh - Press Y. Press Enter.
- Select 2 for Adafruit RGB Matrix Bonnet/HAT. Press Enter.
- Y for real time clock support. Press Enter.
- Select 1 for Quality (if it asks). Press Enter.
- Y to Continue. Press Enter.
- Let it run! It takes a few minutes. When it asks to reboot, type Y.
- Give it about a minute to reboot.
- Once the Pi restarts, reconnect to it the exact same way you did before ssh twitchmatrix@twitchmatrix.local or
ssh Username@Hostname.local if you used a different username and hostname.
Install the "Chat Room" (MQTT)
This software lets your Pi "listen" for alerts from Lumia Stream. Paste these lines one by one, hitting ENTER after each one, and waiting for it to finish:
sudo apt update
sudo apt install -y mosquitto mosquitto-clients python3-paho-mqttNext, we need to open the security doors so Lumia Stream is allowed to talk to the Pi. Paste this:
echo -e "listener 1883 0.0.0.0\nallow_anonymous true" | sudo tee /etc/mosquitto/conf.d/network.conf
sudo systemctl restart mosquitto5. The Matrix Code!
This script is the magic. It handles scrolling your text, connecting the panels together, and adding a really cool color-shifting "pulse" effect whenever a new Twitch chat message pops up. It will also show a default scrolling message when chat is quiet.
Open up the text editor on the Pi by typing this and hitting Enter:
nano twitch_scroller.pyNow, copy this entire block of code below, and right-click to paste it into the terminal:
#!/usr/bin/env python3
import time
import math
from rgbmatrix import RGBMatrix, RGBMatrixOptions, graphics
import paho.mqtt.client as mqtt
# --- CONFIGURATION ---
MQTT_BROKER = "localhost"
MQTT_TOPIC = "twitch/scroll"
LED_ROWS = 32
LED_COLS = 64
LED_CHAIN = 2 # Change this if you have more/fewer panels
GPIO_MAPPING = 'adafruit-hat'
DEFAULT_MSG = "Waiting for Chat..."
TEXT_HEIGHT = 22 # Centers text vertically on a 32-row board
GREEN = graphics.Color(0, 255, 0)
current_message = DEFAULT_MSG
new_message_arrived = False
current_color = GREEN
def on_connect(client, userdata, flags, rc):
client.subscribe(MQTT_TOPIC)
def on_message(client, userdata, msg):
global current_message, new_message_arrived
try:
current_message = msg.payload.decode("utf-8")
new_message_arrived = True
except:
pass
def run_matrix():
global current_message, new_message_arrived, current_color
options = RGBMatrixOptions()
options.rows = LED_ROWS
options.cols = LED_COLS
options.chain_length = LED_CHAIN
options.hardware_mapping = GPIO_MAPPING
options.drop_privileges = False
options.brightness = 40 # Start at 40%, adjust as needed
matrix = RGBMatrix(options = options)
offscreen_canvas = matrix.CreateFrameCanvas()
client = mqtt.Client()
client.on_connect = on_connect
client.on_message = on_message
try:
client.connect(MQTT_BROKER, 1883, 60)
client.loop_start()
except:
print("MQTT Connection Failed")
pos = offscreen_canvas.width
is_scrolling_custom = False
hue = 0
while True:
if new_message_arrived and current_message != DEFAULT_MSG:
pos = offscreen_canvas.width
is_scrolling_custom = True
new_message_arrived = False
offscreen_canvas.Clear()
# Color Pulse Effect for custom messages
if is_scrolling_custom:
r = int(127 * math.sin(hue) + 128)
g = int(127 * math.sin(hue + 2) + 128)
b = int(127 * math.sin(hue + 4) + 128)
current_color = graphics.Color(r, g, b)
hue += 0.1
else:
current_color = GREEN
length = graphics.DrawText(offscreen_canvas, font, pos, TEXT_HEIGHT, current_color, current_message)
pos -= 1
if (pos + length < 0):
if is_scrolling_custom:
current_message = DEFAULT_MSG
is_scrolling_custom = False
pos = offscreen_canvas.width
time.sleep(0.03) # Adjust for scroll speed
offscreen_canvas = matrix.SwapOnVSync(offscreen_canvas)
if __name__ == "__main__":
font = graphics.Font()
font.LoadFont("/home/twitchmatrix/rpi-rgb-led-matrix/fonts/7x13.bdf")
run_matrix()IF you set a different username than twitchmatrix, you will need to change the second to last line of code and put your own unique username in.
To save your work: Press CTRL+X, then press Y, then press ENTER. (Anytime you want to edit your colors or text later, you'll use this exact same process to save and exit).
If you ever make changes to that code later, run this command to restart the screen and apply them (Will only work after completing Step 6):
sudo systemctl restart twitch_led.service6. Make it Run Automatically
We don't want to type code every time we stream! Let's tell the Pi to turn the sign on automatically the second you plug it into the wall.
- Create an auto-start file by pasting this:
sudo nano /etc/systemd/system/twitch_led.service - Paste this block of text into the editor:
[Unit]
Description=Twitch LED Matrix Scroller
Wants=network-online.target
After=network-online.target mosquitto.service
[Service]
ExecStart=/usr/bin/python3 /home/twitchmatrix/twitch_scroller.py
WorkingDirectory=/home/twitchmatrix
StandardOutput=inherit
StandardError=inherit
Restart=always
RestartSec=10
User=root
[Install]
WantedBy=multi-user.target- Save it (CTRL+X, Y, ENTER).
- Tell the Pi to start using it by pasting these three commands separately (hit ENTER after each one):
sudo systemctl daemon-reload
sudo systemctl enable twitch_led.service
sudo systemctl start twitch_led.service**If it doesn't work right away, your likely culprit is a new change to newer Raspberry Pi's. Make sure you are logged into your PowerShell and Follow the steps below. Each of these lines takes a little bit of time to finish and can look like a wall of code happening or look frozen, just let it finish.
Troubleshooting: ModuleNotFoundError: No module named 'rgbmatrix'
If you try to run your Python script and get slapped with a ModuleNotFoundError: No module named 'rgbmatrix' error, don't panic. (You may not see this error upfront, follow these steps first to troubleshoot if it is not working correctly, this is a common error). This simply means the Adafruit installer failed to build the Python library.
On the newest Raspberry Pi OS (Bookworm), Python removed an old building tool called distutils. When the Adafruit installer looks for it, it quietly crashes in the background. To fix the rgbmatrix error, we just need to install the replacement tool and manually build the library ourselves. When logged into your PowerShell, install each of these lines of code separately.
Step 1: Install the updated Python build tools
sudo apt-get install -y python3-setuptools python3-devStep 2: Navigate to the Adafruit matrix folder
cd /home/twitchmatrix/rpi-rgb-led-matrix/Step 3: Build the Python module
make build-python PYTHON=$(which python3)Step 4: Install it to the system
sudo make install-python PYTHON=$(which python3)Step 5: Fire up the matrix!
cd ~
sudo python3 twitch_scroller.pyStep 6: Close PowerShell. The screen should be scrolling your default message now.
Making Default Changes:
7. Link it to Lumia Stream
Almost at the finish line! If you don’t already use Lumia Stream to manage your Twitch alerts, you can get it for free here: Lumia Stream Download. (If you purchase a premium subscription through that link, it is an affiliate link and I truly appreciate the support—but the free version does everything we need for this project!).
Let's connect your stream chat to the LED sign:
- First, find your Pi's exact IP address. In your terminal window, type:
hostname -I. Write down the first number that pops up (it will look something like 192.168.1.50). - Open Lumia Stream on your PC.
- Go to Connections > Add New Connection > MQTT.
- In the Host box, type:
mqtt://YOUR_PI_IP_HERE:1883(Replace the ALL CAPS text with the actual IP address you wrote down). Click ADD. - Go to Commands > Chat Commands > Add Command.
- Name it
highlight. - Go to the Lumia Actions tab, click Add Action, and choose MQTT.
- Fill out the box exactly like this:
- Topic:
twitch/scroll - Value:
{{message}}
- Topic:
- Click Save, then click the Refresh button on your Lumia Dashboard to lock it in.
The Final Test!
Go to your Twitch chat and type !highlight Hello World!. Your LED sign will instantly swap messages and pulse in a rainbow of colors as it scrolls across!
If you have any questions, please feel free to jump into the Discord: https://discord.gg/xyw6MwHv7g
Comments
Post a Comment