Mechanical Simulation Technical Memo

755 Phoenix Drive, Ann Arbor MI, 48108, USA

Phone: 734 668-2930 • Fax: 734 668-2877 • Email: [email protected] carsim.com

CarSim RT for LabCar RTPC Tutorial

Import (Install) LabCar Programs and Datasets .................................................................. 1
Run an Example Simulink Model with LabCar .................................................................. 2
Create and Run a Simulink Real-Time Project ................................................................... 4
Set Up the LabCar Project ............................................................................................4
Prepare CarSim Datasets...............................................................................................6
Modify an Existing Simulink Model ............................................................................8
Build the LabCar Model .............................................................................................11
Run the Simulation ..................................................................................................... 13
Run an Example C-Module Real-Time Project................................................................. 14
Create and Run a C-Module Real-Time Project................................................................15
Set Up the LabCar Project ..........................................................................................15
Add New C Functions and Edit C Code ..................................................................... 19
Apply LabCar Patch (Temporary Bug Fix) ................................................................23
Prepare CarSim Datasets.............................................................................................25
Build the LabCar Model .............................................................................................26
Run the Simulation ..................................................................................................... 28

This memo provides step-by-step instructions for creating and running real-time applications
using CarSim 9.0 RT within the LabCar version 4.1 environment. Two methods are shown:
1. Running with a Simulink model in LabCar.
2. Running with the LabCar C-Module.
This document assumes that you already have basic familiarity with both CarSim and the LabCar
Operator program. Depending on your application, familiarity with MATLAB/Simulink and/or
the C language will also be required.

Import (Install) LabCar Programs and Datasets

Installation of the LabCar-compatible CarSim math models is simple: import a single file that
contains all CarSim math models, corresponding LabCar projects, and supporting CarSim
datasets that will be used in this tutorial.
Start with a PC that has both LabCar 4.1 and CarSim 9.0 installed. CarSim should be up and
running. Note that you will need the optional CarSim RT license for LabCar RTPC in order to use
LabCar with CarSim.
Start CarSim with the database that you will use with LabCar RT. (E.g., the default database
installed with CarSim 9.0.)
Use the File menu command Import Parsfile (Any Export Type) and import the file
CarSim900_LabCar.cpar from the CarSim RT LabCar CD (or web download).
Your database now includes all CarSim solver programs compiled as needed for LabCar RTPC,
plus the datasets that are used for the examples described in this tutorial.

CarSim RT 9.0 1 / 29 October 2014

Run an Example Simulink Model with LabCar
To run a Simulink model in LabCar, you must have MATLAB Coder (formally Real-Time
Workshop) installed. If you will instead be using the C-Module option in LabCar, you can skip to
the C example (page 14).
1. Start CarSim.
2. On the CarSim Run Control screen, use the Dataset menu to go to the run LabCar
RT->Ext. ABS: Split Mu (Figure 1).

Figure 1. LabCar example with a Simulink ABS controller.

3. Click the blue link button 1 (Figure 1) to view the linked Models dataset (Figure 2).
This screen specifies the LabCar working directory 3 , the Simulink model file 4 , and
links to datasets that specify variables to be imported from Simulink 5 and exported to
Simulink 6 .
It also specifies the IP addresses of the target 1 and host 2 machines.
4. Change these IP addresses ( 1 and 2 ) to match your configuration.
5. Return to the Run Control screen (Figure 1).
6. Click the Send button.
This launches the animator (to support live animation), and sends data for the simulation
from the CarSim database to the target machine. This also sends a copy of the data file to
the directory containing the Simulink model file.

2 / 29
 Figure 2. Specification of LabCar project and Simulink model.
7. Start LabCar Operator.
8. Open the LabCar project file Simulink_ABS.lco4. (This is located in the folder
LabCar_Examples in your CarSim database.)

9. Build the LabCar model. Click the icon in LabCar Operator or use the Project
menu command Build.
10. If the Experiment Environment did not automatically open, click the Open Experiment
Environment icon in LabCar Operator (or use the Tool menu Open Experiment
Environment) to open the Experiment Environment.

