- Support portal
- Evaluation Kits and partner products
u-blox Support
- Product documentation
Documentation
- About
- Sustainability
- Partners and Alliances
- Contact
About u-blox
- Investor relations
Investor relations
MQTT AT commands are implemented according to MQTT version 3.1.1. For a more detailed overview on MQTT protocol, see MQTT version 3.1.1 - OASIS standard [MQTT-V3.1.1-OS].
The Message Queueing Telemetry Transport (MQTT) protocol specifies a simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency, or unreliable networks. An MQTT client uses publish and subscribe methods to interact over a TCP connection with an MQTT message broker (henceforth referred to as an MQTT server). u-blox modules can be configured to operate as an MQTT client.
To publish or subscribe, the MQTT client must first establish a TCP connection to an MQTT server.
The MQTT protocol specifies case-sensitive topics, with topic names containing topic level separators “/” to which messages will be published. For example, a message of “78 Fahrenheit or 25 Celsius” could be published to the topic name of “/heat/sensor/SD/bldg5/DelMarConfRm”. MQTT clients subscribe to topic filters to determine if the client receives messages published to a given topic name.
The topic filters may exactly specify a topic name or may contain either of the following wildcards:
‘+’ - (single level wildcard) applies to a single topic level;
‘#’ - (multi-level wildcard) applies to potentially many topic levels (and must be the last character specified in a topic filter).
‘#’ can be specified on its own or following a topic level separator (‘/’). For example, the topic filter, “/heat/sensor/SD/#”, would receive any messages published to the “/heat/sensor/SD/bldg5/DelMarConfRm” topic name.
MQTT specification states that topic filters starting with either wildcard will not match any topic name that starts with “$”.
The MQTT protocol also specifies a Quality of Service (QoS) level to be applied to message transactions:
0 (default setting): at most once delivery
1: at least once delivery
2: exactly once delivery
The MQTT protocol also allows an MQTT client to create a will message, which the MQTT remote server will store and only publish (to the topic name specified as the will topic name) when the MQTT client gets disconnected from the MQTT server, but not if the MQTT client explicitly sends a disconnect command.
A PSD connection must be active before using MQTT AT commands. Some products require additional commands to provide connectivity to the application.
If not specified, the <cid> and the <preferred_protocol_type> parameters set by means of the +UDCONF=19 AT command are used.
See +CGACT AT command for activating a PDP context.
+UMQTT | ||||||
Modules | LEXI-R10401D-00B LEXI-R10801D-00B | |||||
Attributes | Syntax | PIN required | Settings saved | Can be aborted | Response time | Error reference |
partial | No | No | - |
Configures or reads the parameter value of an MQTT client profile. Issue a set command for each <op_code> parameter to set all of the parameters in an MQTT client profile.
Type | Syntax | Response | Example |
---|---|---|---|
Generic syntax | |||
Set | AT+UMQTT=<op_code>[,<param1>[,<param2>]] | +UMQTT: <op_code>,<result> OK | AT+UMQTT=12,1 +UMQTT: 12,1 OK |
MQTT unique client ID | |||
Set | AT+UMQTT=0,<client_id> | +UMQTT: 0,<result> OK | AT+UMQTT=0,"352753090041680" +UMQTT: 0,1 OK |
MQTT local TCP port number | |||
Set | AT+UMQTT=1,<local_port> | +UMQTT: 1,<result> OK | AT+UMQTT=1,1883 +UMQTT: 1,1 OK |
MQTT server name | |||
Set | AT+UMQTT=2,<server_name>[,<server_port>] | +UMQTT: 2,<result> OK | AT+UMQTT=2,"www.commercialmqttbroker.com" +UMQTT: 2,1 OK |
MQTT server IP address | |||
Set | AT+UMQTT=3,<IP_address>[,<server_port>] | +UMQTT: 3,<result> OK | AT+UMQTT=3,"192.168.1.0",1883 +UMQTT: 3,1 OK |
User name and password | |||
Set | AT+UMQTT=4,<username>,<password> | +UMQTT: 4,<result> OK | AT+UMQTT=4,"test","abc123" +UMQTT: 4,1 OK |
Last will QoS | |||
Set | AT+UMQTT=6,<will_QoS> | OK | AT+UMQTT=6,1 OK |
Last will retain | |||
Set | AT+UMQTT=7,<will_retain> | OK | AT+UMQTT=7,1 OK |
Last will topic | |||
Set | AT+UMQTT=8,<will_topic> | OK | AT+UMQTT=8,"u-blox/publish" OK |
Last will message | |||
Set | AT+UMQTT=9,<will_message>[,<hex_mode>] | OK | AT+UMQTT=9,"Unrequested disconnect" OK |
Keep alive and linger time | |||
Set | AT+UMQTT=10,<keep_alive>[,<linger_time>] | +UMQTT: 10,<result> OK | AT+UMQTT=10,3600,20 +UMQTT: 10,1 OK |
MQTT secure option | |||
Set | AT+UMQTT=11,<MQTT_secure>[,<usecprf_profile_id>] | +UMQTT: 11,<result> OK | AT+UMQTT=11,1,2 +UMQTT: 11,1 OK |
MQTT clean session | |||
Set | AT+UMQTT=12,<clean_session> | +UMQTT: 12,<result> OK | AT+UMQTT=12,1 +UMQTT: 12,1 OK |
MQTT server response time | |||
Set | AT+UMQTT=13,<server_response_time> | OK | AT+UMQTT=13,60 OK |
MQTT topic filtering | |||
Set | AT+UMQTT=15,<topic_filtering> | OK | AT+UMQTT=15,0 OK |
MQTT PDP context configuration | |||
Set | AT+UMQTT=20,<cid>[,<preferred_protocol_type>] | OK | AT+UMQTT=20,2,1 OK |
Read | AT+UMQTT=<op_code> | +UMQTT: <op_code>,<param1>[,<param2>] OK | AT+UMQTT=4 +UMQTT: 4,"my_username" OK |
Read | AT+UMQTT? | +UMQTT: 0,<client_id> +UMQTT: 2,<server_name>,<server_port> +UMQTT: 3,IP_address>,<server_port> +UMQTT: 4,<username> +UMQTT: 6,<will_QoS> +UMQTT: 7,<will_retain> +UMQTT: 8,<will_topic> +UMQTT: 9,<wm_length>,<will_message> +UMQTT: 10,<keep_alive>,<linger_time> +UMQTT: 11,<MQTT_secure>[,<usecprf_profile_id>] +UMQTT: 12,<clean_session> +UMQTT: 13,<server_response_time> +UMQTT: 15,<topic_filtering> +UMQTT: 20,<cid>,<preferred_protocol_type> OK | +UMQTT: 0,"352848080012186" +UMQTT: 2,"",1883 +UMQTT: 3,"",1883 +UMQTT: 4,"" +UMQTT: 6,0 +UMQTT: 7,0 +UMQTT: 8,"" +UMQTT: 9,0,"" +UMQTT: 10,0,10 +UMQTT: 11,0 +UMQTT: 12,1 +UMQTT: 13,30 +UMQTT: 15,1 +UMQTT: 20,1,0 OK |
Test | AT+UMQTT=? | +UMQTT: (list of supported <op_code>s) OK | +UMQTT: (0,2-4,6-13,15,20) OK |
URC | +UUMQTT<op_code>: <param1>[,<param2>] | +UUMQTT0: "352753090041680" |
Parameter | Type | Description |
---|---|---|
<op_code> | Number | MQTT parameter:
Allowed values:
|
<result> | Number | Allowed values:
|
<client_id> | String | Client identifier for the MQTT session.
The default value is the IMEI of the MT. |
<local_port> | Number | MQTT client TCP port. The range goes from 1 to 65535. If the MQTT client port number is not specified, the default port number is the IANA assigned port of 1883 for non-TLS MQTT and 8883 for TLS MQTT. |
<server_name> | String | Remote server name.
The default value is an empty string. |
<IP_address> | String | Remote server IP address. The default value is an empty string. For IP address format reference, see the IP addressing. |
<server_port> | Number | MQTT server port. The range goes from 1 to 65535. The default value is 1883 for non-TLS MQTT, 8883 for TLS MQTT.
|
<username> | String | User name for the MQTT login procedure. The default value is an empty string:
|
<password> | String | Password for the MQTT login procedure. The default value is an empty string:
|
<keep_alive> | Number | Keep alive time expressed in seconds. According to the MQTT specification, an MQTT server must disconnect a client if it receives nothing from the client within 1.5x the keep alive time. If the keep alive value is 0 the server is not required to disconnect. The default value is 0. The maximum value is 65535 (corresponding to 18 hours, 12 minutes and 15 seconds). |
<linger_time> | Number | Linger time expressed in seconds. The range goes from 0 to 120 s; 0 means linger time is not set. The default value is 10 s. |
<will_QoS> | Number | MQTT last will Quality of Service:
|
<will_retain> | Number | Whether or not the last will message will be retained across disconnects:
|
<will_topic> | String | Last will topic name. The default value is an empty string.
|
<will_message> | String | Last will message: string of characters (ASCII or hexadecimal octets).
In case of hexadecimal data, the number of characters must be even (one hexadecimal octet is composed of 2 characters). |
<hex_mode> | Number | Allowed values:
|
<wm_length> | Number | Two meanings:
|
<MQTT_secure> | Number | Enables / disables the secure option of MQTT service:
|
<usecprf_profile_id> | Number | USECMNG profile (number). Defines the USECMNG profile which specifies the SSL/TLS properties to be used for the SSL/TLS connection. The range goes from 0 to 4. If no profile is set a default USECMNG profile is used (see +USECMNG AT command description). |
<clean_session> | Number | Clean session value. Allowed values:
|
<cid> | Number | PDP context identifier used for the MQTT communication. The allowed range is product specific, see <cid>. For more details on the default value of the parameter (where supported), see MQTT. |
<preferred_protocol_type> | Number | Preferred protocol type to be specified when the <cid> protocol type is IPv4v6. Allowed values:
For more details on the default value of the parameter (where supported), see MQTT. |
<server_response_time> | Number | Indicates the maximum waiting time of a server response after a request was sent to the server via +UMQTTC AT command. It is expressed in seconds. The default value is 30 s. The range goes from 5 s to 255 s (corresponding to 4 minutes and 15 seconds). |
<topic_filtering | Number | Enables / disables the topic filtering: match of the incoming PUBLISH packets topic with the previously subscribed topics. Allowed values:
|
<param1> | Number / String | Type and supported content depend on the related <op_code> parameter (details are given above). If <param1> is not specified the value of the corresponding parameter <op_code> is reset to the default value. |
<param2> | Number / String | Type and supported content depend on the related <op_code> parameter (details are given above). If <param2> is not specified the value of the corresponding parameter <op_code> is reset to the default value. |
The information text response to the read command does not display the password.
Some network operators do not allow secure MQTT. In this case the AT+UMQTTC=1 command (MQTT login) will return a failure response by means of the +UUMQTTC URC after an TLS timeout of 30 s.
The set command does not provide the +UMQTT: <op_code>,<result> information text response: only the final result code is issued.
The +UUMQTT URC is not supported.
See the Mobile termination error result codes +CME ERROR for the allowed error result codes.
<op_code>=2 (MQTT server name) and <op_code>=3 (MQTT IP address) are equivalent and mutually exclusive: if value for <op_code>=2 is specified by user, then value for <op_code>=3 is reset or vice versa.
<op_code>=12 (clean session) is supported only to maintain server-side persistence (subscription). Disable topic filtering (AT+UMQTT=15,0) to receive the pending publish packets not delivered by the server while the module is disconnected.
LEXI-R10401D / LEXI-R10801D
The MQTT session is always cleaned on disconnection.
<op_code>=15 (MQTT topic filtering) is not supported.
+UMQTTNV | ||||||
Modules | LEXI-R10401D-00B LEXI-R10801D-00B | |||||
Attributes | Syntax | PIN required | Settings saved | Can be aborted | Response time | Error reference |
full | No | No | No | - |
Either saves all of the MQTT client profile parameters to NVM (non-volatile memory) or sets all of the MQTT client profile parameters to either factory-programmed or non-volatile stored values.
For the complete list of parameters that can be stored in the NVM, see the +UMQTT AT command.
The set command does not provide the information text response: only the final result code is issued.
Type | Syntax | Response | Example |
---|---|---|---|
Set | AT+UMQTTNV=<NVM_mode> | [+UMQTTNV: <NVM_mode>,<result>] OK | AT+UMQTTNV=2 +UMQTTNV: 2,1 OK |
Test | AT+UMQTTNV=? | +UMQTTNV: (list of <NVM_mode>s) OK | +UMQTTNV: (0-2) OK |
Parameter | Type | Description |
---|---|---|
<NVM_mode> | Number | Operation to set or save the MQTT client profile parameters as follows:
|
<result> | Number | Operation result:
|
+UMQTTC | ||||||
Modules | LEXI-R10401D-00B LEXI-R10801D-00B | |||||
Attributes | Syntax | PIN required | Settings saved | Can be aborted | Response time | Error reference |
partial | Yes | No | No |
Triggers the MQTT actions corresponding to the <op_code> parameter. The final result code indicates if sending the command request to the MQTT process was successful or not.
The +UUMQTTC URC provides the result of the requested action from the MQTT broker. In addition, the +UUMQTTC URC also provides notification that unread messages are available from the MQTT server. The +UUMQTTC URC is by default enabled.
An MQTT command can be considered completed only after receiving the related +UUMQTTC URC.
The “+CME ERROR: operation not allowed” error result code is returned if an MQTT command is entered before the previous one is completed.
The +UUMQTTC: 0,100 URC is notified when the MQTT broker releases the connection after a period of inactivity (keep alive time expired).
The +UUMQTTC: 0,101 URC is notified when the network connection is lost.
The +UUMQTTC: 0,102 URC is notified when the MT releases the connection because there is a protocol violation in receiving an MQTT message.
Type | Syntax | Response | Example |
---|---|---|---|
Generic syntax | |||
Set | AT+UMQTTC=<op_code>[,<param1>[,<param2>][,<param3>][,<param4>][,<param5>]] | OK | AT+UMQTTC=1 OK |
URC | +UUMQTTC: <op_code>,<param1>[,<param2>,<param3>] | +UUMQTTC: 4,0,2,"sensor/heat/#" | |
MQTT logout | |||
Set | AT+UMQTTC=0 | OK | AT+UMQTTC=0 OK |
URC | +UUMQTTC: 0,<logout_result> | +UUMQTTC: 0,1 | |
MQTT login | |||
Set | AT+UMQTTC=1 | OK | AT+UMQTTC=1 OK |
URC | +UUMQTTC: 1,<MQTT_result> | +UUMQTTC: 1,1 | |
MQTT publish to a topic | |||
Set | AT+UMQTTC=2,<QoS>,<retain>,[<hex_mode>],<topic_name>,<pub_msg> | OK | AT+UMQTTC=2,0,0,0,"sensor/heat/SD/bldg5/DelMarConfRm","23 degrees Celsius" OK |
AT+UMQTTC=2,0,0,1,"sensor/heat/SD/bldg5/DelMarConfRm","323320646567726565732043656C73697573" OK | |||
URC | +UUMQTTC: 2,<MQTT_result> | +UUMQTTC: 2,1 | |
MQTT publish a file to a topic | |||
Set | AT+UMQTTC=3,<QoS>,<retain>,<topic_name>,<filename> | OK | AT+UMQTTC=3,0,0,"home/u-blox","msg.txt" OK |
URC | +UUMQTTC: 3,<MQTT_result> | +UUMQTTC: 3,1 | |
MQTT subscribe to the specified topic filter | |||
Set | AT+UMQTTC=4,<max_QoS>,<topic_filter> | OK | AT+UMQTTC=4,0,"sensor/heat/#" OK |
URC | +UUMQTTC: 4,<MQTT_result>[,<QoS>,<topic_name>] In case of success +UUMQTTC: 4,1,<QoS>,<topic_name> In case of failure +UUMQTTC: 4,0 | +UUMQTTC: 4,1,0,"sensor/heat/#" | |
MQTT unsubscribe from the specified topic filter | |||
Set | AT+UMQTTC=5,<topic_filter> | OK | AT+UMQTTC=5,"sensor/heat/#" OK |
URC | +UUMQTTC: 5,<MQTT_result> | +UUMQTTC: 5,1 | |
MQTT read message | |||
Set | AT+UMQTTC=6[,[<one_message>][,<hex_mode_out>]] | +UMQTTC: 6,<QoS>,<topic_msg_length>,<topic_length>,<topic_name>,<read_msg_length>,<read_msg> OK | AT+UMQTTC=6,1 +UMQTTC: 6,0,31,13,"sensor/heat/#",18,"23 degrees Celsius" OK AT+UMQTTC=6,,1 +UMQTTC: 6,0,31,13,"sensor/heat/#",18,"323320646567726565732043656C73697573" OK |
URC | +UUMQTTC: 6,<num_unread_msgs>,<memory_full> | +UUMQTTC: 6,3,0 | |
Ping MQTT broker | |||
Set | AT+UMQTTC=8,<ping_ON_OFF> | OK | AT+UMQTTC=8,1 OK |
URC (only in case of no ping response received) | +UUMQTTC: 8,0 | +UUMQTTC: 8,0 | |
Publish a binary message to a topic | |||
Set | AT+UMQTTC=9,<QoS>,<retain>,<topic_name>,<pub_msg_length> After the ">" prompt <pub_msg_length> bytes of data are entered | ><pub_bin_message> OK | AT+UMQTTC=9,1,0,"u-blox/test",33 >AABB-→ execute this \nand "this" OK |
URC | +UUMQTTC: 9,<MQTT_result> | +UUMQTTC: 9,1 | |
Test | AT+UMQTTC=? | +UMQTT: (list of supported <op_codes>s) OK | +UMQTTC: (0-9) OK |
Parameter | Type | Description |
---|---|---|
<op_code> | Number | MQTT command request.
Allowed values:
|
<MQTT_result> | Number | Result of an MQTT command request:
|
<login_result> | Number | Result of an MQTT login request. Allowed values:
|
<logout_result> | Number | Result of an MQTT command request:
Result of an unsolicited notification for an MQTT session interruption caused by:
|
<QoS> | Number | Quality of service:
|
<retain> | Number | Whether or not the message will be retained across disconnects. Allowed values:
|
<hex_mode> | Number | Allowed values:
|
<pub_msg> | String | ASCII or hexadecimal data.
|
<message> | String | ASCII or hexadecimal data. The maximum length is 256 characters. The starting quotation mark shall not be taken into account like data. At the end of the byte stream, another quotation mark is provided for user convenience and visualization purposes. |
<filename> | String | Filename containing the message to be published.
|
<max_QoS> | Number | Maximum QoS level at which the MQTT broker can send messages to the MT. For more details, see MQTT version 3.1.1 - OASIS standard [MQTT-V3.1.1-OS].
|
<topic_filter> | String | An expression to indicate an interest in one or more topics, wildcard characters are used to subscribe/unsubscribe to multiple topics at once. See MQTT introduction.
|
<topic_name> | String | Indicates the topic to which the given MQTT message was published.
|
<reason> | Number | Result of an MQTT subscribe request:
|
<num_unread_msgs> | Number |
|
<format> | Number | Specifies the format of the messages when read using the <op_code>=6. Allowed values:
|
<mqtt_server> | String | IP address or URL of MQTT server. |
<one_message> | Number | Allowed values:
|
<topic_msg_length> | Number | Sum of topic and message length |
<topic_length> | Number | Topic length |
<msg_length> | Number | Specifies the number of octets in <message> for <op_code>=6 (MQTT read message) |
<read_msg_length> | Number | Specifies the number of octets in <read_msg> |
<read_msg> | String | Message received from MQTT server.
|
<ping_ON_OFF> | Number | Allowed values:
|
<memory_full> | Number | Indicates the message memory status. Allowed values:
|
<pub_msg_length> | Number | Specifies the number of octets in <pub_bin_message>.
|
<pub_bin_message> | String | Data bytes to be published. |
<hex_mode_out> | Number | Allowed values:
|
The topic name should not include any wildcards for the publish commands.
The topic filter could include the ‘+’ wildcard to substitute for a single topic folder or the ‘#’ wildcard to substitute for any number of topic folders. The ‘#’ wildcard must be the last character in a topic filter.
The <memory_full> parameter is not supported.
If <hex_mode>=1, the publishing message (<pub_msg> parameter) contains a string of hexadecimal nibbles that is transformed into a bytes sequence.
Publish a binary message to a topic:
This feature can be successfully used when there is need to send characters like <CR>, <CTRL-Z>, quotation marks, etc. These characters have a specific meaning and they cannot be used like data in the command itself. For more details, see 3GPP TS 27.005 [27.005].
After the command is sent, the user waits for the > prompt. When it appears the stream of bytes can be provided. After the specified amount of bytes has been sent, the system provides the final result code. The feed process cannot be interrupted i.e. the return in the command mode can be effective only when the number of bytes provided is the declared one.
In binary mode the module does not display the echo of data bytes.
MQTT binary mode sets the AT terminal to direct link mode, thus direct link limitations apply for this command as well. Only one direct link connection at a time can be activated. When considering the number of active direct links, take into account also the connection established by the +USODL AT command, the UHTTP direct link mode (see parameters http_command=6 and http_command=7 in +UHTTPC command), the +USOWR AT command for binary mode and the +FREAD AT command.
If <QoS>=1 or <QoS>=2, the publish command does not automatically retry to send the packet after a timeout failure. Furthermore, it is not possible to manually send an exact duplicate of the original MQTT packet.
The time to establish the secure session (when using +UMQTT: 11,1[,<usecprf_profile_id>]) could require up to 150 s in one of these cases:
RoT generated PSK (+USECPRF: <profile_id>,11)
encrypted session resumption (+USECPRF: <profile_id>,13,2,10)
This is due to “security heartbeat” message operation. For more details on when this scenario occurs, see the +USECCONN AT command.
The PING command activates an internal loop of ping requests and responses to and from the MQTT server. The ping requests are sent when the MQTT keep alive time period expires (see MQTT version 3.1.1
OASIS standard [MQTT-V3.1.1-OS]). Before establishing a connection with the server the keep alive time must be set to a non-zero value, see AT+UMQTT=10. Avoid a value of few seconds otherwise the application will be busy in sending ping requests at the expense of other MQTT requests.
+UMQTTER | ||||||
Modules | LEXI-R10401D-00B LEXI-R10801D-00B | |||||
Attributes | Syntax | PIN required | Settings saved | Can be aborted | Response time | Error reference |
partial | No | No | No | - |
Retrieves the error class and code of the last MQTT operation that provided an error.
Type | Syntax | Response | Example |
---|---|---|---|
Action | AT+UMQTTER | +UMQTTER: <error_code1>,<error_code2> OK | AT+UMQTTER +UMQTTER: 1,1 OK |
Parameter | Type | Description |
---|---|---|
<error_code1> | Number |
|
<error_code2> | Number |
|