268 lines
9.8 KiB
Markdown
268 lines
9.8 KiB
Markdown
|
|
## 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.
|
|
|
|
```bash
|
|
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](https://www.google.com/search?q=https://nodejs.org/en/download/package-manager%23debian-and-ubuntu-based-linux-distributions).
|
|
|
|
```bash
|
|
# 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.
|
|
```bash
|
|
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.
|
|
```bash
|
|
sudo chmod 600 /swapfile
|
|
```
|
|
3. **Set up the swap space.** This command formats the file as a swap file.
|
|
```bash
|
|
sudo mkswap /swapfile
|
|
```
|
|
4. **Enable the swap file.** This command activates the swap file for the current session.
|
|
```bash
|
|
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.
|
|
```bash
|
|
/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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```yaml
|
|
# 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.
|
|
|
|
```bash
|
|
sudo nano /etc/systemd/system/zigbee2mqtt.service
|
|
```
|
|
|
|
Add the following content to the file:
|
|
|
|
```ini
|
|
[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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
sudo systemctl stop zigbee2mqtt.service
|
|
```
|
|
2. **Run the NodeSource script to update the repository:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
cd /opt/zigbee2mqtt
|
|
```
|
|
2. **Pull the latest code from the Git repository:**
|
|
```bash
|
|
sudo git pull
|
|
```
|
|
This command downloads and applies the most recent changes from the official Zigbee2MQTT repository.
|
|
3. **Install new Node.js dependencies:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
sudo systemctl start zigbee2mqtt.service
|
|
```
|
|
5. **Check the service status to confirm it's running:**
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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`.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
cd /opt/zigbee2mqtt/data
|
|
```
|
|
3. **Extract the backup files.** Use the `tar` command to decompress the archive you copied over.
|
|
```bash
|
|
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.
|
|
```bash
|
|
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.**
|
|
```bash
|
|
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. |