ESPFileUpdater Library

Overview

The ESPFileUpdater library provides functionality for checking and updating files from a remote server on ESP32/ESP8266 devices. It simplifies the process of managing file updates by handling metadata, calculating file hashes, and ensuring that the local files are up-to-date with the remote versions.

Features

• Check if a remote file is newer than the local version
• Download updates if available
• Manage metadata files to track last modified time, file hashes and file sizes
• Support for max age checks to prevent unnecessary updates
• Will download even if local file missing
• Verified downloads: a file is only replaced once the transfer is confirmed complete and the installed result is size-checked
• Compatible with SPIFFS (tested) and LittleFS (untested)
• Follows 3xx redirects

PlatformIO

Your platformio.ini should contain:

lib_deps =
  trip5/ESPFileUpdater@^1.5.0

Dependent on Internet, File System, and System Time

• It depends on an Internet connection, file system, and system time.
• Only run it after the these 3 process are stable (usually).
• If system time is not available at the time it runs, it will download the file only if it does not already exist on the file system.

---

Usage

To use the ESPFileUpdater library in your project, include the header file and create an instance of the ESPFileUpdater class. Here is a basic example:

#include <WiFi.h>
#include <SPIFFS.h>
#include <ESPFileUpdater.h>

// WiFi credentials
const char* ssid = "YOUR_SSID";
const char* password = "YOUR_PASSWORD";

void setup() {
    Serial.begin(115200);
    SPIFFS.begin(true);
    WiFi.begin(ssid, password);
    
    // Wait for connection
    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.print(".");
    }
    Serial.println("WiFi connected!");

    // Set system time via SNTP
    configTime(0, 0, "pool.ntp.org", "time.nist.gov");
    Serial.print("Waiting for NTP time sync");
    time_t now = time(nullptr);
    while (now < 8 * 3600 * 2) {
        delay(500);
        Serial.print(".");
        now = time(nullptr);
    }
    Serial.println(" Time synchronized!");

    ESPFileUpdater updater(SPIFFS);
    updater.setTimeout(5000);
    ESPFileUpdater::UpdateStatus status = updater.checkAndUpdate("/path/to/local/file.txt", "https://example.com/remote/File.txt", "7d", true);

    if (status == ESPFileUpdater::UPDATED) {
        Serial.println("[ESPFileUpdater: File.txt] Update completed.");
    } else if (status == ESPFileUpdater::NOT_MODIFIED || status == ESPFileUpdater::MAX_AGE_NOT_REACHED) {
        Serial.println("[ESPFileUpdater: File.txt] No update needed.");
    } else {
        Serial.println("[ESPFileUpdater: File.txt] Update failed.");
    }
}

void loop() {
    // Your main code here
}

---

Syntax

ESPFileUpdater::UpdateStatus status = updater.checkAndUpdate("/local/file", "https://remote/file", "maxAge", verbose);

Mandatory

/local/file : path and file on the file system - probably best to start with root /.

https://remote/file : try to use a URL that doesn't do a re-direct - see the FreeRTOS_Task example for a Github retrieval.

Options

maxAge: can accept X hours, X days, X weeks, X months as an argument. If the file does not exist or maxAge is not specified, it will download/update immediately, without any checks. If maxAge is not specified or is empty, then file information will not be saved to a .meta file (it simply downloads the file). You may use abbreviations like hr or h or d or wk or w or mo or m, with or without spaces, with or without s. Although the process can be called often, it will not update if the accompanying .meta file has a date-stamp within that window of time. Be reasonable. Don't check for updates too frequently. If you need to update often, specify 0d to at least check if the remote file is updated.

verbose: use true or false to enable or disable verbose logging to serial. It will update every step of the way. Good for debugging. If not specified, assumed to be false.

You may specify these options in any order, one, both, or not at all.

---

Process

• Checks local FS for file existence
  • Waits for FS readiness
    • If not ready 🛑 [stop]
  • If file does not exist ✅ [update]
    • This initial file may get 1970-01-01 as timestamp in .meta file if system time is incorrect
  • If maxAge not specified ✅ [update]
    • No .meta file is checked, created, or written (if one exists, it will remain)
  • If maxAge is "0" ✅ [update]
    • This initial file may get 1970-01-01 as timestamp in .meta file if system time is incorrect
• Waits for system time to be correct
  • If not ready 🛑 [stop]
• Reads .meta file URL
  • if URL is different than specified ✅ [update]
• Validates the .meta file against the file on disk
  • If the size recorded in the .meta file does not match the actual file size, the .meta file is stale: it is deleted and the file is re-downloaded ✅ [update]
• Reads accompanying .meta file for date
  • If maxAge has not passed then 🛑 [stop]
• Waits for network connection readiness
  • If not ready 🛑 [stop]
• Attempts to retrieve date-stamp from remote file
  • If remote file is newer ✅ [update]
  • If remote file is not newer 🛑 [stop]
• If the server does not support date-stamp, then stream 100KB (at most) from the remote file and generate a hash
  • This hash is compared to the hash stored in the .meta file
  • The response size must be known and no larger than the hashing window, otherwise the hash cannot prove equality ✅ [update]
  • If the sizes differ ✅ [update]
  • If hashes are the same, update the date-stamp in the meta file with the current date 🛑 [stop]
  • If the hashes differ, assume remote file is newer ✅ [update]

Update Process

• Removes leftover .tmp and .bak files from any interrupted attempt
• Downloads to a temporary .tmp file and checks every write
• The transfer must be complete before anything else happens
  • If Content-Length is known, the received byte count must match it exactly
  • For chunked transfers, a terminal zero-length chunk must be received
  • If the response has neither, the body is copied verbatim and a warning is logged (completeness cannot be verified)
  • Truncated, short-written or malformed transfers discard the .tmp file and keep the current file 🛑 [retry or stop]