11. In the Experiment Environment, click the Download icon to download the
experiment to the target PC.
12. Start running by clicking the icon . When the model is running you should see the
vehicle moving via live animation. Click the icon to stop the run.

13. After stopping the run the results are automatically transferred back to the host. If there
are any problems, you can manually transfer results back to the host by clicking the
Receive button on the CarSim Run Control screen. However, this is normally not
necessary.

3 / 29
Create and Run a Simulink Real-Time Project
You can create a real-time simulation or test project with an existing MATLAB/Simulink model.
This section describes how the Simulink ABS model example was created and set up to run in
LabCar. It has step-by-step instructions for creating a new LabCar project from scratch that will
make use of an existing Simulink model.

Set Up the LabCar Project

Start by creating a new LabCar project.
1. From the menu of LabCar Operator select File -> New Project (Figure 3) to make the
new project.

Figure 3. Create a new LabCar Project.

2. Create a project location and name (Figure 4). Be sure to select the radio button with the
label “Use existing Simulink(TM) Model (will be copied).” Also, set the simulation
target to RTPC and the target name to RTPC before you click the Next button.

4 / 29
 Figure 4. Select project location and name.
3. Select an existing Simulink model (Figure 5). This should be the ABS control model that
is used for several examples in CarSim.

Figure 5. Select an existing Simulink model.

5 / 29
 When you click the Finish button, LabCar Operator creates a LabCar project (Figure 6)
and automatically copies the Simulink MDL file to the folder of the project.

Figure 6. Project of Simulink ABS.

3. Copy several supporting files from LabCar_Libraries (in the CarSim database) to
the LabCar project folder: car_simulink.bmp, lib_i_i_rtpc.a, vs_sf.c and
vs_sf.dll. These files should be copied to the location where the Simulink model was
copied to during the creation of the LabCar project. Specifically, the location should be
something like LabCar_Folder\Target_RTPC\SimulinkModels\Project_name.

Prepare CarSim Datasets

When running Simulink models under Windows, the connection to Simulink is handled with a
dataset from the Models: Simulink library. That dataset specifies the Simulink MDL file, plus
datasets for import and export variables. To run the same Simulink model with LabCar, the same
information is needed, along with transfer information used by LabCar.
1. In CarSim, go to the Run Control library and go to the run that uses the Simulink ABS
model. Copy the dataset category and title for your new run (Figure 7).
2. Use the Models drop-down list 1 to specify the library Models: Transfer to Target by
FTP.

6 / 29
3. Use the dataset select control under the Models control ( 1 in Figure 8) and choose the
option Link to New Dataset. Give the new dataset a name and category, such as LabCar
Target, ABS Example (see Figure 9).
4. Click the blue button for the new link ( 1 in Figure 8) to go to the newly created dataset
(Figure 9).

Figure 7. CarSim Run Control Linked to ABS Model: change the linked Models library.

Figure 8. Make a new dataset in the Models: Transfer to Target by FTP library.
5. As shown in Figure 9, the RTPC login ID 1 is labcar and the password is empty. Put
target 2 and host 3 IP addresses for file transfer between host and target on your
specific network to enable live animation. The directory on the target is
/home/labcar/var 4 . Specify a Simulink MDL file 5 , and make blue links for
import 6 and export 7 datasets as shown.

7 / 29
 Note Visit the dataset in the Models: Simulink library to see the name of the
Simulink MDL file 5 and the datasets for import 6 and export 7
variables. Use the same information here.

Return to the Run Control screen.

Figure 9. Simulink model for RTPC target.

Modify an Existing Simulink Model

1. Click the Open button to view the Simulink model shown in Figure 10. Right-click on
the CarSim S-Function block and disable the library link as shown in the figure. Save the
revised Simulink model and close MATLAB.

8 / 29
 Figure 10. ABS Simulink Model, Disable Library Link.
2. From the project menu of LabCar Operator, select Project -> Options, and select the tab
Modules in the dialog box that appears (see Figure 11). Click the button Link to
External Files and add lib_i_i_rtpc.a to the list Selected Library Files (see Figure
12).

