LibTmsApi

Author

Dr Terry Barnaby

Version

2.0.0

Date

2013-02-01

Introduction

This document covers the BEAM LibTms software API for the CERN trajectory measurement system. This API provides the ability to control and receive data from the TMS System. The API is an object orientated API implemented in 'C++' with a number of object classes. The API operates over a network type interface using an RPC type mechanism.

The LibTms API makes use of the BEAM standard class library. The BEAM standard class library provides a small set of low level 'C++' classes for strings, lists and system interface functions. There is some brief information on the BEAM class library later on in this page.

Overview

Generally users of the system are only concerned with the top level, System Controller API. This is the API that control and data gathering clients use to control and gather data from the system. The System Controller API (TmsApi) is implemented using a simple, object orientated, RPC mechanism. Two main objects, the Tms::TmsControl and Tms::TmsProcess objects, provide the full API.

The TmsApi has been developed using the BOAP (BEAM Object Access Protocol). This provides a simple but powerful Object Orientated RPC mechanism. The TmsApi is written in a high level interface definition language (IDL). The bidl tool generates the client and server side 'C++' interface and implementation files for the API. These are then provided as a set of 'C++' header files and a binary library file for the clients to link to. The BOAP system employs a simple BOAP name server process that provides a translation between object names and IPAddress/Socket numbers. The BOAP name server runs on the System Controller. More information on the BOAP system can be found in the libBeam documentation.

There are two main Objects that are used by clients of the TMS API. They are the Tms::TmsControl and the Tms::TmsProcess objects. The Tms::TmsControl object is used for system configuration, testing and diagnostics. The Tms::TmsProcess object is used for normal clients for Proton Synchrotron (PS) Cycle information configuration and data access. There is some example client code in the tmsExamples of the source code and displayed later on this page. These objects communicate through a network connection with the TmsServer process running on the TMS System Controller. The TMS System Controller operates as a multi-threaded process and can communicate with multiple clients simultaneously.

The TMS system takes most of its system timing signals from digital timing lines connected to the TMS rack hardware. The only timing information that external software needs to supply is the next cycle number and cycle type information. The cycle number is a 32bit unsigned number identifying the next Proton Synchrotron (PS) machine cycle. The cycle type is and ASCII string defining the type of BEAM present in the PS machine. The cycle type defines a set of state/phase tables to be loaded in order to measure the BEAM in the machine. The CERN client software needs to provide this information by calling the setNextCycle() function before the next PS cycle is initiated.

The TMS system keeps a library of state/phase tables indexed by the cycle type. These are loaded into the individual PUPE engines FPGA's during the CYCLE_STOP to CYCLE_START period. The API provides the setControlInfo and delControlInfo calls to maintain this database.

A client would generally use the Tms::TmsProcess object for its interface to the TMS system. It would use call getData() to fetch the required data from the system. There is also an event based data interface implemented using the requestData() call and dataEvent() event call.

Each of the TMS API calls return an error object. If there is an error, an appropriate error number will be given together with an ASCII string describing the error.

BEAM class library

The BEAM class library implements some basic low level classes and is used by the TMS API implementation itself. The main class functionaly includes:

• BString - A simple string class
• BList - A templated list class
• BArray - A templated array class
• BError - An error return class containg an integer and string
• BSocket - A Network socket access class
• BThread - A thread implementation class
• BPoll - A file descriptor event polling class
• BMutex - A mutex lock
• BRWLock - A read/write lock
• BSema - A semaphore
• BCondInt - An integer condition class
• BFile - A simple file access class
• BDir - A simple directory access class
• BEntry - A name/value pair list class
• BNameValue - A name/value pair class
• BRtc - A realtime clock
• BTimer - A simple timer class
• BUrl - URL access class

Examples

There are some examples of client applications using the TmsApi in the tmsExamples directory of the source code. A simple Data Access client example is listed bellow:

/*******************************************************************************
 *      TmsDataClient.cpp       TMS API example code for a Data Client
 *                      T.Barnaby,      BEAM Ltd,       2007-02-07
 *******************************************************************************
 *
 *      This is a very basic example of using the TmsApi from a clients perspective.
 *      It is designed to give an overview of using the API.
 */
#include <iostream>
#include <stdio.h>
#include <TmsD.h>
#include <TmsC.h>
 
using namespace Tms;
using namespace std;
 
 
// Function to reads some data
BError tmsTest(TmsProcess& tmsProcess){
        BError                  err;
        DataInfo                dataInfo;
        Data                    data;
        BUInt32                 cn = 0;
        BString                 ct;
        
        // Find out the current cycle number and type
        if(err = tmsProcess.getCycleInfo(cn, ct)){
                return err.set(1, BString("Error: Getting Cycle Number: ") + err.getString());
        }
        
        printf("Getting data for cycles starting at cycle: %u\n", cn);
 
        for(; ; cn++){
                // Setup dataInfo
                printf("GetData: Cycle Number: %u\n", cn);
                dataInfo.cycleNumber    = cn;
                dataInfo.channel        = 1;
                dataInfo.cyclePeriod    = CyclePeriodEvent0;
                dataInfo.startTime      = 0;
                dataInfo.orbitNumber    = 0;
                dataInfo.bunchNumber    = 0;
                dataInfo.function       = DataFunctionRaw;
                dataInfo.argument       = 0;
                dataInfo.numValues      = 1024;
                dataInfo.beyondPeriod   = 1;
 
                if(err = tmsProcess.getData(dataInfo, data)){
                        return err.set(1, BString("Error: Getting Data: ") + err.getString());
                }
                printf("Data: NumValues: %d\n", data.numValues);
        }
        
        return err;
}
 
