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

Running a VS Math Model in Simulink

Find the Existing Simulink ABS Example ............................................................. 1
Create a Copy for the Tutorial ................................................................................3
Copy the Simulink Model ................................................................................3
Link to the New Simulink Model ....................................................................5
Make a New Connection to Simulink ..................................................................10
Import Variables ............................................................................................13
Export Variables ............................................................................................16
About the Vehicle S-Function Block ...................................................................21
Import and Export Variables..........................................................................21
Simulink Configuration Parameters ...............................................................21
Multiple Ports ................................................................................................22

This memo is a tutorial that demonstrates how you can combine a Simulink model with a VS Math
Model from BikeSim, CarSim, or TruckSim, and run the full system from within Simulink.
A simple antilock brake system (ABS) example is used in various forms in BikeSim, CarSim, and
TruckSim. This memo is not intended for specialists in ABS or brake system modeling, and does
not go into detail about the brake system aspects of the Simulink model. Rather, the point is to
show how to set up a VS vehicle model to work in the Simulink environment.
In order to follow the tutorial, you must have both Simulink (from The MathWorks) and your
VehicleSim product installed. The document assumes you are familiar with Simulink, and that you
have a basic understanding of how to use your VehicleSim product as achieved by going through
the Quick Start Guide.

Find the Existing Simulink ABS Example

The tutorial is based on an example Simulink ABS model that is used for several examples in the
databases provided with each product. The installed Run Control library has a category that
includes Simulink runs (it is named Simulink and LabVIEW Models in CarSim and TruckSim,
and Simulink Models in BikeSim). Within that category, there are some ABS examples. In CarSim
and TruckSim, there is an example named Ext. ABS: Split Mu (Figure 1). For BikeSim, look for
the example ABS: Braking in Turn – Low Mu (Figure 2).
Notice that each ABS example has an overlay of another simulation without ABS .
Begin by clicking the Video button to view the existing simulation results. You should see an
overlay of two vehicles braking. For CarSim and TruckSim, you should see a split-mu surface,
where one side looks like ice and the other like pavement (Figure 3). For BikeSim, you should see
a wet tile surface on a closed track. In any of the cases (CarSim, TruckSim, or BikeSim), there are
two vehicles, and it should be clear which has ABS and which does not.

BikeSim, CarSim, and TruckSim 1 / 23 February 2018

 1

Figure 1. Run Control screen for ABS test on a split-mu surface.

Figure 2. Run Control screen for BikeSim ABS test in a turn.

Close VS Visualizer when you are through viewing the example.
In the following sections, you will create a copy of the Simulink controller and go through the steps
of connecting it to a VS Vehicle model. The figures will usually show the steps for CarSim and
TruckSim. When needed, information will be given that is specific for the BikeSim example.

2 / 23
 Figure 3. Existing simulation results (CarSim).

Create a Copy for the Tutorial

Start by making a copy of an existing Run Control dataset that uses a vehicle with a brake system
that does not include ABS.
1. Viewing the dataset for the Simulink ABS example (Figure 1 or Figure 2), click on the blue
link for the Run Control dataset used for the overlay to view that dataset. In CarSim and
TruckSim, this is a dataset with the title Braking – Split Mu: No ABS; in BikeSim it is named
Braking in Turn – Low Mu.
2. Create a copy of the example dataset by clicking the Duplicate button (Figure 4). You can
accept the default of appending #1 to the original name .
3. Uncheck the box Overlay videos and plots to disable any overlays.
4. Click the Run Math Model button . In a second or so, the simulation will complete and
the Video and Plot buttons will become active.
5. Click the Video button to view the simulation results. You should see unstable vehicle
behavior without ABS. Close VS Visualizer when you are through.

Copy the Simulink Model

