1 files changed, 171 insertions, 0 deletions

diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..c1ac093
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,171 @@
+# Design: WiFi Beacon Price Advertising via Vendor IE
+
+## Problem
+
+TollGate client mode (`tollgate_client.c`) can only discover upstream TollGate pricing **after** connecting to its WiFi and hitting `GET :2121/`. There is no way to compare prices of nearby TollGates before choosing which one to connect to. The Nostr-based wifistr approach requires internet access (expensive WebSocket connections to relays), creating a chicken-and-egg problem.
+
+## Solution
+
+Use IEEE 802.11 **Vendor-Specific Information Elements (IEs)** injected into WiFi beacon frames to broadcast price data over the air. Any nearby device can passively receive this data during a standard WiFi scan — no connection, no internet, no WebSocket required.
+
+This approach is cross-platform compatible:
+- **ESP32**: `esp_wifi_set_vendor_ie()` + `esp_wifi_set_vendor_ie_cb()` + `esp_wifi_scan_start()`
+- **OpenWRT**: hostapd `vendor_elements` config parameter
+- **Ubuntu/Linux**: `iw scan` / `nl80211` / `scapy`
+
+## Architecture
+
+### Wire Format (Phase 1: Binary Struct)
+
+The vendor IE payload uses a fixed binary struct for maximum simplicity and portability.
+
+```
+Vendor IE (Element ID = 0xDD):
+  vendor_oui[3]     = 0xC0, 0xFF, 0xEE   (OpenTollGate OUI, placeholder)
+  vendor_oui_type   = 0x01               (Price Advertisement v1)
+  payload:
+    uint8_t  version            = 1       (protocol version)
+    uint8_t  metric             = 0=milliseconds, 1=bytes
+    uint16_t price_per_step               (sats, little-endian)
+    uint32_t step_size                    (ms or bytes, little-endian)
+    uint8_t  mint_hash[4]                (first 4 bytes of SHA-256(mint_url))
+    uint8_t  geohash_len                  (0-9)
+    char     geohash[9]                  (null-padded to 9 bytes)
+    uint8_t  npub_hash[4]               (first 4 bytes of SHA-256(npub_hex))
+```
+
+Total payload: 1+1+2+4+4+1+9+4 = **26 bytes**. Well under the 255-byte vendor IE limit.
+
+### Sender Flow
+
+```
+tollgate_main.c: start_services()
+  → beacon_price_start()
+    → Build tollgate_price_payload_t from config (price, step_size, metric, mint_url hash, geohash, npub hash)
+    → Wrap in vendor_ie_data_t (element_id=0xDD, oui=0xC0FFEE, oui_type=0x01)
+    → esp_wifi_set_vendor_ie(true, BEACON|PROBE_RESP, ID_0, &ie)
+```
+
+Every beacon frame (typically every 100ms) now carries the price data.
+
+### Receiver Flow
+
+```
+tollgate_main.c: main loop
+  → market_tick()
+    → Every 30s: esp_wifi_scan_start(NULL, false)  // non-blocking all-channel scan
+    → During scan, vendor IE callback fires for each received beacon:
+      → Check OUI == 0xC0FFEE && oui_type == 0x01
+      → Parse tollgate_price_payload_t
+      → Store in market_entry_t indexed by BSSID
+    → On scan complete event: esp_wifi_scan_get_ap_records() → correlate SSID/RSSI by BSSID
+    → Sort entries by effective price
+```
+
+### Future Phases
+
+- **Phase 2**: CBOR-encoded Nostr events in vendor IEs for cryptographic verification (BIP-340 Schnorr signatures on price data)
+- **Phase 3**: Nostr relay subscription for wide-area market discovery (requires internet)
+- **Phase 4**: `client_auto_switch` — automatically disconnect from expensive upstream and reconnect to cheapest
+
+## Cross-Platform Reference
+
+### OpenWRT / hostapd (Sender)
+
+```uci
+config wifi-iface 'tollgate'
+    option vendor_elements 'dd20c0ffee0101001...hex...'
+```
+
+Where the hex is the binary payload encoded as hex string.
+
+### Linux (Receiver)
+
+```bash
+iw dev wlan0 scan | grep -A1 "Vendor specific"
+# Or: scapy/python with Dot11Beacon parsing
+```
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Vendor IE Transmitter
+- [x] Create `main/beacon_price.h` — payload struct, API declarations
+- [x] Create `main/beacon_price.c` — `beacon_price_start()`, `beacon_price_stop()`
+- [x] Compute `mint_hash` and `npub_hash` using SHA-256
+
+### Phase 2: Vendor IE Receiver + Market Scanner
+- [x] Create `main/market.h` — `market_entry_t`, `market_t`, API declarations
+- [x] Create `main/market.c` — vendor IE callback, scan trigger, entry storage, ranking
+- [x] BSSID correlation between vendor IE callback and scan results
+
+### Phase 3: Config Additions
+- [x] Add `market_enabled`, `market_scan_interval_s`, `client_auto_switch` to `config.h`
+- [x] Parse new fields from config.json in `config.c`
+
+### Phase 4: Main Loop Integration
+- [x] Call `beacon_price_start()` / `beacon_price_stop()` in `tollgate_main.c`
+- [x] Call `market_init()` in `start_services()`
+- [x] Call `market_tick()` in main loop
+- [x] Add `beacon_price.c` and `market.c` to `CMakeLists.txt`
+
+### Phase 5: Client Market Consultation
+- [x] In `tollgate_client.c`, log price comparison when connecting to upstream
+- [x] Warn if cheaper alternative exists in market snapshot
+
+### Phase 6: API Endpoint
+- [x] Add `GET /market` handler in `tollgate_api.c`
+- [x] Return JSON array of discovered TollGates with prices
+
+### Phase 7: Unit Tests
+- [x] `tests/unit/test_beacon_price.c` — encode/decode roundtrip, struct packing
+- [x] `tests/unit/test_market.c` — ranking, geohash filtering, entry management
+
+### Phase 8: Integration Tests
+- [x] `tests/integration/test-market.mjs` — GET /market endpoint validation
+- [x] `tests/integration/test-price-discovery.mjs` — two-board price discovery
+- [x] Add Makefile targets for new tests
+
+### Phase 9: ESP-IDF Build
+- [x] Fix format specifiers (`%u` → `%lu` + cast for `uint32_t` on xtensa)
+- [x] Copy local-only files (`display.c/h`, `font.c/h`) to worktree
+- [x] Apply nucula `save_proofs()` private→public patch
+- [x] `idf.py build` succeeds
+- [x] Symlink missing components (`axs15231b`, `qrcode`) from main repo
+
+### Phase 10: Hardware Mutex (per-board, shared across worktrees)
+- [x] Rewrite Makefile with per-board locks (`lock-a`, `lock-b`, `unlock-a`, `unlock-b`)
+- [x] Shared `LOCK_DIR` at `/home/c03rad0r/physical-router-test-automation/locks`
+- [x] `require_lock_a` / `require_lock_b` macros
+- [x] `acquire_lock` function macro (same pattern as `physical-router-test-automation/esp32/Makefile`)
+- [x] Per-board flash/monitor/reset/serial-log/erase-nvs targets
+- [x] `connect-a` / `connect-b` / `disconnect` WiFi targets
+- [x] `_connect-a-if-needed` / `_connect-b-if-needed` auto-connect helpers
+- [x] All integration tests require `lock-a` + `_connect-a-if-needed`
+- [x] `test-price-discovery` requires both `lock-a` AND `lock-b`
+- [x] Board port mapping matches `boards.env` (A=ACM1, B=ACM2)
+- [x] Remove old single-lock `hardware.lock` from `.gitignore`
+
+### Phase 11: Debugging & Hardening
+- [x] Add WiFi disconnect reason code to log output (`tollgate_main.c:58`)
+- [x] Add `esp_wifi_set_country_code("DE")` — was missing, defaults to CN
+- [x] Commit both fixes to `feature/price-discovery`
+- [x] Document findings in `SESSION_NOTES.md`
+
+### Final
+- [x] `make test-unit` passes (all 13 test suites, 45 new assertions)
+- [x] `idf.py build` passes (ESP32-S3 firmware)
+- [x] Commit to `feature/price-discovery` branch
+- [x] Hardware flash + integration test on Board B (`test-market`: 4 passed, 0 failed)
+- [x] Hardware flash + integration test on Board A (`test-market`: 4 passed, 0 failed)
+- [ ] Two-board price discovery test (`test-price-discovery`) — blocked by WiFi STA issue (reason=211 NO_AP_FOUND)
+- [ ] Merge to master
+
+## Blockers
+
+### WiFi STA Connectivity (reason=211)
+Both boards fail to find `EnterSSID-2.4GHz` during STA scan despite the router being visible from the laptop at 100% signal. Root cause unclear — may be RF/environmental, APSTA co-channel limitation, or ESP32 scan sensitivity issue. Board B obtained STA IP once during testing, proving the firmware code is correct. See `SESSION_NOTES.md` for detailed analysis.
+
+### Multi-Session Hardware Conflict
+Other LLM sessions (`esp32-tollgate`, `esp32-tollgate-arch`, `esp32-tollgate-display`) flash boards concurrently without respecting the lock system, overwriting our firmware within seconds of flashing.