guiServer Interface

The DiFX GUI controls DiFX using a network connection to the guiServer application running on the DiFX host. Effectively the GUI is only a visual front end - guiServer is where the actual control takes place. This document describes the network connection(s) and communication protocol that act between the DiFX GUI and guiServer - presumably any piece of software could exploit this interface and control DiFX externally.

Connecting

GuiServer needs to be started on the DiFX "host". The host can be any machine that has access to the DiFX applications (vex2difx, mpifxcorr, etc.). The user that starts guiServer must be able to run these applications. Once start, guiServer maintains an open TCP server socket at a port specifed by...

The last argument on the command line when guiServer is started, or failing that...
The value of the DiFX environment variable "DIFX_MESSAGE_PORT", or if that doesn't exist...
50200 by default.

Once a client connection is made on this port a thread is spawned to handle the communications, and the server waits for new connections - all typical TCP stuff. In theory any number of client connections may be made to guiServer.

Connection Protocol

The top-level connection between guiServer and its client is bi-directional. All communication, whether from client to server or the reverse, follows a fairly trivial "packet" protocol where each instruction, request, data block, whatever, is transmitted as follows:

Packet ID	Integer (network byte order)	A unique integer identifying the packet
Data bytes	Integer (network byte order)	Number of bytes that follow
Data	byte data (undefined order)	Packet content

The Packet ID should be recognized on both sides of the connection - the guiServer software will ignore any packet it does not understand (however it will use the "data bytes" number to completely read through and discard the data). In addition to the top-level connection, guiServer and the GUI can make a number of other connections using this same protocol. What defines the difference between the connections is the list of Packet IDs and what they mean.

This "packet" protocol rests on top of the TCP/IP "packet" structure, and should not be confused with it.

Top-Level Packets

The following Packet IDs are recognized by client, server, or both at the top-level connection. With each Packet ID is its integer value, whether guiServer and/or the client is expected to recognize and respond to it, and a brief description. Follow the links for each to get more information.

Packet ID	Int Value	guiServer	client	Description
RELAY_PACKET	1	X	X	Turn on/off multicast relay, or relay multicast packet to client
RELAY_COMMAND_PACKET	2	X		Broadcast XML to DiFX processes using multicast
COMMAND_PACKET	3	X		Send a command to guiServer (usually to run a DiFX function)
INFORMATION_PACKET	4		X	guiServer information for client
WARNING_PACKET	5		X	guiServer warning for client
ERROR_PACKET	6		X	guiServer error for client
MULTICAST_SETTINGS_PACKET	7	X		Change the multicast settings for the guiServer DiFX monitor
GUISERVER_VERSION	8	X	X	Request version information from guiServer or report it to the client
GUISERVER_DIFX_VERSION	9		X	Report version of DiFX used to build guiServer
AVAILABLE_DIFX_VERSION	10		X	Report a version of DiFX software the guiServer can use
DIFX_BASE	11		X	Base of DiFX software on the host running guiServer
GUISERVER_ENVIRONMENT	12		X	Environment variable accessible to guiServer
DIFX_SETUP_PATH	13	X		Path to the "execute" script
START_DIFX_MONITOR	14	X		Start a guiServer thread to monitor a job
DIFX_RUN_LABEL	15	X		The "label" of the DiFX version that should be used.
GUISERVER_USER	16		X	User that started guiServer

RELAY_PACKET

This is a bi-directional packet type - both guiServer and the client can use it. It is used in the relay of DiFX multicast (UDP) traffic on the DiFX host to the client. If sent to guiServer, the packet data is expected to be a single integer in network byte order, either 1 to turn on, or 0 to turn off multicast relay. If packet relay is on, every multicast message that guiServer sees will be relayed to the client with a RELAY_PACKET, the data being a string containing the multicast message. All DiFX multicast messages are XML, and will have to be parsed by the client to be useful.

RELAY_COMMAND_PACKET

Many DiFX processes accept XML instructions over the multicast network (primarily mk5daemon, but I believe there are others). For the most part guiServer replaces the functionality of this system, but there may be commands that it cannot perform. This packet type can be used in those cases. If received by guiServer, the data (an XML string) will be sent as a multicast, to be picked up or ignored by DiFX processes as they see fit.

INFORMATION_PACKET, WARNING_PACKET, ERROR_PACKET

These packets are generated by guiServer. They contain information, a warning, or an error that guiServer encountered in the form of a string.

MULTICAST_SETTINGS_PACKET

This packet can be used to change the group and port settings for multicast messages that guiServer receives from DiFX. There are default values for these items; for the group:

