This project is a Web GUI for the very good Zigbee2Mqtt software (github sources).
- If you're using zigbee2mqtt for your devices, it's a must.
- Display zigbee devices and the status of each of them.
- Display an interactive map of the network
- Touchlink support
- Automatically turn off allow join of Zigbee network - no matter how you turned it on (don't need to be turned on from Z2MA). Default is 20 minutes.
- Flexible installation:
- Available as a HASS.IO add-on (integration into Home Assistant). Ingress is supported too. note: can be used without Home Assistant.
- Published as a docker images for following architectures
- Linux AMD64 (alpine):
linux-x64
- Linux ARM32 (buster-slim):
linux-arm32
(armv7
+ processor required - Won't work on Raspberry Pi Zero or Zero-W!) - Linux ARM64 (apline):
linux-arm64
(armv8
+ processor required) - Windows 64 bits (v10.0.17763+):
win-64
- Windows ARM32 (v10.0.17763+):
win-arm32
- Also published as a multi-arch manifest:
latest
(ordev
for development version)
- Linux AMD64 (alpine):
- Operations on devices:
- Allow network join - no more need to setup virtual switches in HA just for that.
- Rename devices
- Remove devices from network (+ forced remove)
- Configure device (force reconfiguration of device's reportings)
- Bind device to another one (mostly used for Ikea TRΓ DFRI devices - documentation here)
- Visualize device health
- OTA Upgrades
- Based on ASP.NET Core 3.1 LTS.
- Add the following repository url in HASS.IO:
https://github.com/yllibed/hassio
- Install
Zigbee2Mq2ttAssistant
- Configure your credentials for your MQTT server
- Enjoy!
Run the following command by replacing <mqttserver>
, <mqttusername>
, <mqttpassword>
with your correct values.
docker run -p 8880:80 -e "Z2MA_SETTINGS__MQTTSERVER=<mqttserver>" -e "Z2MA_SETTINGS__MQTTUSERNAME=<mqttusername>" -e "Z2MA_SETTINGS__MQTTPASSWORD=<mqttpassword>" --restart unless-stopped carldebilly/zigbee2mqttassistant
Draft note: Environment variables are currently the easiest way to set those settings. Open an issue if you need it to be in a configuration file/folder.
If you're using Docker Compose, fell free to use this. 8880 is the port where the service will be available, from the outside of the container itself.
######################################
# Zigbee2MqttAssistant (GUI Interface)
######################################
# https://github.com/yllibed/Zigbee2MqttAssistant
zigbee2mqttAssistant:
image: carldebilly/zigbee2mqttassistant
container_name: zigbee2mqttAssistant
environment:
- Z2MA_SETTINGS__MQTTSERVER={IP_OR_HOSTNAME}
- Z2MA_SETTINGS__MQTTUSERNAME={MQTTUSERNAME}
- Z2MA_SETTINGS__MQTTPASSWORD={MQTTPASSWORD}
# Set to your TimeZone when using on Linux https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
# Won't work if you're using the Windows version of the container
- TZ=Europe/Copenhagen
ports:
- 8880:80
restart: unless-stopped
Accepted for Docker-compose Manifest v.3
- Compile the solution file
- Adjust settings in
appsettings.json
for your MQTT connection
Note: it won't compile using the dotnet core build yet. For now, MSBuild is required to build it.
This method is not recommended because any change to dependencies will require you to update your development/deployment environment.
There is 2 channels for Zigbee2MqttAssistant: dev
and stable
. When a build version is considered stable enough, it will be pushed from dev
to stable
(there's no git branch dedicated to the stable version).
If you want to try newest features, you can get the dev
branch in the following way:
- On HASS.IO, pick
zigbee2mqttassistant-dev
package - On Docker, pick the following package/tag:
carldebilly/zigbee2mqttassistant:dev
You can refer to Settings.cs
file for more information
on allowed settings. Here's the important settings:
Field | Default | Usage |
---|---|---|
BaseTopic |
"zigbee2mqtt" |
Base MQTT topic when Zigbee2Mqtt is publishing its data |
HomeAssistantDiscoveryBaseTopic |
"homeassistant" |
Base MQTT topic for HASS Discovery |
MqttServer |
"mqtt" |
Name or IP address of the MQTT server. Put only the name or the address of the server here. DON'T USE THE mqtt:// ADDRESS FORMAT. |
MqttSecure |
false |
If should use TLS to connect to MQTT server. Valid options are true , false or "insecure" . Insecure means it's using TLS, but without any server certificate check. |
MqttPort |
1883 (normal) or 8883 (secured) |
Port for MQTT server |
MqttUsername |
"" |
Username for MQTT server |
MqttPassword |
"" |
Password for MQTT server |
LowBatteryThreshold |
30 |
Threshold for triggering low-battery warning (%) |
AllowJoinTimeout |
20 |
Timeout for turning off allow join of Zigbee network. Set 0 to disable this feature |
AutosetLastSeen |
false |
Will turn on last_Seen on Zigbee2Mqtt automatically when detected as off. |
DevicesPollingSchedule |
*/12 * * * * |
Schedule (cron expression) for device list refresh. Default value: every 12 minutes. |
NetworkScanSchedule |
0 */3 * * * |
Schedule (cron expression) for device list refresh. Default value: every 3 hours. This network scan can have high cost on your network: details here. |
For environment variables, you can use any of the previous fields, prefixed with Z2MA_SETTINGS__
. By example, you can specify the MqttPort
with an environment variable in the following way:
Z2MA_SETTINGS__MQTTPORT=11883
Z2MA_SETTINGS__MQTTSECURE=INSECURE
Note: Uppercase is used here as a convention. It's actually case insensitive.
If you need to change cron expression for other values, you should use a site like https://crontab.guru/ to validate them. Attention: if you specify specific hours, take care of the time offset (timezone) inside the container!
When running this container on Linux, it's a best practice to run containers with a non-root account. To achieve that with Zigbee2MqttAssistant, it's required to change the listening port to something else than 80
, because ports number under 1024
are restricted to priviledged users.
Since it's using ASPNET Core, it's possible to change the listening port in the container to something else by using one of the following method:
-
Set the
--urls
parameter on the command line:# Command line to set alternate listening port in the container # using the --urls parameter docker run carldebilly/zigbee2mqttassistant --urls http://*:8888
-
Use the
ASPNETCORE_URLS
environment variable:# Command line to set alternate listening port in the container # using the ASPNETCORE_URLS environment variable docker run -e "ASPNETCORE_URLS=http://*:8888" carldebilly/zigbee2mqttassistant
This method can also be used to set another scheme (https://
), a specific ip address or many ports at the same time. Microsoft ASPNET Core documentation.
- Build a CI + publish to docker hub
- Shorter environment variables + config file (for docker image)
- Create a
HASS.IO
add-on- Support for
HASS.IO
Ingress - Automatic update of repo on new version
- Support for
- Support Zigbee Bindings
- Support Docker Manifest (support for ARM + Windows)
- Support mapping of network
- Allow-join auto-off
- Support Zigbee groups
- Support for device images
-
You need a running installation of
Zigbee2Mqtt
v1.5.0+- Also tested on v1.6.0, v1.7.0, v1.7.1 and v1.8.0, v1.11 (needed for firmware update feature)
-
Simple MQTT connection with username/password (TLS supported)
- Client certificates not supported yet - open an issue if your need it.
-
Zigbee2Mqtt required settings:
-
Home Assistant Discovery should be activated for a better experience (to see components)
AN ACTUAL INSTALLATION OF HOME ASSISTANT IS NOT REQUIRED
To activate:
homeassistant: true
in Zigbee2Mqtt configuration -
last_seen
should be activated on Zigbee2Mqtt (any format supported). There's an option (AutosetLastSeen
) to activate it automatically through MQTT.
-
- If you have suggestions or find bugs, don't hesitate to open and issue here, on Github.
- PULL REQUESTS are welcome! Please open an issue first and link it to your PR. If you're unsure about how to implement a feature, we should discuss it in the issue first.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!