int main(int argc, char** argv){
        BError                  err;
        BString                 host = "localhost";
        TmsProcess              tmsProcess;
 
        if(argc == 2)
                host = argv[1];
 
        // Connect to the Process service
        if(err = tmsProcess.connectService(BString("//") + host + "/tmsProcess1")){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
        
        // Run a normal data gathering cycle as a normal client would.
        if(err = tmsTest(tmsProcess)){  
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
                
        return 0;
}

A simple Control client example is listed below:

/*******************************************************************************
 *      TmsControlClient1.cpp   TMS API example code
 *                      T.Barnaby,      BEAM Ltd,       2007-02-07
 *******************************************************************************
 *
 *      This is a very basic example of using the TmsApi from a clients perspective.
 *      It is designed to give an overview of using the API.
 */
#include <iostream>
#include <stdio.h>
#include <TmsD.h>
#include <TmsC.h>
 
using namespace Tms;
using namespace std;
 
const BUInt32   tmsStateNum = 16;
const BUInt32   tmsPickupNum = 40;
 
// Initialise and test the TMS system
BError tmsInit(TmsControl& tmsControl){
        BError                  err;
        ConfigInfo              configInfo;
        BIter                   i;
        BList<BError>           errorList;
        BList<NameValue>        nvList;
        BString                 version;
        
        // Get Version
        if(err = tmsControl.getVersion(version)){
                return err.set(1, BString("Error: initialising TMS: ") + err.getString());
        }
        cout << "Version: " << version << "\n";
        
        // Initialise TMS system
        if(err = tmsControl.init()){
                return err.set(1, BString("Error: initialising TMS: ") + err.getString());
        }
        
        // Test TMS system
        if(err = tmsControl.test(errorList)){
                return err.set(1, BString("Error: testing TMS: ") + err.getString());
        }
        
        for(errorList.start(i); !errorList.isEnd(i); errorList.next(i)){
                cout << "Warning: " << errorList[i].getString() << "\n";
        }
        
        // Get Status of TMS system
        if(err = tmsControl.getStatus(nvList)){
                return err.set(1, BString("Error: getting status: ") + err.getString());
        }
        
        for(nvList.start(i); !nvList.isEnd(i); nvList.next(i)){
                cout << nvList[i].name << ":\t" << nvList[i].value << "\n";
        }
 
        return err;
}
 
int main(int argc, char** argv){
        BError                  err;
        BString                 host = "localhost";
        TmsControl              tmsControl;
        TmsProcess              tmsProcess;
 
        if(argc == 2)
                host = argv[1];
 
        // Connect to the Control service
        if(err = tmsControl.connectService(BString("//") + host + "/tmsControl1")){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
 
        // Connect to the Process service
        if(err = tmsProcess.connectService(BString("//") + host + "/tmsProcess1")){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
 
        // Initialise and test the TMS system. Normally carried out by a configuration
        // and test client program.
        if(err = tmsInit(tmsControl)){  
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
 
        return 0;
}

A simple Control client to set the next cycle information example is listed below:

/*******************************************************************************
 *      TmsControlClient2.cpp   TMS API example code
 *                      T.Barnaby,      BEAM Ltd,       2007-02-07
 *******************************************************************************
 *
 *      This is a very basic example of using the TmsApi to set the
 *      TMS's cycleNumber and cycleType.
 *      It is designed to give an overview of using the API.
 */
#include <iostream>
#include <stdio.h>
#include <unistd.h>
#include <TmsD.h>
#include <TmsC.h>
 
using namespace Tms;
using namespace std;
 
// Loop sending next cycle information
BError tmsControlLoop(TmsControl& tmsControl){
        BError                  err;
        BUInt32                 cn = 0;
        BString                 ct = "Beam3";
        
        while(1){
                // Wait for next cycle information
                usleep(1200000);
 
                // Set next cycle information
                cn = cn + 1;
                ct = "Beam3";
 
                printf("SendNextCycle\n");                              
                // Send the next cycle information to the TMS server
                if(err = tmsControl.setNextCycle(cn, ct)){
                        cerr << "Error: " << err.getString() << "\n";
                }
        }       
 
        return err;
}
 
int main(int argc, char** argv){
        BError                  err;
        BString                 host = "localhost";
        TmsControl              tmsControl;
 
        if(argc == 2)
                host = argv[1];
 
        // Connect to the Control service
        if(err = tmsControl.connectService(BString("//") + host + "/tmsControl1")){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
 
        // Set the network priority high
        if(err = tmsControl.setPriority(BSocket::PriorityHigh)){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
 
        // Set the TmsServer thread priority high
        if(err = tmsControl.setProcessPriority(PriorityHigh)){
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
 
        if(err = tmsControlLoop(tmsControl)){   
                cerr << "Error: " << err.getString() << "\n";
                return 1;
        }
 
        return 0;
}