查看“︁AT模块 6: MQTT AT 命令（MQTT AT Commands）”︁的源代码

= MQTT AT 命令 =

== 命令列表 ==

{| class="wikitable"
! 命令
! 描述
|-
| <code>AT+MQTTUSERCFG</code>
| 获取/设置 MQTT 用户配置
|-
| <code>AT+MQTTCLIENTID</code>
| 获取/设置 MQTT Client ID
|-
| <code>AT+MQTTUSERNAME</code>
| 获取/设置 MQTT 用户名
|-
| <code>AT+MQTTPASSWORD</code>
| 获取/设置 MQTT 密码
|-
| <code>AT+MQTTCONNCFG</code>
| 获取/设置 MQTT 连接配置
|-
| <code>AT+MQTTALPN</code>
| 获取/设置 MQTT 应用层协议协商 (ALPN)
|-
| <code>AT+MQTTSNI</code>
| 获取/设置 MQTT 服务器名称指示 (SNI)
|-
| <code>AT+MQTTCONN</code>
| 连接到 MQTT Broker
|-
| <code>AT+MQTTPUB</code>
| 发布字符串格式的 MQTT 消息
|-
| <code>AT+MQTTPUBRAW</code>
| 发布长 MQTT 消息
|-
| <code>AT+MQTTSUB</code>
| 订阅 MQTT 主题
|-
| <code>AT+MQTTUNSUB</code>
| 取消订阅 MQTT 主题
|-
| <code>AT+MQTTCLEAN</code>
| 关闭 MQTT 连接
|}

== MQTT AT 命令详细说明 ==

=== AT+MQTTUSERCFG ===

获取/设置 MQTT 用户配置。

==== 查询命令 ====

查询 MQTT 用户配置。

'''命令:'''

<pre>
AT+MQTTUSERCFG?
</pre>

'''响应:'''

<pre>
+MQTTUSERCFG:<LinkID>,<scheme>,<"client_id">,<"username">,<"password">,<"cert_file">,<"key_file">,<"ca_file">

OK
</pre>

==== 设置命令 ====

设置 MQTT 用户配置。

'''命令:'''

<pre>
AT+MQTTUSERCFG=<LinkID>,<scheme>,<"client_id">,<"username">,<"password">[,<"cert_file">][,<"key_file">][,<"ca_file">]
</pre>

'''响应:'''

<pre>
OK
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<scheme>''':

   * 0: MQTT over TCP。
   * 1: MQTT over TLS (不验证证书)。
   * 2: MQTT over TLS (验证服务器证书)。
   * 3: MQTT over TLS (提供客户端证书)。
   * 4: MQTT over TLS (验证服务器证书并提供客户端证书)。

* '''<client_id>''': MQTT Client ID。最大长度: 23 字节。

* '''<username>''': 登录 MQTT broker 的用户名。最大长度: 128 字节。

* '''<password>''': 登录 MQTT broker 的密码。最大长度: 128 字节。

* '''<"cert_file">''': 证书文件名。

* '''<"key_file">''': 私钥文件名。

* '''<"ca_file">''': 客户端用于验证服务器的 CA 文件名。

==== 注意事项 ====

* 整个 AT 命令的长度应小于 256 字节。

* 如果 <scheme> 配置为 3、5、8 或 10,为了检查服务器证书有效期,请确保在发送 AT+MQTTCONN 命令之前 BLC7X4x 已获取当前时间。(可以发送 AT+CIPSNTPCFG 命令配置 SNTP 并获取当前时间,发送 AT+CIPSNPTIME? 命令查询当前时间。)

---

=== AT+MQTTCLIENTID ===

获取/设置 MQTT Client ID。

==== 查询命令 ====

查询 MQTT Client ID。

'''命令:'''

<pre>
AT+MQTTCLIENTID?
</pre>

'''响应:'''

<pre>
+MQTTCLIENTID:<LinkID>,<"client_id">

OK
</pre>

==== 注意事项 ====

* 查询命令的最大长度不超过 128 字节(受 AT 长度限制)

==== 设置命令 ====

设置 MQTT Client ID。

'''命令:'''

<pre>
AT+MQTTLONGCLIENTID=<LinkID>,<length>
</pre>

'''响应:'''

<pre>
OK

>
</pre>

此响应表示 AT 已准备好接收 MQTT Client ID。您应该输入 Client ID,当 Client ID 长度达到 <length> 值时,系统返回:

<pre>
OK
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<length>''': MQTT Client ID 长度。范围: [1,23]。

==== 注意事项 ====