You will copy the existing Simulink model with the ABS controller and brake hydraulics, and use
that copy to build a new connection from the vehicle model. Start by locating the model file.
1. Select the last item on the Help menu: About CarSim (or TruckSim or BikeSim). This
shows a small window that gives the product name, version, date, and a link to the Windows
Working Directory (Figure 5). The working directory is also the current database for your
VehicleSim product. It is underlined, indicating that it is a hyperlink to the folder on your
machine.

3 / 23
 2
1

3 4

Figure 4. Duplicate of Run Control dataset for brake test without ABS.

Figure 5.Use the “About” window to locate the current working directory.
2. Click on the pathname . This will bring up a view of the database folder in Windows
(Figure 6).

Figure 6. Windows view of VS database folder contents, including the folder named Extensions.

4 / 23
3. Notice that one of the folders is named Extensions . Double-click on that folder name
to view the contents (Figure 7).

Figure 7. Windows view Extensions folder contents, including the folder named Simulink.
4. One of the folders in Extensions is named Simulink. Double click to open the
Simulink folder (Figure 8). The Simulink folder contains many Simulink files, along
with some folders with supporting MATLAB files.

Figure 8. Duplicate the ABS model file and give the copy a new name.
5. Locate the ABS model file and duplicate it. For CarSim, the file is named abs_CS9.mdl
; for TruckSim the file is named ABS_TS9.mdl; for BikeSim the file is named
abs_v90.mdl. Change the name of the duplicate to abs_tutorial.mdl .
6. Go back to CarSim/TruckSim/BikeSim. Use Alt-Tab or click on a part of the window if
visible. The About window (Figure 5) is probably still visible. If so, close it.

Link to the New Simulink Model

You should now be viewing the duplicate Run Control dataset for the vehicle running without an
ABS controller (Figure 9).

5 / 23
 1

Figure 9. Link to the Models: Simulink library.

1. Use the Models drop-down control to choose the Models: Simulink library . This
causes a potential link to appear below the Models control (Figure 10).

Figure 10. Choose the option: [Link to New Dataset].

Note Occasionally, the potential link does not appear on the first attempt. If this
happens, please repeat the selection of Models: Simulink from the drop-
down control.

2. Use the drop-down control for the new link and select the option [Link to New Dataset]
. You will be prompted to provide a name of the new dataset (Figure 11). Type a name
such as ABS for Tutorial and then click the Create button .

Figure 11. Specify a name for the new dataset.

6 / 23
3. Notice that the screen has new controls after the link is made to the new dataset (Figure
12). The title in the center part of the screen now reads Run Control with Simulink , and
there are two new buttons: Run Now and Send to Simulink . Click on the link for the
newly linked dataset to view it (Figure 13).

1
2
3
4

Figure 12. Appearance of Run Control screen with link to Simulink dataset.

1 2

Figure 13. Select the Simulink model using the Windows file browser.
4. The first step in linking to a Simulink model is to specify a pathname to the file in the
pathname field on the screen . Do this by clicking the adjacent browser button to bring
up the Windows file browser . Browse to the Extensions\Simulink folder and select

7 / 23
 the abs_tutorial.mdl file you created earlier , such that the relative pathname is
automatically inserted in the yellow field .
5. Use the Back button or the Home button to return to the Run Control screen (Figure 12).
6. Click the Send to Simulink button from the Run Control screen (Figure 12). The VS
Browser (CarSim/TruckSim/BikeSim) will launch Simulink using the file
abs_tutorial.mdl. Figure 14 shows the CarSim example model, with an S-Function
identified with the CarSim icon . The TruckSim and BikeSim examples are similar, but
use the icons associated with those products.

Figure 14. ABS tutorial example before it is modified.

7. The model now in view is simply the copy you made earlier of the existing ABS controller.
For the purpose of this tutorial, remove the S-Function from the model. Do this by selecting
it and pressing the Delete key (Figure 15).

Note This Simulink has brake hydraulics (with dynamics) and a simple ABS
Controller . However, there is no longer a vehicle dynamics plant to
control.

8 / 23
 2 3

Figure 15. Tutorial example without vehicle S-Function.

