MATLAB XPC TARGET 4 - API GUIDE User's Guide

User’s GuideVersion 2For Use with Real-Time Workshop®xPC Target

vi Contents11xPC Target and FortranIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2Simulink Demos

4 Embedded Option4-2IntroductionThe xPC Target Embedded Option allows you to boot the xPC Target kernel from a 3.5 inch disk drive and other devices,

xPC Target Embedded Option Modes4-3xPC Target Embedded Option ModesThe xPC Target Embedded Option extends the xPC Target base product with two modes:

4 Embedded Option4-4The following are some instances where you might want to use the xPC Target Embedded Option. You might have one of these situation

xPC Target Embedded Option Modes4-5- autoexec.bat — xPC Target version of this file that calls the xpcboot.com executable to boot the xPC Target kerne

4 Embedded Option4-6StandAlone Mode OverviewThe primary purpose of the StandAlone mode is to allow you to use a target PC as a stand-alone system. Sta

xPC Target Embedded Option Modes4-7- xpcboot.com — Contains the xPC Target boot executable. This file executes an xPC Target application and executes

4 Embedded Option4-8RestrictionsThe following restrictions apply to the booted DOS environment when you use xpcboot.com to execute the target applicat

Embedded Option Setup4-9Embedded Option SetupThis section includes the following topics:• “Updating the xPC Target Environment” on page 4-9 • “Creatin

4 Embedded Option4-10The default setting for the option Target boot mode is BootFloppy. When you are using BootFloppy, xPC Target must first create a

Embedded Option Setup4-11For more detailed information about how to use the xPC Target Explorer window, see “xPC Target Explorer” in Chapter 2 in the

vii14Function ReferenceFunctions — Categorical List . . . . . . . . . . . . . . . . . . . . . . . . . 14-2Software Environment . . . . . . . . . .

4 Embedded Option4-12DOSLoader Target SetupDOSLoader mode allows you to copy the xPC Target kernel to the target flash disk, remove the 3.5 inch disk

DOSLoader Target Setup4-135 Click Create BootDisk.A message box opens with the following message.Insert a formatted floppy disk into your host PC disk

4 Embedded Option4-14c Reboot the target PC. The DOS is booted from the target boot disk and the autoexec.bat files, resulting in the automatic execut

DOSLoader Target Setup4-154 Typecopy A:\xpcsgo1.rtb C:\workcopy A:\xpcboot.com C:\workcopy A:\autoexec.bat C:\work5 If you want the kernel to run when

4 Embedded Option4-16Creating a Target Application for DOSLoader ModeFor DOSLoader mode, a target application is created on a host PC and downloaded t

Stand-Alone Target Setup4-17Stand-Alone Target SetupStandAlone mode combines the target application with the kernel and boots them together on the tar

4 Embedded Option4-185 From the Target boot mode list, choose StandAlone.xPC Target updates the environment properties, and the build process is ready

Stand-Alone Target Setup4-192 Edit the Scope (xPC) dialog box and confirm that the check box entry for Start scope when application starts is selected

4 Embedded Option4-20This setting is required to enable target scopes to begin operating as soon as the application starts running. This setting is im

Stand-Alone Target Setup4-21Creating a Kernel/Target ApplicationUse xPC Target with StandAlone mode to create a combined kernel and target application

viii Contents

4 Embedded Option4-22c Reboot the target PC. DOS is booted from the target boot disk and the autoexec.bat files, resulting in the automatic execution

Stand-Alone Target Setup4-236 Edit the file C:\autoexec.bat to include the following lines. Adding these commands to C:\autoexec.bat directs the syste

4 Embedded Option4-24

5Software Environment and DemosThe xPC Target environment defines the connections and communication between the host and target computers. It also de

5 Software Environment and Demos5-2Using Environment Properties and FunctionsUse the xPC Target Explorer window or the MATLAB Command Window to enter

Using Environment Properties and Functions5-3Changing Environment Properties with xPC Target ExplorerxPC Target lets you define and change environment

5 Software Environment and Demos5-4This pane contains all the objects in your xPC Target hierarchy. As you add objects to your system, xPC Target Expl

Using Environment Properties and Functions5-5Note In general, the default values of these parameters are sufficient for you to use xPC Target.1 In th

5 Software Environment and Demos5-67 From the Target scope list, select either Enabled or Disabled. The property Target scope is set by default to Ena

Using Environment Properties and Functions5-72 In the MATLAB window, typeupdatexpcenvThe environment properties you changed with the function setxpcen

1Target and Scope ObjectsBefore you can work with xPC Target target and scope objects, you should understand the concept of target and scope objects.

5 Software Environment and Demos5-8xPC Target DemosThe xPC Target demos are used to demonstrate the features of xPC Target. But they are also M-file s

6Using the Target PC Command-Line InterfaceYou can interact with the xPC Target environment through the target PC command window. xPC Target provides

6 Using the Target PC Command-Line Interface6-2Target PC Command-Line InterfaceThis interface is useful with stand-alone applications that are not con

Target PC Command-Line Interface6-3Once the command window is active, you do not have to reactivate it before typing the next command. Manipulating Ta

6 Using the Target PC Command-Line Interface6-4The command window displays a message to indicate that the new parameter has registered.System: S0 has

Target PC Command-Line Interface6-52 Type a scope command. For example, to add a target scope (scope 2) in the model xpcosc, typeaddscope 2xPC Target

6 Using the Target PC Command-Line Interface6-6Manipulating Scope Object Properties from the Target PCThis section shows some of the common tasks that

Target PC Command-Line Interface6-72 Type the variable name to run that command sequence. For example, to turn the motor on, typeonThe parameter P7 is

6 Using the Target PC Command-Line Interface6-8

7Working with Target PC Files and File SystemsxPC Target scopes of type file create files on the target PC. To work with these files from the host PC

1 Target and Scope Objects1-2Target ObjectsxPC Target uses a target object (of class xpctarget.xpc) to represent the target kernel and your target app

7 Working with Target PC Files and File Systems7-2IntroductionThe xPC Target scope object of type file always writes acquired signal data to a file on

Introduction7-3This chapter describes procedures on how to use the xpctarget.ftp and xpctarget.fs methods for common operations. See Chapter 14, “Func

7 Working with Target PC Files and File Systems7-4FTP and File System ObjectsxPC Target uses two objects, xpctarget.ftp and xpctarget.fs (file system)

