Set Up PIL Connectivity by Using target Package

You can use the target Package to provide PIL connectivity between Simulink^® and the target hardware. In this example, your development computer is the target hardware.

1.  Create the board description

   Create a target.Board object that provides MATLAB^® with a description of your target hardware.

   hostTarget = target.create('Board', ...
                              'Name', 'Example Intel Board');

   To support code generation and data I/O in PIL simulations, associate the object with processor, connection, and communication descriptions.

2.  Associate the board with a processor

   To support code generation, associate the board with a target.Processor object that contains a language implementation. For this example, create a target.Processor object and reuse an existing target.LanguageImplementation object. For information about setting up a custom target.LanguageImplementation object, see Register New Hardware Devices.

   processor = target.create('Processor', 'Name', 'ExampleProcessor');
   processor.LanguageImplementations = target.get('LanguageImplementation', ...
                                                  'Intel-x86-64 (Windows64)'); 

   Associate the target.Board object with the new target.Processor object by using the Processors property

   hostTarget.Processors = processor;

3.  Specify execution information for the target hardware

   Create an 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. To capture system commands for starting and stopping the target application, you can use the HostProcessExecutionTool or SystemCommandExecutionTool class .

   applicationExecution = target.create('HostProcessExecutionTool');
   applicationExecution.Name = 'Windows Application';

   Create a Command object for downloading and running the target application. Assign the string variable '$(EXE)' to the String property as a place holder for the target application name, which is not known until execution.

   runCommand = target.create('Command');
   runCommand.String = '$(EXE)';
   applicationExecution.StartCommand = runCommand;
   hostTarget.Tools.ExecutionTools = applicationExecution;

4.  Create the communication interface for the target hardware

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

   Use:

   • The shipped TCP/IP rtiostream implementation source file.

   • A BuildDependencies object to specify, for the rtiostream API, the source files that are compiled with the target application.

   • A MainFunction object to pass arguments to the target application

   comms = target.create('CommunicationInterface');
   comms.Name = 'Windows TCP Interface';
   comms.Channel = 'TCPChannel';
   comms.APIImplementations = target.create('APIImplementation', ...
                                            'Name', 'x86 RTIOStream Implementation');
   comms.APIImplementations.API = target.create('API', 'Name', 'RTIO Stream');
   comms.APIImplementations.BuildDependencies = target.create('BuildDependencies');
   comms.APIImplementations.BuildDependencies.SourceFiles = ...
                                              {fullfile('$(MATLABROOT)', ...
                                                        'toolbox', ...
                                                        'coder', ...
                                                        'rtiostream', ...
                                                        'src', ...
                                                        'rtiostreamtcpip', ...
                                                        'rtiostream_tcpip.c')};
   comms.APIImplementations.MainFunction = target.create('MainFunction', ...
                                                         'Name', 'TCP RtIOStream Main');
   comms.APIImplementations.MainFunction.Arguments = {'-blocking', '1', '-port', '0'};
   hostTarget.CommunicationInterfaces = comms;

5.  Specify PIL protocol information

   This step is optional. A PIL simulation uses a communication protocol for the transfer of data between Simulink and the target hardware. The target.PILProtocol class describes the parameters of the protocol. For this example, you can improve target run-time performance by increasing the I/O buffer size that the protocol uses.

   Create a target.PILProtocol object and specify I/O buffer size.

   pilProtocol = target.create('PILProtocol');
   pilProtocol.Name = 'Windows PIL Protocol';
   pilProtocol.SendBufferSize = 50000;
   pilProtocol.ReceiveBufferSize = 50000;
   hostTarget.CommunicationProtocolStacks = pilProtocol;

   If you do not perform this step, default target.PILProtocol values are used.

6.  Add profiling timer

   You can configure a PIL simulation to produce execution-time profiles for the generated code. To support code execution profiling, you must create a timer object that describes the retrieval of current time from generated code running on the target hardware. The timer object description must include a description of the function that retrieves time and its implementation.

   This example uses a C function, timestamp_x86, which returns the current time as a uint64 data type.

   timerSignature = target.create('Function');
   timerSignature.Name = 'timestamp_x86';
   timerSignature.ReturnType = 'uint64';

   Capture the function in an API object.

   timerApi = target.create('API');
   timerApi.Functions = timerSignature;
   timerApi.Language = target.Language.C;
   timerApi.Name = 'Windows Timer API';

   Capture the dependencies of the function, that is, the source and header files that are required to run the function.

   timerDependencies = target.create('BuildDependencies');
   timerDependencies.IncludeFiles = {'host_timer_x86.h'};
   timerDependencies.IncludePaths = {'$(MATLAB_ROOT)/toolbox/coder/profile/src'};
   timerDependencies.SourceFiles = {'host_timer_x86.c'};

   Create an object that combines the API and dependencies.

   timerImplementation = target.create('APIImplementation');
   timerImplementation.API = timerApi;
   timerImplementation.BuildDependencies = timerDependencies;
   timerImplementation.Name = 'Windows Timer Implementation';

   Create the timer object and associate it with the timer information.

   timer = target.create('Timer');
   timer.APIImplementation = timerImplementation; 
   timer.Name = 'Windows Timer';

   Assign the timer to the processor object.

   processor.Timers = timer;

7.  Specify connection between development computer and target hardware

   The previous steps created target hardware support for communications and running the target application. Now, set up a connection between your development computer and the target hardware by creating a TargetConnection object. Specify:

   • The communication channel, which is the same channel specified in the target hardware communication interface –– see step 4.

   • The connection properties.

   • The target, which is the board description specified in previous steps.

   connection = target.create('TargetConnection');
   connection.Name = 'Host Process Connection';
   connection.Target = hostTarget;
   connection.CommunicationChannel = target.create('TCPChannel');
   connection.CommunicationChannel.Name = 'External Process TCPCommunicationChannel';
   connection.CommunicationChannel.IPAddress = 'localhost';
   connection.CommunicationChannel.Port = '0';

8.  Add the board and connection objects to persistent memory

   To register the connectivity in MATLAB, use the target.add function to add the target hardware and connection information to MATLAB memory. By default, the information is only available for the current MATLAB session. To make the registration persist across MATLAB sessions, specify the name-value pair 'UserInstall', true.

   target.add([hostTarget connection], 'UserInstall', true);

9.  Specify board for model

   You can now specify your development computer as the target hardware for PIL simulations. Before you run a PIL simulation, in the Configuration Parameters dialog box, set Hardware board to Example Intel Board.