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.

ESPHome firmware writes structured log messages at configurable severity levels. The API client can subscribe to these messages in real time, which is useful for debugging device behaviour and monitoring firmware output without needing a serial connection.

​
Function signature

func (c *Client) SubscribeLogs(
    level pb.LogLevel,
    handler func(msg *pb.SubscribeLogsResponse),
) (unsubscribe func(), err error)
SubscribeLogs sends a SubscribeLogsRequest to the device with DumpConfig: true set automatically. This causes the device to emit its current configuration as log messages immediately after the subscription is accepted.

​
Example

import (
    "fmt"
    "log"

    "github.com/richard87/esphome-apiclient/pb"
)

unsubscribe, err := client.SubscribeLogs(pb.LogLevel_LOG_LEVEL_DEBUG,
    func(msg *pb.SubscribeLogsResponse) {
        fmt.Printf("[%s] %s\n", msg.Level, msg.Message)
    },
)
if err != nil {
    log.Fatal(err)
}
defer unsubscribe()

// Block until the connection closes
<-client.Done()

​
Log levels

Pass one of the following constants as the level argument. The device will deliver messages at that level and all higher-severity levels.
ConstantSeverity
pb.LogLevel_LOG_LEVEL_NONENo log output
pb.LogLevel_LOG_LEVEL_ERRORErrors only
pb.LogLevel_LOG_LEVEL_WARNWarnings and errors
pb.LogLevel_LOG_LEVEL_INFOInformational messages and above
pb.LogLevel_LOG_LEVEL_CONFIGConfiguration messages and above
pb.LogLevel_LOG_LEVEL_DEBUGDebug messages and above (default for CLI)
pb.LogLevel_LOG_LEVEL_VERBOSEVerbose trace messages and above
pb.LogLevel_LOG_LEVEL_VERY_VERBOSEAll messages including very verbose trace

​
SubscribeLogsResponse fields

FieldTypeDescription
Levelpb.LogLevelSeverity level of this message
MessagestringLog message text
SendFailedboolTrue if the device could not send a previous message (buffer overflow)

​
Unsubscribing

The returned unsubscribe function removes the log handler. After calling it, no further messages will be delivered to the handler. 
unsubscribe, err := client.SubscribeLogs(pb.LogLevel_LOG_LEVEL_INFO, handler)
if err != nil {
    log.Fatal(err)
}

// Stop receiving logs after 60 seconds
time.Sleep(60 * time.Second)
unsubscribe()

​
Practical uses

  • Debugging sensor readings — stream DEBUG logs to see raw values before filtering
  • Monitoring firmware boot — the automatic config dump on subscribe shows the active component configuration
  • Detecting errors in production — subscribe at ERROR level to receive only actionable messages
  • Developing automations — trace state machine transitions by watching INFO or DEBUG output

Build docs developers (and LLMs) love

Get started for freeTalk to us