Merge pull request #5 from industrial-edge/updates

Updated HowTo regarding IIH configurator and PLC project

README.md

@@ -9,8 +9,8 @@ This example provides a getting started guide, which shows how to use the Indust
   - [Requirements](#requirements)
     - [Prerequisites](#prerequisites)
     - [Used components](#used-components)
-    - [Studio 5000 Logix Designer Project](#studio-5000-logix-designer-project)
-  - [Configuration steps](#configuration-steps)
+    - [PLC project](#plc-project)
+  - [Configuration](#configuration)
   - [Usage](#usage)
   - [Documentation](#documentation)
   - [Contribution](#contribution)
@@ -20,60 +20,74 @@ This example provides a getting started guide, which shows how to use the Indust
 
 ### Overview
 
-This application example describes how to get the data from a Rockwell PLC using the app Ethernet IP Connector with its respective configurator. The data flow goes through different applications, starting with the data acquisition. Therefore, the Ethernet IP Connector is used which writes all topics to the IE Databus. The Data Service subscribes to all those topics and stores the values in the database. Finally, the values are visualized using Performance Insight.
+This tutorial shows how to use the Industrial Edge applications Ethernet IP Connector to establish a connection between an Industrial Edge Device (IED) and a 3rd party PLC that supports **EtherNet/IP**. These PLC variants are supported:
 
-![Overview](/docs/graphics/overview-eip.png)
+* Allen-Bradley ControlLogix (Rockwell)
+* Allen-Bradley CompactLogix (Rockwell)
+* Allen-Bradley MicroLogix (Rockwell)
+* Allen-Bradley SLC (Rockwell)
+* Omron CJ1 Series PLCs
+* Omron CJ2 Series PLCs
+* Omron CS1 Series PLCs
+
+The Ethernet IP Connector is an application that runs on the individual IED. Connections can be configured using the Common Configurator for Industrial Edge. The connector transfers the value series of selected data points from a PLC to the Databus. From there the data can be used within other Edge apps, e.g. the Flow Creator.
 
 ### General task
 
-The example reads data from a CompactLogix Rockwell PLC using the Ethernet IP Connector. The data is published on the IE Databus. The Data Service monitors the bus and collects the shopfloor data. Therefore, the appropriate adapter for the Ethernet IP Connector must be configured in the Data Service. This data can now be used by the app Performance Insight to visualize the data. See [data-service-how-to](https://github.com/industrial-edge/data-service-configure-s7-adapter-to-collect-data) for further information regarding the Data Service.
+Here we configure a connection to a CompactLogix PLC using the Ethernet IP Connector. The data is published on the IE Databus. By using the application IE Flow Creator, we fetch the metadata of the Ethernet IP Connector, write some data on the configured tags and read out the new data.
+
+![Overview](/docs/graphics/overview-eip.png)
 
 ## Requirements
 
 ### Prerequisites
 
-- Access to an Industrial Edge Management System (IEM)
-- Onboarded Industial Edge Device on IEM
-- Installed System Configurator for Databus on IEM
-- Installed System App Databus on Edge Device
-- Installed Ethernet IP Configurator on Edge Device
-- Installed Ethernet IP Connector on Edge Device
-- Installed Data Service on Edge Device
-- Installed Performance Insight on Edge Device
-- Edge device is connected to Rockwell PLC CompactLogix5370
-- Studio 5000 project loaded on PLC (e.g. for counting application)
-- HTML5-capable Internet browser
+- Access to an Industrial Edge Management (IEM) with onboarded Industrial Edge Device (IED)
+- IEM: Installed system configurator for Databus
+- IED: Installed system app Databus
+- IED: Installed app Ethernet IP Connector
+- IED: Installed app IE Flow Creator
+- IED is connected to the Rockwell PLC CompactLogix via Ethernet
+- Studio 5000 project loaded on PLC
+- Google Chrome (Version ≥ 72)
 
 ### Used components
 
-- Industrial Edge Management (IEM) V 1.2.16 (OS) V 1.2.0-36
-  - IE Databus V 1.2.16
-  - IE Databus Configurator V 1.2.29
-  - Ethernet IP Connector V 1.1.0
-  - Ethernet IP Configurator V 1.1.0
-  - Data Service V 1.2.0
-  - Performance Insight V 1.2.1
-- Industrial Edge Device (OS) V 1.2.0-56
-- Studio 5000 Logix Designer V 32.00
-- CompactLogix 5370 Rev. 32.011
+- Industrial Edge Management (IEM) V1.5.1-4 / V1.8.6
+  - IE Databus Configurator V1.7.8
+- Industrial Edge Device (OS) V1.8.0-6
+  - IE Databus V1.7.1
+  - IIH Configurator V1.5.0
+  - Registry Service V1.5.0
+  - Ethernet IP Connector V2.0.0-5
+  - IE Flow Creator V1.10.0-3
+  - Data Service V1.5.0
+- PLC: Allen-Bradley CompactLogix
+- Studio 5000 Logix Designer V32.00
 
-### Studio 5000 Logix Designer Project
+### PLC project
 
-The used TIA Portal project can be found in the [sources folder](/src) under the following name:
+The used PLC project *Test.ACD* can be found in the [src folder](/src/).
 
-[compactlogix-demo-29042021.7z](./src/compactlogix-demo-29042021.7z)
+## Configuration
 
-## Configuration steps
+You can find further information about the following steps in the [Configuration](/docs/Installation.md) documentation:
 
-You can find further information about the following steps in the [Configuration](/docs/Installation.md) documentation.
-
-- Configure PLC Connection (Databus, EthernetIP Connector)
-- Configure Configure Data Service
-- Configure Performance Insight
+- [Overview](/docs/Installation.md#overview)
+- [Install Ethernet IP Connector](/docs/Installation.md#install-ethernet-ip-connector)
+- [Configure IE Databus](/docs/Installation.md#configure-ie-databus)
+- [Configure Ethernet IP via IIH Configurator](/docs/Installation.md#configure-ethernet-ip-via-iih-configurator)
 
 ## Usage
 
-Once the Data Service app is configured and data is availalbe from a running Rockwell PLC, process data can be collected. Performance Insight visualizes this data and gives data insights (KPIs, metrics, etc.).
+As soon as the Ethernet IP Connector is configured, data can be transfered.
+
+You can find further information about how to handle the data via the IE Flow Creator in the [Usage](/docs/Usage.md) documentation:
+
+* [Read metadata](/docs/Usage.md#read-metadata)
+* [Write data](/docs/Usage.md#write-data)
+* [Read data](/docs/Usage.md#read-data)
+* [Use Data Service](/docs/Usage.md#use-data-service)
 
 ## Documentation
 
@@ -91,6 +105,6 @@ Additionally everybody is free to propose any changes to this repository using P
 
 If you are interested in contributing via Pull Request, please check the [Contribution License Agreement](Siemens_CLA_1.1.pdf) and forward a signed copy to [industrialedge.industry@siemens.com](mailto:industrialedge.industry@siemens.com?subject=CLA%20Agreement%20Industrial-Edge).
 
-## Licence and Legal Information
+## License and Legal Information
 
-Please read the [Legal information](./LICENSE.md).
+Please read the [Legal information](LICENSE.txt).

docs/Installation.md

@@ -1,83 +1,91 @@
 # Configuration
 
 - [Configuration](#configuration)
-  - [Configure PLC Connection](#configure-plc-connection)
-    - [Configure Databus](#configure-databus)
-    - [Configure Ethernet IP Connector](#configure-ethernet-ip-connector)
-  - [Configure Data Service](#configure-data-service)
-  - [Configure Performance Insight](#configure-performance-insight)
+  - [Overview](#overview)
+  - [Install Ethernet IP Connector](#install-ethernet-ip-connector)
+  - [Configure IE Databus](#configure-ie-databus)
+  - [Configure Ethernet IP via IIH Configurator](#configure-ethernet-ip-via-iih-configurator)
 
-## Configure PLC Connection
+## Overview
 
-To read data from a Rockwell PLC and provide the data, we will use the Ethernet IP Connector to establish a connection with the PLC.
-The Ethernet IP Connector sends data to the Databus from where the Data Service can collect and save the needed values.
-In order to build this infrastructure, these apps must be configured properly:
+When working with connectors on Industrial Edge, the **IE Databus** app is required to exchange the data via MQTT. The configuration of the connectors is done via the **IIH Configurator** app. Therefore also the **Registry Service** app is necessary, to find installed connectors on an Industrial Edge Device.
 
-- Databus
-- Ethernet IP Connector
+Make sure the following apps are installed and running on the Industrial Edge Device (IED):
+- IE Databus
+- IIH Configurator
+- Registry Service
 
-### Configure Databus
+## Install Ethernet IP Connector
 
-The system app Databus is essential to exchange data between a PLC and the Industrial Edge Device.
+The Ethernet IP Connector app must be available in your IEM catalog. Proceed the following steps to install the app on your IED:
 
-- Open the Industrial Edge Management web interface
-- Go to "Data Connections" > IE Databus
-- Select the corresponding Industrial Edge Device
-- Create a new user with username and password and give the user publish and subscribe permission
-- Create this topic `"ie/#"`
-- Deploy the databus configuration and wait for the job to be finished successfully
+- open the catalog in the IEM
+- select the Ethernet IP Connector
+- click 'Install'
+- in the tab 'Configurations' click 'Next'
+- in the tab 'Devices' choose your IED
+- click 'Install Now'
+- click 'Install' to allow the installation
 
-![Databus](/docs/graphics/Databus.png)
+![app](/docs/graphics/EIP_App.png)
 
-### Configure Ethernet IP Connector
+## Configure IE Databus
 
-To use the app Ethernet IP Connector properly (which has no web ui), the corresponding app Ethernet IP Configurator is necessary.
-Here the connection to the Rockwell PLC can be configured.
+The system app Databus is essential to exchange data between a PLC and the IED. The Ethernet IP Connector sends the transfered data to the Databus on the IED. From there the data can be used for further processing.
 
-- Open the Industrial Edge Device web interface
-- Make sure that the app Ethernet IP Connector is running
-- Open the app Ethernet IP Configurator
-- Add the Rockwell PLC as data source
+You need to create a user and one or more topics in the Databus configuration, which cover the Ethernet IP data:
 
-![Source](/docs/graphics/ethernet_ip_source.png)
+- ***ie/m/j/simatic/v1/eip1/dp*** for Ethernet IP metadata
+- ***ie/d/j/simatic/v1/eip1/dp*** for Ethernet IP data
+
+Therefore follow these steps:
+
+- open the Industrial Edge Management (IEM)
+- go to 'Data Connections' > IE Databus
+- select the corresponding IED
+- create the topic `ie/#`and a dedicated user with username and password ('edge'/'edge'), set permissions to 'Publish and Subscribe'
+- deploy the configuration and wait for the job to be finished successfully
 
-- Configure the user settings
-
-![Settings](graphics/ethernet_ip_settings.png)
+![databus](/docs/graphics/Databus.png)
 
-- Add all needed tags
+## Configure Ethernet IP via IIH Configurator
 
-![Tags](/docs/graphics/ethernet_ip_tags.png)
+With the IIH Configurator, you can configure several connectors and publish the data to the IE Databus. Therefore, you must enter the Databus credentials within the IIH Configurator:
 
-- Deploy the configuration
-- Start the project
+- open the IED web interface
+- open the app IIH Configurator
+- go to the tab 'Settings' and select the menu 'Databus credentials'
+- enter the databus service name: 'ie-databus:1883'
+- in tab 'Data Publisher settings' enter the databus user name and password ('edge'/'edge')
+- in tab 'Data Subscriber settings' enter the databus user name and password ('edge'/'edge')
+- Save the settings
 
-## Configure Data Service
+![IIH_Settings](/docs/graphics/IIH_Settings.png)
 
-The app Data Service collects the data out of the Ethernet IP Connector and stores it for a defined time period.
-This is a prerequisite for other apps like Performance Insight.
+As soon as the Ethernet IP Connector is installed and started on the same IED as the IIH Configurator, the connector is visible within the configurator. In this example we want to configure an EtherNet/IP connection to a CompactLogix PLC (Allen-Bradley). To configure the Ethernet IP Connector, proceed as following:
 
-- Open the Industrial Edge Device web interface
-- Open the app Data Service
-- Go to the adapter settings and select "Ethernet IP Connector"
-- Enter the username and password for the databus user
-- Activate the adapter
+- go to the tab 'Get data' and select tab 'Databus connectors'
+- select the Ethernet IP Connector
 
-![DataServiceAdapter](/docs/graphics/DataService_Adapter.png)
+![ConnectorOverview](/docs/graphics/IIH_Connector_Overview.png)
+
+- switch to tab 'Tags'
+- choose 'Add data source'
+- configure the PLC accordingly and save
+
+![Source](/docs/graphics/ethernet_ip_source.png)
 
-- Go to the assets view and add new variables for data, comming from the Ethernet IP Connector
+- under column 'Actions' of the newly created PLC, choose 'Add tag'
+- configure a tag as needed and save
 
-![DataServiceAdapter](/docs/graphics/DataService_Add.png)
+![Tags](/docs/graphics/IIH_Tags.png)
 
-![DataServiceAdapter](/docs/graphics/DataService_Variables.png)
+- select the newly created PLC and click 'Deploy'
 
-## Configure Performance Insight
+![Deploy](/docs/graphics/IIH_Deploy.png)
 
-The app Performance Insight is used to visualize the data comming from the Rockwell PLC.
+- back on the overview page 'Databus connectors', the status of the Ethernet IP Connector should be shown as **connected**
 
-- Open the app Performance Insight
-- In the view "My Plant", create a new dashboard
-- Add a new widget "Value" for the parameter `floaty`
-- Add a new widget "Diagram" for the parameter `counter`
+![Connected](/docs/graphics/IIH_Connected.png)
 
-![PerformanceInsight](/docs/graphics/PerformanceInsight.png)
+Now data can be transferred via the Ethernet IP connection. Please find more information in the  [Usage](/docs/Usage.md) documentation.

docs/Usage.md

@@ -0,0 +1,84 @@
+# Usage
+
+- [Usage](#usage)
+  - [Read metadata](#read-metadata)
+  - [Read data](#read-data)
+  - [Write data](#write-data)
+  - [Use Data Service](#use-data-service)
+
+Via the IE Flow Creator, we can write and read the EtherNet/IP data.
+
+The used flow can be downloaded [here](/src/flow.json) and imported into the IE Flow Creator, that is running on the same IED as the Ethernet IP Connector.
+
+## Read metadata
+
+To print out the Ethernet IP Connector metadata, follow these steps:
+
+- create a mqtt in node
+- set the server to 'ie-databus' with port 1883 and corresponding user name/password ('edge'/'edge')
+- set the topic to `ie/m/j/simatic/v1/eip1/dp`
+- create a debug node and connecto to the mqtt in node
+- deploy the flow and watch the debug window
+
+![metadata_flow](/docs/graphics/Metadata_Flow.png)
+
+![metadata](/docs/graphics/Metadata.png)
+
+Now you can see the configured datapoint according to the Ethernet IP settings:
+
+- ***Counter_INT*** with unique id **102**
+- ***Var_BOOL*** with unique id **103**
+- ***Var_REAL*** with unique id **104**
+
+## Read data
+
+To print out the transfered Ethernet IP Connector data, follow these steps:
+
+- create a mqtt in node
+- set the server to "ie-databus" with port 1883 and corresponding user name/password ('edge'/'edge')
+- set the topic to `ie/d/j/simatic/v1/eip1/dp/r/#`
+- create a debug node and connecto to the mqtt in node
+- deploy the flow
+- as soon as the value for a configured tag changes, you can see it in the debug window
+
+![read_data_flow](/docs/graphics/Read_Data_Flow.png)
+
+Since the read payload only contains the tag ID and not the tag name, you need to assign the tag ID according to the metadata. Here the parameter ***Counter_INT*** (tag ID **102**) is incremented automatically by the PLC, so we can read each single value:
+
+![read_int](/docs/graphics/Read_Int.png)
+
+## Write data
+
+To write some data on the Ethernet IP tag, you must fetch the tag ID from metadata payload based on the tag name. Here we want to write to the parameter ***Var_REAL*** (tag ID **104**). Please follow these steps:
+
+- create an inject node with this JSON payload: `{ "vals": [ { "id": "104", "val": "111" } ] }`
+- create a mqtt out node
+- set the server to 'ie-databus' with port 1883 and corresponding user name/password ('edge'/'edge')
+- set the topic to `ie/d/j/simatic/v1/eip1/dp/w/CompactLogix`
+- connect the inject node to the mqtt out node
+- deploy the flow
+- click the inject button, to write the value
+
+![write_data_flow](/docs/graphics/Write_Data_Flow.png)
+
+![write_int](/docs/graphics/Write_Int.png)
+
+## Use Data Service
+
+The app Data Service collects the data out of different connectors and stores it for a defined time period. This is a prerequisite for other apps like Performance Insight.
+
+To activate the data transfer from the Ethernet IP Connector, proceed as following:
+
+- open the IED web interface
+- open the app Data Service
+- go to tab 'Connectors' and select 'Ethernet IP Connector'
+- select the edit button and enter the user name and the password for the Databus user
+- activate the adapter and save
+
+![DataServiceAdapter](/docs/graphics/DataService_Adapter.png)
+
+- go to tab 'Assets & Connectivity' and add the variables, that were configured within the Ethernet IP Connector
+
+![DataServiceAdapter](/docs/graphics/DataService_Add.png)
+
+- data is now collected by the Data Service and can be used by further apps