Export ASAP2 File for Data Measurement and Calibration

The ASAM MCD-2 MC standard, also known as ASAP2, is a data definition standard proposed by the Association for Standardization of Automation and Measuring Systems (ASAM). ASAP2 is a non-object-oriented description of the data used for measurement, calibration, and diagnostic systems. For more information on ASAM and the ASAM MCD-2 MC (ASAP2) standard, see the ASAM Web site at https://www.asam.net.

The code generator lets you export an ASAP2 file containing information about your model during the code generation process.

You can run an interactive example of ASAP2 file generation. To open the example at the MATLAB® command prompt, enter the following command:

rtwdemo_asap2

Note

Simulink® Coder™ support for ASAP2 file generation is version-neutral. By default, the software generates ASAP2 version 1.31 format, but the generated model information is generally compatible with other ASAP2 versions. ASAP2 file generation also is neutral with respect to the specific needs of ASAP2 measurement and calibration tools. The software provides customization APIs that you can use to customize ASAP2 file generation to generate an ASAP2 version and to meet the specific needs of your ASAP2 tools.

What You Should Know

To make use of ASAP2 file generation, you should become familiar with the following topics:

Targets Supporting ASAP2

You can use ASAP2 file generation varying system target file configurations. For example,

  • Generic Real-Time Target (grt.tlc) lets you generate an ASAP2 file as part of the code generation and build process.

  • Embedded Coder (ert.tlc) system target file selections also let you generate an ASAP2 file as part of the code generation and build process.

  • ASAM-ASAP2 Data Definition Target (asap2.tlc) lets you generate only an ASAP2 file, without building an executable program.

Procedures for generating ASAP2 files by using these target configurations are given in Generate an ASAP2 File.

Define ASAP2 Information

Define ASAP2 Information for Parameters and Signals

The ASAP2 file generation process requires information about parameters and signals in your model. Some of this information is contained in the model itself. You must supply the rest by using Simulink data objects in a workspace or data dictionary. In some cases, the use of workspace objects is optional.

Use the Model Data Editor and built-in Simulink data objects to provide the information. For example, you can use Simulink.Signal objects to provide MEASUREMENT information and Simulink.Parameter objects to provide CHARACTERISTIC information. Also, you can use data objects from data classes that are derived from Simulink.Signal and Simulink.Parameter to provide the information. For information about data objects, see Data Objects (Simulink). For information about the Model Data Editor, see Configure Data Properties by Using the Model Data Editor (Simulink).

The following table contains the minimum set of data attributes required for ASAP2 file generation. Some data attributes are defined in the model; others are supplied in the properties of objects. For attributes that are defined in Simulink.Signal or Simulink.Parameter objects, the table gives the associated property name.

Data Attribute

Defined In

Property Name

Name (symbol)

Model and data object

Inherited from the handle of the data object to which parameter or signal name resolves

Description

Data object

Description

Data type

Model or data object

DataType

Scaling
(if fixed-point data type)

Model or data object

DataType

Minimum allowable value

Model or data object

Min

Maximum allowable value

Model or data object

Max

Unit

Model or data object

Unit

Memory address (optional)

Model or data object

MemoryAddress_ASAP2 (optional; see Memory Address Attribute.)

Memory Address Attribute

If the memory address attribute is unknown before code generation, the code generator inserts ECU Address placeholder text in the generated ASAP2 file. You can substitute an actual address for the placeholder by postprocessing the generated file. See the file matlabroot/toolbox/rtw/targets/asap2/asap2/asap2post.m for an example. asap2post.m parses through the linker map file that you provide and replaces the ECU Address placeholders in the ASAP2 file with the actual memory addresses. Since linker map files vary from compiler to compiler, you might need to modify the regular expression code in asap2post.m to match the format of the linker map you use.

Note

If Embedded Coder is licensed and installed on your system, and if you are generating Executable and Linkable Format (ELF) or Program Database (PDB) files for your embedded target, you can use the rtw.asap2SetAddress function to automate ECU address replacement. For more information, see Automatic ECU Address Replacement for ASAP2 Files (Embedded Coder).

If the memory address attribute is known before code generation, it can be defined in the data item or data object. By default, the MemoryAddress_ASAP2 property does not exist in the Simulink.Signal or Simulink.Parameter data object classes. If you want to add the attribute, add a property called MemoryAddress_ASAP2 to a custom class that is a subclass of the Simulink or ASAP2 class. For information on subclassing Simulink data classes, see Define Data Classes (Simulink).

