Merge pull request #4998 from willmmiles/fix-4929-sq

Add OTA metadata validation v2

pio-scripts/output_bins.py

@@ -2,6 +2,7 @@ Import('env')
 import os
 import shutil
 import gzip
+import json
 
 OUTPUT_DIR = "build_output{}".format(os.path.sep)
 #OUTPUT_DIR = os.path.join("build_output")
@@ -22,7 +23,8 @@ def create_release(source):
     release_name_def = _get_cpp_define_value(env, "WLED_RELEASE_NAME")
     if release_name_def:
         release_name = release_name_def.replace("\\\"", "")
-        version = _get_cpp_define_value(env, "WLED_VERSION")
+        with open("package.json", "r") as package:
+            version = json.load(package)["version"]        
         release_file = os.path.join(OUTPUT_DIR, "release", f"WLED_{version}_{release_name}.bin")
         release_gz_file = release_file + ".gz"
         print(f"Copying {source} to {release_file}")

pio-scripts/set_metadata.py

@@ -1,5 +1,6 @@
 Import('env')
 import subprocess
+import json
 import re
 
 def get_github_repo():
@@ -42,7 +43,7 @@ def get_github_repo():
         
         # Check if it's a GitHub URL
         if 'github.com' not in remote_url.lower():
-            return 'unknown'
+            return None
         
         # Parse GitHub URL patterns:
         # https://github.com/owner/repo.git
@@ -63,17 +64,53 @@ def get_github_repo():
         if ssh_match:
             return ssh_match.group(1)
         
-        return 'unknown'
+        return None
         
     except FileNotFoundError:
         # Git CLI is not installed or not in PATH
-        return 'unknown'
+        return None
     except subprocess.CalledProcessError:
         # Git command failed (e.g., not a git repo, no remote, etc.)
-        return 'unknown'
+        return None
     except Exception:
         # Any other unexpected error
-        return 'unknown'
+        return None
 
-repo = get_github_repo()
-env.Append(BUILD_FLAGS=[f'-DWLED_REPO=\\"{repo}\\"'])
+# WLED version is managed by package.json; this is picked up in several places
+# - It's integrated in to the UI code
+# - Here, for wled_metadata.cpp
+# - The output_bins script
+# We always take it from package.json to ensure consistency
+with open("package.json", "r") as package:
+    WLED_VERSION = json.load(package)["version"]
+
+def has_def(cppdefs, name):
+    """ Returns true if a given name is set in a CPPDEFINES collection """
+    for f in cppdefs:
+        if isinstance(f, tuple):
+            f = f[0]
+        if f == name:
+            return True
+    return False
+
+
+def add_wled_metadata_flags(env, node):    
+    cdefs = env["CPPDEFINES"].copy()
+
+    if not has_def(cdefs, "WLED_REPO"):
+        repo = get_github_repo()
+        if repo:
+            cdefs.append(("WLED_REPO", f"\\\"{repo}\\\""))
+
+    cdefs.append(("WLED_VERSION", WLED_VERSION))
+
+    # This transforms the node in to a Builder; it cannot be modified again
+    return env.Object(
+        node,
+        CPPDEFINES=cdefs
+    )
+   
+env.AddBuildMiddleware(
+    add_wled_metadata_flags,
+    "*/wled_metadata.cpp"
+)

pio-scripts/set_version.py

@@ -1,8 +0,0 @@
-Import('env')
-import json
-
-PACKAGE_FILE = "package.json"
-
-with open(PACKAGE_FILE, "r") as package:
-    version = json.load(package)["version"]
-    env.Append(BUILD_FLAGS=[f"-DWLED_VERSION={version}"])

platformio.ini

@@ -10,7 +10,25 @@
 # ------------------------------------------------------------------------------
 
 # CI/release binaries
-default_envs = nodemcuv2, esp8266_2m, esp01_1m_full, nodemcuv2_160, esp8266_2m_160, esp01_1m_full_160, nodemcuv2_compat, esp8266_2m_compat, esp01_1m_full_compat, esp32dev, esp32_eth, lolin_s2_mini, esp32c3dev, esp32s3dev_16MB_opi, esp32s3dev_8MB_opi, esp32s3_4M_qspi, esp32_wrover, usermods
+default_envs = nodemcuv2
+               esp8266_2m
+               esp01_1m_full
+               nodemcuv2_160
+               esp8266_2m_160
+               esp01_1m_full_160
+               nodemcuv2_compat
+               esp8266_2m_compat
+               esp01_1m_full_compat
+               esp32dev
+               esp32dev_debug
+               esp32_eth
+               esp32_wrover
+               lolin_s2_mini
+               esp32c3dev
+               esp32s3dev_16MB_opi
+               esp32s3dev_8MB_opi
+               esp32s3_4M_qspi
+               usermods
 
 src_dir  = ./wled00
 data_dir = ./wled00/data
@@ -110,8 +128,7 @@ ldscript_4m1m = eagle.flash.4m1m.ld
 
 [scripts_defaults]
 extra_scripts =
-  pre:pio-scripts/set_version.py
-  pre:pio-scripts/set_repo.py
+  pre:pio-scripts/set_metadata.py
   post:pio-scripts/output_bins.py
   post:pio-scripts/strip-floats.py
   pre:pio-scripts/user_config_copy.py
@@ -431,13 +448,20 @@ board = esp32dev
 platform = ${esp32_idf_V4.platform}
 build_unflags = ${common.build_unflags}
 custom_usermods = audioreactive
