Skip to content

EtherNet/IP Device Service Component

The EtherNet/IP Device Service component acts as an EtherNet/IP Scanner and Adapter where the Scanner is used for data acquisition and device control.

The current version of the device service supports 3 main features:

  • Implicit Communication
    • Fully-configurable Originator to Target (O2T) and Target to Originator (T2O) initialization settings
    • Reading and writing of O2T data
    • Reading of T2O data
    • Configuration of T2O device resources to allow monitoring and automatic push to XRT on a change in value
  • Explicit Communication
    • Unconnected and Connected messaging
    • Supports the Get Attribute Single service reads for all standard data types
    • Supports the Set Attribute Single service writes for all standard data types
    • Supports the Get Attributes All service for Identity class object instances
    • Supports the Reset service
    • Generically supports all services using the Binary data type
  • Logix Tag Support
    • Support to provision Allen Bradley Compact Logix & Control Logix PLC's
    • Reading and Writing of Tag Data
    • Reading and Writing of individual elements of Tag Arrays
    • Reading of entire Tag Arrays.
    • Deployable on Azure Sphere Device
    • Supports reads on all Tag data types using the Binary data type

The EtherNet/IP Device Service also supports:

  • Communication with up to 16 adapter devices
  • Electronic keying

Ethernet/IP Device Service Configuration

Note

The core components required for running Ethernet/IP (and all other device services) are contained in Device Service Component Configuration. Please refer to this page to ensure the appropriate core components are assigned before continuing.

EtherNet/IP Configuration

The required driver fields are described in the following table:

Driver Field Type Description
NetworkInterface String The primary network interface name

A template of the EtherNet/IP device service configuration file is provided, The NetworkInterface driver option can be changed as required:

{
  "Library": "libxrt-ethernet-ip-device-service.so",
  "Factory": "xrt_ethernet_ip_device_service_factory",
  "Name": "ethernet_ip_device_service",
  "Topic": "xrt/device/ethernet_ip_device_service/data",
  "RequestTopic": "xrt/device/ethernet_ip_device_service/request",
  "ReplyTopic": "xrt/device/ethernet_ip_device_service/reply",
  "ProfileRequestTopic": "xrt/profile/ethernet_ip_device_service/request",
  "DiscoveryTopic": "xrt/discovery/ethernet_ip_device_service/devices",
  "ProfileReplyTopic": "xrt/profile/ethernet_ip_device_service/reply",
  "ScheduleRequestTopic": "xrt/schedule/ethernet_ip_device_service/request",
  "ScheduleReplyTopic": "xrt/schedule/ethernet_ip_device_service/reply",
  "ProfileDir": "./config/profiles",
  "StateDir": "./config/state",
  "Scheduler": "sched",
  "Logger": "logger",
  "ThreadPool": "pool",
  "Bus": "bus",
  "Driver": {
    "NetworkInterface": "eno1"
  }
}

EtherNet/IP Device Profile

Details on general profile usage can be found on the Device Profiles page. The following sections will cover how device resources are mapped to EtherNet/IP properties.

It will be split up into 3 sections:

Implicit Resources

Implicit Initialisation Resources

Implicit communication settings must be configured in order to use implicit device resources. These configuration resources get loaded when the device service initialises.

O2T & T2O Setting Attributes

O2T and T2O settings must be configured if either are being used:

Attribute Name Description Valid Values
type The type of the settings resource.

Used by the Device Service to identify the resource type
  • O2TSettings
  • T2OSettings
assemblyID The output assembly instance ID 0 to 65536 (0xFFFF)
includeHeader32bit A flag that defines whether to include a 32-bit header, which includes a run/idle notification
  • true
  • false
size Defines the output assembly size in bytes 0 to 2000 (0x7D0)
Configuration Settings Attributes

This resource is optional and is dependent on the Ethernet/IP device that is being used.

Attribute Name Description Valid Values
type Configuration Settings Resource Identifier, used by the device service to know what resource type it is ConfigSettings
assemblyID Config assembly instance ID 0 to 65535 (0xFFFF)
size Config assembly size in bytes 0 to 400 (0x190)

