Document 1.17.1.6 release and validation scope

docs/releases/1.17.1.6.md

@@ -0,0 +1,110 @@
+# MeshCore 1.17.1.6 Dev - USA Cascade
+
+This release builds the current `keymindCascade` source after repairing the
+unit-test regressions. Its firmware identifier is
+`v1.17.1.6-halo-keymind-cascade-dev-<commit>`. The recorded commit identifies
+the source for every firmware file; binaries from earlier releases are not reused.
+
+Use the [firmware picker](https://mikecarper.github.io/MeshCore/firmware_picker/)
+to match the exact board, radio, display and flash variant. The Companion release
+is marked Latest. Supporting release pages retain the `repeater-room-`,
+`utility-`, `logging-`, `lora-ota-` and `full-profiles-` prefixes where those
+outputs exist, and remain development prereleases.
+
+The build uses the USA/Canada radio preset and Cascade runtime defaults. Build
+records include the resolved radio settings; the offline USA Cascadia fallback
+is **910.525 MHz, BW62.5, SF7, CR5**. Ordinary updates retain saved node settings.
+
+## Two LoRa profiles
+
+`radio2`, `tempradio2`, `radioat2` and `tempradioat2` add a second profile to
+LoRa-equipped Companion, Repeater, Room Server, Sensor and terminal firmware.
+The second profile starts disabled. It supports receive-only or receive/transmit
+operation, separate retry ownership and backoff, and explicit off commands.
+
+One transceiver alternates between at most two active profiles. Reception and
+transmission occupy that transceiver, so a packet on one profile interrupts
+listening on the other. This does not provide two simultaneous receivers.
+
+By default, traffic can cross between two permanent profiles or two temporary
+profiles. A permanent/temporary pair stays isolated. `radio2.cross auto|on|off`
+controls this policy; receive-only still forbids transmission on profile 2.
+`tempradio2` can carry LoRa OTA traffic while the primary profile remains
+available between packets. Use a firmware profile that supports the required
+OTA role.
+
+Radio commands accept an optional trailing preamble, and their getters include
+the effective preamble. Automatic preambles round up in steps of eight. Paired
+with SF7/BW62.5/preamble 32, the automatic BW500 values are 48 symbols at SF9,
+88 at SF8 and 120 at SF7. Configure transmitters with matching preambles too.
+
+Dual-profile receive uses normal RX with the slower profile visited first.
+RX power saving and device sleep are suspended while scanning, then the saved
+settings apply again in single-profile mode. See the
+[setup guide and command matrix](../radio_profiles.md) and
+[hardware measurements](../radio_profiles_validation.md).
+
+## Other changes since 1.17.1.5
+
+- Restores `set path.hash.mode 0|1|2` on infrastructure firmware, with CLI
+  dispatch and get/set regression coverage. Unsupported `extra.sf` commands
+  report an explicit error on radios without that capability.
+- Uses received MeshCore packets to feed the repeater RX watchdog. Fresh
+  settings default to 24 hours; temporary primary-radio sessions lasting at
+  least 12 hours use 12 hours, while shorter sessions disable that watchdog.
+  Temporary-session adverts and watchdog settings revert when the session ends
+  or the node reboots. See [CLI commands](../cli_commands.md).
+- Adds separate battery and USB display modes, with timeouts in seconds.
+  Companion inbox settings distinguish retained history, pending delivery and
+  the local unread count. Read previews remain browseable in Unread mode.
+- Includes native-USB sleep/wake corrections, nRF52 USB startup fixes,
+  receive recovery and noise-calibration improvements, and the reviewed
+  ExpressLRS board/power changes.
+- Consolidates redundant Full infrastructure builds while retaining useful
+  smaller-slot variants. Full profiles and smaller portable images continue
+  to require their matching partition and update method.
+
+Feature switches and update commands are documented in
+[feature switches by role](../role_feature_switches.md),
+[Full Companion features](../full_companion_features.md) and the
+[ESP-NOW bridge guide](../espnow_bridge_setup.md).
+
+## Validation and installation
+
+The release is gated on the [unit-test workflow](https://github.com/mikecarper/MeshCore/actions/workflows/run-unit-tests.yml)
+for its source commit. CI repairs replace stale display assertions with compiled
+tests of bookmark saves across battery/USB transitions and message summaries in
+each inbox mode. The sleep harness checks both MQTT and dual-profile scanning.
+
+The release packager checks each published profile's capability manifest,
+firmware-file hashes, native file pairs and
+[runtime RAM budget](../firmware_memory_budget.md). Infrastructure must have a
+verified wireless update path. The target manifests and exclusion report describe
+the actual published matrix; a build check is not a physical-board test.
+
+Dual-profile timing was measured on a Heltec V4 with a XIAO ESP32-S3/Wio LoRa
+transmitter. Finite strong-signal tests and an OTA catalogue exchange passed;
+these tests do not establish weak-signal performance, simultaneous traffic
+reliability, a complete hardware OTA installation, or months of uptime.
+
+ESP32 WiFi updates use the application `.bin`. The `-merged.bin` image includes
+boot and partition data for USB installation. nRF52 uses the board's `.uf2` or
+native application DFU `.zip`; LoRa OTA also needs the exact destination package
+and a compatible OTAFIX bootloader. Check the per-profile capability manifest
+before choosing an update method.
+
+## Reproduce the release
+
+Use a clean checkout of the release commit and a fresh output directory:
+
+```bash
+OUTPUT_DIR=.releases/1.17.1.6-halo-keymind-cascade-dev \
+bash build.sh build-firmwares-logging-matrix \
+  --firmware-version v1.17.1.6-halo-keymind-cascade-dev \
+  --radio-preset usa-cascadia --profile cascade \
+  --require-ota --skip-kiss --resume --background
+```
+
+Run only one PlatformIO process in that checkout. Publish only after the full
+matrix completes successfully and `scripts/package_cascade_release.py` accepts
+the completed build status, source commit and `--version 1.17.1.6`.