ESP32-C6 Touch LCD 1.47"
LVGL Animated Clock

✨ Features

🛠 Hardware

Board: Waveshare ESP32-C6 Touch LCD 1.47"

The project is built on the Waveshare ESP32-C6 Touch LCD 1.47" development board, which features a 1.47-inch ST7789 display and an AXS5106L touch controller. The board also includes a QMI8658 IMU for motion sensing, an ETA6098 battery charger for power management, and an SD card slot for storage. This all-in-one design simplifies wiring and allows for a compact form factor.

Key specifications of the display include a resolution of 172 × 320 pixels in landscape mode (ROTATION = 1) and an SPI interface for communication. The touch controller uses I²C for input handling. The board's integrated components make it ideal for building interactive projects like this animated clock.

You can purchase the board from Waveshare. It’s an affiliate link, so if you use it, you’re basically buying me a coffee (and I really appreciate it)! ☕

Pin Map & Wiring

Connect a passive buzzer (not active) between GPIO 5 and GND. If the buzzer is very loud, add a 100 Ω resistor in series.

ESP32-S3 only — optional KY-023 joystick. That board has no IMU, so the tilt-steered games are hidden there by default. A KY-023 module on header P1 gives them back: SW → GPIO 8 (P1.20), VRy → GPIO 9 (P1.18), VRx → GPIO 10 (P1.16), GND → P1.3 and the module’s +5V pin to 3V3 (P1.6) — never to 5 V, since the module is a bare divider with no level shifting. Then turn on Extra Games in the USB carousel. See the README for the full wiring table and tuning options.

💻 Software Dependencies & Setup

Developed using Arduino IDE, download the latest version from the official Arduino website.

Install the board through Arduino IDE → Tools → Board → Boards Manager, search `esp32` and install esp32 by Espressif (this will provide SD, WiFi & WifiMulti libraries).

Install all libraries through Arduino IDE → Tools → Library Manager: LVGL (v9.6.0), Arduino_GFX_Library (1.6.5), FastIMU (1.2.8).

The file lv_conf.h is included in the repo so there is no need to update the local library src file.

Here are some important changes in the lvgl configuration file:

#if 1  /* Enable the file */
#define LV_USE_STDLIB_MALLOC    LV_STDLIB_CLIB
#define LV_USE_STDLIB_STRING    LV_STDLIB_CLIB
#define LV_USE_STDLIB_SPRINTF   LV_STDLIB_CLIB
#define LV_USE_GIF  1
/* Enable Montserrat 14, 16, 48 */

SD Card Setup (FAT32)

GIF files must be resized to 160 × 86 pixels to avoid RAM exhaustion.

SD root/
├── config.ini
├── last_seen.txt
├── scripts/            ← ASCII art for macroPad (not auto-copied to flash)
│   ├── ASCII_house.art
│   ├── ASCII_hut.art
│   └── ASCII_penguin.art
└── cruzr_emotions/
    ├── cruzr_smile.gif
    ├── cruzr_sleep.gif
    ├── cruzr_sad.gif
    ├── cruzr_joy.gif
    ├── alarm_animation.gif
    └── timer_animation.gif

📱 Usage & Interface

Home Screen Touch Zones

┌─────────────────────────────────────────┐
│   Smile GIF (UL)  │  Analog Clock (UR)  │
├───────────────────┼─────────────────────┤
│   Status (LL)     │  Battery (LR)       │
└─────────────────────────────────────────┘
      LONG-PRESS anywhere → Carousel menu
            

• Analog Clock (UR): Tapping the upper-right zone opens the live-rendered analog clock interface.
• Status (LL): Shows WiFi, NTP, and Brightness. Tilt left/right to adjust brightness.
• Battery (LR): Live %, voltage. Long-press for software power-off.
• Emotion Tilt: Tap UL (Smile). While playing, tilt the device to change emotions (sad, joy, sleep) in real-time via IMU.
• Apps Menu: Long-press the smile GIF → pass Math Gate → access Rock Paper Scissors, Dice, Coin Flip, Metronome, Tennis Letters, Letters Rain, Snake Letters, Bingo!, and ToneQuest.
• Gyro shake/tilt: While playing RPS or Dice, physically shake the device or tilt it hard sideways to restart the game — no tap needed.

🎵 Metronome

Accessible from the Apps Menu carousel (4th item). A hardware-timer-accurate metronome with a full control UI:

• BPM slider: Drag to set tempo from 60 to 240 BPM. Updates live while running.
• −1 / +1 buttons: Fine-tune one step at a time.
• START / STOP: Toggle the click on/off.
• Beat dots: Flash in sync — 🔴 red for the downbeat, 🟢 green for weak beats.
• Time signature tabs: 2/4, 3/4, or 4/4. Switches instantly, even while running.

