We’ll start by installing a suitable version of Raspberry Pi OS onto a SD card. If this is your first time or you need a refresher, we have a separate guide explaining the process (opens in new window).

If using a Raspberry Pi 4, Pi 400, or Compute Module 4: the latest "Bullseye" Raspberry Pi OS Desktop software is required (“Lite” versions, and versions prior to “Bullseye” in late 2021, won’t support this code on these boards). For brevity, we’ll call all of these boards “Pi 4” going forward in this guide.

All other Raspberry Pi boards: Raspberry Pi OS Lite (Legacy) software is required. Look for both Lite and Legacy in the name!

For all boards: use the 32-bit version of the operating system, not the 64-bit variant.

If your target system is a Raspberry Pi Zero, you may find the setup process easier with a spare full-size Raspberry Pi board with Ethernet and/or USB, then move the card over to the Pi Zero when finished. If this is not an option, see this guide for steps to make the Pi Zero act as a “USB Ethernet gadget,” and also create a file called “ssh” in the boot volume to enable ssh login.

If using the Raspberry Pi Imager application: from the “CHOOSE OS” menu, select a compatible operating system version as described above. Before writing the card, see “Enable SSH” below.

If using Balena Etcher or other application: download a compatible operating system image from the Raspberry Pi web site (opens in new window). After writing the card, see “Enable SSH” below.

In either case, use the correct OS for the target system, as described earlier.

Enable SSH

It’s usually easiest to set up and install this project remotely over a network, so you can copy-and-paste commands from this page to the command line.

If using the Raspberry Pi Imager application: before writing the card, press Control+Shift+X (Windows) or Command+Shift+X (Mac) to open the Advanced Options menu. Here you can Enable SSH for remote access. If you want to set up WiFi instead of a wired Ethernet connection, those options are also in this menu. Now you can write the card!

If using Balena Etcher or other application: after writing the card, don’t eject! Create an empty file called ssh in the /boot partition. This will enable SSH over a wired Ethernet connection. If you want WiFi, you’ll have to connect temporarily with Ethernet and configure wireless through raspi-config…or see below.

A third option—and required if you only have WiFi but no Ethernet—is to do this on the Raspberry Pi after first boot, with monitor and keyboard connected. The raspi-config utility includes options for enabling WiFi and SSH. Then the rest of this installation can be done remotely.

Once your Raspberry Pi is powered up and connected to a network you can follow the steps below to install the Pi Eyes software.

If you're familiar with connecting to the Raspberry Pi over SSH you can use an SSH terminal application to connect and skip down to the install commands section below.

Install Commands

Run the following at the command line:

This downloads and runs a script which installs all the prerequisite software and does some system configuration. It will ask a few questions along the way…

• Is the target system a Pi 4-type board, or something else? Target system is an important distinction here — this refers to the Pi board where this SD card will ultimately be used, if it’s different from the one where you’re currently installing.

• Will you be connecting OLED (128x128), TFT (128x128) or IPS (240x240) displays? Can’t mix and match; must be one or the other. (There’s also an HDMI option — see the “Using Just the Software” page for guidance.)

These are the screen types:

• The GPIO-halt utility performs an orderly shutdown using a momentary pushbutton between an unused GPIO pin and ground, no login required. If you don’t have a button and plan to shutdown the system the usual way, answer “n”.
• Will you be connecting ANALOG input devices like a JOYSTICK or LIGHT SENSOR? If so, answer “y” when asked “Install ADC support?”

There’s one final confirmation before installation, explaining the steps that will be taken and making it extra clear that the Pi will be dedicated to this one task, it should not be installed on a “daily driver” computer that you use for real work.

The installer has to collect software packages from all over the world. Very infrequently, a server or connection might be unreachable. If this happens, or the script “hangs” mid-download, set the project aside for a couple hours and try again later.

Dry Run

Reboot when prompted by the software installer. When the system restarts, after a minute or so, you should see some activity on the display(s).

The eyes run automatically on every startup; it is a dedicated system. If you don’t want that, you’ll need to edit /etc/rc.local and remove or comment out the line that includes “python3 eyes.py”, typing the full command that appears there manually each time you want to start the code.

If everything seems to be working well, you can skip ahead to the next page and ignore the steps below.

If the eyes are experiencing glitches (video snow, tearing, dropped frames or weird inverted colors), here’s what to do…

Log into the Pi remotely using ssh. Then type the following commands:

The displays will stop updating. This is normal.

Then, if you have OLED displays, type the following:

Or, for TFT displays, try:

The first argument (-o, -t or -i) sets the display type in use; OLED, TFT or IPS, respectively. Second argument (-b) sets the maximum bitrate for the displays. The higher the bitrate, the smoother the animation…but…there’s a limit to how fast this can go, and it can vary with wire lengths, connections, environment (such as interference from other nearby devices) and even slight manufacturing variances from one display to the next.

For OLED displays, the default bitrate is 10000000 (10 MHz). For TFT displays, default is 12000000 (12 MHz). IPS uses 96000000 (96 MHz) by default. But if there’s trouble, we have to dial these back.

Try a lower value, like the 8 MHz or 10 MHz examples above. Watch the output for a minute…does it seem to have stabilized now? If only one of the two displays glitches, you’ll still need to work the speed down until both run reliably.

Press Control+C to kill the program and test again with a different bitrate…maybe work down 4 MHz at a time, then up 1 MHz at a time until you find the “sweet spot” between speed and reliability. Once you find it, Control+C again and let’s make the change permanent…

A couple lines from the bottom you’ll find this:

(or “-t” if using TFT displays)

Insert the additional -b and bitrate value before the & character:

Save changes and exit the editor. Then:

After a minute or so the eyes should come up again, glitch-free this time. If not, repeat these steps again, trying a lower bitrate until you find a setting that works reliably.

Another way to reduce glitches is to solder ribbon cables directly between the bonnet and displays, with no headers or plugs in-between; every intermediary part is an opportunity for noise or connection problems. Consider this if you plan on permanent installation.