Using xpctarget.ftp Objects7-5Using xpctarget.ftp ObjectsThe xpctarget.ftp object enables you to work with any file on the target PC, including the da

7 Working with Target PC Files and File Systems7-6For example, to list the name of the current directory of a target PC through a TCP/IP connection,1

Using xpctarget.ftp Objects7-7Note You must use the dir(f) syntax to list the contents of the directory. To get the results in an M-by-1 structure, u

7 Working with Target PC Files and File Systems7-82 Typef.get('data.dat');This retrieves the file and saves that file to the variable data.

Using xpctarget.fs Objects7-9Using xpctarget.fs ObjectsThe fs object enables you to work with the target PC file system. The fs object has methods tha

7 Working with Target PC Files and File Systems7-10• “Getting Information about a File on the Target PC” on page 7-15• “Getting Information about a Di

Using xpctarget.fs Objects7-111 In the MATLAB window, type a command like the following to assign the xpctarget.fs object to a variable.fsys=xpctarget

Scope Objects1-3Scope ObjectsxPC Target uses scope objects to represent scopes on the target PC. Use scope object functions to view and collect signal

7 Working with Target PC Files and File Systems7-12data2=fread(fsys,h);This reads the file data.dat and stores the contents of the file to data2. This

Using xpctarget.fs Objects7-13If you are using xPC Target in StandAlone mode, you can extract the data from the data file if you know the number of si

7 Working with Target PC Files and File Systems7-14Getting a List of Open Files on the Target PCYou can get a list of open files on the target PC file

Using xpctarget.fs Objects7-15Getting Information about a File on the Target PCYou can display information for a file on the target PC file system fro

