sirmrak/touchkio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update docs

Browse Source
This commit is contained in:
leukipp
2025-01-10 22:30:17 +01:00
parent fd746cc79a
commit 081cee2990
2 changed files with 69 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
HARDWARE.md
+6 -5
View File
@@ -1,27 +1,28 @@
# TouchKio - Supported Hardware
This document contains an incomplete list of device and display hardware combinations that are either intended to be tested or have already been tested.
The [release](https://github.com/leukipp/touchkio/releases) page has builds exclusively for **arm64**, but custom builds for other architectures can be made (see [Development](https://github.com/leukipp/touchkio?tab=readme-ov-file#development)), allowing the application to operate on any hardware.
The [release](https://github.com/leukipp/touchkio/releases) page has builds exclusively for **arm64** and **x64**, but custom builds for other architectures can be made (see [Development](https://github.com/leukipp/touchkio?tab=readme-ov-file#development)), allowing the application to operate on any hardware.
At least the **minimal** features, such as displaying a **kiosk window** (which doesn't necessarily need to be Home Assistant) will work.
## Hardware
Any SBC clones of the Raspberry Pi that operate on **Raspberry Pi OS (64-bit)** and **Wayland** are likely to function as well.
If you are running Linux with a graphical user interface (Wayland or X11), you should be well equipped to use the application. Additionally, any single board computer (SBC) clones of the Raspberry Pi that operate on Raspberry Pi OS **(64-bit)** are likely to function properly as well.
### DSI
| Device | Display | Tested | Status | Notes |
| -------------- | ----------------------------------------------------------------------------------------------- | ------ | ----------------- | ------------------------------------------------------ |
| -------------- | ----------------------------------------------------------------------------------------------- | ------ | ----------------- | ---------------------------------------------------------------- |
| Raspberry Pi 3 | [Official 7" Touch Display 1](https://www.raspberrypi.com/products/raspberry-pi-touch-display/) | ❌ | Unknown | 99% chance that it is slow and the resolution sucks. |
| Raspberry Pi 3 | [Official 7" Touch Display 2](https://www.raspberrypi.com/products/touch-display-2/) | ❌ | Unknown | 99% chance that it is slow. |
| Raspberry Pi 4 | [Official 7" Touch Display 1](https://www.raspberrypi.com/products/raspberry-pi-touch-display/) | ❌ | Unknown | 99% chance that the resolution sucks. |
| Raspberry Pi 4 | [Official 7" Touch Display 2](https://www.raspberrypi.com/products/touch-display-2/) | ❌ | Optimistic | 99% chance that it fully works. |
| Raspberry Pi 5 | [Official 7" Touch Display 1](https://www.raspberrypi.com/products/raspberry-pi-touch-display/) | ❌ | Unknown | 99% chance that the resolution sucks. |
| Raspberry Pi 5 | [Official 7" Touch Display 2](https://www.raspberrypi.com/products/touch-display-2/) | ✅ | Fully operational | Working display power and brightness control via MQTT. |
| Raspberry Pi 5 | [Official 7" Touch Display 2](https://www.raspberrypi.com/products/touch-display-2/) | ✅ | Fully operational | Working display power, brightness and keyboard control via MQTT. |
### HDMI
| Device | Display | Tested | Status | Notes |
| -------------- | ----------------- | ------ | --------------------- | ----------------------------------------------------- |
| -------------- | ---------------------------------------------------------------------- | ------ | --------------------- | ------------------------------------------------------------------ |
| Raspberry Pi 4 | [LAFVIN 5" Touch Display](https://www.amazon.de/gp/product/B0BWJ8YP7S) | ✅ | Partially operational | Display brightness control is not available via MQTT. |
| Raspberry Pi 5 | Generic Non-Touch | ✅ | Partially operational | Display brightness control is not available via MQTT. |
| Generic Ubuntu | Generic Non-Touch | ✅ | Partially operational | Display brightness and keyboard control is not available via MQTT. |
## Contributions
In case your hardware is not listed above don't worry, give it a try.
README.md
+54 -32
View File
@@ -1,32 +1,37 @@
# TouchKio
**TouchKio** is a Node.js application that utilizes **Electron** to create a kiosk mode specifically designed for a Home Assistant dashboard (or any other [webpage](https://github.com/leukipp/touchkio/blob/main/HARDWARE.md)).
This tool is packaged as a **.deb** file, making it easy to launch the kiosk mode on a **Raspberry Pi** (or similar [hardware](https://github.com/leukipp/touchkio/blob/main/HARDWARE.md)) equipped with a touch display.
**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](https://github.com/leukipp/touchkio/blob/main/HARDWARE.md) (e.g. **Raspberry Pi**) equipped with a **DSI or HDMI** Touch Display.
Additional releases for other Linux systems are available as **.zip** file.
[![display](https://raw.githubusercontent.com/leukipp/touchkio/main/img/display.png)](https://github.com/leukipp/touchkio/blob/main/img/display.png)
This implementation addresses common issues encountered when using the built-in browser running in fullscreen mode on the Raspberry Pi with touch display.
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 friendly web browser interface.
- [x] Configurable zoom and theme support.
- [x] Single-tap screen wake-up functionality.
- [x] Remote controllable via MQTT.
- [x] Manage kiosk window status.
- [x] Manage touch keyboard status.
- [x] Touch display power and brightness.
- [x] Show available system package upgrades.
- [x] Execute system reboot and shutdown commands.
- [x] Monitor 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 Raspberry Pi and the connected touch display.
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 Raspberry Pi configured and operational with a [compatible touch display](https://github.com/leukipp/touchkio/blob/main/HARDWARE.md).
This guide assumes that you are using the latest version of **Raspberry Pi OS (64-bit)** together with a **Wayland** based desktop environment.
Before you begin, make sure that you have a Linux device configured and operational with a [compatible](https://github.com/leukipp/touchkio/blob/main/HARDWARE.md) 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 is also compatible with any other Debian based system.
### Optional
To utilize the sensor features of your display through Home Assistant, it's essential to have a **MQTT broker running** and the **MQTT integration installed** on your Home Assistant instance.
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**.
[![mqtt](https://raw.githubusercontent.com/leukipp/touchkio/main/img/mqtt.png)](https://github.com/leukipp/touchkio/blob/main/img/mqtt.png)
@@ -39,22 +44,36 @@ It's recommended to create a **dedicated user** (local access only) for your kio
You might also need a keyboard or remote VNC access to input these credentials once.
#### Option 1 - The easy way
Run this command to download and install the release **.deb** file. It will also adjust some permissions, create a systemd file for auto-startup and will guide you through the setup process:
Run this command to download and install the latest **.deb** (arm64 or x64) release.
It will also create a systemd file for auto-startup and will guide you through the setup process:
```bash
bash <(wget -qO- https://raw.githubusercontent.com/leukipp/touchkio/main/install.sh)
```
If you are paranoid, or smart, or both, have a look into the [install.sh](https://github.com/leukipp/touchkio/blob/main/install.sh) script before executing external code on your machine.
#### Option 2 - The hard way
The [install.sh](https://github.com/leukipp/touchkio/blob/main/install.sh) script mentioned above performs the following tasks (and you just have to do it manually):
- [Download](https://github.com/leukipp/touchkio/releases/latest) the latest **.deb** file,
which is specifically suitable for Raspberry Pi **(64-bit)** ARM architecture.
- Open a terminal and execute the following command to install the application, e.g:
`sudo dpkg -i touchkio_1.x.x_arm64.deb`
- 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`
<details><summary>Alternatives</summary><div>
If you need the application to be automatically started on boot, create a **systemd file**.
If you need the Home Assistant MQTT sensors, create the **udev rule** for backlight control.
#### Option 2 - The standard way
The [install.sh](https://github.com/leukipp/touchkio/blob/main/install.sh) script mentioned above performs the following tasks (and you just have to do it manually):
- [Download](https://github.com/leukipp/touchkio/releases/latest) 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 dpkg -i 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](https://github.com/leukipp/touchkio?tab=readme-ov-file#development) section. However this could do the job:
```bash
yarn build
```
</div></details>
## Configuration
Running `touchkio --setup` will prompt you to enter arguments that will be used when the application starts without any specified arguments.
@@ -85,7 +104,7 @@ To broadcast your local sensor data to Home Assistant, you can use the following
| `--mqtt-discovery` (Optional) | `homeassistant` | The discovery prefix for MQTT (`homeassistant` works with default setups) |
When you start the application with the MQTT arguments, the Home Assistant auto-discovery feature will automatically add controls and sensors that can be used for further integration.
You can find them under **Settings** -> **Devices and Services** -> **Devices** by searching for "Raspberry Pi".
You can find them under **Settings** -> **Devices and Services** -> **Devices** by searching for **TouchKio**.
For example:
```bash
@@ -93,13 +112,13 @@ touchkio --web-url=http://192.168.1.42:8123 --mqtt-url=mqtt://192.168.1.42:1883
```
## Development
If you want to create your own local build install [nodejs](https://pimylifeup.com/raspberry-pi-nodejs) and [yarn](https://classic.yarnpkg.com/lang/en/docs/install) on your Raspberry Pi.
To create your own local build, you first need to install [Node.js](https://pimylifeup.com/raspberry-pi-nodejs) and [Yarn](https://classic.yarnpkg.com/lang/en/docs/install).
Clone this repository and run `yarn install` to install the dependencies.
Then use `yarn start` to execute the `start` script located in the [package.json](https://github.com/leukipp/touchkio/blob/main/package.json) file.
Then use `yarn start` to execute the start script located in [package.json](https://github.com/leukipp/touchkio/blob/main/package.json) file.
There you can adjust the `--web-url` and other arguments for development runs.
If you connect to your Raspberry Pi via SSH, you must export the display variables so that the kiosk application can be loaded in the desktop environment:
If you connect to your device via SSH, you may have to export display variables so that the kiosk application can be loaded inside the desktop environment:
```bash
export DISPLAY=":0"
export WAYLAND_DISPLAY="wayland-0"
@@ -109,11 +128,8 @@ export WAYLAND_DISPLAY="wayland-0"
<details><summary>Don't waste your time reading this.</summary><div></br>
To enable **write access** to the `/sys/class/backlight/10-0045/bl_power` and `/sys/class/backlight/10-0045/brightness` files, you need to set up a **udev rule**. In case you don't use the official touch display you may have to change the rules, that are located under `/etc/udev/rules.d/backlight-permissions.rules`.
This rule is created via the [install.sh](https://github.com/leukipp/touchkio/blob/main/install.sh) script, which also creates a service file.
The service file is located at `~/.config/systemd/user/touchkio.service` and starts the `/usr/bin/touchkio` process when the graphical user interface is loaded.
While creating a service file is optional, it's highly recommended if you want your Raspberry Pi to automatically boot into kiosk mode.
The Raspberry Pi's **build-in on-screen keyboard** named `squeekboard` (it squeaks because some *Rust* got inside), is specifically designed for Wayland environments and features a **D-Bus interface** that allows applications to show or hide the keyboard as needed.
The kiosk application interacts with squeekboard via this `D-Bus` object path `/sm/puri/OSK0`, enabling the keyboard to be hidden or shown based on **MQTT** user input or system events.
The Raspberry Pi's **build-in screen blanking** function uses the command `swayidle -w timeout 600 'wlopm --off \*' resume 'wlopm --on \*' &` inside `~/.config/labwc/autostart` to blank the screen after **10 minutes**.
The `wlopm --off \*` command changes the `bl_power` value to **4**, when setting the value to **0** the screen will turn on again.
@@ -128,7 +144,7 @@ As a result, I went for a **polling solution**, checking the state of the file e
While I understand this is not ideal, it's necessary to ensure proper functionality.
The display power status and brightness can be adjusted via the MQTT integration.
**Support** for changing the power status for **DSI and HDMI** displays is achieved by checking for connected screens in `/sys/class/drm/*/status`.
**Support** for changing the power status on **DSI and HDMI** displays is achieved by checking for connected screens in `/sys/class/drm/*/status`.
Support for changing the brightness of connected display is implemented by using `/sys/class/backlight/*/brightness`.
In cases where no supported backlight device is found, the Home Assistant light entity will only show an on/off switch without brightness control.
@@ -138,11 +154,11 @@ Implementing stronger **security measures** would complicate the setup process a
When using the kiosk application without initializing the default arguments, you will need to provide them with every command.
This means that the password may be stored as plain text in various files, such as `touchkio.service`, `~/.bash_history`, etc.
To resolve the issue where the first **touch** on a **turned-off screen** triggers a **click event** (potentially activating Home Assistant actions), I implemented a workaround.
To resolve the issue where the first **touch** on a **turned-off screen** triggers a **click event** (which could inadvertently activate Home Assistant actions), a workaround needed to be implemented.
When the screen **turns off** the **focus** is removed from the kiosk window.
This way, the first click only turns the screen on and focuses the window, allowing subsequent clicks to work as expected.
Additionally, to address the problem that scrolling on the Raspberry Pi only works with the **web browser scrollbar** on the right, the Electron app is configured to **simulate a touch device** using `Emulation.setEmitTouchEventsForMouse`.
Additionally, to address the problem that scrolling only works with the **web browser scrollbar** on the right, the application is configured to **simulate a touch device** using `Emulation.setEmitTouchEventsForMouse`.
This adjustment provides a user experience similar to that of a proper mobile device.
Electron apps are known to be **resource intensive** due to their architecture and the inclusion of a full web browser environment. If you just run the kiosk application without other heavy loads, everything should run smoothly.
@@ -152,13 +168,19 @@ Electron apps are known to be **resource intensive** due to their architecture a
## Issues
Please have a look into the [hardware](https://github.com/leukipp/touchkio/blob/main/HARDWARE.md) documentation if you ran into any issues.
- Depending on the display hardware you are using, some features of the MQTT integration may not fully work (e.g. display brightness control).
- This is especially common when using X11 instead of Wayland (default on Raspberry Pi OS).
**Minimal features** are designed to run on any system without issues:
- A webview kiosk window launched in fullscreen mode and loading the specified `--web-url` website should not cause any problems.
**Extended features** become available when the `--mqtt-*` arguments are provided and the hardware is supported:
- Sensor features that may work out of the box include those that do not require any interaction with the display or keyboard.
- If your hardware is not fully compatible there should be no crashes, but you may miss some sensors.
**Known Issues** that are by-design or for which there is so far no solution:
- You can use Raspberry Pi's build-in screen blanking functionality, however, if the screen is turned on through Home Assistant after being automatically turned off, it will remain on indefinitely.
- It's recommended to either use the built-in screen blanking feature or implement a Home Assistant automation (e.g. presence detection) to manage the screen status.
- Hyperlinks that redirect the browser away from the main window are intentionally disabled.
- This decision was made to maintain a clean design, as navigation buttons to move back and forth between different sites were not included.
- On the Raspberry Pi terminal you may see some *ERROR:gbm_wrapper.cc* messages.
- On Raspberry Pi's terminal you may see some *ERROR:gbm_wrapper.cc* messages.
- This appears to be a [known issue](https://github.com/electron/electron/issues/42322) that currently lacks a fix, but the webview still works.
## Credits