Public/Documentation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Documentation/Zigbee2MQTT/Installation.md

9.8 KiB
Raw Permalink Blame History

Prerequisites

Before starting, ensure you have a compatible Zigbee coordinator and a computer running a clean Debian Bookworm (Debian 12).

1. Install Dependencies

First, update your package list and install the necessary dependencies for Zigbee2Mqtt, including git and build-essential. These are required to clone the repository and compile some of the components.

sudo apt update
sudo apt install git build-essential

2. Install Node.js

Zigbee2Mqtt is built on Node.js. Although Debian 12 comes with a version of Node.js, it is often not the latest. For better compatibility, it's recommended to install the official Node.js binaries. You can find the instructions for this on the Node.js website.

# This is an example, check the Node.js website for the latest instructions
sudo apt install curl
curl -sL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install nodejs

3. Create a Swap File (Optional but Recommended)

If your system has limited RAM (e.g., 512 MB or less), creating a swap file is highly recommended. A swap file uses a portion of your hard drive as a temporary memory overflow, which can prevent the "out of memory" errors that can occur during the installation and operation of Zigbee2MQTT.

  1. Create a swap file. The following command creates a 2 GB swap file in your root directory. You can change the size by adjusting the -l flag. 
    sudo fallocate -l 2G /swapfile
  2. Set the correct permissions. Only the root user should be able to read and write to the swap file. 
    sudo chmod 600 /swapfile
  3. Set up the swap space. This command formats the file as a swap file. 
    sudo mkswap /swapfile
  4. Enable the swap file. This command activates the swap file for the current session. 
    sudo swapon /swapfile
  5. Make the swap file permanent. To ensure the swap file is enabled automatically after a reboot, add the following line to the end of your /etc/fstab file. 
    /swapfile none swap sw 0 0

4. Install zigbee2mqtt

Now you can install Zigbee2Mqtt. The best way to do this is to clone the official Git repository into a directory you've created for the application.

sudo mkdir /opt/zigbee2mqtt
sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt

Navigate to the newly created directory and install the Node.js dependencies.

cd /opt/zigbee2mqtt
npm install

If you encounter a FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory, run the command with increased heap space.

node --max-old-space-size=2048 /usr/bin/npm install

5. Configure zigbee2mqtt

The next step is to configure Zigbee2Mqtt. The primary configuration file is configuration.yaml located in the /opt/zigbee2mqtt/data directory. Use a text editor like nano to edit the file.

sudo nano /opt/zigbee2mqtt/data/configuration.yaml

At a minimum, you'll need to specify the serial port of your Zigbee coordinator. The correct path for your device will be something like /dev/ttyACM0 or /dev/ttyUSB0. You can use the dmesg command after plugging in your device to see what port it's assigned to.

# In /opt/zigbee2mqtt/data/configuration.yaml
homeassistant: false
permit_join: true
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost
serial:
  port: /dev/ttyACM0

💡 Note: If you want to integrate with Home Assistant or another MQTT broker, you will need to change the homeassistant and mqtt settings accordingly.

6. Create a Systemd Service

To ensure Zigbee2Mqtt starts automatically on boot and runs as a background service, it's best to create a systemd service file. This file will control the service's behavior.

Create a new file called zigbee2mqtt.service in the /etc/systemd/system/ directory.

sudo nano /etc/systemd/system/zigbee2mqtt.service

Add the following content to the file:

[Unit]
Description=zigbee2mqtt
After=network.target

[Service]
ExecStart=/usr/bin/npm start
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=inherit
StandardError=inherit
Restart=always
User=root

[Install]
WantedBy=multi-user.target

Reload the systemd daemon to recognize the new service and then enable and start it.

sudo systemctl daemon-reload
sudo systemctl enable zigbee2mqtt.service
sudo systemctl start zigbee2mqtt.service

7. Check the Status

You can check the status of the service at any time to ensure it is running correctly.

sudo systemctl status zigbee2mqtt.service

This command will show you the service's status, including whether it's active and any recent log entries. If you have any issues, the logs will be a good place to start troubleshooting.

8. How to Update Node.js and Zigbee2MQTT