Note The middle part of the file name i_i indicates the front and rear
suspensions of the vehicle are independent.

If you don’t see the library shown in Figure 12, you must copy this file from
{CarSim_Data}\LabCar_Libraries to the Simulink model folder.

Click the OK button to continue.

9 / 29
 Figure 11. LabCar Project Properties.

Figure 12. Add CarSim Vehicle Solver Library.

10 / 29
Build the LabCar Model
Now you can build the LabCar model.
1. Go back to the LabCar Operator (Figure 13). In the OS Configuration tab, click the
Advanced >> 1 button. In the section that opens, check and make sure the Enable OS
Monitoring box is checked 2 .

Figure 13. LabCar Operator OS Configuration

2. Click the icon in LabCar Operator or from the Project menu. This operation will do
the following:
a. Launch Matlab/Simulink/Real-Time Workshop to convert Simulink model to C
code.
b. Download all C files and library onto RTPC target.
c. Launch the gcc compiler to compile all C files.
d. Link the compiled files and downloaded library to create an executable file.
e. Start the LabCar Experiment Environment.

11 / 29
3. If the Experiment Environment did not automatically open, click the Open Experiment
Environment icon in LabCar Operator (or use the Tool menu Open Experiment
Environment) to open the Experiment Environment.
4. From the LabCar Experiment Environment, drag the item named runtime (from under
OSMonitoring as shown in Figure 15) onto the workspace and select the Oscilloscope
out of the dropdown menu labeled Instrument Type (Figure 14)

Figure 14. Create real-time plot.

Figure 15. Real Time Run

12 / 29
Run the Simulation
1. From the CarSim Run Control screen, click the Send button and you should see the
animator program prepare for live animation.

2. In the LabCar Experiment Explorer, click the Download icon (or use the
Experiment menu Download->Labcar) to download the experiment to the target PC.
3. Start running by clicking the icon . When the model is running you should see the
vehicle moving via live animation. Click the icon to stop the run.

4. After stopping the run the results are automatically transferred back to the host. If there
are any problems, you can manually transfer results back to the host by clicking the
Receive button on the CarSim Run Control screen. However, this is normally not
necessary.

13 / 29
Run an Example C-Module Real-Time Project
The C-Module interface allows you to run in real-time with hardware in the loop without
Matlab/Simulink/RTW. You can directly link modules based on C or hardware I/O to the vehicle
model.
1. Start CarSim.
2. On the CarSim Run Control screen, use the Dataset menu to go to the run LabCar RT-
>B-Class Sports Car, Normal Driving (C-Module) (Figure 16).

Figure 16. LabCar C-Module example.

Figure 17. Specification of LabCar project with C Module setting.

14 / 29
 3. Click the blue link button 1 (Figure 16) to view the linked Models dataset (Figure 17).
This screen specifies the LabCar working directory 3 and the C-module directory 4 .
It also specifies the IP addresses of the target 1 and host 2 machines.
4. Change these IP addresses ( 1 and 2 ) to match your configuration.
5. Return to the Run Control screen (Figure 16).
6. Click the Send button.
This launches the animator (to support live animation), and sends data for the simulation
from the CarSim database to the target machine.
7. Start LabCar Operator.
8. Open the LabCar project file CM_Baseline.lco4. (This is located in the folder
LabCar_Examples\CM_Baseline in your CarSim database.)

9. Build the LabCar model. Click the icon in LabCar Operator or use the Project
menu command Build.
10. If the Experiment Environment did not automatically open, click the Open Experiment
Environment icon in LabCar Operator (or use the Tool menu Open Experiment
Environment) to open the Experiment Environment.

11. In the Experiment Environment, click the Download icon to download the
experiment to the target PC.
12. Start running by clicking the icon . When the model is running you should see the
vehicle moving via live animation. Click the icon to stop the run.

13. After stopping the run the results are automatically transferred back to the host. If there
are any problems, you can manually transfer results back to the host by clicking the
Receive button on the CarSim Run Control screen. However, this is normally not
necessary.

Create and Run a C-Module Real-Time Project

