Drip-scan image receive mode: OW_CAMERA_IMAGE_MODE (0x30) + data-paced 2408 B line forwarding

[boringethan]

Sensor-fw side of the drip-scan single-frame feature (companion to OpenwaterHealth/openmotion-camera-fpga#8; design spec in that repo at docs/superpowers/specs/2026-07-19-drip-scan-single-frame-design.md §4.4). SDK companion: OpenwaterHealth/openmotion-sdk#167.

Scope:

• New OW_CAMERA subcommand OW_CAMERA_IMAGE_MODE = 0x30 (reserved byte = enable 0/1, data[0] = camera bitmask). Response carries per-camera gap counters.
• Image mode suspends histogram streaming (mutually exclusive), aborts in-flight histogram DMA, and arms repeating 2408-B one-shot DMA per masked camera into the existing receive buffers (cam 1 = spi6_buffer in SRAM4 for BDMA, unchanged).
• Data-paced receive: RxCplt builds the USB envelope in place and forwards on the HISTO endpoint with stream type 0x03 (OW_IMAGE_PACKET), then re-arms the camera's DMA.
• Per-camera ~2 ms line timeout serviced from the main loop: abort + re-arm + gap counter.
• Exit restores histogram arming; the next histogram frame is consumed and discarded firmware-side (FPGA first-frame-garbage caveat from the feature/5 line-readout work).
• Host pytest for wire-format constants + CRC table; HIL suite tests/test_image_mode_hil.py (bench).

Laser per-pulse parameters untouched; sensor retiming + FSIN-rate orchestration are host/SDK-side. FPGA side is sim-complete + Diamond-built (163489 B bitstream, register map v2).

[boringethan]

Starting on branch feature/99-drip-scan-image-mode (off next). Planned approach: image mode lives in camera_manager.c reusing the existing per-camera receive buffers (USB image envelope built in place ahead of the DMA landing zone, honoring the cam1 SRAM4/BDMA constraint); on RxCplt the line is forwarded on the HISTO endpoint as stream type 0x03 and the camera's DMA is re-armed data-paced (not FSIN-paced). Note the H7 HAL USART/SPI slave sets State=READY only AFTER the RxCplt callback returns, so the re-arm is pended out of the callback rather than done in-line — exact mechanism finalized during implementation. ~2 ms per-camera line timeout serviced from the main loop (DMA NDTR progress) → abort + re-arm + gap counter. OW_CAMERA_IMAGE_MODE=0x30 handler returns per-camera gap counters. Histogram streaming is suspended while image mode is active and the first post-exit histogram frame is discarded (feature/5 garbage-frame caveat). Host pytest for the wire format + CRC; HIL suite is bench-gated. FPGA companion is sim-complete + Diamond-built.

[boringethan]

Draft PR up: #100 (6 commits on feature/99-drip-scan-image-mode). Implementation complete + reviewed: wire constants, image-mode state machine, data-paced 2408-B receive with in-place 2424-B envelope + LPTIM5 soft-IRQ re-arm, line-timeout watchdog, OW_CAMERA_IMAGE_MODE handler. Verification: clean full firmware build, pytest 37 passed/19 skipped, HIL suite collects+skips off-bench. The two-stage review confirmed histogram-path behavior is byte-identical when image mode is unused, and caught+fixed a latent handler bug (invalid-payload path now returns the status payload) and a cross-repo envelope mismatch (SDK was 2420 B/no-timestamp; both repos now agree on the 2424-B timestamped envelope). Bench-gated (Task 9): tests/test_image_mode_hil.py on the rig — enter/exit + histogram resume, line-timeout, sweep line-rate smoke against the feature/8 bitstream. Stays In review per matched-set policy until the three-repo set validates on hardware. Note: origin/next now uses a bootloader flash layout (app-only image, FPGA flashed separately) — deploy firmware-only.

[boringethan]

First HIL run on the rig (left sensor) — partial validation, one hardware blocker

Flashed the drip-scan firmware (bare-metal merged image, via deploy.py → ROM DFU at 0x08000000) and ran on hardware. Results:

✅ Validated on real hardware:

• Firmware flashes and boots cleanly (bare-metal deploy, sensor re-enumerates after power-cycle).
• Histogram path is NOT regressed — with the drip-scan firmware, a normal 2-camera histogram scan streams fine (the HIL test's Phase 1 passed: cameras brought up, histograms flowing). This is the key regression check the receive-path rewrite needed.
• Image-mode command works at the protocol level — OW_CAMERA_IMAGE_MODE enter returns active=1 with the correct mask, and the 36-byte image_mode_resp_t parses. Firmware suspends histogram streaming on enter as designed.

⛔ Blocked — full image-line data path not yet validated:
The drip-scan FPGA bitstream does not bring up its I2C register map (0x5A) on the cameras. The fleet cameras are NVCM-programmed (production histogram bitstream); I flashed the drip-scan bitstream to flash 0x081A0000 (hash-verified in the merged image) and force-loaded it via force_program_fpga (OW_FPGA_PROG_SRAM reserved=2, which my firmware DOES implement — if_commands.c:258). The force-load returns success, but 0x5A (ID/VERSION/STATUS) stays silent even with the camera streaming. So the CrossLink is still running the NVCM production image, not the drip-scan one. Without the v2 register map, sweep mode can't be driven, so no real 2408-B image lines flow.

To distinguish 'forced SRAM load not taking on these NVCM cameras' from 'drip-scan bitstream has a hardware defect (e.g. the flagged clk_pixel_hs 132.8 MHz timing — camera-fpga#8)': next session needs DEBUG_FLAG_USB_PRINTF during force_program_fpga to read the CrossLink IDCODE/status-verify log, and likely a scope on the MIPI clock (spec §5). May require NVCM-reprogramming the cameras with the drip-scan image (update_bitstream.py) rather than a volatile SRAM load.

Test-suite notes (found via HIL): test_image_mode_hil's 'FPGA-independent' test 1 relies on the 2408-B DMA chopping the FPGA's 4100-B histogram bursts into image lines — that doesn't work on hardware (the STM32 slave DMA doesn't cleanly re-frame a continuous burst; 0 image packets resulted). Real firmware image-path validation needs the drip-scan FPGA actually running. Minor: the per-camera gap counter shows 1 spurious count on the USART camera at enter (a transition artifact — enter zeros gaps before its abort/re-arm loop; zeroing after arming would fix it).

Rig state: left sensor runs the feature/99 bare-metal drip-scan firmware (histogram-compatible); cameras NVCM-booted (production FPGA); Open-Motion app was closed for exclusive USB and left closed. Restore a production build via deploy.py if desired.

[boringethan]

✅ HIL breakthrough: sweep transport validated end-to-end on the rig

Root cause of the earlier 0x5A silence found and fixed (systematic-debug session): the origin/next OW_FPGA_PROG_SRAM handler ignores reserved==2 — the #68 force hunk lives only on the unmerged fix/82-sram-upload-path branch — so force_program_fpga was a silent NVCM-skip returning success, and the production NVCM image kept running. My earlier claim that the firmware was force-capable was wrong (grep matched OW_CMD_SERIAL's reserved==2 block). Fix: ported the bench-validated hunk verbatim (fe3f64e).

With a real force-load (10.6 s/camera observed): the Diamond-built drip-scan bitstream comes up on BOTH link-family cameras — cam0 (USART) and cam1 (SPI6/BDMA): ID=0x5A, VERSION=0x02, STATUS=0x01 (pll_lock), SCRATCH round-trip. That also retires the clk_pixel_hs static-timing concern for the control plane on silicon.

test_image_line_stream_smoke PASSES (e1b64f4): image mode → sweep armed via 0x5A → ≥100 CRC-clean 2424-B TYPE_IMAGE envelopes with valid B6 01 line headers received on USB from a real FPGA sweep → clean exit, healthy ping. This validates on hardware: FPGA sweep engine + image_pusher, MCU data-paced 2408-B DMA receive on both SPI and USART links, in-place envelope build + CRC, TYPE 0x03 forwarding.

Two new bench findings recorded in e1b64f4: (1) bring-up must force per NVCM fleet reality; (2) firmware robustness gap: a multi-camera mask in one OW_FPGA_PROG_SRAM command blocks the main loop >20 s and stalls the COMMS USB endpoint (reproduced 2×) — per-camera commands are reliable. Worth a follow-up (chunked/deferred programming or a documented per-camera contract).

Remaining for full acceptance (spec §5): the SDK capture_full_frames orchestrator with sensor retiming (complete reassembled frame, then laser-synced single-exposure), storage-decay dark frame, and the histogram-regression suite after sweep sessions.