4. Examples

4.1. Introduction

This section includes examples of how to use rtiarcgen against an ECU AUTOSAR ARXML export "Connextors.arxml", which can be found in example/comfort under the installation folder for RTI Connext Integration Toolkit for AUTOSAR Classic.

This export file features the following relevant entities:

  • An AUTOSAR_Platform package containing fundamental Base Types, Computation Methods, Constraints and Implementation Data Types.

  • A DataTypes package defining project-specific Application and Implementation Data Types.

  • A PortInterfaces package containing several project-specific Service Interface definitions upon the types described above.

  • A DataTypeMappingSets containing a single mapping of Application to Implementation Data Types.

  • A ComponentTypes package defining a root ECU composition Comfort, holding:

    • A set of Application SW-C Types representing a specific vehicle behaviour: SeatPosition, SeatTemperature, SeatStatus, and a composition of those three called simply Seat.

    • A set of Complex Device Driver (CDD) SW-C Types featuring Port Prototypes that mirror data sent/received to/from Topics in a DDS Domain via DataWriter / DataReader entities: CabinSurveillanceConnector and InfotainmentConnector.

    • A root ECU Composition Comfort instantiating a single Seat instance (DriveSeat) that sends/receives signals to/from Infotainment and CabinSurveillance SW-C instances.

Figure 1: Example AUTOSAR Classic ECU architecture featuring DDS integration

Using this simple ECU design as starting point, the following sections will demonstrate code generation features offered by rtiarcgen. These examples are progressive, where each step produces the outputs from all previous examples plus the use case at hand. However, the different command-line parameters can be used to generate any set of outputs in isolation or combination.

Note

