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 BrokerSet Command:
AT+MQTTUSERCFG=,,<"client_id">,<"username">,<"password">,,,<"path">
Function:
Set up MQTT
user configuration
Response:
OK
or
ERROR
Parameter Description:
MQTT over TCP
MQTT over TLS(no certificate verify)
MQTT over TLS(verify server certificate)
MQTT over TLS(provide client certificate)
MQTT over TLS(verify server certificate and provide client certificate)
MQTT over WebSocket(based on TCP)
MQTT over WebSocket Secure(based on TLS, no certificate verify)
MQTT over WebSocket Secure(based on TLS, verify server certificate)
MQTT over WebSocket Secure(based on TLS, provide client certificate)
MQTT over WebSocket Secure(based on TLS, verify server certificate and provide client certificate)
ID
of MQTT
client
, served as a symbol of identity, 256 bytes at mostusername
to log in MQTT
broker
, 64 bytes at mostpassword
to log in MQTT
broker
, 64 bytes at mostID
of certificate. Currently only support one cert
certificate, whose parameter is 0CA ID
. Currently only support one CA
certicate, whose parameter is 0Set Command:
AT+MQTTCONNCFG=,,,<"lwt_topic">,<"lwt_msg">,,
Function:
Set up MQTT
connection configuration
Response:
OK
or
ERROR
Parameter Descrption:
MQTT
PING
timeout limits, ranging from 60 seconds to 7200 seconds. Default = 120
MQTT
clean session. The optional values of this parameter are 0 and 1 (default = 0)topic
, 64 bytes at mostmessage
, 64 bytes at mostQoS
. The optional values of this parameter are 0, 1 and 2 (default = 0)retain
. The optional values of this parameter are 0 and 1 (default = 0)Set Command:
AT+MQTTCONN=,<"host">,,
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:,,<"host">,,<"path">,
OK
Parameter Descrption:
MQTT broker
to be connected, 128 bytes at mostMQTT broker
, 65535 at mostMQTT
:
MQTTUSERCFG
has been setMQTTCONNCFG
has been settopic
has not been subscribedtopic
has been subscribedMQTT over TCP
MQTT over TLS(no certificate verify)
MQTT over TLS(verify server certificate)
MQTT over TLS(provide client certificate)
MQTT over TLS(verify server certificate and provide client certificate)
MQTT over WebSocket(based on TCP)
MQTT over WebSocket Secure(based on TLS, no certificate verify)
MQTT over WebSocket Secure(based on TLS, verify server certificate)
MQTT over WebSocket Secure(based on TLS, provide client certificate)
MQTT over WebSocket Secure(based on TLS, verify server certificate and provide client certificate)
Set Command:
AT+MQTTPUB=,<"topic">,<"data">,,
Function:
Publish string data
on LinkID
to a topic
. To publish binary data
, please use AT+MQTTPUBRAW
Response:
OK
or
ERROR
Parameter Descrption:
data
does not contain \0
, and AT+MQTTPUB
does not exceed the length limit of AT commandsretain
Set Command:
AT+MQTTPUBRAW=,<"topic">,,,
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:
MQTT_BUFFER_SIZE_BYTE
of make menuconfig
(default = 1024)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
Set Command:
AT+MQTTSUB=,<"topic">,
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:,<"topic">,,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:,,<"topic1">,
+MQTTSUB:,,<"topic2">,
+MQTTSUB:,,<"topic3">,
...
OK
or
ERROR
Parameter Descrption:
MQTT
:
MQTTUSERCFG
has been setMQTTCONNCFG
has been settopic
has not been subscribedtopic
has been subscribedQoS
subscribedSet Command:
AT+MQTTUNSUB=,<"topic">
Function:
Unsubscribe the specified MQTT
topic. You can unsubscribe different topic
for many times
Response:
OK
or
ERROR
Parameter Descrption:
If a topic is unsubscribed repeatedly, the unsubscription request will still be sent to
MQTT broker
, andNO UNSUBSCRIBE
will be printed in thelog
Set Command:
AT+MQTTCLEAN=
Function:
Disconnect MQTT Client
, and release occupied resources
Response:
OK
or
ERROR
Parameter Descrption:
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
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.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.+MQTTDISCONNECTED:
will be printed+MQTTCONNECTED:,,<"host">,port,<"path">,
will be printedWhen 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
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
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