Set the state of the readout GUI.
Attempt to begin a run.
Attempt to end a run.
Get state from the readout GUI.
Re-initialize the ReadoutGUI's data sources.
Request an arbitrary state transition.
The remote control protocol allows an NSCL Reaodut control panel to be driven remotely by a client. In addition, the client may capture output that goes to the output tabs of the Remote controlled GUI.
A remote controlled ReadoutGUI is said to be enslaved. While there is nothing to stop a system from being remote controlled by several clients, this is not recommended as there's not a good way to keep those clients atomically updated as to the system state.
GUI control panels must be declared elligible for remote control. See the Remote control package section of the ReadoutGUI & ReadoutShell chapter of the general documentation for information that describes how to do that.
A readout GUI that can be remote controlled advertises two services with the DAQ Port manager:
The service to which remote control commands should be directed.
A service that can be connected to in order to capture output that normally goes to a remote controlled ReadoutGUI's output window. This allows the controlling process to report to its user the output that normally would only be shown on a controlled Readout GUI's control panel.
As of NSCLDAQ-12.0, the names of these services can be overridden by supplying them to the RemoteControlClient::initialize command.
The controlling protocol is fully textual. The connected process will be referred to as the master and the remote controlled. The connected process can only have one request in-flight at a time. Requests are textual in nature and must be sent as a single contiguous message. The slave will reply to the request with a message that consists of textual line terminated with the \n (newline) character. Lines will consist of a word of status followed by any additional text needed by the reply.
The status word will be either OK or ERROR or FAIL. OK indicates the request was successful and any additional text depends on the request. FAIL and ERROR indicate the request failed and any additional text is a human readable error message.
The next section will describe the allowed requests.
Sets a parameter in the remote controlled GUI. The following are legal values for [what] and information about the values each parameter can be given:
If the value is 1, the GUI is set to slave mode. This removes or disables most of the run control controls on the GUI since those could conflict with the desires of the master.
If the value is 0, the GUI is removed from slave mode. The run controls that were removed or disabled when in slave mode are restored to their normal states and appearance. This is automatically done when the master closes the connection to the slave.
Note that the run state must be halted in order to enter slave mode. This means that the data sources have been setup and initialized and a run could be started in the slave GUI.
On success the return string has no additional values other than the status word (OK).
Requests that the run number be changed to new-run-number which must be a positive integer. This is only allowed when slave mode is enabled. If this request is issued when the run is not halted, the new run number will take effect at the beginning of the next run.
Requests that the run title be changed to new title string. This is only allowed when slave mode is enabled. If requested in the middle of the run, the new title will take effect at the beginning of the next run. Note that since the ReadoutGUI is a Tcl application, you must take care not to include or to properly quote title characters that have significance to the Tcl interpreter.
Enables or disables event recording. This is only allowed when slave mode is enabled and will take effect on the beginning of the next run.
Sets a new top level directory for the event recording file-system. This is only legal in slave mode. This should not be done when the run is actively recording as it can cause errors when the recording run ends.
Attempts to start a new run. This is only legal if slave mode is enabled (see set slave) and, of course the current run state makes starting a run possible.
This request has no additional data. If successful OK is the reply with no additional data.
Attempts to end an active run. This is only legal if slave mode is enabled and the current run state allows the run to be ended. The request has no additional data. The reply on success is OK without any additional data.
Requests a transition to an arbitrary state. This requires that slave mode is enabled and that the proposed target state, to-state is legal given the current state. If the state transition was successful OK is returned with no additional data.
See the chapter on the ReadoutGUI & ReadoutShell for a diagram showing the legal states and the transitions allowed from each state. Note that this request takes as additional data the name of the proposed target state, not the transition name in that diagram (.g. to resume a paused run, the to-state should be Active not Resume).
Reinitializes the data sources controlled by the readout gui. The GUI must be in slave mode and the state must be Halted to successfully request this operation. OK is returned on success with no additional data.
Returns the value of the requested state. state returns the current run state. On success, this is the string OK followed by one of the state names in the ReadoutGUI state diagram shown in the chapter ReadoutGUI & ReadoutShell.
slave returns OK followed by 1 if the GUI is in slave state or 0 if not.
Failures return ERROR and the reason for the error as a human readable string.
If an illegal service request is made, the error return will be FAIL with a human explanatory error string.