Skip to content

Commit d37e4ea

Browse files
SlykeSlyke
authored
Merge pull request #309 from Paraphraser/20210407-zigbee2mqtt-dockerfile-master
Zigbee2MQTT - IOTstack-friendliness - PR 1 of 2 (master branch)
2 parents f83b6ec + 135696d commit d37e4ea

File tree

4 files changed

+233
-19
lines changed

4 files changed

+233
-19
lines changed

‎.templates/zigbee2mqtt/Dockerfile

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Download base image
2+
FROM koenkk/zigbee2mqtt
3+
4+
# change default configuration.yaml to be IOTstack-friendly
5+
# 1. expect the MQTT service to be in the Mosquitto container
6+
# 2. enable the web front end on port 8080
7+
RUN sed -i.bak \
8+
-e 's/mqtt:\/\/localhost/mqtt:\/\/mosquitto/' \
9+
-e '$s/$/\n\nfrontend:\n port: 8080\n/' \
10+
/app/configuration.yaml
11+
12+
# EOF

‎.templates/zigbee2mqtt/service.yml

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,16 @@
11
zigbee2mqtt:
22
container_name: zigbee2mqtt
3-
image: koenkk/zigbee2mqtt
3+
build: ./.templates/zigbee2mqtt/.
4+
environment:
5+
- TZ=Etc/UTC
6+
ports:
7+
- "8080:8080"
48
volumes:
59
- ./volumes/zigbee2mqtt/data:/app/data
610
devices:
7-
- /dev/ttyAMA0:/dev/ttyACM0
8-
#- /dev/ttyUSB0:/dev/ttyACM0 # Electrolama zig-a-zig-ah! (zzh!) maybe other as well
11+
- /dev/ttyAMA0:/dev/ttyACM0 # should work even if no adapter
12+
#- /dev/ttyACM0:/dev/ttyACM0 # should work if CC2531 connected
13+
#- /dev/ttyUSB0:/dev/ttyACM0 # Electrolama zig-a-zig-ah! (zzh!) maybe other as well
914
restart: unless-stopped
10-
network_mode: host
15+
networks:
16+
- iotstack_nw

‎.templates/zigbee2mqtt_assistant/service.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,6 @@ zigbee2mqtt_assistant:
88
- VIRTUAL_HOST=~^zigbee2mqtt_assistant\..*\.xip\.io
99
- Z2MA_SETTINGS__MQTTSERVER=mosquitto
1010
- VIRTUAL_PORT=8880
11+
networks:
12+
- iotstack_nw
1113

‎docs/Containers/Zigbee2MQTT.md

