hass

Documentation

Overview

Package hass integrates with Home Assistant via the MQTT Device Tracker API. https://www.home-assistant.io/integrations/device_tracker.mqtt/

Index

• Constants
• func VendorByMAC(mac string) string
• type Attrs
• type Configuration
• type Device
• type DeviceTracker
• type Discovery
• type MQTT
  • func NewMQTT(ctx context.Context, opts MQTTOpts) (*MQTT, error)
  • func (m *MQTT) Close()
  • func (m *MQTT) ConfigTopic() string
  • func (m *MQTT) OnConnectionLost(ctx context.Context) error
  • func (m *MQTT) RegisterDeviceTracker(ctx context.Context, dsc Discovery) error
  • func (m *MQTT) StationAttributes(ctx context.Context, mac string, attrs Attrs) error
  • func (m *MQTT) StationHome(ctx context.Context, mac string) error
  • func (m *MQTT) StationNotHome(ctx context.Context, mac string) error
  • func (m *MQTT) StatusOffline(ctx context.Context) error
  • func (m *MQTT) StatusOnline(ctx context.Context) error
  • func (m *MQTT) SubscribeConfig(ctx context.Context, cb func(retained bool, cfg Configuration) error) error
  • func (m *MQTT) UnregisterDeviceTracker(ctx context.Context, mac string) error
• type MQTTOpts
• type MQTTTopics
  • func (m *MQTTTopics) Config() string
  • func (m *MQTTTopics) DeviceDiscovery(mac string) string
  • func (m *MQTTTopics) DeviceJSONAttrs(mac string) string
  • func (m *MQTTTopics) DeviceState(mac string) string
  • func (m *MQTTTopics) Will() string
• type TrackConfig

Constants

const (
	// StatusOnline is the MQTT message when wifi-presence is online.
	StatusOnline = "online"
	// StatusOffline is the MQTT message when wifi-presence is offline.
	StatusOffline = "offline"
	// PayloadHome is the MQTT message when WiFi client connects.
	PayloadHome = "connected"
	// PayloadNotHome is the MQTT message when WiFi client disconnects.
	PayloadNotHome = "not_connected"
	// SourceRouter is 'source' of the device tracker.
	SourceRouter = "router"
)

Functions

func VendorByMAC

func VendorByMAC(mac string) string

VendorByMAC performs a best-effort match of the given MAC address to known vendors/manufacturers.

Types

type Attrs

type Attrs struct {
	Name            string     `json:"name"`
	MAC             string     `json:"mac_address"`
	IsConnected     bool       `json:"is_connected"`
	APName          string     `json:"ap_name"`
	SSID            string     `json:"ssid"`
	BSSID           string     `json:"bssid"`
	ConnectedAt     *time.Time `json:"connected_at,omitempty"`
	ConnectedFor    int        `json:"connected_for,omitempty"`
	DisconnectedAt  *time.Time `json:"disconnected_at,omitempty"`
	DisconnectedFor int        `json:"disconnected_for,omitempty"`
}

Attrs are a device's attributes.

type Configuration

type Configuration struct {
	Devices []TrackConfig `json:"devices"`
}

Configuration describes the expected JSON configuration messages that are published to the config topic.

type Device

type Device struct {
	Connections  [][2]string `json:"connections"`            // A list of connections of the device to the outside world as a list of tuples [connection_type, connection_identifier]. For example the MAC address of a network interface: 'connections': ['mac', '02:5b:26:a8:dc:12'].
	Name         string      `json:"name,omitempty"`         // The name of the device.
	ViaDevice    string      `json:"via_device,omitempty"`   // The name of the device.
	Manufacturer string      `json:"manufacturer,omitempty"` // The manufacturer of the device.
}

Device is part of the DeviceTracker configuration.

type DeviceTracker

type DeviceTracker struct {
	AvailabilityTopic   string `json:"availability_topic,omitempty"`    // The MQTT topic subscribed to receive availability (online/offline) updates.
	Device              Device `json:"device,omitempty"`                // Information about the device this device tracker is a part of that ties it into the device registry. At least one of identifiers or connections must be present to identify the device.
	Icon                string `json:"icon,omitempty"`                  // Icon for the entity. https://materialdesignicons.com
	JSONAttributesTopic string `json:"json_attributes_topic,omitempty"` // The MQTT topic subscribed to receive a JSON dictionary payload and then set as device_tracker attributes. Usage example can be found in MQTT sensor documentation.
	Name                string `json:"name,omitempty"`                  // The name of the MQTT device_tracker.
	ObjectID            string `json:"object_id,omitempty"`             // Used instead of name for automatic generation of entity_id.
	PayloadAvailable    string `json:"payload_available,omitempty"`     // Default: online. The payload that represents the available state.
	PayloadHome         string `json:"payload_home,omitempty"`          // Default: home. The payload value that represents the ‘home’ state for the device.
	PayloadNotAvailable string `json:"payload_not_available,omitempty"` // Default: offline. The payload that represents the unavailable state.
	PayloadNotHome      string `json:"payload_not_home,omitempty"`      // Default: not_home. The payload value that represents the ‘not_home’ state for the device.
	QOS                 int    `json:"qos"`                             // The QoS level of the topic.
	SourceType          string `json:"source_type,omitempty"`           // Attribute of a device tracker that affects state when being used to track a person. Valid options are gps, router, bluetooth, or bluetooth_le.
	StateTopic          string `json:"state_topic"`                     // Required. The MQTT topic subscribed to receive device tracker state changes.
	UniqueID            string `json:"unique_id,omitempty"`             // An ID that uniquely identifies this device_tracker. If two device_trackers have the same unique ID, Home Assistant will raise an exception.
}

