feat(scope): json config-driven instrument creation

[nhschwab]

Closes INSTRO-578. Implements the schema defined in INSTRO-564.

Adds config-driven workflow for InstroScope. Includes a rename of the existing ScopeConfig to ScopeState to reserve ScopeConfig for the config driven workflow, matching existing instrument configs.

Summary

• Add instro/scope/config.py with the Pydantic ScopeConfig model, its ChannelConfig / AcquisitionConfig / TriggerConfig blocks, VisaDriverConfig, and SCOPE_VENDOR_REGISTRY for the three registered drivers. Validators enforce the schema rules: channel keys and trigger.source within num_channels, average_count requires AVERAGE mode, no duplicate measurements, and timing requires at least one polled measurement.
• Add InstroScope(config=..., autostart=False) construction from a ScopeConfig, dict, or JSON path, mirroring InstroPSU / InstroDMM. Direct construction is unchanged.
• Register each channel's measurements as background daemon functions at construction. autostart=True requires at least one; a manual start() with none registered logs a warning rather than raising, since starting the daemon is also how the in-memory channel buffer gets created.
• On open(), apply the config through the public setters in the order the hardware needs, then sync_configuration(), then log one warning per field the instrument reports differently from the config (SNAP_REL_TOL = 1%, SNAP_ABS_TOL = 1e-9). A mid-apply failure closes the driver and re-raises, and the next open() re-attempts the apply. Reopening without closing does not reapply.
• Rename the tracked-state dataclasses ScopeConfig / ChannelConfig / TriggerConfig to ScopeState / ChannelState / TriggerState so the Pydantic models keep the <Category>Config names. sync_configuration() now returns ScopeState. InstroScope has no documented external users yet, so this ships without a major bump (see INSTRO-564 Decision 3).

Apply order on open()

Each step exists because a shipped driver needs it:

