MCA Data Server Reference
wxMCA Package
Supported Devices
MCA API
Summary
The MCA API (mca_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. In the discussion below, MCA generically refers to Counters, MCA-1000, MCA-3000 and Neutron-3000 devices. More device may be added in the future.
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.
| 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 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 mca_api.make_new_io_obj dictionary |
| 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=='mca_cmd' |