mqtt new ?option value ...?

mqtt create name ?option value ...?

The mqtt new and mqtt create commands create an MQTT client instance, either with an auto-generated or a user specified name. That instance can subsequently be used to communicate with an MQTT broker.

The option value pairs configure some options associated with the client instance. See the section Configuration options below for a full list of options supported and their effects.

mqtt log prefix

The mqtt log command configures a command prefix for handling log messages. Whenever the library has something to report, the log message is appended as an extra argument to prefix and the resulting command is executed. Example: Print all log messages to standard output:

mqtt log puts

For each client instance created with the mqtt command, a new Tcl command is created. This command may be used to invoke various mqtt related operations.

The valid forms of this command are:

cmd authentication method prefix

Set up an enhanced authentication method that can subsequently be used as the AuthenticationMethod property for the connect method. When the server challenges the connection attempt, the prefix is executed with the challenge data as an additional argument. The resulting command should return the response to the challenge. Depending on the authentication method, there may be multiple challenge/respond rounds. If an empty string is given as the prefix argument, the enhanced authentication method specified by the method argument is deleted.

cmd configure ?option? ?value ...?

Query or modify the configuration options of the instance. If one or more option-value pairs are specified, then the command modifies the given instance option(s) to have the given value(s); in this case the command returns an empty string. If option is specified with no value, then the command returns the current value of the option. If no option is specified, it returns a list of all available options and their values.

See the section Configuration options below for a full list of options supported and their effects.

cmd connect ?-properties properties? name ?host? ?port?

Connect to the specified MQTT broker, using name as the MQTT ClientID. If an empty string is specified for name, the broker will assign a ClientID. The assigned Client ID is reported back via the AssignedClientIdentifier key in the properties argument passed to the callback for the $SYS/local/connection topic. The default value for host is localhost. The default port is 1883.

The following properties may be passed to a connect call: SessionExpiryInterval, ReceiveMaximum, MaximumPacketSize, TopicAliasMaximum, RequestResponseInformation, RequestProblemInformation, and UserProperty. See the Properties section for more information about properties.

cmd disconnect ?-properties properties? ?reason?

Disconnect from the currently connected MQTT broker. Usual values for reason are: 0 (Normal disconnection) and 4 (Disconnect with Will Message). Check the MQTT specification for a complete list. The default is 0.

The following properties may be passed to a disconnect call: SessionExpiryInterval, ReasonString, and UserProperty. See the Properties section for more information about properties.

cmd publish ?-properties properties? topic message ?qos? ?retain?

Publish an MQTT message to the broker. Valid values for qos are 0 (at most once), 1 (at least once), and 2 (exactly once). Default is 0. Valid values for retain are 0 and 1. Default is 1 when a MessageExpiryInterval property is specified, and 0 otherwise.

The following properties may be passed to a publish call: PayloadFormatIndicator, MessageExpiryInterval, TopicAlias, ResponseTopic, CorrelationData, SubscriptionIdentifier, ContentType, and UserProperty. See the Properties section for more information about properties.

cmd reauthenticate ?-properties properties?

Initiate re-authentication. This can only be used after a connection has been established with enhanced authentication. If the authentication method specifies that the client sends data first, the AuthenticationData property should be provided. The library will populate the AuthenticationMethod property with the same value as used in the connect method, if not provided.

The following properties may be passed to a reauthenticate call: AuthenticationMethod, AuthenticationData, ReasonString, and UserProperty. See the Properties section for more information about properties.

cmd status

Returns information about the connection to the broker. The return value is a list, with the first element indicating the basic status:

connected

The connection to the broker has been established successfully.

disconnected

The connection to the broker was terminated normally.

failed

Connecting to the broker failed. If a reason for the failure is known, it is provided as a second element in the list.

idle

A connection to a broker has not yet been initiated.

cmd subscribe ?-properties properties? pattern prefix ?qos? ?nl? ?rap? ?rh?

Subscribe to topics matching the specified pattern. For both retained and new messages matching the pattern, the prefix is invoked. See the Callback section for details.

The qos argument specifies the maximum quality of service level the broker may use for publishing messages to the client. The broker forwards messages with a QoS level that is the lower of the QoS of the originally published message and the maximum QoS granted by the server. In addition to the regular QoS values, 0 (at most once), 1 (at least once), and 2 (exactly once), a value of -1 may be specified to reinstall a callback without sending a SUBSCRIBE message to the broker. This may be useful to change the callback handler and for resumed sessions (i.e. when the -clean option is set to false). Default is 2.

