单片机与物联网 / 系统课时
接通命令下发和结果响应
接通命令下发和结果响应
让服务端 App 向 motor-07 下发一次调速命令,并等待设备返回结果。这里使用 MQTT 5 的响应主题与关联数据形成请求应答闭环:先确保订阅响应成功,再发送命令,最后依据关联标识验收结果,而不是把 Broker 的确认误认为命令已经执行。
学习目标
- 设计独立的命令 Topic、响应 Topic 和命令唯一标识。
- 使用 MQTT 5 属性打通 App、Broker、设备的请求应答。
- 区分传输确认、业务执行结果、超时与重复交付。
定义命令与响应契约
命令主题为 lab/motor-07/cmd,响应主题为 lab/motor-07/replies/app-01,均使用 QoS 1 且 retain=false。命令 JSON 包含 commandId、action=set_speed 和 rpm=1200;设备返回包含相同 commandId、status 与成功时的 appliedRpm。
请求方还需在 MQTT 5 PUBLISH 属性中设置 ResponseTopic 和二进制 CorrelationData。设备按前者指定的 Topic 回传消息,原样复制后者;App 同时核对响应属性与消息体中的 commandId,避免不同请求的响应串线。Broker 只负责转发,不会自动代设备生成业务响应。
区分传输确认与执行确认
App 必须先订阅响应 Topic 并收到 SUBACK,随后才能发布命令,避免设备先回复而 App 尚未订阅。命令的 PUBACK 仅确认发送端这一跳被 Broker 接收;只有收到设备回传的 status=ok,才代表本例的模拟电机已完成调速。

