esphome

README

esphome

ESPHome client.

Documentation

Index

• Constants
• Variables
• func Discover(devices chan<- *Device) error
• func DiscoverService(devices chan<- *Device, service, domain string, timeout time.Duration) error
• type BinarySensor
• type Camera
  • func (entity *Camera) Image() (image.Image, error)
  • func (entity *Camera) ImageStream() (<-chan image.Image, error)
  • func (entity *Camera) LastFrame() time.Time
  • func (entity *Camera) Stream() (<-chan *bytes.Buffer, error)
• type Client
  • func Dial(addr string) (*Client, error)
  • func DialTimeout(addr string, timeout time.Duration) (*Client, error)
  • func (c *Client) Camera() (Camera, error)
  • func (c *Client) Close() error
  • func (c *Client) DeviceInfo() (DeviceInfo, error)
  • func (c *Client) Entities() Entities
  • func (c *Client) LastMessage() time.Time
  • func (c *Client) Login(password string) error
  • func (c *Client) Logs(level LogLevel) (chan LogEntry, error)
  • func (c *Client) Ping() error
  • func (c *Client) PingTimeout(timeout time.Duration) error
• type Climate
• type ClimateCapabilities
• type ClimateFanMode
• type ClimateMode
• type ClimateSwingMode
• type Cover
• type Device
  • func (d *Device) Addr() string
• type DeviceInfo
• type Entities
• type Entity
• type Fan
• type Light
  • func (entity Light) SetBrightness(value float32) error
  • func (entity Light) SetColor(value color.Color) error
  • func (entity Light) SetEffect(effect string) error
  • func (entity Light) SetState(on bool) error
  • func (entity Light) SetWhite(value float32) error
• type LightCapabilities
• type LightState
• type LogEntry
• type LogLevel
• type Sensor
• type Switch
  • func (entity Switch) SetState(on bool) error
• type TextSensor

Constants

const (
	DefaultTimeout = 10 * time.Second
	DefaultPort    = 6053
)

Client defaults.

const (
	DefaultMDNSService = "_esphomelib._tcp"
	DefaultMDNSDomain  = "local"
	DefaultMDNSTimeout = 5 * time.Second
)

Discovery defaults.

Variables

var (
	ErrPassword = errors.New("esphome: invalid password")
	ErrTimeout  = errors.New("esphome: timeout")
	ErrObjectID = errors.New("esphome: unknown object identifier")
	ErrEntity   = errors.New("esphome: entity not found")
)

Errors.

Functions

func Discover

func Discover(devices chan<- *Device) error

Discover ESPHome deices on the network.

func DiscoverService

func DiscoverService(devices chan<- *Device, service, domain string, timeout time.Duration) error

DiscoverService is used by Discover, can be used to override the default service and domain and to customize timeouts.

Types

type BinarySensor

type BinarySensor struct {
	Entity
	DeviceClass string
	State       bool
}

BinarySensor can be pressed, released and/or clicked.

type Camera

type Camera struct {
	Entity
	// contains filtered or unexported fields
}

Camera is an ESP32 camera.

func (*Camera) Image

func (entity *Camera) Image() (image.Image, error)

Image grabs one image frame from the camera.

func (*Camera) ImageStream

func (entity *Camera) ImageStream() (<-chan image.Image, error)

ImageStream is like Stream, returning decoded frame images.

func (*Camera) LastFrame

func (entity *Camera) LastFrame() time.Time

LastFrame returns the time of the last camera frame received.

func (*Camera) Stream

func (entity *Camera) Stream() (<-chan *bytes.Buffer, error)

Stream returns a channel with raw image frame buffers.

type Client

type Client struct {
	// Info identifies this device with the ESPHome node.
	Info string

	// Timeout for read and write operations.
	Timeout time.Duration

	// Clock returns the current time.
	Clock func() time.Time
	// contains filtered or unexported fields
}

Client for an ESPHome device.

func Dial

func Dial(addr string) (*Client, error)

Dial connects to ESPHome native API on the supplied TCP address.

func DialTimeout

func DialTimeout(addr string, timeout time.Duration) (*Client, error)

DialTimeout is like Dial with a custom timeout.

func (*Client) Camera

func (c *Client) Camera() (Camera, error)

Camera returns a reference to the camera. It returns an error if no camera is found.

func (*Client) Close

func (c *Client) Close() error

Close the device connection.

func (*Client) DeviceInfo

func (c *Client) DeviceInfo() (DeviceInfo, error)

DeviceInfo queries the ESPHome device information.

func (*Client) Entities

func (c *Client) Entities() Entities

Entities returns all configured entities on the connected device.

func (*Client) LastMessage

func (c *Client) LastMessage() time.Time

LastMessage returns the time of the last message received.

func (*Client) Login

func (c *Client) Login(password string) error

Login must be called to do the initial handshake. The provided password can be empty.

func (*Client) Logs

func (c *Client) Logs(level LogLevel) (chan LogEntry, error)

Logs streams log entries.

func (*Client) Ping

func (c *Client) Ping() error

Ping the server.

func (*Client) PingTimeout

func (c *Client) PingTimeout(timeout time.Duration) error

PingTimeout is like ping with a custom timeout.

type Climate

type Climate struct {
	Entity

	// Capabilities of the entity.
	Capabilities ClimateCapabilities
}

Climate devices can represent different types of hardware, but the defining factor is that climate devices have a settable target temperature and can be put in different modes like HEAT, COOL, AUTO or OFF.

type ClimateCapabilities

type ClimateCapabilities struct {
	CurrentTemperature        bool
	TwoPointTargetTemperature bool
	Modes                     []ClimateMode
	VisualMinTemperature      float32
	VisualMaxTemperature      float32
	VisualTemperatureStep     float32
	Away                      bool
	Action                    bool
	FanModes                  []ClimateFanMode
	SwingModes                []ClimateSwingMode
}

