class buffered_data_callbacks_pipe

class scTDC.buffered_data_callbacks_pipe(lib, dev_desc, data_field_selection=64, max_buffered_data_len=65536, dld_events=True)

Base class for using the BUFFERED_DATA_CALLBACKS interface which provides DLD or TDC events in a list-of-events form. Requires scTDC1 library version >= 1.3010.0. In comparison to the USER_CALLBACKS pipe, this pipe reduces the number of callbacks into python, buffering a higher number of events within the library before invoking the callbacks. Thereby, the number of Python lines of code that need to be executed can be drastically reduced if you stick to numpy vector operations rather than iterating through the events one by one. The on_data callback receives a dictionary containing 1D numpy arrays where the size of these arrays can be as large as specified by the max_buffered_data_len parameter. To use this interface, write a class that derives from this class and override the methods

__init__(lib, dev_desc, data_field_selection=64, max_buffered_data_len=65536, dld_events=True)

Creates the pipe which will be immediately active until closed. Requires an already initialized device.

Parameters
  • lib (scTDClib) – an scTDClib object

  • dev_desc (int) – device descriptor as returned by sc_tdc_init_inifile or sc_tdc_init_inifile_overrides

  • data_field_selection (int) – a ‘bitwise or’ combination of SC_DATA_FIELD_xyz constants, defaults to SC_DATA_FIELD_TIME

  • max_buffered_data_len (int) – The number of events that are buffered before invoking the on_data callback. Less events can also be received in the on_data callback, when the user chooses to return True from the on_end_of_meas callback. defaults to (1<<16)

  • dld_events (bool) – if True, receive DLD events. If False, receive TDC events. Depending on the configuration in the tdc_gpx3.ini file, only one type of events may be available. defaults to True

on_data(data)

Override this method to process the data.

Parameters

data

A dictionary containing several numpy arrays. The selection of arrays depends on the data_field_selection value used during initialization of the class. The following key names are always present in this dictionary:

  • event_index

  • data_len

Keywords related to regular event data are:

  • subdevice

  • channel

  • start_counter

  • time_tag

  • dif1

  • dif2

  • time

  • master_rst_counter

  • adc

  • signal1bit

Keywords related to indexing arrays are:

  • som_indices (start of a measurement)

  • ms_indices (millisecond tick as tracked by the hardware)

These contain event indices that mark the occurence of what is described in parentheses in the above list.

Returns

None

on_end_of_meas()

Override this method to trigger actions at the end of the measurement. Do not call methods that start the next measurement from this callback. This cannot succeed. Use a signalling mechanism into your main thread, instead.

Returns

True indicates that the pipe should transfer the remaining buffered events immediately after returning from this callback. False indicates that the pipe may continue buffering the next measurements until the max_buffered_data_len threshold is reached.

Return type

bool

close()

Close the pipe.

start_measurement_sync(time_ms)

Start a measurement and wait until it is finished.

Parameters

time_ms (int) – the duration of the measurement in milliseconds.

Returns

0 on success or a negative error code.

Return type

int

start_measurement(time_ms, retries=3)

Start a measurement ‘in the background’, i.e. don’t wait for it to finish.

Parameters
  • time_ms (int) – the duration of the measurement in milliseconds.

  • retries (int) – in an asynchronous scheme of measurement sequences, trying to start the next measurement can occasionally result in a “NOT READY” error. Often some thread of the scTDC1 library just needs a few more cycles to reach the “idle” state again, where the start of the next measurement will be accepted. The retries parameter specifies how many retries with 0.001 s sleeps in between will be made before giving up, defaults to 3

Returns

0 on success or a negative error code.

Return type

int

scTDC.SC_DATA_FIELD_SUBDEVICE = 1

used in buffered_data_callbacks_pipe

scTDC.SC_DATA_FIELD_CHANNEL = 2

used in buffered_data_callbacks_pipe

scTDC.SC_DATA_FIELD_START_COUNTER = 4

used in buffered_data_callbacks_pipe

scTDC.SC_DATA_FIELD_TIME_TAG = 8

used in buffered_data_callbacks_pipe

scTDC.SC_DATA_FIELD_DIF1 = 16

used in buffered_data_callbacks_pipe

scTDC.SC_DATA_FIELD_DIF2 = 32

used in buffered_data_callbacks_pipe

scTDC.SC_DATA_FIELD_TIME = 64

used in buffered_data_callbacks_pipe

scTDC.SC_DATA_FIELD_MASTER_RST_COUNTER = 128

used in buffered_data_callbacks_pipe

scTDC.SC_DATA_FIELD_ADC = 256

used in buffered_data_callbacks_pipe

scTDC.SC_DATA_FIELD_SIGNAL1BIT = 512

used in buffered_data_callbacks_pipe