Basic concepts

This chapter describes the usage of the Communication Creator platform which applies to all available protocol versions.

Introduction

Using Industrial Communication Creator is working with projects. Your Communication Creator product can support one or more project types, depending on number of features installed. If in doubt, you can check what project types are supported by opening About dialog from Help menu.

Project configuration is stored in project file on local file system. User is asked to specify location of this file during project creation. For changes not to be lost, project needs to be saved to file after modifications are made.

Industrial Communication Creator application window is separated into parts, with movable borders and changeable layout. The placement of application parts is called perspective. Changing perspective can be helpful to adapt tool to screen size and user preferences.

Each opened project can be displayed in its own editor tab located (by default) in center of application window. By interacting with editor, user can browse through project and modify its configuration. Typically configuration settings are laid out in form and use one of few basic input widgets.

If problems are detected by Industrial Communication Creator application, it will attempt to collect information about them and present it in user friendly format. User is then able to diagnose the problem and resolve it using this documentation as reference.

Problems may arise if application is unable to access its resources or when project file is corrupted. Problem handling system also covers project type specific checks: correctness of project configuration, setting contradictions etc.

Menus

The Main Menu

This chapter describes main menu items of Industrial Communication Creator application. Main menu is positioned on top of Communication Creator's main window. It is accessible using mouse or keyboard.

When left Alt key is pressed, menu control becomes focused and underscores appear on menu labels – see Figure 6. Underscores show which keyboard key to press to select menu item. For example to execute menu action New, one can press: Alt, f, n.

Open

Figure 6: Main menu with key selectors

Some commands available as menu items are also executable using direct keyboard shortcuts. For example, user can undo last modification done in currently focused editor by pressing Ctrl+z. If menu command has key shortcut, it will be displayed next to its menu label.

Not all menu items are available all the time. Depending on application state (active application parts, selected objects, etc.), some items may be grayed-out and not available for selection in given moment.

The File Menu

File menu contains main application actions and basic project management. Short information about each of the items is collected in the table below:

The Edit Menu

Edit menu contains actions for editing project data. Short information about each of the items is collected in the table below:

Table 9: Edit menu options

The Window Menu

Window menu contains actions for changing application perspective and to reveal preferences dialog. Short information about each of the items is collected in the table below.

Table 10: Window menu options

The Help Menu

Help menu contains actions related to user assistance and product information. Short information about each of the items is collected in the table below:

Table 11: Help menu options

Application Parts

This chapter describes the different elements of the Communication Creator main window.

Application Perspective

Application window of Industrial Communication Creator is divided into several application parts:

• Package Explorer view

• Outline view

• Help view

• Tasks view

• Problems view

• Editor

Layout of these parts in application window is called perspective.

Perspective can be changed at runtime for better ergonomics. For example, selected part can be maximized to fill the window contents. This can be achieved by clicking the button next to part label - see Figure 7,   . Action can be undone by clicking the same button again.

label - see Figure 7,   . Action can be undone by clicking the same button again.

Open

Figure 7: Application part label

Other options for modifying perspective include: hiding (Figure 7, ) or closing (Figure 7, ) selected parts. One can also swap positions of parts by drag-and-dropping the part label, or change size of part by dragging part border.

All changes to perspective are persisted when application is closed. To restore default layout, use menu item „Window > Reset Perspective”.

Package Explorer

Package Explorer shows opened projects and their contents. When application is opened with no projects, the part looks similar to Figure 8. New and Open are shortcuts for creating new projects and opening existing ones.

Figure 8: Empty Package Explorer

When one or more projects are opened, Package Explorer displays them as tree nodes - see Figure 9. The icon is specific to project type, with the exception that yellow folder icon ( ) represents project not yet loaded. Depending on project type, some projects can have contents (sub-nodes).

Figure 9: Package Explorer with opened projects

Double click on node will cause project or project content to be opened in the editor. Right click on project node opens context menu. There are following menu items available.

Table 12: Project node context menu options

If Package Explorer is hidden, it can be restored using main menu item Show Package Explorer View.

Outline

