CHIPKIN FS-8705-101 MQ Telemetry Transport Ethernet Driver Instruction Manual

CHIPKIN FS-8705-101 MQ Telemetry Transport Ethernet Driver

MQTT Description

The MQTT Driver allows the FieldServer to transfer data from devices over Ethernet using the MQTT protocol. The MQTT Driver uses TCP. The default port is 1883 and is configurable. The driver was developed for the streaming MQ Telemetry Transport (MQTT) protocol. MQTT is an OASIS standard messaging protocol for the Internet of Things (IoT). It is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with a small code footprint and minimal network bandwidth. See https://mqtt.org/ for more information. The FieldServer can emulate both a MQTT Subscriber (Client) and Publisher (Server). When configured as a Subcriber, the MQTT driver will connect to the configured MQTT brokers and subscribe to the configured topics for data. This data is stored on the FieldServer to be mapped to other protocols or simply to be viewed. When configured as a Publisher, the MQTT driver connects to the configured MQTT brokers and publishes data received from other protocols to make them available to MQTT Subscribers. The information that follows describes how to expand upon the factory defaults provided in the configuration files included with the FieldServer

Connection Description

This block diagram lists common network connections that can monitor MQTT data using other protocols like Modbus® RTU/TCP, BACnet® and HTTP.

MQTT Configuration

To configure the MQTT driver, from the home page, visit the following link: Error! Hyperlink reference not valid. To configure the FieldServer, follow the instructions below to add a Connection (information on how to setup the connection), Nodes (MQTT Broker information), and finally Tasks (subscriptions and publishes).

Create Connection
To set up the FieldServer as a passive MQTT server, first create a connection. The connection contains information about the physical port.

1. Click on the “Create Connection” button to open the Create Connection form.
2. Fill out the fields in the form. The fields are as follows:
   Column Title| Function| Legal Values
   ---|---|---
   Name| Name of the server, used internally as an identifier| Text, must be unique
   Type| The type of connection this is| ethernet
   Parameters: Port| The physical port on the FieldServer to use| n1
   • Bolded values are defaults
3. Click the “Save” button to add the connection.
   If successful, the new entry will be populated in the Connections table :

Create Node
Follow the instructions below to configure the information to connect to a MQTT Broker.

1. Click on the “Create Node” button to open the Create Node form.
2. Fill out the fields in the form. The fields are as follows:
   Column Title| Function| Legal Values
   ---|---|---
   Name| The name of the variable to add.| Text, must be unique
   Node| The broker to use.| Text (Use the name of a node created in the previous section)
   DataBroker: Name| The data array in the protocol engine to retrieve the value.| One of the Data Array names
   DataBroker: Start| The starting offset in the array to retrieve the value| 0 to (“Data_Array_length” – 1)
   DataBroker: Length| The length of values to read from the data array (optional)| 1 to (“Data_Array_length” – 1)
   Topic| The MQTT topic to subscribe to or publish to| Text, must not contain MQTT Topic wildcars
   ScanInterval| How often to subscribe or publish data| 0-3600, 60
   Type| The type of task this is. Valid values: subscribe, publish| Subscribe, Publish
   Template| Currently not use| Text
   QOS| The quality of server| 0 , 1, 2

*Note:** Default values are bolded

3. Click on the “Save” button to add the node.
   If successful, the new entry will be populated in the Nodes table:

Repeat the above steps to add additional universes.

Create Task
Create tasks to add subscriptions to topics or to add publishing tasks to publish data to the specified topic.

1. Click on the “Create Task” button to open the Create Task form.
2. Fill out the fields in the form. The fields are as follows:
   Column Title| Function| Legal Values
   ---|---|---
   Name| The name of the broker| Text, must be unique
   Connection| The name of the connection to use.| Text (Use the name of the Connection created in the previous section)
   Broker| The URL of the MQTT broker in the format of {protocol}://{host}:{port}| Example: mqtt://broker.hivemq.com:188 3
   KeepAlive| The number of seconds to keep the connection alive, set to 0 to disable| 0-3600, 60
   ClientId| The MQTT ClientId that represents this device connecting to the broker| Text, must be unique, Example: fs_qs_mqttAEDriver_01234
   Username| The username required by the broker, if any| Text
   Password| The password required by the broker, if any| Text
   Clean| Specifies where the connection starts as a new Session or is a continuation of an existing Session| Boolean, True

*Note:** Default values are bolded

3. Click the “Save” button to add the task.
   If successful, the new entry will be populated in the Tasks table:

Repeat the above steps to add additional variables.

Saving the Server Configuration
When the configuration is complete, click on the “Save Configuration” button to save all of the updates and changes. For the configuration to take effect, reboot the system.

Resetting the Server Configuration
To clear the configuration and start over, click the “Reset Configuration” button. Then follow the instructions in the sections above to create new connections, nodes, and tasks.

MQTT Test Tools

A list of MQTT testing tools that you can use to test the functionality of your system.

HiveMQ MQTT Browser Client
The MQTT is a MQTT client that runs in the browser. It can be used to test subscriptions by publishing to topics that the FieldServer is subscribe to and can also subscribe to topics that the FieldServer is publishing to. For more information, see The Public MQTT Broker by HiveMQ – Check out our MQTT Demo

License

The license system is no longer used for MQTT driver.

Importing and Exporting Configurations

It is possible to export the current configuration to back it up or simply to make some edits. Users can also import either the entire configuration via a zip file or a PE (Protocol Engine) configuration.

