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
  • 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 Uint8Array 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 Uint8Array data type

The EtherNet/IP Device Service also supports:

  • Device Discovery
  • Profile Generation
  • 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
ConnectionTimeout UInt32 The timeout to wait on a connection request in milliseconds
DiscoveryDuration UInt32 The duration to wait for EtherNet/IP devices to respond to a discovery request in milliseconds
DiscoveryRetries UInt8 Controls how many List Identities are sent to the desired broadcast address during a discovery call.
DirectedBroadcastDiscovery Bool The method of broadcast to be used when discovering EtherNet/IP devices. If set to True a directed broadcast is used on the network of where the device service is running. If set to False, local broadcast is used on the broadcast address (255.255.255.255)

A template of the EtherNet/IP Device Service configuration file is provided, The NetworkInterface and ConnectionTimeout driver options can be changed as required:

{
  "Library": "libxrt-ethernet-ip-device-service.so",
  "Factory": "xrt_ethernet_ip_device_service_factory",
  "Name": "ethernet_ip",
  "TelemetryTopic": "xrt/devices/ethernet_ip/telemetry",
  "RequestTopic": "xrt/devices/ethernet_ip/request",
  "ReplyTopic": "xrt/devices/ethernet_ip/reply",
  "DiscoveryTopic": "xrt/devices/ethernet_ip/discovery",
  "StateDir":"./deployment/state",
  "ProfileDir": "./deployment/profiles",
  "Scheduler": "sched",
  "Logger": "logger",
  "ThreadPool": "pool",
  "Bus": "bus",
  "Driver": {
    "NetworkInterface": "eno1",
    "ConnectionTimeout": 3000,
    "DiscoveryRetries": 3,
    "DiscoveryDuration": 4000,
    "DirectedBroadcastDiscovery": false
  }
}

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
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

Note

T2O and O2T settings resources cannot be used for read/write operations

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
size Config assembly size in bytes 0 to 400

Note

Configuration settings resources cannot be used for read/write operations

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
bitLength Only used for 2 data types:
  • Uint8 (optional)
  • Uint8Array (requirement)
Specifies the length of the value in bits 		For data type:
  • Uint8: 1 to 8
  • Uint8Array: 1 to 2000

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 may be used:

Attribute Description Valid Values Required
objClass CIP object class number 0 to 65535 Y
instID CIP object instance ID 0 to 65535 Y
attrID CIP attribute ID (only required depending on service code used) 0 to 65535 N

Note

Any resources with no type attribute will default to be explicit. Therefore, no type attribute is required when creating explicit resources.

The service code of an explicit message request is determined by the EtherNet/IP device service depending on which attributes are included in a device resource. If an attrID attribute is included, then the resource is referring to a specific attribute within an instance of an object class. If no attrID attribute is included, then the resource is referring to the whole instance of an object class. Whether we are reading or writing will also influence what service code is used.

The following table describes which service code will be used in which scenarios:

Service Code Command Description Required Attributes for Inferral Device Resource Properties
Get Attributes All 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 Uint8Array data type returns the object instance as raw bytes.

  • objClass
  • instID
  • Xrt data type: String, Uint8Array
  • readWrite: R
Get/Set Attribute Single Reads/writes a single attribute value.

  • objClass
  • instID
  • attrID
  • Xrt data type: Any
  • readWrite: R/W/RW

Reset Service Code

In addition to the above service codes, the Reset service code can also be used upon an Identity Object instance resource with data type UInt8Array. This resource should be created in the same format as a Get Attributes All resource, where objClass and instID refer to the Identity Object instance (both set to 1), but readWrite must be set to "RW".

To perform this Reset operation, an override of the service code when writing to this resource must be used. This can be done by including the setting "ServiceCode": 5 within the options field of the put request. An example is provided below:

{
  "client": "iotech",
  "request_id": "101",
  "op": "device:put",
  "device": "ethernet-ip-device",
  "values": {
    "IdentityClassInstance": [1]
  },
  "options": {
    "ServiceCode": 5
  },
  "type": "xrt.request:1.0"
}

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 Uint8Array, the payload must be a byte array value. 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":"Uint8Array",
         "readWrite":"RW"
      }
   }
}
  • Uint8Array Example
    • Outputs High: DO3, DO6
    • Outputs Low: DO2, DO4, DO5
    • Payload:
      [18]
      Which represents the following high/low values shown below as binary:
      '0, 0, 0, 1, 0, 0, 1, 0'
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,
   },
   "properties":{
      "value":{
         "type":"Bool",
         "readWrite":"R"
      }
   }
}

