AT模块 6: MQTT AT 命令（MQTT AT Commands）

来自Bouffalo Lab Docs
张良​（留言 | 贡献）2026年1月12日 (一) 02:18的版本 （创建页面，内容为“= 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 应用层…”）
(差异) ←上一版本 | 最后版本 (差异) | 下一版本→ (差异)
跳转到导航 跳转到搜索

MQTT AT 命令

命令列表

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

MQTT AT 命令详细说明

AT+MQTTUSERCFG

获取/设置 MQTT 用户配置。

查询命令

查询 MQTT 用户配置。

命令: 

AT+MQTTUSERCFG?

响应: 

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

OK

设置命令

设置 MQTT 用户配置。

命令: 

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

响应: 

OK

参数

  • <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。

命令: 

AT+MQTTCLIENTID?

响应: 

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

OK

注意事项

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

设置命令

设置 MQTT Client ID。

命令: 

AT+MQTTLONGCLIENTID=<LinkID>,<length>

响应: 

OK

>

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

OK

参数

  • <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 用户名。

命令: 

AT+MQTTUSERNAME?

响应: 

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

OK

注意事项

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

设置命令

设置 MQTT 用户名。

命令: 

AT+MQTTUSERNAME=<LinkID>,<length>

响应: 

OK

>

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

OK

参数

  • <LinkID>: 当前仅支持链路 ID 0。
  • <length>: MQTT 用户名长度。范围: [1,128]。

注意事项

  • AT+MQTTUSERCFG 命令也可以设置 MQTT 用户名。这两个命令的区别包括:
   * 可以使用 AT+MQTTLONGUSERNAME 设置较长的用户名,因为 AT+MQTTUSERCFG 命令的长度有限制。

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

---

AT+MQTTPASSWORD

获取/设置 MQTT 密码。

查询命令

查询 MQTT 密码。

命令: 

AT+MQTTPASSWORD?

响应: 

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

OK

注意事项

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

设置命令

设置 MQTT 密码。

命令: 

AT+MQTTPASSWORD=<LinkID>,<length>

响应: 

OK

>

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

OK

参数

  • <LinkID>: 当前仅支持链路 ID 0。
  • <length>: MQTT 密码长度。范围: [1,128]。

注意事项

  • AT+MQTTUSERCFG 命令也可以设置 MQTT 密码。这两个命令的区别包括:
   * 可以使用 AT+MQTTLONGPASSWORD 设置较长的密码,因为 AT+MQTTUSERCFG 命令的长度有限制。

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

---

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>: 当前仅支持链路 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)。

命令: 

AT+MQTTALPN?

响应: 

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

OK

设置命令

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

命令: 

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

响应: 

OK

参数

  • <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。

示例

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+MQTTSNI

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

查询命令

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

命令: 

AT+MQTTSNI?

响应: 

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

OK

设置命令

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

命令: 

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

响应: 

OK

参数

  • <LinkID>: 当前仅支持链路 ID 0。
  • <"sni">: MQTT 服务器名称指示。可以在 ClientHello 中向服务器发送。

注意事项

  • 整个 AT 命令的长度应小于 256 字节。
  • MQTT SNI 仅在 MQTT 连接基于 TLS 或 WSS 时才有效。
  • 应该在设置 AT+MQTTUSERCFG 命令后设置 AT+MQTTSNI。

示例

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

---

AT+MQTTCONN

连接到 MQTT Broker。

查询命令

查询已连接的 MQTT Broker。

命令: 

AT+MQTTCONN?

响应: 

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

OK

设置命令

连接到 MQTT Broker。

命令: 

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

响应: 

OK

+MQTT:CONNECTED,0

或 

+MQTT:DISCONNECTED,0

参数

  • <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 命令。

命令: 

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

响应: 

OK

参数

  • <LinkID>: 当前仅支持链路 ID 0。
  • <"topic">: MQTT 主题。最大长度: 128 字节。
  • <"data">: MQTT 字符串格式消息。
  • <qos>: 消息 QoS,可以设置为 0、1 或 2。默认值: 0。
  • <retain>: retain 标志。

注意事项

  • 整个 AT 命令的长度应小于 256 字节。
  • 此命令不能发送 \0 数据。如果需要发送 \0,请使用 AT+MQTTPUBRAW 命令。

示例

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  // 发送此命令时,请注意是否需要转义特殊字符。

---

AT+MQTTPUBRAW

发布长 MQTT 消息。

设置命令

功能:

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

命令: 

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

响应: 

OK

>

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

如果传输成功,AT 返回: 

SEND OK

否则返回: 

SEND FAIL

参数

  • <LinkID>: 当前仅支持链路 ID 0。
  • <"topic">: MQTT 主题。最大长度: 128 字节。
  • <length>: MQTT 消息长度。最大长度受可用内存限制。
  • <qos>: 发布消息的 QoS,可以设置为 0、1 或 2。默认值为 0。
  • <retain>: retain 标志。

---

AT+MQTTSUB

订阅 MQTT 主题。

查询命令

查询已订阅的 MQTT 主题。

命令: 

AT+MQTTSUB?

响应: 

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

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

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

...

OK

设置命令

功能:

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

命令: 

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

响应: 

OK

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

+MQTTSUB,ALREADY_SUBSCRIBE

OK

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

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

参数

  • <LinkID>: 当前仅支持链路 ID 0。
  • <state>:
   * 0: MQTT 未初始化。
   * 1: 已设置 AT+MQTTUSERCFG。
   * 2: 已设置 AT+MQTTCONNCFG。
   * 3: 连接已断开。
   * 4: 连接已建立。
   * 5: 已连接,但未订阅任何主题。
   * 6: 已连接,并已订阅 MQTT 主题。
  • <topic>: 已订阅的主题。
  • <qos>: 已订阅的 QoS。

---

AT+MQTTUNSUB

取消订阅 MQTT 主题。

设置命令

功能:

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

命令: 

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

响应: 

OK

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

+MQTTUNSUB:NO_UNSUBSCRIBE

OK

参数

  • <LinkID>: 当前仅支持链路 ID 0。
  • <topic>: MQTT 主题。最大长度: 128 字节。

---

AT+MQTTCLEAN

关闭 MQTT 连接。

设置命令

功能:

关闭 MQTT 连接并释放资源。

命令: 

AT+MQTTCLEAN=<LinkID>

响应: 

OK

参数

  • <LinkID>: 当前仅支持链路 ID 0。
检索自“https://docs.bouffalolab.com/index.php?title=AT模块_6:_MQTT_AT_命令（MQTT_AT_Commands）&oldid=183”