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.

Overview of the MATLAB or Simulink and RoadRunner scenario cosimulation workflow

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, MyExampleScene and MyExampleScenario, respectively.

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.

Simulink model with Road Runner Scenario, Road Runner Scenario Reader, and Road Runner Scenario Writer blocks

This example shows the hVehicle.m behavior that is created as a MATLAB 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 Behaviors folder.
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 these steps.
On the Attributes pane, set Platform to MATLAB/Simulink. As the File Name, use the location of your file hVehicle.m.
- 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 .slx or .m, for example hVehicle.m.
- You can also use the full path to enter the location of your file, for example MyLocation\hVehicle.m.
This action creates a new behavior that you can attach to actors in your scenario. Rename the behavior as MyNewBehavior.
Add a new CompactCar to your scenario MyExampleScenario.
To associate the new behavior to an actor, select CompactCar. On the Attributes pane, in the Behavior box, add MyNewBehavior to CompactCar by 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 using the Simulink.publish.publishActorBehavior() and Simulink.publish.publishActor() functions.

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 .zip file. 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, foo01.slprotodata. The 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:

Drag the foo01.slprotodata proto file into any folder under MyProject/Assets.
Double-click the behavior foo01 and 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 Sedan and click Add Action. Then, select Change Behavior Parameter.
Observe that the model parameter gain01 appears. 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 gain01. 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 gain01.
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:

Open the SimulationConfiguration.xml file 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.

Scenario editor in RoadRunner

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 roadrunner.
Load and save a pre-defined scenario file (.rrScenario). For more information, see openScenario and saveScenario.
Configure and manage a simulation. For more information, see ScenarioSimulation.
- 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 ActorModel.
- Read and write runtime values such as actor runtime attributes, For more information, see ActorSimulation.
- 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 ScenarioSimulation.

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 MyInstallationFolder with 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;
```
Note
Specify the full path to the folder containing the AppRoadRunner.exe executable. The default location of this executable on Windows^® is C:\Program Files\RoadRunner R2022b\bin\win64, where C:\Program Files\RoadRunner R2022b is your RoadRunner installation folder. The folder could be different on your computer.
To open the RoadRunner project MyRoadRunnerProject from MATLAB, use this command.
```
rrApp = roadrunner('MyProjectLocation');
```
Open the scene MyExampleScene.
```
openScene(rrApp, 'MyExampleScene');
```

Open the scenario MyExampleScenario.

openScenario(rrApp, 'MyExampleScenario');

Get the simulation object to control simulation from MATLAB.
```
rrSim = createSimulation(rrApp);
```
Start the simulation from the command line.
```
set(rrSim, 'SimulationCommand','Start');
```

Tip

When debugging cosimulations using the MATLAB or Simulink debugger, the simulation might time out. Check the simulation timeout setting using this code.

s = settings;
s.roadrunner.application.Timeout.ActiveValue

By default, the simulation times out after 300 seconds, or 5 minutes. If you expect the simulation to take more than 5 minutes between simulation steps, set a higher timeout value using this code, which sets the timeout to 600 seconds (10 minutes) in the current MATLAB session.

s = settings;
s.roadrunner.application.Timeout.TemporaryValue = 600;

If the simulation times out, the current ScenarioSimulation object becomes invalid. If the ScenarioSimulation object is invalid, RoadRunner generates an error if you attempt to start the simulation. To restart the simulation, delete the ScenarioSimulation object and recreate it using this code. Replace rrSim with the name of your ScenarioSimulation object and rrApp with the name of your roadrunner object.

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 ScenarioLog.

% 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.