Create and Run Tests Using the ASAM XIL Standard

The Simulink^® Test™ Support Package for ASAM^® XIL Standard implements the ASAM XIL API, which is a standard that defines communication between test automation tools, such as Simulink Test, and test benches, such as Simulink Real-Time™, third-party test benches, and Simulink model simulation test benches. You can use the ASAM XIL API to run real-time hardware-in-the-loop (HIL), software-in-the-loop (SIL), and model-in-the-loop test cases and Simulink simulations created in Simulink Test using its XIL framework. The framework includes methods for mapping variables from the test code to the test bench, configuring the ports to use, specifying the test bench startup and shutdown order, and other commands to query and control the test bench

The steps for creating a test that uses the Simulink Test Support Package for ASAM XIL Standard are:

Install the support package and set up the test bench and your model. See Install and Set Up the Simulink Test Support Package for ASAM XIL Standard.
Configure the Test Bench.
Create the Test Body.
Run the Test.

To use more than one test bench, repeat the set up process and configure the test bench tasks for each test bench. For detailed examples, see Create ASAM XIL Test with Two Test Benches.

Configure the Test Bench

Follow these steps to configure the test bench port, add the port to the Simulink Test ASAM XIL framework, and map variables from the model to the test bench variables. You can include the code for these steps in the same file as the test body. See Create the Test Body.

Create an instance of the sltest.xil.framework.Framework class. Use only one Framework object at a time.
```
frm = sltest.xil.framework.Framework;
```
For tests using third-party test benches, use the displayAvailableTestbenches method of sltest.xil.framework.Framework to obtain the names of the available test benches.
Create an XML port configuration file. You can use any name for the file, but it must use the .xml file extension. The configuration options depend on the test bench. Replace the product version number shown in the sample port configuration file with the version you have. Sample port configuration files are:
- Simulink Real-Time
  Use createPortConfigureFile (Simulink Real-Time) to create the file.
- NI™ VeriStand
```
<?xml version="1.0" encoding="UTF-8"?>
<NIVSPortConfig>
   <Version Major="2020" Minor="4" Fix="0" Build="0"/>
   <Project>C:\NIProjects\Project.nivsproj</Project>
</NIVSPortConfig>
```
- dSPACE^®
```
<?xml version="1.0" encoding="utf-8"?>
<PortConfigurations 
   xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
   <MAPortConfig>
      <SystemDescriptionFile>
         C:\DSPACEProjects\smd_1104_sl.sdf
      </SystemDescriptionFile>
      <PlatformName>DS1104</PlatformName>
   </MAPortConfig>
</PortConfigurations>
```
- Simulink model simulation
  Use sltest.xil.testbench.createMAPortConfigFile to create the file.

Add the port to use with the Simulink Test ASAM XIL framework. See Create Tests That Use Third-Party Test Benches or Create Tests Using Simulink Model Simulation as a Test Bench for where to include this code in the MATLAB^® code file that contains the test body. Replace the product version number shown in the appropriate sample port file with the version you have.

You can use frm.Configuration to display a summary of your configuration.

Simulink Real-Time

To use all of the Simulink Real-Time functionality, add all three ports.

frm.Configuration.addModelAccessPort(...
   'MAPort', ...
   'asamxil.v2_1', ...
   'VendorName','MathWorks', ...
   'ProductName','XIL API', ...
   'ProductVersion','1.0', ...
   'PortConfigFile',fullfile(pwd,'myConfigureFile.xml'));
frm.Configuration.addECUCalibrationPort(...
   'ECUCPort', ...
   'asamxil.v2_1', ...
   'VendorName','MathWorks', ...
   'ProductName','XIL API', ...
   'ProductVersion','1.0', ...
   'PortConfigFile',fullfile(pwd,'myConfigureFile.xml'),...
   'TargetState','started');
frm.Configuration.addECUMeasurementPort(...
   'ECUMPort', ...
   'asamxil.v2_1', ...
   'VendorName','MathWorks', ...
   'ProductName','XIL API', ...
   'ProductVersion','1.0', ...
   'PortConfigFile', fullfile(pwd,'myConfigureFile.xml'));

NI™ VeriStand

frm.Configuration.addModelAccessPort(...
  'MAPort1',...
  'asamxil.v2_1', ... 
  'VendorName','National Instruments', ... 
  'ProductName','NI VeriStand ASAM XIL Interface',... 
  'ProductVersion','2020', ... 
  'PortConfigFile',fullfile(pwd,'NIVeriStandPortConfig.xml'));

dSPACE

