feat: update OTA subsystem from feature/ota-self-flash (v4.6.2)

All 20 OTA files updated to latest version from feature branch.
Key changes:
- F-DISPLAY-MARGINS: fillMarginsBlack + fillScreen override in TftWithOffset
- F-TEL-HTTPS-RESILIENT: fix crash+reboot when HTTPS server drops
- F-UI-OTA-FLOW: user-facing OTA + restore UX messages
- F-BOOT-CYW43-CYCLE: power-cycle WL_REG_ON always in setup()
- F-OTA-STAGE-NOBLOCK + F-FLASH-DIET: fix TCP drop during OTA stage
- F-TEL-ADAPTIVE: adaptive-throughput telemetry (backend-only)
- F-SCREENSHOT-INTEGRITY: eliminate row loss/corruption in /api/screenshot
- F-OTA-ADMIN-ONLY: OTA endpoints require PERM_FULL_ADMIN
- F-RAM-SLIM-FIX: fix broken mDNS and RSSI from v4.2.0
- F-RAM-SLIM: RAM 49.6% → 33.7% (-41 KB / -16pp)
- F-RESTORE: reliable restore via API (98/100 PASS)
- F-OTA: fully closed — Bootloop fix, loop20 OTA 100% PASS

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: angeloINTJ

src/ota/applier.cpp

@@ -1,23 +1,32 @@
 /**
- * @file src/ota/applier.h
- * @brief OTA applier — runs entirely from SRAM.
+ * @file    src/ota/applier.h
+ * @brief   Aplicador OTA — roda inteiramente da SRAM (Fase 7).
  *
- * @details `ota_applier_run` is the destructive routine that erases the app slot
- * and rewrites it with the uncompressed staging content. IT IS MARKED
- * WITH `__not_in_flash_func` to reside in SRAM, and therefore can
- * execute even while flash is being erased/programmed.
+ * @details `ota_applier_run` é a rotina destrutiva que apaga o slot da app
+ *          e reescreve com o conteúdo descomprimido do staging. ESTÁ MARCADA
+ *          COM `__not_in_flash_func` para residir em SRAM, e portanto pode
+ *          executar mesmo enquanto a flash está sendo erased/programmed.
  *
- * PRECONDITIONS (caller orchestrator guarantees):
- * - WiFi/CYW43 off (`WiFi.end()`).
- * - LittleFS unmounted (`LittleFS.end()`).
- * - Core 1 paused via `multicore_lockout_start_blocking()`.
- * - Global IRQs disabled (`save_and_disable_interrupts`).
- * - Metadata.state == APPLYING and persisted in flash.
+ *          PRECONDIÇÕES (caller orchestrator garante):
+ *           - WiFi/CYW43 desligado (`WiFi.end()`).
+ *           - LittleFS desmontada (`LittleFS.end()`).
+ *           - Core 1 pausado via `multicore_lockout_start_blocking()`.
+ *           - IRQs globais desabilitadas (`save_and_disable_interrupts`).
+ *           - Metadata.state == APPLYING e persistida em flash.
  *
- * @project SIMUT — Sistema Integrado de Monitoramento Universal e Telemetria
- *          SIMUT — Integrated Universal Monitoring and Telemetry System
- * @target Raspberry Pi Pico W (RP2040) — Arduino Framework
- * @author Ângelo Moisés Alves
+ *          7a (atual — não destrutivo): a função apenas faz uma pausa breve
+ *          e dispara `watchdog_reboot`. Demonstra que a infraestrutura de
+ *          jump-to-SRAM + lockout + IRQ-off + reboot funciona, sem riscar a
+ *          app slot. Validar 7a antes de evoluir pra 7b real.
+ *
+ *          7b (a implementar — destrutivo): apaga slot da app sector-by-
+ *          sector, descomprime staging via uzlib (que precisará estar em
+ *          SRAM), grava no slot, valida CRC do output relendo via XIP,
+ *          watchdog_reboot. NÃO retorna em sucesso.
+ *
+ * @project SIMUT
+ * @target  Raspberry Pi Pico W (RP2040) — Arduino Framework
+ * @author  Ângelo Moisés Alves
  * @license MIT License
  */
 #pragma once