• Compares the .tmp file size on flash to the received byte count
• Deletes the .meta file before the current file is touched, so it can never describe a missing or partial file
• Renames the current file to .bak, renames the .tmp file into place, then verifies the installed size
  • If any step fails, the .bak file is restored and an error is returned 🛑 [stop]
• Removes the .bak file only after the new file has been verified
• Hashes new file (if not already done during stream)
• Writes the accompanying .meta file last, as the final step

The .meta File

Example

https://example.com/firmware.bin
1718726400
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
131072

• The URL the file was last retrieved from
• UNIX EPOCH of the last update
• Hash
• Size of the file in bytes, verified at the time of the update

The .meta file is written only after the downloaded file has been verified and installed, and it is deleted before the old file is replaced. A .meta file without a size line (from an older version) is still read, and is upgraded the next time it is written.

---

API Reference

ESPFileUpdater Class

• ESPFileUpdater(fs::FS& fs): Constructor that initializes the updater with the specified file system.
• UpdateStatus checkAndUpdate(const String& localPath, const String& remoteURL, const String& maxAge): Checks if the remote file is newer and updates if necessary.

Settings

These can be changed.

setMaxSize(size_t bytes); If the date comparison fails, the file will be streamed from the server (without downloading) and compared to the file on the system. This helps reduce how many bytes are needed to generate a hash for the comparison. 100KB seems a reasonable default but you can increase or decrease the number.

setTimeout(uint32_t ms); You should always do your best to make sure the various components needed for this are ready but there are checks and timeouts as part of the routines to wait if they are ready. If you have time-critical operations, check the FreeRTOS_Task folder so that the updater doesn't block your other operations. 15 seconds is excessive I'm sure but it's just in case.

setUserAgent(const String& ua); Some developers might like to know who / what program is fetching data from them.

setInsecure(bool insecure); Enables insecure mode. It will disable checking of secure certificates when using HTTPS connections. This may help lower memory use (not much likely). Setting to true seems to make connections fail more often.

setBuffer(size_t bytes) Sets the buffer size. Bigger is faster.

setYieldInterval(milliseconds) Sets after how many ms, yield(); is executed. Can help responsiveness. Diminishing returns below 10. Use 0 if other processes need to be greedy.

setRetryCount(uint8_t count) Number of retry attempts on transient network failures. Each retry waits retryDelay ms.

setRetryDelay(uint32_t ms) Delay between retry attempts in milliseconds.

Stack Allocation (with defaults)

  ESPFileUpdater updater(SPIFFS);
  updater.setMaxSize(102400);      // 100 KB max stream size for hashing
  updater.setTimeout(15000);       // 15000ms / 15s for timeout (for each check)
  updater.setUserAgent("MyESPProject/1.2.3 (https://github.com/me/MyESPProject)");
  updater.setInsecure(false);      // insecure mode enabled
  updater.setBuffer(2048);
  updater.setYieldInterval(20);
  updater.setRetryCount(2);
  updater.setRetryDelay(2000);

Heap Allocation

  ESPFileUpdater* updater = nullptr;
  updater = new ESPFileUpdater(SPIFFS);
  updater->setMaxSize(102400);
  updater->setTimeout(15000);
  updater->setUserAgent("MyESPProject/1.2.3 (https://github.com/me/MyESPProject)");
  updater->setInsecure(false);
  updater->setBuffer(2048);
  updater->setYieldInterval(20);
  updater->setRetryCount(2);
  updater->setRetryDelay(2000);

UpdateStatus Enum

• UPDATED: Indicates that the file was updated successfully.
• MAX_AGE_NOT_REACHED: Indicates that the maximum age for updates has not been reached.
• NOT_MODIFIED: Indicates that the remote file has not been modified.
• SERVER_ERROR: Indicates that there was an error connecting to the server.
• FILE_NOT_FOUND: Indicates that the remote file was not found.
• FS_ERROR: Indicates an error with the SPIFFS file system.
• TIME_ERROR: Indicates that system time was not set.
• NETWORK_ERROR: Indicates the network connect was not ready.
• CONNECTION_FAILED: Indicates a connection error; error returned by the upstream library will be shown if verbose is on.
• OUT_OF_MEMORY: Indicates insufficient heap memory for the operation (e.g., SSL connection or buffer allocation failed).

---

SPIFFS Limitations

Keep in mind file names (including path) must be 31 characters or less. Because of this limitation and the fact this library adds extra extensions to the .meta and .tmp download files (plus a transient .bak file), the real usable file name length limit is 27 characters!

I'm not sure about LittleFS limitations.

---

Examples

Check the examples folder for examples of how to use the ESPFileUpdater library in your projects.

---

Update History

Date	Version	Release Notes
2026.10.19	1.5.0	Verified downloads: incomplete transfers are rejected, the swap is size-checked with a .bak rollback, and the .meta file is written only after the swap and records the file size
2026.08.10	1.4.2	Add heap coalesce and reserve so SSL connections always get 40KB contiguous DRAM
2026.06.29	1.4.1	Fixed edge-case of non-chunked binary file corruption
2026.06.26	1.4.0	Retry loop no longer retries on definitive answers
2026.06.17	1.3.0	Added OUT_OF_MEMORY status, heap check before SSL connections, retry logic, nothrow buffer allocation
2026.02.08	1.2.0	Handles chunked transfers properly
2026.02.04	1.1.2	PlatformIO examples and readme fixed
2026.02.03	1.1.1	PlatformIO release
2025.07.20	1.1.0	Settings added
2025.06.29	1.0.0	First release

---

License

This library is released under the MIT License.

See LICENSE for details.