Changes
Commits
| Commit title | Date | Hash |
|---|---|---|
| Add MIT LICENSE - closes #21 | 2017-04-28 10:06:43 +0200 | 3bcbb01 |
| :memo: Add link to hodmin cli-client (#19) | 2017-04-17 22:15:19 +0200 | f137694 |
| :memo: Fix typo in README.md (#20) | 2017-04-17 22:14:44 +0200 | ec0b666 |
| :memo: Add note that the v2 might still change before final release | 2017-02-13 10:12:11 +0100 | 279f55d |
| :art: Fix backticks inside table | 2016-11-16 19:52:15 +0100 | bff4047 |
| :sparkles: Add format of $mac | 2016-11-16 19:51:26 +0100 | c9b402c |
:sparkles: Say $online must be sent last |
2016-11-16 12:33:46 +0100 | 23f4f8f |
| :sparkles: Add MAC address | 2016-11-16 12:25:31 +0100 | b4ce39d |
:bug: Remove old $ota left-over |
2016-11-16 12:21:42 +0100 | 724dfc5 |
| :sparkles: Add firmware checksum | 2016-11-16 12:19:50 +0100 | 284a1f9 |
| :art: Create a stats device property - fix #8 | 2016-10-26 16:40:44 +0200 | 2e28318 |
| :fire: Remove $ota - now implementation specific | 2016-10-24 16:46:27 +0200 | 9f8a584 |
| :sparkles: Make $signal specify an interval too - fix #8 | 2016-10-24 15:58:56 +0200 | b5f27f0 |
| :docs: Add reference to homie-python (#9) | 2016-10-17 22:37:35 +0200 | c181ec0 |
| Center title | 2016-10-12 19:46:47 +0200 | 860b26a |
| Add ID format section and cosmetic tweaks | 2016-10-11 13:13:07 +0200 | 7f5e582 |
| Make banner transparent | 2016-10-10 10:23:02 +0200 | b2a1931 |
Replace devices base topic by homie |
2016-10-03 09:59:09 +0200 | b0ec78f |
| Add broadcast channel | 2016-09-07 19:36:51 +0200 | cd84f93 |
| Add range properties | 2016-08-27 11:17:48 +0200 | 2d5e7fe |
| Remove useless $nodes | 2016-08-19 14:52:04 +0200 | 3bba8d3 |
| Add $type and $properties to node | 2016-08-19 14:48:23 +0200 | d92ceb9 |
| Remove old $reset property | 2016-08-16 18:47:49 +0200 | 675f0aa |
| Cosmetic changes and typo fixes | 2016-08-16 00:31:00 +0200 | d5f4ad1 |
| Allow implementation-specific properties | 2016-08-15 00:39:32 +0200 | 62bc55d |
| Fix typos | 2016-08-13 11:31:40 +0200 | 14f9d81 |
| First v2 changes | 2016-08-13 11:26:27 +0200 | 658f2b3 |
Differences
| v1.5.0 | v2.0.0 | ||||
|---|---|---|---|---|---|
| n | 3 | version: v1.5.0 | n | 3 | version: v2.0.0 |
| 4 | releasedate: 19. June 2016 | 4 | releasedate: 28. April 2017 | ||
| n | 13 | 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. | n | 13 | 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. |
| 14 | |||||
| 15 | ## QoS and retained messages | ||||
| 16 | |||||
| 17 | Homie devices communicate through MQTT. | ||||
| 18 | |||||
| 19 | 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. | ||||
| 20 | |||||
| 21 | ## ID format | ||||
| 22 | |||||
| 23 | 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 `-`. | ||||
| n | 17 | Homie devices communicate through MQTT. | n | 27 | 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. |
| n | 19 | 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. | n | 29 | * `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](#id-format). |
| 20 | |||||
| 21 | * `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 `-`. | ||||
| n | 25 | * `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: | n | 33 | * `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: |
| n | n | 41 | <th>Required</th> | ||
| 42 | </tr> | ||||
| 43 | <tr> | ||||
| 44 | <td>$homie</td> | ||||
| 45 | <td>Device → Controller</td> | ||||
| 46 | <td>Version of the Homie convention the device conforms to</td> | ||||
| 47 | <td>Yes</td> | ||||
| 48 | <td>Yes</td> | ||||
| n | 37 | <td><code>true</code> when the device is online, <code>false</code> when the device is offline (through LWT)</td> | n | 53 | <td><code>true</code> when the device is online, <code>false</code> 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</td> |
| 54 | <td>Yes</td> | ||||
| n | n | 62 | <td>Yes</td> | ||
| n | 51 | </tr> | n | 69 | <td>Yes</td> |
| 52 | <tr> | 70 | </tr> | ||
| 71 | <tr> | ||||
| 72 | <td>$mac</td> | ||||
| 73 | <td>Device → Controller</td> | ||||
| 74 | <td>Mac address of the device network interface. The format MUST be of the type <code>A1:B2:C3:D4:E5:F6</code></td> | ||||
| 75 | <td>Yes</td> | ||||
| 76 | <td>Yes</td> | ||||
| 77 | </tr> | ||||
| 78 | <tr> | ||||
| 53 | <td>$uptime</td> | 79 | <td>$stats/uptime</td> | ||
| n | 57 | </tr> | n | 83 | <td>Yes</td> |
| 58 | <tr> | 84 | </tr> | ||
| 85 | <tr> | ||||
| 59 | <td>$signal</td> | 86 | <td>$stats/signal</td> | ||
| n | 63 | </tr> | n | 90 | <td>No, this is not applicable to an Ethernet connected device for example</td> |
| 64 | <tr> | 91 | </tr> | ||
| 92 | <tr> | ||||
| 93 | <td>$stats/interval</td> | ||||
| 94 | <td>Device → Controller</td> | ||||
| 95 | <td>Interval in seconds at which the <code>$stats/uptime</code> and <code>$stats/signal</code> are refreshed</td> | ||||
| 96 | <td>Yes</td> | ||||
| 97 | <td>Yes</td> | ||||
| 98 | </tr> | ||||
| 99 | <tr> | ||||
| 65 | <td>$fwname</td> | 100 | <td>$fw/name</td> | ||
| n | 67 | <td>Name of the firmware running on the device. This name MAY be composed of lowercase letters from <code>a</code> to <code>z</code>, numbers from <code>0</code> to <code>9</code>, and it MAY contain <code>-</code>, but MUST NOT start or end with a <code>-</code></td> | n | 102 | <td>Name of the firmware running on the device. Allowed characters are the same as the device ID</td> |
| n | 69 | </tr> | n | 104 | <td>Yes</td> |
| 70 | <tr> | 105 | </tr> | ||
| 106 | <tr> | ||||
| 71 | <td>$fwversion</td> | 107 | <td>$fw/version</td> | ||
| n | 75 | </tr> | n | 111 | <td>Yes</td> |
| 76 | <tr> | 112 | </tr> | ||
| 77 | <td>$nodes</td> | ||||
| 78 | <td>Device → Controller</td> | ||||
| 79 | <td>Nodes the device has, with format <code>id:type</code> separated by a <code>,</code> if there are multiple nodes</td> | ||||
| 80 | <td>Yes</td> | ||||
| 81 | </tr> | 113 | <tr> | ||
| 114 | <td>$fw/checksum</td> | ||||
| 115 | <td>Device → Controller</td> | ||||
| 116 | <td>MD5 checksum of the firmware running on the device</td> | ||||
| 117 | <td>Yes</td> | ||||
| 118 | <td>No, depending of your implementation</td> | ||||
| 82 | <tr> | 119 | </tr> | ||
| 120 | <tr> | ||||
| 121 | <td>$implementation</td> | ||||
| 122 | <td>Device → Controller</td> | ||||
| 123 | <td>An identifier for the Homie implementation (example <code>esp8266</code>)</td> | ||||
| 83 | <td>$ota</td> | 124 | <td>Yes</td> | ||
| 84 | <td>Controller → Device</td> | 125 | <td>Yes</td> | ||
| 85 | <td>Latest OTA version available for the device</td> | 126 | </tr> | ||
| 127 | <tr> | ||||
| 128 | <td>$implementation/#</td> | ||||
| 129 | <td>Controller → Device or Device → Controller</td> | ||||
| 130 | <td>You can use any subtopics of <code>$implementation</code> for anything related to your specific Homie implementation.</td> | ||||
| n | 87 | </tr> | n | ||
| 88 | <tr> | ||||
| 89 | <td>$ota/+</td> | ||||
| 90 | <td>Controller → Device or Device → Controller</td> | ||||
| 91 | <td>You can use any subtopics of `$ota` for anything related to your specific OTA implementation.</td> | ||||
| 92 | <td>Yes or No, depending of your implementation</td> | ||||
| 93 | </tr> | ||||
| 94 | <tr> | ||||
| 95 | <td>$reset</td> | ||||
| 96 | <td>Controller → Device</td> | ||||
| 97 | <td><code>true</code> when the controller wants the device to reset its configuration. <code>false</code> otherwise. When the device receives a <code>true</code>, it should replace the retained message with a <code>false</code> before resetting</td> | ||||
| 98 | <td>Yes</td> | 132 | <td>No</td> | ||
| n | 105 | devices/686f6d6965/$online → true | n | 139 | homie/686f6d6965/$online → true |
| 106 | devices/686f6d6965/$name → Bedroom temperature sensor | 140 | homie/686f6d6965/$name → Bedroom temperature sensor | ||
| 107 | devices/686f6d6965/$localip → 192.168.0.10 | 141 | homie/686f6d6965/$localip → 192.168.0.10 | ||
| 108 | devices/686f6d6965/$signal → 72 | 142 | homie/686f6d6965/$signal → 72 | ||
| 109 | devices/686f6d6965/$fwname → 1.0.0 | 143 | homie/686f6d6965/$fw/name → 1.0.0 | ||
| 110 | devices/686f6d6965/$fwversion → 1.0.0 | 144 | homie/686f6d6965/$fw/version → 1.0.0 | ||
| 111 | devices/686f6d6965/$nodes → temperature:temperature,humidity:humidity | ||||
| n | 113 | n | |||
| 114 | And it would receive: | ||||
| 115 | |||||
| 116 | ``` | ||||
| 117 | devices/686f6d6965/$ota ← 1.0.1 | ||||
| 118 | devices/686f6d6965/$reset ← false | ||||
| 119 | ``` | ||||
| 120 | |||||
| 121 | At this point, your device would understand there is an OTA update available, as `$ota` is different from `$version`. | ||||
| n | 125 | * `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. | n | 149 | * `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](#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](#id-format). |
| 150 | |||||
| 151 | Properties starting with a `$` are special properties. It must be one of the following: | ||||
| 152 | |||||
| 153 | <table> | ||||
| 154 | <tr> | ||||
| 155 | <th>Property</th> | ||||
| 156 | <th>Direction</th> | ||||
| 157 | <th>Description</th> | ||||
| 158 | <th>Retained</th> | ||||
| 159 | <th>Required</th> | ||||
| 160 | </tr> | ||||
| 161 | <tr> | ||||
| 162 | <td>$type</td> | ||||
| 163 | <td>Device → Controller</td> | ||||
| 164 | <td>Type of the node</td> | ||||
| 165 | <td>Yes</td> | ||||
| 166 | <td>Yes</td> | ||||
| 167 | </tr> | ||||
| 168 | <tr> | ||||
| 169 | <td>$properties</td> | ||||
| 170 | <td>Device → Controller</td> | ||||
| 171 | <td>Properties the node exposes, with format <code>id</code> separated by a <code>,</code> if there are multiple nodes. For ranges, define the range after the <code>id</code>, within <code>[]</code> and separated by a <code>-</code>. For settable properties, add <code>:settable</code> to the <code>id</code></td> | ||||
| 172 | <td>Yes</td> | ||||
| 173 | <td>Yes</td> | ||||
| 174 | </tr> | ||||
| 175 | </table> | ||||
| n | n | 180 | homie/686f6d6965/temperature/$type → temperature | ||
| 181 | homie/686f6d6965/temperature/$properties → degrees,unit | ||||
| 182 | homie/686f6d6965/temperature/unit → c | ||||
| 130 | devices/686f6d6965/temperature/temperature → 12.07 | 183 | homie/686f6d6965/temperature/degrees → 12.07 | ||
| 131 | devices/686f6d6965/humidity/humidity → 79 | ||||
| 132 | ``` | ||||
| n | n | 185 | homie/686f6d6965/humidity/$type → humidity | ||
| 186 | homie/686f6d6965/humidity/$properties → percentage | ||||
| 187 | homie/686f6d6965/humidity/percentage → 79 | ||||
| 188 | ``` | ||||
| 189 | |||||
| 190 | 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: | ||||
| 191 | |||||
| 192 | ``` | ||||
| 193 | homie/ledstrip-device/ledstrip/$type → ledstrip | ||||
| 194 | homie/ledstrip-device/ledstrip/$properties → led[1-3]:settable | ||||
| 195 | homie/ledstrip-device/ledstrip/led_1 → on | ||||
| 196 | homie/ledstrip-device/ledstrip/led_2 → off | ||||
| 197 | homie/ledstrip-device/ledstrip/led_3 → on | ||||
| 198 | ``` | ||||
| 199 | |||||
| 134 | * `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. | 200 | * `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. | ||
| n | 136 | 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. | n | 202 | 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. |
| n | 138 | For example, an `homielight` device exposing a `light` node would subscribe to `devices/homielight/light/on/set` and it would receive: | n | 204 | For example, a `kitchen-light` device exposing a `light` node would subscribe to `homie/kitchen-light/light/on/set` and it would receive: |
| n | 141 | devices/homielight/light/on/set ← true | n | 207 | homie/kitchen-light/light/on/set ← true |
| t | 147 | devices/homielight/light/on → true | t | 213 | homie/kitchen-light/light/on → true |
| 214 | ``` | ||||
| 215 | |||||
| 216 | ### Broadcast channel | ||||
| 217 | |||||
| 218 | Homie defines a broadcast channel, so a controller is able to broadcast a message to every Homie devices: | ||||
| 219 | |||||
| 220 | * `homie` / `$broadcast` / **`level`**: `level` is an arbitrary broadcast identifier. It must adhere to the [ID format](#id-format). | ||||
| 221 | |||||
| 222 | 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. | ||||
| 223 | |||||
| 224 | ``` | ||||
| 225 | homie/$broadcast/alert ← Intruder detected | ||||