Initial commit
This commit is contained in:
232
README.md
Normal file
232
README.md
Normal file
@ -0,0 +1,232 @@
|
||||
# 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
|
||||
| └── Kconfig.projbuild # To store wifi ssid and pass
|
||||
├── 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
|
||||
|
||||
# Create the file main/Kconfig.projbuild
|
||||
touch main/Kconfig.projbuild
|
||||
```
|
||||
Fill it in with the following:
|
||||
```
|
||||
menu "Wi-Fi Configuration"
|
||||
|
||||
config WIFI_SSID
|
||||
string "WiFi SSID"
|
||||
default ""
|
||||
help
|
||||
The SSID of the WiFi network.
|
||||
|
||||
config WIFI_PASSWORD
|
||||
string "WiFi Password"
|
||||
default ""
|
||||
help
|
||||
The password of the WiFi network.
|
||||
|
||||
endmenu
|
||||
```
|
||||
Then fill in your SSID and Password
|
||||
|
||||
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/
|
||||
Reference in New Issue
Block a user