CANopen Feature

Introduction

To start using port CANopen Library with own application one has to:

• Define Software Model;

• Create Application Code;

• Create Device Description (EDS/XDD file);

To assist its customers with getting started quickly, port provides Communication Creator utility application. Industrial Communication Creator for CANopen comes with easy to use forms and wizards, which make it easier to configure CANopen Library 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 and XDD 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.

CANopen Projects

port CANopen Library 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 CANopen  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 CANopen 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 "CANopen (full version)".

In Package Explorer View, CANopen projects are shown with green CO icon ( ) Sonderzeichen fehlt . Project node contains up to five project contents, as shown on Figure 178. Meaning of these sub-nodes will be explained in Code Generation chapter.

Open

Figure 178: Example CANopen project entry in Package Explorer view

Creating New CANopen project

The creation of new CANopen 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 CANopen Project () - see Figure 179 and click OK.

Open

Figure 179: Contents of Select Wizard dialog with CANopen 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 180. 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 180: 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 181.

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

• Software model configuration file cal_conf.h, co_init.c;

• Object dictionary files objects.h, objects.c, co_odDefines.h;

The page is presented on Figure 182. File name and path of EDS/XDD files are selected in line-specific EDS/XDD settings. As initial setup, wizard will suggest to locate these files in the same directory as project file.

Figure 182: 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 183.

Figure 183: 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 184. In this case user has to change specified path and try again.

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

Figure 185: 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 (cal_conf.h, co_init.c, objects.h, objects.c, co_odDefines.h, EDS/XDD) will be created later. The new project will be opened in new editor tab that appears on top of application window.

Validation

CANopen 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 186.

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

CANopen 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 CANopen project is presented on Figure 187. 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 five groups:

Project Settings

General Settings of CANopen Library configuration.

Project Preferences

Settings for C Code generation and extended interface settings.

Tools

Utility functions for Import/Export.

Hardware Configurations

Settings related to creation of Hardware Configurations.

Line Settings and Object Dictionary

Structure of objects of which application's software model is made plus line-dependent settings.

Figure 187: Top Page for CANopen project

Software Model Pages

Modularity of CANopen Library is represented in software model. The software model is separated into Segments and line-dependent EDS/XDD and Standard settings. 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, Device Profile Segment, Dynamic Variables Segment and EDS/XDD and Standard Settings. Be aware that number and names of blocks depend on your current project configuration.

Code Preview

Editor for CANopen projects has five additional tabs beside main Design Tab. All of these are used for preview of generated code.

Figure 188: Tabs for CANopen editor

Sonderzeichen fehlen

  cal_conf.h ; objects.h ; co_odDefines.h

Preview of C header file for CANopen Library configuration.

  co_init.c ; objects.c

Preview of C code file where software model is defined for use in CANopen Library.

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.

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 CANopen Communication Creator generates several files to be used within the port CANopen Library. 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:

1. iccCmd <singleOption>

2. iccCmd <option 0> ... <option n> <iccProjectFile>

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

Case 2 can consist of multiple options (see Table 39) 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 EDS checker, make all. The output of the command is written into the information file "errorProtocol.txt".

Generated files

cal_conf.h

cal_conf.h file is a C header file which contains defines needed for configuration of CANopen Library.

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

Contents of cal_conf.h file depend on what Hardware Configuration and Project settings and Dictionary Objects are defined. You can get more information about Hardware Configurations in Hardware Configurations chapter.

co_init.c

co_init.c file is a C code file which contains functions needed for initialization of CANopen Library.

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

objects.h

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

objects.c

objects.c file is a C code file which contains the code for the object dictionary.

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

co_odDefines.h

co_odDefines.h file is a C header file which contains additional defines concerning the object dictionary which can be used by the user code.

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

EDS and XDD

Electronic Data Sheet (EDS) and XML-based device description (XDD) contains descriptive and communication information of the device.

EDS and XDD files were generated for every line and have by default a file name which consist of the project name followed by the line number (e.g. myProject_line0.eds, myProject_line1.xdd). The path can be seen on EDS/XDD Settings block. User can change this location using Browse button ( ) at the setting.

Contents of EDS/XDD files depend on Software Model and EDS/XDD information and Settings.

Documentation files

The user can specify files containing user-specific information about the objects in the object dictionary. These files are generated by the Industrial Communication Creator by each generation. The files can have any ASCII-based format, e.g. .html, .txt or .phy..

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

Figure 189: overview of all created documents by Communication Creator

