Page History

...

...

Install the MQTT modules

Install the three MQTT modules listed in the pre-requisites onto your Ignition system following the Cirrus Link Module Installation guide.

...

This allows the three modules to automatically connect and provide a starting base for the tutorial.

...

Configure Primary Host on MQTT Engine and MQTT Transmission

Navigate to the MQTT Engine > Settings in the left side of the Ignition Gateway UI and select the General tab.

...

Edit the Default Set and add a Primary Host ID as shown below:

...

...

Config MQTT Engine File Handling

Now we can configure the MQTT Engine module to process the published files.

...

When complete, it should look similar to the following. Save the changes after confirming.

...

Anchor
configureTransmission configureTransmission

Configure MQTT Transmission to publish files

Now we can configure the MQTT Transmission module to publish files using a configured Transmitter. Navigate to the MQTT Transmission > Settings in the left side bar of the Ignition Gateway UI and select the Transmitters tab.

...

• • Name
    • By default a unique name will be set for this File Record. You can edit this if you choose but it must be unique.
  • Tag Provider
    • Set to 'default'. This is the tag provider where the publish control and information tags will be created. In our example, set to 'default'.
  • Tag Folder Path 
    Tag Folder Path
    • Set to 'files_manual'. This is the tag folder in the specified tag provider where the publish control and information tags will be created. In our example, set to 'files_manual' or 'files_auto'
    • Enable Auto-Publish
      • This will enable auto_publish. Leave this unchecked . This will force manual publishes only  if publishing manually.  
    • Group ID
      • Use the Group ID from your Transmitters Sparkplug ID. For this example, My MQTT Group
    • Edge Node ID:
      • Use the Edge Node ID from your Transmitters Sparkplug ID. For this example, Edge Node faec7e 

        
        

  ...

  After the configuration is saved, it should look similar to below:

  

  ...

  Manually Publish Files

  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 the control and information tags created in the specified tag provider and folder as shown below:

  ...

  • 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

  Note
  The md5 sum file is only required when using the auto publish method. This is needed to ensure that the file to be transferred is complete and ready to be published.

  
  

  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 or through scripting in Ignition. Here are some examples:

  Linux

  Note
  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.
  Note

  Code Block
  language bash
  ubuntu@linux-host:~$ md5sum myfile.bin 07180622a24ebf905cf5f770cd54197a myfile.bin # In the above example, the md5 sum is: 07180622a24ebf905cf5f770cd54197a

  OSX

  Code Block
  language bash
  user@osxhost:~$ md5 sample_file.txt MD5 (sample_file.txt) = 85324ffbcc7d97c478adf53796aff787 # In the above example, the md5 sum is: 85324ffbcc7d97c478adf53796aff787

  Windows

  Code Block
  language powershell
  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

  Ignition Script

  Code Block
  language py
  import hashlib # File to create md5 sum file_name = "D:\MyFiles\test_file.txt" # Open,close, read file and calculate MD5 on its contents with open(file_name, 'rb') as file_to_check: # read contents of the file data = file_to_check.read() # pipe contents of the file through md5_returned = hashlib.md5(data).hexdigest() # Save md5 sum file f = open(file_name + ".md5", "w") f.write(md5_returned) f.close()

  With both files in place, we can now set the 'Publish File Path' tag.

  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

  Image Removed

  Finally, click the 'Publish File' boolean tag. This will begin the file publish process which will cause the file to be published. After doing so, you should see something similar to what is shown below.

  Image Removed

  You should also now see the file to the location you set as the 'Base File Directory' in your MQTT Engine namespace configuration for Sparkplug B.

  Note
  With the File Auto_Publish disabled, the files will be left on the originating filesystem after a successful publish and will need to be removed manually

  Step 6: Viewing the messages in the Ignition logs

  The records published from MQTT Transmission can be be viewed in the Ignition Gateway logs by setting the com.cirruslink.mqtt.engine.gateway.sparkplug.SparkplugPayloadHandler logger to TRACE.

  Tip
  Review the Gateway Loggers from Ignition for details on how to do this.

  Image Removed

  ...

  At this point you have a fully functional system which can be expanded or modified as required. Below are some addition configuration options to try:

  Setup MQTT Transmission to automatically publish files

  ...

  
  

  With the file to be transferred in place, we can now set the 'Publish File Path' tag.

  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

  Image Added

  Finally, click the 'Publish File' boolean tag. This will begin the file publish process which will cause the file to be published. After doing so, you should see something similar to what is shown below.

  Image Added

  You should also now see the file to the location you set as the 'Base File Directory' in your MQTT Engine namespace configuration for Sparkplug B.

  Note
  The files will be left on the originating filesystem after a successful publish and will need to be removed manually

  Auto Publish Files

  Create a File record following the steps in Configure MQTT Transmission to publish files checking the 'Enable Auto-Publish' and configuring the Tag Folder Path to "files_auto".
  
  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 the control and information tags created in the specified tag provider and folder as shown below:

  Image Added

  The control and information tags created in the folder are:

  Name	Type	Description
  Last Published File	String	Name of last published file
  Last Published Sequence Number	Integer	Sequence number of last published file since last reset of metrics
  Percent Completed	Byte	Publish completion percent for file being published
  Publish File Count	Long	Number of files published since last reset of metrics
  Publish File in Transit	String	Name of current file being published
  Publish Files Folder	String	Full path to the target folder containing the files to publish over MQTT
  Publish Operation Status	String	Status description of current publish operation
  Publish Operation Status Code	Integer	Status code for current publish operation
  Reset	Boolean	Trigger to reset publish metrics

  
  

  At this point, we just need to tell MQTT Transmission which file to send. Download and unzip this sample file to some location and note that location.

  This sample_file.zip contains two text files which 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

  
  

  
  

  Note
  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.

  
  

  Note

  When transferring files using auto_publish, 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 md5 sum file is needed to ensure that the file to be transferred is complete and ready to be published. 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 or through scripting in Ignition. Here are some examples: Linux Code Block language bash ubuntu@linux-host:~$ md5sum myfile.bin 07180622a24ebf905cf5f770cd54197a myfile.bin # In the above example, the md5 sum is: 07180622a24ebf905cf5f770cd54197a OSX Code Block language bash user@osxhost:~$ md5 sample_file.txt MD5 (sample_file.txt) = 85324ffbcc7d97c478adf53796aff787 # In the above example, the md5 sum is: 85324ffbcc7d97c478adf53796aff787 Windows Code Block language powershell 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 Ignition Script Code Block language py import hashlib # File to create md5 sum file_name = "D:\MyFiles\test_file.txt" # Open,close, read file and calculate MD5 on its contents with open(file_name, 'rb') as file_to_check: # read contents of the file data = file_to_check.read() # pipe contents of the file through md5_returned = hashlib.md5(data).hexdigest() # Save md5 sum file f = open(file_name + ".md5", "w") f.write(md5_returned) f.close()

  
  MQTT Transmission will scan the folder specified in the tag, with a frequency defined by the File Scan Rate, and publish all files that appear in this directory automatically.

  Note
  When the file is successfully transferred both the file and associated md5 sum file will be removed from the originating filesystem.

  
  Viewing the messages in the Ignition logs

  The records published from MQTT Transmission can be be viewed in the Ignition Gateway logs by setting the com.cirruslink.mqtt.engine.gateway.sparkplug.SparkplugPayloadHandler logger to TRACE.

  Tip
  Review the Gateway Loggers from Ignition for details on how to do this.

  Image Added

  
  
  
  Extra Activities

  At this point you have a fully functional system which can be expanded or modified as required. Below are some addition configuration options to try: will be removed from the originating filesystem.
  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.Image Removed

  Adjust the file transfer configuration to define how quickly a file transfer occurs and how long before a timeout will occur on failure to receive host side acknowledgements based on the size of files you are sending and any bandwidth constraints that you may have.

  ...