.. (c) Copyright, Real-Time Innovations, 2023. All rights reserved. No duplications, whole or partial, manual or electronic, may be made without express written permission. Any such copies, or revisions thereof, must display this notice unaltered. This code contains trade secrets of Real-Time Innovations, Inc. .. include:: vars.rst .. _section-examples: Examples ======== Introduction ------------ This section includes examples of how to use *rtiarcgen* against an ECU AUTOSAR ARXML export file "Connextors.arxml". Wherever you see ````, replace it with the appropriate path. Default paths to the examples are shown below: - macOS systems: ``/Users/your user name/rti_workspace/drive-3.0.0/6.1.2/examples`` - Linux systems: ``/home/your user name/rti_workspace/drive-3.0.0/6.1.2/examples`` - Windows systems: ``\rti_workspace\drive-3.0.0\6.1.2\examples``, where ```` depends on your version of Windows. For example, on Windows 10 systems, the path to the Documents folder is ``C:\Users\your user name\Documents``. The file "Connextors.arxml" can be found under **/integration_toolkit_for_autosar_classic/comfort**. "Connectors.arxml" 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:: static/ecu.png :align: center :alt: 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). Getting Help ------------ You can access online help with *rtiarcgen* parameters and variables with the following command: .. code-block:: console $ rtiarcgen -help RTI Connext AUTOSAR Runtime CDD Code Generator 3.0.0.0 Usage: ./rtiarcgen [options] ... ... .. _section-self-testing: Self-Testing ------------ To ensure proper access to code generation template files (mandatory) and *rtiddsgen* (optional), use the following commmand-line parameter: .. code-block:: console $ 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] sh: rtiddsgen: command not found [CLI|inf] rtiddsgen is NOT available [CLI|inf] rtiddsgen parameters are: 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: .. code-block:: console $ export PATH=$PATH:/opt/Connext/rti_connext_dds_micro-2.4.14.1/rtiddsgen/scripts All integrity checks succeed: .. code-block:: console $ 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] 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: 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: .. code-block:: console $ mkdir types $ rtiarcgen -idlTypes /integration_toolkit_for_autosar_classic/comfort/Connectors.arxml -idlPath types RTI Connext AUTOSAR Runtime CDD Code Generator 3.0.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-IDL files, by using ``-xmlTypes`` and ``-xmlPath ...`` command-line arguments instead: .. code-block:: console $ rm -rf types $ mkdir types $ rtiarcgen -xmlTypes /integration_toolkit_for_autosar_classic/comfort/Connectors.arxml -xmlPath types RTI Connext AUTOSAR Runtime CDD Code Generator 3.0.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 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: .. code-block:: console $ rm -rf types $ mkdir types $ rtiarcgen -idlTypes /integration_toolkit_for_autosar_classic/comfort/Connectors.arxml -idlPath types -singleFile RTI Connext AUTOSAR Runtime CDD Code Generator 3.0.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. 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 :ref:`self-testing ` above for details): .. code-block:: console $ rm -rf types $ mkdir types $ rtiarcgen -idlTypes /integration_toolkit_for_autosar_classic/comfort/Connectors.arxml -idlPath types -cHeaderPath types -cSourcePath types -singleFile -ddsTypeSupport RTI Connext AUTOSAR Runtime CDD Code Generator 3.0.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. 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: .. code-block:: console $ rm -rf types $ mkdir types $ rtiarcgen -idlTypes /integration_toolkit_for_autosar_classic/comfort/Connectors.arxml -idlPath types -cHeaderPath types -cSourcePath types -singleFile -ddsTypeSupport -conversions RTI Connext AUTOSAR Runtime CDD Code Generator 3.0.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. 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 `` command-line parameter to narrow down the code generation scope: .. code-block:: console $ rm -rf types $ mkdir types $ rtiarcgen -idlTypes /integration_toolkit_for_autosar_classic/comfort/Connectors.arxml -idlPath types -cHeaderPath types -cSourcePath types -singleFile -ddsTypeSupport -conversions -runnables RTI Connext AUTOSAR Runtime CDD Code Generator 3.0.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. 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: .. code-block:: console $ rm -rf types $ mkdir types $ rtiarcgen -idlTypes /integration_toolkit_for_autosar_classic/comfort/Connectors.arxml -idlPath types -cHeaderPath types -cSourcePath types -singleFile -ddsTypeSupport -conversions -runnables -entities RTI Connext AUTOSAR Runtime CDD Code Generator 3.0.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``.