SOAP: Communicating with alibava-gui

alibava-gui can also work as a SOAP server. This means that we can send a number (very limited) of commands to the alibava-gui process to start or stop a run and, also, to retrieve some information about the status of the acquisition. The SOAP server and client libraries are implemented using the gSOAP toolkit for Web Services1

The SOAP commands are summarized below:

:
    void getStatus(in int request, out Status status);

Returns the status of the acquisition in a structure of type Status, described in Example 12. The request parameter can be ignored and one can send any value, usually 0.

:
    void Reset(in value);

Resets the board

:
    void startRun(in DAQParam daqParam, out base64binary data);

Starts a run with the parameters specified in a structure of type DAQParam described in Example 14. It returns a data block which contains various histograms. This is a synchronous methods and will not return until the run is over.

:
    void startRunAsync(in daqParam);

Starts a run with the parameters specified in a structure of type DAQParam described in Example 14. It returns immediately. You should use the getStatus method to check the status of the run.

:
    void Reset(in value);

Resets the board

:
    void stopRun(in int value, out int response);

Stops the current run. The value parameter has no meaning and any value is accepted. The output parameter, response, with return 0 if the operation was succesful and an error code otherwise.

:
    void setDataFile(in string fileName, out int response);

Sets the name of the data file and forces alibava-gui to log data into that file. The output parameter, response, with return 0 if the operation was succesful and an error code otherwise.

:
    void setParameter(in ParValue value, out int response);

Set the values of some running parameters like some registers of the Beetle chips.

ParValue, as shown in Example 13 is a pair of a name and a value. The name identifies the parameter. Parameter names are shown in Table 5.

:
    void getHistogram(in string hstName, in string hstType, out int response);

Gets the picture of the historam hstName with type hstType, which can be any of: png, jpg, svg, eps and pdf. The names of the available histograms are listed in Table 6. Note, however, that the histograms are produced only when the server is run in GUI mode.

Example 12The Status structure
class Status
{
public:
    string status;
    time time;
    int nexpected;
    int ntrigger;
    double rate;
    string run_type;
    double value;
}

Example 13The ParValue struc
class ParValue
{
public:
    string name;
    string value;
}

Example 14The DAQParam structure
class DAQParam
{
public:
    int runType;
    int numEvents;
    int sampleSize;
    int nbin;
    double xmin;
    double xmax;
}
Table 5Names of the parameters that can be changed with setParameter. The table does not show the parameters tht refer to a beetle register. Those names are the same as in Table A-1
Parameter Names Description
trgIn Switches ON/OFF Trigger In
thrsIn1 Threshold for the first TrigIn comparator
thrsIn2 Threshodl for the second TrigIn comparator
trgAND Set AND as the operation between In1 and In2
trgOR Set OR as the operation between In1 and In2
trgPulse Switches ON/OFF Pulse
thrsPulse- Nevative threshold for TrigPulse
thrsPulse+ Positive threshold for TrigPuls
enableComp Switches ON/OFF the Beetle comparator
trackMode Set the comparator working mode to track
pulseMode Set the comparator working mode to pulse
compPolarity Sets the polarity for the comparator
mainTh It sets the main comparator settings. The parameter name can be followed by a number specifying a particular chip. If no number is given, the valu will be applied to to all chips.
deltaTh The parameter name can be followed by a number specifying a particular chip. If no number is given, the valu will be applied to to all chips.
trimCh<n> Sets the vector of corrections for trimming the threshold. <n> is the chip number and should be specified.
maskCh<n> Sets the vector of corrections for trimming the threshold. <n> is the chip number and should be specified.
fileFormat Set the data format in the data file. Valid values are hdf and alibava

Table 6Names of the histograms that can be retrieved as pictures.
Histogram Name Description
hstSignal The spectrum
hstPedestal The pedestals of all the channels
hstNoise The noise of all the channels
hstHitmap The hitmap
hstTemp The tracer of the measured temperature
hstTime The tracer of the TDC time
hstEvent The event viewer. It show, for a given event, the content of each channel.
hstCmmdNoise The noise from the common mode
hstCmmd The common mode

