Stateful attribute for properties (#108)

* Update README.md

Stateful attribute for properties

Signed-off: David Graeff <[email protected]>

* Update README.md

Introduce the "retained" flag for properties to express "event"-like, stateless properties. Closes #70.

README.md

@@ -98,6 +98,16 @@ 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.
 
+Properties can be **retained**.
+A property is retained by default. A non-retained property would be useful for momentary events (door bell pressed).
+
+A combination of those flags compiles into this list:
+
+* **retained + non-settable**: The node publishes a property state (temperature sensor)
+* **retained + settable**: The node publishes a property state, and can receive commands for the property (by controller or other party) (lamp power)
+* **non-retained + non-settable**: The node publishes momentary events (door bell pressed)
+* **non-retained + settable**: The node publishes momentary events, and can receive commands for the property (by controller or other party) (brew coffee)
+
 **Attributes:**
 *Devices, nodes and properties* have specific *attributes* characterizing them.
 Attributes are represented by topic identifier starting with `$`.
@@ -437,6 +447,14 @@ A property attribute MUST be one of these:
         <td>Yes</td>
         <td>No (<code>false</code>)</td>
     </tr>
+    <tr>
+        <td>$retained</td>
+        <td>Device → Controller</td>
+        <td>Specifies whether the property is retained (<code>true</code>) or non-retained (<code>false</code>). Publishing to a non-retained property topic MUST always happen with the MQTT 'retain' flag off.</td>
+        <td><code>true</code> or <code>false</code></td>
+        <td>Yes</td>
+        <td>No (<code>true</code>)</td>
+    </tr>
     <tr>
         <td>$unit</td>
         <td>Device → Controller</td>