You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Prerequisites:

Overview:

Transmission is an MQTT module for Ignition that can publish files using MQTT Sparkplug to be processed by MQTT engine. 

Files are transferred using Sparkplug over MQTT and which files get transferred and when they get transferred can be configured in a number of different ways. The file transfer configuration also defines how quickly a file transfer occurs and how long before a timeout will occur on failure to receive host side acknowledgements which can be adjusted as required based on the size of files you are sending and any bandwidth constraints that you may have.

This tutorial shows how to configure the MQTT modules to publish and receive files from one Ignition system to another.


Step 1: Install MQTT Engine and MQTT Distributor on the host machine

Install the MQTT Engine and Distributor modules onto your host Ignition system following the Cirrus Link Module Installation guide.

By default, MQTT Engine is configured to connect to MQTT Distributor on tcp://localhost:1883 and will show as Connected under the Servers configuration setting in the Ignition UI.

Step 2: Install MQTT Transmission on the edge machine

Install the MQTT Transmission onto your edge Ignition system following the Cirrus Link Module Installation guide.

By default, MQTT Transmission is configured to connect to MQTT Distributor on tcp://localhost:1883. As the MQTT Distributor is installed o a different server, we will need to edit the configuration to allow MQTT Transmission to connect to the host server.

The MQTT Server must be accessible to the Ignition system running MQTT Transmission. In order for this to work port 1883 must be open to outside connections. Make sure this is allowed via your operating system's firewall configuration and any anti-virus software you may have installed.

This configuration is not recommended for production systems. If running this in production, you should be using TLS encryption on port 8883. More information on how to configure TLS can be found here.

Navigate to the MQTT Transmission > Settings in the left side bar of the Ignition Gateway UI and select the Servers tab.

Change the server URL to point to the server IP address or domain name of the Ignition system running MQTT Distributor and save the configuration. When complete, you should see something similar to the following:

If you do not see '1 of 1' under the 'Connected' status, check the logs to show what may be going wrong and/or to validate the rest of your configuration

MQTT Transmission will also have an Example Transmitter configured pointing to a set of tags that are configured in the Ignition "default" tag provider. 

Review the MQTT Transmission Transmitters and Tag Trees tutorial for additional information on how Transmitter configurations interact with Ignition tag trees to create the Sparkplug IDs required.

Now we have the three modules connected, we can setup the file publish configuration.

Step 3: Config MQTT Engine 

  • MQTT Engine Settings → Namespaces → Default Tab
    • Click the 'edit' button to the right of the 'Sparkplug B' namespace as shown below
    • Now select the 'Files' tab and set the following
      • Ignore Files: unchecked/false
      • File Host Type: ACTIVE
      • Base File Directory: Set to some directory file path (i.e. 'C:\My Files' or something similar)
      • Add Topic Tokens: checked/true
      • File Storing Policy: REPLACE_EXISTING_FILE
      • When complete, it should look similar to the following. Save the changes after confirming.
    • Finally select the 'Servers' tab and confirm that the 'Status' shows 'Connected' as shown below.
  • Browse to the 'Transmitters' tab and note the 'Sparkplug IDs'. Note these IDs for later use.
    • In the example below, the Sparkplug IDs field is 'My MQTT Group/Edge Node faec7e'. This means the corresponding Group ID and Edge Node ID are:
      • Group ID: My MQTT Group
      • Edge Node ID: Edge Node faec7e
  • Now click the 'Files' tab, select the Create new Files... link and configure the following fields
    • Tag Provider: default
    • Tag Folder Path: files_manual
    • Enable Auto-Publish: unchecked/false
    • Group ID: Use the Group ID you noted in the Transmitter configuration
    • Edge Node ID: Use the Edge Node ID you noted in the Transmitter configuration

    • When complete, it should look as follows. Select the Create New Files to save the settings.

  • After the configuration is saved, it should look as follows

At this point, everything should be configured to send files from MQTT Transmission to MQTT Engine. Open Ignition Designer on the system running MQTT Transmission. You should see a new set of tags there as shown below.

At this point, we just need to tell MQTT Transmission which file to send. Download this sample_file.zip which contains two text files. The two text files are:

  • sample_file.txt

    • This is a text file with an arbitrary string. But, it could be a file of any type. This is purely for demonstration purposes.

  • sample_file.txt.md5

    • This is a text file that contains only the md5 sum of the sample_file.txt


Certain characters have special meanings when used in filenames such as "*" for wildcards, and "\" in filename paths. If a file you are trying to publish contains any of the characters listed below, it will prevent files from being written to the file system.

" * : < > ? / \ |

Leading and trailing spaces in filenames and filenames ending in '.' are also not supported.


Unzip this sample file to some location and note that location. When transferring any file, MQTT Transmission requires two files to be present before it will transfer the target file. The first is the file itself. The second is a file that has the same name as the target file followed by a '.md5' extension. The contents of that file must contain the Message Digest Algorithm 5 (or MD5 sum) of the file. The MD5 sum can be calculated using command line utilities on most operating systems. Here are some examples:

Linux

ubuntu@linux-host:~$ md5sum myfile.bin
07180622a24ebf905cf5f770cd54197a  myfile.bin

# In the above example, the md5 sum is: 07180622a24ebf905cf5f770cd54197a

OSX

user@osxhost:~$ md5 sample_file.txt
MD5 (sample_file.txt) = 85324ffbcc7d97c478adf53796aff787

# In the above example, the md5 sum is: 85324ffbcc7d97c478adf53796aff787

Windows

Get-FileHash -Algorithm MD5 .\some_file.iso

Algorithm       Hash                                                                   Path                                                                              
---------       ----                                                                   ----                                                                              
MD5             80FD169D3FDADBC97E66C168F796B1BF                                       C:\temp\some_file.iso

# In the above example, the md5 sum is: 80FD169D3FDADBC97E66C168F796B1BF


With both files in place, we can now set the 'Publish File Path'. This path must be the full path to the target file to publish over MQTT. In this example, we're using the path of '/tmp/transmission/sample_file.txt'. However, on a Windows system that would look something like 'C:\full\path\to\my\sample_file.txt'. When this is set, you should see something like this

Finally, click the 'Publish File' boolean tag. This will begin the file publish process which will cause the file to be published.  When the file is successfully transferred both files will be removed from the originating filesystem.

After doing so, you should see something similar to what is shown below.

You should also now see the file on the Ignition system with MQTT Engine installed. The file will be saved to the location you set as the 'Base File Directory' in your MQTT Engine namespace configuration for Sparkplug B.

There is also an option to 'automatically' publish files using MQTT Transmission. In the 'File' configuration of MQTT Transmission you can check a tickbox that is 'Enable Auto-Publish'. If this is enabled, MQTT Transmission will create a tag called 'Publish Files Folder' instead of 'Publish File Path' as shown below.

When configured this way, MQTT Transmission will scan the folder specified in the tag and will publish all files that appear in this directory automatically. Just as with the 'manual publish' option, an associated md5 sum file must be present and properly represent the md5 sum of the target file before it will be published.


Advanced Features

The Advanced Settings section of the file transfer configuration define how quickly a file transfer occurs and how long before a timeout will occur on failure to receive host side acknowledgements.

Adjust these as required based on the size of files you are sending and any bandwidth constraints that you may have.

Additional Resources

  • No labels

New to MQTT? Start Here!