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.

Command methods send control messages to ESPHome entities. They are defined on *Client and are safe to call from multiple goroutines.

​
Entity validation

When ListEntities has been called, command methods validate the entity key against the registry before sending:
  • If the key is not found, the method returns ErrEntityNotFound.
  • If the key belongs to a different domain than expected, the method returns ErrEntityTypeMismatch.
  • If the registry is empty (entities have not been listed yet), validation is skipped and the command is sent as-is.
var ErrEntityNotFound    = fmt.Errorf("entity not found")
var ErrEntityTypeMismatch = fmt.Errorf("entity type mismatch")

​
Generic send

​
SendCommand

Sends any command protobuf message to the device. Resolves the message type ID automatically from the Go type. Returns an error for unsupported types. 
func (c *Client) SendCommand(cmd proto.Message) error
​
cmd
proto.Message
required
One of the supported *pb.*CommandRequest types.
Supported types: *pb.CoverCommandRequest, *pb.FanCommandRequest, *pb.LightCommandRequest, *pb.SwitchCommandRequest, *pb.ClimateCommandRequest, *pb.NumberCommandRequest, *pb.SelectCommandRequest, *pb.SirenCommandRequest, *pb.LockCommandRequest, *pb.ButtonCommandRequest, *pb.MediaPlayerCommandRequest, *pb.WaterHeaterCommandRequest. 
err := client.SendCommand(&pb.SwitchCommandRequest{
    Key:   0x12345678,
    State: true,
})

​
Switch

​
SetSwitch

Turns a switch entity on or off. 
func (c *Client) SetSwitch(key uint32, state bool) error
​
key
uint32
required
The entity key from the registry (e.g. 0x12345678).
​
state
bool
required
true to turn on, false to turn off.
// Turn on
err := client.SetSwitch(0x12345678, true)

// Turn off
err := client.SetSwitch(0x12345678, false)

​
Light

​
SetLight

Sends a light command. Only the fields whose corresponding Has* flag is set to true are applied by the device — unset fields are ignored. 
func (c *Client) SetLight(key uint32, opts LightCommandOpts) error
​
key
uint32
required
The entity key from the registry.
​
opts
LightCommandOpts
required
Struct specifying which properties to change.

​
LightCommandOpts

type LightCommandOpts struct {
    HasState            bool
    State               bool      // on/off
    HasBrightness       bool
    Brightness          float32   // 0.0–1.0
    HasColorMode        bool
    ColorMode           pb.ColorMode
    HasColorBrightness  bool
    ColorBrightness     float32   // 0.0–1.0
    HasRGB              bool
    Red                 float32   // 0.0–1.0
    Green               float32   // 0.0–1.0
    Blue                float32   // 0.0–1.0
    HasWhite            bool
    White               float32   // 0.0–1.0
    HasColorTemperature bool
    ColorTemperature    float32   // mireds
    HasColdWhite        bool
    ColdWhite           float32   // 0.0–1.0
    HasWarmWhite        bool
    WarmWhite           float32   // 0.0–1.0
    HasTransitionLength bool
    TransitionLength    uint32    // milliseconds
    HasFlashLength      bool
    FlashLength         uint32    // milliseconds
    HasEffect           bool
    Effect              string
}

// Turn on at 50% brightness with a 1-second transition
err := client.SetLight(0xAABBCCDD, esphome.LightCommandOpts{
    HasState:            true,
    State:               true,
    HasBrightness:       true,
    Brightness:          0.5,
    HasTransitionLength: true,
    TransitionLength:    1000,
})

// Set RGB colour
err = client.SetLight(0xAABBCCDD, esphome.LightCommandOpts{
    HasRGB: true,
    Red:    1.0,
    Green:  0.5,
    Blue:   0.0,
})

​
Climate

​
SetClimate

Sends a climate command. Only the fields whose corresponding Has* flag is set are applied. 
func (c *Client) SetClimate(key uint32, opts ClimateCommandOpts) error

​
ClimateCommandOpts

type ClimateCommandOpts struct {
    HasMode                  bool
    Mode                     pb.ClimateMode
    HasTargetTemperature     bool
    TargetTemperature        float32
    HasTargetTemperatureLow  bool
    TargetTemperatureLow     float32
    HasTargetTemperatureHigh bool
    TargetTemperatureHigh    float32
    HasFanMode               bool
    FanMode                  pb.ClimateFanMode
    HasSwingMode             bool
    SwingMode                pb.ClimateSwingMode
    HasCustomFanMode         bool
    CustomFanMode            string
    HasPreset                bool
    Preset                   pb.ClimatePreset
    HasCustomPreset          bool
    CustomPreset             string
    HasTargetHumidity        bool
    TargetHumidity           float32
}

// Set to heat mode at 21°C
err := client.SetClimate(0x12345678, esphome.ClimateCommandOpts{
    HasMode:              true,
    Mode:                 pb.ClimateMode_CLIMATE_MODE_HEAT,
    HasTargetTemperature: true,
    TargetTemperature:    21.0,
})

​
Number

​
SetNumber

