TouchKio

TouchKio is a Node.js application that utilizes Electron to create a kiosk mode window specifically designed for a Home Assistant dashboard. This tool is packaged as a .deb file, making it easy to launch the kiosk application on any Debian based Linux hardware (e.g. Raspberry Pi) equipped with a DSI or HDMI Touch Display. Additional releases for other Linux systems are available as .zip file.

This implementation addresses common issues encountered when using the built-in browser running in fullscreen mode on a Linux device with Touch Display. Moreover, the device running the kiosk application also offers several Home Assistant MQTT sensors, enhancing it's functionality for automation purposes.

Features

[x] Fast and easy setup.
[x] Remember login credentials.
[x] Touch optimized web browsing.
[x] Dynamic window status bar layout.
[x] Side panel widget for kiosk control.
[x] Navigation bar to switch between pages.
[x] Adjustable browser zoom and theme support.
[x] Extended touch screen wake-up functionality.
[x] Remote controllable via MQTT.
- [x] Toggle the on-screen keyboard.
- [x] Touch display power and brightness.
- [x] Manage kiosk window status and zoom.
- [x] Screenshot image of the kiosk webview.
- [x] Show network interfaces and addresses.
- [x] List all available system package upgrades.
- [x] Multi-webpage switching and url navigation.
- [x] Volume control for connected audio outputs.
- [x] Execute system reboot and shutdown commands.
- [x] Monitor battery, temperature, processor and memory usage.

The kiosk application can be executed with command line arguments to load a Home Assistant dashboard in fullscreen mode. Additionally, a MQTT endpoint can be defined, allowing the application to provide controls and sensors for the Linux device and the connected Touch Display.

Setup

Before you begin, make sure that you have a Linux device configured and operational with a compatible Touch Display. This guide assumes that you are using a Raspberry Pi with the latest version of Raspberry Pi OS (64-bit), along with a desktop environment (preferred using labwc). However, the .deb setup procedure is also compatible with any other Debian based 64-bit system.

Optional

To utilize the sensor features of your device through Home Assistant, it's essential to have a MQTT broker running and the MQTT integration installed on your Home Assistant instance. This setup allows seamless communication between your kiosk device and Home Assistant, enabling real-time data exchange.

For a comprehensive guide on setting up MQTT with Home Assistant, please refer to the official documentation available here: https://www.home-assistant.io/integrations/mqtt.

Installation

On the first run of the application, you will encounter a setup procedure (CLI) and the Home Assistant login screen (UI). It's recommended to create a dedicated Home Assistant user (local access only) for your kiosk device.

You might also need a physical keyboard or remote VNC access to input these credentials once. If your hardware is supported you may be able to activate the on-screen keyboard using the side widget. After the first login the Home Assistant credentials are stored inside the ~/.config/touchkio/ folder.

Option 1 - The easy way

Run this command to download and install the latest .deb (arm64 or x64) release. It will also create a systemd user file for auto-startup and will guide you through the setup process:

bash <(wget -qO- https://raw.githubusercontent.com/leukipp/touchkio/main/install.sh)

Make sure that you run this with your standard user and not with root (sudo). If you are paranoid, or smart, or both, have a look into the install.sh script before executing external code on your machine.

The systemd user service is enabled by default and the kiosk application should start automatically the next time you boot. If you need manual control use:

systemctl --user start|stop|status|restart touchkio.service

<details><summary>Alternatives</summary><div>

Option 2 - The standard way

When connected via SSH, it's necessary to export the display variables first, as outlined in the development section. The install.sh script mentioned above performs the following tasks (and you just have to do it manually):

Download the latest version file that is suitable for your architecture (arm64 or x64).
- Debian (deb): Open a terminal and execute the following command to install the application, e.g: sudo apt install ./touchkio_1.x.x_arm64.deb && touchkio --setup
- Others (zip): Extract the archive and run the binary, e.g: unzip touchkio-linux-x64-1.x.x.zip && cd touchkio-linux-x64 && ./touchkio --setup
If you just want to load a Home Assistant dashboard without further control you are good to go, e.g: touchkio --web-url=https://demo.home-assistant.io
- The --web-url doesn't necessarily need to be a Home Assistant url, any kind of website can be shown in kiosk mode.
- Only when using the MQTT integration via --mqtt-*, a running Home Assistant instance is required.
If you need the application to be automatically started on boot, create a systemd file.

Option 3 - The hard way

Pre-built release files are available for arm64 and x64 Linux systems. If you are using a different architecture, you can still utilize this repository to build your own application.

For more information please refer to the development section, however this will do the job:

yarn build

</div></details>

Update

If you have already installed TouchKio and want to upgrade to the latest version, simply install the newer version over the existing one.

The install.sh script can also be run to update an existing installation to the latest version. The setup procedure can be skipped to use the existing default arguments from the configuration file:

bash <(wget -qO- https://raw.githubusercontent.com/leukipp/touchkio/main/install.sh) update

Configuration

Running touchkio --setup will prompt you to enter arguments that will be used when the application starts without any specified arguments. These default arguments are stored in ~/.config/touchkio/Arguments.json, where they can also be modified.

WEB

The available arguments to control the kiosk application via terminal are as follows: | Name | Default | Description | | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- | | --web-url (Required) | - | Url of the Home Assistant instance<a id="ref1"></a><sup><a href="#foot1">[1]</a></sup> (HTTP(S)://IP:PORT) | | --web-theme (Optional) | dark | Theme settings of the web browser (light or dark) | | --web-zoom (Optional) | 1.25 | Zoom settings of the web browser (1.0 is 100%) | | --web-widget (Optional) | true | Enables the sidebar widget (true or false) |

These arguments allow you to customize the appearance of the web browser view.

For example:

touchkio --web-url=http://192.168.1.42:8123 --web-theme=light --web-zoom=1.0

<a id="foot1"></a><a href="#ref1">[1]</a>: This doesn't necessarily have to be a Home Assistant Url. You can configure multiple pages by separating them with a comma: touchkio --web-url=https://demo.home-assistant.io,https://demo.immichkiosk.app.

In the ~/.config/touchkio/Arguments.json file:

{
  "web_url": [
    "https://demo.home-assistant.io",
    "https://demo.immichkiosk.app"
  ]
}

MQTT

To broadcast your local sensor data to Home Assistant, you can use the following arguments, which require a running MQTT broker: | Name | Default | Description | | ----------------------------- | --------------- | ----------------------------------------------------------------------------------------

Touchkio

Install / Use

README