Interface Specifications

PROTOCOL

The user interface to the detector controller server supports standard TCP/IP sockets. The interface uses simple mnemonic, English-looking ASCII-character commands and return values.

CONFIGURATION

User-configurable parameters are defined in a configuration file which is read upon start-up of the server. When the server is run as a daemon then the configuration file will also be read when the HUP signal is received. The configuration file is ASCII plain text formatted as:

KEY=VALUE # optional comment

Configuration keys also support arrays by specifying the configuration line as:

KEY=(IDX VALUE)
KEY=(IDX VALUE)
etc.

This will assign VALUE to index IDX in an array of keys of name KEY. Allowed keywords are shown in Table 1. Any text following the number sign "#" is ignored and may be used to include comments. Some of these keys can only be set in the configuration file and cannot be changed while the server is running, but others are simply defaults which can be readily changed or overridden by a command. Keys which can be changed or overridden via command are indicated in the 3rd column of Table 1 by the command which changes them.

Table 1. Server configuration keywords

KEY	Description	Command override?
ARCHON_IP	IP address for Archon controller communications Archon only	no
ARCHON_PORT	Port number for Archon controller communications Archon only	no
EXPOSE_PARAM	Archon parameter used to trigger an exposure (param=1 to trigger exposure) Archon only	no
SHUTENABLE_PARAM	Archon parameter used to enable/disable shutter opening on exposure (see SHUTENABLE_ENABLE and SHUTENABLE_DISABLE) Archon only	no
SHUTENABLE_ENABLE	optional Value to write parameter identified by SHUTENABLE_PARAM which enables shutter opening on exposure. Default value is 1 if omitted. Archon only	no
SHUTENABLE_DISABLE	optional Value to write parameter identified by SHUTENABLE_PARAM which disables shutter opening on exposure. Default value is 0 if omitted. Archon only	no
HDR_SHIFT	Sets the number of bits to right-shift the Archon buffer when in HDR mode, i.e. SAMPLEMODE=1, 32 bits per pixel. Archon only	hdrshift
TRIGIN_EXPOSE_PARAM	Parameter name used to control normal, timed exposures triggered externally by TRIGIN. See External Triggering §8.1. Archon only	no
TRIGIN_EXPOSE_ENABLE	optional Value to write to parameter identified by TRIGIN_EXPOSE_PARAM to enable externally triggered timed exposures. Default value is 1 if omitted. Archon only	no
TRIGIN_EXPOSE_DISABLE	IP address for Archon controller communications Archon only	no
TRIGIN_UNTIMED_PARAM	Parameter name used to control start-of-exposure for untimed exposures triggered externally by TRIGIN. See External Triggering §8.1. Archon only	no
TRIGIN_UNTIMED_ENABLE	(optional) Value to write to parameter identified by TRIGIN_UNTIMED_PARAM to enable externally triggered untimed exposures. Default value is 1 if omitted. Archon only	no
TRIGIN_UNTIMED_DISABLE	(optional) Value to write to parameter identified by TRIGIN_UNTIMED_PARAM to disable externally triggered untimed exposures. Default value is 0 if omitted. `Archon only	no
TRIGIN_READOUT_PARAM	Parameter name used to control end-of-exposure for untimed exposures triggered externally by TRIGIN. See External Triggering §8.1. Archon only	no
TRIGIN_READOUT_ENABLE	(optional) Value to write to parameter identified by TRIGIN_READOUT_PARAM to enable externally triggered readout. Default value is 1 if omitted. Archon only	no
TRIGIN_READOUT_DISABLE	(optional) Value to write to parameter identified by TRIGIN_READOUT_PARAM to disable externally triggered readout. Default value is 0 if omitted. `Archon-only	no
DEFAULT_FIRMWARE	default firmware to load when load command is issued with no arguments	load §4.3.27
READOUT_TIME	detector readout time in msec, used to inform system of a timeout if readout doesn't occur within this time plus 10%
IMDIR	default base image directory	imdir §4.3.21
AUTODIR	set = "yes" or "no" to automatically create a UTC subdirectory for images, i.e. IMDIR/YYYYMMDD/filename.fits	autodir §4.3.3
BASENAME	default base image name for FITS files	basename §4.3.3
LOGPATH	fully qualified path to save log files	no
BLKPORT	blocking port number for the server	no
NBPORT	non-blocking port number for the server	no
ASYNCPORT	async message port number	no
ASYNCGROUP	asynchronous broadcast group	no
TM_ZONE	set to local to use local time instead of GMT. Defaults to GMT if this key is omitted	no
DAEMON	set to yes or no to run as a daemon or not. The command line "-d" option will override a "no" here.	no
LONGERROR	set true or false to enable or disable long error messages being returned on the command port	longerror §4.3.29
AMPS_AS_CUBE	for CCDs with multiple amplifiers, write each amplifier to a separate extension when = true. Default is false if undefined.	cubeamps §4.3.9

