Tcl MQTT extension
mqtt - Tcl library for working with the MQTT messaging protocol
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 publish topic message ?qos? ?retain?
cmd subscribe pattern prefix ?qos?
cmd unsubscribe pattern prefix
cmd will topic message ?qos? ?retain?
- 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
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.
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)
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:
- Reports changes in the connection state. The data dict contains the following
- The new connection state. Possible values are: connected, and disconnected. This item is always present.
- 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'.
- 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
- 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.
- 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.