We’ll be installing the Raspbian operating system on the Pi in a moment. If you don’t have the latest version downloaded, you can get that started and then work on the hardware bits while it transfers…

It’s about a gigabyte and will take a while. If you don’t have access to a fast broadband connection, we do offer Raspbian pre-installed on a microSD card.

After downloading, the OS can be installed on a microSD card using the directions in this guide.


Assemble the Pi HAT using the directions in this guide. This requires a bit of soldering. Make sure you get the HUB75 connector (the 8x2 pin socket) pointed the right way!

Install the HAT on the Raspberry Pi and connect the ribbon cable between the matrix and HAT. There are two sockets on the back of the matrix (to allow “chaining”)…but they’re not always labeled. If not, look for the arrows showing the direction of data from IN to OUT.

With the HAT installed, USB power for the Pi is usually not required, unless you have power-hungry USB peripherals connected. For most situations the single 5V barrel jack on the HAT will work for both the matrix and Pi.

System Configuration

Insert the microSD card containing the Raspbian OS and plug a monitor and keyboard into the Raspberry Pi. (The monitor and keyboard are only used during setup — later the system can be run “headless.”)

On first boot, the raspi-config utility will run automatically. Select the following options:

  • Expand Filesystem
  • Change User Password
  • Internationalization Options:
    • Change Locale
    • Change Timezone and…
    • Change Keyboard Layout to suit your language and location preferences
  • Advanced Options:
    • Hostname — assign the system a unique name (e.g. “nextbus”) to distinguish it from other Raspberry Pis on the network
    • Memory Split — since we’ll be using the system “headless,” this can be set to 16 MB to maximize the RAM available to the CPU
    • SSH — again, because it will be a headless system, enabling this will help later when administering the system remotely via network
    • I2C can optionally be enabled if you plan to use the RTC feature of the Matrix HAT (or example code doesn’t use it, but maybe you have projects in mind).

Tab to the “Finish” button and reboot the system when prompted.

Configure Networking

If using a wired Ethernet connection, there’s nothing to do here…skip to the next heading below.

The easiest way to get wireless networking set up is to type “startx” and then use the mouse-driven visual tool with a nice GUI — the icon is right on the desktop. This guide explains wireless network configuration, including command-line (keyboard-only) options.

It’s a little more challenging with a Model A+ Raspberry Pi, with only a single USB port. One option there is to use a powered USB hub during setup, so you can have WiFi, keyboard and mouse all connected. An alternative, if you have a Model B+ board available, is to move the micro SD card over and do the configuration on that system, then move the card and USB WiFi adapter back to the A+, which should now be able to boot headless and connect to the network.

Don’t continue until you have a system that boots and can connect to the internet (e.g. ping

Install Prerequisite Software

Once WiFi is active (or you’re using Ethernet), log in and enter the following to install some prerequisite packages:

sudo apt-get update
sudo apt-get install netatalk python-dev python-imaging

netatalk enables Bonjour networking, so the system is accessible as “nextbus.local” (or whatever hostname you assigned) on your network instead of just an IP address number.

python-dev and python-imaging are necessary packages for using the RGB LED matrix.

Download and Install Matrix and NextBus Software

git clone
cd rpi-rgb-led-matrix
cd ..
git clone
cd Adafruit-NextBus
ln -s ../rpi-rgb-led-matrix/ .

You can test the matrix and network connection with:

sudo python

On the next page we’ll configure this software for our own bus routes of interest.

If there’s no response from the LED matrix…

Try one of the test programs in the rpi-rgb-led-matrix directory, for example:

sudo ./led-matrix -D 0 -c 2

If this throws up an error message, something’s not correctly installed or compiled. Check all of the steps above.

If the software runs without complaint but nothing appears on the LED matrix, check the following:

  • Are the power wires connected to both the matrix and the Pi HAT with the correct polarity? (Red to +, black to )
  • Check for the green power LED on the Pi HAT.
  • Is the ribbon cable connected to the INPUT socket on the matrix? It’s not always labeled…check for the arrows showing the direction of data from IN to OUT.

If everything looks OK but won’t run, check the Adafruit Forums…you can search to see if similar topics have come up before, or post a new thread. A description of the symptoms, steps you’ve tried, and some clear photos of the wiring are all helpful for troubleshooting.

Optional: Shutdown Button

Linux systems don’t like to have the power cord yanked. If you need to do maintenance on the hardware, the system should be cleanly halted first…tricky if there’s no keyboard and monitor attached. There are a couple of options:

  • Network login via ssh, then use the shutdown command.


  • Add a momentary pushbutton between an unused GPIO input and GND, then install software to initiate a shutdown when pressed.
git clone
cd Adafruit-GPIO-Halt
sudo make install
sudo vi /etc/rc.local

(You can substitute your editor of preference instead of 'vi' on that last line)

Before the final 'exit 0' line, insert this additional line:

/usr/local/bin/gpio-halt 25 &

GPIO pin #25 is available and is close to the extra GND connections on the Matrix HAT. Solder a momentary pushbutton between those two points. If installed in a case, run wires to an exterior button.

A few other pins could be used instead, as listed in the RGB Matrix HAT guide. Change the pin number passed to gpio-halt in /etc/rc.local to match.

Reboot to activate the changes in rc.local.

sudo reboot

You should now be able to tap the button to initiate a clean shutdown. Allow 15-20 seconds for this sequence to complete before disconnecting power.

This guide was first published on Mar 01, 2015. It was last updated on Mar 08, 2024.

This page (Pi Setup) was last updated on Feb 26, 2015.

Text editor powered by tinymce.