Struct EspHomeApi 

pub struct EspHomeApi { /* private fields */ }

Low-level ESPHome native API client.

EspHomeApi provides direct access to the ESPHome native API protocol, handling connection setup, encryption, and message framing. This is the lower-level API that crate::esphomeserver::EspHomeServer builds upon.

This struct supports both encrypted and plaintext connections and uses the builder pattern for configuration via TypedBuilder.

Builder Options

• name: Device name (required)
• encryption_key: Base64-encoded encryption key (optional, enables encryption)
• api_version_major: API version major number (default: 1)
• api_version_minor: API version minor number (default: 10)
• server_info: Server identification string (default: “Rust: esphome-native-api”)
• friendly_name: Human-readable device name (optional)
• mac: MAC address (optional)
• model: Device model (optional)
• manufacturer: Device manufacturer (optional)
• suggested_area: Suggested area for the device (optional)
• bluetooth_mac_address: Bluetooth MAC address (optional)

Examples

use esphome_native_api::esphomeapi::EspHomeApi;

let api = EspHomeApi::builder()
    .name("bedroom-light".to_string())
    .api_version_major(1)
    .api_version_minor(10)
    .friendly_name("Bedroom Light".to_string())
    .build().unwrap();

Implementations

impl EspHomeApi

pub fn builder() -> EspHomeApiBuilder<((), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), (), ())>

Create a builder for building EspHomeApi. On the builder, call .name(...), .encryption_key(...)(optional), .api_version_major(...)(optional), .api_version_minor(...)(optional), .server_info(...)(optional), .friendly_name(...)(optional), .mac(...)(optional), .model(...)(optional), .manufacturer(...)(optional), .suggested_area(...)(optional), .bluetooth_mac_address(...)(optional), .project_name(...)(optional), .project_version(...)(optional), .compilation_time(...)(optional), .legacy_bluetooth_proxy_version(...)(optional), .bluetooth_proxy_feature_flags(...)(optional), .legacy_voice_assistant_version(...)(optional), .voice_assistant_feature_flags(...)(optional) to set the values of the fields. Finally, call .build() to create the instance of EspHomeApi.

impl EspHomeApi

Handles the ESPHome API protocol with encryption support.

pub async fn start<S>(&self, stream: S) -> Result<Connection, Error>

where S: AsyncRead + AsyncWrite + Unpin + Send + 'static,

Starts the API client and establishes communication with an ESPHome device.

This method performs the complete connection handshake, including:

1. Detecting whether encryption is required
2. Performing encryption handshake if needed
3. Exchanging hello messages
4. Setting up message routing

Arguments

• tcp_stream - An established TCP connection to the ESPHome device

Returns

Returns a Connection handle. Use Connection::sender to send messages to the device, Connection::receiver to receive messages from it, and Connection::wait to observe when — and why — the connection ends.

Errors

Returns an Error if:

• The connection fails (Error::Io)
• The encryption handshake fails (Error::Handshake)
• The device requires encryption but no key was provided
• The peer disconnects mid-handshake (Error::Disconnected)

Examples

let stream = TcpStream::connect("192.168.1.100:6053").await?;
let api = EspHomeApi::builder().name("client".to_string()).build()?;
let connection = api.start(stream).await?;
let tx = connection.sender();
let mut rx = connection.receiver();

Trait Implementations

impl Clone for EspHomeApi

fn clone(&self) -> EspHomeApi

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl From<EspHomeApi> for EspHomeApiBuildResult

Validates and decodes the configured encryption key when the builder’s build() runs, so a misconfiguration surfaces as Error::Config at construction rather than partway through the connection handshake.

fn from(api: EspHomeApi) -> Self

Converts to this type from the input type.