MQTT AT Commands

Note

  • The MQTT AT commands are disabled by default.

  • Refer to Configuring SDK (menuconfig) to enter CONFIG AT CMD configuration and check Enable MQTT to enable the MQTT AT commands.

MQTT AT Error Codes

The unified MQTT error codes are defined as follows:

  • 1: Parameter error

  • 2: Memory allocation failure

  • 3: Connection error

  • 4: Disconnection error

  • 5: Failed to enter TT mode

  • 6: Certificate suite get failure

  • 7: Not connected

  • 8: Already connected

  • 9: Publish failure

  • 10: Subscribe failure

  • 11: Unsubscribe failure

  • 12: Already subscribed

  • 13: Timeout

  • 14: Thread creation failure

  • 15: Network connection error

AT+MQTTCFG

Function Description

Configure the MQTT connection parameters for a specified link ID

Command Format

AT+MQTTCFG=<link_id>,<keepalive>,<cmd_timeout>,<disable_clean_session>[,<lwt_topic>,<lwt_msg>,<lwt_qos>,<lwt_retain>]

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

<link_id>:

Link ID

  • Range [0,3]

<keepalive>:

Ping timeout (seconds)

  • Default value: 60

<cmd_timeout>:

Connect/Subscribe timeout (seconds)

  • Default value: 60

<disable_clean_session>:

Clean session option

  • 0: Enable clean session.

  • 1: Disable clean session.

<lwt_topic>:

LWT (Last Will and Testament) message topic

<lwt_msg>:

LWT message

<lwt_qos>:

LWT QoS

  • Range [0,2]

  • Default value: 0

<lwt_retain>:

LWT retain

  • Range [0,1]

  • Default value: 0

Error Codes

  • 1: Parameters error

  • 2: Malloc failed

  • 8: Already connected to broker

Example

  • Configure with LWT message:

    AT+MQTTCFG=0,20,60,0,topic/lwt,This is a lwt message,0,0

OK

  • Configure without LWT message:

    AT+MQTTCFG=0,20,60,0

OK

AT+MQTTCONN

Function Description

Connect to MQTT broker.

Command Format

AT+MQTTCONN=<link_id>,<host>,[<port>],<client_id>,<conn_type>[,<cert_index>,<username>,<password>]

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

AT Messages

  • Upon successful connection, the following prompt message will be displayed:

    [$][MQTT][EVENT]:linkid:<link_id>, connected

  • In case of connection failure or exception, the following prompt message will be displayed:

    [$][MQTT][EVENT]:linkid:<link_id>, ERROR:<err_no>

Note

For the specific definitions of err_no, refer to unified MQTT error

Parameters

<link_id>:

Link ID

  • Range [0,3]

<host>:

Broker domain

  • Maximum length: 128 bytes

<port>:

Broker port

  • Range [0,65535]

  • Default value: 0

  • 0: MQTT uses port 1883, MQTTS uses port 8883

<client_id>:

Client ID

  • Maximum length: 256 bytes

<conn_type>:

Connection type

  • 1: MQTT

  • 2: MQTTS (no certificate verification)

  • 3: MQTTS (verify server certificate with CA certificate)

  • 4: MQTTS (provide client certificate to server for verification)

  • 5: MQTTS (mutual authentication, both 3 and 4)

<cert_index>:

Security Certificate Suite index, refer to AT Security Certificates

  • Range [1-10]

  • Required only when <conn_type> is 3-5

<username>:

Login username

  • Maximum length: 64 bytes

<password>:

Login password

  • Maximum length: 64 bytes

Error Codes

  • 1: Parameters error

  • 2: Malloc failed

  • 3: Connection error

  • 8: Already connected to broker

  • 14: Main task create failed

Example

Connect to broker.hivemq.com on port 8883 with the login username “rs” and password “12345678”, and verify the server with CA certificate from certificate suite 1:

AT+MQTTCONN=0,broker.hivemq.com,8883,publisher,3,1,rs,12345678

OK
[$][MQTT][EVENT]:linkid:0, connected

Connect to broker.hivemq.com on port 1883 without a login username and password:

AT+MQTTCONN=0,broker.hivemq.com,1883,publisher,1

OK
[$][MQTT][EVENT]:linkid:0, connected

