Python API for interacting with ESPHome devices.

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for balloob from gravatar.com balloob Avatar for esphome from gravatar.com esphome Avatar for Jesserockz from gravatar.com Jesserockz Avatar for OttoWinter from gravatar.com OttoWinter
Meta

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT
  • Author: Otto Winter
  • Requires: Python >=3.9

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

A cli tool is also available to discover devices:

aioesphomeapi-discover

License

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

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for balloob from gravatar.com balloob Avatar for esphome from gravatar.com esphome Avatar for Jesserockz from gravatar.com Jesserockz Avatar for OttoWinter from gravatar.com OttoWinter
Meta

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT
  • Author: Otto Winter
  • Requires: Python >=3.9

Release history Release notifications | RSS feed

This version

27.0.1

27.0.0

26.0.0

25.4.0

25.3.2

25.3.1

25.3.0

25.2.1

25.2.0

25.1.0

25.0.0

24.6.2

24.6.1

24.6.0

24.5.0

24.4.0

24.3.0

24.2.0

24.1.0

24.0.0

23.2.0

23.1.1

23.1.0

23.0.0

22.1.0

22.0.0

21.0.3

21.0.2

21.0.1

21.0.0

20.1.0

20.0.0

19.3.1

19.3.0

19.2.1

19.2.0

19.1.7

19.1.6

19.1.5

19.1.4

19.1.3

19.1.2

19.1.1

19.1.0

19.0.1

19.0.0

18.5.9

18.5.8

18.5.7

18.5.6

18.5.5

18.5.4

18.5.3

18.5.2

18.5.1

18.5.0

18.4.1

18.4.0

18.3.0

18.2.7

18.2.6

18.2.4

18.2.3

18.2.2

18.2.1

18.2.0

18.1.0

18.0.12

18.0.11

18.0.10

18.0.9

18.0.8

18.0.7

18.0.6

18.0.5

18.0.4

18.0.3

18.0.2

18.0.1

18.0.0

17.2.0

17.1.5

17.1.4

17.1.3

17.1.0

17.0.1

17.0.0

16.0.6

16.0.5

16.0.4

16.0.3

16.0.2

16.0.1

16.0.0

15.1.15

15.1.14

15.1.13

15.1.12

15.1.11

15.1.10

15.1.9

15.1.8

15.1.7

15.1.6

15.1.5

15.1.4

15.1.3

15.1.2

15.1.1

15.1.0

15.0.1

15.0.0

14.1.1

14.1.0

14.0.0

13.9.0

13.8.0

13.7.5

13.7.4

13.7.3

13.7.2

13.7.1

13.7.0

13.6.1

13.6.0

13.5.1

13.5.0

13.4.2

13.4.1

13.4.0

13.3.1

13.3.0

13.2.0

13.1.0

13.0.4

13.0.3

13.0.2

13.0.1

13.0.0

12.2.1

12.2.0

12.1.0

12.0.1

12.0.0

11.5.0

11.4.3

11.4.2

11.4.1

11.4.0

11.3.0

11.2.0

11.1.1

11.1.0

11.0.0

10.14.0

10.13.0

10.12.0

10.11.0

10.10.0

10.9.0

10.8.2

10.8.1

10.8.0

10.7.0

10.6.0

10.5.0

10.4.0

10.3.0

10.2.0

10.1.0

10.0.3

10.0.2

10.0.1

10.0.0

9.1.5

9.1.4

9.1.3

9.1.2

9.1.1

9.1.0

9.0.0

8.0.0

7.0.0

6.1.0

6.0.1

6.0.0

5.1.1

5.1.0 yanked

Reason this release was yanked:

The build went wrong and the python files were not included

5.0.1

5.0.0

4.1.0

4.0.1

4.0.0

3.1.0

3.0.1

3.0.0

2.9.0

2.8.0

2.7.0

2.6.6

2.6.5

2.6.4

2.6.3

2.6.2

2.6.1

2.6.0

2.5.0

2.4.2

2.4.1

2.4.0

2.3.0

2.2.0

2.1.0

2.0.1

2.0.0

1.8.0

1.7.0

1.6.0

1.5.0

1.4.2

1.4.1

1.3.0

1.2.0

1.1.0

1.0.0

Download files

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

Source Distribution

aioesphomeapi-27.0.1.tar.gz (106.6 kB view details)

Uploaded Source

Built Distributions

aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.4 MB view details)

Uploaded CPython 3.13 manylinux: glibc 2.17+ x86-64

aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.4 MB view details)

Uploaded CPython 3.13 manylinux: glibc 2.17+ ARM64

aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.3 MB view details)

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

aioesphomeapi-27.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.12 manylinux: glibc 2.17+ x86-64

aioesphomeapi-27.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.4 MB view details)

Uploaded CPython 3.12 manylinux: glibc 2.17+ ARM64

