ESP32 Template Project

A comprehensive ESP32 project template with WiFi configuration, web server, OTA updates, HTTP client, and serial logging. Built with Arduino framework and PlatformIO for easy development and deployment.

🚀 Features

• ✅ WiFi Management: Auto-reconnect, configurable credentials via web interface
• ✅ Web Server: Async web server with responsive HTML UI
• ✅ OTA Updates: Over-the-air firmware updates for remote devices
• ✅ HTTP Client: Send data to external APIs/servers
• ✅ Serial Logging: Comprehensive logging with multiple log levels
• ✅ SPIFFS: File system for storing configuration and web files
• ✅ Clean Architecture: Well-organized code structure with separation of concerns
• ✅ PlatformIO Support: Complete development environment setup

📁 Project Structure

template-esp32-project/
├── src/                        # Source files
│   ├── main.cpp               # Main application entry point
│   ├── wifi_manager.cpp       # WiFi connection and management
│   ├── web_server.cpp         # Web server implementation
│   ├── ota_manager.cpp        # OTA update handling
│   ├── http_client.cpp        # HTTP client for API calls
│   └── logger.cpp             # Serial logging implementation
├── include/                    # Header files
│   ├── config.h               # Configuration constants
│   ├── wifi_manager.h         # WiFi manager interface
│   ├── web_server.h           # Web server interface
│   ├── ota_manager.h          # OTA manager interface
│   ├── http_client.h          # HTTP client interface
│   ├── logger.h               # Logger interface
│   └── credentials.h.example  # Example credentials file
├── data/                       # Web files (uploaded to SPIFFS)
│   └── index.html             # Web configuration interface
├── docs/                       # Documentation
│   ├── SETUP.md               # Setup and installation guide
│   ├── OTA_UPDATES.md         # OTA update instructions
│   └── API.md                 # HTTP API documentation
├── platformio.ini             # PlatformIO configuration
├── .gitignore                 # Git ignore file
└── README.md                  # This file

🛠️ Quick Start

Prerequisites

• VS Code with PlatformIO IDE extension
• ESP32 development board
• USB cable

Installation

1. Clone the repository:

   git clone https://github.com/pnstack/template-esp32-project.git
   cd template-esp32-project

2. Open in VS Code:

   code .

3. Upload filesystem image (contains web interface):

   pio run --target uploadfs

   Or in VS Code: PlatformIO → Upload Filesystem Image

4. Build and upload firmware:

   pio run --target upload

   Or in VS Code: PlatformIO → Upload

5. Open serial monitor:

   pio device monitor

   Or in VS Code: PlatformIO → Monitor

First-Time Configuration

1. After uploading, the ESP32 will start and display its status in the serial monitor
2. If no WiFi is configured, you can:
   • Option A: Connect to ESP32's default IP (usually 192.168.4.1) if it creates an AP
   • Option B: Connect it to your network and find its IP in the serial monitor
3. Open a web browser and navigate to the ESP32's IP address
4. Enter your WiFi credentials in the web interface
5. Click "Save Configuration"
6. The device will reconnect to your WiFi network

📖 Documentation

Getting Started

• Quick Start Guide: Get running in 5 minutes! ⚡
• Setup Guide: Detailed installation and setup instructions
• Project Checklist: Track your setup progress

Technical Documentation

• Architecture: System design and component interactions
• Folder Structure: Project organization and file layout
• API Documentation: HTTP API endpoints and usage examples
• OTA Updates: Over-the-air firmware update guide

Learning Resources

• Examples: Code examples for common use cases
• Contributing: How to contribute to this project

🎯 Usage Examples

Configure WiFi via Web Interface

1. Access the device at http://<device-ip>/
2. View current status (WiFi connection, IP address, uptime, etc.)
3. Update WiFi credentials
4. Monitor device status in real-time

Send Data to External Server

#include "http_client.h"

HTTPClientManager httpClient;

void sendSensorData() {
    float temperature = 25.5;
    float humidity = 60.0;
    
    const char* endpoint = "http://your-server.com/api/data";
    bool success = httpClient.sendSensorData(endpoint, temperature, humidity);
    
    if (success) {
        Logger::info("Data sent successfully");
    }
}

Update Firmware via OTA

# Configure upload port in platformio.ini
upload_protocol = espota
upload_port = 192.168.1.100

# Upload via OTA
pio run --target upload

Access Device Status via API

curl http://192.168.1.100/api/status

Response:

{
  "device_name": "ESP32-Device",
  "uptime": 123456,
  "wifi_connected": true,
  "ssid": "MyWiFiNetwork",
  "ip_address": "192.168.1.100",
  "signal_strength": -45
}

🔧 Configuration

WiFi Settings

Edit include/config.h:

#define WIFI_RECONNECT_INTERVAL 5000  // ms between reconnect attempts
#define WIFI_MAX_RETRY 20             // max reconnection attempts

Web Server Port

#define WEBSERVER_PORT 80

OTA Settings

#define OTA_HOSTNAME "esp32-device"
#define OTA_PASSWORD "admin"

Serial Logging

#define SERIAL_BAUD_RATE 115200

// In your code:
Logger::setLogLevel(LOG_DEBUG);  // LOG_ERROR, LOG_WARN, LOG_INFO, LOG_DEBUG

🧪 Development

PlatformIO Commands

# Build project
pio run

# Upload firmware via USB
pio run --target upload

# Upload filesystem (web files)
pio run --target uploadfs

# Open serial monitor
pio device monitor

# Clean build files
pio run --target clean

# Update libraries
pio lib update

Adding New Features

1. Create new .cpp and .h files in src/ and include/
2. Add your functionality following the existing code structure
3. Use the Logger for debugging: Logger::info("Your message")
4. Test thoroughly via serial monitor

Modifying Web Interface

1. Edit data/index.html
2. Upload filesystem: pio run --target uploadfs
3. Refresh your browser

📦 Dependencies

The following libraries are automatically installed by PlatformIO:

• ESP32 Arduino Framework: Core ESP32 support
• ESP AsyncWebServer: Asynchronous web server
• AsyncTCP: Async TCP library for ESP32
• ArduinoJson: JSON parsing and generation

🐛 Troubleshooting

Cannot connect to serial port

# Linux: Add user to dialout group
sudo usermod -a -G dialout $USER
# Log out and log back in

Upload fails

• Hold the BOOT button during upload
• Try a different USB cable
• Reduce upload speed in platformio.ini

WiFi connection issues

• Verify credentials are correct
• Ensure network is 2.4GHz (ESP32 doesn't support 5GHz)
• Check router settings (MAC filtering, etc.)
• View detailed logs in serial monitor

Web interface not loading

• Upload filesystem first: pio run --target uploadfs
• Verify data/index.html exists
• Check SPIFFS mount status in serial monitor

🔒 Security Notes

1. Change default OTA password before deployment
2. Never commit credentials to version control (use credentials.h, which is in .gitignore)
3. Use strong WiFi passwords
4. Consider adding API authentication for production
5. Keep firmware updated to patch security vulnerabilities

📝 License

This project is provided as a template. Feel free to use, modify, and distribute as needed.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

📧 Support

For questions and support:

• Check the documentation
• Review serial monitor logs for errors
• Create an issue on GitHub

🙏 Acknowledgments

Built with:

• ESP32 Arduino Core
• ESPAsyncWebServer
• ArduinoJson
• PlatformIO

🎓 Learning Resources

• ESP32 Documentation
• PlatformIO Documentation
• Arduino Reference

---

Made with ❤️ for the ESP32 community