Connect with default port:

AT+MQTTCONN=0,broker.hivemq.com,,publisher,1

OK
[$][MQTT][EVENT]:linkid:0, connected

AT+MQTTDISCONN

Function Description

Disconnect the specified MQTT connection and release the resource.

Command Format

AT+MQTTDISCONN=<link_id>

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

Parameters

<link_id>:

Link ID - Range [0,3]

Error Codes

  • 1: Parameters error

  • 4: Disconnection failed

Example

Close connection:

AT+MQTTDISCONN=0

OK

AT+MQTTSUB

Function Description

Subscribe an MQTT topic, supporting up to 5 topics.

Command Format

AT+MQTTSUB=<link_id>,<topic>,<qos>

Response Format

Successful Response:

OK

If the topic is already subscribed, it will prompt:

OK

ALREADY SUBCRIBE

Error Response:

ERROR:<error_no>

AT Messages

When subscription is successful, the following prompt message will be displayed:

[$][MQTT][EVENT]:linkid:<link_id>, subscribed

When an MQTT message is received on the subscribed topic, the following prompt message will be displayed:

[$][MQTT][DATA][<link_id>][<topic>][<msg_id>][<msg_len>]:<msg>

In case of an exception, the following prompt message will be displayed:

[$][MQTT][EVENT]:linkid:<link_id>, ERROR:<err_no>

Note

For the specific definitions of err_no, please refer to unified MQTT error

Parameters

<link_id>:

Link ID

  • Range [0,3]

<topic>:

Topic to be subscibed

  • Maximum length: 128 bytes

<qos>:

QoS of the topic to be subscribed

  • Range [0,2]

Error Codes

  • 1: Parameters error

  • 2: Malloc failed

  • 7: Connection not exist

  • 10: Subscribe failed

  • 13: Time out

Example

Subscribe topic LASS/Test/Pm25Ameba/#:

AT+MQTTSUB=0,LASS/Test/Pm25Ameba/#,1

OK
[$][MQTT][EVENT]:linkid:0, subscribed

Receiving messages from the subscribed topic:

[$][MQTT][DATA][0][LASS/Test/Pm25Ameba/FT1_018][102][14]:This is a test

AT+MQTTUNSUB

Function Description

Unsubscribe a specified topic.

Command Format

AT+MQTTUNSUB=<link_id>,<topic>

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

AT Messages

When unsubscription is successful, the following prompt message will be displayed:

[$][MQTT][EVENT]:linkid:<link_id>, unsubscribed

In case of an exception, the following prompt message will be displayed:

[$][MQTT][EVENT]:linkid:<link_id>, ERROR:<err_no>

Note

For the specific definitions of err_no, please refer to unified MQTT error

Parameters

<link_id>:

Link ID

  • Range [0,3]

<topic>:

Topic to be unsubscribed

  • Maximum length: 128 bytes

Error Codes

  • 1: Parameters error

  • 7: Connection not exist

  • 11: Unsubscribe failed

  • 13: Time out

Example

Unsubscribe topic LASS/Test/Pm25Ameba/#:

AT+MQTTUNSUB=0,LASS/Test/Pm25Ameba/#

OK
[$][MQTT][EVENT]:linkid:0, unsubscribed

AT+MQTTPUB

Function Description

Publish a message for specific topic.

Command Format

AT+MQTTPUB=<link_id>,<msg_id>,<topic>,<msg>,<qos>,<retain>

Response Format

Successful Response:

OK

Error Response:

ERROR:<error_no>

AT Messages

  • When publish is successful, the following prompt message will be displayed:

    [$][MQTT][EVENT]:linkid:<link_id>, published

  • In case of an exception, the following prompt message will be displayed:

    [$][MQTT][EVENT]:linkid:<link_id>, ERROR:<err_no>

Note

For the specific definitions of err_no, refer to unified MQTT error

Parameters

<link_id>:

Link ID

  • Range [0,3]

<msg_id>:

Message ID

  • Range [0,65535]

<topic>:

Target Topic

  • Maximum length: 128 bytes

  • It is suggested to fill a topic subscribed before

<msg>:

Message Content

  • Maximum length: 512 bytes

<qos>:

QoS of message

  • Range [0,2]

  • Default value: 0

