roadrunner

Start RoadRunner application using MATLAB

Since R2022a

Description

A roadrunner object enables you to perform common workflow tasks in the RoadRunner application, such as opening, closing, and saving scenes and projects, from the MATLAB^® command line. You can also use object functions to import data from files and export scenes from RoadRunner to other formats.

Before you create a roadrunner object for the first time, you must install RoadRunner and activate your RoadRunner license interactively. For more information, see Install and Activate RoadRunner (RoadRunner).

The roadrunner object requires a license for Automated Driving Toolbox™.

Creation

Syntax

rrApp = roadrunner(ProjectFolder=projectFolder)

rrApp = roadrunner

rrApp = roadrunner(Name=Value)

Description

rrApp = roadrunner(ProjectFolder=projectFolder) starts RoadRunner from the default installation folder location, and opens a new scene in an existing project at the location specified by ProjectFolder.

rrApp = roadrunner opens RoadRunner for a ProjectFolder and InstallationFolder defined using MATLAB's settings API or roadrunnerSetup function.

rrApp = roadrunner(Name=Value) sets the properties using name-value pairs.

Properties

ProjectFolder — RoadRunner project folder path

string scalar

RoadRunner project folder path, specified as a string scalar. You can customize the value of ProjectFolder using MATLAB's settings API or roadrunnerSetup function. For details about the RoadRunner project folder structure, see RoadRunner Project and Scene System (RoadRunner).

Example: roadrunner("C:\My Project") opens the project located in the C:\My Project folder in the RoadRunner application on a Windows^® machine.

Data Types: string

InstallationFolder — Location of local RoadRunner installation folder

string scalar

Location of local RoadRunner installation folder, specified as a string scalar. You can customize the value of InstallationFolder using MATLAB's settings API or roadrunnerSetup function

These are the default RoadRunner installation locations on Windows and Linux^® platforms:

• Windows – C:\Program Files\RoadRunner R20NNx\bin\win64

• Linux, Ubuntu^® – /usr/local/RoadRunner_R20NNx/bin/glnxa64

R20NNx is the release version you are using. To customize the default value of the RoadRunner installation folder, use the MATLAB settings API.

Data Types: char | string

NoDisplay — Start RoadRunner in console mode

false or 0 (default) | true or 1

Start RoadRunner in console mode in a non-graphical environment, specified as logical 0 (false) or logical 1 (true). For more details on starting RoadRunner in console mode, see Control RoadRunner Programmatically in Console Mode (RoadRunner).

Data Types: logical

Ports — Start RoadRunner on specified apiPort and cosimPort

matrix

Start RoadRunner on specified apiPort and cosimPort, specified as a matrix of size 1-by-2. RoadRunner API server port (apiPort) and RoadRunner Scenario simulation API server port (cosimPort) are automatically assigned by default when you launch the RoadRunner application. The server runs locally at localhost:port after you open a RoadRunner project. If the ports assigned are not free, a connection error occurs. In this case, you can explicitly assign values to apiPort and cosimPort using the roadrunner object or the connect function.

Example: rrApp= roadrunner(projectFolder,Ports= [54321, 54322]) starts RoadRunner and RoadRunner Scenario on apiPort and cosimPort 54321 and 54322 respectively.

Data Types: int

Object Functions

Project

newProject	Create new RoadRunner project using MATLAB
openProject	Open RoadRunner project using MATLAB
saveProject	Save RoadRunner project using MATLAB

Scenes

newScene	Create new RoadRunner scene using MATLAB
openScene	Open RoadRunner scene using MATLAB
saveScene	Save RoadRunner scene using MATLAB
exportScene	Export RoadRunner scene using MATLAB
exportCustomFormat	Export RoadRunner scene to custom format using MATLAB
importScene	Import scene into RoadRunner using MATLAB

Scenarios