The C-Module interface allows you to run in real-time with hardware in the loop without Matlab
Coder. You can directly link modules based on C or hardware I/O to the vehicle model.
For this example, an externally defined steer controller will be used. This is the same simple
closed-loop steer controller described in the Tech Memo available from the CarSim Help menu:
HelpàTechnical MemosàExample: Extending a model with VS commands and the API.

Set Up the LabCar Project

Start by creating a new LabCar project for this example. The first two steps are the same as used
for a Simulink model, and are repeated here.

15 / 29
1. From the menu of LabCar Operator select FileàNew Project then click the OK button.
2. Select a project location and name (Figure 18) and then click on the Next button. Select
the radio button with the label “No Model.” Set the simulation target to RTPC and the
target name to RTPC. Click the Next button. Because there is no model, the wizard
finishes and returns control to LabCar Operator (Figure 19).

Figure 18. Select project location and name.

16 / 29
 Figure 19. Add a C-Module.
3. Right-click Targets->RTPC in the Project Explorer pane of LabCar Operator (Figure
19) and select the drop-down menu option Add Module. This brings up the Add Module
wizard (Figure 20).

Figure 20. Select "Add C-Code Module or CAN-Module."

17 / 29
4. Select the radio button with the label “Add C-Code Module” then click the Next button
to bring up the next view (Figure 21).

Figure 21. Select Create new C-Code Module.

5. Select the radio button with the label “Create new Module” then click the Next button to
bring up the next view (Figure 22). Specify the name SteerControl and click the
Finish button.

Figure 22. New C-Module name SteerControl.

Alternatively, you can choose “Use existing Module (will be copied)” (Figure 21), link to
the files from the example included in the .cpar, and jump to the subsection Apply
LabCar Patch (Temporary Bug Fix) on page 23.

18 / 29
Add New C Functions and Edit C Code
1. Add functions by right clicking in the Processes field (Figure 23) and choose Add from
the drop-down menu.

Figure 23. Add Functions.

A Process dialog appears for specifying the name of the process. Add three functions:
Initialize, UpdateOneStep and Terminate (see Figure 24), and then click the OK
button shown in Figure 23.

Figure 24. Create Three Functions.

2. In the previous step, LabCar generated files based on the name SteerControl set in
step 6. In this step we will modify the files. These machine-generated files are:
SteerControl.c
SteerControl.h
SteerControlCopyInports.h
SteerControlCopyOutports.h
SteerControl_data.c

Listing 1 shows the original SteerControl.c file generated by LabCar.

19 / 29
 Listing 1. Original SteerControl.c file generated by LabCar.
// Add application-specific include statements here:
#include "connect.h"
#include "SteerControl.h"

// Init-triggered function "Initialize":

void cmod_Initialize_SteerControl() {
// Get Inputs:
#include "SteerControlCopyInports.h"
// Enter your code here:

// Set Outputs:
#include "SteerControlCopyOutports.h"
}

// Exit-triggered function "Terminate":

void cmod_Terminate_SteerControl() {
// Get Inputs:
#include "SteerControlCopyInports.h"
// Enter your code here:

// Set Outputs:
#include "SteerControlCopyOutports.h"
}

// Timer-triggered function "Update":

void cmod_UpdateOneStep_SteerControl () {
// Get Inputs:
#include "SteerControlCopyInports.h"
// Enter your code here:

// Set Outputs:
#include "SteerControlCopyOutports.h"
}

Note the comment “enter your code here:” that appears in several places.
CarSim comes with some example C code for a simple steering controller, contained in
the folder CarSim_Data\Extensions\Custom_C\solver_steer_control.
The file external.c contains C code for providing a closed-loop steer controller as
described by the Tech Memo available using the CarSim Help menu item Technical
Memos->Example: Extending a model with VS commands and the API).
Listing 2 and Listing 3 show the file SteerControl.c after being modified by hand
to include the equations provided with the CarSim custom C example. In these listings,
text shown in green and bold was added by hand.

20 / 29
 Listing 2. SteerControl.c file modified to include steer control variables and initialization.
