Zigbee2MQTT

https://www.zigbee2mqtt.io/
Admin
Zigbee2MQTT is a Zigbee to MQTT gateway that allows you to use Zigbee devices without their original...
Tokens:3,406,918
Snippets:30,385
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start Zigbee2MQTT

Source: https://www.zigbee2mqtt.io/guide/installation/06_freebsd_jail.html

Commands to navigate to the installation directory and launch the application.

```bash
cd /usr/local/opt/zigbee2mqtt
pnpm start
```

--------------------------------

### Start Zigbee2MQTT manually

Source: https://www.zigbee2mqtt.io/guide/installation/01_linux.html

Navigate to the installation directory and start the application using pnpm.

```bash
cd /opt/zigbee2mqtt
pnpm start
```

--------------------------------

### Start Zigbee2MQTT

Source: https://www.zigbee2mqtt.io/guide/installation/05_windows.html

Run this command from the root directory of your installation to start the Zigbee2MQTT service.

```bash
pnpm start
```

--------------------------------

### Zigbee2MQTT Startup Log Output

Source: https://www.zigbee2mqtt.io/guide/installation/06_freebsd_jail.html

Example of the expected output when Zigbee2MQTT starts successfully.

```text
Zigbee2MQTT:info  2019-11-09T13:04:01: Logging to directory: '/opt/zigbee2mqtt/data/log/2019-11-09.14-04-01'
Zigbee2MQTT:info  2019-11-09T13:04:01: Starting Zigbee2MQTT version 1.6.0 (commit #720e393)
Zigbee2MQTT:info  2019-11-09T13:04:01: Starting zigbee-herdsman...
Zigbee2MQTT:info  2019-11-09T13:04:03: zigbee-herdsman started
Zigbee2MQTT:info  2019-11-09T13:04:03: Coordinator firmware version: '{"type":"zStack30x","meta":{"transportrev":2,"product":2,"majorrel":2,"minorrel":7,"maintrel":2,"revision":20190425}}'
Zigbee2MQTT:info  2019-11-09T13:04:03: Currently 0 devices are joined:
Zigbee2MQTT:info  2019-11-09T13:04:03: Connecting to MQTT server at mqtt://localhost
Zigbee2MQTT:info  2019-11-09T13:04:03: Connected to MQTT server
```

--------------------------------

### QuickStartTime

Source: https://www.zigbee2mqtt.io/devices/VZM31-SN.html

Get or set the quick start time duration.

```APIDOC
## MQTT GET zigbee2mqtt/FRIENDLY_NAME/get

### Description
Read the current quickStartTime value.

### Request Example
{"quickStartTime": ""}

## MQTT SET zigbee2mqtt/FRIENDLY_NAME/set

### Description
Set the quickStartTime value (0-60).

### Request Example
{"quickStartTime": 60}
```

--------------------------------

### Windows Flashing Example

Source: https://www.zigbee2mqtt.io/guide/adapters/flashing/alternative_flashing_methods.html

Example of the Windows flashing command for an Arduino UNO on COM7.

```bash
CCLoader_x86_64.exe 7 CC2531ZNP-Prod.bin 0

```

--------------------------------

### Start Docker event listener

Source: https://www.zigbee2mqtt.io/guide/installation/docker/docker_stack.html

Start the newly created service.

```bash
sudo systemctl start docker-event-listener.service
```

--------------------------------

### Example configuration.yaml file

Source: https://www.zigbee2mqtt.io/guide/configuration/zigbee-network.html

A complete example configuration file for Zigbee2MQTT including MQTT, serial, and advanced settings.

```yaml
version: 5 mqtt: base_topic: zigbee2mqtt server: mqtt://<IP_ADDRESS>:<PORT> serial: port: /dev/serial/by-id/<SERIAL_ID> adapter: zstack advanced: channel: 11 network_key: GENERATE pan_id: GENERATE ext_pan_id: GENERATE frontend: enabled: true homeassistant: enabled: false
```

--------------------------------

