MCA-3K Data Server Reference

The file mca3k_data.py contains definitions for data classes. Each data class describes one set of control data or acquired data as shown in the table below. All classes have the same structure: They contain data and a set of standardized functions which the API level uses when executing commands. The data objects transient. They created, used and then discarded during the execution of a command. The data object functions mostly serve to translate between human-readable data in Si units and the bit-fields and register contents on board the MCA-3K.

Data structures

The mca3k_data.py module defines all data classes used for communication. We show the ones pertaining to the FPGA and those residing in the ARM M0+ controller in two different tables.

The common structure of all data classes is explained in the table below.

MCA-3K data class attributes.
MCA-3K Data Class Structure
Attribute	Description
registers	On board data are stored in registers as arrays of data. 'registers' is a copy of that array.
fields	'fields' is a dictionary where the various components of the registers and any bit fields are stored by name.
user	'user' is a dictionary where data are stored as physical quantities in SI units. Since this is not meaningful for all data, 'user' may only capture a subset of all data. On the other hand, when reading data, 'user' may present an enhanced set of data containing evaluated data; eg when reading count rates.
adc_sr	The ADC sampling rate is stored as it is needed to compute some of the evaluated data.
wr_type	Identifies the device to write to (FPGA or ARM).
rd_type	Identifies the device to read from (FPGA or ARM).
cmd_addr	An ID that tells the MCA-3K device which data section is being addressed; cf the Data Classes tables below.
data_type	Tells the device driver what kind of data are being transmitted; they can be 'H', 'I' and 'f' for unsigned int16, unsigned int32 and float32 data.
num_items	Number of data items to transmit between host and MCA-3K.
num_bytes	Number of bytes to transmit between host and MCA-3K.

MCA-3K data class attributes.
MCA-3K Data Class Functions
Function	Description
registers_2_fields	Convert FPGA control register values into a control register dictionary which has names for the bit fields.
fields_2_registess	Compute the values of the control registers from the fields dictionary.
fields_2_user	Convert a few field values into physical quantities in SI units.
user_2_fields	Convert user values from physical quantities in SI units into numerical fields
add_to_cmd_out_list(mca)	If a command requires auxiliary data to be sent with it (up to 14 unsigned int16) those could be copied from a designated member of an mca object. The standard MCA-3K software does not use this feature.

Table of ARM-related data structures.
MCA-3K Data Classes – ARM
Name	Description
arm_version	Version and serial number information for FPGA and ARM firmware and software.
arm_status	Status information (unsigned int32) from the slow-control system, including temperatures, operating voltage, etc.
arm_ctrl	Parameters (float32) to set the SiPM operating voltage, apply gain stabilization and more.
arm_cal	Calibration data (float32) used by the gain stabilization; eg a voltage vs temperature lookup table.

Table of FPGA-related data structures.
MCA-3K Data Classes – FPGA
Name	Description
fpga_ctrl	FPGA control registers; These control all aspects of the real time data acquisition including triggers, count rate measurement, histograms, list mode, trace acquisition, pulse shape discrimination, etc.
fpga_statistics	Statistics data (read only) from which count rates etc are computed.
fpga_results	Status and telemetry data.
fpga_histogram	Histogram data; at least 4Kx32 bins are available
fpga_list_mode	List mode data for at least 341 events
fpga_trace	Oscilloscope trace data; at least 1024 samples are available.
fpga_weights	Weights can be used during the summation of ADC data to improve energy resolution in some scintillators.
fpga_action	Actions control the start and stop of data acquisition as well as momentary events, such as clearing data and resetting statistics counters.