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.

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:

(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:

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:

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:

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

Look for these two lines, starting around line 76:

Change these to:

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):

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:

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…

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:

Save this file and exit the editor.

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

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.