# ESP32-S3 WiFi OTA Template

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

```bash
# 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:
```bash
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

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

### 4. Flash to Device

```bash
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

```bash
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

1. **Connect to WiFi** - The device will automatically connect using stored credentials
2. **Find IP Address** - Check serial monitor for "Got IP: xxx.xxx.xxx.xxx"
3. **Open Web Interface** - Navigate to `http://<device-ip>/` in your browser
4. **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:

```c
// 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

```c
// 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

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

// Register progress callback
ota_server_register_progress_callback(my_progress_handler);
```

### LED Control

```c
// 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:

1. **Remove LED code** if not using RGB LED
2. **Add sensors** - I2C/SPI initialization in main.c
3. **Add MQTT** - Build on WiFi manager callbacks
4. **Add web API** - Extend OTA server with custom endpoints
5. **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/