Downbeat is accented at 1800 Hz; weak beats at 900 Hz, 25 ms each. The metronome always sounds regardless of the mute toggle — it is a musical tool, not a game effect.

🎾 Tennis Letters

A Breakout-style ASCII game where the ball is a cycling letter (a-z). Use the device's Y-axis tilt to move the paddle and catch the ball. Each catch increments the score and advances the letter. Completing a full alphabet plays a success tune. High scores are persisted to config.ini, along with numerous configurable variables to make the game more challenging.

🌧 Letters Rain

An ASCII falling-letters game. Letters and modifiers descend in separate waves — a letter wave (target + decoys) enters first, followed by a modifier wave (+ / - / *) 3–5 rows behind. Use the device's Y-axis tilt to move the paddle:

• Catch the target letter (shown capitalised in the status bar, A→Z) to score. The remaining decoys clear and a fresh letter wave spawns immediately.
• Catching a wrong letter shrinks the paddle by 1.
• Catching + enlarges the paddle (max 10); - shrinks it (min 3).
• Catching * (rare — approx every 20 waves) instantly restores the paddle to its configured default size.
• If the target letter falls through without being caught, the game ends and the last score is saved.
• Catch all 26 letters to win. The status bar shows ✓ on completion.

Each successive target spawns within 5–15 columns of the previous one, keeping the action in a natural zone. Speed increases with every correct catch. Last score is persisted to config.ini.

🐍 Snake Letters

A classic snake ASCII game. Steer the snake using the device's tilt to eat letters of the alphabet in order (a-z). Be careful: after reaching a certain score, "distraction" letters appear—touching any of them ends the game immediately! Look out for modifiers: - shrinks your snake, and / halves its length. High scores are persisted to config.ini.

🎱 Bingo!

An on-device 1–90 number caller for playing classic bingo with printed tickets. A large circle shows the current ball with a status bar underneath (Previous: X / Numbers left: Y). Tap anywhere, or tilt left/right, to draw the next ball — each draw plays a short cycle-and-reveal animation with a distinct buzzer pattern. Long-press inside the circle opens a history popup of every number called so far, in call order. Numbers are drawn from a fresh shuffle each game, so there are never repeats; calling all 90 plays a success tune. Pair it with the printable ticket sheets at Web Configuration.

🌅 ToneQuest

A Simon-says tone-memory game, ported from the Arduino original where a joystick picked the directions and four LEDs echoed them. Here the joystick is the IMU and the LEDs are four “sunset” domes rising from the screen edges — but the direction→tone table is the original one, note for note: UP D4, DOWN C4, LEFT E4, RIGHT F4.

Every game opens on a bubble level. The ball tracks tilt and the sub-note reads level the device until you hold it inside the centre ring for 700 ms; then the round begins. The sequence plays back — each step lights its edge as a semicircle that fades out like a setting sun, and sounds that edge’s tone — and you repeat it by rolling the ball into the same walls in the same order. The ball has to come back near the centre between moves, which is the original joystick’s spring return and also what stops one long sweep from registering two edges.

A clean sequence plays the success melody, adds one move and starts the next level; the pattern is drawn once per game and only ever revealed a prefix at a time, so level N is always level N−1 plus one new move. A wrong wall plays the failure tune and opens a popup with the level reached and the best ever — tap it to play again, long-press to exit. There is no win state: the score is the level you reach. Best is persisted to config.ini under [tonequest] high_score, with start_moves, flash_ms, gap_ms and tilt_percent to tune the difficulty.

Without an IMU — every S3, or a C6 whose sensor did not answer at boot — ToneQuest is the one carousel app that changes input method instead of disappearing. A tap opens the round in place of the levelling gate, and you answer with four-way swipes rather than by rolling the ball; the ball still flies to the wall it was sent to, on playback and on input, so the screen reads the same. LVGL delivers at most one gesture per press, which makes a swipe inherently one move and removes the spring-return step entirely. Scores are not comparable between the two: swiping is quicker than tilting, with no return leg.

Config.ini Reference

[wifi]
mode = wifi   # wifi | ap | off
ssid = myhomewifi
password = changeme

[clock]
ntp_server = pool.ntp.org
tz = CET-1CEST,M3.5.0,M10.5.0/3

[alarm]
enabled = true
time = 07:10

[animation]
schedule = true
duration = 10

🌐 Web Configuration

