# Configuration Reference

The Real-Sim interface is configured through YAML files (for example `config.yaml`). Each top-level section maps directly to structures parsed in `CommonLib/ConfigHelper`. This document describes the supported keys, their defaults, and any special behaviour such as derived paths.

> **Path handling.** Unless stated otherwise, relative paths are resolved against the directory that contains the config file. The interface also accepts absolute paths.

## SimulationSetup

| Key | Type | Default | Notes |
| --- | --- | --- | --- |
| EnableRealSim | bool | true | Master switch for the interface. |
| EnableVerboseLog | bool | false | Enables detailed logging in TrafficLayer and companion tools. |
| SimulationEndTime | double | 90000 | End time (seconds). Large default keeps the session open until external shutdown. |
| EnableExternalDynamics | bool | false | When true, SUMO speed updates use `setPreviousSpeed` so acceleration limits are respected. |
| VehicleMessageField | string list | All supported fields | Controls which vehicle fields are exchanged. Provide a subset if bandwidth is a concern. Must include `id`, `speed`, and one of `speedDesired` or `accelerationDesired`. |
| SelectedTrafficSimulator | string | `"SUMO"` | Use `"SUMO"` or `"VISSIM"`. |
| TrafficSimulatorIP | string | `"127.0.0.1"` | Host for TraCI/VISSIM connections. |
| TrafficSimulatorPort | int | 1337 | Port for the selected simulator. |
| WarmUpUntilEgoEntry | bool | false | Run the traffic simulator with the FIXS boundary closed until the first subscribed ego is in the network. SUMO only. |
| WarmUpTime | double | 0 | Run the traffic simulator with the FIXS boundary closed until this **absolute** simulation time, in one batch step. SUMO only. |
| TrafficLayerIP | string | inferred | Defaults to the first vehicle subscription IP if not provided. |
| TrafficLayerPort | int | inferred | Defaults to the first vehicle subscription port if not provided. |

### Warm-up

XIL testing usually cares about the simulation only from the moment the ego is on the
road. A warm-up runs the traffic simulator up to that moment with the **FIXS boundary
closed**: no message reaches any client, and no client is accepted yet, so CARLA's map
load and CarMaker's start-up overlap the warm-up instead of queueing ahead of it. The
sockets are bound and listening the whole time, so a client's `connect()` succeeds
exactly as it always did — it simply gets no data until the warm-up ends.

Pick the trigger by who knows the entry time:

- `WarmUpUntilEgoEntry: true` — the warm-up ends when the first ego appears. Use this
  when a controller inserts the ego: the controller keeps owning the entry time and no
  number is duplicated in this file. The ids watched are the **union** of the by-id
  vehicle subscriptions in `ApplicationSetup` and `XilSetup`; with several egos the
  *first* to arrive ends the warm-up, because an ego on the road while the boundary is
  still closed would be driven by the traffic model rather than by its XIL.
- `WarmUpTime: <absolute simulation time>` — the warm-up ends at that time, reached in a
  single batch step. Use this when nothing else inserts the ego, i.e. the CarMaker path
  where TrafficLayer injects it and has to be told when. Note it is absolute simulation
  time, not a duration: a scenario that begins at 28800 warms up to, say, 28985.

The two are mutually exclusive: a batch step observes nothing on the way, so it cannot
also watch for an ego. Setting both warns and uses ego entry. Setting neither means no
warm-up — the interface syncs from the first step.

Both are SUMO-only today; TrafficLayer does not own the VISSIM clock (the DriverModel
DLL does), and a VISSIM config that sets either key is rejected at startup rather than
silently ignored.

