MQTT AT Commands¶
AT+MQTTUSERCFG: Set MQTT user configuration
AT+MQTTCLIENTID: Set MQTT client ID
AT+MQTTUSERNAME: Set MQTT username
AT+MQTTPASSWORD: Set MQTT password
AT+MQTTCONNCFG: Set configuration of MQTT connection
AT+MQTTALPN: Set MQTT Application Layer Protocol Negotiation (ALPN)
AT+MQTTCONN: Connect to MQTT Brokers
AT+MQTTPUB: Publish MQTT Messages in string
AT+MQTTPUBRAW: Publish MQTT messages in binary
AT+MQTTSUB: Subscribe to MQTT topics
AT+MQTTUNSUB: Unsubscribe from MQTT topics
AT+MQTTCLEAN: Close MQTT connections
AT+MQTTUSERCFG: Set MQTT User Configuration¶
Set Command¶
Function:
Set MQTT User Configuration.
Command:
AT+MQTTUSERCFG=<LinkID>,<scheme>,<"client_id">,<"username">,<"password">,<cert_key_ID>,<CA_ID>,<"path">
Response:
OK
Parameters¶
<LinkID>: currently only supports link ID 0.
<scheme>:
1: MQTT over TCP.
2: MQTT over TLS (no certificate verify).
3: MQTT over TLS (verify server certificate).
4: MQTT over TLS (provide client certificate).
5: MQTT over TLS (verify server certificate and provide client certificate).
6: MQTT over WebSocket (based on TCP).
7: MQTT over WebSocket Secure (based on TLS, no certificate verify).
8: MQTT over WebSocket Secure (based on TLS, verify server certificate).
9: MQTT over WebSocket Secure (based on TLS, provide client certificate).
10: MQTT over WebSocket Secure (based on TLS, verify server certificate and provide client certificate).
<client_id>: MQTT client ID. Maximum length: 256 bytes.
<username>: the username to login to the MQTT broker. Maximum length: 64 bytes.
<password>: the password to login to the MQTT broker. Maximum length: 64 bytes.
<cert_key_ID>: certificate ID. Currently, ESP-AT only supports one certificate for ID 0.
<CA_ID>: CA ID. Currently, ESP-AT only supports one CA for ID 0.
<path>: the path of the resource. Maximum length: 32 bytes.
Note¶
The length of the entire AT command should be less than 256 bytes.
AT+MQTTCLIENTID: Set MQTT Client ID¶
Set Command¶
Function:
Set MQTT Client ID.
Command:
AT+MQTTCLIENTID=<LinkID>,<"client_id">
Response:
OK
Parameters¶
<LinkID>: currently only supports link ID 0.
<client_id>: MQTT client ID.
Notes¶
The length of the entire AT command should be less than 256 bytes.
The command AT+MQTTUSERCFG can also set MQTT client ID. The differences between the two commands include:
You can use
AT+MQTTCLIENTID
to set a relatively long client ID since there is a limitation on the length of theAT+MQTTUSERCFG
command.You should set
AT+MQTTCLIENTID
after setting theAT+MQTTUSERCFG
command.
AT+MQTTUSERNAME: Set MQTT Username¶
Set Command¶
Function:
Set MQTT username.
Command:
AT+MQTTUSERNAME=<LinkID>,<"username">
Response:
OK
Parameters¶
<LinkID>: only supports link ID 0 currently.
<username>: the username to login to the MQTT broker.
Notes¶
The length of the entire AT command should be less than 256 bytes.
The command AT+MQTTUSERCFG can also set MQTT username. The differences between the two commands include:
You can use
AT+MQTTUSERNAME
to set a relatively long username since there is a limitation on the length of theAT+MQTTUSERCFG
command.You should set
AT+MQTTUSERNAME
after setting the commandAT+MQTTUSERCFG
.
AT+MQTTPASSWORD: Set MQTT Password¶
Set Command¶
Function:
Set MQTT password.
Command:
AT+MQTTPASSWORD=<LinkID>,<"password">
Response:
OK
Parameters¶
<LinkID>: only supports link ID 0 currently.
<password>: the password to login to the MQTT broker.
Notes¶
The length of the entire AT command should be less than 256 bytes.
The command AT+MQTTUSERCFG can also set MQTT password. The differences between the two commands include:
You can use
AT+MQTTPASSWORD
to set a relatively long password since there is a limitation on the length of theAT+MQTTUSERCFG
command.You should set
AT+MQTTPASSWORD
after setting the commandAT+MQTTUSERCFG
.
AT+MQTTCONNCFG: Set Configuration of MQTT Connection¶
Set Command¶
Function:
Set configuration of MQTT Connection.
Command:
AT+MQTTCONNCFG=<LinkID>,<keepalive>,<disable_clean_session>,<"lwt_topic">,<"lwt_msg">,<lwt_qos>,<lwt_retain>
Response:
OK
Parameters¶
<LinkID>: only supports link ID 0 currently.
<keepalive>: timeout of MQTT ping. Unit: second. Range [0,7200]. The default value is 0, which will be force-changed to 120 s.
<disable_clean_session>: set MQTT clean session. For more details about this parameter, please refer to the section Clean Session in MQTT Version 3.1.1.
0: enable clean session.
1: disable clean session.
<lwt_topic>: LWT (Last Will and Testament) message topic. Maximum length: 128 bytes.
<lwt_msg>: LWT message. Maximum length: 64 bytes.
<lwt_qos>: LWT QoS, which can be set to 0, 1, or 2. Default: 0.
<lwt_retain>: LWT retain, which can be set to 0 or 1. Default: 0.
AT+MQTTALPN: Set MQTT Application Layer Protocol Negotiation (ALPN)¶
Set Command¶
Function:
Set MQTT Application Layer Protocol Negotiation (ALPN).
Command:
AT+MQTTALPN=<LinkID>,<alpn_counts>[,<"alpn">][,<"alpn">][,<"alpn">]
Response:
OK
Parameters¶
<LinkID>: only supports link ID 0 currently.
<alpn_counts>: the number of <”alpn”> parameters. Range: [0,5].
0: clean the MQTT ALPN configuration.
[1,5]: set the MQTT ALPN configuration.
<”alpn”>: you can send more than one ALPN in ClientHello to the server.
Notes¶
The length of the entire AT command should be less than 256 bytes.
MQTT ALPN will only be effective if the MQTT connection is based on TLS or WSS.
You should set
AT+MQTTALPN
after setting the commandAT+MQTTUSERCFG
.
Example¶
AT+CWMODE=1
AT+CWJAP="ssid","password"
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com","ntp2.aliyun.com"
AT+MQTTUSERCFG=0,5,"ESP32","espressif","1234567890",0,0,""
AT+MQTTALPN=0,2,"mqtt-ca.cn","mqtt-ca.us"
AT+MQTTCONN=0,"192.168.200.2",8883,1
AT+MQTTCONN: Connect to MQTT Brokers¶
Query Command¶
Function:
Query the MQTT broker that ESP devices are connected to.
Command:
AT+MQTTCONN?
Response:
+MQTTCONN:<LinkID>,<state>,<scheme><"host">,<port>,<"path">,<reconnect>
OK
Set Command¶
Function:
Connect to an MQTT broker.
Command:
AT+MQTTCONN=<LinkID>,<"host">,<port>,<reconnect>
Response:
OK
Parameters¶
<LinkID>: only supports link ID 0 currently.
<host>: MQTT broker domain. Maximum length: 128 bytes.
<port>: MQTT broker port. Maximum: port 65535.
<path>: path. Maximum length: 32 bytes.
<reconnect>:
0: MQTT will not reconnect automatically.
1: MQTT will reconnect automatically. It takes more resources.
<state>: MQTT state.
0: MQTT uninitialized.
1: already set
AT+MQTTUSERCFG
.2: already set
AT+MQTTCONNCFG
.3: connection disconnected.
4: connection established.
5: connected, but did not subscribe to any topic.
6: connected, and subscribed to MQTT topics.
<scheme>:
1: MQTT over TCP.
2: MQTT over TLS (no certificate verify).
3: MQTT over TLS (verify server certificate).
4: MQTT over TLS (provide client certificate).
5: MQTT over TLS (verify server certificate and provide client certificate).
6: MQTT over WebSocket (based on TCP).
7: MQTT over WebSocket Secure (based on TLS, verify no certificate).
8: MQTT over WebSocket Secure (based on TLS, verify server certificate).
9: MQTT over WebSocket Secure (based on TLS, provide client certificate).
10: MQTT over WebSocket Secure (based on TLS, verify server certificate and provide client certificate).
AT+MQTTPUB: Publish MQTT Messages in String¶
Set Command¶
Function:
Publish MQTT messages in string to a defined topic. If you need to publish messages in binary, please use the AT+MQTTPUBRAW command.
Command:
AT+MQTTPUB=<LinkID>,<"topic">,<"data">,<qos>,<retain>
Response:
OK
Parameters¶
<LinkID>: only supports link ID 0 currently.
<topic>: MQTT topic. Maximum length: 128 bytes.
<data>: MQTT message in string.
<qos>: QoS of message, which can be set to 0, 1, or 2. Default: 0.
<retain>: retain flag.
Notes¶
The length of the entire AT command should be less than 256 bytes.
This command cannot send data
\0
. If you need to send\0
, please use the command AT+MQTTPUBRAW instead.
Example¶
AT+CWMODE=1
AT+CWJAP="ssid","password"
AT+MQTTUSERCFG=0,1,"ESP32","espressif","1234567890",0,0,""
AT+MQTTCONN=0,"192.168.10.234",1883,0
AT+MQTTPUB=0,"topic","\"{\"timestamp\":\"20201121085253\"}\"",0,0
AT+MQTTPUBRAW: Publish MQTT Messages in Binary¶
Set Command¶
Function:
Publish MQTT messages in binary to a defined topic.
Command:
AT+MQTTPUBRAW=<LinkID>,<"topic">,<length>,<qos>,<retain>
Response:
OK
>
The symbol >
indicates that AT is ready for receiving serial data, and you can enter the data now. When the requirement of message length determined by the parameter <length>
is met, the transmission starts.
If the transmission is successful, AT returns:
+MQTTPUB:OK
Otherwise, it returns:
+MQTTPUB:FAIL
Parameters¶
<LinkID>: only supports link ID 0 currently.
<topic>: MQTT topic. Maximum length: 128 bytes.
<length>: length of MQTT message. The maximum length is limited by available memory.
<qos>: QoS of the published message, which can be set to 0, 1, or 2. Default is 0.
<retain>: retain flag.
AT+MQTTSUB: Subscribe to MQTT Topics¶
Query Command¶
Function:
List all MQTT topics that have been already subscribed.
Command:
AT+MQTTSUB?
Response:
+MQTTSUB:<LinkID>,<state>,<"topic1">,<qos>
+MQTTSUB:<LinkID>,<state>,<"topic2">,<qos>
+MQTTSUB:<LinkID>,<state>,<"topic3">,<qos>
...
OK
Set Command¶
Function:
Subscribe to defined MQTT topics with defined QoS. It supports subscribing to multiple topics.
Command:
AT+MQTTSUB=<LinkID>,<"topic">,<qos>
Response:
OK
When AT receives MQTT messages of the subscribed topic, it will prompt:
+MQTTSUBRECV:<LinkID>,<"topic">,<data_length>,data
If the topic has been subscribed before, it will prompt:
ALREADY SUBSCRIBE
Parameters¶
<LinkID>: only supports link ID 0 currently.
<state>: MQTT state.
0: MQTT uninitialized.
1: already set
AT+MQTTUSERCFG
.2: already set
AT+MQTTCONNCFG
.3: connection disconnected.
4: connection established.
5: connected, but subscribe to no topic.
6: connected, and subscribed to MQTT topics.
<topic>: the topic that is subscribed to.
<qos>: the QoS that is subscribed to.
AT+MQTTUNSUB: Unsubscribe from MQTT Topics¶
Set Command¶
Function:
Unsubscribe the client from defined topics. This command can be called multiple times to unsubscribe from different topics.
Command:
AT+MQTTUNSUB=<LinkID>,<"topic">
Response:
OK
If the topic has not been subscribed, AT will prompt:
NO UNSUBSCRIBE
OK
Parameters¶
<LinkID>: only supports link ID 0 currently.
<topic>: MQTT topic. Maximum length: 128 bytes.
AT+MQTTCLEAN: Close MQTT Connections¶
Set Command¶
Function:
Close the MQTT connection and release the resource.
Command:
AT+MQTTCLEAN=<LinkID>
Response:
OK
Parameter¶
<LinkID>: only supports link ID 0 currently.
MQTT AT Error Codes¶
The MQTT Error code will be prompted as ERR CODE:0x<%08x>
.
Error Type |
Error Code |
---|---|
AT_MQTT_NO_CONFIGURED |
0x6001 |
AT_MQTT_NOT_IN_CONFIGURED_STATE |
0x6002 |
AT_MQTT_UNINITIATED_OR_ALREADY_CLEAN |
0x6003 |
AT_MQTT_ALREADY_CONNECTED |
0x6004 |
AT_MQTT_MALLOC_FAILED |
0x6005 |
AT_MQTT_NULL_LINK |
0x6006 |
AT_MQTT_NULL_PARAMTER |
0x6007 |
AT_MQTT_PARAMETER_COUNTS_IS_WRONG |
0x6008 |
AT_MQTT_TLS_CONFIG_ERROR |
0x6009 |
AT_MQTT_PARAM_PREPARE_ERROR |
0x600A |
AT_MQTT_CLIENT_START_FAILED |
0x600B |
AT_MQTT_CLIENT_PUBLISH_FAILED |
0x600C |
AT_MQTT_CLIENT_SUBSCRIBE_FAILED |
0x600D |
AT_MQTT_CLIENT_UNSUBSCRIBE_FAILED |
0x600E |
AT_MQTT_CLIENT_DISCONNECT_FAILED |
0x600F |
AT_MQTT_LINK_ID_READ_FAILED |
0x6010 |
AT_MQTT_LINK_ID_VALUE_IS_WRONG |
0x6011 |
AT_MQTT_SCHEME_READ_FAILED |
0x6012 |
AT_MQTT_SCHEME_VALUE_IS_WRONG |
0x6013 |
AT_MQTT_CLIENT_ID_READ_FAILED |
0x6014 |
AT_MQTT_CLIENT_ID_IS_NULL |
0x6015 |
AT_MQTT_CLIENT_ID_IS_OVERLENGTH |
0x6016 |
AT_MQTT_USERNAME_READ_FAILED |
0x6017 |
AT_MQTT_USERNAME_IS_NULL |
0x6018 |
AT_MQTT_USERNAME_IS_OVERLENGTH |
0x6019 |
AT_MQTT_PASSWORD_READ_FAILED |
0x601A |
AT_MQTT_PASSWORD_IS_NULL |
0x601B |
AT_MQTT_PASSWORD_IS_OVERLENGTH |
0x601C |
AT_MQTT_CERT_KEY_ID_READ_FAILED |
0x601D |
AT_MQTT_CERT_KEY_ID_VALUE_IS_WRONG |
0x601E |
AT_MQTT_CA_ID_READ_FAILED |
0x601F |
AT_MQTT_CA_ID_VALUE_IS_WRONG |
0x6020 |
AT_MQTT_CA_LENGTH_ERROR |
0x6021 |
AT_MQTT_CA_READ_FAILED |
0x6022 |
AT_MQTT_CERT_LENGTH_ERROR |
0x6023 |
AT_MQTT_CERT_READ_FAILED |
0x6024 |
AT_MQTT_KEY_LENGTH_ERROR |
0x6025 |
AT_MQTT_KEY_READ_FAILED |
0x6026 |
AT_MQTT_PATH_READ_FAILED |
0x6027 |
AT_MQTT_PATH_IS_NULL |
0x6028 |
AT_MQTT_PATH_IS_OVERLENGTH |
0x6029 |
AT_MQTT_VERSION_READ_FAILED |
0x602A |
AT_MQTT_KEEPALIVE_READ_FAILED |
0x602B |
AT_MQTT_KEEPALIVE_IS_NULL |
0x602C |
AT_MQTT_KEEPALIVE_VALUE_IS_WRONG |
0x602D |
AT_MQTT_DISABLE_CLEAN_SESSION_READ_FAILED |
0x602E |
AT_MQTT_DISABLE_CLEAN_SESSION_VALUE_IS_WRONG |
0x602F |
AT_MQTT_LWT_TOPIC_READ_FAILED |
0x6030 |
AT_MQTT_LWT_TOPIC_IS_NULL |
0x6031 |
AT_MQTT_LWT_TOPIC_IS_OVERLENGTH |
0x6032 |
AT_MQTT_LWT_MSG_READ_FAILED |
0x6033 |
AT_MQTT_LWT_MSG_IS_NULL |
0x6034 |
AT_MQTT_LWT_MSG_IS_OVERLENGTH |
0x6035 |
AT_MQTT_LWT_QOS_READ_FAILED |
0x6036 |
AT_MQTT_LWT_QOS_VALUE_IS_WRONG |
0x6037 |
AT_MQTT_LWT_RETAIN_READ_FAILED |
0x6038 |
AT_MQTT_LWT_RETAIN_VALUE_IS_WRONG |
0x6039 |
AT_MQTT_HOST_READ_FAILED |
0x603A |
AT_MQTT_HOST_IS_NULL |
0x603B |
AT_MQTT_HOST_IS_OVERLENGTH |
0x603C |
AT_MQTT_PORT_READ_FAILED |
0x603D |
AT_MQTT_PORT_VALUE_IS_WRONG |
0x603E |
AT_MQTT_RECONNECT_READ_FAILED |
0x603F |
AT_MQTT_RECONNECT_VALUE_IS_WRONG |
0x6040 |
AT_MQTT_TOPIC_READ_FAILED |
0x6041 |
AT_MQTT_TOPIC_IS_NULL |
0x6042 |
AT_MQTT_TOPIC_IS_OVERLENGTH |
0x6043 |
AT_MQTT_DATA_READ_FAILED |
0x6044 |
AT_MQTT_DATA_IS_NULL |
0x6045 |
AT_MQTT_DATA_IS_OVERLENGTH |
0x6046 |
AT_MQTT_QOS_READ_FAILED |
0x6047 |
AT_MQTT_QOS_VALUE_IS_WRONG |
0x6048 |
AT_MQTT_RETAIN_READ_FAILED |
0x6049 |
AT_MQTT_RETAIN_VALUE_IS_WRONG |
0x604A |
AT_MQTT_PUBLISH_LENGTH_READ_FAILED |
0x604B |
AT_MQTT_PUBLISH_LENGTH_VALUE_IS_WRONG |
0x604C |
AT_MQTT_RECV_LENGTH_IS_WRONG |
0x604D |
AT_MQTT_CREATE_SEMA_FAILED |
0x604E |
AT_MQTT_CREATE_EVENT_GROUP_FAILED |
0x604F |
AT_MQTT_URI_PARSE_FAILED |
0x6050 |
AT_MQTT_IN_DISCONNECTED_STATE |
0x6051 |
AT_MQTT_HOSTNAME_VERIFY_FAILED |
0x6052 |
MQTT AT Notes¶
In general, AT MQTT commands responds within 10 s, except the command
AT+MQTTCONN
. For example, if the router fails to access the Internet, the commandAT+MQTTPUB
will respond within 10 s. But the commandAT+MQTTCONN
may need more time due to packet retransmission in a bad network environment.If the
AT+MQTTCONN
is based on a TLS connection, the timeout of each packet is 10 s, and the total timeout will be much longer depending on the handshake packets count.When the MQTT connection ends, it will prompt the message
+MQTTDISCONNECTED:<LinkID>
.When the MQTT connection established, it will prompt the message
+MQTTCONNECTED:<LinkID>,<scheme>,<"host">,port,<"path">,<reconnect>
.