From 481da45e3d93e5166bd21c66b763ec6ce475edcc Mon Sep 17 00:00:00 2001 From: Moritz Ruth Date: Tue, 7 Mar 2023 12:37:54 +0100 Subject: [PATCH] Document the notifications module --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/README.md b/README.md index 7e9fc61..433db3c 100644 --- a/README.md +++ b/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). \ No newline at end of file