Lines changed: 209 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,221 @@
11
# Zigbee2MQTT
2-
* [Web Guide](https://www.zigbee2mqtt.io/information/docker.html)
32

4-
## First startup
3+
* [Web Guide](https://www.zigbee2mqtt.io)
4+
* [Flashing the CC2531](https://www.zigbee2mqtt.io/information/flashing_the_cc2531.html)
5+
* [Figuring-out your device identifier](https://www.zigbee2mqtt.io/getting_started/running_zigbee2mqtt.html)
56

6-
After starting the stack check to see if there is an error due to missing device. This is because the devices are mapped differently on the Pi. If your device is not showing in the container then you can also follow the followings steps.
7+
## Service definition change - April 2021
78

8-
If you get a startup failure open the docker-compose.yml file and under zigbee2mqtt change device to map to container (uncomment one of alternatives):
9+
The IOTstack service definition for Zigbee2MQTT is at the following path:
910

10-
```yml
11-
devices:
12-
- /dev/ttyAMA0:/dev/ttyACM0
13-
#- /dev/ttyACM0:/dev/ttyACM0
14-
#- /dev/ttyUSB0:/dev/ttyACM0 # Electrolama zig-a-zig-ah! (zzh!) maybe other as well
11+
```
12+
~/IOTstack/.templates/zigbee2mqtt/service.yml
13+
```
14+
15+
As of April 2021, the service definition changed:
16+
17+
1. The Zigbee2MQTT container no longer runs in host mode.
18+
2. Adds timezone support.
19+
3. Builds the container from a Dockerfile providing appropriate defaults for IOTstack.
20+
4. Re-adds a port mapping for port 8080 (the Zigbee2MQTT web UI).
21+
22+
If you were running the Zigbee2MQTT service before this change, you may wish to compare and contrast your active service definition (in `docker-compose.yml`) with the revised template.
23+
24+
Note:
25+
26+
* You may need to `git pull` to update your local copy of the IOTstack repository against GitHub.
27+
28+
## First startup with CC2531 adapter
29+
30+
The service definition includes:
31+
32+
```
33+
devices:
34+
- /dev/ttyAMA0:/dev/ttyACM0 # should work even if no adapter
35+
#- /dev/ttyACM0:/dev/ttyACM0 # should work if CC2531 connected
36+
#- /dev/ttyUSB0:/dev/ttyACM0 # Electrolama zig-a-zig-ah! (zzh!) maybe other as well
37+
```
38+
39+
The default device (`/dev/ttyAMA0`) probably will **not** work for any Zigbee adapter. It is only there because `/dev/ttyAMA0` exists on Raspberry Pis. Its presence permits the container to come up even though it will not actually be able to connect to an adapter.
40+
41+
If you have a CC2531, properly flashed and connected to a USB port, you should be able to see it:
42+
43+
```
44+
$ ls -l /dev/ttyACM0
45+
crw-rw---- 1 root dialout 166, 0 Apr 7 09:38 /dev/ttyACM0
46+
```
47+
48+
> If you see the error "No such file or directory", you will need to first figure out why your device is not visible.
49+
50+
Assuming your CC2531 is visible:
51+
52+
1. Change the device mapping in `docker-compose.yml` to deactivate `ttyAMA0` in favour of activating `ttyACM0`:
53+
54+
```
55+
devices:
56+
#- /dev/ttyAMA0:/dev/ttyACM0 # should work even if no adapter
57+
- /dev/ttyACM0:/dev/ttyACM0 # should work if CC2531 connected
58+
#- /dev/ttyUSB0:/dev/ttyACM0 # Electrolama zig-a-zig-ah! (zzh!) maybe other as well
59+
```
60+
61+
2. Bring up the container:
62+
63+
```
64+
$ cd ~/IOTstack
65+
$ docker-compose up -d zigbee2mqtt
66+
```
67+
68+
You can also follow the instructions in the Zigbee2MQTT documentation to [work out the identifier of your device](https://www.zigbee2mqtt.io/getting_started/running_zigbee2mqtt.html) and use that instead of `/dev/ttyACM0`. Then, your `docker-compose.yml` might look something like this:
69+
70+
```
71+
devices:
72+
#- /dev/ttyAMA0:/dev/ttyACM0 # should work even if no adapter
73+
#- /dev/ttyACM0:/dev/ttyACM0 # should work if CC2531 connected
74+
#- /dev/ttyUSB0:/dev/ttyACM0 # Electrolama zig-a-zig-ah! (zzh!) maybe other as well
75+
- "/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___xxx:/dev/ttyACM0"
76+
```
77+
78+
## First startup with other adapters
79+
80+
Similar principles apply if you use other adapters. You must work out how the adapter presents itself on your Raspberry Pi and then map it to `/dev/ttyACM0` **inside** the container (ie the common right hand side of every device definition).
81+
82+
## Configuration file
83+
84+
### Active configuration file
85+
86+
Under IOTstack, the **active** configuration file for Zigbee2MQTT appears at the following path:
87+
88+
```
89+
~/IOTstack/volumes/zigbee2mqtt/data/configuration.yaml
90+
```
91+
92+
After you make any changes to the configuration file (using `sudo`), you need to inform the running container by:
93+
94+
```
95+
$ cd ~/IOTstack
96+
$ docker-compose restart zigbee2mqtt
97+
```
98+
99+
### Default configuration file
100+
101+
The IOTstack version of Zigbee2MQTT is built using a Dockerfile located at:
102+
103+
```
104+
~/IOTstack/.templates/zigbee2mqtt/Dockerfile
15105
```
16106

17-
and run docker-compose up -d again
107+
The Dockerfile downloads the **base** `koenkk/zigbee2mqtt` image from DockerHub and then alters the **default** configuration file as it builds a **local** image to:
18108

19-
If the container starts then run `docker logs zigbee2mqtt` so see the log output and if your device is recognised. You may need to reset the device for docker to see it.
109+
* change the default MQTT server URL from "mqtt://localhost" to "mqtt://mosquitto"; and
110+
* activate the Zigbee2MQTT web interface on port 8080.
20111

21-
To edit the configuration file `sudo nano volumes/zigbee2mqtt/data/configuration.yaml` you many need to restart the container for changes to take affect `docker-compose restart zigbee2mqtt`
112+
Those changes are intended to help new IOTstack installations get started with a minimum of fuss.
22113

23-
Please follow instructions on https://www.zigbee2mqtt.io/
114+
However, the **default** configuration file will only become the **active** configuration file in two situations:
115+
116+
* On a first install of Zigbee2MQTT; or
117+
* If you erase the container's persistent storage area. For example:
118+
119+
```
120+
$ cd ~/IOTstack
121+
$ docker-compose stop zigbee2mqtt
122+
$ docker-compose rm -f zigbee2mqtt
123+
$ sudo rm -rf ./volumes/zigbee2mqtt
124+
$ docker-compose up -d zigbee2mqtt
125+
```
126+
127+
In either of those situations, the **active** configuration file will be initialised by copying the **default** configuration file into place as the container comes up.
128+
129+
### If you have an existing configuration file
130+
131+
If you have an existing **active** Zigbee2MQTT configuration file, you may need to make two changes:
132+
133+
1. Alter the Mosquitto URL:
134+
135+
- *before:*
136+
137+
```
138+
server: 'mqtt://localhost'
139+
```
140+
- *after:*
141+
142+
```
143+
server: 'mqtt://mosquitto'
144+
```
145+
146+
2. Enable the web interface (if necessary):
147+
148+
- *append:*
149+
150+
```
151+
frontend:
152+
port: 8080
153+
```
154+
155+
## Checking that the container is working
156+
157+
### Checking status
158+
159+
```
160+
$ docker ps --format "table {{.Names}}\t{{.RunningFor}}\t{{.Status}}" --filter name="zigbee2mqtt"
161+
NAMES CREATED STATUS
162+
zigbee2mqtt 2 hours ago Up 2 hours
163+
```
164+
165+
You are looking for signs that the container is restarting (ie the "Status" column only ever shows a low number of seconds).
166+
167+
### Checking the log
168+
169+
```
170+
$ docker logs zigbee2mqtt
171+
```
172+
173+
You are looking for evidence of malfunction.
174+
175+
### Checking that Zigbee2MQTT is able to communicate with Mosquitto
176+
177+
If you have the Mosquitto clients installed (`sudo apt install -y mosquitto-clients`), you can run the following command:
178+
179+
```
180+
$ mosquitto_sub -v -h "localhost" -t "zigbee2mqtt/#" -F "%I %t %p"
181+
```
182+
183+
One of two things will happen:
184+
185+
* *silence,* indicating that Zigbee2MQTT is **not** able to communicate with Mosquitto.
186+
* *chatter,* proving that Zigbee2MQTT **can** communicate with Mosquitto.
187+
188+
Terminate the `mosquitto_sub` command with a Control-C.
189+
190+
### Checking that the Zigbee2MQTT web GUI is working
191+
192+
Open a browser, and point it to port 8080 on your Raspberry Pi. You should see the Zigbee2MQTT interface.
193+
194+
### terminal access inside the container
195+
196+
To access the terminal run:
197+
198+
```
199+
$ docker exec -it zigbee2mqtt ash
200+
```
201+
202+
> `ash` is **not** a typo!
203+
204+
When you want to leave the container, either type `exit` and press return, or press Control-D.
205+
206+
## Container maintenance
207+
208+
Because the Zigbee2MQTT container is built from a Dockerfile, a normal `pull` command will not automatically download any updates released on DockerHub.
209+
210+
When you become aware of a new version of Zigbee2MQTT being released on DockerHub, do the following:
211+
212+
```
213+
$ cd ~IOTstack
214+
$ docker-compose build --no-cache --pull zigbee2mqtt
215+
$ docker-compose up -d zigbee2mqtt
216+
$ docker system prune
217+
```
24218

25-
## terminal access
219+
Note:
26220

27-
To access the terminal run `docker exec -it zigbee2mqtt /bin/sh`
221+
* Sometimes it is necessary to repeat the `docker system prune` command.

0 commit comments

Comments
 (0)