本指南将教你如何在 Linux 上运行 Zigbee2MQTT。

虽然我们以在 Raspberry Pi 4 上使用 Raspbian Stretch Lite 为例，但这个指南基本上适用于所有的 Linux 设备。

有些用户可能会在不同的系统版本上操作，比如在 Openhabian.piopenhabian 上，所以具体步骤可能会略有不同。

开始前，请确保你的系统中已经配置了 MQTT broker。Mosquitto 是一个很好的选择，当然，其他的 broker 也可以。

确定适配器位置及检查权限
首先，你要确认适配器的具体位置。把适配器接到 Raspberry Pi 上，大部分时间它的位置都是 /dev/ttyACM0。可以用下面的命令检查：

pi@raspberry:~ $ ls -l /dev/ttyACM0
crw-rw---- 1 root dialout 166, 0 May 16 19:15 /dev/ttyACM0  # <-- adapter (CC2531 in this case) on /dev/ttyACM0

如果你使用的是 Ethernet 连接的适配器，请按照适配器的说明书操作。

不过，建议使用 "by ID" 路径来找设备（详见“适配器设置”部分）。这种方法更加稳定，尤其是当 Raspberry Pi 连接了多个串行设备时。例如，设备位置可能是 /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00。

pi@raspberry:/ $ ls -l /dev/serial/by-id
total 0
lrwxrwxrwx. 1 root root 13 Oct 19 19:26 usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00 -> ../../ttyACM0

安装步骤

  1. 安装 Node.js 和所需依赖
sudo curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs git make g++ gcc
  1. 确认正确安装了 nodejs 和 npm
node --version
npm --version
  1. 创建 zigbee2mqtt 的目录，并赋予权限
sudo mkdir /opt/zigbee2mqtt
sudo chown -R ${USER}: /opt/zigbee2mqtt
  1. 克隆 Zigbee2MQTT 仓库
git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
  1. 安装必要的依赖
cd /opt/zigbee2mqtt
npm ci
  1. 构建应用程序
npm run build

在 Ubuntu 上的提示
你可以用 Snap 在 Ubuntu 上安装 Node.js。

sudo snap install node --classic
node --version

配置
在启动 Zigbee2MQTT 前，要复制并调整 configuration.yaml 文件的设置。

复制并编辑配置文件：

cp /opt/zigbee2mqtt/data/configuration.example.yaml /opt/zigbee2mqtt/data/configuration.yaml
nano /opt/zigbee2mqtt/data/configuration.yaml

默认的配置已经很完善，你只需要修改 MQTT 服务器的 url/认证以及串口设置。

启动 Zigbee2MQTT
一切准备好后，就可以启动 Zigbee2MQTT 了。

cd /opt/zigbee2mqtt
npm start

如果成功，你会看到以下输出：

Zigbee2MQTT:info  开始 Zigbee2MQTT 版本 1.X.X
Zigbee2MQTT:info  启动 zigbee-herdsman

(可选) 使用 systemctl 使 Zigbee2MQTT 作为守护进程运行
若希望 Zigbee2MQTT 在后台作为守护进程运行，并在开机时自动启动，我们可以通过 systemctl 来实现。

为 Zigbee2MQTT 创建一个 systemctl 配置文件

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

将以下内容添加到文件中：

[Unit]
Description=zigbee2mqtt
After=network.target

[Service]
Environment=NODE_ENV=production
ExecStart=/usr/bin/npm start
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=inherit
# 若不希望 Zigbee2MQTT 的消息填充 syslog，可以使用 StandardOutput=null，更多选项参考 systemd.exec(5)
StandardError=inherit
Restart=always
RestartSec=10s
User=pi

[Install]
WantedBy=multi-user.target

如果你使用的是 Raspberry Pi 1 或 Zero 并且按照这个指南操作，将 ExecStart=/usr/bin/npm start 替换为 ExecStart=/usr/local/bin/npm start。

如果你使用的是 Raspberry Pi 或一个从 SD 卡启动的系统，你可能希望减少写入到磁盘的日志文件数量。通过 Systemd 服务会导致所有内容都记录两次：一次通过 systemd 单元，另一次是 Zigbee2MQTT 默认记录到文件下。你可能只想保留其中之一：

  • 仅保留下面的日志 --> 在 systemd 单元中使用 StandardOutput=null
  • 仅保留日志 --> 在 Zigbee2MQTT 配置中设置 advanced.log_output = ['console']

如果想在另一个目录放置所有 Zigbee2MQTT 数据，加入 Environment=ZIGBEE2MQTT_DATA=/路径/到/数据 在 [Service] 下。

保存文件并退出。

验证配置是否工作：

# 启动 Zigbee2MQTT
sudo systemctl start zigbee2mqtt

# 显示状态
systemctl status zigbee2mqtt.service

输出应如下：

[输出内容]

既然一切都正常，我们希望 systemctl 在开机时自动启动 Zigbee2MQTT，执行以下命令即可：

sudo systemctl enable zigbee2mqtt.service

完成！😃

以下是一些建议你可能会用到的小技巧：

停止 Zigbee2MQTT

sudo systemctl stop zigbee2mqtt

启动 Zigbee2MQTT

sudo systemctl start zigbee2mqtt

查看 Zigbee2MQTT 的日志

sudo journalctl -u zigbee2mqtt.service -f

(以后) 更新 Zigbee2MQTT 到最新版本
要更新 Zigbee2MQTT 到最新版本，执行以下命令：

# 停止 Zigbee2MQTT 并转到目录
sudo systemctl stop zigbee2mqtt
cd /opt/zigbee2mqtt

# 备份配置
cp -R data data-backup

# 更新
git pull
npm ci
npm run build

# 恢复配置
cp -R data-backup/* data
rm -rf data-backup

# 启动 Zigbee2MQTT
sudo systemctl start zigbee2mqtt
打赏微海报分享