Following the command line argument "-mg" when starting guiServer, or if not included...
The value of the environment variable "DIFX_MESSAGE_GROUP", but if that doesn't exist...
A default value of "224.2.2.1".

For the port:

Following the command line argument "-mp" when starting guiServer, or if not included...
The value of the environment variable "DIFX_MESSAGE_PORT", but if that doesn't exist...
A default value of "50200".

The packet data is a string, with the group first and the port second, separated by a newline character. When this packet is received, guiServer will change the settings for its multicast monitoring.

Initial Handshaking Packets

When the GUI makes a connection to guiServer, it requests information about guiServer and its environment. This triggers a series of packets with different Packat IDs from guiServer to the client. It isn't critical that you do this when making a connection, but it can tell you lots of information about how guiServer will run DiFX.

GUISERVER_VERSION

This packet, with zero-length data, is used by the client to request version information from guiServer. It triggers the following packets, so the client needs to be ready to receive them.

Once this request is received by guiServer, it will respond using the same Packet ID, but with string data containing the version of guiServer (or "unknown" if it can't be determined). This is a guiServer-specific version - it doesn't match the DiFX version.

GUISERVER_DIFX_VERSION

This packet contains, as a string, the version of DiFX that the guiServer was compiled under.

DIFX_BASE

This packet contains the "base" of the DiFX software on the DiFX host (as a string). This value comes from the environment variable "DIFX_BASE". It can also be set using the "-b" argument when guiServer is started.

GUISERVER_USER

This packet contains the user that started guiServer. The value is the result of a "getlogin()" function call.

AVAILABLE_DIFX_VERSION

This packet contains the name of a DiFX version that guiServer has access to. There can be any number of these. The values are found by listing all files matching the name "[DIFX_BASE]/*/setup_difx.*". The names of the extensions of the "setup_difx.*" files are assumed to be DiFX version names.

GUISERVER_ENVIRONMENT

This packet contains an environment variable, and its value, separated by "=" in a string. One of these packets is sent by guiServer for each environment variable it has access to.

DIFX_SETUP_PATH

This packet contains the path to an "execution script" that is used by guiServer to run DiFX functions. When guiServer runs a DiFX program (as an example, use vex2difx), it inserts this script in a system command as follows:

	[DIFX_SETUP_PATH] vex2difx [ARGS]

Note that the string used for the DIFX_SETUP_PATH can be anything you want - as long as it contains some method of executing the commands that follow it.

The purpose of the DIFX_SETUP_PATH is to allow guiServer to execute different versions of DiFX. The execution script is used to source the proper setup file for the version (putting in place all of the correct values for environment variables), then execute the command.

START_DIFX_MONITOR

This packet tells guiServer to start a new thread containing a "DiFX monitor". The packet contains a port number (in string form) for a server port opened by the application sending the START_DIFX_MONITOR packet (e.g. the GUI). The DiFX monitor thread will immediately attempt to make a TCP client connection to the specified port (using the IP address the packet came from). When that is successful, an interactive session is started between the client (the thread) and the server that follows the same "packet protocol" described above, but with a different set of packet IDs and functions.

Packet ID	Int Value	thread	server	Description
MESSAGE	0
WARNING	1
ERROR	2
INPUT_FILE_PATH	3
CLOSE_CONNECTION	4
NUM_BASELINES	5
NUM_FREQUENCIES	6
BASELINE	7
FREQUENCY	8
NUM_SCANS	9
SCAN	10
TELESCOPE_1	11
TELESCOPE_2	12
CORRELATION_PRODUCTS	13
NUM_PHASE_CENTERS	14
PHASE_CENTER	15
NUM_PULSAR_BINS	16
PULSAR_BIN	17
NUM_POL_PRODUCTS	18
POL_PRODUCT	19
NEW_PRODUCT	20
AUTOCORRELATION	21
PRODUCT_REQUEST	22
START_PRODUCT_REQUEST	23
END_PRODUCT_REQUEST	24
VISIBILITY_DATA	25
AMPLITUDE_DATA	26
PHASE_DATA	27
LAG_DATA	28
END_VISIBILITY_BLOCK	29
JOB_NAME	30
OBS_CODE	31
SCAN_IDENTIFIER	32
SCAN_START_TIME	33
SCAN_END_TIME	34
SOURCE	35
SOURCE_RA	36
SOURCE_DEC	37

DIFX_RUN_LABEL

This packet contains the "label" (as a string) of the DiFX version that should be used when guiServer runs any DiFX function. The label was used to determine which "setup" script to execute as part of any DiFX command. However this functionality has been replaced (and made more flexible) by the DIFX_SETUP_PATH packet, so this packet probably has no effect at this time.