MQTT 配置
大约 4 分钟
MQTT 配置
功能说明
MQTT 是 FastBee 设备与云平台/私有服务器通信的主要协议。支持设备状态上报、远程控制指令下发、遗嘱消息和自动重连。
保存配置前先确认 Broker 地址、端口、客户端 ID 和主题前缀与平台侧一致；公网或生产环境建议启用认证并评估 TLS 资源占用。
连接问题按图从左到右排查：网络未就绪时先回到网络页，认证失败时核对 Broker 和账号，主题异常时再检查平台侧 Topic 约定。
操作指南
- 进入 Web 界面 → MQTT 配置（或通信协议页面）
- 填写服务器地址、端口、认证信息
- 配置主题前缀
- 保存并测试连接
协议选择 (mqtt / mqtts)
MQTT 配置页面支持在 mqtt（明文 TCP）和 mqtts（TLS 加密）之间切换。后端 API 通过 tlsSupported 字段告知前端当前设备是否具备 TLS 运行条件。
| 协议 | 默认端口 | 内存需求 | 适用场景 |
|---|---|---|---|
| mqtt | 1883 | ~4-8KB | 内网、开发调试、无 PSRAM 设备 |
| mqtts | 8883 | ~20-40KB (TLS 握手) | 公网、生产环境、带 PSRAM 设备 |
内存与 PSRAM 要求
- 带 PSRAM 设备（ESP32-S3 N8R2/N16R8 等）：mqtts 可正常使用，TLS 缓冲区优先分配到 PSRAM。
- 无 PSRAM 设备（ESP32-C3、ESP32-C6、ESP32 4MB 等）：mqtts 连接可能因 DRAM 不足而失败。Web 界面会在选择 mqtts 时显示内存不足提示。如果 mqtts 连接失败，请切换回 mqtt。
- 固件在启动时检测 PSRAM，无 PSRAM 设备选择 mqtts 会输出串口警告日志。
连接失败处理
mqtts 连接失败时（尤其是无 PSRAM 设备），固件会：
- 进入慢速退避重连（避免反复消耗内存）
- 输出清晰的串口日志提示
MQTTS failed: insufficient memory, please switch to mqtt:// - 恢复 Web 服务等被暂停的服务
用户只需在 Web 配置页面将协议切换回 mqtt 并保存即可恢复。
参数说明
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 协议 | mqtt（明文）或 mqtts（TLS 加密） | mqtt |
| 服务器地址 | MQTT Broker IP/域名 | 空 |
| 端口 | 连接端口 | 1883（TCP）/ 8883（TLS） |
| 客户端ID | 设备唯一标识 | FastBee- |
| 用户名 | 认证用户名 | 空 |
| 密码 | 认证密码 | 空 |
| 主题前缀 | 发布/订阅主题前缀 | fastbee/ |
| Keep Alive | 心跳间隔（秒） | 60 |
| QoS | 消息质量等级 | 0 |
| 遗嘱主题 | LWT 主题 | {prefix}/status |
| 遗嘱消息 | LWT 消息内容 | offline |
配置示例
连接公共 MQTT 服务器
{
"broker": "broker.emqx.io",
"port": 1883,
"clientId": "FastBee-A1B2C3",
"username": "",
"password": "",
"prefix": "fastbee/device01/",
"keepAlive": 60
}连接私有服务器（带认证）
{
"broker": "192.168.1.10",
"port": 1883,
"clientId": "FastBee-A1B2C3",
"username": "device01",
"password": "secret123",
"prefix": "home/esp32/",
"keepAlive": 30
}主题格式
发布主题（设备 → 平台）
| 主题 | 说明 | topicType |
|---|---|---|
| {prefix}property/post | 属性数据上报 | 0 |
| {prefix}info/post | 设备信息上报 | 2 |
| {prefix}event/post | 事件上报 | 4 |
| {prefix}monitor/post | 监控数据上报 | 3 |
| {prefix}ntp/post | NTP 时间上报 | 7 |
| {prefix}http/upgrade/reply | HTTP 升级回复 | 5 |
| {prefix}fetch/upgrade/reply | 拉取升级回复 | 6 |
订阅主题（平台 → 设备）
| 主题 | 说明 | topicType |
|---|---|---|
| {prefix}function/get | 功能指令下发 | 1 |
| {prefix}info/get | 设备信息查询 | 2 |
| {prefix}monitor/get | 监控数据查询 | 3 |
| {prefix}ntp/get | NTP 时间查询 | 7 |
| {prefix}http/upgrade/set | HTTP 升级下发 | 5 |
| {prefix}fetch/upgrade/set | 拉取升级下发 | 6 |
{prefix}为配置的主题前缀，默认fastbee/，每个主题可独立启用/禁用
故障排除
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 连接失败 | 服务器不可达 | 检查 IP/端口、防火墙 |
| 认证失败 | 用户名密码错误 | 核对 Broker 配置的凭据 |
| 频繁断线 | Keep Alive 太短 | 增加心跳间隔（30-120秒） |
| 消息丢失 | QoS=0 | 对重要消息使用 QoS=1 |
| 内存不足 | 订阅主题过多 | 减少订阅数量或消息大小 |
| mqtts 连接失败（无 PSRAM） | DRAM 不足以支撑 TLS 握手 | 切换回 mqtt 协议，或使用带 PSRAM 的设备 |
| mqtts 连接超时后自动退避 | TLS SSL 内存分配失败 | 查看串口日志确认，切换为 mqtt |