The mqtt command

Synopsis

mqtt new ?options?
mqtt create name ?options?
mqtt log arg body

Description

The mqtt new and 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 mqtt log command can be used to define what to do with log messages. In its simplest form it may be something like:

mqtt log str {puts $str}

Command Options

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

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:

client configure ?option? ?value 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.
client 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.
client disconnect: Disconnect from the currently connected MQTT broker.
client 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.
client subscribe pattern prefix ?qos?: Subscribe to topics matching the specified pattern. When a matching MQTT message is received by the MQTT broker, the prefix is evaluated with two arguments appended: the topic of the message, and the contents of the message. 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.
client 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.
client 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.

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:

$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:

Normal disconnect
Unacceptable protocol version
Identifier rejected
Server unavailable
Bad user name or password
Not authorized

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

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