### Linux Flashing Example

Source: https://www.zigbee2mqtt.io/guide/adapters/flashing/alternative_flashing_methods.html

Example of the Linux flashing command for an Arduino Uno on /dev/ttyACM0.

```bash
./CCLoader /dev/ttyACM0 CC2531ZNP-Prod.bin 0

```

--------------------------------

### Install Node.js and Zigbee2MQTT dependencies

Source: https://www.zigbee2mqtt.io/guide/installation/01_linux.html

Sets up the Node.js repository, installs required system dependencies, and prepares the /opt/zigbee2mqtt directory.

```bash
# Set up Node.js repository, install Node.js and required dependencies.
# NOTE 1: Older i386 hardware can work with https://unofficial-builds.nodejs.org/download/release/v20.9.0/
#         e.g. Version 20.9.0 should work.
# NOTE 2: For Ubuntu see installing through Snap below.
sudo apt-get install -y curl
sudo curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs git make g++ gcc libsystemd-dev
corepack enable

# Verify that the correct Node.js version has been installed
node --version  # Should output V20.x, V22.X

# Create a directory for zigbee2mqtt and set your user as owner of it
sudo mkdir /opt/zigbee2mqtt
sudo chown -R ${USER}: /opt/zigbee2mqtt

# Clone Zigbee2MQTT repository
git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt

# Install dependencies (as user "pi")
cd /opt/zigbee2mqtt
pnpm install --frozen-lockfile
```

--------------------------------

### Install dependencies with pnpm

Source: https://www.zigbee2mqtt.io/guide/installation/05_windows.html

Install the project dependencies using pnpm in the Zigbee2MQTT directory.

```bash
pnpm install --frozen-lockfile
```

--------------------------------

### Install Dependencies and Zigbee2MQTT

Source: https://www.zigbee2mqtt.io/guide/installation/06_freebsd_jail.html

Commands to install Node.js, clone the repository, and build the application within the jail.

```bash
# Install Node.js and required dependencies:
# - It is recommended to install Node 22 from the official Node repository. Check https://github.com/nodesource/distributions/blob/master/README.md on how to do this.
# - Older i386 hardware can work with [unofficial-builds.nodejs.org](https://unofficial-builds.nodejs.org/download/release/v20.9.0/ e.g. Version 20.9.0 should work.
# - Selecting `npm` also installs `node`.
pkg install git gmake gcc
corepack enable

# Verify that the correct Node.js version has been installed
node --version  # Should output V20.x, V22.X

# Create installation folder (/usr/local prefix is used for software not part of the base system)
mkdir -p /usr/local/opt/zigbee2mqtt
cd /usr/local/opt/zigbee2mqtt

# Clone Zigbee2MQTT repository
git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git .

# Install dependencies
pnpm install --frozen-lockfile

# Build Zigbee2MQTT
pnpm run build
```

--------------------------------

### Create docker-setup-zigbee-serial.sh

Source: https://www.zigbee2mqtt.io/guide/installation/docker/docker_stack.html

Create and set permissions for the setup script.

```bash
sudo nano /usr/local/bin/docker-setup-zigbee-serial.sh
```

```bash
#!/bin/bash
USBDEV=`readlink -f /dev/zigbee-serial`
read minor major < <(stat -c '%T %t' $USBDEV)
if [[ -z $minor || -z $major ]]; then
	echo 'Device not found'
	exit
fi
dminor=$((0x${minor}))
dmajor=$((0x${major}))
CID=`docker ps -a --no-trunc | grep koenkk/zigbee2mqtt | head -1 |  awk '{print $1}'`
if [[ -z $CID ]]; then
	echo 'CID not found'
	exit
fi
echo 'Setting permissions'
echo "c $dmajor:$dminor rwm" > /sys/fs/cgroup/devices/docker/$CID/devices.allow
```

```bash
sudo chmod 744 /usr/local/bin/docker-setup-zigbee-serial.sh
```

--------------------------------

### Start the container

