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-init

Related SDK API#

Pre-conditions#

None

Parameters#

None

Response#

  • OK <client-instance-id> on success, where client-instance-id is 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 0

mqtt-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#

sl_mqtt_broker_v2_t

Pre-conditions#

mqtt-client-init

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#

  • OK on success

  • ERROR 1 in case of failure

Notes#

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
OK

mqtt-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#

mqtt-client-init

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-state is the current state of the MQTT client connection, with one of the following possible values:

      • DISCONNECTED: Client is not connected to the broker

      • CONNECTION_FAILED: Connection attempt to the broker failed

      • CONNECTED: Client is successfully connected to the broker

      • NWP_INIT: Network processor has been successfully initialized

      • NWP_DISCONNECTED: Network processor is disconnected

    • broker-ip is the IP address of the MQTT broker in dotted decimal format (e.g., "192.168.1.100") or "0.0.0.0" if not configured

    • broker-port is the port number of the MQTT broker (typically 1883 for unencrypted, 8883 for encrypted) or 0 if not configured

    • connect-timeout is the MQTT connection timeout in milliseconds

    • keep-alive-interval is the keep-alive interval of the MQTT connection in milliseconds

    • keep-alive-retries is the number of retries that are performed for the MQTT keep-alive message

    • host-name is the MQTT hostname string, or empty string if not configured

    • enable-sni indicates whether SNI is enabled (1 = enabled, 0 = disabled)

    • sni-host-name is the hostname string used in SNI, or empty string if not configured

  • ERROR 1 in 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 enabled

mqtt-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#

mqtt-client-init

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#

  • OK on success

  • ERROR 1 in case of failure

Notes#

Examples#

at+mqtt-client-opt=0,1,3,5000,30000,0,5,65001,768,"SilabsMQTTClient",49
OK

mqtt-client-optinfo#

Query the current MQTT client options.

Command Format#

at+mqtt-client-optinfo=<client-instance-id>

Related SDK API#

Pre-conditions#

mqtt-client-init

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-reconnect indicates whether the SiWx91x device should automatically re-connect to the MQTT broker when the connection is lost (1 = enabled, 0 = disabled)

    • connect-retries is the number of times to automatically attempt re-connection to the MQTT broker when the connection is lost

    • min-back-off-time is the minimum amount of time in milliseconds to back off between two automatic re-connection attempts

    • max-back-off-time is the maximum amount of time in milliseconds to back off between two automatic re-connection attempts

    • clean-session indicates whether to establish a clean MQTT session on connection (1 = enabled, 0 = disabled)

    • mqtt-version is the MQTT protocol version used by the MQTT client

    • port is the port number on the SiWx91x device used to connect to the MQTT broker

    • credential-id is 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 command

    • client-id is a string used to uniquely identify the MQTT client to the MQTT broker

    • tls-flags are the TLS connection options, represented as a bitmap as described in the documentation for the enum sl_mqtt_tls_flag_t

  • ERROR 1 in case of failure

Examples#

at+mqtt-client-optinfo=0
OK 1 3 5000 30000 0 5 65001 768 SilabsMQTTClient 49

mqtt-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#

mqtt-client-init

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 1 on failing to enter data mode.

  • OK on successfully entering data mode.

    • On receiving this response, you must transmit content-len number 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:

      • OK on success

      • ERROR 1 in case of failure

Notes#

Examples#

at+mqtt-client-lwt=0,1,2,"wifi/silabs_device_0/lwt",33      # Silabs device 0 has disconnected.
OK

mqtt-client-conn#

Connect to an MQTT broker.

Command Format#

at+mqtt-client-conn=<client-instance-id>,<timeout>

Related SDK API#

Pre-conditions#

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#

  • OK on successfully completing the command or successfully initiating an asynchronous command

  • TIMEOUT in case of timeout

  • ERROR <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
OK

mqtt-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#

  • OK on successfully completing the command or successfully initiating an asynchronous command

  • TIMEOUT in case of timeout

  • ERROR <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
OK

mqtt-client-deinit#

De-initialize an MQTT client instance.

Command Format#

at+mqtt-client-deinit=<client-instance-id>

Related SDK API#

Pre-conditions#

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#

  • OK on success

  • ERROR <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)
OK

mqtt-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#

  • OK on successfully completing the command or successfully initiating an asynchronous command

  • TIMEOUT in case of timeout

  • ERROR <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
OK

mqtt-client-subinfo#

Query the current MQTT client subscription information.

Command Format#

at+mqtt-client-subinfo=<client-instance-id>

Related SDK API#

Pre-conditions#

mqtt-client-init

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-count is the number of active topic subscriptions

    • topic1 through topicN are the subscribed topic strings

    • qos1 through qosN are the Quality of Service levels for each corresponding topic (0, 1, or 2)

  • OK 0 when no subscriptions are active

  • ERROR 1 in 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 0

mqtt-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#

  • OK on successfully completing the command or successfully initiating an asynchronous command

  • TIMEOUT in case of timeout

  • ERROR <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
OK

mqtt-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 1 on failing to enter data mode.

  • OK on successfully entering data mode.

    • On receiving this response, you must transmit content-len number 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:

      • OK on successfully completing the command or successfully initiating an asynchronous command

      • TIMEOUT in case of timeout

      • ERROR <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
OK

Events#

  • [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=0

MQTT_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=0

MQTT_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=0

MQTT_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=0

MQTT_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=0

MQTT_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,true

MQTT_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)