frm.Configuration.addModelAccessPort(...
   'MAPort1', ...
   'asamxil.v2_1', ...
   'vendorName','dSPACE GmbH', ...
   'productName','XIL API', ...
   'productVersion','2021-A', ...
   'portConfigFile',fullfile(pwd,'dSpaceConfig.XML'));

Simulink model simulation

frm.Configuration.addModelAccessPort...
     ('MAPort1','asamxil.v2_1',...
     'VendorName','MathWorks',...
     'ProductName','Simulation Server XIL API',...
     'ProductVersion','1.0.0.0', ...
     'PortConfigFile',MAPortConfigFile);

Map the test variable names used in the test to the test bench variable names for the specified test bench. Optionally, also specify the task (that is, the logging rate) for the variables. To display the available test bench variable IDs, use the displayAllTestbenchVariables method of the sltest.xil.framework.Framework class. To view the associated tasks, use the displayAllTaskInfo method. See Create Tests That Use Third-Party Test Benches for where to include this code in the MATLAB code file with the test body.
- This example maps the RPM test variable name to the Targets/Controller/Simulation Models/Models/simple_R2020a_2/Outports/Out3 test bench variable name.
  frm.Configuration.addTestVariableMapping(... 'RPM','MAPort1',... ['Targets/Controller/Simulation Models/Models'... '/simple_R2020a_2/Outports/Out3']);

Create the Test Body

Write the test body in a MATLAB code file. If you write the test body as a function, you can call it from functions that define different configurations. The test body steps are independent of a test bench. After you define the test body, you use it as-is with any test bench configuration.

The test body typically includes these steps:

Use init to initialize the test bench.
Instantiate the mapped test variables so you can use them in the rest of the test body.
Tune parameters in the model to desired values for your test. You can change these values at any time, but if you change values in the middle of the test, the timing is not deterministic.
Set up the acquisition and start it.
At any point, if desired, call the sltest.TestCase methods, such as sltest.TestCase.verifyThat, to determine the pass or fail status of the test case.
Wait for acquisition or simulation to complete, or stop the simulation using the stop method.
Fetch the logged data.
Push the logged data results to the Test Manager. Only push the logged data if you plan to run your test using the Test Manager.

Run the Test

After you configure the test bench and write the test body, run your test in the Test Manager or at the command line.

The MATLAB code file inherits from sltest.TestCase, which enables you to open and run the MATLAB code test file in the Test Manager. In the test body code, you can include pushing the logged data results to the Test Manager, and then load the file into the Test Manager using Open > Open MATLAB-Based Simulink Test (.m). Then, run the test like you run other test cases in the Test Manager.
You can run your code at the MATLAB command line, however you cannot push data to the Test Manager from the command line.

Perform additional analysis on the logged data, such as using the verifySignalsMatch method to compare the results to the baseline data.

Limitations

These limitations of the ASAM XIL standard apply when doing real-time testing using the Simulink Test Support Package for ASAM XIL Standard.

The ASAM XIL standard does not provide support for
- Setting the stop time of the model. On some test benches, simulation stops at the stop time the model was built with. Other test benches force the stop time to be Inf.
- Verifying results. Use the verify methods from sltest.TestCase to analyze your captured data.
- Enumerated, fixed point, or bus data types.
On some test benches, logging does not start at the same time as simulation starts. This timing difference might cause your tests to not be precisely repeatable. Use an Acquisition trigger to repeatedly capture a region of interest in the logged data. The trigger corresponds to t = 0.

When using a Simulink model simulation as the test bench, these additional limitations apply:

- Variables in data dictionaries, cell arrays, bus signals, structures, and Simulink.VariantExpression objects do not appear in the MAPort variable list.
- If your model logs a large amount of data for an extended period of time, a memory overflow might occur, especially if simulation pacing is off. One way to avoid this issue is to turn off logging for large signals, such as matrices, and only log the minimum amount of signal data. Additionally, you can specify a simulation stop time, or if your model stop time is set to infinity, turn simulation pacing on.
  Another way to control memory overflows is to limit the number of logged data points by using <MaxLoggedDataPoints>. When you set a value for the maximum number of logged data points, the MaxDataPoints and DataLoggingMaxPoints model settings update to that value. Any data lost due to these settings is not available using ASAM XIL capture or acquisition.
  Memory overflows can occur when logging large amounts of data in any Simulink model. These overflows are not specific to using ASAM XIL with Simulink as the test bench.
- Models that use variable-step solvers are not supported.

Troubleshooting

You can display information about available test benches, variables, and tasks by using these sltest.xil.framework.Framework methods:

displayAllAvailableTestbenches
displayAllTestbenchVariables
displayAllTaskInfo

External Websites

ASAM XIL