MQTT Node

The MQTT Node allows a workflow to publish a message to the configured topic on the WEGnology MQTT Broker, the Gateway Edge Agent Local Broker, a configured external broker, or an MQTT Integration.

Node Properties

Regardless of workflow class, there are two required properties that must be set within the node:

• Topic Template: Enter a string template for the topic on which to publish the message. This must render to a valid topic name, and depending on the selected broker, there may be additional rules around the topic’s format.
• Message Template: Optionally, you may also enter a message to publish on the chosen topic. If no message is entered, or if the string template entered in this field does not resolve to a value, a blank message will be published on the specified topic.

Depending on the workflow class in which the node is being utilized, there are additional configuration options and validation rules.

Application & Experience Workflows

In Application Workflows and Experience Workflows, you must also choose the broker on which to publish your message …

• WEGnology MQTT Broker: By default, the message will be published on the WEGnology MQTT Broker. When choosing this option, there are additional rules for the custom topic on which you are attempting to publish your message.

• MQTT Integration: Any MQTT Integrations you’ve created in your application are also options for where to publish the message. The integration ID is templatable.

  • You may enter any valid MQTT topic; it does not have to be a topic you configured for triggering workflows when setting up the integration.
  • If the integration is disabled, the node will throw an error.
  • If the integration is disconnected, the delivery will occasionally retry for up to one hour. WEGnology will queue a maximum of 1,000 messages per integration.

Edge Workflows

Usage of the MQTT Node in Edge Workflows also requires choosing the broker on which to publish the message …

• WEGnology MQTT Broker: By default, the message will be published on the WEGnology MQTT Broker, and the custom topic rules will still apply. Also, if the agent is offline, the message will be queued and will attempt to send again once a connection to the broker is re-established.

• Local Broker: In Gateway Edge Agent v1.17.0 and higher, the GEA’s local MQTT broker is available as an option. You can learn more in the Gateway Edge Agent broker documentation.

  • You may enter any valid MQTT topic.
  • Messages are published with a QoS level of 1.

• External Broker: In Gateway Edge Agent v1.42.0 and higher, external brokers are available as an option. You can learn more in the MQTT client configuration documentation.

  • When choosing External Broker an additional configuration field is required: the MQTT Client Configuration Name Template. This is a template that must resolve to the name of the MQTT client configuration that you have defined in the GEA’s configuration file. If the resolved name is not the name of an MQTT client configuration, the node will throw an error.
  • You may enter any valid MQTT topic; it does not have to be one of the subscription topics defined in the named configuration.
  • Messages are published with a QoS level of 1.
  • If the agent is not currently connected to the external broker, the message will be queued and will attempt to send again once a connection to the broker is re-established - however, if the agent is restarted, any queued messages will be discarded.

Embedded Workflows

Embedded Workflows are a special case: They do not require choosing a broker on which to publish the message. Instead, when the node executes, the Embedded Edge Agent will invoke its eea_send_message method with the following arguments:

1. Topic: The resolved value of the string template entered in the Topic Template field.
2. Topic Length: The length, in bytes, of the Topic argument.
3. Message: The resolved value of the string template entered in the Message Template field.
4. Message Length: The length, in bytes, of the Message argument.
5. QoS: The Quality of Service with which this message should be treated. The value is always 1.

It is up to the native code on the device to then send the message through to the WEGnology MQTT Broker.

Embedded Workflows also take an optional “Return Code Path”, which is a payload path at which the error code returned by eea_send_message will be placed. 0 is considered successful, and any non-0value is treated as an error. If a “Return Code Path” is not provided, and eea_message_received returns a non-0 value, the node will throw an error and execution of the workflow will stop.

Throttling And Limits

When sending messages to the WEGnology cloud broker, the MQTT Node has the same throttling and data size limit rules as messages published to the broker directly.

• The node is limited to 30 calls in a 15-second window (per topic) — on average, 2 calls per second.
• Additionally, MQTT Node allows for sending a maximum message size of 1 MB to the WEGnology cloud broker.

Related Nodes

• MQTT Trigger