HackSpace magazine

Add uncanny eyes to your Halloween project

By Ben Everard. Posted

2020 has been a strange year – in many ways it feels like we’ve missed the summer, but there’s no denying that autumn now approaches. For many makers, this means a chance to show off our creepy creations designed for Halloween.

Animated eyes – aka uncanny eyes – have been around in the maker world for a while. Phil Burgess first created the code for the Teensy microcontrollers in 2015. However, even after five years, they’re still something of a rarity outside the maker scene and have a real wow factor. Since the original Teensy code, it’s been ported to support a range of ARM Cortex-M0 and Cortex-M4 microcontrollers. Adafruit supports it on a number of its boards. It’s quite hardware-specific, so make sure that it will work on your intended microcontroller before you purchase your hardware.

We’ve used the Adafruit MONSTER M4SK, which features a SAMD51 microcontroller and two 240 × 240 screens. In this tutorial, we won’t be looking at getting the main software up and running. You can sidestep this anyway by downloading precompiled firmware. There’s some here for the Circuit Playground Express that HackSpace magazine subscribers receive, and you’ll also find it on the Adafruit product pages for the Hallowing and MONSTER M4SK.

There’s a range of parameters you can customise for the eyes. We’ll be using the MONSTER M4SK for this article as it makes tweaking the parameters easy. If you’re using a different controller, you can make most of the same tweaks, but you’ll need to update the settings slightly differently. See hsmag.cc/lFnHez for further details.

The eyes are controlled by a configuration file called config.eye. This is loaded when the microcontroller boots, so if you make any changes, you need to restart the board in order to pick up the new config. This can be done either by turning it off and on again or pressing the reset button.

All these eyes are just a modified text-file away

You can download a range of preconfigured graphics from hsmag.cc/hpoXt8. In the zip file, there are a number of folders. Each one includes the config.eye file and the graphics. You just need to copy everything to the device, then copy the relevant config.eye file to the root of the microcontroller USB drive.

