External Mode Simulation by Using XCP Communication

In an external mode simulation, you can tune parameters in real time and monitor target application signals. Using the Run on Custom Hardware app, you can set up and run external mode simulations (Simulink Coder) that use an XCP communication channel.

For an external mode simulation, you:

  1. Build the target application on your development computer.

  2. Deploy the target application to the target hardware.

  3. Connect Simulink® to the target application that runs on the target hardware.

  4. Start execution of generated code on the target hardware.

You can run external mode simulations on your development computer or on custom hardware.

Run XCP External Mode Simulation on Development Computer

Configure and run an external mode simulation (Simulink Coder) that uses the XCP communication protocol. During the simulation:

  • Monitor a signal by using a Scope block, a Dashboard block, and the Simulation Data Inspector.

  • Tune a parameter by using a Dashboard block.

Configure Signal Monitoring and Parameter Tuning for XCP

  1. Create a folder for this example.

    mkdir ext_mode_xcp_example
cd ext_mode_xcp_example

  2. Open Simulink and create a simple model, xcpExample, which contains these blocks:

    • Sine Wave

    • Scope

    • Half Gauge

    • Knob

  3. Double-click the Sine Wave block. Set Sample time to 0.1, and then click OK.

  4. Connect the Sine Wave block to the Scope block and name the connection, for example, Test Signal.

  5. Configure the signal for logging:

    1. Right-click Test Signal.

    2. From the context menu, select Log Selected Signals. If you do not enable signal logging, you cannot view the signal by using the Scope block or stream signal data to the Simulation Data Inspector.

  6. Configure the Half Gauge block to monitor the value of Test Signal:

    1. Double-click the Half Gauge block.

    2. In the Simulink Editor, select Test Signal.

    3. In the Block Parameters dialog box:

      • Connect the block to Test Signal.

      • In the Maximum field, enter a value, for example, 1.

    4. Click OK.

  7. Configure the Knob block to tune the Amplitude parameter of the Sine Wave block:

    1. Double-click the Knob block.

    2. In the Simulink Editor, select the Sine Wave block.

    3. In the Block Parameters dialog box:

      • Connect the block to the Amplitude parameter of the Sine Wave block.

      • In the Minimum and Maximum fields, enter values, for example, 0.1 and 1 respectively.

    4. Click OK.

  8. Save the model as xcpExample.

Specify Hardware and Prepare Model

  1. From the Apps tab on the Simulink toolstrip, in the Setup to Run on Hardware section, click Run on Custom Hardware.

  2. In the Hardware section, specify the system target file. For this example, use the default, grt.tlc. If you have Embedded Coder®, you can specify ert.tlc.

  3. In the Prepare section, click Hardware Settings. The Configuration Parameters dialog box opens, displaying Hardware Implementation settings that are determined by the system target file.

  4. On the Solver pane:

    1. In the Type field, specify Fixed-step.

    2. Under Solver details, in the Fixed-step size field, specify a value, for example, 0.1.

  5. On the Code Generation > Optimization pane, set Default parameter behavior to Tunable.

  6. On the Code Generation > Interface pane, select the External mode check box.

  7. Set Transport layer to XCP on TCP/IP, which specifies ext_xcp for MEX-file name.

  8. You cannot disable the Static memory allocation check box. The Static memory buffer size value specifies the size of XCP slave memory that is allocated for signal logging. For this example, use the default value.

  9. If System target file is ert.tlc, on the Code Generation > Templates pane:

    • Select the Generate an example main program check box. The code generator uses matlabroot\toolbox\coder\xcp\src\target\ext_mode\include\ext_mode.h to produce an example main file, ert_main.c.

    • Set Target operating system to BareBoardExample.

  10. Click OK. Then save the model.

Build and Run Target Application

In the Run on Hardware section:

  1. To specify a nondefault value for the simulation stop time, in the Stop Time field, specify your value, for example, inf.

  2. Click . The software:

    1. Builds the target application:

      • In Windows®, the build process creates:

        • xcpExample.exe –– The executable file.

        • xcpExample.pdb –– A debugging symbols file for signals and parameters.

      • In Linux®, the build process places DWARF format debugging information in the created ELF executable file, xcpExample.

    2. Runs the target application as separate process on your development computer.

    3. Connects Simulink to the target application.

    4. Runs the generated model code.

    To perform the steps separately, click Monitor & Tune. Under Step By Step Commands, click:

    1. Build for Monitoring

    2. Deploy

    3. Connect

    4. Start

Monitor Signal and Tune Parameter

You can monitor Test Signal through the:

  • Scope block –– Double-click the block.

  • Simulation Data Inspector –– Click the Simulation Data Inspector button. When the Simulation Data Inspector opens, select the Test Signal check box, which displays streamed data.

  • Half-Gauge block.