8. Open the Simulink Library Browser (see the Simulink View menu). Depending on your
products, there will be a CarSim, TruckSim, or BikeSim category (Figure 16). Locate the VS
S-Function category (e.g., CarSim S-Function ) and click it to view the S-Function blocks
, , and .

2 3 4

1
6

Figure 16. Drag and drop a VS S-Function block from the Simulink Library Browser.
CarSim, TruckSim, and BikeSim each include three library S-Functions: a general-purpose
vehicle S-Function , an S-Function with support for a camera sensor , and an S-Function
that supports live video . Other than the names and icons, the S-Functions for CarSim are

9 / 23
 the same as those for TruckSim and BikeSim. (All use the same internal code to connect a VS
Solver to Simulink.)
9. When making the Simulink model, you add the S-Function by dragging it as shown in the
figure to the intended location . You next connect input and output signals , as
you would do with any block (Figure 17).

6
7 8

Figure 17. Simulink model with one vehicle S-Function.

10. Save the current version of the Simulink model using the File menu or type Ctrl+S.
11. Close the Simulink window (type Ctrl+W).

Make a New Connection to Simulink

The connection between the VS Database and Simulink is made with a dataset from the Models:
Simulink library. You just created a new dataset with the pathname for the Simulink model, and
you dragged a vehicle model icon into the Simulink model workspace. Next, you will provide the
rest of the information concerning the connection between the VS Solver (math model) and
Simulink.
You should be viewing the Run Control screen linked to your new Models Simulink dataset
(Figure 12, page 7). Once again, click on the blue link to view the Models: Simulink screen
(Figure 18).
This screen has various settings that specify how a vehicle model will be connected to Simulink.
First is the name of the Simulink Model file that you set earlier.

10 / 23
 1

2 3

Figure 18. Models: Simulink dataset for the ABS controller.

In most cases, you will want to specify the integration method and time step in CarSim, in order to
ensure you are coordinating with the external Simulink model. Check the box to show the
controls to do this.
The drop-down list control provides a choice among six options for performing numerical
integration . Right-click to see a short description of the options . The option used most is
the AB-2 method, with a time step of 0.0005s. However, this particular example involves an ABS
controller that switches the brakes on and off abruptly, leading to discontinuous hydraulic pressure.
When the expected behavior is highly discontinuous, the Euler method is recommended (Figure
19).

2 3

Figure 19. Options available when the Euler method is selected.

Besides the integration method , controls are shown for selecting the time step . As indicated
by the right-click pop-up hint (Figure 18), a typical time step when using Euler or AB-2 is
0.0005s .
Another checkbox is shown for selecting an option to synchronize exports and imports. The choice
for enabling this option depends on the types of input and output variables that are exchanged with
the Simulink model, as will be described after we set up the imports and outputs.
First, we will create new datasets specifying the variable used for Import and Export:
1. Use the Import drop-down control to specify the library I/O Channels: Import (Figure
20). A potential link will appear below the control (Figure 21).

11 / 23
 7

8
9

Figure 20. Link to the I/O Channels Import library.

7
10
11
8

Figure 21. Link to a new dataset for Import variables.

2. Use the drop-down control for the new potential link to specify the option [Link to New
Dataset] (Figure 21). You will be prompted to provide a name for the new dataset. Specify
ABS Imports for Tutorial. The screen will show a link to the new dataset (Figure
22).

7
10

12

Figure 22. Link to the I/O Channels Export library.

3. Use the Export drop-down control (Figure 22) to specify the library I/O Channels: Export
. A potential link will appear below the control (Figure 23).

7
10
8
13
14

Figure 23. Link to a new dataset for export variables.

4. As was done for the Import link, use the drop-down control (Figure 23) for the new potential
link to specify the option [Link to New Dataset] . You will be prompted to provide a name
for the new dataset. Specify ABS Exports for Tutorial. The screen will show a link
to the new dataset (Figure 24).

12 / 23
 7
10
8
13