Common CANopen 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 21 the list of common problem reports concerning CANopen 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 /CiA-301/ and /CiA-302/ and for safety-related communication according to /CiA-304/.

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

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

Table 21: overview about profile databases

The following sub-chapters give additional information to some profile database files.

profile304_july_2010. iccprof

The profile database for the CiA-304 provides the profile-specific objects for

• the SRDO service and

• the GFC service.

Some objects use different default values depending on the information direction. The default values of these objects are set to invalid, most on value 0.

profile443_v2_1_0. iccprof

The profile database for the CiA-443 provides the profile-specific data types and objects with except for object 0x6010 (p443_cpu_clock_time_and_date).

The profile-specific data types are dependent on the number of channels or valves which can be different for various objects. The Communication Creator generates special C structures for the sub-indices which are depending on channels or valves to provide an effective access on the objects in C code. All structure definitions are stored in the generated file objects.h.

Example: data type 0x0082 (12-CHANNEL METAL LOSS)

The data type is compound by general and channel-dependent sub-indices. The following C structure for the channel-dependent sub-indices is generated:

typedef struct {

            UNSIGNED8 status;                   /**< channel status */

} P443_CHANNEL_METAL_LOSS_T;

The C structure for data type 0082 with 2 channels is: typedef struct {

P443_CHANNEL_METAL_LOSS_T chan[2]; /**< channels */

} P443_12_CHANNEL_METAL_LOSS_2_T;

The condition for the generation of channel-dependent data types is the setting of the profile number in object 0x1000 (p301_device_type) or in object 0x67FF (single_device_type) for multiple logical devices.

The names of the C structure elements are fixed.

The C names of the P443 objects for the main-index have to be modified by a repeated import without usage of sub-segmentation.

Limitations:

• object 0x6010 (p443_cpu_clock_time_and_date) is not supported because the Industrial Communication Creator does not provide the data type TIME_OF_DAY

• the profile database P443 is not available for non-global variables

Convert old project files

The Industrial Communication Creator with CANopen Feature is the replacement for the previous CANopen Communication Creator. The life-span for the old one is to be ended and to make the transition period as easy as possible users can convert their old project files (*.can) to the new one: *.iccproj.

This can be done at File > Convert (Figure 190) which opens the Convert-Dialog where you can select a *.can file and the resulting *.iccproj file. The converted project will be automatically opened when the checkbox is selected.

Figure 190: Convert .can files

Hardware Configurations and plugin installation

Hardware configurations consist of CPU, Compiler, CAN configuration and Code Maturity Level Settings. The selectable CPUs, Compiler and CAN configuration Settings depend on the installed Driver-Packages that are exclusively delivered by port.

A warning dialog is shown to the user when one or more plugins are missing for the opened project file.

The installation can be done within the menu: Help > Install Plugins. A list of every currently installed HW-Plugins is shown, too (see Figure 191). Furthermore single plugins can be uninstalled by clicking on the “uninstall”-button of the adequate plugin or all plugins can be uninstalled by one click. An example plugin (generic driver package) can be found at: your/Install/Directory/extern plugins.

Note: When installing the tool to a directory where you have no write permissions, you have to start the Communication Creator with admin rights to ensure the install of plugins works properly.

Figure 191: Install Driver-Packages

Driver-Packages are zip-archives that contain several HW-Plugins (.jar files). They have to be extracted first from the archive and can be installed by selecting the folder or a single plugin file. When installing by folder all contained HW-Plugins with their newest version in this folder and its sub-directives will be installed recursively. After every install/uninstall of a plugin the Communication Creator must be restarted to apply changes.

The Communication Creator provides the possibility to configure more than one hardware configuration for the field device. This can be useful when different hardware environments are used during development, test and production for instance. But only one hardware configuration can be active. The hardware configuration is generated to the configuration file cal_conf.h and is used by the CANopen driver. It is configurable to generate the C code settings for all hardware configurations or only for the active hardware configuration about the editor-view Generation-block > C Code > Generate only active hardware configuration. In the case that the C code settings for all hardware configurations are generated only the settings for the active hardware configuration is valid during compilation of the application code. A field device can work in different CANopen networks at the same time. Such multiline devices can be gateways for instance. Each network line needs their own CAN configuration while the CPU and compiler settings are valid for the complete field device. For multi-line devices each Hardware Configuration has to include CAN settings for each line. CAN Settings 0 refers to Line 0 etc.

The CANopen Software Model

Obligatory step of CANopen Library 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 - 127 CANopen devices /CiA-301/. Each CANopen device is connected with one CANopen network. That means each CANopen device is assigned to another CAN line. If the field device only supports 1 CANopen device, the field device is a single-line device. In the other case the field device must be a multi-line device. Each CANopen device can have 1-8 logical devices (Figure 192).

Figure 192: Device structure

Line

The Line item in the project tree represents a network and includes line-dependent settings and 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 - 0x9FFF

• Dynamic Variables Segment: contains standard network variables in the index range 0xA000 - 0xAFFF

• Reserved Area: the index range 0xB000 - 0xFFFF are reserved, system variables are not supported

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 22: 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.

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 sub-segment.

• 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 CANopen Library can be found in the online help of the Communication Creator. Please open the help system via menu “Help” à “Help contents”. Then select “port CANopen 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 CAN 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:

• determine the number of Lines and add further Lines if desired

• install the necessary Hardware Plugin

• configuration of project settings

• configure Hardware Configurations

• configure the Line settings and design and modify objects configuration of standard and service settings

• generation of outputs

Beginning a project

A project is created by the menu File > New.

Existing projects are opened by the menu File > Open… . Each CAN line can be preset with data from a profile database (.iccprof), an EDS or XDD or an user-defined object dictionary file.

Hardware configuration

At first the target hardware has to be configured. The most important decision is to choose a CPU resp. an operating system.

Default configurations for the supported platforms can be found at the s1-example of the CANopen Library. These configuration files (conf_xxxx.h) can be imported via "Import".

Figure 193: hardware configuration part of the project tree

If the CPU is set, the other CPU settings are set to CPU-specific default values. These default values are suitable in the majority of cases. At Compiler Settings the used compiler can be selected. For each line the CAN-controller or the PC-CAN-Interface must be configured. This can be done at CAN Settings. There the CAN controller family must be chosen at first and then the particular CAN controller type can be set. Detailed information about each attribute at this form can be found at the context help.

If the application shall be used on different hardware platforms, more than one hardware configuration can be created. If no configuration is marked as active, the define CONFIG_USE_TARGET_x must be set to 1 in the Makefile or in the compiler project. 

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 – 0x9FFF for standardized device-profile objects (device variables). There are two ways for the definition:

• loading from a profile database,

• user-defined object dictionary file and

• creation by hand

Certain objects can be selected by means of their index from a profile database. Databases for the standardized CANopen 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.

Figure 194: import mask for profiles

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 11.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 objects.c, in the EDS files, in the documentation and also in the object tree the %-variables are replaced by their current values.

Table 23: %-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 an main-index.

Examples for the usage of these %-variables can be found at the SDO or PDO 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

Communication services

The CANopen protocol specifies various communication services. The most communication services are optional. The CANopen Library can be optimized, so that only the code for the required CANopen services is implemented.

Communication services shall be implemented about the project tree by Line / Communication Segment-block / Add New Communication Service.

Figure 195: dialog: " Add New Communication Service"

The dialog allows to configure the selected communication service among other things the implementation of optional communication objects. During creation of the communication service the CANopen Communication Creator makes all necessary settings and loads all necessary communication objects from the profile database of the newest available version.

Communication objects can be also added:

• by loading from profile databases about the Import-block or

• Line / Communication Segment-block / Add new Index,

• by import from csv-file (see chapter 11.15.1) or

• by import from EDS/XDD file or

• by import from user-defined documentation file.

Please note that the CANopen Communication Creator only creates the objects in these cases and does not create the communication service, i.e. if the communication service was not created before it is possible that compiler defines for the CANopen Library are not set correctly.

Objects according to older standard versions can be loaded from the profile databases suitable to the desired standard version. If there is no suitable profile database available, please contact port.

Special cases

This chapter describes some special cases for object dictionary generation. The CANopen Communication Creator supports the generation of object dictionary implementations for the ’single’-line release and the ’multiple’-line release of the CANopen library of port. The following special cases are used for the optimization of the implementation.

Range checking for variables

Entries are set up as a default during generation of the object dictionary for minimum and maximum values. These limit values are used of the CANopen library by port during SDO transfer for limit supervision. The limit monitoring can be switched on/off via Services / SDO / checkbox "Check object limits for SDO transfer". This setting activates or deactivates the compiler define CONFIG_LIMITS_CHECK.

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-specific objects. 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.

Predefined symbols

Predefined preprocessor symbols like __DATE__, __TIME__, __FILE__ etc. can be used within strings, but you have to put quotes around.

Limitations

