Correct the claim that a Bluetooth proxy is mandatory

The documentation said the host adapter cannot hold this appliance and that
the link would keep dropping no matter what. Measured after bonding with
bluetoothctl, it held for over two hours continuously through the host
adapter, across many address-rotation windows, with every parameter still
arriving.

The drops that produced the original claim were this integration raising an
exception inside its own connection callback, which tore the link down every
two minutes. The measurement that condemned the adapter was measuring a bug.

The narrower claim survives and is what the repair issue now says: a reconnect
after a drop can fail, because the appliance may by then advertise under an
address the host cannot map to the bond. A proxy avoids that and reaches
further, so it stays recommended -- but not on evidence that was never there.

Author: cgehring-blip

README.md

@@ -60,18 +60,29 @@ happen, including changes made at the panel or from the app.
 
 Then **Download**, and restart Home Assistant.
 
-## An ESP32 Bluetooth proxy is required
-
-Not a preference. The appliance advertises under a **fast-rotating Resolvable
-Private Address** and only accepts an encrypted reconnect from a client that
-can resolve that address back to the stored bond. A phone's controller does
-this. **BlueZ does not** — it can pair the appliance, but every later reconnect
-arrives on an address it cannot map to the key, and the link is dropped.
-
-This was established independently and exhaustively by
-[rpodgorny/hass-truma-inetx](https://github.com/rpodgorny/hass-truma-inetx)
-against the same protocol — IRK stored, LL-Privacy enabled, three different
-adapters — and it fails at the controller level regardless.
+## An ESP32 Bluetooth proxy is recommended
+
+The appliance advertises under a **rotating Resolvable Private Address**, and
+an encrypted reconnect is only accepted from a client that can resolve that
+address back to the stored bond. A phone's controller does this in hardware;
+a host adapter running BlueZ may not.
+
+Measured on this system, though: once the appliance was bonded with
+`bluetoothctl`, a connection held through the host adapter ran for **hours at a
+time without a single drop**, across many rotation windows. A held connection
+never has to re-resolve anything, and this integration holds one open.
+
+So the risk is narrower than "it will not work": it is the reconnect after a
+drop, when the appliance may be advertising under an address the host cannot
+map to the bond. [rpodgorny/hass-truma-inetx](https://github.com/rpodgorny/hass-truma-inetx)
+hit exactly that against the same protocol, exhaustively — IRK stored,
+LL-Privacy enabled, three adapters — and concluded a proxy was needed.
+
+An earlier version of this page called the proxy mandatory and blamed BlueZ for
+constant drops. Those drops were this integration crashing in its own
+connection callback. The proxy is still worth having — it reconnects reliably
+and can sit metres from the appliance instead of wherever the server is — but
+the host adapter was not the fault.
 
 ESP-IDF resolves private addresses in the controller the way a phone does, so
 an [ESPHome Bluetooth proxy](https://esphome.io/components/bluetooth_proxy.html)

custom_components/truma_aventa/connectivity.py

@@ -62,8 +62,9 @@ def async_check_proxy(hass: HomeAssistant, entry_id: str, address: str) -> None:
 
     _LOGGER.warning(
         "%s is only reachable through this host's own Bluetooth adapter. "
-        "The appliance rotates its address and the link will keep dropping; "
-        "an ESPHome Bluetooth proxy on an esp-idf build is required",
+        "The appliance rotates its Bluetooth address, which a host adapter "
+        "may not resolve after a drop; an ESPHome Bluetooth proxy on an "
+        "esp-idf build reconnects reliably and reaches further",
         address,
     )
     ir.async_create_issue(

custom_components/truma_aventa/strings.json

@@ -39,8 +39,8 @@
   },
   "issues": {
     "no_bluetooth_proxy": {
-      "title": "Truma Aventa needs a Bluetooth proxy",
-      "description": "{address} can only be reached through this host's own Bluetooth adapter.\n\nThe appliance changes its Bluetooth address between connections and only accepts a reconnect from a client that can resolve that address back to the pairing. Home Assistant's host adapter cannot do this, so the connection will keep dropping no matter how good the signal is.\n\nAn ESPHome Bluetooth proxy built on the esp-idf framework resolves the address the way a phone does. Place one within a few metres of the appliance. The documentation has a ready-made configuration."
+      "title": "Truma Aventa is running without a Bluetooth proxy",
+      "description": "{address} can only be reached through this host's own Bluetooth adapter.\n\nThe appliance changes its Bluetooth address between connections. A held connection is unaffected -- this integration keeps one open, and it has run for hours at a time on a host adapter once the appliance was bonded. What is at risk is reconnecting after a drop: the appliance may by then be advertising under an address the host adapter cannot resolve back to the pairing.\n\nAn ESPHome Bluetooth proxy built on the esp-idf framework resolves that address the way a phone does, and can sit closer to the appliance than the host does. The documentation has a ready-made configuration."
     }
   }
 }

custom_components/truma_aventa/translations/de.json

@@ -39,8 +39,8 @@
   },
   "issues": {
     "no_bluetooth_proxy": {
-      "title": "Truma Aventa braucht einen Bluetooth-Proxy",
-      "description": "{address} ist nur über den Bluetooth-Adapter dieses Hosts erreichbar.\n\nDas Gerät wechselt seine Bluetooth-Adresse zwischen den Verbindungen und akzeptiert einen Reconnect nur von einem Client, der diese Adresse auf die Kopplung zurückführen kann. Der Host-Adapter von Home Assistant kann das nicht — die Verbindung bricht deshalb immer wieder ab, egal wie gut der Empfang ist.\n\nEin ESPHome-Bluetooth-Proxy auf Basis des esp-idf-Frameworks löst die Adresse so auf wie ein Handy. Platziere einen davon wenige Meter von der Anlage entfernt. Die Dokumentation enthält eine fertige Konfiguration."
+      "title": "Truma Aventa läuft ohne Bluetooth-Proxy",
+      "description": "{address} ist nur über den Bluetooth-Adapter dieses Hosts erreichbar.\n\nDas Gerät wechselt seine Bluetooth-Adresse zwischen den Verbindungen. Eine gehaltene Verbindung stört das nicht — diese Integration hält eine offen, und sie lief nach dem Pairing stundenlang am Stück über den Host-Adapter. Kritisch ist der Reconnect nach einem Abbruch: Das Gerät wirbt dann womöglich unter einer Adresse, die der Host-Adapter nicht auf die Kopplung zurückführen kann.\n\nEin ESPHome-Bluetooth-Proxy auf Basis des esp-idf-Frameworks löst diese Adresse so auf wie ein Handy und kann näher an der Anlage sitzen als der Host. Die Dokumentation enthält eine fertige Konfiguration."
     }
   }
 }

