Parameter Tuning and Signal Logging over Serial Communication and CAN Calibration Protocol (CCP)

Warning

Support for Monitor & Tune (External mode) with Communication interface as Serial and CAN Calibration Protocol (CCP) will be removed in a future release of MATLAB^®. It is recommended that you use Monitor and Tune with Communication interface as XCP on Serial and XCP on CAN.

With Monitor & Tune (External Mode), you can log signals and tune parameters while the model is running on the target hardware in real time. When you change parameter values from within Simulink, the modified parameter values are communicated to the target hardware immediately. Also, you can monitor the effects of the parameters tuning activity by viewing the algorithm signals on the scopes.

You can run your model on the external mode via two communication interfaces, serial or CAN.

For external mode with serial communication, you have a ready-to-use COM port on the USB drive if your target hardware supports it or the COM1 port on your computer with RS–232 cable. For more information on how to set up serial communication, see Set Up Serial Communication with Target Hardware. You can configure the external mode for different baud rates that your communication interface supports.
To run your model in external mode with CAN Calibration Protocol(CCP), use the CAN Calibration Protocol block and a Vector CAN case hardware. External mode uses the eCAN module to run external mode. You can configure the external mode with any available eCAN module. For more information, see Set Up CAN Communication with Target Hardware. You can configure the baud for eCAN.

Each communication interface (serial and CAN) has this protocol:

Classic External Mode
In this method, you will setup Serial communication between Simulink^® and Texas Instruments™ C2000 board to tune the parameters and monitor the signal of an algorithm running on the board.

Note
Classic External mode provides complete backward compatibility.

Monitor and Tune over Serial Communication

To prepare your model for external mode/PIL with serial communication, refer Serial Configuration for External Mode and PIL

Your model is now ready to perform Monitor and Tune action (External Mode) over serial communication.

To perform the Monitor and Tune action :

Open the Model.
Go to theHardware tab and click Monitor & Tune.
For more information, see Parameter Tuning and Signal Logging with Serial Communication

Note

For targets with small RAM such as F28027, the code has to be booted from flash. To boot the code from flash, select TI Piccolo F2802x (boot from flash) in Hardware Implementation > Hardware board drop-down list
Parameter tuning and signal logging for 8-bit data type is not supported in external mode over serial

Monitor and Tune over CCP

You can tune parameters and log signals (External Mode) using Simulink external mode with CCP. For signal logging and parameter tuning with a third-party calibration tool, see CAN Calibration Protocol with Third Party Tools.

The external mode is supported using the CAN Calibration Protocol block and ASAP2 interface. The ASAP2 interface is used to get information about where a parameter or signal exists in the target memory. The CAN Calibration Protocol block is used to communicate with the target, download parameter updates, and upload signal information.

To prepare your model for external mode over CCP, perform these tasks:

To set up external mode, see Set Up Your Model for External Mode.
To run your model in external mode with ert.tlc, see Monitor and Tune Your Model (External Mode).
To tune your parameters, see Tuning Parameters.

For more information, see:

Set Up Your Model for External Mode

Add a CCP driver block to your model from the Simulink Block Library.
Identify signals that you want to tune. Associate them with Simulink.Parameter or canlib.Parameter objects with ExportedGlobal storage class. Set the data type and value of the object. See Using Supported Objects and Data Types.
Identify signals you want to log. Associate them with canlib.Signal objects. Set the data type of the canlib.Signal. See Using Supported Objects and Data Types.
For information about visualizing logged signal data, see Viewing and Storing Signal Data.
Load the Simulink.Parameter or canlib.Parameter and canlib.Signal data objects into the base workspace.
Select Simulation > Model Configuration Parameters.
In the Configuration Parameters dialog box, select Optimization > Signals and Parameters pane.
Select Default parameter behavior > Inlined and click Configure.
In the Model Parameter Configuration dialog box that opens, define the (global) tunable parameters for your models.
In the Configuration Parameters dialog box, select Code Generation > Interface pane.
Set the Interface parameter to ASAP2.