Implicit Communication Device Resources

Note

The following resource can only be used if the implicit initialisation resources have been setup.

Implicit Communication Device Attributes

Input (T2O) and output (O2T) assemblies contain many values, which are combined into byte arrays. Due to this, information on each resource must be included to identify the bit and byte operations needed to extract the correct value. The attributes provided below should be used in device resources to extract these O2T and T2O values.

Attribute Description Valid Values
type Device resource type identifier telling the device service that this is a T2O/O2T resource
  • T20
  • O2T
offsetBytes Byte offset within the T2O/O2T data 0 to 2000
offsetBits Bit offset within the O2T/T2O data 0 to 7 (0x07)
bitLength Only used for 2 data types:
  • Uint8 (optional)
  • Binary (requirement)
Specifies how long in bits the value is
For data type:
  • Uint8: 1 to 8 (0x08)
  • Binary: 1 to 2000
readOnChange (Only for T2O) Defines whether to push data to XRT:

Set to true to automatically push the reading to XRT if a change in value is detected.

Set to false if data is not to be pushed to XRT
  • true
  • false

Note

The max size of implicit data that the device service can support is 2000 bytes per device.

For examples of all implicit device resource types see Implicit Examples.

Explicit Resources

To create a device resource for explicit messaging, the following attributes are required:

Attribute Description Valid Values
type The type identifier telling the device service that this is a EM resource EM
objClass CIP object class number 0 to 65536 (0xFFFF)
instID CIP object instance ID 0 to 65536 (0xFFFF)
attrID CIP attribute ID (only required depending on service code used) 0 to 65535 (0xFFFF)
serviceCode CIP service command code 0 to 31 (0x31)

The serviceCode determines whether the attrID attribute is required, as some service code commands are not attribute-specific. The table below lists attribute and data type requirements for the current service codes supported:

Service Code Command Call Type Description Required Attributes Device Resource Properties
Get Attributes All Get Retrieves all attributes for the specified object class and instance ID

When invoking this command for the Identity object, the String data type can parse the received data and label each element

The Binary data type splits all data in the message into separate bytes
  • objClass: Any
  • instID: Any
  • serviceCode: 0x01 in hex or 1 in decimal
  • XRT data type: String, Binary
  • readWrite: R
Get Attribute Single Get Retrieves a single attribute value
  • objClass: Any
  • instID: Any
  • attrID: Any
  • serviceCode: 0x0E in hex or 14 in decimal
  • XRT data type: Any
  • readWrite: R
Set Attribute Single Put Writes to a single attribute value
  • objClass: Any
  • instID: Any
  • attrID: Any
  • serviceCode: 0x10 in hex or 16 in decimal
  • XRT data type: Any
  • readWrite: W
Reset Put Resets the device Only supported by the identity object class
  • objClass: 0x01 in hex or 1 in decimal
  • instID:0x01 in hex or 1 in decimal
  • serviceCode: 0x05 in hex or 5 in decimal
  • XRT data type: Any, However, UInt8 or Binary are recommended
  • readWrite: W
Generic Get/Put Using the binary, any service code can be used
  • objClass: Any
  • instID: Any
  • attrID: Any
  • serviceCode: Any in the range 0x00 to 0x31 in hex or 0 to 31 in decimal
  • XRT data type: Binary
  • readWrite: As supported by the service code

For examples of these explicit device resources see Explicit Examples

LogixTag Resources

To create a device resource for a Logix Tag, the following attributes are required:

Attribute Description Valid Values
type The type identifier telling the device service that this is a logixTag resource logixTag
tagName The name of the programmed tag within the PLC <tag name>
arraySize The number of elements of a tag if it is an array.
Note: This resource is only used if an entire Array Tag is to be read at once.
Any value between: 0 and 200

For examples of these logixTag device resources see LogixTag Examples

Example Device Resources

This section is split into 3 parts:

Implicit Resource Examples

Before any Implicit resources can be used, a configuration settings resource will be needed if the Ethernet/IP device that is being used requires it.

