Mechanical Simulation Technical Memo 912 North Main, Suite 210, Ann Arbor MI, 48104, USA Phone: 734 668-2930 • Fax: 734 668-2877 • Email: info@carsim.com www.carsim.com

July 9, 2008 1 / 25

Extending a VS Solver: A Steer Control Example Introduction .................................................................................................................... 1 An Example Model Extension ....................................................................................... 2

Existing Model Documentation............................................................................ 2 The Steering Controller Definition....................................................................... 3

Programming the Steer Controller with VS Commands ................................................ 4 The VS Commands............................................................................................... 4 Running the Extended Model ............................................................................... 5

Extending the Model with a Programming Language: Overview.................................. 7 Extending the Model with Visual Basic (VB)................................................................ 8

The VB Program................................................................................................... 8 Running the VB Program ..................................................................................... 11

Extending the Model with MATLAB ............................................................................ 13 The MATLAB M File .......................................................................................... 13 Running the VB Program ..................................................................................... 17

Extending the Model with ANSI C ................................................................................ 19 Setting up the external code with external_setdef ................................................ 19 Defining external calculations with external_calc................................................ 21 Adding more information to an echo file with external_echo .............................. 22 Handling more information from input parsfiles with external_scan................... 23 Running the extended model ................................................................................ 24

Summary ........................................................................................................................ 25

This technical memo shows by example how a VehicleSim (VS) vehicle model is extended to include an alternative steering controller. The original memo from January 2007 has been updated to match revisions made during the release of CarSim 7.1 and to include examples in three programming languages (Visual Basic, MATLAB, and C).

Introduction The VS solver has a math model with “native” equations that simulate the response of a vehicle to driver controls while traveling on a 3D road surface. The VS solver can be extended to handle custom controllers and alternate component models using an external simulation environment such as Simulink. However there are three other general methods that can also be used to extend the model:

1. Equations can be added at runtime using VS commands.

2. Equations can be written in a programming language and combined with the capabilities of the VS solver using the VS application program interface (API) and the exchange of import and output arrays of variables.

2 / 25

3. Equations can be written in custom C routines and new variables can be defined in C and installed using the VS API.

This memo extends the model using these three methods.

VS commands are described in the VehicleSim Math Models: Solver Program Reference Manual (the VS Solver Manual) and require no additional software beyond a product from Mechanical Simulation such as CarSim. The other three versions use methods described in The VehicleSim API: Accessing and Extending VehicleSim Solver Programs (the VS API Manual).

An Example Model Extension A simple steering control will be based on a “preview point” in front of the vehicle and its relationship to the road centerline. If the point is not on target, a steering wheel angle is calculated that is proportional to the lateral distance between the point and the target lateral position. Figure 1 shows the point represented with an arrow in front of the vehicle. The intended location is the center of the right-hand lane. The arrow is a little to the left of the target line, and therefore the the vehicle steering wheel should be turned to the right.

Figure 1. Vehicle with a preview point for a simple steering controller.

Existing Model Documentation The full list of available import variables for a VS model is available in two readme files: one for viewing with a text editor, and one for viewing as a spreadsheet. The list can be viewed quickly in either format by using the View button in the lower-right corner of the Run Control screen of a product such as CarSim.

Browsing the readme file for any of the vehicle models in CarSim or TruckSim shows that they all include steering wheel angle as a variable that can be imported.

3 / 25

The default settings for all of the import variables are that they be ignored. The setting for the steering wheel can be changed easily by using the library screen I/O Channels: Import to activate the steering wheel import variable. This can also be accomplished by providing a line of text in a file that will be read as input to the model:

IMP_STEER_SW REPLACE 0 (1)

Although the native equations in the VS solver include the effect of the imported steer, they do not define the angle. (After all, the whole purpose of the imported steer is to replace or modify the value already available in the native equations of the model.)

The output variables available in a VS model are contained in readme files similar to those that list the available import files. (The readme file for outputs can also be viewed using the View button on the Run Control screen.) Reading through the list of available variables shows that there are many X and Y coordinates, for points such as the origin of the sprung mass coordinate system, the vehicle center of gravity (CG), etc. A preview point for a new steering controller can be based on any of the existing X and Y coordinate pairs. In this example, the X and Y coordinates of the vehicle CG will be used.

The Steering Controller Definition The desired steer angle will be:

STEER_CTRL = (LAT_TRACK – ROAD_L(XPREVIEW, YPREVIEW))*GAIN_STEER_CTRL (2)

where

LAT_TRACK is the target lateral position relative to the road centerline,

ROAD_L is a function available in VS solvers (see the VS Solver Manual) that gives the lateral distance of a point defined by X and Y coordinates relative to the road centerline,

XPREVIEW and YPREVIEW are X and Y coordinates of a point in front of the vehicle, and

GAIN_STEER_CTRL is a constant used to scale the steering wheel angle.

The X and Y coordinates of the preview point are:

XPREVIEW = XCG_TM + L_FORWARD*COS(YAW) (3)

YPREVIEW = YCG_TM + L_FORWARD*SIN(YAW) (4)

where

XCG_TM and YCG_TM are the X and Y coordinates of the center of mass of the entire vehicle, as listed in the readme file for available outputs,

YAW is the yaw angle for the vehicle, as listed in the readme file for available outputs, and

L_FORWARD is the distance the preview point lies in front of the vehicle mass center.

The controller calculation is potentially complicated at the start of the run because not all of the output variables have been calculated yet. To maintain simplicity, the steering wheel angle will be defined as 0 prior to the start. One way to accomplish this is with equation:

IMP_STEER_SW = IF_GT_0_THEN(T - TSTART, STEER_CTRL, 0) (5)

4 / 25

Programming the Steer Controller with VS Commands This section describes how the steer controller is added to the math model using VS commands.

The VS Commands In reviewing the equations needed to calculate steering wheel angle, we see that they involve four existing output variables (T, XCG_TM, YCG_TM, and YAW), two new variables (XPREVIEW and YPREVIEW ), and three new constants (LAT_TRACK, GAIN_STEER_CTRL, and L_FORWARD). The new variables XPREVIEW and YPREVIEW that are used to calculate the steering would also be helpful if available for plotting, and for animating to show the preview point (see Figure 1).

