incorporate changes from PR #785

Paraphraser · Paraphraser · commit db56bc4d35fe · 2025-01-12T00:53:01.000+11:00
Signed-off-by: Phill Kelley &lt;34226495+Paraphraser@users.noreply.github.com&gt;
diff --git a/docs/Containers/Zigbee2MQTT.md b/docs/Containers/Zigbee2MQTT.md
@@ -168,15 +168,15 @@ See also:
 The default service definition provided by IOTstack for Zigbee2MQTT includes this device mapping:
 
 ``` yaml
-  devices:
-    - "${ZIGBEE2MQTT_DEVICE_PATH:?eg echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyACM0 >>~/IOTstack/.env}:/dev/ttyACM0"
+devices:
+  - "${ZIGBEE2MQTT_DEVICE_PATH:?eg echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyACM0 >>~/IOTstack/.env}:/dev/ttyACM0"
 ```
 
-The above syntax assumes your Zigbee adapter connects via USB. You should either remove both of those lines from your compose file, or make the `devices` clause inactive by prepending `x-`, like this:
+The above syntax assumes your Zigbee adapter connects via USB. You should either remove or comment-out both of those lines from your compose file. An alternative approach is to make the `devices` clause inactive by prepending `x-`, like this:
 
 ``` yaml
-  x-devices:
-    - "${ZIGBEE2MQTT_DEVICE_PATH:?eg echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyACM0 >>~/IOTstack/.env}:/dev/ttyACM0"
+x-devices:
+  - "${ZIGBEE2MQTT_DEVICE_PATH:?eg echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyACM0 >>~/IOTstack/.env}:/dev/ttyACM0"
 ```
 
 You tell the container how to find your Zigbee adapter across the network by using an environment variable:
@@ -196,7 +196,34 @@ Example:
 - ZIGBEE2MQTT_CONFIG_SERIAL_PORT=tcp://192.168.1.5:6638
 ```
 
-## Configuration
+## Configuration { #configTemplate }
+
+When you select Zigbee2MQTT in the IOTstack menu, the following service definition is added to your compose file:
+
+``` yaml linenums="1"
+zigbee2mqtt:
+  container_name: zigbee2mqtt
+  image: koenkk/zigbee2mqtt:latest
+  environment:
+    - TZ=${TZ:-Etc/UTC}
+    - ZIGBEE2MQTT_CONFIG_SERIAL_PORT=/dev/ttyACM0
+    - ZIGBEE2MQTT_CONFIG_SERIAL_ADAPTER=zstack
+    - ZIGBEE2MQTT_CONFIG_MQTT_SERVER=mqtt://mosquitto:1883
+    # only enable the next line for Zigbee2MQTT v1
+    # - ZIGBEE2MQTT_CONFIG_FRONTEND=true
+    - ZIGBEE2MQTT_CONFIG_FRONTEND_ENABLED=true
+    - ZIGBEE2MQTT_CONFIG_ADVANCED_LOG_SYMLINK_CURRENT=true
+    # - DEBUG=zigbee-herdsman*
+  ports:
+    - "8080:8080"
+  volumes:
+    - ./volumes/zigbee2mqtt/data:/app/data
+  devices:
+    - "${ZIGBEE2MQTT_DEVICE_PATH:?eg echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyACM0 >>~/IOTstack/.env}:/dev/ttyACM0"
+  restart: unless-stopped
+  depends_on:
+    - mosquitto
+```
 
 ### Environment variables { #envVars }
 
@@ -219,12 +246,14 @@ For example, if the Zigbee2MQTT `configuration.yaml` example you are following c
 ``` yaml
 serial:
   port: /dev/ttyACM0
+  adapter: zstack
 ```
 
-then the equivalent environment variable is:
+then the equivalent environment variables are:
 
 ``` yaml
 - ZIGBEE2MQTT_CONFIG_SERIAL_PORT=/dev/ttyACM0
+- ZIGBEE2MQTT_CONFIG_SERIAL_ADAPTER=zstack
 ```
 
 Note:
@@ -240,50 +269,139 @@ $ docker-compose up -d zigbee2mqtt
 
 The default service definition provided with IOTstack includes the following environment variables:
 
-* <a name="mqttServer"></a>`ZIGBEE2MQTT_CONFIG_MQTT_SERVER=mqtt://mosquitto:1883`
+#### timezone support { #tzSupport }
 
-	Typical values for this are:
+``` yaml
+- TZ=${TZ:-Etc/UTC}
+```
 
