Hassliebe

Integrates any Linux machine into your Home Assistant ecosystem.

Features

• Command buttons
• Notifications
  • Actions
• System information reporting (CPU usage, RAM usage, battery status)

The following sound like interesting ideas but as I don’t have a use case for them at the moment, I haven’t implemented them yet. Feel free to open an issue and describe your use-case.

• PipeWire control
• Exposing file contents as sensors

Installation

Hassliebe is a single executable. Copy it somewhere and execute it.

For systemd users, a unit file is provided.

As a systemd system service

• Download the latest binary and put it into /usr/bin.
• Download the unit file and put it into /etc/systemd/system.
• Create the configuration file (see below) at /etc/hassliebe/config.toml.
• Enable and start the unit:

systemctl enable hassliebe && systemctl start hassliebe

As a systemd user service

• Download the latest binary and put it into ~/.local/bin.
• Download the unit file 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:

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

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:

[[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:

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

Remember to enable the module:

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

This project is available under the permissive Blue Oak Model License 1.0.0.