Add LI-COR Odyssey Classic + DeviceCard for instrument provenance

[vcjdeboer]

This PR adds the LI-COR Odyssey Classic (model 9120) infrared imaging system as a new device under the v1b1 capability architecture. It also introduces three new capabilities the Odyssey needs (Scanning, ImageRetrieval, InstrumentStatus) and proposes a small architectural addition (DeviceCard) for instrument identity / provenance metadata.

What's added

Device — pylabrobot/li_cor/odyssey/

• OdysseyDriver — pure HTTP transport over Basic Auth. Public surface is setup / stop / post / get / get_bytes (each with with_retry=True opt-in) plus serialize / from_env and two non-capability admin operations (shutdown_instrument, get_instrument_info). No protocol logic on the driver.
• OdysseyScanningBackend, OdysseyImageRetrievalBackend, OdysseyInstrumentStatusBackend — own all CGI protocol: form encoding, redirect orchestration, <Error shorterror=\"...\" /> parsing, the 7→1 initialization countdown, HTML scraping for status / progress.
• OdysseyChatterboxDriver plus three *ChatterboxBackend classes sharing an _OdysseyChatterboxState — runs the full lifecycle without an instrument (CI / notebooks).
• OdysseyClassic(Device, HasDeviceCard) wires everything; stop_and_save() is a device-level orchestration helper (it spans the three capabilities).
• Dual-base errors (OdysseyScanError(OdysseyError, ScanningError) etc.) so callers can except on either the vendor axis or the capability axis.

Capabilities — pylabrobot/capabilities/scanning/

Umbrella package mirroring plate_reading/'s shape:

capabilities/scanning/
├── scanning/             # configure / start / stop / pause / cancel
├── image_retrieval/      # list_groups / list_scans / download
└── instrument_status/    # read_status → InstrumentStatusReading

Each subpackage is a standard Capability + Backend ABC pair. Scanning accepts backend_params: Optional[SerializableMixin]; vendors provide a typed BackendParams subclass (OdysseyScanningParams here). InstrumentStatusReading is a generic state snapshot (state / current_user / progress / time_remaining / lid_open) — not Odyssey-specific.

DeviceCard — pylabrobot/device_card.py

A machine-readable description attached to a Device:

DeviceCard
├── name, vendor, model
├── identity     # PIDInst Handle URI, landing page, friendly name (per-unit)
├── capabilities # spec sheets — operating ranges, supported settings
└── connection   # protocol, port, auth, discovery

Two-tier: a model-base card ships with the device package (ODYSSEY_CLASSIC_BASE); each deployment populates an instance card with its unit's identity. base.merge(instance) produces the effective deployed card.

Devices opt in via HasDeviceCard — same shape as HasLoadingTray, a Device-attribute marker mixin. Existing devices are unaffected.

The motivation is FAIR / provenance: a TIFF or PNG written by the instrument can carry the PIDInst Handle URI in its metadata, so a scan lifted out of its surrounding context still resolves back to the unit it came from. pylabrobot/li_cor/odyssey/tagging.py is the canary that consumes this — it accepts either a DeviceCard or a plain identity dict and embeds the JSON in TIFF tags 270 / 305.

Design notes worth flagging

Three capabilities, one implementation each (P3)

The v1b1 norm is to extract a Backend ABC only when a second device needs the same operation. This PR ships three new ABCs with one implementation each.

The honest framing: Odyssey is the first; Bio-Rad ChemiDoc, ProteinSimple FluorChem, GE Typhoon, and similar flatbed fluorescence imagers fit the same shape, but those drivers don't exist in PLR yet. The Scanning / ImageRetrieval / InstrumentStatus split reflects real differences in their lifecycles (scanning is exclusive control; image retrieval is a read on persistent state; status is generic device-state polling) — but I'm open to merging them if you'd prefer one capability for now and we extract later.

`OdysseyChatterboxDriver` exists only as a placeholder

Odyssey doesn't do runtime discovery (no firmware queries to enumerate installed modules) so the chatterbox lives at the backend tier per the prose. But `Device.init` requires a `Driver` instance, so there's a minimal `OdysseyChatterboxDriver(OdysseyDriver)` that overrides `setup`/`stop` to no-ops. The chatterbox backends don't call it; they use a shared `_OdysseyChatterboxState`.

