hass

package
v7.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 1, 2024 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatID 

func FormatID(s string) string

FormatID will take a string s and format it as snake_case. The new string is then an appropriate format to be used as a unique ID in Home Assistant.

func FormatName 

func FormatName(s string) string

FormatName will take a string s and format it with appropriate spacing between words and capitalised the first letter of each word. For example someString becomes Some String. The new string is then an appropriate format to be used as a name in Home Assistant.

func MarshalConfig 

func MarshalConfig(e *EntityConfig) (*mqtt.Msg, error)

MarshalConfig will generate an *mqtt.Msg for a given entity, that can be used to publish the required config for the entity to the MQTT bus.

func MarshalState 

func MarshalState(e *EntityConfig) (*mqtt.Msg, error)

MarshalState will generate an *mqtt.Msg for a given entity, that can be used to publish the entity's state to the MQTT bus.

func MarshalSubscription 

func MarshalSubscription(e *EntityConfig) (*mqtt.Subscription, error)

MarshallSubscription will generate an *mqtt.Subscription for a given entity, which can be used to subscribe to an entity's command topic and execute a callback on messages.

Types

type Device 

type Device struct {
	Name          string   `json:"name"`
	Manufacturer  string   `json:"manufacturer,omitempty"`
	Model         string   `json:"model,omitempty"`
	HWVersion     string   `json:"hw_version,omitempty"`
	SWVersion     string   `json:"sw_version,omitempty"`
	URL           string   `json:"configuration_url,omitempty"`
	SuggestedArea string   `json:"suggested_area,omitempty"`
	Identifiers   []string `json:"identifiers"`
	Connections   []string `json:"connections,omitempty"`
}

Device contains information about the device an entity is a part of to tie it into the device registry in Home Assistant.

type Entity 

type Entity struct {
	Origin             *Origin `json:"origin,omitempty"`
	Device             *Device `json:"device,omitempty"`
	DeviceClass        string  `json:"device_class,omitempty"`
	StateTopic         string  `json:"state_topic"`
	StateClass         string  `json:"state_class,omitempty"`
	CommandTopic       string  `json:"command_topic,omitempty"`
	UnitOfMeasurement  string  `json:"unit_of_measurement,omitempty"`
	ValueTemplate      string  `json:"value_template"`
	UniqueID           string  `json:"unique_id"`
	Name               string  `json:"name"`
	EntityCategory     string  `json:"entity_category,omitempty"`
	Icon               string  `json:"icon,omitempty"`
	AttributesTopic    string  `json:"json_attributes_topic,omitempty"`
	AttributesTemplate string  `json:"json_attributes_template,omitempty"`
	NumberEntity
}

Entity represents a generic entity in Home Assistant. The fields are common across any specific entity.

type EntityConfig 

type EntityConfig struct {
	Entity             *Entity
	App                string
	CommandCallback    func(MQTT.Client, MQTT.Message)
	StateCallback      func(args ...any) (json.RawMessage, error)
	AttributesCallback func() (json.RawMessage, error)
	ConfigTopic        string
	// contains filtered or unexported fields
}

EntityConfig is a type used by apps to represent a Home Assistant entity and some additional fields for manipulating that entity in the app.

func NewEntityByID 

func NewEntityByID(id, app, prefix string) *EntityConfig

NewEntityByID will create a new entity and config based off the given id and app. Use this when you want to ensure the exact format of the id for the underlying sensor in Home Assistant. The name will be derived from the id.

func NewEntityByName 

func NewEntityByName(name, app, prefix string) *EntityConfig

NewEntityByName will create a new entity and config based off the given name and app. Use this function where you don't care about the id of the underlying sensor in Home Assistant. The id will be derived from the name by converting it to snake_case.

func (*EntityConfig) AsBinarySensor 

func (e *EntityConfig) AsBinarySensor() *EntityConfig

AsBinarySensor will configure appropriate MQTT topics to represent a Home Assistant binary_sensor.

func (*EntityConfig) AsButton 

func (e *EntityConfig) AsButton() *EntityConfig

AsButton will configure appropriate MQTT topics to represent a Home Assistant button.

func (*EntityConfig) AsNumber added in v7.2.0 

func (e *EntityConfig) AsNumber(step float64, min float64, max float64, mode NumberMode) *EntityConfig

AsNumber will configure appropriate MQTT topics to represent a Home Assistant number. See also https://www.home-assistant.io/integrations/number.mqtt/

func (*EntityConfig) AsSensor 

func (e *EntityConfig) AsSensor() *EntityConfig

AsSensor will configure appropriate MQTT topics to represent a Home Assistant sensor.

func (*EntityConfig) GetTopics added in v7.2.0 

func (e *EntityConfig) GetTopics() *Topics

GetTopics returns a Topic struct containing the topics configured for this entity. If an entity does not have a particular topic (due to not having some functionality), the topic value will be an empty string.