* AT+MQTTUSERCFG 命令也可以设置 MQTT Client ID。这两个命令的区别包括:

    * 可以使用 AT+MQTTLONGCLIENTID 设置较长的 Client ID,因为 AT+MQTTUSERCFG 命令的长度有限制。

    * 应该在设置 AT+MQTTUSERCFG 命令后设置 AT+MQTTLONGCLIENTID。

---

=== AT+MQTTUSERNAME ===

获取/设置 MQTT 用户名。

==== 查询命令 ====

查询 MQTT 用户名。

'''命令:'''

<pre>
AT+MQTTUSERNAME?
</pre>

'''响应:'''

<pre>
+MQTTUSERNAME:<LinkID>,<"user_name">

OK
</pre>

==== 注意事项 ====

* 查询命令的最大长度不超过 128 字节(受 AT 长度限制)

==== 设置命令 ====

设置 MQTT 用户名。

'''命令:'''

<pre>
AT+MQTTUSERNAME=<LinkID>,<length>
</pre>

'''响应:'''

<pre>
OK

>
</pre>

此响应表示 AT 已准备好接收 MQTT 用户名。您应该输入 MQTT 用户名,当 MQTT 用户名长度达到 <length> 值时,系统返回:

<pre>
OK
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<length>''': MQTT 用户名长度。范围: [1,128]。

==== 注意事项 ====

* AT+MQTTUSERCFG 命令也可以设置 MQTT 用户名。这两个命令的区别包括:

    * 可以使用 AT+MQTTLONGUSERNAME 设置较长的用户名,因为 AT+MQTTUSERCFG 命令的长度有限制。

    * 应该在设置 AT+MQTTUSERCFG 命令后设置 AT+MQTTLONGUSERNAME。

---

=== AT+MQTTPASSWORD ===

获取/设置 MQTT 密码。

==== 查询命令 ====

查询 MQTT 密码。

'''命令:'''

<pre>
AT+MQTTPASSWORD?
</pre>

'''响应:'''

<pre>
+MQTTPASSWORD:<LinkID>,<"password">

OK
</pre>

==== 注意事项 ====

* 查询命令的最大长度不超过 128 字节(受 AT 长度限制)

==== 设置命令 ====

设置 MQTT 密码。

'''命令:'''

<pre>
AT+MQTTPASSWORD=<LinkID>,<length>
</pre>

'''响应:'''

<pre>
OK

>
</pre>

此响应表示 AT 已准备好接收 MQTT 密码。您应该输入 MQTT 密码,当 MQTT 密码长度达到 <length> 值时,系统返回:

<pre>
OK
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<length>''': MQTT 密码长度。范围: [1,128]。

==== 注意事项 ====

* AT+MQTTUSERCFG 命令也可以设置 MQTT 密码。这两个命令的区别包括:

    * 可以使用 AT+MQTTLONGPASSWORD 设置较长的密码,因为 AT+MQTTUSERCFG 命令的长度有限制。

    * 应该在设置 AT+MQTTUSERCFG 命令后设置 AT+MQTTLONGPASSWORD。

---

=== AT+MQTTCONNCFG ===

获取/设置 MQTT 连接配置。

==== 查询命令 ====

查询 MQTT 连接配置。

'''命令:'''

<pre>
AT+MQTTCONNCFG?
</pre>

'''响应:'''

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

OK
</pre>

==== 设置命令 ====

设置 MQTT 连接配置。

'''命令:'''

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

'''响应:'''

<pre>
OK
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

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

* '''<disable_clean_session>''': 设置 MQTT clean session。关于此参数的更多详细信息,请参阅 MQTT Version 3.1.1 中的 Clean Session 章节。

   * 0: 启用 clean session。
   * 1: 禁用 clean session。

* '''<lwt_topic>''': LWT (Last Will and Testament) 消息主题。最大长度: 128 字节。

* '''<lwt_msg>''': LWT 消息。最大长度: 128 字节。

* '''<lwt_qos>''': LWT QoS,可以设置为 0、1 或 2。默认值: 0。

* '''<lwt_retain>''': LWT retain,可以设置为 0 或 1。默认值: 0。

---

=== AT+MQTTALPN ===

获取/设置 MQTT 应用层协议协商 (ALPN)。

==== 查询命令 ====

查询 MQTT 应用层协议协商 (ALPN)。

'''命令:'''

<pre>
AT+MQTTALPN?
</pre>

'''响应:'''

<pre>
+MQTTALPN:<LinkID>[,<"alpn">][,<"alpn">][,<"alpn">]

OK
</pre>

==== 设置命令 ====

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

'''命令:'''

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

'''响应:'''

