CyberMind-FR
ccfb58124c
Add complete French (fr) and Chinese (zh) translations for all documentation: - Root files: README, CHANGELOG, SECURITY, BETA-RELEASE - docs/: All 16 core documentation files - DOCS/: All 19 deep-dive documents including embedded/ and archive/ - package/secubox/: All 123+ package READMEs - Misc: secubox-tools/, scripts/, EXAMPLES/, config-backups/, streamlit-apps/ Total: 346 translation files created Each file includes language switcher links for easy navigation between English, French, and Chinese versions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
120 lines
5.1 KiB
Markdown
120 lines
5.1 KiB
Markdown
# MQTT 桥接模块
|
||
|
||
> **Languages:** [English](../DOCS/MQTT_BRIDGE.md) | [Francais](../DOCS-fr/MQTT_BRIDGE.md) | 中文
|
||
|
||
**版本:** 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：
|
||
|
||
```bash
|
||
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` 定义：
|
||
|
||
```uci
|
||
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`）可以响应适配器状态转换：
|
||
|
||
```uci
|
||
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` 了解不断演进的待办事项。
|