Listing 1 shows a complete set of VS commands for adding the necessary variables and equations. (The line numbers do not exist in the actual file; they are shown to support the following discussion.)

Listing 1. VS Commands for the simple steering control. 1. ! Simple Steer Controller 2. ! Define new units for control parameter 3. define_units deg/m 57.29577951 4. ! Define 3 new parameters 5. define_variable L_FORWARD 20; units = m ! View point distance (parameter) 6. define_variable LAT_TRACK -1.6; units = m ! distance to driver's left 7. define_variable GAIN_STEER_CTRL 10; units = deg/m ! Control gain (parameter) 8. ! Define 2 new outputs 9. define_output Xpreview = XCG_TM + L_FORWARD*cos(YAW); units = m ; 10. define_output Ypreview = YCG_TM + L_FORWARD*sin(YAW); units = m ; 11. ! Define extra variable for steer control 12. define_variable steer_ctrl 13. !Add equation to define imported steering wheel angle 14. eq_in steer_ctrl = (LAT_TRACK - road_l(Xpreview, Ypreview))*GAIN_STEER_CTRL ; 15. eq_in IMP_STEER_SW = IF_GT_0_THEN(t - tstart, steer_ctrl, 0); 16. ! Activate steering import 17. IMP_STEER_SW replace 0 18. ! 19. ! Define detailed output titles 20. set_output_long_name Xpreview X coord. of driver look-point 21. set_output_long_name Ypreview Y coord. of driver look-point 22. set_output_generic Xpreview X coordinate 23. set_output_generic Ypreview Y coordinate 24. set_output_component Xpreview Driver look-point 25. set_output_component Ypreview Driver look-point

The three new constants are added in lines 5 - 7 and the new dynamic variables are defined as outputs in lines 9 and 10, using the definitions from equations 3 and 4.

Note that the VS commands allow the units to be specified. Every parameter, import, and output variable in a VS model has associated units. As described in the VS Solver Manual, conversions

5 / 25

are made automatically between user units shown for input and output files, and internal dynamical units used for internal calculations. For example, steering wheel angle has user units of degrees, and internal units of radians. Any input angles are divided by 57.29577951 to convert from degrees to radians. For output, the angles are multiplied by 57.29577951 to convert from radians to degrees.

Existing user units are shown in the readme files and the echo files generated with each run.

Note The internal units are generally SI, and by definition require no scale factors for internal calculations. There is a parameter OPT_ECHO_ALL_UNITS that can be set to show everything about the current units system in the echo file, including all of the scale factors that relate user units to internal units.

Most of the new variables and parameters that will be introduced for this example will have units of length. The commands in the listing specify meters, because meters are used for most of the road geometry. The exception is the constant GAIN_STEER_CTRL, which should have units of steer per unit of lateral distance: deg/m.

If the run is made without the command from line 3, an error message appears saying the units “deg/m” are not installed. To allow the use of “deg/m,” the DEFINE_UNITS command on line 3 is used to install everything the solver needs to know about the new units: the printed name is “deg/m” and the scale factor is 57.29577951. After the new units are installed they can be specified with the keyword “DEG/M” (not case sensitive), as shown in line 7.

Line 12 adds an intermediate variable for the steering wheel angle, and lines 14 and 15 provide equations 2 and 5. Line 17 activates the imported steering wheel angle with a copy of equation 1.

At this point (line 17), the steering controller is fully defined and the additional X and Y output coordinates are available for plotting and animation. Lines 20 - 25 in the listing could be considered optional. They provide labeling information to allow nice plot labeling with the two new variables.

The VS commands are shown in the echo files generated by the solver programs when runs are made. Most commands appear at the end of the file, as shown in the excerpt in Listing 2. The printed version in the echo file is not necessarily identical in appearance to the original commands (see Listing 1), but it has the same meaning and will give identical results if used in future runs. One difference is that all variables are shown in upper case, regardless of how they were provided as input. Another difference is that some of the commands are broken up into multiple commands when printed. For example, the commands to add output variables for the X and Y coordinates of the preview point included equations. In the echo file shown in Listing 2, the same information is provided in two commands: one to introduce the variable and one to add an equation for calculating new values at each time step.

Whenever the units system of the VS solver is modified (e.g., adding the new units “deg/m”), a set of commands appears at the top of the echo file to fully specify the units system as it was modified in the run.

Running the Extended Model The commands from the listing can be placed anywhere in the VehicleSim database where they would be passed to the math model when it reads inputs for a new run. The screen Models: Self-Contained Solvers provides a convenient location for model extensions such as this example.

6 / 25

(Another convenient location is the Generic VS Commands screen.) Figure 2 shows the linked dataset with the commands form Listing 1. Note that is also links to a dataset for showing the red arrow at the previous point, as seen in Figure 1.