The following table indicates the Simulink object properties that have replaced the ASAP2 object properties of the previous release:

Differences Between ASAP2 and Simulink Parameter and Signal Object Properties

ASAP2 Object Properties (Previous)

Simulink Object Properties (Current)

LONGID_ASAP2

Description

PhysicalMin_ASAP2

Min

PhysicalMax_ASAP2

Max

Units_ASAP2

Unit

Automatic ECU Address Replacement for ASAP2 Files (Embedded Coder)

If Embedded Coder is licensed and installed on your system, and if you are generating Executable and Linkable Format (ELF) or Program Database (PDB) files for your embedded target, you can use the rtw.asap2SetAddress function to automate the replacement of ECU Address placeholder memory address values with actual addresses in the generated ASAP2 file.

If the memory address attribute is unknown before code generation, the code generator inserts ECU Address placeholder text in the generated ASAP2 file, as shown in the example below.

/begin CHARACTERISTIC
  /* Name            */ Ki
  /* Long Identifier */ ""
  /* Type            */ VALUE
  /* ECU Address     */ 0x0000 /* @ECU_Address@Ki@ */

To substitute actual addresses for the ECU Address placeholders, process the generated ASAP2 file using the rtw.asap2SetAddress function. The general syntax is as follows:

rtw.asap2SetAddress(ASAP2File,InfoFile)

The arguments are character vectors specifying the name of the generated ASAP2 file and the name of the generated executable ELF file, PDB file from Microsoft toolchain, or DWARF debug information files for the model. When called, rtw.asap2SetAddress extracts the actual ECU address from the specified ELF, PDB, or DWARF file and replaces the placeholder in the ASAP2 file with the actual address, for example:

/begin CHARACTERISTIC
  /* Name            */ Ki
  /* Long Identifier */ ""
  /* Type            */ VALUE
  /* ECU Address     */ 0x40009E60

Define ASAP2 Information for Lookup Tables

Simulink Coder software generates ASAP2 descriptions for lookup table data and its breakpoints. The software represents 1-D table data as CURVE information, 2-D table data as MAP information, and breakpoints as AXIS_DESCR and AXIS_PTS information. You can model lookup tables using one of the following Simulink Lookup Table blocks:

  • Direct Lookup Table (n-D) — 1 and 2 dimensions

  • Interpolation Using Prelookup — 1 and 2 dimensions

  • 1–D Lookup Table

  • 2–D Lookup Table

  • n-D Lookup Table — 1 and 2 dimensions

The software supports the following types of lookup table breakpoints (axis points):

Breakpoint TypeGenerates
Tunable and shared among multiple table axes (common axis)

COM_AXIS

Fixed and nontunable (fixed axis)

One of these variants of FIX_AXIS:

  • FIX_AXIS_PAR if breakpoints are integers with equidistant spacing and the equidistant spacing is a power of two

  • FIX_AXIS_PAR_DIST if breakpoints are integers with equidistant spacing

  • FIX_AXIS_PAR_LIST if breakpoints are integers with non-equidistant spacing

Tunable but not shared among multiple tables (standard axis)

STD_AXIS

When you configure the blocks for ASAP2 code generation:

  • For table data, use a Simulink.Parameter data object with a non-Auto storage class.

  • For tunable breakpoint data that is shared among multiple table axes (COM_AXIS), use a Simulink.Parameter data object with a non-Auto storage class.

  • For fixed, nontunable breakpoint data (FIX_AXIS), use workspace variables or arrays specified in the block parameters dialog box. The breakpoints should be stored as integers in the code, so the data type should be a built-in integer type (int8, int16, int32, uint8, uint16, or uint32), a fixed-point data type, or an equivalent alias type.

  • For tunable breakpoint data that is not shared among multiple tables (STD_AXIS):

    1. Create a Simulink.Bus object to define the struct packaging (names and order of the fields). The fields of the parameter structure must correspond to the lookup table data and each axis of the lookup table block. For example, in an n-D Lookup Table block with 2 dimensions, the structure must contain only three fields. This bus object describes the record layout for the lookup characteristic.

    2. Create a Simulink.Parameter object to represent a tunable parameter.

    3. Create table and axis values.

    4. Optionally, specify the Units, Minimum, and Maximum properties for the parameter object. The properties will be applied to table data only.

