Home

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:

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:
  1. Normal disconnect
  2. Unacceptable protocol version
  3. Identifier rejected
  4. Server unavailable
  5. Bad user name or password
  6. 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.