Configuring vehicles

There are two factors in vehicle configuration:

Vehicle model type
Vehicle control type

Vehicle model types

You can run tests with various types of vehicle models:

A custom model that represents the System Under Test (SUT) and is connected to Foretify via a SUT Support Package (DSP).
A Foretellix SUT Model, usually a High-Level Model (HLM) of a SUT. You can use these models to mimic the behavior of a real SUT if one is not available. These models are useful when you need to evaluate new scenarios in a realistic environment.
A simulator-specific behavioral model that is connected to Foretify via a Simulator Support Package (SSP). These models typically represent Non-Player Characters (NPCs). Currently, Foretify supports the Krauss, IDM and W99 models of SUMO.
The native FTX Group Driver Model lets you use the FTX driver in car groups to control vehicles.

Every vehicle has an sp_manager_type field that defines its support package, either DSP or SSP. The default is SSP.

Vehicle control types

From Foretify’s point of view, there are two ways of controlling a vehicle:

The vehicle is controlled autonomously, meaning that it is fully controlled either by a custom SUT model or by a third-party behavioral model. Sometimes this is called uncontrolled.
The vehicle is controlled manually, meaning that Foretify controls it, either partially or completely.

Foretify has two ways of controlling a vehicle:

Foretify provides a trajectory, defined in global lateral and longitudinal (xy) terms. This mode is called kinematic and is typically supported by simulator models of NPCs but not by custom models (SUTs). Kinematic movement allows the execution of more exact trajectories and has lower computational costs for the simulator.
Foretify provides pedal and steering commands using force (N) and torque (Nm), respectively. This mode is called dynamic and is supported by both custom and simulator models. Dynamic movement produces substantially better physical realism of the vehicle movement. The commands are defined by Foretify internally and are not available to users.

Every vehicle has a physical_drive field that defines whether its control is kinematic or dynamic. The default is kinematic.

Vehicle configuration types

Based on the model and control types, there are three vehicle configuration types. A single test can include vehicles configured in different ways:

manual: Foretify plays the part of a human driver by passing pedal and steering commands to the SUT, or it drives an NPC vehicle by passing a trajectory to the simulator. This mode should be used for L1-L3 SUT vehicles and for NPCs that must perform specific maneuvers during a scenario.
sut_control: The vehicle is fully controlled by the SUT. Foretify doesn't calculate trajectories or send pedal or steering commands; it only sets a target destination. This mode can be used for L4 and above SUTs.
third_party_bm: The vehicle is controlled by some external behavioral model. This mode should be used for NPCs driven in car groups that are led by a SUMO behavioral model.

Accordingly, you should set the vehicle.behavior_manager_type field to one of the above values. manual is the default value.

Configuring the principal actor

The Foretify domain model defines an sut actor that is intended to represent the System Under Test (SUT). The sut actor has a field car of type sut_vehicle. The car field represents the vehicle that is controlled fully or partially by the SUT.

Because sut_vehicle inherits from vehicle, all the fields defined in vehicle can be constrained, most importantly:

vehicle.physical holds a general description of a vehicle's physical attributes or limitations.
vehicle.policy holds a general description of a vehicle's behavior in normal circumstances.

In order to facilitate Foretify's planning of scenarios, you should set or constrain the vehicle.physical and vehicle.policy fields appropriately.

In addition, sut.car has several fields that you must constrain appropriately depending on the level of the SUT. The following section shows how to constrain these fields.

See also Vehicle actor for a description of the vehicle fields.

For complete examples that illustrate the concepts in this topic, see Configuring NPC vehicles.

Configuring a L1 - L3 ADAS SUT

In Level 1 - Level 3 Advanced Driver Support Systems (ADAS), Foretify plays the role of a human driver by activating the system and controlling either the lateral or longitudinal movement of the vehicle. In Foretify's terms, the physical_drive of the vehicle is dynamic.

To execute a test with a custom SUT and one or more NPCs, you must import the following files:

