harden sensor acquisition after audit

README.md

@@ -6,7 +6,7 @@ accelerometer and L3G4200D gyroscope on a shared I2C bus.
 This milestone does four things:
 
 1. Detects and verifies both sensors by their identification registers.
-2. Configures each sensor for 100 Hz raw acquisition.
+2. Configures each sensor for a nominal 100 Hz raw output rate.
 3. Emits timestamped, sensor-native raw readings over the XIAO USB connection.
 4. Maps both sensors into a shared enclosure coordinate frame for validation.
 
@@ -29,10 +29,10 @@ Both breakouts share SDA, SCL, 3V3, and GND. The firmware checks both possible
 
 ## Sensor configuration
 
-- ADXL345: 100 Hz output rate, full-resolution mode, +/-8 g. Nominal scale is
+- ADXL345: nominal 100 Hz output rate, full-resolution mode, +/-8 g. Nominal scale is
   3.9 mg/LSB.
-- L3G4200D: 100 Hz output rate, 25 Hz bandwidth, +/-500 dps. Nominal scale is
-  17.5 mdps/LSB.
+- L3G4200D: nominal 100 Hz output rate, LPF2 selected with a 25 Hz cutoff,
+  +/-500 dps. Nominal scale is 17.5 mdps/LSB.
 
 The enclosure coordinate frame is:
 
@@ -48,7 +48,13 @@ enclosure Y = -native X
 enclosure Z =  native Z
 ```
 
-No calibration, filtering, or sensor fusion is performed yet.
+No software calibration, software filtering, or sensor fusion is performed yet.
+
+The ESP32-C3 polls at exactly 100 Hz, but each sensor has an independent internal
+sample clock. The status registers are read immediately before each XYZ read so a
+consumer can distinguish a fresh sample from a repeated poll and identify gyro
+overruns. Hardware data-ready interrupts and FIFO acquisition are deferred to the
+buffering milestone.
 
 ## Build and flash
 
@@ -73,9 +79,28 @@ Exit the serial monitor with `Ctrl-]`.
 After startup metadata, records use CSV:
 
 ```text
-sequence,timestamp_us,accel_x_raw,accel_y_raw,accel_z_raw,gyro_x_raw,gyro_y_raw,gyro_z_raw,accel_native_x_raw,accel_native_y_raw,accel_native_z_raw,gyro_native_x_raw,gyro_native_y_raw,gyro_native_z_raw
+sequence,poll_timestamp_us,accel_x_raw,accel_y_raw,accel_z_raw,gyro_x_raw,gyro_y_raw,gyro_z_raw,accel_native_x_raw,accel_native_y_raw,accel_native_z_raw,gyro_native_x_raw,gyro_native_y_raw,gyro_native_z_raw,accel_int_source,gyro_status,loop_overrun_count
 ```
 
-`timestamp_us` is the ESP32-C3 monotonic microsecond timer since boot. The axes
-in the first six sample columns use the enclosure frame above. The appended native
-columns are temporary diagnostics for the coordinated orientation test.
+`poll_timestamp_us` is the ESP32-C3 monotonic time immediately before the status
+and data reads. It is not the sensors' physical sample time. The axes in the first
+six sample columns use the enclosure frame above. Native columns remain available
+for diagnostics.
+
+Status bits:
+
+- `accel_int_source & 0x80`: an unread ADXL345 sample existed when status was
+  checked. If clear, treat the following sample as stale/untrusted; a sample can
+  arrive in the short interval between the status and data transactions.
+- `accel_int_source & 0x01`: ADXL345 unread data was overwritten.
+- `gyro_status & 0x08`: L3G4200D sample is fresh.
+- `gyro_status & 0x80`: L3G4200D data overran before it was read.
+- `loop_overrun_count`: cumulative acquisition deadlines missed; the loop
+  resynchronizes after a miss instead of issuing catch-up bursts.
+
+The capture tool auto-detects a single `/dev/cu.usbmodem*` device, writes only
+validated numeric records to a real CSV, and reports sequence or timing problems:
+
+```sh
+python tools/capture_serial.py
+```