Tcl MQTT server

Tcl MQTT broker extension

broker - Tcl library for MQTT broker functionality


Synopsis

package require Tcl 8.6
package require mqtt 2.0
package require sqlite3
package require broker 1.0

broker new database ?option value ...?
broker create name database ?option value ...?
broker log prefix
cmd configure ?option? ?value ...?
cmd clientadd clientid
cmd clientdel clientid
cmd listen ?port?
cmd useradd username ?password?
cmd userdel username


Description

The broker library is an extension to the mqtt class, providing the functionality necessary to create an MQTT broker.

broker new database ?option value ...?
broker create name database ?option value ...?
The broker new and broker create commands create an MQTT server instance, either with an auto-generated or a user specified name. That instance can subsequently be used to handle MQTT client connections.

The database argument is usually just the name of a disk file in which the database is stored. If the name of the database is the special name ":memory:" then a new database is created in memory. If the name of the database is an empty string, then the database is created in an empty file that is automatically deleted when the server instance is destroyed.

The option value pairs configure some options associated with the broker instance. See the section Configuration options below for a full list of options supported and their effects.

broker log prefix
The broker 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 instance command

For each client instance created with the broker 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 clientadd clientid
Add the specified client ID to the database. If any client IDs are stored in the database, only those clients will be allowed to connect to the broker. By default, all client IDs are valid.

cmd clientdel clientid
Remove the specified client ID from the database. Trying to remove a non-existent client ID is not considered an error.

cmd listen ?port?
Start accepting MQTT client connections on the specified TCP port. The default port is 1883.

cmd useradd username ?password?
Add the specified user to the database. If any users are stored in the database, only those users will be allowed to connect to the broker. By default, no username is required and if a username is provided when connecting, any name is accepted. If the password argument is specified, the user must provide the given password when connecting. By default, no password is required and if a password is provided when connecting, any value is accepted.

cmd userdel username
Remove the specified user from the database. Trying to remove a non-existent user is not considered an error.

Configuration options

The following options, supported by the broker new, broker create, and cmd configure commands, control how the MQTT broker 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)
-socketcmd prefix
The command prefix to use when creating a socket. This allows the use of encrypted connections (default: socket)

Custom identification and authentication

The library provides very basic support for identification and authentication. If more sophisticated control is needed, the application can install a custom identify or authenticate method, or both.

Upon a new connection from a client, the identify method will be called with a single argument that holds the client ID provided by the client. The authenticate method is called with up to two arguments; the username and password, if they were provided by the client. Both methods should provide a boolean return value, indicating whether the connection is allowed.

Example: To only allow clients with a client ID containing the prefix "secure-", the following code may be used in the application:

package require broker

oo::define broker { method identify {name} { return [string match secure-* $name] } }