Here is an example of an n-D Lookup Table record generated into an ASAP2 file in Standard Axis format:

/begin CHARACTERISTIC
  /* Name */  STDAxisParam
  ...
  /* Record Layout */   Lookup1D_X_WORD_Y_FLOAT32_IEEE
  ...
  begin AXIS_DESCR
    /* Description of X-Axis Points */
    /* Axis Type */      STD_AXIS
    ...
  /end AXIS_DESCR
/end CHARACTERISTIC

/begin RECORD_LAYOUT Lookup1D_X_WORD_Y_FLOAT32_IEEE
  AXIS_PTS_X 1 WORD INDEX_INCR DIRECT
  FNC_VALUES 2 FLOAT32_IEEE COLUMN_DIR DIRECT
/end   RECORD_LAYOUT

Note

The example model rtwdemo_asap2 illustrates ASAP2 file generation for Lookup Table blocks, including both tunable (COM_AXIS) and fixed (FIX_AXIS) lookup table breakpoints.

Generate an ASAP2 File

About Generating ASAP2 Files

You can generate an ASAP2 file from your model in one of the following ways:

  • Use the Generic Real-Time Target or a Embedded Coder target to generate an ASAP2 file as part of the code generation and build process.

  • Use the ASAM-ASAP2 Data Definition Target to generate only an ASAP2 file, without building an executable.

This section discusses how to generate an ASAP2 file by using the targets that have built-in ASAP2 support. For an example, see the ASAP2 example model rtwdemo_asap2.

Use GRT or ERT System Target File

The procedure for generating the ASAP2 data definition for a model using the Generic Real-Time Target or Embedded Coder system target file is as follows:

  1. Use the Model Data Editor to apply storage classes to signals, block states, and block parameters as described in Apply Storage Classes to Individual Signal, State, and Parameter Data Elements. Use signal and state names to refer to corresponding MEASUREMENT records and parameter object names to refer to CHARACTERISTIC records.

    Use a storage class other than Auto, FileScope, or, if you set the default storage class of the corresponding data category to Default in the Code Mappings editor (the default setting), Model default. For example, using ExportedGlobal configures the data item as an unstructured global variable in the generated code.

    Note

    Parameters are not represented in the ASAP2 file if one or more of the following conditions exist:

    • You apply storage class Auto, FileScope, or Default (through Model default).

    • You apply a storage class that causes the code generator to generate a macro or non-addressable variable.

  2. Use the Model Data Editor to configure the remaining properties as desired for each data item.

  3. On the Code Generation pane, click Browse to open the System Target File Browser. In the browser, select grt.tlc or an ERT based target file and click OK.

  4. Select model configuration parameter ASAP2 interface.

  5. Select parameter Generate code only.

  6. Click Apply.

  7. Generate code.

    The code generator writes the ASAP2 file to the build folder. By default, the file is named model.a2l, where model is the name of the model. The ASAP2 setup file controls the ASAP2 file name. For details, see Customize Generated ASAP2 File.

Use the ASAM-ASAP2 Data Definition Target

The procedure for generating the ASAP2 data definition for a model using the ASAM-ASAP2 Data Definition Target is as follows:

  1. Use the Model Data Editor to apply storage classes to signals, block states, and block parameters as described in Apply Storage Classes to Individual Signal, State, and Parameter Data Elements. Use signal and state names to refer to corresponding MEASUREMENT records and parameter object names to refer to CHARACTERISTIC records.

    Use a storage class or custom storage class other than Auto, FileScope, or, if you set the default storage class of the corresponding data category to Default in the Code Mapping Editor (the default setting), Model default. For example, using ExportedGlobal configures the data item as an unstructured global variable in the generated code.

    Note

    The data item is not represented in the ASAP2 file if one or more of the following conditions exist:

    • You apply one of the storage classes Auto, FileScope, or Default (through Model default).

    • You apply a custom storage class that causes the code generator to generate a macro or non-addressable variable.

  2. Use the Model Data Editor to configure the remaining properties as desired for each data item.

  3. On the Code Generation pane, click Browse to open the System Target File Browser. In the browser, select asap2.tlc and click OK.

  4. Select model configuration parameter Generate code only.

  5. Click Apply.

  6. Generate code.

    The code generator writes the ASAP2 file to the build folder. By default, the file is named model.a2l, where model is the name of the model. The ASAP2 setup file controls the ASAP2 file name. For details, see Customize Generated ASAP2 File.

