# 通信协议

设备端提供 MQTT/MQTTS 和 Modbus RTU 两条协议链路。MQTT 负责平台连接、属性/事件上报和命令下发；Modbus RTU 作为主站轮询 RS485 从站，并将结果映射为本地外设数据。

## 页面导读

- **页面内容**: MQTT/MQTTS 与 Modbus RTU 的配置入口、主题类型、规则联动方式和故障排查顺序。
- **适用场景**: 需要把设备接入物联网平台，或通过 RS485 轮询 Modbus 从站并联动本地规则的用户。
- **前置条件**: 设备网络已在线；使用 MQTTS 时需先在“功能配置”开启 `mqtts`。
- **验收点**: `/api/mqtt/status` 显示 `connected`，Modbus 轮询成功/失败计数符合预期，平台可收到上报并能下发命令。

```mermaid
flowchart LR
  A[Web 配置] --> B[ProtocolManager]
  B --> C[网络适配器\nWiFi / W5500 / 4G]
  C --> D[MQTT/MQTTS]
  B --> E[UART/RS485]
  E --> F[Modbus RTU 主站]
  F --> G[寄存器映射/外设规则]
  D --> H[平台上报与命令]
  G --> H
```

## 配置入口

| 协议 | 页面 | API |
| --- | --- | --- |
| MQTT/MQTTS | 通信协议 → MQTT | `/api/protocol/mqtt/config`、`/api/mqtt/status` |
| Modbus RTU | 通信协议 → Modbus RTU | `/api/protocol/modbus-rtu/config`、`/api/modbus/*` |
| [心知天气与旧资源迁移](https://www.fastbee.cn/doc/device/v2/protocols/remote-resources.md) | 设备屏幕 → 心知天气组件 | `/api/screen-panel/weather` |

先确认网络在线，再保存协议配置。保存后查看状态和设备日志；不要只根据“已保存”判断连接成功。

![MQTT 配置](https://www.fastbee.cn/doc/assets/protocol-mqtt-config.d4iGQpef.png)

## MQTT/MQTTS

支持：

* 非加密 MQTT（通常端口 `1883`）和 TLS 加密 MQTTS（通常端口 `8883`）。
* 自定义 Client ID、用户名/密码、Keep Alive 和遗嘱消息。
* 自动重连、事件上报、属性/监控数据上报和平台命令订阅。
* WiFi、W5500 和 EC801E-CN 4G 网络传输层。

配置步骤：

1. 确认设备网络在线并在 MQTT 页面启用连接；使用 MQTTS 时再到“功能配置”开启 `mqtts`。
2. 在 MQTT 页面填写服务器、端口、Client ID 和认证信息。
3. 选择需要的发布/订阅主题，保存并连接。
4. 在 `/api/mqtt/status` 或仪表盘确认 `connected`，再验证平台消息。

`/api/mqtt/test` 先保存恢复记录，再临时应用参数做仅连接测试；业务上报和订阅隔离，结束后尝试恢复。恢复待处理需保留资料并核对状态，握手成功不表示平台业务收件。

### 主题配置

主题由页面中的发布/订阅列表决定；常见类型包括：

| 类型 | 用途 |
| --- | --- |
| `property` | 传感器和外设属性上报 |
| `info` | 设备信息/配置消息 |
| `event` | 按键、故障、告警和设备事件 |
| `monitor` | 状态监控 |
| `ntp` | 时间同步 |
| HTTP upgrade | 已实现的远程升级控制与结果，依编译与分区能力 |

不要在集成程序中硬编码主题前缀；读取实际配置或使用平台分配的主题。

## Modbus RTU

当前固件默认提供 Modbus **主站**能力：

* UART TX/RX 和可选 DE 引脚配置。
* 多从站地址、功能码、寄存器范围和数据类型映射。
* 周期轮询、相邻寄存器合并读、失败重试和超时统计。
* 线圈/寄存器写入，以及通过外设执行规则联动。

配置步骤：

1. 接好 RS485 收发器，确认 A/B、GND、终端电阻和 DE/RE 方向控制。
2. 在 Modbus 页面选择串口、波特率、校验位和停止位。
3. 添加从站设备，填写地址和寄存器映射。
4. 保存后查看轮询成功/失败计数，再创建规则或 MQTT 上报。

Modbus 从站响应功能默认关闭（`FASTBEE_MODBUS_SLAVE_ENABLE=0`），不要按从站设备文档配置本机为从站。

## 规则联动

Modbus 读取由既有调度和总线仲裁处理，当前有效的映射数据可用于独立事件规则；不要把采集动作后紧跟输出当作阈值门控。

```text
RS485 从站 → 轮询任务 → 寄存器映射 → 本地传感器缓存
                                      ↓
                              规则条件/动作
                                      ↓
                              GPIO、显示或 MQTT
```

规则最多 3 个触发器和 4 个动作，详细配置见 [外设执行](https://www.fastbee.cn/doc/device/v2/periph-exec.md)。

## 故障排查

| 现象 | 优先检查 |
| --- | --- |
| MQTT 未连接 | DNS、服务器/端口、账号密码、Client ID、TLS 功能和系统时间 |
| MQTT 频繁重连 | WiFi 信号、Keep Alive、Broker 日志和设备内存 |
| Modbus 全部超时 | A/B 是否接反、波特率/校验、从站地址、DE 引脚和共地 |
| 个别寄存器异常 | 功能码、寄存器基址、字节序、数据类型和缩放系数 |
| 规则没有动作 | `modbus` 功能、轮询任务、目标外设和规则启用状态 |

接口、状态字段和错误码见 [API 接口参考](https://www.fastbee.cn/doc/device/v2/dev/api-reference.md)；网络传输层见 [网络配置](https://www.fastbee.cn/doc/device/v2/system/network-config.md)。

当前 PubSubClient 发布实际使用 QoS 0，发布配置的 `qos=1` 不提供 QoS 1 送达保证；订阅与遗嘱的 QoS 分别处理。旧远程通道已停用，相关旧接口返回410，绑定退休来源的规则整条暂停。详细边界见各专题。

## 常见问题

### 保存协议配置后显示“已保存”，是否代表连接成功？

不代表。保存只写入配置；须在 `/api/mqtt/status` 或仪表盘确认 `connected`，并验证平台消息收发后，才算连接成功。

### 可以把本机配置为 Modbus 从站吗？

不可以。Modbus 从站响应功能默认关闭（`FASTBEE_MODBUS_SLAVE_ENABLE=0`），当前固件默认只提供主站能力，不要按从站设备文档配置本机为从站。

### 发布配置 `qos=1` 是否提供 QoS 1 送达保证？

不提供。当前 PubSubClient 发布实际使用 QoS 0；订阅与遗嘱的 QoS 分别处理，不要把发布配置当作送达保证证据。

### 可以在集成程序中硬编码主题前缀吗？

不要。主题由页面中的发布/订阅列表决定；集成程序应读取实际配置或使用平台分配的主题。

## 相关文档

* [API 接口参考](https://www.fastbee.cn/doc/device/v2/dev/api-reference.md)
* [网络配置](https://www.fastbee.cn/doc/device/v2/system/network-config.md)
* [心知天气与旧资源迁移](https://www.fastbee.cn/doc/device/v2/protocols/remote-resources.md)
* [外设执行](https://www.fastbee.cn/doc/device/v2/periph-exec.md)
