Python Client for ESPHome native API. Used by Home Assistant.
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
github-actions[bot] 5ebd8956ec Bump version to 13.5.2 6 days ago
.devcontainer Update vscode files (#379) 1 month ago
.github Bump docker/setup-buildx-action from 2.4.1 to 2.5.0 (#403) 1 week ago
.vscode Update vscode files (#379) 1 month ago
aioesphomeapi Remove unused lock from frame helper (#406) 6 days ago
script Protobuf version upgrades (#307) 4 months ago
tests Cooldown before reconnecting on expected disconnect (#397) 2 weeks ago
.dockerignore Build docker image to generate protoc (#72) 2 years ago
.gitignore Add vscode task to Generate files (#305) 4 months ago
Dockerfile Protobuf version upgrades (#307) 4 months ago
LICENSE Initial commit 4 years ago Rename master branch to main (#58) 2 years ago Implement PEP561 typing support (#55) 2 years ago
README.rst Remove loop argument (#155) 1 year ago
mypy.ini Bump min python to 3.9 (#265) 6 months ago
pyproject.toml Refactor Lint Configs (#53) 2 years ago
requirements.txt Protobuf version upgrades (#307) 4 months ago
requirements_test.txt Bump pylint from 2.16.3 to 2.17.0 (#402) 1 week ago
setup.cfg Add flake8, black, isort and mypy linting (#39) 2 years ago Bump version to 13.5.2 6 days ago



``aioesphomeapi`` allows you to interact with devices flashed with `ESPHome <>`_.


The module is available from the `Python Package Index <>`_.

.. code:: bash

    $ pip3 install aioesphomeapi


It's required that you enable the `Native API <>`_ component for the device.

.. code:: yaml

   # Example configuration entry
     password: 'MyPassword'

Check the output to get the local address of the device or use the ``name:``under ``esphome:`` from the device configuration.

.. code:: bash

   [17:56:38][C][api:095]: API Server:
   [17:56:38][C][api:096]:   Address: api_test.local:6053

The sample code below will connect to the device and retrieve details.

.. code:: python

   import aioesphomeapi
   import asyncio
   async def main():
       """Connect to an ESPHome device and get details."""

       # Establish connection 
       api = aioesphomeapi.APIClient("api_test.local", 6053, "MyPassword")
       await api.connect(login=True)
       # Get API version of the device's firmware
       # Show device details
       device_info = await api.device_info()
       # List all entities of the device
       entities = await api.list_entities_services()
    loop = asyncio.get_event_loop()

Subscribe to state changes of an ESPHome device.

.. code:: python

   import aioesphomeapi
   import asyncio
   async def main():
       """Connect to an ESPHome device and wait for state changes."""
       cli = aioesphomeapi.APIClient("api_test.local", 6053, "MyPassword")
       await cli.connect(login=True)

       def change_callback(state):
           """Print the state changes of the device.."""
       # Subscribe to the state changes
       await cli.subscribe_states(change_callback)
   loop = asyncio.get_event_loop()
   except KeyboardInterrupt:

Other examples:

- `Camera <>`_
- `Async print <>`_
- `Simple print <>`_
- `InfluxDB <>`_


For development is recommended to use a Python virtual environment (``venv``).

.. code:: bash

    # Setup virtualenv (optional)
    $ python3 -m venv .
    $ source bin/activate
    # Install aioesphomeapi and development depenencies
    $ pip3 install -e .
    $ pip3 install -r requirements_test.txt

    # Run linters & test
    $ script/lint
    # Update protobuf definitions (requires a protobuf compiler installation)
    $ script/gen-protoc


``aioesphomeapi`` is licensed under MIT, for more details check LICENSE.