Monitor and Tune Your Model (External Mode)

Note

Ensure the communication interface is set to CAN (Configuration Parameters > Hardware Implementation > External mode > Communication interface), before performing Monitor & Tune action.

To perform Monitor & Tune action :

Open the Model.
Go to the Hardware tab and click Monitor & Tune.
Your model now runs in the external mode over CCP.

Configuring the Host Vector CAN Application Channel

For external mode, the host-side CAN connection must use the 'MATLAB 1' application channel. To configure the application channel that the Vector CAN drivers use, in the Command Window:

TargetsComms_VectorApplicationChannel.configureApplicationChannels

Use this tool to configure your host-side CAN channel settings.

If you try to connect using an application channel other than 'MATLAB 1', you see the following warning:

Warning:
It was not possible to connect to the target using CCP. 
An error occurred when issuing the CONNECT command.

If you have not already installed the Vector CAN drivers, you get the following error message in the command window:

??? Error using ==>
TargetsComms_VectorApplicationChannel.TargetsComms_VectorApplicationChannel>
TargetsComms_VectorApplicationChannel.configureApplicationChannels at 40
Unable to launch the application channel configuration utility. 
The "vcanconf" utility was not found on the Windows System Path. 
To fix this error, make sure the required CAN drivers are installed on this computer;
refer to the product documentation for details.

If you want to use CAN to transmit or receive CAN messages between your host PC and your target, you need VN1600 supported by the Vector CAN Driver Library. Choose the driver libraries to support profiling, downloading, and external mode. Make sure that the library, vcand32.dll, is placed in the Windows^® system32 folder.

Using Supported Objects and Data Types

Supported objects are:

Simulink.Parameter or canlib.Parameter for parameter tuning
canlib.Signal for signal logging

Supported data types are:

uint8, int8
uint16, int16
uint32, int32
single

Define data objects for the signals and parameters of interest for ASAP 2 file generation. For ease of use, create a MATLAB file to define the data objects so that you only have to set up the objects only once.

To set up tunable parameters and signal logging:

Associate the parameters that you want to tune with Simulink.Parameter or canlib.Parameter objects with ExportedGlobal storage class. It is important to set the data type and value of the parameter object. For an example of how to create such a Simulink.Parameter object for tuning, see the following code:
```
stepSize = Simulink.Parameter;
stepSize.DataType = 'uint8';
stepSize.CoderInfo.StorageClass = 'ExportedGlobal';
stepSize.Value = 1;
```
Associate the signals that you want to log with canlib.Signal objects.Set the data type of the canlib.Signal. The following code example shows how to declare such a canlib.Signal object for logging.
```
counter = canlib.Signal;
counter.DataType = 'uint8'; 
```
Associate the data objects that you defined in the MATLAB file with parameters or signals in the model. For the previous code examples, you can set the Constant value in a Source block to stepSize, and set a Signal name to counter in the Signal Properties dialog box. stepSize and counter are the data objects defined in the code.

Tuning Parameters

In the workspace, set dataobject.value while the model is running in external mode. For example, to tune the parameter stepSize (that is, to change its value) from 1 to 2, at the command line, enter:
```
stepSize.value = 2
```
You see output similar to the following:
```
stepSize = 

  Parameter with properties:

          Value: 2
      CoderInfo: [1×1 Simulink.CoderInfo]
    Description: ''
       DataType: 'uint8'
            Min: []
            Max: []
           Unit: ''
     Complexity: 'real'
     Dimensions: [1 1]
```
Update the model (press Ctrl+D) to apply the changed parameter.

Viewing and Storing Signal Data

To view the logged signals, attach a supported scope type to the signal.

To customize the signals that are logged:

In the Simulink Editor, select Hardware pane > Control Panel.
In External Mode Control Panel, click Signal & Triggering.
In External Signal & Triggering box, clear the check boxes for scope data that you do not want to log.

Storing signal data for further analysis. You can further analyze the logged data in MATLAB.