aioesphomeapi-27.0.1-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.3 MB view details)

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

aioesphomeapi-27.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.4 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

aioesphomeapi-27.0.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.4 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ ARM64

aioesphomeapi-27.0.1-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.3 MB view details)

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

File details

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

File metadata

  • Download URL: aioesphomeapi-27.0.1.tar.gz
  • Upload date:
  • Size: 106.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for aioesphomeapi-27.0.1.tar.gz
Algorithm Hash digest
SHA256 72c786ab9700ca44b536adc0dabd9ac1aedd7e3d414f8ce6774717ac16dedea4
MD5 473c6d21ea6a52fac3fa4af7367c3c52
BLAKE2b-256 4f75a7d0707f197eb8d0019a69e0caae0dac04e53ae2a60d0766a60a6df17f63

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioesphomeapi-27.0.1.tar.gz:

Publisher: release.yml on esphome/aioesphomeapi

Attestations:

File details

Details for the file aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9d9ec2d7dbea065e40334e3ae034d8dc13dc3a364f4b3ac68e88037030576d6d
MD5 5e27a9c32cfe3c41c871b5d6f2205289
BLAKE2b-256 09273a0c1d8fd85f81cc4aa4518157a62fbab39c1b3f6b90f984aad511e494ec

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on esphome/aioesphomeapi

Attestations:

File details

Details for the file aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 96f9a013673c52f1bb58787b43d4af57cc61b4672af6ca8f41e5771b4c53b7ba
MD5 ce0c3f00ace2729880697ca9f686c92d
BLAKE2b-256 ba233f29c5aa95f4959592a874e8b9eba4659214b52d33177d2058755ebe5a63

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on esphome/aioesphomeapi

Attestations:

File details

Details for the file aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl.

File metadata

File hashes

Hashes for aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 d5b965043b025997dfc80faf40f46170e6a61f9b76c19da58b2e274ad6eab3ac
MD5 82e857a906bc6080f45f8c9cdfa0a570
BLAKE2b-256 da770d01f61975bc297d2203fd2ca49b709bdf9d1e5beeef4607c0d84bece64f

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioesphomeapi-27.0.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl:

Publisher: release.yml on esphome/aioesphomeapi

Attestations:

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-27.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c51058cfd401365a75f7962e53c0597ab12444dc7e43c1afaec1ce2bfcc5e61b
MD5 ec5d6b22d29a0e855b8ca9323d14552c
BLAKE2b-256 b87b563d309f30c3231a770a9237a9d6eb3b707fcdb5e32be4a77cb7b5ecd571

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioesphomeapi-27.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on esphome/aioesphomeapi

Attestations:

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-27.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 b9718fcf04fb005f142fbf462ff5c4f9b5b530d44176907f60dde9869016bae1
MD5 32af31f0fe3a87ad6a786c87240f0a21
BLAKE2b-256 d43847da7cccb04f3b76e864dd392cb513f0a8d6d6e8c585d882bcd58a7f9393

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioesphomeapi-27.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on esphome/aioesphomeapi

Attestations:

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-27.0.1-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 b8613baa3a5a1e614a631cbcf9082eb1daa71ae67dc97010b4dc88a5bf25289c
MD5 42419d98f2d10e2fe6653ea3b40fdab2
BLAKE2b-256 5c0a6c67132d049d0a9125204f50673f275ea9092fb2235e0b10ca388d83f53c

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioesphomeapi-27.0.1-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl:

Publisher: release.yml on esphome/aioesphomeapi

Attestations:

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-27.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e25782f3d720d7026c06ec232be942475bced62237aa7dfc3aae97f732afb43f
MD5 87837fd944052174a1ab50b68307dc31
BLAKE2b-256 3fec32f540a9abc68e841fa106a8c765276ed18ec9847545bbac1adad3e755f0

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioesphomeapi-27.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on esphome/aioesphomeapi

Attestations:

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-27.0.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 1593ae40600246e592cfcb9dd1de0d6dd05848aa35ce0eecc66f555179b20bdd
MD5 2476efb0bc9040f256272a8c35b2c75a
BLAKE2b-256 072b01fbe84feb8dee401c3a39d410b395688a6899b4b77d1d7953f48ea14608

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioesphomeapi-27.0.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on esphome/aioesphomeapi

Attestations:

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-27.0.1-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 4306d1d1edb91d9b15ae1272deb93b517a50fb13062293bb11c1e638b07282b0
MD5 7f677e3817747662fc0a5cab62fedd38
BLAKE2b-256 abff5e0e9d5241af5aa345a421057996576960653213850180045cf69437e0d2

See more details on using hashes here.

Provenance

The following attestation bundles were made for aioesphomeapi-27.0.1-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl:

Publisher: release.yml on esphome/aioesphomeapi

Attestations:

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