upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
path: root/docs/WPA-AUTO-DETECT-PLAN.md
diff options
context:
space:
mode:
authorYour Name <you@example.com>2026-05-19 13:21:25 +0530
committerYour Name <you@example.com>2026-05-19 13:31:08 +0530
commiteeba74a4a1c011e85e33dea4252b381e35a64ea4 (patch)
tree14862e7d300511e28e214c743fd2f699bc54c5b8 /docs/WPA-AUTO-DETECT-PLAN.md
parentb0d9d494f00ee77f9efc22d1ef2ea3c94b23ddbd (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.md121
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
6router (`EnterSSID-2.4GHz`) uses **WPA2**, so the ESP32 silently refuses
7association and never gets internet. This blocks health probes, real payments,
8and all downstream testing.
9
10Additionally, 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
17Add `wifi_auth_mode` field to `tollgate_config_t`. Parse it from `config.json`
18as 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
20accepts both WPA2 and WPA3 networks.
21
22### 2. Makefile Auto-Detect (Build Time)
23
24Add Makefile targets that scan WiFi with `nmcli`, detect WPA2 vs WPA3, and
25generate a SPIFFS image with the correct `wifi_auth_mode` baked into
26`config.json`.
27
28### 3. Reduced Probe Interval (Testing)
29
30Temporarily reduce `MINT_HEALTH_PROBE_INTERVAL_S` from 300 to 30 so health
31probes 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
1171. Push commits when Nostr relay recovers
1182. Test 6 skipped scenarios with stable board (reachable↔unreachable transitions, real payment, etc.)
1193. Revert `MINT_HEALTH_PROBE_INTERVAL_S` from 30 to 300 before production
1204. Address NVS `ESP_ERR_NVS_NOT_ENOUGH_SPACE` errors for keyset storage
1215. Investigate display `ESP_ERR_NO_MEM` errors (307KB PSRAM framebuffer)