To change the amplitude of the sine wave, rotate the pointer on the Knob block to the required value.

This table describes more ways of tuning tunable (Simulink) block parameters during a simulation.

ApproachDetails

Model Data Editor

To tune parameters through the Model Data Editor:

  1. On the Hardware tab of the Simulink Editor, in the Prepare section, click Tune Parameters, which opens the Model Data Editor.

  2. If you want to update multiple tunable parameters simultaneously, in the Prepare section, click Batch Mode.

  3. On the Parameters tab of the Model Data Editor, in the Value column, specify new values for your tunable parameters.

  4. If Batch Mode is selected, click Update All Parameters or press Ctrl+D. Simulink downloads the new values to the target application simultaneously.

    If Batch Mode is not selected, then immediately after you specify a new value, Simulink downloads the new value to the target application.

For more information, see Configure Data Properties by Using the Model Data Editor (Simulink).

Block Parameter dialog box

To tune parameters through the Block Parameter dialog box:

  1. For each block that you want to update:

    1. Double-click the block, which opens the Block Parameter dialog box.

    2. In the parameter fields, specify new parameter values.

    3. Click Apply or OK.

  2. If Batch Mode is selected, click Update All Parameters or press Ctrl+D. Simulink downloads the new values to the target application simultaneously.

    If Batch Mode is not selected, then immediately after you click Apply or OK, Simulink downloads the new block values to the target application.

MATLAB® workspace

If block parameters are MATLAB workspace variables:

  1. In the Command Window, assign new values to the variables.

  2. On the Hardware tab of the Simulink Editor, in the Prepare section, click Update All Parameters (Ctrl+D). Simulink downloads the new values to the target application.

For more information, see Create and Edit Variables (MATLAB).

For more information about parameter tuning with generated code, see External Mode Simulation with TCP/IP or Serial Communication and Create Tunable Calibration Parameter in the Generated Code.

If your model contains a Stateflow® chart, you can view state activity. For more information, see Animate Stateflow Charts (Stateflow).

Stop Target Application

To stop the execution of generated model code before StopTime is reached and disconnect the target application, on the Simulink Editor toolbar, click the Stop button .

If you want to disconnect the target application from Simulink without stopping code execution, click . Then, under Step By Step Commands, click Disconnect.

Graphical Controls for XCP External Mode Simulations

You can control an XCP external mode simulation through:

  • The Hardware tab on the Simulink Editor toolbar. To display the Hardware tab, from the Apps tab on the Simulink toolstrip, click Run on Custom Hardware.

  • The External Mode Control Panel. To open this dialog box, on the Hardware tab, in the Prepare section, click . Then, under Signal Monitoring & Tracing, click Control Panel.

This table lists the controls that you can use for an XCP external mode simulation.

External Mode ActionToolstripExternal Mode Control Panel

Build target application.

Run on Hardware > Build for Monitoring

N/A

Run application on target hardware.

Run on Hardware > Deploy

N/A

Connect Simulink to a waiting or running target application.

Run on Hardware > Connect

When Simulink is connected to the target application, Connect appears dimmed and Disconnect is active.

Connect

When Simulink is connected to the target application, Connect changes to Disconnect.

Start real-time execution of generated code in the target environment.

Run on Hardware > Start

Start Real-Time Code

When the generated code starts executing, the button changes to Stop Real-Time Code.

Disconnect Simulink from the target environment, but do not stop real-time execution of code.

Run on Hardware > Disconnect

When Simulink is disconnected from the target application, Disconnect appears dimmed and Connect is active.

Disconnect

Stop target application execution and disconnect Simulink from the target environment.

In Run on Hardware section, Stop button .

Stop Real-Time Code

Tune batch of block parameters.

In Prepare section, Batch Mode and Update All Parameters buttons.

Batch download

To tune a batch of block parameters:

  1. In the External Mode Control Panel, select Batch download.

    Batch download is equivalent to the Simulink toolstrip control Batch Mode.

  2. In the Simulink Editor, modify the required block parameters.

  3. When you modify parameters, the External Mode Control Panel displays this message next to Download:

    Parameter changes pending...
    Simulink stores the modified parameters locally.

    Download is equivalent to the Simulink toolstrip control Update All Parameters.

  4. Click Download. Simulink downloads the batch of modified parameters to the target application.

Run XCP External Mode Simulation From Command Line

You can use commands to run XCP external mode simulations. To retrieve and set the values of model parameters, use the get_param and set_param commands.

