pre uc480 integration

CLAUDE.md

@@ -0,0 +1,25 @@
+# ScanEngine-3 — Claude Code Instructions
+
+## Project Overview
+
+Primary language is Python with PyQt6 for all GUIs. This project consists of hardware test apps and control software for cameras, lasers, and motor drivers communicating over serial/USB/UART. Also includes RP2040 C/PIO firmware for embedded peripherals.
+
+When generating test apps or utilities, use PyQt6 patterns consistent with existing apps in the project (see `helios_test_app.py`, `bbd202_test_app.py`, `camera_test_app.py`).
+
+## Hardware Debugging
+
+This project involves hardware test apps (cameras, lasers, motor drivers) communicating over serial/USB/UART. When debugging hardware issues, always consider these common root causes before proposing code changes:
+
+- **Device held by another process** — check with `lsof /dev/ttyUSB*` or `fuser /dev/ttyUSB*` before diagnosing driver bugs
+- **USB re-enumeration** — device may re-appear on a different `/dev` path after a reset; don't assume the port is stable
+- **Firmware state that persists across soft resets** — registers, enable bits, and error latches may retain values from a previous run; always read current state before assuming defaults
+
+When working with hardware protocol docs (PDFs), register definitions and command specs may be split across multiple documents. Ask the user early if the needed section might be in a separate document rather than assuming all info is in one file.
+
+### PIO (RP2040)
+
+When writing or debugging PIO programs, proactively check for these common pitfalls:
+
+- **`pull noblock`** loads OSR from X (scratch register) if the TX FIFO is empty — if X is uninitialised this silently clobbers the output value
+- **Invisible pulses** — a single-cycle high pulse is often too narrow to trigger a scope; use a counter to hold the output high for several cycles
+- **Off-by-one errors** in division/counting loops — verify the total cycle count matches the intended division ratio including the branch instruction cost