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

Add the following repository url in HASS.IO:
```
https://github.com/yllibed/hassio
```
Install Zigbee2Mq2ttAssistant
Configure your credentials for your MQTT server
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

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.

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!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Zigbee2Mqtt Assistant

Features

Screenshots

Installation

OPTION 1 - Installing as `HASS.IO` Add-on

OPTION 2 - Installing from docker

Docker Compose example

OPTION 3 - Installing from sources & compiling using Visual Studio

Release Channels

Settings

Listening to Alternate Port / Linux Security

Roadmap

Requirements

Contributing

Contributors ✨

Files

README.md

Latest commit

History

README.md

File metadata and controls

Zigbee2Mqtt Assistant

Features

Screenshots

Installation

OPTION 1 - Installing as HASS.IO Add-on

OPTION 2 - Installing from docker

Docker Compose example

OPTION 3 - Installing from sources & compiling using Visual Studio

Release Channels

Settings

Listening to Alternate Port / Linux Security

Roadmap

Requirements

Contributing

Contributors ✨

OPTION 1 - Installing as `HASS.IO` Add-on