用途
该技能使 AI 能够与 MQTT（一种轻量级发布/订阅协议）交互，用于高效的物联网通信。可用于发布遥测数据或订阅设备更新，在受限环境中实现实时交互。
适用场景
适用于需要低带宽、实时消息的场景，例如从 IoT 设备发送传感器数据、远程设备控制或遥测监控。不适用于文件传输等高吞吐需求，此类场景 HTTP 更合适。
主要能力
- 向主题发布消息，支持可配置的服务质量（QoS）等级（0、1 或 2）。
- 订阅主题并异步处理传入消息。
- 支持保留消息（retained messages）、最后遗嘱（last will and testament）以及通配符订阅（例如用 "#" 匹配所有子主题）。
- 通过 TLS 以及用户名/密码等认证方式建立安全连接。
使用方式
使用 MQTT 时，先通过客户端库连接到 broker。使用凭据建立连接，然后发布或订阅。例如在循环中：连接、订阅、处理消息、断开连接。敏感数据使用环境变量，如用 $MQTT_BROKER_URL 表示 broker 地址。对于不稳定网络，始终处理重连。
常用命令/API
Python 交互使用 Paho MQTT 库，导入方式：
import paho.mqtt.client as mqtt
连接到 broker：
client.connect(broker_address, port=1883)
带认证的示例：
client.username_pw_set(username='$MQTT_USERNAME', password='$MQTT_PASSWORD')
发布消息：
client.publish(topic, payload, qos=1)
示例：
client.publish('sensors/temp', '22.5', qos=1)
订阅：
client.subscribe(topic, qos=1)
示例：
client.subscribe('commands/device1', qos=1)
配置格式：使用 JSON 文件保存设置，例如 {"broker": "$MQTT_BROKER_URL", "topic": "sensors/temp"}。CLI 工具如 mosquitto_pub 可通过 subprocess 调用：
subprocess.run(['mosquitto_pub', '-h', '$MQTT_BROKER_URL', '-t', 'sensors/temp', '-m', '22.5'])
集成说明
将 MQTT 封装进 AI 智能体的代码中进行集成。为密钥设置环境变量，例如 export $MQTT_API_KEY 用于基于令牌的认证。多服务部署时，使用 HiveMQ 或 Mosquitto 等 broker，通过 client.connect('$MQTT_BROKER_URL') 连接。安全端点需启用 TLS（例如 client.tls_set()）。若与其他技能（如数据库）组合，可在成功后发布数据：例如插入数据库后执行 client.publish('db/updates', json.dumps(data))。
错误处理
显式处理常见错误。连接问题可捕获 ConnectionRefusedError 并以指数退避重试，例如 time.sleep(5)。发布失败时检查返回码（例如 client.publish() 返回值大于 0 时记录日志并重试）。订阅错误可能涉及无效主题，可用 if '/' not in topic: raise ValueError('Invalid topic') 校验。使用回调处理消息错误，例如在 on_message 处理器中：if error: print('Error: ', error)。始终在 finally 块中用 client.disconnect() 清理。
具体使用示例
示例 1：发布传感器数据
向 MQTT 主题发布温度读数，先设置环境变量：export MQTT_BROKER_URL='broker.example.com'。然后在代码中：
client = mqtt.Client()
client.connect(os.environ['MQTT_BROKER_URL'])
client.publish('sensors/temperature', '25.0', qos=1)
client.disconnect()
这会向 broker 发送消息，用于 IoT 仪表盘更新。
示例 2：订阅设备命令
订阅并响应命令：
def on_message(client, userdata, message):
print(f"Received: {message.payload.decode()}")
client = mqtt.Client()
client.on_message = on_message
client.connect(os.environ['MQTT_BROKER_URL'])
client.subscribe('commands/device1', qos=1)
client.loop_forever()
这会让客户端持续监听命令，以控制 IoT 设备。
图谱关系
- 相关集群：iot
- 相关标签：iot、mqtt
- 连接：可与其他 iot 技能集成，例如用于数据处理或设备管理。