ESP32-S3-LCD-1.47 Sound & Picture Player

This repository contains a responsive, dual-core firmware application developed for the Waveshare ESP32-S3-LCD-1.47 development board.

The application reads PNG images and compressed MP3 / uncompressed WAV audio files from a microSD card, renders the images on the onboard ST7789 LCD display, and plays matching soundbites over an external I2S audio DAC.

🚀 Key Features

WiFi Web Upload Interface: Hosts a local WiFi network and web server so you can upload pictures and audio files directly to the microSD card from your phone or computer.
Alpha-Numeric Media Pairing: Scans the root of the microSD card for PNG images and audio files (.wav or .mp3), sorting and matching them alphabetically (e.g., 01_image.png pairs with 01_sound.mp3).
Dual-Core Software Decoding: Spawns a background task pinned to Core 0 running the ESP32-audioI2S decoding loop. This prevents audio dropouts or stutters during heavy display updates on Core 1.
Interactive Multi-Click Gestures: You can control slide progression, audio status, and volume from the board's single physical button:
- Single Click: Next photo/audio pair.
- Double Click: Toggle Pause / Resume audio playback.
- Triple Click: Previous photo/audio pair.
- Quadruple Click: Cycle volume through levels 4, 8, 12, 16, and 20 (on a 0-21 scale).
- Long Press (>1.5s): Toggle Autoplay slideshow mode.
Visual Status Indicators: Disabled on this Touch board version to prevent SCLK (GPIO 38) line contention.

🌐 WiFi Upload Interface Setup

To upload new files to your photo frame over WiFi:

Connect your phone, tablet, or computer to the WiFi network hosted by the board:
- SSID: love
- Password: love
Open your browser and navigate to: http://192.168.4.1
Choose a file (.png, .mp3, or .wav) and click Upload to Frame.
The file will be saved directly to the microSD card. The board will automatically re-scan the card, and the new files will be indexed and ready to play!

🔌 Hardware Connections (External I2S DAC)

Because the Waveshare ESP32-S3-Touch-LCD-1.47 does not have built-in audio amplification or a speaker, you must connect an external I2S DAC/Amplifier (e.g., MAX98357A or PCM5102) to the exposed headers.

Configure the pin connections as follows:

Board Pin (Header)	ESP32-S3 GPIO	Function
GPIO 1	1	I2S BCLK (Bit Clock)
GPIO 2	2	I2S LRCK / WS (Frame Clock)
GPIO 4	4	I2S DIN / SD (Data Out from ESP)
3V3 / VBUS (5V)	VCC	Power Supply
GND	GND	Ground Reference

Note: The physical BOOT button is permanently connected to GPIO 0 and acts as the input control.

📁 Repository Structure

├── sound_picture_app/         # Custom Application Source
│   ├── sound_picture_app.ino  # Main coordinator, button click gesture parser, state machine
│   ├── Display_ST7789.h/.cpp  # Waveshare display initialization & backlight control
│   ├── Display_PNG.h/.cpp     # PNGdec utility for decoding and drawing images
│   ├── SD_Card.h/.cpp         # SD_MMC mount and folder retrieval helpers
│   ├── Audio_Player.h/.cpp    # background ESP32-audioI2S player task wrapper
│   └── Web_Server.h/.cpp      # local SoftAP WiFi file upload panel
├── ESP32-S3-LCD-1.47-Demo/    # Waveshare Official Reference Demos
└── README.md                  # This file

💾 microSD Card Setup

Format a microSD card to FAT32.
Place your images in the root directory:
- Extension: .png
- Resolution: Sized to 172 x 320 pixels.
Place your sound files in the root directory:
- Extension: .mp3 or .wav
- Format: Compressed MP3 or uncompressed PCM WAV.
Ensure file names map alphabetically:
- photo1.png <--> sound1.mp3
- photo2.png <--> sound2.wav

🛠️ Software Setup & Flashing (Arduino IDE)

1. Board Package Installation

Make sure you have the official Espressif board package installed:

Go to File > Preferences > Additional Boards Manager URLs and add: https://espressif.github.io/arduino-esp32/package_esp32_index.json
Go to Tools > Board > Boards Manager, search for esp32 (by Espressif Systems), and install version 3.0.2 or higher.

2. Install Required Libraries

You need to install the following two libraries in the IDE via Sketch > Include Library > Manage Libraries...:

PNGdec (by Larry Bank): Decoding and drawing PNGs.
ESP32-audioI2S (by Wolle / schreibfaul1): Asynchronous MP3/WAV decoding.

3. Select Board Configurations

Go to the Tools menu and set the following variables:

Board: ESP32S3 Dev Module
USB CDC On Boot: Enabled (Required to see print logs over the native USB port)
Upload Speed: 921600
Flash Size: 16MB (128Mb)
Partition Scheme: 16MB Flash (3MB APP/9.9MB FATFS)

4. Upload

Connect your board to your computer via USB.
Select the corresponding COM Port under Tools > Port.
Click Upload (or press Ctrl+U).

5.2 KiB Raw Blame History