这是最新(主)开发分支的文档。如果您正在查找以前版本的文档,使用左侧的下拉菜单选择所需的版本。

MQTT AT 命令集

AT+MQTTUSERCFG:设置 MQTT 用户属性

查询命令

功能:

查询已设置的 MQTT 用户属性

命令:

AT+MQTTUSERCFG?

响应:

+MQTTUSERCFG:<LinkID>,<scheme>,<"client_id">,<"username">,<"password">,<cert_key_ID>,<CA_ID>,<"path">

OK

设置命令

功能:

配置 MQTT 用户属性

命令:

AT+MQTTUSERCFG=<LinkID>,<scheme>,<"client_id">,<"username">,<"password">,<cert_key_ID>,<CA_ID>,<"path">

响应:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <scheme>

    • 1: MQTT over TCP;

    • 2: MQTT over TLS(不校验证书);

    • 3: MQTT over TLS(校验 server 证书);

    • 4: MQTT over TLS(提供 client 证书);

    • 5: MQTT over TLS(校验 server 证书并且提供 client 证书);

    • 6: MQTT over WebSocket(基于 TCP);

    • 7: MQTT over WebSocket Secure(基于 TLS,不校验证书);

    • 8: MQTT over WebSocket Secure(基于 TLS,校验 server 证书);

    • 9: MQTT over WebSocket Secure(基于 TLS,提供 client 证书);

    • 10: MQTT over WebSocket Secure(基于 TLS,校验 server 证书并且提供 client 证书)。

  • <client_id>:MQTT 客户端 ID,最大长度:256 字节。

  • <username>:用户名,用于登陆 MQTT broker,最大长度:64 字节。

  • <password>:密码,用于登陆 MQTT broker,最大长度:64 字节。

  • <cert_key_ID>:证书 ID,目前 w800-AT 仅支持一套 cert 证书,参数为 0。

  • <CA_ID>:CA ID,目前 w800-AT 仅支持一套 CA 证书,参数为 0。

  • <path>:资源路径,最大长度:32 字节。

说明

  • 每条 AT 命令的总长度不能超过 256 字节。

  • 如果 <scheme> 配置为 3、5、8、10,为了校验服务器的证书有效期,请在发送 AT+MQTTCONN 命令前确保已获取到当前时间。(您可以发送 AT+CIPSNTPCFG 命令来配置 SNTP,获取当前时间,发送 AT+CIPSNTPTIME? 命令查询当前时间。若您在局域网,或不具备连接 NTP 服务器的环境,可以修改 wm_mbedtls_config.h 中 MBEDTLS_HAVE_TIME_DATE 选项,关闭证书有效期校验)

AT+MQTTLONGCLIENTID:设置 MQTT 客户端 ID

设置命令

功能:

设置 MQTT 客户端 ID

命令:

AT+MQTTLONGCLIENTID=<LinkID>,<length>

响应:

OK

>

上述响应表示 AT 已准备好接收 MQTT 客户端 ID,此时您可以输入客户端 ID,当 AT 接收到的客户端 ID 长度达到 <length> 后,返回:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <length>:MQTT 客户端 ID 长度。范围:[1,1024]。

说明

AT+MQTTLONGUSERNAME:设置 MQTT 登陆用户名

设置命令

功能:

设置 MQTT 用户名

命令:

AT+MQTTLONGUSERNAME=<LinkID>,<length>

响应:

OK

>

上述响应表示 AT 已准备好接收 MQTT 用户名,此时您可以输入 MQTT 用户名,当 AT 接收到的 MQTT 用户名长度达到 <length> 后,返回:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <length>:MQTT 用户名长度。范围:[1,1024]。

说明

AT+MQTTLONGPASSWORD:设置 MQTT 登陆密码

设置命令

功能:

设置 MQTT 密码

命令:

AT+MQTTLONGPASSWORD=<LinkID>,<length>

响应:

OK

>

上述响应表示 AT 已准备好接收 MQTT 密码,此时您可以输入 MQTT 密码,当 AT 接收到的 MQTT 密码长度达到 <length> 后,返回:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <length>:MQTT 密码长度。范围:[1,1024]。

说明

AT+MQTTCONNCFG:设置 MQTT 连接属性

查询命令

功能:

查询已设置的 MQTT 连接属性

命令:

AT+MQTTCONNCFG?

响应:

+MQTTCONNCFG:<LinkID>,<keepalive>,<disable_clean_session>,<"lwt_topic">,<"lwt_msg">,<lwt_qos>,<lwt_retain>

OK

设置命令

功能:

设置 MQTT 连接属性

命令:

AT+MQTTCONNCFG=<LinkID>,<keepalive>,<disable_clean_session>,<"lwt_topic">,<"lwt_msg">,<lwt_qos>,<lwt_retain>

