raspberry pi full setup guide

Note

This guide covers setup for a brand new Raspberry Pi.

If your pi is already up and running, you can likely jump to Step 4!

Step 1: Raspberry Pi Imager

• Download here
• Choose your Raspberry Pi
• Select Raspberry Pi OS (Other) - OS Lite (64bit)
• Set hostname (I put matrix), set pass (I kept user as pi)
• Enter wifi credentials
• Enable ssh using password
• When done, insert microSD card in pi and wait a few min for boot up

Step 2: Login via ssh

• ssh [email protected]
• This puts you in the /home/pi directory
• You can use pwd to confirm where you are throughout this process

Step 3: Update packages and install git

• sudo apt update (get latest packages)
• sudo apt upgrade (upgrade out of date packages)
• sudo apt install git
• sudo apt install vim (my preferred text editor - else replace vi with nano)

---

Step 4: Clone and enter the repo

• git clone --recurse-submodules https://github.com/kylejohnsonkj/rpi-spotify-matrix-display
  • the rpi-rgb-led-matrix submodule will be installed as a python module later
• cd rpi-spotify-matrix-display/

Step 5: Update config.ini with Spotify credentials

• Review Spotify Pre-Setup
• vi config.ini
• Adjust hardware_mapping and other options if necessary
  • https://github.com/hzeller/rpi-rgb-led-matrix?tab=readme-ov-file#changing-parameters-via-command-line-flags
• For vim: edit by tapping i, tap esc then enter :wq to save

Step 6: Create a python virtual environment

• python3 -m venv .venv
• source .venv/bin/activate
  • You should now see (.venv) before your shell prompt
• use which python3 to confirm path
  • should be /home/pi/rpi-spotify-matrix-display/.venv/bin/python3

Step 7: Install requirements using venv python3

• sudo .venv/bin/python3 -m pip install -r requirements.txt
  • Must use sudo as matrix will run at root level
  • https://stackoverflow.com/a/66410467/12821693

Step 8: Install rgbmatrix python module (follow exactly!)

• sudo apt install python3-dev cython3
• cd rpi-rgb-led-matrix
• make -C bindings/python/rgbmatrix -B CYTHON=cython3
• make
• cd ../impl
• sudo ../.venv/bin/python3 -m pip install ../rpi-rgb-led-matrix/bindings/python --use-pep517

Step 9: Disable sound card and isolate cpus

• sudo vi /etc/modprobe.d/alsa-blacklist.conf, add “blacklist snd_bcm2835”
• sudo vi /boot/firmware/config.txt, set “dtparam=audio=off”
• sudo vi /boot/firmware/cmdline.txt, add “isolcpus=3"
• sudo reboot
• ssh back in once rebooted

Step 10: Run the controller

• cd rpi-spotify-matrix-display/
• source .venv/bin/activate
• cd impl/
• sudo ../.venv/bin/python3 controller_v3.py
• After running, follow instructions provided in the console. Pasted link should begin with http://localhost:8080/callback
• After successful authorization, play a song and the display will appear!

---

Tip

You can enable the matrix to run automatically when your pi boots up. Just follow the steps below!

Step 11: Setting up autostart at login

• sudo vi /etc/systemd/system/matrix.service
• Paste the following contents:

[Unit]
Description=rpi-spotify-matrix-display

[Service]
WorkingDirectory=/home/pi/rpi-spotify-matrix-display/impl
ExecStart=/home/pi/rpi-spotify-matrix-display/.venv/bin/python3 /home/pi/rpi-spotify-matrix-display/impl/controller_v3.py

[Install]
WantedBy=default.target

• sudo systemctl start matrix
• sudo systemctl enable matrix (enables autostart)

Step 12: Add aliases for fun

• cd /home/pi/
• vi .bash_aliases, add alias matrix='sudo service matrix'
• source .bash_aliases
• Now you can type matrix start, matrix stop, matrix restart!