platform

package
v0.0.0-...-45466fc Latest Latest
Warning

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

 Go to latest Published: Nov 22, 2025 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package platform contains implementations for various Home Assistant MQTT platforms. See the Home Assistant docs for a list of supported platforms: https://www.home-assistant.io/integrations/mqtt. Note: Not all platforms may be implemented by hqtt.

Each hqtt platform implementation satisfies the hqtt.Platform interface. The PlatformName method returns the Home Assistant platform name (e.g. Light's PlatformName method returns the string "light").

Not all fields for a given platform implementation are required by Home Assistant. Required fields will be tagged with `hqtt:"required"`. and checked when marshaling for discovery.

Index

Constants

This section is empty.

Variables

View Source 
var (
	RGBMarshaler mqtt.ValueMarshaler[RGB] = func(v RGB) ([]byte, error) {
		return []byte(fmt.Sprintf("%d,%d,%d", v.R, v.G, v.B)), nil
	}
	RGBUnmarshaler mqtt.ValueUnmarshaler[RGB] = func(bytes []byte) (RGB, error) {
		parts := strings.Split(string(bytes), ",")
		if len(parts) != 3 {
			return RGB{}, fmt.Errorf("invalid RGB representation: %s", bytes)
		}

		r, errR := strconv.ParseUint(parts[0], 10, 8)
		g, errG := strconv.ParseUint(parts[1], 10, 8)
		b, errB := strconv.ParseUint(parts[2], 10, 8)

		return RGB{uint8(r), uint8(g), uint8(b)}, errors.Join(errR, errG, errB)
	}
)

Functions

func NewSensorAttributeValue 

func NewSensorAttributeValue[TAttributes any](topic string, marshaler mqtt.ValueMarshaler[TAttributes]) *mqtt.Value[TAttributes]

NewSensorAttributeValue constructs a mqtt.Value for the provided attribute type. If marshaler is nil, it uses mqtt.JsonValueMarshaler to marshal values.

Types

type BinarySensor 

type BinarySensor[TAttributes any] struct {
	Sensor[hass.PowerState, TAttributes]

	// For sensors that only send on state updates (like PIRs), this variable sets a delay in seconds after which the
	// sensor’s state will be updated back to off by Home Assistant.
	OffDelay time.Duration
}

BinarySensor is a Sensor that uses hass.PowerState for its state type (i.e. hass.PowerStateOn or hass.PowerStateOff).

See Sensor for details about state attributes, and https://www.home-assistant.io/integrations/binary_sensor.mqtt/ for complete documentation.

func NewBinarySensor 

func NewBinarySensor[TAttributes any](state *mqtt.Value[hass.PowerState], attrs *mqtt.Value[TAttributes]) *BinarySensor[TAttributes]

func (*BinarySensor[TAttributes]) MarshalDiscoveryTo 

func (s *BinarySensor[TAttributes]) MarshalDiscoveryTo(e *jsontext.Encoder, prefix string) error

func (*BinarySensor[TAttributes]) PlatformName 

func (s *BinarySensor[TAttributes]) PlatformName() string

func (*BinarySensor[TAttributes]) ServeMQTT 

func (s *BinarySensor[TAttributes]) ServeMQTT(w mqtt.Writer, topic string, message []byte)

func (*BinarySensor[TAttributes]) Subscriptions 

func (s *BinarySensor[TAttributes]) Subscriptions(prefix string) []mqtt.Subscription

type HueSat 

type HueSat struct {
	Hue        float64
	Saturation float64
}

HueSat holds Hue and Saturation values for this component. It implements slog.LogValuer.

func (HueSat) LogValue 

func (h HueSat) LogValue() slog.Value

type Light 

type Light struct {
	// Defines when on the payload_on is sent.
	OnCommandType LightOnCommandType

	// Flag that defines if switch works in optimistic mode.
	Optimistic bool

	// The current state of the Light
	State *mqtt.Value[hass.PowerState]
	// Home Assistant will write commands for this entity to this value
	Command *mqtt.RemoteValue[hass.PowerState] `hqtt:"required"`

	// Custom values to use for payload commands
	CustomPowerStateValues hass.CustomPowerState

	// The Color Mode currently in use by the light. If this is not configured, it will be automatically set in Home
	// Assistant according to the last received valid color or color temperature. The unit used is mireds, or if
	// ColorTemperatureInKelvin is set to true, in Kelvin.
	ColorMode *mqtt.Value[hass.ColorMode]
	// Home Assistant will write the desired color mode to this value
	ColorModeCommand *mqtt.RemoteValue[hass.ColorMode]
	// The color modes supported by this light
	SupportedColorModes []hass.ColorMode

	// The current brightness of the light
	Brightness *mqtt.Value[uint]
	// Home Assistant will write desired brightness to this value
	BrightnessCommand *mqtt.RemoteValue[uint]
	// Defines the maximum brightness value (i.e., 100%). HomeAssistant will use 255 if not otherwise specified.
	BrightnessScale uint

	// The current color temperature of the light
	ColorTemperature *mqtt.Value[uint]
	// Home Assistant will write desired color temperature to this value
	ColorTemperatureCommand *mqtt.RemoteValue[uint]
	// Whether color temperature is in Kelvin (true) or mireds (false)
	ColorTemperatureInKelvin bool
	// The maximum color temperature in Kelvin. Defaults to 6535.
	MaxKelvin uint
	// The minimum color temperature in Kelvin. Defaults to 2000.
	MinKelvin uint
	// The maximum color temperature in mireds.
	MaxMireds uint
	// The minimum color temperature in mireds.
	MinMireds uint

	// The current Hue and Saturation values for this light
	HueSat *mqtt.Value[HueSat]
	// Home Assistant will write the desired Hue and Saturation values to this value
	HueSatCommand *mqtt.RemoteValue[HueSat]

	// The current XY values for this light
	XY *mqtt.Value[XY]
	// Home Assistant will write desired XY values to this value
	XYCommand *mqtt.RemoteValue[XY]

	// The current RGB Value for this light
	RGB *mqtt.Value[RGB]
	// Home Assistant will write desired RGB values to this value
	RGBCommand *mqtt.RemoteValue[RGB]

	// The current RGBW Value for this light
	RGBW *mqtt.Value[RGBW]
	// Home Assistant will write desired RGBW values to this value
	RGBWCommand *mqtt.RemoteValue[RGBW]

	// The current RGBWW Value for this light
	RGBWW *mqtt.Value[RGBWW]
	// Home Assistant will write desired RGBWW values to this value
	RGBWWCommand *mqtt.RemoteValue[RGBWW]

	// Home Assistant writes brightness values to this value when the light should operate in white mode.
	WhiteBrightnessCommand *mqtt.RemoteValue[uint]
	// The maximum white level (i.e., 100%) of this light. Defaults to 255 if not set.
	WhiteScale uint

	// The current effect the light is displaying
	Effect *mqtt.Value[string]
	// Home Assistant will write the desired effect to this value
	EffectCommand *mqtt.RemoteValue[string]
	// The list of possible effects this device supports
	PossibleEffects []string
}

Light is a hqtt.Platform that implements the light.mqtt integration for Home Assistant.

See https://www.home-assistant.io/integrations/light.mqtt/

func (*Light) MarshalDiscoveryTo 

func (l *Light) MarshalDiscoveryTo(e *jsontext.Encoder, prefix string) error

func (*Light) PlatformName 

func (l *Light) PlatformName() string

func (*Light) ServeMQTT 

func (l *Light) ServeMQTT(w mqtt.Writer, topic string, payload []byte)

ServeMQTT handles the mqtt payload received on the specified topic suffix. It will route the payload to the first non-nil mqtt.RemoveValue that has a matching topic for the light. It is up to the user to ensure each configured mqtt.RemoteValue has a unique Topic configured.

func (*Light) Subscriptions 

func (l *Light) Subscriptions(prefix string) []mqtt.Subscription

type LightOnCommandType 

type LightOnCommandType string

LightOnCommandType configures how Home Assistant sends style and power commands via MQTT for this component. 

const (
	// LightOnCommandTypeLast instructs Home Assistant to send any style (brightness, color, etc) topics first and then
	// a payload_on to the Light.Command. This is the default behavior.
	LightOnCommandTypeLast    LightOnCommandType = "last"
	DefaultLightOnCommandType                    = LightOnCommandTypeLast
	// LightOnCommandTypeFirst instructs Home Assistant to send the payload_on and then any style topics. Using
	LightOnCommandTypeFirst LightOnCommandType = "first"
	// LightOnCommandTypeBrightness instructs Home Assistant to only send brightness commands instead of the payload_on
	// to turn the light on.
	LightOnCommandTypeBrightness LightOnCommandType = "brightness"
)

type RGB 

type RGB struct {
	R, G, B uint8
}

RGB holds 8-bit Red, Green, and Blue values for a Light. It implements fmt.Stringer and slog.LogValuer.

func (RGB) LogValue 

func (r RGB) LogValue() slog.Value

func (RGB) String 

func (r RGB) String() string

type RGBW 

type RGBW struct {
	RGB
	W uint8
}

RGBW holds an 8-bit White value in addition to RGB values for a Light. It implements fmt.Stringer and slog.LogValuer.

func (RGBW) LogValue 

func (r RGBW) LogValue() slog.Value

func (RGBW) String 

func (r RGBW) String() string

type RGBWW 

type RGBWW struct {
	RGBW
	WW uint8
}

RGBWW holds an additional 8-bit White value in addition to RGBW values for a Light. It implements fmt.Stringer and slog.LogValuer.

func (RGBWW) LogValue 

func (r RGBWW) LogValue() slog.Value

func (RGBWW) String 

func (r RGBWW) String() string

type Sensor 

type Sensor[TValue, TAttributes any] struct {
	// If set, it defines the number of seconds after the sensor’s state expires if it’s not updated. After expiry, the
	// sensor’s state becomes unavailable. By default, the sensor’s state never expires. Note that when a sensor’s value
	// was sent retained to the MQTT broker, the last value sent will be replayed by the MQTT broker when Home Assistant
	// restarts or is reloaded. As this could cause the sensor to become available with an expired state, it is not
	// recommended to retain the sensor’s state payload at the MQTT broker. Home Assistant will store and restore the
	// sensor’s state for you and calculate the remaining time to retain the sensor’s state before it becomes
	// unavailable.
	ExpireMeasurementsAfter time.Duration

	// Instruct Home Assistant to calculate update events even if the value hasn’t changed. Useful if you want to have
	// meaningful value graphs in history.
	ForceUpdate bool

	// Attributes exposes state attributes for this sensor. Writes to this value imply ForceUpdate of the current sensor
	// state when a message is received on this topic by Home Assistant. For standard marshaling, use
	// mqtt.JsonValueMarshaler for the mqtt.ValueMarshaler for this value. When using a custom marshaler, the resulting
	// byte slice must be a json string.
	Attributes *mqtt.Value[TAttributes]

	// List of allowed sensor state value. The sensor’s device_class must be set to enum. The options option cannot be
	// used together with state_class or unit_of_measurement.
	//
	// Note: The Home Assistant documentation states "an empty list is not allowed". Empty / nil slices will be omitted
	// when marshaling discovery information.
	EnumOptions []TValue

	// The number of decimals which should be used in the sensor’s state after rounding.
	SuggestedDisplayPrecision uint

	// The hass.StateClass of the sensor.
	StateClass hass.StateClass

	// The current value of the sensor
	State *mqtt.Value[TValue] `hqtt:"required"`

	// Defines the units used by this sensor
	// TODO: Can/should we type this and grab constants from Home Assistant?
	UnitOfMeasurement string
}

Sensor is a hqtt.Platform that implements the sensor.mqtt integration for Home Assistant. The state of this sensor has a type of TValue, and attributes for state have a type of TAttributes.

See the Home Assistant documentation for more details: https://www.home-assistant.io/integrations/sensor.mqtt/.

func (*Sensor[TValue, TAttributes]) MarshalDiscoveryTo 

func (s *Sensor[TValue, TAttributes]) MarshalDiscoveryTo(e *jsontext.Encoder, prefix string) error

func (*Sensor[TValue, TAttributes]) PlatformName 

func (s *Sensor[TValue, TAttributes]) PlatformName() string

func (*Sensor[TValue, TAttributes]) ServeMQTT 

func (s *Sensor[TValue, TAttributes]) ServeMQTT(_ mqtt.Writer, _ string, _ []byte)

func (*Sensor[TValue, TAttributes]) Subscriptions 

func (s *Sensor[TValue, TAttributes]) Subscriptions(_ string) []mqtt.Subscription

type XY 

type XY struct {
	X float64
	Y float64
}

func (XY) LogValue 

func (xy XY) LogValue() slog.Value

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.