Glad you’re here! The Raspberry Pi code has all the bells and whistles. This will be discussed in a moment, but first…

System Setup

Basic Raspberry Pi setup is already covered in other guides… so if this is your first time, start there. You can do these initial steps with the Pi outside the case and without the matrices wired up.

Pi power users may have their own setup ritual, but for most folks we recommend using Raspberry Pi Imager to create a bootable micro SD card.

Choose “Raspberry Pi OS Lite (32-bit)” as the operating system. If you require a GUI, use “Desktop (32-bit)” instead…but see prior notes that the HDMI ports may be inaccessible once in the case. Avoid the 64-bit OS versions for now…these are cutting-edge and often problematic.

Click the gear icon, or press Control+Shift+X (Windows) or ⌘+Shift+X (Mac), to show advanced options. Essential system info (hostname, WiFi network, etc.) can all be configured before the system is even booted the first time…it’s so much easier this way! Tip: remember to also set the Wireless LAN country to get WiFi working.

So suppose at this point you have a Raspberry Pi that’s booted and accessible via an ssh remote session…

Prerequisite Software and Setup

First is to edit the system /boot/config.txt file, which must be done as root via the “sudo” command:

sudo nano /boot/config.txt

(You can substitute your editor of preference in place of “nano.” I’m strange and actually like vi.)

Append the following two lines to the end of the file. Just copy-and-paste them verbatim, as the syntax is very persnickety:

dtoverlay=i2c-gpio,bus=2,i2c_gpio_scl=17,i2c_gpio_sda=27,i2c_gpio_delay_us=1
dtoverlay=i2c-gpio,bus=3,i2c_gpio_scl=23,i2c_gpio_sda=24,i2c_gpio_delay_us=1

Save changes to the file. This will enable two “soft” I2C buses on specific GPIO pins. You can use different pins if both the software and wiring are changed to match, but don’t do this unless other hardware you’re interfacing specifically demands it. Most users should stick with the plan.

Extra Steps for the Audio Visualizer Only

This optional part of the project requires the Mini USB Microphone mentioned on the Overview page. If you don’t have this part or don’t want the visualizer, you can skip ahead to “Continue Setup” below.

We’ll do the audio setup before the other software, as it then requires fewer reboots.

Enter these commands:

sudo apt-get install python3-pip libatlas-base-dev libportaudio2
pip3 install numpy pyaudio

Answer “Y” when asked about installing packages.

Following installation, one must then edit the system’s ALSA configuration, which is related to sound input and output:

sudo nano /usr/share/alsa/alsa.conf

(As before, substitute your editor of preference in place of nano.)

Look for these two lines, starting around line 76:

defaults.ctl.card 0
defaults.pcm.card 0

Change these to:

defaults.ctl.card 1
defaults.pcm.card 1

Save changes to this file and exit the editor.

Continue Setup

With or without the audio visualizer, all installations will require the following sequence of commands (please use the “Copy Code” button and paste into the Pi’s terminal window…some of these are single long lines that might appear wrapped here):

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install python3-pip libopenjp2-7 subversion
sudo pip3 install --upgrade setuptools adafruit-python-shell psutil adafruit-extended-bus adafruit-circuitpython-is31fl3731 pillow
wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/raspi-blinka.py
sudo python3 raspi-blinka.py

Answer “Y” when asked about upgrading or installing packages.

That last step—the raspi-blinka.py script—will ask to reboot the system when finished. Play along, answer “Y,” and log back into the system once it’s rebooted.

FYI: Blinka is a package for running CircuitPython (microcontroller) code on “real” computers like Raspberry Pi. It allows leveraging hardware-specific libraries for talking to the LED matrices, for instance. Pretty cool. There’s an entire guide if you’d like to learn more.

Download Project Code and Test

All the system configuration is done, and now to fetch the project code:

svn export https://github.com/adafruit/Adafruit_Learning_System_Guides/trunk/LittleConnectionMachine
cd LittleConnectionMachine/RaspberryPi

Start with the simplest of the examples, some animated lights inspired by the CM-5 control room computer in Jurassic Park:

python chaser.py

If all goes well, this will simply run, lighting all 8 matrices with animated bit patterns. Press CONTROL+C to stop.

If you’re seeing a RuntimeError or ValueError message from the system, it’s usually one of these things:

  • An SDA/SCL wire pair is swapped, either on the Raspberry Pi header or on one or more matrices.
  • SDA and/or SCL are connected to the wrong pin(s).
  • Address select pads on one or more matrices are not correctly set; multiple matrices on the same I2C bus are set to the same address.
  • A poorly-soldered connection in one of the 4-way splitters.

Remember there are two I2C buses at play here, each with four matrices, each of which should have a unique address on that bus.

For posterity, here’s that wiring diagram again:

From a programming perspective, chaser.py is the simplest of the examples, as it doesn’t tie into any obscure system services…it just animates the lights. If creating your own programs for the Little Connection Machine, this is a good starting point.

Then there’s the classic supercomputer blinkenlights:

python cpuload.py

The amount of pixels lit is proportional to the current system workload. Left running in the background…when compiling and debugging two million lines of code to run a dinosaur theme park, you’ll see this really light up! CONTROL-C to stop.

If you have the USB microphone installed and did the extra setup earlier, you can try the third example:

python audio.py

This will react to music and sounds within earshot…higher frequencies toward the top of the matrices, lower frequencies toward the bottom. CONTROL+C to exit.

If this fails to run, double-check the ALSA configuration that was described earlier. It’s notoriously picky.

If this runs but the image appears jumbled, the LED matrices are arranged in the wrong order. The wiring diagram shows the address for each matrix.

Auto-Starting on Boot-Up

The preferred way to do this nowadays is via the systemd service. Begin by creating a unit file for this service…

sudo nano /lib/systemd/system/cm1.service

Copy-and-paste the following into the new file, editing the “ExecStart” line to reference which of the Python scripts you’d like to run. Can also change the directory name, if you’ve moved or called it something else:

[Unit]
Description=CM-1 Service
After=multi-user.target

[Service]
Type=idle
ExecStart=/usr/bin/python /home/pi/LittleConnectionMachine/RaspberryPi/chaser.py

[Install]
WantedBy=multi-user.target

Save this file and exit the editor.

A few commands then enable this new service and will launch it on startup:

sudo systemctl daemon-reload
sudo systemctl enable cm1.service
sudo reboot

To change which program is loaded on startup, just edit /lib/systemd/system/cm1.service and change the ExecStart line, and reboot. No need to repeat the systemctl commands.

This guide was first published on Apr 19, 2022. It was last updated on 2022-04-19 18:34:16 -0400.

This page (Code (Raspberry Pi)) was last updated on May 24, 2022.

Text editor powered by tinymce.