Metadata-Version: 2.4
Name: ws6-200-wvm
Version: 0.2.0
Summary: Python client for the HighFinesse WS/6-200 wavemeter (wlmData wrapper).
Author-email: Marcello Laurel <mlaurel@mit.edu>
Keywords: highfinesse,laser,wavemeter,wlmdata,ws6
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.13
Requires-Dist: pydantic>=2
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# ws6-200-wvm

Python client for the HighFinesse WS/6-200 wavemeter (and other WS/6
variants that share the same `wlmData` library).

The HighFinesse stack is a shared-memory client/server: the vendor's
`wlm_ws6` application owns the USB device and publishes measurements
into shared memory; this package loads `wlmData.dll` (Windows) or
`libwlmData.so` (Linux) via `ctypes` and reads from that shared memory.
Reads are microsecond-scale memory operations.

**Constraints:**

- The vendor library is **x86_64 only** — this package will not work
  on a Raspberry Pi / ARM host. Run on a Windows or Linux x86_64 PC
  attached to the wavemeter over USB.
- The vendor server (`wlm_ws6.exe`) must be running locally. On Windows,
  this package can autostart it for you (default).

## Install

```
pip install ws6-200-wvm
```

or with [uv](https://docs.astral.sh/uv/):

```
uv add ws6-200-wvm
```

## Prerequisites

1. **HighFinesse "Wavelength Meter" application** installed from the
   USB stick that shipped with your WS6. The installer is
   calibration-keyed to your unit's serial, so use the one for *your*
   device. It places `wlmData.dll` under `C:\Windows\System32\` and
   `wlm_ws6.exe` somewhere on PATH.

   Linux equivalent: request the Linux bundle from HighFinesse
   support; it installs `libwlmData.so` and a `wlm_ws6` daemon binary.

2. **USB connection** from the host to the WS6, and the wavemeter
   powered on. First time, run the vendor "Wavelength Meter" GUI to
   confirm it sees the device.

If you are integrating this package into a larger application and need
to write an adapter, see [docs/wrapping.md](docs/wrapping.md).

## Quickstart

```python
from ws6200_wvm import Ws6200

with Ws6200(channel=1) as wm:
    print(wm.idn)
    print(wm.measure_frequency_thz(), "THz")
    print(wm.measure_wavelength_nm(), "nm")
```

Or without the context manager:

```python
wm = Ws6200(channel=1)
wm.connect()
try:
    freq_thz = wm.measure_frequency_thz()
finally:
    wm.disconnect()
```

### Configuration

`Ws6200Config` is a pydantic model that you can populate from YAML /
JSON / env vars and call `.make()` on to get a driver:

```python
from ws6200_wvm import Ws6200Config

cfg = Ws6200Config(channel=1, autostart_server=True, start_timeout_s=10.0)
wm = cfg.make()
```

Fields:

| field              | default | meaning                                                                |
| ------------------ | ------- | ---------------------------------------------------------------------- |
| `channel`          | `1`     | 1-indexed switcher channel.                                            |
| `dll_path`         | `None`  | Override path to `wlmData.dll` / `libwlmData.so`. Auto-detected if unset. |
| `autostart_server` | `True`  | On Windows, launch `wlm_ws6.exe` via `ControlWLMEx` if not running.    |
| `start_timeout_s`  | `10.0`  | Seconds to wait for `wlm_ws6` to come up.                              |

## CLI

A console script `ws6200-wvm` is installed for first-install smoke
tests:

```
ws6200-wvm measure                       # one reading, then exit
ws6200-wvm measure --watch --interval 0.5
ws6200-wvm measure --channel 2 --dll-path "C:\path\to\wlmData.dll"
```

## Errors

Library / setup problems raise `RuntimeError`:

- "could not load HighFinesse wlmData library …" — install the vendor
  software, or pass `dll_path=...` to point at it.
- "HighFinesse wlm server is not running …" — start `wlm_ws6.exe`
  manually, or pass `autostart_server=True` on Windows.

Wavemeter-reported measurement errors raise `WavemeterError` with a
label from `wlmData.h`:

| label              | meaning                              |
| ------------------ | ------------------------------------ |
| `noval`            | No measurement available yet         |
| `nosig`            | No input signal                      |
| `badsig`           | Signal present but uncomputable      |
| `under`            | Underexposed                         |
| `over`             | Overexposed                          |
| `nowlm`            | No wavemeter server running          |
| `outofrange`       | Outside calibrated range             |
| `noresponse`       |                                      |
| `div0`             |                                      |
| `outofresolution`  |                                      |

`NotConnectedError` (subclass of `WavemeterError`) is raised if you
call a `measure_*` method before `connect()`.

## Calibration

HighFinesse units use an internal reference but the factory absolute
calibration drifts over time. Check the recommendation that came with
your unit (typically 12–24 months) and send it back in cycle to keep
the 200 MHz absolute spec.

