71 lines
4.1 KiB
Markdown
71 lines
4.1 KiB
Markdown
# 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.
|