docs(simulation): record Ackermann motion acceptance

This commit is contained in:
DCCONSTRUCTIONS
2026-07-24 23:00:07 +03:00
parent 49b0f47fea
commit bc61331604
4 changed files with 145 additions and 13 deletions
+59 -4
View File
@@ -2,9 +2,10 @@
## Scope
This runbook starts the first browser-visible stock Ackermann rover through the
Mission Core control plane. It accepts only a virtual PX4/Gazebo run. It does
not admit a physical vehicle, direct actuator setpoints, navigation or safety.
This runbook starts and commands the first browser-visible stock Ackermann rover
through the Mission Core control plane. It accepts only a virtual PX4/Gazebo
run. It does not admit a physical vehicle, direct actuator setpoints, navigation
or safety.
Runtime placement:
@@ -82,6 +83,11 @@ deep-link. The live panel must show `Worker готов`. Start/stop calls requir
the `internal-virtual-only` environment gate must leave status visible while
disabling lifecycle actions.
Cold PX4/Gazebo/ROS 2 startup is expected to take roughly 30–60 seconds on the
reviewed worker. The lifecycle request remains bounded at the gateway and the
controller fails closed if ROS publication or armed Offboard admission is not
confirmed.
## Live-state contract
The first S1C live sample comes from:
@@ -104,6 +110,33 @@ It is published to the browser as `missioncore.vehicle-state/v1` with:
This signal proves live presentation and frame naming only. It is not the
accepted PX4/ROS 2 telemetry path.
## S1D command contract
While the run is `running`, the React controls submit:
```text
POST /api/v1/polygon/worker/runs/<run-id>/commands
Idempotency-Key: <unique operator intent>
{"speed_mps": 1.0, "steering_normalized": -0.6}
```
Mission Core validates the S1 envelope, assigns a monotonic sequence and
250 ms simulation-time TTL, and durably journals the command before worker
delivery. The worker keeps the external speed/steering contract but maps the
stock model to PX4 rover-level Offboard control:
- `RoverThrottleSetpoint.throttle_body_x = speed_mps / 3.1`;
- `RoverSteeringSetpoint.normalized_steering_setpoint` carries steering;
- `OffboardControlMode.thrust_and_torque=true`;
- `OffboardControlMode.direct_actuator=false`;
- no `ActuatorMotors` or `ActuatorServos` message is published by Mission Core.
The browser repeats a held directional intent fast enough to renew TTL. Release,
the explicit `Стоп` control, stale command TTL or run stop all drive the
setpoint to zero. The `3.1 m/s` factor is the stock PX4 model's
`RO_MAX_THR_SPEED`; S1D motion acceptance must not be described as calibrated
closed-loop speed tracking.
## Acceptance checklist
- [ ] exact source commit and source/build SHA-256 recorded;
@@ -118,7 +151,29 @@ accepted PX4/ROS 2 telemetry path.
- [ ] browser stop reaches terminal `completed`;
- [ ] stop records `operator-stop-clean`;
- [ ] PX4, Gazebo and Micro XRCE-DDS leave no process residue;
- [ ] command count remains zero until the command-delivery checker is accepted.
- [ ] straight, turn and reverse commands produce causal pose changes;
- [ ] one isolated non-zero command expires at 250 ms and produces a stable
stopped pose;
- [ ] command acceptance reports armed Offboard and remains below TTL;
- [ ] command count and command journal sequences match submitted intents.
## Accepted S1D evidence
- code commit:
`49b0f47fea0ae29c977bbd60808696b85a9380cd`;
- source archive SHA-256:
`30aad33664a536f2a6cb87bc172a5dae111ae479d5899723832a1abc17c4517b`;
- Control Station archive SHA-256:
`014724896c8c2169a89b0ed6971b285b6e80da918d892509e9e93568efb99f25`;
- 40 focused tests passed from the exact source-first D-only generation;
- cold start: one request, 32.08 seconds;
- run: `s1c-49b0f47-20260724t195259z-62edd2`;
- straight endpoint: `(3.74, -0.00)` m from origin;
- turn endpoint: `(5.11, 2.13)` m;
- reverse endpoint: `(5.58, 0.67)` m;
- sampled command admission: 44.6 ms;
- TTL evidence: counter 4 -> 5 and identical following X/Y samples;
- explicit stop: no PX4, Gazebo or Micro XRCE-DDS residue.
## Failure handling