-build_flags = ${common.build_flags} ${esp32_idf_V4.build_flags} -D WLED_RELEASE_NAME=\"ESP32_V4\" #-D WLED_DISABLE_BROWNOUT_DET
+build_flags = ${common.build_flags} ${esp32_idf_V4.build_flags} -D WLED_RELEASE_NAME=\"ESP32\" #-D WLED_DISABLE_BROWNOUT_DET
               -DARDUINO_USB_CDC_ON_BOOT=0 ;; this flag is mandatory for "classic ESP32" when building with arduino-esp32 >=2.0.3
 lib_deps = ${esp32_idf_V4.lib_deps}
 monitor_filters = esp32_exception_decoder
 board_build.partitions = ${esp32.default_partitions}
 board_build.flash_mode = dio
 
+[env:esp32dev_debug]
+extends = env:esp32dev
+upload_speed = 921600
+build_flags = ${common.build_flags} ${esp32_idf_V4.build_flags}
+              -D WLED_DEBUG
+              -D WLED_RELEASE_NAME=\"ESP32_DEBUG\"
+
 [env:esp32dev_8M]
 board = esp32dev
 platform = ${esp32_idf_V4.platform}

platformio_override.sample.ini

@@ -541,12 +541,15 @@ build_flags = ${common.build_flags}
   -D WLED_ENABLE_HUB75MATRIX -D NO_GFX
   -D WLED_DEBUG_BUS
   ; -D WLED_DEBUG
+  -D SR_DMTYPE=-1 -D I2S_SDPIN=-1 -D I2S_CKPIN=-1 -D I2S_WSPIN=-1 -D MCLK_PIN=-1  ;; Disable to prevent pin clash
+
 lib_deps = ${esp32_idf_V4.lib_deps}
   https://github.com/mrfaptastic/ESP32-HUB75-MatrixPanel-DMA.git#3.0.11
 
 monitor_filters = esp32_exception_decoder
 board_build.partitions = ${esp32.default_partitions}
 board_build.flash_mode = dio
+custom_usermods = audioreactive
 
 [env:esp32dev_hub75_forum_pinout]
 extends = env:esp32dev_hub75
@@ -555,10 +558,10 @@ build_flags = ${common.build_flags}
               -D WLED_ENABLE_HUB75MATRIX -D NO_GFX 
               -D ESP32_FORUM_PINOUT ;; enable for SmartMatrix default pins
               -D WLED_DEBUG_BUS
+              -D SR_DMTYPE=-1 -D I2S_SDPIN=-1 -D I2S_CKPIN=-1 -D I2S_WSPIN=-1 -D MCLK_PIN=-1  ;; Disable to prevent pin clash
 ; -D WLED_DEBUG
 
 
-
 [env:adafruit_matrixportal_esp32s3]
 ; ESP32-S3 processor, 8 MB flash, 2 MB of PSRAM, dedicated driver pins for HUB75
 board = adafruit_matrixportal_esp32s3
@@ -575,6 +578,7 @@ build_flags = ${common.build_flags} ${esp32s3.build_flags} -D WLED_RELEASE_NAME=
   -D S3_LCD_DIV_NUM=20 ;; Attempt to fix wifi performance issue when panel active with S3 chips
   -D ARDUINO_ADAFRUIT_MATRIXPORTAL_ESP32S3
   -D WLED_DEBUG_BUS
+  -D SR_DMTYPE=-1 -D I2S_SDPIN=-1 -D I2S_CKPIN=-1 -D I2S_WSPIN=-1 -D MCLK_PIN=-1  ;; Disable to prevent pin clash
 
 
 lib_deps = ${esp32s3.lib_deps}
@@ -584,6 +588,7 @@ board_build.partitions = ${esp32.default_partitions}
 board_build.f_flash = 80000000L
 board_build.flash_mode = qio
 monitor_filters = esp32_exception_decoder
+custom_usermods = audioreactive
 
 [env:esp32S3_PSRAM_HUB75]
 ;; MOONHUB HUB75 adapter board
@@ -601,6 +606,8 @@ build_flags = ${common.build_flags} ${esp32s3.build_flags} -D WLED_RELEASE_NAME=
               -D S3_LCD_DIV_NUM=20 ;; Attempt to fix wifi performance issue when panel active with S3 chips
               -D MOONHUB_S3_PINOUT ;; HUB75 pinout
               -D WLED_DEBUG_BUS
+              -D LEDPIN=14 -D BTNPIN=0 -D RLYPIN=15 -D IRPIN=-1 -D AUDIOPIN=-1 ;; defaults that avoid pin conflicts with HUB75
+              -D SR_DMTYPE=1 -D I2S_SDPIN=10 -D I2S_CKPIN=11 -D I2S_WSPIN=12 -D MCLK_PIN=-1  ;; I2S mic
 
 lib_deps = ${esp32s3.lib_deps}
            https://github.com/mrfaptastic/ESP32-HUB75-MatrixPanel-DMA.git#aa28e2a ;; S3_LCD_DIV_NUM fix
@@ -609,3 +616,4 @@ board_build.partitions = ${esp32.default_partitions}
 board_build.f_flash = 80000000L
 board_build.flash_mode = qio
 monitor_filters = esp32_exception_decoder
+custom_usermods = audioreactive

tools/cdata.js

@@ -388,12 +388,6 @@ const char PAGE_dmxmap[] PROGMEM = R"=====()=====";
       name: "PAGE_update",
       method: "gzip",
       filter: "html-minify",
-      mangle: (str) =>
-        str
-          .replace(
-            /function GetV().*\<\/script\>/gms,
-            "</script><script src=\"/settings/s.js?p=9\"></script>"
-          )
     },
     {
       file: "welcome.htm",

wled00/data/update.htm

@@ -17,7 +17,26 @@
 			}
 			window.open(getURL("/update?revert"),"_self");
 		}
