162 lines
No EOL
5.1 KiB
Markdown
162 lines
No EOL
5.1 KiB
Markdown
# Hassliebe
|
||
|
||
> Integrates any Linux machine into your Home Assistant ecosystem.
|
||
|
||
## Features
|
||
|
||
- [x] Command buttons
|
||
- [x] Notifications
|
||
- [x] Actions
|
||
- [x] System information reporting (CPU usage, RAM usage, battery status)
|
||
- [ ] Media control (MPRIS)
|
||
- [ ] PipeWire control
|
||
- [ ] File watcher
|
||
|
||
## Installation
|
||
|
||
### As a systemd _system_ service
|
||
|
||
- Download [the latest binary](https://git.moritzruth.de/moritzruth/Hassliebe/releases) and put it into `/usr/bin`.
|
||
- Download [the unit file](contrib/systemd/system/hassliebe.service) and put it into `/etc/systemd/system`.
|
||
- Create the configuration file (see below) at `/etc/hassliebe/config.toml`.
|
||
- Enable and start the unit:
|
||
|
||
```sh
|
||
systemctl enable hassliebe && systemctl start hassliebe
|
||
```
|
||
|
||
### As a systemd _user_ service
|
||
|
||
- Download [the latest binary](https://git.moritzruth.de/moritzruth/Hassliebe/releases) and put it into `~/.local/bin`.
|
||
- Download [the unit file](contrib/systemd/user/hassliebe.service) and put it into `~/.local/share/systemd/user`.
|
||
- Create the configuration file (see below) at `$XDG_CONFIG_HOME/hassliebe/config.toml`.
|
||
- Enable and start the unit:
|
||
|
||
```sh
|
||
systemctl --user enable hassliebe && systemctl --user start hassliebe
|
||
```
|
||
|
||
## Configuration
|
||
|
||
Depending on whether Hassliebe is run as root or as a regular user, the configuration is read from
|
||
`/etc/hassliebe/config.toml` or `$XDG_CONFIG_HOME/hassliebe/config.toml`.
|
||
|
||
### Example
|
||
|
||
```toml
|
||
friendly_id = "my_pc" # Used as prefix for MQTT topics and Home Assistant IDs
|
||
display_name = "My PC"
|
||
|
||
[mqtt]
|
||
host = "127.0.0.1" # You probably need to change this
|
||
port = 1883
|
||
|
||
# You can remove the following line if your MQTT broker allows unauthenticated access
|
||
credentials = { user = "user", password = "password" }
|
||
|
||
[modules.buttons]
|
||
enabled = true
|
||
|
||
[[modules.buttons.buttons]]
|
||
id = "reboot"
|
||
name = "Reboot"
|
||
command = "shutdown -r now"
|
||
|
||
[modules.info]
|
||
enabled = true
|
||
cpu_usage = 10 # update interval in seconds
|
||
ram_usage = 0 # 0 disables reporting
|
||
battery = 60
|
||
|
||
[modules.notifications]
|
||
enabled = true
|
||
```
|
||
|
||
### Machine identification
|
||
|
||
Hassliebe needs a way to uniquely identify a machine.
|
||
`friendly_id` is not suited well for this because the user may want to change it from time to time.
|
||
|
||
If `/etc/machine-id` exists (as is the case with systemd-based systems), it will be used.
|
||
Otherwise, a random ID will be generated on the first run and stored in `[data]/machine_id`.
|
||
The latter always takes precedence.
|
||
|
||
## Modules
|
||
|
||
### Buttons
|
||
|
||
You can define MQTT buttons in your configuration file like this:
|
||
|
||
```toml
|
||
[[modules.buttons.buttons]]
|
||
id = "shutdown" # must be unique among all the buttons in the file
|
||
name = "Shutdown"
|
||
command = "shutdown -h now"
|
||
run_in_shell = true # defaults to false
|
||
```
|
||
|
||
When `run_in_shell` is set to `true`, the command will be run with `/bin/sh`.
|
||
|
||
### Info
|
||
|
||
Hassliebe currently supports reporting the following system stats:
|
||
|
||
- CPU usage (%)
|
||
- RAM usage (%)
|
||
- Battery level (%) and status (`/sys/class/power_supply/[name]/status`)
|
||
|
||
For each of these, the update interval can be set to a number of seconds or `0` to disable it:
|
||
|
||
```toml
|
||
[modules.info]
|
||
enabled = true
|
||
cpu_usage = 10 # updates every 10 seconds
|
||
ram_usage = 0 # disabled
|
||
battery = 60 # updates every 60 seconds
|
||
```
|
||
|
||
### Notifications
|
||
|
||
**Not available when running as a system service.**
|
||
|
||
The notifications module allows sending notifications according to the
|
||
[Desktop Notifications Specification](https://specifications.freedesktop.org/notification-spec/notification-spec-latest.html#markup).
|
||
|
||
Remember to enable the module:
|
||
|
||
```toml
|
||
[modules.notifications]
|
||
enabled = true
|
||
```
|
||
|
||
Two MQTT topics can be used for sending notifications:
|
||
|
||
- `[friendly_id]/notifications/simple` — for plain-text messages
|
||
- `[friendly_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:
|
||
`[friendly_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). |