ota.h File Reference

Detailed Description

Minimal, batteries-included OTA (Over-The-Air) update system for ESP32.

This module provides a simple, one-liner API for enabling OTA updates on ESP32 devices via Wi-Fi. It supports both Arduino IDE OTA (port 3232) and a web-based update interface at the root path "/".

Key features:

• One-liner setup: beginWiFi() or begin()
• Arduino IDE OTA support with MD5 password authentication
• Web-based OTA UI with Basic Auth (username: "admin")
• Automatic mDNS hostname registration for discovery
• Optional AP fallback mode for Wi-Fi connection failures
• Progress/error/state callbacks for monitoring
• Low polling overhead: ~10-73µs when idle (<0.5% at 60 FPS)

Performance characteristics:

• Web OTA has ZERO polling overhead (runs in separate FreeRTOS task)
• Arduino IDE OTA: ~10-50µs (native) or ~73µs (ArduinoOTA fallback)
• Safe to call poll() every loop iteration for LED animations

Architecture:

• Built on ESP-IDF native APIs (minimal Arduino dependency)
• Uses esp_http_server.h for async Web OTA (separate task)
• Uses esp_wifi.h for network transport
• Uses mdns.h for service discovery
• Future-proof: designed for ESP-IDF component migration

Platform support:

• ESP32 (all variants): Full feature set (Wi-Fi only)
• ESP8266: Reduced feature set (Wi-Fi only)
• Other platforms: Compile-time stubs (no-op)

Security notes:

• Arduino IDE OTA uses MD5 hash of password
• Web UI uses HTTP Basic Auth (plaintext over HTTP)
• Recommended: Use only on trusted networks or with HTTPS

Hardware considerations:

• OTA flash writes consume ~100-200mA on ESP32 (brief spikes to 300mA)
• LED arrays can draw significant current during animations
• Power supply recommendation: 5V 2A+ for ESP32 + moderate LED count
• During OTA update: Reduce LED brightness or count to prevent brownouts
• Use quality USB cable and power source (cheap cables may cause voltage drop)
• Optional: Add 100-1000µF capacitor between VIN/3.3V and GND for stability
• ESP32 variants with external antenna: Verify antenna is properly connected
• Wi-Fi performance: ESP32 only supports 2.4GHz band (not 5GHz)

Example usage:

#include <FastLED.h>
#include "fl/net/ota.h"
 
fl::net::OTA ota;
 
void setup() {
  // Option 1: Full Wi-Fi setup + OTA
  ota.beginWiFi("my-device", "password", "MySSID", "wifi-pass");
 
  // Option 2: OTA only (network already configured)
  // ota.begin("my-device", "password");
 
  // Optional: Set callbacks
  ota.onProgress([](size_t written, size_t total) {
    Serial.printf("Progress: %u/%u\n", written, total);
  });
}
 
void loop() {
  ota.poll();  // Low overhead: ~10-73µs when idle
  // ... your LED animation code ...
}

Ethernet usage:

// For users who need Ethernet support:
// Initialize ETH manually before calling begin()
ETH.begin(/* your board's PHY config */);
while (!ETH.linkUp()) delay(100);
ota.begin("my-device", "password");  // OTA services work over Ethernet too

References:

• ESP-IDF HTTP Server: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_http_server.html
• ESP-IDF OTA: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/ota.html

Definition in file ota.h.

#include "fl/stl/function.h"
#include "fl/stl/shared_ptr.h"
#include "fl/stl/noexcept.h"

Include dependency graph for ota.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	fl::net::OTA
	OTA (Over-The-Air) update manager for ESP32 platforms. More...

Namespaces
namespace	fl
	Base definition for an LED controller.
namespace	fl::net
namespace	fl::net::ota
namespace	fl::platforms

Enumerations
enum class	fl::net::ota::Service : u8 { fl::net::ota::NONE = 0 , fl::net::ota::MDNS_FAILED = 1 << 0 , fl::net::ota::HTTP_FAILED = 1 << 1 , fl::net::ota::ARDUINO_OTA_FAILED = 1 << 2 }
	OTA service initialization status flags. More...