Set Up External Mode Connectivity Between Simulink and Target Hardware

R2026b

For external mode simulations, you can use the target namespace to provide connectivity between Simulink^® and your target hardware.

This diagram gives an overview of the components of an external mode simulation.

The target namespace provides classes for the implementation of components. This table lists the main classes.

Component	Class	Purpose
Target hardware	target.Board	Provide MATLAB® with a description of target hardware.
Deployment tools	target.SystemCommandExecutionTool	You can use the classes to: Capture system commands for running the target application from your development computer. Describe the execution service implementation for the target application. Provide the MATLAB service interface for the tool that manages the target application execution. To provide Monitor & Tune, Deploy, Connect, and Start functionality, the Run on Custom Hardware app requires the use of target.ExecutionTool.
	target.ExecutionService
	target.ExecutionTool
Connectivity	target.ExternalMode	Provide communication protocol for data transfer between Simulink and target hardware.
	target.CommunicationInterface	Provide target hardware with details of the communication channel and the rtiostream API implementation.
	target.TargetConnection	Provide details about connecting development computer to target hardware.

Customize Connectivity for XCP External Mode Simulations

For code that is generated by using ERT (ert.tlc) and GRT (grt.tlc) system target files, you can run external mode simulations that use the XCP communication protocol:

• On your development computer.

• On other target hardware by using support packages.

If your system target file for custom target hardware is derived from the ERT or GRT system target files, use classes from the target namespace to customize connectivity. For example, target.ExternalMode and target.CommunicationInterface.

This example shows how you can customize connectivity for XCP-based external mode simulations. To set up connectivity between Simulink and the target hardware:

1. Create board description

   Create a target.Board object that provides MATLAB with a description of your target hardware. To support code generation, associate the object with a processor.

   processor = target.get('Processor', 'Intel-x86-64 (Windows64)');
   board = target.create('Board', ...
                   'Name', 'Example Intel Board', ...
                   'Processors', processor);

2. Choose deployment tool

   Use one of these classes:

   • target.ExecutionTool — Provides the getApplicationStatus method, which is required by the Run on Custom Hardware app for Monitor & Tune, Deploy, Connect, and Start functionality.

   • target.SystemCommandExecutionTool — The getApplicationStatus method is not available with this class. The Monitor & Tune, Deploy, Connect, and Start functionality of the Run on Custom Hardware app is not fully supported.

   In step 3 and step 4, the availability of a tool that can download the target application onto the target hardware is assumed.

3. Using target.ExecutionTool

   Implement the MATLAB service interface in a class called MyImplementationClass. For an example pseudocode implementation, see Execution Tool Template.

   classdef MyImplementationClass < target.ExecutionTool
       properties (Access=private)
       …
       end
   
       methods
       …
       end
   
       methods (Access=private)          
       …
       end
   end

   Create a target.ExecutionService object that contains details about executing the target application. The object describes the tool that is required to run the target application on the target hardware.

   matlabExecution = ...
                     target.create('ExecutionService', ...
                                   'Name', 'My Application Launcher');
   matlabExecution.APIImplementation = ...
                     target.create('APIImplementation', ...
                                   'Name', 'MyServiceImplementation');
   matlabExecution.APIImplementation.BuildDependencies = ...
                     target.create('MATLABDependencies');
   matlabExecution.APIImplementation.BuildDependencies.Classes = ...
                                   {'MyImplementationClass'};
   matlabExecution.APIImplementation.API = ...
                     target.get('API', 'ExecutionTool');

   Associate the target.ExecutionService object with the target.Board object.

   board.Tools.ExecutionTools = matlabExecution;

4. Using target.SystemCommandExecutionTool

   Create a target.SystemCommandExecutionTool object that captures system commands for running the target application from your development computer.

   executionTool = target.create('SystemCommandExecutionTool', ...
                   'Name', 'My Execution Tool');            
   executionTool.StartCommand.String = 'customDownloadTool';
   executionTool.StartCommand.Arguments = {'$(EXE)'};

   Associate the target.SystemCommandExecutionTool object with the target.Board object.

   board.Tools.ExecutionTools = executionTool;

