MQTT AT Command Set
AT
Application: https://github.com/espressif/esp-at
AT
Documentation: https://github.com/espressif/esp-at/tree/master/docs
After commit: 8ebdee924
, ESP-AT
support MQTT
AT
commands. Users developing applications based on AT
may refer to commands below, for quick connection with corresponding Broker
using AT+MQTT
.
** Before using AT+MQTT
, please enable AT+MQTT
function:**
make menuconfig
-> Component config
-> AT
-> AT MQTT command support
Command List
AT+MQTTUSERCFG
- Configure MQTT user attributesAT+MQTTCONNCFG
- Configure MQTT connection attributesAT+MQTTCONN
- Connect to/search MQTT BrokerAT+MQTTPUB
- Publish text stringsAT+MQTTPUBRAW
- Publish binariesAT+MQTTSUB
- Subscribe/search themesAT+MQTTUNSUB
- Unsubscribe themesAT+MQTTCLEAN
- Disconnect MQTT Broker
AT+MQTTUSERCFG - Configure MQTT user attributes
Set Command:
AT+MQTTUSERCFG=<LinkID>,<scheme>,<"client_id">,<"username">,<"password">,<cert_key_ID>,<CA_ID>,<"path">
Function:
Set up MQTT
user configuration
Response:
OK
or
ERROR
Parameter Description:
- LinkID: Currently only support 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)
- 1:
- client_id:
ID
ofMQTT
client
, served as a symbol of identity, 256 bytes at most - username:
username
to log inMQTT
broker
, 64 bytes at most - password:
password
to log inMQTT
broker
, 64 bytes at most - cert_key_ID:
ID
of certificate. Currently only support onecert
certificate, whose parameter is 0 - CA_ID:
CA ID
. Currently only support oneCA
certicate, whose parameter is 0 - path: Resource path, 32 bytes at most
AT+MQTTCONNCFG - Configure MQTT connection attributes
Set Command:
AT+MQTTCONNCFG=<LinkID>,<keepalive>,<disable_clean_session>,<"lwt_topic">,<"lwt_msg">,<lwt_qos>,<lwt_retain>
Function:
Set up MQTT
connection configuration
Response:
OK
or
ERROR
Parameter Descrption:
- LinkID: Currently only support 0
- keepalive:
MQTT
PING
timeout limits, ranging from 60 seconds to 7200 seconds. Default =120
- disable_clean_session:
MQTT
clean session. The optional values of this parameter are 0 and 1 (default = 0) - lwt_topic: Will
topic
, 64 bytes at most - lwt_msg: Will
message
, 64 bytes at most - lwt_qos: Will
QoS
. The optional values of this parameter are 0, 1 and 2 (default = 0) - lwt_retain: Will
retain
. The optional values of this parameter are 0 and 1 (default = 0)
AT+MQTTCONN
Set Command:
AT+MQTTCONN=<LinkID>,<"host">,<port>,<reconnect>
Function:
Connect to the specified MQTT broker
Response:
OK
or
ERROR
Query Command:
AT+MQTTCONN?
Function:
Query for MQTT brokers
already connected to AT
Response:
+MQTTCONN:<LinkID>,<state>,<scheme><"host">,<port>,<"path">,<reconnect>
OK
Parameter Descrption:
- LinkID: Currently only support 0
- host: Domain name of the
MQTT broker
to be connected, 128 bytes at most - port: Port to connect
MQTT broker
, 65535 at most - path: Resource path, 32 bytes at most
- reconnect: Reconnect to MQTT. If this parameter is set to 1, more memory resources will be consumed
- state: Current status of
MQTT
:- 0: Connection is not initialized
- 1:
MQTTUSERCFG
has been set - 2:
MQTTCONNCFG
has been set - 3: Connection has been broken
- 4: Connection has been established
- 5: Connected, but
topic
has not been subscribed - 6: Connected, and
topic
has been subscribed
- 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)
- 1:
AT+MQTTPUB
Set Command:
AT+MQTTPUB=<LinkID>,<"topic">,<"data">,<qos>,<retain>
Function:
Publish string data
on LinkID
to a topic
. To publish binary data
, please use AT+MQTTPUBRAW
Response:
OK
or
ERROR
Parameter Descrption:
- LinkID: Currently only support 0
- topic: Topic of published messages, 64 bytes at most
- data: Message published. Please make sure that
data
does not contain\0
, andAT+MQTTPUB
does not exceed the length limit of AT commands - qos: Quality of service. The optional values of this parameter are 0, 1 and 2 (default = 0)
- retain:
retain
AT+MQTTPUBRAW
Set Command:
AT+MQTTPUBRAW=<LinkID>,<"topic">,<length>,<qos>,<retain>
Function:
Publish binary data
on LinkID
to a topic
Response:
OK
>
or
ERROR
Response to input of length
bytes of data:
+MQTTPUB:FAIL
or
+MQTTPUB:OK
Parameter Descrption:
- LinkID: Currently only support 0
- topic: Topic of the message, 64 bytes at most
- length: Length of the message to be published. This parameter can be configured via
MQTT_BUFFER_SIZE_BYTE
ofmake menuconfig
(default = 1024) - qos: Quality of service. The optional values of this parameter are 0, 1 and 2 (default = 0)
- retain:
retain
AT port will wait until it receives data of the specified length. Data received during the waiting period will be regarded as ordinary data
AT+MQTTSUB
Set Command:
AT+MQTTSUB=<LinkID>,<"topic">,<qos>
Function:
Subscribe the specified MQTT
topic. You can subscribe different topic
for many times
Response:
OK
or
ERROR
When a
MQTT
message of a subscribed topic is received, the content of this message will be printed as follows
+MQTTSUBRECV:<LinkID>,<"topic">,<data_length>,data
If a topic is subscribed repeatedly, the subscription request will still be sent to
MQTT broker
, andALREADY SUBSCRIBE
will be printed in thelog
Query Command:
AT+MQTTSUB?
Function:
Query for all the subscribed MQTT
topic
Response:
+MQTTSUB:<LinkID>,<state>,<"topic1">,<qos>
+MQTTSUB:<LinkID>,<state>,<"topic2">,<qos>
+MQTTSUB:<LinkID>,<state>,<"topic3">,<qos>
...
OK
or
ERROR
Parameter Descrption:
- LinkID: Currently only support 0
- state: The current status of
MQTT
:- 0: Connection is not initialized
- 1:
MQTTUSERCFG
has been set - 2:
MQTTCONNCFG
has been set - 3: Connection has been broken
- 4: Connection has been established
- 5: Connected, but
topic
has not been subscribed - 6: Connected, and
topic
has been subscribed
- topic*: Topics subscribed
- qos:
QoS
subscribed
AT+MQTTUNSUB
Set Command:
AT+MQTTUNSUB=<LinkID>,<"topic">
Function:
Unsubscribe the specified MQTT
topic. You can unsubscribe different topic
for many times
Response:
OK
or
ERROR
Parameter Descrption:
- LinkID: Currently only support 0
- topic: Unsubscribe themes, 64 bytes at most
If a topic is unsubscribed repeatedly, the unsubscription request will still be sent to
MQTT broker
, andNO UNSUBSCRIBE
will be printed in thelog
AT+MQTTCLEAN
Set Command:
AT+MQTTCLEAN=<LinkID>
Function:
Disconnect MQTT Client
, and release occupied resources
Response:
OK
or
ERROR
Parameter Descrption:
- LinkID: Currently only support 0
MQTT Status Code
If you encounter ERR CODE:0x<%08x>
when configuring MQTT
, please check the following MQTT
status 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
Notes
- Except
AT+MQTTCONN
, all MQTT commands will return within 10 seconds. For instance, if you the router cannot be connected to the Internet,AT+MQTTPUB
will return within 10 seconds. - For
AT+MQTTCONN
connection based on TLS, the timeout value for each step is 10 seconds, and the total timeout depends on the number of interaction steps. - Once connection to MQTT is broken,
+MQTTDISCONNECTED:<LinkID>
will be printed - Once connection to MQTT is established,
+MQTTCONNECTED:<LinkID>,<scheme>,<"host">,port,<"path">,<reconnect>
will be printed
Test Command 1: MQTT over TCP (Need to set up a MQTT broker locally)
When connecting to a MQTT broker
using MQTT over TCP
(MQTT broker
IP: 192.168.31.113
port: 1883
), you can subscribe and publish to topic
as follows:
AT+MQTTUSERCFG=0,1,"ESP32","espressif","1234567890",0,0,""
AT+MQTTCONN=0,"192.168.31.113",1883,0
AT+MQTTSUB=0,"topic",1
AT+MQTTPUB=0,"topic","test",1,0
AT+MQTTCLEAN=0
Test Command 2: MQTT over TLS (Need to set up a MQTT broker locally)
When connecting to a MQTT broker
using MQTT over TLS
(MQTT broker
IP: 192.168.31.113
, port: 1883
), you can subscribe and publish to topic
as follows:
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"
AT+CIPSNTPTIME?
AT+MQTTUSERCFG=0,3,"ESP32","espressif","1234567890",0,0,""
AT+MQTTCONNCFG=0,0,0,"lwtt","lwtm",0,0
AT+MQTTCONN=0,"192.168.31.113",1883,0
AT+MQTTSUB=0,"topic",1
AefT+MQTTPUB=0,"topic","test",1,0
AT+MQTTCLEAN=0
Test Command 3: MQTT over WSS
When connecting to MQTT broker: iot.eclipse.org
using MQTT over WSS
, (open test port for iot.eclipse.org
: 443
), you can subscribe and publish to topic
as follows:
AT+CIPSNTPCFG=1,8,"ntp1.aliyun.com"
AT+CIPSNTPTIME?
AT+MQTTUSERCFG=0,7,"ESP32","espressif","1234567890",0,0,"wss"
AT+MQTTCONN=0,"iot.eclipse.org",443,0
AT+MQTTSUB=0,"topic",1
AT+MQTTPUB=0,"topic","test",1,0
AT+MQTTCLEAN=0