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

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

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

Uploaded Source

Built Distributions

aioesphomeapi-18.0.2-cp312-cp312-musllinux_1_1_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.12 musllinux: musl 1.1+ x86-64

aioesphomeapi-18.0.2-cp312-cp312-musllinux_1_1_i686.whl (2.6 MB view details)

Uploaded CPython 3.12 musllinux: musl 1.1+ i686

aioesphomeapi-18.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.12 manylinux: glibc 2.17+ x86-64

aioesphomeapi-18.0.2-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.6 MB view details)

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

aioesphomeapi-18.0.2-cp311-cp311-musllinux_1_1_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.11 musllinux: musl 1.1+ x86-64

aioesphomeapi-18.0.2-cp311-cp311-musllinux_1_1_i686.whl (2.6 MB view details)

Uploaded CPython 3.11 musllinux: musl 1.1+ i686

aioesphomeapi-18.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

aioesphomeapi-18.0.2-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.6 MB view details)

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

aioesphomeapi-18.0.2-cp310-cp310-musllinux_1_1_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.10 musllinux: musl 1.1+ x86-64

aioesphomeapi-18.0.2-cp310-cp310-musllinux_1_1_i686.whl (2.4 MB view details)

Uploaded CPython 3.10 musllinux: musl 1.1+ i686

aioesphomeapi-18.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.10 manylinux: glibc 2.17+ x86-64

aioesphomeapi-18.0.2-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.5 MB view details)

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

aioesphomeapi-18.0.2-cp39-cp39-musllinux_1_1_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.9 musllinux: musl 1.1+ x86-64

aioesphomeapi-18.0.2-cp39-cp39-musllinux_1_1_i686.whl (2.5 MB view details)

Uploaded CPython 3.9 musllinux: musl 1.1+ i686

aioesphomeapi-18.0.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.9 manylinux: glibc 2.17+ x86-64

aioesphomeapi-18.0.2-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.5 MB view details)

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

File details

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

File metadata

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

File hashes