The data returned by the startRun consists of 3 histograms in most cases. The first contains the spectrum, the second the mean value of the signal seen by each channel and the third the rms of the signal seen by each channel. In a Pedestal run the last two histograms would correspond to the pedestals and noise respectively. The format of the data is described in Table 7.

Table 7Format of the data from startRun
Size and type Description
int32 number of histograms
For each histogram
int32 number of bins
double xmin
double xmax
nbin * double data chunk with nbin doubles

There are available a Python and a C++ wrap classes to hide the SOAP complexity to the user. These are described in Section 9.1 ― SOAP examples.

9.1. SOAP examples

The test folder in the distribution contains some examples that may help understanding the procedure to communicate with alibava-gui via SOAP. The examples are written in two languages, python and C++. There are Python and C++ classes that hide the complexity of the SOAP implementation and privide a much easier interface. The interface is very similar in both programming languages.

Example 15SOAP interface

class Alibava
{
:
    Alibava(const char * uri = 0);

:
    void connect(in const char * uri);

:
     getStatus(out Status &status);

:
     Reset(in int val);

:
     setDataFile(in string &file_name);

public:
    int setParameter(in string &name, in string &value);

:
    int getMask();

:
    void stopRun();

:
     startPedestalRun(int nevt, bool async, int nbin = 512, int xmin = -512, int xmax = 512, int nsample = 100);

:
     startSourceRun(int nevt, bool async, int nbin = 512, int xmin = -512, int xmax = 512, int nsample = 100);

:
     startLaserRun(int nevt, bool async, int nbin = 512, int xmin = -512, int xmax = 512, int nsample = 100);

:
     startCalibrationRun(bool async, int nevt_per_point = 50, int npts = 10, double vfrom = 0.0, double vto = 30000.0, bool is_charge = true);

:
     startLaserSync(bool async, int nevt_per_point = 50, int npts = 10, double vfrom = 0.0, double vto = 512.0);

:
     startChargeScan(bool async, int nevt_per_point = 50, int npts = 10, double vfrom = 0.0, double vto = 30000.0);
}

The histograms returned by the methods that start a synchronous run are retrieved differently in python and C++. The histograms are returned directly by the method in python, while in C++ one need to retrieve them by calling the get_histogram method. See the examples below.

9.1.1. Python example

In the case of python, we recomend to have SOAPpy installed in the system. It can be downloaded from http://sourceforge.net/projects/pywebsvcs/files/SOAP.py. It is also in most of the Linux distributions so the best is to use the one provided by your particular distribution if you are using Linux. The example below uses this python package. There are two parts. One that hides all the complexity of the SOAP data types intrinsic to Albava and the other the one that contains your actual commands.

The first one is shown in Example 16 and the second in Example 17.

Example 16alibavaSOAP: internals to alibava SOAP structures in Python

#!/usr/bin/env python
"""
Example of a soap client for alibava
"""
import sys
from alibavaSOAP import Alibava, Status
import SOAPpy


def main(host="localhost", port=10000):
    server = Alibava(host, port)
    
    S = Status( server.getStatus() )
    print S
    R = server.stopRun()
    
    R = server.startPedestalRun(1000)
    S = Status( server.getStatus() )
    print S
    
    R = server.startLaserRun(1000, nbin=32, xmin=-512, xmax=512)
    S = Status( server.getStatus() )
    print S
    for hst in R:
        print hst
    
    
    server.setDataFile( "alibava_data.dat" )
    R= server.startSourceRun(1000, nbin=32)
    for hst in R:
        print hst
    
    
    R = server.startCalibrationRun(100, 20, 0, 30000)
    for hst in R:
        print hst
    
    
    #SOAPpy.Config.debug=1
    server.setParameter("Isha", 32)
    server.setParameter("Vfs", 19)
    server.setParameter("trgPulse",1)
    
    mask=''
    for i in range(0,128):
        if i%4 : mask+='1'
        else: mask+='0'
    server.setParameter("maskCh1", mask)
    
    trim=''
    for i in range(0,128):
        if i%4 : trim+='0,'
        else: trim+='1,'
    server.setParameter("trimCh1", trim)
    
    