Source: https://www.zigbee2mqtt.io/guide/installation/02_docker.html

Command to start the Zigbee2MQTT container in detached mode.

```bash
docker compose up -d zigbee2mqtt
```

--------------------------------

### Install Node.js via Snap on Ubuntu

Source: https://www.zigbee2mqtt.io/guide/installation/01_linux.html

Alternative method for installing Node.js on Ubuntu using the Snap store.

```bash
# Install latest nodejs from snap store
# The --classic argument is required here as Node.js needs full access
# to your system in order to be useful.
# You can also use the --channel=XX argument to install a legacy version
# where XX is the version you want to install (we need 14+).
sudo snap install node --classic
corepack enable

# Verify node has been installed
# If you encounter an error at this stage and used the snap store instructions,
# adjust the BIN path as follows:
## PATH=$PATH:/snap/node/current/bin
# then re-verify Node.js as above
node --version
```

--------------------------------

### Verify Node.js installation

Source: https://www.zigbee2mqtt.io/guide/installation/05_windows.html

Check that Node.js is correctly installed by querying its version.

```bash
node --version
```

--------------------------------

### QuickStartTime Configuration

Source: https://www.zigbee2mqtt.io/devices/VZM31-SN.html

Read or write the duration of full power output during lamp transition.

```json
{"quickStartTime": ""}
```

```json
{"quickStartTime": NEW_VALUE}
```

--------------------------------

### Installing the TRV

Source: https://www.zigbee2mqtt.io/devices/ZK03840.html

Step-by-step guide for installing and pairing the Viessmann ZK03840 radiator thermostat valve.

```APIDOC
## Installing the TRV

### Description
Follow these steps to install and pair the Viessmann ZK03840 radiator thermostat valve with Zigbee2MQTT.

### Steps
1. Install the correct adaptor on the valve.
2. Open the cover by pushing the clip on the bottom and sliding the front side.
3. Insert batteries (ensure `--` is displayed).
4. Press the button on the top (`--` + `((•))` should appear on the display).
5. Wait for the device to pair (approximately 2 minutes for a success message in Zigbee2MQTT).
6. Install the TRV onto the adaptor (push firmly until a click is heard, rotate until the display faces up).
7. Press the button on the top for 3 seconds (the motor will turn, and `21°` + `((•))` should be displayed).
8. Close the cover.
```

--------------------------------

### Minimal configuration.yaml example

Source: https://www.zigbee2mqtt.io/guide/configuration

A basic configuration template for Zigbee2MQTT including MQTT server, serial port, and network settings.

```yaml
version: 5 mqtt: base_topic: zigbee2mqtt server: mqtt://<IP_ADDRESS>:<PORT> serial: port: /dev/serial/by-id/<SERIAL_ID> adapter: zstack advanced: channel: 11 network_key: GENERATE pan_id: GENERATE ext_pan_id: GENERATE frontend: enabled: true homeassistant: enabled: false
```

--------------------------------

### Min Time - Zigbee2MQTT Interaction

Source: https://www.zigbee2mqtt.io/devices/Presence_Sensor_v2.html

Information on how to get and set the minimum time (day start) via MQTT.

```APIDOC
## Min time (text)

### Description
Day start time. Value can be found in the published state on the `min_time` property.

### Method
GET, SET

### Endpoint
- GET: `zigbee2mqtt/FRIENDLY_NAME/get`
- SET: `zigbee2mqtt/FRIENDLY_NAME/set`

### Parameters
#### Query Parameters (GET)
- **min_time** (string) - Required - The current day start time.

#### Request Body (SET)
- **min_time** (string) - Required - The desired day start time (e.g., `HH:MM:SS`).

### Request Example (SET)
```json
{
  "min_time": "07:00:00"
}
```

### Response
#### Success Response (200)
- **min_time** (string) - The current day start time.

### Response Example
```json
{
  "min_time": "07:00:00"
}
```
```

--------------------------------

### Single Button Operation Patterns

Source: https://www.zigbee2mqtt.io/devices/SBHT-103C.html

