EtherNet/IP Feature

Owned by Veronika Tannewitz
Last updated: May 19, 2022 by Marcus Tangermann
18 min read

 

 

Introduction

To start using port EtherNet/IP stack with own application one has to:

  • Define Software Model;

  • Create Application Code;

  • Create Device Description (EDS file);

To assist its customers with getting started quickly, port provides Communication Creator utility application. Industrial Communication Creator for EtherNet/IP comes with easy to use forms and wizards, which make it easier to configure EtherNet/IP stack to user needs.

Functionality provided by the tool include

  • Generation of stack configuration files;

  • Generation of software model definition file;

  • Generation of device description EDS file;

  • User assistance for each configuration setting;

  • Detection of common configuration errors;

  • Step by step configuration guide in form of task list.

EtherNet/IP Projects

port EtherNet/IP stack configuration, together with software model, is defined as a single Communication Creator project. Using this project, the tool can generate appropriate code files. Working with EtherNet/IP projects is analogous to working with other Industrial Communication Creator projects. If some aspects are not clear, please check help pages for common functionality: Industrial Communication Creator User Guide.

Project Type

User will be able to create and edit EtherNet/IP projects if he has support for this protocol installed into Industrial Communication Creator application. One can check if that is the case, by opening About Dialog from Help main menu and checking if section Supported project types contains line " EtherNet/IP (full version)".

In Package Explorer View, EtherNet/IP projects are shown with blue EIP icon ( Sonderzeichen fehlt). Project node contains up to three project contents, as shown on Figure 130. Meaning of these sub-nodes will be explained in Code Generation chapter.

 

Figure 130: Example EtherNet/IP project entry in Package Explorer view

Creating New EtherNet/IP project

The creation of new EtherNet/IP project is straightforward. From File main menu, select New option. In case the Communication Creator product supports more project types, the user will be asked to choose what kind of project to create. Select entry EtherNet/IP Project (EtherNet/IP) - see Figure 131 and click OK.

Figure 131: Contents of Select Wizard dialog with EtherNet/IP entry

Specify project file location and version

On the first page of wizard, user is asked to specify location of project file and the version of the project. User can choose between versions with or without IRJ45 support. Wizard window looks similar to that presented on Figure 132. To proceed, click Browse button to display your OS-specific select-file dialog. Project file name has extension .iccproj.

Tip: You can organize project files on disk however you want, but consider creating a new folder for each new project. This way it will be easier to know which code file belongs to which project.

 

Figure 132: First page of New Project wizard

It is possible to select already existing project file. User must be careful though, as it will result in losing all information saved to this file and replacing it with clean new project. This will happen as soon as Wizard finishes. Wizard warns about overwriting existing files with message shown on Figure 133.

Figure 133: Warning that specified file already exists

After location of project file is specified, proceed to next page by clicking Next button.

Specify location for generated code

Second wizard page asks user to specify location of four files that will be generated based on project configuration.

  • Software model configuration file goal_appl.c;

  • GOAL specific settings files goal_config.h; goal_app_parameter_data.h;

  • EDS device description file.

The page is presented on Figure 134. File name of EDS file is not immediately known as it depends on configuration options. As initial setup, wizard will suggest to locate these files in the same directory as project file.

Figure 134: Second page of New Project wizard

You may change location where each of these files is to be saved by using Browse button. Be careful to not overwrite some previously created files. Wizard will warn user if one or more files already exist in location specified – see Figure 135.

Figure 135: Warning that a target file already exists

Finish project creation

After all locations are set, click Finish button to create the project. You may also get back to previous page using Back button. If you do not want to continue with new project creation, click Cancel.

It may be possible that one of selected locations will be inaccessible for the tool. For example, user running application may not have write rights to selected directory. In this case wizard will not finish, but display error message - Figure 136. In this case user has to change specified path and try again.

Figure 136: Error message when projects files can not be created