Figure 24. Links to new Import and Export datasets from the Models: Simulink screen.

Import Variables
Click the Import Channels blue link to transfer to the I/O Channels: Import dataset for this
example. Initially, this is an empty dataset that does not name any Import variables (Figure 25).

Figure 25. Import dataset that is initially empty.

1. Use the drop-down control to Choose run to get import information . When this option is
selected, a potential link is shown for a Run Control dataset (Figure 26).

2
1
3

Figure 26. Select a Run Control data with the vehicle of interest.
2. Use the drop-down control for the potential link to choose a Run Control dataset that
involves the vehicle of interest. For this example, select the braking run that was created earlier

13 / 23
 . When you select the Run Control dataset, the VS Browser will jump to the Run Control
screen and then jump back to the Import screen. The Import screen now has information about
all of the Import variables that exist in the model and can potentially be activated for use with
Simulink (Figure 27).

2
1 4 5

6
7

Figure 27. Import screen appearance after a Run Control dataset was selected.
3. When the Run Control dataset was specified , two documentation files were automatically
generated that list all variables in the math model that might potentially be imported from
Simulink. One of the files is a tabbed-text file. The pathname for this tabbed-text file is shown
in the yellow field , and the number of variables is written underneath (there are 328 import
variables available for this example). The other is a spreadsheet file.
4. If you have Excel or another spreadsheet program installed, click the View Spreadsheet button
. The spreadsheet includes all available variables, their units, descriptions, and the type of
component. For example, Figure 28 shows a spreadsheet with the rows sorted based on the
Component type (column C), scrolled to view some variables related to Brakes.

Notes Depending on the spreadsheet tool and version, you might be given a
warning about the file format and extension not matching. The file has the
extension .xls and the format is tabbed text. It’s OK to open the file.
You might notice that Column E has either a 0 or the name VARIABLE.
This provides the GUI with the information need to support the drop-down
control (Figure 29) described below.

Close the spreadsheet when you are through viewing the contents.

14 / 23
 Figure 28. Spreadsheet with all potential import variables for an example vehicle.
5. Use the Categories drop-down control on the Imports screen (Figure 27) to choose the
option Select by type of component. Notice that a list of component types is shown under the
control (Figure 29).

2
1 4 5

6
8 10 11

Figure 29. Import screen showing variables for the Braking category.
6. Select the component type Brakes . The list of available variables is adjusted to show
only variables related to Brakes.
7. Right-click on any of the available variables to see a longer name in a pop-up field .

15 / 23
8. For CarSim and TruckSim, find the Import variable in the Available Variables list with the
name IMP_PBK_L1 and double-click on it. The variable will appear in the list Variables
Activated for Import . A drop-down control is shown next to the variable name with
options Replace, Add, and Multiply . The default option is Replace, which is appropriate
for this example.
9. Add three more variables by double-clicking on their names in the Available Variables list:
IMP_PBK_L2, IMP_PBK_R1, and IMP_PBK_R2. The list Variables Activated for Import
should match Figure 30.

10

Figure 30. Four variables activated for Import in CarSim and TruckSim examples.
For BikeSim, activate the Import variables IMP_PBK_1 and IMP_PBK_2 (Figure 31).

10
7

Figure 31. Two variables activated for Import in BikeSim.

Export Variables
A similar screen is used to define the set of variables that are exported from the VS solver to
Simulink. Navigate to the I/O Channels: Export screen by first clicking the Back button to return
to the Models: Simulink screen (Figure 24, page 13) and then clicking on the blue link for the
Export Channels .
You should now be viewing the I/O Channels: Export screen (Figure 32, shown for CarSim
during step 6 below). Initially, there will be no variables shown (similar to the Import screen as
shown in Figure 25, page 13). You will go through similar steps to obtain information about all
available output variables, and select those that should be activated for export to Simulink.
1. Use the drop-down control to Choose run to get export information . When this option is
selected, a potential link is shown for a Run Control dataset .

16 / 23
 2
