Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/richard87/esphome-apiclient/llms.txt

Use this file to discover all available pages before exploring further.

Connect to ESPHome devices directly from Go applications using the native API. This library handles TCP connections, Noise protocol encryption, entity discovery, real-time state subscriptions, and device commands — all with zero CGO dependencies.

Quick Start

Connect to your first ESPHome device in minutes

Installation

Add the library to your Go project

Library Guide

Learn how to connect, discover entities, and stream state updates

API Reference

Full reference for all public types and methods

​
What you can do

Read sensor data

Subscribe to live state updates from sensors, binary sensors, text sensors, and more

Control devices

Send commands to switches, lights, fans, climate controllers, locks, and media players

Stream device logs

Receive real-time log output from ESPHome firmware at configurable verbosity levels

Bluetooth proxy

Use ESPHome devices as Bluetooth proxies for BLE advertisement scanning and GATT operations

Noise encryption

Secure all communication with Noise protocol encryption using a pre-shared key from your ESPHome config

Auto-reconnect

Automatically reconnect with exponential backoff and re-subscribe after connection loss

​
Get started

1

Install the module

go get github.com/richard87/esphome-apiclient
2

Connect to a device

import (
    esphome "github.com/richard87/esphome-apiclient"
    "time"
)

client, err := esphome.Dial("mydevice.local:6053", 5*time.Second,
    esphome.WithEncryptionKey("base64-noise-psk"),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close()
3

Discover entities and stream states

client.ListEntities()

client.SubscribeStates(func(msg proto.Message) {
    switch m := msg.(type) {
    case *pb.SensorStateResponse:
        entity := client.Entities().ByKey(m.Key)
        fmt.Printf("sensor %s = %.4g\n", entity.GetName(), m.State)
    }
})
4

Send a command

// Turn a switch on
client.SetSwitch(0x12345678, true)
ESPHome devices must have the Native API component enabled in their firmware configuration. For encrypted connections, copy the encryption.key value from your ESPHome YAML.

Build docs developers (and LLMs) love

Get started for freeTalk to us