{"id":4412,"library":"aioesphomeapi","title":"aioesphomeapi","description":"aioesphomeapi is an asynchronous Python API client designed for interacting with devices running ESPHome firmware. It provides a way for Python applications, notably Home Assistant, to communicate with ESPHome devices using their native API for real-time control and monitoring. The library is actively maintained with frequent updates, often aligning with ESPHome and Home Assistant releases. The current version is 44.13.3.","status":"active","version":"44.13.3","language":"en","source_language":"en","source_url":"https://github.com/esphome/aioesphomeapi","tags":["ESPHome","IoT","Home Automation","async","API Client","Home Assistant"],"install":[{"cmd":"pip install aioesphomeapi","lang":"bash","label":"Install stable release"},{"cmd":"pip install aioesphomeapi --prefer-binary","lang":"bash","label":"Install with optional Cython extension for performance (requires C compiler and Python headers)"}],"dependencies":[],"imports":[{"symbol":"APIClient","correct":"from aioesphomeapi import APIClient"},{"note":"Model classes like DeviceInfo are found within the `aioesphomeapi.model` submodule.","wrong":"from aioesphomeapi import DeviceInfo","symbol":"DeviceInfo","correct":"from aioesphomeapi.model import DeviceInfo"}],"quickstart":{"code":"import aioesphomeapi\nimport asyncio\nimport os\n\nasync def main():\n    host = os.environ.get('ESPHOME_HOST', 'device.local')\n    port = int(os.environ.get('ESPHOME_PORT', 6053))\n    noise_psk = os.environ.get('ESPHOME_NOISE_PSK', '') # Recommended for secure communication\n    password = os.environ.get('ESPHOME_PASSWORD', '') # Deprecated, use noise_psk\n\n    if not noise_psk and not password:\n        print(\"Warning: No encryption key or password provided. Connection might fail or be insecure.\")\n\n    # Establish connection\n    api = aioesphomeapi.APIClient(\n        host,\n        port,\n        noise_psk=noise_psk if noise_psk else None,\n        password=password if password else None\n    )\n    \n    try:\n        await api.connect(login=True)\n        print(f\"Successfully connected to {host}:{port}\")\n\n        # Get API version of the device's firmware\n        print(f\"API Version: {api.api_version}\")\n\n        # Show device details\n        device_info = await api.device_info()\n        print(f\"Device Info: {device_info.name} ({device_info.mac_address})\")\n\n        # List all entities of the device\n        entities = await api.list_entities_services()\n        print(f\"Number of entities: {len(entities.entities)}\")\n        # for entity in entities.entities:\n        #     print(f\" - {entity.name} ({entity.key})\")\n\n    except aioesphomeapi.APIConnectionError as e:\n        print(f\"Connection error: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n    finally:\n        if api.is_connected:\n            await api.disconnect()\n            print(\"Disconnected.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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')`.","message":"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.","severity":"breaking","affected_versions":"ESPHome >= 2026.1.0"},{"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`.","message":"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.","severity":"deprecated","affected_versions":"All versions where `password` is used with ESPHome < 2026.1.0"},{"fix":"Add `api:` (or `api: encryption: key: !secret api_encryption_key`) to your ESPHome device's configuration YAML and re-flash the device.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"`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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}