aioesphomeapi

Warnings

• breaking Password authentication was removed in ESPHome 2026.1.0. Devices running this version or newer will only accept connections using a `noise_psk` (encryption key). Attempting to connect with only a password will fail.
  Fix: Generate an encryption key (noise_psk) for your ESPHome device and update your client code to use the `noise_psk` argument instead of `password` in `APIClient`. Example: `api = APIClient(host, port, noise_psk='YOUR_ENCRYPTION_KEY')`.
• deprecated The `password` argument in `aioesphomeapi.APIClient` is deprecated. While it still works for older ESPHome devices, it's recommended to switch to `noise_psk` for security and future compatibility.
  Fix: Migrate to using `noise_psk` for authentication. Configure `api: encryption: key: !secret api_encryption_key` in your ESPHome device's YAML configuration and pass the generated key as `noise_psk` to `APIClient`.
• gotcha The ESPHome device *must* have the Native API component enabled in its YAML configuration for `aioesphomeapi` to connect. Without it, the device will not be listening for API connections.
  Fix: Add `api:` (or `api: encryption: key: !secret api_encryption_key`) to your ESPHome device's configuration YAML and re-flash the device.
• gotcha For optimal performance, `aioesphomeapi` can use an optional Cython extension. If this extension cannot be built (e.g., due to missing C compiler or Python development headers), the library will silently fall back to a pure Python implementation, which may be slower.
  Fix: Ensure you have a C compiler (e.g., GCC or Clang) and Python development headers installed on your system. Alternatively, set the environment variable `SKIP_CYTHON=1` to forcefully disable the Cython extension.
• gotcha `aioesphomeapi` uses Protocol Buffers for communication and must be kept consistent with the ESPHome firmware version on your devices. Breaking changes in the ESPHome API protocol require corresponding updates in `aioesphomeapi` to maintain compatibility.
  Fix: Always aim to keep your `aioesphomeapi` library version updated, especially when updating ESPHome firmware on your devices or Home Assistant instances that rely on `aioesphomeapi`.

Install

• pip install aioesphomeapi Install stable release
• pip install aioesphomeapi --prefer-binary Install with optional Cython extension for performance (requires C compiler and Python headers)

Imports

• APIClient

  from aioesphomeapi import APIClient

• DeviceInfo

  from aioesphomeapi.model import DeviceInfo

  Model classes like DeviceInfo are found within the `aioesphomeapi.model` submodule.

Quickstart

This quickstart demonstrates how to connect to an ESPHome device, retrieve its API version, device information, and a list of available entities. It prioritizes using `noise_psk` for secure connections, falling back to an optional password (now deprecated). Ensure the ESPHome device has the Native API enabled in its configuration and provide the correct host, port, and authentication details via environment variables.

import aioesphomeapi
import asyncio
import os

async def main():
    host = os.environ.get('ESPHOME_HOST', 'device.local')
    port = int(os.environ.get('ESPHOME_PORT', 6053))
    noise_psk = os.environ.get('ESPHOME_NOISE_PSK', '') # Recommended for secure communication
    password = os.environ.get('ESPHOME_PASSWORD', '') # Deprecated, use noise_psk

    if not noise_psk and not password:
        print("Warning: No encryption key or password provided. Connection might fail or be insecure.")

    # Establish connection
    api = aioesphomeapi.APIClient(
        host,
        port,
        noise_psk=noise_psk if noise_psk else None,
        password=password if password else None
    )
    
    try:
        await api.connect(login=True)
        print(f"Successfully connected to {host}:{port}")

        # Get API version of the device's firmware
        print(f"API Version: {api.api_version}")

        # Show device details
        device_info = await api.device_info()
        print(f"Device Info: {device_info.name} ({device_info.mac_address})")

        # List all entities of the device
        entities = await api.list_entities_services()
        print(f"Number of entities: {len(entities.entities)}")
        # for entity in entities.entities:
        #     print(f" - {entity.name} ({entity.key})")

    except aioesphomeapi.APIConnectionError as e:
        print(f"Connection error: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")
    finally:
        if api.is_connected:
            await api.disconnect()
            print("Disconnected.")

if __name__ == "__main__":
    asyncio.run(main())