During wizard finish, user will be once again warned about every overwrite risk that was detected and asked for confirmation - Figure 137. In case of any doubts, click Cancel to postpone project creation. Otherwise, click OK to continue.

Figure 137: The user has to confirm file overwrite

After project creation wizard finishes successfully, project file will be created and filled with empty project configuration. Other files (goal_config.h, goal_app_parameter_data.h, goal_appl.c, EDS) will be created later. The new project will be opened in new editor tab that appears on top of application window.

Validation

EtherNet/IP projects are subject to correctness checks as every other Industrial Communication Creator project:

  • After project is opened;

  • Before project is saved;

  • At user request.

You can request project validation using Package Explorer. Right click on project entry in Package Explorer View and select Validate menu option. Validation may take a few seconds. After it finishes, dialog with results appears. If no problems are found, the message will simply say "OK". Otherwise, quick overview of detected problems will be displayed in dialog similar to presented on Figure 138.

Figure 138: Dialog with results of explicitly request project validation

See Common Problems chapter for list of common issues that may be reported during validation, and how they may be resolved.

EtherNet/IP projects share editing tools with other Industrial Communication Creator project types. To learn about basic editor elements such as toolbar or input forms, see help pages for common functionality: Industrial Communication Creator User Guide.

Editor Extensions

Top Page

After project is loaded, editor will display graphical top page for it. User can always return to this editor page by using Go Home tool ( ). Sonderzeichen fehlt

Top page for EtherNet/IP project is presented on Figure 139. Each burgundy-red block is a click-able link to editor page with configuration elements. You can also hover mouse cursor over the figure to display longer description of block contents as tool-tip.

Blocks are organized into three groups:

General

General Settings of EtherNet/IP stack configuration.

Project Preferences

Settings for C Code generation.

Device Description

Settings related to creation of device description file.

Software Model

Structure of objects of which application's software model is made plus configuration of the driver.

Figure 139: Top Page for EtherNet/IP project

Software Model Pages

Modularity of EtherNet/IP stack is represented in software model. The software model is separated into Parameters, Assemblies and Connections. Number and properties of these objects are to be specified by the user, with each new project being initialized with few example Parameters, Assemblies and Connections as starting point.

Editor page for managing Parameters, Assemblies and Connections is available from top page under blocks Parameters, Assemblies and Connections. Be aware that number and names of blocks depend on your current project configuration.

Code Preview

Editor for EtherNet/IP projects has four additional tabs beside main Design Tab. All of these are used for preview of generated code.

Figure 140: Tabs for EtherNet/IP editor

Sonderzeichen fehlen

goal_appl.c

Preview of C file where software model is defined for use in EtherNet/IP stack.

  goal_config.h

Preview of C header file for EtherNet/IP stack configuration.

  goal_app_parameter_data.h

Preview of C header file for EtherNet/IP stack configuration (access to parameter).

 

  EDS

Preview of EDS file.

Each time code preview tab is opened, its contents are refreshed to match current project configuration. If project contains errors or inaccuracies previewed code may be incorrect or code will fail to generate altogether. In any case, project validation provides clues about nature of the problem.

 

Code Generation

The EtherNet/IP Communication Creator generates several files to be used within the port EtherNet/IP Stack. This chapter shows how to generate the files via the command line, gives a short overview over the meaning of the different generated files and how to view them.

CMD generation

It is possible to generate files and set variables through CMD commands. The CMD Communication Creator is started via commands with following structure:

a) iccCmd <singleOption>

 

b)  iccCmd <option 0> ... <option n> <iccProjectFile>

Case a) can only have one option (see Table 38).

Case b) can consist of multiple options (see Table 38) but the end of the command has to be always the full path of the project file. Options are separated by whitespaces and start with a double minus (--). The steps done by the commands are documented in the errorProtocol.txt file and after every command the project file will be saved. See chapter 25 for usage of options in commands.

Pre-/Post-Generation

