MQTT Clients
MQTT (MQ Telemetry Transport) is an OASIS standard messaging protocol for the Internet of Things (IoT) that describes how IoT devices (embedded devices, sensors, industrial controllers, etc.) communicate over the Internet. MQTT features clients and brokers; Macula servers have the ability to host MQTT clients, which can connect to existing third-party MQTT brokers, subscribe to topics and publish their own MQTT messages.
On each Macula server, you can create MQTT client(s), and then use it connect to MQTT broker(s) and subscribe to the desired topic or topics, and publish messages. Thus, Macula MQTT clients act as regular MQTT clients, "talking" to the MQTT brokers of your choice. The Macula server installation does not include an MQTT broker, nor does GSF provide such modules as an extra. Before using this functionality in Macula, you need to have a running broker with connected devices.
Create an MQTT Client
To create a new MQTT client in Macula Console, go to the Configuration tab and choose MQTT Clients on the left. On the upper panel, click the + New MQTT Client button to open up the dialog box.
The available settings are summarized in the table below. Note that the connection settings here must match the allowed connection profile in the MQTT broker configuration. For example, if your broker does not support insecure connections, you must enter relevant secure connection settings matching those on the broker side.
Title
User-defined client name that will be used everywhere in Macula Console
[none]
Server
Macula server, to which the MQTT client will be bound. If none are selected, the client will be available on all servers in the Macula Global system
[none]
Broker host
MQTT broker host name or IP address for the client to connect to
[empty]
Broker port
MQTT broker port to be used for client connection
[empty]
Client name
MQTT client name that will be broadcasted. Broker settings may require this field to be set explicitly or allow it to be empty.
[empty]
Username and password
User name and password to authenticate (leave blank if broker allows anonymous connections, allow_anonymous is true)
[empty]
Protocol version
Must be supported by MQTT broker; older version, 3.1.1, is more likely to be supported
3.1.1
Clean session
If enabled, the broker will not queue messages for the Macula server while it is offline
Enabled
Keep alive interval
A ping message will be sent to broker at least at this interval if there is no other traffic occurring
30 seconds
SSL/TLS version
Choose the secure protocol version or leave an insecure connection
none
Certificate
For secure connections, enter the contents of the ca.crt certificate file here (copy from the broker certificate)
[empty]
Enable last will and testament
The message to be sent by broker to other clients in case of a disgraceful disconnect. Specify the message itself, the message topic, QoS*, and choose whether the message should be retained** by broker.
Disabled
*QoS - quality of service - has three levels:
At most once: no delivery guarantee
At least once: guarantees that the message is delivered at least once
Exactly once: highest guarantee, safest and slowest QoS
**The retain flag tells the MQTT broker to always keep the last received message from the client and forward it to every new subscriber. You can retain the LWT message to notify other clients about your MQTT client status.
After entering the MQTT client configuration, click OK to save and close the dialog box. The newly created client configuration will appear in the list. However, the actual MQTT client will not be created not to waste the systems resources: Macula server will create the MQTT client after you use it in an event rule.
Use MQTT Client to Trigger Events
Once you have created one or more MQTT clients, you can use them to subscribe and publish messages to the topics of your choice. For each topic of interest, you need to create one event or action and choose the previously created MQTT client as agent.
To create a new event: in the Events&Actions section of Macula Console, under Events, add a new event and set its type to Event triggered by MQTT notification. Fill in the settings as you would do for your usual MQTT client when subscribing to other clients' messages:
Available settings:
Type: Event triggered by MQTT notification
Title: event name that will appear in the E&A Configurator, corresponds to the macro {EVENT_TITLE}
Source: MQTT client that will subscribe to the current topic and act as event source. Leave empty if you want the event to be visible for all existing MQTT clients
Topic: MQTT topic to subscribe to
Text: incoming message that will trigger the E&A event. If empty, any message will trigger the event. The field cannot be empty if marked as regular expression!
Regular expression: enable this option to enter a regular expression in the Text filed instead of plain text
QoS: required level of quality of service
If you don't know what the exact incoming message will be but you know the format, feel free to enter a regular expression in the Text field.
After you create the event and use it in an active (enabled) rule, the created MQTT client entity will appear in the Monitoring section of Macula Console under MQTT Clients.
If the MQTT client configuration is invalid, the broker is not running/available, or there are other issues, you will see the corresponding error in the Monitoring section of Macula Console. For example, if the broker connection settings are incorrect, the MQTT client status will state that it cannot connect to the broker.
You will also see a relevant message in the Audit log, in the Server section.
Send MQTT Messages
If you wish to send MQTT messages to for other MQTT clients in your system, all you need to do is create an action of the corresponding type in the Event & Action Configurator, and then use it in a rule.
To create a new action in Macula Console, choose Actions in the Events&Actions section, then click the + New action button on the upper panel. Fill in the settings:
Action type: Send MQTT notification
Title: action name that will appear in the E&A Configurator, corresponds to the macro {ACTION_TITLE}
Target: MQTT client pre-configured on the current server; leave empty for the action to be available for all MQTT clients
Topic: MQTT topic
Text: MQTT message text to be published (right-click to insert macros)
QoS: required level of the MQTT quality of service
Click OK to save and close the dialog box; the newly created action will appear in the action list. In the E&A Configurator, the action will appear in the right-hand column, under the MQTT client defined as the action target. If you have not specified the client, the action will appear for every existing and new MQTT clients in your Macula Console configuration.
Last updated