6.6 Controllers

Controller elements are elements of the simulation core that control the motion or appearance of a ScenarioObject. ASAM OpenSCENARIO does not specify how controllers work and how they are implemented. ASAM OpenSCENARIO considers a controller as a runtime element that is used to enforce the control strategies (see Section 7.4.1.1, "Control strategy") assigned to instances of ScenarioObject.

Any number of Controller elements can be assigned to objects of type Vehicle or Pedestrian.

A Controller may be internal, as a part of the simulator, or external, defined in a file. The intended use cases for controllers are:

Specifying that a vehicle is controlled by the system under test.
Defining smart actor behavior, where a controller takes intelligent decisions in response to the road network or other actors. Hence, controllers can be used, for example, to make agents in a scenario behave in a human-like way.
Assigning a vehicle to direct human control.

By default, controllers are assigned in a deactivated state.

6.6.1 Controller types

ASAM OpenSCENARIO defines four different domains of a Controller:

Longitudinal
Lateral
Lighting
Animation

Where the longitudinal and lateral domains are controlling the movement of the ScenarioObject, whereas the lighting and animation domains are controlling the appearance of the ScenarioObject (see Section 6.7, "Appearance").

In the Specification, when controllers are mentioned related to a moving action, it always relates to controllers in either the longitudinal, the lateral, or both domains.

ASAM OpenSCENARIO defines two types of controllers:

The default controller that enforces control strategies exactly as they are described by the actions
A user-defined controller that may have custom interpretations of control strategies

The default controller is expected to enforce control strategies along the entity domains that do not have a user defined controller.

ASAM OpenSCENARIO cannot prescribe the behavior of a user-defined controller. This means that simulations with user-defined controllers can differ from simulations generated using only default controllers, even though they use the same OSC Model Instance. This allows the scenario designer to use ASAM OpenSCENARIO in a broader scope, interpreting Action as suggestions rather than commands. Repeatable simulation results are only expected when using default controllers.

6.6.2 Controlling a scenario object

Any number of controllers can be assigned for the same ScenarioObject domain. However, only one controller can be activated for a domain at the time. If a controller is activated for a domain, the currently active controller in that domain becomes deactivated.

Activating a new controller does not interfere with the existing control strategy and the Action associated with that control strategy. Control strategies belong to the entity they are assigned to. Having a new controller does not change this. The new controller continues to enforce the existing control strategy just like the previous controller did. Figure 27 illustrates the coupling between controllers, entities, and control strategies.

6.6.3 Assigning a user-defined controller

A user-defined controller can be assigned explicitly with the AssignControllerAction:

Code 1. Example for an explicit assignment of a controller

<AssignControllerAction>
    <ObjectController name="UserDefinedEgoController">
        <CatalogReference catalogName="ControllerCatalog" entryName="Ego"/>
    </ObjectController>
</AssignControllerAction>

A user-defined controller may also be implicitly assigned by including it in the definition of a ScenarioObject, for example:

<ScenarioObject name="Traffic">
    <CatalogReference catalogName="VehicleCatalog" entryName="car_white"/>
    <ObjectController name="MovementController">
        <Controller name="SUMO" controllerType="movement"/>
    </ObjectController>
    <ObjectController name="AnimationController">
        <Controller name="Animation" controllerType="animation"/>
    </ObjectController>
</ScenarioObject>

The name attribute of the ObjectController element specifies the identifier of the user-defined controller in the scenario for later reference in an ActivateControllerAction.
The name attribute of the Controller element specifies the identifier for the type of user-defined controller to be instantiated (for example, Ego, SUMO, Animation, OSITrafficParticipant…). This name will be referenced as entryName from the CatalogReference class if the Controller is defined in a catalog. This name must also be interpretable by the Simulator Core to instantiate the corresponding user-defined controller.

By default, controllers are assigned to entities in deactivated state.

6.6.4 Activating a user-defined controller

User-defined controllers are activated for a given domain, for example, longitudinal, or lateral. The following actions are used to activate controllers:

ActivateControllerAction (Section 7.4.1, "Private action")
AssignControllerAction, given the activate options (Section 7.4.1, "Private action")

This is an example of how to use an ActivateControllerAction, given the controller was assigned in the same way as in Code 1 above:

<ActivateControllerAction objectControllerRef="UserDefinedEgoController" lateral="true" longitudinal="true"/>

If multiple controllers are assigned for the same domain and ActivateControllerAction is used without the objectControllerRef, the last assigned controller is activated.

A Controller cannot be activated in a domain where it is not defined through the controllerType.

For backward compatibility, ASAM OpenSCENARIO allows to omit the objectControllerRef attribute if only a single controller is assigned to the concerned entity (no matter if assigned implicitly or explicitly). However, this is considered not meaningful in case of multiple assigned controllers. This is expected to be addressed in one of the follow-up major versions, where the attribute shall be defined as mandatory to exclude an ambiguity in specifying the referenced controller.

6.6.5 Assigning the default controller

At runtime, all ScenarioObjects of type Pedestrian or Vehicle are assigned a default controller capable of enforcing control strategies. This controller shall not be assigned or unassigned by the OSC Model Instance.

6.6.6 Activating the default controller

The default controller cannot be activated or deactivated explicitly in the OSC Model Instance.

At runtime, the default controller is activated for a given domain if no user-defined controller is active for that domain. If a user-defined controller is activated for a domain, it automatically deactivates the default controller for that domain.