This chapter explains the usage of the EtherNet/IP specific features of the Communication Creator.
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
1.1.1 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
1.1.1 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
Sonderzeichen fehlen
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.
1.1.1 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”.