Generate ASAP2 Files for Referenced Models

The build process can generate an ASAP2 file for each referenced model in a model reference hierarchy. In the generated ASAP2 file, MEASUREMENT records represent signals and states inside the referenced model.

To generate ASAP2 files for referenced models, select ASAP2 file generation for the top model and for each referenced model in the reference hierarchy. For example, if you are using the Generic Real-Time Target or an Embedded Coder target, follow the procedure described in Use GRT or ERT System Target File for the top model and each referenced model.

Merge ASAP2 Files for Top and Referenced Models

Use function rtw.asap2MergeMdlRefs to merge the ASAP2 files generated for top and referenced models. The function has the following syntax:

[status,info] = rtw.asap2MergeMdlRefs(topModelName,asap2FileName)

  • topModelName is the name of the model containing one or more referenced models.

  • asap2FileName is the name you specify for the merged ASAP2 file.

  • Optional:: status returns false (logical 0) if the merge completes and true (logical 1) otherwise.

  • Optional:: info returns additional information about merge failure if status is true. Otherwise, it returns an empty character vector.

Consider the following example.

[status,info] = rtw.asap2MergeMdlRefs('myTopMdl','merged.a2l')
This command merges the ASAP2 files generated for the top model myTopMdl and its referenced models in the file merged.a2l.

The example model rtwdemo_asap2 includes an example of merging ASAP2 files.

Structure of the ASAP2 File

The following table outlines the basic structure of the ASAP2 file and describes the Target Language Compiler (TLC) functions and files used to create each part of the file:

  • Static parts of the ASAP2 file are shown in bold.

  • Function calls are indicated by %<FunctionName()>.

File Section

Contents of asap2main.tlc

TLC File Containing Function Definition

File header

%<ASAP2UserFcnWriteFileHead()>

asap2userlib.tlc

/begin PROJECT ""

/begin PROJECT "%<ASAP2ProjectName>"

asap2setup.tlc

/begin HEADER ""
HEADER contents

/begin HEADER"%<ASAP2HeaderName>"
%<ASAP2UserFcnWriteHeader()>

asap2setup.tlc
asap2userlib.tlc

/end HEADER

/end HEADER

asap2userlib.tlc

/begin MODULE ""
MODULE contents:

/begin MODULE "%<ASAP2ModuleName>"}

asap2setup.tlc
asap2userlib.tlc

- A2ML
- MOD_PAR
- MOD_COMMON
 ...

%<ASAP2UserFcnWriteHardwareInterface()>

asap2userlib.tlc

Model-dependent MODULE contents:

%<SLibASAP2WriteDynamicContents()>
Calls user-defined functions:

asap2lib.tlc

- RECORD_LAYOUT
- CHARACTERISTIC
- ParameterGroups
- ModelParameters

...WriteRecordLayout_TemplateName()

  ...WriteCharacteristic_TemplateName()
  ...WriteCharacteristic_Scalar()

user/templates/...

- MEASUREMENT
- ExternalInputs
- BlockOutputs

...WriteMeasurement()

asap2userlib.tlc

- COMPU_METHOD

...WriteCompuMethod()

asap2userlib.tlc

/end MODULE

/end MODULE

 

File footer/tail

%<ASAP2UserFcnWriteFileTail()>

asap2userlib.tlc

Create a Host-Based ASAM-ASAP2 Data Definition File for Data Measurement and Calibration

Open Script

This model shows ASAP2 data export. ASAP2 is a data definition standard proposed by the Association for Standardization of Automation and Measuring Systems (ASAM).

Open Example Model

Open the example model rtwdemo_asap2.

open_system('rtwdemo_asap2');

ASAP2 is a non-object-oriented description of the data used for measurement, calibration, and diagnostics systems. For more information on ASAM and the ASAP2 standard, see the ASAM Web site: https://www.asam.net.

ASAP2 data definition is achieved with Simulink® data objects and test point signals. Using the Target Language Compiler (TLC), you can create highly customized solutions for your application. See the Simulink Coder® documentation for details on ASAP2 file generation.

You can configure ASAP2 file generation by selecting ASAP2 interface on the Code Generation > Interface pane of the Configuration Parameters dialog box.

Related Topics

Simulink Coder Documentation
Support