RTA Knowledge Base

Introduction

Scope

This application note describes the functional background of the ComXf module, which will be used on an RTA-CAR project, the 12.0.0 Standard Starter Kit.

Definitions & Abbreviations

AR: AUTOSAR

BSW: AUTOSAR Basic Software / Hardware independent service layer

ComXf: COM Transformer

CRC: Cyclic Redundancy Checks

Crc: The Crc module, part of the RTA-SAFE stack

DBC: DataBase for Can

E2E: End2End Communication Protection

E2EXf: E2E Transformer

RTE: AUTOSAR Real Time Environment

OS: AUTOSAR Operating System

SK: Starter Kit

PDU: Protocol Data Unit

SWC: Software Component

Prerequisites

In order to complete this guide, it is assumed the user has a good knowledge of AR methodology and terminology. As well as having the specified tool-chain installed, and have access to the VRTA Standard 12.0.0 SK which is to be used.

Functional Overview

General Overview

The communication mechanism Data Transformation (introduced with AR4.2) enables the transmission through Transformers of large complex data as byte arrays via Sender/Receiver and Client/Server communication. Transformers employ a data transformation mechanism to linearize and transform data, and they are executed by the RTE for any inter-ECU communication that has been configured to be transformed. Multiple Transformers can be concatenated into transformer chains. The first transformer in the chain receives the data from the RTE, and the RTE allocates the buffer and calculates the required buffer size using the attribute “BufferComputation”. Each subsequent transformer in the chain uses as input the output of the preceding transformer.

COM Based Transformer

The COM Based Transformer (ComXf) is a transformer of class Serializer and performs the signal packing of the data configured to be transformed. A SWC initiates an inter-ECU communication and then passes the data through the RTE to ComXf. The ComXf will:

  • On the sender side:
    • Serialize the data of the SWC and bring them into a uint8-array representation based on the ComSignalGroup description inside the COM module configuration.
    • Forward the uint8-array representation to the COM module, via the Com_SendSignalGroupArray API, to be placed inside the respective IPdu. The COM module may analyze the provided uint8-array (depending on the configuration of the Transmission Mode Selection) and trigger the respective transmission mode. The IPdu is sent, via the Com stack, over the bus to the receiver(s).
  • On the receiver side:
    • deserializes the linear data from the IPdu back into the original data structure.

In both the sender and receiver scenarios, from the SWC’s point-of-view, it is totally transparent as to whether the data have been transformed or not.
Note that in a Transformer Chain, ComXf is always the first transformer on the transmission side, and the last one on reception side.

Dependencies on other Modules

ComXf has the following dependencies on other modules:

  • COM: ComXf reads the COM module configuration, which contains the detailed description of the communication matrix. Information such as the start position, endianess, signal length and signal type that is configured inside the COM module, is also required by ComXf.
  • rba_SysElem: rba_SysElem imports configuration parameters from the System Extract and stores them in Ecuc Value File.
  • rba_Xfrm: rba_Xfrm contains the header TransformerTypes.h (which includes StdTypes.h), code:Xfrm_EcucParamDef.arxml for general Transformer Values (i.e. which Signal/SignalGroup is used with which Transformer Mechanism), and also a memcopy api called rba_Xfrm_MemCopy.

Data handling

The handling of the data inside the Transformer buffer and COM’s IPdu buffer is shown in figure:


The ISignalIPdu is handled by the COM module as ComIPdu and may contain several parts (signals and signal groups). Thus there can be several signals and signal groups defined inside an ISignalIPdu (e.g. figure 'Signal A’ and ’Signal B’ are part of the IPdu but are not considered by the COM Based Transformer for the ’Signal Group X’). 

The Com APIs Com_SendSignalGroupArray and Com_ReceiveSignalGroupArray handle the signal group as array representation based on length of the signal group and the start position inside the ComIPdu.
This array representation contains all signals that belong to the signal group, regardless whether the application software has a data mapping defined or not.

As an example in figure, the ’Signal Group X’ consists of the signals ’M’, ’CRC’, ’SC’, ’D1’, ’D2’, ’D3’, and ’D4’. Thus the RTE will interact with COM based on the whole array representation of this signal group with length of the signal group. When the RTE interacts with the COM Based Transformer also all the other potential transformers need to be considered in order to determine which part of the array representation of the signal group actually is provided to each transformer since each transformer may add data during sending (or remove data during reception). The part of the array representation which holds the ’CRC’ and ’SC’ signals are handled by the E2E transformer but will not be considered by the COM Based Transformer. The ’M’ signal will neither be handled by the E2E transformer nor the COM Based Transformer. For ’M’ a further transformer is responsible. The RTE will provide the data buffer from the ’Start of data with DataMapping defined’ location to the COM Based Transformer.

Example Project

This example project has been implemented using the v12.0.0 Standard SK.

RTA-CAR 12.0.0 toolchain
ISOLAR-AB12.0.0
RTA-BSW12.0.0
RTA-RTE12.0.0
RTE-OS12.0.0

RTA-CAR Workflow

Step 1: Application Software Configuration

Step 1.a: Implementation Data Types

Configure DataTypes including ImplementationDataType.

The file containing the configuration explained in the next steps can be find here to be used as example: ComXf_AN.arxml

  • An ImplementationDataType for each uint type (8, 16) on which the Signal Group will refer:
    • Category: ‘TYPE_REFERENCE’
    • SwDataDefProps-Conditional: ImplementationDataType: uintX

Example figures:

  • An ImplementationDataType for each Signal Groups (Tx, Rx):
    • Category: ‘Structure’
    • SubElements for each data (Data_0, Data_1, Data_2, Data_3):
      • Category: ‘TYPE_REFERENCE’
      • SwDataDefProps-Conditional: ImplementationDataType: Base_IDT_uintX

Example figures:

Finally you will have two Implementation Data Type of type Structure, one for Tx and one for Rx:

Step 1.b: Port Interface

Configure a SenderRecieverInterface for each SignalGroup (so for: Transmitted Signal Group, Received Signal Group):

Configure a Data Element referencing the ImplementationDataType.

Open the Interface with the Generic Editor and then right click on the SR Interface and then New Child > Data Element.

Example figures:

Step 1.c: SWC

Following the creation of this new interface, the next step is to configure a port of a SWC so that it may be used in the transmission of the structured Data.

Navigate to the MasterSWC located under Software → Components and create a PPort and RPort using the Interfaces configured before and naming it accordingly:

Navigate to the Functions tab to create the Runnable adding the Data Access point:

Navigate to Events and create the Data Received Event for the RE created the step before:

Step 2: System Configuration

Step 2.a: DBC file

Update the DBC file describing the data being communicated, the data must be composed of complex data element's sub-elements and a SignalGroup must aggregate these Signals:

DBC Signal Group
BO_ 4 ComXf_Msg_Tx: 8 ApplicationECU
 SG_ Data_0_Tx : 0|8@1+ (1,0) [0|0] ""  TestECU
 SG_ Data_1_Tx : 8|8@1+ (1,0) [0|0] ""  TestECU
 SG_ Data_2_Tx : 16|16@1+ (1,0) [0|0] ""  TestECU
 SG_ Data_3_Tx : 32|16@1+ (1,0) [0|0] ""  TestECU

BO_ 5 ComXf_Msg_Rx: 8 TestECU 
 SG_ Data_0_Rx : 0|8@1+ (1,0) [0|0] ""  ApplicationECU
 SG_ Data_1_Rx : 8|8@1+ (1,0) [0|0] ""  ApplicationECU
 SG_ Data_2_Rx : 16|16@1+ (1,0) [0|0] ""  ApplicationECU
 SG_ Data_3_Rx : 32|16@1+ (1,0) [0|0] ""  ApplicationECU

SIG_GROUP_ 4 Signal_Group_ComXf_Tx 1: Data_0_Tx Data_1_Tx Data_2_Tx Data_3_Tx;
SIG_GROUP_ 5 Signal_Group_ComXf_Rx 1: Data_0_Rx Data_1_Rx Data_2_Rx Data_3_Rx;

Import the DBC selecting the two Signals Groups:

Now configure the UpdateIndicationBitPosition of each signals as shown in figure:

Add the ISignal Trigger Ref of the Signal Groups for both Tx and Rx:

Step 2.b: System Data Mapping

Open System with SystemDataMappying Editor and configure the SystemDataMapping dragging and dropping the SignalGroups and their Signals to the relative port as shown in figure.

Step 2.c: Data Transformation Set

Configure DataTransformationSet (System > Signals And Signal Groups > Transformer > DataTransformationSet), including DataTransformation and TransformationTechnologies.

Configure the DataTransformationSet as follow:

  • A 'COMBased' TransformationTechnology:
    • Protocol 'COMBased',
    • TransformerClass 'SERIALIZER'
    • Version '1.0.0'.
    • Buffer Properties:
      • HeaderLeght:0
      • In Place: false

  • Data Transformation:
    • Add the ComBased Transformer to the Transformer Chain

Step 2.d: ISignal Groups

Configure all the I Signal Groups including ComBasedSignalGroupTransformations > DataTransformationRefConditional:

DataTransformationRefConditional on the SignalGroup referencing the DataTransformation:

Do it for both the Signal Groups:

Step 3: ECU Configuration

Step 3.a: ConfGen

Run ConfGen to generate automatically the ComXf and rba_SysElem modules. Note: rba_SysElem includes all DataTransformations (SystemSignals, ISignals, DataMappings, DataTypes,…) in the form of ECU configuration values for the later BSW code-generation of modules ComXf and Rba_Xfrm.

Example output of the ConfGen is:

Step 4: BSW Generation

Com/ComGeneral/ComEnableSignalGroupArrayApi and Com/ComConfig/ComSignalGroup/ComSignalGroupArrayAccess should be set to TRUE to enable the API usage ComX to provide data serialization functionality. It accepts complex data (Sender/Receiver data element) from the RTE and provides the resulting byte array as an ISignalGroup (part of IPdu), which is finally transmitted to the receiver by the COM stack. ISignalGroup should be configured so that the serialized data can be sent via COM module. The uint8-array representation is forwarded to the COM module via the Com_SendSignalGroupArray and received from the COM module via the Com_ReceiveSignalGroupArray.

Run the BSW CodeGen enableing manually:

  • ComXf
  • Rba_Xfrm

Step 5: RTE and OS Generation

Update the EcucValueCollection (RE mapping) in this example the RE of the Master SWC.

Generate the RTE and the OS.

Step 6: ASW Code Implementation

An example code that could be used by the MasterSWC runable could be:

MasterSWC.c
/*-----------------------------------------------------------------
                                COMXF TEST
 ------------------------------------------------------------------*/
#define TEST_COMXF              0x84u

/*Assign the data structure IDT_SysSigGrp_ComXf_Tx to a variable, and construct them to be used in testing */
static IDT_SysSigGrp_ComXf_Tx AppDataElVal_Tx_ComXf;
static IDT_SysSigGrp_ComXf_Tx *AppDataEl_Tx_ComXf = &AppDataElVal_Tx_ComXf;

/* Runnable: RE_ComXf_Test
   Reads the test code on Port 'TestCode', sends the data structure through the RTE
*/

FUNC(void, MasterSWC_CODE) RE_ComXf_Test_func(void)
{       
	/*Assign a value to the data structure IDT_SysSigGrp_ComXf_Tx*/
    AppDataEl_Tx_ComXf->IDT_Element_Tx_Data_0_uint8 = 0u;
    AppDataEl_Tx_ComXf->IDT_Element_Tx_Data_1_uint8 = 1u;
    AppDataEl_Tx_ComXf->IDT_Element_Tx_Data_2_uint16 = 2u;
    AppDataEl_Tx_ComXf->IDT_Element_Tx_Data_3_uint16 = 3u;
	
	/*Initialize variables*/
    uint8 testCode   = 0x00;
    uint32 retRteWrite_ComXf;
    
	/* Read the test code received on CAN*/
    Rte_Read_RPort_TestCode_TestCode(&testCode);

    if(testCode == TEST_COMXF)
    {
        /* If the test code correspond to the COMXF test, echo the data structure in the CAN signal with ComXf comunication*/
        retRteWrite_ComXf = Rte_Write_PPort_SysSigGrp_Tx_ComXf_VDP_IDT_SysSigGrp_ComXf_Tx(AppDataEl_Tx_ComXf);
        
        /* If retRteWrite_ComXf is written back as true, meaning the message is handled correctly. */
        if(retRteWrite_ComXf == RTE_E_OK)
        {
            /* Write the test code back to Tester ECU */
            Rte_Write_PPort_TestResult_TestResult(TEST_COMXF);
        }
    } 
}

VRTA Build and Testing

Step 1: MCAL and VRTA Build

Now that the project is completed, the final step before testing is the MCAL and VRTA generation. To do so, run the 01_mcal.bat which can be found under the Build folder in the SK and after it the 02_build.bat file. After these steps an executable is created into the sub-directory Build → output named RTA-SK-VRTA.exe.

Step 2: Testing

The test will be performed with Busmaster.

Run the executable file RTA-SK-VRTA.exe double clicking on it. Ensure, that the runLoopback.bat is running also, as this will allow us to communicate with the virtualized ECU.

Now that both programs are running open BusMaster. Setting the Driver Selection to ETAS BOA. A Hardware Selection prompt window should appear, here select any CAN hardware (except ETAS://ETH/ES523:VLoopBack/CAN:1) and move to Configured CAN Hardware and click Ok.

Then click connect, and the following should appear in the Message Window:

The signal group transmitted by the Master SWC with ID 0x4 is transmitted with initial value 0.

Now that we are connected, within the Simulation Windows tab, select the Transmit Window. A dialog window should appear, within this window enter the message with the ID 0x14 which will be used for testing the Transmission of Protected Messages. Then assign to the 1st byte the test code value 0x84 which is TEST_COMXF.

The ECU will answer with the structured data value set to 0,1,2,3.