Outline view is, by default, positioned on the right side of application window. This application part presents hierarchy of data opened in currently focused editor. By selecting tree nodes on the Outline part, user can cause relevant page to be revealed in the editor.

Figure 10: Outline View with example contents

Outline context menu available through right mouse button, allows to perform actions on selected tree node. Actions are not available for every node.

Table 13: Outline context menu options

If Outline view is hidden, it can be restored using main menu item Show Outline View.

Help

Help view is, by default, positioned on the middle right of the application window. This application part shows automatically the help information after the mouse cursor enters a widget in the Editor View without clicking on the widget e.g. a text input field or a spinner.

Figure 11: Help View with example contents

Tasks

Tasks view is, by default, positioned on the bottom of application window. This application part contains table with all tasks associated with currently opened projects.

Figure 12: Tasks View with example contents

Task View application part filled with example task entries can be seen on Figure 12. Numbers on top of table refer to numbers of items shown and - in the parenthesis number of all items (including hidden ones). Finished tasks are either hidden (by default) or grayed out.

The table has three columns:

• Description: Describes actions necessary to complete task; if too long to read, use context menu to display task details;

• Project: Name of project;

• Location: Name of root element inside project that needs to be modified for task to be completed.

Context menu, available through right mouse button, has following items:

Table 14:  Task View context menu options

If Tasks view is hidden, it can be restored using main menu item Show Tasks View.

Problems

Problems view is, by default positioned on the bottom of application window. This application part contains table with most recent problems identified during application life cycle.

Figure 13: Problem View with example contents

Problems View can be seen on Figure 13. The problems table has three columns:

• Description: Information about problem; color of icon depends on severity: red - error, yellow - warning, blue - information;

• Project: Name of project, if problem can be linked to single project;

• Location: Location inside project where problem was identified;

Context menu, available through right mouse button, has following items:

Table 15: Problems table context menu options

Editor

Editor is the most important application part of Industrial Communication Creator and the only one that can have multiple instances in one application window - one for each project. The purpose of editor is to present user with convenient tools to modify project.

Tracking changes

Editor keeps track on project data modifications. When changes are made through editor, that are not yet saved to project file, asterisk appears next to editor label (Figure 14).

Figure 14: Asterisk on editor label signifies unsaved changes

Because editor remembers subsequent changes done to data, there is possibility to undo and re-do them.

Editor elements

The way project is presented in the editor differs depending on project type and is described in the User Guide for appropriate feature. Nevertheless, basic elements of editor are shared. These elements can be seen on Figure 15.

Figure 15: Basic elements of Editor

Editor has multi-tabbed design. Design Tab is the main tab, present in every editor. This tab is used to browse and modify the data. Other than that, depending on project type, editors can have additional tabs, for example for viewing generated code.

Design Tab

On top of Design Tab there is a small toolbar mostly for navigation purposes. The rest of tab is taken by editor page - the representation of some aspect of the edited project. Toolbar is presented in Figure 16.

Figure 16: Edit toolbar

The following elements can be found on the toolbar:

• Go Back: Opens previously visited editor page;

• Go Forward: Opens editor page visited before using Go Back tool;

• Go Home: Opens top page for given project;

• Save/Generate: Saves changes to project file and generate all files; equivalent to main menu's Save item

• Help: Opens Help Dialog; if possible uses dialog to reveal help page most appropriate to current editor page.

Editor works in tandem with Outline view. Outline is used to show the hierarchy of project objects and quickly navigate through them - clicking tree-node in Outline results in opening editor page for this object in editor's Design Tab.

There are three basic types of editor pages. Starting page for projects (also known as Top page), uses graphical representation of most important elements of project. Sets of configuration elements are represented as form pages, similar to HTML forms. Hierarchical objects are represented by pages with additional tree for easy navigation through their children.

Top page

Top page for project uses block diagram to present user with key elements of project configuration. This is initial page, displayed after project is created/opened. You can quickly return to this page by using Go Home ( ) button on editor toolbar. Exact looks of the page depends on your project structure - defined by project type, but it is similar to that shown on Figure 17.