if __name__ == "__main__":
    try:
        host = sys.argv[1]
    except IndexError:
        host = "localhost"
        
    try:
        port = int(sys.argv[2])
    except IndexError:
        port = 10000
        
    main(host, port)

Example 17testSoap.py: an example of use

#!/usr/bin/env python
"""
Example of a soap client for alibava
"""
import sys
from alibavaSOAP import soapClient, Status


def main(host="localhost", port=10000):
    # connect to the server
    server = soapClient(host, port)
    
    # Get the current status and print it
    S = server.getStatus()
    print S

    # Stop the run
    R = server.stopRun()
    
    # Start a pedestal run with 1000 events
    R = server.startPedestalRun(1000)

    # Start a Laser Run. Set the parameters of the
    # histogram axis
    R = server.startLaserRun(1000, nbin=32, xmin=-512, xmax=512)
    for hst in R:
        print hst
    
    # Set the name of the data file and start a Source Run
    server.setDataFile( "alibava_data.dat" )
    R= server.startSourceRun(1000, nbin=32)
    for hst in R:
        print hst
    
    
if __name__ == "__main__":
    try:
        host = sys.argv[1]
    except IndexError:
        host = "localhost"
        
    try:
        port = int(sys.argv[2])
    except IndexError:
        port = 10000
        
    main(host, port)

9.1.2. C++ example

The alibava package provides libraries for communicating with alibava-gui. The test folder of the distribution contains an example, which also shown in Example 18. Look at the given Makefile to see which are the requered includes and libraries. The example shown here also uses the Histogram class whose implementation can also be found in the test folder of the distribution.

Example 18C++ soap client

#include <iostream>
#include <alibavaClient.h>


int main(int argc, char **argv)
{
    const char *uri = "http://localhost:10000";
    Alibava client;

    if (argv[1])
        uri = argv[1];

    client.connect(uri);


    ns1__Status status;
    client.getStatus(status);
    std::cout << "Status:" << std::endl;
    std::cout << status << std::endl;

    client.startPedestalRun(5000, false);
    client.getStatus(status);
    std::cout << "Status:" << std::endl;
    std::cout << status << std::endl;

    client.startLaserRun(5000, false);
    client.getStatus(status);
    std::cout << "Status:" << std::endl;
    std::cout << status << std::endl;

    client.setParameter("fileFormat", "hdf5");
    client.setDataFile("/tmp/data_file.dat");
    client.startSourceRun(10000, false);
    client.getStatus(status);
    std::cout << "Status:" << std::endl;
    std::cout << status << std::endl;
    client.get_histogram(0)->Print(std::cout);

    return 0;
}

9.2. Monitoring Alibava runs from abroad

The SOAP server also provides a web service where you can monitor the current status of your run. The interface is really simple. The addres you have to give to the browser is

http://address_of_your_computer:nnnn

where nnn is the port you have given to the SOAP server (10000 by default). You may need to enable that port in order to do that from another computer. Figure 26 shows an exmple of what the server will provide. It will, essentially, be the histograms that are shown at the main window of the alibava-gui application.

Figure 26Web server

1

Robert A. van Engelen and Kyle Gallivan, The gSOAP Toolkit for Web Services and Peer-To-Peer Computing Networks, in the proceedings of the 2nd IEEE International Symposium on Cluster Computing and the Grid (CCGrid2002), pages 128-135, May 21-24, 2002, Berlin, Germany.