User Guide Contents GFK-3019G Oct 2019 Contents Chapter 1: Introduction ............. 1 Revisions in this Manual ................1 Related Documentation ................1 1.2.1 Product Landing Pages ..............1 Other Documentation ................. 2 Chapter 2: Overview ............3 Machine Adapter Definition ................. 3 Minimum Requirements to Get Started ............
Page 3
User Guide Contents GFK-3019G Oct 2019 Configuring the Modbus RTU Machine Adapter ......... 17 4.4.1 Modifying the Configuration Files Manually ........17 4.4.2 Field Agent Configuration Tool ............20 4.4.3 Deploying the Modbus RTU Machine Adapter........22 Performance ..................... 22 Troubleshooting ..................
Page 4
User Guide Contents GFK-3019G Oct 2019 5.7.12 Null Timeseries Tag Name ............... 34 Chapter 6: EtherNet/IP Machine Adapter ......35 EtherNet/IP Machine Adapter Architecture ..........35 6.1.1 Features and Compatibility ............. 35 6.1.2 Supported File Types ............... 35 Supported file types when sending PCCC commands......... 35 Supported data types when sending CIP messages ........
Chapter 1: Introduction Revisions in this Manual Date Description Following Emerson’s acquisition of this product, changes have been Oct 2019 made to apply appropriate branding and registration of the product with required certification agencies. No changes to material, process, form, fit or functionality.
The Predix Machine platform ships with Machine Adapters that are suitable in production for OPC UA and Modbus® TCP. These Machine Adapters have been validated on the various Field Agent hardware platforms provided by Emerson business. Additionally, Automation & Controls provides additional Machine Adapters to support the additional industrial protocols of EGD, Modbus RTU, OSI PI, and EtherNet/IP™.
As of this document revision, the Field Agent Configuration Tool only supports configurations for the Modbus-RTU. You cannot use the Field Agent Configuration Tool for other machine adapters. For more updated information on supported machine adapters, please visit Emerson support site and search for Field Agent Configuration Tool.
“Deploy”. 2.3.2 Application Template 6. Download the configuration template for the machine adapter from Salesforce: https://www.emerson.com/Industrial-Automation-Controls/support. 7. Go to EdgeManager and login with your credentials. 8. Click on “Repository” and “Select Action” > “Upload” to upload the application template.
Chapter 3: EGD Machine Adapter EGD Machine Adapter Architecture Ethernet Global Data (EGD) is a proprietary protocol used by Emerson to communicate between industrial data sources. EGD enables a producer (e.g. a CPU) to share a portion of its internal reference memory with consumers (e.g. one or more other CPUs). The EGD Machine Adapter enables Field Agents to consume EGD exchanges to make this industrial data available to the Predix Machine platform and Predix Cloud.
User Guide Chapter 3 GFK-3019G Oct 2019 Configuring the EGD Machine Adapter Many Predix Machine bundles use configuration files to specify their behavior. These configuration files can be managed both from EdgeManager across multiple Field Agents and, under limited circumstances, from the Predix Machine Web Console for an individual Field Agent.
Page 12
User Guide Chapter 3 GFK-3019G Oct 2019 File Source Deployment Modification Destination com.ge.dspmicro.w <Predix Machine <Predix Machine Required for ebsocketriver.send- Configuration Template Configuration sending data to 0.config Directory>\configuration\ Template the cloud machine Directory>\configura tion\machine org.ops4j.pax.loggi <Predix Machine <Predix Machine Optional for ng.cfg Configuration Template Configuration...
Page 13
User Guide Chapter 3 GFK-3019G Oct 2019 bind-address is the IP address to bind when listening for EGD messages. — This configuration item is only supported in the Windows® operating system, and is hence not supported on Automation & Controls Field Agents.
Page 14
User Guide Chapter 3 GFK-3019G Oct 2019 element. If the <Var Name> element is not defined, then <Var EgdId> value will populate {%VarName}. 3. Edit the data contained within the Producer element: • Name is the name of the producer. Valid characters: A-Z, a-z, 0-9 and underscores (_).
Currently the Field Agent Configuration Tool does not support configurations for the EGD machine adapter. For more updated information on the Field Agent Configuration Tool, please visit:https://www.emerson.com/Industrial-Automation-Controls/support. Performance EGD data throughput to Time Series Database (TSDB) is dependent on the number of EGD exchanges processed, as well as network bandwidth of both EGD and cloud networks.
User Guide Chapter 3 GFK-3019G Oct 2019 https://localhost:8443/egd/startup Elements of the EGD Debug Webpage The webpage has the following elements: • Startup Messages: messages from the EGD machine adapter starting up, indicating configurations of the machine adapter. • Configuration: configurations that the EGD machine adapter is utilizing, including the data subscription name, EGD xml config file name and the Predix machine home directory.
User Guide Chapter 3 GFK-3019G Oct 2019 b. Select the template and click on “Select Action” > “Download”. Unzip the zip directory. d. Open the file and verify the .jar file is present in the <Zip Folder Directory Path>\machine\bundles directory. 4.
After downloading the zip file containing the Modbus RTU Machine Adapter, verify the file integrity by calculating a SHA-256 sum of the zip file and compare it to the expected SHA- 256 sum posted on the download page.
Page 20
User Guide Chapter 4 GFK-3019G Oct 2019 • Customers that want to use the Field Agent Configuration Tool to generate Modbus RTU configuration files can ignore the files in this zip. • Customers that want to add these configuration files to an existing Configuration Template can do so using the instructions below.
Page 22
User Guide Chapter 4 GFK-3019G Oct 2019 bitBaseAddress is an optional parameter whose value is either “0“ (the — default) or “1”. This controls the whether the Machine Adapter uses zero or one-based addressing for bit offsets within a register. defaultModbusByteOrder is an optional parameter whose value is either —...
Page 23
User Guide Chapter 4 GFK-3019G Oct 2019 ▪ The bitIndex attribute is only valid for BOOLEAN data types of HOLDING and INPUT registers, and indicates the bit offset within the register to interpret as a Boolean value. When bitBaseAddress=”0”, the valid values are 0-15 inclusive. When bitBaseAddress=”1”, the valid values are 1-16 inclusive.
.config files used to consume incoming Modbus RTU data and send it to a Time Series Database. The Field Agent Configuration Tool can be downloaded from the following URL: https://www.emerson.com/Industrial-Automation-Controls/support. After installing the Field Agent Configuration Tool, follow the steps below: 1. On the Summary tab, fill out the Field Agent Device Settings fields.
Page 25
User Guide Chapter 4 GFK-3019G Oct 2019 h. Set the Channel Settings according to the format used by the Modbus Slave. Click the “Save Data Source” button. 4. On the Data Groups tab, configure one or more data groups. a. Click the “Add Data Group” button, select Modbus Serial Data Group, and press “Add”.
The Mini Field Agent Application and Configuration Templates for Predix Machine 17.1.2 can be downloaded from the URL mentioned below. https://www.emerson.com/Industrial-Automation-Controls/support Detailed instructions for how to upload and deploy EdgeManager Applications and Configurations found in the Application Management and Configuration Management sections of the Field Agents User Guide, GFK-2993.
User Guide Chapter 4 GFK-3019G Oct 2019 4.6.1 RS-232 Cable Disconnected between Field Agent and Modbus Slave When the RS-232 cable between the Field Agent and the Modbus RTU Slave is disconnected, the Modbus RTU Machine Adapter will log the following error messages to the machine.log file, which is also displayed inside the Predix Machine Web Console OSGi Log Service.
User Guide Chapter 4 GFK-3019G Oct 2019 To correct this error, reconfigure the XML file to specify the correct register address on the Modbus Slave and the Modbus RTU Machine Adapter will automatically read the correct Modbus data. Until the configuration is corrected, the Modbus RTU Machine Adapter will not attempt any retries.
Page 29
User Guide Chapter 4 GFK-3019G Oct 2019 to the machine.log file, which is also displayed inside the Predix Machine Web Console OSGi Log Service. com.ge.ac.machineadapter.modbusrtu.api.ModbusMachineAdapterException: Invalid configuration information: Invalid register type HOLD. To correct this error, reconfigure the XML file to specify the correct registerType and the Modbus RTU Machine Adapter will automatically read the correct Modbus data.
After downloading the zip file containing the OSI PI Machine Adapter, verify the file integrity by calculating a SHA-256 sum of the zip file and compare it to the expected SHA-256 sum posted on the download page.
User Guide Chapter 5 GFK-3019G Oct 2019 Deployment Options The OSI PI Machine Adapter is packaged as a single zip file containing two separate components: 1. An inner zip file containing the OSI PI Machine Adapter binaries (.jar). • Customers that want to deploy the non-configured OSI PI Machine Adapter into a running system can directly upload the zip to EdgeManager as an Application and deploy it.
User Guide Chapter 5 GFK-3019G Oct 2019 Add the OSI PI Machine Adapter configuration files (manually copied from the package downloaded) to an existing Configuration Template, like the MFA Configuration Template for Predix Machine 17.1.3. d. Deploy a Configuration Template including the OSI PI Machine Adapter configuration files as an EdgeManager Configuration.
Page 33
User Guide Chapter 5 GFK-3019G Oct 2019 The piServerIpAddress attribute must be set to the web URL where the PI Server — is installed. The piServerPort attribute must be set to the port number for the PI Server, — which is configured at the time of PI Web API installation. Default value is 443. Each tag element corresponds to one PI Point on the PI Server ▪...
The Mini Field Agent Application and Configuration Templates for Predix Machine 17.1.3 can be downloaded from the URLs below. https://www.emerson.com/Industrial-Automation-Controls/support. Detailed instructions for how to upload and deploy Edge Manager Applications and Configurations found in the Application Management and Configuration Management sections of GFK-2993 Field Agents User Guide.
User Guide Chapter 5 GFK-3019G Oct 2019 5.7.1 Invalid PI Server IP Address When the configured PI Server piServerIpAddress in adapter configuration file com.ge.ac.machineadapter.osipi-0.xml is invalid, the OSI PI Machine Adapter will log the following error message to the machine.log file, which is also displayed inside the Predix Machine Web Console OSGi Log Service.
User Guide Chapter 5 GFK-3019G Oct 2019 To correct this error, reconfigure the XML file to specify the correct proxyPort 5.7.5 Invalid Data Node Name When the configured name for node under piConfig element in adapter configuration file com.ge.ac.machineadapter.osipi-0.xml is invalid, the OSI PI Machine Adapter will log the following error message to the machine.log file, which is also displayed inside the Predix Machine Web Console OSGi Log Service.
User Guide Chapter 5 GFK-3019G Oct 2019 5.7.8 Invalid PI Point Name When the configured piPointName for data point under tag element in adapter configuration file com.ge.ac.machineadapter.osipi-0.xml when specified in PIPointName format is invalid, the OSI PI Machine Adapter will log the following error message to the machine.log file, which is also displayed inside the Predix Machine Web Console OSGi Log Service.
User Guide Chapter 5 GFK-3019G Oct 2019 To correct this error, reconfigure the XML file to specify the valid com.ge.ac.machineadapter.osipi.serverPassword for PI server. 5.7.12 Null Timeseries Tag Name When the configured tsTagName for data point under tag element in adapter configuration file com.ge.ac.machineadapter.osipi-0.xml is empty, the OSI PI Machine Adapter will send piPointName to the Predix Time Series Database instead.
User Guide Chapter 6 GFK-3019G Oct 2019 Chapter 6: EtherNet/IP Machine Adapter EtherNet/IP Machine Adapter Architecture EtherNet/IP is an open, industry standard network protocol used by many industrial devices to communicate over Ethernet networks. The EtherNet/IP Machine Adapter enables a Field Agent to read data from an EtherNet/IP Field Device using either the Common Industrial Protocol (CIP) or the Programmable Controller Communication Commands (PCCC) protocol and make this industrial data available to the Predix Machine platform and Predix Cloud.
The EtherNet/IP Machine Adapter must be purchased for each Field Agent where it will be installed. It can then be downloaded from the following location: https://www.emerson.com/Industrial-Automation-Controls/support. After downloading the zip file containing the EtherNet/IP Machine Adapter, verify the file integrity by calculating a SHA-256 sum of the zip file and compare it to the expected SHA-256 sum posted on the download page.
User Guide Chapter 6 GFK-3019G Oct 2019 Deploy the output of the Field Agent Configuration Tool as an EdgeManager Configuration. 2. Deployment Option 2: EtherNet/IP Machine Adapter Application + Configuration Template a. Deploy the EtherNet/IP Machine Adapter Application zip (from the package downloaded) as an EdgeManager Application.
User Guide Chapter 6 GFK-3019G Oct 2019 6.4.1 Modifying the Configuration Files Manually The steps to configure the EtherNet/IP Machine Adapter are: 1. Open the file com.ge.ac.machineadapter.ethernetip-0.xml for editing. 2. Edit the data contained within the dataNodeConfigs element: • Each channel element corresponds to one EtherNet/IP Field Device. The name attribute must contain a unique name given to this Field Device node.
The Mini Field Agent Application and Configuration Templates for Predix Machine 17.1.2 can be downloaded from the URLs below. https://www.emerson.com/Industrial-Automation-Controls/support. Detailed instructions for how to upload and deploy Edge Manager Applications and Configurations are located in the Application Management and Configuration Management sections of the Field Agents User Guide, GFK-2993.
User Guide Chapter 6 GFK-3019G Oct 2019 Actual EtherNet/IP Machine Adapter performance will depend on the capabilities of the EtherNet/IP device and available network bandwidth for Predix communications. Troubleshooting Before attempting some of these possible solutions, be sure to check that the string for each of the configurations in the .config and .xml files are valid and not empty.
User Guide Chapter 6 GFK-3019G Oct 2019 6.6.5 PLC Not reachable or cable disconnected When the cable diconnected with PLC, the EtherNet/IP Machine Adapter will log the following error message to the machine.log file, which is also displayed inside the Predix Machine Web Console OSGi Log Service.
User Guide Chapter 6 GFK-3019G Oct 2019 6.6.10 Tag does not exist (CIP Protocol) When the configured tagame for tag under tag element in adapter configuration file com.ge.ac.machineadapter.ethernetip-0.xml is invalid (for CompactLogix PLC), the EtherNet/IP Machine Adapter will log the following error message to the machine.log file, which is also displayed inside the Predix Machine Web Console OSGi Log Service.
Page 47
Note: If the product is purchased through an Authorized Channel Partner, please contact the seller directly for any support. Emerson reserves the right to modify or improve the designs or specifications of the products mentioned in this manual at any time without notice.