CC-Link IE TSN Feature

This chapter explains the usage of the CC-Link IE TSN specific features of the Communication Creator.

Introduction

To start using port CC-Link IE TSN stack with own application one has to:

• Define Software Model;

• Create Application Code;

• Create Device Description (CSPP file);

To assist its customers with getting started quickly, port provides Communication Creator utility application. Industrial Communication Creator for CC-Link IE TSN comes with easy to use forms and wizards, which make it easier to configure CC-Link IE TSN 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 CSPP file;

• Generation of various documentations

• User assistance for each configuration setting;

• Detection of common configuration errors;

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

An important distinction of CC-Link IE TSN is that the ICC supports the CANopen data access mode defined in the standards. Devices can be built with or without this feature. The object dictionary is only valid when using this feature. This feature is activated by marking a station mode as a CANopen station mode.

CC-Link IE TSN Projects

port CC-Link IE TSN 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 CC-Link IE TSN 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 CC-Link IE TSN 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 " CC-Link IE TSN (full version)".

In Package Explorer View, CC-Link IE TSN projects are shown with blue/red CC icon ( ). Project node contains up to seven project contents, as shown on Figure 230. Meaning of these sub-nodes will be explained in Code Generation chapter.

Open

Figure 230: Example CC-Link IE TSN project entry in Package Explorer view

Creating New CC-Link IE TSN project

The creation of new CC-Link IE TSN 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 CC-Link IE TSN Project () - see Figure 231 and click OK.

Open

Figure 231: Contents of Select Wizard dialog with CC-Link IE TSN 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. Wizard window looks similar to that presented on Figure 232. 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 232: 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 233.

Figure 233: 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 seven files that will be generated based on project configuration.

• Stack configuration file cclco_cal_conf.h, goal_appl.c, goal_config.h;

• Object dictionary files goal_ccl_objects.h, goal_ccl_objects.c, goal_ccl_od.c;

• Device description file CSPP.cspp;

The page is presented on Figure 234.

Figure 234: 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 235.

Figure 235: Warning that a target file already exists

Finish project creation

After all locations are set, click Finish button to create the project. 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 236. In this case user has to change specified path and try again.

Figure 236: 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 237. In case of any doubts, click Cancel to postpone project creation. Otherwise, click OK to continue.

Figure 237: 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 (cclco_cal_conf.h, goal_appl.c, goal_config.h, goal_ccl_objects.h, goal_ccl_objects.c, goal_ccl_od.c, CSPP.cspp) will be created later. The new project will be opened in new editor tab that appears on top of application window.

Validation

CC-Link IE TSN 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 238.

Figure 238: 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.

CC-Link IE TSN 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 CC-Link IE TSN project is presented on Figure 239. 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:

Project Settings

General Settings of CC-Link IE TSN stack configuration.

Project Preferences

Settings for C Code generation and extended interface settings.

Tools

Utility functions for Import/Export.

Device Description

Settings related to creation of CSP+ file.

Line Settings and Object Dictionary

Structure of objects of which application's software model is made.

CSP+ File description

Settings related to creation of CSP+ file structure.

Figure 239: Top Page for CC-Link IE TSN project

Software Model Pages

Modularity of CC-Link IE TSN stack is represented in software model. The software model is separated into Segments. Number and properties of these objects are to be specified by the user, with each new project being initialized with few examples as starting point.

Editor page for managing Sub-Segments, Indices and Sub-Indices is available from top page under blocks Data Types, Communication Segment, Manufacturer Segment and Device Profile Segment. Be aware that number and names of blocks depend on your current project configuration.

Code Preview

Editor for CC-Link IE TSN projects has seven additional tabs beside main Design Tab. All of these are used for preview of generated code.

Figure 240: Tabs for CC-Link IE TSN editor

  goal_config.h ; cclco_cal_conf.h ; goal_ccl_objects.h

Preview of C header file for CC-Link IE TSN stack configuration.

  goal_appl.c ; goal_ccl_od.c ; goal_ccl_objects.c