To use the data archiving in external mode, in the External Mode Control Panel, click Data Archiving.
1. In the Enable Data Archiving dialog box, select the check box Enable archiving.
2. Edit the Directory and File fields. Review the other settings.
3. Click Apply and close the dialog box.
Open the Scope parameters by clicking the scope parameters icon in the scope window toolbar.
Select the check box Save data to workspace.
In the Variable name field, edit the variable name. The data that is displayed in the scope at the end of the external mode session is available in the workspace with this variable name.
The data that was previously displayed in the scope is stored in .mat files.
For example, at the end of an external mode session, the following variable and files are available in the workspace and the current folder:
- A variable ScopeData5 with the data currently displayed on the scope:
```
ScopeData5

ScopeData5 = 

         time: [56x1 double]
      signals: [1x1 struct]
    blockName: 'c28x_ccp_ert/Scope1'
```
- In the current folder, .mat files for the three previous durations of scope data:
```
ExternalMode_0.mat  
ExternalMode_2.mat  
ExternalMode_1.mat
```

CAN Calibration Protocol with Third Party Tools

Embedded Coder^® allows an ASAP2 data definition file to be generated during the code generation process. This file can be used by a third-party tool to access data from the real-time application while it is executing.

ASAP2 is a data definition standard by the Association for Standardization of Automation and Measuring Systems (ASAM). ASAP2 is a standard description for data measurement, calibration, and diagnostic systems. Embedded Coder software lets you export an ASAP2 file containing information about your model during the code generation process.

The build process creates an ASAM-compliant ASAP2 data definition file for the generated C code.

The standard ASAP2 file generation does not include the memory address attributes in the generated file. Instead, it leaves a placeholder that you must replace with the actual address by postprocessing the generated file.

The map file options in the project template has to be set up a certain way for this procedure to work. If you have created your own project templates, and you do not have the correct settings, you see the following instructions:

Warning: It was not possible to do ASAP2 processing on your
.map file.This is because your IDE project template is not 
configured to generate a .map file in the correct format.
To generate a .map file in the correct format you need to 
setup the following options in your IDE project template:
Generate section map should be checked on
Generate register map should be checked off
Generate symbol table should be checked on
Format list file into pages should be checked off
Generate summary should be checked off
Page width should be equal to 132 characters
Symbol colums should be 1
You can change these options via Project -> Project Options
 -> Linker/Locator -> Map File -> Map File Format.

Embedded Coder software performs this postprocessing for you. To do the postprocessing, it first extracts the memory address information from the map file generated during the link process. Then, it replaces the placeholders in the ASAP2 file with the actual memory addresses. This postprocessing is performed automatically.

Limitations

Multiple signal sinks (for instance, scopes) are not supported.
Only the following kinds of scopes are supported with external mode logging:
- Simulink Scope block
- Simulink Display block
- Viewer type: scope — To use this option in your model, right-click a signal in the model, and select Create & Connect Viewer > Simulink > Scope. The other scope types listed are not supported (for instance, floating scope).
  Before connecting to external mode, right-click the signal and select Signal Properties. In the dialog box, select the Test point check box, and click OK.
- GRT is supported only for parameter tuning.

Logging signal at very high sample rates I.e. greater than 10 kHz results in data loss.
Top-level builds are supported for external mode. Subsystem builds are not supported for external mode.
Logging and tuning of nonscalars is not supported. It is possible to log nonscalar signals by breaking down the signal into its scalar components. For an example of how to do this signal deconstruction, see the CCP example models, which use a Demux and Signal Conversion block with contiguous copy.
Logging and tuning of complex numbers is not supported. It is possible to work with complex numbers by breaking down the complex number into its real and imaginary components. You can perform this breakdown using the following blocks in the Simulink Math Operations library: Complex to Real-Imag, Real-Imag to Complex, Magnitude-Angle to Complex, and Complex to Magnitude-Angle.
External Mode fails to connect To File block due to memory constraint.