Python Client for ESPHome native API. Used by Home Assistant.
Go to file
dependabot[bot] 69f399cca4
Bump types-protobuf from 4.25.0.20240417 to 5.26.0.20240422
Bumps [types-protobuf](https://github.com/python/typeshed) from 4.25.0.20240417 to 5.26.0.20240422.
- [Commits](https://github.com/python/typeshed/commits)

---
updated-dependencies:
- dependency-name: types-protobuf
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
2024-04-22 10:25:21 +00:00
.devcontainer Remove deprecated settings for devcontainer (#857) 2024-04-12 11:29:29 +12:00
.github Use trusted publishing token (#862) 2024-04-17 10:26:39 +12:00
.vscode Update vscode files (#379) 2023-02-09 12:07:36 +13:00
aioesphomeapi Alphabetise model_conversions.py (#864) 2024-04-22 17:04:38 +12:00
bench Fix benchmarks from recent refactoring (#717) 2023-11-25 10:34:29 -06:00
script Update pre-commit with newer tools (#724) 2023-11-26 08:09:52 -06:00
tests Add Datetime entities (#859) 2024-04-22 15:58:16 +12:00
.coveragerc Add discover cli tool (#732) 2023-11-26 11:04:17 -06:00
.dockerignore Build docker image to generate protoc (#72) 2021-07-22 11:35:08 +12:00
.gitignore Gitignore the generated .c files for cython (#832) 2024-02-27 15:52:42 +13:00
.pre-commit-config.yaml Bump black from 23.12.1 to 24.1.1 (#812) 2024-02-04 21:39:47 -06:00
Dockerfile Add esphome user to container (#831) 2024-02-27 15:52:22 +13:00
LICENSE Add basic pre-commit to handle eol space (#592) 2023-10-19 14:00:36 -10:00
MAINTAINERS.md Add basic pre-commit to handle eol space (#592) 2023-10-19 14:00:36 -10:00
MANIFEST.in Exclude .c files from wheel builds (#589) 2023-10-17 18:56:30 -10:00
mypy.ini Move mypy disable for async_timeout to mypy.ini (#593) 2023-10-20 06:25:20 -10:00
pyproject.toml Update pre-commit with newer tools (#724) 2023-11-26 08:09:52 -06:00
README.rst Add discover cli tool (#732) 2023-11-26 11:04:17 -06:00
requirements_test.txt Bump types-protobuf from 4.25.0.20240417 to 5.26.0.20240422 2024-04-22 10:25:21 +00:00
requirements.txt Remove zeroconf listener removal workaround (#860) 2024-04-17 16:18:36 -05:00
setup.cfg Add flake8, black, isort and mypy linting (#39) 2021-06-18 17:57:02 +02:00
setup.py Bump version to 24.2.1 2024-04-22 05:04:53 +00:00

aioesphomeapi
=============

.. image:: https://github.com/esphome/aioesphomeapi/workflows/CI/badge.svg
   :target: https://github.com/esphome/aioesphomeapi?query=workflow%3ACI+branch%3Amain

.. image:: https://img.shields.io/pypi/v/aioesphomeapi.svg
    :target: https://pypi.python.org/pypi/aioesphomeapi

.. image:: https://codecov.io/gh/esphome/aioesphomeapi/branch/main/graph/badge.svg
   :target: https://app.codecov.io/gh/esphome/aioesphomeapi/tree/main

``aioesphomeapi`` allows you to interact with devices flashed with `ESPHome <https://esphome.io/>`_.

Installation
------------

The module is available from the `Python Package Index <https://pypi.python.org/pypi>`_.

.. code:: bash

    $ pip3 install aioesphomeapi

An optional cython extension is available for better performance, and the module will try to build it automatically.

The extension requires a C compiler and Python development headers. The module will fall back to the pure Python implementation if they are unavailable.

Building the extension can be forcefully disabled by setting the environment variable ``SKIP_CYTHON`` to ``1``.

Usage
-----

It's required that you enable the `Native API <https://esphome.io/components/api.html>`_ component for the device.

.. code:: yaml

   # Example configuration entry
   api:
     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
       print(api.api_version)

       # Show device details
       device_info = await api.device_info()
       print(device_info)

       # List all entities of the device
       entities = await api.list_entities_services()
       print(entities)

    loop = asyncio.get_event_loop()
    loop.run_until_complete(main())

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.."""
           print(state)

       # Subscribe to the state changes
       await cli.subscribe_states(change_callback)

   loop = asyncio.get_event_loop()
   try:
       asyncio.ensure_future(main())
       loop.run_forever()
   except KeyboardInterrupt:
       pass
   finally:
       loop.close()

Other examples:

- `Camera <https://gist.github.com/micw/202f9dee5c990f0b0f7e7c36b567d92b>`_
- `Async print <https://gist.github.com/fpletz/d071c72e45d17ba274fd61ca7a465033#file-esphome-print-async-py>`_
- `Simple print <https://gist.github.com/fpletz/d071c72e45d17ba274fd61ca7a465033#file-esphome-print-simple-py>`_
- `InfluxDB <https://gist.github.com/fpletz/d071c72e45d17ba274fd61ca7a465033#file-esphome-sensor-influxdb-py>`_

Development
-----------

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 _pb2.py definitions (requires a protobuf compiler installation)
    $ script/gen-protoc

A cli tool is also available for watching logs:

.. code:: bash

   aioesphomeapi-logs --help

A cli tool is also available to discover devices:

.. code:: bash

   aioesphomeapi-discover

License
-------

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