eMorpho Data Server Reference

eMorpho

Introduction

USB driver

bpi_device

Data structures

Overview

Module Constants

Controls

Statistics

Results

Histogram

List Mode

Oscilloscope Trace

Summation Weights

Time Slices

Two-bank List Mode

API

Overview

Data Server

Overview

eMorpho API

Summary

The eMorpho API (emorpho_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 client. It translates data from an input user dictionary to named fields, then merges in any client-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 Morpho 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 nameDescription
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 only needs two functions.

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

API command structure
FieldDescription
snSerial number; eg eRC5000
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
dirread → Read data, short_write → Write data, used to write fpga_ctrl, write → Write data, used for all other writes (eg to nv-mem), rmw → Read-modify-write, and data are exchanged via the data endpoints.
memram → target memory resides in FPGA, flash → target memory resides in on-board non-volatile memory.
nameCommand name; it must be one of the keys in the emorpho_api.make_new_io_obj directory
num_itemsFor some commands the user may want to specify explicitly the number of items to read or write.
dataDictionary of data to be written; includes the standard three keys: 'registers', 'fields' and 'user'.
cmd_typeNot used by the API. The data server will call the API only if cmd_type=='em_cmd'
The API command structure