knowledge/technology/applications/web/zigbee2mqtt.md

obj	repo	website
application	https://github.com/Koenkk/zigbee2mqtt	https://www.zigbee2mqtt.io

zigbee2mqtt

Zigbee to MQTT bridge, get rid of your proprietary Zigbee bridges.
See this for a list of supported devices.

Setup

In order to run zigbee2mqtt you need a MQTT server and a zigbee adapter for talking to the zigbee devices.

Configuration

zigbee2mqtt is configured with configuration.yml

Adapter configuration:

# Required: serial settings
serial:
  # Required: location of the adapter (e.g. CC2531).
  # USB adapters - use format "port: /dev/ttyACM0"
  # To autodetect the USB port, set 'port: null'.
  # Ethernet adapters - use format "port: tcp://192.168.1.12:6638"
  port: /dev/ttyACM0 
  # Optional: disable LED of the adapter if supported (default: false)
  disable_led: false
  # Optional: adapter type, not needed unless you are experiencing problems (default: shown below, options: zstack, deconz, ezsp)
  adapter: null
  # Optional: Baud rate speed for serial port, this can be anything firmware support but default is 115200 for Z-Stack and EZSP, 38400 for Deconz, however note that some EZSP firmware need 57600.
  baudrate: 115200
  # Optional: RTS / CTS Hardware Flow Control for serial port (default: false)
  rtscts: false

MQTT:

# Required: MQTT settings
mqtt:
  # Required: MQTT server URL (use mqtts:// for SSL/TLS connection)
  server: 'mqtt://localhost:1883'
  # Optional: MQTT base topic for Zigbee2MQTT MQTT messages (default: zigbee2mqtt)
  base_topic: zigbee2mqtt
  # Optional: absolute path to SSL/TLS certificate of CA used to sign server and client certificates (default: nothing)
  ca: '/etc/ssl/mqtt-ca.crt'
  # Optional: absolute paths to SSL/TLS key and certificate for client-authentication (default: nothing)
  key: '/etc/ssl/mqtt-client.key'
  cert: '/etc/ssl/mqtt-client.crt'
  # Optional: MQTT server authentication user (default: nothing)
  user: my_user
  # Optional: MQTT server authentication password (default: nothing)
  password: my_password
  # Optional: MQTT client ID (default: nothing)
  client_id: 'MY_CLIENT_ID'
  # Optional: disable self-signed SSL certificates (default: true)
  reject_unauthorized: true
  # Optional: Include device information to mqtt messages (default: false)
  include_device_information: true
  # Optional: MQTT keepalive in seconds (default: 60)
  keepalive: 60
  # Optional: MQTT protocol version (default: 4), set this to 5 if you
  # use the 'retention' device specific configuration
  version: 4
  # Optional: Disable retain for all send messages. ONLY enable if you MQTT broker doesn't
  # support retained message (e.g. AWS IoT core, Azure IoT Hub, Google Cloud IoT core, IBM Watson IoT Platform).
  # Enabling will break the Home Assistant integration. (default: false)
  force_disable_retain: false

Frontend:

frontend:
  # Optional, default 8080
  port: 8080
  # Optional, empty by default to listen on both IPv4 and IPv6. Opens a unix socket when given a path instead of an address (e.g. '/run/zigbee2mqtt/zigbee2mqtt.sock')
  host: 0.0.0.0
  # Optional, enables authentication, disabled by default
  auth_token: your-secret-token
  # Optional, url on which the frontend can be reached, currently only used for the Home Assistant device configuration page
  url: 'https://zigbee2mqtt.myhouse.org'
  # Optional, certificate file path for exposing HTTPS. The sibling property 'ssl_key' must be set for HTTPS to be activated
  ssl_cert: /config/etc/letsencrypt/live/mydomain.com/fullchain.pem
  # Optional, private key file path for exposing HTTPS. The sibling property 'ssl_cert' must be set for HTTPS to be activated
  ssl_key: /config/etc/letsencrypt/live/mydomain.com/privkey.pem

To enable integration with Home Assistant, add this to config:

homeassistant: true

Docker Compose

version: '3'
services:
  zigbee2mqtt:
    restart: unless-stopped
    image: koenkk/zigbee2mqtt
    volumes:
      - ./zigbee2mqtt-data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - 8080:8080
    environment:
      - TZ=Europe/Berlin
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0