esphome/README.md

@@ -0,0 +1,37 @@
+# ESPHome device configs
+
+Source-of-truth YAML for ESPHome devices in the homelab. These are built and
+flashed through the **ESPHome Device Builder** running in-cluster at
+<https://esphome.home.renner.uno> (see `kubernetes/apps/home-assistant/esphome-*`
+and the `esphome-gate` Authentik blueprint).
+
+The dashboard reads configs from its own `/config` on the `esphome-data` PVC — it
+does **not** sync from git. So the flow is: edit here → paste/copy into the
+dashboard → compile + flash. Keep the two in sync manually; git is the reviewed,
+backed-up copy.
+
+## Devices
+
+| File | Device | Role |
+|------|--------|------|
+| `shelly-ble-proxy.yaml` | M5 Atom Echo (ESP32-PICO) | Dedicated Bluetooth proxy that lends its BLE radio to shelly-manager's ble-agent for provisioning WiFi-less Shellys over mOS RPC-over-BLE. |
+
+## Secrets
+
+The dashboard's `secrets.yaml` (on the PVC — **not** in git) must define:
+
+```yaml
+iot_wifi_ssid: "<IoT SSID>"
+iot_wifi_password: "<...>"
+shelly_ble_proxy_ap_password: "<recovery AP password, 8+ chars>"
+shelly_ble_proxy_ota_password: "<...>"
+# 32-byte base64 — dashboard "Generate", or: openssl rand -base64 32
+# This value is the handoff to the ble-agent (its BLE_PROXY_NOISE_PSK).
+shelly_ble_proxy_api_key: "<...>"
+```
+
+## Flashing
+
+First flash is browser-side over USB (ESP Web Tools / Web Serial, Chrome/Edge):
+plug the Atom Echo into your computer, open the dashboard, **Install → Plug into
+this computer**. After that, updates are OTA.

esphome/shelly-ble-proxy.yaml

@@ -0,0 +1,62 @@
+# M5 Atom Echo — DEDICATED Bluetooth proxy for shelly-manager BLE provisioning.
+#
+# Source of truth for the device config. Load it into the ESPHome Device Builder
+# (https://esphome.home.renner.uno) — paste as a new device, or keep in sync with
+# the dashboard's /config copy on the esphome-data PVC (the dashboard reads from
+# the PVC, not from git).
+#
+# Intentionally NOT a voice satellite: the mic/speaker/voice_assistant components
+# are omitted. bluetooth_proxy + voice together overflows the ESP32-PICO (no
+# PSRAM) and boot-loops (esphome/issues#6166, #6217). Lean = active BLE
+# connections fit.
+#
+# Role: this proxy lends its BLE radio to shelly-manager's ble-agent, which drives
+# it over the ESPHome native API (aioesphomeapi / bleak-esphome) to provision a
+# WiFi-less Shelly over mOS RPC-over-BLE. Dedicated to the ble-agent — do NOT also
+# adopt it into Home Assistant, or they contend for the few BLE connection slots.
+substitutions:
+  name: shelly-ble-proxy-1
+  friendly_name: Shelly BLE Proxy 1
+
+esphome:
+  name: ${name}
+  friendly_name: ${friendly_name}
+
+esp32:
+  board: m5stack-atom
+  framework:
+    type: esp-idf # required for a stable bluetooth_proxy
+
+logger:
+  level: INFO
+
+# ESPHome native API — how the ble-agent connects. The encryption key is the
+# handoff to the ble-agent (BLE_PROXY_NOISE_PSK there must equal this value).
+api:
+  encryption:
+    key: !secret shelly_ble_proxy_api_key
+
+ota:
+  - platform: esphome
+    password: !secret shelly_ble_proxy_ota_password
+
+wifi:
+  ssid: !secret iot_wifi_ssid
+  password: !secret iot_wifi_password
+  ap: # recovery AP if the IoT WiFi is down at boot
+    ssid: "${friendly_name} Setup"
+    password: !secret shelly_ble_proxy_ap_password
+
+captive_portal:
+
+# Active BLE proxy — enables the GATT connect + characteristic read/write that
+# Shelly's mOS RPC-over-BLE needs to provision a WiFi-less device
+# (WiFi.SetConfig / Mqtt.SetConfig / Shelly.SetAuth). Default 3 connection slots
+# is ample; provisioning is one device at a time. Active scan surfaces the
+# Shelly's advertised name/service so the agent's /scan can filter to it.
+esp32_ble_tracker:
+  scan_parameters:
+    active: true
+
+bluetooth_proxy:
+  active: true