Main Page | Directories | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages | Examples

Getting Started with IsoAgLib

Object Oriented Program Library ISOAgLib

Development of ISO 11783 and DIN 9684 Applications

Copyright © 1999 - 2004 Achim Spangler, Martin Wodok

Licensed with Exceptions under the General Public License (GPL) of the Free Software Foundation

Main Features
Structural Overview
License Conditions
Thanks to development by Sensortechnik Wiedemann ( STW )
Thanks to Fritzmeier for contribution of ISO 11783 Virtual Terminal support
Thanks to eager and patient initial developers with Win32
Main TODO items
Authors and Contributors of the IsoAgLib
List of Known Projects which use IsoAgLib
HOWTO Identify and download needed archives
HOWTO Access the Version Management Repository
HOWTO Recreate Documentation with Doxygen
HOWTO Learn Usage of IsoAgLib
HOWTO Prepare Suitable Compiler and IDE
HOWTO Install vt2iso - Tool for Creation of ISO 11783 Virtual Terminal Masks
HOWTO Create Project Files with Script
General Information
Modelling as Network of Autonomous Agents
Service Network
Further Development
Questions, Answers and Discussion
Further Reading on Open Source

Last Update:
13 October 2004
by Achim Spangler

HOWTO Learn Usage of IsoAgLib

Information in Tutorial Examples

Please start your learning phase with the several tutorial examples, so that you can get a guided tour through the several options and features of the library. Each example has several links to informative HTML pages where you can more and deeper information on the presented topics.

Look at Example Page for the available tutorial examples.

Documentation Overview Pages

HOWTO Prepare Suitable Compiler and IDE

The ISOAgLib requires standard conformant C++ compilers with a conformant implementation of the Standard Template Library ( STL ). As at least the Microsoft Visual Studion of version 6 doesn't provide either, you have at least to download the conformant STL version from ( Important: Don't use the iostream version of STLport with Visual Studio, as there are some problems ).

KDevelop3 for LINUX

The usage of ISOAgLib is quite easy with LINUX. As this platform is used by Achim Spangler, a first hand support is possible. The fine IDE named kdevelop ( see ) provides code completion, class browser, integrated debugger and several features more. There are some basic kdevelop3 projects in compiler_projects/kdevelop_tmake/IsoAgLib . In case of problems, Achim Spangler can help with some more examples.
The project files which can be created by a helper tool of the ISOAgLib can be very easily compiled with standard GNUmake ( Important: This requires the existance of qmake of the Qt framework - this is available as simple installable binary for all known LINUX distributions ).

Dev-C++ for Win32

Important: An improtant issue for ISOAgLib Version 1.0.1 will be the fix of problems of Win32 programs which should use Vector-Informatik CAN cards, and which are compiled with Dev-C++ ( programs compiled with Microsoft Visual Studio work fine with ISOAgLib and these CAN cards ). The functions of the dirver DLL seem to be called, but something goes wrong, so that no CAN channels are found.

As Achim Spangler had several issues with MS Visual Studio, and the STL version of the standard gcc compiler is quite good, Achim Spangler decided to maintain mainly the free IDE "Dev-C++" ( ) for Win32 platforms. This IDE has some important features:

Installation of Dev-C++

  1. Please download at least the version from
  2. Check for updates with Dev-C++ menu entry TOOLS->CHECK FOR UPDATES
  3. Select the mirror "" from the list ( at least the german version has a dead default mirror entry in the list ) in the dialog window "WebUpdate"
  4. Click on button "Check for updates" in the dialog window "WebUpdate"
  5. Select at least the following packages for download ( as they are needed for vt2iso )

Tasking for Embedded Targets

The Tasking Compiler of version >= 7.56 is handling C++ in a sufficient manner and provides a conformant STL ( important: the STL version of 8.0 is consuming tooo muuuch memory - contact Tasking Support to get alternative like in version 7.56 where the resource requirements are fine; maybe some of the newer Tasking Compiler versions than 8.0 manage the size overhead of STL better; the overhead is caused by the change from and adopted SGI STL to the STLport system; while SGI STL uses templates only, the STLport defines several functions as functions which can be compiled to a linkeable library; this approach is fine, as long as the target linker is able to select just the needed functions from the STLport libraries; at least Tasking Compiler Version 8.0 included a lot too much object code into the firmware, so that the overhead is not acceptible ).