It is possible to execute application-specific programs before and after generation. The commands can be entered about the Generation-block in the editor view > Pre-/Post-Generation Commands. The commands can be a shell-script or a batch file, or you can call an executable file, e.g. the GSDML checker, make all. The output of the command is written into the information file "errorProtocol.txt".

Generated files

goal_appl.c

goal_appl.c file is a C code file which contains structure definitions of application software model.

Code can be displayed for inspection using appropriate editor tab. Location where goal_appl.c file is saved is specified when project is created. The path can be seen on top of code-preview tab. User can change this location using Browse button ( ) in code-preview tab toolbar.

If auto-save check box is selected, the code file will be rewritten, each time project changes are saved to disk. User can also save file manually using Save toolbar button.

Contents of goal_appl.c file depend on what Parameter, Assemblies and Connections are defined. You can get more information about software model in Software Model chapter.

goal_config.h

goal_config.h file is a C header file which contains definitions needed for EtherNet/IP stack configuration.

Code can be displayed for inspection using appropriate editor tab. Location where goal_config.h file is saved is specified when project is created. The path can be seen on top of code-preview tab. User can change this location using Browse button ( ) in code-preview tab toolbar.

If auto-save check box is selected, the code file will be rewritten, each time project changes are saved to disk. User can also save file manually using Save toolbar button.

goal_app_parameter_data.h

goal_app_parameter_data.h file is a C header file which contains definitions needed for EtherNet/IP stack configuration and access to the created parameter in source code.

Code can be displayed for inspection using appropriate editor tab. Location where goal_config.h file is saved is specified when project is created. The path can be seen on top of code-preview tab. User can change this location using Browse button ( ) in code-preview tab toolbar.

If auto-save check box is selected, the code file will be rewritten, each time project changes are saved to disk. User can also save file manually using Save toolbar button.

You can get more information about software model in Software Model chapter.

EDS

Device description, which is needed for IO controller to properly initialize connection with EtherNet/IP device, is saved in EDS format. EDS is a text document which contains EtherNet/IP device description.

Code can be displayed for inspection using appropriate editor tab.

Directory where EDS file is saved is specified when project is created. The path can be seen on top of code-preview tab. User can change this location using Browse button ( ) in code-preview tab toolbar. The file name is made of the project name.

Contents of EDS file depend on Software Model and Device Description Settings.

Common EtherNet/IP problems

During Project Validation problems can be detected in user project. These are collected by Problems View application part, for the user to browse.

In chapter 20 the list of common problem reports concerning EtherNet/IP projects, their meanings and solutions can be found.

The EtherNet/IP Software Model

Obligatory step of EtherNet/IP stack configuration is definition of software model. The software model is supposed to reflect modular and hierarchical structure of hardware it was derived from.

Parameters

This module is used to create parameter entries in the EDS file. Initial project template for EtherNet/IP comes with 4 Parameters already defined (see Figure 141). Properties of the Parameters will be put into EDS file.

Figure 141: Overview of all created Parameters

The following section describes the different Parameters properties users can set.

Name

Figure 142: Parameter name input field

Human-readable name of the Parameter. Shall be concise, yet descriptive. Uniqueness is not enforced, but shall be avoided as potential source of confusion.

Name of Parameter is shown as its label in tree view.

The details-button reveals more specific properties.

Param Id

Figure 143: Parameter number of ports entry field

This number is used to identify the parameter. If the parameter is implemented in the device as a Parameter Object Instance the Parameter ID shall match the instance ID.

Description

Figure 144: Parameter description input field

Additional text information about the Parameter.

DataType

Figure 145: Parameter dataType selection field

This option sets the data type of the parameter. Some data types are not supported yet by OpENer.

Default Value

Figure 146: Parameter default value input field

The default value for this parameter. Its data type depends on the value of “DataType”.

Minimum Value

Figure 148: Parameter maximum value input field

The maximum value this parameter can be set to. Its data type depends on the value of “DataType”.

Access

