• Stars
    star
    132
  • Rank 274,205 (Top 6 %)
  • Language
    Python
  • License
    MIT License
  • Created almost 6 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Python Client for ESPHome native API. Used by Home Assistant.

aioesphomeapi

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.

More Repositories

1

esphome

ESPHome is a system to control your ESP8266/ESP32 by simple yet powerful configuration files and control them remotely through Home Automation systems.
C++
8,351
star
2

esphome-core

🚨 No longer used 🚨 - The C++ framework behind ESPHome
C++
545
star
3

esp-web-tools

Open source tools to allow working with ESP devices in the browser
TypeScript
439
star
4

feature-requests

ESPHome Feature Request Tracker
413
star
5

esphome-docs

Source for esphome.io documentation files.
Python
345
star
6

issues

Issue Tracker for ESPHome
290
star
7

home-assistant-addon

ESPHome Home Assistant Add-on
Python
269
star
8

esphome-devices

ESPHome Device Configurations Repository - A database of user submitted configurations for a variety of devices which can be flashed to run ESPHome.io firmware.
JavaScript
185
star
9

bluetooth-proxies

This repo hosts known, tested devices that can serve as Bluetooth proxies for Home Assistant.
171
star
10

firmware

Holds firmware configuration files for projects that the ESPHome team provides.
HTML
152
star
11

esphome-vscode

ESPHome VSCode plugin
TypeScript
75
star
12

dashboard

ESPHome dashboard and ESPHome Web
TypeScript
74
star
13

media-players

This repo hosts known, tested devices that can server as media players to Home Assistant.
52
star
14

home-assistant-voice-pe

Home Assistant Voice PE
C++
42
star
15

esphome-webserver

A Lit Element web component frontend for the ESPHome web_server.
TypeScript
35
star
16

esphome-project-template

28
star
17

wake-word-voice-assistants

21
star
18

micro-wake-word-models

19
star
19

build-action

Python
14
star
20

esphome-release

Release scripts for the esphomelib framework
Python
6
star
21

workflows

GitHub Action workflows for use with ESPHome
3
star
22

voice-kit-xmos-firmware

C
3
star
23

libsodium-esphome

libsodium port for ESPHome
C
2
star
24

dashboard-api

Python
2
star
25

esphome-docker-base

Docker Base Images for ESPHome ⚠️ NO LONGER USED ⚠️
Python
2
star
26

deployments

Deployment configuration
HCL
1
star
27

.github

1
star
28

developers.esphome.io

ESPHome developer documentation website
1
star