1 4 5

6 10
7

Figure 32. Activating variables for export out of the vehicle S-Function block.
2. Use the drop-down control for the potential link to choose the same Run Control dataset
that you selected as a reference for the Import variable screen (the new braking run). As before,
two documentation files are automatically generated. In this case, they list all variables in the
math model that might potentially be exported to Simulink. One of the files is the tabbed-text
file shown in the yellow field . The number of variables is written underneath (there are 641
output variables for this example). The other is a spreadsheet file, accessible with the View
Spreadsheet button .
3. As before, use the Categories drop-down control to choose the option Select by type of
component. Notice that a list of component types is shown under the control .
4. Select the component type Wheels . The list of available variables is adjusted to show
only variables related to Wheels.
5. Right-click on any of the available variables to see a longer name in a pop-up field .

Note Some of the right-click descriptions have extra information. For example,
the information shown for variable Vx_L1 includes a description of how
it is defined mathematically. When there are groups of similar variables
applied for repeated parts, such as the four wheels of this vehicle, only the
first variable in the group has the extra information. If you right-click on
the next variable (Vx_L2), the description has only basic information.

6. For CarSim and TruckSim, find the output variable in the Available Variables list with the
name Vx_L1 and double-click on it. The variable will appear in the list Variables Activated
for Export .

17 / 23
 Add three more wheel variables by double-clicking on their names in the Available Variables
list: Vx_L2, Vx_R1, and Vx_R2.
Two more variables are needed for the CarSim and TruckSim examples that are not in the
Wheel category. To access them, use the Categories drop-down control to choose the
option Show all variables, and then select the variables Vx_SM and Pbk_Con.
The list Variables Activated for Export should match Figure 33.

10

Figure 33. Six variables activated for Export in CarSim and TruckSim examples.
For BikeSim, activate the five output variables listed in Figure 34.

2 5
1 4

6
10

Figure 34. Five variables activated for Export from BikeSim.

7. You have now completely specified all of the variables that will be exchanged between the
vehicle model and the external Simulink model for this example. Having done this, we will
now consider one more control on the Models: Simulink screen. Click the Back button to
return to this screen (Figure 35).
8. Right-click on the checkbox Sync kinematical exports with force imports . This checkbox
is only shown when the integration method is Euler or AB-2; it is not applicable for other
methods. With these two integration methods (Euler and AB-2), VS Solvers support two
options for controlling the timing of the communication with outside software, specified with
the system parameter OPT_IO_SYNC_FM that is set with this checkbox.

18 / 23
 1

2 3

Figure 35. The option to synchronize exports with force imports.

a. When the box is not checked (OPT_IO_SYNC_FM = 0), all of the model calculations
are made for the simulation time T that is received from Simulink. This sequence works
perfectly if the variables imported into the VS S-Function are based on factors external
to the vehicle model, such as clock time.
b. On the other hand, if the Simulink model calculates forces, moments, or brake
pressures for the vehicle model based on variables that were exported by the vehicle
model, then there is a time delay of one step introduced because the forces and
moments won’t be provided to the model until the next time step. When the box is
checked (OPT_IO_SYNC_FM = 1), kinematical variables exported from the VS S-
Function are calculated for the next time step (T + TSTEP). With this option, forces
and moment variables from Simulink will be synchronized for the next time step, when
they are imported.
In this ABS example, five of the exports are kinematical variables (speeds) and the sixth is a
control (master cylinder brake pressure). Be sure the box is checked.
For more information about this advanced feature, please see the VS Solver Programs
Reference Manual.
9. Return to the Run Control screen by clicking the Home button (Figure 36).

19 / 23
 1

Figure 36. The Run Control dataset.

10. Click the Send to Simulink button . The VS Browser will again load the Simulink model
(Figure 37), using updated connection information.

1 2

Figure 37. Simulink model with connections to the CarSim S-Function.

