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.

Open

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.

Open

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.

Open

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.

Open

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.

Open

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.

Open

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.

Open

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.

Open

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.

Open

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

Open

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.

Open

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.

Open

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

Open

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