Skip to content

Latest commit

 

History

History
99 lines (83 loc) · 5.33 KB

README.md

File metadata and controls

99 lines (83 loc) · 5.33 KB
Raw

Zibee2Mqtt 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.
  • 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 image (Linux & Windows, both for x64 + ARMv7)
  • 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 2.2.

Build Status Release Status Docker Pulls

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

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.

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
MqttSecure false If should use TLS to connect to MQTT server
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 (%)

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 Zigbee groups WAITING FOR NEXT VERSION OF ZIGBEE2MQTT FOR THIS ONE
  • Better display of "routes to coordinator"
  • Improve UI

Requirements

  • You need a running installation of Zigbee2Mqtt v1.5.0+
    • Developped & tested with Zigbee2Mqtt v1.5.1
  • 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: true in Zigbee2Mqtt configuration

    • last_seen should be set to ISO_8601. Not required, but you'll have a better experience when activated.

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.