Metadata-Version: 2.4
Name: dt5800
Version: 1.0.3
Summary: Python binding of the DT5800 SDK: control of the CAEN DT5800 / DT5800D Digital Detector Emulator
Author-email: Nuclear Instruments <support@nuclearinstruments.eu>
License: MIT
Project-URL: Homepage, https://gitlab.nuclearinstruments.eu/public-repo/dt5800/dt5800-sdk
Project-URL: Documentation, https://public-repo.pages.nuclearinstruments.eu/dt5800/dt5800-sdk/
Project-URL: Source, https://gitlab.nuclearinstruments.eu/public-repo/dt5800/dt5800-sdk
Project-URL: Issues, https://gitlab.nuclearinstruments.eu/public-repo/dt5800/dt5800-sdk/-/issues
Keywords: DT5800,DT5800D,DPPE,CAEN,Nuclear Instruments,detector emulator,pulser,nuclear physics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: numpy
Requires-Dist: numpy; extra == "numpy"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# dt5800: Python binding of the DT5800 SDK

Control the **CAEN DT5800 / DT5800D Digital Detector Emulator** (Nuclear Instruments, front
panel "DPPE") from Python: energy (fixed, spectrum, isotopes, sequences), pulse shape (fast
exponential, digital RC, custom shapes, multi-shape), time base, pile-up and dead time,
noise, interference, baseline drift, reset preamplifier, correlation of the two channels
with the delay line, digital I/O, run control, waveform generator, Peltier, statistics and
the signal monitor. The package calls the native DT5800 library (`dt5800.dll` /
`libdt5800.so`) through `ctypes`. A built-in simulator (`sim://`) lets you develop and test
without hardware.

## Installation

```
pip install dt5800
```

The wheels for Windows x64 and Linux x86-64 / aarch64 (glibc 2.34+) include the native
library. Python 3.8 or later. There are no mandatory dependencies: `pip install dt5800[numpy]`
gets numpy arrays from the read functions with `as_numpy=True`. Every function also takes
numpy arrays as input.

### USB driver

The instrument is reached over USB 2 through its FTDI FT2232H and FTDI's D2XX driver:

- **Windows**: FTDI's CDM driver, installed by the DT5800 SDK setup
  (`DT5800-SDK-Setup-<version>.exe`) or downloaded from FTDI (any recent version works).
  It provides `ftd2xx.dll`, which the library loads at run time.
- **Linux**: the wheel includes FTDI's D2XX library (`libftd2xx.so`, next to
  `libdt5800.so`). The **udev rule must still be installed**. It gives every user access to
  the instrument and detaches the kernel's `ftdi_sio` driver from the DT5800 only. The rule
  is installed by the `dt5800-sdk` package (`apt install dt5800-sdk` / `dnf install
  dt5800-sdk`). It is also in the SDK sources: copy `sdk/cpp/udev/60-dt5800.rules` to
  `/etc/udev/rules.d/`, then run `sudo udevadm control --reload-rules` and plug the
  instrument in again.

`dt5800.d2xx_info()` tells which D2XX library was loaded, or why none could be.
`dt5800.supported_buses()` lists `Bus.USB` only when it loads. Other FTDI devices on the
same PC (USB-serial adapters, other instruments) are never opened: the library lists and
opens only the devices whose USB description is a DT5800's.

### Another build of the library

With the source distribution, or to use another build, point `DT5800_LIBRARY` at the
library (full path of `dt5800.dll` / `libdt5800.so`). Otherwise the library is looked up
in the package (`dt5800/_native/`), then by the system loader.

## Quick start

```python
import dt5800

print(dt5800.version())
for d in dt5800.enumerate(dt5800.Bus.USB):
    print(d.serial, d.address, d.description)

with dt5800.Device("sim://") as dev:            # or "usb://", "usb://<FTDI serial>"
    print(dev.info.model_name, dev.info.serial)
    ch = dev.channel(0)
    ch.set_energy_fixed(16000)                  # LSB, 0..32767
    ch.set_shape_exponential(dt5800.ShapeMode.AUTO, rise_ns=50, decay_ns=10000)
    ch.set_timebase(dt5800.TimebaseMode.POISSON, 10000)
    ch.enable()
    print(ch.stats())
```

Spectra come from files of the DT5800 software (`load_values`, `process_spectrum`), from
the Spectrum Editor (`spectrum_from_peaks`), or from the isotope database
(`isotope_lines("Co-60")`, `spectrum_from_lines`). Program them with
`Channel.program_spectrum`.

Errors raise subclasses of `dt5800.Dt5800Error` (`OutOfRangeError`,
`InvalidParameterError`, `NoDataError`, `NotFoundError`, `DeviceTimeoutError`,
`InvalidHardwareError`, ...). Each one carries `.status` and `.message` (the text of
`dt5800_last_error`).

## Examples

The `examples/` folder has a runnable script for each feature. Each takes the address as
its first argument (default `sim://`):

| Script | What |
|---|---|
| `01_list_and_info.py` | instruments, identity, activation, climate, calibration |
| `02_pulser.py` | fixed amplitude at a constant rate, statistics |
| `03_spectrum.py` | a spectrum from peaks or from a file, Poisson rate, loop-back histogram |
| `04_monitor.py` | signal monitor, statistics, loop-back histogram |
| `05_awg.py` | function generator and arbitrary waveform |
| `06_firmware_info.py` | `.NIU` firmware package, FPGA update (simulator, or `--update`) |
| `07_isotopes.py` | Co-60 + Cs-137 from the isotope database |
| `08_noise_and_baseline.py` | noise, interference, baseline drift, reset preamplifier |
| `09_correlation.py` | delayed copy, partial correlation, Peltier |

```
pip install -r examples/requirements.txt
python examples/02_pulser.py usb://
```

## Firmware

```python
info = dt5800.firmware_file_info("DT5800D_2_4.NIU")
dt5800.fpga_update("usb://FT5800AB", "DT5800D_2_4.NIU",
                   progress=lambda stage, f: print(stage, f"{f:.0%}"))
# then power cycle the instrument
```

## Documentation

User guide and API reference: <https://public-repo.pages.nuclearinstruments.eu/dt5800/dt5800-sdk/>

Source: <https://gitlab.nuclearinstruments.eu/public-repo/dt5800/dt5800-sdk>. MIT License.
