Document the notifications module

README.md

@@ -1,7 +1,9 @@
 # Hassliebe
+
 > Integrates any Linux machine into your Home Assistant ecosystem.
 
 ## Features
+
 - [ ] Fallback MQTT broker address
 - [x] Command buttons
 - [x] Notifications
@@ -19,6 +21,42 @@ Ideas:
 - Camera video stream
 - Idle time (→ libseat)
 
+## Installation
+
+TBD
+
+## Modules
+
+### Notifications
+
+Two MQTT topics can be used for sending notifications:
+
+- `[unique_id]/notifications/simple` — for plain-text messages
+- `[unique_id]/notifications/json` — for JSON-encoded messages matching the schema described below
+
+Complex messages have these properties:
+
+- `id` (optional) — A string identifying this notification. If an ID is used multiple times, later notifications
+  replacer earlier ones.
+- `timeout` (optional) — Controls how long the notification will stay.
+  - `"default"` (default) — use the default value of the notification server
+  - `"never"` — stay until manually dismissed
+  - `{ ms: [millseconds] }` — stay for `[milliseconds]`
+- `urgency` (optional) — One of: `"low"`, `"normal"` (default), `"critical"`.
+- `summary_text` — The primary text content, often used as title. Must not be empty.
+- `long_content` (optional) — Optional additional content
+  which [supports a subset of HTML](https://specifications.freedesktop.org/notification-spec/notification-spec-latest.html#markup).
+- `transient` (optional) — Boolean indicating whether to bypass the notification server’s persistence capability.
+- `encoded_image` — Optional padded base64-encoded image attached to the notification.
+- `actions` (optional) — Object with the keys being IDs and the values being labels.
+
+#### Actions
+
+When a notification action is invoked, the ID of the action is sent to the MQTT topic with the following name:
+`[unique_id]/notifications/actions/[notification_id]`.
+
+When a notification is dismissed, `closed` is sent into the topic.
+
 ## License
 
 Hassliebe is licensed under the [Blue Oak Model License 1.0.0](/LICENSE.md).