Skip to content
Snippets Groups Projects

Draft: Conan integration

Closed René Paris requested to merge conan_integration into feature/v1_2
Compare and
765 files
+ 9539
20330
Compare changes
  • Side-by-side
  • Inline
Files
765
+ 21
9
# OpenScenarioEngine
# OpenScenarioEngine Documentation
- [User Guide](../README.md)
- [Architecture Documentation](#Overview) (this document)
@@ -45,7 +45,7 @@ The following shows an (beautified) excerpt of the such an actual behavior tree,
...
```
# Design Principles
## Design Principles
The "ground truth" of [ASAM **OpenSCENARIO**](https://www.asam.net/standards/detail/openscenario/) is an UML model, used to generate the XML specification, documentation, the OpenScenarioLib, and OpenSCENARIO API.
When reading an OpenSCENARIO description with the parser component of the OpenScenarioLib, it generates objects implementing the OpenSCENARIO API.
@@ -58,7 +58,7 @@ For example, a `Condition` object holds either a `ByEntityCondition` or a `ByVal
Based on the current openSCENARIO description, the engine translates from pure **OpenSCENARIO API** objects into actual nodes of the internal behavior tree.
Tree generation is described in the following.
## Generation of the Behavior Tree
### Generation of the Behavior Tree
The heart of the engine is a behavior tree, based on the openPASS project [Yase](https://gitlab.eclipse.org/eclipse/openpass/yase).
Its responsibility is to handle the **interaction between conditions and actions** according to the standard.
@@ -164,12 +164,12 @@ So reaching the end of the function is literally an exception:
> The engine assumes that the description is complete.
> If not, exceptions are allowed.
## Handling of Union and List Types
### Handling of Union and List Types
Very often, the standard allow _xor_ (union) or _sequence_ (list) relations within elements the scenario description.
In the following, some special rules for these types are described:
### Union Types
#### Union Types
Suppose that the user specified a `ByValueCondition`, namely a `SimulationTimeCondition`, as `Condition`.
As `ByValueCondition`s are just a **union type** without additional information, no intermediate node is generated.
@@ -179,7 +179,7 @@ In other words `SimulationTimeCondition` will become the direct child `Condition
**✍️ Principle**
> **Skip** tree nodes for **union type**s, if they do not contain additional logic.
### List Types
#### List Types
For *list type*s, such as `Actions` in the `Event` element, parsing unwraps the individual elements into children of an ``yase::ParallelNode`` (see `gen/Conversion/OscToNode/ParseActions.cpp`):
@@ -211,12 +211,12 @@ Yet, no `Action` node exist as intermediate layer.
Instead each child is directly specialized to the lowest possible occurrence (_union type_).
This could be a concrete action, such as an `EnvironmentAction`, or another intermediate node, such as an `EntityAction`.
## Conditions and Actions
### Conditions and Actions
Concrete conditions and actions are the leafs of the tree.
As conditions precede actions, they will be described first.
### Conditions
#### Conditions
When the parsing process reaches a concrete condition, a leaf is instantiated.
@@ -301,7 +301,7 @@ Condition leaves have two responsibilities:
> Within an `ByEntityCondition`, the triggering entity is accessed via the field `values.triggeringEntity`.
### Actions
#### Actions
In general actions are very similar to conditions.
To explain the differences, a fictitious action shall be used, that follows the fundamental leaf structure shown in Figure 4:
@@ -341,3 +341,15 @@ Action leaves have two responsibilities:
**✍️ Principle**
> Within actions interacting with triggering entities, these entities are accessed via the field `values.entities`.
## Logging and error handling
The OpenScenarioEngine uses the log framework provided by the MantleAPI: https://gitlab.eclipse.org/eclipse/openpass/mantle-api/-/blob/master/include/MantleAPI/Common/i_logger.h
It consists of an ILogger interface class, which is passed to the OpenScenarioEngine on construction and therefore can be implemented outside of the OpenScenarioEngine. The OpenScenarioEngine forwards all log messages to the implementation of ILogger. The implementation of the ILogger interface class can then forward log messages of the OpenScenarioEngine to own logging implementations of a simulator or test framework.
The different log levels defined in the [MantleAPI](https://gitlab.eclipse.org/eclipse/openpass/mantle-api/-/blob/master/include/MantleAPI/Common/i_logger.h#L21) are used by the OpenScenarioEngine in the following way:
- the logs of the OpenScenario API while reading / parsing and validating the scenario are forwarded with the same log levels (e.g. **warning** when deprecated elements are used, **error** when scenario does not validate against schema) together with a summary of the found warnings and errors
- for the use-case of scenario execution the OpenScenarioEngine additionally stop execution by **throwing a runtime error**, if there were errors during the parsing and validation of the scenario
- for the use-case of only scenario validation no runtime error is thrown and it's left to the caller of the validation method how to proceed
- if features are used in a scenario which are not yet supported by the OpenScenarioEngine, then an **error** is logged and the respective feature is not executed
- if scenarios contain semantically wrong information the OpenScenarioEngine can currently only detect this upon execution of the feature and therefore also stops the execution by **throwing a runtime error**. In the future semantic checks could also partially be implemented in the OpenScenario API (parser & validator), so semantic errors in scenarios could also be detected in the "validation only" use-case
Loading