MCA-1K Data Server Reference
COUNTER
USB driver
Data structures
ARM Data structures
API
MCA-1K API
Summary
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.
| 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.
| 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'. |