-		function GetV() {/*injected values here*/}
+		function GetV() {
+			// Fetch device info via JSON API instead of compiling it in
+			fetch('/json/info')
+				.then(response => response.json())
+				.then(data => {
+					document.querySelector('.installed-version').textContent = `${data.brand} ${data.ver} (${data.vid})`;
+					document.querySelector('.release-name').textContent = data.release;
+					// TODO - assemble update URL
+					// TODO - can this be done at build time?
+					if (data.arch == "esp8266") {
+						toggle('rev');
+					}
+				})
+				.catch(error => {
+					console.log('Could not fetch device info:', error);
+					// Fallback to compiled-in value if API call fails
+					document.querySelector('.installed-version').textContent = 'Unknown';
+					document.querySelector('.release-name').textContent = 'Unknown';
+				});
+		}
 	</script>
 	<style>
 		@import url("style.css");
@@ -27,11 +46,15 @@
 <body onload="GetV()">
 	<h2>WLED Software Update</h2>
 	<form method='POST' action='./update' id='upd' enctype='multipart/form-data' onsubmit="toggle('upd')">
-		Installed version: <span class="sip">WLED ##VERSION##</span><br>
+		Installed version: <span class="sip installed-version">Loading...</span><br>
+		Release: <span class="sip release-name">Loading...</span><br>
 		Download the latest binary: <a href="https://github.com/wled-dev/WLED/releases" target="_blank" 
 		style="vertical-align: text-bottom; display: inline-flex;">
 		<img src="https://img.shields.io/github/release/wled-dev/WLED.svg?style=flat-square"></a><br>
+		<input type="hidden" name="skipValidation" value="" id="sV">
 		<input type='file' name='update' required><br> <!--should have accept='.bin', but it prevents file upload from android app-->
+		<input type='checkbox' onchange="sV.value=checked?1:''" id="skipValidation">
+		<label for='skipValidation'>Ignore firmware validation</label><br>
 		<button type="submit">Update!</button><br>
 		<hr class="sml">
 		<button id="rev" type="button" onclick="cR()">Revert update</button><br>

wled00/dmx_input.cpp

@@ -55,8 +55,8 @@ static dmx_config_t createConfig()
   config.software_version_id = VERSION;
   strcpy(config.device_label, "WLED_MM");
 
-  const std::string versionString = "WLED_V" + std::to_string(VERSION);
-  strncpy(config.software_version_label, versionString.c_str(), 32);
+  const std::string dmxWledVersionString = "WLED_V" + std::to_string(VERSION);
+  strncpy(config.software_version_label, dmxWledVersionString.c_str(), 32);
   config.software_version_label[32] = '\0'; // zero termination in case versionString string was longer than 32 chars
 
   config.personalities[0].description = "SINGLE_RGB";

wled00/e131.cpp