Preview of C code file where software model is defined for use in CC-Link IE TSN stack.

  CSPP.cspp

Preview of CSP+ file displayed using HTML style.

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 CC-Link IE TSN Communication Creator generates several files to be used within the port CC-Link IE TSN 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 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 41) 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. 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.

goal_config.h

goal_config.h file is a C header file which contains defines needed for GOAL 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.

cclco_cal_conf.h

cclco_cal_conf.h file is a C header file which contains defines needed for configuration of CC-Link IE TSN stack.

Code can be displayed for inspection using appropriate editor tab. Location where cclco_cal_conf.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.

Note: This is an optional file for the CANopen data access mode.

goal_ccl_od.c

goal_ccl_od.c file is a C code file which contains the Object Dictionary of CC-Link IE TSN device.

Code can be displayed for inspection using appropriate editor tab. Location where goal_ccl_od.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.

Note: This is an optional file for the CANopen data access mode.

goal_ccl_objects.h

goal_ccl_objects.h file is a C header file which contains defines needed for Object Dictionary.

Code can be displayed for inspection using appropriate editor tab. Location where goal_ccl_objects.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.

Note: This is an optional file for the CANopen data access mode.

goal_ccl_objects.c

goal_ccl_objects.c file is a C code file which contains defines needed for Object Dictionary.

Code can be displayed for inspection using appropriate editor tab. Location where goal_ccl_objects.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.

Note: This is an optional file for the CANopen data access mode.

CSPP.cspp

A CSP+ file is a .xml file which contains descriptive and communication information of the hardware device.

Code can be displayed for inspection using appropriate editor tab. Location where CSPP 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.

Additional files

An optional file is the .csv-file which contains the Object Dictionary according to BAP-C2008ENG-001-E.

It has by default the file name ObjectFile.csv. This setting can be set on “Optional Device Settings”-block. User can set an icon file as well as a graphic file next to the csv file. If there are one or more of those three files selected then they are generated into a folder that is named after the vendor code which is specified at “Device Identification”-block. Additionally this folder is zipped together with the CSP+ file.

Documentation files

User-defined files that contain various information about e.g. html-documentation or user-defined profiles and settings.

Those files were generated if the checkbox-button at the Export documents-view is activated (see Figure 241).

Figure 241: overview of all created documents by Communication Creator

Common CC-Link IE TSN 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 23 the list of common problem reports concerning CC-Link IE TSN projects, their meanings and solutions can be found.

Profile Databases

Profile databases contain standardized objects with their attributes and allow implementations in shortest time. The Communication Creator is delivered with profile databases for communication objects according to CLPA standards.

If communication objects are set up with the Communication Creator, the objects will be loaded automatically from the profile databases. Additionally various profile databases to profile device standards are available at port, see Table 32.

Objects within segments in the project tree can be exported to own profile databases. The objects from all profile databases can be imported.

Table 32: overview about profile databases

Note: This is only valid for the CANopen data access mode.

The CC-Link IE TSN Software Model

Obligatory step of CC-Link IE TSN stack configuration is definition of software model. The software model is supposed to reflect modular and hierarchical structure of hardware it was derived from.

Each Communication Creator project specifies a field device with 1 CC-Link IE TSN device. Each CC-Link IE TSN device is connected with one CC-Link IE TSN network. That means each CC-Link IE TSN device is assigned to an CC-Link IE TSN line (Figure 242). Each CC-Link IE TSN device can have 1-8 logical devices.

Note: This chapter is only valid for the CANopen data access mode.

Figure 242: Device structure

Line

The Line item in the project tree represents a network and includes the object dictionary of the device for the line

Object Dictionary

The object dictionary specifies all needed objects and their properties and is grouped in the following segments:

• Data Types: contains all data types in the index range 0x0001 - 0x0FFF

• Communication Segment: contains all objects for communication services in the index range 0x1000 - 0x1FFF

• Manufacturer Segment: contains manufacturer-specific objects in the index range 0x2000 - 0x5FFF

