...
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.
...
J1939 Projects
port J1939 Library configuration, together with software model, is defined as a single Communication Creatorproject. Using this project, the tool can generate appropriate code files. Working with J1939 projects is analogous to working with otherIndustrial 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 J1939 projects if he has support for this protocol installed intoIndustrial 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
...
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
...
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.
...
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.
...
Specify location for generated code
Second wizard page asks user to specify location of six files that will be generated based on project configuration.
...
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 morefiles already exist in location specified – see Figure 273.
Figure 273: 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 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.
...
Validation
J1939 projects are subject to correctness checks as every otherIndustrial Communication Creator project:
...
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 otherIndustrial 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 ( ).
...
Structure of objects of which application's software model is made.
Figure 277: Top Page for J1939 project
...
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.
...
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”.
...
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
...
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 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.
...
CMD generation
It is possible to generate files through CMD commands. The CMD Communication Creator is started via commands with following structure:
...
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.
...
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".
...
Generated files
cal_conf.h
cal_conf.h file is a C header file which contains defines needed for configuration of J1939 Library.
...
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
...
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.
...
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.
...
profile database file
| reference to standard | |
version | content | |
iso_pgns.iccprof | J1939DA – Jul 2019 | ISO PGNs |
Nmeanmea_pgns.iccprof | J1939DA – Jul 2019 | NMEA PGNs |
uds_pgns.iccprof | J1939DA – Jul 2019 | UDS PGNs |
Table 39: Profile databases delivered by port
...
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.
...
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.
...
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
...
it is recommended to use all the ISO PGNs
...
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.
...
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.
...
Hardware configuration
At first the target hardware has to be configured. The most important decision is to choose a CPU resp. an operating system.
...
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.
...
project.
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.:
...
Code that is placed between those marks will be kept for the next generation of the files and will not be overwritten.
...
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.
...
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.
...
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
...
csv-Import
TheIndustrial Communication Creator provides the import of object specifications in the csv-format for PGN objects.
...
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
TheIndustrial Communication Creator provides the import of object specifications in user-defined-formats for PGNs.
...
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
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}”
...
Export
...
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
...
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).
...
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:·
...
...
Use cases
...
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
...
<Length >${pgn.packetLength}</Length>
...
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:·
...
A list of all additional specifiers, variables and lists can be found in Table 54 and Table 55
...