Add PI V-308 / C-414 voice-coil focus stage (USE_PI_FOCUS_STAGE)

[hongquanli]

Summary

Adds support for the PI V-308 voice-coil PIFOC focus drive (on a C-414 PIMag
controller) as a selectable main-Z stage, alongside the existing Cephla and Prior stages.
The V-308 gives fast, high-resolution closed-loop Z for focus / Z-stacking.

Enable with USE_PI_FOCUS_STAGE = True. The V-308 becomes the Z axis, wrapping whatever XY
stage is configured (Cephla µC or Prior) — so it composes with the existing stage, it doesn't
replace XY.

What's included

• software/squid/stage/pi.py (new, self-contained like prior.py/cephla.py):
  • C414FocusStage — GCS-2.0 driver over serial, pipython imported lazily (module imports
    fine without it; CI and simulated builds never need it).
  • _SimulatedC414 — pure-Python backend for hardware-free / CI use.
  • PIFocusStage(AbstractStage) — Z-only adapter, pure pass-through mm (no sign flip, never
    reads Z_AXIS.MOVEMENT_SIGN).
  • CombinedStage(AbstractStage) — routes X/Y/θ to the existing stage, Z to the V-308; presents a
    V-308-correct Z axis (continuous ~10 nm grid) so GUI Z-step snapping isn't coarsened.
• Config (control/_def.py): USE_PI_FOCUS_STAGE, SIMULATE_PI_FOCUS_STAGE,
  PI_FOCUS_STAGE_SN, PI_FOCUS_SERIAL_PORT, PI_FOCUS_BAUDRATE, PI_FOCUS_AXIS,
  PI_FOCUS_REFERENCE_ON_STARTUP, PI_FOCUS_VELOCITY_MM_S.
• Wiring: import branch in gui_hcs.py; CombinedStage construction in
  microscope.build_from_global_config; stage close() on shutdown.
• Deployment: drivers and libraries/pi/udev/{98-pi-c414-bind,99-pi-ftdi-latency}.rules and an
  optional pip install pipython in setup_22.04.sh.
• Tests: tests/squid/test_stage.py (26 V-308 tests), simulated, no hardware.

Hardware / connection (verified on a real unit)

The C-414 is a custom-VID FTDI (1a72:102b, FT-X), serial 1UETR6I!, controller frame
0..7 mm (TMN?=0, TMX?=7) — not the spec sheet's mechanical "±3.5". Because the VID is
custom, the OS doesn't auto-create a COM port:

• Linux: 98-pi-c414-bind.rules binds it to ftdi_sio (new_id) so /dev/ttyUSB* appears;
  99-pi-ftdi-latency.rules drops the FTDI latency timer to 1 ms. setup_22.04.sh installs both.
• Windows: PI's bundled FTDI driver creates the COM port.
• Default transport is serial; PI_FOCUS_STAGE_SN (the FTDI serial) resolves to the port.

A V-308 scope's machine config should set

• PI_FOCUS_STAGE_SN (or PI_FOCUS_SERIAL_PORT).
• OBJECTIVE_RETRACTED_POS_MM — the V-308's retracted / objective-clear Z; home(z) and the
  pre-XY-homing retract drive here. (Reused as the single safe-Z source; Z_HOME_SAFETY_POINT is
  bypassed for the V-308.)
• SOFTWARE_POS_LIMIT.Z — the reachable Z range (the controller travel registers are clamped to
  the hardware travel via qTMN/qTMX).

Behavior notes

• Pass-through mm — the controller's native mm is Squid's Z mm (frame is 0..7, matches
  SOFTWARE_POS_LIMIT.Z); no offset.
• home(z) references only if not already referenced (no redundant FRF sweep), then moves to
  the retracted position. home_xyz() retracts Z before the XY sweep (the voice coil has no
  self-locking).
• zero(z) is an inert warning (V-308 uses an absolute optical reference).
• Continuous closed-loop drive (~nm encoder), so Z-step quantization is effectively a no-op.

Safety

The voice coil has no self-locking: referencing and bring-up move the stage, and servo-off
lets a vertical stage drift. Run bring-up with the objective clear; fence Z via
SOFTWARE_POS_LIMIT.Z. autozero() (weight compensation) is implemented but not auto-wired.

Testing

tests/squid/ — 96 passed (26 new V-308 tests), simulated; black clean.

Status / follow-ups

• Simulated-tested only. The serial path can't run on macOS dev (custom-VID FTDI has no COM
  port); end-to-end serial verification happens on the Linux scope. GCS protocol confirmed over
  libusb (*IDN? → C-414.13030, fw 1.003).
• Open hardware item: confirm which travel end is "up" (objective-clear) on the physical mount;
  if reversed, fix at the controller/mounting level, not in pi.py.
• Deferred (non-blocking): PI_FOCUS_REFERENCE_ON_STARTUP=False to avoid the bring-up reference
  move; analog / wave-generator V-308 modes; the V-308 as a separate fast-fine-Z on top of a coarse
  Z (this PR makes it the main Z).

🤖 Generated with Claude Code

[hongquanli]

Hardware test evidence — V-308 / C-414 Z control verified ✅

Tested on a Toupcam + Cephla-XY microscope with the target hardware attached: PI C-414.13030 (S/N 425001492, fw 1.003) driving a V-308 voice-coil focus, connected via FTDI VCP.

Z control works end-to-end

Exercised the PR's own driver + adapter against the real controller (referenced with the objective clear):

Path	Test	Result
C414FocusStage	Absolute moves 1→3→5→3→1 mm	9/9 in tol, max err 71 nm
C414FocusStage	Relative ±10 µm, ±100 µm	within 70 nm
PIFocusStage (Squid API)	move_z_to / move_z / get_pos	6/6, max err 38 nm
PIFocusStage	home(z) → retract, no re-reference	✅
Referencing	FRF sweep; skipped when already referenced	✅ (cache logic)
GUI Z-step grid	z_mm_to_usteps(1.0)	100000 → 10 nm ✅

Hardware reports qTMN/qTMX = 0..7 mm travel; references near ~0.3 mm.

Findings addressed in 42479325

1. connect_serial() failed on Linux (blocker). It used gcs.ConnectRS232(), which routes through PI's proprietary libpi_pi_gcs2.so — not provided by pip install pipython (OSError: libpi_pi_gcs2.so not found). Switched connect_serial/connect_tcpip to pipython's pure-Python PISerial/PISocket gateway (no DLL). Also deferred GCSDevice creation out of __init__ (the DLL-backed device registered a connection callback that later crashed against the missing DLL). connect_usb keeps the DLL path (USB requires it). Verified on hardware via the PR's own connect_serial().
2. udev bind didn't apply on install. 98-pi-c414-bind.rules matches ACTION=="add", but udevadm trigger defaults to action=change, so an already-connected C-414 got no /dev/ttyUSB*. Changed the setup step to udevadm trigger --action=add.
3. Serial port permission. The /dev/ttyUSB* node came up 0660 root:dialout; the latency ATTR sits on the usb-serial device, not the tty node. Added a SUBSYSTEM=="tty" … MODE="0666" rule so it's usable without dialout membership / re-login.
4. Sim fidelity (cosmetic). _SimulatedC414 travel ±3.5 → 0.0–7.0 mm to match the V-308's reported range. Existing simulated unit-test assertions still hold.

Machine .ini (gitignored) enabled the stage via the stable FTDI serial number, resolved to a port by the bind rule.

Verified with Claude Code.