• Device Profile Segment: contains device profile objects in the index range 0x6000 - 0xFFFF, it is possible to split this range for logical devices according to the device profile standards

Sub-segmentation

Inside the Manufacturer Segment and the Device Profile Segment it is possible to create virtual or real sub-segments.

Virtual sub-segments are used to structure the graphical user interface and for the creation of own sub-segment-specific profile data bases.

Real sub-segments are providing the access about named array variables additionally. This access to variables in C code can be useful for devices with identical logical devices:

device[0].control = 0x1234;

device[1].control = 0x5678;

The indexing on the named array variables starts always with 0 in C code style. The data type of the named array variables is a generated C structure representing all objects inside the sub-segment:

typedef struct {

UNSIGNED16 control;

} CO_OD_LINE0_devSub_T;

CO_OD_LINE0_devSub_T device[2];

All sub-segments are specified by the following properties:

Table 33: sub-segment properties

A new sub-segment can be created about tab Mask > Add New Sub-Segment after selection of the Manufacturer Segment or the Device Profile Segment.

An existing sub-segment can be configured about tab Mask > Configure Sub-Segment after selection of the sub-segment.

An existing sub-segment can be removed about right-click menu > Delete after selection of the sub-segment. ATTENTION! - All objects inside the sub-segment are also deleted!

The usage of sub-segments bases on the following rules:

• A sub-segment must be located completely inside the Manufacturer Segment or the Device Profile Segment.

• The index range of a sub-segment must not overlap the index range of another subsegment.

• The C name of sub-segments inside the Manufacturer Segment must not be used for sub-segments in the Device Profile Segment and vice versa.

• All sub-segments with the same C name must be real or virtual and have to include the same objects shifted by an index offset.

• All sub-segments with the same C name must be constant or non-constant.

Settings reference

A detailed reference of all available settings for port CC-Link IE TSN 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 CC-Link IE TSN Tool User Guide” à “Settings Reference”.

 Project editing

This chapter describes the working flow for creating and editing projects. The order of the flow is not mandatory, but very useful. Basic parameter like the number of CC-Link IE TSN lines and the kind of the device (Slave or Master) shall be clear at the beginning of the development. The necessary steps are the following:

• configuration of global parameter

• configuration of global CSPP parameter

• definition of application variables

• parameterization of application variables

• definition of communication variables

• parameterization of communication variables

• optimization of each object if needed

• generation of outputs

Beginning a project

A project is created by the menu File > New.

Existing projects are opened by the menu File > Open… . The CC-Link IE TSN line can be preset with data from a profile or an user-defined object dictionary file.

Station Modes and CSP+ file

Next to mandatory and optional device identity settings Station Modes can be configured at the “Device Description” section of the editor’s top page.

They can be created using the “Add new Station Mode”-button or deleted via the “remove”-button (see Figure 243). The radio-button specifies which Station Mode should be active by default and via the “details”-button more settings of the Station Mode can be specified.

Figure 243: Overview of all station modes

For every created Station Mode one COMM_IF section will be created in the CSP+ file structure. Every COMM_IF section has one COMM_IF_INFO part which contains all necessary elements of the device identity and Station Mode settings.

Figure 244: CSP+ file structure

User can add more COMM_IF parts if needed. They can be added/removed at the Sections-view by clicking on a COMM_IF section. The part type and the position can be selected via combo-box and spinner before adding the part with the “Add Part of type”-button.

Figure 245: Add/remove COMM_IF parts

In the details of each station mode, several link devices can be set (Figure 246). The sizes define how many points or words of data can be sent in each direction. The addresses are used during communication setup to specify communication partners.

Figure 246: Linked Devices of a selected Station Mode

It is up to the application to fill the link devices with valid data or handle incoming data.

If the station mode is set to CANopen station mode, only the addresses are required as the object dictionary will be used as data storage. The communication setup will also use the PDO settings found inside the object dictionary.

Application and Device variables