Listing 2. Excerpts of echo file, showing VS commands for steering example. … !----------------------------------------------------------------------------------- ! CURRENT UNIT-SYSTEM KEYWORDS, WRITTEN DESCRIPTIONS, AND SCALE FACTORS !----------------------------------------------------------------------------------- DEFINE_UNITS deg/m 57.2958 … !----------------------------------------------------------------------------------- ! NEW VARIABLES DEFINED AT RUN TIME !----------------------------------------------------------------------------------- DEFINE_VARIABLE L_FORWARD = 20; UNITS = m; DEFINE_VARIABLE LAT_TRACK = -1.65; UNITS = m; DEFINE_VARIABLE GAIN_STEER_CTRL = 10; UNITS = deg/m; DEFINE_VARIABLE STEER_CTRL = -1.4399; DEFINE_OUTPUT Xpreview = 0; UNITS = m; SET_OUTPUT_LONG_NAME XPREVIEW X coordinate of driver look-poin; SET_OUTPUT_COMPONENT XPREVIEW Driver look-point; SET_OUTPUT_GENERIC XPREVIEW X coordinate; DEFINE_OUTPUT Ypreview = 0; UNITS = m; SET_OUTPUT_LONG_NAME YPREVIEW Y coordinate of driver look-poin; SET_OUTPUT_COMPONENT YPREVIEW Driver look-point; SET_OUTPUT_GENERIC YPREVIEW Y coordinate; !----------------------------------------------------------------------------------- ! EQUATIONS IN (AT START OF EACH TIME STEP) !----------------------------------------------------------------------------------- EQ_IN STEER_CTRL = (LAT_TRACK -ROAD_L(XPREVIEW, YPREVIEW))*GAIN_STEER_CTRL ; EQ_IN IMP_STEER_SW = IF_GT_0_THEN(T -TSTART, STEER_CTRL, 0) ; !----------------------------------------------------------------------------------- ! EQUATIONS OUT (AT END OF EACH TIME STEP) !----------------------------------------------------------------------------------- EQ_OUT XPREVIEW = XCG_TM + L_FORWARD*COS(YAW) ; EQ_OUT YPREVIEW = YCG_TM + L_FORWARD*SIN(YAW) ; !----------------------------------------------------------------------------------- ! EVENTS !----------------------------------------------------------------------------------- ! Each event is defined with the name of an output variable that is monitored, a ! comparison '<' or '>', a threshold equation, and a pathname with input data to ! read to restart the run if the threshold is reached. If no pathname is ! specified, the run is stopped. !----------------------------------------------------------------------------------- ! IMPORTED VARIABLE NAMES, RELATIONS TO NATIVE VARIABLES, AND INITIAL VALUES !----------------------------------------------------------------------------------- IMP_STEER_SW REPLACE 0 ! #1. Steering wheel angle (deg) END

7 / 25

Figure 2. Appearance of the VS commands on a Models library screen.

Figure 3. Linking to VS commands in the Models: Self-Contained Solvers library.

Figure 3 shows how this dataset is linked to the Run Control screen.

Extending the Model with a Programming Language: Overview The same steering control will be programmed several languages in the following sections of this memo. In each case, a short program will load the VS solver DLL and make the run. The vehicle Yaw and X and Y coordinates will be exported, a VS API equivalent of the ROAD_L function will be used to determine the lateral tracking of the preview point, and a steering wheel angle will be computed for use in the vehicle model. In addition, the X and Y coordinates of the preview

8 / 25

point will be sent to the VS solver in order to put the coordinate in the output file for the animator to show the red arrow as seen in Figure 1.

In normal operation, the top-level input file for the VS solver is a simfile (with the default name simfile) that contains pathnames for the input parsfile for the solver, plus names of output files to be generated by the solver, plus the pathname for the solver DLL. (Details of this process are presented in the VS Solver Manual.) The normal way to load a VS solver DLL is by first reading simfile to get the pathname for the DLL, then loading the DLL, then getting access to the VS API functions from the DLL, and finally, using the VS API functions to make the run. Details of this process are covered in the VS API Manual and are summarized here as four steps.

1. Load. The DLL is loaded using a pathname read from a simfile and the VS API functions are located.

2. Initialize. The VS solver reads input data from a parsfile whose pathname is also obtained from the simfile, and then initializes the internal math model.

3. Run. The run is made with a simple loop in which the VS solver integrates the equations of motion.

4. Terminate. The run terminates and the DLL is unloaded.

Extending the Model with Visual Basic (VB) Running a VS solver from a program written in VB is fairly easy, and this example shows the process. The example VB program can be modified as might be needed for customized automation.

It should be noted that integration of the code from VB with the internal workings of the VS solver DLL is limited in comparison to the extensions that are possible in ANSI C. However, it is indeed possible to make simple extensions to the model and run the VB program from the Run Control screen, as will be shown for the example steering controller.

The VB Program The process of loading and running the solver from VB requires that some of the information must be set manually (hard-coded). Listing 3 shows how the name of the DLL and six of the VS API function names are declared in VB. If more VS functions will be used, they should be declared in the same style.

Note that the name of the DLL appears in every Declare statement. If running with a VS solver with a different name, then lines 6, 9, 10, 11, 13, and 15 would be modified to use the alternative name.

Variables needed to run any VS math model are declared in lines 17 – 19. Additional variables used to implement the steering controller are declared in lines 20 and 21.

Next, the program reads a simfile to get the location of the DLL file (lines 24 – 39).

9 / 25

Listing 3. Visual Basic code for loading a VS solver. 1. Imports System.IO 2. Module Steer_Control 3. ' Declare the VS API functions that will be used to make a run. 4. ' The name of the DLL is hard-coded here; change to match the DLL of interest, 5. ' e.g. i_i.dll, i_s.dll etc. 6. Declare Sub vs_read_configuration Lib "i_i.dll" _ 7. (ByVal Simfile As String, ByRef n_imp As Integer, ByRef n_exp As Integer, _ 8. ByRef tstart As Double, ByRef tstop As Double, ByRef tstep As Double) 9. Declare Function vs_error_occurred Lib "i_i.dll" () As Integer 10. Declare Function vs_get_output_message Lib "i_i.dll" () As String 11. Declare Function vs_integrate_io Lib "i_i.dll" _ 12. (ByVal t As Double, ByRef import As Double, ByRef export As Double) As Integer 13. Declare Function vs_road_l Lib "i_i.dll" _ 14. (ByVal sXprevAs As Double, ByVal Ypreview As Double) As Double 15. Declare Sub vs_terminate Lib "i_i.dll" (ByVal t As Double, ByVal func As Integer) 16. Sub Main() 17. Dim n_import, n_export, status, ibarg, print_interval, i, j As Integer 18. Dim SIMFILE, strBuff, DLL_Dir, VS_Msg As String 19. Dim t_start, t_stop, t_step, t_current, D2R As Double 20. Dim Lfwd, GainStr, LatTrack, ImpStr As Double 21. Dim Xpreview, Ypreview, Xcg, Ycg, Yaw, road_l As Double 22. D2R = 3.1415926 / 180 23. ' Get full pathname for simfile 24. SIMFILE = Directory.GetCurrentDirectory() + "\simfile" 25. ' Open simfile to get DLL folder location 26. FileOpen(1, SIMFILE, OpenMode.Input) 27. strBuff = "input string" 28. Do Until EOF(1) 29. Input(1, strBuff) 30. i = InStr(strBuff, "DLLFILE ") 31. If i = 1 Then 32. j = InStrRev(strBuff, "\") 33. DLL_Dir = Mid(strBuff, i + 8, j - i - 8) 34. ' Change current folder to DLL folder 35. ChDir(DLL_Dir) 36. Exit Do 37. End If 38. Loop 39. FileClose(1)