Foretify's baseline DUT Support Package (DSP) enables communication between Foretify and the SUT, so that Foretify can send commands to the SUT. The SUT then sends the commands, with or without modification, to the simulator in order to control the movement of SUT vehicle.
Foretify's baseline Simulator Support Package (SSP) sends commands to the simulator to control the movements of NPC vehicles.
Customer extensions are required to the DSP and to Foretify's baseline ADAS interface in order to enhance communication with the custom SUT and its ADAS function.

Foretellix provides a default Automated Lane Keeping System (ALKS) execution platform:

$FTX/env/basic/exe_platforms/sumo_dsp/config/sumo_ALKS_dsp_config.osc

To configure a L1 - L3 ADAS SUT:

Import the proper simulator and SUT interface files.

For example, if you are using the SUMO simulator:

OSC2 code: import interface files

import "$FTX/config/sim/sumo_default.osc"
import "$FTX/env/basic/exe_platforms/sumo_dsp/config/sumo_dsp_config.osc"
import "my_custom_DSP_extensions.osc"
import "my_custom_ACC_extensions.osc"

Extend sut.car to define its model and control characteristics:

OSC2 code: define SUT model and control

extend sut:
    keep(car.sp_manager_type == DSP)
    keep(car.behavior_manager_type == manual)
    keep(car.physical_drive == dynamic)
    keep(car.policy.has_dynamic_controller == true)
    keep(car.physical.has_dynamic_controller == true)

See complete example.

During each scenario, activate the appropriate ADAS mode, for example:

OSC2 code: activate ADAS mode

do serial():
    sut.car.press_ACC_main_button()
    sut.car.drive() with:
        speed(requested_acc_cruise_speed,
            at: end, tolerance: acc_tolerance)
        cruising_lane: keep_lane()
        override(cruising_lane, run_mode:best_effort)
    sut.car.press_ACC_set_button(cruise_speed: requested_acc_cruise_speed)
    sut_drive: sut.car.drive(duration:[7..20]s) with:
        sut_cruise_speed: keep_speed()
        override(sut_cruise_speed,run_mode:best_effort)

press_ACC_main_button() and press_ACC_set_button() are the scenarios that implement the Foretify interface for the high-level Foretellix ACC Model. The scenarios that implement the Foretify interface for your SUT may be named differently.

Configuring a L4 or L5 AV SUT

In a Level 4 - Level 5 Autonomous Vehicle (AV), Foretify may play the role of a human driver by activating or deactivating the system, and the SUT controls both lateral and longitudinal movement. In Foretify's terms, the physical_drive of the vehicle may be either dynamic or kinematic.

Foretellix provides default AV execution platforms:

$FTX/env/basic/exe_platforms/carla_dsp/config/carla_AV_dsp_config.osc
$FTX/env/basic/exe_platforms/sumo_dsp/config/sumo_AV_dsp_config.osc

On these platforms, the physical_drive of the vehicle is dynamic and AV mode is activated at the start of the scenario.

To configure an L4 or L5 AV SUT:

Import the proper simulator and SUT interface files.

For example, if you are using the SUMO simulator:

OSC2 code: import interface files

import "$FTX/config/sim/sumo_default.osc"
import "$FTX/env/basic/exe_platforms/sumo_dsp/config/sumo_AV_dsp_config.osc"
import "my_custom_DSP_extensions.osc"
import "my_custom_AV_extensions.osc"

Extend sut.car to define its model and control characteristics:

OSC2 code: SUT control is kinematic

extend sut:
    keep(car.sp_manager_type == DSP)
    keep(car.behavior_manager_type == sut_control)
    keep(car.physical_drive == kinematic)

OSC2 code: SUT control is dynamic

extend sut:
    keep(car.sp_manager_type == DSP)
    keep(car.behavior_manager_type == manual)
    keep(car.physical_drive == dynamic)
    keep(car.policy.has_dynamic_controller == true)
    keep(car.physical.has_dynamic_controller == true)

During each scenario, activate the appropriate AV mode, for example:

OSC2 code: activate ADAS mode

do serial():
    sut.car.drive(duration: 0.5second)
    sut.dut_driver.request_av_mode(state: active)   # sends av_control to DSP
    av_driving: sut.car.drive(duration: 1second)

on @av_driving.end:
    call top.fail_if(sut.car.state.vehicle_indicators.av_state != active, AV_basic_checks,
            "AV did not reported 'active' after activation command")

The request_av_mode() is the scenario that implement the default Foretify interface for Level 4 and above SUTs. The scenario that implements the Foretify interface for your SUT may be named differently.

Using a Foretellix SUT Model

You can use a Foretellix model of an SUT to mimic the behavior of a real SUT if one is not available. These models are useful when you need to evaluate new scenarios in a realistic environment.

Foretellix currently provides several High-Level Models (HLMs) that are simulator-agnostic. These HLMs are internal to Foretify:

Foretellix Adaptive Cruise Control (ACC) Model
Foretellix Autonomous Emergency Braking (AEB) Model (forward motion)
Foretellix Lane Centering Assist (LCA) Model
Foretellix Lane Support System (LSS) Model
Foretellix Speed Assist System (SAS) Model

Foretellix also supports several simulator-specific SUT models. These models are external to Foretify:

Foretellix Active Lane Change Assist (ALCA) Model for SUMO
Foretellix Blind Spot Monitoring (BSM) Model for SUMO
Foretellix Emergency Steering Assist (ESA) Model for Carla
Foretellix Rear Autonomous Emergency Braking (AEB) Model for Carla

To execute a test with a Foretellix SUT Model and one or more NPCs, you need the following:

Foretify's baseline DUT Support Package (DSP) enables communication between Foretify and the SUT, so that Foretify can send commands to the SUT. The SUT then sends the commands, with or without modification, to the simulator in order to control the movement of SUT vehicle.
Foretify's baseline Simulator Support Package (SSP) sends commands to the simulator to control the movements of NPC vehicles.
Foretify's SUT Models play the role of an L1 - L3 ADAS system.

To use a Foretellix SUT Model:

If you are using a simulator-specific model, build the Foretellix SUT Model implementations when you receive a new Foretellix release.
Shell commands: build Foretellix SUT Model implementations
```
$ cd $FTX/env/basic/driver_dut_imps
$ sh build_imps.sh
```

In the test file, import the desired simulator interface files.

OSC2 code: import SUMO interface files

import "$FTX/config/sim/sumo_default.osc"
import "$FTX/env/basic/exe_platforms/sumo_dsp/config/sumo_dsp_config.osc"

OSC2 code: import Carla interface files

import "$FTX/config/sim/carla_default.osc"
import "$FTX/env/basic/exe_platforms/carla_dsp/config/carla_dsp_config.osc"

In the test file, import the desired ADAS interface file.
OSC2 code: import ACC HLM interface
```
import "$FTX/env/basic/adas_hlm_imps/ACC/acc_hlm_imp.osc"
```
OSC2 code: import rear AEB interface for Carla
```
import "$FTX/env/basic/driver_dut_imps/rear_AEB/rear_aeb_drive_imp.osc"
```
[Optional] Control some aspects of the behavior of the Foretellix SUT Model using the appropriate field of sut.car.hlm_driver.acc_behavior, for example:
OSC2 code: configure ACC params
```
extend top.main:
    def post_plan() is also:
        sut.car.hlm_driver.acc_behavior.acc_behavior_params.max_deceleration = 5mpsps
```
OSC2 code: disable collision avoidance
```
keep(default ftx_driver.collision_avoidance_behavior.enabling_policy == always_disabled )
```
For more information on these parameters, see hlm_driver behaviors.

During the drive, activate the ADAS mode.

OSC2 code: activate ACC example

scenario vehicle.activate_acc:
    do serial():
       sut.car.press_ACC_main_button()

OSC2 code: activate AEB example

scenario vehicle.activate_aeb:
    do serial():
       sut.car.request_AEB_mode(state:active)

