Pixel Timer Matrix — an 8×8 Countdown Timer with Pixel Art

# Building an 8x8 LED Matrix Timer and Pixel Art Display

This project turns an ESP32 microcontroller, a standard 8x8 WS2812 addressable LED panel, and an analog thumbstick into a versatile smart kitchen timer and mood display.

Powered entirely by ESPHome and connected to Home Assistant, everything is configurable over the air: countdown duration, display colors, standby animations, and 16 custom pixel art slots that you can paint directly in your browser.

(Bad HDRI effect from phone, looks much nicer live)

---

## Project Overview

- Hardware: ESP32-C3 Super Mini microcontroller, 8x8 WS2812 LED matrix panel, 2-axis analog joystick module with push button, and a 5V power supply.

- Software: A single ESPHome firmware configuration file and a standalone web-based pixel art editor hosted directly on Home Assistant.

- Key Functions:

- Set countdown timers from 1 minute up to 24 hours and 59 minutes using the joystick.

- Animated sweep-in startup, progressive row-by-row countdown fill, and flashing alert when time is up.

- Standby ambient animations (Wave, Pulse, Comet, and Stars) when idle.

- An 8x8 pixel art canvas with 4,096 colors, touch drawing, undo/redo, and flash memory persistence across power cycles.

- Full Home Assistant integration with entity states, switches, selectors, and time-remaining sensors.

---

## Parts List

Here is what you will need for this build:

1. ESP32-C3 Super Mini board: Tiny, affordable, and fully supported in ESPHome.

2. 8x8 WS2812 LED Matrix module: The standard 64-LED panel with 5V, Ground, and Data In pins.

3. Analog Thumbstick Module: Standard 2-axis joystick with an integrated push button (VRX, VRY, SW). I cut the pins and soldered wires on the back to save space. 

4. 5V Power Supply: A 5V / 2A USB power supply or wall adapter.

5. 1000 uF Capacitor (Optional): Placed across 5V and Ground near the LED panel to smooth out power spikes.

6. A female USB-C port.

7. Jumper Wires and M2 Screws: For internal connections and mounting.

8. 3D-Printed Enclosure: Custom casing with front diffuser and side joystick cutout.

### Power Considerations

Addressable LEDs draw up to 60 mA per pixel at 100% white brightness, which theoretically equals 3.8 Amps for all 64 LEDs. In practice, the firmware sets a comfortable 40% default brightness, where green numbers pull around 0.25 Amps and bright multi-color frames draw around 1.5 Amps. A standard 5V / 2A USB adapter works comfortably for daily use.

---

## The 3D-Printed Case

Here are a few tips when designing or printing the enclosure:

- Front Diffuser: Placing a thin white acrylic sheet or a 0.4 mm to 0.8 mm layer of white PLA over the LEDs softens the harsh diode points into crisp square pixels.

- You can print it with every material and settings that you like, it's nothing special. 

---

## Wiring Guide

Wiring the project requires connecting the LED matrix, joystick, and power to the ESP32 board.

### LED Matrix Connections

- 5V connects to 5V Power

- GND connects to Ground

- DIN (Data In) connects to GPIO3

### Joystick Connections

- VCC connects to 3.3V of esp32

- GND connects to Ground

- VRX (X-Axis) connects to GPIO0

- VRY (Y-Axis) connects to GPIO1

- SW (Push Button) connects to GPIO4

The ESP32 reads the joystick analog pins through internal converters with auto-calibration at boot, so resting center voltages are automatically adjusted.

---

## Software Setup

### Step 1: Install the ESPHome Firmware

1. In your Home Assistant dashboard, open the ESPHome add-on.

2. Create a new device named timer-matrix.

3. Open timer-matrix.yaml and paste the configuration into your device editor.

4. Add your Wi-Fi credentials and API encryption key in your secrets.yaml file.

5. Save the configuration.

### Step 2: Flash the Board

You need to plug the board via USB for the first flash:

1. Click Install in the ESPHome dashboard.

2. Select Plug into this computer via USB for the initial setup.

3. Once completed, Home Assistant will automatically discover the new device.

---

## Home Assistant Integration

Once online, the device exposes several controls directly in Home Assistant:

- Timer Hours and Minutes: Set the target duration from your dashboard or through automations.

- Timer Active: A toggle switch to start or cancel countdowns remotely.

- Timer Color: Choose between Green, Red, Orange, Yellow, Blue, Cyan, Purple, or White.

- Standby Animation: Select between Wave, Pulse, Comet, and Stars.

- LED Brightness: Adjust global display brightness from 5% to 100%.

- Pixel Art Mode: Switch between timer mode and saved pixel art.

- Timer Remaining: A live sensor reporting minutes left in the countdown, useful for triggering automations like notifying you when cooking is done.

---

## Web Pixel Art Editor

The project includes a lightweight web editor pixel-art.txt(rename to pixel-art.html) that allows you to paint pixel art and upload it directly to the matrix in real time.

### Setting Up the Editor

1. Copy pixel-art.html into your Home Assistant config/www/ folder.

2. Open your browser and navigate to http://homeassistant.local:8123/local/pixel-art.htmlor just create a webpage card in your dashboard pointing to /local/pixel-art.html.

3. In Home Assistant, create a Long-Lived Access Token under your Profile settings.

4. In the editor settings, paste your access token and click Auto-detect.

5. You can choose to store the token in temporary session memory or encrypt it securely on your device using a 4-digit PIN.

### Painting and Presets

- Use the Brush, Bucket Fill, and Color Picker tools to paint pixels on the 8x8 grid.

- Use Undo and Redo or the shift arrows to adjust your drawing.

- Click Apply to Matrix to instantly view your artwork on the physical display.

- Save your favorite designs into any of the 16 on-device preset slots. Presets are saved directly into the ESP32 flash memory and persist through reboots.

---

## Controls Quick Reference

- Move Joystick Left / Right: Increase or decrease hours.

- Move Joystick Up / Down: Increase or decrease brightness (or minutes, depending on the selected mode).

- Press Joystick Button: Start the countdown or cancel an active timer.

- Idle State: Automatically switches to the selected standby animation or your active pixel art after a short delay.

- Waking the Display: Any movement on the stick brings back the digital time display immediately.

---

## Summary

This project combines retro digital hardware with modern smart home flexibility. Whether used as a kitchen timer, a desk gadget, or a custom pixel art mood light, it offers an engaging balance of hardware making and clean software design.

All source files, firmware configs, and the web editor are included.

Don't forget to rename pixel-art.txt to pixel-art.html and timer-matrix-public.txt to timer-matrix-public.yaml.