homieiot/convention

Homie: An MQTT Convention for IoT/M2M

License: CCA 4.0
Version: [develop] [v1.5.0] [v2.0.0] [v2.0.1] [v3.0.0] [v3.0.1] [v4.0.0]
Changes: [Diff to previous]
Release date: 24. March 2018
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.

Table of Contents

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
$nodes Device → Controller Nodes the device exposes, with format id separated by a , if there are multiple nodes. Yes Yes

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.