Whenever the radio is up, the device serves a browser-based configuration UI on port 80, accessible in both WiFi and AP mode (not in Off/airplane mode) — no app or cable needed.

Connecting

WiFi mode (joined to your home network): navigate to http://esp32clock.local or the IP address shown in the long-press WiFi detail popup.

Two clocks on one network? That .local name has to be unique — if both devices answer to it you reach whichever replies first. Set hostname = esp32clock2 under [wifi] in the second device's config.ini (editable from the web UI, then reboot) and it becomes http://esp32clock2.local. Only letters, digits and hyphens are kept; anything else is converted, and an unusable value falls back to the default. The AP hotspot name never collides — it already carries a per-device suffix.

AP mode (chosen explicitly, or entered automatically as a credential rescue when the WiFi password keeps getting rejected): the device creates its own hotspot, named ESP32-Clock-XXXXXX (a 6-hex-digit suffix from its own MAC, so multiple units stay distinguishable). Long-press anywhere → Carousel → WiFi to open the detail popup, which shows the AP name, IP address, the 6-digit web PIN, and the URL — everything you need to connect:

┌───────────────────────────────────┐
│  📶  ESP32-Clock-8AF8A5           │
│  IP  192.168.4.1                  │
│  🔑  Web PIN: 483921              │
│  http://192.168.4.1               │
└───────────────────────────────────┘

The hotspot itself is open — no WPA2 passphrase. Joining it needs nothing more than picking it from a WiFi list; the PIN is not a WiFi key, it only unlocks the web UI's mutating actions. A new PIN is generated at every boot from a hardware timer seed. Reading it requires physical access to the device, so no fixed credential is ever embedded in the firmware.

Web UI panels

File manager

The Manage Files button opens a second page listing everything stored on the card, so animations and settings can be swapped without ever taking the card out. The list is flat: every file is shown with its full path, rather than folders you click into.

Uploads are size-checked three times so a full card cannot leave a half-written file behind: the browser refuses anything larger than the reported free space, the device rejects the request before accepting a byte, and a running check aborts and deletes the partial file if it overruns anyway.

Two things it deliberately will not do. It never creates folders — upload targets come from a dropdown of folders that already exist — and it refuses to delete or upload while a screen is open on the device, since the animation player may still have that file open. Tap back to the clock first. The listing reaches the root plus two folder levels, which covers the standard layout; anything nested deeper is flagged on the page rather than quietly left out.

Security model

• The AP hotspot is deliberately open (no WPA2 passphrase) — joining it is meant to be frictionless, since it exists purely to reach the web UI.
• The PIN's job is narrower: it authorises the web UI's mutating actions only, never joining the hotspot.
• The PIN is never persisted — it is regenerated at every boot and never written to storage.
• The PIN is not a secret in transit. The web UI is plain HTTP, so it travels in cleartext; it is also printed to the serial console at boot and shown on the device's own status screen by design. It gates casual tampering by someone already within WiFi range, and nothing stronger.
• Downloads and uploads carry the PIN in the URL, so it also lands in browser history. That is forced rather than chosen: a download is a plain link, and during an upload the form fields are not readable until the whole file has already arrived — checking the PIN any later would mean writing it to storage first.
• The WiFi password is never transmitted to the browser — masked on GET, re-injected server-side on POST if unchanged. Downloading config.ini from the file manager bypasses that masking, which is exactly why downloads need the PIN.
• All mutating routes, and the file download route, return HTTP 403 if the PIN is wrong or absent.
• Every file path supplied by the browser is validated before it reaches the card — anything containing .., a backslash, a quote or a control character is rejected outright.
• A fresh PIN on every boot means a captured PIN from a previous session is useless.

🏗 Architecture Notes

