Skip to content

EtherNet/IP

Introduction

EtherNet/IP (Ethernet Industrial Protocol) is a widely used industrial network protocol designed for real-time control and information exchange in automation systems. It is based on the standard Ethernet and TCP/IP protocols, providing seamless integration with existing IT infrastructure. EtherNet/IP enables devices such as programmable logic controllers (PLCs), sensors, actuators, and human-machine interfaces (HMIs) to communicate efficiently and reliably in industrial environments.

Ethernet/IP asset enables communication with EthernetIP devices. It reads values from these devices and posts them to Coreflux Central, an MQTT broker. Additionally, it can receive data from Coreflux Central and relay it back to the EthernetIP devices, facilitating a bidirectional data flow.

Features and Benefits

  • Seamless Communication: Facilitates smooth and efficient data exchange between EthernetIP PLCs and your data hub.PLCs and your data hub.
  • Real-time Monitoring: Provides instant visibility into the status and performance of EthernetIP PLCs.
  • Easy Integration: Simplifies the process of incorporating EthernetIP PLCs into your IIoT projects.
  • Bidirectional data flow: This feature enables users to access and modify all readable and writable values on the device, ensuring seamless interaction and control over device data.
  • Explicit Communication Support: This asset only supports explicit communication, ensuring reliable and controlled data exchange with EthernetIP devices.

Prerequisites

Before you install and configure the asset, make sure you have the following prerequisites:

  • Basic understanding of the MQTT protocol.
  • Basic undertstanding of EthernetIP protocol.
  • Coreflux account.
  • Coreflux 1.3 MQTT broker.
  • MQTT Client (such as MQTT Explorer).
  • An EthernetIP device (PLC for example).

Asset installation

Using Coreflux HUB

Please refer to the general docs for asset installation through the Coreflux HUB.

Using Coreflux HUBLESS

