Dual 1.28" TFT animatronic eyes with an I2C-controlled management board.
skeleton-eye2/
├── firmware/ # ESP32-S3 eye display controller
│ └── src/ # Procedural + sprite rendering, I2C slave, WiFi/OTA
├── lib/eye_control/ # C client library for controlling the eyes over I2C
├── management-board/ # ESP32-C3 I2C master controller
│ ├── src/eye_controller.ino # Serial → I2C bridge
│ └── eye.sh # Send commands via USB serial
├── pcb/ # Gerber files + drill files for the custom PCB
├── cad/ # Frame/cover CAD files (DXF + STEP)
└── wiring.svg # Wiring diagram
| Component | Board | Role |
|---|---|---|
| Eye display controller | ESP32-S3 (LOLIN S3 Mini) | Drives 2× GC9A01 displays, I2C slave at 0x42 |
| Management board (optional) | ESP32-C3 (LOLIN C3 Mini) | I2C master, serial command interface — mainly for testing |
Note: The left eye display is physically mounted upside down; the firmware handles the 180-degree rotation automatically. A non-standard retrofit configuration for the 12 ft Home Depot skeleton is documented at the end of this file.
See firmware/README.md for display pin connections and management-board/README.md for I2C wiring details.
| Part | Qty | Link |
|---|---|---|
| ESP32 S3 Supermini | 1 | AliExpress |
| 24.8mm Round Lens | 2 | AliExpress |
| 1.28" Round TFT display module | 2 | AliExpress |
| 4-pin JST Cable (10cm) | 1 | AliExpress |
| Custom PCB | 1 | Gerbers |
| 7-pin Male header | 1 | AliExpress |
| 4-pin Female JST 2.54mm connector | 1 | AliExpress |
| 3D printed cover | 1 | CAD |
| M3 x 16mm cap head machine screw | 1 | — |
| M3 Nut | 1 | — |
- PlatformIO CLI (
pip install platformio) - Python 3 with Pillow (
pip install Pillow) for custom sprite conversion
# Build and upload firmware
cd firmware && make upload
# Optional: build and upload management board (for testing)
cd management-board && make upload- Dual rendering modes: Procedural 3D eye rendering with lighting, eyelids, and reflections, or pre-rendered sprite animations
- I2C external control: Full remote control over I2C bus with smooth gaze, blink, squint, and color commands
- WiFi OTA updates: Over-the-air firmware updates with progress display on the eyes
- C client library: Drop-in C library for integrating eye control into your own firmware projects
- Serial interface: Interactive command shell via USB serial or the included
eye.shscript
See the subdirectory READMEs for serial commands, I2C protocol details, and sprite development.
The configuration above is the standard product, tuned around the original 1.28" round GC9A01 panels. This section documents a separate, non-standard DIY build made for one specific project: replacing the eyes of a 12 ft Home Depot skeleton (Home Accents "12 Foot Animated Skeleton") with a pair of 2.4" ILI9341 TFT displays (240×320).
The 12 ft skull's eye sockets are far larger than the 24 mm aperture the round panels were sized for, so a bigger eyeball module fills them properly. That is the entire reason this configuration exists — it is not a general drop-in panel option, and it was verified on this one skeleton build only.
Two firmware environments drive the retrofit, on either board:
esp32-s3-devkitc-1-ili9341— ESP32-S3 (same board as the standard build)esp32-devkitc-v1-ili9341— classic ESP32 DevKit V1
See firmware/README.md for the display wiring,
panel behaviour, and 18-bit notes specific to the retrofit.
