Speed Action Follower with RoadRunner Scenario

This example shows how to design and implement a speed action follower in MATLAB® and cosimulate with RoadRunner Scenario.

Introduction

RoadRunner Scenario is an interactive editor that enables you to design scenarios for simulating and testing automated driving systems. You can place vehicles, define their paths and interactions in the scenario, and then simulate the scenario in the editor. RoadRunner Scenario supports in-editor playback for scenario visualization and connecting to other simulators such as MATLAB and Simulink® for cosimulation.

This example shows the steps for cosimulation of RoadRunner Scenario and MATLAB. It shows how to design a speed action follower using a MATLAB System object™. It also shows how to visualize simulation data using MATLAB. This diagram shows an overview of the information exchanged between RoadRunner Scenario and the speed action follower:

The speed action follower reads the vehicle runtime, path, and speed action of the ego vehicle, and all actor runtimes from RoadRunner Scenario. It then uses this information to process the speed action and updates the ego vehicle runtime in the scenario.

In this example, you:

1. Set up Environment — Configure MATLAB settings to interact with RoadRunner Scenario.

2. Explore the scenario — Associate speed action following behavior to the ego vehicle in RoadRunner Scenario.

3. Design a speed action follower — Design a speed action follower in MATLAB using a System object.

4. Simulate following an absolute speed action — Simulate a scenario in which the ego vehicle follows an absolute speed that results in collision with the lead vehicle.

5. Simulate following a relative speed action — Simulate a scenario in which the ego vehicle follows the speed of a lead vehicle to avoid collision.

Set Up Environment

This section shows how to set up the environment to cosimulate MATLAB with RoadRunner Scenario.

Start RoadRunner application interactively by using the roadrunnerSetup function. When the function opens a dialog box, specify the RoadRunner Project Folder and RoadRunner Installation Folder locations.

rrApp = roadrunnerSetup;

The rrApp RoadRunner object enables you to interact with RoadRunner from the MATLAB workspace. You can open the scenario and update scenario variables using this object. For more information on variables, see Generate Scenario Variations Using gRPC API (RoadRunner Scenario).

This example uses two files that you must add to the RoadRunner project.

1. scenario_SAF_OneLeadCar.rrscenario — Scenario file based on the ScenarioBasic.rrscene scene that ships with RoadRunner.

2. SpeedActionFollower.rrbehavior.rrmeta — Behavior file that associates the speed action following behavior implemented using a MATLAB System object to the ego vehicle in RoadRunner Scenario.

Copy these files to the RoadRunner project. To learn more about the RoadRunner environment, see RoadRunner Project and Scene System (RoadRunner).

copyfile("scenario_SAF_OneLeadCar.rrscenario",fullfile(rrApp.status.Project.Filename,"Scenarios"));
copyfile("SpeedActionFollower.rrbehavior.rrmeta",fullfile(rrApp.status.Project.Filename,"Assets","Behaviors"));

Explore Scenario

Open the scenario scenario_SAF_OneLeadCar.rrscenario.

openScenario(rrApp,"scenario_SAF_OneLeadCar.rrscenario");

The scenario contains two vehicles. The blue lead car follows the lane-following built-in behavior. The white ego vehicle travels on the specified path. In this example, you must specify a path for the ego vehicle. The lead car initially travels at a speed of 20 m/s, and then decelerates to a speed of 5 m/s over the next 10 seconds. The ego vehicle initially travels at a speed of 20 m/s. When the ego vehicle is 30 m away from the lead car, it starts decelerating to attain an absolute target speed of 15 m/s.

You can visualize the assigned speed command in the Logic editor pane and the Attributes pane. For more information, see Define Scenario Logic (RoadRunner Scenario).

In this example, you implement a speed action following behavior for the ego vehicle using a MATLAB System object. Select the SpeedActionFollower.rrbehavior file in the Library Browser. The Attributes pane shows that the behavior file points to a MATLAB System object, SpeedActionFollower.m.

Specify the custom SpeedActionFollower.rrbehavior behavior for the ego vehicle. For more information on assigning behaviors, see Specify and Assign Actor Behaviors (RoadRunner Scenario).

This example uses the changeSpeedType scenario variable to programmatically vary the Relative To attribute of the Change Speed action of the ego vehicle. Using this variable, you can specify an absolute target speed or a relative target speed.

Connect to the RoadRunner Scenario server for cosimulation using the createSimulation function.

rrSim = rrApp.createSimulation;

rrSim is the ScenarioSimulation object. Use this object to set variables and to read scenario-related information.

Enable data logging.

rrSim.set('Logging','On');

Design Speed Action Follower

The speed action follower reads path and speed actions from RoadRunner Scenario and updates the runtime pose of the ego vehicle. This diagram shows the key functionality implemented in the speed action follower.

The speed action follower defines a custom behavior for the ego vehicle in RoadRunner Scenario. This custom behavior, SpeedActionFollower.m, is implemented using a MATLAB System object.

The SpeedActionFollower MATLAB program file calls the setupImpl function method during initialization. The function reads the Follow Path action from RoadRunner Scenario and gets the waypoints of the specified path of the ego vehicle.

