Peep dis! Have you always wanted to have another pair of eyes on the back of your head? Or outfit your costume with big beautiful orbs? The MONSTER M4SK is like the Hallowing but twice as good, with two gorgeous 240x240 pixel IPS TFT displays, driven by a 120MHZ Cortex M4 processor that can pump out those pixels super fast. You'll get the same quality display as our Raspberry Pi Eyes kit but without needing to tote around a full Linux computer

This unique design has the eyes at the same pupil-distance as a human (~63mm) but is designed so that the nose section can be broken apart with pliers/cutters and then wired together with a 9-pin JST SH cable up to 100mm long so the eyes can be re-positioned or freely attached.

We wanted to make audio-effects easier so in addition to a class D audio amp, there's also a stereo headphone jack that is connected to the two DACs on the chip. Use it when you want an externally sound amplifier box for big effects. For small portable effects, the built-in amp can drive 8 ohm speakers up to 1 Watt.

On each side are JST-PH plugs for connecting external devices. The 3-pin JSTs connect to analog/timer pins on the SAMD51, so you can use them for sensors or GPIO devices. The 4-pin JST connector connects to the I2C port and you can fit Grove connectors in it for additional hardware support. For the PDM mic port, you can use this cable to wire to a PDM mic.

For power, you can either use a USB micro-B cable, or connect a li-poly battery to the 2-pin JST-PH “BAT” connector — either directly, or with an extension cable and the battery tucked elsewhere.

There's also plenty of sensors built in - light sensor, 3 tactile buttons, and a capacitive touch pad on the nose.

Speaking of that nose, the silkscreen is by the skillful Miss Monster, check out those fangs!

This is by far the cutest, creepiest and most incredible development board we've made so far! Gaze upon these features:

• ATSAMD51G19 Cortex M4 microcontroller running at 120MHz with 512KB Flash, 192KB RAM (the board markings incorrectly say ATSAMD51J19)
• 8 MB QSPI flash for storing graphics and sound effects
• Two 240x240 IPS TFT displays each on their own SPI bus
• Beautiful silkscreen with a boop-able nose that is a capacitive touch pad
• Lipoly battery charge circuit for portable use
• Stereo headphone jack out, for sound effects via an amplifier
• Mono speaker driver for smaller 8 ohm 1W speakers
• One 4 pin STEMMA JST connector for I2C connection (also Grove compatible)
• Two 3 pin STEMMA JST connectors with digital/analog/PWM for servos, sensors, etc
• One 4 pin JST SH port for connecting an optional PDM microphone
• Backlight controls
• Three tactile buttons
• Light sensor
• On/Off Switch and reset button

