Fahrsimulator_MSY2526_UX/docs/CONFIGURATION.md

Configuration

Configuration is loaded from classpath properties files in src/main/resources/config:

• application.properties for runtime behavior
• logger.properties for logging behavior

AppConfigValidator performs startup validation and fails fast on invalid settings.

application.properties

Core runtime keys

Key	Required	Description
mqtt.broker.url	yes	MQTT broker URI (tcp://..., ssl://..., ws://..., wss://...)
mqtt.client.id	yes	MQTT client ID
mqtt.topic	yes	MQTT topic to subscribe to
streaming.url	yes	URL for embedded streaming view (http/https)
animation.output.path	yes	Target path for animation JSON output
app.mode	no	Generic runtime mode flag

Optional simulator keys (mqtt_sim.*)

These become required/validated when mqtt_sim.enabled=true.

Key	Description
mqtt_sim.enabled	Enable Python simulator startup
python.path	Python executable path
mqtt_sim.script	Simulator script path
mqtt_sim.broker	Broker host passed to simulator
mqtt_sim.port	Broker port passed to simulator
mqtt_sim.topic	Simulator publish topic
mqtt_sim.qos	QoS (0-2)
mqtt_sim.interval_seconds	Publish interval in seconds
mqtt_sim.username / mqtt_sim.password	Optional broker auth
mqtt_sim.start_id	Optional starting _id
mqtt_sim.client_id	Optional simulator client id
mqtt_sim.log_file	Optional simulator log path

Optional Unreal keys (unreal.*)

These become required/validated when unreal.enabled=true.

Key	Description
unreal.enabled	Enable Unreal startup flow
unreal.executable	PowerShell launcher script path
unreal.signalling_server.script	Signalling server BAT path
unreal.target.executable	Unreal executable path passed to script
unreal.target.working_dir	Unreal working directory passed to script
unreal.target.args	Unreal launch arguments
unreal.pid.dir	Optional PID output directory for script
unreal.pid.file	PID file used for shutdown cleanup
unreal.signalling.pid.file	Signalling PID file used for cleanup
unreal.startup.delay.seconds	Delay before Unreal launch in script

Process startup health checks

Key	Description	Default
process.startup.healthcheck.enabled	Enable startup health checks for managed processes	true
process.startup.healthcheck.timeout.millis	Health-check timeout	10000
process.startup.healthcheck.poll.millis	Poll interval	250

logger.properties

Key	Description	Typical value
logger.level	Minimum log level	DEBUG
logger.file.enabled	Toggle file logging	true
logger.file	Log file path	logs/application.log
logger.max.size.mb	Rotation threshold in MB	10

Validation Behavior

The validator checks:

• URI format and scheme for MQTT broker URL
• non-empty required keys
• numeric ranges (port, QoS, timeout/poll values, delays)
• file/directory existence for enabled integrations
• optional quote handling and invalid path syntax

Any validation errors are grouped and thrown as a single startup exception.

Script Environment Mapping

mqtt_simulator.py

App config keys are forwarded as environment variables:

• mqtt_sim.broker -> MQTT_SIM_BROKER
• mqtt_sim.port -> MQTT_SIM_PORT
• mqtt_sim.topic -> MQTT_SIM_TOPIC
• mqtt_sim.username -> MQTT_SIM_USERNAME
• mqtt_sim.password -> MQTT_SIM_PASSWORD
• mqtt_sim.qos -> MQTT_SIM_QOS
• mqtt_sim.interval_seconds -> MQTT_SIM_INTERVAL_SECONDS
• mqtt_sim.start_id -> MQTT_SIM_START_ID
• mqtt_sim.client_id -> MQTT_SIM_CLIENT_ID
• mqtt_sim.log_file -> MQTT_SIM_LOG_FILE

start_avatar.ps1

App config keys are forwarded as environment variables:

• unreal.target.executable -> VGA_UE_EXE
• unreal.target.args -> VGA_UE_ARGS
• unreal.target.working_dir -> VGA_UE_WORKDIR
• unreal.signalling_server.script -> VGA_SIGNALLING_BAT
• unreal.startup.delay.seconds -> VGA_SIGNALLING_DELAY
• unreal.pid.dir (or PID parent fallback) -> VGA_PID_DIR

Practical Recommendation

For first-time local runs, keep:

mqtt_sim.enabled=false
unreal.enabled=false

Then enable integrations incrementally after validating local paths and dependencies.