Definition of application variables is the creation of objects with indices in the range of 0x2000 – 0x5FFF for manufacturer-specific objects or in the range of 0x6000 – 0xFFFF for standardized device-profile objects (device variables). There are two ways for the definition:

• loading from a profile database and

• creation by hand

Certain objects can be selected by means of their index from a profile database. Databases for the standardized CC-Link IE TSN device profiles are available from port. If a database does not yet exist, please contact port. All non-standardized objects and not provided objects by a database can be created by hand.

The main-index defines the structure and properties for all sub-indices of the object.

Note: This is only valid for the CANopen data access mode.

Figure 247: import mask for profiles

C Implementation

There are different possibilities of the C implementation of an object. These possibilities are explained in the following table.

Table 34: C implementation types

Parameterization

For parameterization of complex communication variables the mask view can be used.

Generation of source code

About the “save”-button next to saving the project file all files listed in chapter 13.4.3 are generated if no validation errors occur.

This method guarantees that all C code and documentation files are consistent to each other.

The Problems-view contains warnings and errors which are generated into the errorProtocol.txt file, too. It is recommended to check the Problems-view or this file after each generation.

%-Variables

%-variables can be used in Object Names and C Names of objects. In the file goal_ccl_objects.c, in the documentation and also in the object tree the %-variables are replaced by their current values.

Table 35: %-variables

For numerical object settings the %-variable written in lower case is replaced by the decimal value, otherwise the %-variable is replaced by the hexadecimal value without leading "0x". %-Variables that are undefined in the current context return an empty string, e.g. %s at a main-index.

Examples for the usage of these %-variables can be found at the PDO Mapping objects in the communication profile.

{}-Expressions

{}-expressions allow the usage of %-variables and mathematical operators in Object Names and C Names of objects. Inside of the braces %-variables, constants (decimal/hexadecimal) and the operators + - * and / can be used. Examples for valid object names with {}-expressions:

• output {%i - 0x100}

• state {%p + 100} at device %l

Special cases

This chapter describes some special cases for object dictionary generation. The CC-Link IE TSN Communication Creator supports the generation of object dictionary implementations for the ’single’-line release of the CC-Link IE TSN stack of port. The following special cases are used for the optimization of the implementation.

Grouping of indices in sub-segments

A further characteristic is the organization of device variables within structures. Such an organization is possible for the manufacturer data and for data of the standardized device profiles. This is convenient if identical entries in the individual sub-segments are stored. If the data of two sub-segments shall be filled in a structure, the sub-segments shall share the same variable name and the same length.

Useful steps for this are:

• Creation of the sub-segment (Add new sub-segment)

• Filling with objects

• Duplication of the sub-segment (sub-segment view / “Duplicate sub-segment”-button)

Result of this grouping is a structure and a C-array of the type of this structure. The array has as many elements as group members (sub-segments with same variable name) are available. The advantage of such an organization is that the indexed addressing of the C arrays can be used. E.g. with multi axis drives for fast access with pointer switching in firmware between the individual axes.

The same principle is pursued for manufacturer data. However, it is possible to select a starting index for the segment and to declare the segment size freely. That means that the data is stored normally up to the user defined index. From this index on the tree becomes segmented in the manufacturer specific area.

Complex data types

The standard allows the definition of manufacturer-specific complex data types within the index range 0x0040-0x005F and device profile specific standard and complex data types within the index range 0x0060-0x025F. The Industrial Communication Creator only supports the device profile specific complex data types with the object code DEFSTRUCT.

Before objects of such data types can be specified, the data type must be created in the Communication Creator. The following steps are necessary to create a new data type:

1. select

Line > Object Dictionary > Data Types in the project tree

1. press

Add new Data Type on tab Mask

→ the input dialog Add new Index is opened

1. enter the desired index into the dialog

Add new Index in hexadecimal or decimal format, example: 0x0040 or 64, and press <Enter>

→ an entry for the new data type is in the project tree, see Line > Object Dictionary > Data Types > <new index>

