Processor-in-the-Loop Execution from Command Line

Use processor-in-the-loop (PIL) execution to verify code that you intend to deploy in production.

To set up and start a PIL execution from the command line:

1. Create, register, and verify your target connectivity configuration. You can set up target connectivity by using the target namespace or an rtw.connectivity.Config subclass with the rtiostream API—see Set Up PIL Connectivity by Using Target Framework or PIL Execution of Code Generated for a Kalman Estimator.

2. Create a coder.EmbeddedCodeConfig object.

3. Configure the object for PIL.

4. Use the codegen function to generate library code for your MATLAB^® function and the PIL interface.

5. Use the coder.runTest function to run the test file for your original MATLAB function.

To terminate the PIL execution, use the clear function_pil or clear mex command.

The following example shows how you can use line commands to set up and run a PIL execution on your development computer.

Tutorial Files: Kalman Filter

Open this example to obtain the files for this tutorial:

• kalman01.m — MATLAB function for the Kalman estimator

• test01_ui.m — MATLAB file to test kalman01.m

• plot_trajectory.m — File that plots actual target trajectory and Kalman estimator output

• position.mat — Input data

PIL Execution of Code Generated for a Kalman Estimator

1.  Create a target connectivity API implementation

   1. In your current working folder, make a local copy of the connectivity classes.

      src_dir = ...
          fullfile(matlabroot,'toolbox','coder','simulinkcoder','+coder','+mypil');
      if exist(fullfile('.','+mypil'),'dir')
          rmdir('+mypil','s')
      end
      mkdir +mypil
      copyfile(fullfile(src_dir,'Launcher.m'), '+mypil');
      copyfile(fullfile(src_dir,'TargetApplicationFramework.m'), '+mypil');
      copyfile(fullfile(src_dir,'ConnectivityConfig.m'), '+mypil');

   2. Make the copied files writable.

      fileattrib(fullfile('+mypil', '*'),'+w');

   3. Update the namespace to reflect the new location of the files.

      coder.mypil.Utils.UpdateClassName(...
          './+mypil/ConnectivityConfig.m',...
          'coder.mypil',...
          'mypil');

   4. Check that you now have a folder +mypil in the current folder, which includes three files, Launcher.m, TargetApplicationFramework.m, and ConnectivityConfig.m.

      dir './+mypil'

   5. Review the code that starts the PIL application. The mypil.Launcher class configures a tool for starting the PIL executable. Open this class in the editor.

      edit(which('mypil.Launcher'))

      Review the content of this file. For example, consider the setArgString method. This method allows additional command line parameters to be supplied to the application. These parameters can include a TCP/IP port number. For an embedded processor implementation, you might have to hard code these settings.

   6. The class mypil.ConnectivityConfig configures target connectivity.

      edit(which('mypil.ConnectivityConfig'))

      Review the content of this file. For example:

      • The creation of an instance of rtw.connectivity.RtIOStreamHostCommunicator that configures the host side of the TCP/IP communications channel.

      • A call to the setArgString method of Launcher that configures the target side of the TCP/IP communications channel.

      • A call to setTimer that configures a timer for execution time measurement. To define your own target-specific timer for execution time profiling, you must use the Code Replacement Library to specify a replacement for the function code_profile_read_timer.

   7. Review the target-side communication drivers.

      rtiostreamtcpip_dir=fullfile(matlabroot,'toolbox','coder','rtiostream','src',...
          'rtiostreamtcpip');
      edit(fullfile(rtiostreamtcpip_dir,'rtiostream_tcpip.c'))

      Scroll down to the end of this file. The file contains a TCP/IP implementation of the functions rtIOStreamOpen, rtIOStreamSend, andrtIOStreamRecv. These functions are required for target communication with the host. For each of these functions, you must provide an implementation that is specific to your target hardware and communication channel.

      The mypil.TargetApplicationFramework class adds target-side communication drivers to the connectivity configuration.

      edit(which('mypil.TargetApplicationFramework'))

      The file specifies additional files to include in the build.

