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 aioesphomeapiAn 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:6053The 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-protocA cli tool is also available for watching logs:
aioesphomeapi-logs --helpA cli tool is also available to discover devices:
aioesphomeapi-discoverLicense
aioesphomeapi is licensed under MIT, for more details check LICENSE.
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
Built Distributions
File details
Details for the file aioesphomeapi-25.0.0.tar.gz.
File metadata
- Download URL: aioesphomeapi-25.0.0.tar.gz
- Upload date:
- Size: 101.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 245580c0d612748f962bfa563b3e86ffc0d51c7d84bd1bd5ae373a3883eeb541 |
|
| MD5 | a2ee4db656e22619322c1b397cb5fb2f |
|
| BLAKE2b-256 | 0d73e4c62dc734eed11d856f3f09440e7b192d7cb68f464140795fdbbfb8822f |
File details
Details for the file aioesphomeapi-25.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: aioesphomeapi-25.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 2.4 MB
- Tags: CPython 3.12, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 49cde3ca0e3bc7e7f22cbee051aa68a7cb34d005eadfb2b2d353a2c20639bb19 |
|
| MD5 | a42e3b58c1a77e3d601d34179bf5c559 |
|
| BLAKE2b-256 | f4d17a8e1e22f7adc40f34594dd7e0850f616aeb7e7854cfcb74fa89d0e61818 |
File details
Details for the file aioesphomeapi-25.0.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: aioesphomeapi-25.0.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 2.3 MB
- Tags: CPython 3.12, manylinux: glibc 2.17+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 7d7e767d0c2796aa5c8444db192485c7f898ac1e792b311b16b6aac080425ad1 |
|
| MD5 | c7fd10f587f502289666f2df98ac8491 |
|
| BLAKE2b-256 | 776df955a71e41e15d1eb818fb117bb4978056f7c4d069221918efb29ba3acdc |
File details
Details for the file aioesphomeapi-25.0.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl.
File metadata
- Download URL: aioesphomeapi-25.0.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
- Upload date:
- Size: 2.2 MB
- Tags: CPython 3.12, manylinux: glibc 2.17+ i686, manylinux: glibc 2.5+ i686
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | f84dd9aa35545392793d6b28e8730651f00d2663003a3cb78a9680cbe2749c47 |
|
| MD5 | be17157732b5361dc89cf3a5d8e0246a |
|
| BLAKE2b-256 | aeca6c15d50389057102a1e590c228b54e3d89eee0c8ee6a95d3031dc92fa827 |
File details
Details for the file aioesphomeapi-25.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: aioesphomeapi-25.0.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 2.3 MB
- Tags: CPython 3.11, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | c06fd75d0203673e2e1c0df60228c034721376f0d0ab31f73dd61cebead215f9 |
|
| MD5 | 70824538a22127ed332452fb0079b533 |
|
| BLAKE2b-256 | ca2a894d6576b9aa9be4304544a006cc418f73878e2a1178d8dee5cc9ae6cf0d |
File details
Details for the file aioesphomeapi-25.0.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: aioesphomeapi-25.0.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 2.3 MB
- Tags: CPython 3.11, manylinux: glibc 2.17+ ARM64
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | def886c7dcb7174558a87ab14178280838a4ecca01a14bced9ce545f23c8afe6 |
|
| MD5 | 4ce6f6b587bdf41ba5002cd3edaf5b10 |
|
| BLAKE2b-256 | b866f6665f54a15eff82a7cb42df97edf3b8da96fd974f971dd1cbd4ca857609 |
File details
Details for the file aioesphomeapi-25.0.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl.
File metadata
- Download URL: aioesphomeapi-25.0.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
- Upload date:
- Size: 2.2 MB
- Tags: CPython 3.11, manylinux: glibc 2.17+ i686, manylinux: glibc 2.5+ i686
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/5.1.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 3f6bedb1c1ed36abf99d96753f969ae067c35d0fc31733d9ad316d2491d1efd0 |
|
| MD5 | 7614fdd355584170c0fc56243385585c |
|
| BLAKE2b-256 | 966fba2dcc93fbb2b4822be9f05a48a321d2b2568976bd7bd62d5f7e245856c1 |