ISOAgLib provides also some project files for the tutorials which can be used by the Tasking compiler.

HOWTO Install vt2iso - Tool for Creation of ISO 11783 Virtual Terminal Masks

The ISOAgLib provides a complete Open Source Tool Chain for ISO 11783 virtual terminals. A very important part is the tool vt2iso which parses the XML mask definition files and creates ROMable constant declerations for all used virtual terminal objects, which can be easily uploaded to the terminal ( see at the corresponding tutorial for more information on this ).

Install Image Manipulation Library Free Image

The vt2iso can read almost all types of bitmaps to get the compileable variable array representation of bitmaps for the ECU. This stuff is greatly supported by the Open Source libraries FreeImage and Paintlib ( ) ( alternative - choose the library that is easier to install for you ).
Vt2iso uses these libraries to access the color values of all pixels ( and to convert from palettized / indexed formats if needed ) so that the neeed conversion to the chosen color depth can be performed. Vt2iso uses an automatic calculation of a threshold to get the highest contrast in the picture ( optimum 50:50 relation between black and white ).

Installation of Free Image Library on LINUX

The FreeImage library can be best compiled from source for LINUX ( simple to compile with make based on provided Makefile ). Please make shure that the library and include files are installed to system directories ( need root user to install ) or adopt the Makefiles on your own ( no support by author for this config ). The FreeImage library may also be available as a ready made binary distribution.

Installation of Free Image Library on Win32

On Win32 Platform the Dev-C++ IDE provides a very simple download as extension package from within the program. Thus you have no installation afford with any make or manual install ( see Installation of Dev-C++ ). In case you still want to use Visual Studio, then please look at the manuals on the project webpage.