10 / 25

Listing 4. Initializing the math model and making the run from VB. 40. ' Call vs_read_configuration to read parsfile and initialize the VS solver. 41. ' Get no. of import/export variables, start time, stop time and time step. 42. vs_read_configuration(SIMFILE, n_import, n_export, t_start, t_stop, t_step) 43. VS_Msg = vs_get_output_message() 44. Console.WriteLine(VS_Msg) 45. ' Check if error occurred 46. status = vs_error_occurred() 47. Lfwd = 20.0 48. GainStr = 10 * D2R 49. LatTrack = -1.6 50. ImpStr = 0 51. print_interval = (t_stop - t_start) / t_step / 50 52. ibarg = print_interval 53. t_current = t_start 54. ' Create import and export arrays based on sizes from VS solver 55. Dim import(0 To n_import - 1) As Double 56. Dim export(0 To n_export - 1) As Double 57. 'Run integration loop 58. Do While (status = 0) 59. ' Call integration function 60. status = vs_integrate_io(t_current, import(0), export(0)) 61. ' Get 3 variables that were exported from the VS solver 62. Xcg = export(0) 63. Ycg = export(1) 64. Yaw = export(2) * D2R 65. Xpreview = Xcg + Lfwd * Math.Cos(Yaw) 66. Ypreview = Ycg + Lfwd * Math.Sin(Yaw) 67. If t_current > t_start Then 68. road_l = vs_road_l(Xpreview, Ypreview) 69. ImpStr = GainStr * (LatTrack - road_l) / D2R 70. End If 71. ' Prepare 3 variables that are imported to the VS solver 72. import(0) = ImpStr 73. import(1) = Xpreview 74. import(2) = Ypreview 75. t_current = t_current + t_step 76. ' Update bar graph to show progress 77. If ibarg >= print_interval Then 78. Console.Write("=") 79. ibarg = 0 80. End If 81. ibarg = ibarg + 1 82. Loop 83. 'Terminate solver 84. vs_terminate(t_current, 0&) 85. End Sub 86. End Module

11 / 25

Listing 4 shows the remainder of the VB program. It continues by using the VS API function vs_read_configuration (line 42) to handle the Initialize part of the simulation:

1. get the Parsfile name from SIMFILE,

2. read the parsfile to get values for all parameters of the math model,

3. initialize the math model, and

4. provide values for the number of import variables (n_import), export variables (n_export), start time (t_start), stop time (t_stop), and time step (t_step).

Parameters used for the steering controller are given values in lines 47 – 49.

When running a VS solver from Visual Basic, arrays of import and export variables are used to communicate between the VS solver and the calling program. The number of imports (n_import) and exports (n_export) were obtained by vs_read_configuration (line 42) and are used in lines 55 and 56 to define arrays with the proper dimensions.

The main simulation loop starts with the Do While command (line 58) and continues to the matching Loop statement on line 82. The VS solver updates the math model equations via the function vs_integrate_io (line 60), and will continue as long as the function returns a value of 0.

The three variables from the VS solver (X coordinate, Y coordinate, and Yaw) are exported using the array export and are used to compute the X and Y coordinates of the previous point (XPreview and Ypreview) and the steering wheel angle (ImpStr). The VS API function vs_road_l is used in line 68 to compute the lateral distance to the road reference line at the point defined with coordinates XPreview and Ypreview.

The three calculated variables are copied into the array import (lines 72 – 74) so they can be sent to the math model at the next time step (line 60).

The simulation time is updated in line 75, in preparation for the next call to the function vs_integrate_io (line 60).

The Do While loop stays in effect as long as the vs_integrate_io function returns 0. When the run ends, the vs_terminate function (line 84) updates all open VS files and then closes them.

Running the VB Program In order for the arrays defined in the VB code to work with the VS solver, the solver must be set up to activate the appropriate import and export variables. A dataset in the library Models: Self-Contained Solvers can be used to specify the program compiled from the VB and also datasets for import and export variables (see Figure 4). For this example:

• the external wrapper field specifies the EXE file generated by compiling the VB program 1 ;

• one of the misc. links 3 is set to I/O Channels: Import dataset shown in Figure 5; and

• another misc. link 4 is set to the I/O Channels: Export dataset shown in Figure 6.

12 / 25

1

2

3

4

Figure 4. Dataset for VS program that also specifies import and export variables.

Figure 5. Activation of three import variables provided by external program.

13 / 25

Figure 6. Activation of three output variables for use in external program.

Two of the import variables are passed through to the animator, to show a red arrow at the preview point (see Figure 1). In order for the animator setup used for the example with VS commands to also work for this VB example, two VS commands are used to introduce output variables with the same names. The values for these variables are imported from the VB program (see the commands 2 in Figure 4).

Extending the Model with MATLAB VS solvers are ready to run from within MATLAB/Simulink as S-Functions, and many users extend the models using Simulink. Alternatively, the solvers can be run directly from MATLAB (without Simulink) by using the API. The general method for loading and running the VS solver in MATLAB is the same as in VB.

The MATLAB M File Listing 5 shows the first part of a MATLAB file for running a VS solver. MATLAB is a little more dynamic than VS, allowing the name of the DLL file (SolverPath) to be obtained from the simfile (lines 11 - 30).

Next, the DLL is loaded (line 32, 33). The VS API functions are declared in another file vs_api_def_m.h, that is named when loading the solver (line 33).

A few commands that are commented out (lines 36 and 37) can be enabled to view the available VS API functions that were loaded.

14 / 25

