All control and monitor between the EVLA monitor and control (M&C) system and the WIDAR M&C is done by passing XML Documents over the VCI. The content and format of these documents are formally specified using XML schema.

Current schema documentation can be viewed at http://www.aoc.nrao.edu/asg/widar/schemata/vci/. The documentation is stored in subdirectories by version number with the latest version being pointed by a symbolic link called 'current-version'.

VCI Communication Architecture

From the beginning, the WIDAR correlator was designed to be monitored and controlled by state-passing rather than by remotely calling functions. In the latter, known as Remote Procedural Calls (RPC) architectures, one computer makes function calls remotely, over the network, to a system it wants to control and monitor. The disadvantage of RPC architectures is that the controlling computer has to know how the controlled system works. This is what is known as 'tight coupling' in an interface because any change to how the controlled system works has to be reflected back in the controlling computer.

The VCI utilizes a combination of TCP/HTTP/REST and UDP/Muliticast protocols to communicate state information between the controlling/monitoring systems (mainly the Executor and MCAF) and the controlled/monitored system (the WIDAR correlator). By passing state information, Executor can simply tell WIDAR what configuration (state) it wants it to be in. WIDAR's Configuraton Mapper (CM) knows how to put the correlator hardware into that desired state. So it can be said that whats not hows are communicated over the VCI.

The VCI architecture is client/server based where the clients, as mentioned above, are mainly Executor and MCAF. The servers are the Configuratoin Mapper (CM), Delay Model Distributor, WBC Products Handler and the Switched Power Concentrator. All of these services are programs running in the Master Correlator Control Computer (MCCC).

The diagram above shows the various Internet Protocols used between the various clients and servers. The contents of the various messages and when & how they are sent are described in more detail in the 'VCI Messages' section below.

Communicating messages to configure the correlator for observations and then maintaining real-time 'calibration' during the observation is the core use of the VCI. This section discusses the messages used to do this.

Referring to the diagram above, at the beginning of an observation, three message passing events take place:

• A new observation is started by Executor by sending the Configuration Mapper a vciRequest message telling the CM the desired state the correlator should be configured to for the observation.
• The Executor requests a vciStbBbSlopeTable message containing Baseband Slope information from each of the Station Boards; this is used to set amplifier gains in the antennas for use during the remainder of the observation.
• MCAF sends a request to CM for a copy of the Configuration Document (which is the main body of the vciRequest sent from Executor to CM). MCAF uses various parts of this to build the Science Data Model (SDM) for the observation.

During the the observation:

• Executor periodically sends vciStbDelayModel messages over the VCI to tell the correlator what delays to insert into the signal path of each antenna.
• MCAF opens a TCP socket to the Switched Power Concentrator service over which a stream of vciSwitchedPowerTable message are sent that will end up in the SDM.

The rest of this section discusses each of these messages in more detail.

Configuring Hardware - the vciRequest and vciResponse VCI Messages

The vciRequest specifies the correlator configuration and an activation time of when to set it up. If the request meets the following requirements an 'Acknowledgement' (ACK) is sent back as the HTTP response in the form of a vciResponse:vciAck message:

• the request has been properly received,
• the basic syntactic and semantic checks are passed (it's 'well-formed' XML),
• the message has been stored in the queue and is waiting Activation Trigger.

If the request does not pass the tests, CM Raises an EVLA Alert, makes a log entry, creates and sends back to the requester (via the HTTP Response) a Negative Acknowledgement (NACK) in the form of a vciResponse:vciNack message that contains a copy of the received message and the reason for rejection. The VCI Request is then disgarded.

vciRequests are always sent via HTTP but vciResponses not necessarily.

Sometime later (after the HTTP communications has completed) but before the configuration is to be activiated it is checked for viability, in other words, for any inconsistencies and that there are enough hardware resources to obtain the specified products. If a configuration passes these tests a vciResponse:vciAccept is sent via UDP Multicast.

If a configuration request cannot be performed a vciResponse:vciReject is sent via Multicast with the reason why it was rejected, an EVLA Alert is generated, a log entry is made and all configuration messages for the specified activation time are discarded.

Finally at activation time, the configuration commands are sent internally (behind the VCI) to the various correlator components (CBE, Station Boards, Baseline Boards) to create the configuration. At this time a vciResponse:activationReport message is sent via Multicast.

Though not officially a part of the VCI, the Observation document is sent by Executor via Multicast to MCAF and CBE when a new configuration vciRequest is sent to the correlator. An example Observation document is shown here:

vci-messages-vciStbDelayModel
From WIDAR Delay Model Subsystem : Because of the geographical separation of the VLA Antennas, the wavefront of the received signal of an observed object reaches each antenna at a different time. The differences are compensated for in the correlator by inserting delays in the signal paths to effectively sychronize the arrival of the signals before correlation takes place.
A program called CALC from NASA uses ephemeris data for the Earth, the VLA's position on the Earth and the position of the observed source object to calculate the delay for each antenna in the observation. This information is collated by the EVLA Executor program into what are called Delay Models. Because of Earth's movement during the observation, the Delay Models must be recalculated periodically (on the order of every 10-seconds but the system is capable of processing Delay Models at fraction-of-second rates).
A Delay Model consists of a set of polynomial coefficient values, one set for each of the four IF's of each of the (up to) 32 antennas (128 sets of coefficient values).
The models are transmitted from the Executor in the form of XML over 128 separate UDP ports (one for each Station Board) to the DelayModelDistributor service on mccc.

vciStbBbSlopeTable
When observing calls for a frequency band change, the new band is calibrated in terms of signal attenuation and amplitude equalization across the width of the band - the latter is known as baseband slope. In order to do this, Executor queries the WbdProductsHandler service running on mccc for feedback from what the Station Boards are 'seeing' about the signals they are getting from their antenna. This query is done over HTTP using the WIDAR's REST infrastructure. The WbdProductsHandler in turn queries each Station Board CMIB associated with the antennas and IF's specified in Exceutor's request. Software on the CMIB obtains the signal characteristics from the Wideband Correlator (WBC) FPGA on its Station Board.
The information collected from each of the CMIBs is collated into one table that is sent back to the Executor which uses it to set the baseband slope and attenuation for each antenna/IF in the observation.

vciStbSwitchedPowerTable
The Station Board CMIBs generate what is called Switched Power values for each Filter Chip used in the current configuration. These values are used by backend software such as CASA. The SwitchedPowerConcentrator running on mccc software collects the values from each of the Station Board CMIBs normally at once per second (but we are spec'd to be able to provide them 10 per second). The values are then written out in a single stream to MCAF which writes them to the SDM (Science Data Model) file.
Clients (such as the primary client MCAF) 'subscribe' to the continuous switched power VCI message stream which is sent over TCP socket connections. There can be mulitple listeners to this data.

VCI Schema Files

The source files for the VCI schemata have a .xsd extension. These are compiled into a set of JAXB files with the .java extension that will further be compiled with the program that uses them; in the case of WIDAR this is the ConfigurationMapper program.

There are two places where the source (.xsd) files must be maintained: 1) the working file area where the files are checked out of SVN and edited/compiled and 2) the NRAO web server area where the source (.xsd) files are used for runtime XML validation and provide a web-based documentation area.

