docs: add hardware

HARDWARE.md

@@ -0,0 +1,33 @@
+# 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.
+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.
+
+### 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. |
+
+### HDMI
+| Device         | Display           | Tested | Status                | Notes                                                 |
+| -------------- | ----------------- | ------ | --------------------- | ----------------------------------------------------- |
+| Raspberry Pi 4 | -                 | ✅      | Partially operational | -                                                     |
+| Raspberry Pi 5 | Generic Non-Touch | ✅      | Partially operational | Display brightness control is not available via MQTT. |
+
+## Contributions
+In case your hardware is not listed above don't worry, give it a try.
+Running `touchkio --web-url=https://demo.home-assistant.io` will most likely just work.
+The only problems that may arise are when controlling the display via the Home Assistant integration.
+
+- If you encounter any problems, please create a new [issue](https://github.com/leukipp/touchkio/issues).
+- If you encounter any problems and are able to fix it yourself, feel free to create a [pull request](https://github.com/leukipp/touchkio/pulls).
+- If everything works as expected and your hardware is not yet listed, you are welcome to add it and create a [pull request](https://github.com/leukipp/touchkio/pulls).

README.md

@@ -1,6 +1,6 @@
 # TouchKio
-**TouchKio** is a Node.js application that utilizes **Electron** to create a kiosk mode specifically designed for a Home Assistant dashboard.
+**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** equipped with a touch display.
+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.
 
 [![display](https://raw.githubusercontent.com/leukipp/touchkio/main/img/display.png)](https://github.com/leukipp/touchkio/blob/main/img/display.png)
 
@@ -22,8 +22,8 @@ The kiosk application can be executed with command line arguments to load a **Ho
 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.
+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 desktop environment.
+This guide assumes that you are using the latest version of **Raspberry Pi OS (64-bit)** together with a **Wayland** based 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.
@@ -96,7 +96,7 @@ touchkio --web-url=http://192.168.1.42:8123 --mqtt-url=mqtt://192.168.1.42:1883
 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.
+Then use `yarn start` to execute the `start` script located in the [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:
@@ -128,7 +128,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 implemented by searching for connected screens inside `/sys/class/drm/*/status`.
+**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 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.
 
@@ -150,8 +150,12 @@ Electron apps are known to be **resource intensive** due to their architecture a
 </div></details>
 
 ## 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).
 - 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.
+  - 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.