Asset management and control are conducted using the MQTT protocol. Commands (payload) are sent to the $SYS/Coreflux/Command topic. The results of these commands are published to $SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

  1. Connect to the Coreflux MQTT Broker using your preferred client.
  2. Login using your coreflux account: 
    -L myname@mydomain.com password`
  3. Check your available assets: 
    -l
  4. Install asset: 
    -I coreflux_ethernetipmqtt
  5. If there were no issues during the installation you should receive a message on the $SYS/Coreflux/Command/Output: 
    Your coreflux_ethernetipmqtt was installed with version <version> with the <asset_guid>. Let the magic begin!

Asset configuration

Before using the asset, it must be properly configured. This configuration process entails adjusting various parameters that affect its functionality, the setup of the device, and how they interact with each other. This involves specifying the device's IP address and selecting the class, instance, and attribute to be manipulated, among other settings. The configuration is detailed in a JSON file, divided into three main sections: MQTT Parameters, EthernetIP Parameters and Tags Prameters.
The instructions below will guide you through configuring each section.
By the end, you will have a comprehensive example configuration that can be tailored to your specific needs.

⚠ Warning: If a parameter is not included in your asset's configuration and it is not required, a default value will be applied. Incorrect configuration may cause the asset to not work as intended.

ℹ : This configuration is presented using a hubless setup as an example. The key takeaway is the understanding of the parameters and their significance. If you are configuring the asset via Coreflux Hub, the same parameters and configurations apply.

MQTT Parameters

The MQTTParameters in the JSON configuration define how to connect to an MQTT broker, specifying the communication details. The Address and Port indicate the broker's network location (in this case, 127.0.0.1 on port 1883), which is where the data will be sent to or received from. The parameters also detail authentication methods and the use of TLS for secure communication. This setup determines the pathway for data exchange between the device and the MQTT broker, facilitating the monitoring or control of device operations.

Parameter Description Required Example Default Value
Port Port number on which the MQTT broker is running. Yes 1883 1883
Address IP address or hostname of the MQTT broker. Yes "127.0.0.1" "127.0.0.1"
IsAnonymous Indicates if the connection is anonymous (no username/password required). Yes true true
Username Username for authentication, if not anonymous. No "" (empty string) "" (empty string)
Password Password for authentication, if not anonymous. No "" (empty string) "" (empty string)
EnableTLS Specifies whether TLS encryption is enabled for secure communication. No true false

Example:

{
  "MQTTParameters": {
    "Port": 1883,
    "Address": "127.0.0.1",
    "IsAnonymous": true,
    "Username": "",
    "Password": "",
    "EnableTLS": false
  }
}

EthernetIP Parameters

The EthernetIPParameters in the JSON configuration specify the setup for Ethernet/IP communication between a local system and a target device. These parameters are essential for facilitating data exchange using the Ethernet/IP protocol. The configuration includes the target device's IP address and port for establishing the connection. The PollingMs parameter defines the frequency of data polling, ensuring timely updates. Additionally, the DeviceName parameter identifies the target device within the network, simplifying device management and have a better understanding of the logs.

Parameter Description Required Example Default Value
IP Specify the IP address of the EthernetIP device. Yes "192.168.0.52" "127.0.0.1"
PortEthernet Define a port for the EthernetIP device. No 44818 44818
PollingMs Set the polling rate for reading in milliseconds. Yes 750 500

Example:

{
  "MQTTParameters": {
    "Port": 1883,
    "Address": "127.0.0.1",
    "IsAnonymous": true,
    "Username": "",
    "Password": "",
    "EnableTLS": false
  },
  "EthernetIPParameters": {
    "IP": "192.168.0.52",
    "PortEthernet": 44818,
    "PollingMs": 750
  },
  "Tags": []
}

Tags

Tags serve as the bridge between the Ethernet IP devices variables and the MQTT topics within your system. Each Tag represents a specific connection point, linking a data element in Class/Instance/Attribute to a topic on the MQTT broker. Each Tag in your array of Tags encapsulates the necessary details for this data exchange, including parameters related to both the PLC device (such as the data type and trigger conditions) and the MQTT protocol (such as the topic, quality of service, and retain flag).

ℹ : Tags array is not required in the configuration, if it is not included in the configuration, the asset will still run.

Parameter Description Required Example Default Value
Name A unique identifier for the tag, up to 50 characters. Used to reference the tag within the system. Yes "MyTag" N/A
WriteDirection Chose the the origin and destination of data. The options are: 0 - ToOther, 1 - ToMQTT and 2 - ToAll. Yes "ToOther" N/A
MQTTTopic MQTT topic for publishing or subscribing data associated with the Tag. Yes "EthernetIP/DataUpdate" N/A
MQTTQoS Quality of Service level for MQTT communication (0 to 2 : AtMostOnce, AtLeastOnce and ExactlyOnce), balancing efficiency and reliability of message delivery. Yes 1 0 (AtMostOnce)
MQTTRetain Define to retain the message or not. Options are: true or false. Yes false false
DataType Define data type to read/write. Options are: 0 - 10 (Check the table) Yes 6 N/A
ClassID Represents the class or type of an object in the Ethernet/IP network. It specifies the category or group to which the object belongs. Yes 4 N/A
InstanceID A unique identifier that specifies an individual instance of an object within a particular class in the Ethernet/IP network. Yes 100 N/A
AttributeID A numerical value that represents a specific attribute or property associated with an object in the Ethernet/IP network. Yes 1 N/A
AttributeIndex Define the Attribute index where values must be written or read. Range (0-127) Yes 0 N/A
Length Define the length in bytes to be written to or read from the Ethernet/IP device.
⚠️ Use this only for string data type and if Join is enable.		 No 10 N/A
Bit When using the Boolean data type, this specifies the bit from the AttributeIndex to be written to or read from the Ethernet/IP device. Options to send/receive values are: 0 (false) or 1 (true). No 2 (LSB order) N/A
“EnableJoinAttribute” Concatenate the attributes defined by “AttributeID” and “JoinAttributeID”. Options are: true or false. No true false
JoinClassID Represents the class or type of an object in the Ethernet/IP network. It specifies the category or group to which the object belongs. No 120 N/A
JoinInstanceID A unique identifier that specifies an individual instance of an object within a particular class in the Ethernet/IP network. No 100 N/A
JoinAttributeID A numerical value that represents a specific attribute or property associated with an object in the Ethernet/IP network. No 3 N/A
JoinLength Specify the byte length for reading from or writing to the Ethernet/IP device. ⚠️ This is mandatory when using Join. Ensure the total length (Length + JoinLength) matches the byte count of the selected data type. No 4 N/A
JoinIndex Specify the Join index for reading or writing values. No 50 N/A
ClearNull This option is useful when reading string data types, allowing the user to choose whether to display or remove 'null' characters in the MQTT Client from the string. No true false

Example:

{
  "MQTTParameters": {
    "Port": 1883,
    "Address": "127.0.0.1",
    "IsAnonymous": true,
    "Username": "",
    "Password": "",
    "EnableTLS": false
  },
  "EthernetIPParameters": {
    "IP": "192.168.0.52",
    "PortEthernet": 44818,
    "PollingMs": 750
  },
  "Tags": [
    {
      "Name": "outputExample",
      "WriteDirection": 0,
      "MQTTTopic": "Send/to/MasterEthernetIP",
      "MQTTQoS": 0,
      "MQTTRetain": false,
      "DataType": 0,
      "ClassID": 4,
      "InstanceID": 100,
      "AttributeID": 3,
      "AttributeIndex": 7,
      "Bit": 0,
      "EnableJoinAttribute": false
    },
    {
      "Name": "inputExample",
      "WriteDirection": 1,
      "MQTTTopic": "Received/from/MasterEthernetIP",
      "MQTTQoS": 0,
      "MQTTRetain": false,
      "DataType": 11,
      "ClassID": 4,
      "InstanceID": 100,
      "AttributeID": 3,
      "AttributeIndex": 11,
      "Length": 5,
      "EnableJoinAttribute": false,
      "ClearNull": true
    },
    {
      "Name": "JoinExample",
      "WriteDirection": 0,
      "MQTTTopic": "Send2/to/MasterEthernetIP",
      "MQTTQoS": 0,
      "MQTTRetain": false,
      "DataType": 6, 
      "ClassID": 4,
      "InstanceID": 100,
      "AttributeID": 3,
      "AttributeIndex": 50,
      "Length": 3,
      "EnableJoinAttribute": true,
      "JoinClassID": 15,
      "JoinInstanceID": 125 ,
      "JoinAttributeID": 3,
      "JoinIndex": 0,
      "JoinLength": 5

    }
  ]
}

Tag Data Types

This section outlines the various data types used within the system, which are named and structured to mirror the data types found in the corresponding devices. This naming convention ensures a more intuitive and direct mapping of data types from the devices to our system, facilitating easier data handling and integration. Understanding these data types is crucial for effective communication and data manipulation in the system.

Data Type - Integer Value Description Memory Space Lower Bound Upper Bound
Boolean - 0 Set a specific Bit to: 0 (false) or 1 (true). 1 bits FALSE (0) TRUE (1)
Byte - 1 The value to be read from or written to the AttributeIndex must be a valid byte. 8 0 255
INT16 - 2 Signed 16-bit integer. 16 bits -32768 32767
UINT16 - 3 Unsigned 16-bit integer. 16 bits 0 65535
INT32 - 4 Signed 32-bit integer. 32 bits -2147483648 2147483647
UINT32 - 5 Unsigned 32-bit integer. 32 bits 0 4294967295
INT64 - 6 Signed 64-bit integer. 64 bits -2^63 2^63-1
UINT64 - 7 Unsigned 64-bit integer. 64 bits 0 2^64-1
Float32 - 8 32-bit floating point number. 32 -3.402823e+38 3.402823e+38
Float64 - 9 64-bit floating point number (double). 64 bits -1.7976931348623158e+308 1.7976931348623158e+308
ASCII - 10 Will convert the AttributeIndex value to an ASCII character. 1 bit 0 255
String - 11 Strings of characters. In the Tag configuration must set the Length of the string. Variable N/A N/A

Saving the configuration

Asset management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the $SYS/Coreflux/Command topic. The results of these commands are published to $SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ : Configuration requires the user to be logged in and have an asset installed. If these requirements are not met, please refer to the installation section.

  1. Save configuration: 
    -assetConfigSave <asset_guid or assetName> <configuration>`

    ℹ : The asset asset_guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Example:

-assetConfigSave assetName {
    "MQTTParameters": {
        "Port": 1883,
    "Address": "127.0.0.1",
    "IsAnonymous": true,
    "Username": "",
    "Password": "",
    "EnableTLS": false
  },
  "EthernetIPParameters": {
      "IP": "192.168.0.52",
    "PortEthernet": 44818,
    "PollingMs": 750
  },
  "Tags": [
      {
          "Name": "outputExample",
      "WriteDirection": 0,
      "MQTTTopic": "Send/to/MasterEthernetIP",
      "MQTTQoS": 0,
      "MQTTRetain": false,
      "DataType": 0,
      "ClassID": 4,
      "InstanceID": 100,
      "AttributeID": 3,
      "AttributeIndex": 7,
      "Bit": 0,
      "EnableJoinAttribute": false
    }
  ]
}
  1. Check if the configuration was saved (optional) : 
    -assetConfigLoad <asset_guid>

ℹ : Find more detailed information about the asset management here.

Configuration Reference

A comprehensive source for detailed information on asset parameters and their interactions.

Using the asset

⚠ Warning: It is important to understand that the flow of data between the broker and the device highly depends on the configuration of both the asset and the device. In case of unexpected results, please verify the configuration and/or check the logs for any possible errors.

With Coreflux HUB

Please refer to the general docs for asset installation through the Coreflux HUB.

With Coreflux HUBLESS

Asset management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the $SYS/Coreflux/Command topic. The results of these commands are published to $SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ : The asset guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Run asset

  1. Run asset:
-R <asset_guid>

Stop asset

  1. Stop asset:
-S <asset_guid>

⚠ Warning: To update the asset configuration, ensure you stop it first to avoid issues. After making the changes, restart the asset to apply the new configuration.

Logs

Logs are essential for monitoring and debugging your system. They provide insight into the operation of your assets and can help identify and resolve issues promptly.

With Coreflux HUB

On Coreflux HUB, the logs are displayed in the "Log" section of the asset configuration.

With MQTT Explorer

To display logs in MQTT Explorer, follow these steps:

  1. Publish the following command to the $SYS/Coreflux/Command topic:

-addTraceLog topic=topic/to/show/log level=Error/Information/Warning messageContains=(assetID)
2. The logs will be shown on the $SYS/Coreflux/Log/Traces/topic/to/show/log topic.

Example1:

To display informational logs, use:

-addTraceLog topic=log/inf level=Information

Note : This will display the Logs "Information" of all the assets

Example2:

To display error logs, from a specific asset, use:

-addTraceLog topic=log/ethernetip/err level=Error messageContains=assetID

Note : This will display the Logs "Error" of a specific asset

Note: To display all three types of logs (Error, Information, and Warning), you will need to repeat this process three times, one for each log level. three times, one for each log level.