1. Per channel: coupling, probe_attenuation, then vertical_scale, vertical_offset. The probe factor rescales the channel's probe-referred scale and offset on all three drivers.
2. trigger: source, type, slope, level, mode.
3. run() if acquisition.start_acquisition_on_open is set, so the configured trigger is in place when acquisition starts, and so the next step lands on a running scope.
4. acquisition: average_count before mode (Siglent's mode command carries the count inline; Siglent only applies ACQW while acquiring), then horizontal_scale.
5. setup_measurement() for every configured measurement, so Tektronix has its slots installed before the first poll.
6. sync_configuration() and the snapped-value warnings.

Also in this PR

• Keysight1200X.get_acquisition_mode keyed its read-back map on long-form names while the instrument answers with the 4-character short form (AVER, HRES), so AVERAGE and HIGH_RESOLUTION read back as NORMAL. Pre-existing, surfaced by the new post-open check.
• InstroScope.open() / close() now log lifecycle at info level like the sibling HALs, and close() stops the daemon and publishers before closing the driver (scope was the only HAL doing it the other way round), adopting ELoad's flag-reset-then-finally shape.

Deferred

• Publisher leak when the constructor raises after resolve_scope_from_config has built publishers: Publisher resource leak when build_publisher raises mid-list in config resolution #418 (INSTRO-588), shared by every instrument.
• Reopen after close() with attached publishers: INSTRO-606, shared by every instrument.
• Siglent TRMD handling: fix(scope): SiglentSDS1000XE run() and set_acquisition_mode() fight over TRMD run state #494 (INSTRO-626), shared root cause for two driver bugs. run() writes TRMD AUTO, overwriting a configured trigger.mode: NORMAL that the snap check cannot catch since trigger fields are not read back; and set_acquisition_mode() is dropped by the instrument while stopped, so acquisition.mode without start_acquisition_on_open on a non-running Siglent does not take effect (the snap check does surface that one). Both are driver fixes and stay out of this PR.

Docs and examples

• docs/guides/instrumentation/oscilloscope.mdx: new "From a JSON Config File" section, config / autostart parameters, apply-order and lifecycle updates, method-reference row.
• docs/reference/src/instruments/scope.md: include instro.scope.config.
• examples/scope/scope_config.py + scope_config_keysight_1200x.json, with the generated example page and nav entry.
• AGENTS.md: note the scope config module and the *State naming.

Test plan

• just check-python (ruff format, mypy, ruff check) passes
• uv run pytest tests packages passes
• just check-examples reports no drift
• tests/scope/test_scope_config.py covers validation rules, the hardware apply order, the snapped-value warning and its rounding tolerance, rollback and re-apply on a failed open, the start() warning, autostart, and vendor-registry drift
• tests/scope/test_instro_scope.py covers the Keysight short-form acquisition-mode read-back
• Hardware smoke against a Keysight 1200X and a Siglent SDS1000X-E with the example config (not run; no scope attached). The apply-order fixes are wire-ordering changes that mocks cannot verify.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
instro	🟢 Ready	View Preview	Sep 3, 2026, 3:38 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[claude]

Claude finished @nhschwab's task in 5m 2s —— View job

---

Review

• Gather context (PR diff, AGENTS.md conventions)
• Review instro/scope/config.py (new Pydantic config module)
• Review instro/scope/scope.py (config-driven open(), apply order, rollback)
• Review instro/scope/types.py rename (ScopeState/ChannelState/TriggerState)
• Review tests (tests/scope/test_scope_config.py, test_instro_scope.py)
• Review docs/examples sync
• Post inline findings + overview

Overview: Clean port of the InstroPSU/InstroDMM config-construction pattern to Scope — resolve_scope_from_config, VisaDriverConfig, and the vendor registry all mirror instro/psu/config.py exactly, and the rename to ScopeState/ChannelState/TriggerState correctly frees up ScopeConfig/ChannelConfig/TriggerConfig for the Pydantic models without touching the <Category>Config convention. The open() rollback (_apply_config failure → close driver → re-raise, gated by _config_applied so a bare reopen doesn't reapply) matches DMM's existing _apply_measurement_config shape. The channels → acquisition → trigger → sync → warn → run ordering in _apply_config is exactly what's tested in test_scope_config.py::test_open_applies_config_in_order_then_syncs_then_runs, and model validators (_channels_within_num_channels, _timing_requires_measurements, average_count requiring AVERAGE mode) catch the config-shape errors ahead of time rather than at apply time. Docs/examples/nav are all updated in step per AGENTS.md's table.

One inline note on lifecycle logging left below. No correctness bugs found; didn't run tests/lints per review scope (static-only).

[greptile-apps]

Greptile Summary

The PR adds strict JSON/dict-based oscilloscope construction, applies configured channel, acquisition, and trigger state during open, and registers configured measurements for background polling.

• Introduces the Pydantic scope configuration schema and registered VISA-driver resolution.
• Separates declarative configuration models from tracked ScopeState dataclasses.
• Adds open-time application, read-back warnings, optional acquisition start, documentation, examples, and tests.

Confidence Score: 3/5

The PR should not merge until Tektronix measurements are prepared before acquisition and config publishers are closed when construction fails validation.

The new open sequence can begin Tektronix acquisition before required measurement slots exist, and the constructor can abandon already-open publisher resources on its autostart validation path.

Files Needing Attention: instro/scope/scope.py, instro/scope/config.py

Important Files Changed

Filename	Overview
instro/scope/config.py	Adds strict scope configuration models, driver resolution, and eager publisher construction; registry-based imports remain constrained to fixed entries.
instro/scope/scope.py	Adds config-driven construction and open-time application, but starts Tektronix acquisition before measurement setup and misses publisher cleanup for an early validation failure.
instro/scope/types.py	Renames tracked configuration dataclasses to state-oriented names without changing their data model.
tests/scope/test_scope_config.py	Thoroughly covers validation and generic application order but does not exercise Tektronix pre-acquisition measurement setup or early publisher cleanup.
docs/guides/instrumentation/oscilloscope.mdx	Documents config construction, lifecycle, validation, polling, and state synchronization behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Load and validate ScopeConfig] --> B[Resolve driver and publishers]
  B --> C[Construct InstroScope]
  C --> D[Register background measurements]
  D --> E[open driver]
  E --> F[Apply channel settings]
  F --> G[Apply acquisition settings]
  G --> H[Apply trigger settings]
  H --> I[Sync and compare hardware state]
  I --> J{Start acquisition on open?}
  J -->|Yes| K[run]
  J -->|No| L[Return from open]
  K --> L
  L --> M{autostart?}
  M -->|Yes| N[Start background daemon]

Loading

Prompt To Fix All With AI

### Issue 1
instro/scope/scope.py:427-428
**Acquisition precedes measurement setup**

When a Tektronix config enables `start_acquisition_on_open` and background measurements, `run()` starts acquisition before those measurements create their required instrument slots, causing initial background polls to return unavailable or stale results until a later acquisition processes the slots.

### Issue 2
instro/scope/scope.py:363-367
**Validation leaks publisher resources**

When `autostart=True` is used with configured publishers but no background measurements, this validation raises after the publishers have opened their file handles or write streams but before the cleanup handler, leaving those resources open with no constructed scope available to close them.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(scope): JSON config-driven instrume..." | Re-trigger Greptile}