Zigbee2MQTT/Installation.md aktualisiert
This commit is contained in:
@@ -1 +1,268 @@
|
||||
A
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user