@@ -27,12 +36,13 @@
 namespace ota {
 
 /**
- * @brief Applies the update in destructive mode. DOES NOT RETURN on success.
+ * @brief Aplica o update em modo destrutivo. NÃO RETORNA em sucesso.
  *
- * @param meta Metadata in RAM (caller read before IRQ disable).
+ * @param meta  Metadata em RAM (caller leu antes de IRQ disable).
+ *              Em 7a (no-op), parâmetro é ignorado.
  *
- * @return false only if error detected BEFORE any destructive action.
- * On success, NEVER returns (always reboots).
+ * @return false só se erro detectado ANTES de qualquer ação destrutiva.
+ *         Em 7a, NUNCA retorna (sempre reboota).
  */
 bool ota_applier_run(const UpdateMetadata* meta);
 

src/ota/applier.h

@@ -1,19 +1,18 @@
 /**
- * @file src/ota/backup.h
- * @brief Public API of the backup (.bkp) generator — OTA.
+ * @file    src/ota/backup.h
+ * @brief   API pública do gerador de backup (.bkp) — Fase 1 do OTA.
  *
- * @details Generation does two passes over LittleFS to avoid buffering in RAM:
- * 1) scan: calculates payload_size + payload_crc32 + file_count.
- * 2) emit: writes header (with CRCs) + payload streaming via Print.
+ * @details A geração faz dois passes sobre a LittleFS para evitar buffer em RAM:
+ *          1) scan: calcula payload_size + payload_crc32 + file_count.
+ *          2) emit: escreve header (com CRCs) + payload em streaming via Print.
  *
- * The caller is responsible for ensuring LittleFS is mounted and
- * that the operation is serialized against concurrent writes (e.g.
- * via HeavyTaskGuard in WebManager).
+ *          O caller é responsável por garantir que o LittleFS está montado e
+ *          que a operação é serializada contra escritas concorrentes (ex.:
+ *          via HeavyTaskGuard no WebManager).
  *
- * @project SIMUT — Sistema Integrado de Monitoramento Universal e Telemetria
- *          SIMUT — Integrated Universal Monitoring and Telemetry System
- * @target Raspberry Pi Pico W (RP2040) — Arduino Framework
- * @author Ângelo Moisés Alves
+ * @project SIMUT
+ * @target  Raspberry Pi Pico W (RP2040) — Arduino Framework
+ * @author  Ângelo Moisés Alves
  * @license MIT License
  */
 #pragma once
@@ -26,99 +25,98 @@
 namespace ota {
 
 /**
- * @brief Incremental CRC32 (poly 0xEDB88320, init 0xFFFFFFFF, xor-out 0xFFFFFFFF).
+ * @brief CRC32 incremental (poly 0xEDB88320, init 0xFFFFFFFF, xor-out 0xFFFFFFFF).
  *
- * Compatible with gzip/zlib CRC32. Reused in other steps (staging
- * validation, metadata).
+ * Compatível com CRC32 do gzip/zlib. Reutilizado em outras fases (validação
+ * de staging, metadata).
  *
- * @param crc Previous state (pass OTA_CRC32_INIT on first chunk).
- * @param data Byte buffer.
- * @param len Length.
- * @return Partial CRC; apply `^ 0xFFFFFFFFu` when done to get the final CRC.
+ * @param crc   Estado anterior (passar OTA_CRC32_INIT no primeiro chunk).
+ * @param data  Buffer de bytes.
+ * @param len   Tamanho.
+ * @return CRC parcial; aplicar `^ 0xFFFFFFFFu` ao terminar para obter o CRC final.
  */
 uint32_t crc32_update(uint32_t crc, const uint8_t* data, size_t len);
 
 /**
- * @brief Reads the unique RP2040 ID (flash_get_unique_id).
+ * @brief Lê o ID único do RP2040 (flash_get_unique_id).
  *
- * Cached after first call (operation costs ~100us and disables IRQs).
+ * Cacheado após a primeira chamada (operação custa ~100us e desabilita IRQs).
  *
- * @param out 8-byte buffer; filled with the ID.
+ * @param out  Buffer de 8 bytes; preenchido com o ID.
  */
 void read_chip_id(uint8_t out[8]);
 
 /**
- * @brief Encodes version string "vMAJOR.MINOR.PATCH" into packed uint32.
+ * @brief Encoda string de versão "vMAJOR.MINOR.PATCH" em uint32 packed.
  *
- * Format: (major<<16) | (minor<<8) | patch. Each field truncated to 8 bits.
- * E.g.: "v3.37.8" → 0x00032508.
+ * Formato: (major<<16) | (minor<<8) | patch. Cada campo é truncado para 8 bits.
+ * Ex.: "v3.37.8" → 0x00032508.
  *
- * @param version_str String like "v3.37.8" or "3.37.8" (prefix 'v' optional).
- * @return uint32 encoded; 0 if string is invalid.
+ * @param version_str  String tipo "v3.37.8" ou "3.37.8" (prefixo 'v' opcional).
+ * @return uint32 encoded; 0 se string for inválida.
  */
 uint32_t encode_version_u32(const char* version_str);
 
 /**
- * @brief Result of the LittleFS scan (prerequisite to generate header).
+ * @brief Resultado do scan da LittleFS (pré-requisito para gerar header).
  */
 struct BackupScanResult {
- uint32_t payload_size; /**< Total payload size in bytes. */
- uint32_t payload_crc32; /**< Final payload CRC32 (already with xor-out applied). */
- uint16_t file_count; /**< Number of files enumerated. */
+    uint32_t payload_size;      /**< Tamanho total do payload em bytes. */
+    uint32_t payload_crc32;     /**< CRC32 final do payload (já com xor-out aplicado). */
+    uint16_t file_count;        /**< Quantidade de arquivos enumerados. */
 };
 
 /**
- * @brief Backup validation status codes.
+ * @brief Códigos de status da validação de backup (Fase 2).
  *
- * Ordered so lower values correspond to failures detected
- * earlier in parsing — useful for hierarchical error messages.
+ * Ordenados de forma que valores baixos correspondam a falhas detectadas
+ * mais cedo no parse — útil pra mensagens de erro hierárquicas.
  */
 enum class BackupStatus : uint8_t {
- OK = 0,
- BAD_MAGIC = 1,
- UNSUPPORTED_SCHEMA = 2,
- HEADER_CRC_MISMATCH = 3,
- PAYLOAD_TRUNCATED = 4,
- PAYLOAD_CRC_MISMATCH = 5,
- CHIP_ID_MISMATCH = 6,
- PATH_INVALID = 7,
- PATH_TOO_LONG = 8,
- IO_ERROR = 9,
- INTERNAL_ERROR = 10,
+    OK = 0,
+    BAD_MAGIC = 1,
+    UNSUPPORTED_SCHEMA = 2,
+    HEADER_CRC_MISMATCH = 3,
+    PAYLOAD_TRUNCATED = 4,
+    PAYLOAD_CRC_MISMATCH = 5,
+    CHIP_ID_MISMATCH = 6,
+    PATH_INVALID = 7,
+    PATH_TOO_LONG = 8,
+    IO_ERROR = 9,
+    INTERNAL_ERROR = 10,
 };
 
-/* Validation of .bkp in production is done by the state machine in
- * ota::RestoreSession (VALIDATE mode) — see src/ota/restore.h. The
- * Stream-based backup_validate was removed to save flash; the web upload
- * pipeline already consumes chunks and maintains state, so the state
- * machine covers both scenarios. */
+/* Validação de .bkp em produção é feita pelo state machine em ota::RestoreSession
+ * (modo VALIDATE) — ver src/ota/restore.h. backup_validate Stream-based foi
+ * removido para economizar flash; o pipeline de upload web já consome chunks e
+ * mantém estado, então a state machine cobre os dois cenários. */
 
 /**
- * @brief Pass 1: scans LittleFS, computes total size and payload CRC32.
+ * @brief Pass 1: varre a LittleFS, computa tamanho total e CRC32 do payload.
  *
- * Does NOT write anything; only measures. Returns metrics to build the header
- * before pass 2.
+ * NÃO escreve nada; apenas mede. Retorna métricas para construir o header
+ * antes do pass 2.
  *
- * @param out Result.
- * @return true if scan was successful; false on I/O error.
+ * @param out  Resultado.
+ * @return true se o scan foi bem-sucedido; false em I/O error.
  */
 bool backup_scan(BackupScanResult& out);
 
 /**
- * @brief Pass 2: writes the full backup (header + payload) in streaming.
+ * @brief Pass 2: escreve o backup completo (header + payload) em streaming.
  *
- * Requires a valid BackupScanResult obtained by backup_scan (ideally
- * immediately before, under HeavyTaskGuard, to ensure consistency).
+ * Requer um `BackupScanResult` válido obtido por `backup_scan` (idealmente
+ * imediatamente antes, sob HeavyTaskGuard, para garantir consistência).
  *
- * @param out Output stream (Print&; e.g. WebServer client).
- * @param scan Result of pass 1.
- * @param firmware_version Encoded version via encode_version_u32.
- * @param timestamp Unix epoch UTC; 0 if NTP unavailable.
- * @return true if write completed without I/O errors.
+ * @param out               Stream de saída (Print&; ex.: WebServer client).
+ * @param scan              Resultado do pass 1.
+ * @param firmware_version  Versão encoded via encode_version_u32.
+ * @param timestamp         Unix epoch UTC; 0 se NTP indisponível.
+ * @return true se a escrita completou sem erros de I/O.
  */
 bool backup_emit(Print& out,
- const BackupScanResult& scan,
- uint32_t firmware_version,
- uint32_t timestamp);
+                 const BackupScanResult& scan,
+                 uint32_t firmware_version,
+                 uint32_t timestamp);
 
 } /* namespace ota */

