MQTT AT 命令集

备注

  • MQTT AT 命令集默认未启用。

  • 参考 配置 SDK (menuconfig) 进入 CONFIG AT CMD 配置，勾选 Enable MQTT 来启用 MQTT AT 命令集。

MQTT AT 错误码

MQTT AT 命令的错误码定义如下：

  • 1: 参数错误

  • 2: 内存分配失败

  • 3: 连接错误

  • 4: 断开连接错误

  • 5: 进入 TT 模式失败

  • 6: 证书套件获取失败

  • 7: 未连接

  • 8: 已连接

  • 9: 发布失败

  • 10: 订阅失败

  • 11: 取消订阅失败

  • 12: 已订阅

  • 13: 等待超时

  • 14: 线程创建失败

  • 15: 网络连接错误

AT+MQTTCFG

功能说明

配置指定连接ID的MQTT连接参数

命令格式

AT+MQTTCFG=<link_id>,<keepalive>,<cmd_timeout>,<disable_clean_session>[,<lwt_topic>,<lwt_msg>,<lwt_qos>,<lwt_retain>]

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数说明

<link_id>:

连接ID

  • 取值范围[0,3]

<keepalive>:

Ping超时时间（秒）

  • 默认值：60

<cmd_timeout>:

连接/订阅超时时间（秒）

  • 默认值：60

<disable_clean_session>:

清理会话选项

  • 0: 启用清理会话

  • 1: 禁用清理会话

<lwt_topic>:

LWT消息主题

<lwt_msg>:

LWT消息

<lwt_qos>:

LWT消息QoS等级

  • 取值范围[0,2]

  • 默认值：0

<lwt_retain>:

LWT消息保留选项

  • 取值范围[0,1]

  • 默认值：0

错误代码

  • 1: 参数错误

  • 2: 内存分配失败

  • 8: 已连接代理服务器

应用示例

配置 LWT 消息：

AT+MQTTCFG=0,20,60,0,topic/lwt,This is a lwt message,0,0

OK

未配置 LWT 消息：

AT+MQTTCFG=0,20,60,0

OK

AT+MQTTCONN

功能说明

连接MQTT代理服务器

命令格式

AT+MQTTCONN=<link_id>,<host>,[<port>],<client_id>,<conn_type>[,<cert_index>,<username>,<password>]

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

AT 消息

连接成功，会有如下提示消息：

[$][MQTT][EVENT]:linkid:<link_id>, connected

连接失败或者异常，会有如下提示消息：

[$][MQTT][EVENT]:linkid:<link_id>, ERROR:<err_no>

备注

err_no 具体定义参考 MQTT 统一错误码。

参数说明

<link_id>:

连接ID

  • 取值范围[0,3]

<host>:

代理服务器域名

  • 最大长度：128字节

<port>:

代理服务器端口

  • 取值范围[0,65535]

  • 默认值：0

  • 0: MQTT默认端口为1883, MQTTS默认端口为8883

<client_id>:

客户端ID

  • 最大长度：256字节

<conn_type>:

连接类型

  • 1: MQTT

  • 2: MQTTS（不校验证书）

  • 3: MQTTS（用CA证书验证服务器证书）

  • 4: MQTTS（提供客户端证书给服务器验证）

  • 5: MQTTS（双向认证，3和4的合集）

<cert_index>:

安全证书套件索引，参考 AT 安全证书

  • 取值范围[1-10]

  • 仅<conn_type>是3-5时需要

<username>:

登陆用户名

  • 最大长度：64字节

<password>:

登陆密码

  • 最大长度：64字节

错误代码

  • 1: 参数错误

  • 2: 内存分配失败

  • 3: 连接错误

  • 8: 已连接代理服务器

  • 14: 主任务创建失败

应用示例

使用登录用户名为 rs，密码为 2345678，连接broker.hivemq.com的8883端口，并用1号证书套件的CA证书验证服务器：

AT+MQTTCONN=0,broker.hivemq.com,8883,publisher,3,1,rs,12345678

OK
[$][MQTT][EVENT]:linkid:0, connected

不使用登录用户名和密码，连接broker.hivemq.com的1883端口:

AT+MQTTCONN=0,broker.hivemq.com,1883,publisher,1

