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.

You wont be able to double-click this file, so open it from WITHIN your text editor

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:

{
  "pupilColor"    : [ 0, 0, 0 ],
  "backColor"     : [ 140, 40, 20 ],
  "irisTexture"   : "graphics/iris.bmp",
  "scleraTexture" : "graphics/sclera.bmp",
  "upperEyelid"   : "graphics/upper.bmp",
  "lowerEyelid"   : "graphics/lower.bmp"
}

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 commaexcept 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

This guide was first published on Aug 20, 2019. It was last updated on Mar 28, 2024.

This page (Customization Basics) was last updated on Mar 08, 2024.

Text editor powered by tinymce.