// Add application-specific include statements here:
// CarSim:
#include <stdlib.h>
#include <math.h>

#include "connect.h"
#include "SteerControl.h"

//////
// CarSim: Added declaring for calling vehicle solver
void VS_Initialize (char *SIMFILE, int *no_inps, int *no_outps, double *t_step);
int VS_Update (double t, double *IN_PORTS, double *OUT_PORTS);
void VS_Terminate (double t);

static double current_t, t_step, *in_ports, *out_ports;

static int NO_inps, NO_Outps, isTerminated;

/// VS API function

double vs_road_l (double x, double y);
// for Steer Control:
static double sXprev, sYprev, // X and Y coordinates of a preview point
sLfwd, // length forward for preview (m)
sLatTrack, // Lateral offset for tracking target
sGainStr, // parameter for a control gain
sXcg, sYcg, sYaw, // vehicle X, Y, and yaw
sImpStr, // pointer to imported steering wheel angle
D2R = 3.1415926535/180;
// End of declare
/////

// Init-triggered function "Initialize":

void cmod_Initialize_SteerControl() {
// Get Inputs:
#include "SteerControlCopyInports.h"

// Enter your code here:

// CarSim: Initialize vehicle solver
current_t = 0;
isTerminated = 0;
VS_Initialize("simfile.sim", &NO_inps, &NO_Outps, &t_step);
if(NO_inps > 0) in_ports = (double*)malloc(NO_inps*sizeof(double));
if(NO_Outps > 0) out_ports = (double*)malloc(NO_Outps*sizeof(double));

sLfwd = 20.0;
sGainStr = 10;
sLatTrack = -1.6;
sImpStr = 0;

// Set Outputs:
#include "SteerControlCopyOutports.h"
}

21 / 29
 Listing 3. SteerControl.c file with equations in the update and termination functions.
// Exit-triggered function "Terminate":
void cmod_Terminate_SteerControl() {
// Get Inputs:
#include "SteerControlCopyInports.h"

// Enter your code here:

// CarSim:
VS_Terminate(current_t);
free(in_ports);
free(out_ports);

// Set Outputs:
#include "SteerControlCopyOutports.h"
}

// Timer-triggered function "UpdateOneStep":

void cmod_UpdateOneStep_SteerControl() {
// CarSim:
int status;
if(isTerminated) return;

// Get Inputs:
#include "SteerControlCopyInports.h"

// Enter your code here:

// CarSim: main part:
if(current_t == 0)
{
current_t += t_step;
return;
}
status = VS_Update(current_t, in_ports, out_ports);
if(status)
{
isTerminated = 1;
return;
}
current_t += t_step;

sXcg = out_ports[0];
sYcg = out_ports[1];
sYaw = out_ports[2] * D2R;
sXprev = sXcg + sLfwd*cos(sYaw);
sYprev = sYcg + sLfwd*sin(sYaw);
// steer proportional to the lateral error
sImpStr = sGainStr*(sLatTrack -vs_road_l(sXprev, sYprev));
in_ports[0] = sImpStr;
in_ports[1] = sXprev;
in_ports[2] = sYprev;

// End of CarSim

// Set Outputs:
#include "SteerControlCopyOutports.h"
}

22 / 29
Apply LabCar Patch (Temporary Bug Fix)
1. Apply the ETAS LabCar Patch to fix issue of C-Module with additional precompiled
libraries. These patch files are located at
{CarSim_Data}\LabCar_Examples\CM_Patch

Copy these files into the CM_SteerControl folder. From the menu of LabCar
Operator select Project->Options to open the project properties. Click the Events tab
(Figure 25). In the Pre Build event row, select the “Action” box. A drop-down menu will
appear, allowing you to browse for a file. Select the runpl.bat file you just copied.
Click on the Action, and after the path to the file, type a space, followed by the word
upload as shown in the figure. Similarly, for the Post Build Action, select the
runpl.bat file, and after it type the word clean as shown in the figure. Ensure that
the “Skip” option is unchecked for both events.

Figure 25. Project Properties and Event Editor.

