Metadata-Version: 2.5
Name: plesty-lightfield-spectrometer
Version: 0.2.1
Summary: API for the Lightfield Spectrometer Device.
Author-email: Yunshuang Yuan <yunshuang.yuan@fkp.uni-hannover.de>
Maintainer-email: Plesty Development Team <plesty.dev@example.com>
License-Expression: LGPL-3.0-or-later
License-File: COPYING
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: plesty-lib>=0.4.0
Requires-Dist: pythonnet>=3.0.0
Description-Content-Type: text/markdown

# Plesty Lightfield Spectrometer Device

A Plesty device for the Princeton Instruments LightField spectrometer. It
drives LightField through its .NET automation API via `pythonnet`, so the
server runs on the Windows PC the camera is attached to.

Full documentation: `docs/index.md`.

## Setup the server

On the Windows PC where LightField is installed (camera via USB — PIXIS — or
GigE — PyLoN-IR), close all LightField apps: `LightField.exe`,
`AddInProcess.exe` and the LightField Firmware Assistant. Then in a
Terminal/PowerShell:

```bat
git clone https://gitlab.com/plesty/hub/devices/princeton_instruments/lightfield_spectrometer.git
cd lightfield_spectrometer
uv sync
copy .env.example .env
:: edit .env — at least DEVICE_DATA_PATH (where frames go, steerable by clients)
uv run python -m plesty.lightfield_spectrometer --tcp-port 5555
```

Run the server from a **normal (non-elevated) desktop shell** — not over
SSH: Windows OpenSSH gives administrator accounts an elevated token, and
LightField's automation IPC refuses mismatched privilege levels. The
preflight warns when it detects this.

A GigE camera needs no configuration: the preflight finds the link-local
neighbour on the camera NIC, verifies it with a ping, and pins it to `.env`
as `CAMERA_HOST`.

### Starting unattended

Under a supervisor or the bench app there is nobody to answer the
confirmation before an open LightField session is closed, so it refuses and
the server does not start. Pass `--close-lightfield` (or set
`DEVICE_CLOSE_LIGHTFIELD=1`) to close it and discard whatever it has not
saved. The same flag allows ending the LightField Firmware Assistant, which
holds the camera and usually ignores a polite close — check no firmware write
is in progress first, since interrupting one can leave the camera unusable.

## Long runs

LightField's `AddInProcess` keeps a share of every acquisition and never
releases it: about 0.21 MB per acquisition plus 0.037 MB per second of
acquiring, measured on the bench. Idling is free and so are API calls — only
acquiring costs — but overnight that is gigabytes, and no exposure setting
avoids it.

Nothing in this process can free another process's heap, so the server
restarts the LightField session instead, between acquisitions, once the host
passes `DEVICE_RECYCLE_CEILING_MB` (default 1024 MB, `0` to disable). A
restart costs about 22 s and the experiment's settings survive it. See
*Long runs and the automation host* in `docs/index.md`.

## Tests

```bash
uv run pytest                              # hardware-free; what CI runs
uv run python tests/field_test.py          # the instrument, in-process
uv run python tests/field_test_client.py   # the instrument over ZMQ
```

The field tests need hardware and are run by hand — the host tier on the
LightField PC, the client tier from a machine on the instrument network,
against a running server. Run the host tier first; the client tier reads its
report to know what to exercise.

## Regenerate the manuals

```bat
uv run plesty manual generate . --with-pdf
```
