MCA-1K Data Server Reference

The API (mca1k_api.py) serves PMT-based and SiPM-based MCA-1K devices, such as PMT-1000 and SiPM-1000. It takes a command and a dictionary of mca objects as its argument, executes the command and returns data, if any, in the mca.data_in_dict member of each mca object. In the dictionary of mca objects, the keys are the unique 32-character device serial numbers.

Reading data

When reading data (dir='read'), the API reads registers from the device, converts some of these into named fields and again reports some of these as physical quantities in SI-units in the user dictionary. All three hierarchical levels are populated automatically.

Writing data

When writing data (dir='write'), the API writes a list of register values to the device. Named 'fields' and 'user' dictionary entries are not supported. This is useful in some cases where it is desirable to avoid the extra read in a read-modify-write command.

Read-Modify-Write

The most robust and easy to use method for updating parameters is to employ read-modify-write commands (dir='rmw'). When executing such a command, the API reads the current values from the target and promotes data from registers to named fields and then up to the user dictionary.

It then proceeds to update only the values given by the user. It translates data from an input user dictionary to named fields, then merges in any user-supplied named fields, and finally copies all that into the list of data that are to be written to the device.

The advantage to the user is that they only need to supply data for the quantities they want to change and can ignore all the others.

Secondly, the MCA Data Server receives commands from any attached client and will execute them in order or receipt. A read-modify-write command is atomic in the sense that it cannot be interrupted by another client.

API functions

There are two functions to process commands and boot attached devices.

The API only needs two functions.
API functions
Function name	Description
process_cmd(user_cmd, mca_dict)	Prepare all mca in the mca_dict for performing the command, perform the command on each mca and return an in_dict dictionary with data for each serial number. For each mca, return data are also stored in
perform_cmd(mca)	The mca object has been prepared and all relevant command information is stored internally. perform_cmd executes the command and loads results into mca.data_in_dict

The API accepts a command data structure (dictionary in Python) that is the same for all commands.

The API command structure
API command structure
Field	Description
sn	Unique, immutable, serial number consisting of 32 hex characters; eg 123456789ABCDEF123456789ABCDEF Cases: Field is empty or is an empty string: Command applies to all mca in the mca_dict. Field is a non-empty string: Command applies to that mca if it is in the mca_dict. Field is a list of strings: Command applies to all mca in that list if they are in the mca_dict
dir	read → Read data, short_write → Write data, and data are being sent to the command endpoint, write → Write data, and data are being sent to the data endpoint, rmw → Read-modify-write, and data are exchanged via the data endpoints.
memory	ram → target memory resides in the RAM of the ARM processor, flash → target memory resides in ARM non-volatile memory.
name	Command name; it must be one of the keys in the pmt_mca_api.make_new_io_obj directory
num_items	For some commands the user may want to specify explicitly the number of items to read or write.
ctrl	List of control data written to mca.command_out; Mostly used for control or action registers.
data	List of data to be routed via the data endpoints.
cmd_type	Not used by the API. The data server will call the API only if cmd_type=='mca1k_cmd'.