A reusable template for ESP32-S3 projects featuring WiFi connectivity and Over-The-Air (OTA) firmware updates. This project is designed for the SparkFun ESP32-S3 Thing Plus but can be adapted for other ESP32-S3 boards.

Features

🌐 WiFi Manager - Automatic connection with credential storage in NVS
🔄 OTA Updates - Web-based firmware updates with drag-and-drop interface
💡 RGB LED Control - WS2812 driver for visual feedback (GPIO 46)
🔧 Docker-based Development - No local ESP-IDF installation required
📦 Modular Design - Easy to extend with additional features

Hardware Requirements

SparkFun ESP32-S3 Thing Plus (or compatible ESP32-S3 board)
USB-C cable (data capable, not charge-only)
2.4GHz WiFi network

Project Structure

.
├── main/
│   ├── main.c              # Main application
│   ├── wifi_manager.c/h    # WiFi connection management
│   ├── ota_server.c/h      # OTA update server
│   ├── led_strip.c/h       # RGB LED driver
│   └── CMakeLists.txt      # Component configuration
├── partitions.csv          # Flash partition table (4MB)
├── sdkconfig              # Project configuration (auto-generated)
├── .gitignore             # Git ignore rules
└── README.md              # This file

Quick Start

1. Prerequisites

Docker installed on your system
Git for version control
Terminal/command line access

2. Clone and Configure

# Clone the repository (or create new project)
git clone <your-repo-url>
cd esp32-s3-template

# Edit WiFi credentials in main/main.c
#define WIFI_SSID      "YourWiFiNetwork"
#define WIFI_PASSWORD  "YourPassword"

A new project can be started with:

docker run --user $(id -u):$(id -g) --rm -v $PWD:/project -w /project -it espressif/idf:latest idf.py create-project <project-name>

3. Build the Project

docker run --user $(id -u):$(id -g) --rm -v $PWD:/project -w /project -it espressif/idf:latest idf.py build

4. Flash to Device

docker run --privileged --rm -v $PWD:/project -w /project --device=/dev/ttyACM0 -it espressif/idf:latest idf.py flash -p /dev/ttyACM0

Note

: Your device might appear as /dev/ttyUSB0 or another port. Check with ls /dev/tty* after connecting.

5. Monitor Serial Output

docker run --privileged --rm -v $PWD:/project -w /project --device=/dev/ttyACM0 -it espressif/idf:latest idf.py monitor -p /dev/ttyACM0

Press Ctrl+] to exit the monitor.

Using OTA Updates

Connect to WiFi - The device will automatically connect using stored credentials
Find IP Address - Check serial monitor for "Got IP: xxx.xxx.xxx.xxx"
Open Web Interface - Navigate to http://<device-ip>/ in your browser
Upload Firmware:
- Build new version: Update APP_VERSION in main.c
- Run build command again
- Upload build/<project-name>.bin via web interface
- Device will automatically restart with new firmware

Testing OTA Updates

Try these modifications to test OTA:

// Version 2.0.0 - Faster blinking
#define APP_VERSION    "2.0.0"
#define BLINK_DELAY_MS 200  // Was 500

// Version 3.0.0 - Different colors
static const color_t colors[] = {
    {255, 128, 0, "Orange"},
    {128, 0, 255, "Purple"},
    {255, 192, 203, "Pink"},
};

API Usage

WiFi Manager

// Set new credentials
wifi_manager_set_credentials("NewSSID", "NewPassword");

// Check connection status
if (wifi_manager_is_connected()) {
    // Connected
}

// Clear stored credentials
wifi_manager_clear_credentials();

OTA Server

// Set version string
ota_server_set_version("2.0.0");

// Register progress callback
ota_server_register_progress_callback(my_progress_handler);

LED Control

// Set LED color
led_strip_set_pixel(strip, 0, 255, 0, 0);  // Red
led_strip_refresh(strip);

// Turn off
led_strip_clear(strip);

Troubleshooting

Build Issues

Ensure Docker is running and you have internet connection
Clean build: idf.py fullclean before building

Flash Issues

Check USB cable is data-capable (not charge-only)
Try different USB port
Verify device path (/dev/ttyACM0, /dev/ttyUSB0, etc.)
May need to add user to dialout group: sudo usermod -a -G dialout $USER

WiFi Connection Issues

Verify 2.4GHz network (ESP32 doesn't support 5GHz)
Check for special characters in SSID/password
Look for trailing spaces in SSID
Monitor serial output for specific error codes

OTA Issues

Ensure device has sufficient free space (check web interface)
Verify binary file size fits in OTA partition (1.25MB max)
Check same network connectivity between computer and ESP32

Memory Layout

Partition	Type	Size	Purpose
nvs	data	16KB	WiFi credentials
otadata	data	8KB	OTA selection
phy_init	data	4KB	PHY calibration
factory	app	1.25MB	Factory firmware
ota_0	app	1.25MB	OTA partition 1
ota_1	app	1.25MB	OTA partition 2

Security Considerations

For production deployments:

Add authentication to OTA web interface
Use HTTPS for OTA updates
Implement firmware signature verification
Store WiFi credentials securely
Consider encrypted flash storage

Extending the Template

This template provides core functionality. Add your application-specific features:

Remove LED code if not using RGB LED
Add sensors - I2C/SPI initialization in main.c
Add MQTT - Build on WiFi manager callbacks
Add web API - Extend OTA server with custom endpoints
Add BLE - ESP32-S3 supports dual-mode

License

[Your License Here]

Acknowledgments

Built with ESP-IDF v6.0
Designed for SparkFun ESP32-S3 Thing Plus
RGB LED driver uses RMT peripheral

For more information about ESP-IDF: https://docs.espressif.com/