Zigbee2Mqtt Assistant

This project is a Web GUI for the very good Zigbee2Mqtt software (github sources).

Features

• 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 (or dev for development version)
• 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.

Screenshots

Installation

OPTION 1 - Installing as HASS.IO Add-on

1. Add the following repository url in HASS.IO:

   https://github.com/yllibed/hassio
   

2. Install Zigbee2Mq2ttAssistant
3. Configure your credentials for your MQTT server
4. Enjoy!

OPTION 2 - Installing from docker

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.

Docker Compose example

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

OPTION 3 - Installing from sources & compiling using Visual Studio

1. Compile the solution file
2. 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.

Release Channels

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

Settings

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!

Listening to Alternate Port / Linux Security

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.

Roadmap

• 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 Zigbee Bindings
• Support Docker Manifest (support for ARM + Windows)
• Support mapping of network
• Allow-join auto-off
• Support Zigbee groups
• Support for device images

Requirements

• 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.

Contributing

• 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.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

VivantSenior 📖	alwashe 📖	agreenfield1 📖	neographikal 🤔 🐛	wixoff 🐛	heubi76 🐛	Remco van Geel 🤔
James Darling 🐛	Nenad Bogojevic 🐛 💻	trekker25 💬	Brendan Mullan 🤔	seaverd 🐛	timdonovanuk 🤔	Rafhaan Shah 🤔
foXaCe 🤔	Marius 🐛 🤔	Rick van Hattem 🐛	PeeJay 🐛	Jérôme Laban 💻	John Dyer 🐛	Dan Chen 💻
dystechnic 🐛	FutureCow 🐛	Tobias Nordahl Kristensen 💻 📖	tdn131 🤔	Edzilla2000 🤔	Adrian Böckenkamp 🤔 🐛	David 💻
Magnus Pernemark 💻 💬	Florian Gabsteiger 💻	Помозов Виталий 💻	Maciej Panecki 💬

This project follows the all-contributors specification. Contributions of any kind welcome!