src/ota/backup.cpp

@@ -1,66 +1,67 @@
 /**
- * @file src/ota/backup_format.h
- * @brief Binary layout of the SIMUT backup file (.bkp).
- * @details Defines the on-disk format used by the OTA system.
- * Schema-versioned with CRC32 protection at both header and payload
- * levels. Tied to the RP2040 chip_id (prevents cross-device restore).
+ * @file    src/ota/backup_format.h
+ * @brief   Binary layout of the SIMUT backup file (.bkp).
+ * @details Defines the on-disk format used by Phases 1-2 of the OTA system.
+ *          Schema-versioned with CRC32 protection at both header and payload
+ *          levels. Atrelado ao chip_id do RP2040 (impede restauração cruzada).
  *
- * @project SIMUT — Sistema Integrado de Monitoramento Universal e Telemetria
- *          SIMUT — Integrated Universal Monitoring and Telemetry System
- * @target Raspberry Pi Pico W (RP2040) — Arduino Framework
- * @author Ângelo Moisés Alves
+ *          Conforme IMPLEMENTATION_PLAN.md §5.1.
+ *
+ * @project SIMUT
+ * @target  Raspberry Pi Pico W (RP2040) — Arduino Framework
+ * @author  Ângelo Moisés Alves
  * @license MIT License
  */
 #pragma once
 #include <stdint.h>
 #include <stddef.h>
 
