@h2loop/uav 1.0.0

package/skills/uav/references/tuning.md

@@ -0,0 +1,72 @@
+# FFT → Harmonic-Notch Recommender
+
+The tuning recommender (`src/harness/tuning.ts`, `recommendNotch`) is the UAV pack's
+signature feature. It closes the loop that pilots normally run by hand in Mission
+Planner: pull a log, eyeball the FFT, guess a notch frequency, re-fly, repeat. Here it
+is one deterministic pass over the log.
+
+## What it does
+
+1. **Reads the gyro signal.** Prefers the `IMU` table's `GyrX/GyrY/GyrZ` columns
+   (rad/s) and uses the highest-energy axis. Falls back to `VIBE` (`VibeX/Y/Z`) when
+   no IMU gyro is present.
+2. **Finds the sample rate.** Uses `IMU.GHz` (the gyro sample rate, in Hz) when
+   present, otherwise estimates it from the median of `TimeUS` deltas (µs → Hz).
+3. **Runs an FFT.** A pure-TypeScript radix-2 Cooley–Tukey FFT (no npm deps). The
+   signal is de-meaned, Hann-windowed, and zero-padded to the next power of two; the
+   one-sided magnitude spectrum is returned.
+4. **Picks the dominant peak** inside the search band (default **20–200 Hz**, the
+   usual multicopter motor/prop noise range) and reports the top ~3 peaks.
+5. **Emits ArduPilot harmonic-notch params**, each carrying a valid `range` and a
+   `source` of `{kind: "rule-of-thumb", ref: "ArduPilot harmonic notch tuning"}`.
+
+## The message it reads
+
+A `DecodedLog` (see `src/types.ts`). It only touches three tables:
+
+- `IMU` — `GyrX/GyrY/GyrZ` (signal), `GHz` (rate), `TimeUS` (rate fallback).
+- `VIBE` — `VibeX/Y/Z` fallback signal.
+- `CTUN` — `ThH` (hover throttle) for the throttle reference.
+
+Nothing else is required. If none of these carry a usable signal it returns a null
+recommendation — it **never throws**.
+
+## How to read the recommendation
+
+`recommendNotch(log)` returns a `NotchRecommendation`:
+
+- `dominant_peak_hz` — the centre frequency of the strongest in-band peak, or `null`.
+- `peaks` — up to 3 `SpectralPeak`s (`freq_hz`, `magnitude`, `axis`), strongest first.
+- `params` — the suggested settings:
+  - `INS_HNTCH_ENABLE = 1` — turn the harmonic notch on.
+  - `INS_HNTCH_MODE` — the **tracking mode**, chosen from the telemetry in the log:
+    **3 = ESC telemetry** (if `ESC.RPM` present), **2 = RPM sensor** (if an `RPM` message is
+    present), else **1 = throttle-based** (fallback). ESC/RPM modes track the measured motor
+    frequency directly, so they hold the notch on the peak across the whole throttle range —
+    preferred; throttle mode only approximates (freq ∝ √throttle).
+  - `INS_HNTCH_FREQ = round(peak)` — notch centre, clamped to [10, 495].
+  - `INS_HNTCH_BW = round(peak / 2)` — bandwidth ≈ half the centre, a standard
+    starting width, clamped to [5, 250].
+  - `INS_HNTCH_REF` — `avg(CTUN.ThH)` (hover throttle) in throttle mode; `1.0` in RPM/ESC
+    modes (the notch tracks measured RPM, so FREQ is just the low-RPM floor).
+  - `INS_HNTCH_HMNCS = 3` — track the 1st + 2nd harmonics (bitmask).
+  - **`INS_HNTC2_*`** — a **second** harmonic notch, emitted ONLY when a distinct, strong second
+    peak exists (well separated from the dominant and ≥ half its magnitude) — e.g. a separate
+    structural resonance or motor group. Same fields (ENABLE/MODE/FREQ/BW/REF/HMNCS) at that peak.
+- `rationale` — one paragraph: the peak found, the sample rate and its source, and why
+  the values were chosen.
+
+A `null`/empty result means "insufficient gyro/vibe data" — surface that, do not
+fabricate params.
+
+## Safety note
+
+These params are **starting values**, not a verified tune. They must be reviewed by a
+human (or the gating subagent) before they touch a vehicle. Critically, this module
+only *recommends* — it has no path to a flight controller.
+
+**Pushing params is a separate, gated action.** `/uav-tune` (or the `uav_tune` tool) only
+recommends — confirm the recommendation against the airframe and check the ranges, then
+write parameters over the gated MAVLink param link (`--allow-param-write`). After applying,
+re-fly and re-run `recommendNotch` on the new
+log to confirm the peak dropped — the same FFT→notch loop, closed automatically.