Skip to main content

Python API for interacting with ESPHome devices.

Project description

aioesphomeapi allows you to interact with devices flashed with ESPHome.

Installation

The module is available from the Python Package Index.

$ pip3 install aioesphomeapi

Usage

It’s required that you enable the Native API component for the device.

# 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.

[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.

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.

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:

Development

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

# 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

License

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

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aioesphomeapi-13.5.0.tar.gz (59.0 kB view details)

Uploaded Source

Built Distribution

aioesphomeapi-13.5.0-py2.py3-none-any.whl (54.1 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file aioesphomeapi-13.5.0.tar.gz.

File metadata

  • Download URL: aioesphomeapi-13.5.0.tar.gz
  • Upload date:
  • Size: 59.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.2

File hashes

Hashes for aioesphomeapi-13.5.0.tar.gz
Algorithm Hash digest
SHA256 c0b8745048d45a3056181197ae015775a2f2166b72afd9ab1e4f93489d523d74
MD5 dcb45a8deeb2fefb1e9aadd7f5b154f1
BLAKE2b-256 0ebaef43e009ae0a1f759ebb5fdc2e59253538ae80c13017e3cfa4ad7b81df82

See more details on using hashes here.

File details

Details for the file aioesphomeapi-13.5.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for aioesphomeapi-13.5.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 ff48d842403b2bd334afecc2448fb8b2bbc5830296ed1f7c880c71cb55cb2787
MD5 28e270aae4ac79627fc96438c824ef96
BLAKE2b-256 3596fc92ab792098d9e10a4ac84e330105f8e77c721c9d51c52bea9779f4345a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page