From d2b6244ae043378182a917b123410719b58124b6 Mon Sep 17 00:00:00 2001 From: mikecarper Date: Wed, 7 Oct 2026 07:36:08 -0700 Subject: [PATCH] Document 1.17.1.9 profiles and WiFi upgrade limits --- RELEASE.md | 7 + docs/WiFi.md | 61 ++++- docs/firmware_picker.md | 12 +- docs/releases/1.17.1.9.md | 169 ++++++++---- .../firmware_choice_followup_2026-10-06.md | 14 +- ...dation_esp32_web_console_ota_2026-10-05.md | 255 ++++++++++++++++++ docs/upgrading_1.17.1.8_to_1.17.1.9.md | 166 ++++++++++++ mkdocs.yml | 1 + 8 files changed, 605 insertions(+), 80 deletions(-) create mode 100644 docs/upgrading_1.17.1.8_to_1.17.1.9.md diff --git a/RELEASE.md b/RELEASE.md index 3cf10bda..87f6338a 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -39,6 +39,13 @@ names, sizes and checksums before switching the catalogs. Regenerate the downloadable picker from the same family and update its checksum on every page. Documentation-only follow-up commits do not move firmware tags. +Include the [1.17.1.9 release notes](docs/releases/1.17.1.9.md) and +[1.17.1.8 WiFi upgrade guide](docs/upgrading_1.17.1.8_to_1.17.1.9.md) in the +publication review. Replace the release notes' final package-validation gate +with the completed inventory only after packaging passes. Keep the firmware +source separate from a later documentation-only commit, and retain the +measured hardware scope and old-updater completion limitation. + For the USA Cascade 1.17.1.5 matrix, use [the option 3 release instructions](docs/old-releases/1.17.1.5.md). Package the qualified outputs with `scripts/package_cascade_release.py`. diff --git a/docs/WiFi.md b/docs/WiFi.md index 5faee6f5..bf0dbb47 100644 --- a/docs/WiFi.md +++ b/docs/WiFi.md @@ -159,8 +159,35 @@ reboot ``` The SSID and password values are the rest of the command line. Spaces are -allowed and quotes must not be added. SSIDs may contain at most 31 characters -and passwords at most 63. Leave the password value empty for an open network. +allowed and quotes must not be added. SSIDs may contain at most 31 characters. +ESP32 infrastructure MQTT builds with WebConfig share one canonical WiFi +configuration between this CLI and the browser portal. Passwords accept +0-63 characters or exactly 64 hexadecimal characters for a raw WPA PSK. +Leave the password value empty for an open network. Reboot after changing +credentials to apply them; an already-running MQTT worker keeps its current +connection settings until it stops and restarts. + +Older observer-only credentials remain usable until canonical WiFi settings +are saved. The first CLI edit preserves the other legacy credential while +saving the complete pair. Once canonical settings exist, empty, incomplete or +unreadable canonical settings do not revive old observer credentials. Historical +SSID-only canonical settings continue to represent an open network. Builds +without this WebConfig integration retain their legacy 63-character password +limit; this change does not add MQTT support to currently disabled Pico targets. + +On these ESP32 MQTT/WebConfig builds, an empty CLI SSID clears the configured +network while retaining saved broker settings: + +```text +set wifi.ssid +reboot +``` + +Use this to return the node to unconfigured provisioning. The WebConfig setup +form still requires a nonempty SSID. After saving a new network, verify +`get wifi.status`, `get mqtt.config.valid` and `get mqtt.running`; credentials +alone do not prove a broker connection. A local `get wifi.pwd` can inspect the +password, while an authenticated remote command returns only set/unset. Useful checks are: @@ -192,8 +219,9 @@ set mqtt.enabled off start webconfig ap ``` -After provisioning, use **Save & Reboot**, or stop the temporary portal and -restart the bridge: +After changing WiFi credentials, use **Save & Reboot** or `reboot`. For +broker-only changes that keep the existing network, stop the temporary portal +and restart the bridge: ```text stop webconfig @@ -307,6 +335,15 @@ modem sleep can miss ESP-NOW broadcasts; use `min` for coexistence. The primary mesh transport holds the driver's RF wake reference continuously, so `min` does not suspend its ESP-NOW receiver. +Espressif long-range WiFi (LR) trades speed for reach: its raw rates are +250 or 500 kbit/s, with up to about 1 km in suitable line-of-sight conditions. +LR traffic needs compatible Espressif hardware at both ends. An LR-enabled +access point sends LR beacons that ordinary phones, routers and Raspberry Pis +cannot receive. A mixed b/g/n+LR station can still join an ordinary router, +using normal WiFi rates for that connection. MeshCore's setup and OTA access +points therefore use ordinary b/g/n. See +[Espressif's LR compatibility guide](https://docs.espressif.com/projects/esp-idf/en/v4.4.7/esp32s3/api-guides/wifi.html#long-range-lr). + ESP-NOW compatibility also depends on the bytes and PHY used above the common Espressif transport. The historical `*_repeater_bridge_espnow` firmware wraps each MeshCore packet with a magic value, checksum, and secret-based XOR, while @@ -423,6 +460,11 @@ direct browser uploader on HTTP port 80. A FULL role without WebConfig but with browser OTA support can use the `MeshCore-OTA` access point raised by `start ota`; its seeder address is `192.168.4.1:5001`. +For browser uploads from an existing 1.17.1.8 ESP32 node, see the +[1.17.1.9 WiFi upgrade guide](upgrading_1.17.1.8_to_1.17.1.9.md). +It covers the node AP, old-page completion behavior, and choosing an +application-only image or the exact partition-migration package. + Only one external folder link can be active. A TCP client is rejected while `ota folder on` is using USB serial, and disconnecting `motatool` automatically removes the TCP folder. Port 5001 has no login layer, so expose it only on a @@ -675,11 +717,12 @@ Common causes are: For a WiFi companion, find its station IP in the router, connect the client to TCP port 5000, and use the open `MeshCore-Setup-XXXX` AP at `http://192.168.4.1/` if it cannot join the saved network. Current firmware -normalizes both ESP32 WiFi interfaces to standard b/g/n before advertising the -setup AP. Full Companion targets whose primary mesh radio is ESP-NOW use -b/g/n+LR instead and keep the setup AP, infrastructure station, and mesh on the -persisted `espnow.channel` (channel 1 by default). Their configured 2.4 GHz -router and every other primary ESP-NOW node must use that same channel. +uses standard b/g/n for the setup AP, including ESP-NOW-capable targets. +A running LR mesh conflicts with a conventional access point; current firmware +refuses that AP startup and defers LR startup while an AP is active. A primary +ESP-NOW target keeps its infrastructure station and mesh on the persisted +`espnow.channel` (channel 1 by default). Its configured 2.4 GHz router and every +other primary ESP-NOW node must use that same channel. MQTT-capable Companions also accept `get mqtt.enabled`, `get mqtt.running`, and `get mqtt.status` in their USB/TCP and browser terminals. Extended slot and NTP diagnostics remain infrastructure features. diff --git a/docs/firmware_picker.md b/docs/firmware_picker.md index cd7cbd36..fa81fe05 100644 --- a/docs/firmware_picker.md +++ b/docs/firmware_picker.md @@ -25,7 +25,7 @@ The picker reads public release metadata from GitHub. It does not upload device information. Hardware names, target names, and download links come directly from the published firmware assets. -
+
Current release set

Loading release information...

@@ -271,7 +271,7 @@ capacity and sensor-profile choices. Moving an older ESP32 installation to an expanded Full layout requires a partition migration. Use the exact-board merged image over USB, or a supported exact board and role -staged migration ZIP from the [utility release](https://github.com/mikecarper/MeshCore/releases/tag/utility-v1.17.1.8-halo-keymind-cascade-dev-9053038f). +staged migration ZIP from the [utility release](https://github.com/mikecarper/MeshCore/releases/tag/utility-v1.17.1.9-halo-keymind-cascade-dev-88c85108). Read that ZIP's README before choosing the Wi-Fi or LoRa route. Do not send a loose app-only Full `.bin` directly to an older layout: the running application cannot move its own active and inactive partitions. Run @@ -465,7 +465,7 @@ pin map, and other physical differences without crowding the Hardware dropdown. that need a different image or wiring, such as serial port or external storage. The picker skips this step when all available profile choices lead to the same firmware file. -Future nRF52 repeater, room-server and sensor releases publish two separately +The 1.17.1.9 nRF52 repeater, room-server and sensor releases publish two separately qualified choices: **Reduced sensors + LoRa OTA** and **Full supported sensors + LoRa OTA**, with `-reduced-ota` and `-full-ota` artifact suffixes. Each keeps its exact board/role OTA identity and storage layout; the suffix is not a new @@ -512,7 +512,7 @@ retains its optional dedicated interface `02`. Exact filename search finds compatibility images included in the selected release family. For older releases, open their GitHub release pages. -The 1.17.1.8 public matrix keeps one ESP32 Full image per board and role. +The current public matrix keeps one ESP32 Full image per board and role. Some richer images, including Station G2 Full, retain an observer-named OTA identity. Exact older identities needed by a partition migration are packaged inside that board and role's migration ZIP instead of adding a second ordinary @@ -520,8 +520,8 @@ Full download. A deliberate target-ID override does not make a different partition layout or physical board compatible. Some normal ESP32 roles begin in the legacy 1.25 MiB dual-OTA layout but have -a Full image with larger slots. The 1.17.1.8 utility release contains 94 exact -board and role migration ZIPs. Each package checks its source layout and target +a Full image with larger slots. The utility release lists the exact +board and role migration ZIPs available for that release. Each package checks its source layout and target identity, contains the bridge and Full application files for its supported routes, and documents what saved data it preserves. Use the package's own Full application after the bridge; do not substitute a loose Full image with a diff --git a/docs/releases/1.17.1.9.md b/docs/releases/1.17.1.9.md index c0b289ac..bcb21c50 100644 --- a/docs/releases/1.17.1.9.md +++ b/docs/releases/1.17.1.9.md @@ -1,6 +1,9 @@ # MeshCore 1.17.1.9 USA Cascade -This release remains held and unpublished. +Candidate firmware source: `88c85108005a30a730fa7b78b2899b210754f3be`. + +Final package validation remains pending. Hardware observations below retain +the exact source and installation route tested. USA Cascade defaults are 910.525 MHz, 62.5 kHz bandwidth, SF7 and CR5. Saved radio settings take precedence. Match the exact board, role and storage @@ -18,17 +21,41 @@ layout before installing an image. the radio loop. The G2 preserves complete serial packet-log lines under congestion. This supports unmodified Cisien meshcoretomqtt; congested diagnostic output can still be dropped. -- The pinned ESP32-S3 framework releases retained TinyUSB PHY ownership when - starting hardware CDC after a software restart. KISS clears incomplete +- ESP32-S3 hardware CDC startup reclaims TinyUSB PHY ownership retained + across a software restart. KISS clears incomplete host frames on a USB session reset while preserving active radio work. - Browser OTA uploads allow 30 seconds of body inactivity after admission. An upload error stays attached to its HTTP request and stops further flash writes. Error callbacks avoid raw USB printing that could block the shared network task when a connected host stops reading. +- Browser OTA applies the expected MD5 after opening the update, so checksum + verification survives updater initialization. It commits an application only + after the complete HTTP POST finishes. A rejected second file or an + interrupted multipart request cannot finalize the first file as an update. + The successful response is sent before the deferred restart. +- On ESP32 infrastructure, `start ota` starts WiFi as needed, stops WebConfig + to release its HTTP port, and reports the address and network to use. + `start ota ap` can replace a running LAN uploader with the node's + `MeshCore-OTA` access point. Run the handoff from USB, Bluetooth or LoRa; + WebConfig tells its terminal users that the portal will close. +- Setup and OTA access points use ordinary b/g/n WiFi. Firmware rejects AP + startup while a conflicting long-range ESP-NOW transport is active, and + defers that transport while the AP is running. MQTT and Companion station + recovery leave an active setup/OTA AP available. - Infrastructure WebConfig retries its saved WiFi when MQTT has no running worker. Ownership follows the actual worker state while canonical WiFi credentials and 64-hex password support remain independent of that state. Companion's manual WiFi startup behavior is preserved. +- ESP32 infrastructure MQTT builds with WebConfig use the same saved WiFi + credentials for browser setup, CLI configuration, startup and reconnects. + A fresh browser-only setup can now start MQTT. Raw 64-hex PSKs are supported + without changing the observer preferences file layout. Failed saves retain + the committed pair or block an incomplete pair; runtime credentials remain + fixed until the bridge restarts. See [WiFi setup](../WiFi.md#mqtt-observer-setup). +- Compact 1.14.1 preference images retain a saved RX boosted gain of on when + a newer board profile defaults it to off. Newer appended gain values remain + authoritative. The old off byte is indistinguishable from padding used by + earlier versions, so those zero-filled legacy images retain board defaults. - Companion packet streaming supports stock serial MQTT consumers. Text CLI and Binary Companion handoff and reply deadlines are covered against the official app's protocol behavior. @@ -56,6 +83,19 @@ layout before installing an image. firmware with enough rule slots to recover the complete policy. - ESP32 filesystem buffer checks cover the pinned Arduino 3 frameworks used by RC32 and C6 targets and continue rejecting unhonored buffer allocations. +- ESP32 Full LoRa repeater images combine supported ESP-NOW and RS-232 + bridge modes behind runtime controls. Separate ESP-NOW images remain where + a combined profile cannot meet the existing memory and flash guards. + Full Heltec V3, WSL3 and RAK3112 MQTT profiles retain independent RS-232 + controls alongside MQTT and ESP-NOW; see the [bridge controls](../role_feature_switches.md). +- MeshTower V2 uses its SD-card-capable image as the canonical combined + repeater. With the matching combined OTAFIX bootloader, its runtime storage + policy keeps SD primary and allows internal-flash signed application deltas + when no usable card is available; see [MeshTower storage](../ota_meshtower_v2_sdcard.md). +- Supported T-Beam AXP192/AXP2101 boards can configure and persist the + charger's exact supported voltage targets, with hardware readback. Neither + PMU supports 3.65 V. Heltec Mesh Solar's charger voltage remains a hardware + setting; see [charge voltage](../charge_voltage.md). - Generic ESP-NOW Full Companion retains all Full transports and 100 contacts with a 224-frame offline queue to meet the unchanged runtime RAM requirement. - Wio-E5 Mini Companion uses smaller generated code while preserving its @@ -64,6 +104,25 @@ layout before installing an image. - Mesh America preserves download-only installation for hardware cards that require it, including their Full and reduced sensor profiles. +## Firmware profiles + +Choose the exact hardware variant and role in the +[firmware picker](../firmware_picker.md). **Full** includes the transports and +optional sensors supported by that board's qualified recipe; it does not add +peripherals that the hardware cannot support. Runtime controls select USB +logging, power saving and included bridge modes without a separate image. + +ESP32 normally has one public Full image per board and role. A migration ZIP +may contain a different required target identity; use its supplied Full image +for that migration. Station G2's ordinary Full image retains an +Observer-named OTA identity, even though it is the combined Full profile. + +nRF52 Repeater, Room Server and Sensor provide both **Reduced sensors + LoRa +OTA** and **Full supported sensors + LoRa OTA**. Pick Full when its supported +optional sensors are needed. Both keep the exact board/role/storage identity +and need the matching OTAFIX bootloader. Full Companion remains the combined +Companion choice. See [profile details](../firmware_picker.md#hardware-and-variant-names). + ## Installation An ESP32 merged `.bin` installs bootloader, partitions and application over @@ -73,6 +132,10 @@ family's utility page, or the matching merged image over USB. Follow the ZIP's README and use its supplied Full application. `get storage.layout` reports the live layout on firmware that supports it. +For the measured ESP32 upgrade route and examples, read +[Upgrading from 1.17.1.8 over WiFi](../upgrading_1.17.1.8_to_1.17.1.9.md). +Download the selected image before joining the node's update access point. + Check the image's flood-rule capacity before updating a repeater. Move active rules into the supported slots and save them before installing a smaller table. An over-capacity policy is retained on storage but remains inactive @@ -93,63 +156,53 @@ See the [role controls](../role_feature_switches.md), ## Verification scope -The ESP32 migration passed the native unit suite, SDK and protocol regression -tests, sanitizer fixtures and representative builds across all affected board -families. The G2 passed physical USB command/reconnect tests with its original -identity and settings preserved. A separate RAK4631 recovery admin was verified -by passwordless LoRa login, remote status and a remote version reply. + +Final release packaging is still being checked against firmware source +`88c851080`. Publish only after the complete checksum inventory, capabilities, +memory checks, Full/Reduced nRF52 pairs and exact migration packages pass. +The older completed 463-recipe inventory belongs to `1e421ff4`; it does not +qualify the rebuilt release. The publisher must record the completed new +inventory here before switching the firmware picker and Mesh America catalogs. -Earlier old-firmware handoff attempts did not qualify an OTA migration. After -USB restoration, hardware CDC passed 444 strict-deadline queries and a -150-second closed-port idle/reconnect test. Those results remain separate from -the subsequent physical OTA qualification. +Production-code host regressions cover the official configuration GUI's +five-second command deadline, app protocol and ACL replies, USB lifecycle, +OTA admission/MD5/completion/error handling, shared WiFi credentials, AP and +MQTT ownership, and legacy RX-gain loading. Synthetic peripheral tests cover +boards unavailable for physical testing. They do not establish every board's +physical USB, radio, WiFi or power behavior. -On 2026-10-05, the G2 passed an app-only HTTP OTA upgrade from a real TinyUSB -build to normal hardware CDC, both built from `95913c53`. The test drained the -same TCP socket's outstanding bytes before pausing the upload for 4.510 seconds. -HTTP returned 200 after 22.559 seconds. Firmware restarted itself, the host -observed the USB product change, and the first ordinary website `time` command -was acknowledged in 2.997 seconds against the unchanged 5-second deadline. -Identity, saved runtime settings, and the original and recovery Admin ACLs -were preserved. No cable, power, reset, ROM or rescue action was used during -the measured upgrade; the Pi's original WiFi connection was restored. +The latest-source G2 ordinary Full Observer passed a separate USB application +installation with complete application readback, exact normal runtime and +EndF identity, and unchanged checked boot/partition/NVS/OTA-data/filesystem +regions. Its read-only post-boot check matched the original identity, +passwords, two Admin ACLs, all 22 common settings, seven supported bridge +fields and saved extras. Core error flags were zero. MQTT was running with +valid effective configuration; broker connectivity was not tested. Original +TTY settings, three host services and the Pi network were restored. -This is a controlled current-source TinyUSB baseline, not proof of an upgrade -from released stock 1.17.1. A separate earlier LAN upload reset mid-transfer; -continuous uptime and a later successful AP retry showed no CPU crash, but -the LAN failure's cause remains unproven. The synthetic regressions execute -production upload callbacks, preserve queued errors, and distinguish the old -3-second body timeout from the bounded 30-second allowance. Local uploader, -OTA startup, WiFi lifecycle and station ownership tests passed. The latest -`95913c53` hardware CDC application passed quiet 180-second power-saving trials -with the port open and closed, without keepalives or a CPU restart. First -replies took 18.551 ms and 14.728 ms; original power-saving off and other saved -settings were restored. A plain `start ota` then advertised a working LAN -endpoint, reported the WebConfig handoff, and served its page and exact G2 -identity over HTTP. OTA stopped cleanly and the original WebConfig, settings, -Admin ACLs, Pi network and host services were restored. The earlier radio CAD -warning remained unchanged; the earlier LAN upload failure's cause is still -unproven. The GitHub unit workflow passed for source `c88885a3`; this release -remains held and unpublished. +The legacy **stock 1.14.1 G2 WiFi-only migration is not qualified end to end**. +The earlier `1e421ff4` trial completed partition expansion and the supplied +Full application's WiFi upload, but its final network check reached the +client/DHCP deadline without +a verified G2 client or any HTTP request. Final image/layout/identity/settings +verification through HTTP remains unproven. The successful latest-source USB +maintenance above does not qualify that cable-free path. Plan for USB recovery +when starting from this stock image; do not rely on the migration trial as a +verified LoRa or WiFi recovery procedure. -The normal Full Heltec V4 Repeater from `c88885a3` passed two fresh-flash -connections through the unchanged native Chromium setup GUI. With power saving -on, its quiet console checks passed for 600 seconds open and closed with logging -off, and 600 seconds open with USB logging. See the [V4 native console -qualification](../test-results/hardware_validation_heltec_v4_native_console_2026-10-06.md) -for deadlines, host preparation and retained failed attempts. USB remained -attached, so these checks do not measure CPU sleep or button wake. The subsequent -`ebf2f082` V4 button-wake profile correction passed host tests and linked-image -checks, followed by another unchanged native GUI fresh-flash connection and -180-second open/closed console checks with power saving on and USB logging. -Original settings, identity and ACL response were restored. On 2026-10-06 the -user separately confirmed V4 button screen wake, without specifying the -firmware revision or CPU sleep state. The operator USB tests did not include -an actual button press or measure CPU sleep/current draw; the new source's -GitHub unit workflow remains in progress. +A published 1.17.1.8 Full V4 installed newer applications over its node AP and +a controlled LAN on an already-expanded layout. Its old uploader could miss +HTTP completion despite installation and restart; check `ver` before retrying +an apparently stalled page. Current-source physical V4 testing was unavailable. +Earlier V4/G2 AP uploads and quiet USB tests remain evidence for their recorded +revisions. A bridge-setting command also missed its five-second deadline; +later healthy uptime and readback did not turn that timeout into a pass. -Build qualification does not establish physical compatibility on every board. -Hardware CDC has finite buffers, and closing a Linux TTY does not necessarily -produce a hardware session reset. Saturated diagnostic output is not lossless. -See [USB backpressure test results](../test-results/usb_serial_backpressure.md) -for measured scope and the upstream issues reviewed. +The [detailed browser OTA and release-candidate report](../test-results/hardware_validation_esp32_web_console_ota_2026-10-05.md#release-candidate-follow-up-recorded-2026-10-07) +retains the complete source-specific results, failures and recoveries. See +also the [native V4 console report](../test-results/hardware_validation_heltec_v4_native_console_2026-10-06.md), +[Linux Web Serial report](../research/linux_chromium_web_serial_tty.md), and +[USB backpressure results](../test-results/usb_serial_backpressure.md). +These checks do not measure fleet reliability, MCU sleep/current draw, +stack high-water or sustained RF throughput, or qualify every browser, +phone, operating system, bootloader or starting firmware version. diff --git a/docs/research/firmware_choice_followup_2026-10-06.md b/docs/research/firmware_choice_followup_2026-10-06.md index e742e14f..3625bf7c 100644 --- a/docs/research/firmware_choice_followup_2026-10-06.md +++ b/docs/research/firmware_choice_followup_2026-10-06.md @@ -1,4 +1,4 @@ -# Further firmware choice consolidation audit — 6 October 2026 +# Further firmware choice consolidation audit - 6 October 2026 Baseline: pulled commit `08bf174ea30e2e075cdd9fc74111580662b461bb`. The user requested fewer choices after the ESP32 Full-only release change. @@ -53,7 +53,7 @@ download or install firmware, contact a device, or publish the website. ## nRF52 sensor pairs: policy versus demonstrated need At this baseline, `is_nrf52_sensor_ota_pair_target()` in -[`build_legacy.sh`](../../build_legacy.sh) includes every nRF52 repeater, +[`build_legacy.sh`](https://github.com/mikecarper/MeshCore/blob/08bf174ea30e2e075cdd9fc74111580662b461bb/build_legacy.sh) includes every nRF52 repeater, room-server, and sensor recipe, including external-QSPI and SD recipes. `run_nrf52_sensor_ota_pair()` requires Full to pass, then builds Reduced; a successful Reduced build cannot replace a failed Full build. Thus the pair is @@ -145,7 +145,7 @@ qualifying actual duplicate removal. For each candidate: images and verify staging geometry, reconstruction, and the matched deployed bootloader. A passing local-install image does not prove a delta fits. 4. Change publication validation and fixtures deliberately before emitting one - artifact. [`validate_nrf52_sensor_pairs()`](../../scripts/package_cascade_release.py) + artifact. [`validate_nrf52_sensor_pairs()`](https://github.com/mikecarper/MeshCore/blob/08bf174ea30e2e075cdd9fc74111580662b461bb/scripts/package_cascade_release.py) currently requires exactly one qualified Full and one Reduced with matching target, hardware, version, source, and layout; it does not prove either member saves space or is needed. Preserve legacy endpoints needed by qualified chains. @@ -158,18 +158,18 @@ exact-delta evidence. No PlatformIO process was started for this audit. ## Storage and bootloader choices that need real distinctions -[`OtaFlashLayout_nrf52.h`](../../src/helpers/ota/OtaFlashLayout_nrf52.h) derives +[`OtaFlashLayout_nrf52.h`](https://github.com/mikecarper/MeshCore/blob/08bf174ea30e2e075cdd9fc74111580662b461bb/src/helpers/ota/OtaFlashLayout_nrf52.h) derives internal staging space from the trusted live EndF application extent, rounded to a 4 KiB page, and the effective bootloader ceiling. -[`OtaStoreFlashNrf52.cpp`](../../src/helpers/ota/OtaStoreFlashNrf52.cpp) adds +[`OtaStoreFlashNrf52.cpp`](https://github.com/mikecarper/MeshCore/blob/08bf174ea30e2e075cdd9fc74111580662b461bb/src/helpers/ota/OtaStoreFlashNrf52.cpp) adds 64 KiB of retained RAM only with the matching `MOTARAMA` capability and at least one available flash page. Its hybrid application path accepts deltas, not full application containers. A **Full sensor firmware** can still be the destination -of a delta; the two uses of “Full” must not be confused. +of a delta; the two uses of "Full" must not be confused. The historical [RAK3401 chain](rak3401_mota_chain.md) proves tight exact-package geometry under an older bootloader: multiple transitions have zero margin; -steps 1–9 were physically passed, while the replacement final step has offline +steps 1-9 were physically passed, while the replacement final step has offline reconstruction and exact-bootloader simulation only. It does not compare the current sensor pair and must not be generalized to all nRF52 boards. diff --git a/docs/test-results/hardware_validation_esp32_web_console_ota_2026-10-05.md b/docs/test-results/hardware_validation_esp32_web_console_ota_2026-10-05.md index 1c593b03..ea125506 100644 --- a/docs/test-results/hardware_validation_esp32_web_console_ota_2026-10-05.md +++ b/docs/test-results/hardware_validation_esp32_web_console_ota_2026-10-05.md @@ -104,3 +104,258 @@ GUI fresh-flash plus 180-second open/closed console check, as recorded in that linked report. On 2026-10-06 the user separately confirmed V4 button screen wake; its firmware revision and CPU sleep state were not specified. The operator USB tests included no actual button press or sleep/current measurement. + + +## Release candidate follow-up recorded 2026-10-07 + +The following source-scoped observations were originally recorded in the +1.17.1.9 candidate release notes. They are retained here as historical test +results, including failed attempts and their separate recoveries. Build and +publication status in this snapshot does not override the final +[release notes](../releases/1.17.1.9.md#verification-scope). Older passing +images do not qualify a later firmware revision or turn an earlier failure +into a pass. Latest-source V4 hardware was unavailable for a repeat; that is +a physical coverage limitation, not a failed latest-source test. + + +The [earlier c5 GitHub unit workflow](https://github.com/mikecarper/MeshCore/actions/runs/37550980479) +passed all four jobs. Host regressions exercise production OTA callbacks, +the official configuration GUI and app protocol behavior, including MD5 +ordering, rejected second files, incomplete POSTs, cleanup and subsequent +valid uploads. Sanitizer fixtures cover these OTA lifecycle cases. These +checks use MeshCore's actual-code fixtures; MeshBench is not integrated. + +For `1e421ff4`, the coupled production WebConfig credential interception, +NVS commit, CLI routing and MQTT consumer fixture passed four tests, including +fresh portal-only setup, legacy fallback, reconnects, raw-PSK boundaries, +failed and interrupted writes, and mutations that restore the old credential +lookup. The broader WiFi and MQTT host suites passed 62 and 14 cases, +respectively, with some overlap. The WebConfig host suite passed 53 cases, +including the embedded page in an isolated Chromium headless browser. +Seven infrastructure power-lifecycle cases +and six portal-ownership cases passed. Five V4 setup-page cases include actual +button/session handling under both signed and unsigned `char`. The new tests +are explicitly included in the unit workflow. The [current GitHub unit workflow](https://github.com/mikecarper/MeshCore/actions/runs/37570287426) +at documentation and host-test commit `4c5f58f4` passed all four jobs; its +firmware source remains `1e421ff4`. The completed local release passed the +strict package checks below; V4 OTA and G2/V4 portal-to-MQTT hardware checks +remain pending. + +The completed local all-board release has 463 qualified recipes and 926 +firmware files. Its complete checksum inventory, capability and memory +checks passed independent read-only revalidation. All 94 exact ESP32 +board/role migration ZIPs and their combined archive passed validation. +The 114 nRF52 infrastructure targets each have a qualified Full/Reduced +pair with matching actual DFU identity, firmware and flash layout. These +results qualify local packages from `1e421ff4`; they do not qualify the +pending physical upgrade paths or publish the release. The newer +`bd4cbf281` source protects ordinary setup/OTA APs from the SDK's shared +long-range WiFi flag, defers conflicting ESP-NOW starts and keeps long-range +protocol writes out of saved WiFi settings. It reports an active ESP-NOW +conflict before starting an AP. The subsequent `8c4e09275` source also defers +MQTT station maintenance and Full Companion station recovery while an AP +owns WiFi. Final builds and hardware qualification of this candidate remain +pending. Final public assets and catalogs still require their separate +inventory and digest checks. + +The physical G2 and V4 tests used the unchanged embedded browser uploader +and the normal host console, retaining the stock 5-second first-command +deadline. The earlier `c5fe8a0e` applications passed AP uploads with HTTP +200/OK, automatic restart, and preserved identities, ACLs and saved settings. +The G2's initial upload completed in 19.053 seconds; the V4's completed in +16.392 seconds. First ordinary replies took 1.385 and 1.010 seconds, +respectively, without a cable replug or reset rescue. + +On the G2, a full valid first file followed by a second file returned HTTP +409 without an observed MCU restart. A full-file request with an incomplete +closing multipart boundary also left uptime continuous. A valid upload then +passed through that same running listener in 18.767 seconds. Full-image +wrong-MD5 requests had already returned HTTP 400 without restart on parent +`70bf4bdf`. The tests do not claim that rejected requests leave the inactive +flash slot untouched. A fresh 385-second sample of unmodified Cisien +meshcoretomqtt had all four brokers connected, zero publish failures and no +service restarts; both the original and recovery Admin ACLs were preserved. +The earlier G2 LAN upload stall is treated as a local slow-WiFi limitation, +not a release blocker. LAN upload was not qualified by these AP tests. + +The new `1e421ff4` G2 Full Observer application also passed the unchanged +native AP uploader: HTTP 200/OK in 18.437 seconds, firmware-owned restart, +and first ordinary `ver` reply in 1.304 seconds. Live EndF body identity, +the exact G2 target and source were verified, with the original 15 settings, +both Admin ACLs, services and the Pi's exact SlowFi connection preserved. +This qualifies that AP update, not fresh WebConfig provisioning into the +on-device MQTT consumer; that check and the new-source V4 checks remain pending. + +On parent `70bf4bdf`, both G2 and V4 passed four 600-second quiet intervals: +port open and closed with logging off, then open and closed with USB logging, +all with power saving enabled. Uptime remained continuous, with no host +keepalive writes during the intervals. The V4 reported radio-watchdog event +bit 8; this was not an MCU reset or an all-zero-error result. Its USB-logging +open interval received 26 bytes. The V4 also passed the first unchanged +native setup-GUI connection immediately after a fresh flash, with the first +clock reply in 73.3 ms. These quiet and fresh-flash checks were not repeated +on `c5fe8a0e`, whose change was confined to OTA completion behavior. The +newer canonical-WiFi source `1e421ff4` has the narrower G2 results below. + +On `1e421ff4`, the G2 passed one 600.022-second open-port quiet interval +with USB logging and power saving enabled, with no host writes and continuous +uptime. The following 600-second closed-port interval ended in a stock-browser +reopen failure at the test helper's 5-second acquisition gate, before `ver` +was sent. The host then had VMIN=1/VTIME=0; the ordinary exclusive serial +client still replied in 21 ms, with continuous uptime and unchanged core error +flags. This is an unresolved browser/native-port acquisition result, not a +qualified closed-port pass or evidence of an MCU crash. A cleanup-overlay bug +in that test helper was also found and fixed for the instrumented repeat; +the earlier failed receipt is retained. + +The instrumented G2 repeat on the same `1e421ff4` source passed both +600-second open and closed quiet intervals with USB logging and power saving +enabled, continuous uptime and no host keepalive writes. Original settings and +the host were restored. The maximum stock Enter-to-reply time was 3.584 seconds. +The second native port open took 5.532 seconds; click-to-connected took +8.201 seconds. That acquisition time is separate from the unchanged 5-second +command deadline, and the helper's connected wait started after its click RPC +returned. This repeat does not reclassify the earlier failure or establish its +cause. The separate logging-off run also passed both 600-second open and +closed quiet intervals with power saving enabled, 85 successful queries, +continuous uptime and restored original settings. Together the completed +runs qualify all four quiet intervals on this G2 and source. + +The subsequent 100-cycle acceptance attempt stopped after 32 completed cycles. +All 86 stock commands passed, with a maximum Enter-to-reply time of 450 ms +and no observed MCU reset. The failure was an automation timeout while +clicking the stock close-overlay button; this is separate from the stock +command deadline. At the failed-trial snapshot, the UI had marked itself +disconnected while native close had not started. Native close subsequently +fulfilled in 105.5 ms, and the serial port and page closed. The cause of the +earlier disconnect or click delay remains unproven. The failed receipt is +retained; 100-cycle qualification and follow-up diagnosis remain pending. + +A separate Linux Chromium 139 comparison isolated an inherited host TTY +setting: VMIN=0/VTIME=0 produced device-lost stream termination, while changing +only VMIN to 1 gave a stock `ver` reply in 154.1 ms without reset or replug. +That finding does not establish the cause of the later reopen failure above. +See the [Linux Web Serial report](../research/linux_chromium_web_serial_tty.md) +for primary browser-source evidence and the bounded host preflight. + +The physical RAK3401 Companion on `70bf4bdf` passed 21 malformed-request +cases with 217 request/reply frames. Its Full Repeater passed the official +native setup GUI and 600-second open/closed quiet intervals with power saving +on, continuous uptime and zero core error flags. It was returned to the +then-current `c5fe8a0e` Full Companion; the first stock SDK reply took 25.9 ms +without an initial retry or settling delay. Original identity, contacts, +channels, custom variables, RX power-saving settings and actual packet-stream +mode were restored. The planned reboot needed to restore stream mode was +separate from the stability measurements. An initial SWD programming failure +was recovered and verified; this was not a first-attempt programming pass. +These tests did not qualify RAK3401 BLE DFU, LoRa OTA or bootloader updates. + +The actual published `9053038f` 1.17.1.8 Full V4 installed newer applications +over both AP and a controlled shared WiFi LAN, but its old page did not +receive HTTP completion. Check `ver` before retrying a stalled old page. +These trials used already expanded application slots; actual phone-hotspot +uploads remain untested. The requested legacy small-slot G2 trial now has a +verified existing 16 MiB backup and genuinely programmed and verified the +official 1.14.1 stock components and small-slot table while preserving NVS. +Its first stock USB `ver` request reached the five-second host command limit; +a later read-only probe replied without reset. A separately recorded stock +setup restored and verified the original identity, 22 common settings and two +Admin ACLs after normal reboots. Password setters were confirmed and the guest +password persisted; stock has no admin-password getter. The final `start ota` +returned its expected URL, but the test's AP scan timed out. A subsequent +completed native scan found no `MeshCore-OTA` AP at any BSSID. A later +read-only NVS audit identified the test starting-state problem: earlier +preconditioning had saved the WiFi long-range protocol flag, which stock +inherited. Its long-range AP beacons cannot be received by the ordinary +WiFi clients used here. This does not establish a stock AP startup bug. +A separately recorded correction changed only the fresh live NVS protocol +flag and its entry CRC, with exact readback and unchanged stock components +and small-slot table. After stock identity, common settings, ACL and guest/ +private-identity checks, a completed fresh scan found the exact G2 OTA AP. +This establishes the genuine stock WiFi-only starting boundary. The earlier +failed receipts remain failed. The first native migration controller then +failed on a missing host `iw` executable before any HTTP or image-upload +step. It may already have associated with the AP; that outcome was not +verified. Its return to SlowFi and owned guard cleanup passed. A separately +reviewed retry retained the firmware/controller inputs, separately pinned +the old runtime log and checked host executables before using fresh guards. +It associated with the exact stock AP and observed one native bridge-image +POST with the exact bytes, SHA256 and MD5, but the old embedded page did not +complete its HTTP response before the uploader deadline. Browser closure, +return to SlowFi and guard cleanup passed; that transaction remains failed. +A later scan found the exact migration AP. A separately recorded stage2 +continuation then verified the actual expanded-layout-ready page and uploaded +the exact `1e421ff4` ordinary Full application through the unchanged native +page, with matching MD5 and HTTP 200/OK in 14.526 seconds. That upload phase +also passed its network return and guard cleanup. The subsequent controlled +Pi AP phase failed on a host `FileNotFoundError` before any final HTTP request. +The host's scheduled WiFi refresh also interrupted that AP phase. Its later +guard-file cleanup refused an unproven network state; a separate read-only +qualification and owned-file cleanup then verified the original network, +dead controller and removal of all prior guard profiles and files. A new +proof-only attempt stopped before AP activation because reloading services +moved the host hold timer's relative deadline. Its failed receipt is retained, +and the held host script was restored. The next proof used a fixed absolute +hold deadline, but stopped before AP activation when a host-file permission +check rejected the actual private service file; its failed receipt and host +restoration are preserved. A third proof verified and ran the isolated Pi +AP with the independent return timer armed, then reached the five-minute +client/DHCP discovery deadline without a verified G2 client or any HTTP +request. It returned to SlowFi, removed its owned network resources and +restored the host's scheduled WiFi recovery script. Final +running-image/layout/identity/settings HTTP verification remains unproven; +the successful firmware upload does not establish that final verification. +After that completed failed WiFi check, separate USB maintenance installed +the `8c4e09275` ordinary Full Observer application. Full application +readback and the normal running version matched, while the bootloader, +partition table, NVS, OTA selection and checked filesystem region stayed +unchanged. This maintenance does not qualify the WiFi-only upgrade. The +saved-settings check found RX boosted gain off instead of its original on; +the other 21 common settings, identity, passwords and two Admin ACLs matched. +A separate checked CLI repair restored gain on and verified all 22 settings. +The first extras restoration then missed the five-second CLI deadline while +changing bridge source. A later read-only probe found continuous uptime, +zero core error flags and the requested source value; it does not establish +the missing command acknowledgment or its save duration. After checking that +state, a separate restoration completed with the original WiFi pair, saved +extras, all 22 common settings, identity, passwords and both Admin ACLs +verified. The MQTT worker was running with valid effective configuration; +broker connectivity was not tested. Original TTY settings, all three host +services and SlowFi were restored, and the exact temporary host executable +alias was removed. The earlier timeout and WiFi proof failure remain recorded. +The loader correction is included in `88c851080`. Its G2 ordinary Full Observer +application was independently read back in full after installation, and normal +boot matched the exact new runtime and EndF footer. The checked lower 64 KiB, +OTA selection and first 64 KiB of the filesystem stayed unchanged. A separate +read-only post-boot check verified the original identity, passwords, two Admin +ACLs, all 22 common settings, seven supported bridge fields and saved extras. +Core error flags were zero; the MQTT worker was running with valid configuration, +without a broker-connectivity claim. Original TTY settings, all three host +services and SlowFi were restored. This USB maintenance does not qualify the +failed WiFi-only final verification. The fresh all-board build and V4 hardware +checks remain pending. +These are separate +outcomes; the initial failed transactions remain failed. The earlier c5 +AP upload success does not turn those old HTTP-completion failures into +passes. The [upgrade guide](../upgrading_1.17.1.8_to_1.17.1.9.md) keeps the +old and new updater behavior separate. + +Original host services, temporary network changes and owned test resources +were restored after the historical completed hardware checks. The current +new-source V4 native AP OTA trial has not yet produced a verified result; +its return to SlowFi and original host-service state also remain unverified. +The legacy G2 check established the stock starting boundary with its original +identity, common settings and ACLs verified, then completed the expansion and +Full application upload over WiFi. It has not yet qualified the final running +image through HTTP. Post-verdict `88c851080` G2 firmware readback, normal boot, +original-settings acceptance and host restoration passed separately over USB. +The all-board build and current V4 hardware qualification remain pending. These +checks keep publication pending. Build qualification does not +establish physical compatibility on every board. Quiet USB trials do not +measure MCU sleep/current draw, stack high-water, sustained log backpressure +or long-term fleet reliability. Linux native-browser tests required host TTY +preparation; they do not qualify every browser or operating system. Hardware +CDC has finite buffers, and closing a Linux TTY does not necessarily produce +a hardware session reset. See the historical [V4 console report](../test-results/hardware_validation_heltec_v4_native_console_2026-10-06.md) +and [USB backpressure results](../test-results/usb_serial_backpressure.md) +for their exact source revisions and measured scope. diff --git a/docs/upgrading_1.17.1.8_to_1.17.1.9.md b/docs/upgrading_1.17.1.8_to_1.17.1.9.md new file mode 100644 index 00000000..a49e4c44 --- /dev/null +++ b/docs/upgrading_1.17.1.8_to_1.17.1.9.md @@ -0,0 +1,166 @@ +# Upgrading from 1.17.1.8 to 1.17.1.9 over WiFi + +For a supported ESP32 node that already has compatible application slots, +use its own `MeshCore-OTA` access point and the matching application-only +image. This measured V4 route avoids dependence on the site's WiFi credentials +and LAN reachability. USA Cascade defaults remain 910.525 MHz, 62.5 kHz, SF7 and CR5; existing saved radio settings take +precedence after an update. + +Select the exact board, hardware variant and role in the +[firmware picker](firmware_picker.md). Download the image before connecting +to the node's update network. The release's manifests and SHA-256 inventory +identify the exact files. Preserve identity and settings using the tools +appropriate to the installed role before an upgrade. + +## Choose the installation route + +| Installed node | File and route | +| --- | --- | +| Exact ESP32 board/role with compatible dual-OTA slots | Matching application-only `.bin` through its working browser updater. | +| Supported legacy dual-OTA layout needing expansion | Exact board/role migration ZIP from the selected release's utility page; follow its README and use its supplied Full application. | +| Layout without a matching migration package, single application slot, or no working supported updater | Matching `-merged.bin` through that board's USB/serial flashing procedure. | +| nRF52 | Matching application UF2/DFU ZIP or a separately documented LoRa OTA route; this ESP32 browser procedure does not apply. | + +An application-only update cannot replace a partition table. Where available, +`get storage.layout` reports the live layout; a version label does not establish +it. For older firmware, use the [partition lookup guide](esp32_partition_catalog.md). +The tested V4 already had two 6.25 MiB slots in the expanded 16 MiB layout. +That result does not qualify a migration from legacy 1.25 MiB slots. + +Never upload a `-merged.bin` or `target-partitions.bin` to an application-only +browser updater. A merged image includes bootloader and partition-table +offsets for USB/serial installation. A migration package's target table is +a verification artifact, not an application. + +## Recommended 1.17.1.8 V4 example: use the node's AP + +The actual published Full V4 build tested was `9053038f`. From an authenticated +USB, Bluetooth or LoRa command session, send these commands one at a time, +waiting for each reply: + +```text +stop webconfig +stop ota +start ota ap +``` + +Stopping WebConfig explicitly is needed for this old build's HTTP-port +handoff. Stopping a previously running uploader ensures the old `start ota ap` +starts the AP route. The new 1.17.1.9 startup behavior should not be assumed +on the old receiver. + +Join the node's `MeshCore-OTA` WiFi network. Open the exact URL returned by +the command, normally `http://192.168.4.1/update` for an infrastructure node. +Confirm that the page identifies the intended node, select its matching +1.17.1.9 application-only `.bin`, and upload once. Keep the node powered +through the transfer and its automatic restart. + +After restart, reconnect with the normal configuration app or console and +run: + +```text +ver +get storage.layout +``` + +Compare `ver` with the selected image and confirm identity, ACL, radio settings +and the other saved settings used by the node. A command unsupported by the +installed image is not proof of an incorrect layout; use the lookup guide +when necessary. + +The old 1.17.1.8 page can remain at 100% or miss HTTP completion even after +the new application installs and the node restarts. Check the running version +before repeating an upload. Browser transmission progress alone does not +prove successful installation. + +For 1.17.1.9 receivers, `start ota` starts WiFi when needed, stops WebConfig +to free its HTTP port, and reports the IP address and network to use. +`start ota ap` explicitly selects the node AP even if a LAN uploader is +already running. WebConfig's own terminal explains that the handoff closes +the portal; send it through USB, Bluetooth or LoRa instead. On a compatible +two-slot Full Companion, use the returned port-8080 URL; single-slot Full +Companions require USB for self-update. Use `stop ota` if abandoning an update. + +## LAN and phone examples + +If an old 1.17.1.8 infrastructure node is already reachable on the intended +WiFi LAN, retain that connection. Otherwise configure it through its existing +WebConfig UI, then verify the live address with `get webui`. From a separate +USB, Bluetooth or LoRa session: + +```text +stop webconfig +stop ota +start ota +``` + +Open the exact returned LAN URL, for example `http://192.168.1.40/update`. +The upload computer or phone must be able to reach that address. On +1.17.1.8, confirm the actual connection after changing credentials; a serial +WiFi setter alone does not prove that WebConfig uses the new pair. If the LAN +is weak or blocks client-to-client traffic, use the node AP route above. + +A phone near the node can download the correct application while it has +Internet access, join `MeshCore-OTA`, and use its browser at the returned +address. Keep that WiFi connection even if the phone warns it has no Internet. +This is the same intended node-AP route, but an actual phone browser upload +was not physically tested in this run. + +A phone hotspot is useful only if the node and uploading device can both +join it and reach one another. Confirm the node's reported LAN URL before +uploading; hotspot client isolation can prevent this. The controlled shared +LAN test used a Pi access point, not a real phone hotspot, so a phone hotspot +is not the qualified default recommendation. For a node with only LoRa +reachability, use the [LoRa OTA guide](lora_ota_automation.md) and exact matching +target/storage package. + +## When partition expansion is required + +Use the exact migration ZIP selected for this board and role. Its README +defines the supported old updater, live-source checks and preservation set: + +1. Upload that package's `wifi-bridge.bin` through the supported old updater. +2. Join the migration network described in its README and wait for + **Expanded layout ready**. +3. Upload the same package's `full-application.bin` through its `/update` page. +4. Verify the new layout, version, identity, ACL and supported saved settings. + +Do not substitute a loose release application for the ZIP's supplied Full +application: migration packages can carry a required older target identity. +Do not combine stages from different packages. The bridge writes the +partition-table sector; loss of power during that write can require cable +recovery. See the [complete migration directions](esp32_wifi_partition_migration.md) +for the exact preservation limits and supported WiFi/LoRa routes. Actual +legacy-layout V4 migration was not physically tested in this run. + +## Stock G2 migration limitation + +The separate stock 1.14.1 G2 trial reached the `1e421ff4` Full application +over WiFi after partition expansion, but its final isolated +network check reached the client/DHCP deadline without a verified G2 client +or any HTTP request. The complete cable-free migration is therefore not +qualified. Plan for USB recovery if starting from that stock image. + +The G2 was subsequently updated and verified through separate USB maintenance +on release source `88c851080`, with its original identity, ACLs, 22 common +settings and saved extras preserved. That result does not qualify the failed +WiFi-only final check. A legacy RX-gain loading correction preserves an +unambiguous saved gain of on from compact stock preferences; ambiguous older +zero padding retains the board default. + +The [detailed test report](test-results/hardware_validation_esp32_web_console_ota_2026-10-05.md#release-candidate-follow-up-recorded-2026-10-07) +retains the original failures, host/network recovery and exact source revisions. +Latest-source physical V4 testing was unavailable; the measured older upgrade +routes below do not establish every board or starting version. + +## Measured upgrade scope + +The published 1.17.1.8 Full V4 installed newer applications over node AP and +a controlled shared LAN, with automatic restart and preserved identity and +ACL, despite missing old-page HTTP completion. On the earlier `c5fe8a0e` source, +the unchanged native AP pages returned HTTP 200/OK for G2 and V4 uploads; +the V4 upload completed in 16.392 seconds and its first ordinary clock reply +took 1.010 seconds against the unchanged 5-second console deadline. These +tests used compatible expanded layouts and do not qualify every board, +browser, phone or starting version. See the +[1.17.1.9 verification scope](releases/1.17.1.9.md#verification-scope). diff --git a/mkdocs.yml b/mkdocs.yml index ae3bec33..03810071 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -61,6 +61,7 @@ nav: - companion_offline_queue.md - halo_keymind_settings.md - Firmware updates and partitions: + - upgrading_1.17.1.8_to_1.17.1.9.md - ota_user_guide.md - ota_easy.md - lora_ota_automation.md