The best way to update both Node.js and Zigbee2MQTT is to stop the service, perform the updates, and then restart the service. It's a good practice to back up your Zigbee2MQTT configuration files before updating.

⚙️ Update Node.js

Since you installed Node.js from the NodeSource repository, you can update it using the apt package manager. First, you'll need to run the NodeSource setup script for the latest LTS version, which will update the repository's configuration. Then you can update the package itself.

  1. Stop the Zigbee2MQTT service: 
    sudo systemctl stop zigbee2mqtt.service
  2. Run the NodeSource script to update the repository: 
    curl -sL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
    This command will reconfigure your system to point to the latest LTS version of Node.js.
  3. Update and upgrade Node.js: 
    sudo apt update
sudo apt upgrade nodejs -y
    This will install the newest version of Node.js available from the NodeSource repository.

🔄 Update Zigbee2MQTT

Updating Zigbee2MQTT is straightforward. You just need to pull the latest changes from the Git repository and then install any new dependencies.

  1. Navigate to the Zigbee2MQTT directory: 
    cd /opt/zigbee2mqtt
  2. Pull the latest code from the Git repository: 
    sudo git pull
    This command downloads and applies the most recent changes from the official Zigbee2MQTT repository.
  3. Install new Node.js dependencies: 
    npm install
# If you get an 'out of memory' error, use this command instead:
node --max-old-space-size=2048 /usr/bin/npm install
    This ensures that any new or updated dependencies required by the latest version of Zigbee2MQTT are installed correctly.
  4. Restart the Zigbee2MQTT service: 
    sudo systemctl start zigbee2mqtt.service
  5. Check the service status to confirm it's running: 
    sudo systemctl status zigbee2mqtt.service
    This will show you the status and recent logs, confirming that the update was successful and the service is active.

9. Migrate a Running Zigbee2MQTT Instance to New Hardware

The migration process is simple and primarily involves backing up and restoring your data files. The data directory contains all the essential information about your Zigbee network, including device pairings and configurations, which are crucial for a seamless transition.

On the Old System:

  1. Stop the Zigbee2MQTT service. This ensures that the configuration and database files are not being written to while you're backing them up, preventing data corruption.

    sudo systemctl stop zigbee2mqtt.service

  2. Navigate to the Zigbee2MQTT data directory. This is where all your important network files are stored. By default, this is /opt/zigbee2mqtt/data.

    cd /opt/zigbee2mqtt/data

  3. Create a backup of your data directory. You can compress the entire directory into a single file to make it easier to transfer.

    tar -czvf zigbee2mqtt_backup.tar.gz .

    This command creates a compressed archive named zigbee2mqtt_backup.tar.gz that contains all the files in the current directory.

  4. Copy the backup file to your new hardware. You can use a tool like scp (secure copy) or a USB drive to transfer the file. Replace <user> and <new_server_ip> with your new system's login details.

    scp zigbee2mqtt_backup.tar.gz <user>@<new_server_ip>:/home/<user>/

On the New System:

  1. Follow steps 1 through 3 from the initial installation guide on the new hardware to install the dependencies, Node.js, and a fresh Zigbee2MQTT instance. Do not start the service yet.
  2. Navigate to the new Zigbee2MQTT data directory: 
    cd /opt/zigbee2mqtt/data
  3. Extract the backup files. Use the tar command to decompress the archive you copied over. 
    sudo tar -xzvf /path/to/zigbee2mqtt_backup.tar.gz
    This will overwrite the default configuration.yaml and other files with your old ones.
  4. Edit the configuration file. You'll need to update the serial.port in your configuration.yaml to match the new hardware's Zigbee coordinator port. 
    sudo nano /opt/zigbee2mqtt/data/configuration.yaml
    Ensure the port value corresponds to the new location of your Zigbee dongle (e.g., /dev/ttyACM0).
  5. Start the Zigbee2MQTT service. 
    sudo systemctl start zigbee2mqtt.service
    Your Zigbee2MQTT instance should now start up on the new hardware with all your devices, groups, and settings intact. The network should automatically re-establish itself. You can verify this by checking the service status and the Zigbee2MQTT frontend.