newScenario	Create new scenario in RoadRunner Scenario using MATLAB
openScenario	Open scenario in RoadRunner Scenario using MATLAB
saveScenario	Save scenario in RoadRunner Scenario using MATLAB
exportScenario	Export scenario from RoadRunner Scenario using MATLAB
importScenario	Import file into RoadRunner Scenario using MATLAB
createSimulation	Create RoadRunner Scenario simulation using MATLAB
prepareSimulation	Submit simulation data to RoadRunner Scenario simulation engine using MATLAB
simulateScenario	Simulate RoadRunner scenario using MATLAB
getScenarioVariable	Get the value of RoadRunner scenario variable using MATLAB
setScenarioVariable	Set RoadRunner scenario variable using MATLAB
remapAnchor	Remap anchors in RoadRunner Scenario in MATLAB
getAnchors	Retrieve anchor attributes from RoadRunner scenario using MATLAB

Connect, Close and Status

roadrunner.connect	Connect to open instance of RoadRunner using MATLAB
close	Close RoadRunner using MATLAB
status	Get current status of RoadRunner using MATLAB

Examples

Start RoadRunner Application from Default Installation Folder

Specify the path to an existing project using the ProjectFolder variable. For example, this code shows the path to a project, on a Windows® machine, located at C:\RR\MyProject.

projectFolder = "C:\RR\MyProject";

Create a roadrunner object and open RoadRunner by specifying your project as the location where you want to create a scene. This example assumes that RoadRunner is installed in its default location.

rrApp = roadrunner(ProjectFolder=projectFolder, InstallationFolder='C:\Program Files\RoadRunner R2023b\bin\win64'); 

Change Default RoadRunner Installation Folder Settings

Modify the default RoadRunner installation folder settings by using the MATLAB settings function.

You can specify a value for the InstallationFolder property of a roadrunner object that persists across MATLAB sessions, or for a given MATLAB session, using the settings function.

To set a persistent default value for the InstallationFolder property, edit the value of PersonalValue.The specified value persists across multiple MATLAB sessions for an individual user.

s = settings;
s.roadrunner.application.InstallationFolder.PersonalValue = "C:\Program Files\RoadRunner R2022a\bin\win64";

You can also set a temporary default value for the InstallationFolder property. the specified value persists for only the current MATLAB session, and is cleared at the end of the session.

s = settings;
s.roadrunner.application.InstallationFolder.TemporaryValue = "C:\MyRoadRunner Install\bin\win64";

Start Multiple RoadRunner Application Instances Simultaneously

Open multiple RoadRunner applications by creating multiple instances of the roadrunner object. You can use each instance to programmatically interact with the RoadRunner application that it opens. The scenes used in this code are included in RoadRunner projects by default.

Open a first instance of RoadRunner by specifying the Lane Keep project. In this example, the project is located on the path C:\RR\Lane Keep.

rrApp1 = roadrunner("C:\RR\Lane Keep");

Open the FourWaySignal scene in the first project.

openScene(rrApp1,"FourWaySignal.rrscene");

Open a second instance of RoadRunner by specifying the USCity project. In this example, the project is located on the path C:\RR\USCity.

rrApp2 = roadrunner("C:\RR\USCity");

Open the SanAntonio scene in the second project

openScene(rrApp2,"SanAntonio.rrscene");

Start RoadRunner Application in Console Mode

Specify the path to an existing project using the projectFolder variable. For example, this code shows the path to a project, on a Windows® machine, located at C:\RR\MyProject.

projectFolder = "C:\RR\MyProject";

Create a roadrunner object and open RoadRunner by specifying your project as the location where you want to create a scene. This example assumes that RoadRunner is installed in its default location. Specify the NoDisplay property to launch the application in console mode using a non-graphical terminal.

rrApp = roadrunner(projectFolder,InstallationFolder="C:\Program Files\RoadRunner R2022b\bin\win64",NoDisplay=true); 

Limitations

• The roadrunner object and its associated functions are supported only in RoadRunner R2022a and later.

• The project you specify using the projectFolder argument, when creating the roadrunner object must already exist.

• The projectFolder argument and InstallationFolder property do not support Unicode characters in the path.

• The roadrunner object and its associated functions are not supported in MATLAB Online™.

Tips

• Deleting the roadrunner object from the MATLAB workspace does not close the RoadRunner application associated with it. You must manually close the RoadRunner application. Also, exiting from the current MATLAB session does not close any RoadRunner applications created by roadrunner.

Version History

Introduced in R2022a