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.
SimulationMode	int	0	Bitmask mode as documented in the README.
SimulationModeParameter	double	0	Auxiliary parameter consumed by selected modes.
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.

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:

libsumo\bin located next to TrafficLayer.exe.
CommonLib\libsumo\bin relative to the executable, walking up to four parent directories (covers TrafficLayer/x64/<Config> and build).
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:

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	Update rate (seconds) for publishing traffic to CarMaker.
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	inferred or `"127.0.0.1"`	Client binding IP for CARLA streaming. Inferred from subscription if single vehicle.
CarlaClientPort	int	inferred or 2001	Client binding port for CARLA streaming. Inferred from subscription if single vehicle.
CarlaMapName	string	`"Town01"`	Desired CARLA map name.
CenteredViewId	string	`"ego"`	Actor id used for camera centering.
TrafficRefreshRate	double	0.1	CARLA update period (seconds).
InterestedIds	string list	`["ego"]`	Vehicle IDs that receive mirrored CARLA updates. Should be subset of VehicleSubscription.

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:

# 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

Copy an existing configuration (for example tests/Python/SimpleEchoClient/config.yaml or tests/SumoCarla/test_scenarios/Town01_with_ego_type_as_blueprint/defaultConfig.yaml).
Adjust the sections described above.
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.
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.