diff --git a/README.md b/README.md
index 490ec6b..f52d617 100644
--- a/README.md
+++ b/README.md
@@ -2,10 +2,10 @@
Futurehome add-on for Home Assistant. Designed to be a complete drop-in replacement for the official Futurehome app, with support for all device types compatible with the Futurehome hub.
-
-
+
+
-
+
## Features
@@ -16,17 +16,9 @@ This add-on:
* Supports interaction with devices comparable to the official Futurehome app.
* Supports pairing and unpairing devices.
-## Installation
+## Installation Guide
-todo: rewrite the installation instructions
-
-1. In the Futurehome app, go to Settings > My household > Smarthub and enable Local API.
-2. (Optional) In the Futurehome app go to Settings > ??? > ??? and install Thingsplex integration (Needed for support of pairing new devices).
-3. (Optional but highly recommended) Block the hub’s internet (WAN) access in your router settings to prevent future firmware updates.
-4. In Home Assistant, enable the **MQTT** integration.
-5. [Add this add-on repository to Home Assistant](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fadrianjagielak%2Fhome-assistant-futurehome) and refresh the page.
-6. Open the **Add-on Store** and search for "Futurehome".
-7. Install, configure, and start the Futurehome add-on.
+See the full [Installation Guide](https://github.com/adrianjagielak/home-assistant-futurehome/blob/master/docs/installation.md) for step-by-step setup instructions.
# Futurehome Device Services Compatibility Chart
diff --git a/assets/home_assistant_screenshot_dark_mode.jpg b/docs/assets/home_assistant_screenshot_dark_mode.jpg
similarity index 100%
rename from assets/home_assistant_screenshot_dark_mode.jpg
rename to docs/assets/home_assistant_screenshot_dark_mode.jpg
diff --git a/assets/home_assistant_screenshot_light_mode.jpg b/docs/assets/home_assistant_screenshot_light_mode.jpg
similarity index 100%
rename from assets/home_assistant_screenshot_light_mode.jpg
rename to docs/assets/home_assistant_screenshot_light_mode.jpg
diff --git a/docs/assets/installation_ha_config.jpg b/docs/assets/installation_ha_config.jpg
new file mode 100644
index 0000000..44ce84b
Binary files /dev/null and b/docs/assets/installation_ha_config.jpg differ
diff --git a/docs/assets/installation_local_api.jpg b/docs/assets/installation_local_api.jpg
new file mode 100644
index 0000000..7335add
Binary files /dev/null and b/docs/assets/installation_local_api.jpg differ
diff --git a/docs/assets/installation_thingsplex.jpg b/docs/assets/installation_thingsplex.jpg
new file mode 100644
index 0000000..5bef122
Binary files /dev/null and b/docs/assets/installation_thingsplex.jpg differ
diff --git a/assets/pairing.gif b/docs/assets/pairing.gif
similarity index 100%
rename from assets/pairing.gif
rename to docs/assets/pairing.gif
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..c16ed51
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,52 @@
+# Installation Guide
+
+## Step 1: Configure the Futurehome App
+
+1. **Enable Local API**
+
+ Open the Futurehome app and navigate to:
+ **Settings > My household > Smarthub**, then set up **Local API**.
+
+ 
+
+3. **(Optional) Install Thingsplex Integration**
+
+ Thingsplex is an integration for debugging hub adapters. It's also used by this add-on to support pairing and unpairing devices.
+
+ * Go to **Settings > Integrations**, install and start **"Thingsplex Advanced UI"**.
+ * Open the integration’s **"..."** menu, set a **username** and **password**, then **save**.
+
+ 
+
+4. **(Optional but recommended) Block WAN Access**
+ To prevent future firmware updates that might break local functionality, block the hub’s internet access via your router settings.
+
+---
+
+## Step 2: Set Up in Home Assistant
+
+4. **Enable MQTT Integration**
+
+ In Home Assistant, go to **Settings > Devices & Services > Integrations** and enable **MQTT**.
+
+5. **Add the Futurehome Add-on Repository**
+
+ Use this link to add the custom repository to your Home Assistant:
+ [Add repository](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fadrianjagielak%2Fhome-assistant-futurehome).
+ Then **refresh** the page.
+
+6. **Install the Add-on**
+
+ * Open the **Add-on Store** and search for **"Futurehome"**.
+ * Install, configure, and start the add-on.
+
+
+
+---
+
+## Troubleshooting
+
+**Q: My Futurehome trial expired and I can’t modify hub settings to enable Local API. What can I do?**
+
+1. Perform a **factory reset** on the hub.
+2. Open the Futurehome app, **create a new household**, and **re-add the hub**.
diff --git a/futurehome/README.md b/futurehome/README.md
index 123b379..7633b8d 100644
--- a/futurehome/README.md
+++ b/futurehome/README.md
@@ -2,9 +2,9 @@
Futurehome add-on for Home Assistant. Designed to be a complete drop-in replacement for the official Futurehome app, with support for all device types compatible with the Futurehome hub.
-
+
-
+
## Features
@@ -15,17 +15,9 @@ This add-on:
* Supports interaction with devices comparable to the official Futurehome app.
* Supports pairing and unpairing devices.
-## Installation
+## Installation Guide
-todo: rewrite the installation instructions
-
-1. In the Futurehome app, go to Settings > My household > Smarthub and enable Local API.
-2. (Optional) In the Futurehome app go to Settings > ??? > ??? and install Thingsplex integration (Needed for support of pairing new devices).
-3. (Optional but highly recommended) Block the hub’s internet (WAN) access in your router settings to prevent future firmware updates.
-4. In Home Assistant, enable the **MQTT** integration.
-5. [Add this add-on repository to Home Assistant](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fadrianjagielak%2Fhome-assistant-futurehome) and refresh the page.
-6. Open the **Add-on Store** and search for "Futurehome".
-7. Install, configure, and start the Futurehome add-on.
+See the full [Installation Guide](https://github.com/adrianjagielak/home-assistant-futurehome/blob/master/docs/installation.md) for step-by-step setup instructions.
# Futurehome Device Services Compatibility Chart
diff --git a/futurehome/config.yaml b/futurehome/config.yaml
index 712604f..993f096 100644
--- a/futurehome/config.yaml
+++ b/futurehome/config.yaml
@@ -1,6 +1,6 @@
# https://developers.home-assistant.io/docs/add-ons/configuration#add-on-config
name: Futurehome
-version: '0.1.14'
+version: '0.1.17'
slug: futurehome
description: Local Futurehome Smarthub integration
url: 'https://github.com/adrianjagielak/home-assistant-futurehome'