scanengine-3/CLAUDE.md

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