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

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

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

27.0.1

27.0.0

26.0.0

25.4.0

25.3.2

This version

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

Uploaded Source

Built Distributions

aioesphomeapi-25.3.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-25.3.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.3 MB view details)

Uploaded CPython 3.13 manylinux: glibc 2.17+ ARM64

aioesphomeapi-25.3.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (2.2 MB view details)

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

aioesphomeapi-25.3.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.4 MB view details)

Uploaded CPython 3.12 manylinux: glibc 2.17+ x86-64

aioesphomeapi-25.3.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-25.3.1-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-25.3.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

aioesphomeapi-25.3.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.3 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ ARM64

aioesphomeapi-25.3.1-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-25.3.1.tar.gz.

File metadata

  • Download URL: aioesphomeapi-25.3.1.tar.gz
  • Upload date:
  • Size: 102.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.0 CPython/3.12.5

File hashes

Hashes for aioesphomeapi-25.3.1.tar.gz
Algorithm Hash digest
SHA256 22a92c04a0e84664d6e7496e50ea9ab3ba7f9f53b4edf777196b24cb39b28470
MD5 3f792d26afa94eac56262c42434068ce
BLAKE2b-256 5b4e3a4fe2d7a07fc14817c1f03657ddc71a68b50d3c0182428d19450638d449

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-25.3.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3569b9ea7b8846036d34f661574fc7ac9eb89064266b3f904fc979c3ff497b44
MD5 18b28461c53974d7de37e42048096f6f
BLAKE2b-256 72aa64f4e907b1a0542bc5d77318f6807111df6ceb21fe50abb84a11150a1c37

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-25.3.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ee8b8186a3cb5c1eacb0cfe20919f357747999eb6350d35558b4d266f1ed8afb
MD5 21824603b0776c3f4697be3dbdaeb39a
BLAKE2b-256 72c70a9fc10fe7c40635229f6e58f3698a3e0a811e3563d7dafa64e88b335756

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-25.3.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 6bfc92a0a85ef57d03026cf5312d489b794ac12b26befe2729ee056a92cfbf2e
MD5 41c26d391d077c9403d972bed9f26fe3
BLAKE2b-256 1e0a508dd45aa9eb5ebd06a47b0f45a2fccbd876d023348c0bdda43455c65850

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-25.3.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 10a4e979e1346b296b1624a75c66bb03a09692a8a6b17fd3e6dbfa87b9a16c78
MD5 44edfd6c4d1705da88bf8dac6c72d802
BLAKE2b-256 3b0a86d9eaef1f8e784163113f50f8971abb9096123ad4ebcc158781eb2b3d9f

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-25.3.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 128caae3c8bc1597f546a25c1370f783474e24caa9256f7304ee5de8addddb29
MD5 2fd3de244dc05d76baee35106ff07319
BLAKE2b-256 821f88f8cebf21dcb3c51129a45f366b722e6085c5a0553bcf3e7f1483a3492a

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-25.3.1-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 3ba36ed3b52b3f3d1cef0626bd17df1d127c950181ad65be8519391f0bc7e19e
MD5 a8f047c242aab5f0f93abb4ee5967ef4
BLAKE2b-256 143d1a32bf2219a295bdf1ee18d70c16542c984a4e518bf3bd1a88331fade811

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-25.3.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2a7f7113154c3b9863fcaad5c3d66c0c2e264c535d9851ba02ba761b6dd50e6e
MD5 66304d637431fb3c43969d10dfcbed7f
BLAKE2b-256 7a15eea10ce98fef8dc5da9f18e134e829cdea8653aef74de6547e43f5b80fe5

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-25.3.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 a73c77860268cb60ac3be478397747012960ec7f616a6417d11cd397b70df689
MD5 f5babadd1afa7fa11643566a7e213f09
BLAKE2b-256 4e94e09dd3a0ef7eb61498f25b4e829b342ed6c44d81658b6db2a97d7e77b5b1

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for aioesphomeapi-25.3.1-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm Hash digest
SHA256 6d4593f175f8e78a0ab7638866c0f187485ec7a535ad3c853ebaa7aa14554438
MD5 e851c67b1e751b5414de4b9de9b5e209
BLAKE2b-256 e9b34618f8d0e32506a3afb863cd4adf80ece619c223a530a124c9310757ae40

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