P-06 — driver is the wire, backend is the protocol

The driver is genuinely transport-only. `configure_scan`, `start_scan`, `download_tiff`, `get_status`, `_parse_status_html`, `_tiff_xml`, `_jpeg_xml` — all the protocol — lives in the backends. The first commit had protocol on the driver; the third commit refactored it. I left the history intact so the diff between commits 1 and 3 illustrates the shape of the cleanup.

Tests

23 tests, all passing:

```
pylabrobot/capabilities/scanning/scanning/scanning_tests.py (4 tests)
pylabrobot/capabilities/scanning/image_retrieval/image_retrieval_tests.py (4 tests)
pylabrobot/capabilities/scanning/instrument_status/instrument_status_tests.py (3 tests)
pylabrobot/li_cor/odyssey/odyssey_tests.py (12 tests)
```

Coverage:

• Capability surfaces in isolation (recording / in-memory / stub backends)
• `need_capability_ready` guard before setup
• DeviceCard model-base defaults, instance merge, capability-spec override
• `HasDeviceCard` `isinstance` discoverability
• `setup_finished` transitions through `setup` / `stop`
• Full chatterbox scan flow (configure → start → completed → download)
• `stop_and_save` orchestration across all three capabilities

`make lint` / `make format-check` / `make typecheck` clean (0 new mypy errors against the v1b1 baseline). `aiohttp` declared as new optional dependency `odyssey = ["aiohttp"]` and added to `all`.

Real-world deployment

The Odyssey driver and DeviceCard pattern are running in production at the WUR Human and Animal Physiology lab. The lab's FastAPI control app, `vcjdeboer/odyssey-app-hap`, is the first reference consumer and demonstrates the full pattern end-to-end including PIDInst-aware identity tagging. The instrument is registered at b2inst as `hdl.handle.net/21.11157/psf97-zv353` and that handle now travels in TIFF tag 270 / PNG tEXt for every scan the lab writes.

Commits

Five commits, each independently reviewable:

1. Add LI-COR Odyssey Classic to v1b1 architecture
2. Add DeviceCard for instrument identity / provenance metadata
3. Refactor Odyssey driver to transport-only (P-06)
4. Tests + cross-capability orchestration cleanup
5. Pre-PR readiness: lint, format, mypy, changelog, optional dep

Happy to split into multiple PRs if the DeviceCard or capability-trio discussions are likely to block the device merge.

[rickwierenga]

thanks for the PR!

high level comments

• DeviceCard is interesting, but definitely a separate PR :) I would want to think more about a standard structure for describing capabilities (probably capabilities describing themselves) rather than the capabilities being capabilities: dict[str, dict[str, Any]]
• the proposed capabilities seem very specific to this particular scanner. What if one does not work with start/stop/pause and listing scans? I think we should focus capabilities on "scientific actions". Here, that seems to be "image a sample and return images in 700/800nm." Are you familiar with similar machines? How do those work and what is shared? Claude tells me "gel/blot/flatbed documentation imager family — same shape as Bio-Rad ChemiDoc, Azure Sapphire, GE Typhoon, ProteinSimple FluorChem" but I do not know. Are these machines always 700 / 800, are they always two lasers? I think most functions here should be abstracted into one image call that does configure > start > poll-to-done > download.
• "The motivation is FAIR / provenance: a TIFF or PNG written by the instrument can carry the PIDInst Handle URI in its metadata, so a scan lifted out of its surrounding context still resolves back to the unit it came from." I like this part a lot, and should definitely be part of all "analytical capabilities". The tagging.py should probably exist elsewhere in PLR than within the Odyssey directory.

[rickwierenga]

configure > start > poll-to-done > download

The backend of course would still have separate methods for these things so your server and other applications like that will still be possible. But in terms of the capability level abstraction, I think a complete action is the best abstraction. A function that the user calls and performs the complete operation. Similar to how the microscope abstraction works

[rickwierenga]

  result = await odyssey.flatbed_imager.image(
    region=Region(x=0, y=0, w=10, h=10),
    channels=[700, 800],
  )
  tiff_700, tiff_800 = (f.data for f in result.frames)