Complete example: Foretellix ACC Model

OSC2 code: ACC basic drive

import "$FTX/config/sim/sumo_default.osc"
import "$FTX/env/basic/exe_platforms/sumo_dsp/config/sumo_dsp_config.osc"
import "$FTX/env/basic/adas_hlm_imps/ACC/acc_hlm_imp.osc"

extend test_config:
    set map = "$FTX_PACKAGES/maps/straight_long_road.xodr"
    set test_drain_time = 0second

extend sut_vehicle:
    def post_plan() is also:
        hlm_driver.acc_behavior.acc_behavior_params.max_deceleration = 5mpsps

scenario sut.acc_basic_drive:
    acc_speed: speed with:
        keep(it in [50..60]kph)

    do serial():
        sut.car.press_ACC_main_button() # switch from OFF to STANDBY mode

        pre_acc_drive: sut.car.drive() with:
            duration([3..5]second)
            speed(speed:  acc_speed, at: end)

        sut.car.press_ACC_set_button(cruise_speed: acc_speed)

        acc_drive: sut.car.drive() with:
            duration([5..7]second)

        sut.car.press_ACC_cancel_button()

        post_acc_drive: sut.car.drive() with:
            duration([3..5]second)

extend top.main:

    do sut.acc_basic_drive()

Complete example: Foretellix AEB rear Model

OSC2 code: AEB reverse drive and stationary object

import "$FTX/config/sim/sumo_default.osc"
import "$FTX/env/basic/exe_platforms/sumo_dsp/config/sumo_dsp_config.osc"
# import "$FTX/config/sim/carla_default.osc" # From: 'sim: carla' from sim_manually_driven_dynamic_config.tosc
# import "$FTX/env/basic/exe_platforms/carla_dsp/config/carla_dsp_config.osc" # From: 'sim: carla' from sim_manually_driven_dynamic_config.tosc
import "$FTX/env/basic/driver_dut_imps/rear_AEB/rear_aeb_drive_imp.osc"
import "$FTX_PACKAGES/adas/AEB/common/utils/external.osc"

# import "$FTX/env/basic/driver_dut_imps/rear_AEB/rear_aeb_drive_imp.osc"
# import "$FTX_PACKAGES/adas/AEB/common/utils/external.osc"

extend test_config:
    set map = "$FTX_PACKAGES/maps/straight_long_road.xodr"
    set test_drain_time = 0second

extend sut_vehicle:
    def post_plan() is also:
        hlm_driver.aeb_behavior.aeb_behavior_params.roi_length_increase = 2.1m

scenario sut.aeb_sut_reverse_drive_and_stationary_object:
    stationary_object: plain_object
    sut_width: length with:
        keep(it == sut.car.get_width())
    sut_speed: speed
    keep(soft sut_speed in [1..40]kph)
    sut_rel_lon_dist_to_stationary_object: length with:
        keep(default it in [10..60]m)
    overlap_dist: length with:
        keep(default it in [0m..sut_width])
    lane_num: int with:
        keep(default it in [1..3])

    stationary_object_pos: msp_position

    line_shape_reverse: line_shape_reverse with:
        keep(it.lon_speed == sut_speed)
        keep(it.offset == sut_rel_lon_dist_to_stationary_object)

    top.position_along_drive(stationary_object_pos, sut_reverse_drive
                            ,lon_offset: - (sut_rel_lon_dist_to_stationary_object)
                            ,lat_offset: (sut_width/2) - overlap_dist)

    initial_stop_time: time with:
        keep(it == 2s)

    do aeb_sut_reverse_drive_and_stationary_object:parallel(start_to_start:0s, overlap:any):
        sut_drive: serial():
            sut.car.request_rear_AEB_mode(state: active)
            sut_at_stop: sut.car.drive(duration:initial_stop_time) with:
                lane(lane_num, from: curb, at: all)
                sut_reverse_speed: speed(0kph, at: all)
                override(sut_reverse_speed, run_mode: best_effort)
            sut_reverse_drive: sut.car.drive() with:
                lane(lane_num, from: curb, at: all)
                shape(quantity: position, request: both, shape_object: line_shape_reverse)
        stationary_object.exists_at(stationary_object_pos)