响应:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <keepalive>:MQTT ping 超时时间,单位:秒。范围:[0,7200]。默认值:0,会被强制改为 120 秒。

  • <disable_clean_session>:设置 MQTT 清理会话标志,有关该参数的更多信息请参考 MQTT 3.1.1 协议中的 Clean Session 章节。

    • 0: 使能清理会话

    • 1: 禁用清理会话

  • <lwt_topic>:遗嘱 topic,最大长度:128 字节。

  • <lwt_msg>:遗嘱 message,最大长度:128 字节。

  • <lwt_qos>:遗嘱 QoS,参数可选 0、1、2,默认值:0。

  • <lwt_retain>:遗嘱 retain,参数可选 0 或 1,默认值:0。

AT+MQTTALPN:设置 MQTT 应用层协议协商(ALPN)

查询命令

功能:

查询已设置的 MQTT 应用层协议协商(ALPN)

命令:

AT+MQTTALPN?

响应:

+MQTTALPN:<LinkID>,<"alpn">
+MQTTALPN:<LinkID>,<"alpn">
+MQTTALPN:<LinkID>,<"alpn">
+MQTTALPN:<LinkID>,<"alpn">
+MQTTALPN:<LinkID>,<"alpn">

OK

设置命令

功能:

设置 MQTT 应用层协议协商(ALPN)

命令:

AT+MQTTALPN=<LinkID>,<alpn_counts>[,<"alpn">][,<"alpn">][,<"alpn">]

响应:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <alpn_counts>:<”alpn”> 参数个数。范围:[0,5]。

    • 0:清除 MQTT ALPN 配置

    • [1,5]:设置 MQTT ALPN 配置

  • <”alpn”>:字符串参数,表示 ClientHello 中的 ALPN,用户可以发送多个 ALPN 字段到服务器。

说明

  • 整条 AT 命令长度应小于 256 字节。

  • 只有在 MQTT 基于 TLS 或 WSS 时,MQTT ALPN 字段才会生效。

  • 应在设置 AT+MQTTUSERCFG 后再使用 AT+MQTTALPN

示例

AT+CWMODE=1
AT+CWJAP="ssid","password"
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com","ntp2.aliyun.com"
AT+MQTTUSERCFG=0,5,"W800","WinnerMicro","1234567890",0,0,""
AT+MQTTALPN=0,2,"mqtt-ca.cn","mqtt-ca.us"
AT+MQTTCONN=0,"192.168.200.2",8883,1

AT+MQTTCONN:连接 MQTT Broker

查询命令

功能:

查询 w800 设备已连接的 MQTT broker

命令:

AT+MQTTCONN?

响应:

+MQTTCONN:<LinkID>,<state>,<scheme><"host">,<port>,<"path">,<reconnect>
OK

设置命令

功能:

连接 MQTT Broker

命令:

AT+MQTTCONN=<LinkID>,<"host">,<port>,<reconnect>

响应:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <host>:MQTT broker 域名,最大长度:128 字节,不支持设置空字符串。

  • <port>:MQTT broker 端口,最大端口:65535。

  • <path>:资源路径,最大长度:32 字节。

  • <reconnect>

    • 0: MQTT 不自动重连。如果 MQTT 建立连接后又断开,则无法再次使用本命令重新建立连接,您需要先发送 AT+MQTTCLEAN=0 命令清理信息,重新配置参数,再建立新的连接。

    • 1: MQTT 自动重连,会消耗较多的内存资源。

  • <state>:MQTT 状态:

    • 0: MQTT 未初始化;

    • 1: 已设置 AT+MQTTUSERCFG

    • 2: 已设置 AT+MQTTCONNCFG

    • 3: 连接已断开;

    • 4: 已建立连接;

    • 5: 已连接,但未订阅 topic;

    • 6: 已连接,已订阅过 topic。

  • <scheme>

    • 1: MQTT over TCP;

    • 2: MQTT over TLS(不校验证书);

    • 3: MQTT over TLS(校验 server 证书);

    • 4: MQTT over TLS(提供 client 证书);

    • 5: MQTT over TLS(校验 server 证书并且提供 client 证书);

    • 6: MQTT over WebSocket(基于 TCP);

    • 7: MQTT over WebSocket Secure(基于 TLS,不校验证书);

    • 8: MQTT over WebSocket Secure(基于 TLS,校验 server 证书);

    • 9: MQTT over WebSocket Secure(基于 TLS,提供 client 证书);

    • 10: MQTT over WebSocket Secure(基于 TLS,校验 server 证书并且提供 client 证书)。

AT+MQTTPUB:发布 MQTT 消息(字符串)

设置命令

功能:

通过 topic 发布 MQTT 字符串 消息。如果您发布消息的数据量相对较多,已经超过了单条 AT 指令的长度阈值 256 字节,请使用 AT+MQTTPUBRAW 命令。

命令:

AT+MQTTPUB=<LinkID>,<"topic">,<"data">,<qos>,<retain>

