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]
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.

Abstract

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

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

MQTT Restrictions

Homie communicates through MQTT and is hence based on the basic principles of MQTT topic publication and subscription.

Topic IDs

An MQTT topic consists of one or more topic levels, separated by the slash character (/). A topic level ID MAY contain lowercase letters from a to z, numbers from 0 to 9 as well as the hyphen character (-).

A topic level ID MUST NOT start or end with a hyphen (-). The special character $ is used and reserved for Homie attributes. The underscore (_) is used and reserved for Homie node arrays.

Payload

  • Every MQTT message payload MUST be sent as a UTF-8 encoded string
  • The value published as payload MUST be valid for the respective property/attribute type as per the list below

String

  • String types are limited to 268,435,456 characters
  • An empty string (“”) is a valid payload

Integer

  • Integer types are UTF-8 encoded string literal representations of 64-bit signed whole numbers
  • Integers range from -9,223,372,036,854,775,808 (-263) to 9,223,372,036,854,775,807 (263-1)
  • The payload may only contain whole numbers and the negation character “-”. No other characters including spaces (” “) are permitted
  • A string with just a negation sign (“-”) is not a valid payload
  • An empty string (“”) is not a valid payload

Float

  • Float types are UTF-8 encoded string literal representations of 64-bit signed floating point numbers
  • Floats range from 2-1074 to (2-2-52)*21023
  • The payload may only contain whole numbers, the negation character “-”, the exponent character “e” or “E” and the decimal separator “.”, no other characters, including spaces (” “) are permitted
  • The dot character (“.”) is the decimal separator (used if necessary) and may only have a single instance present in the payload
  • Representations of numeric concepts such as “NaN” (Not a Number) and “Infinity” are not a valid payload
  • A string with just a negation sign (“-”) is not a valid payload
  • An empty string (“”) is not a valid payload

Boolean

  • Booleans must be converted to the string literals “true” or “false”
  • Representation is case sensitive, e.g. “TRUE” or “FALSE” are not valid payloads.
  • An empty string (“”) is not a valid payload

Enum

  • Enum payloads must be one of the values specified in the format definition of the property
  • Enum payloads are case sensitive, e.g. “Car” will not match a format definition of “car”
  • Payloads should have leading and trailing whitespace removed
  • An empty string (“”) is not a valid payload

Color

  • Color payload validity varies depending on the property format definition of either “rgb” or “hsv”
  • Both payload types contain comma separated whole numbers of differing restricted ranges
  • The encoded string may only contain whole numbers and the comma character “,”, no other characters are permitted, including spaces (” “)
  • Payloads for type “rgb” contains 3 comma separated values of numbers with a valid range between 0 and 255. e.g. 100,100,100
  • Payloads for type “hsv” contains 3 comma separated values of numbers. The first number has a range of 0 to 360, the second and third numbers have a range of 0 to 100. e.g. 300,50,75
  • An empty string (“”) is not a valid payload

QoS and retained messages

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.

Last will

MQTT only allows one last will message per connection. Homie requires a last will for the homie / device ID / $ready attribute, see Device Behavior. As a consequence a new MQTT connection to the broker is required per published device.

Base Topic

The root topic in this document is homie/. If this root topic does not suit your needs (in case of, e.g., a public broker or because of branding), you can choose another.

Homie controllers must by default perform auto-discovery on the wildcard topic “+/+/$homie”. Controllers are free to restrict discovery to a specific root topic, configurable by the user.

Timings

As soon as a device starts to publish any Homie related topic, it MUST finish with all topics within a timeframe of 500ms. Controllers should assume the default for topic values not received within this timeframe.

Extensions

This convention only covers discoverability of devices and its capabilities. The aim is to have standardized MQTT topics for all kind of complex scenarios. A Homie device may therefore support extensions, defined in separate documents. Every extension is identified by a unique ID and will be linked from this section.

The ID consists of the reverse domain name and a freely chosen suffix. The proper term homie is reserved and must not be used as the suffix or as part of the domain name.

For example, an organization example.org wanting to add a feature our-feature would choose the extension ID org.example.our-feature.

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.