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.

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 (the newest version is the default):

• 1.16 (api-1-16) (2026.9.0b1)
• 1.15 (api-1-15) (2026.8.0b2)
• 1.14 (api-1-14) (2026.1.0)
• 1.13 (api-1-13) (2025.11.0)
• 1.12 (api-1-12) (2025.8.0)
• 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:

• Connection pooling

License

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

See LICENSE for details.

Copyright 2025 Daan Sieben