Device layer: extract hardware-agnostic BaseDeviceLayer + shared HTTP contract (split diSPIM monolith)

[subindevs]

Spun off from #14, which consolidated the device layer into a single process.
That refactor is complete, but it left gently/hardware/dispim/device_layer.py
as a ~3,000-line monolith. The goal here is not just "break up a big file" — it's
to split it along the hardware-agnostic vs. diSPIM-specific line, so a second
hardware plugin (e.g. twophoton) reuses the plumbing instead of reimplementing it.

Context: what's already agnostic

The agent/harness already program against hardware-agnostic interfaces — the
Microscope/HTTPMicroscope base (harness/microscope.py), HardwareProtocol +
CAPABILITIES, and the create_device_layer() / create_client() factories. The
boundary is correct. The problem is that a lot of hardware-independent plumbing
is trapped inside the diSPIM plugin, and a new hardware would have to rewrite it.

1. Extract a hardware-agnostic BaseDeviceLayer

Hoist the reusable scaffolding out of device_layer.py into a base class (in
core/harness, building on the existing core/service.py:Service). Generic,
not diSPIM-specific:

• aiohttp routing / Service lifecycle wiring
• SSE device-state streaming machinery (pollers + broadcast/debounce)
• plan queue + executor
• /api/microscope/execute plan-dispatch translation
• SAM / detection endpoint scaffolding

A hardware plugin should subclass this and only supply device/plan specifics.

2. Define the HTTP wire contract once