-/* Magic = "BKP1" in ASCII little-endian. */
-#define OTA_BACKUP_MAGIC 0x31504B42u
-#define OTA_BACKUP_SCHEMA 1u
+/* Magic = "BKP1" em ASCII little-endian. */
+#define OTA_BACKUP_MAGIC       0x31504B42u
+#define OTA_BACKUP_SCHEMA      1u
 
-/* CRC32 polynomial (identical to gzip/zlib). */
-#define OTA_CRC32_POLY 0xEDB88320u
-#define OTA_CRC32_INIT 0xFFFFFFFFu
+/* CRC32 polinômio (idêntico ao gzip/zlib). */
+#define OTA_CRC32_POLY         0xEDB88320u
+#define OTA_CRC32_INIT         0xFFFFFFFFu
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * @brief Fixed backup file header. Always 40 bytes.
+ * @brief Cabeçalho fixo do arquivo de backup. Sempre 40 bytes.
  *
- * All multi-byte fields are little-endian (RP2040 native).
+ * Todos os campos multi-byte são little-endian (nativo do RP2040).
  */
 struct __attribute__((packed)) BackupHeader {
- uint32_t magic; /**< OTA_BACKUP_MAGIC. */
- uint16_t schema_version; /**< Current OTA_BACKUP_SCHEMA. */
- uint16_t reserved0; /**< Padding/alignment. Always 0. */
- uint8_t chip_id[8]; /**< RP2040 unique ID (flash_get_unique_id). */
- uint32_t firmware_version; /**< Encoded (major<<16)|(minor<<8)|patch. */
- uint32_t timestamp; /**< Unix epoch UTC; 0 if NTP not ready. */
- uint32_t payload_size; /**< Payload bytes after this header. */
- uint32_t payload_crc32; /**< CRC32 (poly EDB88320, init 0xFFFFFFFF, xor-out 0xFFFFFFFF) of payload. */
- uint32_t reserved1; /**< Reserved for future extension. Always 0 — included in header_crc32. */
- uint32_t header_crc32; /**< CRC32 of the preceding 36 bytes of this struct. */
+    uint32_t magic;             /**< OTA_BACKUP_MAGIC. */
+    uint16_t schema_version;    /**< OTA_BACKUP_SCHEMA atual. */
+    uint16_t reserved0;         /**< Padding/alinhamento. Sempre 0. */
+    uint8_t  chip_id[8];        /**< RP2040 unique ID (flash_get_unique_id). */
+    uint32_t firmware_version;  /**< Encoded (major<<16)|(minor<<8)|patch. */
+    uint32_t timestamp;         /**< Unix epoch UTC; 0 se NTP não estiver pronto. */
+    uint32_t payload_size;      /**< Bytes de payload após este header. */
+    uint32_t payload_crc32;     /**< CRC32 (poly EDB88320, init 0xFFFFFFFF, xor-out 0xFFFFFFFF) do payload. */
+    uint32_t reserved1;         /**< Reserva para extensão futura. Sempre 0 — incluído no header_crc32. */
+    uint32_t header_crc32;      /**< CRC32 dos 36 bytes anteriores deste struct. */
 };
 
-/* Compile-time check: guarantees stable layout regardless of compiler/arch. */
+/* Compile-time check: garante layout estável independente do compilador/arch. */
 #ifdef __cplusplus
 static_assert(sizeof(BackupHeader) == 40, "BackupHeader must be exactly 40 bytes");
 #else
 _Static_assert(sizeof(struct BackupHeader) == 40, "BackupHeader must be exactly 40 bytes");
 #endif
 
 /**
- * @brief Header of a TLV entry in the payload.
+ * @brief Cabeçalho de uma entrada TLV no payload.
  *
- * Followed by: char path[path_length] (no null terminator) + uint8_t content[content_length].
- * Sequence repeated until totaling payload_size.
+ * Seguido por: char path[path_length] (sem nul-terminator) + uint8_t content[content_length].
+ * Sequência repetida até totalizar payload_size.
  */
 struct __attribute__((packed)) BackupEntry {
- uint16_t path_length; /**< Path bytes (no terminator). */
- uint32_t content_length; /**< File content bytes. */
+    uint16_t path_length;       /**< Bytes do path (sem terminador). */
+    uint32_t content_length;    /**< Bytes do conteúdo do arquivo. */
 };
 
 #ifdef __cplusplus