hass

package
v8.0.0 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[T any](e *EntityConfig[T]) (*mqttapi.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[T any](e *EntityConfig[T]) (*mqttapi.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[T any](e *EntityConfig[T]) (*mqttapi.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[T any] struct {
	Origin             *Origin `json:"origin,omitempty"`
	Device             *Device `json:"device,omitempty"`
	UnitOfMeasurement  string  `json:"unit_of_measurement,omitempty"`
	StateClass         string  `json:"state_class,omitempty"`
	CommandTopic       string  `json:"command_topic,omitempty"`
	StateTopic         string  `json:"state_topic"`
	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"`
	DeviceClass        string  `json:"device_class,omitempty"`
	// contains filtered or unexported fields
}

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

type EntityConfig 

type EntityConfig[T any] struct {
	Entity             *Entity[T]
	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. Specify the type T to indicate the type of value this entity uses, which will be used to configure any additional fields/parameters that need to be created for the entity type. For example, for a number entity, specifying T as int will ensure the min, max and step parameters are also treated as ints.

func NewEntityByID 

func NewEntityByID[T any](id, app, prefix string) *EntityConfig[T]

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[T any](name, app, prefix string) *EntityConfig[T]

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[T]) AsBinarySensor 

func (e *EntityConfig[T]) AsBinarySensor() *EntityConfig[T]

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

func (*EntityConfig[T]) AsButton 

func (e *EntityConfig[T]) AsButton() *EntityConfig[T]

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

func (*EntityConfig[T]) AsNumber 

func (e *EntityConfig[T]) AsNumber(step, min, max T, mode NumberMode) *EntityConfig[T]

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

func (*EntityConfig[T]) AsSensor 

func (e *EntityConfig[T]) AsSensor() *EntityConfig[T]

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

func (*EntityConfig[T]) GetTopics 

func (e *EntityConfig[T]) 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[T]) WithAttributesCallback 

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

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[T]) WithAttributesTemplate 

func (e *EntityConfig[T]) WithAttributesTemplate(t string) *EntityConfig[T]

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

func (*EntityConfig[T]) WithCommandCallback 

func (e *EntityConfig[T]) WithCommandCallback(c func(mqtt.Client, mqtt.Message)) *EntityConfig[T]

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[T]) WithDefaultOriginInfo 

func (e *EntityConfig[T]) WithDefaultOriginInfo() *EntityConfig[T]

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

func (*EntityConfig[T]) WithDeviceClass 

func (e *EntityConfig[T]) WithDeviceClass(d string) *EntityConfig[T]

WithDeviceClass configures the Device Class for the entity.

func (*EntityConfig[T]) WithDeviceInfo 

func (e *EntityConfig[T]) WithDeviceInfo(d *Device) *EntityConfig[T]

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

func (*EntityConfig[T]) WithIcon 

func (e *EntityConfig[T]) WithIcon(i string) *EntityConfig[T]

WithIcon adds an icon to the entity.

func (*EntityConfig[T]) WithOriginInfo 

func (e *EntityConfig[T]) WithOriginInfo(o *Origin) *EntityConfig[T]

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

func (*EntityConfig[T]) WithStateCallback 

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

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[T]) WithStateClassMeasurement 

func (e *EntityConfig[T]) WithStateClassMeasurement() *EntityConfig[T]

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

func (*EntityConfig[T]) WithStateClassTotal 

func (e *EntityConfig[T]) WithStateClassTotal() *EntityConfig[T]

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

func (*EntityConfig[T]) WithStateClassTotalIncreasing 

func (e *EntityConfig[T]) WithStateClassTotalIncreasing() *EntityConfig[T]

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

func (*EntityConfig[T]) WithUnits 

func (e *EntityConfig[T]) WithUnits(u string) *EntityConfig[T]

WithUnits adds a unit of measurement to the entity.

func (*EntityConfig[T]) WithValueTemplate 

func (e *EntityConfig[T]) WithValueTemplate(t string) *EntityConfig[T]

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

type NumberMode 

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 

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 

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.