Homie Convention - v4.0.0

Homie Release V4.0

With v3.0.0 we introduced the release with the words "a new beginning for Homie as a stable and reliable base".
And we want to build up on this with a new, fully backwards compatible release. With one noteworthy exception that forced us to raise the major version number, according to SemVer.

Arrays got removed

No use case could justify their existence and we found that they do not offer any performance / bandwidth benefits over just defining nodes with properties. Instead the community, especially Homie Controller developers, found Arrays to be an implementation burden. No longer! If you don't find a Homie Controller implementation for your favorite programming language, no is the time to dive in.

$stats changed

The Homie specification no longer defines any topics in $stats. It was always a controversal subject in the community, starting with the fact that Homie attributes (those topic parts that start with a dollar character)
are not meant to have subtopics.

Extensions

The extension mechanism that was first introduced in V3.0.1 has been put in use with V4. The removed $stats subtopics are now specified in a V2/v3-compat extension.

An extension is a specification on its own which allows for more modularity in the implementation space.
A Homie Controller is not required to support any extensions, but if it does, it might help to render Homie Nodes and Properties in a more intended way.

Find more information about extensions on the website:
https://homieiot.github.io/extensions/.

Happy coding!

-- The Homie Community

Homie Convention - v3.0.1

This release adds supports for stateless properties (#108 - closes #70).

Homie Convention - v3.0.0

The first release under the Homie IoT organization.

Increased demand in a convention for the IoT over MQTT awakened a few discussions surrounding Homie as the probably most mature convention out there. The release of v3.0.0 marks a new beginning for Homie as a stable and reliable base for MQTT based IoT communication.

Quite a few improvements since the v2.0.0 release render the convention more versatile for general IoT systems and enable fully automatic discovery of nodes by controller entities.

Starting with v3.0.0 the Homie Convention will now follow a rolling release development model following the semver scheme to support rapid advancements.

v2.0.1

• Added $nodes to device discoverability

Homie Convention - v2.0.0

The Homie convention

Version: 2.0.0

Homie is a lightweight MQTT convention for the IoT.

You can find an implementation of the Homie convention:

• An Arduino library built for the ESP8266: marvinroger/homie-esp8266
• WIP - An opinionated Web UI built with Node.js: marvinroger/homie-server
• WIP - Some Node-RED nodes for automation: marvinroger/node-red-contrib-homie
• A Python-implementation for Raspberry Pi & Co.: jalmeroth/homie-python.
• A Ruby-implementation including a command-line-client with OTA-Support for easy adminstration of multiple Homie-devices: rttools/hodmin

Background

An instance of a physical piece of hardware (an Arduino, an ESP8266...) is called a device. A device has device properties, like the current local IP, the Wi-Fi signal, etc. A device can expose multiple nodes. For example, a weather device might expose a temperature node and an humidity node. A node can have multiple node properties. The temperature node might for example expose a degrees property containing the actual temperature, and an unit property. Node properties can be ranges. For example, if you have a LED strip, you can have a node property led ranging from 1 to 10, to control LEDs independently. Node properties can be settable. For example, you don't want your degrees property to be settable in case of a temperature sensor: this depends on the environment and it would not make sense to change it. However, you will want the degrees property to be settable in case of a thermostat.

QoS and retained messages

Homie devices communicate through MQTT.

The nature of the Homie convention makes it safe about duplicate messages, so the recommended QoS for reliability is QoS 1. All messages MUST be sent as retained, UNLESS stated otherwise.

ID format

An ID MAY contain only lowercase letters from a to z, numbers from 0 to 9, and it MAY contain -, but MUST NOT start or end with a -.

Convention

To efficiently parse messages, Homie defines a few rules related to topic names. The base topic you will see in the following convention will be homie/. You can however choose whatever base topic you want.

• homie / device ID: this is the base topic of a device. Each device must have an unique device ID which adhere to the ID format.

Device properties

• homie / device ID / $ device property: a topic starting with a $ after the base topic of a device represents a device property. A device property MUST be one of these:

Property	Direction	Description	Retained	Required
$homie	Device → Controller	Version of the Homie convention the device conforms to	Yes	Yes
$online	Device → Controller	true when the device is online, false when the device is offline (through LWT). When sending the device is online, this message must be sent last, to indicate every other required messages are sent and the device is ready	Yes	Yes
$name	Device → Controller	Friendly name of the device	Yes	Yes
$localip	Device → Controller	IP of the device on the local network	Yes	Yes
$mac	Device → Controller	Mac address of the device network interface. The format MUST be of the type A1:B2:C3:D4:E5:F6	Yes	Yes
$stats/uptime	Device → Controller	Time elapsed in seconds since the boot of the device	Yes	Yes
$stats/signal	Device → Controller	Integer representing the Wi-Fi signal quality in percentage if applicable	Yes	No, this is not applicable to an Ethernet connected device for example
$stats/interval	Device → Controller	Interval in seconds at which the $stats/uptime and $stats/signal are refreshed	Yes	Yes
$fw/name	Device → Controller	Name of the firmware running on the device. Allowed characters are the same as the device ID	Yes	Yes
$fw/version	Device → Controller	Version of the firmware running on the device	Yes	Yes
$fw/checksum	Device → Controller	MD5 checksum of the firmware running on the device	Yes	No, depending of your implementation
$implementation	Device → Controller	An identifier for the Homie implementation (example esp8266)	Yes	Yes
$implementation/#	Controller → Device or Device → Controller	You can use any subtopics of $implementation for anything related to your specific Homie implementation.	Yes or No, depending of your implementation	No

For example, a device with an ID of 686f6d6965 with a temperature and an humidity sensor would send:

homie/686f6d6965/$online → true
homie/686f6d6965/$name → Bedroom temperature sensor
homie/686f6d6965/$localip → 192.168.0.10
homie/686f6d6965/$signal → 72
homie/686f6d6965/$fw/name → 1.0.0
homie/686f6d6965/$fw/version → 1.0.0

Node properties

• homie / device ID / node ID / property: node ID is the ID of the node, which must be unique on a per-device basis, and which adhere to the ID format. property is the property of the node that is getting updated, which must be unique on a per-node basis, and which adhere to the ID format.

Properties starting with a $ are special properties. It must be one of the following:

Property	Direction	Description	Retained	Required
$type	Device → Controller	Type of the node	Yes	Yes
$properties	Device → Controller	Properties the node exposes, with format id separated by a , if there are multiple nodes. For ranges, define the range after the id, within [] and separated by a -. For settable properties, add :settable to the id	Yes	Yes

For example, our 686f6d6965 above would send:

homie/686f6d6965/temperature/$type → temperature
homie/686f6d6965/temperature/$properties → degrees,unit
homie/686f6d6965/temperature/unit → c
homie/686f6d6965/temperature/degrees → 12.07

homie/686f6d6965/humidity/$type → humidity
homie/686f6d6965/humidity/$properties → percentage
homie/686f6d6965/humidity/percentage → 79

A LED strip would look like this. Note that the topic for a range properties is the name of the property followed by a _ and the index getting updated:

homie/ledstrip-device/ledstrip/$type → ledstrip
homie/ledstrip-device/ledstrip/$properties → led[1-3]:settable
homie/ledstrip-device/ledstrip/led_1 → on
homie/ledstrip-device/ledstrip/led_2 → off
homie/ledstrip-device/ledstrip/led_3 → on

• homie / device ID / node ID / property / set: the device can subscribe to this topic if the property is settable from the controller, in case of actuators.

Homie is state-based. You don't tell your smartlight to turn on, but you tell it to put it's on state to true. This especially fits well with MQTT, because of retained message.

For example, a kitchen-light device exposing a light node would subscribe to homie/kitchen-light/light/on/set and it would receive:

homie/kitchen-light/light/on/set ← true

The device would then turn on the light, and update its on state. This provides pessimistic feedback, which is important for home automation.

homie/kitchen-light/light/on → true

Broadcast channel

Homie defines a broadcast channel, so a controller is able to broadcast a message to every Homie devices:

• homie / $broadcast / level: level is an arbitrary broadcast identifier. It must adhere to the ID format.

For example, you might want to broadcast an alert event with the alert reason as the payload. Devices are then free to react or not. In our case, every buzzer of your home automation system would start buzzing.

homie/$broadcast/alert ← Intruder detected

Any other topic is not part of the Homie convention.

Homie Convention - v1.5.0

Homie

Homie is a lightweight MQTT convention for the IoT.

You can find an implementation of the Homie convention:

• A device Arduino library built for the ESP8266 at marvinroger/homie-esp8266
• An opinionated Web UI built with Node.js at marvinroger/homie-server
• Some Node-RED nodes for automation at marvinroger/node-red-contrib-homie

Background

An instance of a physical piece of hardware (an Arduino, an ESP8266...) is called a device. A device has device properties, like the current local IP, the Wi-Fi signal, etc. A device can expose multiple nodes. For example, a weather device might expose a temperature node and an humidity node. A node can have multiple node properties. The temperature node might for example expose a temperature property containing the actual temperature, and an unit property. Properties can be settable. For example, you don't want your temperature property to be settable in case of a temperature sensor: this depends on the environment and it would not make sense to change it. However, you will want the temperature property to be settable in case of a thermostat.

Convention

Homie devices communicate through MQTT.

To efficiently parse messages, Homie defines a few rules related to topic names. The base topic you will see in the following lines will be devices/. You can customize this base topic if it fits better to your needs.

• devices / device ID: this is the base topic name. Each device must have a unique device ID. This ID MAY be composed of lowercase letters from a to z, numbers from 0 to 9, and it MAY contain -, but MUST NOT start or end with a -.

Device properties

• devices / device ID / $ device property: a property starting with a $ at the third level of the path is related to the device. The property MUST be one of these:

Property	Direction	Description	Retained
$online	Device → Controller	true when the device is online, false when the device is offline (through LWT)	Yes
$name	Device → Controller	Friendly name of the device	Yes
$localip	Device → Controller	IP of the device on the local network	Yes
$uptime	Device → Controller	Time elapsed in seconds since the boot of the device	Yes
$signal	Device → Controller	Integer representing the Wi-Fi signal quality in percentage if applicable	Yes
$fwname	Device → Controller	Name of the firmware running on the device. This name MAY be composed of lowercase letters from a to z, numbers from 0 to 9, and it MAY contain -, but MUST NOT start or end with a -	Yes
$fwversion	Device → Controller	Version of the firmware running on the device	Yes
$nodes	Device → Controller	Nodes the device has, with format id:type separated by a , if there are multiple nodes	Yes
$ota	Controller → Device	Latest OTA version available for the device	Yes or No, depending of your implementation
$ota/+	Controller → Device or Device → Controller	You can use any subtopics of `$ota` for anything related to your specific OTA implementation.	Yes or No, depending of your implementation
$reset	Controller → Device	true when the controller wants the device to reset its configuration. false otherwise. When the device receives a true, it should replace the retained message with a false before resetting	Yes

For example, a device with an ID of 686f6d6965 with a temperature and an humidity sensor would send:

devices/686f6d6965/$online → true
devices/686f6d6965/$name → Bedroom temperature sensor
devices/686f6d6965/$localip → 192.168.0.10
devices/686f6d6965/$signal → 72
devices/686f6d6965/$fwname → 1.0.0
devices/686f6d6965/$fwversion → 1.0.0
devices/686f6d6965/$nodes → temperature:temperature,humidity:humidity

And it would receive:

devices/686f6d6965/$ota ← 1.0.1
devices/686f6d6965/$reset ← false

At this point, your device would understand there is an OTA update available, as $ota is different from $version.

Node properties

• devices / device ID / node ID / property: node ID is the ID of the node, as defined in the $nodes device property. property is the property of the node that is getting updated.

For example, our 686f6d6965 above would send:

devices/686f6d6965/temperature/temperature → 12.07
devices/686f6d6965/humidity/humidity → 79

• devices / device ID / node ID / property / set: the device can subscribe to this topic if the property is settable from the controller, in case of actuators.

Homie is state-based. You don't tell your smarlight to turn on, but you tell it to put it's on state to true. This especially fits well with MQTT, because of retained message.

For example, an homielight device exposing a light node would subscribe to devices/homielight/light/on/set and it would receive:

devices/homielight/light/on/set ← true

The device would then turn on the light, and update its on state. This provides pessimistic feedback, which is important for home automation.

devices/homielight/light/on → true

Any other topic is not part of the Homie convention.