kcl-bmeis/spectrumdevice

Python library for communicating with digitisers manufactured by Spectrum Instrumentation

spectrumdevice's Issues

fix hardware testing on single card

There are some unexpected failed tests when running the single card tests on hardware

Enable firmware averaging

Many cards support on-board averaging. SPC_CARDMODE needs to be set to one of the following values:

• SPC_REC_STD_AVERAGE for averaging in standard acquisition mode resulting in 32 bit data
• SPC_REC_STD_AVERAGE_16BIT for averaging in standard acquisition mode resulting in 16 bit data (8 bit cards only)
• SPC_REC_FIFO_AVERAGE for averaging in FIFO acquisition mode resulting in 32 bit data
• SPC_REC_FIFO_AVERAGE_16BIT for averaging in FIFO acquisition mode resulting in 16 bit data (8 bit cards only)

Then you set the number of averages by writing to the SPC_AVERAGES register.

Python 3.12

Check Python 3.12 compatibility

Package unworking

Hi, I'm trying to install you package.
I'm usually use conda for create new envs, so I did it.

conda create -n myenv
conda activate myenv

Then
conda install -c conda-forge spectrumdevice -y

That does not return me any kind of error.

Then i follow your README with this 2 lines :

from spectrumdevice import SpectrumDigitiserCard
card_0 = SpectrumDigitiserCard(device_number=0)

Here i got an error :
ImportError: cannot import name 'SpectrumDigitiserCardconda' from 'spectrumdevice' (/miniconda/base/envs/envspectrum/lib/python3.11/site-packages/spectrumdevice/__init__.py)

Do i missed something ?

New features in AcquisitionSetting

Hi,
Your package work near perfectly,
However, I'm encountering challenges while attempting to configure specific parameters:

• Input path: HF
• Coupling: AC
• Internal impedance: 50 Ohm

Could you integrate those settings in AcquisitionSetting ?

Best regards

Coercion of `SPC_MEMSIZE` and `SPC_POSTTRIGGER` values to nearest 8 samples only valid for M2p.59xx cards.

Other card series like the M4i.22xx or M4i.44xx have a different step size for the SPC_MEMSIZE and SPC_POSTTRIGGER registers (32 samples for 22xx, 16 samples for 44xx).

The card type can be read from the SPC_PCITYP register. This could be done in SpectrumCard.__init__(). We'd then need a lookup table of step sizes for the different card types.

In `get_waveforms()`, buffer marked as available before data is read

The card could receive enough trigger events in the mean time to overwrite the area just freed with new data, resulting in an inconsistent mix of old and new data being read. It would be better to first execute the “waveforms_in_columns = copy…” line, and after that mark the data as available again by calling “self.write_to_spectrum_device_register(SPC_DATA_AVAIL_CARD_LEN, num_available_bytes)”.

Improve error handling

The error handler in spectrum_wrapper/error_handler.py currently only contains the descriptions of a few frequently encountered errors. Other errors are raised only by their Spectrum API error codes, and must be looked up in the Spectrum documentation.

As more errors are encountered while spectrumdevice is used, those most likely to be encountered should be added to the error handler. This issue holds a list of those errors.

At some point, the whole error codes table from the spectrum documentation should probably be included in spectrumdevice as a lookup table.

• ERR_NETWORKTRANSFER (0x00000041) The network data transfer from/to a digitizerNETBOX has failed

Software averaging

Implement an option for software averaging, for use with devices that do not support hardware averaging.

Convert from setup.py to setup.cfg and pyproject.toml

Following this guide.

Provide trigger timestamps

A spectrum acquisition card can provide trigger timestamps for each of its acquisitions. The device can be configured to provide the timestamps relative to the start of each acquisition, relative to an external trigger signal, or relative to a timestamp provided by the host PC. The timestamps are passed to the PC via the 'extra-FIFO' buffer.

In the first instance, it makes sense to configure a SpectrumCard to return a system-clock timestamp with each acquisition, as this is likely the most commonly useful information.

Pre-release testing on hardware

Test plan for testing on lab machine with drivers installed and hardware connected (before release).

Mock mode

• Check unit tests pass
  pytest -v -m "not integration and not only_without_driver"
• Check integration tests pass
  pytest -v -m "integration and not only_without_driver"

Tests on Spectrum Digitizer Netbox DN2.593-16

Unit tests

In tests/configuration.py

• Set SINGLE_CARD_TEST_MODE = SpectrumTestMode.REAL_HARDWARE
• Set STAR_HUB_TEST_MODE = SpectrumTestMode.REAL_HARDWARE
• Set TEST_DEVICE_IP equal to the device IP address shown in the Spectrum Control Centre
• Set TEST_DEVICE_NUMBER = 1
• Check the card configuration options match the Nextbox (default settings should be correct):

