Merge branch 'shelly'

This adds basic support for Shelly 2PM Gen3 devices.

1 files changed, 69 insertions, 4 deletions

diff --git a/README.md b/README.md
index c9f153a..2b40691 100644
--- a/README.md
+++ b/README.md
@@ -6,14 +6,20 @@ implemented by apps connecting to this central Sia server.
 
 ## Supported vendors and devices
 
-Currently only [Homematic IP][1] as a vendor and the [OpenCCU][2] as interface
-is supported.
+### Homematic IP
 
-The currently only supported device is:
+[Homematic IP][1] with the [OpenCCU][2] as central device is supported with
+these IoT products:
 
 - [HmIP-SWDO-2][3] - optical window or door contact
 
-Further device support is planned.
+### Shelly
+
+[Shelly][8] is supported with the following product:
+
+- [Shelly 2PM Gen3][7] - twin relay e.g. for roller shutter control
+
+The implemented API is documented [here][6].
 
 ## Build instructions
 
@@ -65,8 +71,67 @@ 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
+
+### `/cover/<id>/movement`
+
+- description: Allows control of Shelly 2PM Gen3 covers
+- direction: client to Sia server
+- Quality of Service: QoS 2 (exactly once)
+- retained: no
+- receives will message: no
+- topic parameters:
+    - `id`: ID of the Shelly 2PM Gen3 cover
+- payloads:
+    - `extend`: cover increases the covering surface
+    - `retract`: cover decreases the covering surface
+    - `stop`: cover stops current motion if given
+
 [1]: https://homematic-ip.com/
 [2]: https://openccu.de/
 [3]: https://homematic-ip.com/en/product/window-and-door-contact-optical
 [4]: https://systemd.io/
 [5]: https://semver.org/
+[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