fwt_software/docs/test-command.md

The test command — hardware self-test suite

test runs modular hardware self-tests on the real gimbal, writes a plain-text report to disk, and compares each run against a pinned baseline and the previous run so both outright failures and slow drift are visible. It replaces the old firmware-only gimbal diag (the firmware motor self-test is now one leaf inside test gimbal encoder).

Implementation: TestRunner (worker thread, mirrors CalibrationRoutine) + the pure TestReport model (formatTestReport/parseTestReport/applyComparison) and HostMetrics host reads.

Usage

test [<subsystem> [<leaf>]] [<profile>]
test list            # list configured profiles
test baseline        # pin the most recent report from this session as the baseline

The command is a three-level hierarchy; omitting a level widens scope. A trailing token that names a configured profile selects the profile at any position.

Command	Runs
test	everything
test gimbal	all gimbal leaves
test gimbal homing	just homing
test imu drift	just IMU yaw drift
test host	host thermal/disk/memory/load (no hardware needed)
test gimbal encoder strict	one leaf, strict profile
test strict	everything, strict profile

While a test runs, interfering commands (moves, homing, a second test, capture, refresh) are ignored; Esc (or stop) cancels. Pure-UI keys (p, i, c, g, ?) keep working.

Subsystems and leaves

Subsystem	Leaf	Checks
gimbal	homing	endstop-count + travel + homing-time reproducibility
gimbal	encoder	firmware DIAG tracking quality (repeated) + hold-corrector drift
gimbal	friction	full-range traverse time + motor load per direction
gimbal	backlash	reversal dead-band (encoder error) at small steps
gimbal	balance	pitch up-vs-down per-step peak current (center-of-mass symmetry)
imu	config	device identity, output mode, sample rate, active XKF profile
imu	health	rate, dropped samples, angle noise, accel-norm, temperature
imu	drift	yaw drift rate (deg/min) over a long static window
host	thermal	hottest CPU thermal zone (/sys/class/thermal)
host	disk	free space on the image partition (statvfs)
host	memory	available RAM / swap (/proc/meminfo)
host	load	load average vs CPU count

Gimbal leaves require a homed gimbal (home first); IMU leaves require the IMU ([Features] enable_imu). host needs neither, so test host doubles as a fast non-intrusive smoke check.

Some metrics are most accurate with firmware support (a homing-report HM line and a load-capture LP primitive); until those land the modules fall back to sampling the ST telemetry stream and note it in the report. See test-roadmap.md.

Profiles

A profile is a named bundle of repetition counts, sampling windows and pass thresholds, configured in config.ini under [Test] and [TestProfile.<name>] (see configuration.md and the example config). The default is standard (5 reps). Unknown keys are ignored, so new tests add knobs without code changes. Ship profiles like quick (fewer reps) and strict (more reps, tighter drift gate).

Pass / fail and comparison

Each metric can carry an absolute threshold from the profile. Independently, every metric is compared to the pinned baseline and the previous run; a move worse than drift_warn_pct is flagged, and if drift_gates_pass = true a flagged metric also fails. A section fails if any of its metrics fail; the run fails if any section fails.

Reports

Each run writes logs/test_YYYYMMDD-HHMMSS.log (under the per-user log dir). The format is human-readable and re-parseable:

[host_disk]  PASS  0 ms  # image partition free space
  free_gb = 3.65 GB  PASS  base=3.66  prev=3.66  drift=-0.001%
  used_pct = 2.65 %  PASS

test baseline copies the most recent report to the baseline file ([Test] baseline_file, default <logdir>/test_baseline.txt); subsequent runs show base= columns against it.