You can edit config.eye in any text editor, but it is very pernickety, and the formatting has to be correct. If at some point, you find that the eyes load with just basic colours and no images, then it’s probably because there’s an error in the formatting of the file. Watch particularly for a comma after every item except the last one (which must not have one). The whole section is enclosed in curly braces, and each item is name : value, with the name in double quote marks. For example, the basic hazel eyes are:


  "boopThreshold" : 17500, 

  "eyeRadius"     : 125,

  "eyelidIndex"   : "0x00", // From table: learn.adafruit.com/assets/61921

  "pupilColor"    : [ 0, 0, 0 ],

  "backColor"     : [ 140, 40, 20 ],

  "irisTexture"   : "hazel/iris.bmp",

  "scleraTexture" : "hazel/sclera.bmp",

  "upperEyelid"   : "hazel/upper.bmp",

  "lowerEyelid"   : "hazel/lower.bmp",

  "left" : {


  "right" : {



Perhaps the easiest way of seeing what things do is changing them and seeing the result. Let’s take a look at how one we’ve created compares to this. We wanted to create a slightly unnatural eye which gave a hint of monster-y-ness without being too over the top.

You can create a wide range of different eyes by combining the examples in different ways

Eye radius is, fairly obviously, the radius of the eye in pixels. Since the screens we’re using have 240 × 240 pixels, a radius of 130 puts the eyeballs slightly larger than the screens. This isn’t a problem, as our eyelids cover the edges of our eyeballs anyway.

Speaking of eyelids, their colour is defined with the value "0x00" (note the double quote marks), which references a lookup table available at hsmag.cc/PgwFW8. Pupil colour, however, is given as a simple RGB set. We’ve given ours a dark red tint, to make them look a little menacing.

The pupils change size a little bit to give the impression of real, working eyes. There are three variables that affect this: pupilMin, pupilMax, and slitPupilRadius. The min and max variables are proportions of the iris, while the slitPupilRadius (for non-round pupils such as cats' eyes) is in pixels.  Higher radius values will give a taller, more slitty pupil. The default of 0 will give a round pupil.

The four images we’ll look at in the next section link to different prepared graphics.


  "eyeRadius"       : 130,

  "irisRadius"      : 70,

  "eyelidIndex"     : "0x00",

  "pupilColor"      : [ 30, 0, 0 ],

  "pupilMin"        : 0.3,

  "pupilMax"        : 0.4,

  "slitPupilRadius" : 60,

  "backColor"       : [ 0, 0, 0 ],

  "irisTexture"     : "skull/iris_red.bmp",

  "scleraTexture"   : "hazel/sclera.bmp",

  "upperEyelid"   : "hazel/upper.bmp",

  "lowerEyelid"   : "hazel/lower.bmp"


We’d suggest playing around with these different values to see what effect you get.

Look into my eyes

Let’s now take a look at the graphics. There are four, and each one links to a bitmap file. We’ve found that the upper and lower eyelid graphics are generally best left as they are or omitted completely. You can play around with these if you like, but we’ve not found alternatives that look good.

The iris is the part of the eye that surrounds the pupil, and the sclera surrounds the iris (commonly known as the ‘white of the eye’, although you can make it whatever colour you want).

These files want to be ‘landscape’ rectangles that will be stretched around the circular shapes. The exact size isn’t too important, but there’s limited RAM available, so don’t make them too large (we used 512 × 128 pixels). If you’re feeling artistic, you can create these from scratch, but you can get great effects by playing with a photo editor. We got good results from two ways of creating new eyes: filters, and cropping larger images.

We wanted eyes with a more piercing blue than in the standard hazel. Rather than start from scratch and create a new image, we took the hazel image and put it through a filter (the Arctic filter in Microsoft Photos, though there are many, many different pieces of image editing software that can also add similar filters).

Want to super-size your eyes? Keep an eye on adafruit.com for details of how to use LED matrixes

A second effect we wanted was whirlpool eyes: swirling, watery scleras for a sea creature build. You certainly could start from scratch and design a water image, but we decided to use a real photo of water. We searched for white water on a free stock image site and found a suitable photo. We cut out a 512 × 128 pixel section and placed it in a new image. This looked good, but we wanted a whirlpool effect, so we used the smudge tool in the GNU Image Manipulation Program (GIMP) to add diagonal streaks. The final part of this was adding the irisSpin option to make the irises rotate. You might have noticed that we wanted the scleras to spin, but we used the irisSpin value. This is because there’s no scleraSpin option. Instead, we simply removed the sclera (the iris radius is the same as the pupil radius) and had just a whirlpool and a pupil. 


  "voice"           : true,

  "pitch"           : 0.72,

  "gain"            : 1.2,

  "eyeRadius"       : 125,

  "irisRadius"      : 125,

  "slitPupilRadius" : 40,

  "eyelidIndex"     : "0x00", // From table: learn.adafruit.com/assets/61921

  "pupilColor"      : [ 0, 0, 30 ],

  "pupilMin"        : 0.05,

  "pupilMax"        : 0.15,

  "backColor"       : [ 80, 0, 0 ],

  // From www.deviantart.com/suicidecrew/art/Fire-Seamless-tile-116721709

  "irisTexture"     : "demon/sclera-water2.bmp",

  "upperEyelid"     : "demon/upper.bmp",

  "lowerEyelid"     : "demon/lower.bmp",

  "tracking"        : false,

  "left" : {

    "irisSpin"      : 18


  "right" : {

    "irisSpin"      : 18



Those are the eyes that we’ve created, but ultimately it’s up to you to decide what effect you want to create for your build. It’s possible to get some really creepy, realistic, or just plain fun eyes. We strongly recommend having a play with all of the examples and mashing them up. Eyes have a strange psychological impact on us, and it can be a little hard to understand how changing some values will affect how the eyes make you feel until you’ve seen them.  


From HackSpace magazine store