Listing 5. Loading the VS solver DLL in MATLAB. 1. % Simple Steering control example to show you how to use an M-File script 2. % wrapper to work with a VS solver DLL 3. clc; 4. D2R = pi/180; 5. R2D = 180/pi; 6. % Check if last loaded library is still in memory. If so, unload it. 7. if libisloaded('vs_solver') 8. unloadlibrary('vs_solver'); 9. end 10. % Open simfile 11. simfile = 'simfile'; 12. SIMFILE = fopen(simfile, 'r'); 13. if SIMFILE == -1 14. fprintf('\n Error: Can''t find out simfile.\n\n'); 15. return; 16. end 17. % Scan simfile to get the pathname for the VS DLL 18. SolverPath = []; 19. while 1 20. tmpstr = fgetl(SIMFILE); 21. if tmpstr == -1 % File end 22. break; 23. end 24. if strncmpi(tmpstr, 'DLLFILE', 7) 25. [keyword SolverPath] = strtok(tmpstr); 26. SolverPath(1) = []; 27. break; 28. end 29. end 30. fclose(SIMFILE); 31. % Load solver DLL 32. [notfound, warnings] = ... 33. loadlibrary(SolverPath, 'vs_api_def_m.h', 'alias', 'vs_solver'); 34. disp('The VS DLL is loaded.'); 35. % Display function list in the DLL 36. %libfunctions('vs_solver', '-full'); 37. %libfunctionsview('vs_solver');

Listing 6 shows the part of the MATLAB program that initializes the model. It uses the VS API function vs_read_configuration (lines 46 - 48) to get the Parsfile name from simfile, read the parsfile with all parameters for the math model, initialize the math model, and provide values for the number of import variables (n_import), export variables (n_export), start time (t_start), stop time (t_stop), and time step (t_step).

Some of the arguments to the VS API function vs_read_configuration are pointers, so special pointer variables are declared (lines 39 – 43) to set up the function call.

15 / 25

Listing 6. Initializing the math model from MATLAB. 38. % Define pointer 39. p_nimp = libpointer('int32Ptr', 0); 40. p_nexp = libpointer('int32Ptr', 0); 41. p_start = libpointer('doublePtr', 0); 42. p_stop = libpointer('doublePtr', 0); 43. p_step = libpointer('doublePtr', 0); 44. % Read parsfile, get number of channels for import/export 45. % get start time, stop time and time step and initialization 46. [str n_import n_export t_start t_stop t_step] = ... 47. calllib('vs_solver', 'vs_read_configuration', ... 48. simfile, p_nimp, p_nexp, p_start, p_stop, p_step); 49. msg = calllib('vs_solver', 'vs_get_output_message'); 50. disp(msg); 51. disp('Initialization is done.'); 52. % Check if error occurred 53. status = calllib('vs_solver', 'vs_error_occurred'); 54. if status 55. unloadlibrary('vs_solver'); 56. return; 57. end 58. % Set import/export pointer 59. imports = zeros(1, n_import); 60. p_imp = libpointer('doublePtr', imports); 61. exports = zeros(1, n_export); 62. p_exp = libpointer('doublePtr', exports); 63. % extend model with new steer equations. Start with new parameters 64. Lfwd = 20.0; % preview distance 65. GainStr = 10*D2R; % control gain for steering wheel angle 66. LatTrack = -1.6; % target lateral position 67. ImpStr = 0; % steering to be imported into VS solver 68. t_current = t_start; 69. print_interval = (t_stop-t_start)/t_step/50; 70. ibarg = print_interval;

As was done for the VB program, arrays of import and export variables are used to communicate between MATLAB and the VS solver. The number of imports (n_import) and exports (n_export) obtained by vs_read_configuration are used in lines 59 and 61 to define arrays with the proper dimensions. Pointers to those arrays are assigned to the variables p_imp and p_exp (lines 60 and 62) for later use during the run.

The parameters for the steering controller are given values in lines 64 – 66, and the steering wheel angle is set to 0 (line 67).

Listing 7 shows the rest of the MATLAB program.

The main simulation loop starts with the While statement (line 72) and continues to the matching end statement on line 98. The VS solver updates the math model equations via the function vs_integrate_io (line 75), and will continue as long as the function returns a value of 0.

16 / 25

Listing 7. Running and terminating the VS solver from MATLAB. 71. % Start integration loop 72. while ~status 73. set(p_imp, 'Value', imports); % Assign import value to pointer 74. % Call integration function 75. status = calllib('vs_solver', 'vs_integrate_io', t_current, p_imp, p_exp); 76. % Get variables exported from VS solver 77. exports = get(p_exp, 'Value'); 78. % Steering Controller variables 79. Xcg = exports(1); 80. Ycg = exports(2); 81. Yaw = exports(3)*D2R; 82. Xpreview = Xcg + Lfwd*cos(Yaw); 83. Ypreview = Ycg + Lfwd*sin(Yaw); 84. if t_current > t_start 85. road_l = calllib('vs_solver', 'vs_road_l', Xpreview, Ypreview); 86. ImpStr = GainStr*(LatTrack - road_l)*R2D; 87. end 88. % calculate values for 3 variables imported to VS solver 89. imports(1)= ImpStr; 90. imports(2)= Xpreview; 91. imports(3)= Ypreview; 92. t_current = t_current + t_step; 93. if ibarg >= print_interval 94. fprintf('='); 95. ibarg = 0; 96. end 97. ibarg = ibarg + 1; 98. end 99. fprintf('\n'); 100. % Terminate solver 101. calllib('vs_solver', 'vs_terminate', t_current, []); 102. disp('Simulation has finished.'); 103. % Unload solver DLL 104. unloadlibrary('vs_solver');

The three variables from the VS solver (X coordinate, Y coordinate, and Yaw) are exported using the array exports and are used to compute the X and Y coordinates of the previous point (XPreview and Ypreview) and the steering wheel angle (ImpStr). The VS API function vs_road_l is used in line 85 to compute the lateral distance to the road reference line at the point defined with coordinates XPreview and Ypreview.

The three calculated variables are copied into the array imports (lines 89 - 91) so they can be sent to the math model.

Lines 93 – 97 are not technically necessary, but provide visual feedback that the simulation is running by generating a bar graph with ‘=’ characters as the run proceeds. The VS command

17 / 25