响应:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <topic>:MQTT topic,最大长度:128 字节,不支持设置空字符串。

  • <data>:MQTT 字符串消息。

  • <qos>:发布消息的 QoS,参数可选 0、1、或 2,默认值:0。

  • <retain>:发布 retain。

说明

  • 每条 AT 命令的总长度不能超过 256 字节。

  • 本命令不能发送数据 \0,若需要发送该数据,请使用 AT+MQTTPUBRAW 命令。

示例

AT+CWMODE=1
AT+CWJAP="ssid","password"
AT+MQTTUSERCFG=0,1,"W800","WinnerMicro","1234567890",0,0,""
AT+MQTTCONN=0,"192.168.10.234",1883,0
AT+MQTTPUB=0,"topic","\"{\"timestamp\":\"20201121085253\"}\"",0,0  // 发送此命令时,请注意特殊字符是否需要转义。

AT+MQTTPUBRAW:发布长 MQTT 消息

设置命令

功能:

通过 topic 发布长 MQTT 消息。如果您发布消息的数据量相对较少,不大于单条 AT 指令的长度阈值 256 字节,也可以使用 AT+MQTTPUB 命令。

命令:

AT+MQTTPUBRAW=<LinkID>,<"topic">,<length>,<qos>,<retain>

响应:

OK
>

符号 > 表示 AT 准备好接收串口数据,此时您可以输入数据,当数据长度达到参数 <length> 的值时,数据传输开始。

若传输成功,则 AT 返回:

+MQTTPUB:OK

若传输失败,则 AT 返回:

+MQTTPUB:FAIL

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <topic>:MQTT topic,最大长度:128 字节,不支持设置空字符串。

  • <length>:MQTT 消息长度,w800 设备的最大长度受到可利用内存的限制,最大不超过 5760 字节。

  • <qos>:发布消息的 QoS,参数可选 0、1、或 2,默认值:0。

  • <retain>:发布 retain。

AT+MQTTSUB:订阅 MQTT Topic

查询命令

功能:

查询已订阅的 topic

命令:

AT+MQTTSUB?

响应:

+MQTTSUB:<LinkID>,<state>,<"topic1">,<qos>
+MQTTSUB:<LinkID>,<state>,<"topic2">,<qos>
+MQTTSUB:<LinkID>,<state>,<"topic3">,<qos>
...
OK

设置命令

功能:

订阅指定 MQTT topic 的指定 QoS,支持订阅多个 topic

命令:

AT+MQTTSUB=<LinkID>,<"topic">,<qos>

响应:

OK

当 AT 接收到已订阅的 topic 的 MQTT 消息时,返回:

+MQTTSUBRECV:<LinkID>,<"topic">,<data_length>,data

若已订阅过该 topic,则返回:

ALREADY SUBSCRIBE

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <state>:MQTT 状态:

    • 0: MQTT 未初始化;

    • 1: 已设置 AT+MQTTUSERCFG

    • 2: 已设置 AT+MQTTCONNCFG

    • 3: 连接已断开;

    • 4: 已建立连接;

    • 5: 已连接,但未订阅 topic;

    • 6: 已连接,已订阅过 MQTT topic。

  • <topic>:订阅的 topic,不支持设置空字符串。

  • <qos>:订阅的 QoS。

说明

  • 最多可以订阅10个主题,订阅满了之后会提示: ALREADY FULL SUBSCRIBE

AT+MQTTUNSUB:取消订阅 MQTT Topic

设置命令

功能:

客户端取消订阅指定 topic,可多次调用本命令,以取消订阅不同的 topic。

命令:

AT+MQTTUNSUB=<LinkID>,<"topic">

响应:

OK

若未订阅过该 topic,则返回:

NO UNSUBSCRIBE

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

  • <topic>:MQTT topic,最大长度:128 字节,不支持设置空字符串。

AT+MQTTCLEAN:断开 MQTT 连接

设置命令

功能:

断开 MQTT 连接,释放资源。

命令:

AT+MQTTCLEAN=<LinkID>

响应:

OK

参数

  • <LinkID>:当前仅支持 link ID 0。

MQTT AT 说明

  • 一般来说,AT MQTT 命令都会在 10 秒内响应,但 AT+MQTTCONN 命令除外。例如,如果路由器不能上网,命令 AT+MQTTPUB 会在 10 秒内响应,但 AT+MQTTCONN 命令在网络环境不好的情况下,可能需要更多的时间用来重传数据包。

  • 如果 AT+MQTTCONN 是基于 TLS 连接,每个数据包的超时时间为 10 秒,则总超时时间会根据握手数据包的数量而变得更长。

  • 当 MQTT 连接断开时,会提示 +MQTTDISCONNECTED:<LinkID> 消息。

  • 当 MQTT 连接建立时,会提示 +MQTTCONNECTED:<LinkID>,<scheme>,<"host">,port,<"path">,<reconnect> 消息。