In all following sections, a UNIX-style convention is used for describing file paths ("/" is the component separator). On Windows platforms, use Windows-style paths ("\" is the component separator, and drive specifiers such as "C:" or "\\" should be used in absolute paths).

4.2. Getting Help

You can access online help with rtiarcgen parameters and variables with the following command:

$ rtiarcgen -help
RTI Connext Integration Toolkit for AUTOSAR Classic 0.2.0.0

Usage:
   ./rtiarcgen [options] <input> <input> ...

...

4.3. Self-Testing

To ensure proper access to code generation template files (mandatory) and rtiddsgen (optional), use the following commmand-line parameter:

$ rtiarcgen -selfTest
[CLI|inf] C templates base path: "/Users/john/Projects/Automotive/AutosarClassicIntegrationToolkit/templates/c"
[CLI|inf] /* C templates OK */
[CLI|inf]
[CLI|inf] DDS-IDL templates base path: "/Users/john/Projects/Automotive/AutosarClassicIntegrationToolkit/templates/ddsidl"
[CLI|inf] /* DDS-IDL templates OK */
[CLI|inf]
[CLI|inf] DDS-XML templates base path: "/Users/john/Projects/Automotive/AutosarClassicIntegrationToolkit/templates/ddsxml"
[CLI|inf] <!-- DDS-XML templates OK -->
sh: rtiddsgen: command not found
[CLI|inf] rtiddsgen is NOT available
[CLI|inf] rtiddsgen parameters are: <undefined>

In the above example, template files are found, but rtiddsgen is not in the terminal session's PATH environment variable, so rtiarcgen can't ensure its availability. After making rtiddsgen available through PATH inclusion as follows:

$ export PATH=$PATH:/opt/Connext/rti_connext_dds_micro-2.4.14/rtiddsgen/scripts

All integrity checks succeed:

$ rtiarcgen -selfTest
[CLI|inf] C templates base path: "/Users/john/Projects/Automotive/AutosarClassicIntegrationToolkit/templates/c"
[CLI|inf] /* C templates OK */
[CLI|inf]
[CLI|inf] DDS-IDL templates base path: "/Users/john/Projects/Automotive/AutosarClassicIntegrationToolkit/templates/ddsidl"
[CLI|inf] /* DDS-IDL templates OK */
[CLI|inf]
[CLI|inf] DDS-XML templates base path: "/Users/john/Projects/Automotive/AutosarClassicIntegrationToolkit/templates/ddsxml"
[CLI|inf] <!-- DDS-XML templates OK -->
INFO com.rti.ndds.nddsgen.Main rtiddsgen version 2.5.2.32
INFO com.rti.ndds.nddsgen.Main Connext DDS templates: E4EE-7F61-28DC-89C9-D1F9-8AED-A94C-BB28
INFO com.rti.ndds.nddsgen.Main Connext Micro templates: 05F2-53AD-C0CA-DF36-387C-37DF-CC26-13F6
[CLI|inf] rtiddsgen is available
[CLI|inf] rtiddsgen parameters are: <undefined>

4.4. Generating DDS Types from AUTOSAR Types (Multiple Files)

As mentioned above, Connectors.arxml contains a rather complete set of platform- and project-specific data types. In the following example we will use rtiarcgen to produce DDS-IDL files mapping AUTOSAR types referenced either directly or indirectly by any SW-C:

$ mkdir types
$ rtiarcgen -idlTypes examples/comfort/generated/Connectors.arxml -idlPath types
RTI Connext Integration Toolkit for AUTOSAR Classic 0.2.0.0
[CLI|inf] Parsing XML file...
[CLI|inf] Parsing types...
[CLI|inf] Parsing interfaces...
[CLI|inf] Parsing components...
[CLI|inf] Pruned 0/2 components.
[CLI|inf] Pruned 1/6 interfaces.
[CLI|inf] Pruned 17/30 types.
[CLI|inf] Pruned 0/30 union types.
[CLI|inf] Pruned 2/30 union types.
[CLI|inf] Generating DDS-IDL types...
[CLI|inf] Done.
[CLI|inf] 0 error(s), 0 warning(s).
$ tree types
types
├── AUTOSAR_Platform
│   └── ImplementationDataTypes
│       ├── boolean.idl
│       ├── float32.idl
│       ├── sint8.idl
│       └── uint8.idl
└── DataTypes
    ├── CompuMethods
    │   └── OccupationType.idl
    ├── SeatOccupationImpl.idl
    ├── SeatOccupationImpl__occupation.idl
    ├── SeatPositionImpl.idl
    └── SeatTemperatureImpl.idl

Note how directories are used to convey AUTOSAR package (and DDS module) structure. The -idlPath types flag is employed to direct all generation to a specific path.

Also, a similar command line can be used to output DDS-XML instead of DDS-XML files, by using -xmlTypes and -xmlPath ... command-line arguments instead:

$ rm -rf types
$ mkdir types
$ rtiarcgen -xmlTypes examples/comfort/generated/Connectors.arxml -xmlPath types
RTI Connext Integration Toolkit for AUTOSAR Classic 0.2.0.0
[CLI|inf] Parsing XML file...
[CLI|inf] Parsing types...
[CLI|inf] Parsing interfaces...
[CLI|inf] Parsing components...
[CLI|inf] Pruned 0/2 components.
[CLI|inf] Pruned 1/6 interfaces.
[CLI|inf] Pruned 17/30 types.
[CLI|inf] Pruned 0/30 union types.
[CLI|inf] Pruned 2/30 union types.
[CLI|inf] Generating DDS-XML types...
[CLI|inf] Done.
[CLI|inf] 0 error(s), 0 warning(s).
$ tree types
types
├── AUTOSAR_Platform
│   └── ImplementationDataTypes
│       ├── boolean.xml
│       ├── float32.xml
│       ├── sint8.xml
│       └── uint8.xml
└── DataTypes
    ├── CompuMethods
    │   └── OccupationType.xml
    ├── SeatOccupationImpl.xml
    ├── SeatOccupationImpl__occupation.xml
    ├── SeatPositionImpl.xml
    └── SeatTemperatureImpl.xml

4.5. Generating DDS Types from AUTOSAR Types (Single File)

Producing too many DDS-IDL (or DDS-XML) files can be undesired or problematic in some environments, thus rtiarcgen provides the -singleFile command-line flag:

$ rm -rf types
$ mkdir types
$ rtiarcgen -idlTypes examples/comfort/generated/Connectors.arxml -idlPath types -singleFile
RTI Connext Integration Toolkit for AUTOSAR Classic 0.2.0.0
[CLI|inf] Parsing XML file...
[CLI|inf] Parsing types...
[CLI|inf] Parsing interfaces...
[CLI|inf] Parsing components...
[CLI|inf] Pruned 0/2 components.
[CLI|inf] Pruned 1/6 interfaces.
[CLI|inf] Pruned 17/30 types.
[CLI|inf] Pruned 0/30 union types.
[CLI|inf] Pruned 2/30 union types.
[CLI|inf] Generating DDS-IDL types...
[CLI|inf] Done.
[CLI|inf] 0 error(s), 0 warning(s).
$ tree types
types
└── Connectors_types.idl

In the above example, Connectors_types.idl contains the same set of types (within the same package/module structure) generated in previous examples, but appended together in a single file and sorted by dependency. This way, no type is defined without all related types being defined earlier.

Note

From this point on, all examples will use the -singleFile command-line parameter, so examples produce a smaller and easier to understand set of files.

4.6. Generating DDS Type Support Files

DDS-IDL and/or DDS-XML files produced by previous examples can be fed to rtiddsgen as needed, in order to produce C-language type support code. rtiarcgen can also do this via the -ddsTypeSupport command-line parameter, provided that rtiddsgen is available in the terminal sessions PATH environment variable (see self-testing above for details):

$ rm -rf types
$ mkdir types
$ rtiarcgen -idlTypes examples/comfort/generated/Connectors.arxml -idlPath types -cHeaderPath types -cSourcePath types -singleFile -ddsTypeSupport
RTI Connext Integration Toolkit for AUTOSAR Classic 0.2.0.0
[CLI|inf] Parsing XML file...
[CLI|inf] Parsing types...
[CLI|inf] Parsing interfaces...
[CLI|inf] Parsing components...
[CLI|inf] Pruned 0/2 components.
[CLI|inf] Pruned 1/6 interfaces.
[CLI|inf] Pruned 17/30 types.
[CLI|inf] Pruned 0/30 union types.
[CLI|inf] Pruned 2/30 union types.
[CLI|inf] Generating DDS-IDL types...
INFO com.rti.ndds.nddsgen.Main rtiddsgen version 2.5.2.32
INFO com.rti.ndds.nddsgen.Main Connext DDS templates: E4EE-7F61-28DC-89C9-D1F9-8AED-A94C-BB28
INFO com.rti.ndds.nddsgen.Main Connext Micro templates: 05F2-53AD-C0CA-DF36-387C-37DF-CC26-13F6
[CLI|inf] Generating type support files...
[CLI|inf] Generating C type support files from types/Connectors_types.idl ...
INFO com.rti.ndds.nddsgen.Main Running rtiddsgen version 2.5.2.32, please wait ...
INFO com.rti.ndds.nddsgen.Main Done
[CLI|inf] Done.
[CLI|inf] 0 error(s), 0 warning(s).
$ tree types
types
├── Connectors_types.c
├── Connectors_types.h
├── Connectors_types.idl
├── Connectors_typesPlugin.c
├── Connectors_typesPlugin.h
├── Connectors_typesSupport.c
└── Connectors_typesSupport.h

Note how -cSourcePath ... and -cHeaderPath ... command-line parameters are used to direct the target folder of .c and .h file generation.

4.7. Generating C Conversion Routines

After DDS-IDL (and/or DDS-XML) type files and their C type support counterparts have been produced, the next step towards ECU integration is conversion routine generation with the -conversions command-line parameter:

$ rm -rf types
$ mkdir types
$ rtiarcgen -idlTypes examples/comfort/generated/Connectors.arxml -idlPath types -cHeaderPath types -cSourcePath types -singleFile -ddsTypeSupport -conversions
RTI Connext Integration Toolkit for AUTOSAR Classic 0.2.0.0
[CLI|inf] Parsing XML file...
[CLI|inf] Parsing types...
[CLI|inf] Parsing interfaces...
[CLI|inf] Parsing components...
[CLI|inf] Pruned 0/2 components.
[CLI|inf] Pruned 1/6 interfaces.
[CLI|inf] Pruned 17/30 types.
[CLI|inf] Pruned 0/30 union types.
[CLI|inf] Pruned 2/30 union types.
[CLI|inf] Generating DDS-IDL types...
INFO com.rti.ndds.nddsgen.Main rtiddsgen version 2.5.2.32
INFO com.rti.ndds.nddsgen.Main Connext DDS templates: E4EE-7F61-28DC-89C9-D1F9-8AED-A94C-BB28
INFO com.rti.ndds.nddsgen.Main Connext Micro templates: 05F2-53AD-C0CA-DF36-387C-37DF-CC26-13F6
[CLI|inf] Generating type support files...
[CLI|inf] Generating C type support files from types/Connectors_types.idl ...
INFO com.rti.ndds.nddsgen.Main Running rtiddsgen version 2.5.2.32, please wait ...
INFO com.rti.ndds.nddsgen.Main Done
[CLI|inf] Generating conversions...
[CLI|inf] Done.
[CLI|inf] 0 error(s), 0 warning(s).
$ tree types
types
├── Connectors_conversions.c
├── Connectors_conversions.h
├── Connectors_types.c
├── Connectors_types.h
├── Connectors_types.idl
├── Connectors_typesPlugin.c
├── Connectors_typesPlugin.h
├── Connectors_typesSupport.c
└── Connectors_typesSupport.h

Two new Connectors_conversions.c and Connectors_conversions.h C files have now been generated, containing conversion routines between AUTOSAR RTE types and DDS IDL C PSM types. These conversion routines may be referenced by code generated in the following examples.

4.8. Generating Runnable Implementations

This step goes beyond data type management into analysis and code generation for AUTOSAR SW-C runnable C code, based on the definition of the runnables (with respect to the data ports they reference and how they reference them).

In this particular ARXML export, only the two CDD SW-C's serving as DDS connectors have been exported. Had the ARXML export contained other SW-C's not targeted as DDS connectors, it would be adivsable to employ the -componentFilter <regex> command-line parameter to narrow down the code generation scope:

$ rm -rf types
$ mkdir types
$ rtiarcgen -idlTypes examples/comfort/generated/Connectors.arxml -idlPath types -cHeaderPath types -cSourcePath types -singleFile -ddsTypeSupport -conversions -runnables
RTI Connext Integration Toolkit for AUTOSAR Classic 0.2.0.0
[CLI|inf] Parsing XML file...
[CLI|inf] Parsing types...
[CLI|inf] Parsing interfaces...
[CLI|inf] Parsing components...
[CLI|inf] Pruned 0/2 components.
[CLI|inf] Pruned 1/6 interfaces.
[CLI|inf] Pruned 17/30 types.
[CLI|inf] Pruned 0/30 union types.
[CLI|inf] Pruned 2/30 union types.
[CLI|inf] Generating DDS-IDL types...
INFO com.rti.ndds.nddsgen.Main rtiddsgen version 2.5.2.32
INFO com.rti.ndds.nddsgen.Main Connext DDS templates: E4EE-7F61-28DC-89C9-D1F9-8AED-A94C-BB28
INFO com.rti.ndds.nddsgen.Main Connext Micro templates: 05F2-53AD-C0CA-DF36-387C-37DF-CC26-13F6
[CLI|inf] Generating type support files...
[CLI|inf] Generating C type support files from types/Connectors_types.idl ...
INFO com.rti.ndds.nddsgen.Main Running rtiddsgen version 2.5.2.32, please wait ...
INFO com.rti.ndds.nddsgen.Main Done
[CLI|inf] Generating conversions...
[CLI|inf] Generating runnables...
[CLI|inf]   Falling back to full file generation.
[CLI|inf]   Falling back to full file generation.
[CLI|inf] Done.
[CLI|inf] 0 error(s), 0 warning(s).
$ tree types
types
├── CabinSurveillanceConnector_dds.c
├── CabinSurveillanceConnector_dds.h
├── Connectors_conversions.c
├── Connectors_conversions.h
├── Connectors_types.c
├── Connectors_types.h
├── Connectors_types.idl
├── Connectors_typesPlugin.c
├── Connectors_typesPlugin.h
├── Connectors_typesSupport.c
├── Connectors_typesSupport.h
├── InfotainmentConnector_dds.c
└── InfotainmentConnector_dds.h

Files CabinSurveillanceConnector_dds.c/h and InfotainmentConnector_dds.c/h now contain declaration and definition of the SW-C runnables defined in the ARXML model export for CabinSurveillanceConnector and InfotainmentConnector, with RTE-DDS marshaling code according to the port access policies defined in each of them.

4.9. Generating DDS Entity Support Code

Runnables generated in the above example can't run in a vaccuum, specifically without access to DDS DataWriter and DataReader entities that the marshaling code can use to send and receive data samples. This set of entities is managed by the "dds_entities" module, which provides AUTOSAR SW-C Component, PortPrototype and PortInterface Element discriminators, as well as APIs to initialise, retrieve and finalize DDS entity graphs.

Generation of this module works via the -entities command-line parameter, as follows:

$ rm -rf types
$ mkdir types
$ rtiarcgen -idlTypes examples/comfort/generated/Connectors.arxml -idlPath types -cHeaderPath types -cSourcePath types -singleFile -ddsTypeSupport -conversions -runnables -entities
RTI Connext Integration Toolkit for AUTOSAR Classic 0.2.0.0
[CLI|inf] Parsing XML file...
[CLI|inf] Parsing types...
[CLI|inf] Parsing interfaces...
[CLI|inf] Parsing components...
[CLI|inf] Pruned 0/2 components.
[CLI|inf] Pruned 1/6 interfaces.
[CLI|inf] Pruned 17/30 types.
[CLI|inf] Pruned 0/30 union types.
[CLI|inf] Pruned 2/30 union types.
[CLI|inf] Generating DDS-IDL types...
INFO com.rti.ndds.nddsgen.Main rtiddsgen version 2.5.2.32
INFO com.rti.ndds.nddsgen.Main Connext DDS templates: E4EE-7F61-28DC-89C9-D1F9-8AED-A94C-BB28
INFO com.rti.ndds.nddsgen.Main Connext Micro templates: 05F2-53AD-C0CA-DF36-387C-37DF-CC26-13F6
[CLI|inf] Generating type support files...
[CLI|inf] Generating C type support files from types/Connectors_types.idl ...
INFO com.rti.ndds.nddsgen.Main Running rtiddsgen version 2.5.2.32, please wait ...
INFO com.rti.ndds.nddsgen.Main Done
[CLI|inf] Generating conversions...
[CLI|inf] Generating runnables...
[CLI|inf]   Falling back to full file generation.
[CLI|inf]   Falling back to full file generation.
[CLI|inf] Generating entities...
[CLI|inf] Done.
[CLI|inf] 0 error(s), 0 warning(s).
$ tree types
types
├── CabinSurveillanceConnector_dds.c
├── CabinSurveillanceConnector_dds.h
├── Connectors_conversions.c
├── Connectors_conversions.h
├── Connectors_types.c
├── Connectors_types.h
├── Connectors_types.idl
├── Connectors_typesPlugin.c
├── Connectors_typesPlugin.h
├── Connectors_typesSupport.c
├── Connectors_typesSupport.h
├── InfotainmentConnector_dds.c
├── InfotainmentConnector_dds.h
├── dds_entities.c
└── dds_entities.h

Please note that "dds_entities.c" refers to a number of project- and ECU-specific C functions that shall be defined by "dds_entities_config.c". To produce an example "dds_entities_config.c" file, append the -entitiesTemplate command-line parameter along with -entities.