We've updated our file storage system, so some links may no longer work. If you need a file, just email us at support@secomea.com—we’re happy to help!

Collector EtherNet/IP

  • Updated on Dec 17, 2024
  • Published on Jul 3, 2024
  • 6 minute(s) read
  • SE
 Prev Next

The purpose of this article is to be a reference for the EtherNet/IP collector part of the full Data Collection Module documentation.

The EtherNet/IP collector is used to collect samples (data points) from any EtherNet/IP enabled equipment, either by using a single collector or multiple collectors if collecting from multiple different devices.

The supported EtherNet/IP capable devices are:

  • Allen-Bradley Micro800
  • Allen-Bradley MicroLogix, CompactLogix, ControlLogix, FlexLogix
  • SLC500
  • PLC5
  • Omron NJ/NX

EtherNet/IP Collector main

The Collectors list (mandatory array of objects) contains the following fields:

Function Type Importance Description
CollectorName string mandatory Unique name (within this configuration file) of a device to collect data from. This is the name used in the agent configuration. Follows the normal rules for names.
CollectorDescription string optional Description of this collector. For your use, no system function.
CollectorIPAddr string optional Default IP address (or DNS name) for the device to be polled. The agent Target IP address will take precedence over this.
CollectorPortno integer > 0 and < 65535 optional Default port number for the device to be polled. The agent Target Port number will take precedence over this. If neither CollectorPortno nor agent Target Port Number is specified, the appropriate port will be used, depending on the Protocol parameter value.
Alias string optional This is the CollectorName of another collector, from which all the parameters (except CollectorName , CollectorDescription , CollectorIPAddr and CollectorPortno ) are copied. An alias cannot refer to another alias.
Protocol string-enum mandatory The protocol used to collect data. The value must be EtherNet/IP to use the EtherNet/IP collector.
ConnectRetryMin integer > 0 mandatory The minimum number of seconds before trying to re-establish a connection to the device being sampled. An exponential backoff algorithm is used to retry connection establishment, starting after ConnectRetryMin and increasing to ConnectRetryMax.
ConnectRetryMax integer > 0 mandatory The maximum number of seconds before trying to re-establish a connection to the device being sampled.
EtherNetIPAccess Object mandatory Collection of parameters needed to access a PLC via EtherNet/IP.
SamplePoints Array of objects mandatory List of samples to be collected, possibly aggregated and stored in the Store and Forward database.

EtherNet/IP Access object

The EtherNetIPAccess objects contains the following elements:

Function Type Importance Description
PlcType string-enum mandatory The type of PLC. Accepted values are: Micro800, MicroLogix, CompactLogix, SLC500, PLC5, ControlLogix, NJ/NX.
Path object maybe-optional Additional routing path - not used for Micro800.
Timeout integer optional Timeout in miliseconds before a request towards the PLC is deemed failed. Default value 500.
ShareSession boolean optional Determines if sample points share a session towards the PLC, or if each sample point creates a separate session. Defaults to false (not sharing sessions). Using the shared session can be helpful if timeouts are experienced when collecting multiple values from a PLC.

EtherNet/IP Tag object

The EtherNetIPTag objects contains the following elements:

Function Type Importance Description
TagName string mandatory Name of the variable.
ProgramName string optional For CIP based PLCs. Name of the program, for variables located in programs.
SampleInterval integer > 0 mandatory Number of seconds between each collection of data using this collector.
ElementCount integer > 0 maybe-optional See below. The number of elements of the given size that should be collected.
ElementOffset integer >= 0 maybe-optional See below. Defaults to 0. This is used as index into the requested data.

Depending on the SampleDataType selected in the SamplePoints section, the EtherNetIPTag fields ElementCount and ElementOffset is used like this:

  • For data type data, size unit of byte is used.
    • Field ElementCount is mandatory, maximum is 24575.
    • Field ElementOffset is optional, must be less than field ElementCount.
  • For data type string, size unit depends on the PLC, ControlLogix uses 88 bytes and PLC-5 uses 84 bytes.
    • Field ElementCount is mandatory, the maximum calculated as count times size unit, must maximum be 24575. Multiple strings are separated by \n.
    • Field ElementOffset is not used.
  • For other data types, size unit is the number of bytes used by the data type.
    • If the field ElementCount > 1, it is assumed that an array starting at TagName / Path is requested, and the ElementOffset element of the array is returned. The ElementOffset field must be set, minimum is zero and maximum is (ElementCount - 1).
    • If the field ElementCount is 1 or omitted, it is assumed that the value is directly accessible from the TagName / Path, and the field ElementOffset is not used.
  • Maximum size of one sample is 24575 bytes, and calculated as ElementCount times size of data type.

Configuration examples

Below is an example of a configuration of collection from an Allen Bradley 820 MicroLogix PLC.

{
    "CollectorName": "AB-820",
    "CollectorDescription": "Allen Bradley 820 MicroLogix EIP",
    "CollectorIPAddr": "192.168.1.101",
    "CollectorPortno": 123,
    "Protocol": "EtherNet/IP",
    "ConnectRetryMin": 2,
    "ConnectRetryMax": 240,
    "EtherNetIPAccess": {
        "Path": "1,0",
        "PlcType": "Micro800"
    },

    "SamplePoints": [
      {
          "SampleName": "Test-Float",
          "SampleDescription": "Sample a float value",
          "SampleDataType": "float",
          "SamplesSaved" : 10,
          "EtherNetIPTag": {
               "TagName": "Value1",
               "ElementCount": 1,
               "SampleInterval": 15
           }
      },
      {
          "SampleName": "Test-int16",
          "SampleDescription": "Sample a 16 bit signed value",
          "SampleDataType": "int16",
          "SamplesSaved" : 10,
          "EtherNetIPTag": {
               "TagName": "MDB_INT",
               "ElementCount": 1,
               "SampleInterval": 15
           }
      },
      {
          "SampleName": "Test-uint16",
          "SampleDescription": "Sample a 16 bit unsigned value",
          "SampleDataType": "uint16",
          "SamplesSaved" : 10,
          "EtherNetIPTag": {
               "TagName": "_IO_EM_AO_00",
               "ElementCount": 1,
               "SampleInterval": 15
           }
      },
      {
          "SampleName": "Test-int32",
          "SampleDescription": "Sample a 32 bit signed value",
          "SampleDataType": "int32",
          "SamplesSaved" : 10,
          "EtherNetIPTag": {
               "TagName": "Value5",
               "ElementCount": 1,
               "SampleInterval": 15
           }
      },
      {
          "SampleName": "Test-bool",
          "SampleDescription": "Sample a boolean value",
          "SampleDataType": "bool",
          "SamplesSaved" : 10,
          "EtherNetIPTag": {
               "TagName": "Value4",
               "ElementCount": 1,
               "SampleInterval": 15
           }
      }
    ]
}

Here is and example of a CompactLogix controller, with a value collected only when a trigger value is above a certain level.

{
    "CollectorName": "CompactLogix-EIP",
    "CollectorDescription": "EtherNet/IP collector from CompactLogix",
    "CollectorIPAddr": "192.168.10.5",
    "Protocol": "EtherNet/IP",
    "ConnectRetryMin": 2,
    "ConnectRetryMax": 240,
    "EtherNetIPAccess": {
        "Path": "1,0",
        "PlcType": "CompactLogix"
    },
    "SamplePoints": [
        {
            "SampleName": "Test-CompactLogix-bool",
            "SampleDescription": "Test a CompactLogix BOOL value",
            "SampleDataType": "bool",
            "SamplesSaved" : 10,
            "EtherNetIPTag": {
                "TagName": "SECO_BOOL_CMX",
                "SampleInterval": 5,
                "ElementCount": 1
            }
        },
        {
            "SampleName": "Test-CompactLogix-int",
            "SampleDescription": "Test a CompactLogix DINT value",
            "SampleDataType": "int16",
            "SamplesSaved" : 10,
            "EtherNetIPTag": {
                "TagName": "SECO_DINT_CMX",
                "SampleInterval": 15,
                "ElementCount": 1
            }
        },
        {
            "SampleName": "Test-CompactLogix-programm-tag",
            "SampleDescription": "Test a CompactLogix program tag REAL value",
            "SampleDataType": "float",
            "SamplesSaved" : 10,
            "EtherNetIPTag": {
                "TagName": "Program:MainProgram.Programm_SECO_REAL_CMX",
                "SampleInterval": 15,
                "ElementCount": 1
            }
        },

        {
            "SampleName": "Event-Trigger",
            "SampleDescription": "Compute if expression is fulfilled",
            "SampleDataType": "int32",
            "SamplesSaved": 0,
            "Aggregation": {
              "Function": "eventcompute",
              "Expression": "Test-CompactLogix-bool,5000,>=",
              "Values": [
                 "Test-CompactLogix-float"
              ],
              "TriggerSample": "Test-CompactLogix-bool",
              "TriggerNewInterval": 30
            }
        },
        {
            "SampleName": "Test-CompactLogix-float",
            "SampleDescription": "Test a CompactLogix REAL value",
            "SampleDataType": "float",
            "SamplesSaved" : 10,
            "EtherNetIPTag": {
                "TagName": "SECO_REAL_CMX",
                "SampleInterval": 0,
                "ElementCount": 1
            }
        }
    ]
}

Collecting a value from an array, can be configured in two different ways. Below is two examples of configuring a sample point, collecting the second value from an array. Only the sample point json is shown.

First the example using the ElementOffset:

{
    "SampleName": "Second-int64-using-offset",
    "SampleDescription": "Use sample offset to get second value in an array of signed 64 bit integers",
    "SampleDataType": "int64",
    "SamplesSaved" : 10,
    "EtherNetIPTag": {
        "TagName": "signed_longs_array",
        "ElementOffset": 1,
        "ElementCount": 2,
        "SampleInterval": 5
     }
}

and here the c-style indexing example:

{
    "SampleName": "Second-int64-using-index",
    "SampleDescription": "Use c-style array index to get second value in an array of signed 64 bit integers",
    "SampleDataType": "int64",
    "SamplesSaved" : 10,
    "EtherNetIPTag": {
        "TagName": "signed_longs_array[1]",
        "ElementCount": 1,
        "SampleInterval": 5
     }
}