docs(uno-q): oscillator + DVF commands, gain findings, demo script

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

deploy/uno-q/ACTUATOR.md

@@ -37,6 +37,26 @@ enforces the limits. Two ways to reach it:
 
 **Relay commands** (`:9999`, for setup/calibration from the host — `nc`/socket):
 - `step <count> <dir>` · `zero` · `pos` · `setmax <n>`
+- `osc <amp_steps> <freq_cHz> <cycles>` — open-loop sinusoidal excitation (shaker mode)
+- `oscm <amp> <freq_cHz> <cycles>` — oscillate while measuring the ADXL355 (per-axis p-p mg)
+- `accel` — one ADXL355 sample (mg); `dvf <gain> <secs>` — closed-loop damping (below)
+
+### Direct Velocity Feedback (`dvf`) — active damping
+Closes the loop: ADXL355 X-accel @ ~250 Hz → leaky-integrated velocity → stepper
+commands `-g·v` (velocity feedback adds damping, c → c+g). Envelope-clamped and
+slew-limited. **Runs must be ≤ 8 s** — the RouterBridge RPC times out at 10 s.
+
+Bench-measured gain range:
+| gain | behaviour |
+|---|---|
+| 500 | gentle |
+| **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:
+tap with DVF off (rings) → `dvf 1500 8` (damped) → `dvf 4000 6` (goes unstable,
+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.
 
 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.