5. Create communication interface for target hardware

   Create a target.CommunicationInterface object that provides the target hardware with details of the communication channel and the rtiostream API implementation.

   For the rtiostream API, use a BuildDependencies object to specify the source files that are compiled with the target application. This example uses the shipped TCP/IP rtiostream implementation source file, which enables you to run external mode simulations on your development computer. For your target hardware, provide your own rtiostream implementation.

   buildDependencies = target.create('BuildDependencies', ...
                   'SourceFiles', ...
                   {fullfile('$(MATLAB_ROOT)', ...
                                 'toolbox', 'coder', ...
                                 'rtiostream', ...
                                 'src', ...
                                 'rtiostreamtcpip', ...
                                 'rtiostream_tcpip.c')});
   
   apiImplementation = target.create('APIImplementation', ...
                   'Name', 'TCP x86 RTIOStream Implementation', ...
                   'API', target.get('API', 'rtiostream'), ...
                   'BuildDependencies', buildDependencies);
   
   tcpComms = target.create('CommunicationInterface', ...
                   'Name', 'Windows TCP Interface', ...
                   'Channel', 'TCPChannel', ...
                   'APIImplementations', apiImplementation);

   To specify a TCP channel, this example uses the name-value argument 'Channel', 'TCPChannel'. You can specify a serial communication channel by using the name-value argument 'Channel', 'RS232Channel'.

   Associate the target.CommunicationInterface object with the target.Board object.

   board.CommunicationInterfaces = tcpComms;

6. Specify communication protocol stack

   Create an object that provides the communication protocol for data transfer between Simulink and target hardware.

   1. Use the target.XCPPlatformAbstraction class to utilize your custom implementation of the XCP platform abstraction layer. The layer provides a static memory allocator and other platform abstraction functionality.

      xcpPlatformAbstraction = target.create('XCPPlatformAbstraction', ...
                      'Name', 'XCP Platform Abstraction');
      
      xcpPlatformAbstraction.BuildDependencies.Defines = {'XCP_CUSTOM_PLATFORM'};
      customPlatformAbstractionPath = 'pathToImplementationFolder';
      xcpPlatformAbstraction.BuildDependencies.SourceFiles = ...
                      {fullfile(customPlatformAbstractionPath, 'myXCPPlatform.c')};
      xcpPlatformAbstraction.BuildDependencies.IncludePaths = ...
                      {customPlatformAbstractionPath};

   2. Use the target.XCPTCPIPTransport class to implement the XCP transport layer, which transmits and receives messages from the communication medium according to ASAM specifications. In this example, the transport protocol is TCP/IP. For serial transport, replace target.XCPTCPIPTransport with target.XCPSerialTransport.

      xcpTransport = target.create('XCPTCPIPTransport', ...
                      'Name', 'XCP Transport');

   3. Create a target.XCP object that represents the XCP protocol stack for the target hardware.

      xcpConfiguration = target.create('XCP', ...
                      'Name', 'XCP Configuration', ...
                      'XCPTransport', xcpTransport, ...
                      'XCPPlatformAbstraction', xcpPlatformAbstraction);

   4. Create an object that represents the XCP external mode connectivity options that are available in the XCP protocol stack.

      extModeConnectivity = ... 
                   target.create('XCPExternalModeConnectivity', ...                
                   'Name', 'External Mode Connectivity', ...
                   'XCP', xcpConfiguration);

      Note

      If you want to control more finely the use of target hardware resources by the XCP stack, you can specify values for XCP parameters MaxCTOSize, MaxDTOSize, and MaxODTEntrySizeDAQ. For example:

      extModeConnectivity.XCP.XCPTransport.MaxCTOSize = 16
      extModeConnectivity.XCP.XCPTransport.MaxDTOSize = 256
      extModeConnectivity.XCP.XCPTransport.MaxODTEntrySizeDAQ = 128

   5. Create an external mode protocol stack object.

      externalMode = target.create('ExternalMode', ...
                      'Name', 'External Mode', ...
                      'Connectivities', extModeConnectivity);

      Note

      You can create the object in a single call to target.create.

      externalMode = target.create('ExternalMode', ...
              'Name', 'External Mode', ...
              'XCPTransportLayer', 'TCP', ...
              'Defines', {'XCP_CUSTOM_PLATFORM'}, ...
              'SourceFiles', {fullfile('pathToImplementationFolder', 'myXCPPlatform.c')}, ...
              'IncludePaths', {'pathToImplementationFolder'});

   6. Add the object to the list of communication protocols that the target hardware supports.

      board.CommunicationProtocolStacks = externalMode;
      

