Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The following examples can be found on this page:
This example demonstrates how to use the Listener to return temperature readings from an MQTT broker using minimal configuration. It is designed to work with the MQTT Action Agent Basic Settings Example.
Refer to configuration to understand all configuration options of this Agent.
Drag the MQTT Listener onto the canvas and rename it. Link the output endpoint to the printer and save the Data Stream.
Select the Agent and click Configure. In this case, keep the default Collection.
Fill in the broker address of your MQTT broker and the topic to listen for. In this case, tick to use variables, and select a broker address and topic.
Fill in the payload definition. In this case, leave the payload format default and enter the following properties:
Temperature, Double
Timestamp, DateTime
Apply the changes, save the Data Stream, and publish it.
Let's look at the Live Data View. Make sure the MQTT Action Agent Basic Settings Example is also published.
Observe that any new temperature readings published by the MQTT Action Agent for the specified topic are printed by the Listener.
See the Import, Export, and Clone - XMPro article for steps to import a Data Stream.
This example demonstrates how to use the Listener to return temperature readings from an MQTT broker using advanced configuration.
Refer to configuration to understand all configuration options of this Agent.
Drag the MQTT Listener onto the canvas and rename it. Link the output endpoint to the printer and save the Data Stream.
Select the Agent and click Configure. In this case, keep the default Collection.
Fill in the broker address of your MQTT broker and the topic to listen for. In this case, tick to use variables, select a broker address and topic and leave clean session ticked.
Tick the advanced settings to show more configuration options.
Enter the port and QoS option. In this example, select your port and keep the default QoS (Exactly Once).
Tick the secure channel if you want to enable TLS/SSL channel communication and enter the channel details.
In this case, keep the default protocol (TSL v1.2), upload both the root and client certificates and select the client certificate password.
Enter the authentication details: username and password.
Fill in the payload definition. In this case, leave the payload format default and enter the following properties:
Temperature, Double
Timestamp, DateTime
Apply the changes, save the Data Stream, and publish it.
Let's look at the Live Data View. Observe that any new temperature readings published to the MQTT broker for the specified topic are printed.
See Basic Settings Example for a side-by-side results with an Action Agent.
See the Import, Export, and Clone - XMPro article for steps to import a Data Stream.
The MQTT protocol is a lightweight communication method designed for the Internet of Things concept. It allows small devices to communicate on networks with low throughput or high bandwidth usage.
The MQTT Agents allow your Data Stream to send messages to and receive messages from an external MQTT broker.
The following is required to use this Agent:
MQTT broker address
Access to broker port e.g. 1883
Minimum XMPro Data Stream v4.0
File | Link | Security Key |
---|---|---|
File | Link | Security Key |
---|---|---|
The allows you to receive records from sensors that are set up to send messages to an MQTT broker.
The as Remote Agents, allows you to send records between different legs of a single Data Stream running on different Stream Host Collections.
For more information about the MQTT protocol, please .
Name | Link |
---|
Please XMPro if you're looking for an older version of this Agent.
MQTT Listener v2.04 |
MQTT Action Agent v2.02 |
This section explains each of the properties in the configuration blade.
Visit Collections and Stream Hosts to understand more about Collections.
This applies when Use Advanced Settings is ticked.
TLS and SSL provide a secure communication channel between the client and the MQTT broker. It can be used in the Agent if the MQTT broker is configured to support Certificate-based TLS/SSL. This applies when Use Advanced Settings is ticked.
The client certificate and password are not required if the MQTT broker is configured to not require a client certificate. In this case, the root certificate will suffice.
This applies when Use Advanced Settings is ticked.
Before configuring the Action Agent, please ensure that its input endpoint is connected to a parent Agent which will be sending data to it.
This section explains each of the properties in the configuration blade.
This applies when Use Advanced Settings is ticked.
TLS and SSL provide a secure communication channel between the client and the MQTT broker. It can be used in the Agent if the MQTT broker is configured to support Certificate-based TLS/SSL. This applies when Use Advanced Settings is ticked.
The client certificate and password are not required if the MQTT broker is configured to not require a client certificate. In this case, the root certificate will suffice.
This applies when Use Advanced Settings is ticked. Anonymous authentication will be used if these values are not provided.
Data Stream
C0mp|ex123
Data Stream
C0mp|ex123
Property | Description |
---|---|
Property | Description |
---|---|
Property | Description |
---|---|
Property | Description |
---|---|
Property | Description |
---|---|
Property | Description |
---|---|
Name | Description |
---|---|
Property | Description |
---|
Refer to to understand more about Collections.
Property | Description |
---|
Property | Description |
---|
Property | Description |
---|
Property | Description |
---|
Property | Description |
---|
Name | Description |
---|
Collection
This associates the Agent to a specific Collection (defaults to that of the current Data Stream).
Use Variables
Tick to select saved variables; or enter the text manually.
Broker Address
The MQTT broker URL.
Use Dynamic Topic
Tick this to send events to different topics based on an event property, rather than sending all events to the same topic. This will also cause events to be sent as individual messages, rather than in bulk.
Topic
The name of the topic to send messages on the broker (applies when Use Dynamic Topic is not ticked).
Dynamic Topic
The event property which will be used as a topic name (applies when Use Dynamic Topic is ticked).
Retain Message
Tick to tell the broker to remember the latest message this agent sends on each topic, and to send that message to any receivers that connect to that topic. Events will be sent as individual messages, rather than in bulk.
Clear Retained Message Flag
An optional Boolean event attribute to monitor the events (applies when Retain Message is ticked).
If the attribute is true for an event, the event will not be sent as a message. Instead, the retained message for that event's topic will be cleared.
Use Advanced Settings
Tick to use Advanced Settings, Channel, and Authentication for the Broker Connection.
Port
The listener Port for the MQTT broker.
Defaults to Port 1883 if left blank or Use Advanced Settings is not ticked.
Client ID
The unique Client ID when connecting to the MQTT broker. A temporary GUID is generated if left blank or Use Advanced Settings is not ticked. The MQTT broker does not allow a second connection using the same Client ID.
QoS
The Quality of Service defines the guarantee of delivery of messages to the MQTT broker. The options are:
At most once - (QoS 0) Guarantees a best-effort delivery. There is no guarantee of delivery.
At least once - (QoS 1) Guarantees that a message is delivered at least one time to the receiver.
Exactly once - (QoS 2) Guarantees that each message is received only once by the intended recipients.
Defaults to Exactly Once when Use Advanced Settings is not ticked.
Post as Batch
Tick to publish messages from the received event as a batch. The messages are posted as a batch by default when Use Advanced Settings is not ticked and neither Use Dynamic Topic is ticked, nor a Clear Retained Message Flag attribute is selected.
Secure Channel
Tick to use a Secure Channel when connecting to the MQTT broker.
Protocol
The TLS/SSL protocol and version options to use on the Secure Channel are (applies when Secure Channel is ticked):
SSL v3
TLS v1.0
TLS v1.1
TLS v1.2
Root Certificate
The Root CA Certificate of the MQTT broker - usually provided by the MQTT broker owner (applies when Secure Channel is ticked).
Client Certificate
The Client Certificate contains the Public/Private Key pair, which verifies the identity of the client (applies when Secure Channel is ticked). The Client Certificate must be generated from the same CA used by the MQTT broker. This is bundled with its Private key into a PFX format and password protected when exporting.
Client Certificate Password
The Password used to export the Public/Private Key pair of the Client Certificate (applies when Secure Channel is ticked).
Anonymous?
Tick to use Anonymous authentication.
Username
The Username to authenticate the broker connection (applies when Anonymous? is not ticked).
Password
The Password to authenticate the broker connection (applies when Anonymous? is not ticked).
Payload Type
The published payload options are:
Multi-Column JSON - publish a JSON with multiple values from the input payload.
Single-Column Text - publish a single value from the input payload.
Nested Object - publish a Nested Object with the selected properties inside it.
Payload (Multi-Column)
The columns or attributes of the input payload that will be included in the output payload (applies to Multi-Column JSON Payload Type only). If none are specified, all columns will be returned.
Payload (Single-Column)
The column or attribute of the input payload that will be included in the output payload (applies to Single-Column Text Payload Type only).
Object Field Name
The Field Name of the Object where the selected properties will be nested (applies to Single-Column Text Payload Type only).
As Array
Tick to nest the selected properties on the Object as an Array (applies to Nested Object Payload Type only).
Nested Object Properties (Source, Alias)
The properties that will be nested on the object in the output payload:
Source: the column or attribute of the input payload to include.
Alias: the field name of the value when nested on the Object (applies when As Array is not ticked).
Input
This endpoint is used to receive data from the parent Agent.
Output
Events received from the parent Agent are published to the MQTT broker and made available to this endpoint with unchanged attributes and data.
Error
Errors encountered during the execution of this Agent will be published on this endpoint.
Collection | This associates the Agent to a specific Collection (defaults to that of the current Data Stream). |
Port | The listener Port for the MQTT broker. Defaults to Port 1883 if left blank or Use Advanced Settings is not ticked. |
QoS | The Quality of Service defines the guarantee of delivery of messages to the MQTT broker. The options are:
Defaults to Exactly Once when Use Advanced Settings is not ticked. |
Secure Channel | Tick to use a Secure Channel when connecting to the MQTT broker. |
Protocol | The TLS/SSL protocol and version options to use on the Secure Channel are (applies when Secure Channel is ticked):
|
Root Certificate | The Root CA Certificate of the MQTT broker - usually provided by the MQTT broker owner (applies when Secure Channel is ticked). |
Client Certificate | The Client Certificate contains the Public/Private Key pair, which verifies the identity of the client (applies when Secure Channel is ticked). The Client Certificate must be generated from the same CA used by the MQTT broker. This is bundled with its Private key into a PFX format and password protected when exporting. |
Client Certificate Password | The Password used to export the Public/Private Key pair of the Client Certificate (applies when Secure Channel is ticked). |
Username | The Username to authentice the broker connection. |
Password | The Password to authenticate the broker connection. |
Payload Format | The expected format of the received messages. The options are JSON (default), HEX and Plain Text. |
Specify JSON Path to Payload | Tick to allow complex JSON objects to be read from the message by specifying a dot-notation path for each property (applies to JSON Payload Format only). |
Include Source Message in Payload | Tick to add a "SourceMessage" string property to the output payload which contains the original message. |
Include Topic in Payload | Tick to add a "Topic" string property to the output payload which contains the message's topic name. This is useful when using wildcards in the Topic property to distinguish data coming from multiple topics. |
Include Timestamp in Payload | Tick to add a "CurrentTimestampInUTC" datetime property to the output payload which contains the message's current timestamp in UTC. |
Payload Definition (Name, JSON Path, Type, Indexes) | Defines the shape of records that will be received and output:
When using a Plain Text Payload Format, adding or removing grid rows is disabled. One row is made available with "Value" as the Name and "String" as the data type. The data type can be amended. |
Output | An event per received message is made available to this endpoint, with attributes as specified by the Payload configuration. |
Error | Errors encountered during the execution of this Agent will be published on this endpoint. |
Added an Advanced Settings option
Added variable support
Repackaged to include the Agent's Category
Added option to clear retained messages based on new drop-down option to specify an input column that contains a Boolean value
Added a checkbox to choose whether to specify a static topic or dynamic topic and then provide topic name as a static value or select from drop-down respectively
Changed Topic to a drop-down to allow for dynamic topic name
Added checkbox option to Retain message
Updated Help URL
Added ability to reconnect to broker if the connection drops while use case is running
Added Validation
Fixed bug where an unhandled exception could crash the stream host
Initial Release
Added Payload Format option 'Plain Text'
Added 'Include Topic in Payload' property - tick to append a Topic column to the output payload
Added 'Include Timestamp in Payload' property - tick to append a Timestamp column to the output payload
Added support for Topic single-level (+) and multi-level (#) wildcards
Added the Advanced Settings option
Added variable support
Repackaged to include the Agent's Category
Added option to return source message in the payload
Added checkbox to specify whether to use Clean Session or not
Handle re-connection after Broker connection drop - Agent tries to reconnect every 5 seconds until connection is established
Updated help URL
Payload definition - cannot focus out of a new row
Added HEX as payload
Added exception handling to receive method
Added Checkbox option to specify JSON Path for nested payload
Modified listener to handle messages with format as Json Object as well as Json Array
Modified listener to handle messages with nested structure
Added Validation
Unhandled exception crashes the Host
Initial Release
Use Variables | Tick to select saved variables; or enter the text manually. |
Broker Address | The MQTT broker URL. |
Topic |
|
Clean Session | Tick to have the MQTT broker keep undelivered messages for a short period in the event of connection issues, which will be delivered to the listener when connection is re-established; otherwise, any messages that arrive during a connection issue will not be received. |
Client ID | A string to uniquely identify this stream object among the listeners on the topic (applies when Clean Session is not ticked). |
Use Advanced Settings | Tick to use Advanced Settings, Channel, and Authentication for the Broker Connection. |
The following examples can be found on this page:
This example demonstrates how to use the Action Agent to publish curated temperature readings to an MQTT broker using minimal configuration. It is designed to work with the MQTT Listener Basic Settings Example.
Refer to configuration to understand all configuration options of this Agent.
Drag the MQTT Action Agent onto the canvas and rename it. Link the input endpoint to the temperature readings, the output endpoint to the printer, and save the Data Stream.
Select the Agent and click Configure. In this case, keep the default Collection.
Fill in the broker address of your MQTT broker and the topic to listen for. In this case, tick to use variables, and select a broker address and topic.
Select the payload type and content to be published. In this case, leave the default payload type (Multi-Column JSON) and select the temperature and timestamp attributes as the payload.
Apply the changes, save the Data Stream, and publish it.
Let's look at the Live Data View. Make sure the MQTT Listener Basic Settings Example is also published.
Observe that the curated temperature readings are printed, as well as the configured payload is published to the MQTT broker - and printed by the MQTT Listener too.
See the Import, Export, and Clone - XMPro article for steps to import a Data Stream.
This example demonstrates how to use the Action Agent to publish curated temperature readings to an MQTT broker using advanced configuration.
Refer to configuration to understand all configuration options of this Agent.
Drag the MQTT Action Agent onto the canvas and rename it. Link the input endpoint to the temperature rata, the output endpoint to the printer, and save the Data Stream.
Select the Agent and click Configure. In this case, keep the default Collection.
Fill in the broker address of your MQTT broker and the topic to listen for. In this case, tick to use variables, select a broker address and topic and leave clean session ticked.
Tick the advanced settings to show more configuration options.
Enter advanced settings for the MQTT broker. Select a Port, and Client ID. And then leave QoS (Exactly Once) and Post as Batch (ticked) as Default.
Enter the port, client ID, QoS, and post as batch preference. In this example, select your port and client ID. Keep the default QoS (Exactly Once) and batch option (ticked).
Tick the secure channel if you want to enable TLS/SSL channel communication and enter the channel details.
In this case, keep the default protocol (TSL v1.2), upload both the root and client certificates and select the client certificate password.
Enter the authentication details: either anonymous or the username and password.
In this case, leave anonymous unticked and select a username and password.
Select the payload type and content to be published. In this case, leave the default payload type (Multi-Column JSON) and select the temperature and timestamp attributes as the payload.
Apply the changes, save the Data Stream, and publish it.
Let's look at the Live Data View. Observe the curated temperature readings printed, as well as the configured payload published to the MQTT broker.
See Basic Settings Example for a side-by-side results with a Listener.
See the Import, Export, and Clone - XMPro article for steps to import a Data Stream.
The name of the topic to listen for messages on the broker. To subscribe to multiple sites/assets in one Agent, the below can be used:
File | Link | Security Key |
---|---|---|
File | Link | Security Key |
---|---|---|
Data Stream
C0mp|ex123
Data Stream
C0mp|ex123