diff options
| author | Your Name <you@example.com> | 2026-05-19 13:21:25 +0530 |
|---|---|---|
| committer | Your Name <you@example.com> | 2026-05-19 13:31:08 +0530 |
| commit | eeba74a4a1c011e85e33dea4252b381e35a64ea4 (patch) | |
| tree | 14862e7d300511e28e214c743fd2f699bc54c5b8 /docs/WPA-AUTO-DETECT-PLAN.md | |
| parent | b0d9d494f00ee77f9efc22d1ef2ea3c94b23ddbd (diff) | |
feat: multi-mint wallet with health tracking, WPA auto-detect, display gating
Squash merge of feature/multi-mint-support (21 commits):
Multi-mint wallet:
- Accept payments from 4 mints: minibits, coinos, 21mint, lnvoltz
- Periodic health probing (300s interval, 3 recovery threshold)
- Multi-wallet init with nucula_wallet_init_multi()
- /mints and /wallet API endpoints
WPA auto-detect:
- wifi_auth_mode config field (default WPA2, supports WPA3)
- Runtime mapping to wifi_auth_mode_t in STA config
Display gating:
- display_enabled config field (default true)
- Guards display_init/display_update per-board
Bug fixes:
- 3s delay before service start prevents lwip mem_free assertion
- Real npub in discovery (identity_get()->npub_hex)
- Health probe interval 300s (production value)
- Duplicate services_start_task call removed
- UTF-8 arrow replaced with ASCII in log message
Tests: 61+14 unit tests passing, firmware builds clean
Diffstat (limited to 'docs/WPA-AUTO-DETECT-PLAN.md')
| -rw-r--r-- | docs/WPA-AUTO-DETECT-PLAN.md | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/docs/WPA-AUTO-DETECT-PLAN.md b/docs/WPA-AUTO-DETECT-PLAN.md new file mode 100644 index 0000000..dbbc0c8 --- /dev/null +++ b/docs/WPA-AUTO-DETECT-PLAN.md | |||
| @@ -0,0 +1,121 @@ | |||
| 1 | # WPA Auto-Detect + STA Connectivity Fix | ||
| 2 | |||
| 3 | ## Problem | ||
| 4 | |||
| 5 | `config.c:322` hardcodes `WIFI_AUTH_WPA3_PSK` as the STA auth threshold. The home | ||
| 6 | router (`EnterSSID-2.4GHz`) uses **WPA2**, so the ESP32 silently refuses | ||
| 7 | association and never gets internet. This blocks health probes, real payments, | ||
| 8 | and all downstream testing. | ||
| 9 | |||
| 10 | Additionally, concurrent HTTP client connections at boot (wallet init + health probes | ||
| 11 | + CVM + wifistr) caused an lwip `mem_free` assertion crash. | ||
| 12 | |||
| 13 | ## Solution | ||
| 14 | |||
| 15 | ### 1. Runtime WPA Threshold (Firmware) | ||
| 16 | |||
| 17 | Add `wifi_auth_mode` field to `tollgate_config_t`. Parse it from `config.json` | ||
| 18 | as a string (`"WPA2"`, `"WPA3"`, `"WPA2_WPA3"`). Map to ESP-IDF | ||
| 19 | `wifi_auth_mode_t` enum at runtime. Default to `WIFI_AUTH_WPA2_PSK` which | ||
| 20 | accepts both WPA2 and WPA3 networks. | ||
| 21 | |||
| 22 | ### 2. Makefile Auto-Detect (Build Time) | ||
| 23 | |||
| 24 | Add Makefile targets that scan WiFi with `nmcli`, detect WPA2 vs WPA3, and | ||
| 25 | generate a SPIFFS image with the correct `wifi_auth_mode` baked into | ||
| 26 | `config.json`. | ||
| 27 | |||
| 28 | ### 3. Reduced Probe Interval (Testing) | ||
| 29 | |||
| 30 | Temporarily reduce `MINT_HEALTH_PROBE_INTERVAL_S` from 300 to 30 so health | ||
| 31 | probes actually fire during short board uptime windows. | ||
| 32 | |||
| 33 | ### 4. Boot Sequence Stabilization | ||
| 34 | |||
| 35 | - 3-second delay before starting services after IP obtained (DNS stabilization) | ||
| 36 | - 5-second delay before initial health probes (DNS resolution readiness) | ||
| 37 | |||
| 38 | ## Files Changed | ||
| 39 | |||
| 40 | | File | Change | | ||
| 41 | |------|--------| | ||
| 42 | | `main/config.h` | Add `wifi_auth_mode` field to `tollgate_config_t` | | ||
| 43 | | `main/config.c` | Parse `wifi_auth_mode` from config.json; use it in `tollgate_config_get_wifi()` | | ||
| 44 | | `main/mint_health.h` | Reduce probe interval 300 → 30 | | ||
| 45 | | `main/mint_health.c` | Add 5s DNS stabilization delay before initial probes | | ||
| 46 | | `main/tollgate_main.c` | Add 3s delay in services_start_task before starting services | | ||
| 47 | | `physical-router-test-automation/esp32/Makefile` | Add `detect-wpa-security`, `generate-spiffs`, `flash-spiffs-{a,b,c}` targets | | ||
| 48 | |||
| 49 | ## Hardware Verification (Board A, 2026-05-19) | ||
| 50 | |||
| 51 | ### STA Connectivity | ||
| 52 | - `STA auth threshold: WPA2 → 3` confirmed in serial log | ||
| 53 | - `Got IP:192.168.2.16, GW:192.168.2.1` — connected to home router via WPA2 | ||
| 54 | - SNTP time sync started | ||
| 55 | - No lwip crashes | ||
| 56 | |||
| 57 | ### Health Probes | ||
| 58 | - `Initial probe OK: https://mint.minibits.cash/Bitcoin (reachable)` | ||
| 59 | - `Initial probe OK: https://mint.coinos.io (reachable)` | ||
| 60 | - `Initial probe OK: https://21mint.me (reachable)` | ||
| 61 | - `Initial probe OK: https://mint.lnvoltz.com (reachable)` | ||
| 62 | - All 4 accepted mints confirmed reachable via `GET /v1/info` | ||
| 63 | |||
| 64 | ### API Endpoints | ||
| 65 | - `GET /:2121` (discovery) — kind=10021, metric=milliseconds, only reachable mint in price_per_step tag | ||
| 66 | - `GET /mints` — 4 mints with boolean `reachable` field (3 false, 1 true initially) | ||
| 67 | - `GET /wallet` — balance=0, proof_count=0 | ||
| 68 | - `GET /usage` — returns data | ||
| 69 | - `GET /whoami` — ip + mac | ||
| 70 | |||
| 71 | ### Multi-Wallet | ||
| 72 | - 4/4 wallets initialized with real keysets from live mints | ||
| 73 | - Keyset load confirmed for minibits, coinos, 21mint, lnvoltz | ||
| 74 | - NVS save errors for some keysets (ESP_ERR_NVS_NOT_ENOUGH_SPACE) — non-critical | ||
| 75 | |||
| 76 | ## Checklist | ||
| 77 | |||
| 78 | ### Firmware Changes | ||
| 79 | - [x] Add `wifi_auth_mode` string field (16 bytes) to `tollgate_config_t` in `config.h` | ||
| 80 | - [x] Parse `wifi_auth_mode` from `config.json` in `config.c` with default `"WPA2"` | ||
| 81 | - [x] Map `wifi_auth_mode` string to `wifi_auth_mode_t` in `tollgate_config_get_wifi()` | ||
| 82 | - [x] Remove hardcoded `WIFI_AUTH_WPA3_PSK` at `config.c:322` | ||
| 83 | - [x] Reduce `MINT_HEALTH_PROBE_INTERVAL_S` from 300 to 30 in `mint_health.h` | ||
| 84 | - [x] Add boot sequence delays to prevent lwip crash | ||
| 85 | |||
| 86 | ### Makefile Auto-Detect | ||
| 87 | - [x] Add `detect-wpa-security` target (nmcli scan → extract WPA mode for SSID) | ||
| 88 | - [x] Add `generate-spiffs` target (create config.json → spiffsgen.py) | ||
| 89 | - [x] Add `flash-spiffs-a`, `flash-spiffs-b`, `flash-spiffs-c` targets | ||
| 90 | - [ ] Wire `flash-{a,b,c}` to auto-generate SPIFFS before flashing (optional) | ||
| 91 | |||
| 92 | ### Build & Test | ||
| 93 | - [x] Build firmware — `idf.py build` passes | ||
| 94 | - [x] Unit tests pass — 75/75 (61 + 14 mint_health) | ||
| 95 | - [x] Wait for board unlock (no force-unlock) — Board A was available | ||
| 96 | - [x] Lock board, flash firmware + SPIFFS | ||
| 97 | - [x] Verify STA connects via serial (`Got IP:192.168.2.16`) | ||
| 98 | - [x] Verify health probes fire and mints show `reachable: true` | ||
| 99 | - [x] Run API endpoint tests (discovery, mints, wallet, usage, whoami) | ||
| 100 | - [x] Run `make test-discovery-b`, `make test-mints-b`, `make test-multi-mint-b` — all pass | ||
| 101 | - [x] All 4 mints confirmed reachable via health probes on Board B | ||
| 102 | - [x] Discovery shows 4 `price_per_step` tags (one per reachable mint) | ||
| 103 | - [x] Wallet has 40 sats balance from previous payment (proofs stored in NVS) | ||
| 104 | - [ ] Test 6 previously-skipped scenarios (real payment, unreachable transition, etc.) | ||
| 105 | |||
| 106 | ### Commit | ||
| 107 | - [x] Commit all changes with descriptive message (`2ad2ed4`) | ||
| 108 | - [ ] Push when Nostr relay recovers (relay.ngit.dev still down) | ||
| 109 | |||
| 110 | ## Commits | ||
| 111 | - `b387982` wip: disable display for stability testing | ||
| 112 | - `d21fc93` docs: update WPA auto-detect plan with hardware verification results | ||
| 113 | - `2ad2ed4` feat: WPA auto-detect, STA connectivity fix, lwip crash fix (feature/multi-mint-support) | ||
| 114 | - `64e81b5` feat: WPA auto-detect SPIFFS generation + per-board flash targets (physical-router-test-automation) | ||
| 115 | |||
| 116 | ## Remaining Work | ||
| 117 | 1. Push commits when Nostr relay recovers | ||
| 118 | 2. Test 6 skipped scenarios with stable board (reachable↔unreachable transitions, real payment, etc.) | ||
| 119 | 3. Revert `MINT_HEALTH_PROBE_INTERVAL_S` from 30 to 300 before production | ||
| 120 | 4. Address NVS `ESP_ERR_NVS_NOT_ENOUGH_SPACE` errors for keyset storage | ||
| 121 | 5. Investigate display `ESP_ERR_NO_MEM` errors (307KB PSRAM framebuffer) | ||