Learn more about xPC Target

Before You Start

On this page…
Introduction Important Guidelines

Introduction

This chapter describes how to write a custom application using the xPC Target API. This API enables you to write high-level language applications to load an xPC Target application, and run and control it.

Before you start, read this section for important notes on writing custom applications based on the xPC Target API. It is assumed that you already know how to write C or C++ code.

This chapter provides tutorials on how to generate a C application for xPC Target. It also provides some guidelines on using the xPC Target API. Refer to Visual C Example for tutorials that you can follow to create, build, and run a sample Visual C program.

For the xPC Target API function synopses and descriptions, refer to API Function and Method Reference.

Back to Top

Important Guidelines

This section describes some guidelines you should keep in mind before beginning to write xPC Target API applications with the xPC Target API DLL:

• You must carefully match the data types of the functions documented in the API function reference. For C, the API includes a header file that matches the data types.

• To write a non-C application that calls functions in the xPC Target API library, refer to the compiler documentation for a description of how to access functions from a library DLL. You must follow these directions to access the xPC Target API DLL

• If you want to rebuild the model sf_car_xpc.mdl, or otherwise use MATLAB, you must have xPC Target Version 2.0 or later. This is the version of xPC Target that comes with Release 13 (MATLAB 6.5) or later.

  To determine the version of xPC Target you are currently using, at the MATLAB command line, type

  xpclib

  This opens the xPC Target Simulink blocks library. The version of xPC Target should be at the bottom of the window.

• You can work with xPC Target applications with either MATLAB or an xPC Target API application. If you are working with an xPC Target application simultaneously with a MATLAB session interacting with the target, keep in mind that only one application can access the target PC at a time. To move from the MATLAB session to your application, in the MATLAB Command Window, type

  close(xpc)

  This frees the connection to the target PC for use by your xPC Target API application. Conversely, you will need to quit your application, or do the equivalent of calling the function xPCClosePort, to access the target from a MATLAB session.

• All xPC Target API functions that communicate with the target PC check for time-outs during communication. If a time-out occurs, these functions will exit with the global variable xPCError set to either ECOMTIMEOUT (serial connections) or ETCPTIMEOUT (TCP/IP connections). Use the xPCGetLoadTimeOut and xPCSetLoadTimeOut functions to get and set the time-out values, respectively.

There are a few things that are not covered in and for the individual functions, because they are common to almost all the functions in the xPC Target API. These are

• Almost every function (except xPCOpenSerialPort, xPCOpenTcpIpPort, xPCGetLastError, and xPCErrorMsg) has as one of its parameters the integer variable port. This variable is returned by xPCOpenSerialPort and xPCOpenTcpIpPort, and is the placeholder for the communications link with the target PC. The returned value from these two functions should be used in the other functions to ensure that the proper communications channel is used.

• Almost every function (except xPCGetLastError and xPCErrorMsg) sets a global error value in case of error. The application obtains this value by calling the function xPCGetLastError, and retrieves a descriptive string about the error by using the function xPCErrorMsg. Although the actual values of the error numbers are subject to change, a zero value always means that the operation completed without errors, while a nonzero value typically signifies an error condition. Note also that the library resets the error value every time an API function is called; therefore, your application should check the error status as soon as possible after a function call.

  Some functions also use their return values (if applicable) to signify that an error has occurred. In these cases as well, you can obtain the exact error with xPCGetLastError.

Back to Top

xPC Target API

Visual C Example

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS