The SDK is designed around Home Assistant MQTT Device Discovery via the Device type. Devices contain one or more Component[T Platform] components which map to entities provided by the device. The Platform interface provides basic platform information that is required to form the Device Discovery payload:

package hqtt

// Platform is the interface implemented by every MQTT Entity Component type.
type Platform interface {
    mqtt.Handler

    // MarshalDiscoveryTo marshals MQTT Device Discovery information to the specified jsontext.Encoder using the
    // provided prefix for all MQTT Topics.
    MarshalDiscoveryTo(e *jsontext.Encoder, prefix string) error

    // PlatformName returns the value for the `platform` field when configuring a component using this platform for MQTT
    // Device Discovery.
    PlatformName() string

    // Subscriptions returns the set of paho.SubscribeOptions for configured fields of this component. Only fields that
    // are properly configured should be included. Typically, each subscription is individually subscribed to, but other
    // mqtt.Subscriber implementations may choose to group topics with wildcards.
    Subscriptions(prefix string) []mqtt.Subscription
}

The following platforms are currently implemented:

• binary_sensor: platform.BinarySensor[TAttributes any]
• light: platform.Light
• sensor: platform.Sensor[TValue, TAttributes any]

You can create a Component for other MQTT Entity types by providing a type that satisfies the Platform interface, but if you find yourself implementing a core MQTT Entity type provided by Home Assistant please send a pull request to add it to the SDK!

The discovery package provides helpers for constructing minified Device Discovery payloads (including constants for abbreviated field keys). Unless you are implementing support for a new platform you will typically not need to import this package.

This package also contains a helper for watching the state of Home Assistant itself (which it publishes to homeassistant/status by default).

A subset of Home Assistant core types (e.g. Availability, Power/Switch state, etc.) are provided by the hass package.

HQTT utilizes log/slog for logging. See the log package package for details on configuring logging for the SDK.

MQTT abstractions are provided by the mqtt package. The two main types you will interact with are Value[T any] (for values that should be written to an MQTT topic), and RemoteValute[T any] (for values to be read from MQTT Subscriptions).

Values require a ValueMarshaler[T] which is used to encode the value when writing to MQTT. Typically, this is a StringMarshaler (which encodes the value as a string), or a JsonValueMarshaler (which encodes the value using its JSON representation).

RemoteValues require a ValueUnmarshaler[T], which does the same thing but in reverse.

Right now, the only officially supported client is github.com/eclipse/paho.golang/autopaho, a v5 MQTT client by Eclipse. You can implement your own adapter for any client by implementing the following interfaces from the mqtt package:

package mqtt

// Writer is the minimum abstraction around writing values to MQTT.
type Writer interface {
	// WriteTopic writes the provided value to the specified topic with the specified WriteOptions.
	WriteTopic(ctx context.Context, topic string, options WriteOptions, value []byte) error
}

// Subscriber manages MQTT Subscriptions
type Subscriber interface {
    // Subscribe configures the underlying MQTT connection to send the client messages for the provided subscriptions.
    // The provided Handler will be called for all subscribed topics in this call.
    Subscribe(ctx context.Context, handler Handler, subscriptions ...Subscription) error

    // Unsubscribe removes any subscriptions configured for the specified topics.
    Unsubscribe(ctx context.Context, topics ...string) error
}

See example/fake_light for a small example.