NUM_MODULES_PER_CARD = 2
NUM_CHANNELS_PER_MODULE = 4
NUM_CARDS_IN_STAR_HUB = 2
STAR_HUB_MASTER_CARD_INDEX = 1

• Set ACQUISITION_LENGTH = 4096

Then:

• Check unit tests pass
  pytest -v -m "not integration and not only_without_driver"

Integration tests (without a signal generator connected)

In tests/configuration.py

• Keep the same setup as shown above for the unit tests
• But since no trigger signal will be connected to the device, make sure to set INTEGRATION_TEST_TRIGGER_SOURCE = TriggerSource.SPC_MASK_SOFTWARE.

Then:

• Check integration tests pass
  pytest -v -m "integration and not only_without_driver"

Integration tests (with a signal generator)

Signal generator setup:

• The example scripts used by the integration tests configure a sample rate of 40 MHz and acquisition length of 400 samples, generating 10-microsecond long waveforms.
• So configure the signal generator to generate sine wave bursts shorter than 10 microseconds, e.g. 5 cycles at 1 MHz (a 5 microsecond burst)
• Set the burst repetition rate 10 Hz
• Set the sync (trigger) output to a level > 1 V (the example scripts used as integration tests configure the external trigger level to 1V)

Connect signal generator to Netbox:

• Connect the signal generator output to channel 8 (i.e. channel 0 of the master card of the Netbox)
• Connect the trigger signal to 'Trig In' (EXT_0) on the Netbox

In tests/configuration.py

• Keep the same setup as shown above for the unit tests
• But set INTEGRATION_TEST_TRIGGER_SOURCE = TriggerSource.SPC_MASK_EXT0.

Then:

• Check integration tests pass
  pytest -v -m "integration and not only_without_driver"

Run example scripts with the Netbox

Manually run each of the example scripts in the example_scripts directory, with the signal generator set up as for the Integration tests (with a signal generator) above. You will need to temporarily modify the if __name__ == '__main__': of the scripts so that:

• Mock mode is disabled
• The device IP address is correct
• The device number is set to 1 (the index of the master card of the Netbox)

Then:

• Verify that the plotted waveforms match the expected data (5 cycles at 1 MHz)

Tests on Spectrum PCIe Digitizer M2p.5961-x4

Unit tests

In tests/configuration.py

• Set SINGLE_CARD_TEST_MODE = SpectrumTestMode.REAL_HARDWARE
• Set TEST_DEVICE_IP = None
• Set TEST_DEVICE_NUMBER = 0
• Set NUM_MODULES_PER_CARD = 1
• Set NUM_CHANNELS_PER_MODULE = 2

Then:

• Check unit tests pass
  pytest -v -m "not star_hub and not integration and not only_without_driver"

Integration tests

Using the same configuration as above, and ensuring software triggering is selected in configuration.py:

• Check integration tests pass
  pytest -v -m "not star_hub and integration and not only_without_driver"

Converting ADC samples to voltage values

The waveforms provided by spectrumdevice currently contain raw ADC samples in LSB. They should be converted to voltages as follows:

"The Spectrum driver also contains a register that holds the value of the decimal value of the full scale representation of the installed ADC. This value should be used when converting ADC values (in LSB) into real-world voltage values, because this register also automatically takes any specialities into account, such as slightly reduced ADC resolution with reserved codes for gain/offset compensation.

Register: SPC_MIINST_MAXADCVALUE
Value: 1126
Description: Contains the decimal code (in LSB) of the ADC full scale value

In case of a board that uses an 8 bit ADC that provides the full ADC code (with- out reserving any bits) the returned value would be 128. The the peak value for a ±1.0 V input range would be 1.0 V (or 1000 mv).

When converting samples that contain any additional data such as for example additional digital channels or overrange bits, this extra information must be first masked out and a proper sign-extension must be per- formed, before these values can be used as a signed two’s complement value for above formulas."

Improve timestamp acquisition

We're using polling mode for timestamp transfer, which is quite slow. Should have a look at using FIFO/DMA mode

Crash when enabled channels not provided in correct order (star hub)

SpectrumStarHub.set_enabled_channels() does not work if the channels in the list provided are not in the numerical order

Support for arbitrary waveform generators

We need to support arbitrary waveform generators as well as digitisers. This will likely require some refactoring of the class hierarchy (and some renaming - SpectrumDevice will likely become SpectrumDigitiser, for example). This work will likely form the bulk of the version 1 release.

Refactoring was done in PR #29

Python 3.11 support

Check works with 3.11