It is by convention only, and not a requirement that the server configuration file ends in ".cfg". There are no constraints on the configuration filename.

Timezone

By default, the system will use Universal Coordinated Time (UTC) for all logging and time stamps. Adding the line "TM_ZONE=local" to the configuration file will cause the system to use local time, which may be useful for lab testing where the UTC date could change in the middle of the day. The system will automatically include a FITS header keyword to indicate the time zone.

Ports

Communication ports are defined in a configuration file as described in Configuration, §3.2. The detector controller server uses three ports, a blocking port, a non-blocking port, and an asynchronous message port, defined by BLKPORT, NBPORT, and ASYNCPORT, respectively.

Blocking Port

When a client connects to the blocking port it will remain open as long as the client maintains its connection. This port can be used with Telnet (for example) to easily create a form of a command line interface. Only one command at a time can be received on this port. If the client tries to send a command before the previous command has completed, then it will be ignored. Completion of a command will be signaled by returning a response on that same port.

Non-Blocking Port

The non-blocking port will accept a single command and immediately close the connection. The server spawns a new thread for each non-blocking connection so multiple commands can be received on this port. Since each non-blocking connection is handled by a separate thread of executing, this means that non-blocking port commands are processed in their own thread, as simultaneously as the host CPU allows. Note that the order of processing of commands in these independent threads is not guaranteed so one must take care when sending commands to the non-blocking port. If the order of execution must be guaranteed then the blocking port should be used.

Since each non-blocking connection spawns a separate thread, in order to prevent multiple clients from wasting resources by opening connections to the non-blocking port and not sending a command, all non-blocking port connections will time-out and automatically close after a period of 3 seconds.

The server automatically guards against multiple simultaneous access to hardware which doesn't allow for it.

Asynchronous Message Port

The asynchronous message port is a connectionless UDP multicast port. The server will multi-cast datagrams to the broadcast group defined in the configuration file by ASYNCGROUP. Responses to commands sent on the non-blocking port, lengthy responses to all commands, and other instantaneous status messages (such as exposure time remaining, etc.) will be sent to the async port. Asynchronous status messages are preceded by a message tag to indicate the type or source of the message. These tags are listed in Section 5.

Clients

Any client which follows the TCP/IP protocol is capable of communicating with the detector controller server. Example clients might include scripting languages (MATLAB, Python, etc.), shell scripts, or even telnet, as described below.

Scripting languages

All common / popular scripting languages such as MATLAB, Python, etc. possess a TCP/IP stack and are capable of communicating with the server. In these instances it would be up to the user to develop an appropriate script for sending commands to, and receiving responses from the detector controller server, in accordance with this document.

Shell (e.g. csh, bash, etc.)

As another example, COO/OIR often uses a simple C-language based program called sendsockcmd 1 which accepts command line arguments to send an ASCII string to a specified host:port and then closes the connection. Combining this program with a shell script can make a quick and easy command-line tool for sending commands to the server, which can in turn be listed in a bash script for performing frequently used sequences.

[developer@localhost ~]$ cam open

which would send the "open" command to the localhost on port 2158. Similarly, entire shell scripts could be built around "cam" to send commands to the detector controller server.

#!/bin/csh
setenv camport 2158
setenv camhost localhost
setenv camtimeout 20000
set command = "$argv[1]"
shift argv
while ($#argv > 0)
set command = "$command $argv[1]"
shift argv
end
$HOME/bin/sendsockcmd -h $camhost -p $camport "$command" -t $camtimeout

Telnet

An example client can be as simple as using the telnet command which uses the Telnet application protocol. This can be useful as a quick check, or as a way to provide a simple, "no-code" CLI for test and engineering purposes by using telnet to connect to the blocking port.

An example telnet session might look like the following:

[developer@localhost ~]$ telnet localhost 3031
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
open
DONE
load
DONE
buffer 4200 4200
35280000 DONE
geometry 4200 4200
4200 4200 DONE
exptime 2000
2000 DONE
expose
DONE

DAEMONIZE

The user may choose to run the detector controller server as a daemon 2 . This might be done to ensure that the server runs independently of user activity such as logins, logouts, accidently closing a terminal, etc. To run the server as a daemon, add "-d" to the command line when starting the application or set DAEMON=yes in the server's configuration file.