1. specify the new data type about button

Add new Sub-Index, Sub-Index-view

If the data type is created, objects of the data type can be defined, when the objects have the Object Code RECORD.

It is recommended to use the same name for C Name and Object Name for the data type.

During the generation process the Industrial Communication Creator generates a struct definition for the data type and stores the struct definition in goal_ccl_objects.h. Sub-index 0 does not belong to the struct.

Import

Sub-segments and indices can be imported via the Import GUI. User can select between different import options e.g. delete objects before the import action or override existing objects (Figure 248: Import GUI). Example Profile databases with standardized indices for import are located at:

<toolInstallDirectory>/plugins/de.port.dsntool.ui.cclink.helppages_*/SegmentProfiles/

Figure 248: Import GUI

There are several files and filetypes available for import (see Table 36) and some of them need an additional description template created by the user to get properly read by the Communication Creator.

Table 36: Supported files/filetypes

csv-Import

The Industrial Communication Creator provides the import of object specifications in the csv-format for:

• manufacturer-specific complex data types (index range: 0x0040 – 0x005F)

• profile-specific complex data types (index range: 0x0080 – 0x0FFF)

• objects for communication, manufacturer-specific and device profile (index range: 0x1000 - 0xFFFF)

• object-specific options for the code generation

All data from the csv-file are imported into the specified line of the actual Industrial Communication Creator project.

The specification of an object refers to:

• main-index, i.e. these specifications are valid for all sub-indices of the object, and

• sub-index, i.e. these specifications are only valid for the specific sub-index of the object.

The differentiation between main-index and sub-index is relevant for objects of object code ARRAY or RECORD especially.

If the object already exists in the Industrial Communication Creator project it is completely substituted by the imported object specification, i.e. the object is deleted with all sub-indices and then the new object is imported. Sub-index 0 must be imported before higher sub-indices.

Errors during csv-import are reported about the GUI.

Numerical values in hexadecimal format has to be written with the prefix "0x" in C Syntax, example: 0x123A.

For csv-Import a description template representing the structure of the data file is needed.

Structure of the csv-description template file

The csv-description template is a .txt file that contains one line of special keywords for each object property separated by the csv-separator sign (Figure 249: Example of csv-description template). These separator signs can be comma, semicolon or colon but only one per template and data file. All csv-data lines have to use the same csv-specifier line. The csv description template can be entered about the GUI. All supported csv-specifiers for import can be seen in Table 44.

${index.address},${subindex.address},${index.CName},${index.objectCode},…

Figure 249: Example of csv-description template

Structure of the csv-data-file

The csv-import has taken the recommendations from /RFC 4180/ in consideration with few extras. Empty lines and comments between the csv-data are allowed. Empty lines mean lines without any char or lines containing only the csv-separators in the correct number. These lines are ignored during the csv-import as well as additional comment lines who are signed with a leading “#”.

Each csv-data line has to contain the specification of one object identified by the main-index and sub-index. This specification is a list of object properties, which can be arranged application-specific. The specification is defined by the csv description template.

If the csv-data-file has coloumns with unwanted values, then this coloumn can be skipped by writing the special ignore key: “${IGNORE}” at the dedicated position in the csv-description template file.

Import with description templates

The Industrial Communication Creator provides the import of object specifications in user-defined-formats for:

• manufacturer-specific complex data types (index range: 0x0040 – 0x005F)

• profile-specific complex data types (index range: 0x0080 – 0x0FFF)

• objects for communication, manufacturer-specific and device profile (index range: 0x1000 - 0xFFFF)

• object-specific options for the code generation

All data from the selected data file are imported into the specified line of the actual Industrial Communication Creator project.

The specification of an object refers to:

• main-index, i.e. these specifications are valid for all sub-indices of the object,

• sub-index, i.e. these specifications are only valid for the specific sub-index of the object, and

• sub-segment, i.e. these specifications are only valid for the specific sub-segment of the object.

