From 6982a6b87f2fb618f08872d02801dd418016a76b Mon Sep 17 00:00:00 2001 From: xengineering Date: Sun, 22 Mar 2026 11:32:12 +0100 Subject: Document MQTT interface It is even quite late to document the main application programming interface (API) of the Sia server. This is now fixed. --- README.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) (limited to 'README.md') 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//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 -- cgit v1.3