MCA-3K Data Server (sipm-MDS) Reference

The MCA-3K API (mca3k_api.py) 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.

Reading data

When reading data, 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

For a short_write or write command the API only accepts the list data, and they have to be complete. For instance all 16 control registers must be given for a fpga_ctrl write to succeed. Write and short_write commands are used only when execution speed is of utmost performance, and added USB-delays (2ms) are unacceptable.

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 three main 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 ARM or FPGA RAM, flash → target memory resides in ARM non-volatile memory.
name	Command name; it must be one of the keys in the mca3k_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 FPGA 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=='mca3k_cmd'