creativeprojects / go-homie

Homie for MQTT convention library

Homie convention for Go

The Homie convention defines a standardized way of how IoT devices and services announce themselves and their data on the MQTT broker.

This library is MQTT implementation agnostic: it only generates and manages topics and values, not actually sending them through the wire.

See an example on how to define a Homie device:

device := homie.NewDevice("my-sensor", "MQTT ESP8266 agent")
device.
    AddNode("bme280", "BME280 via ESP8266EX", "bme280").
    AddProperty("temperature", "Temperature", homie.TypeFloat).SetUnit("°C").Node().
    AddProperty("pressure", "Pressure", homie.TypeFloat).SetUnit("hPa").Node().
    AddProperty("humidity", "Humidity", homie.TypeFloat).SetUnit("%")

Send the Homie attributes and or values to the MQTT client:

// all homie attributes
for _, attribute := range device.GetHomieAttributes() {
    publish(attribute.Topic, attribute.Value)
}

// all property values
for _, attribute := range device.GetValues() {
    if attribute.Value != "" {
        publish(attribute.Topic, attribute.Value)
    }
}

Your publish function can use the MQTT client of your choice.

You can set a callback for sending property values for you when you set them:

func onSet(topic, value string, dataType homie.PropertyType) {
    if value == "<nil>" {
        value = ""
    }
    if value == "" && dataType != homie.TypeString {
        // don't send a blank string on anything else than a string data type
        return
    }
    publish(topic, value)
}

// either install a global callback on the device...
device.OnSet(onSet)

// ...or install the callback on this property only
device.Node("bmp280").Property("temperature").OnSet(onSet)

// new values will be published for you
device.Node("bme280").Property("temperature").Set(20.0)

Supported extensions

Legacy Firmware

See Specifications

device := NewDevice("deviceID", "deviceName")
device.AddExtension(NewLegacyFirmware("C0:FF:EE:01", "192.168.26.5", "awesome-firmware", "version"))

Legacy Stats

See Specifications

stats := NewLegacyStats()
NewDevice("deviceID", "deviceName").
    AddExtension(stats).
    OnSet(onSet)

stats.
    SetInterval(60).
    SetUptime(0)

More information

See the example

See go doc