And as you can expect, we've got some great new eyeball code, which does 2 eyes with user-configurable graphics. Right now our code support is only for Arduino - CircuitPython isn't quite fast enough to do the 3D animation techniques we use to draw the eyeballs. The eyes look even better if you pair them with these 40mm glass or plastic lenses. (You'll need two of course)

The MONSTER M4SK board should arrive ready-to-scare. Connect a battery or USB cable, move the power switch to the “on” position, and after a few seconds you should get blinking eyes.

The next few pages cover…

• How to reformat the flash storage. Most readers can skip this, unless you got one of the very earliest MONSTER M4SK boards, or if it just needs a complete wipe.
• How to install or update the eye firmware for the latest features and bug fixes.
• Loading different eye designs.

If plugging your MONSTER M4SK board into a computer over USB and it does not appear as a small flash drive named CIRCUITPY, it’s usually one of three reasons:

• Verify that you’re using a USB “charge and sync” cable, not a charge only cable.
• The first batch of MONSTER M4SK boards did not have the flash filesystem initialized…we’ll cover that below.
• Something happened…maybe static, maybe a bug in the software…and corrupted the flash drive contents.

If you do see the CIRCUITPY flash drive, everything’s good and you can skip ahead to the next page.

Creating the SPI Flash Filesystem

If the CIRCUITPY drive does not appear, this just involves temporarily installing a version of CircuitPython. The eye code isn’t written in CircuitPython, we’ll just use it here to get the flash initialized!

Download that .UF2 file here:

After a moment, a drive called MASKM4BOOT should appear.

After CircuitPython installs, and with the MONSTER M4SK board connected over USB, it should appear on your computer as an 8 MB flash drive called CIRCUITPY.

Initializing the filesystem is a one-time operation. You should not need to repeat this process, unless the flash drive contents somehow get corrupted.

To update firmware on your MONSTER M4SK board with the latest eye animation software, start by downloading this .UF2 file:

For a HALLOWING M4 board, use this .UF2 instead:

To install different “looks,” download and unzip this collection of eyeball graphics:

Inside the “eyes” folder are several sub-folders, one for each of our ready-made eye designs. “hazel” is our standard human eye from prior projects…then we’re adding more as Halloween approaches.

Each folder contains a set of .bmp images for that eye, plus a file called config.eye. Copy one of these folders to the CIRCUITPY drive — not the individual files, but the whole folder. Then copy or move the file called config.eye out of the folder and into the drive’s root directory.

Copy these files to the CIRCUITPY drive.

Remember that config.eye goes in the root directory, along with the hazel (or other eye name) folder.

Press the board’s reset button…

There will be a delay of several seconds as the eye code initializes. Then…animation!

If you get a flat-colored white eyeball with blue irises and no eyelids, something’s wrong! Verify that you’ve copied over a whole folder of graphics (not the individual files) and moved or copied that folder’s config.eye to the root directory.

Aside from the stock hazel eyes, some of the alternate designs include:

SECRET FEATURE: You can select among four different eye configurations on startup. Hold down one of the three buttons on top when powering on (or pressing reset) to load files config1.eye (inner button), config2.eye (middle button) or config3.eye (outer button) instead of the default config.eye. All go in the root directory for now (but graphics & such can go in folders).

If one of the ready-made designs does what you need…fantastic, you’re all done! If you want to make changes, or create your own custom eyes, read on…

If our ready-made eye designs don’t meet your needs, you can personalize quite a bit by editing a text file and providing some graphics.

On startup, our eyeball code loads a file called config.eye from the device’s root directory. This is a plain-text file that any simple editor can handle…Notepad, TextEdit, vim and so forth.

If customizing your eyes, maintain a backup of the board’s contents on your computer. There is a small but nonzero chance of a glitch that could require a full reinstall. See the Troubleshooting page for help.

The syntax of this file is a format called JSON. There’s good and bad news…

The good: JSON has a standardized syntax and we can leverage existing code to read it…we’re not starting from scratch with a new file format.

The bad: JSON files are really meant to be read and written by machines, as a way to preserve program state…not edited by humans. It’s phenomenally picky about getting syntax just right and does not fall back gracefully.

The saving grace: if you’re just changing colors and textures, you might not need to edit this file at all! Quite often you can just substitute different graphics files with the same names.

Troubleshooting JSON

If even a single character is out of place in config.eye, the whole thing will fail to load and there’s no helpful indication of where the problem lies.

If this happens, the eyes will run in a default state: blue eyes with no eyelids, and everything is “flat” colors, no textures. This isn’t helpful in isolating the problem but at least tells you there is a problem.

One way to troubleshoot this is to start with a known valid eye configuration, then change one setting at a time and restart the code. If the eyes revert to the default state, the last change contains the syntax error. Quite often it’s just a missing double quote or extra comma.

Another option is to use a JSON validator such as this one at hjson.org. Copy-and-paste your eyeball configuration into the left pane…if there’s a problem, this will be reported on the right.

Here’s an simple config.eye file to start with:

Some things to notice:

• The whole thing is contained within curly braces — { and }
• Each item has a name (always in quotes), a colon separator ( : ) and a value. Values might be numbers, strings (in quotes) or arrays (in square brackets) depending on what’s being configured.
• This is a list and each line ends with a comma…except for the last item in the list. Watch out for missing or surplus commas!
• JSON is case-sensitive. "Foo", "foo" and "FOO" are all different things.
• Using extra spaces to line up columns really isn’t necessary, just something I do to assist with legibility. Some folks just find it annoying.
• Comments (starting with // ) are not standard JSON syntax, but the library we use allows them and I find them very helpful.

Each option will be explained in detail on the “Configurable Settings” page. But first let’s talk about graphics…

So we’re singing from the same page, let’s lay out some eye terminology…

This program’s eye graphics are stored flat and unrolled, like a map projection. The horizontal (X) axis works like the longitude, or angle around the eye, while the vertical (Y) axis is the latitude. The images are wrapped around the pupil in a clockwise direction.

There are two images (or texture maps) associated with the eyes…one for the iris, another for the sclera.

The iris is what we think of as the “color” of the eye and is most often what you’ll want to edit. Sometimes you just need to edit the hue & saturation in a program like Photoshop, or you can make something totally custom if you’re after a particular look.

The sclera is the “white” of the eye…which really isn’t that white at all. There’s veins and blotches and gross stuff!

Image Storage

The texture maps are stored as 24-bit BMP images…nobody’s favorite, but easy for microcontrollers to handle. (This is also sometimes called “Windows Bitmap” format, though plenty of non-Windows software can read and write these images…and not to be confused with “X BitMap” or “Portable Bitmap Format,” different animals.)

Textures are loaded from drive into RAM, downsampled to 16-bit color (what the displays natively use) and then written to the chip’s internal flash memory (different from the flash filesystem). Although the code places no strict limit on image dimensions, RAM and flash are both finite resources, and this limits to how large these textures can be…both individually and in total.

No single image can exceed available RAM, or about 160 kilobytes. The total of all images must fit within flash, or about 360 kilobytes. These figures might change a bit in the future, so try to leave yourself some overhead.

Use the following formula to determine the space needed for an image:

width in pixels × height in pixels × 2 bytes

For example, a 500 × 150 pixel texture would consume 500 × 150 × 2 = 150,000 bytes. This fits in RAM just fine, and takes up a bit less than half of the flash space.

You don’t have to texture-map both the iris and sclera if you don’t want to…on the Configurable Settings page we explain how to use solid colors for either or both. Also shown there…it’s possible to assign independent textures to the left and right eyes. When both eyes are sharing the same texture, the code will place only one instance in flash, saving space.

To make the re-use of textures less obvious, the “seam” where a texture map wraps around is normally at the 12 o’clock position for the right eye and 6 o’clock for the left eye. The Configurable Settings page shows how to change this.

Too-large images may exceed available space, while too-small images may exhibit visible jaggies (unless you’re aiming for that effect as described above). The ideal size can be calculated based on the circumference of the iris or the whole eye…

The iris and overall eye size are configurable (shown on following page)…but for example, let’s assume you’ve got an iris with a 60 pixel radius (120 pixel diameter) and the eyeball has a 125 pixel radius (250 pixel diameter)…both of these are the defaults.

Multiply the iris and/or eye diameters by Pi (3.14) to get the ideal width in pixels for the iris and sclera images.

For example: iris with 120 pixel diameter. 120 px × 3.14 = 377 pixels wide. You can use that, or round up or down a smidge to a round number if you like (e.g. 360 or 380 pixels).

Sclera image width for 250 pixel diameter eye: 250 × 3.14 = 785 pixels wide…but again, OK to round up or down a little…use 800 pixels wide if you like, unless really pressed for space.

The ideal image heights are a bit different. First, although the code can load any size image, it won’t actually benefit above 128 pixels on the vertical axis, it’s just wasted space. For the iris, use its radius (60 pixels in the case described above) or even a little less, since the pupil is always open a bit. For the sclera…try 200 minus the iris radius, keeping in mind the 128 pixel recommended maximum (e.g. with a 60 pixel iris, 140 is our target, then cap it at 128). But…with an 800 pixel wide sclera as described above…800 × 128 × 2 = 204 kilobytes…quite a bit over the 160K RAM limit! Whittle down one or both axes, whatever you think can best handle less resolution, until you find a size that fits. Once in motion, and at a reasonable viewing distance, minor “jaggies” aren’t that noticeable.

Photoshop users: the eye code maps textures differently than Photoshop’s “Polar Coordinates” filter. Ours wraps clockwise, with the top of the image becoming the outer circumference, while Photoshop wraps counterclockwise, with the bottom becoming the outer circumference. If using Photoshop to create or preview textures, simply rotate the rectangular image 180° before applying a rectangular-to-polar filter, or after a polar-to-rectangular filter.

Eyelids

The eyelids have stricter requirements. There are always two files (one each for the upper and lower eyelids) both 240 × 240 pixels exactly, both 1-bit BMP images (NOT 24-bit like the texture maps!).

The white area — which should span the entire 240 pixel width — represents the extent of vertical motion, the “open-most” and “closed-most” range. The eyes won’t hold the open-most position all the time when idle…the upper eyelid “tracks” the moving pupil, because that’s how eyes work.

A good set of eyelid images will overlap by a few pixels, so the eye makes a good solid blink.

This particular set of eyelids is slightly asymmetrical to approximate the eye’s caruncle* — that triangular bit by the tear duct. The shape is mirrored between the two eyes. But it is super 100% okay to make symmetrical eyelids if you prefer…a simple “football shape”…that usually looks better on a single-eye board like the HalloWing M4. For some of the eye designs we’ll offer both.

* Which itself is a vestigial remnant of the nictitating membrane, the “third eyelid” that reptiles have. How cool is that!?

The eyelid images as shown above are for the right eye. That is…the monster’s right eye, meaning the eye on the left when looking at the M4SK.

Let’s look at the configuration for our stock “hazel” human eye. It doesn’t reference every configurable setting, but shows the general format of these files…

This is a plain text file that any simple editor should be able to handle…Notepad or TextEdit or whatever comes bundled on your computer.

It’s worth reiterating these points from the “Customization Basics” page:

• The whole thing is contained within curly braces — { and }
• Each item has a name (always in quotes), a colon separator ( : ) and a value. Values might be numbers, strings (in quotes) or arrays (in square brackets) depending on what’s being configured.
• This is a list and each line ends with a comma…except for the last item in the list. Watch out for missing or surplus commas!
• JSON is case-sensitive. "Foo", "foo" and "FOO" are all different things.
• Using extra spaces to line up columns really isn’t necessary, just something I do to assist with legibility. Some folks just find it annoying.
• Comments (starting with // ) are not standard JSON syntax, but the library we use allows them and I find them very helpful.

The “Customization Basics” page also has some JSON troubleshooting tips. If you encounter trouble, review that page!

Two settings define the basic geometry of the eye…

eyeRadius establishes the size of the overall eyeball, in pixels. This is a radius — center to edge — so the overall eye size is twice this across. For example eyeRadius:125 configures the eye to be 250 pixels wide. This is the default if left unspecified.

The screens are only 240 pixels wide. Reason the eye is made a little bigger is because the code uses tricks to fake a rotating sphere…and that faking is more apparent as the pupil approaches an edge. So we push the edge out a few extra pixels, then cover it up with eyelids.

If designing an eye with no eyelids, you might want eyeRadius:120 instead, which provides a nice perfect circle on the screen.

Remember that JSON is case-sensitive. This must be spelled eyeRadius. Different capitalization will cause it to be ignored!

irisRadius establishes the size of the iris…again a radius, in pixels.

irisRadius:60 will make the iris 120 pixels across, or half the width of the screen. If you plan to use lenses over the displays, consider scaling down this number a bit to compensate.

Some creatures…cats and so forth…have very large irises and almost no visible sclera. In that case you can set irisRadius much larger, up to (but not exceeding) eyeRadius.

A third setting, slitPupilRadius, lets you make cat or dragon type eyes with a vertical slit pupil (only a vertical slit is available, no goat pupils, sorry). If set to 0 (the default), a normal round pupil is used. Larger numbers (up to irisRadius) make a taller/thinner pupil. This number sets the height. You’ll probably want an in-between value…maybe irisRadius:80 (160 pixels round) and slitPupilRadius:60 (120 pixels tall) to start.

Note that using slitPupilRadius makes the program a bit slower to initialize…you’ll just see blank screens for several seconds while it works. This is normal and just an unfortunate math thing.

The texture map images for iris and sclera are specified with irisTexture and scleraTexture:

If you prefer a solid color to an image, omit those lines and instead use irisColor and/or scleraColor, with color specified as three values [red, green,blue] in brackets:

Colors can either be three integers in the range 0 to 255 (like most folks are used to) or three floating-point values from 0.0 to 1.0 (same idea, just different scale).

Solid colors save a TON of space compared to texture maps, if your design can get away with it.

A few more items have configurable colors:

pupilColor is self-explanatory…like if you want glowing red or white pupils or something.

backColor covers the outermost/backmost part of the eye where the sclera texture map (or color) doesn’t reach. With a little planning, this and your sclera texture map can be designed to blend together…otherwise you’ll see a conspicuous crescent of backColor when the eye is looking off to a side.

The eyelid (and background) color is also configurable, but it’s not a normal RGB color. Instead, use eyelidIndex and an 8-bit value:

Notice the hexadecimal value must be quoted. The value corresponds to one of the colors in this palette:

eyelidIndex doesn’t use a normal RGB value because the code is using an optimization trick here, which limits the available colors in this one area. The default eyelidIndex if unspecified is “0x00” — black.

Colors/textures can be independent on the left and right eyes. Notice in the config file there’s these two empty sections:

Between each item’s curly braces, independent irisTexture, scleraTexture, irisColor, scleraColor, pupilColor and backColor can be specified, which will override anything set outside of these.

It was mentioned earlier that the left eye’s textures are rotated 180° so it’s less obvious that the images are being re-used. If you need to override this, so both eyes have aligned textures, the irisAngle and scleraAngle settings can be used (either globally or in the left/right sections).

irisAngle and scleraAngle are a rotation offset in the clockwise direction, using either normalized floating point where 0.0=seam at top, 0.25=seam at right, 0.5=bottom, 0.75=left, and 1.0=back to top. You can also use integer units from 0 to 1024 (0=top, 256=right and so forth). Negative values are accepted for both the floating-point and integer modes, in which case the angle will be counter-clockwise.

irisSpin and scleraSpin can be used to make the texture maps revolve around the pupil, which might be handy for certain fun effects (spiral hypno-eyes, cyborg stuff, etc.). These are specified in RPM, with positive values being clockwise. So for example, setting irisSpin to -60 will make the iris rotate counter-clockwise once per second. These can be specified globally or on a left/right basis.

There’s also irisMirror and scleraMirror settings (specify as true or false, or 1 or 0 — default setting is false), which flip the way the texture is wrapped (clockwise default vs counterclockwise override). If mirroring on just one eye, you might want to set the corresponding irisAngle or scleraAngle value to 0 depending on what you’re after.

Screen orientation is specified with the rotate keyword, with a value from 0 to 3 (default is 3). This can be helpful if you’ve split your MONSTER M4SK in two. Sometimes the mask-halves will fit into a project better if they’re each turned 90 degrees, and this setting compensates so the eyes are right-side-up again. You can put separate rotate values in the left and right sections…try 0 and 2 (or 2 and 0, depending which way the eyes are turned).

None of this left/right stuff applies on the HalloWing M4, which only has one eye. Having these sections won’t cause the config load to fail, it just ignores anything eye-specific.

The following are NOT left/right configurable: eyeRadius, irisRadius and slitPupilRadius (these affect how certain tables are calculated and there isn’t enough RAM to have independent left and right tables).

The eyelid graphics format is explained on the “Preparing Graphics” page. These are 1-bit BMPs, 240 pixels square. Use the upperEyelid and lowerEyelid settings to specify the filenames of these images.

Eyelids are one of those global (not configurable per-eye) things. The design of the eyelid graphics might be symmetrical or asymmetrical…some eye designs might provide two sets of eyelid images, one for a single-eye device (like HalloWing M4) and another for the Monster M4SK, where the left and right eyelid shapes are mirrored.

If you want no eyelids at all, just leave out any upperEyelid or lowerEyelid filenames. You’ll then have a circular unblinking eye…looks good for skulls!

With eyelids enabled, normally the upper lid “tracks” the movement of the pupil (when the eye looks down, the eyelid follows with it). This is something that eyes do in real life…but some folks think it looks sleepy, or just want a particular caffeinated look. Use the tracking keyword with a value of false to disable the eyelid tracking and maintain wide-open eyes.

The pupils normally do some dilation movement on their own…but you can have them respond to light if you like! Use the lightSensor keyword along with a pin number where the light sensor is connected. If it’s on a Seesaw interface chip (e.g. on MONSTER M4SK), add 100 to the pin number. For example, on MONSTER M4SK the built-in light sensor is:

"lightSensor" : 102

And for HalloWing M4, use:

"lightSensor" : 21

(Add a trailing comma if this appears mid-file.)

This used to be a separate program…it now works together with the eyes! This requires the following:

• MONSTER M4SK board
• PDM microphone and JST SH cable
• You can test with headphones…but for portable or costume use, you’ll want a battery-operated amplified speaker and a male/male 3.5mm audio cable. Some Bluetooth boom box speakers include an aux input jack, or I’ve used this belt-worn speaker from Monoprice with some success (see notes below).

Usage

The PDM microphone connects using a tiny 4-pin cable to the “PDM MIC” port on MONSTER M4SK — it’s near the reset button. You can optionally fashion a pop filter over the mic using a little fabric or foam, it’ll probably sound better.

Connect an audio cable from MONSTER M4SK headphone jack to the aux input on the powered speaker.

The voice changer is off by default! It saps a fair bit of compute cycles (anywhere from about 25 to 50 percent…with a corresponding drop in eye animation frame rates) so you’ll have to turn this on only if you really want it. To do so, you'll add a line to the config.eye JSON file on the root level of your MONSTER M4SK. Use:

"voice" : true

to enable the voice changer. See the link below for an example config file that's been set up with voice changer parameters. Add a trailing comma if it’s not the last line.

There are three buttons along the top edge of the monster’s left eye. Tapping the inner button (the one closest to the nose) raises the pitch by 5%. Tapping the outer button (near the corner) lowers the pitch by 5%. Tapping the middle button resets the pitch to its default.

The default pitch is set with the pitch keyword. This is a floating-point value, where 1.0 is normal (voice is passed straight through, no change), 2.0 will double the frequency (raising the voice by one octave), 0.5 will halve the frequency (lowering by one octave).

pitch can be from 0.4 to 4.0…but the actual usable range where you can still understand things is a bit narrower, perhaps 0.6 to 2.0…you’ll want to experiment a bit to find a setting that achieves the desired effect with your own voice.

Microphone gain (sensitivity) is set with the gain keyword. If installed in a mask and you need to adjust the microphone to compensate for its placement relative to your mouth, use this with a floating-point value where 1.0 is “normal” sensitivity, 0.5 is quieter by half, 2.0 is double the loudness and so forth. There are limits to what can be done here, you may want to experiment a bit with this setting and the volume of an external amplified speaker.

Don’t shout! Speak in a normal to soft voice, let the speaker take care of amplification. This helps the “weird” voice be heard over your own.

Similarly…speak at your normal voice pitch and let the voice changer do its thing. You don’t need to make a funny voice.

Need a Dalek voice effect? With the voice changer enabled as described above, also add "waveform" : "sine" to enable this effect, which applies a 30 Hz sine wave modulation to the pitch-adjusted voice — same as used for the original Dr Who Daleks. You can try other waveforms ("square", "sine", "tri" and "saw" are all supported) and other modulation frequencies ("modulate" : 100 for a 100 Hz modulation wave)…but, to be perfectly honest…this all turned out a bit disappointing, the feature is only left in there because the 30 Hz Dalek modulation was spot-on. With some experimentation with different pitch and modulation settings you might also get a passable “Chicken, fight like a robot!” voice from Berzerk, if anyone even remembers that one.

Example Config.eye File

Tips for using the Monoprice 5-Watt Guitar Amplifier

I have a love/hate thing with this speaker. On the plus side: it’s pretty inexpensive, is rechargeable, and is slim(ish) and clips to one’s belt or a lanyard, making it handy for costume use.

It’s really designed for guitar use and MP3 playback (from microSD card) and there’s some hoops necessary to get it to pass through audio undistorted…

• Connect MONSTER M4SK to the AUX phono jack (center of three), not the MIC input.
• After powering on, wait a moment and then press the “M” button to pass through audio.

You can see in the photo that I’ve labeled mine and highlighted the correct jack and button…I use it infrequently and forget this ritual (also helps when others are borrowing it).

This is not an Adafruit product and we do not provide support. Please check with Monoprice if you encounter trouble.

The next couple of pages explain how to set up the Arduino software to work with the SAMD microcontroller boards like the HalloWing M4 or MONSTER M4SK. If you’ve previously worked with Adafruit SAMD boards with Arduino, that part’s already set up and you can skip ahead to the “Libraries and Settings” page.

In summary: use the latest Arduino IDE, install the latest Adafruit SAMD boards package, install Windows drivers if necessary, and install all the library dependencies for this project…

At this point you should be able to upload code (such as the “Blink” sketch) to the board, the basics are confirmed working. If not, work though the prior two pages.

Source Code

Source code for this project is found in the Adafruit_Learning_System_Guides repository on Github, specifically in the M4_Eyes subdirectory. Here’s a direct download link:

Libraries

The following libraries are used by the eye code (or are referenced indirectly by libraries used). These can be installed through the Arduino Library Manager (Sketch→Include Library→Manage Libraries…)

• Adafruit_Arcada
• Adafruit_GFX
• Adafruit_BusIO
• Adafruit_ImageReader
• Adafruit_LIS3DH
• Adafruit_MSA301
• Adafruit_NeoPixel
• Adafruit_Seesaw
• Adafruit_Sensor (Adafruit Unified Sensor in Library Manager)
• Adafruit_SPIFlash
• Adafruit_ST7789
• Adafruit_TinyUSB
• Adafruit_TouchScreen
• Adafruit_ZeroDMA (Adafruit Zero DMA in Library Manager)
• Adafruit_ZeroPDM (Adafruit Zero PDM in Library Manager)
• Adafruit_ZeroTimer
• ArduinoJson (not Arduino_JSON)
• SdFat - Adafruit fork (not the standard SdFat fork)

Recent versions of the Arduino IDE install dependent automatically, so installing Adafruit_Arcada should cover most if not all of this.

Additionally, depending on which of the “user” code tabs is active, you might need:

• Adafruit_AMG88xx (used by user_watch.cpp)

Project Settings

• Tools→CPU Speed→180 MHz (overclock) (200 MHz is a bit too much for some boards and may lock up, but you can give it a try. We use 180 MHz for our prepackaged .UF2 files since it’s likely to work on more boards in the wild.)
• Tools→Optimize→Faster (-O3) (do not use higher settings for this code, it may corrupt the flash filesystem requiring a complete wipe)
• Tools→USB Stack→TinyUSB (the code will not compile without this selected!)

Board does not show up as drive when connected to computer

• The most common cause is using a charge-only USB cable rather than charge-and-sync. Try swapping out for a different cable.
• If you’re not getting the CIRCUITPY filesystem: have you installed CircuitPython on the board to initialize the drive the first time? See CircuitPython instructions below.
• If you can’t access the bootloader (MASKM4BOOT or HALLOWM4BOOT drive), it might be the timing of the reset double-tap. Try a little slower or a little faster.

Board Unresponsive; Flashing Red LED

There is an extremely small but nonzero chance of a glitch that wipes the board’s flash filesystem. No eyes, just a flashing red LED. We’ve yet to track down the source of this bug. Fortunately it’s pretty rare, and usually just when loading a new design.

If this happens with your board, you’ll need to completely wipe and reinstate the flash filesystem. Any files on your board are lost … it’s strongly recommended to maintain a backup of any customized files.

To recover from this situation:

1. Visit the CircuitPython download page and search for your board — either MONSTER M4SK or HalloWing M4 (not M0).
2. Download two files there: a CircuitPython “UF2” installer (current stable release), and bootloader updater UF2 (further down on the same page).
3. Connect board to computer with USB cable, set switch to “on” position, and double-tap the board’s reset button. After a few seconds, you should see a small flash drive called MASKM4BOOT or HALLOM4BOOT.
4. Drag the bootloader UF2 file to the boot drive. That drive will go away for about 10 seconds while the software works, and then reappear once it’s finished.
5. Drag the CircuitPython UF2 file to the boot drive. That drive will go away and is replaced in a few seconds with one called CIRCUITPY. You should see some text on the board’s display now.
6. Reload eye graphics files to the CIRCUITPY drive, either one of the ready-made designs, or from a backup of your customized files.
7. Download and install the M4 EYES firmware as explained on this page. This is another double-tap-drag-UF2 sequence, like we did above.

Everything on your board should be factory fresh now.

Ol’ Blue Eyes

If the eyes used to work but after editing have reverted to flat-colored blue irises, that’s almost always a JSON syntax error…usually a missing or extra comma. The “Customization Basics” page has more tips for ensuring proper syntax.

Crossed Eyes

Occasionally the eyes might go crossed and stay that way. The software thinks the “nose booper” is being held and this is its attempt at being funny.

This false booping can happen when the battery is running low and its voltage starts to drop.

Occasionally though…it just gets a false reading, maybe due to gradual changes in temperature, humidity or other unknown factors. Tap the reset button (or toggle power off and on) and this should clear up…the booper calibrates it’s un-booped state on start-up.

Technicolor Snow

If you see one or more of your texture maps show up as multicolored snow/noise, it may be an indication that you've run out of texture memory and will need to reduce the file size of some of your maps.

If the entire screen is snow, it usually means you’ve run out of RAM, and the most likely culprit there is the eyeRadius setting. Larger eyes require geometrically more RAM. Dial it back until everything fits.

Erase the Filesystem

If your board has a filesystem problem that’s not fixed by the troubleshooting steps up top, you can try a more thorough QSPI flash initialization. Download the UF2 file linked below, then plug in your M4SK and double-click the reset button. You'll see a M4SKM4BOOT drive show up on your computer. Drag the M4SK_QSPI_Eraser.UF2 onto that drive. After a few moments, the board's drive will disconnect. Double-click reset to put the board back into bootloader mode. Then follow the CircuitPython, graphics and eye firmware steps above.

Diagnostics

Want to see some stats on your M4SK? Double-click the board's reset button to get to bootloader mode, then drag the M4SK_Diagnostics.UF2 onto the M4SKM4BOOT drive!

Screen(s) Coming Unstuck

You might find over time that the foam tape holding one or both screens softens up…or the tape is fine, but the thin plastic light diffuser behind the LCDs is giving way. Use a toothpick to add dots of a pliable glue like E-6000 or Duco Cement between the PCB and side edges of the screen. Will usually need to dry overnight…follow directions and safety guidance on the glue packaging.

Lens Holders

Here’s an Adobe Illustrator file for laser-cut 1/8" thick (3mm) acrylic that provides frames for two plastic or glass lenses:

Each frame is held in place with three M3 x ~12-14mm screws. Slots are provided for a 3/4" (20mm) elastic strap. This can be worn around a hat or the forehead of a mask. Not worn over your own eyes please…it blocks your vision and might scratch your eyes!

You can skip the lenses and just use the frames for the strap if that’s all you need. Regardless, don’t make the strap too snug…the board is designed to be split in two, and we don’t want that happening unintentionally.

There is an optional extra nose bridge piece. If you have split your MONSTER M4SK apart and want to use it in its original shape again, this piece holds the frames at their original spacing. An optional 9-pin JST cable must link the two boards, you’ll need some different length M3 screws, and you will not get the boopable nose feature back.

3D Printed Options

The voice changer is no longer a standalone program…it’s been merged in with the eye code and runs at the same time now!

Enabling and customizing the voice changer are now documented on the Configurable Settings — Voice Changer page.

Displays and Display Connectors

Microcontrollers and Flash

Power Switch and Ports

Audio

Capacitive Touch Pad and Buttons

Sensors

I2C Connector

Digital/Analog Connectors

Reset Button

LED

SECTION TITLE HERE

Files:

• Product page with datasheet for ATSAMD51J19
• EagleCAD files on GitHub
• 3D Models on GitHub
• Fritzing object in the Adafruit Fritzing library

Schematic

Fab Print