Proposal: Add Optional BLE Connection Parameter Management (MGMT/HCI) to habluetooth

[philbert]

Some BLE devices require specific connection parameters (interval, latency, supervision timeout) to behave reliably—for example faster notifications, reduced lag, or more stable presence detection. BlueZ does support updating these parameters via the Linux kernel’s HCI Management (MGMT) interface, which tools like btmgmt already use.

Bleak, however, has confirmed that bypassing the D-Bus/bluetoothd layer to call MGMT directly is out of scope for the library (hbldh/bleak#1446). BlueZ currently exposes no D-Bus API for connection parameter updates, so Bleak cannot support this feature natively. This opens a possibility for Home Assistant’s Bluetooth stack to provide this functionality instead.

Problem Statement

Certain integrations (e.g., locks, sensors, high-frequency notification devices, presence detectors) benefit significantly from tuning BLE connection parameters. Without this, Home Assistant may experience:

• Slow notification delivery
• Higher latency on characteristic subscriptions
• Less responsive device interaction
• Suboptimal power/performance trade-offs depending on device type

Home Assistant currently relies entirely on Bleak for BLE interactions, and Bleak cannot expose connection parameter control because of its cross-platform API constraints.

Proposed Solution

Introduce an optional, Linux-only connection parameter manager inside habluetooth that:

1. Applies BLE connection parameters using the kernel MGMT API
   • Opens the MGMT socket
   • Sends “Set Connection Parameters” for the active connection
   • Mirrors how btmgmt handles this
   • Degrades to no-op if permissions (e.g., CAP_NET_ADMIN) are not available
2. Supports predefined “policies”
   Example:
   • fastest_response
   • responsive
   • balanced
   • slow_updates
   • lowest_power
     These map to specific interval/latency/timeout combinations for clarity.
3. Integrates with existing HA Bluetooth connection flow
   • Apply policy immediately after establishing a BLE connection
   • Log results for debugging
   • No changes required in Bleak itself
4. Platform behavior
   • Linux (HA OS / Supervisor / containers): Full MGMT support
   • macOS / Windows: Graceful no-op
   • Keeps HA cross-platform consistent while enabling an optional enhancement where supported

If this proposal aligns with HA’s direction, I’m happy to prepare an initial PR or RFC-style design.

[bdraco]

Also we should look at what ESP-IDF supports since the ESPHome use case is where more and more are going

https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/bluetooth/esp_gap_ble.html#_CPPv428esp_ble_conn_update_params_t

https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/bluetooth/esp_gap_ble.html#_CPPv430esp_ble_gap_update_conn_paramsP28esp_ble_conn_update_params_t

We likely need to make these kwargs to a client.update_connection_params()

Public Members

esp_bd_addr_t bda
Bluetooth device address

uint16_t min_int
Min connection interval

uint16_t max_int
Max connection interval

uint16_t latency
Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3

uint16_t timeout
Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec Time Range: 100 msec to 32 seconds

[bdraco]

Implementation Plan: BLE Connection Parameter Management

API

# Before connect - stores params to apply during connection
client.set_connection_params(
    min_interval=...,
    max_interval=...,
    latency=...,
    timeout=...,
)

# After connect - updates params on active connection
client.update_connection_params(
    min_interval=...,
    max_interval=...,
    latency=...,
    timeout=...,
)

Parameters (raw values, no presets):

• min_interval / max_interval: units of 1.25ms (range: 6-3200)
• latency: slave latency (range: 0-499)
• timeout: supervision timeout in 10ms units (range: 10-3200)

Changes

Layer 1: habluetooth (BlueZ/Linux)

1. Add load_conn_params_raw() to MGMTBluetoothCtl accepting raw parameters
2. Add set_connection_params() and update_connection_params() to HaBleakClientWrapper
3. Apply stored params during connect() instead of hardcoded FAST/MEDIUM

Layer 2: bleak-esphome (ESPHome proxies)

1. Add set_connection_params() and update_connection_params() to ESPHomeClient
2. New feature flag: BluetoothProxyFeature.CONNECTION_PARAMS
3. Graceful no-op if ESPHome firmware doesn't support it

Layer 3: aioesphomeapi

1. Add bluetooth_device_update_connection_params() API call
2. Add protobuf messages for connection param requests

Layer 4: ESPHome firmware

1. set_connection_params → esp_ble_gap_set_prefer_conn_params() (before connect)
2. update_connection_params → esp_ble_gap_update_conn_params() (after connect)
3. Expose via Bluetooth proxy API

Layer 5: bleak-retry-connector

1. Add stub methods to BleakClientWithServiceCache (no-op, for API discoverability)

Behavior

• BlueZ: Uses MGMT socket, requires CAP_NET_ADMIN
• ESPHome: Uses ESP-IDF API via proxy protocol
• Other platforms: Graceful no-op
• If no params set, current FAST→MEDIUM behavior preserved (BlueZ only)

[philbert]

Ultimately, I want to configure different connection policies, or even specific connection values for different devices (my primary use case is for my Yale door locks).

When I think through the UX side of things, I can envisage two ways that users can configure the connections.

1. via configuration.yaml
2. via the UI if implemented by an integration which includes the device.

In the configuration.yaml I can see this kind of thing (functions for all bluetooth peripherals):

bluetooth_device:
  - address: "AA:BB:CC:DD:EE:FF"
    connection_params:
      min_interval: 15
      max_interval: 40
      latency: 0
      timeout: 400

or this:

bluetooth_device:
  - address: "AA:BB:CC:DD:EE:FF"
    connection_policy: responsive

A potential (and likely) error that a user could make here is that they add a mac address of a device which is either not a bluetooth device or not a bluetooth peripheral, in which case we can just log the error and ignore the configuration.

The connection policies that I previously implemented in bleak (untested guesstimations) were as follows:

   - FASTEST_RESPONSE:
     - min_interval_ms: 15
     - max_interval_ms: 30
     - latency: 0
     - supervision_timeout_ms: 4000
   - RESPONSIVE:
     - min_interval_ms: 30
     - max_interval_ms: 50
     - latency: 0
     - supervision_timeout_ms: 5000
   - BALANCED:
     - min_interval_ms: 50
     - max_interval_ms: 100
     - latency: 1
     - supervision_timeout_ms: 6000
   - SLOW_UPDATES:
     - min_interval_ms: 100
     - max_interval_ms: 200
     - latency: 4
     - supervision_timeout_ms: 7000
   - LOWEST_POWER:
     - min_interval_ms: 200
     - max_interval_ms: 1000
     - latency: 8
     - supervision_timeout_ms: 8000

If it was important enough for an integration to support connection policies (e.g. yalexs_ble), then it could simply be done via an input_select entity based on the policy name, which would likely be sufficient for most users.

Is this an acceptable approach?

[bdraco]

I think the discussion on how to implement it per integration / HA is separate from the implementation details above.

For yalexs-ble I think the answer is simple. When always connected is on set it to the minimum levels to reduce battery drain that the lock will support.

In general HA does not add new YAML config these days except for debugging or very advanced features. In this case I think all users would want to save battery life.

Additionally users will have no idea what connection params are so we should avoid exposing them to the implementation details

[philbert]

I think the discussion on how to implement it per integration / HA is separate from the implementation details above.

Agreed. I brought it up because it helps me think through the design and how all the different pieces relate to each other.

In general HA does not add new YAML config these days except for debugging or very advanced features.

I was afraid you would say that. Not hard to understand why.

For yalexs-ble I think the answer is simple. When always connected is on set it to the minimum levels to reduce battery drain that the lock will support.

I have completely over-invested in x7 Yale MD-04I locks and created this problem for myself. Now that I'm middle-aged I've come to terms acknowledging that, "I'm the weird one." So my own use case may very well be an edge case because I want to have at least two different connection policies for the locks on my house versus the ones on my garage.

As awesome as it would be to have a central/integration-agnostic level in the configuration.yaml to set these connection policies for individual devices, if that is off the table and since this is an "opt-in" only feature, then it's up to every integration to implement it, however the maintainers wish to implement it.

When it comes to yalexs_ble, since I want device-level control, I would be happy to add this feature as a disabled/hidden entity with a default value so that users, like me, who wish to set their own connection policy can do so.

Let's agree that we are arguing about the color of the bike shed here, but I would not not assume that lowest power would be correct default for yalexs_ble. Since the 1950 users of the integration have so far been putting up with connections in the realm of "fastest response", they might be a bit shocked if after some future upgrade it takes 2-3 seconds for the door to unlock when previously it was almost immediate. I would not be surprised at all to learn that some people have chucked the batteries and hard-wired their Yale locks to a 12V power supply.

Additionally users will have no idea what connection params are so we should avoid exposing them to the implementation details

I spent a long time coming up with what I thought are pretty intuitive names for the policies! (what the values are inside is a separate discussion)

[bdraco]

this is an "opt-in" only feature, then it's up to every integration to implement it, however the maintainers wish to implement it.

The vast majority of devices have better designs where they signal state updates in advertising data (or have the actual update in the advertising) and don't require connections 99% of their lifecycle so it really should be up to the integration to decide what is best.

The config entry options could have a selector under the always connected option to select some predefined params for yalexs-ble.