实现可运行的双端程序
准备本地支持 MQTT 5 的 Broker,地址为 127.0.0.1:1883,并安装 python -m pip install "paho-mqtt>=2,<3"。下面用内存变量模拟电机转速,不会操作真实设备;接入硬件时要在实际执行成功之后才返回 ok。
将程序保存为 command_demo.py。设备保留已处理命令的内存记录,App 每次启动都生成新的命令 ID,并在确认响应主题订阅成功后发布命令。
import json
import sys
import threading
from uuid import uuid4
import paho.mqtt.client as mqtt
from paho.mqtt.packettypes import PacketTypes
from paho.mqtt.properties import Properties
CMD = "lab/motor-07/cmd"
REPLY = "lab/motor-07/replies/app-01"
def create_client(role):
return mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
client_id=f"lesson10-{role}", protocol=mqtt.MQTTv5)
def run_device():
processed = {}
motor = {"rpm": 0}
client = create_client("cmd-device")
def on_connect(c, userdata, flags, reason_code, properties):
if not reason_code.is_failure:
c.subscribe(CMD, qos=1)
def on_subscribe(c, userdata, mid, reason_code_list, properties):
if reason_code_list and all(not rc.is_failure for rc in reason_code_list):
print("设备订阅就绪")
def on_message(c, userdata, msg):
try:
request = json.loads(msg.payload)
except (ValueError, UnicodeDecodeError):
print("忽略无效 JSON")
return
if not isinstance(request, dict):
return
cmd_id = request.get("commandId")
if not isinstance(cmd_id, str):
return
correlation = getattr(msg.properties, "CorrelationData", None)
reply_to = getattr(msg.properties, "ResponseTopic", None)
# 回复地址必须受控,关联数据必须与业务命令 ID 一致。
if reply_to != REPLY or correlation != cmd_id.encode("utf-8"):
print("拒绝不匹配的响应主题或关联数据")
return
if cmd_id in processed:
result = processed[cmd_id]
print(f"设备跳过重复命令 {cmd_id}")
else:
rpm = request.get("rpm")
if request.get("action") == "set_speed" and type(rpm) is int and 0 <= rpm <= 3000:
motor["rpm"] = rpm
result = {"commandId": cmd_id, "status": "ok", "appliedRpm": motor["rpm"]}
print(f"设备执行 {cmd_id} rpm={rpm}")
else:
result = {"commandId": cmd_id, "status": "rejected", "reason": "invalid_command"}
processed[cmd_id] = result
# 网络回调只发响应,不阻塞等待自己的 PUBACK。
props = Properties(PacketTypes.PUBLISH)
props.CorrelationData = correlation
c.publish(reply_to, json.dumps(result, separators=(",", ":")),
qos=1, retain=False, properties=props)
client.on_connect = on_connect
client.on_subscribe = on_subscribe
client.on_message = on_message
client.connect("127.0.0.1", 1883, 60)
try:
client.loop_forever()
except KeyboardInterrupt:
client.disconnect()
def run_app():
cmd_id = uuid4().hex
subscribed = threading.Event()
answered = threading.Event()
client = create_client("cmd-app-01")
def on_connect(c, userdata, flags, reason_code, properties):
if not reason_code.is_failure:
c.subscribe(REPLY, qos=1)
def on_subscribe(c, userdata, mid, reason_code_list, properties):
if reason_code_list and all(not rc.is_failure for rc in reason_code_list):
subscribed.set()
def on_message(c, userdata, msg):
if msg.topic != REPLY or getattr(msg.properties, "CorrelationData", None) != cmd_id.encode():
return
try:
result = json.loads(msg.payload)
except (ValueError, UnicodeDecodeError):
return
if isinstance(result, dict) and result.get("commandId") == cmd_id:
print("App 收到", json.dumps(result, separators=(",", ":")))
answered.set()
client.on_connect = on_connect
client.on_subscribe = on_subscribe
client.on_message = on_message
client.connect("127.0.0.1", 1883, 60)
client.loop_start()
try:
if not subscribed.wait(5):
print("响应订阅失败或超时")
return
props = Properties(PacketTypes.PUBLISH)
props.ResponseTopic = REPLY
props.CorrelationData = cmd_id.encode("utf-8")
request = {"commandId": cmd_id, "action": "set_speed", "rpm": 1200}
print(f"App 发送 {cmd_id}")
client.publish(CMD, json.dumps(request), qos=1, retain=False,
properties=props).wait_for_publish()
if not answered.wait(5):
print("业务响应超时:PUBACK 不代表设备已执行")
finally:
client.disconnect()
client.loop_stop()
if __name__ == "__main__":
if len(sys.argv) != 2 or sys.argv[1] not in {"device", "app"}:
raise SystemExit("用法: python command_demo.py device|app")
(run_device if sys.argv[1] == "device" else run_app)()预期结果:先运行 python command_demo.py device,看到 设备订阅就绪,再在另一终端运行 python command_demo.py app。App 输出如下,<ID> 是本次生成的十六进制命令标识,前后两处实际值相同:
App 发送 <ID>
App 收到 {"commandId":"<ID>","status":"ok","appliedRpm":1200}设备端同时打印 设备执行 <ID> rpm=1200。App 的匹配条件包含 CorrelationData 与业务命令 ID,收到其他请求的响应不会误结束等待。
验证超时、拒绝与重复交付
- 停止设备,仅运行 App。响应订阅成功约 5 秒后会看到
业务响应超时;这只能说明未收到匹配结果,不能证明设备一定没有执行。 - 重新运行设备和 App,应收到
status=ok。把示例命令的转速改为 4000 再运行,会收到status=rejected和reason=invalid_command,这属于明确的业务拒绝。 - QoS 1 可能重投相同命令。示例使用
processed[commandId]复用首次处理结果,同一进程内不会重复改变转速;但设备重启会清空这份记录。
生产环境应持久化命令 ID、执行状态和结果,并对命令主题、响应主题设置身份认证与 ACL。超时重试必须复用原业务 commandId;若支持多个 App,要为每个 App 分配独立回复 Topic。命令不可设为 Retained,避免设备稍后订阅时误执行过期指令。