SmartestHome/firmware/esphome-ble-proxy/README.md

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 (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.