115 lines
5.6 KiB
Markdown
115 lines
5.6 KiB
Markdown
# 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.
|
|
* **WS2812 RGB LED Status Feedback:** Utilizes the onboard RGB LED to output real-time visual feedback:
|
|
* 🔵 **Solid Blue:** Idle, waiting for manual trigger.
|
|
* 🟢 **Pulsing Green:** Audio is playing.
|
|
* 🟣 **Pulsing Purple:** Autoplay/Slideshow mode is active.
|
|
* ⚪ **White Flashing:** Confirms a volume change has been triggered.
|
|
* 🔴 **Blinking Red:** Error state (microSD card failed to initialize, or no media files were found).
|
|
|
|
---
|
|
|
|
## 🌐 WiFi Upload Interface Setup
|
|
|
|
To upload new files to your photo frame over WiFi:
|
|
1. Connect your phone, tablet, or computer to the WiFi network hosted by the board:
|
|
* **SSID:** `ESP32-Photo-Frame`
|
|
* **Password:** None (Open Network)
|
|
2. Open your browser and navigate to: **`http://192.168.4.1`**
|
|
3. Choose a file (`.png`, `.mp3`, or `.wav`) and click **Upload to Frame**.
|
|
4. 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-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 9** and acts as the input control.*
|
|
|
|
---
|
|
|
|
## 📁 Repository Structure
|
|
|
|
```text
|
|
├── 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
|
|
|
|
1. Format a microSD card to **FAT32**.
|
|
2. Place your images in the root directory:
|
|
* **Extension:** `.png`
|
|
* **Resolution:** Sized to **172 x 320** pixels.
|
|
3. Place your sound files in the root directory:
|
|
* **Extension:** `.mp3` or `.wav`
|
|
* **Format:** Compressed MP3 or uncompressed PCM WAV.
|
|
4. 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...**:
|
|
1. **`PNGdec`** (by Larry Bank): Decoding and drawing PNGs.
|
|
2. **`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
|
|
1. Connect your board to your computer via USB.
|
|
2. Select the corresponding COM Port under **Tools > Port**.
|
|
3. Click **Upload** (or press `Ctrl+U`).
|