package require ReadoutRESTClient
ReadouRESTClient name ?option value...?
name configure option value ?...?
name begin
name end
name init
name shutdown
name getState
name getTitle
name getRunNumber
name getStatistics
name setTitle new-title-string
name setRunNumber new-run-number
The ReadoutREST package provides NSCLDAQ based Tcl driven Readout programs a REST server that can be used to remotely control and query the Readout. This facility is normally used in conjunction with the NSCLDAQ DAQ manager facility to manage Readout programs as critical programs that require attention during state transitions.
The ReadoutRESTClient package, ass the name implies, provides a Tcl REST client library for the ReadoutREST server.
Configuration options control how the REST client connects with the server. Note that each REST operations (public method call), performs service discovery, connects with the server, performs the request, gets the response and closes the connection.
Therefore the pre-defined configure
method allows client code to dynamically modify the server
options. Furthermore, this strategy supports the
case when the server exits and restarts, potentially with a different
server listen port, between requests.
Here are the options, their defaults and their meanings:
-hostTHe host in which the Readout program we want to communicate with is running. This defaults to localhost. Note, however that the use of locahost is not host portable. Please get in the habit of specifying a real hostname.
-user
The user the Readout program you want to communicate with
was run under. Defaults to the name of the person
runing the application. This, in conjunction with the
-service option below is used to
translate the Readout's service advertisement into a
numeric TCP/IP port number.
-serviceThe name of the servic advertised by the ReadoutREST package in the Readout we want to communicate with. This defaults to ReadoutREST which is the default service name.
Each of the public methods below performs a REST transaction with
the server. This transaction includes service discovery (translating
the -user and -service values to
a numeric TCP/IP port number), connecting with the server to perform
a REST transaction and unmarshalling any resulting JSON into
reasonable return values.
The methods which are considered public are:
beginAttempts to start a new run. The resulting Readout state is returned. Note that this is not the same as the DAQ Manager's state. If a transition to active data taking is not permitted (e.g. data taking is in progress) and error is raised.
endEnds active data taking in the Readout program. Returns the name of the resulting state.
initAttempts to initialize the hardsware in the Readout. Not all Readout programs support this. Those that do not are expected to silently ignore the request. Data taking must not be active.
shutdownRequests the Readout program to exit.
getStateReturns the current Readout program state.
getTitleReturns the currently set title.
getRunNumberReturns the currently set run number.
getStatisticsReturns a dict that describes the Readout's statistics. This is a dict with the keys cumulative and perRun. The cumulative key contains statistics over the course of the entire readout program while beginning a run clear the counters in the perRun statistics.
Each of the keys contains a value that is a dict which is identical, containing the following keys:
Number of triggers sent to the Readout.
Number of triggers that resulted in an event. This reflects the ability of some hardware (e.g. XIA modules) and some software to reject triggers resulting in no data.
Number of bytes read from the hardware.
setTitle title-string
Sets the Readout's title to the specified
title-string
setRunNumber5 number
Sets the new run number to number.