func (*EntityConfig) WithAttributesCallback 

func (e *EntityConfig) WithAttributesCallback(c func() (json.RawMessage, error)) *EntityConfig

WithAttributesCallback will add the passed in function as the callback action to be run whenever the attributes of the entity are needed. If this callback is to be used, then the WithAttributesTopic() builder function should also be called to set-up the attributes topic.

func (*EntityConfig) WithAttributesTemplate 

func (e *EntityConfig) WithAttributesTemplate(t string) *EntityConfig

WithAttributesTemplate configures the passed in template to be used to extract the value of the attributes in Home Assistant.

func (*EntityConfig) WithCommandCallback 

func (e *EntityConfig) WithCommandCallback(c func(MQTT.Client, MQTT.Message)) *EntityConfig

WithCommandCallback will add the passed in function as the callback action to be run when a message is received on the command topic of the entity. It doesn't make sense to add this for entities that don't have a command topic, like regular sensors.

func (*EntityConfig) WithDefaultOriginInfo 

func (e *EntityConfig) WithDefaultOriginInfo() *EntityConfig

WithOriginInfo adds a pre-filled origin that references go-hass-agent to the entity config.

func (*EntityConfig) WithDeviceClass 

func (e *EntityConfig) WithDeviceClass(d string) *EntityConfig

WithDeviceClass configures the Device Class for the entity.

func (*EntityConfig) WithDeviceInfo 

func (e *EntityConfig) WithDeviceInfo(d *Device) *EntityConfig

WithDeviceInfo adds the passed in device info to the entity config.

func (*EntityConfig) WithIcon 

func (e *EntityConfig) WithIcon(i string) *EntityConfig

WithIcon adds an icon to the entity

func (*EntityConfig) WithOriginInfo 

func (e *EntityConfig) WithOriginInfo(o *Origin) *EntityConfig

WithOriginInfo adds the passed in origin info to the entity config.

func (*EntityConfig) WithStateCallback 

func (e *EntityConfig) WithStateCallback(c func(args ...any) (json.RawMessage, error)) *EntityConfig

WithStateCallback will add the passed in function as the callback action to be run whenever the state of the entity is needed. It doesn't make sense to add this for entities that don't report a state, like buttons. It might not be useful to use this where you have a single state that represents many entities. In such cases, it would be better to manually send the state in your own code.

func (*EntityConfig) WithStateClassMeasurement 

func (e *EntityConfig) WithStateClassMeasurement() *EntityConfig

WithStateClassMeasurement configures the State Class for the entity to be "measurement".

func (*EntityConfig) WithStateClassTotal 

func (e *EntityConfig) WithStateClassTotal() *EntityConfig

WithStateClassMeasurement configures the State Class for the entity to be "total".

func (*EntityConfig) WithStateClassTotalIncreasing 

func (e *EntityConfig) WithStateClassTotalIncreasing() *EntityConfig

WithStateClassMeasurement configures the State Class for the entity to be "total_increasing".

func (*EntityConfig) WithUnits 

func (e *EntityConfig) WithUnits(u string) *EntityConfig

WithUnits adds a unit of measurement to the entity.

func (*EntityConfig) WithValueTemplate 

func (e *EntityConfig) WithValueTemplate(t string) *EntityConfig

WithValueTemplate configures the passed in template to be used to extract the value of the entity in Home Assistant.

type NumberEntity added in v7.2.0 

type NumberEntity struct {
	Min  float64 `json:"min,omitempty"`
	Max  float64 `json:"max,omitempty"`
	Mode string  `json:"mode,omitempty"`
	Step float64 `json:"step,omitempty"`
}

NumberEntity represents the fields specifically for number entities in Home Assistant.

type NumberMode added in v7.2.0 

type NumberMode int

NumberMode reflects how this number entity is displayed in Home Assistant. It can be either automatically chosen or explicitly set to display as a slider or box. 

const (
	// NumberAuto will tell Home Assistant to automatically select how the number is displayed.
	NumberAuto NumberMode = 0 // auto
	// NumberBox will tell Home Assistant to display this number as a box.
	NumberBox NumberMode = 1 // box
	// NumberSlider will tell Home Assistant to display this number as a slider.
	NumberSlider NumberMode = 2 // slider
)

func (NumberMode) String added in v7.2.0 

func (i NumberMode) String() string

type Origin 

type Origin struct {
	Name    string `json:"name,omitempty"`
	Version string `json:"sw_version,omitempty"`
	URL     string `json:"support_url,omitempty"`
}

Origin contains information about the app that is responsible for the entity. It is used by Home Assistant for logging and display purposes.

type Topics added in v7.2.0 

type Topics struct {
	Config     string
	Command    string
	State      string
	Attributes string
}

Topics is a helper struct that is returned when an EntityConfig is created containing the names of important topics on the MQTT bus related to the entity. Apps can store these topics for later retrieval and usage (for example, to update state topics or listen to command topics).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.