180 lines
8.4 KiB
Markdown
180 lines
8.4 KiB
Markdown
# ADR 0017: Provider-neutral simulation and Unreal evaluation
|
|
|
|
## Status
|
|
|
|
Accepted for architecture on 2026-07-25. The provider contract is implemented
|
|
on the Polygon branch. Gazebo remains the accepted regression baseline. No
|
|
Unreal integration, Unreal runtime profile or choice between native Unreal,
|
|
CARLA and Project AirSim is accepted by this decision.
|
|
|
|
## Context
|
|
|
|
The first Polygon vertical proved that Mission Core can own a virtual Ackermann
|
|
run, display canonical ENU/FLU state in React, persist evidence and deliver
|
|
bounded virtual-only rover commands through PX4. That proof used one concrete
|
|
stack: Gazebo Harmonic, PX4 SITL, ROS 2 and Micro XRCE-DDS.
|
|
|
|
Treating that stack as the product architecture would make later work expensive:
|
|
|
|
- a realistic vehicle, road surface, terrain and sensor model may be easier to
|
|
build and inspect in Unreal;
|
|
- reconstructed Gaussian scenes are primarily visual evidence and do not by
|
|
themselves supply collision, friction, road or navigation geometry;
|
|
- native Unreal, CARLA and Project AirSim have different vehicle, sensor,
|
|
controller, platform and lifecycle assumptions;
|
|
- a browser cannot and should not execute the full physics/autopilot stack;
|
|
- replacing Gazebo must not replace Mission Core run identity, authority,
|
|
evidence, UI or evaluator contracts.
|
|
|
|
The choice is therefore not “Gazebo or Unreal for the whole product.” It is
|
|
which worker-side provider profile is appropriate for each qualification case.
|
|
|
|
## Decision
|
|
|
|
1. Mission Core remains simulation-provider neutral. A worker publishes an
|
|
exact `missioncore.simulation-provider-profile/v1` before it may be used by
|
|
the browser or gateway.
|
|
2. A provider profile declares logical providers, roles, capabilities,
|
|
authoritative simulation clock, supported canonical control profiles and
|
|
the fixed `map_enu`/`base_link_flu` boundary.
|
|
3. Provider roles are `world`, `physics`, `state`, `controller`, `transport`,
|
|
`sensor` and `traffic`. One process may implement several roles; several
|
|
processes may compose one profile.
|
|
4. Component pins and provider roles remain separate:
|
|
component pins prove exact software provenance, while provider descriptors
|
|
explain runtime responsibility and interoperability.
|
|
5. Worker status v2 exposes the configured provider profile separately from
|
|
currently active process IDs. `VehicleState` names its source provider.
|
|
Command acceptance v2 names the delivering controller provider and canonical
|
|
control profile.
|
|
6. The browser consumes canonical state and evidence. Unreal, Gazebo, PX4,
|
|
ROS 2 and their native windows remain outside React and run on registered
|
|
workers.
|
|
7. Gazebo/PX4 remains the frozen, comparatively cheap deterministic regression
|
|
profile until another profile passes the same lifecycle, clock, command,
|
|
safety and evidence gates.
|
|
8. Unreal is evaluated as a high-fidelity provider family. Native Unreal,
|
|
CARLA and Project AirSim are separate candidates and are not interchangeable
|
|
labels:
|
|
- native Unreal maximizes project control but requires Mission Core-owned
|
|
vehicle, sensor, clock and bridge work;
|
|
- CARLA is evaluated when road/traffic simulation and its supported vehicle
|
|
model fit the rover case;
|
|
- Project AirSim is evaluated only against its current supported vehicle,
|
|
PX4, ROS 2, platform and maintenance constraints.
|
|
9. A Gaussian scene may provide appearance and sensor-rendering context. Every
|
|
qualification world still needs separately versioned physical collision
|
|
meshes, road/drivable surfaces, materials/friction, semantic regions,
|
|
spawn/goal definitions and evaluator truth.
|
|
10. Unreal does not block S1 completion or the S2 Gazebo/Nav2 baseline. It
|
|
becomes most valuable in S3 virtual-sensor/perception work and S5
|
|
high-fidelity/digital-twin work. An earlier bounded adapter spike is allowed
|
|
because it reduces architectural risk.
|
|
11. PX4 remains a replaceable controller provider. An Unreal profile may use
|
|
PX4 through an admitted external-simulator boundary or may use a different
|
|
virtual controller, but each choice creates a distinct profile and cannot
|
|
inherit the other profile's evidence.
|
|
12. No real actuator authority is introduced. All current profiles remain
|
|
`virtual-only`.
|
|
|
|
## Fidelity ladder
|
|
|
|
| Level | Purpose | Initial provider |
|
|
| --- | --- | --- |
|
|
| L0 contract tests | Fast lifecycle, schema and safety regression | In-process fakes |
|
|
| L1 dynamics regression | Cheap repeated control/navigation qualification | Gazebo + PX4 SITL |
|
|
| L2 sensor/scene fidelity | Camera/LiDAR/perception and difficult visual worlds | Unreal candidate |
|
|
| L3 hardware/control integration | Controller-in-loop and HIL | Separate gated profile |
|
|
| L4 physical evidence | Shadow and later controlled field qualification | Vehicle Edge Agent |
|
|
|
|
A higher level does not replace lower-level regression. Evidence is comparable
|
|
only when scenario, provider profile, metric profile and reproducibility tier
|
|
allow it.
|
|
|
|
## Unreal evaluation gates
|
|
|
|
### U0 — selection spike
|
|
|
|
For native Unreal, CARLA and Project AirSim, record:
|
|
|
|
- supported rover/Ackermann dynamics and controllable wheel/suspension model;
|
|
- fixed-step clock, pause/step/reset and headless execution;
|
|
- external command/state bridge and PX4 compatibility;
|
|
- camera, depth, LiDAR, IMU, GNSS and ground-truth availability;
|
|
- collision/contact and semantic truth;
|
|
- Linux/Windows worker placement, GPU/VRAM/RAM and startup time;
|
|
- automation, packaging, licensing, upstream activity and version pinning;
|
|
- import path for existing Unreal assets and Gaussian reconstructions.
|
|
|
|
Exit: one candidate or native implementation is selected for a disposable U1
|
|
adapter. “Looks better” is not an exit criterion.
|
|
|
|
### U1 — canonical adapter proof
|
|
|
|
- publish one provider profile and authoritative fixed-step clock;
|
|
- launch/reset/stop through the Simulation Orchestrator;
|
|
- map a stock Ackermann pose to `VehicleState`;
|
|
- accept `rover-speed-steering/v1` under the existing TTL/watchdog boundary;
|
|
- prove straight, turn, reverse, command expiry and clean zero-residue stop;
|
|
- retain exact world, provider, host and resource evidence on D.
|
|
|
|
Exit: the existing React panel and run archive work without Unreal-specific
|
|
branches in Mission Core.
|
|
|
|
### U2 — physical and sensor world
|
|
|
|
- add reviewed collision/drivable geometry alongside visual assets/Gaussians;
|
|
- pin vehicle mass, inertia, wheelbase, steering limits, suspension, friction
|
|
and sensor extrinsics;
|
|
- publish evaluator-only truth separately from planner/perception inputs;
|
|
- validate camera/LiDAR timing, noise and frame conversion.
|
|
|
|
Exit: sensor/perception experiments are repeatable and do not consume hidden
|
|
ground truth.
|
|
|
|
### U3 — comparative qualification
|
|
|
|
- run equivalent scenarios through the Gazebo and Unreal profiles;
|
|
- report control, collision, latency, resource and reproducibility differences;
|
|
- declare which conclusions are portable across providers and which are not.
|
|
|
|
Exit: Unreal supplies measurable product value beyond rendering quality.
|
|
|
|
## Immediate work policy
|
|
|
|
Continue work that remains valuable across providers:
|
|
|
|
- provider-neutral orchestration and capability admission;
|
|
- run, event, command, artifact and report contracts;
|
|
- TTL, heartbeat, watchdog, failsafe and authority gates;
|
|
- canonical frames, clocks, telemetry and evaluator metrics;
|
|
- scenario/profile registry and browser presentation of canonical state;
|
|
- Gazebo regression cases needed to validate those boundaries.
|
|
|
|
Defer until U0 selects a direction:
|
|
|
|
- a polished custom Gazebo vehicle;
|
|
- large Gazebo world/model libraries;
|
|
- simulator-specific UI controls;
|
|
- a production Unreal bridge;
|
|
- Gaussian collision or road generation assumptions;
|
|
- provider-specific perception contracts.
|
|
|
|
## Consequences
|
|
|
|
- Existing Polygon work is retained as the control plane and regression tier.
|
|
- Unreal experimentation can proceed independently without forking the product
|
|
model or exposing a native engine to the browser.
|
|
- The first Unreal work is a measured adapter spike, not a platform migration.
|
|
- More explicit provider metadata and compatibility testing is required.
|
|
- Two physics providers increase qualification cost, but allow fast regression
|
|
and high-fidelity experiments to coexist.
|
|
|
|
## References
|
|
|
|
- [PX4 simulator MAVLink API](https://docs.px4.io/main/en/simulation/)
|
|
- [CARLA documentation](https://carla.readthedocs.io/)
|
|
- [Project AirSim documentation](https://iamaisim.github.io/ProjectAirSim/)
|
|
- [ASAM OpenDRIVE](https://www.asam.net/standards/detail/opendrive/)
|
|
|