The /api/* contract (/api/microscope/execute, /api/devices/stream,
/api/detect_embryos, …) is currently defined only inside diSPIM and re-parsed by
hand in three places: dispim/client.py, app/device_state_monitor.py,
harness/microscope.py. Pin it down in one shared schema/dataclass module so
client and server agree by construction.

3. Keep diSPIM-specific code in the plugin

What stays in gently/hardware/dispim/: MMCore init, Ophyd device definitions,
Bluesky plans, dual-view/galvo specifics, the concrete SAM detector, accessory
devices (SwitchBot, temperature, bottom camera).

4. Purge dead RPyC references

Stale comments/handling from the old RPyC transfer path:

• gently/hardware/dispim/devices/acquisition.py:216
• gently/hardware/dispim/plans/calibration.py:524

Scope guard (deliberately deferred)

There is exactly one hardware plugin today; twophoton is aspirational. To avoid
abstracting the wrong joints from a sample size of one: extract only the obviously
generic plumbing now (1, 2, 4). Defer a "universal" device-layer abstraction until a
real second hardware exists to validate the seams (rule of three).

[pskeshu]

It would be immensly helpful here if we can "assume" a second microscope - at least in terms of a dummy micro-manager config file. I have asked for it internally from folks at Janelia - but if that does not work out, we can assume the anisotropy microscope config I had used from TIFR. https://github.com/ndsystems/hard-link/blob/main/hard-link/mmconfigs/Bright_Star.cfg and https://github.com/ndsystems/deepthought/blob/main/deepthought/hardware/devices.py

Perhaps this could be a dummy second microscope, and use it as a test case for the idea of generalizability of the current refactor of an architecture that we are planning, until a time we can validate it on a real second microscope.

Thoughts? @schneidermc

[pskeshu]

if @ceej640 is interested, perhaps the AO-dispim could also be described as a second microscope. We could just to define the basic devices to start with - perhaps just the cameras, some of the stages, and leave out the critical stuff.

[ceej640]

Thanks for tagging me. I’m interested in using the AO-adiSPIM as a second microscope shape for this refactor, but I would start with an offline/dummy profile or a non-critical device inventory rather than live hardware control.

One important correction: my system is an AO-adiSPIM, not an AO-diSPIM. A default diSPIM has 45° / 45° views, with the cameras/objectives physically arranged around that geometry. The AO-adiSPIM has asymmetric views, approximately 56.7° / 33.3°. Because the system is asymmetric, the two physical views have different effective magnifications, pixel sizes, and fields of view by definition.

The Gently diSPIM unit also has a specific optical detail that should be considered: a C60-CUBE-135 mirror cube on each side rotates the image to 0°, as if each camera were mounted in a conventional microscope. That likely helps maximize usable camera area with the additional image-splitting optics for dual-color acquisition within a single frame. My AO-adiSPIM does not have those rotation optics or the splitter.

From reading the current Gently code, the diSPIM plugin appears to assume this standard/Gently-specific view handling in several places. Dual-view images are treated as equal-width stitched halves, often described in code comments as physical View A / View B; focus/vision helpers often select the brighter half; coordinate conversion uses default pixel-size/magnification values; and I do not see an explicit view-geometry model for per-view angle, per-view pixel scale, camera orientation, splitter layout, or camera-space-to-lab-space transforms.

One ambiguity I noticed is that “side-by-side” images are not explicitly typed. The code does not appear to declare whether a side-by-side frame contains physical View A/B, spectral splitter channels, or another camera layout. That matters because physical AO-adiSPIM View A and View B are not geometrically equivalent: equal-width image halves would not imply equal physical scale or field of view.

I am not fully sure how much image roll itself matters for all vision paths. Simple detection/focus/embryo-presence checks may be mostly rotation-tolerant. But developmental perception does seem potentially sensitive: the code renders “three orthogonal views” as XY/YZ/XZ projections, and the C. elegans perception prompt gives biological meaning to vertical/horizontal structure in XZ. If the AO-adiSPIM volume is oblique in camera space relative to lab-frame XYZ, then generated XZ/YZ projections may not mean the same thing as on the Gently diSPIM. That could plausibly fool perception unless the volume is deskewed/reoriented or the prompt/model is calibrated for that geometry.

The stage naming is another useful test case. The current code maps ZStage:V:37 to DiSPIMFDrive and treats it as a SPIM-head height/F-drive device. My understanding is that both the Gently diSPIM unit and the AO-adiSPIM use an FTP stage with a fixed SPIM head, not a moving-head F-drive. It may be that Micro-Manager/ASI maps the FTP master axis V into an F-drive-like role because it serves a similar function. However, the safe height range depends on the physical mounting height of the fixed head, which is very likely different between the two systems. For AO-adiSPIM, V/W axis roles, coupling, zero convention, and safe ranges should be explicit rather than inherited from the current DiSPIMFDrive semantics.

So for #50, AO-adiSPIM would be a useful acceptance test because it shares much of the same hardware family while breaking several hidden assumptions: scanner/camera/stage overlap, but different view geometry, different image layout, asymmetric objective angles, asymmetric pixel scale/FOV, and different physical safe-height envelope for the FTP stage. I’d suggest the hardware profile require explicit declarations for device identity, physical role, units, per-axis safety envelope, firmware-vs-software limit source, homing/zero convention, view angle/geometry, per-view pixel size and FOV, camera orientation/affine transform, frame layout, tile identity, channel identity, and whether each motion/actuation path is enabled or read-only.

For a first pass, I’d define only the safe/common pieces: cameras, scanner, stage readout, piezos if clearly mapped, and read-only/no-op placeholders for AO-specific devices. I would leave critical motion disabled until the V/W axis mapping, physical limits, and view transforms are explicit and validated.

[pskeshu]

That's a really good and detailed analysis, @ceej640! The AO-adiSPIM integration already sounds super promising, and I'm very excited about this direction.

@subindevs how can we refactor the device layer at the most basic, high level so that @ceej640 can effectively start working on an AO-adiSPIM device for Gently?

[pskeshu]

This is great — thanks again, @ceej640. To make this concrete, the next question is how we split the work so that both @ceej640 and @subindevs can move in parallel, and how we land the abstractions in a way I can validate on the diSPIM to confirm nothing regresses there.

Roughly, I see the work breaking into these pieces:

1. Generalizing the device layer itself — the core abstraction work.
2. Where the second-microscope code lives — establishing where an AO-adiSPIM (and future scopes) plug in.
3. Cataloguing and correcting the wrong assumptions — @ceej640 already has the list and is best placed to identify and correct them, since they're fundamentally microscopy-domain decisions.
4. A second pass at the abstraction once those assumptions are corrected — the corrections will likely reshape the initial design.
5. Multiple iterations overall — I expect we'll need several rounds of abstraction/generalization as we actually build against it, rather than getting it right in one shot.

Throughout, I'd like to keep validating each stabilized layer on the diSPIM so we catch any regressions early.

Curious to hear from you both on how you'd like to approach this.