2.  Register a target connectivity configuration

   Use an rtwTargetInfo.m file to:

   • Create a target connectivity configuration object.

   • Invoke registerTargetInfo, which registers the target connectivity configuration.

   The target connectivity configuration object specifies, for example:

   • The configuration name and associated API implementation. See rtw.connectivity.ConfigRegistry.

   • A toolchain for your target hardware. This example assumes that the target hardware is your host computer, and uses the toolchain supplied for host-based PIL verification. For information about toolchains, see Custom Toolchain Registration.

   1. Insert the following code into your rtwTargetInfo.m file, and save the file in the current working folder or in a folder that is on the MATLAB search path:

      function rtwTargetInfo(tr)
      % Register PIL connectivity config: mypil.ConnectivityConfig
      
      tr.registerTargetInfo(@loc_createConfig);
      
      % local function
      function config = loc_createConfig
      
      % Create object for connectivity configuration
      config = rtw.connectivity.ConfigRegistry;
      % Assign connectivity configuration name
      config.ConfigName = 'My PIL Example';
      % Associate the connectivity configuration with the connectivity
      % API implementation
      config.ConfigClass = 'mypil.ConnectivityConfig';
      
      % Specify toolchains for host-based PIL
      config.Toolchain =  rtw.connectivity.Utils.getHostToolchainNames;
      
      % Through the HardwareBoard and TargetHWDeviceType properties,
      % define compatible code for the target connectivity configuration
      config.HardwareBoard = {};  % Any hardware board
      config.TargetHWDeviceType = {'Generic->32-bit x86 compatible' ...
                                   'Generic->Custom' ...
                                   'Intel->x86-64 (Windows64)', ...
                                   'Intel->x86-64 (Mac OS X)', ...
                                   'Intel->x86-64 (Linux 64)'};
      

   2. Refresh the MATLAB Coder™ library registration information.

      RTW.TargetRegistry.getInstance('reset');

3.  Verify target connectivity configuration

   Use the supplied piltest function to verify your target connectivity configuration.

   1. Create a coder.EmbeddedCodeConfig object for verifying the target connectivity configuration.

      configVerify = coder.config('lib');
      

   2. Specify the manufacturer and test hardware type. For example, PIL execution on a 64-bit Windows^® development computer requires:

      configVerify.HardwareImplementation.TargetHWDeviceType =... 
         'Intel->x86-64 (Windows64)'; 
      configVerify.HardwareImplementation.ProdLongLongMode = true;

   3. Run piltest.

      piltest(configVerify, 'ConfigParam', {'ProdLongLongMode'} )

4.  Configure the PIL execution

   1. Create a coder.EmbeddedCodeConfig object.

      config = coder.config('lib');

   2. Configure the object for PIL.

      config.VerificationMode = 'PIL';

   3. Specify production hardware, which must match one of the test hardware settings in rtwTargetInfo.m. For PIL execution on your development computer, specify settings that match the computer. For example, if your computer is a Windows 64-bit system, specify:

      config.HardwareImplementation.ProdHWDeviceType =...
         'Intel->x86-64 (Windows64)';
      config.HardwareImplementation.ProdLongLongMode = true;

      For a Linux^® 64-bit system, set ProdHWDeviceType to 'Intel->x86-64 (Linux 64)'.

      For a Mac OS X system, set ProdHWDeviceType to 'Intel->x86-64 (Mac OS X)'.

5.  Generate code and run PIL execution

   Generate library code for the kalman01 MATLAB function and the PIL interface, and run the MATLAB test file, test01_ui. The test file uses kalman01_pil, the generated PIL interface for kalman01.

   codegen -config config -args {zeros(2,1)} kalman01 -test test01_ui

   The software creates the following output folders:

   • codegen\lib\kalman01 — Standalone code for kalman01.

   • codegen\lib\kalman01\pil — PIL interface code for kalman01.

   Verify that the output of this run matches the output from the original kalman01.m function.

   Note

   On a Windows operating system, the Windows Firewall can potentially block a SIL or PIL execution. To allow the execution, use the Windows Security Alert dialog box. For example, in Windows 7, click Allow access.

6.  Terminate PIL execution

   Terminate the PIL execution process.

   clear kalman01_pil;