doc: api: future: Update MQTT API

1 files changed, 17 insertions, 8 deletions

diff --git a/doc/api/future.md b/doc/api/future.md
index 7530704..bc870b8 100644
--- a/doc/api/future.md
+++ b/doc/api/future.md
@@ -99,11 +99,20 @@ receiving entity.
 The `<api-path>` is fixed by the firmware implementation. This is the only part
 noted down explicitly in the following MQTT API documentation.
 
-- read-only  `heartbeat` (period in milliseconds, "on-time" in milliseconds)
-- read-only  `contact/state` (`open`, `closed`)
-- read-only  `blind/closure` (`0`, `1`, ... `100`)
-- write-only `request/blind/closure` (`0`, `1`, ... `100`)
-- read-only  `blind/motion` (`up`, `down`, `stopped`)
-- write-only `request/blind/motion` (`up`, `down`, `stopped`)
-- write-only `update/trigger`
-- read-only  `update/required` (`true`, `false`)
+These are the topics to which the device publishes. Users should not publish to
+these and only subscribe.
+
+- `heartbeat` QoS 0 not retained (period in milliseconds, "on-time" in milliseconds)
+- `update/required` QoS 2 not retained (`true`, `false`)
+- `contact/state` QoS 1 retained (`open`, `closed`)
+- `blind/closure` QoS 1 retained (`0`, `1`, ... `100`)
+- `blind/motion` QoS 1 retained (`up`, `down`, `stopped`)
+
+These are the topics the device subscribes to. Users can publish there and
+optionally subscribe to them to see messages from other users if required. The
+annotations according Quality of Service (QoS) and the retained flag should be
+followed.
+
+- `update/trigger` QoS 2 not retained
+- `request/blind/motion` QoS 2 not retained (`up`, `down`, `stopped`)
+- `request/blind/closure` QoS 2 not retained (`0`, `1`, ... `100`)