The nl argument controls the MQTT "No Local" subscription option. A value of 1 indicates to the server that Application Messages must not be forwarded to a connection with a ClientID equal to the ClientID of the publishing connection.

The rap argument maps to the MQTT "Retain As Published" subscription option. When a new subscription is established, retained messages that match the pattern are reported with the retain flag set to 1 (unless disabled by the rh argument, see below). When the rap argument is set to 0 (the default), any messages matching the pattern that are subsequently received by the broker are reported with a retain flag value of 0. If the rap argument is 1, the retain flag of subsequent messages reflects the retain flag the message was published with.

The rh argument maps to the MQTT "Retain Handling" subscription option. This option controls whether the server will send retained messages when the subscription is established. The following values are possible:

0 = Always (default)

Send retained messages at the time of the subscribe.

1 = Only on new subscriptions

Send retained messages at subscribe only if the subscription does not currently exist.

2 = Never

Do not send retained messages at the time of the subscribe.

The following properties may be passed to a subscribe call: SubscriptionIdentifier and UserProperty. See the Properties section for more information about properties.

cmd unsubscribe ?-properties properties? pattern

Remove a subscription for a topic pattern.

The following properties may be passed to a unsubscribe call: UserProperty. See the Properties section for more information about properties.

cmd will ?-properties properties? topic message ?qos? ?retain?

Include a last will and testament in all future connections to the MQTT broker. If topic is the empty string, no last will and testament will be included in future connections to the MQTT broker. Valid values for qos are 0 (at most once), 1 (at least once), and 2 (exactly once). Default is 0. Valid values for retain are 0 and 1. Default is 1 when a MessageExpiryInterval property is specified, and 0 otherwise.

The following properties may be passed to a will call: WillDelayInterval, PayloadFormatIndicator, MessageExpiryInterval, ContentType, ResponseTopic, CorrelationData, and UserProperty. See the Properties section for more information about properties.

The following options, supported by the mqtt new, mqtt create, and cmd configure commands, control how the MQTT client behaves:

-keepalive seconds

Rate at which to send keepalive messages (default: 60)

-retransmit milliseconds

When to retransmit a message if no confirmation has been received (default: 5000)

-username value

The username to use to authenticate with the MQTT broker

-password value

The password to use to authenticate with the MQTT broker

-clean boolean

Whether to use a clean connection to the MQTT broker (default: on)

-protocol version

Which protocol version to use for the connection to the MQTT broker. Valid values are 3 (for MQTT version 3.1), 4 (for MQTT version 3.1.1), and 5 (for MQTT version 5). The default is 5. See the Versions section for more information.

-socketcmd prefix

The command prefix to use when creating a socket. This allows the use of encrypted connections (default: socket)

When a message is published to a subscribed topic, a number of arguments is appended to the command prefix so that the actual command is as follows:

commandPrefix topic message retain ?properties?

See the Properties section for more information about properties.

Since MQTT v5, almost all messages may contain properties. In the Tcl MQTT library, properties are represented as a list of key-value pairs. To include properties in a message, several methods take a -properties option. Sending properties in PUBACK, PUBREC, PUBREL, and PUBCOMP messages is not currently possible with the library. A properties argument will also be passed to the callback command if the received message contains any properties.

Below is the complete list of properties defined in the MQTT v5 specification. Unless otherwise indicated, the same property key may only occur once in a properties list.

PayloadFormatIndicator

Boolean indicating that the payload is UTF-8 Encoded Character Data. The library takes care of the conversions between UTF-8 and Tcl's internal string representation.

MessageExpiryInterval

Lifetime of the message in seconds (32-bit integer).

ContentType

String describing the content of the Application Message.

ResponseTopic

String to be used as the Topic Name for a response message.

CorrelationData

Binary data used by the sender of the Request Message to identify which request the Response Message is for when it is received.

SubscriptionIdentifier

Integer representing the identifier of the subscription (1 - 268,435,455). This key appears multiple times if the publication is the result of a match to more than one subscription. In this case their order is not significant.

SessionExpiryInterval

Integer representing the Session Expiry Interval in seconds.

