J1939 Feature

This chapter explains the usage of the J1939 specific features of the Communication Creator.

Introduction

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

• Define Software Model;

• Create Application Code;

To assist its customers with getting started quickly, port provides Communication Creator utility application. Industrial Communication Creator for J1939 comes with easy to use forms and wizards, which make it easier to configure J1939 Library to user needs.

Functionality provided by the tool include

• Generation of library configuration files;

• Generation of software model definition 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.

1.2      J1939 Projects

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

1.2.1     Project Type

User will be able to create and edit J1939 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 "J1939 (full version)".

In Package Explorer View, J1939 projects are shown with a black J icon ( ). Project node contains up to seven project contents, as shown on Figure 268. Meaning of these sub-nodes will be explained in Code Generation chapter.

Figure 268: Example J1939 project entry in Package Explorer view

1.2.2     Creating New J1939 project

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

Figure 269: Contents of Select Wizard dialog with J1939 entry

1.2.3     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 270. 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 270: 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 271.

Figure 271: Warning that specified file already exists

After location of project file is specified, proceed to next page by clicking Next button.

1.2.4     Specify location for generated code

Second wizard page asks user to specify location of six files that will be generated based on project configuration.

• Library configuration file cal_conf.h;

• Software Model configuration files N2KComms.h, N2KComms.c, nmea_conf.h, usr_nmea.c, kvknmsgs.inc, kvsys.h

The page is presented on Figure 272. As initial setup, wizard will suggest to locate these files in the same directory as project file.

Figure 272: 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 273.

Figure 273: Warning that a target file already exists

1.2.5     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 274. In this case user has to change specified path and try again.

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

Figure 275: 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, N2KComms.h, N2KComms.c, nmea_conf.h, usr_nmea.c, kvknmsgs.inc) will be created later. The new project will be opened in new editor tab that appears on top of application window.

1.2.6     Validation

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

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

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

1.3      Editor Extensions

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

Top page for J1939 project is presented on Figure 277. 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 J1939 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.

Software Model

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

Figure 277: Top Page for J1939 project

1.3.2     Software Model Pages

Modularity of J1939 Library is represented in software model. The software model is separated into PGNs. 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 PGNs is available from top page under blocks PGNs. Be aware that number and names of blocks depend on your current project configuration.

Settings reference

A detailed reference of all available settings for port EtherCAT stack can be found in the online help of the Communication Creator. Please open the help system via menu “Help” à “Help contents”. Then select “port EtherCAT Tool User Guide” à “Settings Reference”.

1.3.3     Code Preview

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

Figure 278: Tabs for J1939 editor

  cal_conf.h ; N2KComms.h ; nmea_conf.h ; kvsys.h

Preview of C header file for J1939 Library configuration.

  N2KComms.c ; usr_nmea.c; kvknmsgs.inc

Preview of C code file where software model is defined for use in J1939 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.

1.4      Code Generation

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

1.4.1     CMD generation

It is possible to generate files through CMD commands. The CMD Communication Creator is started via commands with following structure:

a) iccCmd <singleOption>

b)  iccCmd <option 0> ... <option n> <iccProjectFile>

Case a) can only have one option (see Table 42).

Case b) can consist of multiple options (see Table 46) 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 27 for usage of options in commands.

1.4.2     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. make all. The output of the command is written into the information file "errorProtocol.txt".

1.4.3     Generated files

cal_conf.h

cal_conf.h file is a C header file which contains defines needed for configuration of J1939 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 settings are defined. You can get more information about Hardware Configurations in Hardware Configurations chapter.

N2kComms.h

N2KComms.h file is a C header file which contains functions needed for software model of the J1939 Library.

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

N2KComms.c

N2KComms.c file is a C code file which contains functions needed for software model of the J1939 Library.

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

nmea_conf.h

nmea_conf.h file is a C header file which contains defines needed for configuration J1939 Library.

Code can be displayed for inspection using appropriate editor tab. Location where nmea_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 nmea_conf.h file depend on what Project settings and PGN Objects are defined.

usr_nmea.c

usr_nmea.c file is a C code file which contains functions needed for software model of the J1939 Library.

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

kvknmsgs.inc

kvknmsgs.inc file is a C code file which contains functions needed for software model of the J1939 Library.

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

kvsys.h

kvsys.h file is a C code file which defines system wide parameters for the protocol stack.

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

Documentation files

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

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

Figure 279: overview of all created documents by Communication Creator

1.5      Common J1939 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 27 the list of common problem reports concerning J1939 projects, their meanings and solutions can be found.

1.6      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 ISO- and NMEA-PGN objects.

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

Table 39: Profile databases delivered by port

1.7      Hardware Configurations and plugin installation

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

