onlyn00bs-badge

provisioning.md (16503B)

---

 # Provisioning: the web/BLE setup flow
 
 How a blank badge gets a handle. On first boot (or any time you force it) the badge
 comes up as a **BLE GATT peripheral**, a browser talks to it over **Web Bluetooth**,
 and you type the badge's name + a couple of optional extras. The write lands in NVS,
 the badge reboots, and from then on it lives in discovery mode broadcasting that
 handle.
 
 Source of truth:
 [`firmware/src/main.cpp`](../firmware/src/main.cpp) (the `PROVISIONING MODE` block +
 `setup()`), [`firmware/src/config.h`](../firmware/src/config.h) (UUIDs + clamps), and
 the companion app [`provisioning/index.html`](../provisioning/index.html). This doc is
 the *why*; the code is the *what*.
 
 > One radio, never shared. The ESP32 has a single 2.4 GHz radio. Provisioning runs
 > **BLE**; discovery runs **WiFi/ESP-NOW**. The firmware picks exactly one at boot so
 > the two never have to coexist. You provision, the badge reboots, and only then does
 > the ESP-NOW beacon start.
 
 ---
 
 ## The two modes, chosen at boot
 
 ```
   BOOT ─┬─ (no handle stored) OR (BOOT held) OR (one-shot "provreq" flag) ─► PROVISIONING (BLE)
         │        browser writes pairing code → handle (+ clock, + pet) → NVS → reboot
         └─ (handle stored, no override) ──────────────────────────────────► DISCOVERY (ESP-NOW)
 ```
 
 `setup()` resolves the mode. There are **three ways** to land in provisioning — a
 fresh badge, the BOOT button, or a one-shot NVS flag set from the on-device menu
 (`Options → Badge Settings → Developer Options → Provisioning Mode`) so you can re-seed
 without holding a button through a power cycle:
 
 ```cpp
 // firmware/src/main.cpp — setup()
 bool force_provision = (digitalRead(BUTTON_PIN) == LOW) ||       // BOOT held at power-on
                        (prefs.getUChar("provreq", 0) == 1);      // menu → Provisioning Mode
 prefs.putUChar("provreq", 0);                                    // consume the one-shot
 
 String stored   = prefs.getString("handle", "");
 bool have_handle = stored.length() > 0 && !force_provision;
 
 if (!have_handle) { mode = MODE_PROVISION; start_provisioning(); }
 else              { mode = MODE_DISCOVER;  start_discovery();    }
 ```
 
 ---
 
 ## The GATT layout
 
 One custom service, five characteristics — four **write**, plus one **read/notify**
 metrics stream. The UUIDs are shared between firmware and browser —
 they **must** match `config.h` and `index.html` or the browser can't find them.
 
 ```
   service  6e8f0001-…            "badge-setup" provisioning service
     ├─ 0006  CODE   (write)      3-char pairing code   ── GATES everything below
     ├─ 0002  HANDLE (write)      the name your crew sees
     ├─ 0003  TIME   (write)      epoch secs, u32 LE — seed the soft-clock
     ├─ 0004  PET    (write)      custom-avatar blob (name + 5 faces)
     └─ 0005  METRICS(read/notify) framed CSV/TSV dump — pairing-code gated (live, v1.7)
 ```
 
 ```cpp
 // firmware/src/config.h
 #define PROV_SERVICE_UUID    "6e8f0001-b5a3-f393-e0a9-e50e24dcca9e"
 #define PROV_CHAR_UUID       "6e8f0002-b5a3-f393-e0a9-e50e24dcca9e"  // handle (write)
 #define PROV_TIME_CHAR_UUID  "6e8f0003-b5a3-f393-e0a9-e50e24dcca9e"  // epoch secs, u32 LE (write)
 #define PROV_PET_CHAR_UUID   "6e8f0004-b5a3-f393-e0a9-e50e24dcca9e"  // custom pet blob (write)
 #define PROV_CODE_CHAR_UUID  "6e8f0006-b5a3-f393-e0a9-e50e24dcca9e"  // 3-char code — GATES the others
 ```
 
 `start_provisioning()` stands the whole thing up with NimBLE — create the server,
 create the service, attach a callback object per characteristic:
 
 ```cpp
 // firmware/src/main.cpp — start_provisioning()
 NimBLEServer*  server = NimBLEDevice::createServer();
 server->setCallbacks(new ServerCB());
 NimBLEService* svc = server->createService(PROV_SERVICE_UUID);
 
 svc->createCharacteristic(PROV_CODE_CHAR_UUID, NIMBLE_PROPERTY::WRITE)->setCallbacks(new CodeWriteCB());
 svc->createCharacteristic(PROV_CHAR_UUID,      NIMBLE_PROPERTY::WRITE)->setCallbacks(new HandleWriteCB());
 svc->createCharacteristic(PROV_TIME_CHAR_UUID, NIMBLE_PROPERTY::WRITE)->setCallbacks(new TimeWriteCB());
 svc->createCharacteristic(PROV_PET_CHAR_UUID,  NIMBLE_PROPERTY::WRITE)->setCallbacks(new PetWriteCB());
 svc->start();
 ```
 
 ---
 
 ## The pairing-code gate (physical presence, not crypto)
 
 BLE writes are cleartext, so anyone in range could otherwise scribble a handle onto
 any badge in setup mode. The defense is a **fresh 3-char code** shown on the badge's
 own screen each session. The browser must write that code first; until it matches,
 every other write is dropped on the floor.
 
 ```
    ┌─────────────┐        code shown on OLED         ┌──────────┐
    │  badge OLED  │  ── "code: K7Q" ────────────────►│  human   │
    │  SETUP MODE  │                                   │  eyeball │
    └─────────────┘                                   └────┬─────┘
                                                           │ retypes K7Q
                                                           ▼
    handle / time / pet writes  ◄── unlocked only after ── CODE write matches
 ```
 
 The code is drawn from an **unambiguous uppercase alphabet** (no `0/O/1/I/L`) so it's
 easy to read off a tiny mono OLED and retype:
 
 ```cpp
 // firmware/src/main.cpp — a fresh code per provisioning session
 static void gen_prov_code(char out[4]) {
   static const char A[] = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";   // 30 glyphs
   for (int i = 0; i < 3; i++) out[i] = A[esp_random() % (sizeof(A) - 1)];
   out[3] = '\0';
 }
 ```
 
 The gate is a single `volatile bool`. Only an exact (case-insensitive) match flips it:
 
 ```cpp
 // firmware/src/main.cpp — CodeWriteCB::onWrite
 char in[4] = {0};
 for (uint8_t i = 0; i < v.length() && i < 3; i++) {
   char ch = (char)v.data()[i];
   in[i] = (ch >= 'a' && ch <= 'z') ? (char)(ch - 32) : ch;   // uppercase
 }
 g_prov_authed = (strcmp(in, g_prov_code) == 0);
 ```
 
 Every other callback opens with the same guard, so an unauthorized write is a no-op:
 
 ```cpp
 // firmware/src/main.cpp — HandleWriteCB::onWrite (TimeWriteCB / PetWriteCB are identical)
 void onWrite(NimBLECharacteristic* c, NimBLEConnInfo&) override {
   if (!g_prov_authed) { Serial.println("[PROV] handle write ignored — pairing code not accepted"); return; }
   NimBLEAttValue v = c->getValue();
   char clean[HANDLE_MAX_LEN + 1];
   uint8_t len = sanitize_handle(v.data(), v.length(), clean);
   if (len == 0) return;                       // ignore empty/garbage writes
   prefs.putString("handle", clean);
   g_saved = true;                             // loop() will reboot us
 }
 ```
 
 And the auth flag resets on every disconnect, so a new connection must re-send the
 code — you can't authorize once and let a second client ride the same session:
 
 ```cpp
 // firmware/src/main.cpp — ServerCB
 void onDisconnect(NimBLEServer*, NimBLEConnInfo&, int) override {
   g_prov_authed = false;                      // each new connection must re-send the code
   NimBLEDevice::startAdvertising();           // allow repeated attempts
 }
 ```
 
 > **What it is / isn't.** The code proves *line-of-sight to the screen* — a
 > physical-presence gate against drive-by BLE provisioning. It is **not** crypto:
 > BLE writes are still cleartext, so someone who can *see your screen* (or shoulder-surf
 > the code) could provision your badge. That's an acceptable threat model for a con
 > badge — the real beacon-authenticity guarantees live in the HMAC layer
 > ([`docs/hmac-beacon-auth.md`](hmac-beacon-auth.md)), not here.
 >
 > **What the code protects.** The read/notify metrics stream (above) is behind the same
 > code, so a matched code also dumps the owner's **encounter log**, not just the ability to
 > rename the badge. Guessing is bounded: repeated wrong codes latch the gate shut until a
 > reboot, which needs physical access. The 3-char code (27,000 keyspace) proves
 > *presence*, not secrecy.
 
 ---
 
 ## Advertising: why the name lives in the scan response
 
 The badge advertises as `badge-setup-<full 6-byte MAC>` (e.g.
 `badge-setup-14335C591858`) so multiple badges in setup mode are distinguishable in
 the browser's device picker and map 1:1 to the bench roster (which dedups by MAC).
 
 That 24-char name is the catch. A legacy BLE advertisement is only 31 bytes, and the
 128-bit service UUID (18 B) + flags (3 B) already eat 21 of them — the name won't
 fit alongside. So the firmware builds **both packets explicitly**: the primary
 advertisement carries flags + the service UUID (so the browser's service filter can
 find it), and the **scan response** carries the full name *alone* in its own 31 B:
 
 ```cpp
 // firmware/src/main.cpp — start_provisioning()
 NimBLEAdvertisementData advData;                 // PRIMARY: flags + service filter
 advData.setFlags(BLE_HS_ADV_F_DISC_GEN | BLE_HS_ADV_F_BREDR_UNSUP);
 advData.addServiceUUID(PROV_SERVICE_UUID);
 adv->setAdvertisementData(advData);
 
 NimBLEAdvertisementData scanData;                // SCAN RESPONSE: full name, alone
 scanData.setName(prov_name);
 adv->setScanResponseData(scanData);
 adv->enableScanResponse(true);
 adv->start();
 ```
 
 Letting NimBLE auto-route the name truncated it to an 11-char *Shortened Local Name*
 (`badge-setup`), which killed the per-badge MAC suffix — hence the manual split.
 
 ---
 
 ## The browser side (Web Bluetooth)
 
 The companion app is a single static [`provisioning/index.html`](../provisioning/index.html)
 — no build step, no dependencies. It needs **Chrome or Edge** (Web Bluetooth isn't
 in Firefox/Safari) served over **https or localhost** (Web Bluetooth is a secure
 context). Its UUID constants mirror `config.h`:
 
 ```js
 // provisioning/index.html — must match firmware/src/config.h
 const SERVICE_UUID = "6e8f0001-b5a3-f393-e0a9-e50e24dcca9e";
 const CHAR_UUID    = "6e8f0002-b5a3-f393-e0a9-e50e24dcca9e";   // handle
 const TIME_UUID    = "6e8f0003-b5a3-f393-e0a9-e50e24dcca9e";   // clock sync
 const PET_UUID     = "6e8f0004-b5a3-f393-e0a9-e50e24dcca9e";   // custom pet
 const CODE_UUID    = "6e8f0006-b5a3-f393-e0a9-e50e24dcca9e";   // pairing code (gates the others)
 ```
 
 **Connect** — `requestDevice` pops the OS chooser, filtered to our service and
 name prefix, then resolves the primary service:
 
 ```js
 // provisioning/index.html — connect()
 const device = await navigator.bluetooth.requestDevice({
   filters: [{ services: [SERVICE_UUID] }, { namePrefix: DEVICE_NAME }],
   optionalServices: [SERVICE_UUID]
 });
 const server = await device.gatt.connect();
 return { device, service: await server.getPrimaryService(SERVICE_UUID) };
 ```
 
 **Code first, every time** — because the badge resets its auth flag on each new
 connection, the app writes the code immediately after connecting for *every* action
 (save / sync / pet):
 
 ```js
 // provisioning/index.html — writeCode()
 const code = ($("code").value || "").trim().toUpperCase();
 if (code.length !== 3) throw new Error("enter the 3-char pairing code shown on the badge");
 const cch = await service.getCharacteristic(CODE_UUID);
 await cch.writeValue(new TextEncoder().encode(code));
 ```
 
 **The main flow** — connect → code → handle → (best-effort) clock → disconnect:
 
 ```js
 // provisioning/index.html — provision()
 const { device, service } = await connect();
 await writeCode(service);                                    // unlock
 const ch = await service.getCharacteristic(CHAR_UUID);
 await ch.writeValue(new TextEncoder().encode(handle).slice(0, MAX_LEN));
 try { await writeTime(service); } catch (_) { /* time char optional */ }
 device.gatt.disconnect();
 ```
 
 The handle input is clamped to printable ASCII and 24 bytes **in the browser**, and
 the firmware re-clamps with `sanitize_handle()` on arrival — never trust the client.
 
 ---
 
 ## The optional writes
 
 **Clock sync** — the phone/laptop knows real wall-clock time; the badge doesn't. The
 app writes the current epoch as a little-endian `u32` so the con report can show real
 timestamps. There's also a **`sync clock only`** button that skips the handle write
 entirely (re-sync after a battery swap without renaming):
 
 ```js
 // provisioning/index.html — writeTime()
 const tb = new Uint8Array(4);
 new DataView(tb.buffer).setUint32(0, Math.floor(Date.now() / 1000), true);   // LE u32 epoch
 await (await service.getCharacteristic(TIME_UUID)).writeValue(tb);
 ```
 
 ```cpp
 // firmware/src/main.cpp — TimeWriteCB::onWrite (guard omitted)
 uint32_t epoch = (uint32_t)d[0] | ((uint32_t)d[1] << 8) |
                  ((uint32_t)d[2] << 16) | ((uint32_t)d[3] << 24);
 g_clock.set(epoch);
 // re-sync on an already-named badge reboots to home; first-time setup waits for the handle write
 if (prefs.getString("handle", "").length() > 0) g_saved = true;
 ```
 
 **Custom pet** — an optional blob of `name` + 5 state faces (idle / contact /
 milestone / lonely / low-batt), newline-separated. The browser joins the fields; the
 firmware splits on `\n`, clamps each field to printable ASCII + its max length, stores
 it to NVS slot `PET_BUILTIN_N`, and auto-selects it. The pet model itself is in
 `firmware/src/pet.h`.
 
 ```js
 // provisioning/index.html — writePet()
 const blob = [f("pet_name"), f("pet_idle"), f("pet_contact"),
               f("pet_milestone"), f("pet_lonely"), f("pet_lowbatt")].join("\n");
 await (await service.getCharacteristic(PET_UUID)).writeValue(new TextEncoder().encode(blob));
 ```
 
 ---
 
 ## Commit: the reboot handshake
 
 Callbacks run on the BLE stack task; they don't reboot inline. Instead the write that
 completes provisioning sets a `volatile bool g_saved`, and the main `loop()` — which
 in provisioning mode does nothing but poll that flag — performs the restart. That
 guarantees the NVS write is flushed and the BLE client sees its write-response before
 the radio drops:
 
 ```cpp
 // firmware/src/main.cpp — loop()
 if (mode == MODE_PROVISION) {
   if (g_saved) {
     display_boot("saved — rebooting to home");
     delay(800);
     ESP.restart();                    // comes back up in DISCOVERY with the new handle
   }
   delay(50);
   return;
 }
 ```
 
 Full round-trip:
 
 ```
   browser                         badge (BLE peripheral)
   ───────                         ──────────────────────
   requestDevice / connect  ──────►  advertising as badge-setup-<MAC>
   write CODE "K7Q"         ──────►  CodeWriteCB → g_prov_authed = true
   write HANDLE "crash…"    ──────►  HandleWriteCB → sanitize → NVS → g_saved = true
   write TIME <epoch>       ──────►  TimeWriteCB → g_clock.set()
   gatt.disconnect()        ──────►  ServerCB::onDisconnect → g_prov_authed = false
                                     loop() sees g_saved → ESP.restart()
                                     ↳ reboots into DISCOVERY, beaconing "crash…"
 ```
 
 ---
 
 ## Onboard metrics export
 
 The fifth characteristic (`PROV_METRICS_CHAR_UUID`, read/notify) streams a framed
 CSV/TSV dump to the browser: the **encounter log** (`/encounters.log`) + **points
 history** (`/points_history.csv`) + the **best-friends ledger** (`/best_friends.csv`),
 plus the Test-Mode CSVs (`/test_batt.csv`, `/test_pts.csv`) when Debug is on. It is
 **gated by the pairing code** — the badge won't stream until the code matches — chunked
 to the negotiated MTU, and the page reassembles the notify chunks up to an
 `==== EOF ====` sentinel, then the badge auto-reboots to discovery a few seconds later.
 
 Firmware: `stream_metrics()` in `main.cpp` (runs from `loop()`, never a BLE callback);
 served by the characteristic created in `start_provisioning()`. Browser:
 `fetchMetricsOverBle()` in `index.html` renders inline-SVG charts (friends ranking ·
 best friends · points over time) and offers **PDF** (print-to-PDF) and re-importable
 **JSON** export, all from one in-memory `g_data`.
 
 > **Export regularly over a long con:** the encounter log is size-capped
 > (`ENC_LOG_MAX_BYTES` in `config.h`) and trims its oldest entries once it's full, so a
 > daily JSON export keeps the whole history.
 
 ---
 
 ## Related docs
 
 - [`docs/hmac-beacon-auth.md`](hmac-beacon-auth.md) — beacon authenticity in discovery mode (the actual crypto)
 - `firmware/src/clock.h` — the soft-clock the TIME write seeds
 - `firmware/src/pet.h` — the custom-pet model the PET write feeds