Step by step guide.
To be sure that you have the best performance possible, this project requires Raspberry Pi OS Lite.
This version does not have a GUI which allows the Pi to dedicate as much resource as possible to the scoreboard.
Follow these instructions to install Raspberry Pi OS Lite on your Raspberry Pi and once you are up and running comeback to
this page.
Raspbian Buster Lite Installation
Before you start installing anything, make sure your raspberry pi is set to your local time zone. Usually, you do so when you install Raspian, but if you think you skipped that part, you can change it by running sudo raspi-config
You will need to install Git on your raspberry pi in order to download the software. To do so, run this command.
sudo apt install git
This installation process might take some time because it will install all the dependencies.
git clone --recursive https://github.com/riffnshred/nhl-led-scoreboard
cd nhl-led-scoreboard/
chmod +x scripts/install.sh
./scripts/install.sh
If it's a first install of the software, there is no config.json only a config.json.sample. This is normal. You need to configure your scoreboard. Follow the steps in the Configuration section of this documentation.
git reset --hard
git checkout master
git pull
chmod +x scripts/install.sh
./scripts/install.sh
If you face any issue after updating, rerun the install and it should fix it. otherwise check the issue section to see if a solution as been found for your problem. If not open an issue and I'll find a solution.
Sometimes, the only way to fix the issues after an update is to delete and reinstall. From the nhl-led-scoreboard folder, run these commands
cd
sudo rm -R nhl-led-scoreboard
Than run the installation commands above.
note Since V1.1.2, you won't need to reconfigure your board everytime you update, UNLESS we add a major feature or we make a major update. There is 2 way to configure you board:
From the root of the nhl-led-scoreboard, run this command: ./nhl_setup. Please take a look at the documentation here: src/nhl_setup/README.md
New with v1.5.0
You can now edit your current file instead of creating a new one.
If you have no issue working with json files in a prompt, you can still configure manualy.
FIRST, you will need to make a copy of the config.json.sample and rename it config.json. Then open it and modify the options.
If it's a first install of the software, there is no config.json only a config.json.sample. This is normal. You need to configure your scoreboard. Fallow the steps in the Configuration section of this documentation.
If you have been using a Led matrix on a raspberry pi before and know how to run it properly skip this part.
If you just bought your Led matrix and want to run this software right away, first thank you. Second, don't get too excited just yet.
Depending on your setup, you will need to configure the scoreboard using specific command flags when you run it.
To do so, start by disabling the audio of the raspberry pi (this is a must to run the led matrix properly).
From the root of the pi run the following commands.
cat <<EOF | sudo tee /etc/modprobe.d/blacklist-rgb-matrix.conf
blacklist snd_bcm2835
EOF
sudo update-initramfs -u
reboot the pi
sudo reboot now
Now let's show something on the screen. Get to the matrix submodule and run some samples.
cd nhl-led-scoreboard/submodules/matrix/bindings/python/samples
sudo python3 runtext.py --led-rows=32 --led-cols=64 --led-gpio-mapping=adafruit-hat --led-brightness=60
If you've done the anti-flickering mod, use this flag instead --led-gpio-mapping=adafruit-hat-pwm
You should see "Hello World" scroll on screen.
Reference the rpi-rgb-led-matrix library. Check out the section that uses the python bindings and run some of their examples on your screen. For sure you will face some issues at first, but don't worry, more than likely there's a solution you can find in their troubleshooting section.
Once you found out how to make it run smoothly, come back here and do what's next.
This is a list of Flags you can use to optimize your screen's performance. For more details check out the rpi-rgb-led-matrix library.
--led-rows Display rows. 16 for 16x32, 32 for 32x32 and 64x32. (Default: 32)
--led-cols Panel columns. Typically 32 or 64. (Default: 32)
--led-chain Daisy-chained boards. (Default: 1)
--led-parallel For Plus-models or RPi2: parallel chains. 1..3. (Default: 1)
--led-pwm-bits Bits used for PWM. Range 1..11. (Default: 11)
--led-brightness Sets brightness level. Range: 1..100. (Default: 100)
--led-gpio-mapping Hardware Mapping: regular, adafruit-hat, adafruit-hat-pwm
--led-scan-mode Progressive or interlaced scan. 0 = Progressive, 1 = Interlaced. (Default: 1)
--led-pwm-lsb-nanosecond Base time-unit for the on-time in the lowest significant bit in nanoseconds. (Default: 130)
--led-show-refresh Shows the current refresh rate of the LED panel.
--led-limit-refresh Limit the refresh rate of the LED panel to a maximum number.
--led-slowdown-gpio Slow down writing to GPIO. Range: 0..4. (Default: 1)
--led-no-hardware-pulse Don't use hardware pin-pulse generation.
--led-rgb-sequence Switch if your matrix has led colors swapped. (Default: RGB)
--led-pixel-mapper Apply pixel mappers. e.g Rotate:90, U-mapper
--led-row-addr-type 0 = default; 1 = AB-addressed panels. (Default: 0)
--led-multiplexing Multiplexing type: 0 = direct; 1 = strip; 2 = checker; 3 = spiral; 4 = Z-strip; 5 = ZnMirrorZStripe; 6 = coreman; 7 = Kaler2Scan; 8 = ZStripeUneven. (Default: 0)
Using either a raspberry Zero, 3B+, 3A+ and 4B with an Adafruit HAT or Bonnet, here's what I did to run my board properly.
-
Do the hardware mod found in the Improving flicker section.
-
Disable the onboard sound. You can find how to do it from the Troubleshooting sections
-
From the same section, run the command that removes the Bluetooth firmware, Unless you use any Bluetooth device with your Pi.
Finally, these are the flag I use. (ONLY USE THESE FLAGS IF YOU'VE DONE THE HARDWARD ANTI-FLICKERING
MOD. If not, replace the first flag with --led-gpio-mapping=adafruit-hat).
--led-gpio-mapping=adafruit-hat-pwm --led-brightness=60 --led-slowdown-gpio=2
Once you are done optimizing your setup and configuring the software, you are ready to go.
Start by running your board and see if it runs properly. If you use the typical Pi 3b+ and HAT/Bonnet setup, here's the command I use.
If you've done the anti-flickering mod, change the --led-gpio-mapping=adafruit-hat for --led-gpio-mapping=adafruit-hat-pwm
sudo python3 src/main.py --led-gpio-mapping=adafruit-hat --led-brightness=60 --led-slowdown-gpio=2
Once you know it runs well, turn off your command prompt. SURPRISE !!! the screen stop! That's because the SSH connection is interrupted and so the python script stopped.
There are multiple ways to run the Scoreboard on it's own. I'm going to cover 2 ways. One that's a bit more hand's on, and the other will run the board automatically (and even restart in case of a crash).
Supervisor is a Process Control System. Once installed and configured it will run the scoreboard for you and restart it in case of a crash. What's even better is that you can also control the board from your phone !!!!
To install Supervisor, run this installation command in your terminal.
sudo apt-get install supervisor
Once the process done, open the supervisor config file,
sudo nano /etc/supervisor/supervisord.conf
and add those two lines at the bottom of the file.
[inet_http_server]
port=*:9001
Close and save the file.
Press Control-x
Press y
Press [enter]
Now lets create a new file called scoreboard.conf into the conf.d directory of supervisor, by running this command,
sudo nano /etc/supervisor/conf.d/scoreboard.conf
In this new file copy and past these line.
[program:scoreboard]
command=[SCOREBOARD COMMAND]
directory=[LOCATION OF THE SCOREBOARD DIRECTORY]
autostart=true
autorestart=true
Than fill in the missing information. For the command, insert the command that worked for you when you tested the scoreboard. If
you used the same as mine then this line should look like, command=sudo python3 src/main.py --led-gpio-mapping=adafruit-hat-pwm --led-brightness=60 --led-slowdown-gpio=2.
Lastly, for the directory, insert the location of the scoreboard directory. It should be something like /home/{user}/nhl-led-scoreboard. If you use the base account "pi" then
the {user} will be pi.
Now, reboot the raspberry pi. It should run the scoreboard automatically. Open a browser and enter the ip address of your raspberry pi in the address bar
fallowing of :9001. It should look similar to this 192.168.2.19:9001. You will see the supervisor dashboard with the scoreboard process running.
If you see the dashboard but no process, reboot the pi and refresh the page.
You should be up and running now. From the supervison dashboard, you can control the process of the scoreboard (e.g start, restart, stop).
To troubleshoot the scoreboard using supervision, you can click on the name of the process to see the latest log of the scoreboard. This is really useful to know what the scoreboard is doing in case of a problem.
To make sure it keeps running you will need a Terminal Multiplexer like. Screen. This allows you to run the scoreboard manually in a terminal and To install Screen, run the fallowing in your terminal.
sudo apt install screen
Then start a screen session like so
screen
Now run the scoreboard. Once it's up and running do Ctrl+a then d. This will detach the screen session from your terminal.
NOW ! close the terminal. VOILA !!! The scoreboard now runs on it's own.
To go back and stop the scoreboard, open your terminal again and ssh to your Pi. Once you are in, do screen -r. This will bring the screen session up on your terminal.
This is useful if the scoreboard stop working for some reason, you can find out the error it returns and uses that to find a solution.
Maybe you want to debug, or you have a small screen nearby that you want to use instead. You can run this in the terminal using:
sudo python3 src/main.py --terminal-mode=true
Note:
- If you want to run this straight from a raspberry pi, you will need to install a GUI and a terminal emulator that has all the colors
- If you are using a touchscreen instead of an HDMI output, make sure the proper drivers are installed