MQTT 配置
MQTT 负责平台命令、属性和设备事件上报。先确认设备身份、当前网络、Broker、认证及主题，再到“通信协议 → MQTT”配置。保存修改要求登录与开发环境功能；默认开发环境功能关闭，按需密码确认开启，保留已有选择。
连接参数
| 配置 | 含义 |
|---|---|
enabled | 用户启用意图，与实际连接状态不同 |
scheme | mqtt 明文或 mqtts TLS |
server/port | Broker 主机和端口，通常 1883/8883，以服务实际配置为准 |
clientId | 当前平台身份，必须避免重复占用 |
| 认证字段 | 按实际平台选择普通用户名/密码或已支持的加密认证 |
keepAlive/autoReconnect | 保活与有界退避重连 |
publishTopics/subscribeTopics | 主题、启用、前缀、类型及相关参数 |
| 遗嘱字段 | 非正常断线的 Broker 遗嘱，不是设备每次停止都主动发送 |
平台自动身份与主题前缀依设备编号、产品/用户信息和认证模式生成；不要拿示例 Client ID 直接替换现场设备。发布主题的类型常见为属性 0、信息 2、监控 3、设备事件 4、升级 5、校时 7。选择页面提供的当前类型，不能据保存了任意数字推断协议已实现。
MQTT 与 MQTTS
MQTTS 需要编译支持、mqtts 功能启用、可信安全传输后端及资源准入。tlsSupported 目前只是检测到非零 PSRAM 的资源提示，不证明安全连接已经可用；内部 DRAM、最大连续块及 TLS 握手仍要分别核对。PSRAM 不能替代网络所需内部 RAM。
内存压力下 TLS 暂停保留用户的协议、端口、凭据与启用意图，禁止自动降为明文 MQTT。恢复须等待资源与实例实际就绪，排队重建不等于 Broker 已连接。蜂窝 TLS 后端不可用时拒绝启动，不换普通 Client；具体错误可能是实例启动失败或安全传输不可用，按当前状态排查。
旧内存降密/禁用资料保留，恢复安全传输只依据明确且合法的原配置；缺失时要求重新配置，不猜端口或删除用户资料。停止、重建和切换网络等待在途操作退休，资源尚未释放时不并行创建第二个重连。
主题、QoS 与数据
当前 PubSubClient 发布调用实际使用 QoS 0，配置里的发布 qos=1 不会把发送升级为 QoS 1。订阅按订阅主题 QoS 请求，遗嘱的 QoS 是另一个独立字段。retain 可影响 Broker 保留，不代表动作完成或平台业务已处理。
平台下发常用 id/value 数组：
[
{
"id": "brightness",
"value": "128"
}
]平台触发操作符 1 是按 ID 接受任意值的设置模式，具体输出仍验证参数；见平台触发。读取报告保留采样时间、质量与单位，不能以收到时间替代测量时间；启动只读补报不会重放 Modbus 输出。
命令脚本 MQTT <topicIndex> <message> 使用发布主题索引，不是 QoS。每条队列正文最多 512 字节，模板中间和最终结果也须完整；JSON/RAW 超限不截断成伪成功。
上报队列与身份
客户端环形槽最多 8 条等待项加 1 条保留发送项；发布失败可保留原项，环形满额可能淘汰最旧等待报告。规则离线报告缓存另有 5 槽，不能用其中一层深度代表全部未送达数据。内存、限流、主题、OTA/NTP 等状态也可能拒绝准入。
报告在准入时绑定原客户端实例、主题、编码及已生成正文。实例销毁、改配或禁用后旧报告不能投到新 Broker、身份或主题；本地保留、排队和发送返回均不能证明平台收到。未知输出不会因为上报失败自动重放；电机 ACK 的报告状态也不会改变已尝试步骤。
仅连接测试
POST /api/mqtt/test 会先保存并校验恢复记录，再临时应用测试参数和重建连接。测试期间隔离业务上报、命令订阅、遗嘱、设备信息、校时及连接规则事件。connectionTestOnly=true 不能当作完整业务测试。
通过 GET /api/mqtt/status 查看连接结果及 testRestorePending 等恢复状态，测试结束后自动尝试恢复原配置。若恢复失败，保留恢复资料并提示待处理；不要直接覆盖。配置恢复不等于正式 Broker 已重连，握手成功也不证明认证之外的业务主题可用。测试重建会打断现有连接，应安排在已授权的设备测试范围。
状态与排错
状态字段包括 connected/connecting、initialized、lastErrorCode/Name/Class/Message 和 statusReason。生命周期切换可能为错误码 0、MQTT_LIFECYCLE_BUSY、pending，不能只以零码判连接成功。重连、断开返回已排队或待退休时继续核对状态，不高频重复请求。
| 现象 | 核对项 |
|---|---|
| 网络/DNS/TCP 失败 | 当前 STA 地址、网关、Broker 主机/端口及路由 |
| 认证失败 | 设备身份、Client ID、账号、Broker 日志及平台模式 |
| MQTTS 不可用 | 编译能力、功能、可信后端、内部 RAM 与连续块 |
| 有连接但无数据 | 实际主题、启用状态、前缀、编码、队列与平台收到的完整正文 |
| HTTP 401 | 重新登录 |
| HTTP 503/Retry-After | 按退避提示处理并保存失败证据；正常声明负载下不能据此判长期稳定通过 |
MQTT admission storage unavailable; restart required 表示本次启动的准入存储不可用，自动重试不能修复。保留配置和失败证据，按现场授权处理资源并重启，不把它当成 Broker 认证失败。
常用接口为 /api/protocol/mqtt/config、/api/mqtt/status、/api/mqtt/test、/api/mqtt/reconnect、/api/mqtt/disconnect 和 /api/mqtt/ntp-sync。具体方法与字段见API 参考。本页软件行为不代表实机、平台收件或长期稳定验收通过。