feat(update): add phase tracking and improve download reliability

cbrown350 · cbrown350 · commit 0486f7aee9fd · 2026-02-12T16:55:56.000-07:00
- Add phase tracking (firmware/filesystem/complete) to update process for better observability
- Add Content-Length verification to detect incomplete downloads
- Add yield() in download loop to allow async web server to handle status requests
- Extend restart delay to 5 seconds to allow status poll to see COMPLETE state
- Improve error messages with specific failure details (incomplete, write failures)
- Simplify release workflow by removing duplicate latest release creation step
- Cast size values to unsigned long for proper logging display
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -198,7 +198,7 @@ jobs:
         with:
           tag_name: ${{ steps.version.outputs.version }}
           name: Release ${{ steps.version.outputs.version }}
-          make_latest: false
+          make_latest: true
           files: |
             artifacts/firmware.bin
             artifacts/littlefs.bin
@@ -231,63 +231,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Delete Existing Latest Release & Tag
-        continue-on-error: true
-        run: |
-          # Delete the release via GitHub API (using gh CLI)
-          echo "Attempting to delete existing 'latest' release..."
-          gh release delete latest --yes --cleanup-tag 2>/dev/null || echo "No existing latest release to delete"
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Set Latest Tag to Current Commit
+      - name: Update Latest Tag
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -fa latest -m "Update latest release to ${{ steps.version.outputs.version }}"
+          git tag -fa latest -m "Update latest tag to ${{ steps.version.outputs.version }}"
           git push origin latest --force
-
-      - name: Create Latest Release with Current Timestamp
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: latest
-          name: Latest Release
-          prerelease: false
-          make_latest: true
-          files: |
-            artifacts/firmware.bin
-            artifacts/littlefs.bin
-            artifacts/firmware_merged.bin
-            artifacts/version_manifest.json
-            artifacts/firmware.bin.sha256
-            artifacts/littlefs.bin.sha256
-            artifacts/firmware_merged.bin.sha256
-          body: |
-            # Latest Firmware Release
-
-            **Version:** ${{ steps.version.outputs.version }}
-
-            ${{ env.CHANGELOG }}
-
-            This is the latest stable release. Use these artifacts for the most current firmware installation.
-
-            ## Download Firmware
-            - **Merged Binary (recommended for OTA):** firmware_merged.bin
-            - **Firmware Binary:** firmware.bin
-            - **Filesystem Binary:** littlefs.bin
-            - **Version Manifest:** version_manifest.json (for OTA updates)
-
-            ## Checksums
-            **Firmware SHA256:** ${{ env.FIRMWARE_SHA256 }}
-            **Filesystem SHA256:** ${{ env.FILESYSTEM_SHA256 }}
-            **Merged SHA256:** ${{ env.MERGED_SHA256 }}
-
-            ## Build Artifacts
-            - Firmware Size: ${{ env.FIRMWARE_SIZE }} bytes
-            - Filesystem Size: ${{ env.FILESYSTEM_SIZE }} bytes
-            - Merged Size: ${{ env.MERGED_SIZE }} bytes
-            - Git Commit: ${{ github.sha }}
-
-            For version history, see [Releases](https://github.com/${{ github.repository }}/releases)
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/lib/HAL_ESP32/HAL_ESP32.cpp b/lib/HAL_ESP32/HAL_ESP32.cpp
@@ -856,13 +856,22 @@ bool HAL_ESP32::httpGetStream(const String& url, HttpDataCallback on_data,
               return false;
             }
           }
+          yield();  // Allow async web server to handle status requests
         }
       } else {
         delay(10);
       }
     }
 
     client.stop();
+
+    // Verify complete download if Content-Length was provided
+    if (contentLength > 0 && bytesDownloaded != contentLength) {
+      Serial.printf("[HAL_ESP32] httpGetStream: incomplete download %u/%u bytes\n",
+                    bytesDownloaded, contentLength);
+      return false;
+    }
+
     return true;
   }
 
