RoadRunner Scenario

Define interface for Simulink actor model

Since R2022a

expand all in page
  • RoadRunner Scenario block

Libraries:
Automated Driving Toolbox / RoadRunner Scenario

Description

The RoadRunner Scenario block defines the interface of a Simulink® actor model. The Block Parameters dialog box contains these tabs under which inputs are grouped together.

  • Scenario

  • Actions

  • Events

  • Configuration

The RoadRunner Scenario block must be present at the root level of the model, otherwise model compilation results in an error.

Examples

expand all

This example uses:

Open Live Script

This example shows how you can start the simulation of a RoadRunner scenario interactively from a Simulink actor behavior model.

In the MATLAB Command Window, specify the path to your local RoadRunner installation folder. This code snippet uses the default installation path of the RoadRunner application on Windows.

RRInstallationFolder =  "C:\Program Files\RoadRunner " + matlabRelease.Release + "\bin\win64";

To update the path for the RoadRunner installation folder, get the root object within the settings hierarchical tree. Then, use the root object to set the installation path of the RoadRunner application. For more information, see SettingsGroup.

s = settings;
s.roadrunner.application.InstallationFolder.PersonalValue = RRInstallationFolder;

Set the project location to the RoadRunner project folder on your machine. For example:

rrProjectLocation = "C:\FollowPath\New RoadRunner Project";

Create and open the roadrunner object that represents the specified project.

rrApp = roadrunner(rrProjectLocation,InstallationFolder=RRInstallationFolder,NoDisplay=true);

Add the scene file SceneBasic to the Scenes folder within your RoadRunner project.

copyfile("SceneBasic.rrscene",fullfile(rrProjectLocation,"Scenes"));

Add the scenario file FollowPath to the Scenarios folder within your RoadRunner project.

copyfile("FollowPath.rrscenario",fullfile(rrProjectLocation,"Scenarios"));

Open the Simulink model mSLPathfollower and load the required bus types into the base workspace.

model = "mSLPathfollower";
open_system(model);
load("rrScenarioSimTypes.mat");

Observe the predefined parameters in the Block Parameters dialog box of the RoadRunner Scenario block:

  • Scenario file name — Scenario file FollowPath present in the Scenarios folder of the project FollowPath. This scenario is built on the scene file, SceneBasic.

  • Actor ID linked to model — Actor with ID 1 in the scenario FollowPath

  • Sample time — Sample time of 0.02 seconds for the scenario FollowPath

  • Open RoadRunner at simulation start — Enable viewing the scenario in RoadRunner when you start the simulation of the RoadRunner scenario interactively from the Simulink actor behavior model.

blockName = "RoadRunner Scenario";
blockPath = append(model,"/",blockName);
open_system(blockPath);

Start the simulation of the RoadRunner scenario interactively from the Simulink behavior by using the set_param command.

set_param("mSLPathfollower",SimulationCommand="start")
pause(10);
close_system(blockPath);
set_param('mSLPathfollower', 'Dirty', 'off');

You can change the values of block parameters in the RoadRunner Scenario block to check different outcomes.

Parameters

expand all

Scenario

Configure block parameters to start the simulation of a RoadRunner scenario interactively from a Simulink behavior. The block parameters in the Scenario tab are used to set up this specific workflow only. For more information, see Start Simulation of RoadRunner Scenario Interactively from Simulink Actor Behavior Model.

Filename of the RoadRunner scenario which you want to simulate interactively from a Simulink behavior.

To start the simulation of a RoadRunner scenario interactively from a Simulink behavior, perform one of these actions:

  • Click Run in the Simulink Toolstrip.

  • Click Step Forward in the Simulink Toolstrip.

  • Set the SimulationCommand name-value argument to "start" by using the set_param (Simulink) function in the MATLAB® Command Window for a model named driveleft:

    set_param("driveleft",SimulationCommand="start")

Note

The sim command does not support the simulation of a RoadRunner scenario interactively from a Simulink behavior.

To select a scenario file, click Browse, locate and select the file, or type the filename directly. If you type the scenario file name without its absolute path, then Simulink searches for this scenario within the designated project folder. You can set up the designated project folder by using the Set Up RoadRunner button.

The Open Scenario button allows you to launch RoadRunner with the specified scenario file. Clicking this button opens the RoadRunner application, if it is not already running, and loads the scenario specified by the user to establish a connection between MATLAB and RoadRunner.

The default auto option detects and uses the scenario that is currently open in RoadRunner given that a valid connection is already established between MATLAB and RoadRunner. For more information about establishing this connection, see Connect MATLAB and RoadRunner to Control and Analyze Simulations.

