Before diving too deep into the software, there are some gotchas to be aware of…

• Do not install the Adafruit_GFX, Adafruit_SSD1351 or Adafruit_ST7735 libraries offered by the Teensyduino installer! Use the Arduino Library Manager or install these manually from Github code. The Teensyduino-installed libraries sometimes diverge from the latest Adafruit code and might prevent this project from compiling.
• When first building this project, please test initially with the canonical “Uncanny Eyes” sketch linked later in this guide, not anyone’s derivative code. This will help with any troubleshooting/support. Once the default code works, then you can try out variants that may be out there.

Teensy uses the Arduino environment for programming, so it’s pretty familiar and simple to work with, but it does require a little extra setup first…

If you’re not using a recent version of the Arduino IDE (1.6.5 or newer), this would be a good time to upgrade. Once you have that software installed and working, download and run the Teensyduino installer, which adds support for the full line of Teensy microcontroller boards in the Arduino IDE (but remember, don’t install the display/graphics libraries there…use the Arduino Library Manager instead).

From the Tools menu, select Board→Teensy 3.2 and CPU Speed→72 MHz (and whatever optimization settings you’d like). Confirm that you can compile and upload the classic “blink” sketch to the Teensy board. Don’t use the 96 MHz setting; the code actually performs a bit better at 72 MHz (due to SPI settings).

Using the Arduino Library Manager (Sketch→Include Library→Library Manager…) install Adafruit_GFX, Adafruit_BusIO and Adafruit_ZeroDMA, plus the library compatible with your display: Adafruit_SSD1351 for the OLED display, Adafruit_ST7735 for TFT LCD.

(If you’re still using an oldschool version of the Arduino IDE, these libraries can be fetched from Github: Adafruit_GFX, Adafruit_BusIO, Adafruit_SSD1351, Adafruit_ST7735 and installed manually.)

Finally, there’s the sketch code itself:

The sketch is utterly ginormous. In addition to several hundred lines of code in the main sketch, arrays containing graphics take up most of the space in the microcontroller’s flash program space.

Before uploading to the board, check lines 56 and 57 in the file config.h:

One line is enabled, the other is commented out. By default, OLED is used. Comment out the opposite line if using TFTs.

If using all the same wiring as the previous page, it should be possible to compile and upload to the board and see some results…you should at least see an eye doing something. (If you changed the wiring, skip ahead to the next section below to make the code match, then return here.)

Still having trouble? Start a new thread in the Adafruit forums describing the symptoms. It’s extremely helpful if you can provide in-focus and well-lit photos that clearly show all the connections between the display and Teensy.

Changing Appearance, Wiring and Inputs

Basic customization — enabling or disabling certain features, or changing pins assigned to functions — is done by editing the file config.h (it’s the second tab when the code is open in the Arduino IDE).

First section of this file controls the appearance of things.

The software includes a few ready-made eyes that can be used by simply enabling the corresponding #include line — remove the comment (//) at the start of that line, and make sure all the others are commented out. The stock sketch has “defaultEye” enabled:

Just above the eye selection is this line, disabled by default:

Normally the software renders the two eyes with distinct left and right shapes (there’s a caruncle — that corner area near the tear duct). Some projects only use a single eye and this shape just seems odd. Enabling SYMMETRICAL_EYELID uses a simpler “football shape” that’s neither left nor right…it’s a bit cartoonish but may look better on single-eyed creatures.

A little further down is a list indicating the pins used for each eye. The software can handle any number of eyes (it splits up time between them), but will usually be two (or, if compiling this for the Hallowing board, there’s just one):

Each line contains three items: the pin that’s connected to the corresponding display’s OC (OLED chip select) or TCS (TFT chip select) pin, and another pin where a button (connected to ground) makes that eye independently wink. If you don’t want or need this wink control, the second pin value can be set to -1. Third item on each line is a rotation setting (0–3) for that screen:

• 0 is the default orientation, with the display’s connector at the top.
• 1 rotates the graphics 90 degrees clockwise (compensating for a display that’s installed 90° counterclockwise, with the connector at the left).
• 2 rotates the display 180° (as on the Hallowing board).
• 3 rotates 90 degrees counterclockwise (compensating for a display with the connector at right).