vs_terminate causes the VS solver to clean up output files and free memory (line 101), and the DLL is then unloaded (line 104).

Running the MATLAB Program There are several ways to initiate a run using MATLAB. If the intent is to open MATLAB and control the simulation from within MATLAB, then the VS browser should be set up to generate the required simfile in the folder containing the MATLAB files. This information is normally provided using the Models: Transfer to Local Windows Directory screen, as shown in Figure 7. This screen is very similar to the one used for setting up the VB example (Figure 4), with the main difference being that a directory is specified 1 rather than a file name. As with the VS example, link 3 is set to I/O Channels: Import dataset (see Figure 5), and another misc. link

4 is set to the I/O Channels: Export dataset (see Figure 6).

When the dataset from Figure 7 is specified on the Run Control screen, the active button is Generate Files for This Run (see Figure 8). Clicking the button causes the browser to write a new simfile in the specified directory ( 1 in Figure 7). When runs are made under the control of MATLAB, all output files are written into the VS database so results can be viewed normally with the VS animator and plotter.

1

2

3

4

Figure 7. Dataset to identify M-File directory and also specify import and export variables.

18 / 25

Figure 8. Appearance of Run Control screen for the MATLAB example.

Listing 8. Loading the DLL and making a run from C. 1. /* ---------------------------------------------------------------------------- 2. Main program to run DLL with VS API. 3. ---------------------------------------------------------------------------- */ 4. void main(int argc, char **argv) 5. { 6. HMODULE vsDLL = NULL; // DLL with VS API 7. double t; 8. char pathDLL[FILENAME_MAX], simfile[FILENAME_MAX]={"simfile"}, *printMsg; 9. int ibarg = 0; 10. // get simfile from argument list and load DLL 11. if (argc > 1) strcpy (simfile, &argv[1][0]); 12. if (vs_get_dll_path(simfile, pathDLL)) return; 13. vsDLL = LoadLibrary(pathDLL); 14. if (vs_get_api_basic(vsDLL, pathDLL)) return; // get basic functions 15. if (vs_get_api_extend(vsDLL, pathDLL)) return; // get model extension functions 16. if (vs_get_api_road(vsDLL, pathDLL)) return; // get road functions 17. printMsg = vs_get_output_message(); // pointer to text from DLL 18. // Initialize VS model 19. t = vs_setdef_and_read(simfile, external_setdef, external_scan); 20. vss_check_for_dll_error (); 21. vs_initialize (t, external_calc, external_echo); 22. vss_print_message (printMsg); 23. vss_check_for_dll_error (); 24. // Run. Each loop advances time one full step. 25. while (!vs_stop_run()) 26. { 27. vs_integrate (&t, external_calc); 28. vss_check_for_dll_error (); 29. vs_bar_graph_update (&ibarg); // update bar graph? 30. vss_print_message (printMsg); 31. } 32. // Terminate 33. external_calc (t, VS_EXT_EQ_END); 34. vs_terminate (t, external_echo); 35. vss_print_message (printMsg); 36. vss_opt_pause (); 37. FreeLibrary (vsDLL); 38. return; 39. }

19 / 25

Extending the Model with ANSI C The VS solver programs are written in ANSI C, and the VS API allows a tight connection between the internal math model and external programming when the programming is done in C. The parameters for the new steering controller will not only be used in externally programmed equations, but they will be installed into the VS math model so new values can be set at runtime using the same VS GUI and database. Also, the values for the parameters will be shown in the echo files generated with each run.

Listing 8 shows the C program that scans the simfile and loads the DLL (lines 11 – 17), reads the parsfile and initializes the model (lines 19 – 23), runs the simulation (lines 25 – 31), and terminates the simulation (lines 33 – 38). (For more detail about this specific file, please see the VS API Manual.)

Model extensions can be installed in four functions that are compiled along with the program from Listing 8. These functions are passed as arguments to VS API functions in the code shown in Listing 8: functions external_setdef and external_scan are made available to the API function vs_setdef_and_read (line 19); function external_echo is provided to the API functionss vs_initialize (line 21) and vs_terminate (line 34); and function external_calc is provided to the API functions vs_initialize (line 21), vs_integrate (line 27), and is also called directly in the main function (line 33).

Setting up the external code with external_setdef Listing 9 shows some static variables that are shared by the four external functions.

Listing 10 shows the source code for external_setdef, the function that installs new variables and links to the variables in the VS solver.

Listing 9. Required include statements and some shared static variables. // VehicleSim header files and prototypes for these functions #include "vs_deftypes.h" // VS types and definitions #include "vs_api.h" // VS API structure definition #include "external.h" // prototypes for the functions in this file // define some static variables used for the controller static vs_real 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, // pointers to vehicle X, Y, and yaw *sImpStr, // pointer to imported steering wheel angle *sTstart; // pointer to start time static int sUseExternal; // option to use external model.

20 / 25

Listing 10. Example function external_setdef. 1. /* ---------------------------------------------------------------------------- 2. Set up variables for the model extension. For the steering controller, 3. define new units and parameters and set default values of the parameters 4. that will be used if nothing is specified at runtime. 5. ---------------------------------------------------------------------------- */ 6. void external_setdef (void) 7. { 8. int idX, idY; 9. 10. // set default values for parameters defined in this file 11. sUseExternal = 0; 12. sLfwd = 20.0; 13. sGainStr = 10.0*PI/180.0; 14. sLatTrack = -1.6; 15. 16. // C version of VS command: define_units deg/m 57.29577951 17. vs_define_units ("deg/m", 180.0/PI); 18. 19. // define two new parameters: L_FORWARD and LAT_ERR 20. vs_define_parameter ("L_FORWARD", 21. "Distance preview point is forward of vehicle CG", 22. &sLfwd, "M"); 23. vs_define_parameter ("LAT_TRACK", 24. "Lateral offset (to driver's left) for target", 25. &sLatTrack, "M"); 26. vs_define_parameter ("GAIN_STEER_CTRL", 27. "Control parameter: steering angle per meter of " 28. "lateral offset", &sGainStr, "DEG/M"); 29. 30. // define two new outputs using variables defined here 31. idX = vs_define_output ("Xpreview", "X coordinate of preview point", 32. &sXprev, "M"); 33. idY = vs_define_output ("Ypreview", "Y coordinate of preview point", 34. &sYprev, "M"); 35. 36. // set labels and units for new output variables 37. vs_set_sym_attribute (idX, OUTVAR_GEN_NAME, "X coordinate"); 38. vs_set_sym_attribute (idY, OUTVAR_GEN_NAME, "Y coordinate"); 39. vs_set_sym_attribute (idX, OUTVAR_BODY_NAME, "Steer control look point"); 40. vs_set_sym_attribute (idY, OUTVAR_BODY_NAME, "Steer control look point"); 41. vs_set_sym_attribute (idX, OUTVAR_UNITS, "M"); 42. vs_set_sym_attribute (idY, OUTVAR_UNITS, "M"); 43. 44. // get pointers to vehicle X, Y, yaw, and imported steering wheel angle 45. // that will be used in calculation made during the run 46. sXcg = vs_get_var_ptr("XCG_TM"); 47. sYcg = vs_get_var_ptr("YCG_TM"); 48. sYaw = vs_get_var_ptr("YAW"); 49. sImpStr = vs_get_var_ptr("IMP_STEER_SW"); 50. sTstart = vs_get_var_ptr("TSTART"); 51. }

21 / 25

In addition to the constants and variables for the steering controller, a new variable will be used to activate the controller: the integer sUseExternal. Lines 11-14 define the default values for these four parameters (variables that remain constant during a run).

Line 17 has the C equivalent of the VS command DEFINE_UNITS, and installs the “deg/m” units for the steering control gain. Note that the default value set for this gain in line 13 should be set with internal units (rad/m).

Lines 20 - 28 define three new parameters. Although a single VS command is used to add any kind of variable, the VS API has separate functions for defining parameters, import variables, outputs, and other miscellaneous variables. Variables added with the vs_define_parameter function are handled the same as native parameters when the solver reads a parsfile or generates an echo file. Note that the function takes the pointer to the variable as an input. The installation is such that when the keyword associated with the parameter is found in an input, the variable in the external code is updated properly. For example, if the keyword L_FORWARD is used in an input parsfile, the associated value is assigned to the variable sLfwd in the external code.

Lines 31 - 34 define two new output variables and also obtain ID numbers to the symbolic structures created within the VS solver. Those ID numbers are used with attribute codes (OUTVAR_GEN_NAME, OUTVAR_BODY_NAME, and OUTVAR_UNITS) in lines 37 - 42 to set names for the new output variables. These function call serve the same purposes as the VS commands SET_OUTPUT_GENERIC, SET_OUTPUT_COMPONENT, and SET_UNITS.

Up to this point (line 42), all code in Listing 10 has involved defining attributes of new variables that will be used in equations that will be added to the model. Lines 46 - 49 provide access to variables that have always existed in the VS solver, based on their associated keywords. This external code will work with any VS math model that has variables with the keywords shown: XCG_TM, YCG_TM, YAW, and IMP_STEER_SW. (This includes any vehicle in CarSim or TruckSim.) Note that the function vs_get_var_ptr returns a pointer to the internal variable. Therefore, the local copies sXcg, sYcg, sYaw, sImpStr, and sTstart were defined as pointers in Listing 9.

Defining external calculations with external_calc Listing 11 shows the source code for external_calc, the function that performs most of the calculations that extend the original model within the VS solver. This function has two arguments: the first is the current simulation time, and the second is the location in the equations. As noted in the comments (and in the VS API Manual), this function can be used in six places. In the case of the steering controller, only one is needed: VS_EXT_EQ_IN. This is at the beginning of each time step. Output variables are available from the previous time step, and imported variables can be computed for use in the native equation built into the VS solver (in the DLL).

Lines 75 and 76 always compute the new output variables, whether or not the new steer control is active.

Lines 78 - 81 handle the imported steering wheel angle. If the flag sUseExternal is FALSE then the steering is not touched. If the time is less than or equal to tstart, the steering is set to 0. Otherwise, the steering is set using the point-follower control equation (line 81).

22 / 25

Listing 11. Example function external_calc. 52. /* ---------------------------------------------------------------------------- 53. Perform calculations involving the model extensions. The function is called 54. from four places as indicated with the argument where, which can have the 55. values: VS_EXT_EQ_PRE_INIT, VS_EXT_EQ_INIT, VS_EXT_EQ_IN, VS_EXT_EQ_OUT, 56. and VS_EXT_EQ_END (defined in vs_deftypes.h). 57. ---------------------------------------------------------------------------- */ 58. void external_calc (vs_real t, vs_ext_loc where) 59. { 60. switch (where) 61. { 62. // initialization after reading parsfile but before init 63. case VS_EXT_EQ_PRE_INIT: 64. break; 65. 66. case VS_EXT_EQ_INIT: // initialization after reading parsfile 67. break; 68. 69. case VS_EXT_EQ_INIT2: // initialization after calculating outputs 70. break; 71. 72. case VS_EXT_EQ_IN: // calculations at the start of a time step 73. 74. // calculate X and Y coordinates of preview point 75. sXprev = *sXcg + sLfwd*cos(*sYaw); 76. sYprev = *sYcg + sLfwd*sin(*sYaw); 77. 78. if (!sUseExternal) ; // no effect if sUseExternal is FALSE 79. else if (t <= *sTstart) *sImpStr = 0.0; // no steering at the start 80. else // steer proportional to the lateral error 81. *sImpStr = sGainStr*(sLatTrack -vs_road_l(sXprev, sYprev)); 82. 83. break; 84. 85. case VS_EXT_EQ_OUT: // calculate output variables at the end of a time step 86. break; 87. 88. case VS_EXT_EQ_END: // calculations done at end of run 89. break; 90. } 91. }

Adding more information to an echo file with external_echo Listing 12 shows the source code for external_echo, the function that can write more information into an echo file.

When the VS solver writes an echo file, it will call this function in four places, identified with the argument where. A VS API function vs_write_to_echo_file is used to send a string to the DLL so the VS solver can in turn write the string to file.

In this example, we use two of the locations. First, additional text is written at the top of the echo file to tell users that the run was made with an extended model (lines 106 - 108). Next, the value of sUseExternal is written at the end of the block of system parameters in the echo file (lines 112 - 113).

23 / 25

Listing 12. Example function external_echo. 92. /* ---------------------------------------------------------------------------- 93. Write information into the current output echo file using the VS API 94. function vs_write_to_echo_file. This function is called four times when 95. generating the echo file as indicated with the argument where, which can 96. have the values: VS_EXT_ECHO_TOP, VS_EXT_ECHO_SYPARS, VS_EXT_ECHO_PARS, and 97. VS_EXT_ECHO_END (defined in vs_deftypes.h). 98. ---------------------------------------------------------------------------- */ 99. void external_echo (vs_ext_loc where) 100. { 101. static char buffer[200]; 102. 103. switch (where) 104. { 105. case VS_EXT_ECHO_TOP: // top of echo file 106. vs_write_to_echo_file ( 107. "! This model was extended with custom C code to provide a point-follower\n" 108. "! steer controller.\n\n"); 109. break; 110. 111. case VS_EXT_ECHO_SYPARS: // end of system parameter section 112. vs_write_i_to_echo_file ("OPT_USE_EXT_STEER", sUseExternal, 113. "! Use steering controller defined with external C code"); 114. break; 115. 116. case VS_EXT_ECHO_PARS: // end of model parameter section 117. break; 118. 119. case VS_EXT_ECHO_END: // end of echo file 120. break; 121. } 122. }

Listing 13 shows excerpts of the resulting echo file. Lines 5 and 6 identify the extension. Line 10 documents the state of sUseExternal.

In many cases, this function is not needed. (For this example, the function is used for an integer variable sUseExternal that is included mainly to provide an excuse for showing how to use external_echo and external_scan.) Note that the three variables added with the vs_define_parameter function are automatically included in the list of parameters, appearing in lines 15 - 17.

Handling more information from input parsfiles with external_scan Listing 14 shows the source code for external_scan, the function that can help process the information in an input parsfile. This capability is not needed for any variables added with vs_define_parameter, vs_define_import, or vs_define_output. However, it can be used to obtain information for other variables that are defined for use in the external functions. In this example, it is used read a value for the variable sUseExternal.

24 / 25

Listing 13. Excerpts of an echo file that created with the help of external_echo. 1. PARSFILE 2. ! CarSim 7- (VS Alpha 6) 3. ! Vehicle-suspension arrangement: i_i 4. ! Generated by VehicleSim 1.0 Alpha 6 on December 18, 2006 5. ! This model was extended with custom C code to provide a point-follower 6. ! steer controller. 7. TITLE Simple Driver Control (Road) #1 <* Custom Driver Model> 8. … 9. TSTOP 15 ! Stop when this time is reached (s) 10. OPT_USE_EXT_STEER 1 ! Use steering controller defined with external C code. 11. !----------------------------------------------------------------------------- 12. ! MODEL PARAMETERS 13. !----------------------------------------------------------------------------- 14. … 15. L_FORWARD 20 ! Distance preview point is forward of vehicle CG (m) 16. LAT_TRACK -1.6 ! Lateral offset (to driver's left) for target (m) 17. GAIN_STEER_CTRL 10 ! Control parameter: steering angle per meter of … 18. !----------------------------------------------------------------------------- 19. ! TABULAR DATA 20. !----------------------------------------------------------------------------- 21. …

Listing 14. Example function external_scan. /* ---------------------------------------------------------------------------- Scan a line read from the current input parsfile. Return TRUE if the keyword is recognized, FALSE if not. keyword -> string with current ALL CAPS keyword to be tested buffer -> string with rest of line from parsfile. ---------------------------------------------------------------------------- */ vs_bool external_scan (char *keyword, char *buffer) { if (!strcmp(keyword, "OPT_USE_EXT_STEER")) { sUseExternal = atoi(buffer); return TRUE; } return FALSE; }

Running the extended model To run with the extended model, it is necessary to specify that the compiled EXE program should be launched, and also to activate the imported steering wheel angle. This can be done with a dataset in the library Models: Self-Contained Solvers, as shown in Figure 9. In this case, the external wrapper field is identifies the compiled C program 1 , and two lines of inputs are provided to activate the imported steering wheel angle and external calculations 2 .

25 / 25

1

2

Figure 9. Specifying the compiled C program and activating the alternative steer control.

The variables from the external code are installed into the solver, and access to the variables within the solver is handled using C pointers. Because variables can be shared directly between the solver and the external code, the arrays of import and export variables used for the VB and MATLAB examples are not needed here.

Summary The purpose of this document was to show how a VS math model could be extended using four methods. The example is a steering controller, in which the vehicle is steered in proportion to the lateral distance between a preview point a fixed distance in front of the vehicle, and the target path (a constant distance to the left or right of a road centerline).

The first approach uses VS commands and requires no additional software beyond a package from Mechanical Simulation such as CarSim. To extend the model with VS commands:

1. Read through the detailed documentation (readme text files and echo files) to find the existing import and output variables of interest. Also, review the echo file for any existing parameters that would be used in equations you will add to the model.

2. Add variables to the model using VS commands such as DEFINE_VARIABLE, DEFINE_OUTPUT, and others (see the VS Solver Manual).

3. Add equations to the model using VS commands such as EQ_IN, EQ_OUT, EQ_DIFFERENTIAL, and others (see the VS Solver Manual).

4. Add extra information for user-friendliness, such as new units (e.g., “deg/m”) and labels for output variables.

The other three methods use programming languages to calculate the steering wheel angle. With MATLAB and Visual Basic (VB), the VS solver is loaded and run, and arrays are used to communicate between the new program and the math model in the VS solver.

More options exist when the programming language is C. Example source code files provided with VS products (CarSim, BikeSim, and TruckSim) can be modified to provide any extension possible with VS commands. In addition, complex model equations can be provided and integrated with the existing VS model. The example in this document showed how access is provided to internal variables in the existing solver, to allow the external calculations to be made with a mixture of existing model variables and new variables defined in the external code.