Programmatic Use

Block Parameter: ScenarioFileName
Type: character vector | string
Values: 'auto' | filename
Default: 'auto'

Data Types: string | character vector

Identifier of a valid actor, present in the scenario specified by Scenario file name, to associate with the Simulink behavior. The Simulink behavior remains attached to the actor for the duration of the simulation.

Programmatic Use

Block Parameter: ActorIDLinkedToModel
Type: character vector | string
Values: '1' | '2' | positive integer
Default: '1'

Step size of the connected RoadRunner scenario. The scenario uses the sample time as its step size, overriding any previously set value.

Sample time accepts values ranging between 1e-5 and 10.

Programmatic Use

Block Parameter: SampleTime
Type: character vector | string
Values: '.02' | positive scalar
Default: '.02'

If you select this parameter, a RoadRunner application window opens at the start of the simulation. If the RoadRunner application is already open and connected, then it will remain open when the simulation starts, regardless of whether the parameter is selected or not.

If you clear the parameter, then the scenario will simulate in console mode. For more information, see Control RoadRunner Programmatically in Console Mode (RoadRunner).

Programmatic Use

Block Parameter: OpenRoadRunnerAtSimulationStart
Type: character vector | string
Values: 'on' | 'off'
Default: 'on'

Option to enable logging when you start the simulation of a RoadRunner scenario interactively from a Simulink behavior. If you select the check box, then you can retrieve simulation and actor information from the log at each time step.

Programmatic Use

Block Parameter: EnableSimulationLoggingInRoadRunner
Type: character vector | string
Values: 'on' | 'off'
Default: 'off'

Actions

Name of user-defined action to map to a bus object.

To add an action name, click the Add button below the User-defined actions input table and double-click on a cell in the Action name column to type a new table entry.

Programmatic Use

Block Parameter: UserDefinedActions
Type: string
Values: "{'UserDefinedAction1','Bus object','BusActions'}" | cell array of character vectors in quotes
Default: "{}"

Name of bus object that corresponds to a user-defined action.

To add a bus object name corresponding to a user-defined action, double-click on a cell in the Bus object name column at the same level of the user-defined action, and type a new table entry.

All added bus object names must have a corresponding bus object. Bus objects represent a user-defined action. You must define a bus object in MATLAB in such a way that it contains the same parameter names, data types and values as the user-defined action that it represents in RoadRunner Scenario. The RoadRunner Scenario Reader and RoadRunner Scenario Writer blocks rely on a bus object loaded to the MATLAB workspace to recognize the structure of incoming user-defined actions.

For more information about creating a bus object for a user-defined action, see Model Actor Behavior Using User-Defined Actions.

Events

Name of user-defined event to map to a bus object.

To add an event name, click the Add button below the User-defined events input table and double-click on a cell in the Event name column to type a new table entry.

Programmatic Use

Block Parameter: UserDefinedEvents
Type: string
Values: "{'UserDefinedEvent1','Bus object','BusEvents'}" | cell array of character vectors in quotes
Default: "{}"

Name of bus object that corresponds to a user-defined event.

To add a bus object name corresponding to a user-defined event, double-click on a cell in the Bus object name column at the same level of the user-defined event, and type a new table entry.

All added bus object names must have a corresponding bus object. Bus objects represent a user-defined event. You must define a bus object in MATLAB in such a way that it contains the same parameter names, data types and values as the user-defined event that it represents in RoadRunner Scenario. The RoadRunner Scenario Reader and RoadRunner Scenario Writer blocks rely on a bus object loaded to the MATLAB workspace to recognize the structure of incoming user-defined events.

For more information about creating a bus object for a user-defined event, see Model Actor Behavior Using User-Defined Actions.

Configuration

Maximum number of points on the path of a vehicle actor to be read by a path-following action.

You can set the value of this parameter to any positive integer between 1 and 232. There is a tradeoff between the maximum number of points and the simulation performance of the actor behavior model.

This parameter is applicable only if a Simulink actor behavior model contains a RoadRunner Scenario Reader block that reads the Path Following action of an actor by setting Topic Category to Action and Action Type to Path Following. The RoadRunner Scenario Reader block stops reading points on a path after its number reaches the maximum value.

Programmatic Use

Block Parameter: PathPoints
Type: character vector | string
Values: '500' | positive integer
Default: '500'

Data Types: uint64

Version History

Introduced in R2022a

expand all

See Also

|