Skip to content

About

Open Source, I2C controllable, dual 1.28" TFT eye module

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

15 Commits

Folders and files

Repository files navigation

Skeleton Eye

Tindie

Dual 1.28" TFT animatronic eyes with an I2C-controlled management board.

Repository Layout

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

Hardware

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.

Wiring

Wiring diagram

See firmware/README.md for display pin connections and management-board/README.md for I2C wiring details.

Bill of Materials

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 —

Quick Start

Prerequisites

  • PlatformIO CLI (pip install platformio)
  • Python 3 with Pillow (pip install Pillow) for custom sprite conversion

Build and Upload

# Build and upload firmware
cd firmware && make upload

# Optional: build and upload management board (for testing)
cd management-board && make upload

Features

  • 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.sh script

See the subdirectory READMEs for serial commands, I2C protocol details, and sprite development.


Retrofitting the 12 ft Home Depot Skeleton (non-standard)

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.

About

Open Source, I2C controllable, dual 1.28" TFT eye module

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages