# Hassliebe

> Integrates any Linux machine into your Home Assistant ecosystem.

## Features

- [x] Command buttons
- [x] Notifications
  - [x] Actions
- [x] System information reporting (CPU usage, battery status, …)
- [ ] Media control (MPRIS)
- [ ] PipeWire control
- [ ] File watcher

Ideas:

- Camera video stream
- Idle time (→ libseat)

## 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](distrib/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](distrib/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

[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).