Software Installation

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

Use Raspbian “Lite” for this project. Full-featured Raspbian is weighted down with things we don’t need here.

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…

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, TFT or IPS 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.)
  • Do you want to install the gpio-halt utility? With a button wired between a GPIO pin and ground, this initiates an orderly shutdown (Linux systems hate it when you just pull the plug).
  • Do you plan to use the ADC (analog-to-digital converter) pins on the bonnet? This is for extras light joysticks or light sensors.
  • If your target system is a Pi Zero, do you want to enable USB Ethernet gadget support? This lets the Pi Zero share a host computer’s network connection over a USB cable…you can also log into the Pi using ssh. Or you may have already enabled this with directions above.

After a confirmation step, the script goes about its business, which may take 20 minutes or more…some parts of the software are pretty complicated to install! It’s also possible the script may time out during the “numpy” install if the software server is responding slowly. If that happens, just run the script again.

You’ll see some compiler warnings as the script runs. This is normal.

When it finishes, you’ll be asked if you want to reboot the system. Enter “Y” to reboot or “N” if there’s further work you want to do first (wrap up later with “sudo reboot” or “sudo shutdown”).

If the bonnet and displays are attached, you should see animated eyes (or something close to it) following the reboot. It may take about a minute to start up, depending on the Pi model and SD card speed. If using the HDMI option, you’ll see a single animated eye and can disregard the steps below.

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.

Last updated on 2018-05-23 at 09.13.56 PM Published on 2017-01-11 at 05.41.14 PM