..
  *******************************************************************************
  Copyright (c) 2021 in-tech GmbH

  This program and the accompanying materials are made available under the
  terms of the Eclipse Public License 2.0 which is available at
  http://www.eclipse.org/legal/epl-2.0.

  SPDX-License-Identifier: EPL-2.0
  *******************************************************************************

.. _systemconfigblueprint:

SystemConfigBlueprint
=====================

This file contains the possible agent modules and channels of a dynamically generated agent. The content of this file should only be adjusted by experienced users with knowledge of the simulation architecture. The SystemConfigBlueprint is a special SystemConfig and has the same schema. Only the system with id 0 is used for generating dynamic agents.
If the simulation uses only statically configured agents (AgentProfile Type attribute is "Static"), this file isn't required.

.. _systemconfigblueprint_agentComponents:

AgentComponents
---------------
All components are listed here. An agent consists of a subset of this components.

.. table::
   :class: tight-table

   =========== ===============================================================================
   Attribute   Description
   =========== ===============================================================================
   Id          Used as key by the simulation to find the component
   Priority    The module with the highest priority value gets executed first by the scheduler
   Offset      Delay for the trigger method of each component in ms
   Cycle       Interval in which the component gets triggered by the scheduler in ms
   Response    Delay for the UpdateOutput method of each component in ms
   Library     Library name of this component
   Parameters  Parameters used by the component
   =========== ===============================================================================

Example:
This example describes the Sensor_Driver module.

.. literalinclude:: /../../../tuev/sim/contrib/examples/Common/systemConfigBlueprint.xml
   :language: xml
   :dedent: 12
   :lines: 28-38

.. _systemconfigblueprint_priorities:

Priorities
----------

Please refer to the :ref:`Components and channel communication diagram <component_channel_communication>` for assignment of a proper priority.
Based on the signal flow, input relevant components like sensors need to be executed first. They provide data for consuming components (algorithms) like ADAS and drivers.
Data is then handled by algorithms like Algorithm_Lateral.
Output-relevant modules like dynamics and actions are executed last.

Prioritizer can be applied on different levels depending on the modules/data they need to handle levels as following can be defined:

- Level 1 describes data produced by ADAS and drivers
- Level 2 describes data output by vehicle dynamic controllers
- Level 3 describes data delivered by dynamics

Priorities can be grouped (coarse) as following:
Highest number indicates highest priority.

.. table::
   :class: tight-table

   =========================== ===========
   Scope                       Range
   =========================== ===========
   Parameters                  500
   OpenScenarioActions         400
   Sensor                      350...399
   Event                       330
   DriverMode                  310
   ADAS                        250...299
   ComponentController         200
   Prioritizer (Lvl. 1)        150...199
   VehicleDynamicsControllers  100...149
   Prioritizer (Lvl. 2)        75...99
   Dynamics                    50...74
   Prioritizer (Lvl. 3)        25...49
   Updater                     0...24
   =========================== ===========

The table below can be used as orientation when a new module is introduced.

.. table::
   :class: tight-table

   ========================================= ======================================= ========= =========================== =======================================================================================================================
   Name                                      Library                                 Priority  Scope                       Note
   ========================================= ======================================= ========= =========================== =======================================================================================================================
   ParametersAgentModules                    ParametersAgent                         500       Parameters                  Sets all init-data and is updated cyclically
   OpenScenarioActions                       OpenScenarioActions                     400       ADAS                        Reads events from OpenScenario Actions and forwards them to other components
   SensorObjectDetector                      Sensor_OSI                              398       Sensor                      Gets instantiated multiple times (one time per sensor)
   SensorAggregation                         SensorAggregation_OSI                   351       Sensor
   SensorFusionErrorless                     SensorFusionErrorless_OSI               350       Sensor
   AlgorithmAgentFollowingDriverModel        AlgorithmAgentFollowingDriverModel      310       DriverModels
   AEB                                       AlgorithmAutonomousEmergencyBraking     250       ADAS
   FMU1                                      AlgorithmFmuWrapper                     250       ADAS
   FMU2                                      AlgorithmFmuWrapper                     250       ADAS
   FMU3                                      AlgorithmFmuWrapper                     250       ADAS
   ComponentController                       ComponentController                     200       ADAS                        Manages vehicle component states with regard to other vehicle component states and conditions and in response to events.
   PrioritizerLaterDriver                    SignalPrioritizer                       150       Prioritizer
   PrioritizerAccelerationDriver             SignalPrioritizer                       150       Prioritizer
   PrioritizerTurningIndicator               SignalPrioritizer                       150       Prioritizer
   PrioritizerSteeringVehicleComponents      SignalPrioritizer                       150       Prioritizer
   PrioritizerAccelerationVehicleComponents  SignalPrioritizer                       150       Prioritizer
   LimiterAccelerationVehicleComponents      LimiterAccelerationVehicleComponents    120       VehicleDynamicsControllers
   AlgorithmLateralDriver                    AlgorithmLateralDriver                  100       VehicleDynamicsControllers
   AlgorithmLongitudinalVehicleComponents    AlgorithmLongitudinalVehicleComponents  100       VehicleDynamicsControllers
   AlgorithmLongitudinalDriver               AlgorithmLongitudinalDriver             100       VehicleDynamicsControllers
   PrioritizerSteering                       SignalPrioritizer                       75        Prioritizer
   PrioritizerLongitudinal                   SignalPrioritizer                       75        Prioritizer
   DynamicsCollision                         DynamicsCollision                       50        Dynamics
   DynamicsRegularDriving                    DynamicsRegularDriving                  50        Dynamics
   DynamicsTrajectoryFollower                DynamicsTrajectoryFollower              50        Dynamics
   PrioritizerDynamics                       SignalPrioritizer                       25        Prioritizer
   SensorRecordStateModule                   SensorRecordState                       2         Updater                     Since values are "frozen" for current time step, logging can be placed anywhere
   ActionLongitudinalDriverModules           ActionLongitudinalDriver                3         Updater                     Will be expanded to ActionPrimary DriverTasks
   ActionSecondaryDriverTasksModules         ActionSecondaryDriverTasks              3         Updater
   AgentUpdater                              AgentUpdater                            1         Updater
   ========================================= ======================================= ========= =========================== =======================================================================================================================

