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-11.4.3.tar.gz (57.3 kB view details)

Uploaded Source

Built Distribution

aioesphomeapi-11.4.3-py2.py3-none-any.whl (59.6 kB view details)

Uploaded Python 2 Python 3

File details

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

File metadata

  • Download URL: aioesphomeapi-11.4.3.tar.gz
  • Upload date:
  • Size: 57.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.11.0

File hashes

Hashes for aioesphomeapi-11.4.3.tar.gz
Algorithm Hash digest
SHA256 6f305f7519021a82c7d810692448e176ad0eba2fe09ec9ec611185dc420380fb
MD5 e2d37b5b1818c511703e21857c5e5a64
BLAKE2b-256 60b8ffd58d87ecb7fa18078d30afc9d64dde3d85038be09b552f699d3d040cb5

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-11.4.3-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 732154c2c2bcd3d620ada2b71da0849e510fe6a806a235cfccaafd64c00606bc
MD5 bb46678fdb34cc1b40fdf512e019e710
BLAKE2b-256 b1ca5fa1f7f8bddd248409ead9873ee8aefbf3da4b7614104d14a807c2d69469

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