From 14b49c511e1bab7d44af48c9cec6dbf6ebc7d683 Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Sat, 15 Mar 2025 18:25:35 +0100
Subject: [PATCH 01/25] fix: docs for Koenkk/zigbee2mqtt#26608
---
docs/guide/getting-started/README.md | 60 +++++++++++++++++++++++-----
1 file changed, 50 insertions(+), 10 deletions(-)
diff --git a/docs/guide/getting-started/README.md b/docs/guide/getting-started/README.md
index 3a61a8237b1d5..65102cef43beb 100755
--- a/docs/guide/getting-started/README.md
+++ b/docs/guide/getting-started/README.md
@@ -28,9 +28,48 @@ You can run Zigbee2MQTT in different ways, see [Installation](../installation/).
[Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) is used to
set up and run Zigbee2MQTT.
+### Onboarding
+
+Zigbee2MQTT offers an onboarding process on first run (when no `configuration.yaml` exists).
+
+The onboarding page, by default, is reachable at the same URL as the frontend (`http://localhost:8080`). _Note: This URL may be different for specific setups (like Home Assistant)._
+
+If you successfully configure everything during onboarding, you can skip the following steps in the guide below: `1.1`, `1.2`, and `2.2`.
+If the `adapter type` is unknown by the discovery process, you can find a list of the most common adapters in the corresponding pages: [zstack](../adapters/zstack.md), [ember](../adapters/emberznet.md), [deconz](../adapters/deconz.md), [zigate](../adapters/zigate.md), [zboss](../adapters/zboss.md).
+
+:::tip TIP
+The adapter discovery process will try to find serial and mDNS-discoverable devices.
+Refreshing the page will re-execute the discovery process.
+
+_Note: This may not be available on all setups. If not, you will have to enter the adapter path and type manually._
+:::
+
+If Zigbee2MQTT fails validation after submitting the configuration, the page will show the error details.
+
+If Zigbee2MQTT fails to start after submitting the initial configuration (due to something like a wrong adapter path), the onboarding will be executed again on the following start.
+
+:::tip TIP
+Onboarding failure pages will hold the `node` process from exiting until the page's `Close` button is triggered or the process is manually exited.
+:::
+
+:::tip TIP
+You can also force the onboarding to run later (if configuration needs changing) with the environment variable `Z2M_ONBOARD_FORCE_RUN=1`.
+Depending on your setup, this may be offered in form of a toggle (Home Assistant add-on for example), or you may have to set it manually for the `node` process.
+:::
+
+:::details Environment variables available to customize the onboarding process
+The following environment variables are available, if your setup requires customizing the onboarding server:
+
+- `Z2M_ONBOARD_NO_SERVER=1` => disable onboarding server completely (_supersedes all below_)
+- `Z2M_ONBOARD_URL=http://localhost:8080` => set the URL where the onboarding page can be reached
+- `Z2M_ONBOARD_NO_FAILURE_PAGE=1` => disable failure pages (_failure is logged, and the process exits immediately_)
+- `Z2M_ONBOARD_FORCE_RUN=1` => see above TIP
+- `Z2M_ONBOARD_NO_REDIRECT=1` => if frontend is enabled, prevent the onboarding validation page from trying to redirect to frontend (_useful for setups where frontend has an unusual URL_)
+ :::
+
### 1.) Find the Zigbee-Adapter
-#### 1.1) USB Zigbee adapter
+:::details 1.1) USB Zigbee adapter
After you plug the adapter in see the `dmesg` output to find the device location:
@@ -52,8 +91,9 @@ crw-rw---- 1 root dialout 188, May 16 19:15 /dev/ttyUSB0
```
Here we can see that the adapter is owned by `root` and accessible from all users in the `dialout` group.
+:::
-#### 1.2) Network Zigbee adapter
+:::details 1.2) Network Zigbee adapter
Zigbee2MQTT supports mDNS autodiscovery feature for network Zigbee adapters. If your network Zigbee adapter supports mDNS, you do not need to know the IP address of your network Zigbee adapter, Zigbee2MQTT will detect it and configure. Otherwise, you need to know the network Zigbee adapter's IP address:
@@ -61,10 +101,11 @@ Zigbee2MQTT supports mDNS autodiscovery feature for network Zigbee adapters. If
- Go to your router/switch setting and find the list of connected device.
- Find the IP address and of your Ethernet Zigbee adapter.
- You also need to know the communication port of your Ethernet Zigbee-Adapter. In most cases (TubeZB, SLZB-06) the default port is `6638`. You can check the port at your Adapter's user manual.
+ :::
### 2.) Setup and start Zigbee2MQTT
-#### 2.1) Configure Docker
+:::details 2.1) Configure Docker
It's assumed, that you have a recent version of Docker and Docker Compose installed.
@@ -98,7 +139,9 @@ services:
- /dev/ttyUSB0:/dev/ttyUSB0
```
-#### 2.2) Configure Zigbee2MQTT
+:::
+
+:::details 2.2) Configure Zigbee2MQTT
In the next step we'll create a simple [Zigbee2MQTT config file](../configuration/) in `zigbee2mqtt-data/configuration.yaml`.
@@ -123,8 +166,9 @@ serial:
```
Where `slzb-06` is the mDNS name of your network Zigbee adapter.
+:::
-#### 2.3) Start Zigbee2MQTT
+:::details 2.3) Start Zigbee2MQTT
We should now have two files in our directory and can start the stack:
@@ -144,6 +188,7 @@ After some short time you should see some log messages that Mosquitto and Zigbee
You can open the frontend using [http://localhost:8080](http://localhost:8080) (or the hostname of your remote server).
We can now go on and pair our first device.
+:::
## Connect a device
@@ -156,8 +201,3 @@ Once you see something similar to below in the log your device is paired and you
```
Zigbee2MQTT:info 2019-11-09T12:19:56: Successfully interviewed '0x00158d0001dc126a', device has successfully been paired
```
-
-::: warning ATTENTION
-It's important that `permit_join` is set to `false` in your `configuration.yaml` after initial setup is
-done to keep your Zigbee network safe and to avoid accidental joining of other Zigbee devices.
-:::
From bde2fb71baf133157f6555d1a5eba44e9400603a Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Mon, 17 Mar 2025 18:41:12 +0100
Subject: [PATCH 02/25] update
---
docs/guide/installation/01_linux.md | 4 ++++
docs/guide/installation/02_docker.md | 14 ++++++++++++--
docs/guide/installation/05_windows.md | 4 ++++
docs/guide/installation/06_freebsd_jail.md | 4 ++++
4 files changed, 24 insertions(+), 2 deletions(-)
diff --git a/docs/guide/installation/01_linux.md b/docs/guide/installation/01_linux.md
index 944131309b329..262422a855ab7 100755
--- a/docs/guide/installation/01_linux.md
+++ b/docs/guide/installation/01_linux.md
@@ -68,6 +68,10 @@ pnpm --version
## Configuring
+:::tip TIP
+See [Onboarding](../getting-started/README.md#onboarding) to make this step easier.
+:::
+
Before we can start Zigbee2MQTT we need to copy and edit the `configuration.yaml` file. This file contains the configuration which will be used by Zigbee2MQTT.
Copy and open the configuration file:
diff --git a/docs/guide/installation/02_docker.md b/docs/guide/installation/02_docker.md
index 5e261c0ea23c4..1b97d2d7ed686 100755
--- a/docs/guide/installation/02_docker.md
+++ b/docs/guide/installation/02_docker.md
@@ -15,10 +15,20 @@ Start by figuring out the location of your adapter as explained [here](../config
## Creating the initial configuration
-Navigate to the directory where you will store the Zigbee2MQTT data and execute the following command:
+Navigate to the directory where you will store the Zigbee2MQTT data and execute the following command to create the folder:
```bash
-mkdir data && wget https://raw.githubusercontent.com/Koenkk/zigbee2mqtt/master/data/configuration.example.yaml -O data/configuration.yaml
+mkdir data
+```
+
+:::tip TIP
+See [Onboarding](../getting-started/README.md#onboarding) to make the below easier. It will allow you to configure this on container start via a simple frontend page.
+:::
+
+You can grab the default `configuration.yaml` with the following command:
+
+```bash
+wget https://raw.githubusercontent.com/Koenkk/zigbee2mqtt/master/data/configuration.example.yaml -O data/configuration.yaml
```
Now configure the MQTT server and adapter location as explained [here](./01_linux.md#configuring).
diff --git a/docs/guide/installation/05_windows.md b/docs/guide/installation/05_windows.md
index 3d8c6b457d154..09bfdeaca7de4 100644
--- a/docs/guide/installation/05_windows.md
+++ b/docs/guide/installation/05_windows.md
@@ -45,6 +45,10 @@ In order to be able to communicate with your USB device over a virtual COM port,
## Configuring
+:::tip TIP
+See [Onboarding](../getting-started/README.md#onboarding) to make this step easier.
+:::
+
1. Copy `data\configuration.example.yaml` to `data\configuration.yaml`
1. Open `data\configuration.yaml` in a text editor
1. Change the MQTT configuration to match your setup, see the [documentation](../configuration/mqtt.md) for more info.
diff --git a/docs/guide/installation/06_freebsd_jail.md b/docs/guide/installation/06_freebsd_jail.md
index f1b272fb03aaf..2a5f4c42e70bb 100644
--- a/docs/guide/installation/06_freebsd_jail.md
+++ b/docs/guide/installation/06_freebsd_jail.md
@@ -51,6 +51,10 @@ pnpm run build
## Configuring
+:::tip TIP
+See [Onboarding](../getting-started/README.md#onboarding) to make this step easier.
+:::
+
Configuration is the same as on [Linux](01_linux.md#configuring).
Note that the `configuration.yaml` is at a different location:
From 637b29efe7df1cd45527e1453d549c1239224fa7 Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Mon, 17 Mar 2025 21:23:15 +0100
Subject: [PATCH 03/25] update
---
docs/guide/installation/01_linux.md | 2 +-
docs/guide/installation/02_docker.md | 2 +-
docs/guide/installation/05_windows.md | 2 +-
docs/guide/installation/06_freebsd_jail.md | 2 +-
4 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/guide/installation/01_linux.md b/docs/guide/installation/01_linux.md
index 262422a855ab7..4aa96cd2548c6 100755
--- a/docs/guide/installation/01_linux.md
+++ b/docs/guide/installation/01_linux.md
@@ -69,7 +69,7 @@ pnpm --version
## Configuring
:::tip TIP
-See [Onboarding](../getting-started/README.md#onboarding) to make this step easier.
+As an alternative of this, you can also use [Onboarding](../getting-started/README.md#onboarding).
:::
Before we can start Zigbee2MQTT we need to copy and edit the `configuration.yaml` file. This file contains the configuration which will be used by Zigbee2MQTT.
diff --git a/docs/guide/installation/02_docker.md b/docs/guide/installation/02_docker.md
index 1b97d2d7ed686..08ef4770cf985 100755
--- a/docs/guide/installation/02_docker.md
+++ b/docs/guide/installation/02_docker.md
@@ -22,7 +22,7 @@ mkdir data
```
:::tip TIP
-See [Onboarding](../getting-started/README.md#onboarding) to make the below easier. It will allow you to configure this on container start via a simple frontend page.
+As an alternative of this, you can also use [Onboarding](../getting-started/README.md#onboarding). It will allow you to configure this on container start via a simple frontend page.
:::
You can grab the default `configuration.yaml` with the following command:
diff --git a/docs/guide/installation/05_windows.md b/docs/guide/installation/05_windows.md
index 09bfdeaca7de4..3f0f8f4fc7642 100644
--- a/docs/guide/installation/05_windows.md
+++ b/docs/guide/installation/05_windows.md
@@ -46,7 +46,7 @@ In order to be able to communicate with your USB device over a virtual COM port,
## Configuring
:::tip TIP
-See [Onboarding](../getting-started/README.md#onboarding) to make this step easier.
+As an alternative of this, you can also use [Onboarding](../getting-started/README.md#onboarding).
:::
1. Copy `data\configuration.example.yaml` to `data\configuration.yaml`
diff --git a/docs/guide/installation/06_freebsd_jail.md b/docs/guide/installation/06_freebsd_jail.md
index 2a5f4c42e70bb..3a291b84a1252 100644
--- a/docs/guide/installation/06_freebsd_jail.md
+++ b/docs/guide/installation/06_freebsd_jail.md
@@ -52,7 +52,7 @@ pnpm run build
## Configuring
:::tip TIP
-See [Onboarding](../getting-started/README.md#onboarding) to make this step easier.
+As an alternative of this, you can also use [Onboarding](../getting-started/README.md#onboarding).
:::
Configuration is the same as on [Linux](01_linux.md#configuring).
From 88a1abed3c52c9229601e1cc47d93bd89e7f6763 Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Mon, 17 Mar 2025 21:25:05 +0100
Subject: [PATCH 04/25] remove install from getting-started
---
docs/guide/getting-started/README.md | 130 +--------------------------
1 file changed, 2 insertions(+), 128 deletions(-)
diff --git a/docs/guide/getting-started/README.md b/docs/guide/getting-started/README.md
index 65102cef43beb..81f514cd0a4a9 100755
--- a/docs/guide/getting-started/README.md
+++ b/docs/guide/getting-started/README.md
@@ -22,13 +22,10 @@ In order to use Zigbee2MQTT we need the following hardware:
See [Improve network range and stability](../../advanced/zigbee/02_improve_network_range_and_stability.md).
:::
-## Installation
-You can run Zigbee2MQTT in different ways, see [Installation](../installation/). In this example
-[Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) is used to
-set up and run Zigbee2MQTT.
+## Onboarding
-### Onboarding
+You can run Zigbee2MQTT in different ways, see [Installation](../installation/).
Zigbee2MQTT offers an onboarding process on first run (when no `configuration.yaml` exists).
@@ -67,129 +64,6 @@ The following environment variables are available, if your setup requires custom
- `Z2M_ONBOARD_NO_REDIRECT=1` => if frontend is enabled, prevent the onboarding validation page from trying to redirect to frontend (_useful for setups where frontend has an unusual URL_)
:::
-### 1.) Find the Zigbee-Adapter
-
-:::details 1.1) USB Zigbee adapter
-
-After you plug the adapter in see the `dmesg` output to find the device location:
-
-```bash
-$ sudo dmesg
-
-...
-usbcore: registered new interface driver ch341
-usbserial: USB Serial support registered for ch341-uart
-ch341 3-1:1.0: ch341-uart converter detected
-usb 3-1: ch341-uart converter now attached to ttyUSB0
-```
-
-As we can see the adapter was identified and mounted on `ttyUSB0`.
-
-```bash
-$ ls -l /dev/ttyUSB0
-crw-rw---- 1 root dialout 188, May 16 19:15 /dev/ttyUSB0
-```
-
-Here we can see that the adapter is owned by `root` and accessible from all users in the `dialout` group.
-:::
-
-:::details 1.2) Network Zigbee adapter
-
-Zigbee2MQTT supports mDNS autodiscovery feature for network Zigbee adapters. If your network Zigbee adapter supports mDNS, you do not need to know the IP address of your network Zigbee adapter, Zigbee2MQTT will detect it and configure. Otherwise, you need to know the network Zigbee adapter's IP address:
-
-- Connect your adapter to your LAN network either over Ethernet or Wi-Fi, depending on your adapter.
-- Go to your router/switch setting and find the list of connected device.
-- Find the IP address and of your Ethernet Zigbee adapter.
-- You also need to know the communication port of your Ethernet Zigbee-Adapter. In most cases (TubeZB, SLZB-06) the default port is `6638`. You can check the port at your Adapter's user manual.
- :::
-
-### 2.) Setup and start Zigbee2MQTT
-
-:::details 2.1) Configure Docker
-
-It's assumed, that you have a recent version of Docker and Docker Compose installed.
-
-First, we create a folder where we want the project to reside `mkdir folder-name`. In the folder, we create we save the `docker-compose.yml` file which defines how Docker would run our containers. The following file consists of two services, one for the MQTT-Server and one for Zigbee2MQTT itself. Be sure to adjust the file to your needs and match the devices-mount in the case your adapter was not mounted on `/dev/ttyUSB0` or in case you use a network adapter.
-
-```yaml
-version: '3.8'
-services:
- mqtt:
- image: eclipse-mosquitto:2.0
- restart: unless-stopped
- volumes:
- - './mosquitto-data:/mosquitto'
- ports:
- - '1883:1883'
- - '9001:9001'
- command: 'mosquitto -c /mosquitto-no-auth.conf'
-
- zigbee2mqtt:
- container_name: zigbee2mqtt
- restart: unless-stopped
- image: koenkk/zigbee2mqtt
- volumes:
- - ./zigbee2mqtt-data:/app/data
- - /run/udev:/run/udev:ro
- ports:
- - 8080:8080
- environment:
- - TZ=Europe/Berlin
- devices:
- - /dev/ttyUSB0:/dev/ttyUSB0
-```
-
-:::
-
-:::details 2.2) Configure Zigbee2MQTT
-
-In the next step we'll create a simple [Zigbee2MQTT config file](../configuration/) in `zigbee2mqtt-data/configuration.yaml`.
-
-NOTE: Docker Compose makes the MQTT-Server available using "mqtt" hostname.
-
-
-
-For network adapters, `serial` > `port` settings should look like this:
-
-```yaml
-serial:
- port: tcp://192.168.1.12:6638
-```
-
-Where `192.168.1.112` is the IP address of your network Zigbee adapter, and `6638` is the port.
-
-In case you adapter supports mDNS, you can omit the IP address and use a configuration like:
-
-```yaml
-serial:
- port: mdns://slzb-06
-```
-
-Where `slzb-06` is the mDNS name of your network Zigbee adapter.
-:::
-
-:::details 2.3) Start Zigbee2MQTT
-
-We should now have two files in our directory and can start the stack:
-
-```bash
-$ find
-./docker-compose.yml
-./zigbee2mqtt-data/configuration.yaml
-
-# First start
-$ docker compose up -d
-
-# Check the logs
-$ docker compose logs -f
-```
-
-After some short time you should see some log messages that Mosquitto and Zigbee2MQTT is running now.
-You can open the frontend using [http://localhost:8080](http://localhost:8080) (or the hostname of your remote server).
-
-We can now go on and pair our first device.
-:::
-
## Connect a device
Search the [supported devices](../../supported-devices/) for your device and follow the instructions how to pair.
From 37794f0b266a0223b530a93b08d831311a92af89 Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Mon, 17 Mar 2025 21:26:09 +0100
Subject: [PATCH 05/25] fix
---
docs/guide/getting-started/README.md | 1 -
1 file changed, 1 deletion(-)
diff --git a/docs/guide/getting-started/README.md b/docs/guide/getting-started/README.md
index 81f514cd0a4a9..67308ea0e05a9 100755
--- a/docs/guide/getting-started/README.md
+++ b/docs/guide/getting-started/README.md
@@ -22,7 +22,6 @@ In order to use Zigbee2MQTT we need the following hardware:
See [Improve network range and stability](../../advanced/zigbee/02_improve_network_range_and_stability.md).
:::
-
## Onboarding
You can run Zigbee2MQTT in different ways, see [Installation](../installation/).
From 22ffaa56a319eaa141efc77b1a77f6212ea00b42 Mon Sep 17 00:00:00 2001
From: Nerivec <62446222+Nerivec@users.noreply.github.com>
Date: Mon, 17 Mar 2025 21:33:55 +0100
Subject: [PATCH 06/25] update
---
docs/guide/getting-started/README.md | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/docs/guide/getting-started/README.md b/docs/guide/getting-started/README.md
index 67308ea0e05a9..d9de74674938b 100755
--- a/docs/guide/getting-started/README.md
+++ b/docs/guide/getting-started/README.md
@@ -22,6 +22,10 @@ In order to use Zigbee2MQTT we need the following hardware:
See [Improve network range and stability](../../advanced/zigbee/02_improve_network_range_and_stability.md).
:::
+## Installation
+
+The next step is to install Zigbee2MQTT, follow [installation instructions](../installation/) for your platform. Once Zigbee2MQTT is started, you can continue with the onboarding procedure below.
+
## Onboarding
You can run Zigbee2MQTT in different ways, see [Installation](../installation/).
From 6c2f5664ad7fe74ae9b19d71cee15ca5ed42c785 Mon Sep 17 00:00:00 2001
From: Koen Kanters
Date: Tue, 18 Mar 2025 22:06:05 +0100
Subject: [PATCH 07/25] Some improvements
---
docs/guide/getting-started/README.md | 13 +-
.../07_python_virtual_environment.md | 112 ------------------
docs/guide/installation/README.md | 1 -
docs/images/onboarding.png | Bin 0 -> 201145 bytes
docs/information/virtual_environment.md | 9 --
5 files changed, 6 insertions(+), 129 deletions(-)
delete mode 100755 docs/guide/installation/07_python_virtual_environment.md
create mode 100644 docs/images/onboarding.png
delete mode 100755 docs/information/virtual_environment.md
diff --git a/docs/guide/getting-started/README.md b/docs/guide/getting-started/README.md
index d9de74674938b..f5e485632a293 100755
--- a/docs/guide/getting-started/README.md
+++ b/docs/guide/getting-started/README.md
@@ -9,13 +9,13 @@ next: ../usage/
In order to use Zigbee2MQTT we need the following hardware:
-1. 
**A Zigbee Adapter** which is the interface between the Computer (or Server) where you run Zigbee2MQTT and the Zigbee radio
+1. **A Zigbee adapter** which is the interface between the host system where you run Zigbee2MQTT and the Zigbee radio
communication. Zigbee2MQTT supports a variety of adapters with different kind of connections like USB, GPIO or remote via WIFI or Ethernet.
- Recommended adapters have a chip starting with CC2652 or CC1352. See [supported Adapters](../adapters/README.md). It's recommended to check out your adapter's recommendation details before the installation process, to find out whether it needs any additional configuration parameters.
+ Recommended adapters are [zStack](../adapters/zstack.md) and [EmberZNet](../adapters/emberznet.md). See [Supported Adapters](../adapters/README.md) for all supported adapters. It's recommended to check out your adapter's recommendation details before the installation process, to find out whether it needs any additional configuration parameters.
-2. 
**A Server** where you would run Zigbee2MQTT. Most Raspberry-Pi models are known to work but you can run it on many computers and platforms including Linux, Windows and MacOS. It should have an MQTT broker installed. [Mosquitto](https://www.mosquitto.org/download/) ([Tutorial for Raspberry-Pi](https://randomnerdtutorials.com/how-to-install-mosquitto-broker-on-raspberry-pi/)) is the recommended MQTT broker but [others](https://mqtt.org/software/) should also work fine.
+2. **A host system** where you would run Zigbee2MQTT (e.g. a Raspberry Pi or Intel NUC). Zigee2MQTT runs on many computers and platforms including Linux, Windows and MacOS. It should have an MQTT broker installed. [Mosquitto](https://www.mosquitto.org/download/) ([tutorial for Raspberry-Pi](https://randomnerdtutorials.com/how-to-install-mosquitto-broker-on-raspberry-pi/)) is the recommended MQTT broker but [others](https://mqtt.org/software/) should also work fine.
-3. 
One or more **Zigbee Devices** which will be paired with Zigbee2MQTT.
+3. One or more **Zigbee devices** which will be paired with Zigbee2MQTT.
::: tip TIP
To improve network range and stability use a USB extension cable. If you experience ANY trouble with device (timeouts, not pairing, devices unreachable, devices dropping from the network, etc.) this is the first thing to do to avoid interference.
@@ -28,13 +28,12 @@ The next step is to install Zigbee2MQTT, follow [installation instructions](../i
## Onboarding
-You can run Zigbee2MQTT in different ways, see [Installation](../installation/).
-
Zigbee2MQTT offers an onboarding process on first run (when no `configuration.yaml` exists).
The onboarding page, by default, is reachable at the same URL as the frontend (`http://localhost:8080`). _Note: This URL may be different for specific setups (like Home Assistant)._
-If you successfully configure everything during onboarding, you can skip the following steps in the guide below: `1.1`, `1.2`, and `2.2`.
+
+
If the `adapter type` is unknown by the discovery process, you can find a list of the most common adapters in the corresponding pages: [zstack](../adapters/zstack.md), [ember](../adapters/emberznet.md), [deconz](../adapters/deconz.md), [zigate](../adapters/zigate.md), [zboss](../adapters/zboss.md).
:::tip TIP
diff --git a/docs/guide/installation/07_python_virtual_environment.md b/docs/guide/installation/07_python_virtual_environment.md
deleted file mode 100755
index a0ad8ac0509e0..0000000000000
--- a/docs/guide/installation/07_python_virtual_environment.md
+++ /dev/null
@@ -1,112 +0,0 @@
----
-next: ../configuration/
----
-
-# Python Virtual Environment
-
-It is possible to run Zigbee2MQTT in a virtual environment, this has been tested with a Raspberry Pi 3B+.
-
-This guide is similar to the [Running Zigbee2MQTT on Linux guide](./01_linux.md), follow the steps from there by replacing the steps with the ones from below.
-
-## Installing
-
-```bash
-# Clone Zigbee2MQTT repository
-sudo git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
-sudo chown -R pi:pi /opt/zigbee2mqtt
-
-# Enter folder
-cd /opt/zigbee2mqtt
-
-# Install python env
-python3 -m venv .
-
-# Activate environment
-source /opt/zigbee2mqtt/bin/activate
-
-# Upgrade pip, wheel and setuptools
-pip install --upgrade pip wheel setuptools
-
-# Install node environment
-pip install nodeenv
-
-# Init node environment
-nodeenv -p -n 20.14.0
-
-# Install pnpm
-npm install -g pnpm
-
-# Deactivate and activate environment to be sure
-deactivate
-source /opt/zigbee2mqtt/bin/activate
-
-# Install dependencies
-cd /opt/zigbee2mqtt
-pnpm i --frozen-lockfile
-
-# Deactivate environment
-deactivate
-```
-
-## Starting Zigbee2MQTT
-
-```bash
-# Enter folder
-cd /opt/zigbee2mqtt
-
-# Activate environment
-source /opt/zigbee2mqtt/bin/activate
-
-# Start
-pnpm start
-
-# ctrl + c to quit
-
-# Deactivate environment
-deactivate
-```
-
-## (Optional) Running as a daemon with systemctl
-
-To run Zigbee2MQTT as daemon (in background) and start it automatically on boot we will run Zigbee2MQTT with systemctl.
-
-```bash
-# Create a systemctl configuration file for Zigbee2MQTT
-sudo nano /etc/systemd/system/zigbee2mqtt.service
-```
-
-Add the following to this file:
-
-```bash
-[Unit]
-Description=zigbee2mqtt
-After=network.target
-
-[Service]
-Type=notify
-Environment=NODE_PATH=/opt/zigbee2mqtt/lib/node_modules
-Environment=NPM_CONFIG_PREFIX=/opt/zigbee2mqtt
-Environment=npm_config_prefix=/opt/zigbee2mqtt
-Environment=NODE_ENV=production
-ExecStart=/opt/zigbee2mqtt/bin/node index.js
-WorkingDirectory=/opt/zigbee2mqtt
-StandardOutput=inherit
-StandardError=inherit
-Restart=always
-User=pi
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Now continue with _Verify that the configuration works:_ from the _Running Zigbee2MQTT guide_.
-
-## (For later) Update Zigbee2MQTT to the latest version
-
-To update Zigbee2MQTT to the latest version, execute:
-
-```sh
-# Run the update script from the Zigbee2MQTT directory
-cd /opt/zigbee2mqtt
-./update.sh
-```
diff --git a/docs/guide/installation/README.md b/docs/guide/installation/README.md
index 4fb560a620755..2b20694ef161b 100644
--- a/docs/guide/installation/README.md
+++ b/docs/guide/installation/README.md
@@ -11,7 +11,6 @@ Zigbee2MQTT was written in Node.js and runs almost on every platform with afford
- [openHABian](./04_openhabian.md)
- [Windows](./05_windows.md)
- [FreeBSD jail](./06_freebsd_jail.md)
-- [Python virtual-environment](./07_python_virtual_environment.md)
- [Kubernetes](./08_kubernetes.md)
## Optional
diff --git a/docs/images/onboarding.png b/docs/images/onboarding.png
new file mode 100644
index 0000000000000000000000000000000000000000..b853e7a7f84bdbbd2da08f0e71b7a883678b3558
GIT binary patch
literal 201145
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