esp32FOTA

The esp32FOTA library uses a JSON manifest hosted on a webserver to determine if an update is available. You can define firmware updates using two different strategies. You cannot mix these strategies in a single manifest entry.

1. Complete URL (Firmware Only)

Use the url field to provide a direct link to the .bin file. This method does not support filesystem updates (SPIFFS, LittleFS, etc.).

2. Component-based URLs (Firmware + Filesystem)

Use host, port, and bin to construct the firmware URL, and optional spiffs, littlefs, or fatfs keys for filesystem updates. This method allows updating both the firmware and the filesystem in one cycle.

Important: If the url field is present, all other URL-related fields (like host, port, bin, or filesystem keys) will be ignored.

{
    "type": "esp32-fota-http",
    "version": "1.0.0",
    "host": "example.com",
    "port": 443,
    "bin": "/firmware.bin",
    "littlefs": "/filesystem.bin"
}

A single JSON manifest can contain an array of objects to support multiple hardware types or multiple version entries for the same type. The library selects the entry where the type matches the string passed to the esp32FOTA constructor.

Multiple Hardware Types

[
   {
      "type":"esp32-fota-http",
      "version":"0.0.2",
      "url":"http://192.168.0.100/fota/esp32-fota-http-2.bin"
   },
   {
      "type":"esp32-other-hardware",
      "version":"0.0.3",
      "url":"http://192.168.0.100/fota/esp32-other-hardware.bin"
   }
]

Multiple Versions for One Type

[
   {
      "type":"esp32-fota-http",
      "version":"0.0.2",
      "url":"http://192.168.0.100/fota/esp32-fota-0.0.2.bin"
   },
   {
      "type":"esp32-fota-http",
      "version":"0.0.3",
      "url":"http://192.168.0.100/fota/esp32-fota-0.0.3.bin",
      "spiffs":"http://192.168.0.100/fota/esp32-fota-0.0.3.spiffs.bin"
   }
]

To ensure firmware integrity, you can sign your firmware binary using a private key. The ESP32 will verify the signature using a public key stored in a dedicated SPIFFS partition before applying the update.

1. Generate the signature

Use OpenSSL to create a signature file from your firmware binary and private key:

openssl dgst -sign priv_key.pem -keyform PEM -sha256 -out firmware.sign -binary firmware.bin

2. Create the signed image

Concatenate the signature and the firmware binary into a single .img file. The library expects the signature to be the first 512 bytes of the file:

cat firmware.sign firmware.bin > firmware.img

3. Deploy and Verify

1. Upload firmware.img to your OTA server.
2. Update your firmware.json to point to the new firmware.img URL.
3. Ensure your ESP32 has a SPIFFS partition containing your rsa_key.pub. This partition is only distributed once and is not touched during subsequent OTA updates.

During the update check, the ESP32 downloads firmware.img, extracts the first 512 bytes (the signature), and validates it against the remaining image using the public key. If valid, the device resets into the new firmware.

You can initialize the library using a simple constructor for basic use cases, or use FOTAConfig_t for advanced configurations like signature verification and custom certificates.

Early Initialization (Simple)

Best for standard HTTP updates with a known name and version.

Late Initialization (Advanced)

Use getConfig() and setConfig() to set parameters like semantic versioning, signature checking, and custom root certificates.

Note: If you are using a filesystem (like SPIFFS) to store certificates, include the filesystem header (e.g., #include <SPIFFS.h>) before including esp32FOTA.hpp.

### Early Init
```cpp
#include <esp32FOTA.hpp>

esp32FOTA esp32FOTA("esp32-fota-http", "1.0.0");

void setup() {
  // ...
  esp32FOTA.setManifestURL("http://server/fota/fota.json");
}

Late Init

#include <SPIFFS.h>
#include <esp32FOTA.hpp>

esp32FOTA FOTA;

void setup() {
  auto cfg = FOTA.getConfig();
  cfg.name          = "esp32-fota-http";
  cfg.manifest_url  = "http://server/fota/fota.json";
  cfg.sem           = SemverClass(1, 0, 0);
  cfg.check_sig     = false;
  cfg.unsafe        = true; // Disable cert check for TLS
  FOTA.setConfig(cfg);
}