Hashes for aioesphomeapi-18.0.2.tar.gz
Algorithm Hash digest
SHA256 3e79fbed9d0e5863e79282e06aff8632a0fadd5cf151745a82747dd58f474198
MD5 bd8ff195bcaef3043b81d0573cfa4e27
BLAKE2b-256 af99d16a9cb481bb9cb9e3d944f15618864fe33025f8de196831853b529ba0a7

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp312-cp312-musllinux_1_1_x86_64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp312-cp312-musllinux_1_1_x86_64.whl
Algorithm Hash digest
SHA256 f92b88eab37a674b67a4c3ada34e358f354158612241bfc808852bbba0e47c8f
MD5 a179529b27dc4129e190232e5a942feb
BLAKE2b-256 60df13491dc3983d5a483ba4682a8fd640afa9a1aaa5e4aaa61a7f720fe6ee3b

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp312-cp312-musllinux_1_1_i686.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp312-cp312-musllinux_1_1_i686.whl
Algorithm Hash digest
SHA256 9e1620b7aefbc8b4972265c27f92c65e79436a278d9fde5c29c506a434441f24
MD5 af80f00eb89156cfd6039f730d4bda93
BLAKE2b-256 9e14e4f957bcff59aba5bc02d3c9259d1b085e2d19e92a68403a36ae9460b107

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 49143cd32e4fec40c64108fe50c3077bdcbcebfe1032e0b6714588bfff4ccc07
MD5 8647114c8fd286971fea1a01dba17e04
BLAKE2b-256 4a5a3df55baae739cebc9f2a8977052bafd3b37b9825c94fafcf3d276457acd9

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 a74377a3762ecf019a236423540b0a4fc68004c0df42eeab01aa764e040c5711
MD5 d4e6c9f52c0815085139cc31625a93ef
BLAKE2b-256 3a8f48af41eaa78750ae1407cb45b7bb807a6399a7002999d0c4437745d77c09

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp311-cp311-musllinux_1_1_x86_64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp311-cp311-musllinux_1_1_x86_64.whl
Algorithm Hash digest
SHA256 ba3d55082a41d5e943ae218761428f182716bce3fa9d3d0636d0517f4d67e04a
MD5 5513b13b9079d4d483110a2668d6321c
BLAKE2b-256 6839226ef6bddc54e70f0159418f8f472bdce41bd73ca89c56bf3c2f74decc2f

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp311-cp311-musllinux_1_1_i686.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp311-cp311-musllinux_1_1_i686.whl
Algorithm Hash digest
SHA256 2f1f1b69ae5f8bf6c0ab3fb75a35c887c9b6d3fb813810175e012d2a16294e96
MD5 13d56ac4cbd1a7b23bc1c1f6f1a1ea96
BLAKE2b-256 2cfd0b82e69e1f83636d200b713321b08753117054d6f5e2ff1c313e18426a96

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a484eea3a4ddaabb0dee66f647a08203e6198e56ae7118968148cd149de8f652
MD5 ca14c28be75fcacc3d6a44ea608818f5
BLAKE2b-256 c86347ab45f4601a32baa35ec2517dbdf572a74d026e721445687c035e9f61f9

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 f3f475a8440f02f1aecceea15ad2d81962f31b9b11b30572a8273c0fe0a60f0f
MD5 73dd22b37a8f2edd54e3cf33347f287f
BLAKE2b-256 d0eaf1426db9e3b6312b88634525eac8f65ad96342865fee92681a6e1114067b

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp310-cp310-musllinux_1_1_x86_64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp310-cp310-musllinux_1_1_x86_64.whl
Algorithm Hash digest
SHA256 3372f31dbf1fca5594e6d08eb656509d59a42708035ddf17515f3cce4e47a29a
MD5 45ae73637fee52173ee3183941d460c0
BLAKE2b-256 1aaa968d8570e586dff7e6c5c80612aea3c078c8e80e27350ae74a13eea21c38

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp310-cp310-musllinux_1_1_i686.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp310-cp310-musllinux_1_1_i686.whl
Algorithm Hash digest
SHA256 ac2324008d2586eb0ff466dc6323f02ecce769e318cebdd2a5299ac8e01d640c
MD5 86d1acaadee1202394075fd329b8c2e3
BLAKE2b-256 27168d27357073770ea768bca7afeb2e68c5599ab79a6cdbec8ac72de0493f22

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 68b4800e8ab8350b9b0659f5cbd51dddede316cc43ab28e860c0390ca511eac4
MD5 717be35b8e121eeec9f5902cc57e9170
BLAKE2b-256 4cdf15121098aca91c76dc98c37b759fea364e34ef75b8f03317c298151d1a92

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 1f77068e8338695c6a4ade8dc14b94293bc23520cbdf9b9f7aa1c2c503b80549
MD5 8109c4fd3560220ed50a28a47e705dbd
BLAKE2b-256 2c51cf1024bb6c2091b80fb19fe89b3b081772b72d6e2b5d3d50fee5b8903b76

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp39-cp39-musllinux_1_1_x86_64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp39-cp39-musllinux_1_1_x86_64.whl
Algorithm Hash digest
SHA256 84afb9fc143b554554718e42e2108db580fa49a46b919d29e101c02b88700f6d
MD5 1159baf55d000ddc7ebfb397d443aa3b
BLAKE2b-256 e005132fb8093f929b571d78716e43bd6e8a4d4f4a2f59c79a3dcb0f4d940959

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp39-cp39-musllinux_1_1_i686.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp39-cp39-musllinux_1_1_i686.whl
Algorithm Hash digest
SHA256 29e00c4417464649d96b700863e2e3a1e8cbb4d62dabbe7ca748573be518eda1
MD5 297e27765f1f9d143547b6a288c1ea21
BLAKE2b-256 2ac3e678f56cbcb3170e73103d2830a3a42a812b000d1c8ea9a2fcfb47ec0ba9

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 1abcf8e9d490206f2a9f5c096cbc052ad0a8983cd41b0e98616d35aa5a1a50e6
MD5 4bf94231a4fb70bea94648ae60040228
BLAKE2b-256 81580bb59fab9d6b48adbe023f87c28c78f7a4262bffe83fd841637b326ccc6c

See more details on using hashes here.

File details

Details for the file aioesphomeapi-18.0.2-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl.

File metadata

File hashes

Hashes for aioesphomeapi-18.0.2-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 d1e0f1f99fb1019456fc19305b679f7292556d0f437f0ad4d6f50845b2c46d61
MD5 5baf26c8cfd825d7471af09e9568f7ce
BLAKE2b-256 864ac5bbbfee9c8e2da1868722b1319ef3c5801c8ed7fa89e8413c3a66fd224b

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