Main Content

Connect MATLAB and RoadRunner to Control and Analyze Simulations

This topic shows you how to create and verify the connection between MATLAB® and RoadRunner. Once you create this connection, you can use MATLAB commands to:

  • Open and close the RoadRunner application.

  • Open, close, and save scenes, scenarios, and projects.

  • Start, pause, and stop simulations.

  • Obtain and analyze data from simulation logs.

  • Import and export scenes and scenarios.

Note

You must connect MATLAB and RoadRunner to simulate behaviors based in MATLAB- or Simulink® in RoadRunner Scenario.

This topic assumes you have:

  • An Automated Driving Toolbox™ license.

  • A RoadRunner license, and the product is installed. For information on installing and activating RoadRunner, see Install and Activate RoadRunner (RoadRunner).

  • A RoadRunner Scenario license, and the product is installed.

  • A RoadRunner project folder. For information on creating a RoadRunner project, see RoadRunner Project and Scene System (RoadRunner).

Set Up Environment to Launch RoadRunner from MATLAB

You must specify the install location of RoadRunner to MATLAB to ensure the roadrunner object opens RoadRunner successfully.

If you do not specify an installation directory, the roadrunner object opens RoadRunner from the default installation folder for the platform you are using, either Windows® or Linux®. These installation locations are the defaults by platform:

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

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

R20NNx is the MATLAB release you are using, such as R2023b. Use the same release of MATLAB and RoadRunner.

If your RoadRunner installation is in a different location than the default location, use these MATLAB commands to change the default value of the RoadRunner installation folder. Replace MyInstallationFolder with the full path to the folder containing the AppRoadRunner.exe executable.

Tip

You only need to set the RoadRunner installation folder once using these commands. The value you set persists between MATLAB sessions.

RRInstallationFolder = "MyInstallationFolder";
s = settings;
s.roadrunner.application.InstallationFolder.PersonalValue = RRInstallationFolder; 
s.roadrunner.application.InstallationFolder.TemporaryValue = RRInstallationFolder;

Tip

If you run the commands in this topic in a MATLAB script, place pause statements between commands to allow RoadRunner sufficient time to respond. Pause for at least 0.5 seconds between commands for best results.

Launch RoadRunner Using MATLAB

You can use the roadrunner object to launch RoadRunner in an existing project. The roadrunner object provides functions for manipulating scenes and scenarios and managing simulations and simulation data.

The roadrunner object requires an argument that specifies the location of an existing RoadRunner project. For more information on the RoadRunner project system and how to create a new project, see RoadRunner Project and Scene System (RoadRunner).

This code opens RoadRunner to a project located in C:\RR\MyProject and creates a roadrunner object called rrApp. Replace C:\RR\MyProject with the path to your project folder. 

rrProj = "C:\RR\MyProject";
rrApp = roadrunner(rrProj);

Verify RoadRunner Launch

When you run this step successfully, you see these results:

  • A new instance of the RoadRunner application opens to the specified project.

  • No error messages are displayed in the MATLAB Command Window.

  • The RoadRunner Output Window displays no errors and may display a message about starting the RoadRunner API server.

To check the status of this connection, run this command. 

status(rrApp)
If the connection is active, this command returns a struct containing information on the open project, scene, and scenario. If the connection is inactive or broken, the software displays an error message in the Command Window. For more information, see status (RoadRunner).

Open a Scenario in RoadRunner

After creating a roadrunner object, you can open an existing scenario in RoadRunner Scenario from MATLAB. To open a scenario, use the openScenario function, specifying the roadrunner object and the scenario filename that you want to open. For example, this code opens the TrajectoryCutIn scenario file, which is a scenario included by default in RoadRunner projects.

openScenario(rrApp, "TrajectoryCutIn.rrscenario");

Verify Scenario Is Opened

When you run this step successfully, you see these results:

  • RoadRunner opens to the specified scenario in scenario editing mode.

  • No error messages are displayed in the MATLAB Command Window.

  • The RoadRunner Output Window displays no errors and may display a message about starting the Simulation API server.

Create a Scenario Simulation Object to Manage Simulations

After you open a scenario and switch to scenario editing mode, use the createSimulation function with the roadrunner object to create a ScenarioSimulation object. This object provides functions to start, stop, and pause simulations as well as to retrieve simulation logs containing actor and event data. For example, this code creates a scenario simulation object named rrSim.

rrSim = createSimulation(rrApp);

Tip

Run the createSimulation function only once when setting up the connection. To close and reopen RoadRunner during a MATLAB session, delete the simulation object first using this command before rerunning createSimulation.

delete(rrSim);
Otherwise, you may encounter errors due to multiple ScenarioSimulation objects.

Verify Scenario Simulation Object

When you run this step successfully, you see these results:

  • No error messages are displayed in the MATLAB Command Window.

  • No error messages are displayed in the RoadRunner Output Window.

Start and Stop Simulation from MATLAB

Once you connect RoadRunner and MATLAB and created a scenarioSimulation object, you can start, stop and pause scenario simulation using these commands, where rrSim is replaced by the name of your scenarioSimulation object.

  • Start the simulation. 

    set(rrSim, "SimulationCommand", "start")

    Tip

    This command may return while the simulation is still running. To pause MATLAB execution until the simulation finishes, use this code. 

    set(rrSim,"SimulationCommand","Start");
while strcmp(get(rrSim,"SimulationStatus"),"Running")
    pause(1);
end
    This code checks the simulation status and executes a pause command while the simulation is still running.

  • Stop the simulation. 

    set(rrSim, "SimulationCommand", "stop")

  • Pause the simulation. 

    set(rrSim, "SimulationCommand", "pause")

Next Steps for Scene Management and Scenario Simulation

Once you connect MATLAB and RoadRunner and create a roadrunner object, you can open, close, import and export scenes and scenarios programmatically. See roadrunner and Export Multiple Scenes Using MATLAB for more information.

Once you create a simulation object, you can:

See Also

| | | | |

Related Topics