secubox-openwrt/DOCS-zh/MQTT_BRIDGE.md

MQTT 桥接模块

Languages: English | Francais | 中文

版本: 0.4.0 状态: 草案

SecuBox MQTT 桥接通过带主题的 LuCI 界面暴露 USB 适配器和 IoT 传感器。

组件

• 概览 - broker 健康状态、已连接适配器、最近的 payload。
• 设备 - 已配对的 USB 设备及状态 (在线/离线)。
• 设置 - broker 凭据、基础主题模板、保留。

RPC API (luci.mqtt-bridge)

方法	描述
status	Broker 指标、存储的 payload 和当前设置。
list_devices	枚举已配对的 USB/传感器节点。
trigger_pairing	打开配对窗口 (2分钟)。
apply_settings	持久化 broker/桥接配置。

status 现在还包含一个 profiles 数组，描述检测到的 USB/Zigbee 预设。每个条目公开：

字段	描述
id	内部预设标识符 (例如 zigbee_usb2134)。
label	从 USB 描述符获取的友好适配器名称。
vendor / product	USB VID:PID 对。
bus / device	在 dmesg/lsusb 中看到的 Linux 总线/设备编号。
port	可用时解析的 /dev/tty* 路径。
detected	布尔标志 (当 dongle 当前已连接时为 true)。
notes	在设备视图中呈现的人类可读提示。

文件

luci-app-mqtt-bridge/
 ├── htdocs/luci-static/resources/view/mqtt-bridge/*.js
 ├── htdocs/luci-static/resources/mqtt-bridge/common.css
 ├── root/usr/libexec/rpcd/luci.mqtt-bridge
 ├── root/usr/share/luci/menu.d/luci-app-mqtt-bridge.json
 ├── root/usr/share/rpcd/acl.d/luci-app-mqtt-bridge.json
└── root/etc/config/mqtt-bridge

Zigbee / SMSC USB2134B 配置文件

设备标签页现在显示"Bus 003 Device 002: ID 0424:2134 SMSC USB2134B"桥接器的预设，该桥接器通常刷有 Zigbee 协调器固件。LuCI 视图使用上面解释的 profiles 数组，并显示当前检测状态以及 tty 提示。

手动验证 dongle：

dmesg | tail -n 40 | grep -E '0424:2134|usb 3-1'
lsusb -d 0424:2134
ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null

典型内核日志：

[ 6456.735692] usb 3-1.1: USB disconnect, device number 3
[ 6459.021458] usb 3-1.1: new full-speed USB device number 4 using xhci-hcd

将报告的 Bus/Device 编号与 /sys/bus/usb/devices/*/busnum 和 /sys/bus/usb/devices/*/devnum 匹配；RPC 助手检查这些文件并发布解析的 /dev/tty* 路径（当在 /sys/bus/usb/devices/*/tty 下导出时）。如果适配器未插入，UI 仍会呈现预设，以便操作员知道要查找的确切 VID/PID 对。

一旦确认 tty 节点，更新 /etc/config/mqtt-bridge 并重启桥接服务，将 Zigbee 流量绑定到设置标签页中定义的 MQTT 主题。

适配器监控守护进程

该软件包现在安装了一个轻量级监视器 (/usr/sbin/mqtt-bridge-monitor)，用于通知 SecuBox 已连接的适配器：

• 通过 /etc/config/mqtt-bridge 中的 config monitor 'monitor'（间隔秒数）和 config adapter '...' 部分配置。
• 使用标准 init 脚本管理：service mqtt-bridge start|stop|status。
• 将状态转换写入系统日志（logread -e mqtt-bridge-monitor）。
• 更新每个适配器部分的 detected、port、bus、device、health 和 last_seen，LuCI 设备标签页现在会显示这些。
• MQTT 设置视图公开相同的适配器条目，以便您可以启用/禁用预设、重命名标签或覆盖 /dev/tty* 分配，而无需离开 UI。
• 设置视图中的按钮允许您触发重新扫描（API.rescanAdapters）或清除特定适配器的缓存数据（API.resetAdapter），这在重新刷写 dongle 或更换 USB 端口后很有帮助。

使用 uci show mqtt-bridge.adapter 检查持久化的元数据，或使用 ubus call luci.mqtt-bridge status 查看 UI 使用的 JSON payload。

模板和自动化规则

/etc/config/mqtt-bridge 现在包含 Zigbee 和 Modbus 设备的 config template 定义：

config template 'zigbee_default'
	option device_type 'zigbee'
	option topic 'secubox/zigbee/{id}/state'
	option qos '1'
	option retain '1'

这些通过 status RPC（templates 数组）导出，以便 LuCI 或外部客户端可以按设备类型建议主题模式。添加您自己的部分以涵盖其他总线或命名方案。

自动化规则（config rule）可以响应适配器状态转换：

config rule 'zigbee_disconnect'
	option type 'adapter_status'
	option adapter 'zigbee_usb2134'
	option when 'missing'
	option action 'alert'
	option message 'Zigbee USB 桥接器已断开'
	option topic 'alerts/mqtt/zigbee'

当守护进程注意到适配器变为 missing 或 online 时，匹配的规则会写入 syslog 和 /tmp/mqtt-bridge-alerts.log，便于将事件转发到 SecuBox Alerts 或任何其他管道。

下一步

• 添加与 Mosquitto 的真正守护进程集成。
• 支持 TLS 和每设备主题。
• 在传感器阈值上发出 SecuBox 告警。

查看 .codex/apps/mqtt-bridge/TODO.md 了解不断演进的待办事项。