126 lines
4.4 KiB
Markdown
126 lines
4.4 KiB
Markdown
# 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:
|
|
|
|
```properties
|
|
mqtt_sim.enabled=false
|
|
unreal.enabled=false
|
|
```
|
|
|
|
Then enable integrations incrementally after validating local paths and dependencies.
|