API reference

Auto-generated reference for the public surface of bleak_esphome — the four names exported from the top-level package. For how these pieces fit together, see the architecture overview; for task-oriented examples, see usage.

Everything documented here is re-exported from bleak_esphome directly (the one exception, async_set_unavailable, is reached through client_data.bluetooth_device), so the import you write in application code is, for example:

from bleak_esphome import APIConnectionManager, ESPHomeDeviceConfig

High-level entry point

APIConnectionManager is the standalone, Home-Assistant-free way to drive a Bluetooth proxy: hand it a device config, await start(), and it owns the APIClient, reconnect logic, and scanner registration for you.

class bleak_esphome.APIConnectionManager(config)

Manager for the API connection to an ESPHome device.

Parameters:

config (ESPHomeDeviceConfig)

async start()

Start the API connection and wait for the first successful connect.

Constructs the APIClient and ReconnectLogic on first call so no event loop work happens at __init__ time. Returns once _on_connect has fired (scanner registered, disconnect_callbacks captured). If stop() is called before the first connect completes, the awaiting task is unblocked with ESPHomeStartAborted rather than a bare CancelledError so it does not surface as a spurious cancellation in TaskGroup or asyncio.timeout contexts.

Call once per manager instance; a second call raises RuntimeError to prevent leaking the prior APIClient / ReconnectLogic (and its background reconnect task) by overwriting them.

Raises:

• ESPHomeStartAborted – if stop() is called before the first successful connect.

• RuntimeError – if start() has already been called.

Return type:

None

async stop()

Stop the API connection.

Return type:

None

class bleak_esphome.ESPHomeDeviceConfig

Configuration for an ESPHome device.

address: str

noise_psk: str | None

exception bleak_esphome.ESPHomeStartAborted

Raised when APIConnectionManager.start() is aborted by stop().

Low-level escape hatch

connect_scanner is for advanced callers that manage their own APIClient lifecycle. It wires an aioesphomeapi.APIClient to an ESPHomeScanner + ESPHomeClient and returns the assembled ESPHomeClientData, but leaves the four caller responsibilities (scanner setup, marking the device unavailable on disconnect, disconnect callbacks, manager registration) up to you — read the docstring carefully before reaching for it.

bleak_esphome.connect_scanner(cli, device_info, available)

Connect scanner.

The caller is responsible for:

1. Calling ESPHomeClientData.scanner.async_setup()

2. Registering the scanner with the HA Bluetooth manager and also un-registering it when the ESP is disconnected.

3. Calling ESPHomeClientData.bluetooth_device.async_set_unavailable() when the ESP is disconnected, before firing the callbacks, so the connector’s can_connect gate closes and slot waiters fail fast.

4. Calling ESPHomeClientData.disconnect_callbacks when the ESP is disconnected.

The caller may choose to override ESPHomeClientData.disconnect_callbacks with its own set. If it does so, it must do so before calling ESPHomeClientData.scanner.async_setup().

Parameters:

• cli (APIClient)

• device_info (DeviceInfo)

• available (bool)

Return type:

ESPHomeClientData

async_set_unavailable lives on the ESPHomeBluetoothDevice returned in client_data.bluetooth_device; it is not a top-level export.

ESPHomeBluetoothDevice.async_set_unavailable()

Mark the proxy unavailable and fail pending slot waiters.

Failing fast lets a parked waiter retry against another proxy instead of sitting out its full timeout. The latch clears on the next slot report; available is not restored by that, so a reusing caller must set it back to True on reconnect, which disarms the fail fast immediately. The free count stays zero until the first slot report. Unanswered-connect streaks are dropped with the rest of the dead session’s state. This method never raises, so teardown paths can call it without guards.

Return type:

None