The stock code, as shown above, has two eyes. To work with just a single eye, comment out or delete one of the two lines. In the Hallowing case (if ADAFRUIT_HALLOWING is defined), this is already done (notice also the rotation value of “2,” because the Hallowing screen is oriented upside-down).

As previously explained, the next section decides whether to use the library for OLED or TFT displays, by #including one or the other:

After this, two lines indicate the pins used for the displays’ DC (data/command) and RESET signals:

If the project involves multiple eyes, these lines should fan out from the microcontroller to ALL displays; unlike the select pins above, which are unique to each display.

The Hallowing board has a different set of pins already defined, plus some extra items for backlight control.

The last section configures various controls:

JOYSTICK_X_PIN and JOYSTICK_Y_PIN (here set to A0 and A1, respectively) state where the joystick inputs are connected. By default, these lines are commented out — the eye moves autonomously, without user input. If you have a joystick connected, enable these two lines. (X_FLIP and Y_FLIP reverse the input direction if needed)

TRACKING sets whether the upper eyelid follows the pupil (as actual eyes do, it’s a neat thing). You can turn this off by commenting out this line.

LIGHT_PIN states where the photocell or dial is connected for adjusting the size of the pupil/iris. LIGHT_PIN_FLIP reverses the direction, like the joystick settings (lower values should be darker). LIGHT_MIN and LIGHT_MAX are the minimum and maximum reliable readings from the sensor (it might occasionally go below or above these, but it's rare, probably noise that can be disregarded), while IRIS_MIN and IRIS_MAX control the dilation of the pupil in response to the light reading (smaller numbers = smaller pupil, range is 0 to 1023).

IRIS_SMOOTH filters the input from LIGHT_PIN so it’s not twitchy. This slows the reaction time, but the movement is similar to real eyes, pretty nifty.

BLINK_PIN specifies a pin where a button is connected for blinking both eyes simultaneously (distinct from the individual left/right wink pins previously discussed). If you don’t have a button connected for this, the line can be commented out or the value set to -1.

AUTOBLINK (enabled by default) makes the eyes automatically blink randomly every few seconds. You can comment this out to make the eyes only blink with the buttons…or you can use both in combination.

If the example eyes don’t deliver quite what you need, it’s possible to generate new header files with custom graphics…

Before diving in, give some thought to how you’ll be using this.

At the very least, this project uses a Teensy microcontroller and a display or two. The animation effects are all capable of running autonomously if need be, or there are options to have them manually controlled. The method of assembly is also open to interpretation.

If you’re making a spooky prop to sit in the window on Halloween, but plan to disassemble it afterward and use the parts in other projects, you can use a breadboard and jumper wires for quick assembly and re-use.

For something portable, like jewelry or a costume piece, soldering wires directly between components is vital — both for space savings and for durability.

If creating eyes for a puppet, you probably want manual controls for nearly everything, as that’s the very nature of puppetry.

For a costume, I think autonomous works better. Good cosplay is all body language…but when electronics are added, fantastic characters are spoiled when the performer is focused on modes and buttons. But hey, it’s up to you.

Give it some thought. I’ll wait!

Connections

Many configurations of this project are possible, depending on the features you’re after. Rather than a single complex wiring diagram, a few subassemblies are illustrated here…pick and choose to match your needs.

What’s shown here are schematic diagrams — they indicate where to connect wires, but not necessarily their exact actual layout or lengths when you build the thing. You’ll need to think how everything fits in your own setting. Using color-coded wires helps a lot here!

We’ll be referring to several pins by name or number, so here’s a pin map for the Teensy 3.1 or 3.2 microcontroller:

This is a simplified pinout to clarify things specifically for this guide. If you plan to add your own advanced bells and whistles, a more complete pinout map is available on the PJRC web site.

Ground connections are vital for distributing power throughout the circuit. In addition to the two GND pins labeled here, there are two copper pads on the back of the board — one near the center, and a second large one near the USB port (next to the GND pin).

The AGND pin provides a cleaner ground reference specifically for analog inputs — this is not a current-carrying pin for distributing power, do not connect the displays here.

Some of the pin numbers we’ll be referencing are negotiable…if you find that a different pin would make routing wires easier, there’s usually a setting in the code that can be made for it. Anything related to power or SPI is not negotiable…those wires must go to the pins stated.

Power

If you have an opportunity to power everything from the Teensy’s USB port (running a USB cable to a power bank or wall charger), that’s easiest and reduces parts and steps.

The most compact, portable installations may optionally want a built-in Lithium-Polymer (LiPoly) battery. If your project uses one or two TFT LCDs, a 150 mAh battery may suffice (though a larger capacity will provide a longer run time). For one or two OLEDs, a 500 mAh battery is the minimum size.

When you cut the trace on the Teensy board, it won’t run from USB power until the LiPoly backpack is connected and switched on. This is normal. If a sketch won’t upload on a half-built project, this may be the reason why.

Power the display(s) from the BAT+ (corner) pin. If you're not using the LiPoly backpack (powering off a USB cable instead), that’s okay — by default this pin also connects to USB+.

Displays

You have a choice of using one or two displays, either OLED or LCD. But you can’t mix one of each — both must be the same type.

OLED displays have brighter colors and contrast. Downside is the price, and also that they flicker a little when captured on video. They also have a finite lifespan, albeit many thousands of hours.

TFT LCD displays are more affordable. Not as bright, but still a good effect. And they’re rock-steady on video.

If making two eyes, both displays need to connect to the same SPI MOSI and CLK pins on the Teensy, plus a few other wires. The “OC” or “TCS” pins are unique to each display, left or right.

“Left” and “right” eye in this case refer to the positions when looking at the eyes, not from their point of view. This nomenclature is used throughout this guide and in the software.

If you’re using them, the 3D-printed enclosures have a small notch that’s just wide enough for a 7-conductor ribbon cable to fit through. Space inside is really tight (I wanted them to fit inside a mask), so it’s necessary to route these wires to their pins very carefully so they lie as flat as possible on the back of the board, not all piled up. It’s delicate work that requires tweezers and patience.

If using a ribbon cable as shown above, write down your own legend that maps wire colors (or wire numbers if single-colored cable) to pin functions.

Because the cable colors are in a fixed order and there’s little space to reroute inside the case, certain wiring conventions used in electronics (such as using red wire for positive voltage and black for ground) no longer apply…you’re forced to take what you’re given. What’s more, with wires doubled back, the conductors along the ribbon don’t necessarily match the order along the display breakout header, it’s all jumbled now.

Do not use our photos for reference. Do not rely on the colors shown in any diagrams here. Write down the exact sequence for your cable and your routing, and use only that for reference, nothing else.

If you’re not using the 3D-printed enclosures, everything is much simpler. You can just connect to the pins in-order, there’s no space constraint that must be met.

The displays arrive with a plastic sheet on them. Keep this in place when soldering, but remove it once you’re done. This isn’t like a phone screen protector, just for shipping and soldering protection.

The display breakout boards include microSD slots, but those are not wired up in this project and the code doesn’t reference them at all. Advanced users who want this capability can connect the SPI MISO and card select pins (you’ll need to modify the enclosure slightly to accommodate the extra wires) and make the required changes in the code.

Analog Controls

Any analog controls that are used should include connections to the 3.3V and AGND pins. Don’t use the other power pins or there will be…trouble.

Buttons

The eyes normally blink autonomously, but you can also add one or more buttons to make them blink (or even wink individually) on command.

Pro tip: a fully-equipped version of the circuit requires several ground connections, but there are only a few GND pins on the Teensy board. Two- or three-way splices are one option, but another way to provide extra ground connections is to repurpose unused I/O pins. Let’s suppose you want to make Digital Pin 4 a spare ground pin. Add the following code in the setup() function:

OUTPUT LOW makes the pin function as an ersatz ground connection. This works perfectly for button connections like the blink controls, but don’t use it for heavy loads (like powering the displays) — it won’t work and might even damage the Teensy.

Next Steps…

After wiring everything up, proceed to the next page and test out the software.

Once it’s all tested and working…if using the 3D-printed enclosures, return to that page to complete the assembly. Otherwise, you’re on your own now, to install the electronics in your own finished design.