The CarMaker target for Real-Time Workshop comes with several example models. They can be found underExamples/RTW in the CarMaker installation directory:
• BodyCtrl
• TractCtrl
• UserSteer
All examples are complete with source code and parameter files.
5.7.1 Contents of the examples directory
Each example XXX typically consists of the following parts:
• README-XXX.txt
Text file containing a detailed description of the example.
• mdl/XXX.mdl
mdl/XXX_CarMaker_rtw/XXX_wrap.h mdl/XXX_CarMaker_rtw/XXX_wrap.c
Simulink model of the example, together with the wrapper source files.
• src_XXX
Directory containing everything needed to build a CarMaker simulation program with the example model integrated.
• Data/TestRun/Examples/Simulink/...
Data/Vehicle/...
Testrun and vehicle parameter files needed to run the example.
5.7.2 Preparing the examples
Before you can actually use the examples, some preparation is necessary.
Copying the examples into your project directory
The example directory contains nothing but the examples and is by no means a complete project directory. Instead it is intended to be added to a fresh project directory derived from the standardExamples/Car_Generic.
Simply copy the complete contents of theExamples/RTWdirectory into a new project direc-tory. Everything should fall into place and after the few remaining steps described below everything should be ready for your first simulation.
Choosing the right mdl directory
Since the model C code generated by Real-Time Workshop may differ significantly depend-ing on the Matlab version actually used, threemdldirectories are provided, one for each major Matlab version:
• mdl61 – for Matlab version 6.1
• mdl65 – for Matlab versions 6.5 and 6.5.1
• mdl70 – for Matlab versions 7.0, 7.0.1 and 7.0.4
Pick the directory that fits your Matlab version and either rename it tomdlor copy its con-tents to an existingmdldirectory. The files insrc_XXXexpect their remaining model parts to be found in themdl directory.
91 Integrating Simulink models
Demonstration examples
You probably won’t need the othermdldirectories so you may safely remove them from your project directory.
Setting the right Matlab version in the Makefiles
Just like choosing the right mdl directory, the Makefiles need to know which Matlab version you are using. Unfortunately this is hard to determine automatically.
In order to use example XXX, opensrc_XXX/Makefileusing your favourite ASCII editor and change the line
MATSUPP_MATVER = v6.5.1-r13
using one of the following values:
v6.1-r12.1 v6.5-r13 v6.5.1-r13 v7.0-r14 v7.0.1-r14 v7.0.4-r14
5.7.3 Rebuilding an example
A complete rebuild of example XXX just takes a few steps.
• In themdl directory, generate the C code of modelXXX.mdl.
• Compile the C code generated in directorymdl/XXX_CarMaker_rtw.
• Rebuild the CarMaker simulation program in thesrc_XXX directory.
These are the same steps as described in the chapter "Step-by-Step: Integrating a Simulink model".
92 CarMaker for Simulink
Demonstration examples
Chapter 6
CarMaker for Simulink
CarMaker for Simulink is a complete integration of IPG’s vehicle dynamics simulation soft-ware, CarMaker, into The MathWorks’ modeling and simulation environment, Matlab/Simu-link. The highly optimized and robust features of CarMaker were added to the Simulink environment using an S-Function implementation and the API functions that are provided by Matlab/Simulink. CarMaker for Simulink is not a loosely coupled co-simulation but a closely linked combination of the two best-in-class applications, resulting in a simulation environment that has both good performance and stability.
Because of this integration, it is now possible to use the power and functionality of CarMaker in the intuitive and full-featured environment of Simulink. And using CarMaker in Simulink is no different than using standard S-Function blocks or built in Simulink blocks.
The CarMaker blocks are connected the same way other Simulink blocks are connected, and existing Simulink models can now easily be added to the CarMaker vehicle model with literally a few clicks of the mouse.
Integration does not, however, mean a loss of functionality, as all the features that make CarMaker the premier software in its domain have been included, and can now be used in conjuction with Simulink’s rich tool set. The CarMaker GUI can still be used for simulation control and parameter adjustments, as well as defining maneuvers and road configurations.
IPG-CONTROL can still be used for data analysis and graphing. IPG-MOVIE can still be used to bring the vehicle model to life, with realistic animation and rendering of the multi-body vehicle model in 3-Dimensional space.
Access to CarMaker simulation results is possible using thecmreadutility that can be called from within Matlab. This utility loads the data of any CarMaker simulation results file into the Matlab workspace. After that, the data can be manipulated and viewed, e.g. for postpro-cessing purposes, using any of the available Matlab tools.
In short, CarMaker for Simulink is not a stripped down version of the original, but a complete system that can become a part of any Simulink simulation quickly and easily. This chapter of the Programmer’s Manual will show you just how easy it can be.
93 CarMaker for Simulink
CarMaker for Simulink basics
6.1 CarMaker for Simulink basics
6.1.1 Creating a new CarMaker project directory
Working with CarMaker for Simulink is organized around a so called project directory. Each project directory has a fixed directory structure with subdirectories likeData, SimInput, SimOutput, src, mdletc. The mdl subdirectory is intended as the default place where to keep the CarMaker for Simulink models.
In order to start modeling you need to make a fresh copy of theCar_Generic_SLtemplate project directory. This directory is part of the examples that come with CarMaker and can usually be found in
/opt/ipg/hil/linux-2.1/Examples/Car_Generic_SL
and on MS Windows systems in
c:\ipg\hil\win32-2.1\Examples\Car_Generic_SL of the installed product.
Making a copy ofCar_Generic_SLgives you a ready-to-run Simulink model with an initial set of CarMaker for Simulink blocks, some example Simulink models, a clean set of CarMaker configuration files for a simple vehicle and several test runs.
Start with these files and modify or extend them step by step according to your needs.
6.1.2 Starting Matlab
Matlab and CarMaker for Simulink work together by extending Matlab’s search path, so that Matlab knows where to find CarMaker for Simulink’s blockset and auxiliary commands. The Matlab search path is extended by execution of a small script namedcmenv.m, which is contained in themdlsubdirectory of a CarMaker project directory. Execution of this script may be done manually, but there’s also a way to invoke it automatically each time Matlab is started or a model is loaded.
The golden rule is: Always keep thecmenv.mscript in the same directory as your Simulink model. Whenever you load a Simulink model which contains the CarMaker subsystem block from the CarMaker for Simulink blockset, cmenv.mwill be executed automatically. This default behaviour should be sufficient for most uses of CarMaker for Simulink.
Alternatively, you may want to make use of Matlab’s startup file, i.e. a file called startup.m in Matlab’s working directory will be executed automatically when Matlab is started. Just make sure thatcmenvis invoked in yourstartup.mfile and you’re done. The advantage of this method is that the search path is setup for CarMaker without having to load a Simulink model first. See your Matlab documentation for further details about the Matlab startup options.
Starting Matlab under Unix
In your shell (probably running in anxtermor some other console window) change to the mdl subdirectory of your CarMaker project directory, then simply start Matlab:
% cd </path/to/your/project_dir>/mdl
% matlab
Depending on how you set up your working directory (see above), you may have to load a CarMaker for Simulink model or invokecmenv.m manually:
>> cmenv
94 CarMaker for Simulink
CarMaker for Simulink basics
Thecmenv.mscript should issue a message like the following in your Matlab console win-dow:
In Windows Explorer, simply double click on a Simulink model’s.mdlfile in themdl subdi-rectory of your CarMaker project disubdi-rectory. This will automatically start Matlab withmdlas its current working directory.
Starting Matlab using a desktop shortcut
An alternative way of starting Matlab is by creating a desktop shortcut to one of your Simu-link models’.mdlfile. In the shortcut’s properties dialog then, set the working directory to the path themdlsubdirectory of your CarMaker project directory. Matlab may then be start-ed by double-clicking on the desktop shortcut’s icon and your model will be loadstart-ed automat-ically.
Depending on how you set up your working directory (see above), you may have to load a CarMaker for Simulink model or invokecmenv.m manually:
>> cmenv
Thecmenv.mscript should issue a message like the following in your Matlab console win-dow:
6.1.3 Creating a new model
You can start building your own model by extending thegeneric.mdlmodel that is part of every CarMaker project directory, but you may create a new CarMaker for Simulink model from scratch as well.
Creating a new model is only a matter of drag’n’drop. Open the CarMaker for Simulink blockset (in the Simulink library, under Blocksets & Toolboxes, double click on the CarMaker for Simulink block). From the blockset window that opens drag’n’dop at least the following two blocks into your empty model:
• the block labeled Open GUI
• the subsystem block labeled CarMaker
The CarMaker Model Configuration block is optional; you may add it any time later.
95 CarMaker for Simulink
CarMaker for Simulink basics
Your model should now look like this:
CarMaker for Simulink works with all standard Simulink solvers. No special solver settings are required to run a CarMaker for Simulink model.
Normally, however, CarMaker for Simulink should be given control of the simulation, i.e. a simulation should stop according to the criteria configured in a test run. Examples for such criteria: A certain distance that has been driven, an error condition met and, of course, a total time elapsed. This requires the simulation stop time in Simulink to be set toinf, i.e.
from Simulink’s point of view it should run forever.
To set the simulation stop time, selectSimulation / Simulation Parametersfrom the model window’s menu bar. The entry field for the simulation stop time is on the Solver tab.
After that, your model is ready for simulation.
6.1.4 Starting the CarMaker GUI
The single tool central to all work with CarMaker for Simulink is the CarMaker GUI. It is used for configuration of test runs and other parts of the CarMaker environment. A running CarMaker GUI is required to perform any simulation with CarMaker for Simulink.
The easiest way to start the CarMaker GUI is to double click on the CarMaker GUI block of your Simulink model. If no CarMaker GUI is running, a new one will be started. If a CarMaker GUI is already running, its window will pop up and come to the foreground.
The CarMaker GUI may as well be started from the Matlab console. This does not require any model to be already loaded. Use the following command:
>> CM_Simulink
6.1.5 Running a simulation
You may start and stop a simulation the way you normally do with Simulink, i.e. by invoking Start or Stop from the Simulation menu of your model window.
In CarMaker for Simulink, there’s a (possibly easier accessible) alternative: The big green and red Start and Stop buttons of the CarMaker GUI.
Both ways of controlling a simulation may be mixed freely, e.g. you may start a simulation from the CarMaker GUI, then stop it via the model window and vice versa.
Figure 6.1: A newly created model
96 CarMaker for Simulink
CarMaker for Simulink basics
6.1.6 Switching between several Simulink models
In case you have several models loaded in Simulink, the question is: When using the Start button of the CarMaker GUI, how does the CarMaker GUI know, which model to start?
In the rare case the CarMaker GUI can’t find out itself, it will ask you (see dialog shown below). Otherwise the CarMaker GUI will simulate the model that was simulated last.
To switch to a different model, either double-click on the model’s CarMaker GUI button or explicitly invoke a simulation from that model’s window. Next time you press the green Start button in the CarMaker GUI, the new model will be simulated.
6.1.7 Switching between several CarMaker project directories
During your Matlab session with CarMaker for Simulink you may change Matlab’s current working directory to another CarMaker project directory. CarMaker for Simulink will notice the change and ask you what to do. Normally changing to another project directory requires the GUI to be restarted.
6.1.8 Dealing with the start values of your model
...
In the CarMaker GUI useSimulation / Determine Start Valuesto take a snapshot of the vehicle state at an arbitrary time during a testrun. CarMaker will store the current vehicle state into theSimOutput/<hostname>/Snapshot.infofile. See the CarMaker Reference Manual for details.
Use thecmstartcondcommand on the Matlab console to read the start values into the Matlab workspace. The workspace variables containing the start values can then be used to parametrize blocks of the Simulink model. This may be done automatically each time a simulation starts using one of Simulink’s model callback functions. See the Simulink manual for details.
...
Figure 6.2: CarMaker asking which model to use
97 CarMaker for Simulink
CarMaker for Simulink basics
6.1.9 Working in a non-default model directory
The default place for your Simulink models is in the mdl subdirectory of your Car Maker project directory. You may, however, want to organize things differently and keep your mod-els, parameter files etc. in a different place.
When CarMaker for Simulink starts, it tries to find the directories containing configuration information about the vehicle, test runs etc. The directory names are SimInput, SimOutput, Movie, Dataetc. In theCar_Generic_SLtemplate you will find them paral-lel to the model directory,mdl.
The search strategy to locate the configuration directories is as follows: Starting in your cur-rent working directory (i.e. the directory where you started Matlab), CarMaker for Simulink works its way upward through the entire directory tree and checks for a complete set of the configuration directories. Once they are found, the search stops. Once the topmost direc-tory is reached and nothing is found, an error message will be issued.
That means you can place your model(s) in a directory parallel to the configurations direc-tories (like the standardmdldirectory) or in a subdirectory somewhere below, allowing you to organize things in a flexible way. In the latter case, however, be sure to adapt your local cmenv.mfile to the new directory organizsation, so that Matlab still has thesrcdirectory in its search path (important if you rebuilding the model library).
6.1.10 Upgrading to a new CarMaker version
When upgrading to a new CarMaker version, always be sure to update yourcmenv.mscript as well:
• Either replace it with its successor, to be found inExamples/Car_Generic_SL/mdl/
cmenv.m in the installation directory of the new CarMaker for Simulink version (recom-mended).
• Or change the setting of the cminstdir variable in the first few lines of yourcmenv.m script and make it point to the new version.
There might be other files, too, that must be updated. The Release Notes of every CarMaker version will provide you with the necessary information.
In case you’re working with a CarMaker model library that you’ve compiled and linked your-self (i.e. you’ve made some changes to the C code) it is also required that you rebuild the model library. When you invokelibcarmaker4slfrom the Matlab command line, the Appli-cation.Version line shows you (in parentheses) the CarMaker for Simulink version your model library was built for.
6.1.11 Troubleshooting
When I want to run a simulation, I get the following error message:
Minimum step size (...) is larger than the fastest discrete sampling period (0.001) time.
Simulink will not allow you to set a solver step size greater than 0.001 seconds in models containing CarMaker for Simulink blocks. The reason for this is the internal configuration of the CarMaker for Simulink blocks, which use a fixed sample time of one millisecond.
98 CarMaker for Simulink
CarMaker for Simulink basics
After trying to add or remove blocks of the active CarMaker model while the simulation is running, suddenly the Start/Stop buttons of the CarMaker GUI do not work anymore.
This behaviour has been observed with Matlab 6.5 and later versions under MS Windows.
After closing the error message window telling you "Cannot change the model ... while the simulation is running", there seems to be some disorder in Matlab’s event processing. You may stop the simulation usingSimulation / Stopfrom the model’s window, however. After the simulation has been stopped, the buttons of the CarMaker GUI will work again as expected.
S-functions using ssGet/SetUserData(ssGetRootSS(SimStruct *S)) do not work or cause Matlab to crash.
During a simulation of a Simulink model CarMaker for Simulink relies on having complete control over the user data pointer associated with the model. Adding an S-function to a CarMaker for Simulink model, that makes use of the pointer itself, would seriously confuse CarMaker for Simulink, resulting in Matlab crashes and possible loss of data. This situation is not likely to change in the future.
When I start CarMaker for Simulink, I see the following message:
Warning: CarMaker command engine task could not be started CarMaker will be fully functional, but can only start a simulation in Simulink. The CarMaker GUI’s start/stop buttons, Model Check, Driver Adaption, ScriptControl etc. won’t work
This message is most often seen when Java is not properly enabled in Matlab or when try-ing to use Matlab 6.1 on a SuSE Linux 9.x system.
When I try to simulate, I see the following message:
libcarmaker4sl.mexglx: missing symbol: CarMaker4SL_CMLib
You’re trying to use a model library compiled with CarMaker 2.0 or older. Please update both your Simulink model and model library C code and recompile your model library.
99 CarMaker for Simulink
Using the C language interface