Raspberry Pi LED Matrix Sports Scoreboard

Display live hockey, basketball, and baseball game scores, future start times, standings, etc. on an LED matrix driven by a Raspberry Pi.

Hardware requirements, installation instructions (with and without Docker), and configuration breakdown are below.

Leagues Implemented:

• 🏒 NHL
• 🏒 PWHL
• 🏀 NBA
• 🏀 WNBA
• ⚾️ MLB

Watch Demo on YouTube

Additional Examples

Contents

1. Hardware Required
2. Installation Instructions
3. Scenes
4. Configuration

Hardware Required

1. A Raspberry Pi Zero 2W and all Pi 3 or 4 models should work. The Pi 5 is currently unsupported due to a critical dependency being incompatible with that device.
2. An Adafruit RGB Matrix Bonnet (recommended) or RGB Matrix HAT + RTC.
3. HUB75 type 32x64 RGB LED matrix. These can be found at electronics hobby shops (or shipped from China for a lot cheaper). I recommend heading to a shop to purchase if you're unsure of exactly what you need.
4. An appropriate power supply. A 5V 4A power supply should suffice, but I offer the same advice as the LED matrix. I'm currently using a 5V 8A power supply as that's what I had lying around.
5. OPTIONAL, but recommended: A soldering iron, solder, and a short wire.

Installation Instructions

These instructions assume some very basic knowledge of electronics and Linux command line navigation. For additional details on driving an RGB matrix with a Raspberry Pi, check out my fork of hzeller's rpi-rgb-led-matrix repo (it's the submodule used in this project).

As of release v3.0.0, the recommended installation method for this project leverages Docker. Instructions are provided for installation with or without Docker.

Initial Setup: All Options

Any installation will need to start with these steps:

0. OPTIONAL, but recommended: Solder a jumper wire between GPIO4 and GPIO18 on the Bonnet or HAT board. This will allow you to get the best image quality later in the setup.

1. On your personal computer, use the Raspberry Pi Imager to flash an SD card with Raspberry Pi OS Lite (64 bit). During this process, be sure to...

   • Set a password (keep username as "pi").
   • Set your time zone.
   • Specify WiFi credentials.
   • Enable SSH via password authentication.

   See full Raspberry Pi Imager getting started guide here.

2. Remove the SD card from your computer and insert it into your Raspberry Pi.

3. Assemble all hardware per these instructions (steps 1 - 5).

4. Plug in your Raspberry Pi. From your personal computer, SSH into it and enter the password you set when prompted. These instructions will assume the default user of "pi" and device name of "raspberrypi". The command would look like this:

   ssh pi@raspberrypi.local

5. If you completed step 0 disable on-board sound to take advantage of the increased image quality. If you didn't complete step 0, skip this step.

   echo "blacklist snd_bcm2835" | sudo tee -a /etc/modprobe.d/alsa-blacklist.conf

6. Update built-in packages.

   sudo apt-get update && sudo apt-get upgrade -y

Option 1: Docker (Recommended)

7. Install Docker via installation script.

   curl -fsSL https://get.docker.com -o get-docker.sh
   sh get-docker.sh

   Then add the current user to the "docker" group. This will enable us to run "docker" commands without sudo.

   sudo usermod -aG docker $USER

8. Reboot your Raspberry Pi.

   sudo reboot

   Wait a couple minutes, then SSH back into your Raspberry Pi.

   ssh pi@raspberrypi.local

9. Clone this repository, including submodules.

   git clone --recursive https://github.com/gidger/rpi-led-sports-scoreboard.git

10. Navigate to the repository we just cloned.

    cd rpi-led-sports-scoreboard

11. If you're using a Raspberry Pi 4, skip this step. If you're using a Raspberry Pi Zero 2W, 3B, or older, you'll need to update hardware_config.gpio_slowdown in config.yaml to prevent flickering. It's recommended that you reduce the value by 1 each test and try every option to see what looks best for your hardware.

12. If you completed Step 0, skip this step. If not, you'll need to update hardware_config.hardware_mapping in config.yaml to match the following:

    hardware_mapping: 'adafruit-hat'

13. Update config.yaml with your preferred scoreboard behaviour. Don't worry, you can freely edit these settings at any time. Recommend setting a favourite team at the minimum. See the Configuration section for more details.

14. Start scoreboard. It will start running shortly after entering the below command. The scoreboard will automatically restart after a Raspberry Pi reboot.

    docker compose up -d

15. Done!

Option 2: Manual Installation

7. Install required packages.

    sudo apt-get install -y git make build-essential python3 python3-dev python3-venv cython3

8. Clone this repository, including submodules.

   git clone --recursive https://github.com/gidger/rpi-led-sports-scoreboard.git

9. Navigate to the repository we just cloned.

   cd rpi-led-sports-scoreboard

10. Create a Python virtual environment with the name "venv". Then activate.

    python -m venv venv
    source venv/bin/activate

11. Install required Python packages.

    pip install -r requirements.txt

