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
- 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 - Linux ARM64 (apline):
linux-arm64 - Windows 64 bits (v10.0.17763+):
win-64 - Windows ARM32 (v10.0.17763+):
win-arm32 - Also published as a multi-arch manifest:
latest(ordevfor 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
- Bind device to another one (mostly used for Ikea TRÅDFRI devices - documentation here)
- Visualize device health
- Based on ASP.NET Core 3.0 (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 always carldebilly/zigbee2mqttassistantdraft 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.
- Compile the solution file
- Adjust settings in
appsettings.jsonfor your MQTT connection
Note: it won't compile using the dotnet core build yet. For now, MSBuild is required to build it.
There is 2 branches 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-devpackage - 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!
- Build a CI + publish to docker hub
- Shorter environment variables + config file (for docker image)
- Create a
HASS.IOadd-on- Support for
HASS.IOIngress - 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
Zigbee2Mqttv1.5.0+- Also tested on v1.6.0, v1.7.0 and v1.7.1
- Should work with next herdsman version too
- 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 MUST be activated - event if you're not using it. This shouldn't have any side effect to your installation.
AN ACTUAL INSTALLATION OF HOME ASSISTANT IS NOT REQUIRED
To activate:
homeassistant: truein Zigbee2Mqtt configuration -
last_seenshould 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!