extend top.main:
    do a:sut.aeb_sut_reverse_drive_and_stationary_object() with:
        keep(it.stationary_object.kind == person)
        keep(it.sut_speed == 4kph)
        keep(it.sut_rel_lon_dist_to_stationary_object == 10m)
        keep(it.overlap_dist == 0.40m)
        keep(it.lane_num == 2)

Configuring NPC vehicles

You can run most tests without configuring NPC vehicles. However, if you want to more closely simulate the behavior of human drivers, you can use the models provided by various simulators.

These models display movement-related behavior, such as speed and lane changes. They can also model other behaviors, such as the willingness to change behavior in order to accommodate other actors, respect for other vehicles' safety gap and so on.

Behavioral models let you control vehicle traffic around the SUT or program the behavior of a single actor to have an active role in the scenario.

Behavioral models are executed by a simulator-specific behavioral model engine (BME). Currently, Foretellix provides a SUMO-specific BME. For more information, see Foretify's SUMO Behavioral Model Engine.

Alternatively, you can use the FTX Group Driver Model. This model struct lets you use the FTX driver in car groups to control vehicles. The benefit of using FTX driver is that it supports all NPC behaviors, including avoiding collisions, reacting to traffic signals, and so on.

Complete example: Foretellix Behavioral Model Engine (BME)

This example uses the Foretellix BME and the sumo_idm_normal_driver profile to program random traffic around the SUT vehicle.

OSC2 code: normal driver model

import "$FTX/config/sim/sumo_default.osc"
import "$FTX/env/basic/behavioral_models/sumo/builtin/sumo_builtin_bme.osc"
import "$FTX/env/basic/behavioral_models/sumo/common/sumo_demo_profiles.osc"

extend test_config:
    set map = "$FTX_PACKAGES/maps/straight_long_road.xodr"

extend top.main:
    random_traffic: random_traffic_car_group with(origin_actor: sut.car)

    dm: sumo_idm_normal_driver
    for car in random_traffic.cars:
        keep(car.initial_bm == dm)

    do parallel(overlap:equal):
        dut_drive: sut.car.drive(duration: 10second) with:
            speed(20kph)
        random_traffic.light_highway_traffic()

Complete example: Foretellix Behavioral Model Engine (BME)

This example uses the Foretellix BME and the sumo_idm_aggressive_driver profile to program a car group (a group of cars moving in unison) around the SUT vehicle.

OSC2 code: aggressive driver model

import "$FTX/config/sim/sumo_default.osc"
import "$FTX/env/basic/behavioral_models/sumo/builtin/sumo_builtin_bme.osc"
import "$FTX/env/basic/behavioral_models/sumo/common/sumo_demo_profiles.osc"

extend test_config:
    set map = "$FTX_PACKAGES/maps/highway.xodr"

extend top.main:
    lead_vehicle: vehicle
    sut_cruise_speed: speed with:
      keep(default it == 90kph)
    hwy: highway
    car_group: single_lane_car_group with(reference_car: lead_vehicle):
        keep(it.cars.size() == 6)

    dm: sumo_idm_aggressive_driver
    for car in car_group.cars:
        keep(car.initial_bm == dm)

    do parallel(overlap:equal):
            lead_vehicle.drive() with:
                lane(side_of: sut.car)
                position(time: [2s..4.5s], ahead_of: sut.car, at: start)
                speed(speed: [-sut_cruise_speed+10kph..-sut_cruise_speed+20kph], 
                            faster_than: sut.car, track: projected, at: end)
                along(hwy)
            sut.car.drive() with:
                speed(speed: sut_cruise_speed)
                along(hwy)
            car_group_start: car_group.group_drive()
    with:
        duration([10..10]second)