Commands

Reference for all command methods to control ESPHome entities

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,
})