AssignedClientIdentifier

String containing the Client Identifier asisgned to the client by the server.

ServerKeepAlive

Integer with the Keep Alive time assigned by the Server.

AuthenticationMethod

String containing the name of the authentication method used for extended authentication.

AuthenticationData

Binary Data containing authentication data.

RequestProblemInformation

Boolean to indicate whether the server may send Reason String or User Properties in the case of failures.

WillDelayInterval

Integer specifying the delay in seconds before the server publishes the client's Will Message

RequestResponseInformation

Boolean to request the Server to return Response Information in the CONNACK.

ResponseInformation

String which is used as the basis for creating a Response Topic.

ServerReference

String containing a space separated list of other servers for the client to use.

ReasonString

String representing the reason associated with this response. This property may be discarded if necessary to keep the message below the maximum packet size specified by the receiver.

ReceiveMaximum

Integer specifying a limit for the number of QoS 1 and QoS 2 publications that the server is willing to process concurrently for the client.

TopicAliasMaximum

Integer indicating the highest value that the server will accept as a Topic Alias sent by the client.

TopicAlias

Integer value that is used to identify the Topic instead of using the Topic Name.

MaximumQoS

Byte defining the maximum QoS value the server supports (either 0 or 1)

RetainAvailable

Boolean declaring whether the server supports retained messages.

UserProperty

Name-value pair used to provide additional information to the remote party. The UserProperty key is allowed to appear multiple times to represent multiple name-value pairs. The same name is allowed to appear more than once. This property may be discarded if necessary to keep the message below the maximum packet size specified by the receiver.

MaximumPacketSize

Integer representing the maximum packet size the server is willing to accept.

WildcardSubscriptionAvailable

Boolean declaring whether the server supports Wildcard Subscriptions.

SubscriptionIdentifierAvailable

Boolean declaring whether the server supports Subscription Identifiers.

SharedSubscriptionAvailable

Boolean declaring whether the server supports Shared Subscriptions.

In general, commands are issued to the library, which will try its best to perform the requested action. It does this asynchronously, so a result is not yet available when the call into the library returns. In certain cases it may be useful for the calling code to be informed of the completion of the task. The library leverages its existing callback framework to provide this service. A caller may subscribe to several special topics to be notified of different events. The content provided by all of these special topics is a dict. The keys of the dict depend on the topic. The following topics are currently defined:

$SYS/local/connection

Reports updates of the connection state. This can be the result of receiving a CONNACK, DISCONNECT, or final AUTH message. The data dict contains the following information:

state

The new connection state. Possible values are: connected, and disconnected. This item is always present.

session

Whether the broker has a session present for the client. This key will only exist upon the successful establishment of a connection using protocol level 4 or later. The value will always be '0' when the -clean option is set to '1'.

reason

The reason for a disconnection or failed connection. Please check the MQTT specification for possible values.

$SYS/local/subscription

The result of one or more subscribe or unsubscribe commands. The data dictionary contains topics and the result of the subscribe or unsubscribe request. In case of an error, the result will be 128 or greater. On a successful subscribe, the result is the granted qos values 0, 1, or 2. The result is an empty string for successful unsubscribes, or 17 if the server reported that no subscription existed.

$SYS/local/publication

Reports when the broker has accepted a PUBLISH message. This notification will only happen for publish requests with a qos value of 1 or 2, as the broker does not acknowledge the receipt of a PUBLISH message with a qos value of 0. The data dict contains the published topic, data, and a result code.

The mqtt library supports three versions of the MQTT protocol. The MQTT specifications number these versions as 3 (v3.1), 4 (v3.1.1), and 5 (v5). The -protocol configuration option follows that numbering.

The commands listed above show the options and arguments as valid for version 5 of the protocol. When using a different protocol version, the following limitations exist:

VERSION 4

• None of the methods accept a -properties option.
• The connect name argument may only be empty when used in combination with a true value for the -clean option. The client is not informed of the assigned name.
• The disconnect method does not take any arguments.
• The subscribe method lacks the nl, rap, and rh arguments.
• The authentication and reauthenticate methods are not available.
• The data dict passed to the {$SYS/local/publication} topic does not contain a result code.

VERSION 3

• All the limitations of protocol version 4.
• The connect name argument must have a length between 1-23. An empty Client ID is not allowed.