The optimization configured at the optimization tab of an index can only be used outside of sub-segments. The reason for this is, that sub-segments are stored in C-structures and it is not possible to assign a storage class to a single member of a structure.

Complex data types

The standard /CiA_301/ 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 Industrial Communication Creator. Data types are considered line-dependent, i.e. in order to specify objects of complex data types the complex data type must be available on the same line. The following steps are necessary to create a new data type:

1. select

Line > 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> or Finish

→ an entry for the new data type is in the project tree, see Line > 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.

During the generation process the Industrial Communication Creator generates a struct definition for the data type and stores the struct definition in objects.h. In multi-line projects identical data type definitions on various lines are summed up to one struct definition.

Object-specific callback functions

Object-specific callback functions allow to execute application-specific operations during reading and/or writing of objects via SDO, PDO and/or MPDO.

Figure 196: dialog for Project Settings / Objects

The usage of the object-specific callback functions requires the following steps:

• Use CANopen Library V4.5 and higher and select the stack version 4.5.x within creating a new project. This makes the object-specific callback functions available.

• The object-specific callback functions can be activated or deactivated about Project Settings / Objects / Enable object-specific callback functions.

• If object-specific callback functions are activated generally, it is possible to switch on/off the object-specific callback functions service related according to the following criteria, see Figure 196:

o   access to the object via SDO, PDO and/or MPDO,

o   read and/or write access to the object and

o   before and/or after changing the value of the object in the object dictionary.

o   The extern declaration for the object-specific callback functions can be located in the generated or application software. This can be configured about Project Settings / Objects / Generate extern declaration for all object-specific functions.

o   For each object one object-specific callback function can be specified about object Main-Index / C Callback, see Figure 197. This function is called for all accesses to the object configured in Project Settings / Objects. The name of the object-specific callback function is application-specific. But the function prototype for the object-specific callback function is fixed as follow:

RET_T <callback_name> (UNSIGNED16 index, UNSIGNED8 sub,

CO_OBJ_CB_TYPE_T reason CO_COMMA_LINE_DECL);

It is allowed to specify the same object-specific callback function for different objects.

Figure 197: dialog for object Main-Index / C Callback

Each setting in the Industrial Communication Creator is described in the online help about <F1> which opens automatically in the Help-view by hovering over the setting. The flow of calling of the object-specific callback functions is documented in the user manual of the CANopen Library.

Project-Merge

Project-Merge provides functions to visualize and modify differences between different CANopen Communication Creator projects. The Project-Merge main window can be opened (Figure 198) via the “Open Project-Merge”-button in the Miscellaneous-View.

Figure 198: Project-Merge main window

CANopen Projects can be opened via double-click into the path-field or via shortcut: Ctrl+L for the left side and Ctrl+R for the right side.

Figure 199: Project-Merge main window displaying two projects

Project View

The project view shows different settings, sub-segments, objects and sub-indices with different colors. By using the “Merge” function in the tool bar these elements can be copied from one project into the other one. Via the tool bar save-icon the modified projects can be saved to disk but they have to be closed first in the CANopen Communication Creator. The menu entry “Options” opens a dialog where several settings can be configured. These include the attributes to be compared or merged and further options.

Detail View

Figure 200: Project-Merge diff window displaying differences of two sub-indices

The detail view displays differences of global settings, indices and sub-indices. Attributes of indices and sub-indices are read only within this view and can only modified by the “Merge” tool bar.

Import

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

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

Figure 201: Import GUI

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

Table 24: 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 – 0x025F)

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

• object-specific options for the generation of the EDS/XDD file

• 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 202). 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 42.

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

Figure 202: 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 – 0x025F)

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

• object-specific options for the generation of the EDS/XDD file

• 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 203. The ftl-specifier is a placeholder that will be replaced with its current value while generating (see chapter 11.17.1 and 11.17.2 for more examples).

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

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

          </CANopenObject>

Figure 203: 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 “<DesingTool root directory>/plugins/de.port.dsntool.ui.canopen.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 42 and an example on how to write description templates for import is described in chapter 11.17.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

2. 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}” (e.g. datatype or address property of indices in an XDD file)

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

Export

Export profiles

The export of profile databases (.iccprof) can be done via the export documents GUI (opened by Export documents block) 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 204).

Figure 204: 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 205). 

Figure 205: 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 206).

Figure 206: Content GUI of one exported document

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

• Hardware Configurations

• 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 doc”-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)

• Hardware Configuration (.iccconf)

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.canopen.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 11.17.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 42

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

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:

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

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

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

and is followed by:

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:

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. 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 42 and Table 43

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