@@ -422,7 +422,7 @@ void prepareArtnetPollReply(ArtPollReply *reply) {
 
   reply->reply_port = ARTNET_DEFAULT_PORT;
 
-  char * numberEnd = versionString;
+  char * numberEnd = (char*) versionString; // strtol promises not to try to edit this.
   reply->reply_version_h = (uint8_t)strtol(numberEnd, &numberEnd, 10);
   numberEnd++;
   reply->reply_version_l = (uint8_t)strtol(numberEnd, &numberEnd, 10);

wled00/ota_update.cpp

@@ -0,0 +1,257 @@
+#include "ota_update.h"
+#include "wled.h"
+
+#ifdef ESP32
+#include <esp_app_format.h>
+#include <esp_ota_ops.h>
+#endif
+
+// Platform-specific metadata locations
+#ifdef ESP32
+constexpr size_t METADATA_OFFSET = 256;          // ESP32: metadata appears after Espressif metadata
+#define UPDATE_ERROR errorString
+#elif defined(ESP8266)
+constexpr size_t METADATA_OFFSET = 0x1000;     // ESP8266: metadata appears at 4KB offset
+#define UPDATE_ERROR getErrorString
+#endif
+constexpr size_t METADATA_SEARCH_RANGE = 512;  // bytes
+
+
+/**
+ * Check if OTA should be allowed based on release compatibility using custom description
+ * @param binaryData Pointer to binary file data (not modified)
+ * @param dataSize Size of binary data in bytes
+ * @param errorMessage Buffer to store error message if validation fails 
+ * @param errorMessageLen Maximum length of error message buffer
+ * @return true if OTA should proceed, false if it should be blocked
+ */
+
+static bool validateOTA(const uint8_t* binaryData, size_t dataSize, char* errorMessage, size_t errorMessageLen) {
+  // Clear error message
+  if (errorMessage && errorMessageLen > 0) {
+    errorMessage[0] = '\0';
+  }
+
+  // Try to extract WLED structure directly from binary data
+  wled_metadata_t extractedDesc;
+  bool hasDesc = findWledMetadata(binaryData, dataSize, &extractedDesc);
+
+  if (hasDesc) {
+    return shouldAllowOTA(extractedDesc, errorMessage, errorMessageLen);
+  } else {
+    // No custom description - this could be a legacy binary
+    if (errorMessage && errorMessageLen > 0) {
+      strncpy_P(errorMessage, PSTR("This firmware file is missing compatibility metadata."), errorMessageLen - 1);
+      errorMessage[errorMessageLen - 1] = '\0';
+    }
+    return false;
+  }
+}
+
+struct UpdateContext {
+  // State flags
+  // FUTURE: the flags could be replaced by a state machine
+  bool replySent = false;
+  bool needsRestart = false;
+  bool updateStarted = false;
+  bool uploadComplete = false;
+  bool releaseCheckPassed = false;
+  String errorMessage;
+
+  // Buffer to hold block data across posts, if needed
+  std::vector<uint8_t> releaseMetadataBuffer;  
+};
+
+
+static void endOTA(AsyncWebServerRequest *request) {
+  UpdateContext* context = reinterpret_cast<UpdateContext*>(request->_tempObject);
+  request->_tempObject = nullptr;
+
+  DEBUG_PRINTF_P(PSTR("EndOTA %x --> %x (%d)\n"), (uintptr_t)request,(uintptr_t) context, context ? context->uploadComplete : 0);
+  if (context) {
+    if (context->updateStarted) {  // We initialized the update
+      // We use Update.end() because not all forms of Update() support an abort.
+      // If the upload is incomplete, Update.end(false) should error out.
+      if (Update.end(context->uploadComplete)) {
+        // Update successful!
+        #ifndef ESP8266
+        bootloopCheckOTA(); // let the bootloop-checker know there was an OTA update
+        #endif
+        doReboot = true;
+        context->needsRestart = false;
+      }
+    }
+
+    if (context->needsRestart) {
+      strip.resume();
+      UsermodManager::onUpdateBegin(false);
+      #if WLED_WATCHDOG_TIMEOUT > 0
+      WLED::instance().enableWatchdog();
+      #endif
+    }
+    delete context;
+  }
+};
+
+static bool beginOTA(AsyncWebServerRequest *request, UpdateContext* context)
+{
+  #ifdef ESP8266
+  Update.runAsync(true);
+  #endif  
+
+  if (Update.isRunning()) {
+      request->send(503);
+      setOTAReplied(request);
+      return false;
+  }
+
+  #if WLED_WATCHDOG_TIMEOUT > 0
+  WLED::instance().disableWatchdog();
+  #endif
+  UsermodManager::onUpdateBegin(true); // notify usermods that update is about to begin (some may require task de-init)
+  
+  strip.suspend();
+  backupConfig(); // backup current config in case the update ends badly
+  strip.resetSegments();  // free as much memory as you can
+  context->needsRestart = true;
+
+  DEBUG_PRINTF_P(PSTR("OTA Update Start, %x --> %x\n"), (uintptr_t)request,(uintptr_t) context);
+
+  auto skipValidationParam = request->getParam("skipValidation", true);
+  if (skipValidationParam && (skipValidationParam->value() == "1")) {
+    context->releaseCheckPassed = true;
+    DEBUG_PRINTLN(F("OTA validation skipped by user"));
+  }
+  
+  // Begin update with the firmware size from content length
+  size_t updateSize = request->contentLength() > 0 ? request->contentLength() : ((ESP.getFreeSketchSpace() - 0x1000) & 0xFFFFF000);
+  if (!Update.begin(updateSize)) {    
+    context->errorMessage = Update.UPDATE_ERROR();
+    DEBUG_PRINTF_P(PSTR("OTA Failed to begin: %s\n"), context->errorMessage.c_str());
+    return false;
+  }
+  
+  context->updateStarted = true;
+  return true;
+}
+
+// Create an OTA context object on an AsyncWebServerRequest
+// Returns true if successful, false on failure.
+bool initOTA(AsyncWebServerRequest *request) {
+  // Allocate update context
+  UpdateContext* context = new (std::nothrow) UpdateContext {};  
+  if (context) {
+    request->_tempObject = context;
+    request->onDisconnect([=]() { endOTA(request); });  // ensures we restart on failure
+  };
+
+  DEBUG_PRINTF_P(PSTR("OTA Update init, %x --> %x\n"), (uintptr_t)request,(uintptr_t) context);
+  return (context != nullptr);
+}
+
+void setOTAReplied(AsyncWebServerRequest *request) {
+  UpdateContext* context = reinterpret_cast<UpdateContext*>(request->_tempObject);
+  if (!context) return;
+  context->replySent = true;
+};
+
+// Returns pointer to error message, or nullptr if OTA was successful.
+std::pair<bool, String> getOTAResult(AsyncWebServerRequest* request) {
+  UpdateContext* context = reinterpret_cast<UpdateContext*>(request->_tempObject);
+  if (!context) return { true, F("OTA context unexpectedly missing") };
+  if (context->replySent) return { false, {} };
+  if (context->errorMessage.length()) return { true, context->errorMessage };
+
+  if (context->updateStarted) {
+    // Release the OTA context now.
+    endOTA(request);
+    if (Update.hasError()) {
+      return { true, Update.UPDATE_ERROR() };
+    } else {
+      return { true, {} };
+    }
+  }
+
+  // Should never happen
+  return { true, F("Internal software failure") };
+}
+
+
+
+void handleOTAData(AsyncWebServerRequest *request, size_t index, uint8_t *data, size_t len, bool isFinal)
+{
+  UpdateContext* context = reinterpret_cast<UpdateContext*>(request->_tempObject);
+  if (!context) return;
+
+  //DEBUG_PRINTF_P(PSTR("HandleOTAData: %d %d %d\n"), index, len, isFinal);
+
+  if (context->replySent || (context->errorMessage.length())) return;
+
+  if (index == 0) {
+    if (!beginOTA(request, context)) return;
+  }
+
+  // Perform validation if we haven't done it yet and we have reached the metadata offset
+  if (!context->releaseCheckPassed && (index+len) > METADATA_OFFSET) {
+    // Current chunk contains the metadata offset
+    size_t availableDataAfterOffset = (index + len) - METADATA_OFFSET;
+
+    DEBUG_PRINTF_P(PSTR("OTA metadata check: %d in buffer, %d received, %d available\n"), context->releaseMetadataBuffer.size(), len, availableDataAfterOffset);
+
+    if (availableDataAfterOffset >= METADATA_SEARCH_RANGE) {
+      // We have enough data to validate, one way or another
+      const uint8_t* search_data = data;
+      size_t search_len = len;
+      
+      // If we have saved data, use that instead
+      if (context->releaseMetadataBuffer.size()) {
+        // Add this data
+        context->releaseMetadataBuffer.insert(context->releaseMetadataBuffer.end(), data, data+len);
+        search_data = context->releaseMetadataBuffer.data();
+        search_len = context->releaseMetadataBuffer.size();
+      }
+
+      // Do the checking
+      char errorMessage[128];
+      bool OTA_ok = validateOTA(search_data, search_len, errorMessage, sizeof(errorMessage));
+      
+      // Release buffer if there was one
+      context->releaseMetadataBuffer = decltype(context->releaseMetadataBuffer){};
+      
+      if (!OTA_ok) {
+        DEBUG_PRINTF_P(PSTR("OTA declined: %s\n"), errorMessage);
+        context->errorMessage = errorMessage;
+        context->errorMessage += F(" Enable 'Ignore firmware validation' to proceed anyway.");
+        return;
+      } else {
+        DEBUG_PRINTLN(F("OTA allowed: Release compatibility check passed"));
+        context->releaseCheckPassed = true;
+      }        
+    } else {
+      // Store the data we just got for next pass
+      context->releaseMetadataBuffer.insert(context->releaseMetadataBuffer.end(), data, data+len);
+    }
+  }
+
+  // Check if validation was still pending (shouldn't happen normally)
+  // This is done before writing the last chunk, so endOTA can abort 
+  if (isFinal && !context->releaseCheckPassed) {
+    DEBUG_PRINTLN(F("OTA failed: Validation never completed"));
+    // Don't write the last chunk to the updater: this will trip an error later
+    context->errorMessage = F("Release check data never arrived?");
+    return;
+  }
+
+  // Write chunk data to OTA update (only if release check passed or still pending)
+  if (!Update.hasError()) {
+    if (Update.write(data, len) != len) {
+      DEBUG_PRINTF_P(PSTR("OTA write failed on chunk %zu: %s\n"), index, Update.UPDATE_ERROR());
+    }
+  }
+
+  if(isFinal) {
+    DEBUG_PRINTLN(F("OTA Update End"));
+    // Upload complete
+    context->uploadComplete = true;
+  }
+}

wled00/ota_update.h

@@ -0,0 +1,52 @@
+//  WLED OTA update interface
+
+#include <Arduino.h>
+#ifdef ESP8266
+  #include <Updater.h>
+#else
+   #include <Update.h>
+#endif
+
+#pragma once
+
+// Platform-specific metadata locations
+#ifdef ESP32
+#define BUILD_METADATA_SECTION ".rodata_custom_desc"
+#elif defined(ESP8266)
+#define BUILD_METADATA_SECTION ".ver_number"
+#endif
+
+
+class AsyncWebServerRequest;
+
+/**
+ *  Create an OTA context object on an AsyncWebServerRequest
+ * @param request Pointer to web request object
+ * @return true if allocation was successful, false if not
+ */
+bool initOTA(AsyncWebServerRequest *request);
+
+/**
+ *  Indicate to the OTA subsystem that a reply has already been generated
+ * @param request Pointer to web request object
+ */
+void setOTAReplied(AsyncWebServerRequest *request);
+
+/**
+ *  Retrieve the OTA result.
+ * @param request Pointer to web request object
+ * @return bool indicating if a reply is necessary; string with error message if the update failed.
+ */
+std::pair<bool, String> getOTAResult(AsyncWebServerRequest *request);
+
+/**
+ *  Process a block of OTA data.  This is a passthrough of an ArUploadHandlerFunction.
+ * Requires that initOTA be called on the handler object before any work will be done.
+ * @param request Pointer to web request object
+ * @param index Offset in to uploaded file
+ * @param data New data bytes
+ * @param len Length of new data bytes
+ * @param isFinal Indicates that this is the last block
+ * @return bool indicating if a reply is necessary; string with error message if the update failed.
+ */
+void handleOTAData(AsyncWebServerRequest *request, size_t index, uint8_t *data, size_t len, bool isFinal);

wled00/wled.cpp

@@ -1,6 +1,7 @@
 #define WLED_DEFINE_GLOBAL_VARS //only in one source file, wled.cpp!
 #include "wled.h"
 #include "wled_ethernet.h"
+#include "ota_update.h"
 #ifdef WLED_ENABLE_AOTA
   #define NO_OTA_PORT
   #include <ArduinoOTA.h>
@@ -173,9 +174,9 @@ void WLED::loop()
   if (millis() - heapTime > 15000) {
     uint32_t heap = getFreeHeapSize();
     if (heap < MIN_HEAP_SIZE && lastHeap < MIN_HEAP_SIZE) {
-      DEBUG_PRINTF_P(PSTR("Heap too low! %u\n"), heap);
-      forceReconnect = true;
+      DEBUG_PRINTF_P(PSTR("Heap too low! %u\n"), heap);      
       strip.resetSegments(); // remove all but one segments from memory
+      if (!Update.isRunning()) forceReconnect = true;
     } else if (heap < MIN_HEAP_SIZE) {
       DEBUG_PRINTLN(F("Heap low, purging segments."));
       strip.purgeSegments();

wled00/wled.h

@@ -194,6 +194,7 @@ using PSRAMDynamicJsonDocument = BasicJsonDocument<PSRAM_Allocator>;
 #include "colors.h"
 #include "bus_manager.h"
 #include "FX.h"
+#include "wled_metadata.h"
 
 #ifndef CLIENT_SSID
   #define CLIENT_SSID DEFAULT_CLIENT_SSID
@@ -270,20 +271,6 @@ using PSRAMDynamicJsonDocument = BasicJsonDocument<PSRAM_Allocator>;
 #define STRINGIFY(X) #X
 #define TOSTRING(X) STRINGIFY(X)
 
-#ifndef WLED_VERSION
-  #define WLED_VERSION dev
-#endif
-#ifndef WLED_RELEASE_NAME
-  #define WLED_RELEASE_NAME "Custom"
-#endif
-#ifndef WLED_REPO
-  #define WLED_REPO "unknown"
-#endif
-
-// Global Variable definitions
-WLED_GLOBAL char versionString[] _INIT(TOSTRING(WLED_VERSION));
-WLED_GLOBAL char releaseString[] _INIT(WLED_RELEASE_NAME); // must include the quotes when defining, e.g -D WLED_RELEASE_NAME=\"ESP32_MULTI_USREMODS\"
-WLED_GLOBAL char repoString[] _INIT(WLED_REPO);
 #define WLED_CODENAME "Niji"
 
 // AP and OTA default passwords (for maximum security change them!)

wled00/wled_metadata.cpp

@@ -0,0 +1,164 @@
+#include "ota_update.h"
+#include "wled.h"
+#include "wled_metadata.h"
+
+#ifndef WLED_VERSION
+  #warning WLED_VERSION was not set - using default value of 'dev'
+  #define WLED_VERSION dev
+#endif
+#ifndef WLED_RELEASE_NAME
+  #warning WLED_RELEASE_NAME was not set - using default value of 'Custom'
+  #define WLED_RELEASE_NAME "Custom"
+#endif
+#ifndef WLED_REPO
+  // No warning for this one: integrators are not always on GitHub
+  #define WLED_REPO "unknown"
+#endif
+
+constexpr uint32_t WLED_CUSTOM_DESC_MAGIC = 0x57535453;  // "WSTS" (WLED System Tag Structure)
+constexpr uint32_t WLED_CUSTOM_DESC_VERSION = 1;
+
+// Compile-time validation that release name doesn't exceed maximum length
+static_assert(sizeof(WLED_RELEASE_NAME) <= WLED_RELEASE_NAME_MAX_LEN, 
+              "WLED_RELEASE_NAME exceeds maximum length of WLED_RELEASE_NAME_MAX_LEN characters");
+
+
+/**
+ * DJB2 hash function (C++11 compatible constexpr)
+ * Used for compile-time hash computation to validate structure contents
+ * Recursive for compile time: not usable at runtime due to stack depth
+ * 
+ * Note that this only works on strings; there is no way to produce a compile-time
+ * hash of a struct in C++11 without explicitly listing all the struct members.
+ * So for now, we hash only the release name.  This suffices for a "did you find 
+ * valid structure" check.
+ * 
+ */
+constexpr uint32_t djb2_hash_constexpr(const char* str, uint32_t hash = 5381) {
+    return (*str == '\0') ? hash : djb2_hash_constexpr(str + 1, ((hash << 5) + hash) + *str);
+}
+
+/**
+ * Runtime DJB2 hash function for validation
+ */
+inline uint32_t djb2_hash_runtime(const char* str) {
+    uint32_t hash = 5381;
+    while (*str) {
+        hash = ((hash << 5) + hash) + *str++;
+    }
+    return hash;
+}
+
+// ------------------------------------
+// GLOBAL VARIABLES
+// ------------------------------------
+// Structure instantiation for this build 
+const wled_metadata_t __attribute__((section(BUILD_METADATA_SECTION))) WLED_BUILD_DESCRIPTION = {
+    WLED_CUSTOM_DESC_MAGIC,                   // magic
+    WLED_CUSTOM_DESC_VERSION,                 // version 
+    TOSTRING(WLED_VERSION),
+    WLED_RELEASE_NAME,                        // release_name
+    std::integral_constant<uint32_t, djb2_hash_constexpr(WLED_RELEASE_NAME)>::value, // hash - computed at compile time; integral_constant enforces this
+};
+
+static const char repoString_s[] PROGMEM = WLED_REPO;
+const __FlashStringHelper* repoString = FPSTR(repoString_s);
+
+static const char productString_s[] PROGMEM = WLED_PRODUCT_NAME;
+const __FlashStringHelper* productString = FPSTR(productString_s);
+
+static const char brandString_s [] PROGMEM = WLED_BRAND;
+const __FlashStringHelper* brandString = FPSTR(brandString_s);
+
+
+
+/**
+ * Extract WLED custom description structure from binary
+ * @param binaryData Pointer to binary file data
+ * @param dataSize Size of binary data in bytes
+ * @param extractedDesc Buffer to store extracted custom description structure
+ * @return true if structure was found and extracted, false otherwise
+ */
+bool findWledMetadata(const uint8_t* binaryData, size_t dataSize, wled_metadata_t* extractedDesc) {
+  if (!binaryData || !extractedDesc || dataSize < sizeof(wled_metadata_t)) {
+    return false;
+  }
+
+  for (size_t offset = 0; offset <= dataSize - sizeof(wled_metadata_t); offset++) {
+    if ((binaryData[offset]) == static_cast<char>(WLED_CUSTOM_DESC_MAGIC)) {
+      // First byte matched; check next in an alignment-safe way
+      uint32_t data_magic;
+      memcpy(&data_magic, binaryData + offset, sizeof(data_magic));
+      
+      // Check for magic number
+      if (data_magic == WLED_CUSTOM_DESC_MAGIC) {            
+        wled_metadata_t candidate;
+        memcpy(&candidate, binaryData + offset, sizeof(candidate));
+
+        // Found potential match, validate version
+        if (candidate.desc_version != WLED_CUSTOM_DESC_VERSION) {
+          DEBUG_PRINTF_P(PSTR("Found WLED structure at offset %u but version mismatch: %u\n"), 
+                        offset, candidate.desc_version);
+          continue;
+        }
+        
+        // Validate hash using runtime function
+        uint32_t expected_hash = djb2_hash_runtime(candidate.release_name);
+        if (candidate.hash != expected_hash) {
+          DEBUG_PRINTF_P(PSTR("Found WLED structure at offset %u but hash mismatch\n"), offset);
+          continue;
+        }
+        
+        // Valid structure found - copy entire structure
+        *extractedDesc = candidate;
+        
+        DEBUG_PRINTF_P(PSTR("Extracted WLED structure at offset %u: '%s'\n"), 
+                      offset, extractedDesc->release_name);
+        return true;
+      }
+    }
+  }
+  
+  DEBUG_PRINTLN(F("No WLED custom description found in binary"));
+  return false;
+}
+
+
+/**
+ * Check if OTA should be allowed based on release compatibility using custom description
+ * @param binaryData Pointer to binary file data (not modified)
+ * @param dataSize Size of binary data in bytes
+ * @param errorMessage Buffer to store error message if validation fails 
+ * @param errorMessageLen Maximum length of error message buffer
+ * @return true if OTA should proceed, false if it should be blocked
+ */
+
+bool shouldAllowOTA(const wled_metadata_t& firmwareDescription, char* errorMessage, size_t errorMessageLen) {
+  // Clear error message
+  if (errorMessage && errorMessageLen > 0) {
+    errorMessage[0] = '\0';
+  }
+
+  // Validate compatibility using extracted release name
+  // We make a stack copy so we can print it safely
+  char safeFirmwareRelease[WLED_RELEASE_NAME_MAX_LEN];
+  strncpy(safeFirmwareRelease, firmwareDescription.release_name, WLED_RELEASE_NAME_MAX_LEN - 1);
+  safeFirmwareRelease[WLED_RELEASE_NAME_MAX_LEN - 1] = '\0';
+  
+  if (strlen(safeFirmwareRelease) == 0) {
+    return false;
+  }  
+
+  if (strncmp_P(safeFirmwareRelease, releaseString, WLED_RELEASE_NAME_MAX_LEN) != 0) {
+    if (errorMessage && errorMessageLen > 0) {
+      snprintf_P(errorMessage, errorMessageLen, PSTR("Firmware compatibility mismatch: current='%s', uploaded='%s'."), 
+               releaseString, safeFirmwareRelease);
+      errorMessage[errorMessageLen - 1] = '\0'; // Ensure null termination
+    }
+    return false;
+  }
+
+  // TODO: additional checks go here
+
+  return true;
+}

wled00/wled_metadata.h

@@ -0,0 +1,61 @@
+/*
+  WLED build metadata
+
+  Manages and exports information about the current WLED build.
+*/
+
+
+#pragma once
+
+#include <cstdint>
+#include <string.h>
+#include <WString.h>
+
+#define WLED_VERSION_MAX_LEN 48
+#define WLED_RELEASE_NAME_MAX_LEN 48
+
+/**
+ * WLED Custom Description Structure
+ * This structure is embedded in platform-specific sections at an approximately
+ * fixed offset in ESP32/ESP8266 binaries, where it can be found and validated 
+ * by the OTA process.
+ */
+typedef struct {
+    uint32_t magic;               // Magic number to identify WLED custom description
+    uint32_t desc_version;        // Structure version for future compatibility
+    char wled_version[WLED_VERSION_MAX_LEN];
+    char release_name[WLED_RELEASE_NAME_MAX_LEN]; // Release name (null-terminated)    
+    uint32_t hash;               // Structure sanity check
+} __attribute__((packed)) wled_metadata_t;
+
+
+// Global build description
+extern const wled_metadata_t WLED_BUILD_DESCRIPTION;
+
+// Convenient metdata pointers
+#define versionString (WLED_BUILD_DESCRIPTION.wled_version)   // Build version, WLED_VERSION
+#define releaseString (WLED_BUILD_DESCRIPTION.release_name)   // Release name,  WLED_RELEASE_NAME
+extern const __FlashStringHelper* repoString;                       // Github repository (if available)
+extern const __FlashStringHelper* productString;                    // Product, WLED_PRODUCT_NAME -- deprecated, use WLED_RELEASE_NAME
+extern const __FlashStringHelper* brandString ;                     // Brand
+
+
+// Metadata analysis functions
+
+/**
+ * Extract WLED custom description structure from binary data
+ * @param binaryData Pointer to binary file data
+ * @param dataSize Size of binary data in bytes
+ * @param extractedDesc Buffer to store extracted custom description structure
+ * @return true if structure was found and extracted, false otherwise
+ */
+bool findWledMetadata(const uint8_t* binaryData, size_t dataSize, wled_metadata_t* extractedDesc);
+
+/**
+ * Check if OTA should be allowed based on release compatibility
+ * @param firmwareDescription Pointer to firmware description
+ * @param errorMessage Buffer to store error message if validation fails 
+ * @param errorMessageLen Maximum length of error message buffer
+ * @return true if OTA should proceed, false if it should be blocked
+ */
+bool shouldAllowOTA(const wled_metadata_t& firmwareDescription, char* errorMessage, size_t errorMessageLen);

wled00/wled_server.cpp

@@ -1,11 +1,7 @@
 #include "wled.h"
 
 #ifndef WLED_DISABLE_OTA
-  #ifdef ESP8266
-    #include <Updater.h>
-  #else
-    #include <Update.h>
-  #endif
+  #include "ota_update.h"  
 #endif
 #include "html_ui.h"
 #include "html_settings.h"
@@ -404,59 +400,47 @@ void initServer()
   });
 
   server.on(_update, HTTP_POST, [](AsyncWebServerRequest *request){
-    if (!correctPIN) {
-      serveSettings(request, true); // handle PIN page POST request
-      return;
-    }
-    if (otaLock) {
-      serveMessage(request, 401, FPSTR(s_accessdenied), FPSTR(s_unlock_ota), 254);
-      return;
-    }
-    if (Update.hasError()) {
-      serveMessage(request, 500, F("Update failed!"), F("Please check your file and retry!"), 254);
+    if (request->_tempObject) {
+      auto ota_result = getOTAResult(request);
+      if (ota_result.first) {
+        if (ota_result.second.length() > 0) {
+          serveMessage(request, 500, F("Update failed!"), ota_result.second, 254);
+        } else {
+          serveMessage(request, 200, F("Update successful!"), FPSTR(s_rebooting), 131);
+        }
+      }
     } else {
-      serveMessage(request, 200, F("Update successful!"), FPSTR(s_rebooting), 131);
-      #ifndef ESP8266
-      bootloopCheckOTA(); // let the bootloop-checker know there was an OTA update
-      #endif
-      doReboot = true;
+      // No context structure - something's gone horribly wrong
+      serveMessage(request, 500, F("Update failed!"), F("Internal server fault"), 254);
     }
   },[](AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len, bool isFinal){
-    IPAddress client  = request->client()->remoteIP();
-    if (((otaSameSubnet && !inSameSubnet(client)) && !strlen(settingsPIN)) || (!otaSameSubnet && !inLocalSubnet(client))) {
-      DEBUG_PRINTLN(F("Attempted OTA update from different/non-local subnet!"));
-      request->send(401, FPSTR(CONTENT_TYPE_PLAIN), FPSTR(s_accessdenied));
-      return;
-    }
-    if (!correctPIN || otaLock) return;
-    if(!index){
-      DEBUG_PRINTLN(F("OTA Update Start"));
-      #if WLED_WATCHDOG_TIMEOUT > 0
-      WLED::instance().disableWatchdog();
-      #endif
-      UsermodManager::onUpdateBegin(true); // notify usermods that update is about to begin (some may require task de-init)
-      lastEditTime = millis(); // make sure PIN does not lock during update
-      strip.suspend();
-      backupConfig(); // backup current config in case the update ends badly
-      strip.resetSegments();  // free as much memory as you can
-      #ifdef ESP8266
-      Update.runAsync(true);
-      #endif
-      Update.begin((ESP.getFreeSketchSpace() - 0x1000) & 0xFFFFF000);
-    }
-    if(!Update.hasError()) Update.write(data, len);
-    if(isFinal){
-      if(Update.end(true)){
-        DEBUG_PRINTLN(F("Update Success"));
-      } else {
-        DEBUG_PRINTLN(F("Update Failed"));
-        strip.resume();
-        UsermodManager::onUpdateBegin(false); // notify usermods that update has failed (some may require task init)
-        #if WLED_WATCHDOG_TIMEOUT > 0
-        WLED::instance().enableWatchdog();
-        #endif
+    if (index == 0) { 
+      // Allocate the context structure
+      if (!initOTA(request)) {
+        return; // Error will be dealt with after upload in response handler, above
       }
+
+      // Privilege checks
+      IPAddress client  = request->client()->remoteIP();
+      if (((otaSameSubnet && !inSameSubnet(client)) && !strlen(settingsPIN)) || (!otaSameSubnet && !inLocalSubnet(client))) {        
+        DEBUG_PRINTLN(F("Attempted OTA update from different/non-local subnet!"));
+        serveMessage(request, 401, FPSTR(s_accessdenied), F("Client is not on local subnet."), 254);
+        setOTAReplied(request);
+        return;
+      }
+      if (!correctPIN) {
+        serveMessage(request, 401, FPSTR(s_accessdenied), FPSTR(s_unlock_cfg), 254);
+        setOTAReplied(request);
+        return;
+      };
+      if (otaLock) {
+        serveMessage(request, 401, FPSTR(s_accessdenied), FPSTR(s_unlock_ota), 254);
+        setOTAReplied(request);
+        return;
+      }      
     }
+
+    handleOTAData(request, index, data, len, isFinal);
   });
 #else
   const auto notSupported = [](AsyncWebServerRequest *request){

wled00/xml.cpp

@@ -671,16 +671,6 @@ void getSettingsJS(byte subPage, Print& settingsScript)
     UsermodManager::appendConfigData(settingsScript);
   }
 
-  if (subPage == SUBPAGE_UPDATE) // update
-  {
-    char tmp_buf[128];
-    fillWLEDVersion(tmp_buf,sizeof(tmp_buf));
-    printSetClassElementHTML(settingsScript,PSTR("sip"),0,tmp_buf);
-    #ifndef ARDUINO_ARCH_ESP32
-    settingsScript.print(F("toggle('rev');"));  // hide revert button on ESP8266
-    #endif
-  }
-
   if (subPage == SUBPAGE_2D) // 2D matrices
   {
     printSetFormValue(settingsScript,PSTR("SOMP"),strip.isMatrix);