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, 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 three caller responsibilities (scanner setup, 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. Calling ESPHomeClientData.disconnect_callbacks when the ESP is disconnected.

3. Registering the scanner with the HA Bluetooth manager and also un-registering it 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