This project is a Web GUI for the very good Zigbee2Mqtt software (github sources).
linux-x64
linux-arm32
(armv7
+ processor required - Won't work on Raspberry Pi Zero or Zero-W!)linux-arm64
(armv8
+ processor required)win-64
win-arm32
latest
(or dev
for development version)
HASS.IO
Add-onhttps://github.com/yllibed/hassio
Zigbee2Mq2ttAssistant
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.
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
appsettings.json
for your MQTT connectionNote: 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.
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:
zigbee2mqttassistant-dev
packagecarldebilly/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!
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.
HASS.IO
add-on
HASS.IO
IngressYou need a running installation of Zigbee2Mqtt
v1.5.0+
Simple MQTT connection with username/password (TLS supported)
Zigbee2Mqtt required settings:
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.Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!