MQTT AT Commands#
This section describes AT commands for the Message Queue Telemetry Transport (MQTT) protocol using Transport Control Protocol (TCP) sockets from the SiWx91x network processor. MQTT clients over WebSockets from the SiWx91x application processor are not currently supported.
Commands#
mqtt-client-init#
Initialize the MQTT client on the SiWx91x device.
Command Format#
at+mqtt-client-initRelated SDK API
Pre-conditions#
None
Parameters#
None
Response#
OK <client-instance-id>on success, whereclient-instance-idis a unique identifier for the MQTT client instance on the SiWx91x device.ERROR <error code>in case of failure. Possible error codes are the same as those returned by the sl_mqtt_client_init API.
Notes#
At present, you can call the mqtt-client-init command only once unless you first call mqtt-client-deinit. Only one MQTT client instance is supported. Theclient-instance-id value is always returned as 0 and must be passed as 0 in all subsequent mqtt-client- commands. The client-instance-id parameter is provided for forward compatibility in case a future release adds support for multiple MQTT client instances.
Examples#
at+mqtt-client-init
OK 0mqtt-client-conncfg#
Configure settings for connecting to an MQTT broker.
Command Format#
at+mqtt-client-conncfg=<client-instance-id>,<ip-addr-type>,<ip-addr>,<port>,<connect-timeout>,<keep-alive-interval>,<keep-alive-retries>[,<host-name>][,<enable-sni>][,<sni-host-name>]Related SDK API
Pre-conditions#
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance to configure. Currently always set to 0 as there is only one MQTT client instance supported.
ip-addr-type#
The type of IP address (for example, IPv4 or IPv6). Contains a numeric value that corresponds to one of the enum sl_ip_address_type_t values.
ip-addr#
A string containing either an IPv4 or IPv6 address.
port#
The port to connect to on the host running the MQTT broker.
connect-timeout#
The timeout in milliseconds after which connection to the MQTT broker is aborted.
keep-alive-interval#
The interval in milliseconds at which keep-alive packets are sent to the MQTT broker.
keep-alive-retries#
The number of times the keep-alive packet is re-transmitted in case of transmission failure.
host-name#
Optional. A string containing the MQTT hostname. This parameter is currently not supported. It can be omitted and is ignored if passed.
enable-sni#
Optional. Set to 1 or 0 to enable or disable the use of a Server Name Indication (SNI) in the TLS handshake.
sni-host-name#
Optional. A string containing the hostname to use in SNI.
Response#
OKon successERROR 1in case of failure
Notes#
When this command is sent for the first time, the SiWx91x device initializes an sl_mqtt_broker_v2_t structure with the parameters passed to this command.
When this command is sent again, the sl_mqtt_broker_v2_t structure is overwritten with the parameters passed to this command.
The sl_mqtt_broker_v2_t structure is passed as a parameter to the sl_mqtt_client_connect_v2 API in response to the mqtt-client-conn command.
Examples#
at+mqtt-client-conncfg=0,4,"192.168.10.1",1883,60000,30000,3 # Configure MQTT broker connection settings
OK
at+mqtt-client-conncfg=0,4,"192.168.10.1",1883,60000,30000,3,,1,"sni.example.com" # Configure MQTT broker connection settings with SNI enabled
OKmqtt-client-conninfo#
Query the current MQTT client connection information and state on the SiWx91x device.
Command Format#
at+mqtt-client-conninfo=<client-instance-id>Related SDK API
Pre-conditions#
Parameters#
client-instance-id#
Unique identifier for the MQTT client instance (currently only 0 is supported).
Response#
OK <connection-state> <broker-ip> <broker-port> <connect-timeout> <keep-alive-interval> <keep-alive-retries> <host-name> <enable-sni> <sni-host-name>on success, where:connection-stateis the current state of the MQTT client connection, with one of the following possible values:DISCONNECTED: Client is not connected to the brokerCONNECTION_FAILED: Connection attempt to the broker failedCONNECTED: Client is successfully connected to the brokerNWP_INIT: Network processor has been successfully initializedNWP_DISCONNECTED: Network processor is disconnected
broker-ipis the IP address of the MQTT broker in dotted decimal format (e.g., "192.168.1.100") or "0.0.0.0" if not configuredbroker-portis the port number of the MQTT broker (typically 1883 for unencrypted, 8883 for encrypted) or 0 if not configuredconnect-timeoutis the MQTT connection timeout in millisecondskeep-alive-intervalis the keep-alive interval of the MQTT connection in millisecondskeep-alive-retriesis the number of retries that are performed for the MQTT keep-alive messagehost-nameis the MQTT hostname string, or empty string if not configuredenable-sniindicates whether SNI is enabled (1 = enabled, 0 = disabled)sni-host-nameis the hostname string used in SNI, or empty string if not configured
ERROR 1in case of failure
Notes#
The host-name parameter of mqtt-client-conncfg is not currently supported and its value is ignored.
Examples#
at+mqtt-client-conninfo=0 # Query MQTT client connection information
OK CONNECTED 192.168.10.1 1883 60000 30000 3 "" 0 "" # Response: Connected, SNI disabled
at+mqtt-client-conninfo=0 # Query MQTT client connection information
OK CONNECTED 192.168.10.1 1883 60000 30000 3 "" 1 "sni.example.com" # Response: Connected, SNI enabledmqtt-client-opt#
Configure MQTT client options.
Command Format#
at+mqtt-client-opt=<client-instance-id>,<auto-reconnect>,<connect-retries>,<min-back-off-time>,<max-back-off-time>,<clean-session>,<mqtt-version>,<port>,<credential-id>,<client-id>,<tls-flags>Related SDK API
Pre-conditions#
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance to configure. Currently always set to 0 as there is only one MQTT client instance supported.
auto-reconnect#
Set to 1 or 0 to indicate whether or not the SiWx91x device should automatically re-connect to the MQTT broker when the connection is lost.
connect-retries#
The number of times to automatically attempt re-connection to the MQTT broker when the connection is lost.
min-back-off-time#
The minimum amount of time in milliseconds to back off between two automatic re-connection attempts.
max-back-off-time#
The maximum amount of time in milliseconds to back off between two automatic re-connection attempts.
clean-session#
Set to 1 or 0 to indicate whether or not to establish a clean MQTT session on connection.
mqtt-version#
MQTT protocol version used by the MQTT client.
port#
The port number on the SiWx91x device used to connect to the MQTT broker.
credential-id#
The unique credential identifier for the MQTT client username and password used to authenticate the client to the MQTT broker, previously saved using the net-cred-mqttclient command.
client-id#
A string used to uniquely identify the MQTT client to the MQTT broker.
tls-flags#
TLS connection options, represented as a bitmap as described in the documentation for the enum sl_mqtt_tls_flag_t.
Response#
OKon successERROR 1in case of failure
Notes#
When this command is sent for the first time, the SiWx91x device initializes an sl_mqtt_client_configuration_t structure with the parameters passed to this command.
When this command is sent again, the sl_mqtt_client_configuration_t structure is overwritten with the parameters passed to this command.
The sl_mqtt_client_configuration_t structure is passed as a parameter to the sl_mqtt_client_connect_v2 API in response to the mqtt-client-conn command.
Examples#
at+mqtt-client-opt=0,1,3,5000,30000,0,5,65001,768,"SilabsMQTTClient",49
OKmqtt-client-optinfo#
Query the current MQTT client options.
Command Format#
at+mqtt-client-optinfo=<client-instance-id>Related SDK API
Pre-conditions#
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance to query. Currently always set to 0 as there is only one MQTT client instance supported.
Response#
OK <auto-reconnect> <connect-retries> <min-back-off-time> <max-back-off-time> <clean-session> <mqtt-version> <port> <credential-id> <client-id> <tls-flags>on success, where:auto-reconnectindicates whether the SiWx91x device should automatically re-connect to the MQTT broker when the connection is lost (1 = enabled, 0 = disabled)connect-retriesis the number of times to automatically attempt re-connection to the MQTT broker when the connection is lostmin-back-off-timeis the minimum amount of time in milliseconds to back off between two automatic re-connection attemptsmax-back-off-timeis the maximum amount of time in milliseconds to back off between two automatic re-connection attemptsclean-sessionindicates whether to establish a clean MQTT session on connection (1 = enabled, 0 = disabled)mqtt-versionis the MQTT protocol version used by the MQTT clientportis the port number on the SiWx91x device used to connect to the MQTT brokercredential-idis the unique credential identifier for the MQTT client username and password used to authenticate the client to the MQTT broker. Set using the net-cred-mqttclient commandclient-idis a string used to uniquely identify the MQTT client to the MQTT brokertls-flagsare the TLS connection options, represented as a bitmap as described in the documentation for the enum sl_mqtt_tls_flag_t
ERROR 1in case of failure
Examples#
at+mqtt-client-optinfo=0
OK 1 3 5000 30000 0 5 65001 768 SilabsMQTTClient 49mqtt-client-lwt#
Configure the Last Will and Testament (LWT) message for the MQTT client.
Command Format#
at+mqtt-client-lwt=<client-instance-id>[,<retained>][,<qos>][,<topic>][,<content-length>]Related SDK API
Pre-conditions#
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance to configure. Currently always set to 0 as there is only one MQTT client instance supported.
retained#
Optional. Set to 1 to retain the LWT message on the MQTT broker, or set to 0 to not retain it.
qos#
Optional. Set to a value between 0 to 2 to indicate the MQTT protocol Quality of Service (QoS) level for the LWT message.
topic#
Optional. A string containing the topic on which the LWT message is published.
content-length#
Optional. The length of the LWT message's content.
Response#
ERROR 1on failing to enter data mode.OKon successfully entering data mode.On receiving this response, you must transmit
content-lennumber of characters.As soon as the given number of characters are transmitted, the LWT message details are saved and one of the following responses is sent back:
OKon successERROR 1in case of failure
Notes#
When you send this command for the first time, the SiWx91x device initializes an sl_mqtt_client_last_will_message_t structure with the parameters passed to this command.
When you send this command again, the device overwrites the sl_mqtt_client_last_will_message_t structure with the parameters passed to this command.
Send this command with only the
client-instance-idparameter to set the sl_mqtt_client_last_will_message_t structure pointer to NULL.This command is optional. The sl_mqtt_client_last_will_message_t structure pointer is set to NULL if this command is never sent.
When a specific parameter is omitted (by sending two commas or just a trailing comma), the corresponding member of the sl_mqtt_client_last_will_message_t structure is set to NULL (in case of a string argument) or its default value (in case of a numeric argument):
Default value is 0 for
retained, 0 forqos, and 0 forcontent-length.contentis set to NULL whencontent-lengthis defaulted to 0.
The sl_mqtt_client_last_will_message_t structure is passed as a parameter to the sl_mqtt_client_connect_v2 API in response to the mqtt-client-conn command.
Examples#
at+mqtt-client-lwt=0,1,2,"wifi/silabs_device_0/lwt",33 # Silabs device 0 has disconnected.
OKmqtt-client-conn#
Connect to an MQTT broker.
Command Format#
at+mqtt-client-conn=<client-instance-id>,<timeout>Related SDK API
Pre-conditions#
mqtt-client-conncfg and mqtt-client-opt if you are sending mqtt-client-conn for the first time.
mqtt-client-discon if you have previously sent mqtt-client-conn.
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance to connect. Currently always set to 0 as there is only one MQTT client instance supported.
timeout#
The duration in milliseconds after which this command returns a timeout status. Set to 0 to make this an asynchronous command. An asynchronous Event message is sent with the status of an asynchronous command.
Response#
OKon successfully completing the command or successfully initiating an asynchronous commandTIMEOUTin case of timeoutERROR <error code>in case of failure. Possible error codes are the same as those returned by the sl_mqtt_client_connect API.
Examples#
at+mqtt-client-conn=0,120000 # Connect MQTT client instance 0 (the only supported instance) with a timeout of 120 seconds
OKmqtt-client-discon#
Disconnect from an MQTT broker.
Command Format#
at+mqtt-client-discon=<client-instance-id>,<timeout>Related SDK API
Pre-conditions#
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance to disconnect. Currently always set to 0 as there is only one MQTT client instance supported.
timeout#
The duration in milliseconds after which this command returns a timeout status. Set to 0 to make this an asynchronous command. An asynchronous Event message is sent with the status of an asynchronous command.
Response#
OKon successfully completing the command or successfully initiating an asynchronous commandTIMEOUTin case of timeoutERROR <error code>in case of failure. Possible error codes are the same as those returned by the sl_mqtt_client_disconnect API.
Examples#
at+mqtt-client-discon=0,120000 # Disconnect MQTT client instance 0 (the only supported instance) with a timeout of 120 seconds
OKmqtt-client-deinit#
De-initialize an MQTT client instance.
Command Format#
at+mqtt-client-deinit=<client-instance-id>Related SDK API
Pre-conditions#
mqtt-client-discon if the mqtt-client-conn command has previously been sent.
mqtt-client-init if the mqtt-client-conn command has not previously been sent.
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance to de-initialize. Currently always set to 0 as there is only one MQTT client instance supported.
Response#
OKon successERROR <error code>in case of failure. Possible error codes are the same as those returned by the sl_mqtt_client_deinit API.
Examples#
at+mqtt-client-deinit=0 # De-initialize MQTT client instance 0 (the only supported instance)
OKmqtt-client-sub#
Subscribe to a topic on the MQTT broker.
Command Format#
at+mqtt-client-sub=<client-instance-id>,<qos>,<topic>,<timeout>Related SDK API
Pre-conditions#
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance to subscribe. Currently always set to 0 as there is only one MQTT client instance supported.
qos#
The MQTT protocol QoS for the delivery of messages from the subscribed topic to the MQTT client.
topic#
A string containing a wildcard for one or more topics to subscribe to.
timeout#
The duration in milliseconds after which this command returns a timeout status. Set to 0 to make this an asynchronous command. An asynchronous Event message is sent with the status of an asynchronous command.
Response#
OKon successfully completing the command or successfully initiating an asynchronous commandTIMEOUTin case of timeoutERROR <error code>in case of failure. Possible error codes are the same as those returned by the sl_mqtt_client_subscribe API.
Examples#
at+mqtt-client-sub=0,1,"wifi/#/lwt",120000 # Subscribe MQTT client instance 0 (the only supported instance) to topics matching wifi/#/lwt with a timeout of 120 seconds
OKmqtt-client-subinfo#
Query the current MQTT client subscription information.
Command Format#
at+mqtt-client-subinfo=<client-instance-id>Related SDK API
Pre-conditions#
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance to query. Currently always set to 0 as there is only one MQTT client instance supported.
Response#
OK <subscription-count> <topic1> <qos1> <topic2> <qos2> ... <topicN> <qosN>on success, where:subscription-countis the number of active topic subscriptionstopic1throughtopicNare the subscribed topic stringsqos1throughqosNare the Quality of Service levels for each corresponding topic (0, 1, or 2)
OK 0when no subscriptions are activeERROR 1in case of failure
Notes#
This command returns information from the subscription linked list pointed to by the subscription_list_head member of the sl_mqtt_client_t structure.
Examples#
at+mqtt-client-subinfo=0
OK 0
at+mqtt-client-subinfo=0
OK 3 device/+/status 2 sensor/+/data 1 control/+/command 0mqtt-client-unsub#
Un-subscribe from a topic on the MQTT broker.
Command Format#
at+mqtt-client-unsub=<client-instance-id>,<topic>,<timeout>Related SDK API
Pre-conditions#
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance to un-subscribe. Currently always set to 0 as there is only one MQTT client instance supported.
topic#
A string containing a wildcard for one or more topics to un-subscribe from.
timeout#
The duration in milliseconds after which this command returns a timeout status. Set to 0 to make this an asynchronous command. An asynchronous Event message is sent with the status of an asynchronous command.
Response#
OKon successfully completing the command or successfully initiating an asynchronous commandTIMEOUTin case of timeoutERROR <error code>in case of failure. Possible error codes are the same as those returned by the sl_mqtt_client_unsubscribe API.
Examples#
at+mqtt-client-unsub=0,"wifi/#/lwt",120000 # Un-subscribe MQTT client instance 0 (the only supported instance) from topics matching wifi/#/lwt with a timeout of 120 seconds
OKmqtt-client-pub#
Publish a message to the MQTT broker.
Command Format#
at+mqtt-client-pub=<client-instance-id>,<qos>,<id>,<retained>,<duplicate>,<topic>,<timeout>,<content-length>Related SDK API
Pre-conditions#
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance from which to publish. Currently always set to 0 as there is only one MQTT client instance supported.
qos#
The MQTT protocol QoS for publishing the message to the MQTT broker.
id#
A unique identifier for the message packet.
retained#
Set to 1 or 0 to indicate whether or not to publish the message as a retained message on the MQTT broker.
duplicate#
Set to 1 or 0 to indicate whether or not the message being published is a duplicate.
topic#
A string containing the topic on which to publish the message.
timeout#
The duration in milliseconds after which this command returns a timeout status. Set to 0 to make this an asynchronous command. An asynchronous Event message is sent with the status of an asynchronous command.
content-length#
The length of the message content.
Response#
ERROR 1on failing to enter data mode.OKon successfully entering data mode.On receiving this response, you must transmit
content-lennumber of characters.As soon as the given number of characters are transmitted, the message publishing is initiated and one of the following responses sent back:
OKon successfully completing the command or successfully initiating an asynchronous commandTIMEOUTin case of timeoutERROR <error code>in case of failure. Possible error codes are the same as those returned by the sl_mqtt_client_publish API.
Notes#
Unlike other AT commands, the command string is not terminated by a CR-LF sequence. Instead, it is considered complete after the specified content-length number of characters are transmitted following the comma (,) after the content-length parameter value.
Examples#
at+mqtt-client-pub=0,0,0,1,0,"wifi/silabs_device_0/name",120000,11 # Publish from MQTT client instance 0 (the only supported instance) to the given topic
OK
Silabs Light
OKEvents#
[MQTT_CLIENT_CONNECTED] (#mqtt-client-connected)
[MQTT_CLIENT_DISCONNECTED] (#mqtt-client-disconnected)
[MQTT_CLIENT_SUBSCRIBED] (#mqtt-client-subscribed)
[MQTT_CLIENT_UNSUBSCRIBED] (#mqtt-client-unsubscribed)
[MQTT_CLIENT_PUBLISHED] (#mqtt-client-published)
[MQTT_CLIENT_MESSAGE_RECEIVED] (#mqtt-client-message-received)
[MQTT_CLIENT_ERROR] (#mqtt-client-error)
MQTT_CLIENT_CONNECTED#
Event message sent by the SiWx91x device to indicate that an MQTT client instance has successfully connected to an MQTT broker.
Event Message Format#
at+MQTT_CLIENT_CONNECTED=<client-instance-id>Related SDK API
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance that has successfully connected. Currently always set to 0 as there is only one MQTT client instance supported.
Examples#
at+MQTT_CLIENT_CONNECTED=0MQTT_CLIENT_DISCONNECTED#
Event message sent by the SiWx91x device to indicate that an MQTT client instance has disconnected from an MQTT broker.
Event Message Format#
at+MQTT_CLIENT_DISCONNECTED=<client-instance-id>Related SDK API
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance that has disconnected. Currently always set to 0 as there is only one MQTT client instance supported.
Examples#
at+MQTT_CLIENT_DISCONNECTED=0MQTT_CLIENT_SUBSCRIBED#
Event message sent by the SiWx91x device to indicate that an MQTT client instance has successfully subscribed to a topic wildcard on the MQTT broker.
Event Message Format#
at+MQTT_CLIENT_SUBSCRIBED=<client-instance-id>Related SDK API
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance that has subscribed. Currently always set to 0 as there is only one MQTT client instance supported.
Examples#
at+MQTT_CLIENT_SUBSCRIBED=0MQTT_CLIENT_UNSUBSCRIBED#
Event message sent by the SiWx91x device to indicate that an MQTT client instance has successfully unsubscribed from a topic wildcard on the MQTT broker.
Event Message Format#
at+MQTT_CLIENT_UNSUBSCRIBED=<client-instance-id>Related SDK API
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance that has unsubscribed. Currently always set to 0 as there is only one MQTT client instance supported.
Examples#
at+MQTT_CLIENT_UNSUBSCRIBED=0MQTT_CLIENT_PUBLISHED#
Event message sent by the SiWx91x device to indicate that an MQTT client instance has successfully published a message to the MQTT broker.
Event Message Format#
at+MQTT_CLIENT_PUBLISHED=<client-instance-id>Related SDK API
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance that has published a message. Currently always set to 0 as there is only one MQTT client instance supported.
Examples#
at+MQTT_CLIENT_PUBLISHED=0MQTT_CLIENT_MESSAGE_RECEIVED#
Event sent by the SiWx91x device with the content of an incoming message on a subscribed topic.
Event Message Format#
at+MQTT_CLIENT_MESSAGE_RECEIVED=<client-instance-id>,<topic>,<content-length>,<content>Related SDK API
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance that has received a message. Currently always set to 0 as there is only one MQTT client instance supported.
topic#
A string indicating the topic on which the message was received.
content-length#
The length of the message content.
content#
The content of the message. This is not terminated by a CR-LF (carriage return-line feed) sequence but instead contains exactly content-length number of characters.
Examples#
at+MQTT_CLIENT_MESSAGE_RECEIVED=0,"wifi/silabs_device_0/on",4,trueMQTT_CLIENT_ERROR#
Event message sent by the SiWx91x device to indicate that an error occurred during the processing of a command.
Event Message Format#
at+MQTT_CLIENT_ERROR=<client-instance-id>,<error-code>Related SDK API
Parameters#
client-instance-id#
The unique identifier of the MQTT client instance that encountered an error in command processing. Currently always set to 0 as there is only one MQTT client instance supported.
error-code#
The error that was encountered. Contains a numeric error code that corresponds to one of the values of the enum sl_mqtt_client_error_status_t.
Examples#
at+MQTT_CLIENT_ERROR=0,0 # Connection failure (error code 0) on MQTT client instance 0 (the only supported instance)