Figure 149: Parameter access selection field

Sets access of the parameter. It can be “Read/Write”, “Read only” or “Write only”. The attribute value can only be read if the parameter exists as a Parameter Object. The attribute value can only be written if the parameter exists as a Parameter Object.

Exists on network

 

Figure 150: Parameter maximum value input field

If this option is set the application must implement this parameter as a Parameter Object.

Assemblies

This module is used to create Assemblies. Assemblies are the endpoints of Implicit Connections, i.e. They define the layout of the cyclic IO data. Initial project template for EtherNet/IP comes with three example assemblies already defined (see Figure 151). They can be changed or removed depending on user preference.

Figure 151: Overview of all created Assemblies

The following section describes the different assembly properties users can set.

 

Name

Figure 152: Assembly name input field

Human-readable name of the assembly. Shall be concise, yet descriptive. Uniqueness is not enforced, but shall be avoided as potential source of confusion.

Name of assembly is shown as its label in tree view. It will be put into software model code as well as device description code.

Instance Id

Figure 153: Assembly instance id input field

Instance ID if the Assembly Object. Unsigned 16-bit integer. Each assembly must have unique instance id. Instance ids below 1 are reserved. Assembly instance id together with the name are displayed as Assembly's label, in decimal format e.g. "Assembly: Input Assembly; ID: 100".

Description

Figure 154: Assembly description input field

Additional text information about assembly.

C Name

Figure 155: Assembly C name input field

This is used by the goal_appl.c file as part of the variables which are generated. Uniqueness is enforced. For each assembly there are two variables generated: one for the instance id and one for the size of the assembly. If no C name is given, the instance id is used as part of these variables’ names, e.g. with C name: “#define GOAL_APP_ASM_ID_INPUT”, “#define GOAL_APP_ASM_SIZE_INPUT”, without C name: “#define GOAL_APP_ASM_ID_100”. “#define GOAL_APP_ASM_SIZE_100”.

Configure Members

Figure 156: Assembly configure members button and table

This part let the user configure members of an assembly. If there are already members selected, they are shown in a table with the referenced Parameter, e.g. “Member3: Parameter Input Data, ID: 1, Size: 8”. If user wants to add/delete members from assembly, user has to click on “Configure Members”-button which opens the Wizard for selecting members (see Figure 157).

Figure 157: Configure Members Wizard

Members can be added by selecting a Parameter from the upper list and click on “Add new Member”-button. To delete a member select the member from the “MemberList” and click on “Delete selected”-button (multiple selection possible).

Connections

This module is used to create Implicit CIP connections, i.e. cyclic IO messages. Initial project template for EtherNet/IP comes with three example connections already defined (see Figure 158). They can be changed or removed depending on user preference.

Figure 158: Overview of all created Connections

The following section describes the different connections properties users can set.

 

Name

Figure 159: Connection name input field

Human-readable name of the connection. Shall be concise, yet descriptive. Uniqueness is not enforced, but shall be avoided as potential source of confusion. The connection name can be used by a configuration tool to select a connection

Description

Figure 160: Connection description input field

Additional text information about connection. This description can be used to describe the data that is exchanged with this connection.

Transport Class

Figure 161: Connection transport class selection

Implicit Connections can either have the Transport Class 0 or the Transport Class 1. Messages of the latter transport class have a 16-bit sequence count.

 

Production Trigger

Figure 162: Connection production trigger selection

This option defines which Production Triggers are supported for this connection. The following triggers are available:

§  cyclic (data is cyclically produced)

§  change of state (data is produced when a change of state is detected)

§  application (application decides when to produce data).

 

Application Type

Figure 163: Connection application type selection

Set the Application connection Type:

  • Exclusive Owner (device produces data and consumes data from a single originator)

  • Input Only (device only produces data, connection is independent)

  • Listen Only (device only produces data, connection depends on existing non-Listen-Only connection)

  • Redundant Owner (device produces data and consumes data from a single originator, other originators wait on standby).

 

