diff --git a/README.md b/README.md
index d7f53c3..0058597 100644
--- a/README.md
+++ b/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, 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**.
+
+[![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)