How to Export the Configuration

1. Goto the system configuration page.
2. Click the Export Configuration button.

How to Import the Configuration
The file to import the configuration must be a zip file. The zip file should contain the following folders:

• ae – this folder contains any configuration files for the ae configuration
• documents – this folder contains any driver specific documents. For example, license product keys, etc.
• pe – this folder contains one config.csv file for the pe configuration.

To make sure the folder directory is correct, do an Export first, then extract the files, edit them, then zip them up again.

To import the configuration:

1. Goto the system configuration page http://{IP_ADDRESS}/chipkinConfiguration/ui/
2. Click the “Browse” button in the “Import/Export System Configuration” section and select the zip file containing the configuration to import.
3. Click the “Import Configuration” button and wait for the configuration to finish importing.
4. If successful, a success message will appear prompting a reboot of the Fieldserver for the changes to take effect.

How to Import a PE Configuration
It is possible to import a PE (Protocol Engine) configuration separately. To import a PE configuration:

1. Go to the system configuration page http://{IP_ADDRESS}/chipkinConfiguration/ui/
2. Click the “Browse” button in the “Import Specific Configuration” section and select the csv file containing the pe configuration to import.
3. Click the “Import PE Configuration” button and wait for the configuration to finish importing.
4. If successful, a success message will appear prompting a reboot of the FieldServer for the changes to take effect.

Revision History

Date

| ****

Resp

| Doc. Rev.| ****

Comment

---|---|---|---
08 Dec 2020| ACF| 1| Created initial document
09 Dec 2020| ACF| 2| Removed Firmware Section
02 June 2021| YC| 3| Updated document format
27 June 2022| SWS| 4| Updated tasks to support length. Removed license section

Added payload examples

 |  |  |
 |  |  |

Troubleshooting

Debugging a MQTT connection

• If the FieldServer is not receiving any data from subscriptions, verify the MQTT Broker connection is correct and that the topic exists on the Broker.
• If the FieldServer is not publishing any data, verify the MQTT Broker connection is correct and check that the data point being published exists.
• Check if the MQTT Broker requires a username and password.
• Verify comms by taking a wireshark log or a FieldServer diagnostics log.

Using HiveMQ MQTT Browser Client for Testing
Follow the steps in this section to setup the HiveMQ MQTT Browser Client tool to test MQTT devices.

1. Access the Browser Client: MQTT Websocket Client (hivemq.com)
2. Fill out the Broker Connection information:

• Host: Fill out the host name of the MQTT Broker. If using the example broker, use broker.hivemq.com
• Port: This tool uses websockets, so connect using port 8000.
• Keep all the other options with their default values.

Finally click the “Connect” button to connect to the Broker. If successful, you will see the following:

Setup a Subscription or Publish:

• To setup a subscription:
  • Click the “Add New Topic Subscription” button
• Fill out the form to subscribe to a topic:
• Color: Choose a color to represent the subscription.
• QoS: Select the Quality of Service. If unsure, select 0.
• Topic: Add the topic to subscribe to. If testing all points, you can use wildcards. In the image above, this will record all data points published to chipkin/test/{any topic}. Otherwise, specify the specific topic, for example: chipkin/test/SetPoint. Click the “Subscribe” button to add the subscription. New data points will appear in the Messages section:
• To publish to a topic:
  • Fill out the Publish form:
• Topic: The topic to publish to (cannot contain wildcards)
• QoS: Select the Quality of Server, set to 0 if unsure.
• Message: The data value to publish.

When done, click the “Publish” button.
If the client has been setup with a subscriptions for the same topic that you are publishing to, the published message will show up in the Messages section .

Testing FieldServer as a MQTT Subscriber
The following instructions are how to confirm that a FieldServer that has been configured as a MQTT Subscriber is working correctly.

1. Follow the instructions in Appendix A.2 to use HiveMQ MQTT Browser Client to publish data to the FieldServer configured as a MQTT Subscriber.
2. Access the Data Array page on the FieldServer interface
3. Follow the instructions in Appendix A.2 to publish a value using the HiveMQ MQTT Browser Client.
4. Verify that the values update in the correct Data Array offsets.

Testing FieldServer as a MQTT Publisher
The following instructions are how to confirm that a FieldServer that has been configured as a MQTT Publisher is working correctly.

1. Follow the instructions in Appendix A.2 to use HiveMQ MQTT Browser Client to subscribe to a topic that the FieldServer is publishing to.
2. Access the Data Array page on the FieldServer interface
3. Edit the value in the Data Arrays
4. Verify in the Message section of the HiveMQ MQTT Browser client that the value was published:

Example Configuration

Example publish payloads

The example ‘publish’ payloads from the MQTT driver to the MQTT broker.

Single value

Multiple values

Appendix E. Marketing

Appendix E.1 Case Study
A series of case studies for MQTT can be found here [TODo]-Add Case Study or link to Case Studies…

Appendix E.2 Keyword
MQTT, 1OT, Broker, Pub/Sub, Subscriber, Publisher

Appendix F.

• MQTT Message Queuing Telemetry Transport
• TCP-Transmission Control Protocol

References

• MQTT Dashboard
• HiveMQ - Enterprise ready MQTT to move your IoT data
• MQTT Websocket Client
• MQTT - The Standard for IoT Messaging
• The Free Public MQTT Broker by HiveMQ - Check out our MQTT Demo

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>