To run these commands, you must have a Simulink model open and a target application running.

  1. Set the model simulation mode to external mode.

    set_param(gcs,'SimulationMode','external');

  2. Connect Simulink to the target application.

    set_param(gcs,'SimulationCommand','connect')

  3. Run generated model code.

    set_param(gcs,'SimulationCommand','start');

  4. To tune a parameter, change its workspace variable value through a line command. For example, if a block parameter value is specified as a Simulink.Parameter object, assign the new value to the Value property.

    myParamObj.Value = 5.23;

  5. To download the new value to the target application, update the model.

    set_param(gcs,'SimulationCommand','update');

  6. Stop the target application and disconnect Simulink from the target environment.

    set_param(gcs,'SimulationCommand','stop');

    To disconnect Simulink from the target application without stopping execution of generated code, use this command:

    set_param(gcs,'SimulationCommand','disconnect');

The set_param commands that use the 'SimulationCommand' argument are asynchronous. If you run the commands successively from a script, each command starts without waiting for the previous command to complete. To check that each command is complete, in the script, use the get_param command with the 'SimulationStatus' argument. For example, for steps 1 to 3, specify these commands in the script:

set_param(gcs,'SimulationMode','external');
set_param(gcs,'SimulationCommand','connect');

isExternalSimulationActive = false;
while ~isExternalSimulationActive
    simStatus = get_param(gcs, 'SimulationStatus');
    isExternalSimulationActive = strcmp(simStatus, 'external');
end
set_param(gcs,'SimulationCommand','start');

For more information, see Run Simulations Programmatically (Simulink).

The Diagnostic Viewer displays error messages produced by the get_param and set_param commands.

Register Custom Launcher

To support the one-click workflow or Deploy step for custom hardware, register your custom launcher for the target application.

  1. Create an rtw.connectivity.Config subclass, which requires myCustomLauncher, a launcher that you provide. myCustomLauncher is a subclass of rtw.connectivity.Launcher. In myCustomLauncher, to support one-click functionality, provide an implementation of the getApplicationStatus method. For the communicator and builder subclasses, you can use dummy classes.

    classdef myTargetConnectivityConfig < rtw.connectivity.Config
  methods
    % Constructor
    function this = myTargetConnectivityConfig(componentArgs)
      
      % Launcher with port 0 argument to start TCP/IP server on free port
      modelName = componentArgs.getModelName();
      bDirInfo = RTW.getBuildDir(modelName);
      exeName = fullfile(bDirInfo.CodeGenFolder, modelName);
      if ispc
        exeName = [exeName, '.exe'];
      end
      launcher = myCustomLauncher(componentArgs);
      launcher.setExe(exeName);

      % Create dummy communicator and builder
      communicator = rtw.connectivity.RtIOStreamHostCommunicator.empty();
      builder = rtw.connectivity.MakefileBuilder.empty();

      % Call super class constructor to register components
      this@rtw.connectivity.Config(componentArgs, builder, launcher, communicator);
    end
  end
end

  2. To register the implementation in Simulink, create an sl_customization.m file.

    function sl_customization(cm)
  cm.registerTargetInfo(@loc_createConfig);
end
% local function
function config = loc_createConfig
  config = rtw.connectivity.ConfigRegistry;
  config.ConfigClass = 'myTargetConnectivityConfig';

  % Specify compatible model configuration. For example,
  % through SystemTargetFile and TargetHWDeviceType properties.
  config.SystemTargetFile = {'ert.tlc'};
  config.TargetHWDeviceType = { 'ARM Compatible->ARM Cortex' };
end
    See Create sl_customization.m File.

  3. Add the folder containing sl_customization.m to the search path and refresh your customizations.

    addpath(sl_customization_path);
sl_refresh_customizations;

Target Application Arguments

You can run your target application with optional arguments. You can pass the optional arguments to your target application through your custom launcher implementation.

ArgumentDescription
-w

Specify that the target application enters and stays in a wait state until it receives a message from Simulink.

If you do not specify -w, the target application executes model code immediately. The model code runs with parameter values from the time when you built the model.

-tf timeOverride the model parameter StopTime. -tf inf specifies that the model runs indefinitely when model code is executed.

For host-based external mode simulations, you can specify additional rtiostream arguments.

ArgumentDescription

-verbose level

Specify verbosity level:

  • 0 –– No information

  • 1 –– Detailed information

-port number

For XCP on TCP/IP transport layer, specify the port number of the TCP/IP server. Use an integer value between 256 and 65535. Default is 17725.

For XCP on Serial transport layer, specify the serial port ID. For example:

On Windows, 'COM1' or 1 for COM1, 'COM2' or 2 for COM2, and so on.

On Linux, '/dev/ttyS0', and so on.

-baud value

For XCP on Serial transport layer, specify the baud value: 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600 (default), or 115200.