If the object already exists in the Industrial Communication Creator project it is completely substituted by the imported object specification, i.e. the object is deleted with all sub-indices and then the new object is imported.

Errors during user-defined-import are reported about the GUI.

The user-defined Import needs a description template that represents the structure of the imported data file.

Structure of the description template file

Empty lines and comments within the description template are allowed. Empty lines mean lines without any char and lines with a leading “#” means comment lines. These lines are ignored during the user-defined import.

The description template contains the structure of one object of the data file to be read. Each object property shall be delimited by a beginning tag and an end tag (end tag is always the first sign after the ftl-specifier). Between these tags is a ftl-specifier (ftl – FreeMarker Template Language), see Figure 250. The ftl-specifier is a placeholder that will be replaced with its current value while generating (see chapter 13.13.1 and 13.13.2 for more examples).

          <CCLinkObject index="${index.address.@hex}" name="${index.name}"  … >

              <CCLinkSubObject subIndex="${subindex.address.@hex}"  … />

          </CCLinkObject>

Figure 250: Example of description template for import xdd files

The “.@hex” specifies that in the data file the numerical value of this property has no hexadecimal-prefix “0x” but has to be interpreted as hex value.

A full example for a description template is located in “<ToolInstallDirectory>/plugins/de.port.dsntool.ui.cclink.helppages_*/DescriptionTemplates/xdd_template.txt”. The import of any XDD file is done via this description template by the Communication Creator.

All supported description template specifiers for import are listed in Table 44 and an example on how to write description templates for import is described in chapter 13.13.1.

Structure of the data file

Empty lines and comments between the data are allowed. Empty lines mean lines without any char and lines with a leading “#” means comment lines. These lines are ignored during the user-defined import.

The Communication Creator searches the data file for the beginning tags and filters out the data between the beginning tag and the end tag. There are some rules to ensure the correct reading of the user-defined data files:

1. the beginning of a new object is recognized by the number-property of a main-index, sub-index or sub-segment. This has to be always the first property for every object

1. numerical values that are in hex format and has no prefix “0x” but shall be interpreted as hexadecimal values can be marked in the description template via “${*.@hex}”

1. the datatype-property has to be before the limits- or defaultValue-properties

Export

Export profiles

The export of index profiles (.iccprof) can be done via the export documents GUI by specifying a line and a start and end index. A profile contains only indices and their sub-indices of one line and can be used e.g. as a database. Furthermore it is possible to export the sub-segment structure of the Manufacturer and Device Profile Segment, too (see Figure 251).

Figure 251: Export index profiles GUI

Export documents using description templates

The export of user defined documents can be done in the export documents GUI. A new document can be created by clicking on the “Add new document”-button and via the checkbox-button the generation of this file can be enabled (Figure 252). 

Figure 252: Export user defined documents GUI

The file name and destination can be selected via the “browse”-button and there can be up to nine documents created per project. The “details”-button opens the GUI of the selected document where the content of the file can be set (Figure 253).

Figure 253: Content GUI of one exported document

The content of one exported document can consists of up to four separate parts: 

• Sub-segments

• Indices

• Header

• End

The parts can be arranged in any order in the file with the “up/down”-buttons and every part can use its own description template. Also it is possible to use just one description template for a document.

Examples of documents are selectable via the “sample docs”-combo by selecting a file type from the combobox and then clicking the “apply”-button. There are the following file types selectable:

• Device description in CiA-301 style (.html)

Every example file comes with the needed description templates. All description templates the Communication Creator uses are stored in the directory: ../de.port.dsntool.ui.cclink.helppages_*/DescriptionTemplates which is opened when selecting description templates via the “template list”-button. The following path variable can be used only here at export documents which points always to this description templates directory: ${DESCR_TEMPL_PATH} e.g. usage when selecting description template for end: “${DESCR_TEMPL_PATH}\devDescCiA301Style_end.ftl”.

The description templates used by the export of documents are written in the FreeMarker Template Language (FTL). Basic instructions on how to write those files are described in chapter 13.13.2. For further instructions with more detailed information, please look at the FreeMarker user manual:

• https://freemarker.apache.org/

• https://freemarker.apache.org/docs/ref_builtins_string.html

Use cases

Writing Description templates for import

The description template for importing a user-defined file containing indices, sub-indices and sub-segments has to consist of one of each of these objects while the data values will be replaced by specifiers. A list of all supported specifiers can be found in Table 44

e.g there is a data file that contains some objects that look as follow:

    <Index index="1000">

            <Name> <![CDATA[p301_device_type]]> </Name>

            <EDS_Name> <![CDATA[Device Type]]> </EDS_Name>

            <MandatoryFlag> <![CDATA[1]]> </MandatoryFlag>

            <Description> <![CDATA[The device type specifies the kind of device. The lower 16 bit

                  contain the device profile number and the upper 16 bit an additional information.]]>

            </Description>

            <ObjectCode> <![CDATA[7]]> </ObjectCode>

            <MaxSubIndices> <![CDATA[1]]> </MaxSubIndices>

            <DataType> <![CDATA[0007]]> </DataType>

            <DefineIfExists></DefineIfExists>

            <LineDependent> <![CDATA[1]]> </LineDependent>

            <Link></Link>

            <Opt_ConstDefault> <![CDATA[1]]> </Opt_ConstDefault>

            <Opt_ConstDesc> <![CDATA[1]]> </Opt_ConstDesc>

            <Opt_ConstLimits> <![CDATA[1]]> </Opt_ConstLimits>

            <Opt_CreateExternal> <![CDATA[1]]> </Opt_CreateExternal>

            <Opt_CreateTypeDef> <![CDATA[0]]> </Opt_CreateTypeDef>

            <Opt_CreateVariable> <![CDATA[1]]> </Opt_CreateVariable>

            <Opt_Memory_Specifier></Opt_Memory_Specifier>

            <Opt_DefinedVarName></Opt_DefinedVarName>

            <Opt_SameStructure> <![CDATA[0]]> </Opt_SameStructure>

            <Opt_UseDefinedVar> <![CDATA[0]]> </Opt_UseDefinedVar>

            <Opt_VirtualObject> <![CDATA[0]]> </Opt_VirtualObject>

            <MaskNr> <![CDATA[1000]]> </MaskNr>

            <SubIndex subindex="000">

                <EDS_Name> <![CDATA[Device Type]]> </EDS_Name>

                <MandatoryFlag> <![CDATA[0]]> </MandatoryFlag>

                <DataType> <![CDATA[0007]]> </DataType>

                <Size> <![CDATA[4]]> </Size>

                <LowerLimit> <![CDATA[0x00000000]]> </LowerLimit>

                <UpperLimit> <![CDATA[0xFFFFFFFF]]> </UpperLimit>

                <DefaultValue> <![CDATA[0x00000000]]> </DefaultValue>

                <Value> <![CDATA[0x00000000]]> </Value>

                <Unit></Unit>

                <AccessTypes>

                        <AccessType active="1"> <![CDATA[CONST]]> </AccessType>

                        <AccessType> <![CDATA[RO]]> </AccessType>

                </AccessTypes>

                <PDO_Mapping><![CDATA[-1]]> </PDO_Mapping>

                <DefineData></DefineData>

                <DefaultEDS> <![CDATA[1]]> </DefaultEDS>

                <LimitEDS> <![CDATA[0]]> </LimitEDS>

                <RefuseRead> <![CDATA[0]]> </RefuseRead>

                <RefuseWrite> <![CDATA[0]]> </RefuseWrite>

            </SubIndex>

    </Index>

    <Structure>

        <Segment nr="1">

            <StartIndex>

                <![CDATA[6000]]>

            </StartIndex>

            <EndIndex>

                <![CDATA[9FFF]]>

            </EndIndex>

            <Name>

                <![CDATA[Device_Segment_I]]>

            </Name>

                <SubSegment nr="6000">

                <StartIndex>

                <![CDATA[6000]]>

                </StartIndex>

                <EndIndex>

                <![CDATA[67FF]]>

                </EndIndex>

                <Name>

                <![CDATA[Device_1]]>

                </Name>

                <VarName>

                <![CDATA[devseg]]>

                </VarName>

                <const>

                <![CDATA[0]]>

                </const>

                <virt>

                <![CDATA[1]]>

                </virt>

                </SubSegment>

        </Structure>

The first line <Index index="1000"> represents the number of the index or the address. This number is in hex format but has no hexadecimal prefix (“0x”). The first line of the description template is then:

<Index index="${index.address.@hex}">.

The second line <Name> <![CDATA[p301_device_type]]> </Name> represents the name in C code of the index. The <![CDATA[…]]> will be filtered out so the second line in the template is:

<Name>${index.CName}</Name> followed by:

<EDS_Name>${index.name}</EDS_Name>

<MandatoryFlag>${index.mandatoryFlag}</MandatoryFlag>

<Description>${index.description}</Description>

<ObjectCode>${index.objectCode}</ObjectCode>

The next line of the example file is now: <MaxSubIndices> <![CDATA[1]]> </MaxSubIndices>. This value is not represented in any attribute of the index from the Communication Creator, i.e. there is no specifier for this value. Therefore there is no line for the description template.

The next line is again a hex formatted value without a prefix – the data type number: <DataType> <![CDATA[0007]]> </DataType>. The corresponding line for the description template will be:

<DataType>${index.dataType.address.@hex}</DataType>

The next lines for the description template will be

<Opt_CreateExternal>${index.createExtern}</Opt_CreateExternal>

<Opt_CreateTypeDef>${index.createTypedef}</Opt_CreateTypeDef>

<Opt_CreateVariable>${index.createVariable}</Opt_CreateVariable>

<Opt_VirtualObject>${index.virtualObject}</Opt_VirtualObject>

Now the sub-index number starts: <SubIndex subindex="000">. The line for the description template is:

<SubIndex subindex="${subindex.address}">

and is followed by:

<EDS_Name>${subindex.name}</EDS_Name>

<DataType>${subindex.dataType.address.@hex}</DataType>

<Size>${subindex.size}</Size>

<LowerLimit>${subindex.lowerLimit.@hex}</LowerLimit>

<UpperLimit>${subindex.upperLimit.@hex}</UpperLimit>

<Value>${subindex.defaultValue.@hex}</Value>

<Unit>${subindex.unit}</Unit>

<AccessType active="1">${subindex.accessPreOp}</AccessType>

<PDO_Mapping>${subindex.pdoAccess}</PDO_Mapping>

<DefaultEDS>${subindex.defaultInESI}</DefaultEDS>

<LimitEDS>${subindex.limitsInESI}</LimitEDS>

The next lines of the example data file contain the sub-segment structure. The first useable line that has the sub-segment number attribute is: <SubSegment nr="6000">. The next line for the description template is:

<SubSegment nr="${subsegment.address.@hex}">

and the following additional description template lines will have the attributes of the sub-segment:

<StartIndex>${subsegment.startIndex.@hex}</StartIndex>

<EndIndex>${subsegment.endIndex.@hex}</EndIndex>

<Name>${subsegment.name}</Name>

<VarName>${subsegment.CName}</VarName>

<virt>${subsegment.virtualObject}</virt>

 Writing Description templates for export

The export description templates are written in FreeMarker Template Language (FTL). FreeMarker is a template engine and in this chapter general functions are described (see Table 37). For more detailed information please look at the FreeMarker user manual at:

• https://freemarker.apache.org/

• https://freemarker.apache.org/docs/ref_builtins_string.html

A list of all additional specifiers, variables and lists can be found in Table 44 and Table 45

Templates for formatting functions for defaultValue and limits of a subindex can be found at: <ToolDirectory>/plugins/de.port.dsntool.ui.cclink.helppages/DescriptionTemplates/functionTemplates.txt

Table 37: Examples using FTL