( Remark: As this program is only running on development PC, the compiler needn't be able to generate code for embedded platforms -> Tasking not needed for this on Win32 )

Install XML Parser Library Xerces of the Apache Foundation

The parsing of the XML files is performed by the Xerces library from apache, which can be downloaded from .

Installation of Xerces-C on LINUX

Most of the LINUX distributions provide a binary package for Xerces-C which can be easily installed from within the distribution specific package manager. Select at least a Xerces-C package which contains* and the corresponding headers in /usr/include/xercesc/ ( or /usr/local/include/xercesc/ ).

Installation of Xerces-C on Windows

  1. Download the Dev-C++ prepared binary of Xerces-C from
  2. Call the packagemanager for Dev-C++ ( menu TOOLS->PACKAGE MANAGER ) and select the downloaded archive xerces-c_2_5_0-mingw.DevPak for install

Compile vt2iso

Compile VT2Iso on LINUX

  1. cd build_utils/vt2iso
  2. call make

Compile VT2Iso on Win32 with Dev-C++

  1. Install first Dev-C++ with the library packages FreeImage and ImageLib
  2. Install Xerces-C ( see above )
  3. Open the Dev-C++ project file build_utils/vt2iso/
  4. Start project compile
  5. Copy the dll's xerces-c_2_5_0.dll and FreeImage.dll to a place where Vt2Iso.exe can find them if you execute the EXE ( e.g. same directory as EXE or system directory ) or extend the PATH. As Achim Spangler is very seldom using Win32 development tools, I ask you to check other resources on how to manage dll placement.

Use Vt2Iso to create mask definition

You can find the description of the XML syntax which is used by vt2iso at Specification for ISO VirtualTerminal XML files .
An example mask pool is defined for the example . Some handler functions are also demonstrated there.
The automatic generation itself is triggered by a call like described in the script build_utils/ ( LINUX ) or build_utils/vt2iso-3-0_VirtualTerminalIso.bat ( Win32 ). This script/BAT results in suitable files with constant variable array definition for include into the main souce file of a project ( in this example in IsoAgLib_Examples/tutorial/3_Terminal/3_0_VirtualTerminalIso/MaskDefinition/ ).

HOWTO Create Project Files with Script

Caused by the huge amount of optional features in the ISOAgLib , the manual selection of needed project files can get quite complicated. The script compiler_projects/projectGeneration/ can create project files and project specific configuration headers for all projects. The feature setup is feed to this script by configuration files with a very simple syntax. Please have a look at the comments inside the several conf_* files in the directory compiler_projects/projectGeneration/ . Call the script like this:

Use MSYS to run script on Win32

As scripts can only natively executed in UNIX or LINUX, the tool MSYS ( ) is needed as a minimal POSIX layer to call bash scripts within Win32. This project is simply to install. You don't need the other tools on this side, as the MinGW compiler is also integrated into the Dev-C++ tool.

Integrate Win32 CAN card drivers

The IsoAgLib provides at the moment an integration with the CAN drivers from Vector Informatik. Both driver types CANLIB and XL Driver Library are supported by the source modules and . Both modules support the usage of a thread based CAN receive, which can be activated by the setting of the #define USE_THREAD ( if it's undef -> no threading is used ). The integration of ISOAgLib and Vector CAN drivers runs as follows:
  1. Download either the current CANLIB or XL Driver Library driver
  2. Install the driver with the SETUP.EXE ( don't rename the contained root directories CANLIB resp. XL Driver Library as the ISOAgLib uses them )
  3. Set the project configuration file conf_* ( e.g. conf_0_0_AddressClaimIso ) as follows:
    1. set the variables USE_WIN32_HEADER_DIRECTORY and USE_WIN32_LIB_DIRECTORY to your installation root ( don't include the directory name part CANLIB resp. XL Driver Library )
      • You selected "D:/Development/VectorInformatik" during the execution of SETUP.EXE.
      • SETUP.EXE placed everything in the directory "D:/Development/VectorInformatik/CANLIB" resp. "D:/Development/VectorInformatik/XL Driver Library"
      • Set both above mentioned variables to "D:/Development/VectorInformatik"
    2. set the variable USE_CAN_DRIVER to either "vector_canlib" or "vector_xl"
    3. select the CAN card type variable USE_WIN32_CAN_HW_TYPE to HWTYPE_VIRTUAL, HWTYPE_CANCARDX, HWTYPE_CANAC2, HWTYPE_CANAC2PCI, HWTYPE_CANCARDXL, HWTYPE_CANCARD2 ..... ( look at driver manual )
    4. Set the target platform USE_TARGET_SYSTEM vaiable to pc_win32
  4. select in the driver library specific source file the wanted thread or not thread state
  5. let create a project file for Dev-C++
  6. build the project with Dev-C++
  7. install the .dll of the used CAN driver library ( file from Vector Informatik ) into the DLL-Search-Path of your system ( or into the directory of your resulting EXE )

This strategy can be mapped to other Win32 or LINUX CAN cards as well. Please contact the Achim Spangler for help on adoption and please send a running adoption back to the project.

Available Command Line Options for

The script provides several command line options which enables the individual overwrite of target specific project settings. Thus you can use a project config file, which reflects for example a pc_linux platform, to get a project file for pc_win32 ( Dev-C++ project file ). The following parameters are available ( you can get this list by calling the script with "./ --help" ).
Usage: ./ [OPTION] project_config_file
Create filelist, Makefile and configuration settings for a IsoAgLib project.

  -h, --help                        print this message and exit.
  --doxygen-export-directory=DIR    write the filelist and configuration files with doxygen documentation
                                    blocks to the given directory instead of the default directory of all generated files.
  --IsoAgLib-root=DIR               use the given root directory instead of the entry in the selected configuration file.
  --target-system=TARGET            produce the project definition files for the selected TARGET instead of the
                                    target which is specified in the configuration file
                                    ( "pc_linux"|"pc_win32"|"esx"|"imi"|"pm167"|"mitron167" ).
  --pc-can-driver=CAN_DRIVER        produce the project definition files for the selected CAN_DRIVER if the project shall run on PC
                                    ( "simulating"|"sys"|"rte"|"vector_canlib"|"vector_xl" ).
  --pc-rs232-driver=RS232_DRIVER    produce the project definition files for the selected RS232_DRIVER if the project shall run on PC
                                    ( "simulating"|"sys"|"rte" ).

./ parses the selected project configuration file and overwrites the default values for all contained settings.
It collects then the corresponding files which can then be imported to an individual IDE.
Additionally a project specific configuration header is created in the directory lgpl_src/Application_Config with the
name scheme ".config_<project_name>.h". If the #define PRJ_USE_AUTOGEN_CONFIG is set to ".config_<project_name>.h",
the central configuration header lgpl_src/Application_Config/isoaglib_config.h will include this header.
Please set additionally the SYSTEM_FOO for the wanted platform - $0 will output the correct define at the end of the
Thus with these two DEFINE settings, the compiler can generate a clean running executable / HEX.

Report bugs to <Achim.Spangler@osb-ag:de>.

The script parses the given project feature set selection and configuring file and

  1. selects all needed project file ( thus you don't have do manually select the neded files, a big part of the files can be excluded for simple projects )
  2. generate a project specific configuration header, which is placed in the directory "lgpl_src/Application_Config/" ( you can trigger the compiler to include it by simply setting the compile time DEFINE PRJ_USE_AUTOGEN_CONFIG to ".config_<project_name>.h"
  3. create suitable project files for the following build systems:
  4. tells you which DEFINES must be set for compile, if none of the automatically created project files will be used.

Contents of Feature Setup File

The setup file can be derived from the following example ( see compiler_projects/projectGeneration/conf_0_0_AddressClaimIso ):

# Filename: conf_0_0_AddressClaimIso
# Configuration setting for tutorial example 0_0_AddressClaimIso
# in the tutorial group 0_SystemMgmt

# optionally define path to qmake
# if it can be automatically found by
# + which qmake ( e.g. in search path for binaries )
# + can be found with sys-cmd find beneath /usr/lib/qt*
#   ( there should be only one version of qmake in this path
#      -> if there are more qt installations, please manually define
#          it by uncommenting and adopting the following line )
# QMAKE_PATH=/usr/lib/qt3/bin/qmake

# define the path where the aplication can be found
# ( in relation to the root of the IsoAgLib
# seperate files by whitespace
# define the name of the app
# ( if this variable is not set, then
#   all files of the selected directories are used )
# seperate files by whitespace
# define the file extensions to include for the
# application source file search ( default: *.c *.cc *.cpp *.h *.hpp )
# APP_SEARCH_SRC_CONDITION="*.cc *.c *.cpp"
# define pathes ( jokers like "*" are allowed ) which shall be
# excluded from application file search
# ( example:
#    - exclude path Fii somewhere in deep dir: ".../Fii/..."
#    - exclude file as part of directory Fii: ".../Fii/Foo.c"
#      ( includes occurences of in other directories!! )
#  )
# define filenames which shall be excluded in all directories
# ( jokers like "*" are allowed - example "test*.cc" )

# define path to the main directory if the IsoAgLib
# - i.e. where both lgpl_src and IsoAgLibExamples are located

# optionally set individual DEFINES - seperated by whitespace
# ( e.g. DEBUG to activate some debug messages )

# select if the project shall use the float data type
# default is FALSE as far as possible
# ( this has an impact on process data, RS232 output,
#   GPS decode )

# select if Debug messages within the IsoAgLib shall be sent via RS232
# ( if this is activated, the PRJ_RS232 setting is activated -> integrate
#   the IsoAgLib RS232 driver extension to your project )

# select watned type of target system: "pc_linux" | "pc_win32" | "esx" | "imi" | "pm167" | "mitron167"
# select wanted type of CAN driver connection: "simulating"|"sys"|"rte"|"vector_canlib"|"vector_xl"
# targets other than pc_linux or pc_win32 can only use "sys"
# only target "pc_win32" can use the driver "vector_canlib"|"vector_xl"
# only target "pc_linux" can us the driver "rte"
# select wanted type of RS232 driver connection: "simulating"|"sys"|"rte"
# targets other than pc_linux or pc_win32 can only use "sys"
# only target "pc_linux" can us the driver "rte"

# #############################################
# configuration options typical for embedded project
# ( these are used for target systems like "esx",
#   "imi", "pm167" ) or Win32 development targets
# where the system libraries aren't placed in standard
# directories ( UNIX/LINUX has standard directories
# /usr/include, /usr/local/include, /usr/lib
# and /usr/local/lib -> IsoAgLib awaits the libraries
# in this directories for UNIX/LINUX )
# These settings are at the moment only used for project
# generation of
# + Tasking EDE
# + Dev-C++ (esp. needed for Win32 CAN driver integration
#             which is at the moment provided for
#             Vector Informatik canlib43 and XL Driver Library )
# But this could be extended to other compilers.
# These config settings allow to create project files
# which can be used to generate runnable HEX out of the
# box from automatic generation
# #############################################

# specify the path to the embedded compiler
# USE_EMBED_COMPILER_DIR="c:/programme/tasking/7.56/c166"

# specify the path ( relative to IsoAgLib root or absolute )
# to the libraries of the embedded BIOS / OS
# ( please seperate entries by whitespace )
# USE_EMBED_LIB_DIRECTORY="commercial_BIOS/bios_esx"

# specify the path ( relative to IsoAgLib root or absolute )
# to the headers of the embedded BIOS / OS
# ( please seperate entries by whitespace )
# USE_EMBED_HEADER_DIRECTORY="commercial_BIOS/bios_esx"

# specify the needed library files
# ( please seperate entries by whitespace )
# USE_EMBED_LIBS="C756/Xos20l.lib Module/Xma20l.lib"

# specify the needed linker / locater control file
# USE_EMBED_ILO="Xos20lcs.ilo"

# ( esp. Vector Informatik )
# specify the path ( relative to IsoAgLib root or absolute )
# to the WIN32 CAN libraries
# IMPORTANT: Set the path to the directory where you installed
# the CAN driver library during its SETUP.EXE process
# As the individual library file sets are at fixed places
# within a CAN driver installation, the IsoAgLib will
# select the library files automatically
# ==>> this path can be used without changes, if several
#      driver version like "CANLIB" and "XL Driver Library"
#      are installed in parallel
#      ( all IsoAgLib parts will access the individual
#        headers and libraries with the addition of the
#        default directory name from the SETUP.EXE
#        e.g. "<USE_WIN32_LIB_DIRECTORY>/CANLIB"
#          or "<USE_WIN32_LIB_DIRECTORY>/XL Driver Library" )
# USE_WIN32_LIB_DIRECTORY="D:/Development/VectorInformatik"

# specify the path ( relative to IsoAgLib root or absolute )
# to the WIN32 CAN headers
# IMPORTANT: Set the path to the directory where you installed
# the CAN driver library during its SETUP.EXE process
# ==>> this path can be used without changes, if several
#      driver version like "CANLIB" and "XL Driver Library"
#      are installed in parallel
#      ( all IsoAgLib parts will access the individual
#        headers and libraries with the addition of the
#        default directory name from the SETUP.EXE
#        e.g. "<USE_WIN32_LIB_DIRECTORY>/CANLIB"
#          or "<USE_WIN32_LIB_DIRECTORY>/XL Driver Library" )
# ( please seperate entries by whitespace )
# USE_WIN32_HEADER_DIRECTORY="D:/Development/VectorInformatik"

# specify the wanted Hardware Type of the CAN card
# ( esp. Vector Informatik CAN drivers can be used for several
#   CAN cards of their product line )
# ( refer their documentaion to find more types )
# ( IsoAgLib places automatically "XL_" before the card define,
#   if the XL driver is selected --> DONT'T set the XL_ here again
#   ==> this allows simpler switch between different CAN driver libs )

# define the amount of available CAN BUSes at the ECU
# ( default 1 )

# define the amount of CAN instances to support
# ( all values lower than 1 are overwritten by default 1 )

if [ $CAN_INSTANCE_CNT -gt 1 ] ; then
  # if more than one CAN BUS is defined, the selected
  # protocol(s) can be executed as independent instances
  # at more than one channel
  # ( if more than one CAN instance is used, but
  #   only one channel is used for protocol, than
  #   the index 0 - i.e. the first item is used for protocol )
  # default is to run only one protocol instance

# define project name - used for directory with makefile

# set value of feature to 1 if wanted
# unset or set to 0 if not wanted
# PRJ_DIN9684=0

# PRJ_BASE defaults to 0

# PRJ_RS232=0

# activate globally the use of process data

# for DIN 9684 the process data system can be used
# to decode GPS information from Fieldstar or LBS+ extension
# ( if this and DIN9684 is activated, but PRJ_PROCESS is not
#   then the value of PRJ_PROCESS is overwritten with 1 to activate it )

# decide if local process data are wanted

# select the feature set of the wanted local process data

# decide if remote process data are wanted

# select the feature set of the wanted remote process data

Generated on Wed Oct 13 15:16:24 2004 for IsoAgLib by  doxygen 1.3.8-20040913