SpeedActionFollower then calls the stepImpl function at each simulation step. The speed action adapter reads the Change Speed action from RoadRunner Scenario and calculates the current speed of the ego vehicle. The polyline evaluator reads the waypoints and the current speed to calculate the current pose of the ego vehicle.

Speed Action Adapter

The speed action adapter processes Change Speed action messages and updates the current speed of the vehicle. It supports absolute and relative types of target speed. The HelperSpeedActionAdapter.m script implements the speed action adapter with this primary interface:

[currentSpeed] = stepImpl(obj,timestep,stopVehicle,vehicleRuntime,msgSpeedAction,msgAllVehicleRuntime)

• timestep — Step size for simulation time.

• stopVehicle — Flag that shows whether the ego vehicle finished traveling on its route.

• vehicleRuntime — Runtime data of the ego vehicle.

• msgSpeedAction — Message about the Change Speed action from RoadRunner Scenario.

• msgAllVehicleRuntime — Message about runtime data for all vehicles in RoadRunner Scenario.

• currentSpeed — Current speed of the ego vehicle.

Polyline Evaluator

The polyline evaluator calculates the next ego position based on the current position and the current speed. The HelperPolylineEvaluator.m script implements the polyline evaluator with this primary interface:

[posX,posY,posZ,yaw,routeDistance,routeFinished] = stepImpl(obj,polyline,polylineLength,timestep,speed)

• polyline — 2-D matrix representing the waypoints on the path. Each row contains three elements, representing the x-, y-, and z-coordinates of the corresponding waypoint, respectively.

• polylineLength — Number of waypoints in the path.

• timestep — Step size for simulation time.

• speed — Current speed of the ego vehicle.

• posX, posY, posZ — Updated x-, y-, and z-positions of the ego vehicle, respectively.

• yaw — Updated yaw of the ego vehicle.

• routeDistance — Distance traveled by the ego vehicle.

• routeFinished — Flag that shows whether the ego vehicle finished traveling on its route.

Simulate Following Absolute Speed Action

This example assigns the changeSpeedType variable to the Relative To attribute of the Change Speed action of the ego vehicle in RoadRunner Scenario. Set changeSpeedType to Absolute.

rrApp.setScenarioVariable('changeSpeedType','Absolute');

Start the simulation and wait for the simulation to complete.

rrSim.set('SimulationCommand','Start');
while strcmp(rrSim.get('SimulationStatus'),'Running')
    pause(1);
end

Use the helperVisualizeSpeedFollowerVelocityProfile function to plot the simulation results. The helperVisualizeSpeedFollowerVelocityProfile helper function takes rrSim, the ego actor ID, and the lead vehicle actor ID as inputs.

helperPlotSpeedFollowerVelocityProfile(rrSim,1,2);

Examine the simulation results.

• The Relative distance plot shows the relative longitudinal distance between the ego vehicle and lead vehicle. When the relative distance reaches 30 m, the ego vehicle slows down to 15 m/s. At the end of the simulation, the ego vehicle collides with the lead vehicle.

• The Relative velocity plot shows the relative longitudinal velocity between the ego and lead vehicles. Initially, relative velocity is 0 m/s because both the ego and lead vehicle starts traveling at the same speed. When the ego vehicle slows down, the relative velocity first decreases, and then increases because the ego vehicle maintains a velocity of 15 m/s and the lead car continues to slow down to attain a velocity of 5 m/s.

• The Longitudinal velocity plot shows the absolute longitudinal velocities of both the ego and the lead vehicle. When the Change Speed action is triggered, the ego vehicle slows down to 15 m/s and maintains that speed.

Simulate Following Relative Speed Action

Set changeSpeedType to Relative.

rrApp.setScenarioVariable('changeSpeedType','Relative');

The second action phase of the ego vehicle now defines a relative speed action. When the ego vehicle is 30 m away from the lead car, the ego vehicle starts decelerating to match the speed of the lead car.

Start the scenario and wait for the simulation to complete.

rrSim.set('SimulationCommand','Start');
while strcmp(rrSim.get('SimulationStatus'),'Running')
    pause(1);
end

Use the helperVisualizeSpeedFollowerVelocityProfile function to plot the simulation results.

helperPlotSpeedFollowerVelocityProfile(rrSim,1,2);

Examine the simulation results.

• The Relative distance plot shows the relative longitudinal distance between the ego and lead vehicle. When the relative distance reaches 30m, the ego vehicle slows down to match the speed of the lead vehicle. At the end of the simulation, the ego vehicle maintains a constant distance from the lead vehicle and avoids collision.

• The Relative velocity plot shows the relative longitudinal velocity between the ego and lead vehicles. When the ego vehicle slows down, the relative velocity decreases until it reaches 0 m/s.

• The Longitudinal velocity plot shows the absolute longitudinal velocity of both the ego and the lead vehicle. When the Change Speed action is triggered, the ego vehicle slows down to match the speed of the lead vehicle, and continues to follow the speed of the lead vehicle.

Conclusion

This example showed how to design a speed action follower in MATLAB by reading a Change Speed action and Follow Path action from RoadRunner Scenario. It also showed how to use a scenario variable to parameterize the scenario and simulate the updated scenario.