<pre>
OK
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<alpn_counts>''': <"alpn"> 参数的数量。范围: [0,5]。

   * 0: 清除 MQTT ALPN 配置。
   * [1,5]: 设置 MQTT ALPN 配置。

* '''<"alpn">''': 可以在 ClientHello 中向服务器发送多个 ALPN。

==== 注意事项 ====

* 整个 AT 命令的长度应小于 256 字节。

* MQTT ALPN 仅在 MQTT 连接基于 TLS 或 WSS 时才有效。

* 应该在设置 AT+MQTTUSERCFG 命令后设置 AT+MQTTALPN。

==== 示例 ====

<pre>
AT+CWMODE=1

AT+CWJAP="ssid","password"

AT+CIPSNTPCFG=1,-5,"0.pool.ntp.org","time.google.com"

AT+MQTTUSERCFG=0,4,"Bflb","bl","123456789","client_1.crt","client_1.key","ca_1.crt"

AT+MQTTALPN=0,2,"mqtt-ca.cn","mqtt-ca.us"

AT+MQTTCONN=0,"192.168.31.112",8883,1
</pre>

---

=== AT+MQTTSNI ===

获取/设置 MQTT 服务器名称指示 (SNI)。

==== 查询命令 ====

查询 MQTT 服务器名称指示 (SNI)。

'''命令:'''

<pre>
AT+MQTTSNI?
</pre>

'''响应:'''

<pre>
+MQTTSNI:<LinkID>,<"sni">

OK
</pre>

==== 设置命令 ====

设置 MQTT 服务器名称指示 (SNI)。

'''命令:'''

<pre>
AT+MQTTSNI=<LinkID>,<"sni">
</pre>

'''响应:'''

<pre>
OK
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<"sni">''': MQTT 服务器名称指示。可以在 ClientHello 中向服务器发送。

==== 注意事项 ====

* 整个 AT 命令的长度应小于 256 字节。

* MQTT SNI 仅在 MQTT 连接基于 TLS 或 WSS 时才有效。

* 应该在设置 AT+MQTTUSERCFG 命令后设置 AT+MQTTSNI。

==== 示例 ====

<pre>
AT+CWMODE=1

AT+CWJAP="ssid","password"

AT+CIPSNTPCFG=1,-5,"0.pool.ntp.org","time.google.com"

AT+MQTTUSERCFG=0,4,"Bflb","bl","123456789","client_1.crt","client_1.key","ca_1.crt"

AT+MQTTSNI=0,"my_specific_prefix.iot.my_aws_region.amazonaws.com"

AT+MQTTCONN=0,"192.168.31.112",8883,1
</pre>

---

=== AT+MQTTCONN ===

连接到 MQTT Broker。

==== 查询命令 ====

查询已连接的 MQTT Broker。

'''命令:'''

<pre>
AT+MQTTCONN?
</pre>

'''响应:'''

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

OK
</pre>

==== 设置命令 ====

连接到 MQTT Broker。

'''命令:'''

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

'''响应:'''

<pre>
OK

+MQTT:CONNECTED,0
</pre>

或

<pre>
+MQTT:DISCONNECTED,0
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<"host">''': MQTT broker 域名。最大长度: 128 字节。

* '''<port>''': MQTT broker 端口。最大值: 65535。

* '''<reconnect>''':

    * 0: MQTT 不会自动重连。如果 MQTT 连接建立后断开,您无法使用此命令重新建立 MQTT 连接。请先发送 AT+MQTTCLEAN=0 命令清除 MQTT 连接,重新配置连接参数,然后建立新的 MQTT 连接。
    * 1: MQTT 将自动重连。会占用更多资源。

* '''<state>''':

    * 0: MQTT 未初始化。
    * 1: 已设置 AT+MQTTUSERCFG。
    * 2: 已设置 AT+MQTTCONNCFG。
    * 3: 连接已断开。
    * 4: 连接已建立。
    * 5: 已连接,但未订阅任何主题。
    * 6: 已连接,并已订阅 MQTT 主题。

* '''<scheme>''':

   * 0: MQTT over TCP。
   * 1: MQTT over TLS (不验证证书)。
   * 2: MQTT over TLS (验证服务器证书)。
   * 3: MQTT over TLS (提供客户端证书)。
   * 4: MQTT over TLS (验证服务器证书并提供客户端证书)。

---

=== AT+MQTTPUB ===

发布字符串格式的 MQTT 消息。

==== 设置命令 ====

'''功能:'''

以字符串格式向指定主题发布 MQTT 消息。如果您发布的数据量较大,且单条 AT 命令长度超过 256 字节阈值,请使用 AT+MQTTPUBRAW 命令。

'''命令:'''

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

'''响应:'''

<pre>
OK
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<"topic">''': MQTT 主题。最大长度: 128 字节。