custom_components/truma_aventa/translations/en.json

@@ -39,8 +39,8 @@
   },
   "issues": {
     "no_bluetooth_proxy": {
-      "title": "Truma Aventa needs a Bluetooth proxy",
-      "description": "{address} can only be reached through this host's own Bluetooth adapter.\n\nThe appliance changes its Bluetooth address between connections and only accepts a reconnect from a client that can resolve that address back to the pairing. Home Assistant's host adapter cannot do this, so the connection will keep dropping no matter how good the signal is.\n\nAn ESPHome Bluetooth proxy built on the esp-idf framework resolves the address the way a phone does. Place one within a few metres of the appliance. The documentation has a ready-made configuration."
+      "title": "Truma Aventa is running without a Bluetooth proxy",
+      "description": "{address} can only be reached through this host's own Bluetooth adapter.\n\nThe appliance changes its Bluetooth address between connections. A held connection is unaffected -- this integration keeps one open, and it has run for hours at a time on a host adapter once the appliance was bonded. What is at risk is reconnecting after a drop: the appliance may by then be advertising under an address the host adapter cannot resolve back to the pairing.\n\nAn ESPHome Bluetooth proxy built on the esp-idf framework resolves that address the way a phone does, and can sit closer to the appliance than the host does. The documentation has a ready-made configuration."
     }
   }
 }

docs/bluetooth-proxy.md

@@ -1,12 +1,22 @@
 # The Bluetooth proxy
 
-## Why it is mandatory here
+## Why it is recommended here
 
 The appliance advertises under a **rotating Resolvable Private Address** and
 accepts an encrypted reconnect only from a client that can resolve that address
-back to the stored bond. A phone's Bluetooth controller does this. **BlueZ does
-not** — it can complete the pairing, but every later reconnect arrives on an
-address it cannot map to the key, and the link is dropped.
+back to the stored bond. A phone's Bluetooth controller does this in hardware;
+a host adapter running BlueZ may not.
+
+What was actually measured here: after bonding with `bluetoothctl`, a
+connection held through the host adapter ran for hours without dropping,
+through many rotation windows. A held connection never re-resolves anything.
+The exposure is the reconnect after a drop, not the steady state.
+
+This section previously called the proxy mandatory and attributed frequent
+drops to BlueZ. Those drops came from a fault in this integration, which
+crashed inside its own connection callback and tore the link down every two
+minutes. That is worth stating plainly: the measurement that condemned the
+adapter was measuring a bug.
 
 Our own captures show the rotation directly. Across four traces the appliance
 connected under three different addresses:

docs/findings.md

@@ -365,13 +365,26 @@ truncated message then costs itself and nothing after it.
 - Whether `AirCirculation.FanLevel` is the right control while ventilating, or
   whether the app uses `AirCooling.Mode` there too. Only one write was seen.
 
-## A host Bluetooth adapter is not enough
+## A host Bluetooth adapter: what was actually measured
 
 The appliance advertises under a fast-rotating Resolvable Private Address and
 accepts an encrypted reconnect only from a client that can resolve that address
-back to the stored bond. A phone's controller does this; **BlueZ does not**.
-It can complete the pairing, but every later reconnect arrives on an address it
-cannot map to the key and the link is dropped.
+back to the stored bond. A phone's controller does this in hardware; a host
+adapter running BlueZ may not.
+
+**Corrected.** This section used to say the link is dropped on every reconnect
+and that a proxy is mandatory. On this system, after bonding with
+`bluetoothctl`, the link held through the host adapter for over two hours
+continuously — many rotation windows — with every parameter still updating.
+
+The drops that produced the original claim were this integration raising an
+exception inside its connection callback, which tore the link down roughly
+every two minutes. Attributing them to the adapter was a mistake: the
+measurement was of a bug, not of BlueZ.
+
+The narrower claim stands: a *reconnect* after a drop can fail, because the
+appliance may by then advertise under an address the host cannot map to the
+bond, and that is what rpodgorny hit.
 
 This was established independently and exhaustively by
 [rpodgorny/hass-truma-inetx](https://github.com/rpodgorny/hass-truma-inetx)