Crate esphome_client 

ESPHome Client

This crate contains a library for interacting with ESPHome devices using sockets. It provides all the necessary functionality to connect, authenticate, and communicate with ESPHome devices. The library is designed to be used as a dependency in other Rust projects that require communication with ESPHome devices.

To be able to compile this crate you will need to install the protobuf compiler protoc. Official installation instructions can be found here. Depending on your system, you can also rely on installers:

• apt install protobuf-compiler
• brew install protobuf

Example

Basic example retrieving device info:

use esphome_client::{EspHomeClient, types};

// 32-byte, base64 encoded api key
const KEY: &str = "AAECAwQFBgcICRAREhMUFRYXGBkgISIjJCUmJygpMDE=";

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = EspHomeClient::builder()
        .address("192.168.0.2:6053")
        .key(KEY)
        .connect()
        .await?;

    client.try_write(types::DeviceInfoRequest {}).await?;

    loop {
        let response = client.try_read().await?;
        match response {
            types::EspHomeMessage::DeviceInfoResponse(response) => {
                println!("Received DeviceInfoResponse: {:?}", response);
            }
            _ => {
                println!("Received unsupported message type: {:?}", response);
            }
        }
    }
}

API Versions

Different API versions used during communication can be enabled using features. By default, it will use the latest available. Note this means your implementation might break if you don’t pin down the used version and this crate is updated. It’s recommended that you add the feature flag with the version in your Cargo.toml to avoid unexpected issues in the future.

Currently supported:

• 1.12 (api-1-12) (2025.8.0) this is the current default
• 1.10 (api-1-10) (2025.5.0)
• 1.9 (api-1-9) (2024.4.0)
• 1.8 (api-1-8) (2023.5.0)

Follow the guide in the proto dir to see how to add a new version.

Future

Some things to be added/improved in the future:

• Automatic updates to newly released ESPHome API versions
• Connection pooling

License

esphome-client is distributed under the terms of the MIT License.

See LICENSE for details.

Copyright 2025 Daan Sieben

Modules

discovery

error

types

Structs

EspHomeClient

EspHomeClientBuilder

EspHomeClientWriteStream

Constants

API_VERSION

Functions

convert_gatt_uuid

This is a helper function to convert GATT UUIDs from the format used in ESPHome: [u64, u64] to a byte array.