Working Area

The working files are located in SVN at https://svn.aoc.nrao.edu/repos/widar/trunk/schema/. There are other schemata located in this directory for other components of the WIDAR system such as CBE, Baselines Boards and Station Boards. The files associated with the VCI are located in the vci directory and are:

• widarCommon.xsd
• vci
• vciCommon.xsd
• vciLog.xsd
• vciRequest.xsd
• vciReponse.xsd
• vciStbBbSlopeTable.xsd
• vciStbDelayModel.xsd
• vciStbSwitchedPowerTable.xsd

widarCommon.xsd is not strictly for VCI schema, it provides common definitions across all WIDAR schemata.

Documentation and Validation Server Area

This directory is located at /home/asg/www/widar/schemata/vci/ and is part of the NRAO web services. The URL to this area is: http://www.aoc.nrao.edu/asg/widar/schemata/vci/.

As can be seen above, each new version gets its own directory. This must be created by hand and the source .xsd files copied into it from the work area (after the new changes were made of course). At this time, XMLSpy can be used to generate the documentation files.

Editing and Compiling Files

The files can be edited using just a standard text editor or an XML editor such as XMLSpy. Only the working area files should be edited, the documentation and valaidation server files should be copies of the edited, SVN-based, working area files.

Compilation is done using the command ant genJaxb from within the vci directory. This will generate the associated JAXB files that CM and other EVLA programs use that utilize the VCI.

XMLSpy changes the indentation of the .xsd files to using large 8-space tabs which gets messy and causes grief when attempting an 'svn diff' because almost the whole file will be different making the changes lost in the noise.
One way around this is to load the file into emacs and re-indent it using the command: ^ alt \ (control-alt-\) or MX indent region. The text to be re-indented must be highlighted.

VCI Version Number Changing

The VCI has a version number associated with it in order to facilitate synchronization across all users of it such as CM and Executor. At the time of this writing it was in the process of being changed to 3.18.2. When new functionality is being added, such as the frequency averaging change the first decimal number ('18' in this casee) is incremented. When non-functional changes are made, such as when we promoted the binWidth attribute from a float to a double only the second decimal ('2') is incremented.

The version number is changed in the vciCommon.xsd file and must be hand-changed in two places: the VciProtocolVersionTyp enumeration and the version attribute. This code snippet from vciCommon.xsd illustrates where the version was changed to 3.18.2:

vciCommon.xsd is included in the vciRequest.xsd so the JAXB version of vciRequest will have the version attribute filled in with the default value at compile time. This will be used to find that version of the schema source file that will be used for validation at runtime as described below.

Run Time XML Validation

The source files in the NRAO server area can be accessed by software (such as CM that uses the VCI for the purpose of runtime XML validation against the schema located here.

When CM starts up, the Constructor for VciConfigMapper is run and the vdiRequestSchemaLocation variable is populated by fetching the latest version from the vciRequest JAXB code that was generated at compile time as shown below.

Documentation

While the .xsd schema files may be edited using simple text editors, to generate the official documentation diagrams requires the program XMLSpy which, unfortunately, only runs in Microsoft Windows. It costs money and there are very few licenses for it in our group but it does generate nice documentation that benefit all users of the VCI.

While operation of XMLSpy is beyond the scope of this document a brief description of how to use it to generate a documentation web page on an already edited schema file can be shown here.