Overview of Simulating RoadRunner Scenarios with MATLAB and Simulink
This topic describes the workflow to simulate RoadRunner scenarios with MATLAB® and Simulink®. RoadRunner is an interactive editor that enables you to design scenarios for simulating and testing automated driving systems. Automated Driving Toolbox™ provides a cosimulation framework for simulating scenarios in RoadRunner with actors modeled in MATLAB and Simulink.
To follow this workflow, you must connect RoadRunner and MATLAB. This topic provides basic instructions for creating this connection; for more detailed information, see Connect MATLAB and RoadRunner to Control and Analyze Simulations.
These are the steps of the workflow:
Author MATLAB System objects or Simulink models to define actor behavior.
Associate actor behavior in RoadRunner.
Optionally, publish an actor behavior.
Tune the parameters defined in MATLAB or Simulink for RoadRunner simulations.
Simulate a scenario using the RoadRunner user interface or control simulations programmatically from MATLAB.
Inspect simulation results using the simulation log.
Replay a scenario simulation from a saved simulation log.
This workflow assumes that:
You have a RoadRunner license and the product is installed. For more information, see Install and Activate RoadRunner (RoadRunner).
You have a RoadRunner Scenario license and the product is installed.
You have created a RoadRunner project folder. For more information, see RoadRunner Project and Scene System (RoadRunner).
You have created and saved a scene and a scenario file for your project,
Author RoadRunner Actor Behavior Using Simulink or MATLAB System Objects
You can define custom behaviors for your actors in RoadRunner using Simulink or a MATLAB System object™.
For example, this model
SimulinkVehicle.slx is created using
Simulink and RoadRunner scenario blocks from the Automated Driving Toolbox library. The model reads the actor data, increases its velocity, and then
writes the data back to the actor in RoadRunner scenario. For more information about creating Simulink behaviors for RoadRunner, see Simulate RoadRunner Scenarios with Actors Modeled in Simulink.
This example shows the
hVehicle.m behavior that is created as a
System object file. In this behavior, the
code reads the initial pose and velocity of an actor and updates the values to make the
actor follow a lane. For more information about creating actor behaviors using
MATLAB, see Simulate RoadRunner Scenarios with Actors Modeled in MATLAB.
classdef hVehicle < matlab.System % Copyright 2021 The MathWorks, Inc. properties (Access = private) mActorSimulationHdl; mScenarioSimulationHdl; mActor; mLastTime = 0; end methods (Access=protected) function sz = getOutputSizeImpl(~) sz = [1 1]; end function st = getSampleTimeImpl(obj) st = createSampleTime( ... obj, 'Type', 'Discrete', 'SampleTime', 0.02); end function t = getOutputDataTypeImpl(~) t = "double"; end function resetImpl(~) end function setupImpl(obj) obj.mScenarioSimulationHdl = ... Simulink.ScenarioSimulation.find( ... 'ScenarioSimulation', 'SystemObject', obj); obj.mActorSimulationHdl = Simulink.ScenarioSimulation.find( ... 'ActorSimulation', 'SystemObject', obj); obj.mActor.pose = ... obj.mActorSimulationHdl.getAttribute('Pose'); obj.mActor.velocity = ... obj.mActorSimulationHdl.getAttribute('Velocity'); end function stepImpl(obj, ~) currentTime = obj.getCurrentTime; elapsedTime = currentTime - obj.mLastTime; obj.mLastTime = currentTime; velocity = obj.mActor.velocity; pose = obj.mActor.pose; pose(1,4) = pose(1,4) + velocity(1) * elapsedTime; % x pose(2,4) = pose(2,4) + velocity(2) * elapsedTime; % y pose(3,4) = pose(3,4) + velocity(3) * elapsedTime; % z obj.mActor.pose = pose; obj.mActorSimulationHdl.setAttribute('Pose', pose); end function releaseImpl(~) end end end
Associate Actor Behavior in RoadRunner Scenario
This section describes how to associate a custom behavior to your actors in RoadRunner. The workflow is the same for MATLAB and Simulink behaviors.
In your RoadRunner scenario, select the Library Browser and then the
To create a new behavior, right-click an empty space in the list of behaviors, pause on New, then select Behavior. Enter a name for your new behavior, such as
MyNewBehavior. This animation shows how to complete steps 1 and 2.
On the Attributes pane, set Platform to
MATLAB/Simulink. As the File Name, use the location of your file
If your Simulink model or MATLAB System object file is in your working folder, you can enter the name of your file together with its extension such as
.m, for example
You can also use the full path to enter the location of your file, for example
This action creates a new behavior that you can attach to actors in your scenario. Rename the behavior as
Add a new
CompactCarto your scenario
To associate the new behavior to an actor, select
CompactCar. On the Attributes pane, in the Behavior box, add
CompactCarby clicking and dragging the behavior icon to the box.
Publish Actor Behavior
After you create your custom behavior, you can attach your behavior to actors in your
scenario. Optionally, you can publish your actor behaviors as proto files or packages
Proto files are specific to RoadRunner and have a
.slprotodata extension. This data interface
allows you to combine your behavior model, its parameters, and their values and share
them with RoadRunner.
You can also publish your behavior as a package in a
Publishing in a
.zip file will allow you to create a package that
includes the proto file along with other supporting files for your model.
For more information on the behavior publishing workflow, see Publish Actor Behavior as Proto File, Package, Action Asset or Event Asset.
Tune Actor Parameters
You can tune the parameters you define for your custom MATLAB and Simulink behaviors in RoadRunner.
For example, suppose that you have a Simulink model
foo01.slx with a gain parameter
gain01. The parameter value is
2. You can
associate your model in two different ways to tune model parameters in RoadRunner.
You can publish your model as a proto file and tune the parameters in RoadRunner.
You can directly associate your MATLAB or Simulink model to a behavior in RoadRunner then tune the parameters in RoadRunner.
Tune Parameters of a Proto File in RoadRunner
Publish the model as a proto file,
published proto file has the model, its parameters, and the values. For more
information see, Publish Actor Behavior as Proto File, Package, Action Asset or Event Asset.
To tune the
gain01 parameter in a RoadRunner scenario:
foo01.slprotodataproto file into any folder under
Double-click the behavior
foo01and observe that the gain parameter and its value appears in RoadRunner. This display is read-only for the value of the parameter. To tune the parameter, continue with these steps.
Attach the proto file to your vehicle in your scenario.
Select the action phase for the
Sedanand click Add Action. Then, select
Change Behavior Parameter.
Observe that the model parameter
gain01appears. You can now tune the parameter for your simulations.
Tune Parameters of Model Associated as Behavior without Publishing
You can also associate a Simulink behavior directly to an actor in a scenario without publishing.
In this case, you create a new behavior then add a new parameter to your behavior
with a name that is identical to the Simulink parameter
Then, you can tune the parameter without any additional steps.
Create a new behavior by following the previous steps.
Select Add Parameter.
Create the parameter that has the same name as the model parameter
The remainder of the workflow is the same as when you publish your file. Attach the behavior to your vehicle, and from the action phase, tune the parameter for your simulations.
Simulate Scenario in RoadRunner
Use the Scenario Editor in RoadRunner to simulate your scenario with the custom behavior and control the progression of the simulation and perform start, pause, step, continue, stop actions.
To support the simulation of custom behaviors defined as Simulink models or MATLAB System objects, you need to configure RoadRunner so that it can find an installation of MATLAB that is available on your computer.
To configure the file:
SimulationConfiguration.xmlfile that is generated with your RoadRunner installation. For more information, see Simulation Configuration (RoadRunner Scenario).
In the file, search for the configuration related to MATLAB platform (see the example below).
<Platform name="MATLAB"> <ExecutablePath>C:\Program Files\MATLAB\R2022a\matlab\bin\matlab.exe</ExecutablePath> <StartTimeOut>60000</StartTimeOut> <NoDesktop>true</NoDesktop> </Platform>
Replace the full path to the MATLAB executable (denoted by the
<ExecutablePath>tag) with the installed executable on your computer.
You can also control the pace of the simulation and the simulation step size and observe the current simulation time during simulation.
Control Scenario Simulation Using MATLAB
Instead of using the Scenario Editor in RoadRunner you can also use MATLAB to control your simulations.
Start RoadRunner and RoadRunner Scenario. For more information, see
Configure and manage a simulation. For more information, see
From MATLAB, prepare a simulation by getting or setting simulation step size and simulation pace.
Use MATLAB to control the simulation and to start, stop, pause, resume, and single-step.
Get the current playback status.
Use MATLAB functions, and MATLAB System objects.
Read actor static specifications or scenario logic models. For more information, see
Read and write runtime values such as actor runtime attributes, For more information, see
Report or be notified with simulation results and diagnostics such as warnings and errors, or receive and send scenario logic events. For more information, see
This example shows how to simulate a scenario using MATLAB code. After each step, wait for the expected response from RoadRunner or MATLAB before proceeding to next steps.
Specify the path to your RoadRunner installation folder using these commands, replacing
MyInstallationFolderwith the path to your RoadRunner installation. You need to run the commands in this step only the first time you are setting up the connection between RoadRunner and your MATLAB installation.
RRInstallationFolder = "MyInstallationFolder"; s = settings; s.roadrunner.application.InstallationFolder.PersonalValue = RRInstallationFolder; s.roadrunner.application.InstallationFolder.TemporaryValue = RRInstallationFolder;
Specify the full path to the folder containing the
AppRoadRunner.exeexecutable. The default location of this executable on Windows® is
C:\Program Files\RoadRunner R2022b\bin\win64, where
C:\Program Files\RoadRunner R2022bis your RoadRunner installation folder. The folder could be different on your computer.
To open the RoadRunner project
MyRoadRunnerProjectfrom MATLAB, use this command.
rrApp = roadrunner('MyProjectLocation');
Open the scene
Open the scenario
Get the simulation object to control simulation from MATLAB.
rrSim = createSimulation(rrApp);
Start the simulation from the command line.
When debugging cosimulations using the MATLAB or Simulink® debugger, simulation may time out. Check the simulation timeout setting using this code.
s = settings; s.roadrunner.application.Timeout.ActiveValue
s = settings; s.roadrunner.application.Timeout.TemporaryValue = 600;
If simulation times out, the current
ScenarioSimulation object becomes
invalid, and attempts to start simulation generate an error. To restart simulation,
ScenarioSimulation object and recreate it using this
rrSim with the name of your
ScenarioSimulation object and
with the name of your
delete(rrSim); rrSim = createSimulation(rrApp);
Inspect Simulation Results Using Data Logging
You can inspect simulation results using data logging. This example code logs the
simulation data, runs the simulation, and then gets the logged simulation data. For more
information about logging, see
% Turn logging on set(rrSim, 'Logging', 'On') % Run simulation set(rrSim, 'SimulationCommand', 'Start') % Get logged simulation data log = get(rrSim, 'SimulationLog');
Controlling scenario simulation using MATLAB and inspecting results using data logging assumes that you manually open a MATLAB session to control your simulation. If there is not any active MATLAB session connected to RoadRunner prior to the start of the simulation, RoadRunner automatically opens a MATLAB session to simulate the scenario with MATLAB or Simulink actors.
To enable this, configure the Simulation Configuration (RoadRunner Scenario) by setting the ExecutablePath parameter to MATLAB executable and setting the StartTimeOut parameter properly before starting RoadRunner.