-	- `mqtt://mosquitto:1883`
+This assumes that your system timezone has been copied to `~/IOTstack/.env`, otherwise defaults to `Etc/UTC`.
 
-		This is default value supplied with the IOTstack template. It assumes that both Zigbee2MQTT and the Mosquitto broker are running in non-host mode containers on the same Raspberry Pi.
+If you want to set your timezone:
+
+``` console
+$ echo "TZ=$(cat /etc/timezone)" >> ~/IOTstack/.env
+```
 
-	- `mqtt://localhost:1883`
+Most (but not yet all) IOTstack containers use this syntax. The idea is that a single value set in `.env` will ensure your containers operate in the same timezone.
 
-		This would be appropriate if you were to run Zigbee2MQTT in host mode and the Mosquitto broker was running on the same Raspberry Pi.
+#### serial adapter { #serialAdapter }
 
-	- `mqtt://«host-or-ip»:1883`
+``` yaml
+- ZIGBEE2MQTT_CONFIG_SERIAL_PORT=/dev/ttyACM0
+```
 
-		If the Mosquitto broker is running on a *different* computer, replace `«host-or-ip»` with the IP address or domain name of that other computer. You should also remove or comment-out the following lines from the service definition:
+The default value of `/dev/ttyACM0` works in conjunction with the `devices` clause:
 
-		```yaml
-		depends_on:
-		  - mosquitto
-		```
+``` yaml
+devices:
+  - "${ZIGBEE2MQTT_DEVICE_PATH:?eg echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyACM0 >>~/IOTstack/.env}:/dev/ttyACM0"
+```
 