A reference guide for the various button press combinations used to control the SBHT-103C, including setup modes, pairing, and display settings.

```text
Press 1 time: Enter setup mode for 3 minutes.

    Press 1 time: Exit setup mode.

    Press 2 times rapidly: Force clock synchronization via a Shelly device set as a Bluetooth gateway.

    Press 4 times rapidly: Enter Bluetooth pairing mode.

    Press 5 times rapidly: Enter Zigbee pairing mode.

    Press and hold for 5 seconds: Toggle Bluetooth on/off.

    Press and hold for 10 seconds: Toggle Zigbee on/off.

    Press and hold for 30 seconds: Resets the device to factory settings.

Press 2 times rapidly: Toggle the clock display segment between showing the clock or the date.

Press 3 times rapidly: Switch temperature unit between Celsius and Fahrenheit. When Celsius is selected, the date format is DD.MM; when Fahrenheit is selected, the date format is MM.DD.

Press 4 times rapidly: Invert the display colors.

Press 5 times rapidly: Toggle the clock format between 24-hour and 12-hour.
```

--------------------------------

### Install Python and Pip (Debian)

Source: https://www.zigbee2mqtt.io/guide/adapters/flashing/flashing_via_cc2538-bsl.html

Installs Python 3 and pip, the package installer for Python, on Debian-based systems. This is a prerequisite for installing other Python packages.

```bash
sudo apt update && sudo apt install python3 python3-pip

```

--------------------------------

### Define devices in configuration.yml

Source: https://www.zigbee2mqtt.io/guide/configuration/devices-groups.html

Example configuration showing device definitions with various options like friendly_name, retain, and Home Assistant discovery settings.

```yaml
devices:
    # First device
    '0x00158d0001d82999':
        friendly_name: 'my_occupancy_sensor'
        retain: true
        disabled: false
        qos: 1
        debounce: 0.5
        debounce_ignore:
            - action
            - brightness
        # Set `homeassistant: null` to skip discovery for this device
        homeassistant:
            # Applied to all discovered entities.
            expire_after: 30
            # Only applied to discovered temperature sensor.
            temperature:
                icon: mdi:oil-temperature
                # Omit values by setting them to null, e.g. don't send device_class
                device_class: null
        # Device type specific examples
        occupancy_timeout: 120
        no_occupancy_since: [10, 600]
        # Ignore update check requests from the device (Zigbee2MQTT will always reply "no image available")
        disable_automatic_update_check: true
    # Another device
    '0x000d6ffffee405eb':
        friendly_name: 'Kitchen bulb'
```

--------------------------------

### Installation Method

Source: https://www.zigbee2mqtt.io/devices/HS2FD-EF1-3.0.html

Configures the installation method of the sensor.

```APIDOC
## MQTT Topic: zigbee2mqtt/FRIENDLY_NAME/get

### Description
Read the current installation method.

### Request Example
{"installation_method": ""}

## MQTT Topic: zigbee2mqtt/FRIENDLY_NAME/set

### Description
Write the installation method (WallMounted, Ceiling, RotateCeiling45).

### Request Example
{"installation_method": "Ceiling"}
```

--------------------------------

### Start One Key Pairing

Source: https://www.zigbee2mqtt.io/devices/AC221.html

To start the one key pairing process, publish a message with the payload 'start' to the device's set topic.

```mqtt
zigbee2mqtt/FRIENDLY_NAME/set
{"one_key_pairing": "start"}
```

--------------------------------

### Start auto weight reporting command

Source: https://www.zigbee2mqtt.io/devices/3RKS030Z.html

To start auto weight reporting, publish a message to the set topic with the payload containing the START value.

```json
{"start_report_button": "START"}
```

--------------------------------

### POST zigbee2mqtt/FRIENDLY_NAME/set (time_periods)

Source: https://www.zigbee2mqtt.io/devices/HS-SW300ZB-VNM.html

Sets the start hours for morning, evening, and night time periods. Morning must start before evening, and evening must start before night.