> **Renamed in v0.9.0 (#86).** `SimulationMode` and `SimulationModeParameter` are gone —
> the "bitfield" never behaved like one (`5` was a duplicate of `4`, and `3`/`6`/`7`
> silently meant `0`). `SimulationMode: 1` becomes `WarmUpUntilEgoEntry: true`,
> `SimulationMode: 4` + `SimulationModeParameter: T` becomes `WarmUpTime: T`, and
> `SimulationMode: 0` means removing the key. No config in either FIXS or
> FIXS_Applications set them, so they are simply gone: an old config that still does is
> ignored like any other unknown key, and runs with no warm-up.

## SumoSetup

| Key | Type | Default | Notes |
| --- | --- | --- | --- |
| SpeedMode | int | 0 | Passed to `SUMO_TRACI_NAMESPACE::Vehicle::setSpeedMode`. Common values: 0 (default safety), 31 (default mode), 32 (all checks off). |
| ExecutionOrder | int | 1 | Order passed to `Simulation::setOrder`. |
| EnableAutoLaunch | bool | false | When true, TrafficLayer starts SUMO automatically; otherwise it expects a running instance. |
| SumoConfigFile | string | `""` | Path to `.sumocfg` used when auto-launching. Relative paths resolved against config file directory. |
| NumClients | int | 1 | Number of SUMO clients negotiated during auto-launch. |
| RuntimeLibraryPath | string | `""` | Optional override for the SUMO runtime directory (DLL/.so path). |

When `RuntimeLibraryPath` is omitted the executable searches for the libsumo runtime in the following order:

1. `libsumo\bin` located next to `TrafficLayer.exe`.
2. `CommonLib\libsumo\bin` relative to the executable, walking up to four parent directories (covers `TrafficLayer/x64/<Config>` and `build`).
3. `CommonLib\libsumo\bin` relative to the current working directory.

On Windows the resolved folder is supplied to `SetDllDirectory`. On Linux the folder is prepended to `LD_LIBRARY_PATH`. Leave the field commented out unless you intentionally repackage the SUMO binaries elsewhere.

## ApplicationSetup

| Key | Type | Default | Notes |
| --- | --- | --- | --- |
| EnableApplicationLayer | bool | false | Enables the application message bus. |
| ApplicationPort | int list | [] | Ports that receive messages (alternative to subscription-based port definition). |
| VehicleSubscription | list of subscription blocks | [] | Each block has `type`, an `attribute` map, `ip`, and `port`. |
| DetectorSubscription | list of subscription blocks | [] | Detector data subscriptions. |
| SignalSubscription | list of subscription blocks | [] | Traffic signal subscriptions. |

### Subscription Types

**VehicleSubscription** supports the following types:
- `ego`: Subscribe by vehicle ID. Attributes: `id` (list), `radius` (list), or `all` (bool).
- `link`: Subscribe by edge/link ID. Attributes: `id` (list).
- `point`: Subscribe by geographic point. Attributes: `x`, `y`, `z`, `radius` (all lists).
- `vehicleType`: Subscribe by vehicle type. Attributes: `id` (list), `radius` (list).

**SignalSubscription** supports:
- `intersection`: Subscribe by signal controller. Attributes: `name` or `id` (list).

**DetectorSubscription** supports:
- `detector`: Subscribe by detector pattern. Attributes: `pattern`, `name`, or `id` (list).

Example subscription block:

```yaml
VehicleSubscription:
-   type: ego
    attribute: {id: ['ego'], radius: [0]}
    ip: ['127.0.0.1']
    port: [2444]
```

## XilSetup

| Key | Type | Default | Notes |
| --- | --- | --- | --- |
| EnableXil | bool | false | Enables the co-simulation bridge. |
| AsServer | bool | false | When true, TrafficLayer listens for XIL connections; otherwise acts as client. |
| VehicleSubscription | list | [] | Same schema as the application-layer subscriptions. |
| SignalSubscription | list | [] | Signal subscriptions for XIL. |
| DetectorSubscription | list | [] | Detector subscriptions for XIL. |

When the application layer is disabled but XIL is enabled, the interface automatically reuses the XIL vehicle subscriptions to seed outbound traffic.

## CarMakerSetup

| Key | Type | Default | Notes |
| --- | --- | --- | --- |
| EnableCosimulation | bool | false | Turn on integration with IPG CarMaker. |
| EnableEgoSimulink | bool | false | When true, ego state comes from Simulink; when false, from User.cpp. |
| CarMakerIP | string | inferred or `"127.0.0.1"` | Connection IP for CarMaker. Inferred from subscription if single vehicle subscribed. |
| CarMakerPort | int | inferred or 7331 | Connection port for CarMaker. Inferred from subscription if single vehicle subscribed. |
| TrafficRefreshRate | double | 0.001 | How often traffic poses are re-applied to CarMaker, i.e. CarMaker's own step. **Not** the FIXS exchange period, which is a fixed 0.1 s — the core interpolates each sample (position, heading, grade) across the sub-steps in between, so 0.001 means smooth 1 kHz traffic motion off a 10 Hz feed. |
| EgoId | string | inferred or `"egoCm"` | Identifier for the ego vehicle in SUMO. Inferred from subscription if single vehicle subscribed. |
| EgoType | string | `""` | SUMO vehicle type for ego. Empty uses SUMO default. |
| SynchronizeTrafficSignal | bool | false | If enabled, subscribes to all signal controllers for synchronization. |
| TrafficSignalPort | int | 2444 or inferred | Port for signal data. Inferred from SignalSubscription if available. |

## CarlaSetup

| Key | Type | Default | Notes |
| --- | --- | --- | --- |
| EnableVerboseLog | bool | false | Verbose logging for the CARLA bridge. |
| EnableCosimulation | bool | false | Enables CARLA co-simulation. |
| EnableExternalControl | bool | false | When true, SUMO vehicles updated from CARLA state; when false, CARLA only visualizes. |
| UseVehicleTypeAsBlueprint | bool | false | Interpret SUMO vehicle types as CARLA blueprints. |
| CarlaServerIP | string | `"127.0.0.1"` | CARLA server endpoint IP. |
| CarlaServerPort | int | 2000 | CARLA server endpoint port. |
| CarlaClientIP | string | `"127.0.0.1"` | **Not CARLA.** Where VirCarlaEnv reaches **TrafficLayer** — `mainVirCarla` assigns it to `core.trafficLayerIP_`. Keep it local even when the CARLA server is on another machine: TrafficLayer runs beside VirCarlaEnv, not beside CARLA. |
| CarlaClientPort | int | 430 | TrafficLayer's bridge port for this client (`core.vehDataPort_`); pair it with `ApplicationSetup.VehicleSubscription[].port`. Nothing to do with CARLA's streaming port. |
| CarlaMapName | string | `"Town01"` | Desired CARLA map name. |
| CenteredViewId | string | `"ego"` | Actor id used for camera centering. |
| CarlaTimeStep | double | 0 (= the FIXS feed) | CARLA world step, i.e. `fixed_delta_seconds`. Must be the FIXS feed period or an exact divisor of it (0.1 / 0.05 / 0.025 / 0.02 / 0.01): the exchange boundary is tested on the feed grid, so a tick that does not divide it never lands on one and the bridge would exchange nothing. Finer than the feed makes the bridge interpolate traffic — position **and** heading — across the sub-steps, exactly as the CarMaker host does at 0.001 s. |
| TrafficRefreshRate | double | 0 (= every tick) | How often traffic poses are **re-applied**. Same meaning as the CarMakerSetup key above; **not** the feed period. Must be ≥ `CarlaTimeStep` and have a whole reciprocal. Coarser than the tick = fewer `ApplyBatch` calls on a heavy scene while physics and sensors still run at the tick rate. |
| InterestedIds | string list | `["ego"]` | Vehicle IDs that receive mirrored CARLA updates. Should be subset of VehicleSubscription. |

> **The FIXS feed period is not configurable.** It is 0.1 s (`fixs::kFeedPeriodS` in
> `CommonLib/FixsProtocol.h`): every VirEnvCore host tests its send/recv boundary
> against that grid on its own sim clock, and TrafficLayer steps the traffic simulator
> exactly once per exchange. The traffic simulator's step length therefore **is** that
> value — `run_cosim` passes `--step-length 0.1` to both bridges rather than offering
> it as a choice. Give SUMO a different step and the two clocks run at different rates:
> at 0.05 s, CARLA advances two ticks per SUMO step, so every sample is drawn twice and
> the scene plays back at half speed.
>
> Before #219, `CarlaSetup.TrafficRefreshRate` doubled as the feed period *and* as the
> tick whenever `CarlaTimeStep` was unset — so setting it to 0.05 silently turned
> interpolation off. They are separate keys now and neither falls back to the other. An
> older yaml carrying a feed-period value in it is migrated (generated yamls) or
> reported (app-owned ones) by `run_cosim`.

## Vehicle Message Field Specifications

This is the full list of available vehicle message fields that can be specified in `VehicleMessageField`:

| Field | Type | Description |
| --- | --- | --- |
| id | string | Vehicle ID (VISSIM integer converted to string, e.g., 8 → "8"). **Required.** |
| type | string | Vehicle type (VISSIM integer converted to string, e.g., 100 → "100") |
| vehicleClass | string | Vehicle class (car, truck in VISSIM; private, passenger, truck in SUMO) |
| speed | float | Current speed (m/s). **Required.** |
| acceleration | float | Current acceleration (m/s²) |
| positionX | float | X position (m) in simulator coordinates |
| positionY | float | Y position (m) in simulator coordinates |
| positionZ | float | Z position (m) in simulator coordinates |
| heading | float | Heading in degrees (north = 0°, clockwise, east = 90°) |
| color | uint32 | Combined RGBA bits (8-bit each, leftmost = R) |
| linkId | string | Link ID (VISSIM integer converted to string) |
| laneId | int32 | Lane ID (rightmost lane = 1, consistent with VISSIM) |
| distanceTravel | float | Cumulative driving distance since entering network (m) |
| speedDesired | float | Desired speed (m/s). **Required if accelerationDesired not specified.** |
| accelerationDesired | float | Desired acceleration (m/s²). **Required if speedDesired not specified.** |
| hasPrecedingVehicle | int8 | 1 = has preceding vehicle, 0 = none |
| precedingVehicleId | string | ID of preceding vehicle |
| precedingVehicleDistance | float | Distance to preceding vehicle (m), -1 if none |
| precedingVehicleSpeed | float | Speed of preceding vehicle (m/s), -1 if none |
| signalLightId | string | Signal controller ID |
| signalLightHeadId | int32 | Signal head index |
| signalLightDistance | float | Distance to next signal (m), -1 if none |
| signalLightColor | int8 | 1=red, 2=amber, 3=green, 4=red/amber, 5=amber flashing, 6=off, 0=other, -1=none |
| speedLimit | float | Current speed limit (m/s), -1 if none |
| speedLimitNext | float | Next speed limit ahead (m/s), -1 if none |
| speedLimitChangeDistance | float | Distance to speed limit change (m), -1 if none |
| linkIdNext | string | Next link ID |
| grade | float | Road grade angle (radians), positive = uphill |
| activeLaneChange | int8 | 1 = left, -1 = right, 0 = stay |
| lightIndicators | - | Turn signal indicators |
| length | float | Vehicle length (m) |
| width | float | Vehicle width (m) |
| height | float | Vehicle height (m) |

## Example Configuration

Below is a comprehensive example configuration demonstrating SimulationSetup, SumoSetup, ApplicationSetup, XilSetup, CarMakerSetup, and CarlaSetup:

```yaml
# NOTE: YAML files do not allow tabs. use 2 or 4 spaces for indentation
#
# Reserved TCP/IP port by RealSim: 1337, 1338
# DO NOT use these ports when setting up clients to RealSim
#
# TCP/IP connection port config
#               1337/1338                 ApplicationPort                                   XilPort
#   VISSIM/SUMO ---------> Traffic Layer -----------------> Application Layer (controller) -----------> XIL Clients

# =============================================================================
# Global Simulation Setup
# =============================================================================
SimulationSetup:
    # Master Switch to turn on/off RealSim interface
    EnableRealSim: true

    # Whether or not to save verbose log during the simulation
    EnableVerboseLog: false

    # Simulation end time in seconds
    SimulationEndTime: 300

    # Specify which traffic simulator: 'SUMO' or 'VISSIM'
    SelectedTrafficSimulator: 'SUMO'

    # Traffic simulator connection parameters
    TrafficSimulatorIP: "127.0.0.1"
    TrafficSimulatorPort: 1337

    # Vehicle message fields to exchange
    # Must include: id, speed, and one of speedDesired or accelerationDesired
    VehicleMessageField: [id, type, vehicleClass, speed, acceleration, positionX,
        positionY, positionZ, heading, color, linkId, laneId, distanceTravel,
        speedDesired, grade, length, width, height]

    # Use setPreviousSpeed instead of setSpeed to respect SUMO's acceleration dynamics
    EnableExternalDynamics: true

# =============================================================================
# SUMO Setup
# =============================================================================
SumoSetup:
    # Speed mode bitmask: 0 = default safety, 31 = default mode, 32 = all checks off
    SpeedMode: 32

    # Auto-launch SUMO directly from TrafficLayer
    EnableAutoLaunch: true

    # Path to SUMO configuration file (.sumocfg)
    # Relative paths are resolved against the config file directory
    SumoConfigFile: "./network.sumocfg"

    # Number of SUMO client instances
    NumClients: 1

    # Optional override for SUMO runtime library directory
    # RuntimeLibraryPath: '../../../CommonLib/libsumo/bin'

# =============================================================================
# Application Layer Setup
# =============================================================================
ApplicationSetup:
    # Enable application layer to receive vehicle data
    EnableApplicationLayer: true

    # Vehicle subscriptions
    VehicleSubscription:
    # Subscribe to ego vehicle with 50m radius for surrounding vehicles
    -   type: ego
        attribute: {id: ['ego'], radius: [50]}
        ip: ['127.0.0.1']
        port: [440]

    # Subscribe to vehicles by geographic point
    -   type: point
        attribute: {radius: [200], x: [100.0], y: [500.0], z: [0]}
        ip: ['127.0.0.1']
        port: [441]

    # Signal subscriptions for traffic light data
    SignalSubscription:
    -   type: intersection
        attribute: {name: ['signal_1', 'signal_2', 'signal_3']}
        ip: ['127.0.0.1']
        port: [440]

    # Detector subscriptions
    DetectorSubscription:
    -   type: detector
        attribute: {pattern: ['det_*']}
        ip: ['127.0.0.1']
        port: [442]

# =============================================================================
# XIL Setup (Simulink / Hardware-in-the-Loop)
# =============================================================================
XilSetup:
    # Enable/disable XIL
    EnableXil: true

    # Set to true if TrafficLayer should act as server
    AsServer: false

    # Vehicle subscription for XIL client
    # Typically ego vehicle with radius 0 (only ego data sent to XIL)
    VehicleSubscription:
    -   type: ego
        attribute: {id: ['ego'], radius: [0]}
        ip: ['127.0.0.1']
        port: [420]

    # Signal subscription for XIL
    SignalSubscription:
    -   type: intersection
        attribute: {name: ['signal_1']}
        ip: ['127.0.0.1']
        port: [420]

# =============================================================================
# CarMaker Setup (IPG CarMaker Co-simulation)
# =============================================================================
CarMakerSetup:
    # Enable CarMaker co-simulation
    EnableCosimulation: true

    # If true, ego state comes from Simulink; if false, from User.cpp
    EnableEgoSimulink: true

    # CarMaker connection settings
    CarMakerIP: 127.0.0.1
    CarMakerPort: 7890

    # Traffic objects update rate (seconds)
    TrafficRefreshRate: 0.001

    # Ego vehicle settings
    EgoId: ego
    EgoType: passenger

    # Synchronize traffic signals with CarMaker
    SynchronizeTrafficSignal: true
    TrafficSignalPort: 2444

# =============================================================================
# CARLA Setup (Virtual Environment Co-simulation)
# =============================================================================
CarlaSetup:
    # Enable verbose logging for CARLA bridge
    EnableVerboseLog: false

    # Enable CARLA co-simulation
    EnableCosimulation: true

    # If true, SUMO vehicles updated from CARLA state
    # If false, CARLA only visualizes SUMO vehicles
    EnableExternalControl: true

    # Use vehicle type as CARLA blueprint
    UseVehicleTypeAsBlueprint: true

    # CARLA server connection
    CarlaServerIP: 127.0.0.1
    CarlaServerPort: 2000

    # CARLA client binding
    CarlaClientIP: 127.0.0.1
    CarlaClientPort: 440

    # CARLA map name
    CarlaMapName: Town01

    # Traffic objects update rate (seconds)
    TrafficRefreshRate: 0.1

    # Vehicle IDs to mirror in CARLA (subset of VehicleSubscription)
    InterestedIds: ['ego']

    # Center camera view on this vehicle
    CenteredViewId: ego
```

## Updating the YAML

1. Copy an existing configuration (for example `tests/Python/SimpleEchoClient/config.yaml` or `tests/SumoCarla/test_scenarios/Town01_with_ego_type_as_blueprint/defaultConfig.yaml`).
2. Adjust the sections described above.
3. If SUMO auto-launch is enabled, ensure the `.sumocfg` path is valid and that either `RuntimeLibraryPath` is set or the default `CommonLib/libsumo/bin` directory remains beside the executable.
4. Keep indentation spaces (YAML does not support tabs).

For quick reference, see the inline comments in the test configuration files, which demonstrate various setup combinations.