Connection Parameters

Figure 164: Connection’s connection parameters

Connection parameters must be specified for both directions.

§  Originator-to-Target (consuming direction for device)

§  Target-to-Originator (producing direction for device)

 

Fixed size supported

Figure 165: Connection fixed size supported selection

The consumed or produced IO data has a fixed size.

 

Variable size supported

Figure 166: Connection fixed size supported selection

The consumed or produced IO data has a variable size, i.e. implicit messages can be valid even if they only contain a part of the cyclic data.

 

Real time transfer format

Figure 167: Connection real time transfer format selection

This option defines the format of the IO data within the Implicit Message.

  • Modeless Format (message only contains application data)

  • Zero Length Data Format (message only contains application data, data length 0 means idle mode)

  • Heartbeat Format (message contains no application data)

  • 32-bit Header Format (message contains application data prefixed with a header, header contains Run/Idle Information and Redundant Owner information)

 

Connection Type

Figure 168: Connection’s connection type selection

This option defines the supported types of a connection.

  • NULL (this direction does not open a connection)

  • Point to Point (this connection is sent to / received from a single endpoint)

  • Multicast (this connection is sent to / received from multiple endpoints)

 

Priority

Figure 169: Connection priority selection

This option defines the supported priorities of a connection. For EtherNet/IP these priorities are mapped to the DSCP value of the IP header in the CIP messages.

  • Urgent (for CIP Motion, highest priority)

  • Scheduled

  • High

  • Low (lowest priority)

 

RPI

Figure 170: Connection RPI input field and button

The Requested Packet Interval defines the requested cycle time for Implicit Messages in milliseconds. The EDS file can reference a parameter that defines a range of acceptable values. RPI values can be configured by clicking on the “…”-button next to the input field. In the subsequently opening Wizard-Dialog user can choose between direct input via a number in milliseconds or a pre-created Parameter (see Figure 171).

Figure 171: Selecting RPI wizard dialog

Consuming Assembly Instance

Figure 172: Connection consuming assembly instance input field and button

This option defines the assembly instance that is used for configuration data, i.e. the layout of the configuration data. This data is sent with a Forward Open Request during connection establishment.

 

Producing Assembly Instance

Figure 173: Connection producing assembly instance input field and button

This option defines the Assembly instance that is used for produced data, i.e. the layout of the data cyclically sent.

 

Config Assembly Instance

Figure 174: Connection producing assembly instance input field and button

This option defines the Assembly instance that is used for consumed data, i.e. the layout of the data cyclically received.

 

The configuration of the assembly instances can be done by clicking on the “…”-button next to each assembly instance input field. In the subsequently opening Wizard-Dialog user can choose a pre-created assembly or delete an assembly from this connection (see Figure 175).

Figure 175: Connection assembly instances selection wizard

Create/Delete Parameters, Assemblies and Connections

User can add much more Parameters, Assemblies and Connections in the Software Model than the predefined ones in new project template. One can add new one to the model by selecting Parameters, Assemblies or Connections editor block and using the “Add new …”-button

New object is defined using Wizard dialog. The wizard has one page, shown on Figure 176, where to specify basic Object properties like name and id.

Figure 176: Create new Parameter Wizard

Completing this page is needed to create the Object. You have to at least provide valid name and id for the wizard to continue. Remember, that Id must be unique within an Object type.

After name and identification number are specified, the user is free to finish the wizard by clicking the Finish button.

Parameter/Assembly/Connection objects that are no longer used, can be deleted from software model. This can be done either through editor via the “remove”-button or Outline (see Figure 177).

Figure 177: Deleting Objects using Outline View

Settings reference

A detailed reference of all available settings for port EtherNet/IP stack can be found in the online help of the Communication Creator. Please open the help system via menu “Help” à “Help contents”. Then select “port EtherNet/IP Tool User Guide” à “Settings Reference”.