ha-linux

Home Assistant Companion for Linux - a background service that exposes your Linux system's state to Home Assistant via MQTT.

Inspired by the Home Assistant iOS app.

Sensors

Sensor	Type	Description	Requirements
online	binary_sensor	System online/offline status	None (uses MQTT LWT)
microphone	binary_sensor	Microphone in use	PulseAudio or PipeWire
webcam	binary_sensor	Webcam in use	None
wifi_ssid	sensor	Current WiFi network name	iwgetid or NetworkManager
location	device_tracker	GPS coordinates	GeoClue2
distro	sensor	Linux distribution name	None

The WiFi SSID sensor automatically detects the distribution and uses nmcli on Fedora/RHEL-based systems, falling back to iwgetid on others.

Features

• Home Assistant MQTT Discovery (auto-registers entities)
• Per-sensor configurable poll intervals
• MQTT Last Will and Testament for reliable offline detection
• Systemd integration

Planned:

• Idle/active detection
• Suspend/resume detection
• Battery status

Requirements

• Linux with systemd
• Python 3.10+
• MQTT broker (e.g., Mosquitto)
• Home Assistant with MQTT integration

Optional (for specific sensors):

• PulseAudio or PipeWire (pactl) - for microphone sensor
• iwgetid or NetworkManager (nmcli) - for WiFi SSID sensor
• GeoClue2 (gdbus) - for location sensor

Installation

From Release Tarball

1. Download the latest release tarball from the Releases page

2. Extract and install:

   tar -xzf ha-linux-*.tar.gz
   cd ha-linux-*
   sudo ./scripts/install.sh

3. Edit the configuration:

   sudo nano /etc/ha-linux/config.yaml

4. Enable and start the service:

   sudo systemctl enable ha-linux
   sudo systemctl start ha-linux

For Development

git clone https://github.com/alastairm/ha-linux.git
cd ha-linux
pip install -e ".[dev]"

Run locally with a custom config:

ha-linux -c ./config.example.yaml -v

Configuration

Configuration is stored in /etc/ha-linux/config.yaml:

mqtt:
  host: "192.168.1.100"
  port: 1883
  username: "ha-linux"
  password: "your-password"

device:
  name: "My Linux PC"  # Optional, defaults to hostname

# Each sensor can be:
#   false    - disabled
#   true     - enabled with default poll_interval
#   <number> - enabled with custom poll interval (seconds)
sensors:
  poll_interval: 60  # Default poll interval (seconds)
  online: true       # System online/offline
  microphone: 5      # Poll every 5 seconds
  webcam: 5
  wifi_ssid: true
  location: 300      # Poll every 5 minutes
  distro: true       # Linux distribution

Home Assistant

Once the service is running, your device will automatically appear in Home Assistant via MQTT Discovery.

Device: "Linux Companion - <hostname>"

Entities:

• binary_sensor.<hostname>_online - ON when system is running
• binary_sensor.<hostname>_microphone - ON when mic is in use
• binary_sensor.<hostname>_webcam - ON when camera is in use
• sensor.<hostname>_wifi_ssid - Current network name or "disconnected"
• device_tracker.<hostname>_location - GPS coordinates with lat/lon attributes
• sensor.<hostname>_distro - Linux distribution (e.g., "Fedora Linux 41")

The online sensor uses MQTT's Last Will and Testament feature, so Home Assistant will correctly show the device as unavailable when it goes offline unexpectedly.

GeoClue2 Setup (Location Sensor)

The location sensor requires GeoClue2. On most systems it's installed but may need configuration.

1. Ensure GeoClue2 is installed:

   # Fedora/RHEL
   sudo dnf install geoclue2
   
   # Debian/Ubuntu
   sudo apt install geoclue-2.0

2. Add ha-linux to allowed apps in /etc/geoclue/geoclue.conf:

   [ha-linux]
   allowed=true
   system=true
   users=

3. Restart GeoClue:

   sudo systemctl restart geoclue

Systemd Commands

# Check status
sudo systemctl status ha-linux

# View logs
journalctl -u ha-linux -f

# Restart service
sudo systemctl restart ha-linux

# Stop service
sudo systemctl stop ha-linux

Uninstalling

sudo /opt/ha-linux/scripts/uninstall.sh

Or if you still have the tarball extracted:

sudo ./scripts/uninstall.sh

License

MIT