```APIDOC
## POST zigbee2mqtt/FRIENDLY_NAME/set

### Description
Sets the start hours for morning, evening, and night time periods.

### Request Body
- **time_periods** (object) - Required
  - **morning_start_hour** (numeric) - Required - Morning period start hour (0-23)
  - **evening_start_hour** (numeric) - Required - Evening period start hour (0-23)
  - **night_start_hour** (numeric) - Required - Night period start hour (0-23)

### Request Example
{
  "time_periods": {
    "morning_start_hour": 6,
    "evening_start_hour": 18,
    "night_start_hour": 22
  }
}
```

--------------------------------

### Enable service on boot

Source: https://www.zigbee2mqtt.io/guide/installation/docker/docker_stack.html

Configure the service to start automatically on system boot.

```bash
sudo systemctl enable docker-event-listener.service
```

--------------------------------

### Install Python Packages for cc2538-bsl

Source: https://www.zigbee2mqtt.io/guide/adapters/flashing/flashing_via_cc2538-bsl.html

Installs necessary Python packages 'pyserial' and 'intelhex' required for the cc2538-bsl script. Ensure Python 3 and pip are installed first.

```bash
sudo pip3 install pyserial intelhex

```

--------------------------------

### Install Zigbee2MQTT via Helm

Source: https://www.zigbee2mqtt.io/guide/installation/08_kubernetes.html

Deploy the Zigbee2MQTT chart using a custom values file.

```bash
helm install -f myvalues.yaml zigbee2mqtt zigbee2mqtt/zigbee2mqtt
```

--------------------------------

### Enable Zigbee2MQTT on boot

Source: https://www.zigbee2mqtt.io/guide/installation/01_linux.html

Configure the systemd service to start automatically when the system boots.

```bash
sudo systemctl enable zigbee2mqtt.service
```

--------------------------------

### Set time periods

Source: https://www.zigbee2mqtt.io/devices/HS-SW300ZB-VNM.html

Configure morning, evening, and night start hours by publishing to the set topic. Morning must start before evening, and evening must start before night.

```json
{"time_periods": {"morning_start_hour": VALUE, "evening_start_hour": VALUE, "night_start_hour": VALUE}}
```

--------------------------------

### Configure cgroupv1 in /boot/cmdline.txt

Source: https://www.zigbee2mqtt.io/guide/installation/docker/docker_stack.html

Example of adding the systemd.unified_cgroup_hierarchy=false flag to the kernel command line in /boot/cmdline.txt to enable cgroupv1 support.

```text
[...] rootfstype=ext4 fsck.repair=yes rootwait cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=false
```

--------------------------------

### Install Wireshark on Linux

Source: https://www.zigbee2mqtt.io/advanced/zigbee/04_sniff_zigbee_traffic.html

Command to install Wireshark on APT-based Linux distributions.

```bash
sudo apt install -y wireshark
```

--------------------------------

### Install ser2net

Source: https://www.zigbee2mqtt.io/advanced/remote-adapter/connect_to_a_remote_adapter.html

Install the ser2net package on the system where the adapter is physically connected.

```bash
sudo apt-get install ser2net
```

--------------------------------

### Get Illuminance

Source: https://www.zigbee2mqtt.io/devices/AY205Z.html

Publish to the get topic to retrieve the current measured illuminance.

```json
{"illuminance": ""}
```

--------------------------------

### Launch openHABian Configuration Utility

Source: https://www.zigbee2mqtt.io/guide/installation/04_openhabian.html

Command to initiate the openHABian configuration interface on a Raspberry Pi.

```bash
sudo openhabian-config
```

--------------------------------

### Initialize scene for transitions

Source: https://www.zigbee2mqtt.io/guide/usage/scenes.html

Create an empty scene with a transition time using scene_add, then populate it with scene_store.

```json
{
    "scene_add": {
        "ID": 0,
        "name": "Scene Name",
        "transition": 5
    }
}
```

