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

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

pip install smartmca

From source (this repository)

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.

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/

To build the documentation locally:

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 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

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