7 Working with Target PC Files and File Systems7-16Use the method syntax to run an xpctarget.fs object method. The syntax method_name(fs_object, argum

8Graphical User InterfacesYou can run and test your target application using the MATLAB command-line interface or the Simulink block diagram for your

8 Graphical User Interfaces8-2xPC Target Interface Blocks to Simulink ModelsYou can use Simulink to create a custom graphical user interface (GUI) for

xPC Target Interface Blocks to Simulink Models8-3Altia Design — Altia also provides Simulink blocks that communicate with xPC Target interface blocks.

8 Graphical User Interfaces8-45 To the user interface template model, add Simulink interface blocks from add-on products (Virtual Reality Toolbox, Alt

xPC Target Interface Blocks to Simulink Models8-5To xPC Target BlockThis block behaves as a sink and usually receives its input data from a control de

1 Target and Scope Objects1-4A scope object on the host PC represents a scope on the target PC. You use scope objects to observe the signals from your

8 Graphical User Interfaces8-6Note The use of To xPC Target blocks require a connection between the host and target PC. If there is no connection bet

xPC Target Interface Blocks to Simulink Models8-7xpclib/Misc sublibrary. See “From xPC Target” on page 34-10 in the xPC Target I/O reference documenta

8 Graphical User Interfaces8-8Creating a Target Application ModelA target application model is a Simulink model that describes your physical system, a

xPC Target Interface Blocks to Simulink Models8-94 In the Description box, delete the existing tag and enter a tag to the parameters for this block.Fo

8 Graphical User Interfaces8-10For the PumpSwitch and ValveSwitch blocks, enter the following tags respectively:xPCTag(2)=pump_switch;xPCTag(1)=drain_

xPC Target Interface Blocks to Simulink Models8-11Note that you cannot select signals on the output ports of any virtual blocks such as Subsystem and

8 Graphical User Interfaces8-12The tag has the following format syntax:xPCTag(1, . . . index_n)=label_1 . . . label_n;For single dimension ports, the

xPC Target Interface Blocks to Simulink Models8-13xPCTag(2,4)=label_1 label_2;6 From the File menu, click Save as. Enter a filename for your model. Fo

8 Graphical User Interfaces8-14

9xPC Target Web Browser InterfacexPC Target has a Web server that allows you to interact with your target application through a Web browser. You can

Scope Objects1-5The xpcschost scope object of type host has the following object properties:•Data• StartTime• TimeThe xpcfs scope object of type file

9 xPC Target Web Browser Interface9-2Web Browser InterfacexPC Target has a Web server built into the kernel that allows you to interact with your targ

Web Browser Interface9-31 In the MATLAB window, typexpcwwwenableMATLAB is disconnected from the target PC, and the connection is reset for connecting

9 xPC Target Web Browser Interface9-42 Open a DOS command window, and enter the command to start the TCP/IP to RS-232 gateway. For example, if the tar

Web Browser Interface9-56 In the MATLAB Command Window, typexpcMATLAB reconnects to the target application and lists the properties of the target obje

9 xPC Target Web Browser Interface9-6Using the Main PaneThe Main pane is divided into four parts, one below the other. The four parts are System Statu

Web Browser Interface9-7After you connect a Web browser to the target PC, you can use the Main pane to control the target application:

9 xPC Target Web Browser Interface9-81 In the left frame, click the Refresh button.System status information in the top cell is uploaded from the targ

Web Browser Interface9-9The new property values are downloaded to the target application. Note that the SampleTime box is visible only when the target

9 xPC Target Web Browser Interface9-102 In the Refresh Interval box, enter a value greater than 10. For example, enter 20.The signal pane updates auto

Web Browser Interface9-11Viewing Parameters with a Web BrowserThe Parameters pane displays a list of all the tunable parameters in your model. Row and

1 Target and Scope Objects1-6

9 xPC Target Web Browser Interface9-123 In the Target selection section, access levels are set in the RTW system target file box. For example, to set

10Interrupts Versus PollingxPC Target interrupt mode is the default real-time execution mode for the xPC Target kernel. For performance reasons, you

10 Interrupts Versus Polling10-2Polling ModeA good understanding of polling mode will help you to use it effectively, and a better understanding of in

Polling Mode10-3Additionally, background tasks like host-target communication or updating the target screen run in parallel with sample-time-based mod

10 Interrupts Versus Polling10-4• Interrupt handler entry and exit latency — Because an interrupt can stop the currently executing task at any instruc

Polling Mode10-5Polling means that the kernel waits in an empty while loop until the time at which the next model step has to be executed is reached.

10 Interrupts Versus Polling10-6• The model is optimal concerning execution speed — First, you should run the model through the Simulink profiler to f

Polling Mode10-71 In the Simulink window, and from the Tools menu, point to Real-Time Workshop, and then click Options.The Configuration Parameters di

10 Interrupts Versus Polling10-8displays the CPU clock rate in MHz right after the target PC has been powered up.For example, if your target PC is a 1

Polling Mode10-9Restrictions Introduced by Polling ModeAs explained above, polling mode executes the Simulink-based target application in real time ex

2Targets and Scopes in the MATLAB InterfaceYou can work with xPC Target target and scope objects through the MATLAB interface (MATLAB Command Window)

10 Interrupts Versus Polling10-10If the target application execution finally reaches the stop time and polling mode execution is stopped, host-target

Polling Mode10-11• Signal tracing through scope objects — Neither through scope objects of type host (xPC Target Explorer or scripts) or type target (

10 Interrupts Versus Polling10-12I/O Drivers Using Kernel Timing Information Cannot Be Used Within a ModelSome xPC Target drivers use timing informati

Polling Mode10-13Generally, you can use the same software/hardware setup for passing other information back and forth during run time of the target ap

10 Interrupts Versus Polling10-14

11xPC Target and FortranxPC Target supports the incorporation of Fortran code into Simulink models. This chapter describes the following:Introduction

11 xPC Target and Fortran11-2IntroductionxPC Target supports Fortran in Simulink models with S-functions. (See “Creating Fortran S-Functions” in the w

Introduction11-35 Double-click the Fortran S-functions block. A library of Fortran S-functions and associated templates appears. This library also con

11 xPC Target and Fortran11-46 Define the Fortran libraries, and the Fortran object files from step 1, in the Real-Time Workshop dialog of the Simulin

Step-by-Step Example of Fortran and xPC Target11-5Step-by-Step Example of Fortran and xPC TargetThis example uses the demo Atmosphere model that comes

How to Contact The MathWorks:www.mathworks.com Webcomp.soft-sys.matlab [email protected] Technical [email protected] Product

2 Targets and Scopes in the MATLAB Interface2-2Working with Target ObjectsThis topic describes how to work with target objects using target object fun

11 xPC Target and Fortran11-64 Connect this Scope block to the Tamb, K signal.The model sfcndemo_atmos.mdl should look like the figure shown.5 Double-

Step-by-Step Example of Fortran and xPC Target11-7Compiling Fortran FilesThis section describes the ways that you can compile Fortran code for xPC Tar

11 xPC Target and Fortran11-83 Typefl32 -c /iface:cref -G5 -Ox -Zi sfun_atmos_sub.fThis command generates the sfun_atmos_sub.obj file.Of these options

Step-by-Step Example of Fortran and xPC Target11-9Creating a C-MEX Wrapper S-FunctionThis section assumes that you have compiled your Fortran code. Se

11 xPC Target and Fortran11-10Invoking the mex command includes the following steps:1 Compile the wrapper C file sfun_atmos.c. Be sure to link in the

Step-by-Step Example of Fortran and xPC Target11-111 At the MATLAB window, typefortran_atmos_xpcThis opens the Simulink model associated with the Atmo

11 xPC Target and Fortran11-123 In the left pane, click the Real-Time Workshop node.The Real-Time Workshop pane opens.4 In the Target selection sectio

Step-by-Step Example of Fortran and xPC Target11-13Building and Running the xPC Target ApplicationThis section assumes that you have prepared the mode

11 xPC Target and Fortran11-14

12TroubleshootingThis chapter describes guidelines, hints, and tips for issues you might encounter while using xPC Target. Refer to The MathWorks Sup

Working with Target Objects2-3To check a connection between a host and a target, use the target function targetping. For example,tg.targetpingNote To

12 Troubleshooting12-2General Troubleshooting Hints and TipsThis section lists general troubleshooting tips that you can use as a first attempt to res

General Troubleshooting Hints and Tips12-3• Verify that the xPC Target boot disk contains files like the following:-BOOTSECT.RTT- checksum.dat- XPCTGB

12 Troubleshooting12-4The xpctest command performs a series of tests on your xPC Target system. These tests range from performing a basic communicatio

General Troubleshooting Hints and Tips12-5• USB support — Disable all USB support, including general USB and USB keyboard support. Failure to do this

12 Troubleshooting12-6Refer to The MathWorks Support Web SiteThis chapter contains general xPC Target troubleshooting tips. Refer to the MathWorks Sup

Installation, Configuration, and Test Troubleshooting12-7Installation, Configuration, and Test TroubleshootingThe following are some issues you might

12 Troubleshooting12-8xpctest: Test 2 Fails. First, follow the procedure described in the “Test 2, Ping Target System xPC Target Ping” section of the

Installation, Configuration, and Test Troubleshooting12-9xpctest norebootThis command runs the test without trying to reboot the target PC. It display

12 Troubleshooting12-10Error executing build command: Error using ==> make_rtwError using ==> rtw_cErrors encountered while building model "

Installation, Configuration, and Test Troubleshooting12-11xpctest: Test 5 Fails. This error occurs only when the environment variable settings are out

2 Targets and Scopes in the MATLAB Interface2-41 In the MATLAB window, typetgThe current target application properties are uploaded to the host PC, an

12 Troubleshooting12-12xpctest: Test 6 Fails. This test runs the basic target object constructor, xpc. This error rarely occurs without an earlier tes

Installation, Configuration, and Test Troubleshooting12-13• There is a known issue with an earlier version of xPC Target (1.3). It might occur when yo

12 Troubleshooting12-14Advanced TroubleshootingThe following are some advanced issues or questions you might have with xPC Target. This section has th

Advanced Troubleshooting12-15General I/O Troubleshooting GuidelinesIf you encounter issues using the xPC Target I/O drivers,• Ensure that you have pro

12 Troubleshooting12-16When this error occurs, the target object property CPUoverload changes from none to detected. To correct the issue, perform one

Advanced Troubleshooting12-17More Help. If the preceding procedures do not resolve the issue, if you can build a target application with the CAN board

12 Troubleshooting12-18Note You can also obtain PCI device information from xPC Target Explorer. To do so, in xPC Target Explorer, select a connected

Advanced Troubleshooting12-19• The referenced xPC Target driver has an issue.xPC Target I/O Boards with Slow Initialization Times. Some xPC Target boa

12 Troubleshooting12-20In this case, the host PC waits for about 20 seconds before declaring that a time-out has occurred. Note that it does not take

Advanced Troubleshooting12-21However, hardware does not allow infinite precision in setting the spacing between the timer interrupts. It is this limit

Working with Target Objects2-5To get a list of the writable properties, type set(target_object). The build process assigns the default name of the tar

12 Troubleshooting12-22Round this number to the nearest whole number of 117 ticks. The resulting frequency is then(116.96 ticks/117)(50) = 49.983 HzTh

Advanced Troubleshooting12-23• http://www.mathworks.com/support/solutions/data/31528.html• Existing xPC Target device driver source code. Refer to the

12 Troubleshooting12-24Can I Create a Stand-Alone xPC Target Application to Interact with a Target Application?Yes. You can use either the xPC Target

Advanced Troubleshooting12-25For example, if a model has a stop time of 2.4 and a step size of 1, Real-Time Workshop adjusts the stop time of the mode

12 Troubleshooting12-26

13Target PC Command-Line Interface ReferencexPC Target provides a limited set of commands that you can use to work the target application after it ha

13 Target PC Command-Line Interface Reference13-2Target PC CommandsThe target PC command-line interface enables you to work with target and scope obje

Target PC Commands13-3Target Object MethodsWhen you are using the target PC command-line interface, target object methods are limited to starting and

13 Target PC Command-Line Interface Reference13-4 Target PC CommandDescription and Syntax MATLAB EquivalentgetparDisplay the value of a block paramete

Target PC Commands13-5Scope Object MethodsWhen using the target PC command-line interface, you use scope object methods to start a scope and add signa

2 Targets and Scopes in the MATLAB Interface2-6Using the Method Syntax with Target ObjectsUse the method syntax to run a target object method. The syn

13 Target PC Command-Line Interface Reference13-6The following table lists the syntax for the target commands that you can use on the target PC. The M

Target PC Commands13-7ylimitylimit scope_indexylimit scope_index = autoylimit scope_index = num1, num2grid grid scope_index ongrid scope_index offTarg

13 Target PC Command-Line Interface Reference13-8Scope Object Property CommandsWhen you use the target PC command-line interface, scope object propert

Target PC Commands13-9triggerslope scope_index = 0, either, 1, rising, 2, fallingsc.TriggerSlope = 'Either', 'Rising', 'Falli

13 Target PC Command-Line Interface Reference13-10Aliasing with Variable CommandsThe following table lists the syntax for the aliasing variable comman

14Function Reference

14 Function Reference14-2Functions — Categorical ListThis topic contains reference pages for xPC Target functions.Software Environment“Software Enviro

Functions — Categorical List14-3GUITestTarget ObjectsThe target object methods allow you to control a target application on the target PC from the hos

14 Function Reference14-4start (target object) Start execution of target application on target PCstop (target object) Stop execution of target applica

Functions — Categorical List14-5Scope ObjectsThe scope object methods allow you to control scopes on your target PC. If you want to control the target

Working with Scope Objects2-7Working with Scope ObjectsThis topic describes how to work with scope objects using scope object functions.• “Displaying

14 Function Reference14-6File and File System ObjectsxPC Target uses the xpctarget.ftp object to represent a target PC file, such as a signal data fil

Functions — Categorical List14-7xpctarget.ftp FunctionsThe xpctarget.ftp methods allow you to work with a target PC file, such as a signal data file,

14 14-8Functions — Alphabetical List 14This section contains function reference pages listed alphabetically.

addscope14-914addscopePurpose Create one or more scopesSyntax MATLAB command lineCreate a scope and scope object without assigning to a MATLAB variabl

addscope14-10A scope acquires data from the target application and displays that data on the target PC, uploads the data to the host PC, or stores tha

addscope14-11sc1 = getscope(tg,1) or sc1 = tg.getscope(1)Create two scopes using a vector of scope objects scvector. Two target scopes are created on

addsignal14-1214addsignalPurpose Add signals to a scope represented by a scope objectSyntax MATLAB command lineaddsignal(scope_object_vector, signal_i

addsignal14-13Signals = 1 : Signal Generator 0 : Integrator1Another way to add signals without using the method a

cd14-1414cdPurpose Change directory on target PCSyntax MATLAB command line cd(file_obj,target_PC_dir)file_obj.cd(target_PC_dir)Arguments Description

close14-1514closePurpose Close serial port connecting host PC with target PCSyntax MATLAB command lineclose(target_object)target_object.closeArguments

2 Targets and Scopes in the MATLAB Interface2-8For a list of target object properties with a description, see the target function get (target object)

delete14-1614deletePurpose Remove target objectSyntax MATLAB command linedelete(target_object)target_object.deleteArguments Description Use this meth

dir14-1714dirPurpose List contents of current directory on target PCSyntax MATLAB command linedir(file_obj)Arguments Description Method of xpctarget.

dir14-18 11/2/2003 13:54 6 MSDOS SYS 11/5/1998 20:01 93880 COMMAND COM 11/2/2003 13:54 <DIR> 0

diskinfo14-1914diskinfoPurpose Get information about target PC driveSyntax MATLAB command line diskinfo(filesys_obj,target_PC_drive)filesys_obj.diskin

fclose14-2014fclosePurpose Close one or more open target PC filesSyntax MATLAB command line fclose(filesys_obj,file_ID)filesys_obj.fclose(file_ID)Argu

fc422mexcalcbits14-2114fc422mexcalcbitsPurpose Calculate parameter values for Fastcom 422/2-PCI boardSyntax MATLAB command line [a b ] = fc422mexcalcb

fileinfo14-2214fileinfoPurpose Get target PC file informationSyntax MATLAB command line fileinfo(filesys_obj,file_ID)filesys_obj.fileinfo(file_ID)Argu

filetable14-2314filetablePurpose Get information about open files in target PC file systemSyntax MATLAB command line filetable(filesys_obj)filesys_obj

fopen14-2414fopenPurpose Open target PC file for readingSyntax MATLAB command line file_ID = fopen(file_obj,'file_name')file_ID = file_obj.f

fread14-2514freadPurpose Read open target PC fileSyntax MATLAB command line fread(file_obj,file_ID)file_obj.fread(file_ID)Arguments Description Metho

Working with Scope Objects2-92 Alternatively, you can typeset(sc1,'triggermode', 'signal') or typesc1.set('triggermode',

fwrite14-2614fwritePurpose Write binary data to the open target PC fileSyntax MATLAB command line fwrite(file_obj,file_ID,A)file_obj.fwrite(file_ID,A)

get (ftp)14-2714get (ftp)Purpose Retrieve copy of requested file from target PCSyntax MATLAB command lineget(file_obj,file_name)file_obj.get(file_name

get (scope object)14-2814get (scope object)Purpose Return property values for scope objectsSyntax MATLAB command lineget(scope_object_vector)get(scope

get (scope object)14-29The properties for a scope object are listed in the following table. This table includes descriptions of the properties and the

get (scope object)14-30Filename Provide a name for the file to contain the signal data. By default, the target PC writes the signal data to a file nam

get (scope object)14-31ModeFor scopes of type 'Target', indicate how a scope displays the signals. Values are 'Numerical', 'R

get (scope object)14-32NumSamplesNumber of contiguous samples captured during the acquisition of a data package. If the scope stops before capturing t

get (scope object)14-33StatusIndicate whether data is being acquired, the scope is waiting for a trigger, the scope has been stopped (interrupted), or

get (scope object)14-34TriggerSampleIf TriggerMode is 'Scope', then TriggerSample specifies which sample of the triggering scope the current

get (scope object)14-35Examples List all the readable properties, along with their current values. This is given in the form of a structure whose fiel

2 Targets and Scopes in the MATLAB Interface2-102 Alternatively, you can typebeginrun = get(sc1,'starttime') or typesc1.get('starttime&

get (scope object)14-36List the value for the scope object property Type. Notice that the property name is a string, in quotation marks, and is not ca

get (target object)14-3714get (target object)Purpose Return target object property values Syntax MATLAB command lineget(target_object, 'target_ob

get (target object)14-38ExecTimeExecution time. Time, in seconds, since your target application started running. When the target application stops, th

get (target object)14-39ModeType of Real-Time Workshop code generation. Values are 'Real-Time Singletasking', 'Real-Time Multitasking&a

get (target object)14-40ParametersList of tunable parameters. This list is visible only when ShowParameters is set to 'on':• Property value.

get (target object)14-41SignalsList of viewable signals. This list is visible only when ShowSignals is set to 'on'.• Property name. S0, S1.

get (target object)14-42Examples List the value for the target object property StopTime. Notice that the property name is a string, in quotation marks

getfilesize14-4314getfilesizePurpose Get size of file on target PCSyntax MATLAB command line getfilesize(file_obj,file_ID)file_obj.getfilesize(file_ID

getlog14-4414getlogPurpose Get all or part of output logs from target objectSyntax MATLAB command linelog = getlog(target_object, 'log_name'

getparam14-4514getparamPurpose Return value of target object parameter indexSyntax MATLAB command linegetparam(target_object, parameter_index)Argument

Working with Scope Objects2-111 In the MATLAB window, typeallscopes(1).addsignal([0,1]) 2 Alternatively, you can typeaddsignal(allscopes(1), [0,1])Acq

getparamid14-4614getparamidPurpose Get parameter index from parameter listSyntax MATLAB command linegetparamid(target_object, 'block_name',

getparamname14-4714getparamnamePurpose Get block path and parameter name from index listSyntax MATLAB command linegetparamname(target_object, paramete

getscope14-4814getscopePurpose Get scope object pointing to scope defined in kernelSyntax MATLAB command linescope _object_vector = getscope(target_ob

getscope14-49The following example gets the properties of all scopes on the target PC and creates a vector of scope objects on the host PC. If the tar

getsignal14-5014getsignalPurpose Return value of target object signal indexSyntax MATLAB command linegetsignal(target_object, 'signal index'

getsignalid14-5114getsignalidPurpose Get signal index or signal property from signal listSyntax MATLAB command linegetsignalid(target_object, 'si

getsignalname14-5214getsignalnamePurpose Get signal name from index listSyntax MATLAB command linegetsignalname(target_object, signal_index)Arguments

getxpcenv14-5314getxpcenvPurpose List environment properties assigned to MATLAB variableSyntax MATLAB Command LinegetxpcenvDescription Function to lis

getxpcenv14-54TargetRAMSizeMBValues are 'Auto' and 'Manual'. From the xPC Target Explorer window Target RAM size list, select eith

getxpcenv14-55HostTargetCommValues are 'RS232' and 'TcpIp'. From the xPC Target Explorer window Host target communication list, se

Printing History: September 1999 First printing New for Version 1 (Release 11.1)November 2000 Online only Revised for Version 1.1 (Release 12)June 200

2 Targets and Scopes in the MATLAB Interface2-12• Freerun — Starts to acquire data as soon as the scope is started (default)•Software — Starts to acqu

getxpcenv14-56TcpIpTargetPortValue is 'xxxxx'.In the xPC Target Explorer window TcpIp target port box, enter a value greater than 20000. Thi

getxpcenv14-57TcpIpTargetDriverValues are 'NE2000', 'SMC91C9X', 'I82559', and 'RTLANCE'.From the xPC Target Ex

getxpcenv14-58TcpIpTargetISAMemPortValue is '0xnnnn'.If you are using an ISA bus Ethernet card, you must enter values for the properties Tcp

getxpcenv14-59TargetScopeValues are 'Disabled' and 'Enabled'. From the xPC Target Explorer window Enable target scope list, select

getxpcenv14-60Examples Return the xPC Target environment in the structure shown below. The output in the MATLAB window is suppressed. The structure co

getxpcpci14-6114getxpcpciPurpose Determine which PCI boards are installed in target PCSyntax MATLAB Command Linegetxpcpci(target_object, 'type_of

getxpcpci14-62getxpcpci('all')Display a list of the currently supported PCI devices in the xPC Target block library. The result is displayed

load14-6314loadPurpose Download target application to target PCSyntax MATLAB command lineload(target_object,'target_application')target_obje

loadparamset14-6414loadparamsetPurpose Restore parameter values saved in specified fileSyntax MATLAB command lineloadparamset(target_object,'file

mkdir14-6514mkdirPurpose Make a directory on target PCSyntax MATLAB command line mkdir(file_obj,dir_name)file_obj.mkdir(dir_name)Arguments Descriptio

Working with Scope Objects2-13• “Triggering One Scope with Another Scope to Acquire Data” on page 2-13 — Describes a configuration of one scope to tri

put14-6614putPurpose Copy file from host PC to target PCSyntax MATLAB command lineput(file_obj,file_name)file_obj.put(file_name)Arguments Description

pwd14-6714pwdPurpose Retrieve current directory path of target PCSyntax MATLAB command linepwd(file_obj)file_obj.pwdArguments Description Method of x

reboot14-6814rebootPurpose Reboot target PCSyntax MATLAB command linereboot(target_object)Target PC command linerebootArguments Description reboot re

remscope14-6914remscopePurpose Remove scope from target PCSyntax MATLAB command lineremscope(target_object, scope_number_vector)target_object.remscope

remscope14-70Examples Remove a single scope.remscope(tg,1) or tg.remscope(1)Remove two scopes.remscope(tg,[1 2]) or tg.remscope([1,2])Remove all scope

removefile14-7114removefilePurpose Remove file from target PCSyntax MATLAB command lineremovefile(file_obj,file_name)file_obj.removefile(file_name)Arg

remsignal14-7214remsignalPurpose Remove signals from a scope represented by a scope objectSyntax MATLAB command lineremsignal(scope_object)remsignal(s

remsignal14-73See Also The xPC Target scope object method remsignal and the target object method getsignalid.

rmdir14-7414rmdirPurpose Remove directory from target PCSyntax MATLAB command linermdir(file_obj,dir_name)file_obj.rmdir(dir_name)Arguments Descripti

saveparamset14-7514saveparamsetPurpose Save current target application parameter valuesSyntax MATLAB command linesaveparamset(target_object,'file

2 Targets and Scopes in the MATLAB Interface2-14• For Scope 2, set the following values:-sc(2).ScopeId = 2- sc(2).TriggerMode = 'Scope'- sc(

set (scope object)14-7614set (scope object)Purpose Change property values for scope objectsSyntax MATLAB command lineset(scope_object_vector)set(scope

set (scope object)14-77The properties for a scope object are listed in the following table. This table includes descriptions of the properties and the

set (scope object)14-78Filename Provide a name for the file to contain the signal data. By default, the target PC writes the signal data to a file nam

set (scope object)14-79ModeFor scopes of type 'Target', indicate how a scope displays the signals. Values are 'Numerical', 'R

set (scope object)14-80NumSamplesNumber of contiguous samples captured during the acquisition of a data package. If the scope stops before capturing t

set (scope object)14-81StatusIndicate whether data is being acquired, the scope is waiting for a trigger, the scope has been stopped (interrupted), or

set (scope object)14-82TriggerSampleIf TriggerMode is 'Scope', then TriggerSample specifies which sample of the triggering scope the current

set (scope object)14-83Examples Get a list of writable properties for a scope object.sc1 = getscope(tg,1)set(sc1)ans=TriggerSlopeIf TriggerMode is &ap

set (scope object)14-84 NumSamples: {} Decimation: {} TriggerMode: {5x1 cell} TriggerSignal: {} TriggerLevel: {}

set (target object)14-8514set (target object)Purpose Change target object property valuesSyntax MATLAB command lineset(target_object)set(target_object

Working with Scope Objects2-15Posttriggering (P>0)Scope 1 triggers Scope 2 after the trigger event occurs. The following describes some of the ways

set (target object)14-86Properties must be entered in pairs or, using the alternate syntax, as one-dimensional cell arrays of the same size. This mean

set (target object)14-87The function set typically does not return a value. However, if called with an explicit return argument, for example, a = set(

set (target object)14-88See Also xPC Target target object method get (target object).Scope object methods get (scope object) and set (scope object). B

setparam14-8914setparamPurpose Change writable target object parametersSyntax MATLAB command linesetparam(target_object, 'parameter_value')A

setxpcenv14-9014setxpcenvPurpose Change xPC Target environment propertiesSyntax MATLAB Command Linesetxpcenv('property_name', 'property

setxpcenv14-91CompilerPathValue is a valid compiler root directory. Enter the path where you installed a Watcom C/C++ or Microsoft Visual C/C++ compil

setxpcenv14-92MaxModelSizeValues are '1MB', '4MB', and '16MB'. From the xPC Target Explorer window Maximum model size li

setxpcenv14-93RS232BaudrateValues are '115200', '57600', '38400', '19200', '9600', '4800',

setxpcenv14-94TcpIpGatewayValue is 'xxx.xxx.xxx.xxx'.In the xPC Target Explorer window TcpIp gateway address box, enter the IP address for y

setxpcenv14-95TcpIpTargetISAMemPortValue is '0xnnnn'.If you are using an ISA bus Ethernet card, you must enter values for the properties Tcp

2 Targets and Scopes in the MATLAB Interface2-16Note The difference between setting TriggerSample = (N + P - 1), where N and P are the parameters of

setxpcenv14-96TargetScopeValues are 'Disabled' and 'Enabled'. From the xPC Target Explorer window Enable target scope list, select

setxpcenv14-97The function setxpcenv works similarly to the set function of the MATLAB Handle Graphics® system. Call the function setxpcenv with an ev

setxpcenv14-98 See Also The xPC Target functions getxpcenv, updatexpcenv, and xpcbootdisk. The procedures “Changing Environment Properties with xPC Ta

start (scope object)14-9914start (scope object)Purpose Start execution of a scope on target PCSyntax MATLAB command linestart(scope_object_vector)scop

start (scope object)14-100somescopes = getscope(tg,[1,2]) or somescopes= tg.getscope([1,2])start(somescopes) or somescopes.startor typesc1 = getscope(

start (target object)14-10114start (target object)Purpose Start execution of target application on target PCSyntax MATLAB command linestart(target_obj

stop (scope object)14-10214stop (scope object)Purpose Stop execution of a scope on target PCSyntax MATLAB command linestop(scope_object_vector)scope_o

stop (scope object)14-103See Also The xPC Target target object methods getscope, stop (target object), and start (target object). The scope object met

stop (target object)14-10414stop (target object)Purpose Stop execution of target application on target PCSyntax MATLAB command linestop(target_object)

targetping14-10514targetpingPurpose Test communication between a host and its target computersSyntax MATLAB command linetargetping(target_object)targe

Working with Scope Objects2-17“Acquisition of Gap-Free Data” on page 2-17, illustrates how the scopes trigger one another.Acquisition of Gap-Free Data

trigger14-10614triggerPurpose Software-trigger start of data acquisition for one or more scopesSyntax MATLAB command linetrigger(scope_object_vector)

unload14-10714unloadPurpose Remove current target application from target PCSyntax MATLAB command lineunload(target_object)target_object.unloadArgumen

updatexpcenv14-10814updatexpcenvPurpose Change current environment properties to new propertiesSyntax MATLAB Command LineupdatexpcenvDescription Funct

xpc14-10914xpcPurpose Call target object constructor, xpctarget.xpcNote See “xpctarget.xpc” on page 14-116

xpcbootdisk14-11014xpcbootdiskPurpose Create xPC Target boot disk and confirm the current environment propertiesSyntax MATLAB Command LinexpcbootdiskD

xpcexplr14-11114xpcexplrPurpose Open xPC Target Explorer windowSyntax MATLAB Command LinexpcexplrDescription This graphical user interface (GUI) allow

xpctarget.fs14-11214xpctarget.fsPurpose Create xPC Target file system objectSyntax MATLAB command linefilesys_object = xpctarget.fs('mode',

xpctarget.fs14-113If you have multiple target PCs in your system, or if you want to identify a target PC with the file system object, use the followin

xpctarget.ftp14-11414xpctarget.ftpPurpose Create xPC Target FTP objectSyntax MATLAB command linefile_object = xpctarget.fs('mode', 'arg

xpctarget.ftp14-115If you have multiple target PCs in your system, or if you want to identify a target PC with the file object, use the following synt

2 Targets and Scopes in the MATLAB Interface2-18sc(1).trigger; % Start things off by triggering scope 1data = zeros(0, 2);t = [];scNum = 1; % We wi

xpctarget.xpc14-11614xpctarget.xpcPurpose Create a target object representing target applicationSyntax MATLAB command linetarget_object = xpctarget.xp

xpctarget.xpc14-117If you have multiple target PCs in your system, use the following syntax to create the additional target objects.target_object=xpct

xpctargetping14-11814xpctargetpingPurpose Test communication between host and target computersSyntax MATLAB Command LinexpctargetpingExamples Check fo

xpctargetspy14-11914xpctargetspyPurpose Open Real-Time xPC Target Spy window on host PCSyntax MATLAB Command Linexpctargetspy(target_object)Arguments

xpctest14-12014xpctestPurpose Test the xPC Target installationSyntax MATLAB Command Linexpctestxpctest('noreboot')Arguments Description xpc

xpcwwwenable14-12114xpcwwwenablePurpose Disconnect target PC from current client applicationSyntax MATLAB Command LinexpcwwwenableDescription Use this

xpcwwwenable14-122

Index-1IndexAapplicationswith DOSLoader mode 4-16with StandAlone mode 4-21Bblock parametersparameter tuning with external mode 3-50Cchanging environme

IndexIndex-2FreeDOScopying kernel 4-14copying kernel/application 4-22FTP objectsxpctarget.ftp introduction 7-4functionschanging parameters 3-47signal

IndexIndex-3Rreadxpcfile 7-12Sscope objectscommand-line interface 1-3commands 1-3list of properties with files 3-30list of properties with targets 3-2

3Signals and ParametersChanging parameters in your target application while it is running in real time, and checking the results by viewing signal da

IndexIndex-4task execution time (TET)average 14-37definition 3-41in an example 3-42logging 14-41maximum 14-38minimum 14-38with the getlog function 14-

IndexIndex-5xPC Target Exploreradding signals 3-16configuring the host scope viewer 3-23creating scopes 3-12monitoring signals 3-2stopping scopes 3-20

IndexIndex-6

3 Signals and Parameters3-2Monitoring SignalsSignal monitoring is the process for acquiring signal data during a real-time run without time informatio

Monitoring Signals3-32 In the Solver pane, change the Stop time parameter to inf (infinity).3 To get the list of signals in the target application, ex

3 Signals and Parameters3-4The Model Hierarchy node can have up to three types of nodes: subsystems ( ) (including their signals and parameters), para

Monitoring Signals3-54 To get the value of a signal, select the signal in the Model Hierarchy node.The value of the signal is shown in the right pane.

3 Signals and Parameters3-6Signal Monitoring with MATLABThis procedure uses the model xpc_osc3.mdl as an example, and assumes you created and download

Monitoring Signals3-73 Click the Real-Time Workshop® node.The Real-Time Workshop pane opens.4 To build a basic target application, in the Target selec

3 Signals and Parameters3-88 In the chart, select Tools -> Explore.The Model Explorer is displayed.9 In the Model Explorer, expand sf_car.10 Expand

Monitoring Signals3-93 Choose the state as you do a signal to monitor.Monitoring Stateflow States with MATLABThis topic assumes that you have already

3 Signals and Parameters3-10For test pointed Stateflow states, the state appears in the BLOCK NAME column like any signal. For example, if you set a t

Signal Tracing3-11Signal TracingSignal tracing is the process of acquiring and visualizing signals while running a target application. In its most bas

3 Signals and Parameters3-12Creating Scopes1 In xPC Target Explorer, ensure that your xpcosc application is still running. 2 To get the list of signal

Signal Tracing3-134 To create a scope to display on the target PC, right-click the Target Scopes node under the xPC Scopes node.A context menu appears

iContents1Target and Scope ObjectsTarget Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2What Is a Target

3 Signals and Parameters3-146 To create a scope to be displayed on the host PC, right-click the Host Scopes node under the xPC Scopes node.A context m

Signal Tracing3-1510 To list the properties of the scope object Scope 2, select the xPC Target Explorer tab to return to that window, and left-click S

3 Signals and Parameters3-1612 Right-click the File Scopes node under the xPC Scopes node.A scope node appears under File Scopes. In this example, the

Signal Tracing3-173 Start the scope. For example, to start Scope 1, right-click it and select Start.The target screen plots the signals after collecti

3 Signals and Parameters3-185 Expand the Scope 2 node.The Scope 2 signals are displayed.6 Start the scope. For example, to start the scope Scope 2, ri

Signal Tracing3-197 Add signals to the scope of type file. For example, to add signals Integrator1 and Signal Generator, right-click each signal and s

3 Signals and Parameters3-209 To specify a filename for the data file, select the scope of type file. In the right pane, enter a name in the Filename

Signal Tracing3-21If you have scopes of type file, you can copy the file that contains the signal data from the target PC to the host PC. See “Copying

3 Signals and Parameters3-223 Start the scope and target application.4 Right-click the scope to be triggered. For example, select Scope 1.5 Select Tri

Signal Tracing3-23Configuring the Host Scope ViewerYou can customize your host scope viewer. This section assumes that you have added a host scope to

ii Contents3Signals and ParametersMonitoring Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Signal Monitoring wi

3 Signals and Parameters3-24Copying Files to the Host PCFrom xPC Target Explorer, you can download target PC files from the target PC to the host PC.

Signal Tracing3-25A file Save As dialog is displayed.7 Choose the directory to contain the signal data file. If you want, you can also save the file u

3 Signals and Parameters3-26Signal Tracing with MATLABCreating a scope object allows you to select and view signals using the scope methods. This sect

Signal Tracing3-27ShowSignals = on Signals = INDEX VALUE BLOCK NAME0 0.000000 Integrator11 0.000000 Signal

3 Signals and Parameters3-28 YLimit = Auto Grid = OnSignals = no Signals defined5 Add signals to the sc

Signal Tracing3-29Signal Tracing with MATLAB and Scopes of Type FileThis procedure uses the Simulink model xpcosc.mdl as an example, and assumes you h

3 Signals and Parameters3-303 Start running your target application. Type+tg or tg.start or start(tg)The target PC displays the following message:Syst

Signal Tracing3-31 Mode = Lazy WriteSize = 512 AutoRestart = offNote that there is no name initially assigne

3 Signals and Parameters3-32 TriggerScope = 2 TriggerSample = 0 TriggerSignal = 0 TriggerLevel = 0.000000 Trig

Signal Tracing3-33Signal Tracing with xPC Target Scope BlocksUse scopes of type host to log signal data triggered by an event while your target applic

iiiEmbedded Option Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9Updating the xPC Target Environment . . . . . . . . . . .

3 Signals and Parameters3-34Scope of Type FileFor a scope of type file, the scope acquires data and writes it to the file named in the FileName parame

Signal Tracing3-353 Click the Edit button.The scope editing pane opens. From this pane, you can edit the properties of any scope, and control the scop

3 Signals and Parameters3-36Signal LoggingSignal logging is the process for acquiring signal data during a real-time run, stopping the target applicat

Signal Logging3-371 In xPC Target Explorer, select the downloaded target application node. For example, xpc_osc4.The right pane displays the target ap

3 Signals and Parameters3-385 Send the selected logged data to the MATLAB workspace. In the target application properties dialog for xpc_osc4, go to t

Signal Logging3-39All scopes copy the last N samples from the log buffer to the target object logs (tg.TimeLog, tg.OutputLog, tg.StateLog, and tg.TETL

3 Signals and Parameters3-40

Signal Logging3-413 In the MATLAB window, typeplot(tg.TimeLog,tg.TETLog)Values for the task execution time (TET) log are uploaded to the host PC from

3 Signals and Parameters3-424 In the MATLAB window, type eithertg.AvgTET or get(tg,'AvgTET')MATLAB displays the following information about

Parameter Tuning and Inlining Parameters3-43Parameter Tuning and Inlining ParametersBy default, xPC Target lets you change parameters in your target a

iv Contents6Using the Target PC Command-Line InterfaceTarget PC Command-Line Interface . . . . . . . . . . . . . . . . . . . . 6-2Using Target Appl

3 Signals and Parameters3-44Parameter Tuning with xPC Target ExplorerxPC Target lets you change parameters in your target application while it is runn

Parameter Tuning and Inlining Parameters3-45The model hierarchy only shows blocks that have tunable parameters.4 Select the parameter of the signal yo

3 Signals and Parameters3-46If there is a scope, the plot frame then updates the signals after running the simulation with the new parameter value.8 S

Parameter Tuning and Inlining Parameters3-47Parameter Tuning with MATLABYou use the MATLAB functions to change block parameters. With these functions

3 Signals and Parameters3-48Parameters = 3 Change the gain. For example, to change the Gain1 block, type eithertg.setparam(5,800) or setparam(tg,5,800

Parameter Tuning and Inlining Parameters3-494 Stop the target application. In the MATLAB window, type-tg or tg.stop or stop(tg)The target application

3 Signals and Parameters3-502 To reset to the previous values, typesetparam(tg,pt.parIndexVec,pt.OldValues)ans = parIndexVec: 5OldValues: 800NewValues

Parameter Tuning and Inlining Parameters3-512 In the Simulink block window, and from the Simulation menu, click Connect to target. All of the current

3 Signals and Parameters3-525 In the Gain text box, enter 800 and click OK.As soon as you change a model parameter and click OK, or you click the Appl

Parameter Tuning and Inlining Parameters3-53Parameter Tuning with a Web BrowserThe Parameters pane displays a list of all the tunable parameters in yo

v8Graphical User InterfacesxPC Target Interface Blocks to Simulink Models . . . . . . . . . 8-2Simulink User Interface Model . . . . . . . . . . . .

3 Signals and Parameters3-54• You have parameters you would like to save for reuse. See- “Parameter Tuning with MATLAB” on page 3-47- “Parameter Tunin

Parameter Tuning and Inlining Parameters3-552 In the MATLAB window, type eithertg.loadparamset('xpc_osc4_param1') or loadparamset(tg,'x

3 Signals and Parameters3-56Inlined ParametersThis procedure describes how you can globally inline parameters for a model, then specify which of these

Parameter Tuning and Inlining Parameters3-578 Click the Configure button.The Model Parameter Configuration dialog is displayed. Note that the MATLAB w

3 Signals and Parameters3-5812 Build and download the model to your target PC.You can next use xPC Target Explorer or MATLAB to work with the tunable

Parameter Tuning and Inlining Parameters3-595 Enter a new value for the parameter.6 Press the Enter key.The box is updated and the Update Parameter bu

3 Signals and Parameters3-609 Stop the target application.Tuning Inlined Parameters with MATLABThis procedure describes how you can tune inlined param

Parameter Tuning and Inlining Parameters3-611 Save the following code in an M-file. For example, change_inlineA,tg=xpc; %Create xPC Target objectpid=t

3 Signals and Parameters3-62

4Embedded OptionThe xPC Target Embedded Option allows you to boot the target PC from a device other than a 3.5 inch disk drive, such as a hard disk o