OK
[$][MQTT][EVENT]:linkid:0, connected

使用默认端口连接：

AT+MQTTCONN=0,broker.hivemq.com,,publisher,1

OK
[$][MQTT][EVENT]:linkid:0, connected

AT+MQTTDISCONN

功能说明

关闭指定MQTT连接，并释放资源

命令格式

AT+MQTTDISCONN=<link_id>

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

参数说明

<link_id>:

连接ID

  • 取值范围[0,3]

错误代码

  • 1: 参数错误

  • 4: 断开连接失败

应用示例

关闭连接：

AT+MQTTDISCONN=0

OK

AT+MQTTSUB

功能说明

订阅MQTT主题，最多支持订阅5个主题

命令格式

AT+MQTTSUB=<link_id>,<topic>,<qos>

响应格式

成功响应：

OK

如果已订阅过该主题，将返回：

OK

ALREADY SUBCRIBE

错误响应：

ERROR:<error_no>

AT 消息

订阅成功时，会有如下提示消息：

[$][MQTT][EVENT]:linkid:<link_id>, subscribed

收到订阅主题的MQTT消息时，会有如下提示消息：

[$][MQTT][DATA][<link_id>][<topic>][<消息ID>][<消息长度>]:<消息>

遇到异常，会有如下提示消息

[$][MQTT][EVENT]:linkid:<link_id>, ERROR:<err_no>

备注

err_no 具体定义参考 MQTT 统一错误码。

参数说明

<link_id>:

连接ID

  • 取值范围[0,3]

<topic>:

待订阅的主题

  • 最大长度：128字节

<qos>:

待订阅主题的QoS

  • 取值范围[0,2]

错误代码

  • 1: 参数错误

  • 2: 内存分配失败

  • 7: 连接不存在

  • 10: 订阅失败

  • 13: 超时

应用示例

订阅主题LASS/Test/Pm25Ameba/#：

AT+MQTTSUB=0,LASS/Test/Pm25Ameba/#,1

OK
[$][MQTT][EVENT]:linkid:0, subscribed

接收到订阅主题的消息：

[$][MQTT][DATA][0][LASS/Test/Pm25Ameba/FT1_018][102][14]:This is a test

AT+MQTTUNSUB

功能说明

取消订阅指定主题

命令格式

AT+MQTTUNSUB=<link_id>,<topic>

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

AT 消息

取消订阅成功时，会有如下提示消息：

[$][MQTT][EVENT]:linkid:<link_id>, unsubscribed

遇到异常，会有如下提示消息

[$][MQTT][EVENT]:linkid:<link_id>, ERROR:<err_no>

备注

err_no具体定义参考 MQTT统一错误码

参数说明

<link_id>:

连接ID

  • 取值范围[0,3]

<topic>:

需要取消订阅的主题

  • 最大长度：128字节

错误代码

  • 1: 参数错误

  • 7: 连接不存在

  • 11: 取消订阅失败

  • 13: 超时

应用示例

取消订阅主题LASS/Test/Pm25Ameba/#：

AT+MQTTUNSUB=0,LASS/Test/Pm25Ameba/#

OK
[$][MQTT][EVENT]:linkid:0, unsubscribed

AT+MQTTPUB

功能说明

向特定主题发布消息

命令格式

AT+MQTTPUB=<link_id>,<msg_id>,<topic>,<msg>,<qos>,<retain>

响应格式

成功响应：

OK

错误响应：

ERROR:<error_no>

AT 消息

发布成功时，会有如下提示消息：

[$][MQTT][EVENT]:linkid:<link_id>, published

遇到异常，会有如下提示消息

[$][MQTT][EVENT]:linkid:<link_id>, ERROR:<err_no>

备注

err_no 具体定义参考 MQTT 统一错误码。

参数说明

<link_id>:

连接ID

  • 取值范围[0,3]

<msg_id>:

消息ID

  • 取值范围[0,65535]

<topic>:

目标主题

  • 最大长度：128字节

  • 建议填写之前已订阅的主题

<msg>:

消息内容

  • 最大长度：512字节

<qos>:

消息QoS等级

  • 可设置为0，1，2

  • 默认值：0

<retain>:

保留值

  • 可设置为0或1

  • 默认值：0