12. Install the LED matrix Python package. First, navigate to the LED matrix library directory.

    cd submodules/rpi-rgb-led-matrix

    Then, build and install:

    make build-python PYTHON=$(which python)
    sudo make install-python PYTHON=$(which python)

13. Return to the root of your clone of this repository.

    cd /home/pi/rpi-led-sports-scoreboard/ 

14. If you're using a Raspberry Pi 4, skip this step. If you're using a Raspberry Pi Zero 2W, 3B, or older, you'll need to update hardware_config.gpio_slowdown in config.yaml to prevent flickering. It's recommended that you reduce the value by 1 each test and try every option to see what looks best for your hardware.

15. If you completed Step 0, skip this step. If not, you'll need to update hardware_config.hardware_mapping in config.yaml to match the following:

    hardware_mapping: 'adafruit-hat'

16. Update config.yaml with your preferred scoreboard behaviour. Don't worry, you can freely edit these settings at any time. Recommend setting a favourite team for each league at the minimum. See the Configuration section for more details.

17. Make the scoreboard script run at startup.

    nano ~/start-scoreboard.sh

    Paste the following:

    #!/bin/bash
    cd /home/pi/rpi-led-sports-scoreboard
    source venv/bin/activate
    
    n=0
    until [ $n -ge 10 ]
    do
       sudo /home/pi/rpi-led-sports-scoreboard/venv/bin/python main.py  && break
       n=$[$n+1]
       sleep 10
    done
    

    Save and exit.

18. Now, let's make that script executable:

    chmod +x ~/start-scoreboard.sh
    

19. And make it run at boot. First, enter:

    sudo crontab -e
    

    Then paste the following at the bottom:

    @reboot /home/pi/start-scoreboard.sh > /home/pi/cron.log 2>&1
    

    Save and exit.

20. Finally, test your change by rebooting your Raspberry Pi. If everything was done correctly, the scoreboard should start automatically running shortly after boot.

    sudo reboot
    

21. Done!

Scenes

