Document MQTT interfaceshelly

It is even quite late to document the main application programming
interface (API) of the Sia server. This is now fixed.

1 files changed, 42 insertions, 0 deletions

diff --git a/README.md b/README.md
index 74ac093..d4a73b8 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,47 @@ Only aspects explicitly stated here are part of the public API:
 - configuration file format
 - MQTT interface
 
+## MQTT interface
+
+The Sia server connects to a MQTT broker and exposes its client interface
+there.
+
+The MQTT broker host, port and the Sia server's client ID is configured via the
+Sia configuration file.
+
+Furthermore a topic prefix is selected. **All topics documented below are
+implicitly prefixed with this topic prefix.** This allows using multiple Sia
+server instances on one MQTT broker.
+
+All message payloads are UTF-8 encoded strings.
+
+For all terms not explained here see the [MQTT version 3.1.1 documentation][9].
+
+### `/server/health`
+
+- description: Indicates if Sia server is connected to the broker
+- direction: Sia server to client
+- Quality of Service: QoS 1 (at least once)
+- retained: yes
+- receives will message: yes, indicating sudden disconnect of Sia server
+- topic parameters: none
+- payloads:
+    - `good`: Sia server is connected to MQTT broker
+    - `bad`: Sia server is disconnected from MQTT broker
+
+### `/contact/<id>/state`
+
+- description: Indicates state of Homematic IP SWDO-2 contacts
+- direction: Sia server to client
+- Quality of Service: QoS 1 (at least once)
+- retained: yes
+- receives will message: no
+- topic parameters:
+    - `id`: ID of the Homematic IP SWDO-2 contact
+- payloads:
+    - `open`: contact is open
+    - `closed`: contact is closed
+
 [1]: https://homematic-ip.com/
 [2]: https://openccu.de/
 [3]: https://homematic-ip.com/en/product/window-and-door-contact-optical
@@ -79,3 +120,4 @@ Only aspects explicitly stated here are part of the public API:
 [6]: https://shelly-api-docs.shelly.cloud/gen2/
 [7]: https://www.shelly.com/de/products/shelly-2pm-gen3-1/
 [8]: https://shelly.com/
+[9]: https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html