DeviceTracker is used to configure HomeAssistant to track a device.

type Discovery

type Discovery struct {
	Name string
	MAC  string
}

Discovery is used to publish Home Assistant MQTT discovery configuration.

type MQTT

type MQTT struct {
	// contains filtered or unexported fields
}

MQTT manager.

func NewMQTT

func NewMQTT(ctx context.Context, opts MQTTOpts) (*MQTT, error)

NewMQTT returns an MQTT instance using the given options.

func (*MQTT) Close

func (m *MQTT) Close()

Close the MQTT connection.

func (*MQTT) ConfigTopic

func (m *MQTT) ConfigTopic() string

ConfigTopic is the MQTT topic that SubscribeConfig will listen to.

func (*MQTT) OnConnectionLost

func (m *MQTT) OnConnectionLost(ctx context.Context) error

OnConnectionLost blocks until either the context is cancelled or when the MQTT connection is lost, in which case an error is returned.

func (*MQTT) RegisterDeviceTracker

func (m *MQTT) RegisterDeviceTracker(ctx context.Context, dsc Discovery) error

RegisterDeviceTracker publishes a message for Home Assistant to start tracking the defined device.

func (*MQTT) StationAttributes

func (m *MQTT) StationAttributes(ctx context.Context, mac string, attrs Attrs) error

StationAttributes publishes the device's attributes.

func (*MQTT) StationHome

func (m *MQTT) StationHome(ctx context.Context, mac string) error

StationHome publishes the device's state as 'home'.

func (*MQTT) StationNotHome

func (m *MQTT) StationNotHome(ctx context.Context, mac string) error

StationNotHome publishes the device's state as 'not_home'.

func (*MQTT) StatusOffline

func (m *MQTT) StatusOffline(ctx context.Context) error

StatusOffline publishes that wifi-presence is offline using the same topic as the will.

func (*MQTT) StatusOnline

func (m *MQTT) StatusOnline(ctx context.Context) error

StatusOnline publishes that wifi-presence is online using the same topic as the will.

func (*MQTT) SubscribeConfig

func (m *MQTT) SubscribeConfig(ctx context.Context, cb func(retained bool, cfg Configuration) error) error

SubscribeConfig registers the callback to receive configuration messages. The method blocks until either the provided context is cancelled, an error occurs, or the callback function returns a non-nil error.

func (*MQTT) UnregisterDeviceTracker

func (m *MQTT) UnregisterDeviceTracker(ctx context.Context, mac string) error

UnregisterDeviceTracker publishes a message for Home Assistant to stop tracking the defined device.

type MQTTOpts

type MQTTOpts struct {
	BrokerAddr         string // Required
	ClientID           string // Required
	Username, Password string // Optional

	APName          string // Required
	TopicPrefix     string // Optional
	DiscoveryPrefix string // Optional
}

MQTTOpts configured an MQTT instance.

type MQTTTopics

type MQTTTopics struct {
	Name       string
	Prefix     string
	HASSPrefix string // Optional
}

MQTTTopics configures MQTT topic generation.

func (*MQTTTopics) Config

func (m *MQTTTopics) Config() string

Config topic for configuration changes sent to wifi-presence.

func (*MQTTTopics) DeviceDiscovery

func (m *MQTTTopics) DeviceDiscovery(mac string) string

DeviceDiscovery topic for Home Assistant device tracker configuration.

func (*MQTTTopics) DeviceJSONAttrs

func (m *MQTTTopics) DeviceJSONAttrs(mac string) string

DeviceJSONAttrs topic for device's attributes.

func (*MQTTTopics) DeviceState

func (m *MQTTTopics) DeviceState(mac string) string

DeviceState topic for device's state.

func (*MQTTTopics) Will

func (m *MQTTTopics) Will() string

Will topic for the overall wifi-presence status.

type TrackConfig

type TrackConfig struct {
	Name string `json:"name"`
	MAC  string `json:"mac"`
}

TrackConfig describes a single Wifi station/device to monitor for state changes.