<retain>:

Retain value

  • Range [0,1]

  • Default value: 0

Error Codes

  • 1: Parameters error

  • 2: Malloc failed

  • 7: Connection not exist

  • 9: Publish failed

  • 13: Time out

Example

Publish a message for topic LASS/Test/Pm25Ameba/FT1_018:

AT+MQTTPUB=0,1,LASS/Test/Pm25Ameba/FT1_018,This is a test,1,1

OK
[$][MQTT][EVENT]:linkid:0, published

AT+MQTTPUBRAW

Function Description

Publish a message of a specified length for specific topic using Transparent Transmission (TT) Mode.

Note

This command is only supported in Host Control Mode.

Command Format

AT+MQTTPUBRAW=<link_id>,<msg_id>,<topic>,<length>,<qos>,<retain>

Response Format

Successful Response:

OK
[$][MQTT][EVENT]:linkid:<link_id>, published

Error Response:

ERROR:<error_no>

Parameters

<link_id>:

Link ID

  • Range [0,3]

<msg_id>:

Message ID

  • Range [0,65535]

<topic>:

Target Topic

  • Maximum length: 128 bytes

  • It is suggested to fill a topic subscribed before

<length>:

Message Length (bytes)

  • Maximum length: 10240 bytes

<qos>:

QoS of message

  • Range [0,2]

  • Default value: 0

<retain>:

Retain value

  • Range [0,1]

  • Default value: 0

Error Codes

  • 1: Parameters error

  • 2: Malloc failed

  • 5: Enter TT mode failed

  • 7: Connection not exist

  • 9: Publish failed

  • 13: Time out

Example

Send 14 bytes of text message:

AT+MQTTPUBRAW=0,2,LASS/Test/Pm25Ameba/FT1_018,14,1,1
>>>
This is a test

OK
[$][MQTT][EVENT]:linkid:0, published

AT+MQTTRESET

Function Description

Reset all MQTT entities and release resource

Command Format

AT+MQTTRESET

Response Format

Successful Response:

OK

Note

If there are any running MQTT entities, they will be disconnected, and all related resources will be released.

Example

MQTT reset:

AT+MQTTRESET
OK

AT+MQTTQUERY

Function Description

Query the status and configuration information of a specified connection.

Command Format

AT+MQTTQUERY=<link_id>

Response Format

Successful Response:

link_id: <Link ID>
state: <Connection state, 0: Not Connected, 1: Connected>
conn_type: <Connection type>
host: <Broker domain>
port: <Broker port>
cliend_id: <Client ID>
username: <Login username>
password: <Login password>
cmd_timeout: <Connect/Subscribe timeout (seconds)>
keepalive: <Ping timeout (seconds)>
disable_clean_session: <Clean session option>
LWT: <LWT flag>
lwt_qos: <LWT QoS>
lwt_retain: <LWT retain>
lwt_topic: <LWT message topic>
lwt_msg: <LWT message>

OK

Error Response:

ERROR:<error_no>

Parameters

<link_id>:

Link ID

  • Range [0,3]

Error Codes

  • 1: Parameters error

Example

Query information for link ID 0:

AT+MQTTQUERY=0

link_id: 0
state: 1
conn_type: 1
host: broker.hivemq.com
port: 1883
client_id: publisher
username: rs
password: 12345678
cmd_timeout: 60
keepalive: 20
disable_clean_session: 0
LWT: 1
lwt_qos: 0
lwt_retain: 0
lwt_topic: topic/lwt
lwt_message: This is a lwt message

OK

AT+MQTTSUBQUERY

Function Description

List all subscribed topics.

Command Format

AT+MQTTSUBQUERY=<link_id>

Response Format

Successful Response:

link_id: <link_id>
state: <isconnected>
topic: <topic1>, qos: <topic1_qos>
topic: <topic2>, qos: <topic2_qos>
...

OK

Error Response:

ERROR:<error_no>

Parameters

<link_id>:

Link ID

  • Range [0,3]

Error Codes

  • 1: Parameters error

Example

List all subscribed topics for link ID 0:

AT+MQTTSUBQUERY=0

link_id: 0
state: 1
topic: LASS/Test/Pm25Ameba/#, qos: 1

OK