Metadata-Version: 2.4
Name: smartmca
Version: 0.1.9
Summary: Smart MCA for DT5771 Python Library
Project-URL: Homepage, https://gitlab.nuclearinstruments.eu/public-repo/dt5771/smart-mca-python-library
Project-URL: Bug Tracker, https://support.nuclearinstruments.eu
Author-email: Nuclear Instruments <info@nuclearinstruments.eu>
License-Expression: MIT
License-File: LICENSE
Keywords: CAEN,DT5771,MCA,Nuclear Instruments,firmware,fpga
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.5
Requires-Dist: requests
Description-Content-Type: text/markdown

# SmartMCA Python Library

High-level Python client library to control Nuclear Instruments Smart Digital MCA firmware (e.g. DT5771) over an HTTP/REST interface.

It provides typed configuration objects, parameter validation, and convenience helpers for:

- Analog front-end configuration
- Digital I/O and trigger routing
- MCA processing (trigger, energy, baseline, pile-up rejection)
- Acquisition presets, MCS and statistics
- Oscilloscope readout and histogram retrieval

> The full user documentation is available [here](https://public-repo.pages.nuclearinstruments.eu/dt5771/smart-mca-python-library/)

---

## Features

- Simple connection handling (login/logout, cookies, error reporting)
- Pythonic configuration objects mirroring firmware registers
- Enumerations for all categorical parameters (trigger modes, energy algorithms, etc.)
- High-level acquisition control (start/stop/reset, presets, auto-save)
- Readout of MCA statistics, MCS data, oscilloscope traces, histograms
- Can be used both from a remote PC and from the embedded Jupyter environment on the instrument

---

## Installation

### From PyPI

```bash
pip install smartmca
````

### From source (this repository)

```bash
git clonehttps://gitlab.nuclearinstruments.eu/public-repo/dt5771/smart-mca-python-library.git
cd smart-mca-python-library

# (optional) create a virtualenv
python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\\Scripts\\activate

pip install -e .
```

---

## Quick start

Minimal example showing how to connect to a board, configure a couple of parameters and acquire an energy spectrum.

```python
from smartmca import (
    connect,
    disconnect,
    get_mca_configuration,
    set_mca_configuration,
    acquisition_start,
    acquisition_stop,
    histogram_get,
    ConfigAcquisition,
)

# 1. Connect to the instrument
url = "http://192.168.0.10"  # or "http://127.0.0.1" when running on-board
username = "user"
password = "password"  # change if you modified the default password on the device

if not connect(url, username, password):
    raise RuntimeError("Could not connect to SmartMCA server")

try:
    # 2. Read and adjust MCA configuration
    mca_cfg = get_mca_configuration()

    # Example: change some processing parameters
    # (see the MkDocs pages for the full list of fields)
    # mca_cfg.trigger_mode = TriggerMode.INTERNAL
    # mca_cfg.energy_mode = EnergyMode.TRAPEZOIDAL
    # mca_cfg.trap_shaping = 2000  # [ns]

    set_mca_configuration(mca_cfg)

    # 3. Start an acquisition
    result = acquisition_start()
    if result != "ok":
        raise RuntimeError(f"Acquisition start failed: {result}")

    # ... wait for statistics / preset condition using your own logic ...

    # 4. Read an energy histogram (rebin to 4096 channels)
    spectrum, status = histogram_get(
        ConfigAcquisition.SpectrumType.ENERGY,
        rebin=4096,
    )

    if status != "ok":
        raise RuntimeError(f"Histogram read failed: {status}")

    # `spectrum` is a list of counts per bin
    print(f"Number of channels: {len(spectrum)}")

finally:
    # 5. Stop acquisition and disconnect
    acquisition_stop()
    disconnect()
```

This is intentionally minimal. Refer to the configuration pages for the full list of parameters (analog, digital I/O, MCA processing, acquisition, oscilloscope).

---

## Documentation

The full user guide is generated with MkDocs and published as GitLab Pages.

* Online docs: [`https://public-repo.pages.nuclearinstruments.eu/dt5771/smart-mca-python-library/`](https://public-repo.pages.nuclearinstruments.eu/dt5771/smart-mca-python-library/)

To build the documentation locally:

```bash
pip install -r requirements-mkdocs.txt

# From the repository root
mkdocs serve
```

Then open `http://127.0.0.1:8000/` in your browser.

The documentation is organized as:

* `Home` – overview and installation
* `Connection and System` – connection helpers and system information
* `Configuration` – analog and digital I/O, MCA processing, acquisition, oscilloscope
* `Data Acquisition & Readout` – statistics, MCS, oscilloscope and histogram APIs

---


## Versioning

Follow [Semantic Versioning](https://semver.org/) for library releases:

* `MAJOR` – incompatible API changes
* `MINOR` – new functionality in a backwards compatible manner
* `PATCH` – backwards compatible bug fixes

Tag releases in Git and publish the same version on PyPI and GitLab pages when appropriate.

---



## Contact / Support

* Issues: [https://support.nuclearinstruments.eu](https://support.nuclearinstruments.eu)

This gives external users and colleagues a single place to start when using the library.