Below is a sample configuration settings resource if: - The assembly instance was 100 - The size of the assembly data was 8 bytes

 {
      "name": "Implicit Configuration Settings",
      "description": "Settings for Configuration of Implicit Data Exchange",
      "attributes": {
        "type": "ConfigSettings",
        "assemblyID": "100",
        "size": "8"
      },
      "properties": {
        "value": {
          "type": "String",
          "readWrite": "R"
        }
      }
    }
O2T Example

Provided here is an example IO mapping of an EtherNet/IP device. The output mapping will be used as the example here.

enip1

Note

Before using O2T resources we need to create a settings resource.

The configuration used for the above mapping would be as follows:

  • As the output assembly instance is 101; assemblyID of the output mapping is set to 101
  • As the output assembly size is 2 bytes; size is set to 2
  • As there is a 32-bit header that includes a run/idle notification; includeHeader32bit is set to true
{
   "name":"Implicit O2T Settings",
   "description":"Settings for Originator to Target Implicit Data Exchange",
   "attributes":{
      "type":"O2TSettings",
      "assemblyID":"101",
      "size":"2",
      "includeHeader32bit":"true"
   },
   "properties":{
      "value":{
         "type":"String",
         "readWrite":"R"
      }
   }
}

This first O2T example resource is to control the state of the single output of DO4.

{
   "name":"DO4",
   "description":"Digital Output 4",
   "attributes":{
      "type":"O2T",
      "offsetBytes":"1",
      "offsetBits":"4"
   },
   "properties":{
      "value":{
         "type":"Bool",
         "readWrite":"RW"
      }
   }
}

To provide a value for a O2T device resource of data type Binary, the payload must be Base64 encoded. An example value payload is provided for the following device resource which covers the states of DO2 to DO6.

{
   "name":"DO2_6",
   "description":"Digital Outputs 2 to 6",
   "attributes":{
      "type":"O2T",
      "offsetBytes":"1",
      "offsetBits":"2",
      "bitLength":"5"
   },
   "properties":{
      "value":{
         "type":"Binary",
         "readWrite":"RW"
      }
   }
}
  • Binary Example
    • Outputs High: DO3, DO6
    • Outputs Low: DO2, DO4, DO5
    • Payload: 00010010Eg==
T2O Example

Provided here is an example IO mapping of an EtherNet/IP device. The input mapping will be used as the example here:

enip1

Note

Before using T2O resources we need to create an implicit initialisation resource.

The configuration used for the above mapping would be as follows:

  • As the input assembly is 102; assemblyID of the input mapping is set to 102
  • As the input assembly size is 2 bytes; size is set to 2
  • As there is no 32-bit header that includes a run/idle notification; includeHeader32bit is set to false

The T2O settings resource can be seen below:

{
   "name":"Implicit T2O Settings",
   "description":"Settings for Target to Originator Implicit Data Exchange",
   "attributes":{
      "type":"T2OSettings",
      "assemblyID":"102",
      "size":"2",
      "includeHeader32bit":"false"
   },
   "properties":{
      "value":{
         "type":"String",
         "readWrite":"R"
      }
   }
}

This first T2O example is to read the state of a single input DI4:

{
   "name":"DI4",
   "description":"Digital Input 4",
   "attributes":{
      "type":"T2O",
      "offsetBytes":"0",
      "offsetBits":"4",
      "readOnChange":"true"
   },
   "properties":{
      "value":{
         "type":"Bool",
         "readWrite":"R"
      }
   }
}

The value returned by a O2T device resource of data type Binary will be returned as a Base64 encoded value. The attribute bitLength is used to determine how many bytes will be returned. If the value of bitLength is not a multiple of 8 then the modulo of bits remaining will be set to zero for the end of the final byte. An example of this is provided with a device resource covering the input states ranging from DI0 to DI7:

