MQTT.Client

Description

This class allows you to create client connections to an MQTT broker.

A client is capable of publishing messages to the broker. A client is also capable of subscribing one or more topics, enabling it to receive messages that other clients publish on those topics.
This class uses the mosquitto client library. See mosquitto.org and mosquitto.h for more information.
To use this class, you'll complete the following steps:

1. Construct
2. Configure
3. Connect
4. Communicate
5. Disconnect
6. Destroy

Construct

You can construct a client by specifying an id, a version, and a clean start flag:

MQTT.Client c = MQTT.Client("my-client-id", MQTT.Version.v31, 1);

You can also choose to use the default arguments:

MQTT.Client c = MQTT.Client("");

Note that a blank ID implies that the client will generate a random ID.

In the above cases, the client you create will be destroyed automatically when the FlexScript function finishes running. To create a more persistant connection, you can specify a treenode for the client:

treenode holder = Model.find("path/to/target/node");
MQTT.Client c = MQTT.Client("my-client-id", MQTT.Version.v31, 1, holder);

When you supply a node this way, the data for the client is stored on the node. You can access this client later as follows:

treenode holder = Model.find("path/to/target/node");
MQTT.Client c = holder;
// OR
MQTT.Client c = MQTT.Client(holder);

It is an error to create a client from a node that does not have client data on it.

Configure

Once the client is constructed, you can configure the client:

• If desired, setting a will message with setWill(). The will message is optional and is published only if the client disconnects unexpectedly.
• If the broker requires, setting a username and password with setUsernamePassword().
• If the broker requires, setting SSL options with setSSL().

You must also decide how FlexSim will receive messages from the broker. There are two options:

• You can either wait for messages with getMessage(), or
• You can specify a node to use as a callback with setDefaultCallback(). The callback will be called any time a message is received.

Configuration is Irreversible

Most configuration functions make changes that can't be reversed on the client. For example, once you set a username and password, you can't remove the username and password. If you need to change the client's configuration, create a new client.

If you are making a persistent client, first create a non-presistant client that successfully connects to ensure your configuration is correct.

Connect

To connect to a broker, specify a host, a port, and a keep-alive interval:

int code = c.connect("localhost", 1883, 60);

Once connected, you can then communicate with the broker. When you finish communications, be sure to disconnect.

Once you have disconnected, you can reconnect the client with the exact same settings as were used before:

int code = c.connect();

Note that in order to use this simple version of connect, you must meet the following conditions:

1. The client has successfully connected in the past and you haven't called any configuration functions, or
2. The client is bound to a node and all member node values are set correctly (intended for developer use).

Communicate

In MQTT, clients do not communicate with each other directly. Instead, they publish messages. A message includes a topic and a payload. Any client can subscribe to a topic. Once a client has subscribed, they will receive all messages that are published on that topic.

The broker's main role is to distribute published messages to any client subscribed to the correct topic. Only connected clients receive messages. The broker does not store messages for later. The only exception is retained messages. If a message is retained, the broker will keep the latest message for that topic. As soon as a client subscribes, the broker will send the retained message, if any.

Once connected, a client can subscribe to one or more topics:

int rc = c.subscribe("some-topic");

If a callback node is set, then it will be evaulated whenver a message arrives. Otherwise, the client will store incoming messages in a queue until they are retrieved:

MQTT.Message msg = c.getMessage(5.0);
// Check if the message was received
if (msg) {
    // use the message
    print(msg.topic, msg.payload);
}

To publish a message, create an MQTT.Message object and publish it:

MQTT.Message msg = Message("some-topic", "some-message");
int rc = c.publish(msg);
        

Disconnect

You can disconnect the client as follows:

int rc = c.disconect();

Once disconnected, the client will no longer receive messages from the broker.

Destroy

If you don't bind the client to a node, the client will be destroyed automatically at the end of the FlexScript function where it was created. If the client is bound to a node, it will be destroyed when the node is destroyed or when the the node's data changes.

Properties

Properties are an advanced feature that most users can safely ignore.

MQTT 5.0 introduced Properties. Properties can be passed to most of the methods in the client, and can be part of a message. The MQTT.Client class represents properties with a Map. The client attempts to convert all keys and values in the map to valid MQTT properties. If a key is text and is not a valid property name, the client will use the key and value as a user property.

A full list of properties is included in the MQTT 5.0 specification, along with which properties are valid for a particular API call: https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901027

Properties

isConnected	Returns whether the client is currently connected to the broker.
settings	Returns the set of all construction, configuration, and connection values.

Methods

connect	Connects the client to a broker.
disconnect	Disconnects the client from the broker.
getMessage	Waits for the client to receive a message.
publish	Publishes a message.
setDefaultCallback	Specifies a node to evaluate when a message is received.
setSSL	Specifies options to use for TLS/SSL.
setUsernamePassword	Specifies a username and password for the client.
setWill	Sets a will message for the client.
subscribe	Subscribes the client to a topic.
unsubscribe	Unsubscribe from a topic.

Constructor

MQTT.Client

Operators

=	Accesses a client stored on the given node.