The Homie convention

License: CCA 4.0 Version: [develop] [v1.5.0] [v2.0.0] [v2.0.1] [v3.0.0] [v3.0.1] [v4.0.0] Release date: 19. June 2016

Frequently asked questions

How do I query/request a property?

You don’t. The MQTT protocol does not implement the request-reply but rather the publish-subscribe messaging pattern. The Homie convention follows the publish-subscribe principle by publishing data as retained messages on a regular basis. You might want to rethink the design of your application - in most scenarios a regularly updated information is sufficient.

Workaround: You are free to implement your own ideas on top of the basic structure of the Homie convention. You could either implement a get getter topic and its logic to trigger a value update, or you may exploit the concept of Homie properties and define a settable property to trigger a value update.

License

By exercising the Licensed Rights (defined on https://creativecommons.org/licenses/by/4.0/), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.

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.

Homie: An MQTT Convention for IoT/M2M