EtherNet/IP tutorials

FairCom Edge EtherNet/IP connector service tutorials

This tutorial walks through how to capture, store, transform, forward, and query data using the Ethernet/IP simulator.

Requirements

  • Ensure the FairCom server is installed and running.
  • Verify that the Ethernet/IP service is enabled in the FairCom Edge server.
  1. Edit the services.json file in the config folder.
  2. Locate the "integrationServices" object of the service for the desired platform.
  3. Set "enabled" to true
    1. Windows
      "integrationServices": [
      {
      	"serviceName": "ab",
      	"serviceLibrary": "abservice.dll",
      	"schemaName": "ab",
      	"enabled": true
      },
    2. Unix/Linux
      "integrationServices": [
      {
      	"serviceName": "ab",
      	"serviceLibrary": "libabservice.so",
      	"schemaName": "ab",
      	"enabled": true
      },

4. Save any changes. Restart FairCom Edge Server.

  • Confirm server access by running the FairCom API explorer. The typical URL is https://localhost:8443/.

 

Initialize the Ethernet/IP simulator

For this tutorial, we are using an open-source Ethernet/IP simulator available in the libplctag package.

  1. Download and extract libplctag package that is available at https://github.com/libplctag/libplctag/releases. For example, libplctag_2.7.1_windows_x64.zip.
  2. Open a command prompt and navigate to the directory where the package was extracted. Ensure that the programs ab_server and tag_rw2 are present in this directory.
  3. Run the following command to execute the Ethernet/IP Server simulator.
    1. .\ab_server --plc=ControlLogix --path=1,0 --port=4400 --tag=MESSAGE:STRING[10] --tag=SCADA:dint[10] --tag=TEMPERATURE:real[1]  --tag=OUT_TEMP:real[1]
    2. This instruction executes the Ethernet/IP server simulator of type ControlLogix on port 4400, creating 4 tags: MESSAGE, SCADA, TEMPERATURE and OUT_TEMP—the first two with ten elements each, and the last two with only one element each.
    3. Leave the ab_server program running.
  4. Open another command prompt and navigate to the directory where the libplctag package was extracted.
  5. Execute the following commands to write some data to the Ethernet/IP Server simulator.
    1. .\tag_rw2 --type="sint32" --tag="protocol=ab-eip&gateway=localhost:4400&path=1,0&plc=controllogix&elem_count=10&name=SCADA" --debug=1 --write=10,20,30,40,50,60,70,80,90,100 --timeout=1000
    2. .\tag_rw2 --type="real32" --tag="protocol=ab-eip&gateway=localhost:4400&path=1,0&plc=controllogix&elem_count=1&name=TEMPERATURE" --write=35.3 --timeout=1000
    3. .\tag_rw2 --type="string" --tag="protocol=ab-eip&gateway=127.0.0.1:4400&path=1,0&plc=controllogix&elem_count=5&name=MESSAGE" --debug=1 --write="check temperature","a1","a2","a3","a4" --timeout=1000

Note There is also a Linux version of this simulator.

 

Create a session

  1. Start the FairCom Control Center.
  2. Sign in with the username and password. FairCom's default username is ADMIN (case-insensitive) and the password is ADMIN (case-sensitive).

Note When you log into the FairCom Control Center, a session is automatically created. Any request submitted in the API Console will have the "authToken" property automatically populated with that session's auth token. If you aren't following this tutorial inside the FairCom Control Center, you must first execute the createSession action and set the "authToken" property manually.

 

Create Integration Table for Ethernet/IP data

This procedure creates an Integration Table named abTable in the faircom database to store data received from an Ethernet/IP source. The Integration Table automatically creates the create_ts, error, and source_payload JSON fields.
 

  1. Navigate to the Code tab from the sidebar menu and select API Console.
  2. Copy and paste the following code into the API Console request:
    1. {
          "action": "createIntegrationTable",
          "params": {
              "databaseName": "faircom",
              "tableName": "abTable"
          },
          "authToken": "replaceWithAuthTokenFromCreateSession"
      }

Note An "errorCode" with a value of 0 indicates success. An "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

Create Tags for the Integration Table

This procedure creates three tags. They represent properties in table abTable, field source_payload. The tags are also assigned to user-defined fields (scada, temperature and message) and its values are automatically synchronized with the source_payload properties.

  1. Copy and paste the following code into the API Console request:
    1. {
        "action": "createTag",
        "params": {
          "tagName": "scada",
          "tableName": "abTable",
          "tagDataType": "number",
          "sourcePayloadPath": "scada",
          "sourceFieldName": "scada",
          "sourceFieldType": "integer",
          "sourceFieldLength": 4
      
        },
        "authToken": "replaceWithAuthTokenFromCreateSession"
      }
  2. Click the Run button.
  3. Observe the response in the Output section and ensure the action is completed successfully.
  4. Do the same with the following code to create the second tag:
    1. {
        "action": "createTag",
        "params": {
          "tagName": "temperature",
          "tableName": "abTable",
          "tagDataType": "number",
          "sourcePayloadPath": "temperature",
          "sourceFieldName": "temperature",
          "sourceFieldType": "float",
          "sourceFieldLength": 4
        },
        "authToken": "replaceWithAuthTokenFromCreateSession"
      }
  5. Do the same with the following code to create the third tag:
    1. {
        "action": "createTag",
        "params": {
          "tagName": "message",
          "tableName": "abTable",
          "tagDataType": "string",
          "sourcePayloadPath": "message",
          "sourceFieldName": "message",
          "sourceFieldType": "varchar",
          "sourceFieldLength": 64
        },
        "authToken": "replaceWithAuthTokenFromCreateSession"
      }

 

Capture Ethernet/IP data in the Integration Table

This procedure creates an input that captures data from an Ethernet/IP source and writes the incoming data to the abTable Integration Table for subsequent processing.

  1. Copy and paste the following code into the API Console request:
    1. {
         "api":"hub",
         "action":"createInput",
         "params":{
            "inputName":"abInput",
            "serviceName":"ab",
            "tableName":"abTable",
            "dataCollectionIntervalMilliseconds":5000,
            "dataCollectionBufferCount": 1,
            "settings":{
               "dataReadingTimeoutMilliseconds": 4000,
               "plcAddress": "localhost:4400",
               "plcType": "controllogix",
               "propertyMapList":[
                  {
                     "tagName":"scada",
                     "eipTagPath":"1,0",
                     "eipTagName":"SCADA",
                     "eipTagType":"int32"
                  },
                  {
                     "tagName":"temperature",
                     "eipTagPath":"1,0",
                     "eipTagName":"TEMPERATURE",
                     "eipTagType":"float32"
                  },
                  {
                     "tagName": "message",
                     "eipTagPath": "1,0",
                     "eipTagName": "MESSAGE",
                     "eipTagType": "string",
                     "eipTagSize": 20
                  }
               ]
            }
         },
         "authToken": "replaceWithAuthTokenFromCreateSession"
      }
  1. Click the Run button.
  2. Observe the response in the Output section and ensure the action is completed successfully.

Note An "errorCode" with a value of 0 indicates success. An "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

That is all that is required to configure the FairCom server to read data from a device via the Ethernet/IP protocol. Continue the tutorial to learn how to view the collected data, forward the collect data to an MQTT topic and how to write data to an Ethernet/IP device.

 

View the collected data

View the abTable table in the faircom database to see the collected data.

You can use either of these procedures to view the collected data.


 

View collected data through the Integration Tables navigation window

  1. Navigate to the Data tab from the sidebar menu and select Integration Tables.
  2. Click on the abTable table.
  3. Click on the fields section.
  4. Search for and enable the fields scada, temperature and message.
  5. For each piece of data collected, it is possible to see its values and information. For example, in the last record collected temperature is 35.3.

Note If the table has no records, look at <faircom>/data/CTSTATUS.FCS to see errors related to the connector.

 

View collected data through a SQL query

  1. Navigate to the Data tab from the sidebar menu and select SQL Commands.
  2. In the Statement section, enter and run the following SQL query:
    1. SELECT * from abTable where scada > 0
  3. Observe the response and ensure the action is completed successfully.

 

Forward captured data to an MQTT topic

Once Ethernet/IP data is flowing into a table as JSON and is being transformed into discrete fields in the same table, forward the data out over MQTT.

  1. Navigate to the Code tab from the sidebar menu and select API Console.
  2. Copy and paste the following code into the API Console request:
    1. {
        "action": "configureTopic",
        "params":
        {
          "topic": "abForward",
          "databaseName": "faircom",
          "tableName": "abTable"
        },
        "authToken": "replaceWithAuthTokenFromCreateSession"
      }
  3. Click the Run button.
  4. Observe the response in the Output section and ensure the action is completed successfully.
  5. Subscribe to the MQTT topic to verify that your data was forwarded.
    1. Navigate to the MQ tab from the sidebar menu and select Messages.
    2. Click the Add Subscription button. In the Topic filter search bar, select "abForward" and click Subscribe. As soon as new data is read, messages will appear in the Messages section.

 

Configure Ethernet/IP to output data to a device

The following example configures an Ethernet/IP connector to output data to an Ethernet/IP device. When MQTT, SQL, JSON DB, or an input connector inserts a record into the "abTable" integration table, the FairCom server delivers the record to the Ethernet/IP connector. This example configures the Ethernet/IP connector to extract the value of the temperature property from the record’s source_payload field and write it to a device (at the OUT_TEMP tag) using the Ethernet/IP protocol.

  1. Navigate to the Code tab from the sidebar menu and select API Console.
  2. Copy and paste the following code into the API Console request:
    1. {
       "action": "createOutput",
       "params": {
         "outputName": "abOutput",
         "serviceName": "ab",
         "databaseName": "faircom",
         "tableName": "abTable",
         "settings": {
           "plcAddress": "localhost:4400",
           "plcType": "controllogix",
           "propertyMapList": [
             {
               "eipTagPath": "1,0",
               "eipTagName": "OUT_TEMP",
               "eipTagType": "float32",
               "tagName": "temperature"
             }
           ]
         }
       },
       "authToken": "replaceWithAuthTokenFromCreateSession"
      }
  3. Click the Run button.
  4. Observe the response in the Output section and ensure the action is completed successfully.
  5. To verify that the temperature value has been written to the Ethernet/IP simulator at the OUT_TEMP tag, open a command prompt and run:
    1. .\tag_rw2 --type="real32" --tag="protocol=ab-eip&gateway=localhost:4400&path=1,0&plc=controllogix&elem_count=1&name=OUT_TEMP" --timeout=1000
    2. The output of the previous command should contain this line, which confirms that the value has been written correctly.
    3. data[0]=35.299999