diff --git a/docs/RELEASE_GUIDE.md b/docs/RELEASE_GUIDE.md index 553b2ab..a620ba7 100644 --- a/docs/RELEASE_GUIDE.md +++ b/docs/RELEASE_GUIDE.md @@ -105,6 +105,32 @@ state/delivery latency with the hard limits in `RESOURCE_BUDGET.md`. - Capture `/api/health`, reset reason, and the exact source revision before reporting a failure. Never capture or publish tokens or Wi-Fi credentials. +## Network recovery qualification + +This target-board checklist is required before declaring the Wi-Fi recovery +milestone complete. It is deliberately manual: radio association, DHCP, AP +visibility, and memory stability cannot be proven by a host build. + +Before each case, record `/api/health` where the device is reachable. Record +the `gameId` and `version` of an active game before a network transition and +again after clients reconnect. Do not include credentials, session tokens, or +private network names in the record. + +| Case | Required observation | +| --- | --- | +| Saved network cold boot | The board obtains a DHCP address and serves the application without configuration. | +| Missing/deleted, malformed, or unavailable profile | `Battleship-open` is visible no later than 30 seconds after boot or loss of connectivity; `/setup` works at `http://192.168.4.1/setup`. | +| Incorrect password, hidden network, or DHCP unavailable | The previous saved profile remains intact; the fallback AP and configuration page remain usable. | +| External-network loss during an active game | After fallback begins, reconnect clients through the AP and verify the same `gameId` and a current state snapshot. | +| Successful replacement | Keep the fallback connection until the success confirmation, then reconnect through the new DHCP address without rebooting and verify the game remains in RAM. | +| Repeated transition run | Complete 20 external-network-loss/fallback/recovery cycles. Compare health snapshots for reset reason, minimum free heap, largest free block, and response responsiveness. | + +During a failed saved-network attempt, serial output must show the disconnect +reason and either a successful STA address or the 30-second fallback timeout. +For fallback, confirm the AP address and `fallback AP active`; report DNS or +HTTP startup failures as failures of this checklist. The firmware must never +erase NVS, LittleFS, or flash while performing these checks. + ## Release record template Complete this only after all physical checks pass: diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 8444568..cefa36a 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -365,7 +365,7 @@ components: properties: ok: { type: boolean, enum: [true] } uptimeMs: { $ref: '#/components/schemas/GameId' } - wifiState: { type: string, enum: [not_configured, connecting, connected] } + wifiState: { type: string, enum: [not_configured, connecting, connected, fallback] } freeHeapBytes: { $ref: '#/components/schemas/GameId' } minimumFreeHeapBytes: { $ref: '#/components/schemas/GameId' } largestFreeBlockBytes: { $ref: '#/components/schemas/GameId' }