Changes

Changes from v2.0.1 to v3.0.0

Commits

Commit title	Date	Hash
Merge pull request #71 from homieiot/rolling-releases	2018-03-25 08:55:18 +1100	96c3086
Add info regarding rolling releases	2018-03-24 15:18:37 +0100	c5ad0b2
Add NodeJS implementation	2018-03-24 11:25:36 +1100	110b68f
Small Readme version fix	2018-03-21 09:00:35 +1100	508f6ae
Fix Versioning.	2018-03-16 07:55:10 +1100	09c84e4
Merge pull request #67 from marvinroger/v2	2018-03-12 12:01:13 +1100	0b90e74
Update Version	2018-03-12 12:00:15 +1100	be4d750
Merge branch ‘redesign’ into v2	2018-03-12 11:59:28 +1100	e25c5dc
added micropython-homie	2018-03-12 11:54:43 +1100	00285cb
Merge pull request #64 from microhomie/v2	2018-02-17 21:12:45 +1100	0a9e88b
Remove WIP state	2018-02-12 10:49:02 +0100	85d6a1f
Add MicroPython implementation	2018-02-10 11:56:40 +0100	d7392c0
Merge pull request #63 from nerdfirefighter/redesign	2018-02-03 18:44:59 +1100	b071d29
Typo Fix	2018-02-02 20:46:05 +1100	25b727f
Merge pull request #1 from marvinroger/redesign	2018-02-02 20:43:27 +1100	71b15b9
Update Branch	2018-01-24 12:08:45 +1100	755b994
Merge pull request #60 from nerdfirefighter/v2	2018-01-24 11:50:03 +1100	0482588
Update README.md	2018-01-17 22:10:47 +1100	97e5ec9
:bug: Fix typos (#55)	2018-01-02 15:25:25 +0100	2247839
:art: Update ToC	2017-11-13 16:34:15 +0100	8d33c76
:art: Clean up MQTT restrictions (#47)	2017-11-13 16:30:32 +0100	3e51c9e
:art: Cosmetic change	2017-11-13 16:22:54 +0100	d977ceb
:fire: Make properties optional with default (#48)	2017-11-10 12:12:22 +0100	a19b81a
:art: Add TOC	2017-11-06 15:39:44 +0100	1b60390
:sparkles: Add $state topic (#50)	2017-11-06 15:11:13 +0100	e355f4e
:art: Small comestic change	2017-09-25 22:00:16 +0200	ddbe9c9
:sparkles: Add a link to the tags	2017-09-25 21:57:58 +0200	e0e3bad
:memo: Add Node.js implementation (#42)	2017-09-21 03:22:32 -0700	e5dcd7e
:sparkles: Allow possibility to know when a device is fully discovered	2017-08-11 20:02:20 +0200	0003daa
:bug: Fix node attributes array	2017-08-11 12:55:26 +0200	90f94c6
:memo: Make clear all values are string	2017-08-11 12:40:44 +0200	11cd9ff
:sparkles: Add color datatype	2017-08-11 12:34:47 +0200	a17b8b3
:fire: Replace property arrays to node arrays	2017-08-11 12:14:11 +0200	460e547
:memo: Change to a car example	2017-08-11 11:46:49 +0200	949ad7d
:art: Moved statistics to seperate section and made some clarifications, when to send device attributes. (#40)	2017-08-10 17:43:27 +0200	7ab2e87
:fire: $unit should not be mandatory (#39)	2017-08-08 11:14:43 +0200	1a5d314
:art: Improve example presentation with strings and java syntax (#36)	2017-08-07 18:39:11 +0200	d81a00a
:memo: Add example for implementation (#37)	2017-08-07 17:35:18 +0200	2be405c
:fire: $unit should not be mandatory (#35)	2017-08-07 15:43:33 +0200	04441dc
:sparkles: Add optional stats properties	2017-08-06 14:29:31 +0200	08666c3
:art: Rearrange and clarify topology (#31)	2017-08-06 14:17:35 +0200	15e8df0
:memo: Add Motivation chapter (#29)	2017-08-05 19:16:02 +0200	1e33ab8
:memo: Add implementations file	2017-08-04 16:38:43 +0200	e87738f
:fire: Move implementations on another page	2017-08-04 16:38:00 +0200	cf92268
:bug: Fix all examples	2017-08-04 16:30:26 +0200	65a91f9
:bug: Use more adequate examples for nodes	2017-08-04 16:05:25 +0200	d10e380
:sparkles: Add shared array attributes	2017-08-04 15:58:41 +0200	b7e1b6b
:art: Make the $format regex simple	2017-08-04 15:43:33 +0200	20c0c13
:fire: Remove $signal and	2017-08-04 15:39:59 +0200	081c5af
:art: Make the structure more consistent	2017-08-04 15:33:49 +0200	4d49797
:art: Clarify background	2017-08-04 15:17:09 +0200	c8a270a
:art: Make each paragraph line on a newline	2017-08-04 15:10:11 +0200	cae1fa5
:sparkles: Make properties discoverable (#27)	2017-08-04 13:56:14 +0200	779093a

Differences

+version: v3.0.0
+releasedate: 25. March 2018
+## Table of Contents
+* [Motivation](#motivation)
+* [MQTT restrictions](#mqtt-restrictions)
+  * [Topic IDs](#topic-ids)
+  * [Payload](#payload)
+  * [QoS and retained messages](#qos-and-retained-messages)
+* [Topology](#topology)
+  * [Base topic](#base-topic)
+  * [Devices](#devices)
+    * [Device attributes](#device-attributes)
+    * [Device behavior](#device-behavior)
+    * [Device statistics](#device-statistics)
+  * [Nodes](#nodes)
+    * [Node attributes](#node-attributes)
+  * [Properties](#properties)
+    * [Property attributes](#property-attributes)
+  * [Arrays](#arrays)
+  * [Broadcast channel](#broadcast-channel)
+## Motivation
+The Homie convention strives to be a **communication definition on top of MQTT** between IoT devices and controlling entities.
+> [MQTT](http://mqtt.org) is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol.
+> It was designed as an extremely lightweight publish/subscribe messaging transport.
+MQTT supports easy and unrestricted message-based communication.
+However, MQTT doesn't define the structure and content of these messages and their relation.
+An IoT device publishes data and provides interaction possibilities but a controlling entity will need to be specifically configured to be able to interface with the device.
+The Homie convention defines a **standardized way** of how IoT devices and services announce themselves and their data on the communication channel.
+The Homie convention is thereby a crucial aspect in the support of **automatic discovery, configuration and usage** of devices and services over the MQTT protocol.
+----
+## MQTT Restrictions
+Homie communicates through [MQTT](http://mqtt.org) 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 string.
+If a value is of a numeric data type, it MUST be converted to string.
+Booleans MUST be converted to "true" or "false".
+All values MUST be encoded as UTF-8 strings.
+### 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.
+## Topology
+**Devices:**
+An instance of a physical piece of hardware is called a *device*.
+For example, a car, an Arduino/ESP8266 or a coffee machine.
+**Nodes:**
+A *device* can expose multiple *nodes*.
+Nodes are independent or logically separable parts of a device.
+For example, a car might expose a `wheels` node, an `engine` node and a `lights` node.
+Nodes can be **arrays**.
+For example, instead of creating two `lights` node to control front lights and back lights independently, we can set the `lights` node to be an array with two elements.
+**Properties:**
+A *node* can have multiple *properties*.
+Properties represent basic characteristics of the node/device, often given as numbers or finite states.
+For example the `wheels` node might expose an `angle` property.
+The `engine` node might expose a `speed`, `direction` and `temperature` property.
+The `lights` node might expose an `intensity` and a `color` property.
+Properties can be **settable**.
+For example, you don't want your `temperature` property to be settable in case of a temperature sensor (like the car example), but to be settable in case of a thermostat.
+**Attributes:**
+*Devices, nodes and properties* have specific *attributes* characterizing them.
+Attributes are represented by topic identifier starting with `$`.
+The precise definition of attributes is important for the automatic discovery of devices following the Homie convention.
+Examples: A device might have an `IP` attribute, a node will have a `name` attribute, and a property will have a `unit` attribute.
+----
+### Base Topic
+The base topic you will see in the following convention will be `homie/`.
+If this base topic does not suit your needs (in case of, e.g., a public broker), you can choose another.
+Be aware, that only the default base topic `homie/` is eligible for automatic discovery by third party controllers.
+----
+### Devices
+* `homie` / **`device ID`**: this is the base topic of a device.
+Each device must have a unique device ID which adhere to the [ID format](#topic-ids).
+#### Device Attributes
+* `homie` / `device ID` / **`$device-attribute`**:
+When the MQTT connection to the broker is established or re-established, the device MUST send its attributes to the broker immediately.
+    <th>Topic</th>
+    <td>$state</td>
+    <td>Device → Controller</td>
+    <td>
+      See <a href="#device-behavior">Device behavior</a>
+    </td>
+    <td>Yes</td>
+    <td>Yes</td>
+  </tr>
+  <tr>
+    <td>$nodes</td>
+    <td>Device → Controller</td>
+    <td>
+      Nodes the device exposes, with format <code>id</code> separated by a <code>,</code> if there are multiple nodes.
+      To make a node an array, append <code>[]</code> to the ID.
+    </td>
+    <td>Yes</td>
+    <td>Yes</td>
+    <td>$stats</td>
+    <td>Device → Controller</td>
+    <td>Specify all optional stats that the device will announce, with format <code>stats</code> separated by a <code>,</code> if there are multiple stats. See next section for an example</td>
+    <td>Yes</td>
+    <td>Yes</td>
+  </tr>
+  <tr>
+    <td>$stats/interval</td>
+    <td>Interval in seconds at which the device refreshes its <code>$stats/+</code>: See next section for details about statistical attributes</td>
+For example, a device with an ID of `super-car` that comprises off a `wheels`, `engine` and a `lights` node would send:
+```java
+homie/super-car/$homie → "2.1.0"
+homie/super-car/$name → "Super car"
+homie/super-car/$localip → "192.168.0.10"
+homie/super-car/$mac → "DE:AD:BE:EF:FE:ED"
+homie/super-car/$fw/name → "weatherstation-firmware"
+homie/super-car/$fw/version → "1.0.0"
+homie/super-car/$nodes → "wheels,engine,lights[]"
+homie/super-car/$implementation → "esp8266"
+homie/super-car/$stats/interval → "60"
+homie/super-car/$state → "ready"
+#### Device Behavior
+The `$state` device attribute represents, as the name suggests, the current state of the device.
+There are 6 different states:
+* **`init`**: this is the state the device is in when it is connected to the MQTT broker, but has not yet sent all Homie messages and is not yet ready to operate.
+This is the first message that must that must be sent.
+* **`ready`**: this is the state the device is in when it is connected to the MQTT broker, has sent all Homie messages and is ready to operate.
+You have to send this message after all other announcements message have been sent.
+* **`disconnected`**: this is the state the device is in when it is cleanly disconnected from the MQTT broker.
+You must send this message before cleanly disconnecting.
+* **`sleeping`**: this is the state the device is in when the device is sleeping.
+You have to send this message before sleeping.
+* **`lost`**: this is the state the device is in when the device has been "badly" disconnected.
+You must define this message as LWT.
+* **`alert`**: this is the state the device is when connected to the MQTT broker, but something wrong is happening. E.g. a sensor is not providing data and needs human intervention.
+You have to send this message when something is wrong.
+#### Device Statistics
+* `homie` / `device ID` / `$stats`/ **`$device-statistic-attribute`**:
+The `$stats/` hierarchy allows to send device attributes that change over time. The device MUST send them every `$stats/interval` seconds.
+    <th>Topic</th>
+    <td>$stats/uptime</td>
+    <td>Device → Controller</td>
+    <td>Time elapsed in seconds since the boot of the device</td>
+    <td>Yes</td>
+    <td>Yes</td>
+  </tr>
+  <tr>
+    <td>$stats/signal</td>
+    <td>Device → Controller</td>
+    <td>Signal strength in %</td>
+    <td>Yes</td>
+    <td>No</td>
+  </tr>
+  <tr>
+    <td>$stats/cputemp</td>
+    <td>Device → Controller</td>
+    <td>CPU Temperature in °C</td>
+    <td>Yes</td>
+    <td>No</td>
+  </tr>
+  <tr>
+    <td>$stats/cpuload</td>
+    <td>Device → Controller</td>
+    <td>
+      CPU Load in %.
+      Average of last <code>$interval</code> including all CPUs
+    </td>
+    <td>Yes</td>
+    <td>No</td>
+  </tr>
+  <tr>
+    <td>$stats/battery</td>
+    <td>Device → Controller</td>
+    <td>Battery level in %</td>
+    <td>Yes</td>
+    <td>No</td>
+  </tr>
+  <tr>
+    <td>$stats/freeheap</td>
+    <td>Device → Controller</td>
+    <td>Free heap in bytes</td>
+    <td>Yes</td>
+    <td>No</td>
+  </tr>
+  <tr>
+    <td>$stats/supply</td>
+    <td>Device → Controller</td>
+    <td>Supply Voltage in V</td>
+    <td>Yes</td>
+    <td>No</td>
+  </tr>
+</table>
+For example, our `super-car` device with `$stats/interval` value "60" is supposed to send its current values every 60 seconds:
+```java
+homie/super-car/$stats → "uptime,cputemp,signal,battery"
+homie/super-car/$stats/uptime → "120"
+homie/super-car/$stats/cputemp → "48"
+homie/super-car/$stats/signal → "24"
+homie/super-car/$stats/battery → "80"
+```
+----
+### Nodes
+* `homie` / `device ID` / **`node ID`**: this is the base topic of a node.
+Each node must have a unique node ID on a per-device basis which adhere to the [ID format](#topic-ids).
+#### Node Attributes
+* `homie` / `device ID` / `node ID` / **`$node-attribute`**:
+A node attribute MUST be one of these:
+<table>
+  <tr>
+    <th>Topic</th>
+    <th>Direction</th>
+    <th>Description</th>
+    <th>Retained</th>
+    <th>Required</th>
+  </tr>
+  <tr>
+    <td>$name</td>
+    <td>Device → Controller</td>
+    <td>Friendly name of the Node</td>
+    <td>Yes</td>
+    <td>Yes</td>
+  </tr>
+  <tr>
+    <td>
+      Properties the node exposes, with format <code>id</code> separated by a <code>,</code> if there are multiple nodes.
+    </td>
+    <td>Yes</td>
+    <td>Yes</td>
+  </tr>
+    <tr>
+       <td>$array</td>
+       <td>Device → Controller</td>
+       <td>Range separated by a <code>-</code>. e.g. <code>0-2</code> for an array with the indexes <code>0</code>, <code>1</code> and <code>2</code></td>
+       <td>Yes</td>
+       <td>Yes, if the node is an array</td>
+    </tr>
+For example, our `engine` node would send:
+```java
+homie/super-car/engine/$name → "Car engine"
+homie/super-car/engine/$type → "V8"
+homie/super-car/engine/$properties → "speed,direction,temperature"
+```
+----
+### Properties
+* `homie` / `device ID` / `node ID` / **`property ID`**: this is the base topic of a property.
+Each property must have a unique property ID on a per-node basis which adhere to the [ID format](#topic-ids).
+* A property value (e.g. a sensor reading) is directly published to the property topic, e.g.:
+  ```java
+  homie/super-car/engine/temperature → "21.5"
+  ```
+#### Property Attributes
+* `homie` / `device ID` / `node ID` / `property ID` / **`$property-attribute`**:
+A property attribute MUST be one of these:
+<table>
+    <tr>
+        <th>Topic</th>
+        <th>Direction</th>
+        <th>Description</th>
+        <th>Valid values</th>
+        <th>Retained</th>
+        <th>Required (Default)</th>
+    </tr>
+    <tr>
+       <td>$name</td>
+       <td>Device → Controller</td>
+       <td>Friendly name of the property.</td>
+       <td>Any String</td>
+       <td>Yes</td>
+       <td>No ("")</td>
+    </tr>
+    <tr>
+        <td>$settable</td>
+        <td>Device → Controller</td>
+        <td>Specifies whether the property is settable (<code>true</code>) or readonly (<code>false</code>)</td>
+        <td><code>true</code> or <code>false</code></td>
+        <td>Yes</td>
+        <td>No (<code>false</code>)</td>
+    </tr>
+    <tr>
+        <td>$unit</td>
+        <td>Device → Controller</td>
+        <td>
+          A string containing the unit of this property.
+          You are not limited to the recommended values, although they are the only well known ones that will have to be recognized by any Homie consumer.
+        </td>
+        <td>
+            Recommended:<br>
+            <code>°C</code> Degree Celsius<br>
+            <code>°F</code> Degree Fahrenheit<br>
+            <code>°</code> Degree<br>
+            <code>L</code> Liter<br>
+            <code>gal</code> Galon<br>
+            <code>V</code> Volts<br>
+            <code>W</code> Watt<br>
+            <code>A</code> Ampere<br>
+            <code>%</code> Percent<br>
+            <code>m</code> Meter<br>
+            <code>ft</code> Feet<br>
+            <code>Pa</code> Pascal<br>
+            <code>psi</code> PSI<br>
+            <code>#</code> Count or Amount
+        </td>
+        <td>Yes</td>
+        <td>No ("")</td>
+    </tr>
+    <tr>
+       <td>$datatype</td>
+       <td>Device → Controller</td>
+       <td>Describes the format of data.</td>
+       <td>
+         <code>integer</code>,
+         <code>float</code>,
+         <code>boolean</code>,
+         <code>string</code>,
+         <code>enum</code>,
+         <code>color</code>
+       </td>
+       <td>Yes</td>
+       <td>No (<code>string</code>)</td>
+    </tr>
+    <tr>
+       <td>$format</td>
+       <td>Device → Controller</td>
+       <td>
+        Describes what are valid values for this property.
+       </td>
+       <td>
+         <ul>
+           <li>
+             <code>from:to</code> Describes a range of values e.g. <code>10:15</code>.
+             <br>Valid for datatypes <code>integer</code>, <code>float</code>
+           </li>
+           <li>
+             <code>value,value,value</code> for enumerating all valid values.
+             Escape <code>,</code> by using <code>,,</code>. e.g. <code>A,B,C</code> or <code>ON,OFF,PAUSE</code>.
+             <br>Valid for datatypes <code>enum</code>
+           </li>
+           <li>
+             <code>regex:pattern</code> to provide a regex that can be used to match the value. e.g. <code>regex:[A-Z][0-9]+</code>.
+             <br>Valid for datatype <code>string</code>
+           </li>
+           <li>
+             <code>rgb</code> to provide colors in RGB format e.g. <code>255,255,0</code> for yellow.
+             <code>hsv</code> to provide colors in HSV format e.g. <code>60,100,100</code> for yellow.
+             <br>Valid for datatype <code>color</code>
+           </li>
+         </ul>
+       </td>
+       <td>Yes</td>
+       <td>Depends on $datatype</td>
+    </tr>
+</table>
+For example, our `temperature` property would send:
+```java
+homie/super-car/engine/temperature/$name → "Engine temperature"
+homie/super-car/engine/temperature/$settable → "false"
+homie/super-car/engine/temperature/$unit → "°C"
+homie/super-car/engine/temperature/$datatype → "float"
+homie/super-car/engine/temperature/$format → "-20:120"
+homie/super-car/engine/temperature → "21.5"
+```
+* `homie` / `device ID` / `node ID` / `property ID` / **`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 its `power` state to `on`.
+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/power/set` and it would receive:
+```java
+homie/kitchen-light/light/power/set ← "on"
+The device would then turn on the light, and update its `power` state.
+This provides pessimistic feedback, which is important for home automation.
+```java
+homie/kitchen-light/light/power → "true"
+### Arrays
+A node can be an array if you've added `[]` to its ID in the `$nodes` device attribute, and if its `$array` attribute is set to the range of the array.
+Let's consider we want to control independently the front lights and back lights of our `super-car`. Our `lights` node array would look like this. Note that the topic for an element of the array node is the name of the node followed by a `_` and the index getting updated:
+```java
+homie/super-car/$nodes → "lights[]"
+homie/super-car/lights/$name → "Lights"
+homie/super-car/lights/$properties → "intensity"
+homie/super-car/lights/$array → "0-1"
+homie/super-car/lights/intensity/$name → "Intensity"
+homie/super-car/lights/intensity/$settable → "true"
+homie/super-car/lights/intensity/$unit → "%"
+homie/super-car/lights/intensity/$datatype → "integer"
+homie/super-car/lights/intensity/$format → "0:100"
+homie/super-car/lights_0/$name → "Back lights"
+homie/super-car/lights_0/intensity → "0"
+homie/super-car/lights_1/$name → "Front lights"
+homie/super-car/lights_1/intensity → "100"
+```
+Note that you can name each element in your array individually ("Back lights", etc.).
+----
+### Broadcast Channel
+* `homie` / `$broadcast` / **`level`**: `level` is an arbitrary broadcast identifier.
+It must adhere to the [ID format](#topic-ids).
+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.
+```java
+homie/$broadcast/alert ← "Intruder detected"