Difference between revisions of "MQTT Adapter"

From Datonis
Jump to: navigation, search
m (→‎MQTT Adapter Workflow)
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
  [[Datonis Edge Gateway|Edge Gateway Home]] > '''MQTT Adapter'''
 
  [[Datonis Edge Gateway|Edge Gateway Home]] > '''MQTT Adapter'''
 +
 +
== MQTT Adapter Workflow ==
 +
[[File:MQTT_Adapter_Workflow.png|alt=MQTT Adapter Workflow|center|1047x1047px|MQTT Adapter Workflow|frameless]]
  
 
== Prerequisite ==
 
== Prerequisite ==
 +
* MQTT broker should be installed in your setup and accessible to Datonis Edge.
 +
** To install the MQTT broker in Ubuntu you can follow the steps given at https://www.digitalocean.com/community/tutorials/how-to-install-and-secure-the-mosquitto-mqtt-messaging-broker-on-ubuntu-18-04. You can generate the certificates required for MQTTS connection using the steps given at http://www.steves-internet-guide.com/mosquitto-tls/
 +
** To install the MQTT broker in Windows, you can download the latest exe file from the official mosquitto site https://mosquitto.org/download/. Then you can follow the steps given at https://bytesofgigabytes.com/mqtt/installing-mqtt-broker-on-windows/. To configure the MQTTS you can follow the steps given at https://bytesofgigabytes.com/mqtt/installing-mqtt-broker-on-windows/.
 +
 +
== MQTT Advanced Configuration ==
 +
You can configure the details about the MQTT broker in the advanced configuration tab. You can set the following configurations in this tab:
 +
{| class="wikitable"
 +
!Configuration
 +
!Type
 +
!Description
 +
|-
 +
|config-json*
 +
|JSON
 +
|Advanced configuration json to fine tune adapter.
 +
|-
 +
|MQTT Address*
 +
|String
 +
|The address the MQTT broker listens for incoming connections. Be sure to check if the firewall is configured correctly to allow access to this address. The default value is 0.0.0.0.
 +
|-
 +
|MQTT Port*
 +
|Number
 +
|The port of the MQTT broker. Be sure to check if the firewall is configured correctly to allow access to this port. The default value is 1883.
 +
|-
 +
|MQTT Secure Port*
 +
|Number
 +
|The secure transport port of the MQTT broker. Be sure to check if the firewall is configured correctly to allow access to this port. The default value is 8883.
 +
|-
 +
|User Name
 +
|String
 +
|This is an optional field. The user name is required to access the broker.
 +
|-
 +
|Password
 +
|String
 +
|This is an optional field. The password is required to connect. If the password is empty, no password will be required to connect.
 +
|-
 +
|Scheduled Thread Pool Size
 +
|Number
 +
|The server scheduled thread pool is used for most activities on the server-side that require running periodically or with delays. The default value is 3.
 +
|-
 +
|General Thread Pool Size
 +
|Number
 +
|This general purpose thread pool is used for most asynchronous actions on the server side. The default value is 10.
 +
|-
 +
|Use Integrated MQTT Broker*
 +
|Boolean
 +
|Switch to enable or disable the usage of the integrated MQTT broker, if disabled(i.e. false) external broker can be used. The default value is true. If it is set to true then we can use the integrated MQTT broker to connect to the other Datonis edge services.
 +
|-
 +
|Client Clean Session*
 +
|Boolean
 +
|If set to false, the client will continue with the old session and the broker may deliver older messages. The default value is true.
 +
|}
 +
 +
== MQTT Protocol Connection ==
 +
{| class="wikitable"
 +
!Configuration
 +
!Type
 +
!Description
 +
|-
 +
|Topic Type*
 +
|Enum
 +
|Topic Type of the connection, DATONIS_SCAN and DATONIS_EVENT can be used to consume data from other Edge Gateways, CUSTOM or CUSTOM_JSON can be used for data from any client. CUSTOM is used for the non-JSON messages. CUSTOM_JSON is used for the JSON messages, it will also automatically parse the JSON string message to a JSON object and the context variable 'message_val' will hold a JSON object.
 +
|-
 +
|Subscribe Topics CSV*
 +
|String
 +
|Topics to be subscribed to local MQTT broker for this connection. More than one topic can be put via comma separated values, also wild cards + and # are allowed e.g. 'plc/#, plc/vibration/#, plc/+/pressure/#'.
 +
|-
 +
|Message Parsing Script*
 +
|String
 +
|The default value is 'message_val' i.e. it will pass the message value as it is. All messages would be parsed using this script before passing to the tag script. Context var 'message_val' holds the message, Context var 'message_list' holds the empty list and can be used to return multiple messages for handling collection cases. The return value or non-empty 'message_list' of the script would be passed to all tags.
 +
|-
 +
|Batch Delay (Millis)
 +
|String
 +
|The default value is 100 milliseconds. Once a message arrives, the Adapter waits for this delay to wait for other messages to become available. All the messages accumulated in a batch would be passed to the tags in one go. If a message for the same topic arrives again then the older message would be ignored.
 +
|}
 +
 +
