also looking at this
feat: expose owned VTOL transition simulation through native CLI
#82
20 files
+743
-36
| @@ -11,6 +11,7 @@ profiles in the `/missions` workspace. | ||
| 11 | 11 | ./buddy vtol:hover |
| 12 | 12 | ./buddy vtol:hover --scenario host-loss |
| 13 | 13 | ./buddy vtol:hover --scenario imu-loss |
| 14 | ./buddy vtol:hover --electrical | |
| 14 | 15 | ``` |
| 15 | 16 | |
| 16 | 17 | The native Stacks command defaults to 60 virtual seconds. It accepts `hover`, `imu-loss`, |
| @@ -25,6 +26,7 @@ The copied standalone CLI registers the same command definition: | ||
| 25 | 26 | ```sh |
| 26 | 27 | bun run runtime:cli |
| 27 | 28 | ./storage/runtime-build/cli/drone vtol:hover |
| 29 | ./storage/runtime-build/cli/drone vtol:hover --electrical | |
| 28 | 30 | ``` |
| 29 | 31 | |
| 30 | 32 | ## Model and measurements |
| @@ -50,8 +52,9 @@ RC takeover, kill and sensor loss revoke shared authority. Host death leaves its | ||
| 50 | 52 | stale while the independently ticking modeled board expires the output lease. |
| 51 | 53 | |
| 52 | 54 | The mission's 50 Wh capacity, 1200 W ceiling and 30% reserve are declared budget inputs for this |
| 53 | fictional hover experiment. They are not identified electrical power, measured endurance or a | |
| 54 | complete hybrid energy model. Neutral outputs during an airborne fault do not establish a safe | |
| 55 | fictional hover experiment. The default retains a constant declared-ceiling charge. The optional | |
| 56 | electrical model below supplies fictional propulsion/battery dynamics and delayed energy measurements. | |
| 57 | Neither mode identifies hardware power or measured endurance. Neutral outputs during an airborne fault do not establish a safe | |
| 55 | 58 | emergency landing. Physical flight commands remain disabled. |
| 56 | 59 | |
| 57 | 60 | ## Explicit hover observation in library plans |
| @@ -71,8 +74,27 @@ new CLI scenario. Existing hover-only recordings keep their prior shapes. | ||
| 71 | 74 | is a separate development experiment on the same owned runtime. Its nominal mission observes initial |
| 72 | 75 | hover, takes off vertically to 15 m, requests a front transition, flies a cruise leg, requests back |
| 73 | 76 | transition, returns to the back request's capture point, observes settled hover, and lands vertically. |
| 74 | A turning leg also has an actual completed model campaign. This profile is not registered as a CLI | |
| 75 | scenario or selectable workspace profile. | |
| 77 | A turning leg also has an actual completed model campaign. The native `vtol:simulate` command runs | |
| 78 | the nominal route. This profile is not a selectable workspace profile. | |
| 79 | ||
| 80 | ```sh | |
| 81 | ./buddy vtol:simulate | |
| 82 | ./buddy vtol:simulate --electrical | |
| 83 | ./storage/runtime-build/cli/drone vtol:simulate --electrical | |
| 84 | ``` | |
| 85 | ||
| 86 | The command defaults to 160 virtual seconds and accepts an integer `--seconds` from 2 to 180. | |
| 87 | It reports the existing runtime's actual status and the three qualified initial-hover, cruise and | |
| 88 | back-hover observations, including their event, task, reference and capture epochs. Exit 0 requires | |
| 89 | those ordered confirmations, observed estimated flight, completed landing with qualified modeled | |
| 90 | contact, no runtime fault, neutral board outputs and no active output lease. An incomplete route | |
| 91 | retains its partial observations and status and exits 1. The condensed report omits the full path | |
| 92 | and trace. The library still exposes both for replay and evaluation. | |
| 93 | ||
| 94 | Buddy discovers the typed command natively; the standalone binary registers the same definition. | |
| 95 | This command currently exposes the nominal route only. Fault scenarios, operator schedules and | |
| 96 | recovery route selection remain library capabilities. Simulation completion does not qualify | |
| 97 | physical transitions, arbitrary flight envelopes or hardware landing. | |
| 76 | 98 | |
| 77 | 99 | The controller receives measured relative airspeed, differential pressure, airflow angles and modeled |
| 78 | 100 | rotor/pusher response, together with the qualified raw gyro and estimated navigation. Delayed airflow |
| @@ -96,8 +118,8 @@ requires wrapped heading error within 0.1 rad for the complete 500 ms dwell. Hov | ||
| 96 | 118 | therefore have a finite 45-second ceiling; front requests retain 15 seconds. The original 15-second |
| 97 | 119 | back budget still fails without retry or a claimed landing. This is a virtual task allowance, |
| 98 | 120 | not a wall-clock test timeout. The complete declared mission budget is 131,520 ms, or 43.84 Wh at its |
| 99 | 1200 W ceiling, with 100 Wh capacity and 30% reserve. These remain declared planning values, without | |
| 100 | a complete hybrid electrical-power law or measured battery identification. | |
| 121 | 1200 W ceiling, with 100 Wh capacity and 30% reserve. These remain declared planning values. Select | |
| 122 | the optional electrical law below for modeled consumption; measured battery identification remains open. | |
| 101 | 123 | |
| 102 | 124 | The experiment keeps the 2 m transition-height deviation, 0.6 rad roll, 0.5 rad pitch and 22 m/s |
| 103 | 125 | speed guards. Its own target range is bounded to 400 m. The quadcopter and hover development kernel's |
| @@ -147,7 +169,8 @@ and releases outputs. Neither result establishes an airborne landing. | ||
| 147 | 169 | Task execution time stops during pause. Global endurance and the declared energy charge continue, |
| 148 | 170 | so a later scheduled resume can be preempted by reserve, endurance, health or authority refusal. |
| 149 | 171 | Operator actions never extend the original planning allowance or rearm revoked authority. The |
| 150 | transition library and these actions remain separate from the hover-only CLI and common workspace. | |
| 172 | operator schedules remain library-only; neither CLI command exposes them, and the common workspace | |
| 173 | does not select this VTOL profile. | |
| 151 | 174 | |
| 152 | 175 | ## Declared transition recovery routes |
| 153 | 176 | |
| @@ -196,7 +219,7 @@ airborne. A separately declared 35-second allowance completes after about 26.94 | ||
| 196 | 219 | the complete 156,520 ms / 52.1733 Wh worst-case plan. A normal 45-second back plus 45-second recovery |
| 197 | 220 | hover and 35-second landing exceeds the unchanged 180-second graph cap and is rejected. The phase |
| 198 | 221 | abort/pause/recover campaigns instead declare 40-second recovery hover and 30-second landing, fitting |
| 199 | 176,520 ms / 58.84 Wh. These remain declared 1200 W planning charges, without identified electrical | |
| 222 | 176,520 ms / 58.84 Wh. These remain conservative 1200 W planning charges, without identified electrical | |
| 200 | 223 | power or measured battery endurance. |
| 201 | 224 | |
| 202 | 225 | Sensor loss, reference/clock guards, RC takeover, kill, fence, reserve and global endurance remain |
| @@ -204,11 +227,72 @@ authoritative during recovery. Host loss still produces a stale host snapshot an | ||
| 204 | 227 | lease expiry. Fault-induced neutral outputs do not become a landing claim. These bounded library |
| 205 | 228 | campaigns do not qualify arbitrary wind, failed lift rotors, every transition state or physical recovery. |
| 206 | 229 | |
| 230 | ## Fictional electrical model | |
| 231 | ||
| 232 | Select `--electrical` in either VTOL command, or pass `{ electrical: true }` to | |
| 233 | `createVtolHoverProfile('hover', options)` or `createVtolTransitionProfile(options)` in TypeScript. | |
| 234 | The default/disabled profiles keep their prior reports and declared-ceiling energy accounting. | |
| 235 | Both commands run through Buddy and the copied standalone CLI. The nominal full-route command | |
| 236 | uses the same experimental transition library profile. | |
| 237 | ||
| 238 | Each session owns its electrical state. The plant uses actual lagged individual rotor and pusher | |
| 239 | thrust, with these declared coefficients: | |
| 240 | ||
| 241 | | Source | Fictional law | | |
| 242 | | --- | --- | | |
| 243 | | Each of four lift motors | `4 * thrustN ** 1.5` W | | |
| 244 | | Independent pusher | `5 * thrustN ** 1.5` W | | |
| 245 | | Avionics and idle auxiliaries | 12 W | | |
| 246 | | Each surface | `3 * abs(deflectionRad) / 0.4` W | | |
| 247 | | Open-circuit voltage | 20 to 24 V, linear in remaining chemical energy fraction | | |
| 248 | | Series resistance | 0.04 ohm | | |
| 249 | ||
| 250 | The low-current solution of `loadW = (openCircuitV - currentA * resistanceOhm) * currentA` | |
| 251 | sets terminal voltage and current. Chemical source power is `openCircuitV * currentA`, including | |
| 252 | series loss. The four motors, full pusher and all surfaces together draw 948.023527 W at the load. | |
| 253 | At the minimum open-circuit voltage their chemical source demand is 1060.486740 W, rounded upward | |
| 254 | to a **1061 W envelope**. This is an analytic bound on this fictional law, not a motor/battery rating. | |
| 255 | The 20 to 24 V open-circuit range is a simulation parameter; the hardware list's 4S pack retains | |
| 256 | its own specification. | |
| 257 | ||
| 258 | Before session allocation, the runtime requires a planning ceiling at least this envelope and | |
| 259 | capacity matching the captured plant declaration. Existing longest-path graph validation charges | |
| 260 | the complete declared ceiling across normal and supported failure/recovery/landing routes. With the | |
| 261 | 1200 W planning ceiling, the normal route is 43.84 Wh and the declared back-abort route is 58.84 Wh. | |
| 262 | At 50% reserve of 100 Wh, the former fits and the latter is refused before resources are created. | |
| 263 | The front-failure path is shorter than the normal route, so it does not increase that worst-case budget. | |
| 264 | ||
| 265 | The plant integrates chemical source energy on its independent 4 ms steps. Before remaining energy | |
| 266 | cannot fund one complete worst-case step, propulsion demand is cut and latched. Retained motor response | |
| 267 | may coast down; it cannot rearm from a voltage rebound. Auxiliary draw continues to exhaustion. | |
| 268 | Rejected rigid-body integration commits neither body nor electrical state. | |
| 269 | ||
| 270 | Battery data travels through existing delayed, sequence/reference/capture-qualified measurements. | |
| 271 | Energy use rounds upward to micro-watt-hours; current/voltage/load use declared milli-unit quantization. | |
| 272 | The common qualifier rejects missing, nonfinite, inconsistent, over-envelope or decreasing consumption. | |
| 273 | The authority and mission receive a conservative remaining-energy bound after charging the maximum | |
| 274 | source envelope over the measurement's age. A reported supply cutoff withdraws authority even if | |
| 275 | chemical capacity remains. Source loss never substitutes a full battery. | |
| 276 | ||
| 277 | Reports add `energy.model` and `energy.lastObservation`. `energyUsedWh` belongs to its capture epoch; | |
| 278 | `remainingWhLowerBound` and `remainingPercentLowerBound` include the worst-case age charge at | |
| 279 | `observedAtMs`. Host loss leaves this host observation unchanged while independent plant consumption | |
| 280 | and board expiry continue. Mission-policy replay uses the recorded battery observations; it does not | |
| 281 | reconstruct the electrical plant from a mission trace alone. | |
| 282 | ||
| 283 | Actual model campaigns cover combined front demand, all nominal phases, open-circuit pusher timeout, initial/front/back abort | |
| 284 | landing, held recovery/resume, global endurance during pause, supply cutoff, bad battery observations, | |
| 285 | reserve, host loss and independent sessions. The nominal example's front peak is 347.313 W; its | |
| 286 | last captured use is about 4.62 Wh. Neither value predicts aircraft endurance. Motor/propeller advance | |
| 287 | ratio, voltage-dependent thrust, cell temperature/degradation, current-sensor calibration and measured | |
| 288 | capacity remain unmodeled or unqualified. The open-circuit fixture removes pusher demand and thrust; | |
| 289 | it does not model a seized motor's electrical current. | |
| 290 | ||
| 207 | 291 | ## Remaining implementation |
| 208 | 292 | |
| 209 | 293 | [Issue #12](https://github.com/stacksjs/drone/issues/12) remains open. The experimental nominal |
| 210 | 294 | controller and opt-in recovery routes do not establish complete VTOL support. Complete recovery/abort |
| 211 | envelopes, fresh-process restoration, the complete hybrid power/reserve model, native transition CLI and | |
| 295 | envelopes, fresh-process restoration, identified hybrid power/voltage/cell behavior, CLI fault/operator scenarios and | |
| 212 | 296 | the common mission workspace still require implementation and qualification. Wind campaigns and |
| 213 | 297 | broader mission/envelope coverage remain necessary. Full TECS/soaring, tiltrotor/tailsitter mechanisms, |
| 214 | 298 | helicopters and other airframe families remain separate work. Native board control, measured airframe |