From fac5a48f36a9904e098effb6f6e3f018d4a23c07 Mon Sep 17 00:00:00 2001 From: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> Date: Tue, 16 May 2023 16:00:49 +1000 Subject: [PATCH 1/2] 2023-05-16 Zigbee2MQTT adaptation to expected kernel change - master branch - PR 1 of 2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Background: - #690 – Kernel update may remove /dev/ttyAMA0 Changes: 1. Adopts generic syntax for device specification to prompt user to add the relevant key (`ZIGBEE2MQTT_DEVICE_PATH`) and path (eg `/dev/ttyUSB0`) to `.env`. Example: ``` $ echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyUSB0 >>~/IOTstack/.env ``` 2. Adopts `TZ=${TZ:-Etc/UTC}` 3. Adds (disabled) environment variable to enable debugging. 4. Rewrites documentation to explain the how-to of device-path setup. Signed-off-by: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> --- .templates/zigbee2mqtt/service.yml | 5 +++-- docs/Containers/Zigbee2MQTT.md | 32 +++++++++++++----------------- 2 files changed, 17 insertions(+), 20 deletions(-) diff --git a/.templates/zigbee2mqtt/service.yml b/.templates/zigbee2mqtt/service.yml index c9281c2a9..b5fefdb6c 100644 --- a/.templates/zigbee2mqtt/service.yml +++ b/.templates/zigbee2mqtt/service.yml @@ -2,16 +2,17 @@ zigbee2mqtt: container_name: zigbee2mqtt image: koenkk/zigbee2mqtt:latest environment: - - TZ=Etc/UTC + - 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: - - /dev/ttyAMA0:/dev/ttyACM0 + - "${ZIGBEE2MQTT_DEVICE_PATH:?eg echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyACM0 >>~/IOTstack/.env}:/dev/ttyACM0" restart: unless-stopped depends_on: - mosquitto diff --git a/docs/Containers/Zigbee2MQTT.md b/docs/Containers/Zigbee2MQTT.md index ff97d59fb..bf3cd223d 100644 --- a/docs/Containers/Zigbee2MQTT.md +++ b/docs/Containers/Zigbee2MQTT.md @@ -131,25 +131,21 @@ For those reasons, it is better to take the time to identify your Zigbee adapter What the output is telling you is that the *by-id* path is a symbolic link to `/dev/ttyACM0`. Although this *may* always be true on your Raspberry Pi, the only part that is actually *guaranteed* to be true is the *by-id* path, which is why you should use it. -7. Use your favourite text editor to open your *compose file*. -8. Find your `zigbee2mqtt` service definition and identify this line: +7. Once you have identified the path to your adapter, you communicate that information to docker-compose like this: - ```yaml - - /dev/ttyAMA0:/dev/ttyACM0 + ```console + $ echo ZIGBEE2MQTT_DEVICE_PATH=/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00125A00183F06C5-if00 >>~/IOTstack/.env ``` - The default from the IOTstack template maps the *external* (Raspberry Pi) device `/dev/ttyAMA0` to the *internal* (Zigbee2MQTT container) device `/dev/ttyACM0`. - - > On the Raspberry Pi, the *external* device `/dev/ttyAMA0` is the Bluetooth adapter. It was chosen as the default because it normally exists and its presence avoids docker-compose refusing to bring up the container. However, a Bluetooth adapter doesn't actually respond like a Zigbee adapter so the Zigbee2MQTT container will go into a restart loop if you start it before completing these steps. A side-effect of the container entering a restart loop is the web GUI never starts. - -9. Replace `/dev/ttyAMA0` with your *by-id* path. Example: + Note: + + * if you forget to do this step, docker-compose will display the following error message: - ```yaml - - /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00125A00183F06C5-if00:/dev/ttyACM0 - ``` + ``` + parsing ~/IOTstack/docker-compose.yml: error while interpolating services.zigbee2mqtt.devices.[]: required variable ZIGBEE2MQTT_DEVICE_PATH is missing a value: eg echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyACM0 >>~/IOTstack/.env + ``` -10. Save your work. -11. Continue from [bring up your stack](#upStack). +8. Continue from [bring up your stack](#upStack). ## Configuration { #configuration } @@ -172,10 +168,6 @@ $ docker-compose up -d zigbee2mqtt The default service definition provided with IOTstack includes the following environment variables: -* `TZ=Etc/UTC` - - You should replace `Etc/UTC` with a value that is correct for your location. - * `ZIGBEE2MQTT_CONFIG_MQTT_SERVER=mqtt://mosquitto:1883` { #mqttServer } Typical values for this are: @@ -212,6 +204,10 @@ The default service definition provided with IOTstack includes the following env ``` See [Checking the log](#checkLog) for more information about why this is useful. + +* `- DEBUG=zigbee-herdsman*` { #enableDebug } + + Enabling this variable turns on extended debugging inside the container. ### Configuration file { #confFile } From b21e3231fb5d9811ff9f65b4578a35b73199ef27 Mon Sep 17 00:00:00 2001 From: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> Date: Tue, 16 May 2023 17:00:39 +1000 Subject: [PATCH 2/2] fix TZ reference Signed-off-by: Phill Kelley <34226495+Paraphraser@users.noreply.github.com> --- docs/Containers/Zigbee2MQTT.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/Containers/Zigbee2MQTT.md b/docs/Containers/Zigbee2MQTT.md index bf3cd223d..c8b0ff116 100644 --- a/docs/Containers/Zigbee2MQTT.md +++ b/docs/Containers/Zigbee2MQTT.md @@ -389,16 +389,17 @@ zigbee2mqtt: container_name: zigbee2mqtt image: koenkk/zigbee2mqtt:latest environment: - - TZ=Etc/UTC + - 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: - - /dev/ttyAMA0:/dev/ttyACM0 + - "${ZIGBEE2MQTT_DEVICE_PATH:?eg echo ZIGBEE2MQTT_DEVICE_PATH=/dev/ttyACM0 >>~/IOTstack/.env}:/dev/ttyACM0" restart: unless-stopped depends_on: - mosquitto