docs(uno-q): shaker-campaign findings — position-target DVF, safe settings, sensor placement

Co-Authored-By: Claude Opus 4.8 <[email protected]>

deploy/uno-q/ACTUATOR.md

@@ -53,10 +53,25 @@ Bench-measured gain range:
 | **1000–2000** | **authoritative and stable — recommended** |
 | 4000 | **UNSTABLE** — self-excites off its own step-vibration (velPk 30→1442, 26k steps); the soft-limit envelope catches the runaway |
 
-The instability at high gain is the root-locus gain limit — great live demo:
+Actuator FRF note: open-loop amplitude rolls off with frequency — full ~10 mm
-tap with DVF off (rings) → `dvf 1500 8` (damped) → `dvf 4000 6` (goes unstable,
+holds to ~2–3 Hz, only a few mm by 10 Hz.
-envelope catches it). Actuator FRF note: open-loop amplitude rolls off with
+
-frequency — full ~10 mm holds to ~2–3 Hz, only a few mm by 10 Hz.
+**Shaker-table campaign findings (2 Hz base excitation):**
+- The control law is **position-target DVF**: carriage position target =
+  `center − K·v` (reaction force ∝ −v = true damping). A velocity-command law
+  (carriage velocity ∝ v) is force ∝ −a = *added mass* — no dissipation; it
+  amplified the response at every gain/sign. Don't regress to it.
+- **Safe reference setting: `dvf 30 8`** with the slew limit at 8 steps/tick
+  (~2000 steps/s). Ran 2 min continuous, silent, self-centering, no runaway.
+  Slew 25 grinds the motor (lost steps → position corrupted).
+- **Sensor placement is the binding constraint:** a deck-mounted sensor near
+  the rail reads the carriage's own motion (~856 mg open-loop) louder than the
+  structure sway (~435 mg), so closed-loop damping can't be scored (or cleanly
+  fed back). Mount the feedback sensor at the structure's max-sway point (tower
+  top), ideally a second ADXL355 on mux channel 1.
+- `listen <secs>` (≤8 s) = passive baseline/ring-down instrument. Old numbers:
+  tap tests gave stable-looking g up to ~2000, but that predates the shaker
+  campaign — trust the shaker findings.
 
 Every move is **clamped to `[0, stepMax]`** and the reply reports position, e.g. `pos=1234
 max=9635`, ending in `LIMIT` if it hit the soft limit.