Thomas Ales
26 lines
1.9 KiB
Markdown
Executable File
26 lines
1.9 KiB
Markdown
Executable File
# 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
|