错误代码

  • 1: 参数错误

  • 2: 内存分配失败

  • 7: 连接不存在

  • 9: 发布失败

  • 13: 超时

应用示例

向主题LASS/Test/Pm25Ameba/FT1_018发布消息：

AT+MQTTPUB=0,1,LASS/Test/Pm25Ameba/FT1_018,This is a test,1,1

OK
[$][MQTT][EVENT]:linkid:0, published

AT+MQTTPUBRAW

功能说明

用 透传（TT）模式 向特定主题发布指定长度的消息

备注

该命令仅支持在 主控控制模式 下使用。

命令格式

AT+MQTTPUBRAW=<link_id>,<msg_id>,<topic>,<length>,<qos>,<retain>

响应格式

成功响应：

OK
[$][MQTT][EVENT]:linkid:<link_id>, published

错误响应：

ERROR:<error_no>

参数说明

<link_id>:

连接ID

  • 取值范围[0,3]

<msg_id>:

消息ID

  • 取值范围[0,65535]

<topic>:

目标主题

  • 最大长度：128字节

  • 建议填写之前已订阅的主题

<length>:

消息长度（字节）

  • 最大长度：10240字节

<qos>:

消息QoS等级

  • 可设置为0，1，2

  • 默认值：0

<retain>:

保留值

  • 可设置为0或1

  • 默认值：0

错误代码

  • 1: 参数错误

  • 2: 内存分配失败

  • 5: 进入TT模式失败

  • 7: 连接不存在

  • 9: 发布失败

  • 13: 超时

应用示例

发送14个字节的文本消息：

AT+MQTTPUBRAW=0,2,LASS/Test/Pm25Ameba/FT1_018,14,1,1
>>>
This is a test

OK
[$][MQTT][EVENT]:linkid:0, published

AT+MQTTRESET

功能说明

重置所有MQTT实例，并释放资源

命令格式

AT+MQTTRESET

响应格式

成功响应：

OK

备注

如果存在正在运行的MQTT实例，将立即断开连接，并释放所有相关资源。

应用示例

MQTT重置：

AT+MQTTRESET
OK

AT+MQTTQUERY

功能说明

查询指定连接的状态及配置信息

命令格式

AT+MQTTQUERY=<link_id>

响应格式

成功响应：

link_id: <连接ID>
state: <连接状态，0：未连接，1：已连接>
conn_type: <连接类型>
host: <代理服务器域名>
port: <代理服务器端口>
cliend_id: <客户端ID>
username: <登陆用户名>
password: <登陆密码>
cmd_timeout: <连接/订阅超时时间（秒）>
keepalive: <Ping超时时间（秒）>
disable_clean_session: <清理会话选项>
LWT: <LWT消息标志>
lwt_qos: <LWT消息QoS等级>
lwt_retain: <LWT消息保留选项>
lwt_topic: <LWT消息主题>
lwt_msg: <LWT消息>

OK

错误响应：

ERROR:<error_no>

参数说明

<link_id>:

连接ID

  • 取值范围[0,3]

错误代码

  • 1: 参数错误

应用示例

查询连接ID 0的相关信息：

AT+MQTTQUERY=0

link_id: 0
state: 1
conn_type: 1
host: broker.hivemq.com
port: 1883
client_id: publisher
username: rs
password: 12345678
cmd_timeout: 60
keepalive: 20
disable_clean_session: 0
LWT: 1
lwt_qos: 0
lwt_retain: 0
lwt_topic: topic/lwt
lwt_message: This is a lwt message

OK

AT+MQTTSUBQUERY

功能说明

列出所有已订阅的主题

命令格式

AT+MQTTSUBQUERY=<link_id>

响应格式

成功响应：

link_id: <link_id>
state: <isconnected>
topic: <topic1>, qos: <topic1_qos>
topic: <topic2>, qos: <topic2_qos>
...

OK

错误响应：

ERROR:<error_no>

参数说明

<link_id>:

连接ID

  • 取值范围[0,3]

错误代码

  • 1: 参数错误

应用示例

列出连接ID 0所有已订阅的主题：

AT+MQTTSUBQUERY=0

link_id: 0
state: 1
topic: LASS/Test/Pm25Ameba/#, qos: 1

OK