-		The `depends_on` clause ensures that the Mosquitto container starts alongside the Zigbee2MQTT container. That would not be appropriate if Mosquitto was running on a separate computer.
+Taken together, these assume your Zigbee adapter is connected to a local USB port. If you are using a [remote adapter](#identifyRemoteAdapter) then you should:
 
-* <a name="frontEndEnable"></a>`ZIGBEE2MQTT_CONFIG_FRONTEND=true`
+1. Change the right hand side of this variable so that it points to your adapter. For example:
 
-	This variable activates the Zigbee2MQTT web interface on port 8080. If you want to change the port number where you access the Zigbee2MQTT web interface, see [connecting to the web GUI](#connectGUI).
+	``` yaml
+	- ZIGBEE2MQTT_CONFIG_SERIAL_PORT=tcp://«ipaddr»:«port»`
+	```
 
-* <a name="logSymlink"></a>`ZIGBEE2MQTT_CONFIG_ADVANCED_LOG_SYMLINK_CURRENT=true`
+2. Remove, comment-out or inactivate the `devices` clause (as explained in [remote adapters](#identifyRemoteAdapter)).
 
-	Defining this variable causes Zigbee2MQTT to create a symlink pointing to the current log **folder** at the path:
+#### adapter type { #adapterType }
 
+``` yaml
+- ZIGBEE2MQTT_CONFIG_SERIAL_ADAPTER=zstack
+```
+
+Identify your adapter from the [official list](https://www.zigbee2mqtt.io/guide/configuration/adapter-settings.html#basic-configuration). At the time of writing, the possible values were `zstack`, `ember`, `deconz`, `zigate` or `zboss`.
+
+#### MQTT server type { #mqttServer }
+
+``` yaml
+- ZIGBEE2MQTT_CONFIG_MQTT_SERVER=mqtt://mosquitto:1883
+```
+
+Typical values for this are:
+
+- `mqtt://mosquitto:1883`
+
+	This is default value supplied with the IOTstack template. It assumes that both Zigbee2MQTT and the Mosquitto broker are running in non-host mode containers on the same Raspberry Pi.
+
+- `mqtt://localhost:1883`
+
+	This would be appropriate if you were to run Zigbee2MQTT in host mode and the Mosquitto broker was running on the same Raspberry Pi.
+
+- `mqtt://«host-or-ip»:1883`
+
+	If the Mosquitto broker is running on a *different* computer, replace `«host-or-ip»` with the IP address or domain name of that other computer. You should also remove or comment-out the following lines from the service definition:
+
+	```yaml
+	depends_on:
+	  - mosquitto
 	```
-	~/IOTstack/volumes/zigbee2mqtt/data/log/current
-	```
 
-	See [Checking the log](#checkLog) for more information about why this is useful.
+	The `depends_on` clause ensures that the Mosquitto container starts alongside the Zigbee2MQTT container. That would not be appropriate if Mosquitto was running on a separate computer.
+
+#### front end { #frontEndEnable }
+
+The "front end" is the name given to the Zigbee2MQTT web interface on port 8080. If you want to change the port number where you access the Zigbee2MQTT web interface, see [connecting to the web GUI](#connectGUI).
+
+Zigbee2MQTT version 2 introduced an incompatibility with this setting. The IOTstack template contains the following lines:
+
+``` yaml
+# only enable the next line for Zigbee2MQTT v1
+# - ZIGBEE2MQTT_CONFIG_FRONTEND=true
+- ZIGBEE2MQTT_CONFIG_FRONTEND_ENABLED=true
+```
+
+If you are running Zigbee2MQTT version 1 then the front end will not be enabled unless you uncomment:
+
+``` yaml
+- ZIGBEE2MQTT_CONFIG_FRONTEND=true
+```
+
+Zigbee2MQTT version 1 ignores the following environment variable so you do not need to comment it out:
+
+``` yaml
+- ZIGBEE2MQTT_CONFIG_FRONTEND_ENABLED=true
+```
+
+However, if you have been running Zigbee2MQTT version 1 and you upgrade to version 2 then you **must** either delete or comment-out:
+
+``` yaml
+# - ZIGBEE2MQTT_CONFIG_FRONTEND=true
+```
+
+If you do not do that then the container will go into a restart loop. If you examine the container's log, you will see this error:
+
+```
+frontend must be object
+```
+
+That error is telling you to comment-out that environment variable.
+
+#### logging { #logSymlink }
+
+``` yaml
+- ZIGBEE2MQTT_CONFIG_ADVANCED_LOG_SYMLINK_CURRENT=true
+```
+
+Defining this variable causes Zigbee2MQTT to create a symlink pointing to the current log **folder** at the path:
 
-* `- DEBUG=zigbee-herdsman*`
+```
+~/IOTstack/volumes/zigbee2mqtt/data/log/current
+```
 
-	Enabling this variable turns on extended debugging inside the container.
+See [Checking the log](#checkLog) for more information about why this is useful.
 
-See also [Remote adapters](#identifyRemoteAdapter) for an example of:
+#### debugging { #debugging }
 
-* `- ZIGBEE2MQTT_CONFIG_SERIAL_PORT=tcp://«ipaddr»:«port»`
+``` yaml
+- DEBUG=zigbee-herdsman*
+```
+
+Enabling this variable turns on extended debugging inside the container.
 
 ### Configuration file { #confFile }
 
@@ -329,25 +447,21 @@ You are looking for evidence that the container is restarting (ie the "Status" c
 
 ### Checking the log { #checkLog }
 
-You can't use `docker logs zigbee2mqtt` to inspect the Zigbee2MQTT container's logs. That's because Zigbee2MQTT writes its logging information to the path:
+You can watch the container's log using this command:
 
 ```
-~/IOTstack/volumes/zigbee2mqtt/data/log/yyyy-mm-dd.hh-mm-ss/log.txt
+$ docker logs -f zigbee2mqtt
 ```
 
-where `yyyy-mm-dd.hh-mm-ss` is the date and time the container was last started. This means that you have to identify the folder with the latest timestamp before you can inspect the log contained within it.
-
-Fortunately, Zigbee2MQTT offers a shortcut. If the [`… LOG_SYMLINK_CURRENT`](#logSymlink) environment variable is `true` then the path to the *current* log will be:
+Press <kbd>control</kbd>+<kbd>c</kbd> to terminate the command. An alternative is to observe the following path using commands like `cat` and `tail`:
 
 ```
-~/IOTstack/volumes/zigbee2mqtt/data/log/current/log.txt
+~/IOTstack/volumes/zigbee2mqtt/data/log/current/log.log
 ```
 
-You can use commands like `cat` and `tail` to examine the *current* log. Example:
+Note:
 
-```console
-$ cat ~/IOTstack/volumes/zigbee2mqtt/data/log/current/log.txt
-```
+* this depends on the [`… LOG_SYMLINK_CURRENT`](#logSymlink) environment variable being set to `true`.
 
 ### Checking Mosquitto connectivity { #checkMQTT }
 
@@ -444,7 +558,59 @@ In words:
 
 You can omit the `zigbee2mqtt` arguments from the `pull` and `up` commands, in which case `docker-compose` makes an attempt to pull any available updates for all non-Dockerfile-based images, and then instantiates any new images it has downloaded.
 
-## Service definition change { #update202204 }
+## 2025 v1 to v2 upgrade { #update202501 }
+
+If you have been running Zigbee2MQTT version 1 but do a "pull" from DockerHub you will be upgraded to version 2. The first time you do this, you may encounter the following error:
+
+```
+frontend must be object
+```
+
+This is caused by a configuration incompatibility between v1 and v2. Although it is not *difficult* to update your service definition to work with v2, if you are in a hurry to get your Zigbee service running again you can revert to v1 by making a temporary alteration to your service definition, like this:
+
+``` yaml
+# image: koenkk/zigbee2mqtt:latest
+image: koenkk/zigbee2mqtt:1.42.0
+```
+
+Then, "up" the container:
+
+``` console
+$ cd ~/IOTstack
+$ docker-compose up -d zigbee2mqtt
+```
+
+When you are ready to upgrade to v2, you will need to undo the above change, and you will also need to update your Zigbee2MQTT service definition based on the [template](#configTemplate). In general terms, you will need to do the following:
+
+1. If you have a locally-connected USB adapter then you will need to add:
+
+	``` yaml
+	- ZIGBEE2MQTT_CONFIG_SERIAL_PORT=/dev/ttyACM0
+	```
+
+	If you have a network adapter, you will have that variable defined already so you should not change it.
+
+2. Add:
+
+	``` yaml
+	- ZIGBEE2MQTT_CONFIG_SERIAL_ADAPTER=zstack
+	```
+
+	Then read the explanation about [adapter types](#adapterType) and make a decision on whether `zstack` is the correct choice.
+
+3. The value of `ZIGBEE2MQTT_CONFIG_MQTT_SERVER` will probably be correct so you should not change it.
+
+4. Replace the existing `ZIGBEE2MQTT_CONFIG_FRONTEND` with the following:
+
+	``` yaml 
+	# only enable the next line for Zigbee2MQTT v1
+	# - ZIGBEE2MQTT_CONFIG_FRONTEND=true
+	- ZIGBEE2MQTT_CONFIG_FRONTEND_ENABLED=true
+	```
+
+5. Any other variables you have set will likely be correct so leave those alone.
+
+## 2022 Service definition change { #update202204 }
 
 This information is for existing users of the Zigbee2MQTT container.
 
@@ -459,28 +625,7 @@ If you were using the Zigbee2MQTT container in IOTstack before April 2022, you s
 
 > You *could* run the menu, then de-select and re-select Zigbee2MQTT. That *will* have the effect of applying the updated service definition but it also risks overwriting any other customisations you may have in place. That is why editing your *compose file* is the recommended approach.
 
-The updated service definition is included here for ease of reference:
-
-``` { .yaml linenums="1" }
-zigbee2mqtt:
-  container_name: zigbee2mqtt
-  image: koenkk/zigbee2mqtt:latest
-  environment:
-    - TZ=${TZ:-Etc/UTC}
-    - ZIGBEE2MQTT_CONFIG_MQTT_SERVER=mqtt://mosquitto:1883
-    - ZIGBEE2MQTT_CONFIG_FRONTEND=true
-    - ZIGBEE2MQTT_CONFIG_ADVANCED_LOG_SYMLINK_CURRENT=true
-    # - DEBUG=zigbee-herdsman*
-  ports:
-    - "8080:8080"
-  volumes:
-    - ./volumes/zigbee2mqtt/data:/app/data
-  devices:
-    - "${ZIGBEE2MQTT_DEVICE_PATH:?eg echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyACM0 >>~/IOTstack/.env}:/dev/ttyACM0"
-  restart: unless-stopped
-  depends_on:
-    - mosquitto
-```
+The updated service definition is included [here](#configTemplate) for ease of reference.
 
 The changes you should make to your existing Zigbee2MQTT service definition are:
 
@@ -498,17 +643,7 @@ The changes you should make to your existing Zigbee2MQTT service definition are:
 
 	This causes IOTstack to use Zigbee2MQTT images "as is" from [DockerHub](https://hub.docker.com/r/koenkk/zigbee2mqtt/tags).
 
-2. Add these environment variables:
-
-	```yaml
-	  - ZIGBEE2MQTT_CONFIG_MQTT_SERVER=mqtt://mosquitto:1883
-	  - ZIGBEE2MQTT_CONFIG_FRONTEND=true
-	  - ZIGBEE2MQTT_CONFIG_ADVANCED_LOG_SYMLINK_CURRENT=true
-	```
-
-	The first two have the **identical** effect to the changes previously made via the Dockerfile. The last variable makes it easier for you to find and [view the current log](#checkLog).
-
-	See [environment variables](#envVars) for more detail.
+2. Use the [template](#configTemplate) as a guide to adjusting your environment variables. See also [environment variables](#envVars) for more detail.
 
 3. Add the dependency clause:
 
