Home

Tcl MQTT extension

mqtt - Tcl library for working with the MQTT messaging protocol


Synopsis

package require Tcl 8.6
package require mqtt 2.0

mqtt new ?option value ...?
mqtt create name ?option value ...?
mqtt log prefix
cmd configure ?option? ?value ...?
cmd connect name ?host? ?port?
cmd disconnect
cmd publish topic message ?qos? ?retain?
cmd subscribe pattern prefix ?qos?
cmd unsubscribe pattern prefix
cmd will 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 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 name ?host? ?port?
Connect to the specified MQTT broker, using name as the MQTT ClientID. The default value for host is localhost. The default port is 1883.

cmd disconnect
Disconnect from the currently connected MQTT broker.

cmd publish 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 1. Valid values for retain are 0 and 1. Default is 0.

cmd subscribe pattern prefix ?qos?
Subscribe to topics matching the specified pattern. For both retained and new messages matching the pattern, the prefix is evaluated with three arguments appended: the topic of the message, the contents of the message, and a flag indicating the retained status of the message.

When a new subscription is made by a client, all retained messages that match the pattern are reported with the flag set to 1. Any messages matching the pattern that are subsequently received by the broker are reported with a flag value of 0.

Valid values for qos are 0 (at most once), 1 (at least once), and 2 (exactly once). In addition to the regular qos values, a value of -1 may be specified to reinstall a callback without sending a SUBSCRIBE message to the broker. This may be useful for resumed sessions (i.e. when the -clean option is set to false). Default is 2.

cmd unsubscribe pattern prefix
Remove a callback for a topic pattern. When the last callback for a topic pattern is removed, an UNSUBSCRIBE message is sent to the broker.

cmd will 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 1. Valid values for retain are 0 and 1. Default is 0.

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. Set this to 3 for brokers that only support the older mqtt-v3.1 specification, rather than the mqtt-v3.1.1 (version 4) specification (default: 4)
-socketcmd prefix
The command prefix to use when creating a socket. This allows the use of encrypted connections (default: socket)

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 changes in the connection state. 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. The value will always be '0' when the -clean option is set to '1'.
reason
The reason for a disconnection or failed connection. Possible values are:
  • 0 Normal disconnect

  • 1 Unacceptable protocol version
  • 2 Identifier rejected
  • 3 Server unavailable
  • 4 Bad user name or password
  • 5 Not authorized
$SYS/local/subscription
The result of one or more subscribe or unsubscribe commands. The data dictionary contains topics and their accepted maximum quality of service level. The possible values are the normal qos values 0, 1, and 2, 0x80 for failure, or an empty string for unsubscribes.

$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 both the published topic and data.