diff --git a/lib/UpdateManager/UpdateManager.cpp b/lib/UpdateManager/UpdateManager.cpp
@@ -203,12 +203,13 @@ void UpdateManager::installUpdate(bool skip_filesystem, bool force) {
 
     // --- Install firmware ---
     if (manifest_.firmware.url.length() > 0 && manifest_.firmware.size_bytes > 0) {
+        phase_ = "firmware";
         setStatus(UpdateStatus::DOWNLOADING, true);
         bytes_downloaded_ = 0;
         total_bytes_ = manifest_.firmware.size_bytes;
         progress_percent_ = 0;
 
-        logger.logInfo("Downloading firmware: " + String(manifest_.firmware.size_bytes) + " bytes");
+        logger.logInfo("Downloading firmware: " + String((unsigned long)manifest_.firmware.size_bytes) + " bytes");
 
         // Begin OTA firmware partition
         if (!hal_->otaBegin(manifest_.firmware.size_bytes, 0)) {
@@ -231,10 +232,12 @@ void UpdateManager::installUpdate(bool skip_filesystem, bool force) {
 
         if (!downloadSuccess) {
             hal_->otaAbort();
-            setError(UpdateError::DOWNLOAD_FAILED, "Firmware download failed");
+            setError(UpdateError::DOWNLOAD_FAILED, "Firmware download failed or incomplete");
             return;
         }
 
+        logger.logInfo("Firmware download complete: " + String((unsigned long)bytes_downloaded_) + " bytes, finalizing...");
+
         // Finalize firmware OTA
         setStatus(UpdateStatus::INSTALLING);
         if (!hal_->otaEnd(true)) {
@@ -248,12 +251,13 @@ void UpdateManager::installUpdate(bool skip_filesystem, bool force) {
 
     // --- Install filesystem (if not skipping) ---
     if (!skip_filesystem && manifest_.filesystem.url.length() > 0 && manifest_.filesystem.size_bytes > 0) {
+        phase_ = "filesystem";
         bytes_downloaded_ = 0;
         total_bytes_ = manifest_.filesystem.size_bytes;
         progress_percent_ = 0;
         setStatus(UpdateStatus::DOWNLOADING, true);
 
-        logger.logInfo("Downloading filesystem: " + String(manifest_.filesystem.size_bytes) + " bytes");
+        logger.logInfo("Downloading filesystem: " + String((unsigned long)manifest_.filesystem.size_bytes) + " bytes");
 
         // End current filesystem before flashing
         hal_->fsEnd();
@@ -268,6 +272,7 @@ void UpdateManager::installUpdate(bool skip_filesystem, bool force) {
             [this](const uint8_t* data, size_t len, uint32_t downloaded, uint32_t total) -> bool {
                 size_t written = hal_->otaWrite(data, len);
                 if (written != len) {
+                    logger.logError("Filesystem OTA write failed: wrote " + String((unsigned long)written) + "/" + String((unsigned long)len) + " bytes");
                     return false;
                 }
                 bytes_downloaded_ = downloaded;
@@ -279,10 +284,12 @@ void UpdateManager::installUpdate(bool skip_filesystem, bool force) {
         if (!fsDownloadSuccess) {
             hal_->otaAbort();
             hal_->fsBegin();
-            setError(UpdateError::DOWNLOAD_FAILED, "Filesystem download failed");
+            setError(UpdateError::DOWNLOAD_FAILED, "Filesystem download failed or incomplete");
             return;
         }
 
+        logger.logInfo("Filesystem download complete: " + String((unsigned long)bytes_downloaded_) + " bytes, finalizing...");
+
         setStatus(UpdateStatus::INSTALLING);
         if (!hal_->otaEnd(true)) {
             hal_->otaAbort();
@@ -294,10 +301,11 @@ void UpdateManager::installUpdate(bool skip_filesystem, bool force) {
         logger.logInfo("Filesystem update installed successfully");
     }
 
+    phase_ = "complete";
     setStatus(UpdateStatus::COMPLETE, true);
     progress_percent_ = 100;
-    logger.logWarning("Update complete! Restarting device...");
-    delay(1000);
+    logger.logWarning("Update complete! Restarting device in 5 seconds...");
+    delay(5000);  // Allow time for status poll to see COMPLETE
     hal_->restart();
 }
 
@@ -326,6 +334,7 @@ UpdateStatusSnapshot UpdateManager::getStatus() const {
     snapshot.bytes_downloaded = bytes_downloaded_;
     snapshot.total_bytes = total_bytes_;
     snapshot.error_message = last_error_message_;
+    snapshot.phase = phase_;
     snapshot.last_check_time = last_check_time_;
     snapshot.next_check_time = 0; // TODO: Calculate based on settings
 
@@ -397,6 +406,7 @@ JsonDocument UpdateManager::getStatusResponseJson() const {
 
     doc["status"] = statusStr;
     doc["progress"] = progress_percent_;
+    doc["phase"] = phase_;
     doc["last_check"] = last_check_time_;
     doc["error"] = last_error_message_;
 
@@ -414,6 +424,7 @@ void UpdateManager::reset() {
     status_ = UpdateStatus::IDLE;
     error_ = UpdateError::NONE;
     last_error_message_ = "";
+    phase_ = "";
     progress_percent_ = 0;
     bytes_downloaded_ = 0;
     total_bytes_ = 0;
diff --git a/lib/UpdateManager/UpdateManager.h b/lib/UpdateManager/UpdateManager.h
@@ -75,6 +75,7 @@ struct UpdateStatusSnapshot {
     uint32_t bytes_downloaded;
     uint32_t total_bytes;
     String error_message;
+    String phase;              ///< Current phase: "firmware", "filesystem", or ""
     unsigned long last_check_time;
     unsigned long next_check_time;
 };
@@ -115,6 +116,9 @@ class UpdateManager {
     // Error tracking
     String last_error_message_;
 
+    // Phase tracking
+    String phase_;
+
     /**
      * @brief Compare two semantic versions
      *
diff --git a/web/src/Update.tsx b/web/src/Update.tsx
@@ -25,6 +25,7 @@ interface UpdateCheckResult {
 interface UpdateStatus {
   status: 'idle' | 'checking' | 'available' | 'current' | 'downloading' | 'verifying' | 'installing' | 'complete' | 'error';
   progress: number;
+  phase: string;
   last_check: number;
   error: string;
 }
@@ -279,7 +280,12 @@ function Update() {
             <div class="card bg-base-200 card-sm shadow-sm mb-4">
               <div class="card-body">
                 <h3 class="font-bold">Update Progress</h3>
-                <p>Status: {updateStatus()?.status ?? 'starting...'}</p>
+                <p>
+                  Status: {updateStatus()?.status ?? 'starting...'}
+                  <Show when={updateStatus()?.phase}>
+                    {' '}({updateStatus()!.phase})
+                  </Show>
+                </p>
                 <progress class="progress progress-primary w-full" value={updateStatus()?.progress ?? 0} max="100"></progress>
                 <p>{updateStatus()?.progress ?? 0}%</p>
               </div>

Original file line number	Diff line number	Diff line change
`@@ -856,13 +856,22 @@ bool HAL_ESP32::httpGetStream(const String& url, HttpDataCallback on_data,`
`856`	`856`	`return false;`
`857`	`857`	`}`
`858`	`858`	`}`
	`859`	`+ yield(); // Allow async web server to handle status requests`
`859`	`860`	`}`
`860`	`861`	`} else {`
`861`	`862`	`delay(10);`
`862`	`863`	`}`
`863`	`864`	`}`
`864`	`865`
`865`	`866`	`client.stop();`
	`867`	`+`
	`868`	`+ // Verify complete download if Content-Length was provided`
	`869`	`+ if (contentLength > 0 && bytesDownloaded != contentLength) {`
	`870`	`+ Serial.printf("[HAL_ESP32] httpGetStream: incomplete download %u/%u bytes\n",`
	`871`	`+ bytesDownloaded, contentLength);`
	`872`	`+ return false;`
	`873`	`+ }`
	`874`	`+`
`866`	`875`	`return true;`
`867`	`876`	`}`
`868`	`877`