ClimateCapabilities represents the capabilities of a climate device.

type ClimateFanMode

type ClimateFanMode int32

ClimateFanMode represents a climate fan speed.

const (
	ClimateFanModeOn ClimateFanMode = iota
	ClimateFanModeOff
	ClimateFanModeAuto
	ClimateFanModeLow
	ClimateFanModeMedium
	ClimateFanModeHigh
	ClimateFanModeMiddle
	ClimateFanModeFocus
	ClimateFanModeDiffuse
)

Climate fan modes.

type ClimateMode

type ClimateMode int32

ClimateMode represents the mode for a climate device.

const (
	ClimateModeOff ClimateMode = iota
	ClimateModeAuto
	ClimateModeCool
	ClimateModeHeat
	ClimateModeFanOnly
	ClimateModeDry
)

Climate modes.

type ClimateSwingMode

type ClimateSwingMode int32

ClimateSwingMode represents a climate (fan) swing mode.

const (
	ClimateSwingModeOff ClimateSwingMode = iota
	ClimateSwingModeBoth
	ClimateSwingModeVertical
	ClimateSwingModeHorizontal
)

Climate swing modes.

type Cover

type Cover struct {
	Entity
}

Cover device.

type Device

type Device struct {
	Name    string
	Host    string
	Port    int
	IP      net.IP
	IP6     net.IP
	Version string
	// contains filtered or unexported fields
}

Device is an ESPHome device (returned by Discover).

func (*Device) Addr

func (d *Device) Addr() string

Addr returns the device API address.

type DeviceInfo

type DeviceInfo struct {
	UsesPassword bool

	// The name of the node, given by "App.set_name()"
	Name string

	// The mac address of the device. For example "AC:BC:32:89:0E:A9"
	MacAddress string

	// A string describing the ESPHome version. For example "1.10.0"
	EsphomeVersion string

	// A string describing the date of compilation, this is generated by the compiler
	// and therefore may not be in the same format all the time.
	// If the user isn't using ESPHome, this will also not be set.
	CompilationTime string

	// The model of the board. For example NodeMCU
	Model string

	// HasDeepSleep indicates the device has deep sleep mode enabled when idle.
	HasDeepSleep bool
}

DeviceInfo contains information about the ESPHome node.

type Entities

type Entities struct {
	BinarySensor map[string]BinarySensor
	Camera       map[string]Camera
	Climate      map[string]Climate
	Cover        map[string]Cover
	Fan          map[string]Fan
	Light        map[string]Light
	Sensor       map[string]Sensor
	Switch       map[string]Switch
	TextSensor   map[string]TextSensor
}

Entities is a high level map of a device's entities.

type Entity

type Entity struct {
	Name     string
	ObjectID string
	UniqueID string
	Key      uint32
	// contains filtered or unexported fields
}

Entity is the base struct for all supported entities.

type Fan

type Fan struct {
	Entity
}

Fan device.

type Light

type Light struct {
	Entity

	Capabilities LightCapabilities
	Effects      []string

	State        LightState
	StateIsValid bool

	HandleState            func(on bool)
	HandleBrightness       func(float32)
	HandleColor            func(r, g, b, w float32)
	HandleColorTemperature func(float32)
	HandleEffect           func(string)
}

Light device.

func (Light) SetBrightness

func (entity Light) SetBrightness(value float32) error

SetBrightness sets the light's intensity (brightness).

func (Light) SetColor

func (entity Light) SetColor(value color.Color) error

SetColor sets the light's red, green and blue values.

func (Light) SetEffect

func (entity Light) SetEffect(effect string) error

SetEffect selects a preconfigured effect.

func (Light) SetState

func (entity Light) SetState(on bool) error

SetState turns the light on or off.

func (Light) SetWhite

func (entity Light) SetWhite(value float32) error

SetWhite sets the light's white value.

type LightCapabilities

type LightCapabilities struct {
	Brightness       bool
	RGB              bool
	WhiteValue       bool
	ColorTemperature bool
	MinMired         float32
	MaxMired         float32
}

LightCapabilities represents the capabilities of a Light.

type LightState

type LightState struct {
	On                      bool
	Brightness              float32
	Red, Green, Blue, White float32
	ColorTemperature        float32
	Effect                  string
}

LightState represents the state of a Light.

type LogEntry

type LogEntry struct {
	// Level of the message.
	Level LogLevel

	// Tag for the message.
	Tag string

	// Message is the raw text message.
	Message string

	// SendFailed indicates a failure.
	SendFailed bool
}

LogEntry contains a single entry in the ESPHome system log.

type LogLevel

type LogLevel int32

LogLevel represents the logger level.

const (
	LogNone LogLevel = iota
	LogError
	LogWarn
	LogInfo
	LogDebug
	LogVerbose
	LogVeryVerbose
)

Log levels.

type Sensor

type Sensor struct {
	Entity
	Icon              string
	UnitOfMeasurement string
	AccuracyDecimals  int32
	ForceUpdate       bool

	State        float32
	StateIsValid bool

	HandleState func(float32)
}

Sensor probes.

type Switch

type Switch struct {
	Entity
	Icon         string
	AssumedState bool

	// State of the switch.
	State bool

	HandleState func(bool)
}

Switch includes all platforms that should show up like a switch and can only be turned ON or OFF.

func (Switch) SetState

func (entity Switch) SetState(on bool) error

SetState updates the switch state.

type TextSensor

type TextSensor struct {
	Entity
	State        string
	StateIsValid bool
}

TextSensor is a lot like Sensor, but where the “normal” sensors only represent sensors that output numbers, this component can represent any text.