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.

4

I agree, thanks for sharing, this is great. I actually wanted this as an app to hopefully get the screen saver element of the normal companion app working, which doesn’t happen with the WebGUI instance. Alas, this app doesn’t seem to show the clock screensaver either, it’s still great though!

One question/problem to ask about.

I installed the app via your manual option and then followed all the subsequent info on removal/tidy up afterwards. I also updated the npm version so everything is up to date and working, but, now that I’m using it I can’t seem to logout of the user that I first logged into the app with. So I changed the password of the user and relaunched the whole node; mainly because I couldn’t find a way to exit the app once it has launched and auto logged in. The log out wasn’t working and the touch display I’m using has no way of returning to the underlying OS.

Now, the app auto launches and forever loops through the login credential screen with the user it has stored, which are no longer the correct credentials so it just forever tries them again and again and again for what seems, could be eternity!

So my question is, how do I reset the log in credentials to make it ask me to log in a fresh?

Sorry, it’s a brilliant app, it’s just this problem has stopped me using the whole touch display setup all together. I suppose I could re-install the app again and register the other HA user I want to use going forward with this device…

(Using a Pi5 and PiOS)