ProSoft Technology MVI56E-LDM-MQTT User manual

MVI56E-LDM-MQTT
MQ Telemetry Transport
ControlLogix®Platform
August 3, 2020
QUICK START GUIDE

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Start Here
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 2 of 55
Your Feedback Please
We always want you to feel that you made the right decision to use our products. If you have suggestions,
comments, compliments or complaints about our products, documentation, or support, please write or call
us.
How to Contact Us
ProSoft Technology, Inc.
[phone]
[phone] (Fax)
www.prosoft-technology.com
[email protected]
MVI56E-LDM-MQTT Quick Start Guide
August 3, 2020
ProSoft Technology®, is a registered copyright of ProSoft Technology, Inc. All other brand or product names
are or may be trademarks of, and are used to identify products and services of, their respective owners.
Content Disclaimer
This documentation is not intended as a substitute for and is not to be used for determining suitability or
reliability of these products for specific user applications. It is the duty of any such user or integrator to
perform the appropriate and complete risk analysis, evaluation and testing of the products with respect to
the relevant specific application or use thereof. Neither ProSoft Technology nor any of its affiliates or
subsidiaries shall be responsible or liable for misuse of the information contained herein. Information in this
document including illustrations, specifications and dimensions may contain technical inaccuracies or
typographical errors. ProSoft Technology makes no warranty or representation as to its accuracy and
assumes no liability for and reserves the right to correct such inaccuracies or errors at any time without
notice. If you have any suggestions for improvements or amendments or have found errors in this
publication, please notify us.
No part of this document may be reproduced in any form or by any means, electronic or mechanical,
including photocopying, without express written permission of ProSoft Technology. All pertinent state,
regional, and local safety regulations must be observed when installing and using this product. For reasons
of safety and to help ensure compliance with documented system data, only the manufacturer should
perform repairs to components. When devices are used for applications with technical safety requirements,
the relevant instructions must be followed. Failure to use ProSoft Technology software or approved software
with our hardware products may result in injury, harm, or improper operating results. Failure to observe this
information can result in injury or equipment damage.
Copyright © 2020 ProSoft Technology, Inc. All Rights Reserved.
For professional users in the European Union
If you wish to discard electrical and electronic equipment (EEE), please contact your dealer
or supplier for further information.
Prop 65 Warning –Cancer and Reproductive Harm –www.P65Warnings.ca.gov

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Start Here
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 3 of 55
Important Installation Instructions
Power, Input, and Output (I/O) wiring must be in accordance with Class I, Division 2 wiring methods, Article
501-4 (b) of the National Electrical Code, NFPA 70 for installation in the U.S., or as specified in Section 18-
1J2 of the Canadian Electrical Code for installations in Canada, and in accordance with the authority having
jurisdiction. The following warnings must be heeded:
WARNING - EXPLOSION HAZARD - SUBSTITUTION OF COMPONENTS MAY IMPAIR SUITABILITY
FOR CLASS I, DIV. 2;
WARNING - EXPLOSION HAZARD - WHEN IN HAZARDOUS LOCATIONS, TURN OFF POWER BEFORE
REPLACING OR WIRING MODULES
WARNING - EXPLOSION HAZARD - DO NOT DISCONNECT EQUIPMENT UNLESS POWER HAS BEEN
SWITCHED OFF OR THE AREA IS KNOWN TO BE NON-HAZARDOUS.
Class 2 Power
Agency Approvals and Certifications
Please visit our website: www.prosoft-technology.com

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Start Here
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 4 of 55
Contents
Your Feedback Please................................................................................................................2
How to Contact Us.......................................................................................................................2
Content Disclaimer......................................................................................................................2
Important Installation Instructions................................................................................................3
Agency Approvals and Certifications...........................................................................................3
1Start Here 6
1.1 MQTT-LDM Generic and SparkplugB ...............................................................6
1.1.1 Using the MQTT LDM Generic Implementation ................................................6
1.1.2 Using the SparkplugB Implementation ..............................................................7
2Obtaining Sample Applications 9
2.1 MVI56E-LDM-MQTT Zip File.............................................................................9
2.2 Obtain MQTT Explorer.....................................................................................10
2.3 Obtain Ignition..................................................................................................10
3Connecting to the MVI56E-LDM Module 11
3.1 Physical Connections ......................................................................................11
3.2 Configuring the ControlLogix PLC...................................................................12
3.2.1 Firmware Update .............................................................................................13
3.3 Configuring the MVI56E-LDM’s EtherNet/IP Address .....................................14
4MQTT Generic Type Sample Application 15
4.1 Configuring the Sample Applications...............................................................15
4.1.1 MQTT Generic config.json File........................................................................15
4.1.2 SparkplugB config.json File .............................................................................16
4.2 Un-encrypted Data Exchange..........................................................................17
4.3 MQTT Explorer Client Configuration................................................................18
4.4 Encrypted Data Exchange...............................................................................22
5MQTT SparkplugB Example 25
5.1 Config.json Configuration Requirements.........................................................25
5.2 Configuring the ControlLogix PLC...................................................................26
5.3 Ignition .............................................................................................................27
5.3.1 Installing .modl Files ........................................................................................27
5.4 Configuring the Un-Encrypted Sparkplug Data Exchange ..............................28
5.4.1 Configuring the MQTT Broker Distributor within Ignition.................................29
5.4.2 Configuring the MQTT Subscribing Client and MQTT Engine Within Ignition.31
5.4.3 Configuring the MQTT Publishing Client and MQTT Transmission Within
Ignition 32
5.4.4 Verify Ignition to PLC Communication.............................................................34
5.5 Installing the Ignition Designer Software .........................................................35
5.5.1 Using Ignition Designer to Send Data to the PLC ...........................................36

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Start Here
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 5 of 55
6Prerequisites for Customizing the Sample Application 41
6.1 MVI56E-LDM-MQTT Zip File...........................................................................41
6.2 Turn on Hyper-V ..............................................................................................41
6.3 Docker®............................................................................................................41
7Development Setup 42
7.1 Create User......................................................................................................42
7.2 Sharing the C:/Workspace Folder....................................................................42
8Creating a Build 43
9Configuration File Details 44
9.1 Configuration File Structure.............................................................................44
9.1.1 MQTT Server Settings.....................................................................................44
9.1.2 PLC Path..........................................................................................................45
9.1.3 Sync Time with PLC ........................................................................................45
9.1.4 Status Print Interval .........................................................................................45
9.1.5 Tags.................................................................................................................45
9.2 Configuring Generic MQTT Brokers................................................................46
9.2.1 Generic MQTT Broker .....................................................................................46
9.2.2 Online MQTT Brokers......................................................................................46
9.2.3 Install MQTT Locally........................................................................................47
9.3 Running the Sample Application......................................................................47
10 MQTT-LDM Library 48
10.1 Component Diagram........................................................................................48
10.2 Main API Functions and Data Flow .................................................................49
10.2.1 Functions Implemented by the Library ............................................................49
10.2.2 Callback Function Declarations.......................................................................50
10.3 Logging............................................................................................................51
10.4 Data Flow for Reading Tag Values..................................................................51
10.5 Data Flow for Writing Tag Values....................................................................51
11 Firmware 52
11.1 Firmware Contents ..........................................................................................52
11.2 Run the Application..........................................................................................52
12 Visual Studio 2017 Project 53
12.1 Visual Studio Build...........................................................................................53
13 Support, Service & Warranty 55
13.1 Contacting Technical Support..........................................................................55
13.2 Warranty Information .......................................................................................55

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Start Here
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 6 of 55
1 Start Here
MQTT is a lightweight messaging protocol, ideal for passing IIoT (Industrial Internet of
Things) data from remote locations. For more information, see the MQTT v3.1.1
Specification.
This Quick Start Guide describes how to:
Obtain sample applications
Run MQTT application programs
Setup your LDM development environment
Customize and build your own MQTT application programs
1.1 MQTT-LDM Generic and SparkplugB
1.1.1 Using the MQTT LDM Generic Implementation
The mqtt-ldm is a software library available for free from the ProSoft Technology
website.
This document provides step-by-step information on how to enable communication
between Rockwell Automation®’s ControlLogix®PLC and a simple MQTT Broker, using
MQTT-Explorer.
The goal is to read data from the PLC, and publish to topic(s) on an MQTT Broker. It
also allows subscription to topic(s) on an MQTT Broker to receive new values published
by other MQTT clients, and then write them to the PLC. This is accomplished by running
the sample application on the MVI56E-LDM, connected to the MQTT Broker.
The MVI56E-LDM acts as a Message Queuing Telemetry Transport (MQTT) Client. This
document references two public MQTT Brokers, they are available on the internet for
testing.
Sample data exchanges can be accomplished in unencrypted mode and in encrypted
mode.
The sample application can be used as-is, or you can follow the step-by-step instructions
on how to build it from source code. The sample application features may be extended
to suit your needs.

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Start Here
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 7 of 55
1.1.2 Using the SparkplugB Implementation
This document provides step-by-step information on how to enable communication
between a ControlLogix PLC and Inductive Automation®’s Ignition, using MQTT
SparkplugB.
The goal is to read data from the ControlLogix PLC, then publish it by a topic to the
MQTT Broker. Another MQTT client will subscribe to that topic in that MQTT broker, so
that the Client can present the PLC information to the user. Additionally, the MQTT
Client can publish data of that topic to the MQTT broker. The LDM_MQTT Client can
subscribe to it, and write the data to the PLC.
In the MQTT protocol, one MQTT Client does not require to be programmatically linked
to another MQTT Client.
The MVI56E-LDM acts as a Message Queuing Telemetry Transport (MQTT) Client. This
document references the Ignition Gateway (by Inductive Automation), a Windows
Service. It will require an up-to-date installation of three files from Cirrus link Solutions. It
provides Sparkplug B based MQTT software modules that perform the service of MQTT
Distributor (Broker), the MQTT Engine (Subscribing Client) and the MQTT Transmission
(Publishing Client).
Videos are available to help you to become familiar with the Ignition implementation of
the MQTT and its use by the LDM_MQTT module:
Video 1: What is MQTT?
https://inductiveautomation.com/resources/video/what-is-mqtt
Video 2: How MQTT Works
https://inductiveautomation.com/resources/video/how-mqtt-works
Video 3: MQTT Sparkplug Specification
https://inductiveautomation.com/resources/video/mqtt-sparkplug-specification
Video 4: MQTT & Ignition
https://inductiveautomation.com/resources/video/mqtt-ignition
Video 5: MQTT Distributor Module
https://inductiveautomation.com/resources/video/mqtt-distributor-module
Video 6: MQTT Transmission Module
https://inductiveautomation.com/resources/video/mqtt-transmission-module
Video 7: Using the MQTT Transmission Module to Publish Data
https://inductiveautomation.com/resources/video/using-the-mqtt-transmission-module-to-
publish-data
Video 8: MQTT Engine Module
https://inductiveautomation.com/resources/video/mqtt-engine-module

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Start Here
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 8 of 55
Video 9: Allow Outbound Tag Writes
https://inductiveautomation.com/resources/video/allow-outbound-tag-writes
Video 10: Primary Host ID Setting
https://inductiveautomation.com/resources/video/primary-host-id-setting
Video 11: How to Set Up Transport Layer Security
https://inductiveautomation.com/resources/video/how-to-set-up-transport-layer-security
Video 12: Set Up Store-and-Forward System
https://inductiveautomation.com/resources/video/set-up-storeandforward-system
Note: Each video contains a transcript available on its webpage.

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Obtaining Sample Applications
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 9 of 55
2 Obtaining Sample Applications
2.1 MVI56E-LDM-MQTT Zip File
The MVI56E-LDM-MQTT zip file is available at www.prosoft-technology.com. This file
contains both the Generic and SparkplugB implementations.
1 Navigate to the MVI56E-LDM product webpage.
2 Create a folder on your PC named C:\Workspace and download the MVI56E-
LDM-MQTT-xxx.zip (where xxx is version number) to this folder.
3 Unzip the file in this folder.
4 Make note of the location of the firmware file.
The interface library contains the following components:
c:\Workspace\
Subfolder
Description
aws-iot-device-sdk-
embedded-C
Open source library AWS IoT Device SDK C v4.0.0
cJSON
cJSON, open source C library to parse JSON formatted
configuration file.
mqtt-ldm
MQTT-LDM Library root folder.
build
Location where target binaries are created during build.
docker
Toolchain to build source code and Docker®
configuration files to start container with build
environment.
mqtt-ldm-lib
Source code of the library mqtt-ldm-lib, wrapper on top of
the AWS IoT Device SDK.
scripts
Build scripts.
mqtt-ldm-sample-
app-mvi56e
Source code of the sample application, with default
configuration file; firmware build scripts and some runtime
scripts; and optional Visual Studio 2017 solution and
project files; Visual Studio 2017 solution and project files
for sample application (optional).
src
Source code of the sample application.
test-*
Folders with sample configurations file and certificates to
connect to different MQTT brokers.
Firmware\ mvi56e-
ldm.firmware_<version>_
<date>.firmware
MVI56E-LDM MQTT sample application
mvi56e-ldm
Source code of dependency libraries required to
communicate with the PLC.
tahu
Eclipse Tahu, an open source library with implementation
of the Sparkplug format of encoding/decoding.
LDM_MQTT_.ACD
ControlLogix Ladder Logic file.

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Obtaining Sample Applications
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 10 of 55
2.2 Obtain MQTT Explorer
If you are implementing MQTT-LDM Generic, navigate to http://mqtt-explorer.com and
download MQTT Explorer to a Windows 10 PC. You do not need to perform this step if
implementing SparkplugB.
Note: The MQTT Explorer Windows installer version had issues with storing connection settings, therefore
the portable version is recommended.
2.3 Obtain Ignition
If you are implementing MQTT-LDM SparkplugB, navigate to
https://inductiveautomation.com/downloads/.
You will need to complete a form to gain access to a free trial of Ignition.

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Connecting to the MVI56E-LDM Module
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 11 of 55
3 Connecting to the MVI56E-LDM Module
3.1 Physical Connections
1 With the MVI56E-LDM in the ControlLogix rack, connect the top Ethernet port to
your local network, and connect to the Windows 10 PC.
2 Use the middle Ethernet port to connect to the network where MQTT Broker is
running.
3 Use the bottom port to connect the Windows 10 PC via USB to a 1756-EN2T
module. This is for debugging purposes using TeraTerm (Open Source Telnet
terminal).
Figure 1: MVI56E-LDM-MQTT Generic Type Communication Topology

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Connecting to the MVI56E-LDM Module
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 12 of 55
Figure 2: MVI56E-LDM-MQTT SparkplugB Communication Topology
3.2 Configuring the ControlLogix PLC
1 Open the LDM_MQTT.ACD program and change the appropriate ControlLogix
chassis type to match your hardware and firmware.
2 Download LDM_MQTT.ACD file to the ControlLogix processor by choosing
COMMUNICATIONS > WHO ACTIVE > DOWNLOAD.
3 Install the Sample Application.
Note: If there is an application currently running on the MVI56E-LDM, be sure to back it up before
proceeding.

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Connecting to the MVI56E-LDM Module
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 13 of 55
3.2.1 Firmware Update
1 Obtain the .firmware file from the MVI56E-LDM-MQTT zip file, or that was built in
the “Creating a Build” section in this document.
2 Download the .firmware file to the module via the module’s webpage. Refer to
the MVI56E-LDM Developer Manual for details.
Figure 3: Firmware Update Page
3 At the end of the Firmware Update process, the module reboots and connections
to the module are lost during reboot.
4 The sample application starts running automatically after reboot. It still needs to
be configured.

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport Connecting to the MVI56E-LDM Module
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 14 of 55
3.3 Configuring the MVI56E-LDM’s EtherNet/IP Address
Configure the MVI56E-LDM’s Ethernet port IP addresses by modifying the
/etc/network/interfaces file on the module. Refer to Figure 1 for a sample
communication topology.
Refer to the MVI56E-LDM Developer Manual for detailed information about the
interfaces file. Use an FTP client such as WinSCPTM to edit the eth0 and eth1 sections
of the Interfaces file.
Interfaces file
Parameters
Values
# We always want the loopback interface.
#
auto lo
iface lo loopback
#An example Ethernet card setup:
(broadcast and gateway are optional)
#
auto
eth0
iface eth0
inet static
address
102.168.0.188
network
192.168.0.0
netmask
255.255.255.0
broadcast
192.168.0.255
#gateway
192.169.0.1
auto
eth1
iface eth1
inet static
address
192.168.4.188
network
192.168.4.0
netmask
255.255.255.0
broadcast
192.168.4.255
gateway
192.168.4.1
Figure 4: Network Interfaces

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport MQTT Generic Type Sample Application
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 15 of 55
4 MQTT Generic Type Sample Application
This chapter pertains to installing, configuring, and running MQTT generic type
implementations.
4.1 Configuring the Sample Applications
Configure the MVI56E-LDM MQTT sample application by modifying the
root/psft/sample/mqtt/config.json file on the module.
MQTT reserves port 1883 for unencrypted communication, and port 8883 for encrypted
communication.
4.1.1 MQTT Generic config.json File
If you are using MQTT Generic, edit the config.json file parameter values in the
MVI56E-LDM_MQTT module according to the ‘Values for Un-Encrypted messaging’
column indicated in the following table:
Parameters
Values for un-encrypted messaging
Vales for encrypted messaging
{
"MqttServer": {
"Type":
"Generic",
"Generic",
"Host":
"137.135.83.217",
"137.135.83.217",
"Port":
1883,
8883,
"Timeout"
5000,
5000,
"DoNotUseTls":
1,
0,
"DisableCertificateValidation":
1,
1,
"RootCaFileName":
"root ca.cer",
"root ca.cer",
"ClientCertPublicFileName":
"client_cert_public_key.cer",
"client_cert_public_key.cer",
"ClientCertPrivateFileName":
"client_cert_private_key.pem",
"client_cert_private_key.pem",
"UserName":
"",
"",
"Password":
"",
"",
"ClientId":
"",
"",
"WillTopic":
"Will",
"Will",
"WillMessage":
"PSFT-LDM Disconnected",
"PSFT-LDM Disconnected",
"PublishRetryInterval":
1000,
1000,
"MaxPublishRetries":
10,
10,
"MaxPublishInterval":
5000
5000
"PublishTopicPrefix":
"PSFT",
"PSFT",
"SubscribeTopicPrefix":
"",
"",
"PublishOOS":
1,
1,
"PublishRetain":
1,
1,
},
The remaining section of the "config.json" files are applicable to the PLC communications. No editing required.
Figure 5: MQTT Configuration File

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport MQTT Generic Type Sample Application
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 16 of 55
Two public MQTT Brokers/Servers and Clients can be found here:
1) test.mosquitto.org: current IP = 5.196.95.208. (Subject to change)
2) mqtt.eclipse.org: current IP = 137.135.83.217. (Subject to change)
For this sample configuration, ‘mqtt.eclipse.org’ is accessed remotely and used as the
broker. The locally installed MQTT Explorer is used as the Client.
4.1.2 SparkplugB config.json File
If you are implementing SparkplugB, please skip the following section and restart with
Config.json Configuration Requirements on page 25.

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport MQTT Generic Type Sample Application
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 17 of 55
4.2 Un-encrypted Data Exchange
The home webpage for the MQTT Broker is at https://mqtt.eclipse.org. It has no
diagnostic support.
Figure 6: mqtt.eclipse.org Broker Home Page
Rather than verifying the MVI56E-LDM module’s communication on the eclipse site, the
communication with the remote Broker can be verified by reviewing the log messages on
the module. To do that, open a browser and enter URL:
http://192.168.0.188/log/messages.txt
(Replace 192.168.0.188 with the MVI56E-LDM module’s IP address)
Figure 7: MVI56E-LDM-MQTT successful communications with the remote MQTT Broker
This log file is located in the MVI56-LDM module at this path:
“root/www/html/log/messages.txt”

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport MQTT Generic Type Sample Application
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 18 of 55
4.3 MQTT Explorer Client Configuration
The MQTT Explorer Client must be configured so that the data from the PLC is
displayed in the MQTT Explorer.
Activating an installed unconfigured MQTT Explorer displays the following pop-up. By
default, it has 2 pre-configured settings in the Connections panel.
1 Select mqtt.eclipse.org and ensure that the settings are as follows:
Figure 8: Initial MQTT Explorer Pop-up
2 Click on the icon to add the MQTT Client.
3 Fill out the fields as shown below:
Name: mqtt.eclipse.org
Validate certificate: Off
Encryption: Off
Protocol: mqtt://
Host: mqtt.eclipse.org
Port: 1883
Figure 9: MQTT Explorer Connections Dialog Popup

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport MQTT Generic Type Sample Application
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 19 of 55
4 Click Save, then Connect.
MQTT Explorer displays all other published MQTT Clients currently connected to
the mqtt.eclipse.org broker. Note that published brokers have connections from
many clients, and the client will receive several published messages.
Figure 10: MQTT Explorer Main Display
5 By default, published messages from the MVI56E-LDM are prefixed with “PSFT”.
In order to filter it, enter PSFT in the search field to display the PSFT topics
coming from the module.
Figure 11: PSFT Topic Selected

MVI56E-LDM-MQTT ♦ MQ Telemetry Transport MQTT Generic Type Sample Application
ControlLogix® Platform Quick Start Guide
ProSoft Technology, Inc. Page 20 of 55
6 Observe that the indicated six tags/variables have their values continuously
changing every few seconds. Select the STRING variable as indicated in the
following screen capture:
Figure 12: Selecting String Type
7 Expand the Publish section in the center panel, and add “/Set” to end the topic
name (so it will be equal to the value of the SubscribeTopic field, in the
config.json file). Select payload format type raw.
Figure 13: Preparing the String for Publishing to the Broker
8 In the PLC, disable the highlighted enable text incrementing bit.
Figure 14: Preparing the PLC Program for receiving the published string from the Broker