184 lines
7.1 KiB
Markdown
184 lines
7.1 KiB
Markdown
# ESP32-S3 AI Smart Speaker Control & Diagnostics Suite
|
||
|
||
This repository contains the complete firmware, development socket server, and real-time operations dashboard for the **Waveshare ESP32-S3-AUDIO-Board-EN** (No Battery version).
|
||
|
||
The project implements a state-driven smart speaker capable of auto-connecting to Wi-Fi, linking to a remote WebSocket server via a configurable WebSocket endpoint, playing back high-quality audio chimes via I2S, driving WS2812B LEDs, and receiving real-time control actions (such as volume adjustments, sound trigger cues, and voice synthesis broadcasts) from a dedicated operations dashboard.
|
||
|
||
---
|
||
|
||
## System Architecture
|
||
|
||
```mermaid
|
||
graph TD
|
||
Dashboard[Enterprise Monitor Dashboard <br/> Port 8902] <-->|JSON Control Protocol| DevServer[WebSocket API Gateway <br/> Port 8901]
|
||
ESP32[ESP32-S3 Audio Board] <-->|Secure WebSocket Link| DevServer
|
||
|
||
subgraph ESP32-S3 Core Drivers
|
||
I2S[I2S Audio Output - ES8311 DAC]
|
||
LED[WS2812B 7-Ring RGB LEDs]
|
||
WiFi[WiFi Manager State Machine]
|
||
SPIFFS[SPIFFS Audio Assets Model]
|
||
end
|
||
|
||
ESP32 --> I2S
|
||
ESP32 --> LED
|
||
ESP32 --> WiFi
|
||
ESP32 --> SPIFFS
|
||
```
|
||
|
||
---
|
||
|
||
## 1. Hardware Specifications & Pin Mapping
|
||
|
||
* **SoC:** ESP32-S3R8 (Dual-core 32-bit LX7, 240 MHz, 16MB Flash, 8MB Octal PSRAM).
|
||
* **Audio DAC (Playback):** ES8311 mono codec connected via I2C & I2S.
|
||
* **Audio ADC (Recording):** ES7210 microphone encoder.
|
||
* **Audio PA Enable:** Controlled via Pin 8 of the TCA9555 I2C I/O expander.
|
||
* **LED Ring:** 7 WS2812B RGB LEDs connected to GPIO 38.
|
||
|
||
| Signal Name | ESP32-S3 GPIO | Signal Description |
|
||
|:---|:---|:---|
|
||
| **I2S MCLK** | GPIO 12 | Audio Master Clock |
|
||
| **I2S BCLK** | GPIO 13 | Audio Bit Clock |
|
||
| **I2S LRCK** | GPIO 14 | Audio Left/Right Word Clock |
|
||
| **I2S DIN** | GPIO 15 | Microphone Data Input (ADC) |
|
||
| **I2S DOUT** | GPIO 16 | Speaker Data Output (DAC) |
|
||
| **I2C SDA** | GPIO 11 | Codec & Expander I2C Data |
|
||
| **I2C SCL** | GPIO 10 | Codec & Expander I2C Clock |
|
||
| **RGB LED** | GPIO 38 | WS2812B Data Line |
|
||
|
||
---
|
||
|
||
## 2. Workspace Setup & Prerequisites
|
||
|
||
### ESP-IDF SDK Target:
|
||
* Install **ESP-IDF v6.0.1** (target framework `esp32s3`).
|
||
* Ensure that the environment paths are configured (or run under your standard ESP-IDF terminal shell).
|
||
|
||
---
|
||
|
||
## 3. Configuration & Deployment
|
||
|
||
Before building, you must configure your network credentials and target endpoints:
|
||
|
||
### Wi-Fi Configuration
|
||
Copy the template configuration file `wifi-credentials.example` in the project root to a new file named `wifi-credentials` (which is excluded from Git in `.gitignore`):
|
||
```bash
|
||
cp wifi-credentials.example wifi-credentials
|
||
```
|
||
Open `wifi-credentials` and write your actual credentials:
|
||
```text
|
||
SSID="Your_WiFi_Name"
|
||
PASSWORD="Your_WiFi_Password"
|
||
```
|
||
*Note: CMake automatically reads this file during configuration to compile the private header `wifi_credentials.h` inside your build folder. Never commit your private `wifi-credentials` file.*
|
||
|
||
### WebSocket Server URL
|
||
Open `main/spiffs/server_url.txt` and write the target WebSocket server URL (e.g. your local gateway or public Cloudflare domain):
|
||
```text
|
||
wss://example.com
|
||
```
|
||
*Note: This text file is packaged into the SPIFFS partition and loaded dynamically on board boot.*
|
||
|
||
---
|
||
|
||
## 4. Hardware Model Variants
|
||
|
||
The firmware supports two hardware model profiles: **DEV-1** (default) and **PROTO-1**. The active model is controlled by the `device-config` file in the project root.
|
||
|
||
### Switching Models
|
||
|
||
Open `device-config` and set the `MODEL` field to either `DEV-1` or `PROTO-1`:
|
||
|
||
```text
|
||
# For the standard development board (default):
|
||
MODEL=DEV-1
|
||
|
||
# For the prototype board with additional peripherals:
|
||
MODEL=PROTO-1
|
||
```
|
||
|
||
> **Important:** After changing `device-config`, you **must perform a clean rebuild** to regenerate `device_config.h` and recompile the correct pin mappings. Run `scripts/clean.bat` before `scripts/build.bat`.
|
||
|
||
---
|
||
|
||
### DEV-1 Profile
|
||
|
||
The standard Waveshare ESP32-S3-AUDIO-Board-EN pin configuration:
|
||
|
||
| Peripheral | GPIO | Mode |
|
||
|:---|:---|:---|
|
||
| I2C SCL | GPIO 10 | I2C Clock |
|
||
| I2C SDA | GPIO 11 | I2C Data |
|
||
| I2S MCLK | GPIO 12 | Audio Master Clock |
|
||
| I2S BCLK | GPIO 13 | Audio Bit Clock |
|
||
| I2S LRCK | GPIO 14 | Audio Word Select |
|
||
| I2S DIN (Microphone) | GPIO 15 | I2S Input |
|
||
| I2S DOUT (Speaker) | GPIO 16 | I2S Output |
|
||
| RGB LEDs (7x WS2812B) | GPIO 38 | WS2812 Signal |
|
||
| PA Enable | EXIO 8 | TCA9555 I/O Expander |
|
||
|
||
---
|
||
|
||
### PROTO-1 Profile
|
||
|
||
Inherits all DEV-1 audio functionality but remaps the LED signal pin and adds three new peripheral drivers:
|
||
|
||
| Peripheral | GPIO | Mode |
|
||
|:---|:---|:---|
|
||
| I2S DIN (Microphone) | GPIO 15 | I2S Input *(remapped: DOUT ↔ DIN swapped vs DEV-1)* |
|
||
| I2S DOUT (Speaker) | GPIO 16 | I2S Output |
|
||
| RGB LEDs (WS2812) | **GPIO 9** | WS2812 Signal *(changed from GPIO 38)* |
|
||
| **Haptics Motor** | **GPIO 5** | PWM Output (LEDC, 1kHz, 10-bit) |
|
||
| **Ambient Light Sensor** | **GPIO 4** | ADC1 Channel 3, Analog Input |
|
||
| **Touch Sensor** | **GPIO 7** | Digital Input |
|
||
|
||
**Additional PROTO-1 runtime behaviours:**
|
||
- A background FreeRTOS task (`proto1_sensor_task`) polls the LDR and touch GPIO every 100ms and updates the shared device state.
|
||
- Ambient light ADC values (0–4095) are scaled to 0–100% in the web dashboard.
|
||
- Haptic intensity is controllable via the WebSocket `set_haptics` command (0–100%).
|
||
- All three sensor readings are included in uplink telemetry state reports.
|
||
- The web dashboard automatically unlocks the **Haptic Vibration** control slider for PROTO-1 devices; it appears greyed-out with a *PROTO-1 Only* indicator for DEV-1 devices.
|
||
|
||
---
|
||
|
||
## 5. Build, Flash & Logging
|
||
|
||
Use the preconfigured batch scripts inside the `/scripts` directory to compile and flash the firmware:
|
||
|
||
* **Compile Code:** Run `scripts/build.bat` to run incremental CMake compiles.
|
||
* **Flash Firmware:** Run `scripts/flash.bat` to build and flash the application to `COM5` (at `460800` baud) alongside generated SPIFFS images.
|
||
* **Monitor Console Logs:** Run `scripts/monitor.bat` to read live serial logs from `COM5` (press `Ctrl + ]` to exit).
|
||
* **Clean Build:** Run `scripts/clean.bat` to delete compilation cache.
|
||
|
||
---
|
||
|
||
## 6. Starting the Servers
|
||
|
||
To run the full diagnostics suite, launch both the API Gateway and the Dashboard Operations Console:
|
||
|
||
### Start the API Gateway (Port 8901)
|
||
The gateway handles data routing, client registration, and active device command routing:
|
||
```bash
|
||
cd dev-server
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
### Start the Operations Dashboard (Port 8902)
|
||
The dashboard displays connection metrics, device health parameters, and hosts the command center:
|
||
```bash
|
||
cd monitor-server
|
||
npm install
|
||
npm start
|
||
```
|
||
Open **`http://localhost:8902`** in your browser to access the control panel.
|
||
|
||
---
|
||
|
||
## 7. Remote Routing & Tunnel Configuration
|
||
|
||
If deploying publicly, ensure your local configurations route traffic properly:
|
||
1. Map Cloudflare tunnel configuration to forward requests for `example.com` to `http://localhost:8901`.
|
||
2. The Dashboard client code automatically scales and shifts its endpoint from `ws://localhost:8901` (when accessed locally) to `wss://example.com` (when accessed remotely) to match your environment.
|