Figure 17: Top view page for project - an example

Blocks (in burgundy-red) are hyper-links to other editor pages. As a visual hint, little decoration icons can be rendered on top of these blocks. Below are their meanings; they are listed in decreasing priority:

Sonderzeichen fehlen !!!!!!

• Problems detected for objects inside this block.

• There are unfinished tasks associated with objects inside this block.

• Neither problems, nor unfinished tasks found for this element.

Form page

Using editor's design tab, one can display several configuration pages for project. They can be accessed by clicking a block on Top page, selecting Outline node or double clicking on Task. Remember that you can always go back to previously visited location using Go Back ( ) tool.

Most of these pages use forms, similar to these on WWW pages. See Figure 18 for reference - each configuration setting is displayed with short name on the left and interactive widget on the right.

Figure 18: Editor form page - an example

Please see the next chapter for detailed description of commonly used widgets and other editing tips. For specific information about settings and objects available in your project, please refer to user guide appropriate for your project type.

Form page with tree

You can also encounter editor pages that have tree widget nested inside. They are used for objects that have complicated hierarchy and are otherwise not different from ordinary form pages.

Figure 19: Editor page with tree - an example

Use the tree to access objects hierarchically linked to currently displayed - click on the node to fill editor form with appropriate configuration entries.

 Code Preview Tab

Apart from Design Tab, editor instance can have one or more code-preview tabs. You can select one of them by clicking tab label at the bottom of editor area (see Figure 19). Code preview tab allows for quick preview of artifacts generated by Industrial Communication Creator from currently edited project. They also control location of generated code in file system.

Figure 20: Elements of code preview tab

You can see elements of code preview tab on Figure 20. Descriptions follow below:

• Preview area: Most of space in the tab is taken for text field where generated code is displayed.

• "Save" button: Saves contents of preview area to file.

• "auto-save" check box: If checked, code will be regenerated and saved to file each time parent project is saved. If unchecked, user has to do it manually by clicking "Save" button.

• Save Location: Text field in the middle of toolbar displays currently specified location where code is saved.

• "Browse" button: Allows to change location where code shall be saved.

 Editing Tools

This chapter explains in detail types of configuration widgets used for different project settings. For basic information about editor, please see Editor chapter first.

Configuration widgets

When browsing through Industrial Communication Creator project structure using editor, you will encounter different sets of configuration options, represented by input fields: text fields, lists, check-boxes etc. Each of these widgets was designed to be intuitive in use and to ensure proper format of input.

Table 16: Checkbox example

Table 17: Numeric setting example

Table 18: Hexadecimal setting example

Table 19: Text input example

Table 20: Drop-down list example

Input checking

Before new value is accepted, it must pass quick validation test. For example most numeric settings only accept values which belong to certain range. The test is performed immediately after user modifies input. In case of failure user gets visual feedback - see Figure 21.

Figure 21: Error mark displayed next to incorrectly modified input

Appearance of error mark next to modified input means that new value is incorrect and not accepted.

Assistance Options

Effort was made to make editing Industrial Communication Creator projects as intuitive and self-explanatory as possible. Nevertheless, it is still possible that users will not immediately recognize meaning of some setting and how to change its value. For this purpose user assistance system was connected to each configuration entry.

In case the name of the setting is not descriptive enough, hover the mouse cursor over the help icon ( ) next to input in question to get a longer description in form of tool-tip message (Figure 22).

Figure 22: Mouse-over text contains more descriptive information about the project entry

If this short information is still not sufficient, click on the help icon. This will open user guide for your project type and reveal page most relevant to the setting in question.

Configuring your project

Industrial Communication Creator is designed for working with different project types using the same set of convenient tools and user assistance system. The general instructions about editing tools were presented above. For more specific instructions about meaning and significance of settings, refer to user guide appropriate for your project type.

Projects 

Project Type

Industrial Communication Creator has a modular architecture, that allows using the same set of tools for editing different project types. You can check what project types are supported by given Communication Creator application by opening About dialog - see Figure 23.

