Ansible Role zigbee2mqtt

Description

This role helps you install and set up zigbee2mqtt on a Raspberry Pi running the standard Raspbian lite or full versions. It should also be compatible with other Debian-based systems.

It includes a script /usr/local/bin/zigbee2mqtt-backup for backing up and restoring your configuration and device database.

This role is based on igami.zigbee2mqtt.

Requirements

You need a Raspberry Pi with SSH enabled and a CC2531 USB sniffer.

If you're installing on a new 'headless' Raspberry Pi server, create an empty file named 'ssh' in the boot directory of the SD card to enable remote SSH access.

Role Variables

Variable	Type	Default	Comments
zigbee_user	string	zigbee	User for running zigbee2mqtt.
zigbee_user_groups	string	tty,dialout	Necessary groups for the zigbee user to access the serial port.
zigbee_user_append	boolean	false	If true, add the user to the groups in zigbee_user_groups. If false, user will be added only to specified groups, removing them from others.
zigbee_dir	string	/opt/zigbee2mqtt	Directory where zigbee2mqtt will be installed.
zigbee_repository	string	https://github.com/Koenkk/zigbee2mqtt.git	URL for the zigbee2mqtt git repository used during installation.
zigbee_version	string	HEAD	Version to install (should be a commit hash, branch, or tag name).
zigbee_permit_join	boolean	false	Allow new devices to connect.
zigbee_mqtt	object		MQTT settings (see zigbee_mqtt).
zigbee_advanced	object		Advanced settings for zigbee2mqtt configuration (see zigbee_advanced).
zigbee_serial	object		Serial port settings (see zigbee_serial).
zigbee_frontend	object/boolean		If false, disables the frontend. An object can be used to configure frontend settings (see zigbee_frontend).
zigbee_ota	object		Firmware update settings for devices (see zigbee_ota).
zigbee_device_options	object		Device options settings (see the configuration guide for devices).
zigbee_blocklist	object		Blocklist for devices (see blocklist guide).
zigbee_passlist	object		Passlist for devices (see passlist guide).
zigbee_external_converters	list of objects		Settings for external converters (see external converters).
zigbee_map_options	object		Settings for the network map (see the network map guide).
zigbee_availability	object		Device availability settings (see availability guide). Not defined means this feature is disabled.
zigbee_homeassistant	object		Settings for Home Assistant integration (see Home Assistant guide). Not defined means integration is disabled.
zigbee_generate_new_network_key	boolean	false	If true, forces the generation of a new network key (only if no key is specified in zigbee_advanced.network_key).

zigbee_mqtt

For detailed settings, check the MQTT configuration guide.

Variable	Type	Default	Comments
base_topic	string	zigbee2mqtt	Basic topic for zigbee2mqtt MQTT messages.
server	string	mqtt://localhost	URL to connect to the MQTT server.
user	string		User name for connecting to the MQTT server.
password	string		Password for connecting to the MQTT server.

zigbee_advanced

For a complete list of settings, visit:

• Adapter settings guide
• Zigbee network configuration guide
• Logging configuration guide

Variable	Type	Default	Comments
pan_id	hex	0x1a62	ZigBee pan ID.
ext_pan_id	array	[0xDD, 0xDD, 0xDD, 0xDD, 0xDD, 0xDD, 0xDD, 0xDD]	Extended pan ID for Zigbee.
channel	integer	11	ZigBee channel (Use channels 11, 15, 20, or 25 to avoid issues). Note: Changing requires re-pairing of all devices.
network_key	string	'!network_key network_key'	Network encryption key for better security. Changing requires re-pairing of all devices.

zigbee_serial

For serial port setting details, see the adapter settings guide.

Variable	Type	Default	Comments
port	string	/dev/ttyACM0	Location of the Zigbee USB adapter.
baudrate	integer	115200	Baud rate for the serial port.
rtscts	boolean	false	RTS/CTS Hardware Flow Control for the serial port.

zigbee_frontend

Details on frontend settings can be found in the frontend configuration guide.

Variable	Type	Default	Comments
port	integer	8080	Port that the frontend listens on.

zigbee_ota

Full details are in the OTA firmware update guide.

Variable	Type	Default	Comments
ikea_ota_use_test_url	boolean	false	Use IKEA TRADFRI OTA test server (check OTA documentation).
update_check_interval	integer	1440	Minimum time between OTA update checks.
disable_automatic_update_check	boolean	false	Disable automatic update checks.

zigbee_external_converters

Configuration for external converters.

Variable	Type	Default	Comments
name	string		Name of the external converter.
script	string		Script for the external converter.
state	string	present	present creates or updates the converter. absent removes it.

Dependencies

• git
• npm version 5.8 or higher
• nodejs version 10 or higher

Example Playbook

To install zigbee2mqtt with the default serial port:

- name: Install zigbee2mqtt on Raspberry Pi
  hosts: ip_address_of_rpi
  become: true

  roles:
  - finalgene.zigbee2mqtt

To install zigbee2mqtt with a custom serial port:

- name: Install zigbee2mqtt on Raspberry Pi
  hosts: ip_address_of_rpi
  become: true

  roles:
  - role: finalgene.zigbee2mqtt
    vars: 
      zigbee_serial:
        port: /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00

To install zigbee2mqtt with the default serial port and MQTT authentication:

- name: Install zigbee2mqtt on Raspberry Pi
  hosts: ip_address_of_rpi
  become: true

  roles:
  - role: finalgene.zigbee2mqtt
    vars:
      zigbee_mqtt:
        user: mqtt_user
        password: mqtt_password

License

BSD

Author Information

• igami
• Frank Giesecke