ATTENTION! - At first start of the Communication Creator (e.g. after update of the Communication Creator) user must ensure that all necessary Driver-Packages were installed. Otherwise when a project file contains hardware configurations from plugins that are not installed to the Communication Creator and the project is saved within this state of the tool, then those settings will be lost.

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 installed HW-Plugins is shown, too (see Figure 280). 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 280: 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 a 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 J1939 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.

1.8      Project editing

This chapter describes the working flow for creating and editing projects. The order of the flow is not mandatory, but very useful. The necessary steps are the following:

·       Fill in the identity info with device identification information

·       configuration of the hardware settings

·       definition of device PGNs

o   it is recommended to use all the ISO PGNs

o   use NMEA PGNs for a NMEA2000 device

·       definition of application PGNs and their data direction

·       Fill the created function stubs with application specific data handling

·       generation of outputs

Note: Using the import tool, many PGNs can be imported from a provided CSV file. This will set proper names and length information, though this has to be double checked.

Note: By default the ICC tool overwrites all generated files every time it saves. Using the User Code Protection Marks (see chapter 16.8.3), it is possible to keep the application code.

1.8.1     Beginning a project

A project is created by the menu File > New.

Existing projects are opened by the menu File > Open… . PGNs can be preset with data from a profile or an user-defined PGN file.

1.8.2     Hardware configuration

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

These configuration files (conf_xxxx.h) can be imported via "Import".

Note: User has to rename these files extensions with “.iccconf” to get them imported as a configuration file.

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

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.

1.8.3     User Code Marks

The ICC tool overwrites all generated files every time it saves. It is possible to keep the application code at predefined positions in the generated file. This feature has to be activated via the button: “Project Preferences > Generation > Enable user code marks”. If activated then there will be special marks in the generated files e.g.:

/* ICC_USER_INCLUDES_BEGIN usr_nmea.c */

/* ICC_USER_INCLUDES_END usr_nmea.c */

/* ICC_USER_CODE_BEGIN PROCESS_PGN_59904 */

/* ICC_USER_CODE_END PROCESS_PGN_59904 */

Code that is placed between those marks will be kept for the next generation of the files and will not be overwritten.

1.8.4     Generation of source code

About the “save”-button next to saving the project file all files listed in chapter 16.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.

1.9      Import

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

<toolInstallDirectory>/plugins/de.port.dsntool.ui.j1939.helppages_*/Profiles/

Figure 282: Import GUI

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

Table 40: Supported files/filetypes

1.9.1     csv-Import

The Industrial Communication Creator provides the import of object specifications in the csv-format for PGN objects.

If the object already exists in the Industrial Communication Creator project it is completely substituted by the imported object specification.

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

${pgn.address},${pgn.name},${pgn.description},${pgn.multipacket},…

Figure 283: 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 pgn. 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.

1.9.2     Import with description templates

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

If the object already exists in the Industrial Communication Creator project it is completely substituted by the imported object specification.

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

          <PgnObject pgn="${pgn.address.@hex}" name="${pgn.name}"  … >

          </PgnObject>

Figure 284: Example of description template for import userdefined .xml 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.

All supported description template specifiers for import are listed in Table 54 and an example on how to write description templates for import is described in chapter 16.11.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 PGN. This has to be always the first property for every object

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

1.10  Export

1.10.1 Export profiles

The export of PGN profiles (.iccprof) can be done via the export documents GUI by specifying a start and end address (see Figure 285). A profile contains only PGNs in the selected range and can be used e.g. as a database.

Figure 285: Export PGN profiles GUI

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

Figure 286: 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 287).

Figure 287: Content GUI of one exported document

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

·       Hardware Configurations

·       PGNs

·       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:

·       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.ethercat.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 16.11.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

1.11  Use cases

1.11.1 Writing Description templates for import

The description template for importing a user-defined file containing PGNs has to consist of one of each of those objects while the data values will be replaced by specifiers. A list of all supported specifiers can be found in Table 54

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

    <Pgn pgn="1000">

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

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

            <Multipacket> <![CDATA[true]]> </Multipacket>

            <Length> <![CDATA[10]]> </Length>

    </Pgn>

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

<Pgn pgn="${pgn.address.@hex}">.

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

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

The next line of the example file is now: <MandatoryFlag> <![CDATA[true]]> </MandatoryFlag>. This value is not represented in any attribute of the PGN 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 a boolean value – the multipacket bool: <Multipacket> <![CDATA[true]]> </Multipacket>. The corresponding line for the description template will be:

<Multipacket>${pgn.multipacket}</Multipacket>

The last line for the description template will be

<Length >${pgn.packetLength}</Length>

1.11.2 Writing Description templates for export

The export description templates are written in FreeMarker Template Language (FTL). FreeMarker is a template engine and in this chapter general functions are described (see Table 41). 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 54 and Table 55

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

Table 41: Examples using FTL