Figure 23: "About" dialog with supported project types

Support for project type, comes with Wizard for creating new projects. When new project is to be created, user will be asked to choose wizard for the desired project type. The question will be skipped if there is only one wizard available.

Project properties

You can see list of opened projects using Package Explorer. If hidden, restore Package Explorer using menu item “Show Package Explorer”. The content of Package Explorer View includes all projects created and loaded from disk during application runtime, which have not been explicitly closed.

Figure 24: Three projects visible in Packet Explorer

On Figure 24 you can see example contents of Package Explorer View: three project entries. Each project entry is labeled with project name, which is equivalent to its file name. The same project name will be displayed on associated editor label. Icon entry is characteristic to project type.

A yellow folder ( ) is a generic icon used in following circumstances:

• Project is not loaded yet;

• Project type is not supported by the tool;

• Project failed to load (problem with file access or file corrupted);

If application is launched with many projects from previous session, not all of them will be loaded from disk at the same time to save resources.

If project fails to load (second and third case) user can try to diagnose the situation by checking reported problems.

You can open editor for project by double clicking its entry in Package Explorer view.

You can remove project entry from view by right clicking it and selecting Close Project from context menu. The same effect can be achieved using main menu. Closing the project doesn't delete its project file, so the project may be opened for editing later. The application will warn about any unsaved changes. It is recommended to close projects that are no longer in active use to save program resources and remove entries associated with project from Tasks and Problems Views.

Figure 25: Project Properties dialog

Figure 25 shows an example Project Properties dialog. You can open this dialog by right clicking on selected project entry in Package Explorer and selecting Properties from menu. The dialog displays:

• Project name - equivalent to file name;

• Location of project file in file system;

• Type of project;

• Stack Version.

Validation

Project validation is a process of checking correctness of project data. Validation is supposed to detect problems with project structure that can happen when project file becomes corrupt, as well as smaller issues e.g. when two setting values contradict each other.

Project validation is performed in following circumstances:

• On project opening: right after project file is loaded from the disk;

• On project save: right before changes are saved to disk;

• On user request.

Validation may be requested by right clicking project entry in Package Explorer and selecting Validate from the menu.

At the start, validation process clears from memory all previously detected problems for project about to be validated. This allows to eliminate from the view, problems that were resolved since previous validation run. After validation completes, you can review all detected problems using Problems View. It can be revealed using Show Problems View menu item.

Automatic validation before project save will interrupt the process, if problems are detected. User will be asked to make decision whether to continue saving invalid project data - see Figure 26. It is recommended to cancel save, check out reported problems, fix them if possible and try again. Users

shall be aware, that attempting to use such corrupted project to generate code may result in incorrect result.

Figure 26: Tool asks for confirmation if problems were detected during project saves

For information about problem handling, and most common problems and solutions, see dedicated chapter. Please, also refer to user guide appropriate to project type.

Tasks

Introduction

Industrial Communication Creator user assistance system comes with task list functionality. Task list is a list of actions that need to be performed to properly configure project. The tool is able to check the project data against the task list and identify which tasks are completed and which remain open. Each project type comes with separate task list.

Tasks application part is used to view all tasks for currently loaded projects. It can be revealed using Show Tasks View menu item.

Figure 27: Example contents of Tasks View

On Figure 27, example contents of Tasks View are presented. The entries are grouped by project they apply to. Each task entry can be viewed using separate dialog, which may be more convenient way, especially if task description is long. To display task details right click on task entry and select Details from menu.

Figure 28: Task Details dialog for example task

Example task opened in Task Details dialog can be seen on Figure 28. Contents include:

• Project name: Name of project associated with this task;

• Path: Location of project file name in the file system;

• Description: Description of task; this field gives information about how to complete task;

• Location: Location of object associated with the task inside project; this object will be opened when task entry is double-clicked.

• Completed: If the box is checked, task is completed; this can be temporarily changed by the user.

Application checks whether tasks are completed automatically when project is first time loaded and after each save. Checking of tasks can also be triggered manually, by right clicking in Tasks View area and selecting Refresh from menu (this checks every displayed task).