== MQTT Read Tag ==
 +
{| class="wikitable"
 +
!Configuration
 +
!Type
 +
!Description
 +
|-
 +
|Tag Id*
 +
|String
 +
|The unique Tag Id value within a Thing Config object. It is mainly used in metric mappings to map this tag to a thing metric. Only alphanumeric or underscore characters are allowed.
 +
|-
 +
|Match Topics CSV*
 +
|String
 +
|Topics to be matched for this tag. More than one topic can be put via comma separated values, also wild cards + and # are allowed e.g. 'plc/temperature, plc/+/vibration, plc/pressure/#'.
 +
|-
 +
|Message Parsing Script*
 +
|String
 +
|The default value is 'message_val' i.e. it will pass the value as it is. Tag messages would be parsed using this script. Context var 'message_val' holds the value returned from the connection message parsing script. The return value of the script would be passed as the tag value.
 +
|}
  
 +
= Usecases =
  
−
== Settings ==
+
== Usecase 1 ==
−
This is settings section.
+
Let's assume that the machine 'Mixer' is sending the temperature and pressure value to the topic '/mixer' as a JSON value. MQTT broker address is '127.0.0.1', the port is 1883, the username is 'altizon' and password is 'altizonmqtt'.
 +
# Machine 'Mixer' sends the value '{\"temperature\":45,\"pressure\":6}' to the topic '/mixer'.
 +
# Now let's set up the MQTT broker configuration. Go to the advance configuration tab in the MQTT adapter and set following configurations:
 +
## set MQTT Address to '127.0.0.1'.
 +
## set MQTT Port to 1883.
 +
## set User Name to 'altizon'.
 +
## set password to 'altizonmqtt'.
 +
## set Use Integrated MQTT Broker to false.
 +
# Add a thing in the MQTT Adapter. Follow following steps:
 +
## Delete any existing sample thing.
 +
## Click on the sync button to sync the things from Datonis cloud.
 +
## Select a thing for which you want to send the data.
 +
## Click on the Add thing button.
 +
## Now in the things table select the added thing.
 +
# Set the MQTT adapter connection configurations. Go to the Connections tab under the basic configuration tab in the MQTT adapter and set the following configurations:
 +
## set Topic Type to CUSTOM_JSON.
 +
## set Subscribe Topics CSV to '/mixer'.
 +
## set Message Parsing Script to 'message_val'.
 +
# Set the MQTT adapter read tags. Go to the Read Tags tab under the basic configuration tab in the MQTT adapter and set the following configurations:
 +
## Let's assume that the selected thing has temperature and pressure tags.
 +
## Delete other tags except for the temperature and pressure tags.
 +
## select the temperature tag and do the following configurations:
 +
### set Tag Id to 'temperature'.
 +
### set Match Topics CSV to '/mixer'.
 +
### set Message Parsing Script to 'message_val.temperature'.
 +
## select the pressure tag and do the following configurations:
 +
### set Tag Id to 'pressure'.
 +
### set Match Topics CSV to '/mixer'.
 +
### set Message Parsing Script to 'message_val.pressure'.
 +
# Now save the configuration by clicking on the 'Apply' button.
 +
# Finally, let's test the configuration before enabling it.
 +
# If everything is working then we can now enable the adapter by setting 'enabled' configuration to true and clicking on 'Apply' button.

Latest revision as of 10:29, 6 April 2022

Edge Gateway Home > MQTT Adapter

MQTT Adapter Workflow

MQTT Adapter Workflow

Prerequisite

MQTT Advanced Configuration

You can configure the details about the MQTT broker in the advanced configuration tab. You can set the following configurations in this tab:

Configuration Type Description
config-json* JSON Advanced configuration json to fine tune adapter.
MQTT Address* String The address the MQTT broker listens for incoming connections. Be sure to check if the firewall is configured correctly to allow access to this address. The default value is 0.0.0.0.
MQTT Port* Number The port of the MQTT broker. Be sure to check if the firewall is configured correctly to allow access to this port. The default value is 1883.
MQTT Secure Port* Number The secure transport port of the MQTT broker. Be sure to check if the firewall is configured correctly to allow access to this port. The default value is 8883.
User Name String This is an optional field. The user name is required to access the broker.
Password String This is an optional field. The password is required to connect. If the password is empty, no password will be required to connect.
Scheduled Thread Pool Size Number The server scheduled thread pool is used for most activities on the server-side that require running periodically or with delays. The default value is 3.
General Thread Pool Size Number This general purpose thread pool is used for most asynchronous actions on the server side. The default value is 10.
Use Integrated MQTT Broker* Boolean Switch to enable or disable the usage of the integrated MQTT broker, if disabled(i.e. false) external broker can be used. The default value is true. If it is set to true then we can use the integrated MQTT broker to connect to the other Datonis edge services.
Client Clean Session* Boolean If set to false, the client will continue with the old session and the broker may deliver older messages. The default value is true.

