Contents
Introduction
Scope
This application note provides a detailed overview of the Diagnostic Event Manager (DEM) and how to configure it within an existing RTA-CAR project configured with a diagnostic stack and a memory stack. The document will follow the creation of the DEM module as configured within our RTA-CARv12 Starter Kit, as well as implementing further features such as Debouncing and other basic use-cases.
Definitions & Abbreviations
AR: AUTOSAR
BSW: AUTOSAR Basic Software / Hardware independent service layer
RTE: AUTOSAR Real Time Environment
OS: AUTOSAR Operating System
DEM: Diagnostic Event Manager
SWC: Software Component
DCM: Diagnostic Communication Manager
DTC: Diagnosis Trouble Code
DID: Data Identifiers
Tool-chain
It is assumed you are using the RTA-CAR 12.0.1 toolchain:
RTA-CAR 12.0.1 toolchain | |
---|---|
ISOLAR-AB | 12.0.1 |
RTA-RTE | 12.0.0 |
RTA-BSW | 12.0.0 |
RTA-OS | 12.0.0 |
Pre-requisites
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.
Functional Overview
The Diagnostic Event Manager (DEM) within AUTOSAR is a central software component that is responsible for monitoring the system for events that may indicate a malfunction or fault, and the managing of reports for these events to other components. It is designed to be the central point of control for all diagnostic events in the system, maintaining a list of all diagnostic events: event data, status information and also trigger specific diagnostic actions based on the events.
Journey through DEM
Event Detection
Detection of diagnostic events within a system, is the initial operation of the DEM, detecting events from various sources: software components from Engine Control Units (ECU) or the Anti-Lock Brake System (ABS), as well as hardware components such as sensors and actuators. When an event is detected, the DEM receives the event data and assigns it a unique identifier called a Diagnostic Trouble Code (DTC). DTCs are used represent specific faults or malfunctions within the system, and they are used to communicate diagnostic event information to other components. DTCs are usually a combination of alphanumeric characters that correspond to a specific diagnostic event, and can be stored/retrieved by the DEM for later analysis.
Furthermore, the DEM also assigns unique identifiers called Diagnostic Data Identifier (DIDs) to specific diagnostic event data. DIDs are used to identify and access the data associated with a diagnostic event; typically, numerical values that correspond to a specific piece of diagnostic data.
Event Evaluation
After an event has been detected, the DEM evaluates the event data to determine its severity level. This can range from a simple warning to a critical fault that may require immediate attention. The severity level is determined by the DEM based on pre-configured rules and thresholds. Once the severity level is determined, the DEM can take appropriate actions based on the event's severity.
Event Reaction
Depending on the event's severity level, the DEM may trigger a specific diagnostic action. For example, if a critical fault is detected, it may trigger a warning light on the dashboard to inform the driver or shut down the engine to prevent damage/further faults. If a less severe event is detected, the DEM may simply store the event for later analysis.
Event Reporting
The DEM also manages the reporting of diagnostic events to other components. It does this through a standardised interface, which allows components to access the event data and status information of relevant events. This enables components such as diagnostic testers or repair tools to analyse these events and determine the cause of the fault. The DEM can handle multiple communication channels, allowing it to report diagnostic events to different components using differing communication protocols, such as CAN, UDS or Ethernet.
Event Storage
The DEM can also handle and store historical data of diagnostic events, this information can be used for later analysis or to check if a specific pattern of issue is repeating, which could indicate a malfunction within the system. Additionally, DTCs can be cleared by the DEM, this is useful when a problem has been solved, and it prevents unnecessary warning lights or alarms.
Debouncing
Event Debouncing is another important feature of the DEM. Event debouncing refers to the process of eliminating multiple occurrences of a diagnostic event that are caused by a single physical event. This is done by ensuring that a diagnostic event is only reported once, even if it is detected multiple times within a short period of time. Event debouncing is typically implemented by using a timer or counter. When diagnostic event is detected, the timer or counter is started. If another diagnostic event of the same fault is detected within a certain period of time (the "debounce time"), it is ignored, and the timer or counter is reset. If no further diagnostic events are detected within the debounce time, the timer or counter expires and the diagnostic event is reported.
Event Aging
Event Aging refers to the mechanism of automatically discarding old diagnostic events that are no longer relevant. The event aging process removes events from the event memory if they are older than a specified time limit, or if they've already been reported. This helps to prevent the event memory from being cluttered with outdated information and ensures only current and relevant data is stored.
Workflow
Workflow Summary
- DEM Creation
- DemGeneral Configuration
- DemEventMemorySet
- DemClient
- DemOperationCycles
- DemRbGeneral
- DemConfig Configuration
- DemDTC
- DemEventParameter
- DemDataElementClass
- DemExtendedDataRecordClass
- DemDID
- DemNvRamBlockId
- BswM Configuration
- Action Item
- Action List Item
- EcucM Configuration
- DCM Configuation
- DcmDsdServiceTable
- DcmRbDspReadDTC
- BSW Generation
- SWC Update
- System Update
Dem Creation
Begin by creating a new DEM module; this must be manually configured due to ConfGen not supporting it's generation. To do this, right-click on the Services category under Bsw Modules. Here select "Create Dem":
The DEM module consists of two main containers: DemGeneral and DemConfigSet. This application will first look into the DemGeneral container, before configuring DemConfigSet which has the bulk of our configurations.
Dem Configuration
Once the DEM module has been created, open it within the BSW Editor. Then to begin, navigate to the DemGeneral container and start configuring these parameters:
DemEventMemorySet
Following these configurations, navigate within the DemGeneral container to create the DemEventMemorySet:
Within the DemEventMemorySet container, there are further attributes that can be configured. For the purpose of this workflow, navigate to the DemPrimaryMemory container:
Here configure the following parameters:
DemClient
After configuring the general parameters and EventMemorySet, the next step is to create a client that will have access to DEM through it's APIs. To do this, navigate to the DemClient container within DemGeneral:
Then configure the DemClient as shown below:
Here is a brief description of each attribute configure and their purpose:
DemOperationCycles
Navigate to the DemOperationCycles container within DemGeneral.
An operation cycle within DEM is the duration between two time points. An operation cycle has start and end points, during which diagnostic Monitors check for a diagnostic event periodically. Configure this operation cycle as follows:
DemRbGeneral
After configuring the DemOperationCycle, configure the DemRbGeneral container. To do this, navigate to the DemRbGeneral tab:
This will show a long list of attributes to configure, below are the essential configurations made for this workflow:
DemDataElementClass
At this point within the workflow, DemGeneral has been configured, though there are further containers found in this element which require configuration. However, these further configurations directly influence the DTCs that will be configured for this project. To begin, navigate within DemGeneral to container DemDataElementClass:
DemDataElementClass is a container for internal/external data element classes, and provides three possible implementations: DemExternalCSDataElementClass, DemExternalSRDataElementClass and DemInternalDataElementClass. DemExternalCSDataElementClass contains configuration for an external client/server based data element, while DemExternalSRDataElementClass contains the same but based on sender/receiver ports.
Within our project, we will be configuring three DemDataElementClass'. Two external client/server data element classes and one internal class. Starting with the first external class, select the DemExternalCSDataElementClass within the DemDataElementClass container:
Then configure this class "DemDataElementClass_EngineSpeed" as follows:
After configuring this class, create another external client/server class "DemDataElementClass_VehicleSpeed" as follows:
Finally create the internal class "DemDataElementClass_Aging_Counter":
DemExtendedDataRecordClass
Extended Data Records (EDRs) are used to store additional information related to a diagnostic event, with the ability to contain multiple data fields (DemDataElementClass) that are specific to a type of diagnostic event. Within this project, it will be used to represent our aging counter. To do this, navigate to the DemExtendedDataRecordClass within DemGeneral:
Name the new EDR "ExtRec_AgingCounter" and configure it as follows:
DemExtendedDataClass
The Extended Data Class contains combinations of extended data records, grouping them. And represents event related data, as diagnostic events can contain up to one set of extended data records, the same goes for freeze frame records. To create an extended data class from the EDR created, navigate to DemExtendedDataClass within DemGeneral:
This container should be configured as follows for the aging counter:
DemDidClass
With the two remaining DemDataElementClass's, they will be used to configure Diagnostic Data Identifiers (DIDs). As discussed in the functional overview: DIDs are identifiers for accessing data associated with a diagnostic event, corresponding to specific pieces. To create a DemDidClass navigate to the container in DemGeneral:
Here set the identifier to be used for accessing the DemDataElementClass referenced as configured below:
Repeat this for the DemDataElementClass_VehicleSpeed:
DemFreezeFrameClass
Freeze Frames allow the capture and storage of values at specific moments in time during a diagnostic event. It's purpose is to provide a 'snapshot' of the systems state at the discovery of a diagnostic event. The DemFreezeFrameClass is typically implemented as a data structure storing values of multiple parameters; as it will be in this project. To do so, navigate to the DemFreezeFrameClass container within DemGeneral:
Naming the DemFreezeFrameClass "Set1_Freeze" configure it as follows, including the references to the 2 previously created DIDs:
DemNvRamBlockId
DEM module typically uses non volatile memory to store diagnostic event related data. Thus the blocks of Nv-Memory used by DEM must also be configured in NvM. Please note that this is only a typical situation but DEM can also be configured to use RAM only. This example, as most of cases, uses permanent memory; so, NvM blocks must be configured.
NB: to compute the BlockLength parameter to bet set for each Block Descriptor consider the following:
- For each EventStatusByte BlockDescriptor the size must be equal to the number of diagnostic events configured in DEM plus one
- For each Eventmemorylocation Block Descriptor the size depends on the configuration of some parameters, refer to structure ‘Dem_EvMemEventMemoryType’ to compute the size
Then go back to DEM configuration and set the references to these NvMBlockDescriptors creating the DemNvRamBlockId containers as shown:
Below are the four DemNvRamBlockId's for this project:
DemDebounceCounterBasedClass
Now that the DemGeneral containers are all configured, the next configurations within the DEM module are located in the DemConfigSet container. The first to be configured here: DemDebounceCounterBasedClass. Earlier, it was configured if a counter-based or timer-based debounce feature was to be used, within this project the counter-based debounce was chosen. Therefore, navigate to the DemDebounceCounterBasedClass container:
To configure this container, here are the attributes used in this project to create our debounce feature:
DemDTCAttributes
The DemDTCAttributes container holds attributes associated with a Diagnostic Trouble Code (DTC) such as severity, functional unit, and the status of the DTC. It is an essential part of the DEM module and is required for building a functioning DTC. Navigate to the DemDTCAttributes container within DemConfigSet:
Here create a DemDTCAttribute with the following parameters:
DemDTC
The DemDTC container stores information about each DTC, including its status, the functional unit associated with the fault, and the severity of the problem. To have a DTC within our project, it must be configured here. Navigate to the DemDTC container within DemConfigSet:
Here create a DTC with the following parameters:
DemComponents
The DemComponent holds information about the various components or sub-systems within a vehicle that can generate DTCs. Each component/sub-system is represented by a unique DemComponent record; the information stored includes: the name of the component, it's type, and the events or conditions that can trigger a DTC. To create a DemComponent navigate to its container within DemConfigSet:
Here create a DemComponent in accordance to the following parameters:
DemEventParameter
The DemEventParameter holds information about the parameters associated with an event that can trigger a DTC. This is required to link a DTC to a DemComponent and an operation cycle. To create one, navigate to DemEventParameter within DemConfigSet:
Here create an event parameter using the following parameters:
After creating this DemEventParameter assign the previously created Debounce Class:
BswM Configuration
After configuring the DEM module, it must be included into the BswM module to allow it to initialise on startup. To do this navigate to the BswM module in BSW Modules → Mode Mgm:
Action Item(s)
Open the module using the BSW Editor, then navigate to the BswMConfig container. Here are three further containers for BswM configuration, our interests lie within BswMModeControl. There will be attributes known as BswMActionLists and BswMActions, these are required to allow DEM to initialise. Start by creating a BswMAction as this will later be added to a BswMActionList which is ran at runtime:
Within this container, create a new BswMAction for both "BswM_AI_Dem_Init" and "BswM_AI_DemShutdown" and set their callout functions as follows:
Action List Item(s)
After creating the Action Items, it is time to implement them into an action list. Navigate back to the container: BswMActionLists and follow to the action list BswM_AL_BswModules_InitListReadAll. Within this container add the new init action item BswM_AI_Dem_Init as shown:
Complete the same for the shutdown action item BswM_AI_DemShutdown but within the BswM_AL_Shutdown
EcuM Configuration
The DEM module shall distinguish between a pre-initialization mode and a full-initialized mode (operation mode). The function Dem_PreInit shall initialize the internal states of the DEM module necessary to process events and reset debounce counters reported by BSW modules. Add this function to the EcuM initialization list one as shown below:
DCM Configuration
As said in the introduction to this AN, UDS 0x19 service will be used to read Diagnostic Event memory. To do this, edit the DcmDsdServiceTable and add the new Service by setting its identifier; configuring the diagnostic session during which it will be available and the sub-service availability:
In a similar way, configure the needed sub-services; in this case sub-services 4, 6 and 10 have been configured:
As last, switch to Dcmdsp and create a new container of type DcmRbDspReadDTC and set the maximum number of DTC that can be read within a single request as well as the maximum number of records:
BSW Generation
Now to generate the BSW code:
Make sure DEM is selected in the generator: