Skip to main content

Python API for interacting with ESPHome devices.

Project description

https://github.com/esphome/aioesphomeapi/workflows/CI/badge.svg https://img.shields.io/pypi/v/aioesphomeapi.svg https://codecov.io/gh/esphome/aioesphomeapi/branch/main/graph/badge.svg

aioesphomeapi allows you to interact with devices flashed with ESPHome.

Installation

The module is available from the Python Package Index.

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

A cli tool is also available for watching logs:

aioesphomeapi-logs --help

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

Uploaded Source

Built Distributions

aioesphomeapi-18.5.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded CPython 3.12 manylinux: glibc 2.17+ x86-64

aioesphomeapi-18.5.6-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.3 MB view details)

Uploaded CPython 3.12 manylinux: glibc 2.17+ ARM64

aioesphomeapi-18.5.6-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.2 MB view details)

Uploaded CPython 3.12 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

aioesphomeapi-18.5.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.2 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

aioesphomeapi-18.5.6-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.2 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ ARM64

aioesphomeapi-18.5.6-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.2 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

File details

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

File metadata

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

File hashes

Hashes for aioesphomeapi-18.5.6.tar.gz
Algorithm Hash digest
SHA256 dd79193f8f4c25b2cd2514c34312e966a05e226f04dbb45862a2967594f243e7
MD5 74aac11318cbefddc2805fe927adf471
BLAKE2b-256 71221ebac628aedec543d0b9c5b0a4e7b25814e78e4c4d204a017ec228c01bb7

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.5.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.5.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 7ee93ce71ca80aec2d93b862deddf3e8b0b6a40374d38c0dde8f8f2e5ac10f0b
MD5 ac709f1ff793980c14bd1a7b42c4bd13
BLAKE2b-256 f1097b599f374fcbe4ddeced21d50f512b22de613983e80a29c93b1b62c7a79b

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.5.6-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.5.6-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 1bfc3d07751c400f419783932617bd25775fbf47baf5e23fc165c6187e8b76b2
MD5 260cb5d830dadfcb31d8e3abafbeab91
BLAKE2b-256 822e54003e108493e31ab1f12ea8cda9648026bda828585776e7a3df0458339f

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.5.6-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.5.6-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 46b2e147e993128eb1d8cacb81a6748a037493d9b06b8a2799a3c8a33facbd35
MD5 ccb07226808d386d92dd0bbacb513864
BLAKE2b-256 7e539a383af5f3b8f29d0f9af7ca89187cae98c9b05ce0ec5b18d0d144ee822e

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.5.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.5.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 84070c7e9041114d3d6e5c67f55933450af7ae8f4b10a2d9a4732af3d3349a85
MD5 0cfd4cc8f7060315fc9b1c1b67338812
BLAKE2b-256 c51b7778122bd001204aa54b81e65a140c71310139ca11078b1acf466ca8bc64

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.5.6-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.5.6-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 25b9999dce521d9c575f5bab47791dd0fee9991dfe456763555097cbba4e90bc
MD5 7f7884504662cc9f92bbb186279aad33
BLAKE2b-256 fd91f3bb55ad34b6595ce59c06322ee995247dfd238521d37093e44162239912

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.5.6-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.5.6-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 4d6625f4e4a58969993cd0f65e4923f97f20715bfc575a11d883cf634a35258a
MD5 baad0bd8e1f0df11f9c151bb1c748c1e
BLAKE2b-256 ac7a0eb4f19558887265e63d7cf3cc6a4f747a6c812dfc7a3dc11fe19cb7376d

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