diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 73 |
1 files changed, 69 insertions, 4 deletions
@@ -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 |