The Homie convention
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.
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
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.
An ID MAY contain only lowercase letters from
z, numbers from
9, and it MAY contain
-, but MUST NOT start or end with a
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.
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 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:
|$homie||Device → Controller||Version of the Homie convention the device conforms to||Yes||Yes|
|$online||Device → Controller||
|$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
|$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
|$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
|$implementation/#||Controller → Device or Device → Controller||You can use any subtopics of
||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 IDis the ID of the node, which must be unique on a per-device basis, and which adhere to the ID format.
propertyis 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:
|$type||Device → Controller||Type of the node||Yes||Yes|
|$properties||Device → Controller||Properties the node exposes, with format
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
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, 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
Homie defines a broadcast channel, so a controller is able to broadcast a message to every Homie devices:
levelis 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.