build: update version

README.md

@@ -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.
+
+[![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 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, make sure that you have a Raspberry Pi configured and operational with a compatible touch display.
+This guide assumes that you are using the latest version of **Raspberry Pi OS (64-bit)** together with a desktop environment.
+
+### 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**.
+
+[![mqtt](https://raw.githubusercontent.com/leukipp/touchkio/main/img/mqtt.png)](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)

index.js

@@ -1,5 +1,6 @@
 const fs = require("fs");
 const path = require("path");
+const crypto = require("crypto");
 const readline = require("readline/promises");
 const integration = require("./src/integration");
 const hardware = require("./src/hardware");
@@ -12,6 +13,11 @@ const { app } = require("electron");
  * initialization tasks.
  */
 app.whenReady().then(async () => {
+  const lock = app.requestSingleInstanceLock();
+  if (!lock) {
+    console.error("TouchKio is already running");
+    return app.quit();
+  }
   let args = parseArgs(process);
   let argsProvided = !!Object.keys(args).length;
 
@@ -24,11 +30,14 @@ app.whenReady().then(async () => {
     do {
       args = await promptArgs(process);
     } while (!Object.keys(args).length);
-    fs.writeFileSync(argsFilePath, JSON.stringify(args, null, 2));
+    writeArgs(argsFilePath, args);
   } else if (!argsProvided && argsFileExists) {
-    args = JSON.parse(fs.readFileSync(argsFilePath));
+    args = readArgs(argsFilePath);
   }
-  console.log(JSON.stringify(args, null, 2));
+
+  // Show used arguments
+  const json = JSON.stringify(args, null, 2);
+  console.log(`Arguments: ${json}`);
 
   // Chained init functions
   const chained = [webview.init, hardware.init, integration.init];
@@ -68,8 +77,8 @@ const promptArgs = async (proc) => {
     output: proc.stdout,
   });
 
-  // Array of arguments
-  const arguments = [
+  // Array of prompts
+  const prompts = [
     {
       key: "web_url",
       question: "\nEnter WEB url",
@@ -85,6 +94,11 @@ const promptArgs = async (proc) => {
       question: "Enter WEB zoom level",
       fallback: "1.25",
     },
+    {
+      key: "mqtt",
+      question: "\nConnect to MQTT Broker?",
+      fallback: "y/N",
+    },
     {
       key: "mqtt_url",
       question: "\nEnter MQTT url",
@@ -108,24 +122,39 @@ const promptArgs = async (proc) => {
     {
       key: "check",
       question: "\nEverything looks good?",
-      fallback: "yes",
+      fallback: "Y/n",
     },
   ];
 
-  // Prompt each argument and wait for the answer
+  // Prompt questions and wait for the answers
   let args = {};
-  for (const { key, question, fallback } of arguments) {
-    if (key === "check") {
+  let ignore = [];
+  for (const { key, question, fallback } of prompts) {
+    if (key === "mqtt") {
+      const prompt = `${question} (${fallback}): `;
+      const answer = await read.question(prompt);
+      const value = (answer.trim() || fallback.match(/[YN]/)[0]).toLowerCase();
+      if (!["y", "yes"].includes(value)) {
+        ignore = ignore.concat([
+          "mqtt_url",
+          "mqtt_user",
+          "mqtt_password",
+          "mqtt_discovery",
+        ]);
+      }
+    } else if (key === "check") {
       const json = JSON.stringify(args, null, 2);
       const prompt = `${question}\n${json}\n(${fallback}): `;
-      const answer = (await read.question(prompt)).trim() || fallback;
-      if (!["y", "yes"].includes(answer)) {
+      const answer = await read.question(prompt);
+      const value = (answer.trim() || fallback.match(/[YN]/)[0]).toLowerCase();
+      if (!["y", "yes"].includes(value)) {
         args = {};
       }
-    } else {
+    } else if (!ignore.includes(key)) {
       const prompt = `${question} (${fallback}): `;
-      const answer = (await read.question(prompt)).trim() || fallback;
-      args[key] = answer;
+      const answer = await read.question(prompt);
+      const value = answer.trim() || fallback;
+      args[key] = value;
     }
   }
   read.close();
@@ -133,6 +162,66 @@ const promptArgs = async (proc) => {
   return args;
 };
 
+/**
+ * Writes argument values to the filesystem.
+ *
+ * @param {string} path - Path of the .json file.
+ * @param {Object} args - The arguments object.
+ */
+const writeArgs = (path, args) => {
+  const argc = Object.assign({}, args);
+  if ("mqtt_password" in argc) {
+    argc.mqtt_password = encrypt(argc.mqtt_password);
+  }
+  fs.writeFileSync(path, JSON.stringify(argc, null, 2));
+};
+
+/**
+ * Reads argument values from the filesystem.
+ *
+ * @param {string} path - Path of the .json file.
+ * @returns {Object} The arguments object.
+ */
+const readArgs = (path) => {
+  const args = JSON.parse(fs.readFileSync(path));
+  if ("mqtt_password" in args) {
+    args.mqtt_password = decrypt(args.mqtt_password);
+  }
+  return args;
+};
+
+/**
+ * Helper function for string encryption.
+ *
+ * @param {string} value - Plain text value.
+ * @returns {string} Encrypted value.
+ */
+const encrypt = (value) => {
+  const iv = crypto.randomBytes(16);
+  const key = crypto.scryptSync(hardware.getMachineId(), app.getName(), 32);
+  const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
+  let encrypted = cipher.update(value, "utf8", "hex");
+  encrypted += cipher.final("hex");
+  return Buffer.from(iv.toString("hex") + ":" + encrypted).toString("base64");
+};
+
+/**
+ * Helper function for string decryption.
+ *
+ * @param {string} value - Encrypted value.
+ * @returns {string} Plain text value.
+ */
+const decrypt = (value) => {
+  const p = Buffer.from(value, "base64").toString("utf8").split(":");
+  const iv = Buffer.from(p.shift(), "hex");
+  const key = crypto.scryptSync(hardware.getMachineId(), app.getName(), 32);
+  const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
+  const buffer = Buffer.from(p.join(":"), "hex");
+  let decrypted = decipher.update(buffer, "binary", "utf8");
+  decrypted += decipher.final("utf8");
+  return decrypted;
+};
+
 /**
  * Helper function for asynchronous sleep.
  *

install.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+
+# Download the latest .deb package
+echo -e "Downloading the latest release..."
+
+DEB_URL=$(wget -qO- https://api.github.com/repos/leukipp/touchkio/releases/latest | \
+grep -o '"browser_download_url": "[^"]*\.deb"' | \
+sed 's/"browser_download_url": "//;s/"//g')
+DEB_PATH="/tmp/$(basename "$DEB_URL")"
+
+if [ -z "$DEB_URL" ]; then
+    echo "Download url for .deb file not found."
+    exit 1
+fi
+
+if ! wget --show-progress -q -O "$DEB_PATH" "$DEB_URL"; then
+    echo "Failed to download the .deb file."
+    exit 1
+fi
+
+# Install the latest .deb package
+echo -e "\nInstalling the latest release..."
+
+if ! sudo dpkg -i "$DEB_PATH"; then
+    echo "Installation of .deb file failed."
+    exit 1
+fi
+
+# Create the systemd user service
+echo -e "\nCreating systemd user service..."
+
+SERVICE_FILE="$HOME/.config/systemd/user/touchkio.service"
+mkdir -p "$(dirname "$SERVICE_FILE")" || { echo "Failed to create directory for $SERVICE_FILE"; exit 1; }
+
+bash -c "cat << EOF > \"$SERVICE_FILE\"
+[Unit]
+Description=TouchKio
+After=graphical.target
+
+[Service]
+ExecStart=/usr/bin/touchkio
+Restart=on-failure
+RestartSec=5s 
+
+[Install]
+WantedBy=default.target
+EOF"
+
+systemctl --user enable "$(basename "$SERVICE_FILE")" || { echo "Failed to enable service $SERVICE_FILE"; exit 1; }
+
+# Create the udev rule for backlight
+echo -e "\nCreating udev rule for backlight..."
+
+sudo bash -c 'cat << EOF > /etc/udev/rules.d/backlight-permissions.rules
+SUBSYSTEM=="backlight", KERNEL=="10-0045", RUN+="/bin/chmod 666 /sys/class/backlight/%k/bl_power /sys/class/backlight/%k/brightness"
+EOF'
+
+# Start the setup mode
+echo ""
+read -p "Start touchkio setup? (Y/n) " answer
+if [[ ${answer:-y} == [Yy]* ]]; then
+    echo "/usr/bin/touchkio --setup"
+    /usr/bin/touchkio --setup
+fi

package.json

@@ -2,7 +2,7 @@
     "name": "touchkio",
     "description": "Home Assistant Touch Kiosk",
     "author": "leukipp",
-    "version": "0.0.2",
+    "version": "1.0.0",
     "license": "MIT",
     "main": "index.js",
     "scripts": {

src/hardware.js

@@ -122,6 +122,15 @@ const getSerialNumber = () => {
   ]);
 };
 
+/**
+ * Gets the host machine id using `/etc/machine-id`.
+ *
+ * @returns {string|null} The machine id of the system.
+ */
+const getMachineId = () => {
+  return execSyncCommand("cat", ["/etc/machine-id"]);
+};
+
 /**
  * Gets the host name of the current system using `os.hostname()`.
  *
@@ -364,6 +373,7 @@ module.exports = {
   update,
   getModel,
   getSerialNumber,
+  getMachineId,
   getHostName,
   getUpTime,
   getMemorySize,

src/webview.js

@@ -24,12 +24,10 @@ const init = async (args) => {
   const theme = args.web_theme ? args.web_theme : "dark";
   const zoom = args.web_zoom ? parseFloat(args.web_zoom) : 1.25;
 
-  // Set app theme and name
-  nativeTheme.themeSource = theme;
-  app.setName("TouchKio");
-
   // Init global root window
+  nativeTheme.themeSource = theme;
   WEBVIEW.window = new BaseWindow({
+    title: `TouchKio - ${url.host}`,
     icon: path.join(__dirname, "..", "img", "icon.png"),
   });
   WEBVIEW.window.setMenuBarVisibility(false);
@@ -106,18 +104,28 @@ const windowEvents = (window, zoom) => {
     WEBVIEW.locked = false;
   });
 
-  // Update window status
+  // Handle window status updates
   window.on("minimize", update);
   window.on("restore", update);
   window.on("maximize", update);
   window.on("unmaximize", update);
   window.on("enter-full-screen", update);
   window.on("leave-full-screen", update);
+
+  // Handle signal and exit events
   process.on("SIGINT", app.quit);
   app.on("before-quit", () => {
     WEBVIEW.status = "Terminated";
     integration.update();
   });
+
+  // Handle multiple instances
+  app.on("second-instance", () => {
+    if (window.isMinimized()) {
+      window.restore();
+    }
+    window.focus();
+  });
 };
 
 /**