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();

Implementations

impl EspHomeApi

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

Create a builder for building EspHomeApi. On the builder, call .first_message_received(...)(optional), .plaintext_communication(...)(optional), .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( &mut self, tcp_stream: TcpStream, ) -> Result<(Sender<ProtoMessage>, Receiver<ProtoMessage>), Box<dyn Error>>

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 tuple containing:

• An mpsc::Sender for sending messages to the device
• A broadcast::Receiver for receiving messages from the device

Errors

Returns an error if:

• The connection fails
• The encryption handshake fails
• The hello exchange fails
• The device requires encryption but no key was provided

Examples

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

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.