Sets the value of a number entity. 
func (c *Client) SetNumber(key uint32, value float32) error
​
key
uint32
required
The entity key from the registry.
​
value
float32
required
The new value. Must be within the entity’s MinValue–MaxValue range.
err := client.SetNumber(0x12345678, 42.5)

​
Select

​
SetSelect

Sets the selected option of a select entity. 
func (c *Client) SetSelect(key uint32, value string) error
​
key
uint32
required
The entity key from the registry.
​
value
string
required
The option string to select. Must match one of the values in SelectEntity.Options.
err := client.SetSelect(0x12345678, "Auto")

​
Button

​
PressButton

Triggers a stateless button entity. 
func (c *Client) PressButton(key uint32) error
​
key
uint32
required
The entity key from the registry.
err := client.PressButton(0x12345678)

​
Cover

​
SetCover

Sends a cover command with full control over position, tilt, and stop. 
func (c *Client) SetCover(key uint32, opts CoverCommandOpts) error

​
CoverCommandOpts

type CoverCommandOpts struct {
    HasPosition bool
    Position    float32  // 0.0 = fully closed, 1.0 = fully open
    HasTilt     bool
    Tilt        float32  // 0.0–1.0
    Stop        bool     // send stop command
}

// Open to 75%
err := client.SetCover(0x12345678, esphome.CoverCommandOpts{
    HasPosition: true,
    Position:    0.75,
})

// Stop movement
err = client.SetCover(0x12345678, esphome.CoverCommandOpts{Stop: true})

​
SetCoverPosition

Convenience method for setting cover position only. 0.0 is fully closed, 1.0 is fully open. 
func (c *Client) SetCoverPosition(key uint32, position float32) error
​
position
float32
required
Target position: 0.0 = closed, 1.0 = open.
err := client.SetCoverPosition(0x12345678, 1.0) // fully open

​
Fan

​
SetFan

Sends a fan command. Only the fields with their corresponding Has* flag set are applied. 
func (c *Client) SetFan(key uint32, opts FanCommandOpts) error

​
FanCommandOpts

type FanCommandOpts struct {
    HasState       bool
    State          bool             // on/off
    HasOscillating bool
    Oscillating    bool
    HasDirection   bool
    Direction      pb.FanDirection
    HasSpeedLevel  bool
    SpeedLevel     int32
    HasPresetMode  bool
    PresetMode     string
}

// Turn on at speed level 2
err := client.SetFan(0x12345678, esphome.FanCommandOpts{
    HasState:      true,
    State:         true,
    HasSpeedLevel: true,
    SpeedLevel:    2,
})

​
Siren

​
SetSiren

Sends a siren command. Only the fields with their Has* flag set are applied. 
func (c *Client) SetSiren(key uint32, opts SirenCommandOpts) error

​
SirenCommandOpts

type SirenCommandOpts struct {
    HasState    bool
    State       bool
    HasTone     bool
    Tone        string
    HasDuration bool
    Duration    uint32   // seconds
    HasVolume   bool
    Volume      float32  // 0.0–1.0
}

err := client.SetSiren(0x12345678, esphome.SirenCommandOpts{
    HasState:    true,
    State:       true,
    HasTone:     true,
    Tone:        "default",
    HasDuration: true,
    Duration:    5,
})

​
Lock

​
SetLock

Sends a lock command. Pass a non-empty code string for devices that require a PIN. 
func (c *Client) SetLock(key uint32, command pb.LockCommand, code string) error
​
key
uint32
required
The entity key from the registry.
​
command
pb.LockCommand
required
One of pb.LockCommand_LOCK_LOCK, pb.LockCommand_LOCK_UNLOCK, or pb.LockCommand_LOCK_OPEN.
​
code
string
Optional PIN code. Pass an empty string for locks that do not require a code.
// Unlock without code
err := client.SetLock(0x12345678, pb.LockCommand_LOCK_UNLOCK, "")

// Unlock with PIN
err = client.SetLock(0x12345678, pb.LockCommand_LOCK_UNLOCK, "1234")

// Lock
err = client.SetLock(0x12345678, pb.LockCommand_LOCK_LOCK, "")

​
Media player

​
SetMediaPlayer

Sends a media player command. Only the fields with their Has* flag set are applied. 
func (c *Client) SetMediaPlayer(key uint32, opts MediaPlayerCommandOpts) error

​
MediaPlayerCommandOpts

type MediaPlayerCommandOpts struct {
    HasCommand      bool
    Command         pb.MediaPlayerCommand
    HasVolume       bool
    Volume          float32   // 0.0–1.0
    HasMediaUrl     bool
    MediaUrl        string
    HasAnnouncement bool
    Announcement    bool
}

// Play a URL
err := client.SetMediaPlayer(0x12345678, esphome.MediaPlayerCommandOpts{
    HasCommand:  true,
    Command:     pb.MediaPlayerCommand_MEDIA_PLAYER_COMMAND_PLAY,
    HasMediaUrl: true,
    MediaUrl:    "http://example.com/stream.mp3",
})

// Set volume to 60%
err = client.SetMediaPlayer(0x12345678, esphome.MediaPlayerCommandOpts{
    HasVolume: true,
    Volume:    0.6,
})

Build docs developers (and LLMs) love

Get started for freeTalk to us