docs: update docs
This commit is contained in:
leukipp
@@ -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.
|
||||
|
||||
[](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**.
|
||||
|
||||
[](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
|
||||
|
||||
Reference in New Issue
Block a user