.. _systemconfigblueprint_channelids:

Channel-Ids
-----------

Channels allow components to communicate with each other.
The signal flow is set explicitly via a channel-Id of 4 digits (see also :ref:`Components and channels communication diagram <component_channel_communication>`).

The first two numbers define the sending module (XX 00).
The other two digits define the type of signal that is sent (00 XX).

Signals as well as modules can be grouped to allow explicit numbering (see tables below).

Channel-Ids between Sensor and SensorFusion are an exception to this rule. For sensor/sensor fusion communication channel-ids are 9900 + x (incremented for every new sensor)

Example:
PrioritizerAccelerationDriver -> AlgorithmLongitudinalDriver with signal of type AccelerationSignal: 1813.


**Ids for Modules (first two digits)**


Index range for module groups:

.. table::
   :class: tight-table

   ================= ==========
   Group             Id
   ================= ==========
   Dynamics          1...10
   Algorithm         11...30
   DriverTasks       31...40
   Driver            41...50
   VehicleComponent  51...70
   Special           81...89
   Sensor            91...99
   ================= ==========

With corresponding defined indices:

.. table::
   :class: tight-table

   ========================================= ================= =====
   Module                                    Group             Id
   ========================================= ================= =====
   AgentUpdater                              Dynamics          1
   Dynamics_TrajectoryFollower               Dynamics          2
   Dynamics_RegularDriving                   Dynamics          3
   Dynamics_Collision                        Dynamics          4
   PrioritizerDynamics                       Dynamics          5
   Algorithm_LongitudinalVehicleComponent    Algorithm         11
   Algorithm_LongitudinalAfdm                Algorithm         12
   Algorithm_SteeringVehicleComponent        Algorithm         14
   Algorithm_LateralVehicleAfdm              Algorithm         15
   LimiterAccelerationVehicleComponents      Algorithm         17
   PrioritizerLongitudinal                   Algorithm         21
   PrioritizerSteering                       Algorithm         22
   PrioritizerAccelerationVehicleComponents  Algorithm         23
   PrioritizerSteeringVehicleComponents      Algorithm         24
   Action_LongitudinalDriver                 DriverTasks       31
   Action_SecondaryDriverTasks               DriverTasks       32
   PrioritizerTurningIndicator               DriverTasks       33
   AlgorithmAgentFollowingDriverModel        Driver            41
   AEB                                       VehicleComponent  52
   FMU1                                      VehicleComponent  71
   FMU2                                      VehicleComponent  72
   FMU3                                      VehicleComponent  73
   ComponentController                       Special           83
   OpenScenarioActions                       Special           84
   Parameter_Vehicle                         Sensor            92
   SensorAggregation                         Sensor            93
   SensorFusionErrorless                     Sensor            94
   Sensor_Driver                             Sensor            95
   SensorObjectDetector                      Sensor            98
   ========================================= ================= =====

**Ids for Signals (last two digits)**

Index range for signal groups:


.. table::
   :class: tight-table

   ==================== ==========
   Group                Id
   ==================== ==========
   Dynamics             1...10
   Algorithm            11...30
   OpenScenarioActions  61...70
   Special              71...80
   Sensor               81...90
   Parameters           91...99
   ==================== ==========

With corresponding defined indices:

.. table::
   :class: tight-table

   ======================================= ==================== =====
   Signal                                  Group                Id
   ======================================= ==================== =====
   Dynamics                                Dynamics             01
   Longitudinal                            Algorithm            11
   Steering                                Algorithm            12
   Acceleration                            Algorithm            13
   Lateral                                 Algorithm            14
   SecondaryDriverTasks                    Algorithm            19
   Trajectory                              OpenScenarioActions  71
   AcquireGlobalPosition                   OpenScenarioActions  62
   CustomParameters (CustomCommandAction)  OpenScenarioActions  63
   SensorDriver                            Sensor               81
   SensorData                              Sensor               90
   ParametersVehicle                       Parameters           92
   ======================================= ==================== =====

.. _systemconfigblueprint_parameters:

Parameters
----------

For more information on the type of parameters (especially stochastic distributions), please refer to the :ref:`ProfilesGroup section <profilescatalog_profilegroups>`.

**Important Note:** The syntax for defining parameters in the SystemConfigBlueprint file differs from the ProfilesCatalog syntax.
See the following example:

.. code-block:: xml

   <parameters>
       <parameter>
           <id>StringParameter</id>
           <type>string</type>
           <unit/>
           <value>Lorem ipsum</value>
       </parameter>
       <parameter>
           <id>RandomParameter</id>
           <type>normalDistribution</type>
           <unit/>
           <value>
               <mean>15.0</mean>
               <sd>2.5</sd>
               <min>10.0</min>
               <max>20.0</max>
           </value>
       </parameter>
   </parameters>