{
   "name":"DI0_7",
   "description":"Digital Inputs 0 to 7",
   "attributes":{
      "type":"T2O",
      "offsetBytes":"0",
      "offsetBits":"0",
      "bitLength":"8",
      "readOnChange":"true"
   },
   "properties":{
      "value":{
         "type":"Binary",
         "readWrite":"R"
      }
   }
}
  • Binary Example
    • Inputs High: DI0, DI1, DI3, DI4, DI5, DI7
    • Inputs Low: DI2, DI6
    • Reading: uw==10111011

Explicit Resource Examples

Get Attributes All Examples

This resource will retrieve all of the attributes of the identity object and return it to the user in a string format. The device service knows the format of the identity object in advance so it can take the response and generate each attribute name value pair from the response. Currently only the identity object is supported for this service code and data type string combination.

{
   "name":"Get All Identity Attributes",
   "description":"This will retrieve all of the attributes of the identity object and return it to the user in a string format",
   "attributes":{
      "type":"EM",
      "objClass":"0x01",
      "instID":"1",
      "serviceCode":"0x01"
   },
   "properties":{
      "value":{
         "type":"String",
         "readWrite":"R"
      }
   }
}

If the user wants issue a Get Attributes All request to a class or class instance that the device service does not know how to parse, they can just use the Binary data type. The following example will request instance 1 of the Ethernet Link object class. When the data from the request has been received, the data will be returned as a Base64 encoded value.

{
   "name":"Get All Ethernet Link Class Attributes",
   "description":"This will retrieve all of the attributes of the Ethernet Link Class object and return it as base64 encoded value",
   "attributes":{
      "type":"EM",
      "objClass":"0xF6",
      "instID":"1",
      "serviceCode":"0x01"
   },
   "properties":{
      "value":{
         "type":"Binary",
         "readWrite":"R"
      }
   }
}
Get Attribute Single Examples

These examples will return a specified attribute. The resource’s data type informs the device service on how to cast the receive data and inform the request on the size of the message.

{
   "name":"Serial Number - Identity Object",
   "description":"Reading the serial number of the device",
   "attributes":{
      "type":"EM",
      "objClass":"0x01",
      "instID":"1",
      "attrID":"6",
      "serviceCode":"0x0E"
   },
   "properties":{
      "value":{
         "type":"Uint32",
         "readWrite":"R"
      }
   }
},

{
   "name":"Assembly Input - Assembly Object",
   "description":"Reading the assembly input isntance of the device",
   "attributes":{
      "type":"EM",
      "objClass":"0x04",
      "instID":"102",
      "attrID":"3",
      "serviceCode":"0x0E"
   },
   "properties":{
      "value":{
         "type":"Uint16",
         "readWrite":"R"
      }
   }
}
Set Attribute Single Examples

This example will write to a specified attribute:

{
   "name":"Assembly Output - Assembly Object",
   "description":"Writing to the assembly output isntance of the device",
   "attributes":{
      "type":"EM",
      "objClass":"0x04",
      "instID":"101",
      "attrID":"3",
      "serviceCode":"0x10"
   },
   "properties":{
      "value":{
         "type":"Uint16",
         "readWrite":"W"
      }
   }
}
Reset Example

The Reset service can perform different functions based on what the value that is provided. The actions of the first two values are provided below:

Value Function
0 Emulate power cycle
1 Factory reset and then emulate power cycle

The Reset device resource is provided below and should be added to a device’s profile if you require to use it. Upon triggering this request for a device, if successful, the device service will attempt to reinitialise all of the devices connections.

{
   "name":"Reset",
   "description":"Triggers the device to emulate a power cycle",
   "attributes":{
      "type":"EM",
      "objClass":"0x01",
      "instID":"1",
      "serviceCode":"0x05"
   },
   "properties":{
      "value":{
         "type":"Uint8",
         "readWrite":"W"
      }
   }
}

LogixTag Resource Examples

Provided below is an example of Tags that may be programmed into a PLC through studio 5000:

Tag Name Data Type
test_dint DINT
test_real REAL
bool_array[0] BOOL
bool_array Array

Resources for all the above tags can be seen below

{
   "name":"test_dint",
   "description":"Double Integer Value",
   "attributes":{
      "type":"logixTag",
      "tagName":"test_dint"
   },
   "properties":{
      "value":{
         "type":"int16",
         "readWrite":"RW"
      }
   }
},