The value returned by a O2T device resource of data type Uint8Array will be returned as a byte array 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 15",
   "attributes":{
      "type":"T2O",
      "offsetBytes":0,
      "offsetBits":0,
      "bitLength":16,
   },
   "properties":{
      "value":{
         "type":"Uint8Array",
         "readWrite":"R"
      }
   }
}
  • Uint8Array Example
    • Inputs High: DI0, DI1, DI3, DI4, DI5, DI7, DI8, DI9, DI10, DI11, DI12, DI13, DI14, DI15
    • Inputs Low: DI2, DI6
    • Reading:
      [255, 187]
      Which represents the following high/low values shown below as binary:
      '1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1'

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":{
      "objClass":1,
      "instID":1
   },
   "properties":{
      "value":{
         "type":"String",
         "readWrite":"R"
      }
   }
}

If the user wants to 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 Uint8Array 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":{
      "objClass":246,
      "instID":1
   },
   "properties":{
      "value":{
         "type":"Uint8Array",
         "readWrite":"R"
      }
   }
}
Get/Set Attribute Single Examples

These examples will return a specified attribute. The resource’s data type informs the device service on how to cast the received 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":{
      "objClass":1,
      "instID":1,
      "attrID":6
   },
   "properties":{
      "value":{
         "type":"Uint32",
         "readWrite":"R"
      }
   }
},
{
   "name":"Assembly Input - Assembly Object",
   "description":"Reading the assembly input instance of the device",
   "attributes":{
      "objClass":4,
      "instID":102,
      "attrID":3
   },
   "properties":{
      "value":{
         "type":"Uint16",
         "readWrite":"R"
      }
   }
}

To be able to use Set Attribute Single on the resources above, the readWrite property must instead be set to "W" or "RW".

The examples below demonstrate a write-only resource, followed by a readable and writeable resource: 

{
   "name":"Assembly Output - Assembly Object",
   "description":"Writing to the assembly output instance of the device",
   "attributes":{
      "objClass":4,
      "instID":101,
      "attrID":3
   },
   "properties":{
      "value":{
         "type":"Uint16",
         "readWrite":"W"
      }
   }
},
{
   "name":"Assembly Input/Output - Assembly Object",
   "description":"Reading from/writing to the assembly output instance of the device",
   "attributes":{
      "objClass":4,
      "instID":101,
      "attrID":3
   },
  "properties":{
      "value":{
         "type":"Uint16",
         "readWrite":"RW"
     }
}

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":{
      "objClass":1,
      "instID":1
   },
   "properties":{
      "value":{
         "type":"Uint8Array",
         "readWrite":"RW"
      }
   }
}

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 using the Uint8Array data type. This will output the array as a list.

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.

To provision an EtherNet/IP device, the EtherNet-IP protocol must be used and relevant protocol properties must be specified. There are five different types of properties, these are:

Address Protocol Properties

The following Address protocol property is always required for all EtherNet/IP devices:

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":{
         "EtherNet-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 (14)
  • Get Attribute All (1)
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":{
         "EtherNet-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 an EtherNet/IP device provision within the devices.json file is provided below for an ADAM-6150EI Module:

{
   "ADAM-Module":{
      "profile":"ADAM-6150EI",
      "protocols":{
         "EtherNet-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":{
         "EtherNet-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

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":{
         "EtherNet-IP":{
            "Address":"192.168.50.2",
            "Key":{
               "Method":"exact",
               "VendorID":10,
               "DeviceType":"72",
               "ProductCode":"50",
               "MajorRevision":"12",
               "MinorRevision":"2",
            }
         }
      }
   }
}

EtherNet/IP Device Discovery

When triggering a EtherNet/IP discovery request as described in the MQTT API Guide, there are the following device service settings that can be included within the options field. Some of these will override the corresponding device service driver options that can be found in EtherNet/IP Device Service Configuration

Parameter Type Description Example Value
DiscoveryDuration UInt16 Driver Option Override

Controls the length of time to wait between who-is broadcasts in milliseconds. 		5000
DiscoveryRetries UInt8 Driver Option Override

Controls how many extra who-is broadcasts are made during a discovery call. 		2
DirectedBroadcastDiscovery Bool The method of broadcast to be used when discovering EtherNet/IP devices. If set to True a directed broadcast is used on the network of where the device service is running. If set to False, local broadcast is used on the broadcast address (255.255.255.255) false

An example discovery:trigger command using these options is provided:

{
  "client":"iotech",
  "request_id": "108",
  "op": "discovery:trigger",
  "options": {
    "DiscoveryDuration": 5000,
    "DiscoveryRetries": 2,
    "DirectedBroadcastDiscovery": false
  },
  "type": "xrt.request:1.0"
}

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.

For interactive examples of the EtherNet/IP Device Service, refer to EtherNet/IP Xrt Examples. Following the instructions within the link will demonstrate many features of Edge Xrt and the device service running against a compatible EtherNet/IP device.

Run the EtherNet/IP Device Service

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