Functionality is divided into different "scenes" that each display information on a specific topic (e.g., today's games, standings, etc.). The currently implemented scenes are detailed below.

Scene	Name in config.yaml scene_order	Description
🏒 NHL Games	nhl_games	Displays live NHL game scores, time remaining, etc. If the game hasn't started, start time is displayed. Can optionally display games for previous day as well.
🏒 NHL Favourite Team Next Game	nhl_fav_team_next_game	Displays next game details for all specified favourite teams. If game is today, displays start time. Can optionally be suppressed if game is in progress. Will not display anything if no favourite team is set.
🏒 NHL Standings	nhl_standings	Displays standings for wild card, division, conference, and/or overall, as configured by the user. Can optionally highlight favourite team.
🏒 PWHL Games	pwhl_games	Displays live PWHL game scores, time remaining, etc. If the game hasn't started, start time is displayed. Can optionally display games for previous day as well.
🏒 PWHL Favourite Team Next Game	pwhl_fav_team_next_game	Displays next game details for all specified favourite teams. If game is today, displays start time. Can optionally be suppressed if game is in progress. Will not display anything if no favourite team is set.
🏒 PWHL Standings	pwhl_standings	Displays overall standings. Can optionally highlight favourite team.
🏀 NBA Games	nba_games	Displays live NBA game scores, time remaining, etc. If the game hasn't started, start time is displayed. Can optionally display games for previous day as well.
🏀 NBA Favourite Team Next Game	nba_fav_team_next_game	Displays next game details for all specified favourite teams. If game is today, displays start time. Can optionally be suppressed if game is in progress. Will not display anything if no favourite team is set.
🏀 NBA Standings	nba_standings	Displays standings for division and/or conference, as configured by the user. Can optionally highlight favourite team.
🏀 WNBA Games	wnba_games	Displays live WNBA game scores, time remaining, etc. If the game hasn't started, start time is displayed. Can optionally display games for previous day as well.
🏀 WNBA Favourite Team Next Game	wnba_fav_team_next_game	Displays next game details for all specified favourite teams. If game is today, displays start time. Can optionally be suppressed if game is in progress. Will not display anything if no favourite team is set.
🏀 WNBA Standings	wnba_standings	Displays overall standings. Can optionally highlight favourite team.
⚾️ MLB Games	mlb_games	Displays live MLB game scores, current inning, outs, runners on base, etc. If the game hasn't started, start time is displayed. Can optionally display games for previous day as well.
⚾️ MLB Favourite Team Next Game	mlb_fav_team_next_game	Displays next game details for all specified favourite teams. If game is today, displays start time. Can optionally be suppressed if game is in progress. Will not display anything if no favourite team is set.
⚾️ MLB Standings	mlb_standings	Displays standings for wild card, division, and/or league, as configured by the user. Can optionally highlight favourite team.

Configuration

The scoreboard can be customized to meet your specific needs and preferences. Each scene has their own settings that can be used to fine tune behaviour. Additionally, there's general settings that apply to all scenes. The following sections details what can be edited in config.yaml to fine tune your scoreboard experience. All non hardware configuration settings can be updated without restarting the scoreboard. Scene changes will take effect the next time that scene is displayed.

General

These settings impact general scoreboard operations and are not tied to any specific scene.

Setting in config.yaml	Description	Options	Additional Notes
scene_order	Order of scenes to display. Any number and order of scenes can be specified. They should be provided as elements in a list. This scene order will repeat infinitely.	N/A, freeform	Must ensure that the correct names listed in the table above are used.
favourite_teams.<league>	Notes the users favourite team(s). Any number can be specified for each league. They should be provided as elements in a list.	N/A, freeform	Should be provided as the team abbreviation in all caps.
alt_logos.<league>	Notes if any alternative logos should be used for specific teams. A user can provide their own alternative logos by placing them in the correct teams_alt directory following the standard format. A small number of alt logos have been included.	N/A, freeform	User should provide a key value pair of team abbreviation and wanted alt logo. E.g., "BOS: 1924" would set display BOS_1924.png in place of the default logo.
brightness.brightness_mode	How the brightness should be determined.	auto (default): Automatically determine and set brightness based on the time of day. Max brightness of brightness.max_brightness is achieved at noon static: Static brightness of brightness.max_brightness
brightness.max_brightness	Max brightness that the matrix will display in any mode.	Any integer 15 ≤ x ≤ 100 Default 100
hardware_config.hardware_mappings	Hardware mapping per the rpi-rgb-led-matrix settings.	adafruit-hat-pwm (default) adafruit-hat ...	See submodule repository for more information.
hardware_config.gpio_slowdown	GPIO slowdown per the rpi-rgb-led-matrix settings.	4 (detaulf) 3 2 1 0	See submodule repository for more information.

All Scenes

These settings impact specific scenes and are found in all (most) specific scene settings. Each scene can be edited independently.

Setting in config.yaml	Description	Options	Additional Notes
...<scene>.transition	Transition that should be used when moving between scenes (or between elements in the same scene).	modern (Default): Horizontal slide with a fade to black between scene elements fade: Fade to black between scene elements without any horizontal motion cut: Simple jump cut, no animated transition	Recommend that you use the same transition for all scenes for visual consistency, but you do you.
...<scene>.splash.display_splash	If the splash should be displayed before the scene.	True (Default) False	Not relevant for favourite team next game scenes.
...<scene>.splash_display_duration	How many seconds the splash should be displayed for.	Any number > 0 Default 2	If <scene>.splash.display_splash = False, this setting is irrelevant.

Scene Specific

These setting impact individual scenes only and are (generally) unique to that scene.

Relevant Scene	Setting in config.yaml	Description	Options	Additional Notes
Games	...games.game_display_duration	How many seconds each game should be displayed for.	Any number > 0 Default 3.5
Games	...games.score_alerting.score_coloured	If when a team scores, their number should be highlighted red alerting a user to the score increase.	True (Default) False
Games	...games.score_alerting.score_fade_animation	If when a team scores, their number should fade back to white before moving to the next scene element. Will remain red if false.	True (Default) False	If score_fade_animation = False, this setting is irrelevant.
Games	...games.rollover.rollover_start_time_local	Time of day to start reporting on that days games.	Any time in 'HH:MM' format Default 07:00
Games	...games.rollover.show_completed_games_until_rollover_end_time	If games for both yesterday and today should be displayed when time is between rollover_start_time_local and rollover_end_time_local.	True (Default) False
Games	...games.rollover.rollover_end_time_local	Time of day to stop reporting on yesterdays games.	Any time in 'HH:MM' format Default 12:00	If show_completed_games_until_rollover_end_time = False, this setting is irrelevant.
Games	mlb.games.display_outs_and_bases	If outs and runners on base should be displayed for live games.	True (Default) False	Only applicable for the MLB games scene.
Favourite Team Next Game	...fav_team_next_games.display_duration	How many seconds to display the next game info for each favourite team.	Any number > 0 Default 3.5
Favourite Team Next Game	...fav_team_next_games.display_if_in_progress	If the next game should be displayed when the favourite team is currently playing.	False (Default) True	If True, the next game will be displayed with 'Ipr' in place of a date or time.
Standings	...standings.scroll.scroll_pause_duration	How many seconds to pause once a team has been fully scrolled on/off the matrix.	Any number > 0 Default 1
Standings	...standings.scroll.scroll_frame_duration	How long to wait between frames of the scroll animation.	Any number Default 0.075	The higher this number, the slower the scroll animation.
Standings	...standings.highlight_fav_teams	If favourite team(s) should be highlighted yellow in the standings.	True (Default) False
Standings	...standings.colour_sidebar	If sidebar should have a coloured stripe at the left edge to help identify the league.	True (Default) False
Standings	...standings.display_for	Which standings should be displayed (division, conference, etc.).	See options in config.yaml. Comment/uncomment lines as needed.