PLEASE NOTE: the steps in this page currently DOES NOT WORK on the new Raspberry Pi 4 due to lots of changes in the graphics subsystem. We have a work-around toward this, discussed on
You must use the latest version of Raspberry Pi OS Lite

Start by downloading the current version of the Raspberry Pi OS Lite operating system from the Raspberry Pi web site, then write this to a 2GB or larger micro SD card using Etcher, Raspberry Pi Imager, or similar software.

Use latest Raspberry Pi OS Lite for this project. Full-featured Rasperry Pi OS won't work, and older versions won't work.

If your target system is a Raspberry Pi Zero, you may find the setup process easier with a spare full-size Raspberry Pi board such as a Pi 3, Pi 2 or Model B+, 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.

Setup will require:

  • USB keyboard
  • HDMI monitor
  • Network, one of:

Insert the micro SD card, connect monitor and USB keyboard (and Ethernet cable, if using a wired network) and power up the board. The system will reboot once shortly after the first boot; this is normal as it readies the SD card. Then, on second boot…

Log in as user pi, with password raspberry. Then run the raspi-config tool for some initial setup…

sudo raspi-config

The following options are recommended:

  • Change User Password.
  • Under “Internationalisation Options,” select “Change Keyboard Layout.” If you’re getting unexpected characters from the keyboard, this is usually why.
  • Under “Advanced Options,” select “SSH” and enable it. This lets you log into the system using a terminal program across the network, so you won’t need the keyboard and monitor in the future.

Next step is to get the Pi on the network. If using wired Ethernet, it’s usually a simple matter of plugging it in. For WiFi, this tutorial can offer some guidance…specifically the “Setting Up WiFi on the Command Line” page.

You may need to reboot once or twice during the above setup procedures; this is normal. Do not continue until the Pi is networked. You can test with “ping” or similar.

The next part may be easiest if you log in remotely using ssh; this allows you to copy-and-paste from this browser window into a terminal. If not, that’s okay, log in using keyboard and monitor and type in this next part very carefully…

Pi-Eyes Software Options

Run the following at the command line

curl >
sudo bash

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…

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

Select TFT if you have Product #2088


The 1.44" 128x128 plain TFT

Select IPS if you have Product #3787


The 1.54" 240x240 IPS TFT

Select OLED if you have Product #1431


The 1.5" 128x128 color OLED

  • 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?”
It can take an extremely long time to download, build and install everything — ESPECIALLY NUMPY! Even on a Pi 3 B+ it might take 15 minutes or more. Be patient, it’s working.

The installer has to collect software packages from all over the world. Very infrequently, a server or connection might be down. 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”, typing the full command that appears there manually each time you want to start the code.

IT’S NORMAL THAT THE EYES MAY EXHIBIT “GLITCHES” ON THE FIRST TRY. We’ll fine-tune some parameters to get them working right.

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:

cd /boot/Pi_Eyes
sudo killall fbx2

The displays will stop updating. This is normal.

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

sudo ./fbx2 -o -b 8000000

Or, for TFT displays, try:

sudo ./fbx2 -t -b 10000000

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…

sudo nano /etc/rc.local

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

/boot/Pi_Eyes/fbx2 -o &

(or “-t” if using TFT displays)

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

/boot/Pi_Eyes/fbx2 -o -b 8000000 &

Save changes and exit the editor. Then:

sudo reboot

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.

This guide was first published on Jan 11, 2017. It was last updated on Jan 11, 2017.

This page (Software Installation) was last updated on Oct 23, 2021.

Text editor powered by tinymce.