# ESPHome BLE proxy — Bermuda's radios (Phase 2)

Plain ESPHome config wrapping ESPHome's own first-party `bluetooth_proxy`
component — this is the hardware Bermuda (HACS) and HA's Private BLE Device use to
actually see BLE advertisements and resolve them into room-level presence. It is
**not** RuView (`firmware/ruview/`) — separate hardware, separate job, see that
directory's own README for why CSI presence sensing is a fundamentally different
(and much higher-risk-to-fabricate) kind of firmware than this one.

## Why this one is safe to just write, unlike RuView

`bluetooth_proxy` is a stock, actively-maintained ESPHome component with a
documented, stable config schema — there is no custom signal-processing, no
hardware-specific register-level bring-up, no invented protocol here. The only
real per-unit decision is `room` (`ble-proxy.yaml`'s substitutions). This is the
same category of "safe to build directly" as this project's other plain ESPHome
usage (the BLE proxy pattern is explicitly the "separate hardware from RuView"
half of `docs/project-plan.md` §1.5), unlike RuView's CSI DSP work.

## Flash it

1. Install [ESPHome](https://esphome.io/) (CLI or the dashboard add-on/container —
   this repo doesn't bundle a specific install method, use whichever you already
   use for other ESPHome devices).
2. `cp secrets.yaml.example secrets.yaml` in this directory, fill in your Wi-Fi
   credentials and generate an `api_encryption_key` (command in the file).
3. Edit `ble-proxy.yaml`'s `substitutions.room`/`friendly_name` for this specific
   unit — every proxy needs a distinct name so HA (and Bermuda's triangulation,
   which deliberately uses ALL proxies' RSSI readings together, not just the
   nearest one) can tell them apart.
4. `esphome run ble-proxy.yaml` over USB for the first flash; OTA (the `ota:`
   block) works for every flash after that.
5. Repeat steps 3–4 per room needing BLE presence coverage — §1.5 suggests one
   per room, same density as RuView's own per-room CSI nodes.

## What you still have to do in Home Assistant — this repo doesn't build the HA side

Same convention as every other "nothing under this repo builds the HA side" entry
in `docs/project-plan.md` §2 (UniFi, CalDAV, Matter, ...):

1. **Bermuda** (HACS integration) — install it, it auto-discovers ESPHome
   Bluetooth proxies on the network via HA's native `esphome` integration once
   this firmware is flashed and online; no manual proxy registration needed
   beyond that.
2. **Private BLE Device** (HA core integration) — set up per phone, using each
   phone's actual IRK (iOS: requires pairing the phone as a bookmark in the
   Apple/Google "Find My"-style private-address rotation scheme via HA's own
   guided flow; Android: similar, see HA's own Private BLE Device docs). This is
   what turns a rotating randomized MAC into a stable `person.*`-trackable
   device — without it, Bermuda sees BLE adverts but can't attribute them to a
   specific phone reliably.
3. Once both are set up, `identity`'s `TRUSTED_ENTITY_PREFIXES` env var (see
   `identity/README.md`) needs to match whatever entity ID pattern Private BLE
   Device / your fixed-MAC BLE tags actually create — **this is flagged as the
   single highest-risk unverified assumption in Phase 6** (`docs/project-plan.md`
   open decision #20) precisely because steps 1–2 above have never been run
   against a real HA instance from within this project.

## Manual verification still outstanding

1. `esp32dev` as the board id is a generic fallback for "D1 Mini32 or similar"
   (§1.5) — if your actual board has its own more specific ESPHome board id, use
   that instead; a wrong-but-pin-compatible generic id usually still works, but
   isn't guaranteed to for every board variant.
2. `esp-idf` vs. Arduino framework for `bluetooth_proxy`/`esp32_ble_tracker` — see
   `ble-proxy.yaml`'s own VERIFY comment; check your ESPHome version's release
   notes/docs if you'd rather use Arduino.
3. Never flashed to real hardware or run against a real Bermuda install — this
   config passes ESPHome's own config validator (`esphome config ble-proxy.yaml`)
   but nothing further.