Skip to main content

Node-RED - MQTT Homie Convention

Abashiri, Japan

Communication according to the MQTT HOMIE Convention​

The Homie convention defines a standardized way of how IoT devices and services announce themselves and their data on the MQTT broker. It is thereby a crucial aspect on top of the MQTT protocol for automatic discovery, configuration and usage of devices and services.

Details of the homie convention are available here Homie IoT.

I want to use Node-RED to explore how to configure devices using the Homie Convention with the goal of adding this feature to INSTAR MQTT cameras.

Set-up the Homie Nodes​

Start by installing node-red-contrib-homie-convention:

Node-RED nodes for MQTT communication according to the MQTT HOMIE convention

Let's register a Homie Device with our MQTT broker using the MQTT Explorer:

homie/TestDevices/$homie → 4.0.0
homie/TestDevices/$name → This is a Test
homie/TestDevices/$state → ready
homie/TestDevices/$extensions → ''
homie/TestDevices/$nodes → my_thermostat

homie/TestDevices/my_thermostat/$name → My thermostat
homie/TestDevices/my_thermostat/$properties → temperature

homie/TestDevices/my_thermostat/temperature → 22 
homie/TestDevices/my_thermostat/temperature/$name → Temperature
homie/TestDevices/my_thermostat/temperature/$unit → °C
homie/TestDevices/my_thermostat/temperature/$datatype → integer
homie/TestDevices/my_thermostat/temperature/$settable → true

Node-RED nodes for MQTT communication according to the MQTT HOMIE convention

It is important to add the retain flag to all topics. Otherwise the device will not be picked up by the Homie service!

Homie Node​

Configuration:

First use a homie Node to add your MQTT broker:

Node-RED nodes for MQTT communication according to the MQTT HOMIE convention

  • Name : specify a name
  • Broker : Select the mqtt broker where your device is sending messages to.

Basic Configuration (see 7.2.1 Node Attributes):

  • Node Id : Unique ID of this homie node
  • $name : Human readable name of this homie node
  • $type : Type of this homie node

Node-RED nodes for MQTT communication according to the MQTT HOMIE convention

Device Node​

Now we are ready to add our Test Device by adding a device Node. Your device should be selectable from the drop-down menu:

Node-RED nodes for MQTT communication according to the MQTT HOMIE convention

State Node​

The State Node emits a topic update when the $state topic (or any other status information) of a Homie device changes:

Node-RED nodes for MQTT communication according to the MQTT HOMIE convention

The message you receive from this node contains the topic that you have to use to either subscribe to device channel or add a MQTT-Out Node to update it's value - Note that you have to prefix this topic with homie/, e.g. homie/TestDevices/my_thermostat/temperature:

Node-RED nodes for MQTT communication according to the MQTT HOMIE convention

You can now inject a number on msg.payload to the MQTT node and see that the state node will register the change and emit the state update:

Node-RED nodes for MQTT communication according to the MQTT HOMIE convention