{
   "name":"test_real",
   "description":"Floating point value",
   "attributes":{
      "type":"logixTag",
      "tagName":"test_real"
   },
   "properties":{
      "value":{
         "type":"float32",
         "readWrite":"RW"
      }
   }
},

{
   "name":"bool_array[0]",
   "description":"First element of bool array",
   "attributes":{
      "type":"logixTag",
      "tagName":"bool_array[0]"
   },
   "properties":{
      "value":{
         "type":"bool",
         "readWrite":"RW"
      }
   }
}

{
   "name":"bool_array",
   "description":"First element of bool array",
   "attributes":{
      "arraySize":"10",
      "type":"logixTag",
      "tagName":"bool_array"
   },
   "properties":{
      "value":{
         "type":"Uint8Array",
         "readWrite":"R"
      }
   }
}

The example above shows that the device service has the ability to read and write to individual elements from array tags, in the examples case: bool_array[0] is the first element of bool_array and has the ability to read and write to it.

You can can also read but not write to the whole array tag itself. In the examples case: bool_array is being outputed as a binary using the Uint8Array data type.

Data Types

The following tables list the EtherNet/IP data types and their equivalent XRT data type:

Implicit Data Types

Implicit Data Type XRT Data Type Requires bitLength Attribute Read/Write Ability
BIT# UInt8 When using T2O or O2T resources RW
BOOL bool No RW
DINT Int32 No RW
INT Int16 No RW
LINT Int64 No RW
LREAL Float64 No RW
REAL Float32 No RW
SINT Int8 No RW
UDINT UInt32 No RW
UINT UInt16 No RW
ULINT UInt64 No RW
USINT UInt8 No RW
Any Binary When using T2O or O2T resources RW

Explicit Data Types

Explicit Data Type XRT Data Type Read/Write Ability
BIT# UInt8 RW
BOOL bool RW
DINT Int32 RW
INT Int16 RW
LINT Int64 RW
LREAL Float64 RW
REAL Float32 RW
SINT Int8 RW
UDINT UInt32 RW
UINT UInt16 RW
ULINT UInt64 RW
USINT UInt8 RW
String String RW
Any Binary RW

Logix Tag Data Types

Tag Data Type XRT Data Type Read/Write Ability
BOOL Bool RW
SINT Int8 / UInt8 RW
INT Int16 / UInt16 RW
DINT Int32 / UInt32 RW
REAL Float32 RW
BIT ARRAY UInt8Array / Binary R
STRUCTURE Binary R
STRUCTHANDLE_STRING String R

Note

All other Tag data types can be read as Binary

The EtherNet/IP Device service also supports the reading and writing of Tag Arrays and its individual elements. Examples of this are provided in LogixTag Examples.

Device Commands

See the Device Commands page for details on how to define device commands for grouping device resources for fewer requests.

EtherNet/IP Device Provisioning

The following sections will explain how devices can be statically configured for EtherNet/IP.

Note

For information on dynamic device additions, removals and updates please see the MQTT API Guide.

There are 5 different types of properties for EtherNet/IP:

IP Protocol Properties

The following IP protocol property is always required:

Property Description Valid Values
Address The IP address of the device A valid device IP address

Note

When provisioning an Allen Bradley PLC for reading and writing Tags, only the IP address of the PLC is needed to correctly provision.

An example of a EtherNet/IP device provision within the devices.json file is provided below for an Allen Bradley PLC:

{
   "Allen-Bradley-PLC":{
      "profile":"ab_profile",
      "protocols":{
         "IP":{
            "Address":"192.168.4.6"
         }
      }
   }
}

ExplicitConnected Protocol Properties

The following ExplicitConnected protocol properties are required if an explicit connection type is set to connected. This will mean that an explicit request will be made periodically to a resource to keep an explicit connection alive.

Property Description Valid Values
DeviceResource When using explicit communication, a request must be made to the device at a configured interval to keep the connection alive

