diff --git a/Zigbee2MQTT/Installation.md b/Zigbee2MQTT/Installation.md index 8c7e5a6..341097d 100644 --- a/Zigbee2MQTT/Installation.md +++ b/Zigbee2MQTT/Installation.md @@ -1 +1,268 @@ -A \ No newline at end of file + +## 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 `` and `` with your new system's login details. + + ```bash + scp zigbee2mqtt_backup.tar.gz @:/home// + ``` + +#### 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. \ No newline at end of file