11. Display the signal dimensions. Note that Figure 37 shows four imports and six exports
(CarSim and TruckSim), matching the setups made earlier with the Import and Export datasets.
Figure 38 shows similar information for BikeSim (two imports and five exports ).
12. Run the model from Simulink by clicking the Play button (Figure 37) and confirm that the
same results are obtained as were seen in the original example.

20 / 23
 1 2

Figure 38. Simulink model with connections to the BikeSim S-Function.

About the Vehicle S-Function Block

Now that the link between the vehicle model and the Simulink model has been specified and
confirmed, we will look at the S-Function block in the Simulink model shown in Figure 37.
The VS S-Function has several properties that are set automatically to both represent the vehicle as
specified in the VehicleSim product and to fit with the signal requirements of the Simulink model.
These include the organization of the import variables and the export variables .

Note If you change the vehicle, its properties, or the sets of import or export
variables from the VS browser, you must click the Send to Simulink
button to update the model in Simulink.

Import and Export Variables

When you click the Send to Simulink button to update the model in Simulink, the VS S-Function
sets up import and export arrays based on settings from the Import and Export datasets that are
linked to the Models: Simulink dataset, as shown in the previous section.
In order for the Simulink model to work properly, it is critical that the number of Import and Export
variables defined from the VS side match the signal dimension in the Simulink model. It is equally
critical that the variables be specified in the order expected in the Simulink model.
The selection process used in the previous section was specific to the design of the ABS controller
models provided in CarSim, TruckSim, and BikeSim. If the Simulink model expects different
variables for Import or Export, then the Import and Export datasets must be manually created to
match the requirements.

Simulink Configuration Parameters

The Simulink model may involve underlying differential equations that are solved by Simulink
using numerical methods. For example, the ABS controller models provided with CarSim,
TruckSim, and BikeSim each have a brake actuator system (the magenta box) with fluid dynamics
represented with transfer function blocks. Some of the methods used to solve the equations can be
viewed and adjusted. To do this, use the Simulink Simulation menu item Model Configuration
Parameters to display a dialog box (Figure 39).

21 / 23
 1

Figure 39. Simulink Configuration Parameters.

The VS Solver always solves its own equations at a fixed time step, whether it runs by itself, with
Simulink, or with other software. From the point of view of Simulink, the VS S-Function block is
always a discrete system.
You can configure the Simulink model as a continuous system with either fixed or variable-step
solvers, so long as the Simulink parameter settings are compatible with the discrete time step used
by the VS solver.
When transferring control from the VS Browser to Simulink, simulation parameters such as the
start time and stop time are sent automatically. For example, the stop time of 10 s was specified
in the Procedure dataset for this example simulation.

Multiple Ports
The VS S-Function supports Simulink models with multiple Import and Export ports. The database
for your VehicleSim product includes a multiport version of the ABS example, such as the CarSim
example shown in Figure 40.
In comparing the multiport version to the single-port version shown earlier (Figure 37, page 20),
you see the same blocks for the Brake Actuator Model , the ABS Controller Model , and the
CarSim S-Function . However, in in the multiple-port case, there are four import ports for
CarSim and three export ports .
The setup for this model from the VS Browser is almost the same as shown earlier. Figure 41 shows
the lower-left part of the Models: Simulink dataset, with the sidebar visible in order to see the
linked datasets . In this case, the blue links for Import and Export channels are not used,
and a link is made to an I/O Channels: Ports dataset . The I/O Channels: Ports dataset is
shown in the background of Figure 40.
The I/O Channels: Ports screen shows drop-down controls that specify four import ports
(Figure 40) and three export ports . Each Import port is represented with an Import dataset
and each Export port is represented with an Export dataset . The number of ports can be set to
anything between 0 and 20. The Import and Export datasets are made from the same libraries shown
for single-port models, in the previous section.

22 / 23
 2 3

1 4

6
5 7

Figure 40. Alternate version of the ABS Model using multiple ports.

Figure 41. Models: Simulink dataset for multiport version of ABS example.

23 / 23