Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/yllibed/Zigbee2MqttAssistant

GUI for Zigbee2Mqtt running in docker and HASS.IO
https://github.com/yllibed/Zigbee2MqttAssistant

home-assistant home-automation mqtt smarthome zigbee zigbee2mqtt

Last synced: 12 days ago
JSON representation

GUI for Zigbee2Mqtt running in docker and HASS.IO

Awesome Lists containing this project

README 

        
# Zigbee2Mqtt Assistant

[![Codacy Badge](https://api.codacy.com/project/badge/Grade/431c077a2fe84565849ee9a5ee5fcd62)](https://app.codacy.com/gh/yllibed/Zigbee2MqttAssistant?utm_source=github.com&utm_medium=referral&utm_content=yllibed/Zigbee2MqttAssistant&utm_campaign=Badge_Grade_Dashboard)

[![All Contributors](https://img.shields.io/badge/all_contributors-22-orange.svg?style=flat-square)](#contributors)

[![Build Status](https://dev.azure.com/yllibed/Zigbee2MqttAssistant/_apis/build/status/yllibed.Zigbee2MqttAssistant?branchName=master)](https://dev.azure.com/yllibed/Zigbee2MqttAssistant/_build/latest?definitionId=4&branchName=master)

[![Release Status](https://vsrm.dev.azure.com/yllibed/_apis/public/Release/badge/35f7fc7c-f867-48e4-83b5-3381156a439a/1/1)](https://dev.azure.com/yllibed/Zigbee2MqttAssistant/_release?view=mine&definitionId=1)

[![Docker Pulls](https://img.shields.io/docker/pulls/carldebilly/zigbee2mqttassistant)](https://hub.docker.com/r/carldebilly/zigbee2mqttassistant)



This project is a _Web GUI_ for the very good [Zigbee2Mqtt](https://www.zigbee2mqtt.io/) software

([github sources](https://github.com/Koenkk/zigbee2mqtt)).



## 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](https://www.zigbee2mqtt.io/information/binding.html))

  * Visualize device health

  * OTA Upgrades

* Based on _ASP.NET Core_ 3.1 LTS.



## Screenshots

![](images/devices-list.png)

![](images/device-page.png)

![](images/status-page.png)



## 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 ``, ``, `` with your correct values.

```bash

docker run -p 8880:80 -e "Z2MA_SETTINGS__MQTTSERVER=" -e "Z2MA_SETTINGS__MQTTUSERNAME=" -e "Z2MA_SETTINGS__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.

``` yaml

######################################

# 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](Zigbee2MqttAssistant/Models/Settings.cs) 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](https://github.com/Koenkk/zigbee2mqtt/issues/2118#issuecomment-541339790). |



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  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:



  ``` shell

  # 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:



  ``` shell

  # 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](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel?view=aspnetcore-3.1#endpoint-configuration).



## Roadmap



* [X] Build a CI + publish to docker hub

* [X] Shorter environment variables + config file (for docker image)

* [X] Create a `HASS.IO` add-on

  * [X] Support for `HASS.IO` Ingress

  * [X] Automatic update of repo on new version

* [X] Support _Zigbee Bindings_

* [X] Support _Docker Manifest_ (support for ARM + Windows)

* [X] Support mapping of network

* [X] 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](https://allcontributors.org/docs/en/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](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!