HA Linux Companion — Raspberry into a Home Assistant touch panel

Share your Projects!
, , ,
1

A native Electron-based companion app that turns a Raspberry Pi (or any Linux device) with a touchscreen into a dedicated Home Assistant wall panel.

GitHub: GitHub - SimoneB79/ha-linux-companion: Home Assistant companion app for Linux touchscreen panels — Electron · GitHub

What it does

  • Full-screen Lovelace dashboard in kiosk mode via Electron
  • 8 system sensors (CPU temp, CPU%, RAM, disk, uptime, IP, display state) via mobile_app integration
  • Push notifications with custom toast overlay, priority levels, action buttons, and sound
  • Notification channels — auto-created from HA, per-channel enable/sound/priority
  • Custom sounds — load your own .wav/.ogg/.mp3/.flac files
  • Hardware controls overlay — volume, brightness, bluetooth, display ON/OFF
  • Hardware info panel — board model, CPU temp/freq, RAM, disk, OS, kernel, serial, uptime
  • Network info — WiFi SSID, signal strength, IP, gateway, DNS
  • Audio output selector — switch between HDMI, jack 3.5mm, Bluetooth
  • CPU governor — performance / powersave / ondemand
  • Night scheduling — auto display off/on at configurable times
  • System power — reboot and shutdown from the overlay menu
  • On-screen virtual keyboard for touch panels
  • Full Home Assistant auth flow (username/password + 2FA + long-lived token)
  • mobile_app device registration with webhook sensors
  • Self-signed certificates support (Caddy, Nginx, etc.)
  • Update checker — shows latest stable and dev releases from GitHub

:satellite: Notification Commands — Remote Panel Control

Control the panel from any HA automation by sending commands instead of notifications:

Command Description
command_screen_on Turn display on
command_screen_off Turn display off
command_screen_brightness_level Set brightness (0-100)
command_volume_level Set volume (0.0-1.0)
command_dnd Toggle Do Not Disturb
command_bluetooth Bluetooth on/off
command_update_sensors Force sensor update
command_navigate Navigate to HA path
command_open_url Open URL in panel
command_restart_app Restart the app
command_reload_dashboard Reload dashboard
command_set_theme Set HA dashboard theme

Example — dim and turn off display at night:

automation:
  - alias: "Panel night mode"
    trigger:
      - platform: time
        at: "23:00:00"
    action:
      - service: notify.mobile_app_pannello
        data:
          message: command_screen_brightness_level
          data:
            brightness: 20
      - delay:
          seconds: 30
      - service: notify.mobile_app_pannello
        data:
          message: command_screen_off

:musical_note: Audio

  • Auto-detects audio backend (PipeWire, PulseAudio, ALSA)
  • Notifications play alongside other audio (e.g., Squeezebox/LMS) thanks to PipeWire mixing
  • Fallback chain: pw-play → paplay → aplay

Tested on

  • Raspberry Pi 5 + 7" DSI touchscreen
  • Raspberry Pi 4 + 7" DSI touchscreen
  • Any Linux desktop with Wayland/X11

Quick start

curl -sSL https://raw.githubusercontent.com/SimoneB79/ha-linux-companion/main/install.sh | bash

Or manual setup:

git clone https://github.com/SimoneB79/ha-linux-companion.git
cd ha-linux-companion
npm install
npx electron .

Login with your Home Assistant credentials, and the device registers automatically — sensors appear in HA, notifications work instantly.

How it differs from similar projects

Feature HA Linux Companion Fully Kiosk Browser
Native app (Electron) :white_check_mark: :cross_mark: (Android only)
System sensors via mobile_app :white_check_mark: Limited
Push notifications with sound :white_check_mark: :white_check_mark:
Notification commands :white_check_mark: Limited
Linux / Raspberry Pi native :white_check_mark: :cross_mark:
Audio mixing (squeezelite + notifications) :white_check_mark: N/A
Hardware info panel :white_check_mark: :cross_mark:
CPU governor control :white_check_mark: :cross_mark:
Display night scheduling :white_check_mark: :cross_mark:
Network info :white_check_mark: Limited
Audio output selector :white_check_mark: :cross_mark:

This fills a gap for the Linux/Raspberry Pi ecosystem — similar to what the Android companion app does, but for wall-mounted touch panels running Linux.

Current status

v2.3.0 — Stable and running in production on two Raspberry Pis. Feedback, testing, and contributions are welcome!

Releases: Releases · SimoneB79/ha-linux-companion · GitHub

2

This look awesome, thanks for sharing!
Is there anything specific this does over TouchKio (GitHub - leukipp/touchkio: Home Assistant Touch Panel Kiosk application for a Linux device (e.g. Raspberry Pi) with Touch Display. · GitHub)?
I've got that running on a couple of devices and it runs well.

3

Thanks! TouchKio is great — I actually studied it while building this.

The key difference: TouchKio is a kiosk wrapper around the HA web UI, while HA Linux Companion is a native mobile_app integration.

TouchKio loads http://ha:8123 in a webview. HA handles login via browser cookies. It adds MQTT for hardware controls (volume, brightness, display on/off).

HA Linux Companion registers as a mobile device via the HA API (/api/mobile_app/registrations), which gives it:

  • 8 system sensors published via webhook (CPU temp, CPU%, RAM, disk, uptime, IP, display state) — visible as a device in HA
  • Push notification channel via WebSocket — receives HA notifications in real-time
  • Notification sounds via PipeWire with per-device audio
  • Device registration — appears as a companion device in HA integrations, just like the Android/iOS app
  • Built-in auth flow — username/password login with persistent sessions (refresh token management)

In short: TouchKio = thin kiosk layer, HA Linux Companion = full mobile_app integration.

They serve different needs — TouchKio is simpler to set up if you just need a dashboard display, HA Linux Companion if you want the panel to be a full HA device with sensors and notifications.