{"id":34760921,"url":"https://github.com/pnstack/template-esp32-project","last_synced_at":"2026-05-28T07:31:46.857Z","repository":{"id":318032837,"uuid":"1069769760","full_name":"pnstack/template-esp32-project","owner":"pnstack","description":"template-esp32-project","archived":false,"fork":false,"pushed_at":"2025-10-04T15:57:08.000Z","size":47,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T17:36:26.642Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pnstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["nvp2k1"]}},"created_at":"2025-10-04T15:34:03.000Z","updated_at":"2025-10-04T15:57:12.000Z","dependencies_parsed_at":"2025-10-04T17:36:28.594Z","dependency_job_id":null,"html_url":"https://github.com/pnstack/template-esp32-project","commit_stats":null,"previous_names":["pnstack/template-esp32-project"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pnstack/template-esp32-project","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnstack%2Ftemplate-esp32-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnstack%2Ftemplate-esp32-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnstack%2Ftemplate-esp32-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnstack%2Ftemplate-esp32-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pnstack","download_url":"https://codeload.github.com/pnstack/template-esp32-project/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pnstack%2Ftemplate-esp32-project/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33599465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-25T06:24:12.395Z","updated_at":"2026-05-28T07:31:46.852Z","avatar_url":"https://github.com/pnstack.png","language":"C++","funding_links":["https://github.com/sponsors/nvp2k1"],"categories":[],"sub_categories":[],"readme":"# ESP32 Template Project\n\nA 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.\n\n## 🚀 Features\n\n- ✅ **WiFi Management**: Auto-reconnect, configurable credentials via web interface\n- ✅ **Web Server**: Async web server with responsive HTML UI\n- ✅ **OTA Updates**: Over-the-air firmware updates for remote devices\n- ✅ **HTTP Client**: Send data to external APIs/servers\n- ✅ **Serial Logging**: Comprehensive logging with multiple log levels\n- ✅ **SPIFFS**: File system for storing configuration and web files\n- ✅ **Clean Architecture**: Well-organized code structure with separation of concerns\n- ✅ **PlatformIO Support**: Complete development environment setup\n\n## 📁 Project Structure\n\n```\ntemplate-esp32-project/\n├── src/                        # Source files\n│   ├── main.cpp               # Main application entry point\n│   ├── wifi_manager.cpp       # WiFi connection and management\n│   ├── web_server.cpp         # Web server implementation\n│   ├── ota_manager.cpp        # OTA update handling\n│   ├── http_client.cpp        # HTTP client for API calls\n│   └── logger.cpp             # Serial logging implementation\n├── include/                    # Header files\n│   ├── config.h               # Configuration constants\n│   ├── wifi_manager.h         # WiFi manager interface\n│   ├── web_server.h           # Web server interface\n│   ├── ota_manager.h          # OTA manager interface\n│   ├── http_client.h          # HTTP client interface\n│   ├── logger.h               # Logger interface\n│   └── credentials.h.example  # Example credentials file\n├── data/                       # Web files (uploaded to SPIFFS)\n│   └── index.html             # Web configuration interface\n├── docs/                       # Documentation\n│   ├── SETUP.md               # Setup and installation guide\n│   ├── OTA_UPDATES.md         # OTA update instructions\n│   └── API.md                 # HTTP API documentation\n├── platformio.ini             # PlatformIO configuration\n├── .gitignore                 # Git ignore file\n└── README.md                  # This file\n```\n\n## 🛠️ Quick Start\n\n### Prerequisites\n\n- [VS Code](https://code.visualstudio.com/) with [PlatformIO IDE](https://platformio.org/install/ide?install=vscode) extension\n- ESP32 development board\n- USB cable\n\n### Installation\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/pnstack/template-esp32-project.git\n   cd template-esp32-project\n   ```\n\n2. **Open in VS Code**:\n   ```bash\n   code .\n   ```\n\n3. **Upload filesystem image** (contains web interface):\n   ```bash\n   pio run --target uploadfs\n   ```\n   Or in VS Code: **PlatformIO → Upload Filesystem Image**\n\n4. **Build and upload firmware**:\n   ```bash\n   pio run --target upload\n   ```\n   Or in VS Code: **PlatformIO → Upload**\n\n5. **Open serial monitor**:\n   ```bash\n   pio device monitor\n   ```\n   Or in VS Code: **PlatformIO → Monitor**\n\n### First-Time Configuration\n\n1. After uploading, the ESP32 will start and display its status in the serial monitor\n2. If no WiFi is configured, you can:\n   - **Option A**: Connect to ESP32's default IP (usually `192.168.4.1`) if it creates an AP\n   - **Option B**: Connect it to your network and find its IP in the serial monitor\n3. Open a web browser and navigate to the ESP32's IP address\n4. Enter your WiFi credentials in the web interface\n5. Click \"Save Configuration\"\n6. The device will reconnect to your WiFi network\n\n## 📖 Documentation\n\n### Getting Started\n- **[Quick Start Guide](QUICKSTART.md)**: Get running in 5 minutes! ⚡\n- **[Setup Guide](docs/SETUP.md)**: Detailed installation and setup instructions\n- **[Project Checklist](CHECKLIST.md)**: Track your setup progress\n\n### Technical Documentation\n- **[Architecture](ARCHITECTURE.md)**: System design and component interactions\n- **[Folder Structure](FOLDER_STRUCTURE.md)**: Project organization and file layout\n- **[API Documentation](docs/API.md)**: HTTP API endpoints and usage examples\n- **[OTA Updates](docs/OTA_UPDATES.md)**: Over-the-air firmware update guide\n\n### Learning Resources\n- **[Examples](docs/EXAMPLES.md)**: Code examples for common use cases\n- **[Contributing](CONTRIBUTING.md)**: How to contribute to this project\n\n## 🎯 Usage Examples\n\n### Configure WiFi via Web Interface\n\n1. Access the device at `http://\u003cdevice-ip\u003e/`\n2. View current status (WiFi connection, IP address, uptime, etc.)\n3. Update WiFi credentials\n4. Monitor device status in real-time\n\n### Send Data to External Server\n\n```cpp\n#include \"http_client.h\"\n\nHTTPClientManager httpClient;\n\nvoid sendSensorData() {\n    float temperature = 25.5;\n    float humidity = 60.0;\n    \n    const char* endpoint = \"http://your-server.com/api/data\";\n    bool success = httpClient.sendSensorData(endpoint, temperature, humidity);\n    \n    if (success) {\n        Logger::info(\"Data sent successfully\");\n    }\n}\n```\n\n### Update Firmware via OTA\n\n```bash\n# Configure upload port in platformio.ini\nupload_protocol = espota\nupload_port = 192.168.1.100\n\n# Upload via OTA\npio run --target upload\n```\n\n### Access Device Status via API\n\n```bash\ncurl http://192.168.1.100/api/status\n```\n\nResponse:\n```json\n{\n  \"device_name\": \"ESP32-Device\",\n  \"uptime\": 123456,\n  \"wifi_connected\": true,\n  \"ssid\": \"MyWiFiNetwork\",\n  \"ip_address\": \"192.168.1.100\",\n  \"signal_strength\": -45\n}\n```\n\n## 🔧 Configuration\n\n### WiFi Settings\n\nEdit `include/config.h`:\n```cpp\n#define WIFI_RECONNECT_INTERVAL 5000  // ms between reconnect attempts\n#define WIFI_MAX_RETRY 20             // max reconnection attempts\n```\n\n### Web Server Port\n\n```cpp\n#define WEBSERVER_PORT 80\n```\n\n### OTA Settings\n\n```cpp\n#define OTA_HOSTNAME \"esp32-device\"\n#define OTA_PASSWORD \"admin\"\n```\n\n### Serial Logging\n\n```cpp\n#define SERIAL_BAUD_RATE 115200\n\n// In your code:\nLogger::setLogLevel(LOG_DEBUG);  // LOG_ERROR, LOG_WARN, LOG_INFO, LOG_DEBUG\n```\n\n## 🧪 Development\n\n### PlatformIO Commands\n\n```bash\n# Build project\npio run\n\n# Upload firmware via USB\npio run --target upload\n\n# Upload filesystem (web files)\npio run --target uploadfs\n\n# Open serial monitor\npio device monitor\n\n# Clean build files\npio run --target clean\n\n# Update libraries\npio lib update\n```\n\n### Adding New Features\n\n1. Create new `.cpp` and `.h` files in `src/` and `include/`\n2. Add your functionality following the existing code structure\n3. Use the Logger for debugging: `Logger::info(\"Your message\")`\n4. Test thoroughly via serial monitor\n\n### Modifying Web Interface\n\n1. Edit `data/index.html`\n2. Upload filesystem: `pio run --target uploadfs`\n3. Refresh your browser\n\n## 📦 Dependencies\n\nThe following libraries are automatically installed by PlatformIO:\n\n- **ESP32 Arduino Framework**: Core ESP32 support\n- **ESP AsyncWebServer**: Asynchronous web server\n- **AsyncTCP**: Async TCP library for ESP32\n- **ArduinoJson**: JSON parsing and generation\n\n## 🐛 Troubleshooting\n\n### Cannot connect to serial port\n\n```bash\n# Linux: Add user to dialout group\nsudo usermod -a -G dialout $USER\n# Log out and log back in\n```\n\n### Upload fails\n\n- Hold the BOOT button during upload\n- Try a different USB cable\n- Reduce upload speed in `platformio.ini`\n\n### WiFi connection issues\n\n- Verify credentials are correct\n- Ensure network is 2.4GHz (ESP32 doesn't support 5GHz)\n- Check router settings (MAC filtering, etc.)\n- View detailed logs in serial monitor\n\n### Web interface not loading\n\n- Upload filesystem first: `pio run --target uploadfs`\n- Verify `data/index.html` exists\n- Check SPIFFS mount status in serial monitor\n\n## 🔒 Security Notes\n\n1. **Change default OTA password** before deployment\n2. **Never commit credentials** to version control (use `credentials.h`, which is in `.gitignore`)\n3. **Use strong WiFi passwords**\n4. **Consider adding API authentication** for production\n5. **Keep firmware updated** to patch security vulnerabilities\n\n## 📝 License\n\nThis project is provided as a template. Feel free to use, modify, and distribute as needed.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\n## 📧 Support\n\nFor questions and support:\n- Check the [documentation](docs/)\n- Review serial monitor logs for errors\n- Create an issue on GitHub\n\n## 🙏 Acknowledgments\n\nBuilt with:\n- [ESP32 Arduino Core](https://github.com/espressif/arduino-esp32)\n- [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer)\n- [ArduinoJson](https://arduinojson.org/)\n- [PlatformIO](https://platformio.org/)\n\n## 🎓 Learning Resources\n\n- [ESP32 Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/)\n- [PlatformIO Documentation](https://docs.platformio.org/)\n- [Arduino Reference](https://www.arduino.cc/reference/en/)\n\n---\n\nMade with ❤️ for the ESP32 community","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpnstack%2Ftemplate-esp32-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpnstack%2Ftemplate-esp32-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpnstack%2Ftemplate-esp32-project/lists"}