7. Create connection between Simulink and target hardware

   Create an object that specifies a connection between Simulink and your target hardware.

   connection = target.create('TargetConnection', ...
                         'Name', 'Host Process Connection', ...
                         'Target', board, ...
                         'CommunicationType', 'TCPChannel', ...
                         'IPAddress', 'localhost', ... 
                         'Port', '17725')

8. Make board and connection objects persist across MATLAB sessions

   Add the board and connection objects to an internal database and make the objects persist over MATLAB sessions.

   target.add(board, 'UserInstall', true);
   target.add(connection, 'UserInstall', true);

9. Select board for model

   On the Simulink Editor Hardware tab, from the Board list, select Example Intel Board.

   

   Or, you can use the configuration parameter HardwareBoard. In the Command Window, enter:

   set_param(gcs,'HardwareBoard','Example Intel Board')

10. Select connection between Simulink and target hardware

    From the Connection list, select the connection that corresponds to TCP/IP address localhost and port number 17725.

    

    Or, you can use the model parameter HardwareConnection. In the Command Window, enter:

    set_param(gcs,'HardwareConnection','TargetConnection-Host Process Connection')

    For connections defined elsewhere, this table shows the argument values that you can specify for HardwareConnection.

    Defined in	Specify
    Mex-file arguments field	TargetConnection-External Mode Connection
    AUTOSAR Code Generation Options pane	TargetConnection-Adaptive AUTOSAR Connection
    Linux Runtime Manager Target Configuration section, in the Name field	TargetConnection-Linux Runtime Manager Connection for targetName, where targetName is the Name field value

Customize Connectivity for TCP/IP or Serial External Mode Simulations

For a model configured to use data code interfaces, you can customize connectivity for TCP/IP or serial external mode. For TCP/IP or serial external mode simulations, you can customize connectivity through a workflow that:

• Implements transport and communication protocols.

• Specifies the execution tool for the target application by using the target namespace.

To set up connectivity between Simulink and the target hardware, use the workflow described in Customize Connectivity for XCP External Mode Simulations with these differences:

• After step 1, using the information in Choose Communication Protocol for Client and Server and Create a Transport Layer for TCP/IP or Serial External Mode Communication, implement the client and server sides of external mode communication for TCP/IP or serial protocols.

• Do not perform steps 5, 6, and 7.

• In step 8, you can add only the board object.

• In step 10, to specify a connection between Simulink and the target hardware, in the Configuration Parameters dialog box:

  • From the Transport layer list, select tcpip or serial.

  • In the MEX-file arguments field, enter 'localhost' 1 0.

Execution Tool Template

This section provides a pseudocode example for a target.ExecutionTool service interface. The tool starts and tracks an application on the target hardware.

classdef MyExecutionTool < target.ExecutionTool

  methods        
    function errFlag = startApplication(this)
      % Call "customDownloadTool" to download the application.
      [status, result] = ...
       system(sprintf('customDownloadTool %s', this.Application));
      if status == 0
        errFlag = false;                
      else
        disp(result);
        errFlag = true;
      end
    end

    function errFlag = stopApplication(~)
      % Add code here to stop the application, if possible.
      errFlag = false;
    end

    function [status, errFlag] = getApplicationStatus(~)
      % Add code here to return the application status, if known.
      status = target.ApplicationStatus.Unknown;
      errFlag = false;
    end
  end
end