From 04d8485b04ed65cfed9bdbd19db17b1e0267d94d Mon Sep 17 00:00:00 2001
From: Claude Bot <claude-bot@renner.uno>
Date: Mon, 13 Jul 2026 01:11:39 +0200
Subject: [PATCH] feat(esphome): version the Atom Echo Shelly BLE proxy config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Source-of-truth YAML (+ README) for the M5 Atom Echo dedicated Bluetooth proxy
that lends its BLE radio to shelly-manager's ble-agent for provisioning WiFi-less
Shellys over mOS RPC-over-BLE. Built/flashed via the in-cluster ESPHome Device
Builder (esphome.home.renner.uno).

Lean, dedicated config (no voice — bluetooth_proxy + voice boot-loops the
ESP32-PICO), esp-idf framework, bluetooth_proxy active. The api encryption key is
the handoff to the ble-agent (its BLE_PROXY_NOISE_PSK). The dashboard reads from
its PVC, not git, so these files are the reviewed/backed-up copy kept in sync by
hand.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 esphome/README.md             | 37 +++++++++++++++++++++
 esphome/shelly-ble-proxy.yaml | 62 +++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 esphome/README.md
 create mode 100644 esphome/shelly-ble-proxy.yaml

diff --git a/esphome/README.md b/esphome/README.md
new file mode 100644
index 00000000..8400dfb7
--- /dev/null
+++ b/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.
diff --git a/esphome/shelly-ble-proxy.yaml b/esphome/shelly-ble-proxy.yaml
new file mode 100644
index 00000000..06c4575b
--- /dev/null
+++ b/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
-- 
2.54.0