MQTT是HermesAgent平台实现设备与云低开销、高可靠通信的核心协议，需依次完成平台凭证配置、设备客户端初始化、遥测数据发布、指令订阅及响应上报五步集成。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在使用HermesAgent物联网平台并希望实现设备与云平台之间的低开销、高可靠消息通信，则MQTT协议是核心集成路径。以下是MQTT在HermesAgent中完成端到端接入与交互的实操步骤：
一、配置HermesAgent平台MQTT接入参数
平台需为每个设备分配唯一身份凭证，包括Broker地址、端口、Client ID、用户名与密码，这些参数决定了设备能否成功建立MQTT连接并被平台识别。
1、登录HermesAgent管理控制台，进入【设备管理】→【接入配置】页面。
2、选择目标产品线，点击【生成MQTT凭证】按钮，系统自动生成一组含有效期的client_id、username和password。
3、记录返回的broker地址（如 mqtt.hermesagent.io）及SSL端口（8883）或非SSL端口（1883），确保网络策略允许该端口出站通信。
二、设备端MQTT客户端初始化与连接
设备需基于标准MQTT v3.1.1或v5.0协议实现客户端逻辑，正确设置连接选项（如Clean Session、Keep Alive）以适配HermesAgent心跳机制与会话恢复策略。
1、在嵌入式设备固件中引入Paho-MQTT（C/C++）、Eclipse Paho（Java）或mqtt_client（Rust）等轻量级库。
2、构造MQTT连接对象，设置client_id为平台分配的唯一标识，禁用Clean Session以启用QoS 1消息的离线缓存能力。
3、调用connect()方法前，配置TLS证书验证：若使用SSL端口，必须加载HermesAgent提供的根CA证书（ca.crt）用于服务端身份校验。
三、发布设备遥测数据至指定Topic
HermesAgent采用预定义Topic层级结构路由消息，设备必须按规范格式组织发布路径，否则数据将被平台拒绝或路由至错误处理通道。
1、构造发布Topic，格式为：/v1/{product_key}/{device_key}/telemetry，其中product_key与device_key须与平台注册信息完全一致。
2、将传感器原始数据序列化为JSON，要求包含timestamp（毫秒级Unix时间戳）字段，并确保整体Payload大小不超过64KB限制。
3、调用publish()方法，设置QoS级别为1，启用消息确认机制；若返回CONNACK失败码0x04，说明client_id重复或凭证失效。
四、订阅平台指令Topic并解析下行命令
平台通过固定Topic向设备推送控制指令，设备需维持长连接并主动订阅该路径，及时响应实时性要求高的操作请求。
1、在连接成功回调中执行subscribe()，目标Topic为：/v1/{product_key}/{device_key}/command，QoS设为1以保障指令必达。
2、注册消息到达回调函数，对payload进行UTF-8解码后校验JSON结构，提取msg_id、method、params三个必选字段。
3、若method值为set_light_power，则从params中读取power_state（on/off）并触发本地硬件动作，随后发布响应。
五、上报指令执行结果至Response Topic
设备完成指令处理后，必须向平台反馈执行状态，否则平台将超时标记为失败；响应Topic与原始指令具备严格映射关系，缺失将导致任务状态悬空。
1、构造响应Topic：/v1/{product_key}/{device_key}/command/response/{msg_id}，其中{msg_id}必须与接收到的指令中msg_id完全相同。
2、构建响应JSON体，包含code（200表示成功，500表示内部错误）、message（简明描述）和可选data字段。
3、调用publish()发送响应，QoS保持为1；若平台未在30秒内收到该Topic消息，将在控制台标记该指令为“响应超时”。
