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 adafruit.com” 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

cd
curl https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/pi-eyes.sh >pi-eyes.sh
sudo bash pi-eyes.sh

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 TFT screens:

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

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 Aug 13, 2018 Published on Jan 11, 2017