XCP External Mode Limitations

This table describes limitations that apply to external mode simulations that use XCP communication.

FeatureDetails

Parameter updates that change model structure

You cannot change:

  • The number of states, inputs, or outputs of a block

  • The sample time or the number of sample times

  • The integration algorithm for continuous systems

  • The name of the model or of a block

If you make parameter updates that change the model structure, you must rebuild the target application.

You can change numerator and denominator polynomial parameters for the Transfer Fcn, Discrete Transfer Fcn, and Discrete Filter blocks if the number of states does not change.

You cannot change zero entries in the State-Space, Zero-Pole, and Discrete Zero-Pole blocks in the user-specified or computed parameters, that is, the A, B, C, and D matrices obtained by a zero-pole to state-space transformation.

In the State-Space block, if you specify the matrices in the controllable canonical realization, then changes to the A, B, C, and D matrices that preserve this realization and the dimensions of the matrices are allowed.

If the Simulink block diagram does not match the target application, Simulink produces an error stating that the checksums do not match. The checksums take into account the top models, but not referenced models. To rebuild the target application, use the updated block diagram.

Signal value display

The graphical display of signal values during a simulation is not supported. For example, you cannot use the Data Display in Simulation menu items Show Value Labels When Hovering, Toggle Value Labels When Clicked, and Show Value Label of Selected Port. For more information, see Display Signal Values in Model Diagrams (Simulink).

Signal triggering and data archiving

The Signal & Triggering, Arm Trigger, Cancel Trigger, and Data Archiving features available on the External Mode Control Panel are not supported.

Signal streaming

Dynamic selection of signals for streaming is not supported. To select different signals for streaming, rebuild the model.

Overriding signal logging settingsOverriding signal logging settings by using the Signal Logging Selector is not supported.

Compiler debug symbol format

Your toolchain must generate debug information in one of these formats:

  • DWARF

  • PDB

Inlined parameters

If you set DefaultParameterBehavior to 'Inlined', the code generator embeds numeric model parameter values instead of symbolic parameter names in the generated code. You can use Simulink.Parameter objects to remove remove parameters from inlining and declare the parameters tunable. However, when you connect Simulink to the target application, the numeric values of the tunable parameters are not automatically uploaded to the model. Simulink produces a warning.

Global variables

Signals, parameters, and states must be specified as global variables. The target memory locations where the variables are stored must lie in the range 0 – 4294967295.

Parameter structures

You cannot tune parameters that are structures.

Pure integer code

Pure integer code is supported. For code generation, if 'PurelyIntegerCode' is 'on', specify 'FixedStep' with a resolution that is greater or equal to 1 microsecond. For example, specify 1.000001, but not 1.0000001.

If you do not specify -tf finalTime in the execution command, the target application runs the generated model code indefinitely, ignoring StopTime.

If you specify -tf finalTime in the execution command:

  • The finalTime value represents base rate clock ticks, not seconds.

  • The maximum value for finalTime, in ticks, is MAX_int32_T.

Variable-size signals

Uploading of variable-size signals is not supported.

Compiler support

lcc-win64 is not supported.

Endianess

Target hardware that uses big endian architecture is not supported.

Address granularity

Target hardware that uses word addresses is not supported.

Portable word sizes

When the production target hardware is word-addressable, the generation of a host-based target application by using portable word sizes is not supported. The production target hardware must support 8-bit, 16-bit, and 32-bit native data types.

Scope and Floating Scope blocks, and Scope Viewer

Some signal data types are not supported. The simulation produces a warning.

Scopes in referenced models

In a model hierarchy, if the top model runs in external mode and a referenced model runs in normal or accelerator mode, scopes in the referenced model are not displayed.

Nonzero simulation start time

Nonzero simulation start times are not supported. Use the default value for Solver > Start time, 0.0.

Intermediate step values

Some Simulink blocks can generate multiple values in a simulation time step. For example:

For each time step in an external mode simulation, Simulink uploads from the target application only the final values of such blocks. Simulink does not upload the intermediate values generated during the step.

File-scoped data

File-scoped data is not supported. For example, data items to which you apply the built-in custom storage class FileScope. The simulation produces a warning.

For more information about the FileScope storage class, see Choose Storage Class for Controlling Data Representation in Generated Code.

Row-major code generation

Code generated with the row-major format is not supported.

Concurrent execution

Concurrent execution is not supported. If System target file is ert.tlc and Target operating system is NativeThreadsExample, you cannot build the target application.

VxWorks® example

If System target file is ert.tlc and Target operating system is VxWorksExample, you cannot build the target application.

Related Topics

External Websites

Embedded Coder Documentation
Support