Merge pull request #50 from asam-oss/clarify_ALKS_controller_activation

Clarify ALKS controller activation
asam-oss · Nov 18, 2021 · 289f12b · 289f12b
2 parents 1cbfa77 + 864b9b2
commit 289f12b
Show file tree

Hide file tree

Showing 16 changed files with 75 additions and 49 deletions.
diff --git a/README.md b/README.md
@@ -1,27 +1,33 @@
 ALKS Scenario Interpretation in OpenSCENARIO
 ============================================
 
+## Description
+
+### Introduction
+
 As presented in the [UNECE Press Release](https://unece.org/transport/press/un-regulation-automated-lane-keeping-systems-milestone-safe-introduction-automated), the "UN Regulation No. 157 - Automated Lane Keeping Systems (ALKS)" ECE/TRANS/WP.29/2020/81 <sup>[[1]](https://unece.org/transport/documents/2021/03/standards/un-regulation-no-157-automated-lane-keeping-systems-alks)</sup> describes the necessary requirements to be fulfilled for the approval of an ALKS, which is a level 3 automated driving system on motorways.
 
 The ALKS regulation also contains test scenarios at a functional level, which are to be carried out in close coordination with a technical service:
 
 *"Until [...] specific test provisions have been agreed, the Technical Service shall ensure that the ALKS is subject to at least the tests outlined in Annex 5."*
 
-## Goal
+### Goal
 
 The ALKS regulation itself leaves room for interpretation, therefore one goal of this publication is the coordination on a common interpretation with partners. Hence, this work has also been conducted in the context of the German research project [SET Level](https://setlevel.de). 
 
-BMW has taken on the task of implementing the test scenarios from the ALKS regulation. Since exchange and compatibility via the tool landscape is vital, another goal is the implementation of the scenarios using an international standard. At the [ASAM e.V.](https://www.asam.net/standards/domain-simulation/) members are developing the so called "OpenX" standards for the simulation domain like OpenSCENARIO (Release v1.1 Q1/21) for scenario definitions and OpenDRIVE (Release v1.6.1 Q1/2021) for road network definitions. The implementation is using [OpenSCENARIO](https://www.asam.net/standards/detail/openscenario/) and [OpenDRIVE](https://www.asam.net/standards/detail/opendrive/), resulting in a bundle of XML files executable with standard compliant simulators.
+BMW has taken on the task of implementing the test scenarios from the ALKS regulation. Since exchange and compatibility via the tool landscape is vital, another goal is the implementation of the scenarios using an international standard. At the [ASAM e.V.](https://www.asam.net) members are developing the so called "OpenX" standards for the simulation domain like OpenSCENARIO (Release v1.1 3/2021) for scenario definitions and OpenDRIVE (Release v1.7 8/2021) for road network definitions. The implementation is using [OpenSCENARIO](https://www.asam.net/standards/detail/openscenario/) and [OpenDRIVE](https://www.asam.net/standards/detail/opendrive/), resulting in a bundle of XML files executable with standard compliant simulators.
 
-## Content
+### Content
 
 The here provided 15 concrete parametrized test scenarios are derived from the 6 subject areas analogous to Annex 5, Chapter 4.1-4.6 as an initial attempt to clarify the described set of functional scenarios.
 
 Each concrete scenario is complemented by a variation file to form a logical scenario, which then represents a set of concrete scenarios. By applying the parameter variation defined in the variation files to the parameters in the concrete scenarios, multiple concrete scenarios can be derived or generated to cover the required scenario space.
 
 The focus of the here provided scenarios is on securing the planning aspects of an "Automated Lane Keeping System". By extending the scenarios with environmental conditions (e.g. light, rain or wind) or references to e.g. 3D models, aspects of sensor and actuator technology could also be simulated and validated.
 
-## Executing on Windows
+## Installation & Execution
+
+### Windows
 
 The execution of the concrete scenarios in the open source tools "esmini", a basic OpenSCENARIO player, and "openPASS", a simulation platform for traffic simulation, is described on Windows:
 
@@ -30,37 +36,47 @@ _Note:_ Currently only esmini supports the OpenSCENARIO 1.1 format. For openPASS
 _Note:_ The execution with openPASS expects xsltproc on the system path. Check out the "Notes regarding openPASS" for more information.
 
 1. Clone or download this repository to your local drive.
-2. a) Download the [latest esmini release](https://github.com/esmini/esmini/releases) (e.g. esmini-bin_win_x64.zip) (tested successfully with [esmini 2.12.4](https://github.com/esmini/esmini/releases/tag/v2.12.4)),  
+2. a) Download the [latest esmini release](https://github.com/esmini/esmini/releases) (e.g. esmini-bin_win_x64.zip) (tested successfully with [esmini 2.15.3](https://github.com/esmini/esmini/releases/tag/v2.15.3)),  
 or  
 b) Download the [latest openPASS release](https://gitlab.eclipse.org/eclipse/simopenpass/simopenpass) (tested successfully with [openPASS v0.7](https://gitlab.eclipse.org/eclipse/simopenpass/simopenpass/-/tree/openPASS_0.7))
 3. a) Create an environment variable "ESMINI", which directs to the "bin" folder of esmini. E.g. "C:\MyFolder\esmini\bin\",  
 or  
 b) Create an environment variable "OPENPASS", which directs to the installation directory of openPASS. E.g. "C:\MyFolder\openPASS\"
-4. Execute the script "run_Scenario.bat", located in the "Scenarios" folder of the local repository
-5. If you change the parameter values in the parameter declaration section of the OpenSCENARIO files within their defined constraints, the concrete scenarios can be varied manually.
+4. Execute the script "run_Scenario.bat", located in the "Scenarios" folder of the local repository and follow the instructions
 
 #### Notes regarding esmini:
 
-Esmini is an environment simulator with a visualization and does not provide an ALKS. Therefore, for demonstration purposes the vehicle under test is controlled by a so called "default controller", which is provided by esmini. This controller type is defined by the OpenSCENARIO standard as a controller that only maintains the speed and lane offset without taking other traffic participants into account. 
-If the scenarios are used for testing an ALKS, then the activation of the ALKS is already prepared in the scenarios. Every scenario has an "ActivateALKSControllerAction" with an "ActivateALKSControllerStartCondition" referring to the simulation time. If the value for the simulation time is changed to 0, then the ALKS shall be activated directly at the beginning of the scenario. The actual sending of the manufacturer-specific signal from the environment simulation to the ALKS component for ALKS activation needs to be implemented in the environment simulation. Another option would be to embed the scenarios in test cases and trigger the activation of the ALKS from the test case.
+Esmini is an environment simulator with a visualization. It even provides a simple internal ALKS controller, which is activated through the scenario to demonstrate how the scenarios should run.
 
 #### Notes regarding openPASS:
 
 openPASS currently supports the execution of the scenarios 4.1_1, 4.2_1, 4.2_2, 4.2_4, 4.5_1, 4.5_2 and 4.6_1. The remaining scenarios will be enabled in upcoming releases of openPASS.
 
-The execution with openPASS works on Linux with the same scenarios. However, steps from the execution script "run_Scenario.bat" have to be performed manually.
-
 The simulation in openPASS is configured through a set of configuration files. These files consist of the scenario, its catalogs and the map. Additionally some configuration files located in "OSC-ALKS-scenarios\Scenarios\openPASS_Resources" are required. Prior to simulation some slight modifications have to be done in the scenarios. This step is automated in the "run_Scenario.bat" by applying an xslt to the scenario. 
 
 Dependency: xsltproc is used to apply the xslt script to the scenario. Guide for installation:  
 1. Download and install [msys2](https://www.msys2.org/)
 2. Extent the path environment variable by the _bin_ directory of msys2 (e.g. "C:\msys64\usr\bin") 
 
-Similar to esmini, openPASS does not provide an ALKS. Therefore, for demonstration purposes the vehicle under test is controlled by a so called "Algorithm Following Driver Model - AFDM", which is provided by openPASS. This model is parametrized to drive approximately at its target velocity of 60 km/h and keeps the lane. Other traffic participants are taken into account (This differentiates the execution of the scenarios in openPASS from execution in esmini). For information on the integration of an ALKS in the simulation, we refer to the documentation of openPASS.
+OpenPASS does not provide an ALKS. Therefore, for demonstration purposes the vehicle under test is controlled by a so called "Algorithm Following Driver Model - AFDM", which is provided by openPASS. This model is parametrized to drive approximately at its target velocity of 60 km/h and keeps the lane. Other traffic participants are taken into account. For information on the integration of an ALKS in the simulation, we refer to the documentation of openPASS.
 
 Currently openPASS does not support the controller concept of OpenSCENARIO. Instead, entities and their controlling components are defined in the ProfilesCatalog.xml. Sourrounding entities are also controlled by the Algorithm Following Driver Model. Therefore, the velocities of the surrounding entities may differ slightly from the definitions in the scenarios. 
 
-## Executing on Linux
+### Linux
+
+#### esmini
+
+1. Please follow the steps 1. and 2. a) from the above instructions for Windows (clone/download repo and install esmini)
+2. Once esmini is installed (e.g. to ~/esmini), go to the "Scenarios" folder and execute e.g.:
+```
+~/esmini/bin/esmini --osc ALKS_Scenario_4.1_1_FreeDriving_TEMPLATE.xosc
+```
+
+#### openPASS
+
+The execution with openPASS works on Linux with the same scenarios as for Windows. However, steps from the execution script "run_Scenario.bat" have to be performed manually.
+
+#### CARLA
 
 The execution in the open source simulator "CARLA" under Ubuntu 20.04 is described here:
 
@@ -73,17 +89,27 @@ The execution in the open source simulator "CARLA" under Ubuntu 20.04 is describ
 
 _Note:_ For execution with CARLA please use the [release v0.3.2](https://github.com/asam-oss/OSC-ALKS-scenarios/releases/tag/v0.3.2) with scenarios in OpenSCENARIO 1.0 format.
 
-Execution with esmini or openPASS on Linux hasn't been tested yet.
-
-#### Notes regarding CARLA
-
 With CARLA version 0.9.11 the following scenarios are supported: 4.1_1, 4.2_1, 4.2_2, 4.2_4.
 
 _Note:_ 4.2_X scenarios do only work if the pedestrian is modeled directly in the scenario and not in a catalog or is exchanged by a vehicle. Please refer to the bug fix in [this PR](https://github.com/carla-simulator/scenario_runner/pull/713)
 
+## Usage
+
+### Scenario variation
+
+You can either manually vary the scenarios by changing the parameter values in the parameter declaration section of the OpenSCENARIO files within their defined constraints. Or you can use the provided variation files to automatically create multiple concrete parameter sets / concrete scenarios prior to execution. For this an additional parameter set / scenario generation tool is necessary.
+
+### ALKS activation
+
+If the scenarios should be used for testing an actual simluation-external ALKS, a manufacturer-specific activation signal needs to be sent to the ALKS at the same time the "ActivateControllerAction" is executed.
+Architecturally this could be achieved in different ways:
+1. Implement in the environment simulation to activate an external ALKS instead of a simulation internal one (requires a manufacturer-specific simulation).
+2. Add a "CustomCommandAction" to the scenarios which is executed together with the "ActivateControllerAction". The command is used to start a script containing the manufacturer-specific activation signal (requires only a scenario-specific simulation to understand the command).
+3. Embed the scenarios in test cases and trigger the activation of the ALKS from the test case/software. Then the "ActivateControllerAction" will only cause the environment simulation to not control the ego vehicle anymore. The action then needs to be triggered not with a "SimulationTimeCondition" but by the test software. This can be achieved by setting a user defined value in the environment simulation with the test software and triggering the "ActivateControllerAction" with a "UserDefinedValueCondition". This requires neither a manufacturer-specific or a scenario-specific implementation of the environment simulation. 
+
 ## Quality Measures
 
-As a first proof-of-concept the scenarios have been integrated and simulated in [openPASS 0.7](https://git.eclipse.org/c/simopenpass/simopenpass.git/tag/?h=openPASS_0.7) at BMW. In addition the open source tool esmini can be used as described above.
+As a first proof-of-concept the scenarios have been integrated and simulated in [openPASS 0.7](https://gitlab.eclipse.org/eclipse/simopenpass/simopenpass/-/tree/openPASS_0.7) at BMW. In addition the open source tool esmini can be used as described above.
 
 The validation of the scenarios and maps provided in this repository is integrated into the CI workflow. There are two validation mechanisms implemented with GitHub actions:
 1. Syntactic validation of the scenarios and maps against the XSD schemas of the OpenSCENARIO 1.1 and OpenDRIVE 1.6 standards with xmllint
@@ -95,9 +121,9 @@ _Note:_ The *Standalone Checker* does not yet support OpenSCENARIO 1.1. Those ch
 
 The corresponding OpenSCENARIO Bundle has been licensed by [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/deed.de) and is hereby made publicly available. 
 
-The XSD schema of OpenSCENARIO is used under the license of ASAM, which can be found [here](https://www.asam.net/index.php?eID=dumpFile&t=f&f=3496&token=df4fdaf41a8463e585495001cc3db3298b57d426).
+The XSD schema of OpenSCENARIO is used under the license of ASAM, which can be found [here](https://www.asam.net/index.php?eID=dumpFile&t=f&f=4092&token=d3b6a55e911b22179e3c0895fe2caae8f5492467).
 
-The XSD schemas of OpenDRIVE are used under the license of ASAM, which can be found [here](https://www.asam.net/index.php?eID=dumpFile&t=f&f=3495&token=56b15ffd9dfe23ad8f759523c806fc1f1a90a0e8)
+The XSD schemas of OpenDRIVE are used under the license of ASAM, which can be found [here](https://www.asam.net/index.php?eID=dumpFile&t=f&f=4422&token=e590561f3c39aa2260e5442e29e93f6693d1cccd)
 
 The *Standalone Checker* of the OpenSCENARIO API and the corresponding GitHub action are used under the [Apache 2.0](https://github.com/RA-Consulting-GmbH/openscenario.api.test/blob/master/LICENSE) license.
 

diff --git a/Scenarios/ALKS_Scenario_4.1_1_FreeDriving_TEMPLATE.xosc b/Scenarios/ALKS_Scenario_4.1_1_FreeDriving_TEMPLATE.xosc
@@ -77,9 +77,9 @@
               </Action>
               <StartTrigger>
                 <ConditionGroup>
-                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="rising">
+                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="none">
                     <ByValueCondition>
-                      <SimulationTimeCondition value="10000" rule="greaterOrEqual" />
+                      <SimulationTimeCondition value="3.0" rule="greaterOrEqual" />
                     </ByValueCondition>
                   </Condition>
                 </ConditionGroup>

diff --git a/Scenarios/ALKS_Scenario_4.1_2_SwervingLeadVehicle_TEMPLATE.xosc b/Scenarios/ALKS_Scenario_4.1_2_SwervingLeadVehicle_TEMPLATE.xosc
@@ -130,7 +130,7 @@
                 <ConditionGroup>
                   <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="none">
                     <ByValueCondition>
-                      <SimulationTimeCondition value="10000" rule="greaterOrEqual" />
+                      <SimulationTimeCondition value="3.0" rule="greaterOrEqual" />
                     </ByValueCondition>
                   </Condition>
                 </ConditionGroup>

diff --git a/Scenarios/ALKS_Scenario_4.1_3_SideVehicle_TEMPLATE.xosc b/Scenarios/ALKS_Scenario_4.1_3_SideVehicle_TEMPLATE.xosc
@@ -125,9 +125,9 @@
               </Action>
               <StartTrigger>
                 <ConditionGroup>
-                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="rising">
+                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="none">
                     <ByValueCondition>
-                      <SimulationTimeCondition value="10000" rule="greaterOrEqual" />
+                      <SimulationTimeCondition value="3.0" rule="greaterOrEqual" />
                     </ByValueCondition>
                   </Condition>
                 </ConditionGroup>

diff --git a/Scenarios/ALKS_Scenario_4.2_1_FullyBlockingTarget_TEMPLATE.xosc b/Scenarios/ALKS_Scenario_4.2_1_FullyBlockingTarget_TEMPLATE.xosc
@@ -113,9 +113,9 @@
               </Action>
               <StartTrigger>
                 <ConditionGroup>
-                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="rising">
+                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="none">
                     <ByValueCondition>
-                      <SimulationTimeCondition value="10000" rule="greaterOrEqual" />
+                      <SimulationTimeCondition value="3.0" rule="greaterOrEqual" />
                     </ByValueCondition>
                   </Condition>
                 </ConditionGroup>

diff --git a/Scenarios/ALKS_Scenario_4.2_2_PartiallyBlockingTarget_TEMPLATE.xosc b/Scenarios/ALKS_Scenario_4.2_2_PartiallyBlockingTarget_TEMPLATE.xosc
@@ -120,9 +120,9 @@
               </Action>
               <StartTrigger>
                 <ConditionGroup>
-                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="rising">
+                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="none">
                     <ByValueCondition>
-                      <SimulationTimeCondition value="10000" rule="greaterOrEqual" />
+                      <SimulationTimeCondition value="3.0" rule="greaterOrEqual" />
                     </ByValueCondition>
                   </Condition>
                 </ConditionGroup>

diff --git a/Scenarios/ALKS_Scenario_4.2_3_CrossingPedestrian_TEMPLATE.xosc b/Scenarios/ALKS_Scenario_4.2_3_CrossingPedestrian_TEMPLATE.xosc
@@ -120,9 +120,9 @@
               </Action>
               <StartTrigger>
                 <ConditionGroup>
-                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="rising">
+                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="none">
                     <ByValueCondition>
-                      <SimulationTimeCondition value="10000" rule="greaterOrEqual" />
+                      <SimulationTimeCondition value="3.0" rule="greaterOrEqual" />
                     </ByValueCondition>
                   </Condition>
                 </ConditionGroup>

diff --git a/Scenarios/ALKS_Scenario_4.2_4_MultipleBlockingTargets_TEMPLATE.xosc b/Scenarios/ALKS_Scenario_4.2_4_MultipleBlockingTargets_TEMPLATE.xosc
@@ -128,9 +128,9 @@
               </Action>
               <StartTrigger>
                 <ConditionGroup>
-                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="rising">
+                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="none">
                     <ByValueCondition>
-                      <SimulationTimeCondition value="10000" rule="greaterOrEqual" />
+                      <SimulationTimeCondition value="3.0" rule="greaterOrEqual" />
                     </ByValueCondition>
                   </Condition>
                 </ConditionGroup>

diff --git a/Scenarios/ALKS_Scenario_4.3_1_FollowLeadVehicleComfortable_TEMPLATE.xosc b/Scenarios/ALKS_Scenario_4.3_1_FollowLeadVehicleComfortable_TEMPLATE.xosc
@@ -149,9 +149,9 @@
               </Action>
               <StartTrigger>
                 <ConditionGroup>
-                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="rising">
+                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="none">
                     <ByValueCondition>
-                      <SimulationTimeCondition value="10000" rule="greaterOrEqual" />
+                      <SimulationTimeCondition value="3.0" rule="greaterOrEqual" />
                     </ByValueCondition>
                   </Condition>
                 </ConditionGroup>

diff --git a/Scenarios/ALKS_Scenario_4.3_2_FollowLeadVehicleEmergencyBrake_TEMPLATE.xosc b/Scenarios/ALKS_Scenario_4.3_2_FollowLeadVehicleEmergencyBrake_TEMPLATE.xosc
@@ -139,9 +139,9 @@
               </Action>
               <StartTrigger>
                 <ConditionGroup>
-                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="rising">
+                  <Condition name="ActivateALKSControllerEventCondition" delay="0" conditionEdge="none">
                     <ByValueCondition>
-                      <SimulationTimeCondition value="10000" rule="greaterOrEqual" />
+                      <SimulationTimeCondition value="3.0" rule="greaterOrEqual" />
                     </ByValueCondition>
                   </Condition>
                 </ConditionGroup>