docs: update readme
This commit is contained in:
leukipp
@@ -1 +1,153 @@
|
||||
# touchkio
|
||||
# TouchKio
|
||||
**TouchKio** is a Node.js application that utilizes **Electron** to create a kiosk mode specifically designed for a Home Assistant dashboard.
|
||||
This tool is packaged as a **.deb** file, making it easy to launch the kiosk mode on a **Raspberry Pi** equipped with the official 7" touch display.
|
||||
|
||||
[](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 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] 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] Touch display power and brightness.
|
||||
- [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.
|
||||
|
||||
## Setup
|
||||
Before you begin, ensure that you have a Raspberry Pi configured and running with a compatible touch display.
|
||||
This guide assumes you are using **Raspberry Pi OS Lite (64-bit)**, which is recommended for kiosk applications due to its **lightweight** nature and minimal overhead.
|
||||
|
||||
### 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.
|
||||
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)
|
||||
|
||||
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 may encounter a **setup procedure** and the Home Assistant **login screen**.
|
||||
It's recommended to create a **dedicated user** (local access only) for your kiosk device.
|
||||
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:
|
||||
```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`
|
||||
|
||||
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.
|
||||
|
||||
## 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 (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%`) |
|
||||
|
||||
These arguments allow you to customize the appearance of the web browser window.
|
||||
|
||||
For example:
|
||||
```bash
|
||||
touchkio --web-url=http://192.168.1.42:8123 --web-theme=dark --web-zoom=1.25
|
||||
```
|
||||
|
||||
### 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 |
|
||||
| ----------------------------- | --------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `--mqtt-url` (Required) | - | Url of the MQTT broker instance (MQTT(S)://IP:PORT) |
|
||||
| `--mqtt-user` (Required) | - | Username which is available in Home Assistant (e.g. create a user named `kiosk`) |
|
||||
| `--mqtt-password` (Required) | - | The password of the user (e.g. use `password`, because it's secure and easy to remember) |
|
||||
| `--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".
|
||||
|
||||
For example:
|
||||
```bash
|
||||
touchkio --web-url=http://192.168.1.42:8123 --mqtt-url=mqtt://192.168.1.42:1883 --mqtt-user=kiosk --mqtt-password=password
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
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` file.
|
||||
There you can adjust the `--web-url` and other arguments for development runs.
|
||||
|
||||
### The nitty gritty
|
||||
|
||||
<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**.
|
||||
This is done within the `install.sh` script, which also creates a `.service` file.
|
||||
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 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.
|
||||
However, `swayidle` still seems to consider the screen to be off and as a result it will not turn off again unless there is some interaction in the meantime.
|
||||
|
||||
When using the MQTT integration, the kiosk application must be able to **detect changes** made on the **device** itself.
|
||||
I managed to achieve this for the `brightness` file by implementing a simple `fs.watch(..)` file listener.
|
||||
However, I found that it **never triggered** for the `bl_power` file.
|
||||
Although the file content changes, none of the filesystem listeners where fired.
|
||||
This could be due to `swayidle`/`wlopm` performing write actions at a deeper level that are not detectable by file listeners.
|
||||
As a result, I went for a **polling solution**, checking the state of both files every **500 milliseconds** for any changes.
|
||||
While I understand this is not ideal, it's necessary to ensure proper functionality.
|
||||
|
||||
Keep in mind that default arguments are stored as plain text in `~/.config/touchkio/Arguments.json`.
|
||||
This file also includes the **MQTT user password**, which is somewhat obfuscated/encrypted, but in a way that it could be easily reverse engineered.
|
||||
Implementing stronger **security measures** would complicate the setup process and could discourage some users from configuring the application properly.
|
||||
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.
|
||||
When the screen **turns off**, I remove **focus** 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, I configured the Electron app 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.
|
||||
|
||||
</div></details>
|
||||
|
||||
## Issues
|
||||
- Currently, only the Raspberry Pi 5 in combination with the new touch display 2 supports the MQTT integration.
|
||||
- Other variations, such as Raspberry Pi 4 or Raspberry Pi 5 with touch display 1, could likely be added, but this will require additional testing and contributions via pull requests.
|
||||
- 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.
|
||||
- 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
|
||||
Inspired by the one and only Raspberry Pi Master Lord, [Jeff Geerling](https://www.jeffgeerling.com/blog/2024/home-assistant-and-carplay-pi-touch-display-2).
|
||||
|
||||
## License
|
||||
[MIT](https://github.com/leukipp/touchkio/blob/main/LICENSE)
|
||||
|
||||
Reference in New Issue
Block a user