Python Client for ESPHome native API. Used by Home Assistant.
Go to file
J. Nick Koston 96b75c5337
Avoid a jump to the executor to unpack an ip address string (#26)
Avoids executor overload on Home Assistant startup

2021-02-13 18:31:38 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.211.201', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.210.102', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.211.180', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.210.100', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.214.225', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.213.240', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.213.168', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.210.29', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.209.89', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.209.250', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.214.56', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:31:51 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.209.137', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:32:04 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.209.89', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:32:14 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.209.89', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:32:23 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.209.89', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:32:58 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.209.89', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:33:10 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.209.89', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-13 18:33:19 DEBUG (MainThread) [homeassistant.runner] Calling executor with function: <function getaddrinfo at 0x7f00184c8ca0>, args: ('10.45.209.89', 6053, <AddressFamily.AF_INET: 2>, 0, 6, 0), kwargs: {}
2021-02-15 11:58:11 -03:00
.github Fix typo (#23) 2020-12-22 16:45:02 -03:00
aioesphomeapi Avoid a jump to the executor to unpack an ip address string (#26) 2021-02-15 11:58:11 -03:00
.gitignore Initial commit 2018-12-13 21:34:57 +01:00
gen-protoc.sh Add climate feature fan (#4) 2019-11-16 16:34:14 +01:00
LICENSE Initial commit 2018-12-13 21:34:57 +01:00
MANIFEST.in Fix sdist requirements.txt missing (#17) 2020-09-15 17:16:23 +02:00
pylintrc Unpin pylint (#22) 2020-12-14 00:16:58 -03:00
README.rst Fix example code indentation in READMY.rst (#18) 2020-12-22 16:45:32 -03:00
requirements_test.txt Unpin pylint (#22) 2020-12-14 00:16:58 -03:00
requirements.txt Load requirements from requirements.txt 2020-07-15 13:41:55 +02:00
setup.py Bump version to 2.6.4 2020-12-14 00:30:48 -03:00

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

``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

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."""
       loop = asyncio.get_running_loop()
   
       # Establish connection 
       api = aioesphomeapi.APIClient(loop, "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."""
       loop = asyncio.get_running_loop()
       cli = aioesphomeapi.APIClient(loop, "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

    $ python3 -m venv .
    $ source bin/activate
    $ python3 setup.py develop

License
-------

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