From 730357e0a2133216460085f230ce10b0876261c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Gr=C3=A4ff?= <david.graeff@web.de>
Date: Sat, 27 Oct 2018 15:22:20 +0200
Subject: [PATCH] Stateful attribute for properties (#108)

* Update README.md

Stateful attribute for properties

Signed-off: David Graeff <david.graeff@web.de>

* Update README.md

Introduce the "retained" flag for properties to express "event"-like, stateless properties. Closes #70.
---
 README.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/README.md b/README.md
index 4e7dead..8bd163d 100644
--- a/README.md
+++ b/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>