ESP32 Gallery — Waveshare ESP32-S3-Touch-AMOLED-1.43

A tiny image-gallery launcher for the Waveshare ESP32-S3-Touch-AMOLED-1.43 (466×466 round AMOLED touchscreen). It boots with an animated splash, shows a home screen of app icons, and opens each "app" into a full-screen, swipeable photo gallery — all running from on-board flash, no SD card required.

The stock build ships two albums — family/ and projects/ — populated with placeholder PNGs. Replace them with your own photos to make it yours.

Boot	Home	App
pink "Booting up!" spinner with a live 0–100%, then fades into home	one rounded app icon per folder (the folder's first image); tap to open	swipe ←/→ through photos; swipe up to close (photo shrinks back to its icon, iPhone-style)

⚠️ Board variant. This targets the non-C ESP32-S3-Touch-AMOLED-1.43 (SH8601/CO5300 display, FT3168 touch, microSD slot). It will not run on the 1.43C AI-voice variant (different display pins + CST820 touch). Display/touch drivers are derived from Waveshare's official ESP32-S3-AMOLED-1.43-Demo.

---

Option A — Flash the prebuilt firmware (no setup)

Use this to just put the demo on a board. Nothing to install.

The ready-to-flash image is prebuilt/esp32-gallery.bin (flash at offset 0x0).

Easiest — web browser (Chrome or Edge):

1. Go to https://espressif.github.io/esptool-js/.
2. Plug the board in over USB-C, click Connect, pick the serial port.
3. Add a file at Flash Address 0x0, choose prebuilt/esp32-gallery.bin.
4. Click Program. Done — the board reboots into the gallery.

Or from a terminal (only needs pip install esptool):

esptool --chip esp32s3 write_flash 0x0 prebuilt/esp32-gallery.bin

If the board won't connect, hold BOOT, tap RESET, release BOOT, then retry.

---

Option B — Build from source (develop)

Use this to change the images, the UI, or the code.

1. Install ESP-IDF v5.5.x

Follow Espressif's Get Started guide. ESP-IDF needs Python 3.9–3.13 (if your system Python is newer, point the installer at a supported one, e.g. brew install python@3.12 and run the IDF installer with it).

2. Build & flash

. $IDF_PATH/export.sh            # load the ESP-IDF environment
idf.py set-target esp32s3        # first time only
idf.py -p <PORT> flash monitor   # e.g. -p /dev/cu.usbmodem1101  (Linux: /dev/ttyACM0)

The first build auto-downloads the managed components esp_lcd_sh8601 and lvgl/lvgl (v8). idf.py flash also writes the bundled image to flash, so your photos go with it.

3. Use your own pictures

Each folder under flash_data/ becomes an app on the home screen (its icon is the folder's first image, alphabetically).

flash_data/
├── family/    01.png … 05.png   (placeholders — replace with your photos)
└── projects/  01.png … 05.png

• Drop in your own PNG files (ideally 466×466, the panel size — the round screen clips the corners). Name them so they sort in the order you want (01.png, 02.png, …).
• Add an app: create a new folder under flash_data/, then add one line to the s_album[] array in main/main.c. A new icon appears automatically.
• Rename / remove an album: edit the matching entry in s_album[] to match the folder name on disk.
• Rebuild and flash — the flash filesystem image is regenerated each build.

4. Make a prebuilt binary (for Option A / releases)

idf.py merge-bin                 # -> build/merged-binary.bin (flash at 0x0)
cp build/merged-binary.bin prebuilt/esp32-gallery.bin

---

Hardware wiring (fixed on this board)

Function	Signal	GPIO
AMOLED (QSPI, SPI2)	CS / PCLK / D0 / D1 / D2 / D3 / RST	9 / 10 / 11 / 12 / 13 / 14 / 21
Touch FT3168 (I2C, addr 0x38)	SDA / SCL	47 / 48
microSD slot (unused here; SPI)	CS / MOSI / MISO / SCLK	38 / 39 / 40 / 41

Project layout

.
├── CMakeLists.txt            builds + flashes the FAT image from flash_data/
├── partitions.csv            2M app + 3M read-only "storage" (FAT) partition
├── sdkconfig.defaults        S3 + octal PSRAM; LVGL 16-bit-swap + PNG + spinner; FATFS long names
├── flash_data/               images bundled into flash (family/, projects/)
├── prebuilt/                 ready-to-flash merged firmware (Option A)
├── main/
│   ├── main.c                home launcher, gallery, gestures, loader, background decode
│   ├── display_bsp.c/.h      QSPI panel + FT3168 touch + LVGL bring-up
│   ├── idf_component.yml     deps: esp_lcd_sh8601, lvgl ^8.4
│   └── CMakeLists.txt
└── components/
    ├── read_lcd_id_bsp/      detects SH8601 vs CO5300 (bit-banged read of reg 0xDA)
    └── touch_bsp/            FT3168 touch driver

How it works (notes)

• Storage: images are baked into a read-only FAT partition (storage) generated from flash_data/ by fatfs_create_rawflash_image() in CMakeLists.txt, mounted at /flash.
• Decoding: at boot every PNG is decoded once into a compact RGB565 bitmap in PSRAM (LV_IMG_CF_TRUE_COLOR, ~434 KB each) so all navigation is instant. The decode runs on a low-priority background task calling lodepng_decode32 directly (safe off the LVGL thread because LV_MEM_CUSTOM=y), while the LVGL task animates the loading spinner.
• UI: home is one LVGL screen; the open app is a transparent full-screen overlay on top of it, so the home screen shows through as the photo shrinks away on close.
• Tuning: loader look → build_loader(); slide speed → SLIDE_MS; open/close feel → MINI_ZOOM / APP_ANIM_MS (all in main/main.c).
• Orientation: the UI is rotated 90° so the USB-C port faces you (bottom), set by disp_drv.rotated = LV_DISP_ROT_270 in main/display_bsp.c. Use LV_DISP_ROT_90 for the opposite, or LV_DISP_ROT_NONE for USB on the left. LVGL rotates touch to match.
• microSD: this board has an SD slot (SPI pins above) but the demo doesn't use it. Note: very old / non-spec-compliant cards can fail SD init — use a standard modern card.