The ReadoutREST package provides a REST server to NSCLDAQ Tcl based Readout programs that adhere to the standard Readout command set. Clients can interact with this REST interface to both control the state of the Readout program and obtain status information.
The intent of this server is to support Readout programs that are run under the control of the DAQ manager subsystem, however, in fact, any situtation in which a Readout program must be controlled remotely is supported.
The server package (tclhttpd) used to implement the REST server divides the URL space recognized by the server into Domains. A domain is a URL prefix. Three domains are supported by the ReadoutREST package:
Obtains status and state information
Sets parameters (e.g. title or run number).
Controls the Readout.
Before describing each of these domains, it's important to describe URL formation. Recall that a URL has the form http://host:port/path/to/resource. The host part of the URL is trivially the host in which the Readout program exporting the REST service runs. The port, in general, is dynamically assigned by the NSCLDAQ Port manager and associated with a named service advertised by the server, qualified by the user running the program. The default service name is ReadoutREST. This must be translated into a port via interactions with the host's DAQ Port manager. The top level of the /path/to/resource is a domain as described above. E.g. http://somehost:39998/status/state is a URL that (assuming the host and port are correct) within the /status domain that returns the program state.
Finally a bit on what the server returns in response to its requests. All reqplies are a JSON encoded object (mimetype application/json). THe object has two standard attributes and additional attributes that depend on the request. The two standard attributes are:
The status of the request. This is either OK or, if the server recognized the request but, for some reason, could not execute it (e.g. a request for an invalid state transition), ERROR
A human readable error message in the event that status was ERROR
In subsequent documentation we will only describe the additional attributes each request can return if status is OK
As described above, this domain provides state/status information. Requests are made using additional URL path elements e.g. in http://host:port/status/request-type, request-type is the request. Supported requests and the additional JSON attributes they return are:
Returns the Readout's state in the state attribute. This is a string that can be one of: idle, active, or paused.
Returns the Readout's title as the string value of the title attribute.
Returns the Readout's run number as the integer value of the run attribute.
Returns readout statistics. These are provided in JSON encoded objects that are values of the cumulative and perRun attributes which provide statistics over the lifetime of the Readout program or over the current (or most recent if the state is idle) run.
Statistics objects have the following attributes:
Number of triggers seen by the readout.
Number of triggers that resulted in events.
Number of bytes read from the hardware. Note that this explicitly does not include Ring item overhead or body header sizes.
This domain provides the abilityfor the client to request state transitions of the Readout program. All requests must be POST requests and must have a POST parameter called operation that indicates the state transition requested. the returned JSON includes an attribute, newstate that provides the state of the program after the transition.
Valid values for the operation POST parameter are:
Not actually a transition. This operation is legal in the idle state. It requests that the Readout program perform what is normally one-time hardware initialization. This is not fully supported by all Readout frameworks. If not supported it is silently ignored (although the requirement the state by idle is enforced).
Begins a new run. State must be idle
Ends the current run, the state must be either active or paused
Always legal, this operation requests the program shutdown (exit).
Note that while the state paused is recognized and END can end the run when the program is in that state, the REST interface does not fully support paused runs, in the sense that there is no mechanism to transition the run into the paused state.
This domain supports setting Readout parameters. All operations must be POST operations and two post parameters are required: name, which is the name of the parameter to modify and value the new value to give to that value. Return data does not provide any additional JSON attributes.
The name parameter can be either title, in which case value is a new title string, or run, in which case value must be a new positive integer run number.