MQTT 开发文档

准备 Broker 与设备

• 准备可从面板访问的 Broker

  使用自己管理的 MQTT Broker，例如局域网里的 Mosquitto。记下主机、端口、用户名与密码。为设备配置 Broker 授权，允许它订阅自身网关的 command Topic、发布设备状态、结果、在线状态和 revision。需要 HA 自动发现时，再允许相应的 homeassistant/switch/…/config 发布。

• 核对网关与联网版本

  使用兼容的 LANBON 版及适用固件。Mesh 组网在主节点设置开放 MQTT。准备一个 MQTT 客户端连接同一 Broker，用来订阅和验证消息。

设置设备连接

1. 开启开放集成

   打开面板「设置 → 开放集成」，开启总开关。进入 Broker 设置并输入主机，若需自定义端口，按面板提示填写主机:端口。输入 Broker 的用户名与密码。

2. 匹配 Broker 的传输设置

   按 Broker 的监听配置选择 TLS。常见默认端口为明文 1883、TLS 8883。面板若标明局域网 TLS 不校验证书，该模式只加密传输，无法验证 Broker 身份。请在可信局域网中使用，并限制 Broker 和设备访问范围。

3. 开启开放 MQTT 并确认在线

   打开「开放 MQTT」子开关。首次验证保持 Discovery 关闭。MQTT 客户端订阅下面的过滤器，确认 loip/<gateway_id>/availability 收到 online。初次识别网关可从这个过滤器找到 ID，或在 LOIP /info 查 gateway_id。账号权限限定到某个网关时，直接订阅该网关的 availability Topic。

   复制

   loip/+/availability

订阅状态并发送指令

1. 订阅组件状态与结果

   把示例中的网关、设备和组件标识替换为实际值。可在 Broker 中查看已有 state Topic，或从 LOIP 的设备快照读取 ID。保留组件 ID 中的冒号。先订阅 state、result 和 availability，再发送命令。状态是保留消息，结果是非保留消息。revision 标识当前快照版本。

   复制

   loip/aabbccddeeff/availability
   loip/aabbccddeeff/revision
   loip/aabbccddeeff/d/aabbccddeeff/availability
   loip/aabbccddeeff/d/aabbccddeeff/c/switch:1/state
   loip/aabbccddeeff/d/aabbccddeeff/c/switch:1/result

2. 发布命令

   用 MQTT 客户端发布到下面的 command Topic，选择 QoS 1、关闭 Retain。Payload 使用完整 LOIP JSON，把示例中的 ID 替换成与 Topic 一致的实际值，每次新操作换一个 request_id。调光、风扇、窗帘和热水器同样读取设备声明，再选择对应的命令和参数。

   复制

   loip/aabbccddeeff/d/aabbccddeeff/c/switch:1/command

3. 确认设备和状态变化

   发送下面的示例后，在 result 中用 request_id 找到对应结果。观察设备实际动作，并确认 state Topic 中的 state.on 变为 true。再在面板上手动关闭开关，检查 MQTT 客户端是否收到新状态。QoS 1 的送达确认和设备操作结果分别读取。

   复制

   {
     "request_id": "setup-001",
     "device_id": "aabbccddeeff",
     "component_id": "switch:1",
     "command": "set_on",
     "params": {
       "on": true
     }
   }

查看其他组件的命令示例

在 Home Assistant 使用 MQTT 自动发现

• 自动发现使用现有 Broker

  面板把开关实体的发现配置发布到同一个 Broker。Home Assistant 读取配置里的命令和状态 Topic，自动创建开关。设备其余组件可按各自的 MQTT 命令和状态 Topic 接入。

查看 Home Assistant 用户接入指南

排错与停用

• 没有 online 消息

  核对两个开关、Broker 的监听地址和端口、TLS 模式及账号权限。查看 Broker 连接日志。若已经有多个网关，在订阅中用正确的 gateway_id 缩小范围。

• 有状态却无法控制

  核对客户端发布权限、Topic 与 JSON 中的 ID、命令格式及参数。先看 result 和新状态，再决定是否重发。设备离线时保留的状态仍可见，控制前同时核对网关和目标的 availability。

• 暂停或恢复

  关闭开放 MQTT 可暂停 Broker 连接。关闭开放集成总开关也会停止 MQTT，并保留保存的子开关、Discovery 和 Broker 配置。重新开启总开关后，已启用且配置有效的 MQTT 会重新连接。恢复出厂会清除这些设置和凭据。

资料与下载