EZMQTT Client

How to use the EZMQTT Client robot skill

MQTT (MQ Telemetry Transport) is a publish-subscribe-based "lightweight" messaging protocol for use on top of the TCP/IP protocol (port 1883). The publish-subscribe messaging pattern requires a message broker. The broker is responsible for distributing messages to interested clients based on the topic of a message.

This is an MQTT Client Control that connects to an MQTT broker and publishes/subscribes to topics. When messages are published to matching topics, the incoming data will be assigned to a variable and an associated EZ-Script (message) will launch.

How EZMQTT Works

1. Start the EZMQTT Broker
2. In the EZMQTT Client Configuration enter the Broker IP
3. In the EZMQTT Client Configuration enter a topic (Subscription) name
4. In the EZMQTT Client Configuration write a script that sends a message
5. Connect Publisher Client(s) to the Broker to publish topic messages
6. Connect Subscriber Client(s) to the Broker to receive topic messages

*Note: Clients can be both Publishers & Subscribers. The diagram above is a simplification.

Main Window

1. Client Connect Button This button connects the EZMQTT Client to the Broker. The Client publishes/subscribes to topics and sends/receives messages.

Configuration

1. Broker Hostname/IP Field This field is for entering the IP address of the Broker server that you'd like the client to connect to.

2. Connected Variable Field This variable holds the status of the client connection to the broker. True means the client is connected to the broker.

3. Subscription Name Field This is the topic name that other clients will subscribe to.

4. Variable Name Field This variable is used for data that is being shared between clients.

5. Is Binary Array Checkbox If the data from the published messages are expected to be Binary, then check the checkbox. This will assign the data to an Array of the specified variable. If the Binary checkbox is unchecked, the expected data is an alphanumeric string.

6. Script Field This field is for the published topic messages.

7. Topic Management Buttons These buttons are used to add/remove topics, move them up/down the list, or edit them.

How to Use EZMQTT Client

1. Add the EZMQTT Client skill to your ARC project (Project -> Add Skill -> Misc -> EZMQTT Client).

2. In the EZMQTT Client Configuration add the broker IP address.

3. In the EZMQTT Client Configuration add a topic name, variable name, and script (message).

4. Click the Client Connect button.

Code Samples

Connect Connects to the hostname of the specified MQTT broker. Either the CONNECT button on the control can be pressed, or a ControlCommand() can be passed. If no parameter is specified in the ControlCommand(), the default value from the config is used. Both examples of specifying a hostname and not are provided below.

# If not connected, connect to local MQTT broker
IF (!$MQTTClientStatus)
  ControlCommand("EZMQTT Client", Connect, "127.0.0.1")
ENDIF

# Connect to default hostname specified in config
ControlCommand("EZMQTT Client", Connect)

Disconnect Waits for the MQTT client to finish any work it must do, and for the TCP/IP session to disconnect. This may be executed by pressing the DISCONNECT button on the control, or using the ControlCommand().

ControlCommand("EZMQTT Client", Disconnect)

Subscribe Subscription to topics are specified in the Config menu of the control. The variable name and script to execute must also be provided. If the data from the published messages are expected to be Binary, then check the Binary box. This will assign the data to an Array of the specified variable. If the Binary checkbox is not checked, the expected data is alphanumeric string.

Publish Publish specified data to the specified topic. The following commands are...

# Publish a string to the 'asdf' topic
ControlCommand("EZMQTT Client", PublishString, "asdf", "Hello World")

# Publish binary array to the 'asdf' topic
defineArray($array, 5)
$array[0] = 1
$array[1] = 2
$array[2] = 3
$array[3] = 4
$array[4] = 5
ControlCommand("EZMQTT Client", PublishBinary, "asdf", "$array")

# Publish a comma separated list of numeric values, variables and strings to the 'asdf' topic
$x = "Hello"
ControlCommand("EZMQTT Client", PublishBytes, "asdf", $x, 32, "World")

Resources

You may also be interested in the Synthiam EZMQTT Broker from here: https://synthiam.com/Docs/Skills/Misc/EZMQTT-Broker?id=15863

Here is a sample ARC project that demonstrates the EZMQTT Client connecting to a EZMQTT Broker: test mqtt.EZB