Working with Tasks

Reading and completing tasks is a helpful way to properly configure all required aspects of the project. To begin, open Tasks part and scroll to tasks that point to project you are working on. It is usually appropriate to start completing tasks in order they are presented in Tasks View.

First read task description, if description doesn't fit in table view, open details dialog as described above. Double click task entry to open editor page associated with task. When modifications are made, you can re-check tasks using context menu item Refresh, or just save project.

If you want to go back to some finished task, you can use context menu item Show/Hide Completed to reveal all tasks in the table - completed ones will be grayed out. To help with sorting out the tasks, you can also temporarily change task state to be completed/open by using context menu options Set Completed or Details. This change will be overridden, the next time task is checked by the application.

If task description is not sufficient in explaining what shall be done, refer to user guide for given project type. Double click on the task entry and use editor's help tool, to open help page most relevant to topic at hand.

Problem Handling

There are different types of problems one can encounter when working with project. Tool may fail to access project file due to Input/Output error, project file may be corrupted and unable to be read or project configuration may be self-contradicting in a way that can be detected using project validation.

In any case, the effort was made to have tool detect most of these errors, and to keep problem reports for user to explore.

Log file

All error handling information is written to log file right after problem is encountered. This file is not generally thought to be of assistance for normal users due to technical nature of its contents. It may be helpful though, to prepare copy of this file when reporting a problem to port GmbH user support.

Log file is a normal text file located under path:

Users/home/.iccproj/.metadata/.log

Problem types

Problems can be classified depending on their scope and severity.

Problem scope:

• Project specific: These problems are associated with concrete project. That includes errors in saving project file or generating code, problems with project configuration, missing values, etc.

• Global: These are problems that concern application itself. That includes errors in accessing license file or auto-update repository, errors caused by corrupted application files, etc.

Problem severity:

• Errors: Most severe. Reported when due to a problem, requested operation can not be completed. In case of project problems, error means that project is incorrectly configured and is not used to generate code.

• Warnings: Moderately severe. Reported when requested operation was able to continue, but with complications. Warning reports shall be reviewed carefully to check if they do not indicate some larger problem.

• Info: Least severe. Reported for situations that are not likely to be of concern.

Problem properties

Problem reports can be viewed using Problems View. If hidden, it can be revealed using menu item Show Problems View. Figure 29 presents contents of Problems View - the table is filled with example problems of different severity and scope.

Figure 29: Problems View with examples

To better examine selected problem entry, user can open separate dialog with problem details. This can be done by clicking on problem entry in Problems View with right mouse button and selecting Details menu item. Problem-Details dialog opened for example problem entry can be seen on Figure 30.

Figure 30: Problem Details dialog

Contents of Problem Details dialog, from the top:

• Severity: Symbol (depends on your operating system) and label in dialog header indicate problem severity (Error, Warning or Information);

• Affected Project: Only for project-specific problems; name of project in which problem was detected;

• Path: Only for project-specific problems; file-system location of project in which problem was detected;

• Description: Description of the problem;

• Location: Only for project-specific problems; object inside of project for which problem was detected;

Resolving problems

When problems are indicated (or suspected) in project user is working on, there is a chance they can be quickly resolved using assistance from Problems View and Help documentation.

To browse problem reports open Problems View.

It may be helpful to (re)run project validation. This will cause all currently inactive problems associated with project to be removed from view, and problems reported during validation will appear on top of the list.

Open details dialog for reported problems to read description in full. If report contains specific object where problem is located (Location field is not empty), you can try to open it in editor. To do this, double click on problem entry in Problems View.

If solution is not immediately apparent, check if similar problem is described in the next section. If problematic object or setting is identified, use help tool built into editor ( ) to open help page about it. You may also check, if user guide document for your project type has "Common Problems" section.

After modifications were made to resolve issues, you can re-run project validation and whatever action that had caused problem messages to appear in the first place (e.g. code generation). If problem reports won't appear again, the issue was fixed.

Common problems

For a list of common problems and their solutions please see Appendix C – Common Problems.