MQTT for Tcl

Tcl MQTT client
Login

Tcl MQTT extension

mqtt - Tcl library for working with the MQTT messaging protocol

SYNOPSIS

package require Tcl 8.6
package require mqtt 3.0
mqtt new ?option value ...?
mqtt create name ?option value ...?
mqtt log prefix
cmd authentication method prefix
cmd configure ?option? ?value ...?
cmd connect ?-properties properties? name ?host? ?port?
cmd disconnect ?-properties properties? ?reason?
cmd publish ?-properties properties? topic message ?qos? ?retain?
cmd reauthenticate ?-properties properties?
cmd subscribe ?-properties properties? pattern prefix ?qos? ?nl? ?rap? ?rh?
cmd unsubscribe ?-properties properties? pattern
cmd will ?-properties properties? topic message ?qos? ?retain?

DESCRIPTION

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
    

THE CLIENT COMMAND

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

CONFIGURATION OPTIONS

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)

CALLBACK

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?
    
Topic contains the topic the message was published to. Message gives the contents of the message. The retain flag provides the retain information for the message. The meaning of this flag depends on the value of the rh argument of the subscribe command. If the message contains any properties, they are passed to the command in the properties] argument as a key-value list. The properties argument is only added to the callback if there are any properties to report. Since properties are first defined in the MQTT v5 specification, the callback will always only get three arguments when -protocol 3 or 4 is used.

See the Properties section for more information about properties.

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.
When a message would exceed the Maximum Packet Size specified by the server in the CONNACK message, some or all ReasonString and/or UserProperty entries may be discarded by the library to reduce the size of the message. If the message is still too big, the message cannot be sent and is discarded.

COMMAND RESULTS

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.

VERSIONS

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.

COPYRIGHT

Copyright © 2019, 2021 Schelte Bron