Allows you to choose the device resource from a profile to use as the periodic request
Explicit device resource name that uses the service code of either:
  • Get Attribute Single (0x0E)
  • Get Attribute All (0x01)
SaveValue Defines whether the received data is pushed to XRT on each periodic request

Set to true to push the received data to XRT
  • true
  • false
RPI The interval at which the periodic request is sent to keep the class 3 connection alive Interval in milliseconds

An example of a EtherNet/IP device provision within the devices.json file is provided below for an ADAM-6150EI Module:

{
   "ADAM-Module":{
      "profile":"ADAM-6150EI",
      "protocols":{
         "IP":{
            "Address":"192.168.1.92"
         },
         "ExplicitConnected":{
            "DeviceResource":"VendorID",
            "RPI":"3000",
            "SaveValue":"true"
         }
      }
   }
}

O2T Protocol Properties

The following O2T protocol properties are required if there is an O2TSettings device resource in the device profile:

Property Description Valid Values
ConnectionType Defines whether data is communicated using peer-to-peer or multicast

Set to p2p to communicate using peer-to-peer

Set to mcast to react in a broadcast way
  • p2p
  • mcast
RPI The requested packet interval, which is the interval in which data is exchanged Interval in milliseconds
Priority Defines the priority in which the implicit data exchange is treated
  • low
  • high
  • scheduled
  • urgent
Ownership Defines the exclusivity of the data on the target If not set to exclusive, other scanners can also establish an implicit connection to the device
  • exclusive
  • inputonly
  • listenonly

An example of a EtherNet/IP device provision within the devices.json file is provided below for an ADAM-6150EI Module:

{
   "ADAM-Module":{
      "profile":"ADAM-6150EI",
      "protocols":{
         "IP":{
            "Address":"192.168.50.2"
         },
         "O2T":{
            "ConnectionType":"p2p",
            "RPI":"10",
            "Priority":"low",
            "Ownership":"exclusive"
         }
      }
   }
}

T2O Protocol Properties

The following T2O protocol properties are required if there is an T2OSettings device resource in the device profile:

Property Description Valid Values
ConnectionType Defines whether data is communicated using peer-to-peer or multicast

Set to p2p to communicate using peer-to-peer

Set to mcast to react in a broadcast way
  • p2p
  • mcast
RPI The requested packet interval, which is the interval in which data is exchanged Interval in milliseconds
Priority Defines the priority in which the implicit data exchange is treated
  • low
  • high
  • scheduled
  • urgent
Ownership Defines the exclusivity of the data on the target If not set to exclusive, other scanners can also establish an implicit connection to the device
  • exclusive
  • inputonly
  • listenonly

An example of a EtherNet/IP device provision within the devices.json file is provided below for an ADAM-6150EI Module:

{
   "ADAM-Module":{
      "profile":"ADAM-6150EI",
      "protocols":{
         "IP":{
            "Address":"192.168.50.2"
         },
         "T2O":{
            "ConnectionType":"p2p",
            "RPI":"10",
            "Priority":"low",
            "Ownership":"exclusive"
         }
      }
   }
}

Key Protocol Properties

The following Key protocol properties are needed only when a key is required by the device:

Property Description Valid Values
Method Defines how the device accepts the key

If set to compatibility, the device accepts the key if it can emulate the device defined in the key

This generally works if the devices have the same product code and the same or higher major revision

If set to exact, the device requires an exact match of every identifying attribute
  • compatibility
  • exact
VendorID The ID of the device manufacturer Any UInt16 value
DeviceType The class of device, for example motor drives or I/O device Any UInt16 value
ProductCode The product code of the device Any UInt16 value
MajorRevision The major revision of the device Valid range 0 to 127, inclusive
MinorRevision The minor revision of the device Any UInt8 value

EtherNet/IP Device Service Interaction

For information on how to dynamically execute reads, writes, setting up schedules, triggering device discovery and much more, please refer to the MQTT API Guide.

Run the EtherNet/IP Device Service

Find details on how to run the EtherNet/IP device service on the Run Device Services page.

Back to top