{"id":15286959,"url":"https://github.com/esphome/aioesphomeapi","last_synced_at":"2026-05-16T01:06:15.505Z","repository":{"id":37863254,"uuid":"161691980","full_name":"esphome/aioesphomeapi","owner":"esphome","description":"Python Client for ESPHome native API. Used by Home Assistant.","archived":false,"fork":false,"pushed_at":"2025-04-04T17:16:29.000Z","size":1895,"stargazers_count":150,"open_issues_count":5,"forks_count":74,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-05T10:01:44.478Z","etag":null,"topics":["asyncio","home-assistant","home-automation","internet-of-things","iot","python"],"latest_commit_sha":null,"homepage":"https://esphome.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esphome.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-13T20:35:02.000Z","updated_at":"2025-04-04T17:16:31.000Z","dependencies_parsed_at":"2023-10-20T17:46:40.374Z","dependency_job_id":"38cafdbd-bc38-4179-8b32-f8bad93aeae7","html_url":"https://github.com/esphome/aioesphomeapi","commit_stats":{"total_commits":1166,"total_committers":39,"mean_commits":"29.897435897435898","dds":0.7058319039451115,"last_synced_commit":"1dbec5e4f19bc99fef10c3b0afb722700ed2dd83"},"previous_names":[],"tags_count":235,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome%2Faioesphomeapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome%2Faioesphomeapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome%2Faioesphomeapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esphome%2Faioesphomeapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esphome","download_url":"https://codeload.github.com/esphome/aioesphomeapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248006874,"owners_count":21032441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","home-assistant","home-automation","internet-of-things","iot","python"],"created_at":"2024-09-30T15:19:26.349Z","updated_at":"2026-02-23T21:27:18.484Z","avatar_url":"https://github.com/esphome.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"aioesphomeapi\n=============\n\n.. image:: https://github.com/esphome/aioesphomeapi/workflows/CI/badge.svg\n   :target: https://github.com/esphome/aioesphomeapi/actions/workflows/ci.yml?query=branch%3Amain\n\n.. image:: https://img.shields.io/pypi/v/aioesphomeapi.svg\n    :target: https://pypi.org/project/aioesphomeapi/\n\n.. image:: https://codecov.io/gh/esphome/aioesphomeapi/branch/main/graph/badge.svg\n   :target: https://app.codecov.io/gh/esphome/aioesphomeapi/tree/main\n\n.. image:: https://img.shields.io/endpoint?url=https://codspeed.io/badge.json\n   :target: https://codspeed.io/esphome/aioesphomeapi\n\n``aioesphomeapi`` allows you to interact with devices flashed with `ESPHome \u003chttps://esphome.io/\u003e`_.\n\nInstallation\n------------\n\nThe module is available from the `Python Package Index \u003chttps://pypi.org/\u003e`_.\n\n.. code:: bash\n\n    $ pip3 install aioesphomeapi\n\nAn optional cython extension is available for better performance, and the module will try to build it automatically.\n\nThe extension requires a C compiler and Python development headers. The module will fall back to the pure Python implementation if they are unavailable.\n\nBuilding the extension can be forcefully disabled by setting the environment variable ``SKIP_CYTHON`` to ``1``.\n\nUsage\n-----\n\nIt's required that you enable the `Native API \u003chttps://esphome.io/components/api/\u003e`_ component for the device.\n\n.. code:: yaml\n\n   # Example configuration entry\n   api:\n\nFor secure communication, use encryption (recommended):\n\n.. code:: yaml\n\n   api:\n     encryption:\n       key: !secret api_encryption_key\n\nGenerate an encryption key with ``openssl rand -base64 32`` or visit https://esphome.io/components/api/\n\n**Note:** Password authentication was removed in ESPHome 2026.1.0. Encryption is optional but recommended for security.\n\nTo connect to older devices still using password authentication:\n\n.. code:: python\n\n   api = aioesphomeapi.APIClient(\"device.local\", 6053, password=\"MyPassword\")\n\nCheck the output to get the local address of the device or use the ``name:`` under ``esphome:`` from the device configuration.\n\n.. code:: bash\n\n   [17:56:38][C][api:095]: API Server:\n   [17:56:38][C][api:096]:   Address: api_test.local:6053\n\n\nThe sample code below will connect to the device and retrieve details.\n\n.. code:: python\n\n   import aioesphomeapi\n   import asyncio\n\n   async def main():\n       \"\"\"Connect to an ESPHome device and get details.\"\"\"\n\n       # Establish connection\n       api = aioesphomeapi.APIClient(\n           \"api_test.local\",\n           6053,\n           noise_psk=\"YOUR_ENCRYPTION_KEY\",  # Remove if not using encryption\n       )\n       await api.connect(login=True)\n\n       # Get API version of the device's firmware\n       print(api.api_version)\n\n       # Show device details\n       device_info = await api.device_info()\n       print(device_info)\n\n       # List all entities of the device\n       entities = await api.list_entities_services()\n       print(entities)\n\n    loop = asyncio.get_event_loop()\n    loop.run_until_complete(main())\n\nSubscribe to state changes of an ESPHome device.\n\n.. code:: python\n\n   import aioesphomeapi\n   import asyncio\n\n   async def main():\n       \"\"\"Connect to an ESPHome device and wait for state changes.\"\"\"\n       api = aioesphomeapi.APIClient(\n           \"api_test.local\",\n           6053,\n           noise_psk=\"YOUR_ENCRYPTION_KEY\",  # Remove if not using encryption\n       )\n       await api.connect(login=True)\n\n       def change_callback(state):\n           \"\"\"Print the state changes of the device.\"\"\"\n           print(state)\n\n       # Subscribe to the state changes\n       api.subscribe_states(change_callback)\n\n   loop = asyncio.get_event_loop()\n   try:\n       asyncio.ensure_future(main())\n       loop.run_forever()\n   except KeyboardInterrupt:\n       pass\n   finally:\n       loop.close()\n\nOther examples:\n\n- `Camera \u003chttps://gist.github.com/micw/202f9dee5c990f0b0f7e7c36b567d92b\u003e`_\n- `Async print \u003chttps://gist.github.com/fpletz/d071c72e45d17ba274fd61ca7a465033#file-esphome-print-async-py\u003e`_\n- `Simple print \u003chttps://gist.github.com/fpletz/d071c72e45d17ba274fd61ca7a465033#file-esphome-print-simple-py\u003e`_\n- `InfluxDB \u003chttps://gist.github.com/fpletz/d071c72e45d17ba274fd61ca7a465033#file-esphome-sensor-influxdb-py\u003e`_\n\nDevelopment\n-----------\n\nFor development is recommended to use a Python virtual environment (``venv``).\n\n.. code:: bash\n\n    # Setup virtualenv (optional)\n    $ python3 -m venv .\n    $ source bin/activate\n    # Install aioesphomeapi and development depenencies\n    $ pip3 install -e .\n    $ pip3 install -r requirements/test.txt\n\n    # Run linters \u0026 test\n    $ script/lint\n    # Update protobuf _pb2.py definitions (requires docker or podman)\n    $ docker run --rm -v $PWD:/aioesphomeapi ghcr.io/esphome/aioesphomeapi-proto-builder:latest\n    # Or with podman:\n    $ podman run --rm -v $PWD:/aioesphomeapi --userns=keep-id ghcr.io/esphome/aioesphomeapi-proto-builder:latest\n\nA cli tool is also available for watching logs:\n\n.. code:: bash\n\n   aioesphomeapi-logs --help\n\nA cli tool is also available to discover devices:\n\n.. code:: bash\n\n   aioesphomeapi-discover --help\n\n\nLicense\n-------\n\n``aioesphomeapi`` is licensed under MIT, for more details check LICENSE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesphome%2Faioesphomeapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesphome%2Faioesphomeapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesphome%2Faioesphomeapi/lists"}