```json
{
    "scene_store": {
        "ID": 0,
        "name": "Scene Name"
    }
}
```

--------------------------------

### Schedule start time

Source: https://www.zigbee2mqtt.io/devices/PS-S04D.html

Read or write the LED disable schedule start time.

```APIDOC
## GET zigbee2mqtt/FRIENDLY_NAME/get

### Description
Reads the current schedule start time.

### Request Example
{"schedule_start_time": ""}

## POST zigbee2mqtt/FRIENDLY_NAME/set

### Description
Sets the schedule start time (HH:MM format).

### Request Example
{"schedule_start_time": "22:00"}
```

--------------------------------

### ShinaSystem TQM-300ZB Options

Source: https://www.zigbee2mqtt.io/devices/TQM-300ZB.html

Configuration options specific to the ShinaSystem TQM-300ZB device.

```APIDOC
## Device Specific Options

### `temperature_calibration`
- **Description**: Calibrates the temperature value (absolute offset). Takes effect on the next report of the device.
- **Type**: `number`

### `temperature_precision`
- **Description**: Number of digits after the decimal point for temperature. Takes effect on the next report of the device. This option can only decrease the precision, not increase it.
- **Type**: `number`
- **Minimum Value**: 0
- **Maximum Value**: 3

### `humidity_calibration`
- **Description**: Calibrates the humidity value (absolute offset). Takes effect on the next report of the device.
- **Type**: `number`

### `humidity_precision`
- **Description**: Number of digits after the decimal point for humidity. Takes effect on the next report of the device. This option can only decrease the precision, not increase it.
- **Type**: `number`
- **Minimum Value**: 0
- **Maximum Value**: 3
```

--------------------------------

### Get Switch State

Source: https://www.zigbee2mqtt.io/devices/TS0001_fingerbot_1.html

Publish to the get topic to retrieve the current switch state.

```APIDOC
## MQTT GET zigbee2mqtt/FRIENDLY_NAME/get

### Description
Retrieves the current state of the switch.

### Request Body
- **state** (string) - Required - Empty string ""
```

--------------------------------

### GET /get

Source: https://www.zigbee2mqtt.io/devices/Mercury_3ph_Counter.html

Retrieve specific electrical measurements from the device by publishing to the get topic.

```APIDOC
## MQTT GET Request

### Description
Read the current value of a specific property by publishing a message to the device's get topic.

### Topic
`zigbee2mqtt/FRIENDLY_NAME/get`

### Request Body
- **property** (string) - Required - The property name to retrieve (e.g., "power", "voltage", "current", "energy_t1", etc.). The value should be an empty string.

### Request Example
{
  "power": ""
}

### Response
- **property** (numeric) - The requested measurement value published to the device state topic.
```

--------------------------------

### Run Zigbee2MQTT container

Source: https://www.zigbee2mqtt.io/guide/installation/02_docker.html

Standard command to start the Zigbee2MQTT container. Ensure the --device path matches your specific adapter location.

```bash
$ docker run \
   --name zigbee2mqtt \
   --restart=unless-stopped \
   --device=/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00:/dev/ttyACM0 \
   -p 8080:8080 \
   -v $(pwd)/data:/app/data \
   -v /run/udev:/run/udev:ro \
   -e TZ=Europe/Amsterdam \
   ghcr.io/koenkk/zigbee2mqtt
```

--------------------------------

### Get detach_relay_mode

Source: https://www.zigbee2mqtt.io/devices/MINI-ZB1GSP.html

Publish to the get topic to retrieve the current detach relay mode.

```json
{"detach_relay_mode": ""}
```

--------------------------------

### Configure Options

Source: https://www.zigbee2mqtt.io/devices/SQM300Z1.html

This section details the configuration options available for the ShinaSystem SQM300Z1 switch.

```APIDOC
## Options

### Description
Device type specific configuration options.

### `state_action`
- **Type**: boolean
- **Default**: `false`
- **Description**: When `true`, state actions will also be published as 'action'. This allows for observing state changes as events.
```
Tokens:
Raw