MQTT Protocol Connection

Configuration Type Description
Topic Type* Enum Topic Type of the connection, DATONIS_SCAN and DATONIS_EVENT can be used to consume data from other Edge Gateways, CUSTOM or CUSTOM_JSON can be used for data from any client. CUSTOM is used for the non-JSON messages. CUSTOM_JSON is used for the JSON messages, it will also automatically parse the JSON string message to a JSON object and the context variable 'message_val' will hold a JSON object.
Subscribe Topics CSV* String Topics to be subscribed to local MQTT broker for this connection. More than one topic can be put via comma separated values, also wild cards + and # are allowed e.g. 'plc/#, plc/vibration/#, plc/+/pressure/#'.
Message Parsing Script* String The default value is 'message_val' i.e. it will pass the message value as it is. All messages would be parsed using this script before passing to the tag script. Context var 'message_val' holds the message, Context var 'message_list' holds the empty list and can be used to return multiple messages for handling collection cases. The return value or non-empty 'message_list' of the script would be passed to all tags.
Batch Delay (Millis) String The default value is 100 milliseconds. Once a message arrives, the Adapter waits for this delay to wait for other messages to become available. All the messages accumulated in a batch would be passed to the tags in one go. If a message for the same topic arrives again then the older message would be ignored.

MQTT Read Tag

Configuration Type Description
Tag Id* String The unique Tag Id value within a Thing Config object. It is mainly used in metric mappings to map this tag to a thing metric. Only alphanumeric or underscore characters are allowed.
Match Topics CSV* String Topics to be matched for this tag. More than one topic can be put via comma separated values, also wild cards + and # are allowed e.g. 'plc/temperature, plc/+/vibration, plc/pressure/#'.
Message Parsing Script* String The default value is 'message_val' i.e. it will pass the value as it is. Tag messages would be parsed using this script. Context var 'message_val' holds the value returned from the connection message parsing script. The return value of the script would be passed as the tag value.

Usecases

Usecase 1

Let's assume that the machine 'Mixer' is sending the temperature and pressure value to the topic '/mixer' as a JSON value. MQTT broker address is '127.0.0.1', the port is 1883, the username is 'altizon' and password is 'altizonmqtt'.

  1. Machine 'Mixer' sends the value '{\"temperature\":45,\"pressure\":6}' to the topic '/mixer'.
  2. Now let's set up the MQTT broker configuration. Go to the advance configuration tab in the MQTT adapter and set following configurations:
    1. set MQTT Address to '127.0.0.1'.
    2. set MQTT Port to 1883.
    3. set User Name to 'altizon'.
    4. set password to 'altizonmqtt'.
    5. set Use Integrated MQTT Broker to false.
  3. Add a thing in the MQTT Adapter. Follow following steps:
    1. Delete any existing sample thing.
    2. Click on the sync button to sync the things from Datonis cloud.
    3. Select a thing for which you want to send the data.
    4. Click on the Add thing button.
    5. Now in the things table select the added thing.
  4. Set the MQTT adapter connection configurations. Go to the Connections tab under the basic configuration tab in the MQTT adapter and set the following configurations:
    1. set Topic Type to CUSTOM_JSON.
    2. set Subscribe Topics CSV to '/mixer'.
    3. set Message Parsing Script to 'message_val'.
  5. Set the MQTT adapter read tags. Go to the Read Tags tab under the basic configuration tab in the MQTT adapter and set the following configurations:
    1. Let's assume that the selected thing has temperature and pressure tags.
    2. Delete other tags except for the temperature and pressure tags.
    3. select the temperature tag and do the following configurations:
      1. set Tag Id to 'temperature'.
      2. set Match Topics CSV to '/mixer'.
      3. set Message Parsing Script to 'message_val.temperature'.
    4. select the pressure tag and do the following configurations:
      1. set Tag Id to 'pressure'.
      2. set Match Topics CSV to '/mixer'.
      3. set Message Parsing Script to 'message_val.pressure'.
  6. Now save the configuration by clicking on the 'Apply' button.
  7. Finally, let's test the configuration before enabling it.
  8. If everything is working then we can now enable the adapter by setting 'enabled' configuration to true and clicking on 'Apply' button.
Retrieved from "https://docs.datonis.io/mediawiki/index.php?title=MQTT_Adapter&oldid=1688"