* '''<"data">''': MQTT 字符串格式消息。

* '''<qos>''': 消息 QoS,可以设置为 0、1 或 2。默认值: 0。

* '''<retain>''': retain 标志。

==== 注意事项 ====

* 整个 AT 命令的长度应小于 256 字节。

* 此命令不能发送 \0 数据。如果需要发送 \0,请使用 AT+MQTTPUBRAW 命令。

==== 示例 ====

<pre>
AT+CWMODE=1

AT+CWJAP="ssid","password"

AT+CIPSNTPCFG=1,-5,"0.pool.ntp.org","time.google.com"

AT+MQTTUSERCFG=0,4,"Bflb","bl","123456789","client_1.crt","client_1.key","ca_1.crt"

AT+MQTTALPN=0,2,"mqtt-ca.cn","mqtt-ca.us"

AT+MQTTCONN=0,"192.168.31.112",8883,1

AT+MQTTPUB=0,"topic","\"{\"timestamp\":\"20201121085253\"}\"",0,0  // 发送此命令时,请注意是否需要转义特殊字符。
</pre>

---

=== AT+MQTTPUBRAW ===

发布长 MQTT 消息。

==== 设置命令 ====

'''功能:'''

向指定主题发布长 MQTT 消息。如果您发布的数据量较小,且单条 AT 命令长度不大于 256 字节阈值,也可以使用 AT+MQTTPUB 命令。

'''命令:'''

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

'''响应:'''

<pre>
OK

>
</pre>

符号 > 表示 AT 已准备好接收串口数据,您现在可以输入数据。当满足参数 <length> 确定的消息长度要求时,开始传输。

如果传输成功,AT 返回:

<pre>
SEND OK
</pre>

否则返回:

<pre>
SEND FAIL
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<"topic">''': MQTT 主题。最大长度: 128 字节。

* '''<length>''': MQTT 消息长度。最大长度受可用内存限制。

* '''<qos>''': 发布消息的 QoS,可以设置为 0、1 或 2。默认值为 0。

* '''<retain>''': retain 标志。

---

=== AT+MQTTSUB ===

订阅 MQTT 主题。

==== 查询命令 ====

查询已订阅的 MQTT 主题。

'''命令:'''

<pre>
AT+MQTTSUB?
</pre>

'''响应:'''

<pre>
+MQTTSUB:<LinkID>,<state>,<"topic1">,<qos>

+MQTTSUB:<LinkID>,<state>,<"topic2">,<qos>

+MQTTSUB:<LinkID>,<state>,<"topic3">,<qos>

...

OK
</pre>

==== 设置命令 ====

'''功能:'''

使用指定 QoS 订阅指定的 MQTT 主题。支持订阅多个主题。

'''命令:'''

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

'''响应:'''

<pre>
OK
</pre>

如果该主题之前已订阅,将提示:

<pre>
+MQTTSUB,ALREADY_SUBSCRIBE

OK
</pre>

当 AT 收到已订阅主题的 MQTT 消息时,将提示:

<pre>
+MQTT:SUBRECV,<LinkID>,<topic_length>,<data_length>,<"topic">,<data>
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<state>''':

    * 0: MQTT 未初始化。
    * 1: 已设置 AT+MQTTUSERCFG。
    * 2: 已设置 AT+MQTTCONNCFG。
    * 3: 连接已断开。
    * 4: 连接已建立。
    * 5: 已连接,但未订阅任何主题。
    * 6: 已连接,并已订阅 MQTT 主题。

* '''<topic>''': 已订阅的主题。

* '''<qos>''': 已订阅的 QoS。

---

=== AT+MQTTUNSUB ===

取消订阅 MQTT 主题。

==== 设置命令 ====

'''功能:'''

取消客户端对指定主题的订阅。可以多次调用此命令以取消不同主题的订阅。

'''命令:'''

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

'''响应:'''

<pre>
OK
</pre>

如果该主题之前已订阅,将提示:

<pre>
+MQTTUNSUB:NO_UNSUBSCRIBE

OK
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

* '''<topic>''': MQTT 主题。最大长度: 128 字节。

---

=== AT+MQTTCLEAN ===

关闭 MQTT 连接。

==== 设置命令 ====

'''功能:'''

关闭 MQTT 连接并释放资源。

'''命令:'''

<pre>
AT+MQTTCLEAN=<LinkID>
</pre>

'''响应:'''

<pre>
OK
</pre>

==== 参数 ====

* '''<LinkID>''': 当前仅支持链路 ID 0。

----