• No blocking calls in loop(): Everything runs as LVGL timer callbacks.
• SD ↔ LVGL filesystem bridge: Allows `lv_gif_set_src("S:/...")` natively.
• DST-aware timekeeping: `configTzTime` sets POSIX TZ handling DST automatically.
• Emotion tilt in-place swap: Swaps the GIF path dynamically based on IMU data without rebuilding the overlay.
• Gyro shake/tilt trigger: app_gyro_poll_cb() runs as a 150 ms LVGL timer while RPS or Dice is active. It detects a physical shake via |ΔaccelZ| > 1.8 g between consecutive samples, and a hard tilt via |accelY| > 1.0 g. Both call app_screen_start() identically to a tap. The timer is created on game start and deleted on exit.
• Metronome hardware timer: Beat timing uses two esp_timer hardware timers running outside the LVGL loop. metro_hw_beat_cb() writes directly to ledcChangeFrequency() (safe from timer task context) and sets a volatile flag. A 20 ms LVGL poll timer reads the flag and updates dot colours on the LVGL thread. BPM changes stop and restart the periodic timer with the new period (60,000,000 / bpm µs).
• WiFi state machine: WiFiMulti removed — its blocking channel scan stalled LVGL on every reconnect. Non-blocking WiFi.begin() plus a WiFi.onEvent() disconnect-reason handler tell a rejected password from an unreachable network apart: repeated auth failures trigger an automatic AP rescue, everything else backs off the radio 30s→10min between attempts, fully powered down in between.
• Web configuration server: WebServer on port 80, routes registered once and shared between WiFi and AP modes as the radio comes and goes. Boot PIN seeded from esp_timer_get_time(); authorises only the web UI's mutating routes — the AP hotspot itself is open, no WPA2. POST /config re-injects the masked WiFi password from RAM before writing to SD. POST /settime calls settimeofday() directly. All mutating routes return 403 on PIN mismatch.

🕒 Analog Clock Engine

The analog clock is built purely with LVGL primitive drawing events (`LV_EVENT_DRAW_MAIN`), updated every 60 seconds by `aclock_timer`. It calculates screen coordinates from angles via the `ac_pt(cx, cy, r, angle_deg, *ox, *oy)` helper function.

Drawing Order (Back to Front):

1. Pie Sector: A triangle fan sweeps the elapsed minutes. Opacity ramps dynamically from 30 to 160.
2. Sector Edge Arc: Thin bright blue arc outlining the swept area.
3. Seconds Arc: Very faint thin arc tracking the current second.
4. Clock Ring: Blue circle outline (R=76).
5. Tick Marks: Minor 1px ticks every 6°; medium 2px ticks every 30° (hours).
6. Numbers: 12 hour numbers drawn with `lv_draw_label()` using Montserrat 14.
7. Hands: Thick hour hand (55% R), thin minute hand (80% R), and a central dot.

🔋 Low-Battery Startup Gate

To prevent boot-looping on a dead battery, a low-power gate intercepts the boot process between WiFi initialization and the UI build. If the battery is ≤ 10%:

1. The screen turns black.
2. A single `LV_SYMBOL_BATTERY_EMPTY` label is created (Montserrat 48px).
3. `lv_timer_handler()` is pumped in a tight 5-second loop to flush the UI.
4. The backlight is blanked and the device calls `esp_deep_sleep_start()` with no wakeup source configured.

The device remains asleep until plugged in and the hardware RESET button is pressed.

🗺️ Roadmap

⚡ Build & Flash

Flashing a prebuilt release takes a couple of minutes and needs no toolchain. Building from source is only necessary if you want to change the firmware.

Option A — Flash a prebuilt release (no toolchain)

Every release ships firmware-<version>-esp32c6-full.bin, a complete image containing the bootloader, partition table and application.

1. Download firmware-<version>-esp32c6-full.bin from Releases.
2. Open Espressif's ESP Launchpad in Chrome or Edge — it flashes over WebSerial, which Firefox and Safari do not support.
3. Open the DIY tab, connect the board over USB, click Connect and pick its serial port.
4. Select the .bin file and set the flash address to 0x0.
5. Click Program. The board reboots into the new firmware when it finishes.

The address is 0x0, not 0x1000. The ESP32-C6 places its bootloader at zero; 0x1000 is the offset used by the older Xtensa parts, and using it produces an image that will not boot.

You do not need to erase the flash first — the image already spans it. Your settings are safe either way: they live on the SD card in /config.ini, not in flash.

If you prefer a command line, the same image works with esptool:

esptool --chip esp32c6 write-flash 0x0 firmware-<version>-esp32c6-full.bin

Releases also contain firmware-<version>-esp32c6-app.bin, the application partition on its own, for reflashing over an existing install at 0x10000. Use esptool for that one, not a browser flasher — esptool writes exactly the offset given and erases only the sectors it touches, whereas a browser tool makes it easy to erase the chip or write to the wrong address, either of which removes the bootloader and leaves the board unable to boot. Recover by flashing firmware-<version>-esp32c6-full.bin at 0x0 again.

Option B — Build from source

1. Install ESP32 board support in Arduino IDE.
2. Select ESP32C6 Dev Module.
3. Set USB CDC On Boot to Enabled (Crucial!).
4. Set Flash Size to 8MB (64Mb) and Partition Scheme to 8MB with spiffs (3MB APP/1.5MB SPIFFS).
5. Upload at `921600` baud rate and open Serial Monitor at `115200`.

Troubleshooting