2. Switch to the Modules tab (Figure 26) and click the button Link to External Files in
order to add a vehicle solver library. Add lib_i_i_rtpc.a to “Selected Library Files”
(Figure 27). The i_i represent front/rear axles are independent suspension. If you don’t
see this library, you must copy this file from {CarSim_Data}\LabCar_Libraries to
the folder where the C files are located.

23 / 29
 Figure 26. Link External Files.

Figure 27. Add CarSim Vehicle Solver Library.

24 / 29
Prepare CarSim Datasets
When running a VS solver with LabCar, it is necessary to specify how data values are exchanged
between the VS solver and the C-module with possibly some custom hardware I/O. For example,
CarSim 9.0 comes with an external steering controller that is set up for external code written in
MATLAB, VB, and C. We will copy the data exchange information used for MATLAB and
apply it to the LabCar C module.
1. In CarSim, go to the Run Control library and go to a run that is similar to the one you
will make with the C-module. Use the Datasets menu to select an existing run such as
Extended Models->Simple Steer Control with MATLAB.
Copy this dataset, and then set the category and title for your new run (Figure 28).

Figure 28. CarSim Run Control linked to simple steer model example (originally for MATLAB).
2. Use the Models drop-down list 1 to specify the library Models: Transfer to Target by
FTP.
3. Use the dataset select control under the Models control ( 1 in Figure 28) and choose the
option Link to New Dataset. Give the new dataset a name and category, such as LabCar
Target, Simple Steer Controller.
4. Click the blue button for the new link ( 1 in Figure 28) to go to the newly created dataset
(Figure 29).

25 / 29
 Figure 29. LabCar data exchange information for simple steer controller.
5. As shown in the figure, the RTPC login ID is labcar and the password is empty 1 . Put
target and host IP addresses for file transfer between host and target on your specific
network to enable live animation ( 2 and 3 ). The directory on the target is
/home/labcar/var 4 and the model file on the host should specify the C-Module’s
Target_RTPC folder (LabCar_Example\CM_SteerControl\TargetRTPC 5 ).

Note The browse button for the model file will not work; it only looks for the
folder with a Simulink model file (MDL file).

6. Provide information for import and export variables. Information from the dataset used
for the MATLAB connection is repeated here: Add variables Xpreview and
Ypreview by VS commands 6 , and specify datasets that list import and export
channels needed to support the steer control ( 7 and 8 ).

Build the LabCar Model

Now you can build the LabCar model from the LabCar Operator window.
1. Go back to the LabCar Operator (Figure 30). In the OS Configuration tab, click the
Advanced >> 1 button. In the section that opens, check and make sure the Enable OS
Monitoring box is checked 2 .

26 / 29
 Figure 30. LabCar Operator OS Configuration

2. Start to build the model by clicking the icon at the top of the LabCar Operator
window. This operation will do the following:
b. Download all C files and library onto RTPC target.
c. Launch the gcc compiler to compile all C files.
d. Link compiled files and downloaded the resulting library to an executable file.
e. Start the LabCar Experiment Environment.
3. If the Experiment Environment did not automatically open, click the Open Experiment
Environment icon in LabCar Operator (or use the Tool menu Open Experiment
Environment) to open the Experiment Environment.
4. From the LabCar Experiment Environment, drag the item named runtime (from under
OSMonitoring as shown in Figure 32) onto the workspace and select the Oscilloscope
out of the dropdown menu labeled Instrument Type (Figure 31).

27 / 29
 Figure 31. Create Real-Time Plot.

Figure 32. Real Time Run.

Run the Simulation

1. From the CarSim Run Control screen, click the Send button and you should see the
animator program prepare for live animation.

2. In the Experiment Environment, click the Download icon to download the

experiment to the target PC.
3. Start running by clicking the icon . When the model is running you should see the
vehicle moving via live animation. Click the icon to stop the run.

28 / 29
4. After stopping the run the results are automatically transferred back to the host. If there
are any problems, you can manually transfer results back to the host by clicking the
Receive button on the CarSim Run Control screen. However, this is normally not
necessary.

29 / 29