calibrate enclosure motion outputs

docs/axis-validation-2026-08-16.md

@@ -56,5 +56,5 @@ in firmware.
 
 The mounted sensor axes and the firmware's enclosure-frame axis assignments are
 consistent. These tests established the dominant gyro axis but did not establish
-gyro polarity; directed positive and negative rotations remain part of the
-calibration pass.
+gyro polarity. The subsequent 2026-08-17 calibration pass used directed positive
+and negative rotations and confirmed polarity on all three axes.

docs/calibration-2026-08-17.md

@@ -0,0 +1,89 @@
+# Sensor Calibration — 2026-08-17
+
+Calibration used one continuous 83,229-record hardware capture. The enclosure
+was held stationary on all six faces, then returned flat for three explicitly
+directed rotations around each enclosure axis. Position changes remained in the
+recording so freshness behavior could also be checked during motion.
+
+The raw capture is `captures/calibration_session_20260817.csv` and is
+intentionally excluded from source control.
+
+## Capture integrity
+
+- Sequence gaps and resets: 0
+- Timestamp anomalies: 0
+- Rejected or ignored records: 0
+- Acquisition-loop overruns: 0
+- ADXL345 overruns: 0
+- ADXL345 DATA_READY clear: 4,282 records
+- L3G4200D ZYXDA clear: 0 records
+- L3G4200D ZYXOR set: 2,456 records
+
+## Accelerometer
+
+Only records with ADXL345 DATA_READY set were used in the stationary face means.
+The paired positive and negative faces produced these enclosure-frame
+coefficients:
+
+| Axis | Offset (counts) | Scale (counts/g) | Scale (mg/LSB) |
+| --- | ---: | ---: | ---: |
+| X | -1.417678 | 258.890661 | 3.862635 |
+| Y | -4.400892 | 259.825135 | 3.848742 |
+| Z | +11.776132 | 245.755573 | 4.069084 |
+
+Firmware converts a mapped raw value to integer milligravity with:
+
+```text
+accel_mg = round((raw_counts - offset_counts) * 1000 / counts_per_g)
+```
+
+The ADXL345 hardware offset registers remain zero. Calibration is deliberately
+performed in software so raw readings remain recoverable and the coefficients
+remain explicit.
+
+## Gyroscope
+
+The central five thousand samples of the flat stationary interval produced:
+
+| Axis | Zero-rate bias (counts) | Stationary SD (counts) |
+| --- | ---: | ---: |
+| X | +9.0482 | 9.8933 |
+| Y | -153.6198 | 9.5714 |
+| Z | -7.0238 | 10.4259 |
+
+The instructed positive motion was top/USB-edge lift for +X, left-edge lift for
++Y, and counterclockwise rotation viewed from the cover for +Z. Every outward
+stroke was positive on its intended gyro channel, and every return stroke was
+negative. Axis assignment and polarity are therefore confirmed.
+
+Firmware subtracts the measured zero-rate bias and converts with the nominal
+L3G4200D +/-500 dps scale of 17.5 mdps/LSB. Gyro scale itself was not measured
+because no controlled angular-rate reference was available.
+
+## Freshness under motion
+
+Using gyro magnitude greater than 500 counts from stationary bias as a
+conservative motion selector gave 8,233 moving records. Of the 425 records with
+ADXL345 DATA_READY clear, 300 (70.6%) exactly repeated the preceding XYZ tuple.
+Of 7,808 records with DATA_READY set, 85 (1.1%) repeated the tuple. Identical
+fresh samples remain possible from quantization, pauses, or rotation about the
+gravity vector, but the strong enrichment confirms that the status flag is
+practically useful under motion.
+
+The clear flag remains conservative: 125 moving records changed values despite
+DATA_READY being clear at the earlier status transaction, consistent with a new
+sample arriving between the separate status and data reads.
+
+## Firmware verification
+
+The calibrated CSV-v3 firmware was built, flashed to the assembled prototype,
+and checked with a 3,814-record flat smoke capture:
+
+- Sequence gaps, resets, timestamp anomalies, and rejected records: 0
+- Acquisition-loop and ADXL345 overruns: 0
+- Independently recomputed calibrated fields differing from firmware output: 0
+- Mean calibrated acceleration: (+19.5, -5.6, +999.9) mg
+- Mean bias-corrected gyro: (+25.4, -62.9, -54.8) mdps
+
+The small residual horizontal acceleration is consistent with the enclosure not
+being perfectly level. The largest residual gyro mean is 0.063 dps.