Overview of the DOM Surface Software

*- D R A F T -*

John Jacobsen

Lawrence Berkeley National Laboratory

jacobsen@rust.lbl.gov

Last updated April 9, 2001

**Abstract**

In 2000, a set of forty Digital Optical Modules (DOMs) were deployed at
the South Pole. The purpose of these devices is to sense faint light
signals from muon and neutrino radiation in deep Antarctic ice. In order
to build, test and operate the DOMs, a suite of applications was
developed using the Perl language. The applications rely on a
multi-layered, object-oriented communications Application Program
Interface (API), also written in Perl. This document describes these
applications and the API. It includes instructions for their
installation and use, as well as explanations about how they work.

**Note:** This document is a work in progress. Some sections are missing
or incomplete.

Table of Contents

Introduction [2](#introduction)

Overview of Digital String Components
[2](#overview-of-digital-string-components)

DOM Surface Software: Motivation and Philosophy
[3](#dom-surface-software-motivation-and-philosophy)

Organization of the Software [4](#organization-of-the-software)

Getting and Installing the Software
[4](#getting-and-installing-the-software)

Using the Applications [5](#using-the-applications)

Interacting with the DOM Boot program using domtalk
[5](#interacting-with-the-dom-boot-program-using-domtalk)

Interacting with the DOM Application using domtest
[8](#interacting-with-the-dom-application-using-domtest)

Controlling DOM High Voltages with domhv
[8](#controlling-dom-high-voltages-with-domhv)

Automated Data Taking with DOMLogger
[8](#automated-data-taking-with-domlogger)

The DOM Communications Protocol [8](#the-dom-communications-protocol)

The Communications API [8](#the-communications-api)

Detailed Descriptions of the Layers of the Communications API
[9](#detailed-descriptions-of-the-layers-of-the-communications-api)

The Functional Layer (DOMSet) [9](#the-functional-layer-domset)

The Messaging Layer (DOMMsg) [11](#the-messaging-layer-dommsg)

The Packet Layer (DOMPacket) [11](#the-packet-layer-dompacket)

The Serial Communications Layer (GenericDOMSerial)
[12](#the-serial-communications-layer-genericdomserial)

#  

# Introduction

This document describes software for communicating with and controlling
the string of Digital Optical Modules (DOMs) deployed at the South Pole
in January of 2000. The DOMs are custom-built optical sensors with fast
digitizing electronics, memory, and a controlling CPU, whose purpose is
the detection of faint light signals from charged particles travelling
through transparent materials (e.g., water or ice).

The programs described here together comprise the control software for
the DOMs. The software provides the interface which most people will use
in order to operate, diagnose and collect data from the DOMs. Written
entirely in Perl, the software includes a layered Application Program
Interface (API) for communications, and four applications which use the
API. A separate package of embedded software which runs on the CPU in
the DOM itself will be described elsewhere.

The subject of time calibration and other functions controlled by the
Test DAQ is currently covered in *Control of the LBNL Digital Optical
Module Test Boards Using a PC-104 Single-Board Computer*, by J.
Jacobsen. Eventually, that document should be absorbed into this one.

The primary application programs to be documented here are:

  ------------ ----------------------------------------------------------
  domtest      The main program for testing and configuring the DOMs.

  domtalk      A program for controlling DOMs in "boot mode."

  domlogger    A program for ongoing data collection from the DOMs

  domhv        A program for monitoring, setting and deactivating high
               voltage on the DOMs.
  ------------ ----------------------------------------------------------

The API used by these programs to access and control the DOMs will also
be described.

# Overview of Digital String Components

Before launching into the use, care and feeding of the applications
making up the DOM surface software, it is instructive to review the
various hardware elements at play. The current setup for controlling the
DOMs is somewhat complicated. It has several variants, so we will focus
on the setup consisting of four DOMs connected to the 2001 LBNL Test DAQ
(one alternate variant substitutes the data acquisition electronics
created at DESY for the LBNL Test DAQ).

As far as the hardware setup is concerned, the following elements are
involved (see Figure 1):

1)  The DOMs.

2)  The Test DAQ, consisting of a PC-104 CPU and four "test boards" with
    analog front-end electronics and a controlling FPGA. The PC-104 CPU
    "talks" to the test boards over a C-104 (ISA) bus. Each test board
    talks to a single DOM.

3)  A network-to-serial-port terminal server. Four ports are dedicated
    to DOM/test board pairs.

4)  A Linux PC (typically rust.lbl.gov or fireball.spole.gov) which runs
    the applications which access and control the DOMs.

5)  A GPS clock which sends timing signals to the PC-104 CPU.

These hardware elements are connected via several communications
channels:

1)  Four network sockets from the Linux PC to the terminal server. These
    carry commands ("DOM Messages") destined for the four DOMs, and the
    response data from the DOMs.

2)  Four RS-232 serial connections connecting the terminal server to the
    test boards.

3)  Four twisted pair cables carrying signals from the test boards to
    the DOMs.

4)  One network socket from the Linux PC to the PC-104 CPU in the Test
    DAQ. This socket carries commands to syncserver running on the
    PC-104, and the response data for each command.

5)  One RS-232 serial cable connecting the GPS clock to the PC-104
    system. The GPS clock sends an ASCII string with the UTC time to the
    PC-104 system, once per second. Syncserver reports this time in the
    response data for certain commands, sent over the network socket to
    the controlling Linux PC.

The diagram in Figure 1 illustrates these relationships:

Figure 1 - Digital String Components with Communications Channels
Illustrated

# DOM Surface Software: Motivation and Philosophy

The basic task of the software described here is to enable communication
with the DOMs. At the beginning, we simply needed for a user to be able
to sit at a Windows or Linux workstation hooked directly to a DOM
circuit board, to give commands to the DOM boot program and to see the
result. Free, publicly-available software such as TeraTerm was adequate
at first, but we soon needed extra capability such as the ability to
upload files with cyclic-redundancy checks (CRC) and more detailed
debugging of the communications functionality. The program domtalk was
written to address these requirements. Meanwhile, a more sophisticated
application (domtest) was also needed which would communicate with the
application embedded in the DOM using a packet-based messaging protocol.
Finally, it was anticipated that additional programs would be needed to
automatically control the DOMs and collect data. The program domlogger
does this. Since it was recognized from the beginning that multiple
programs would need to communicate with and control the DOMs in
well-defined ways, communications and control tasks were grouped
together in an API. The programs and the API grew as hardware and
firmware functionality improved.

The choice of Perl, a scripting language with associations to Web site
development and system administration, might seem a curious one.
However, Perl can be a very powerful tool for the quick construction of
prototype systems. It is fully object-oriented and benefits from a huge
user community, as well an extensive library of modules for networking
and myriad other tasks. Development time for projects carried out in
Perl tends to be significantly shorter than for other OO languages like
C++. While somewhat "high-level" when compared to languages like C, it
has functions for directly accessing data structures down to the level
of individual bits (a crucial capability for the DOM software). Perl
code executes surprisingly fast in most circumstances, and can
incorporate separately compiled, C-language modules. In our case, speed
was always constrained by network and communications bottlenecks, not by
CPU time.

In the case of the DOM software, the original motivation for using Perl
was to get something working as quickly as possible, but the language
proved to be a flexible and robust enough basis on which to build a
complete system. The development of the surface software took place in
parallel with the hardware production, testing and debugging, with only
minimal programming effort. It was possible to make additions to the
software very quickly to test new hardware functions as soon as they
became available.

All the programs described in this document are text-based rather than
GUI-based. This was a conscious choice based on the realities of low
bandwidth communications to and from the South Pole.

The software was developed and maintained in a Concurrent Versions
System (CVS) archive at LBNL, with mirrors at the South Pole. This
facilitated software installation at the remote site and reduced version
conflicts between different copies of the software.

# Organization of the Software

The DOM surface software consists of four applications - domtalk,
domtest, domlogger and domhv. These all use the communications API,
which encapsulate the various functions of the DOMs and the means of
accessing them through the terminal servers. The layers of the API are
as follows:

1)  **DOMSet - The Functional Layer.** A DOMSet object represents the
    functions of a collection of DOMs. Applications use the methods of
    DOMSet to instruct the DOM to perform high level tasks, and report
    any resulting error conditions. For example, the function
    SingleADCRead causes a message to be sent to the DOM requesting the
    value of a particular ADC channel on a particular DOM.

2)  **DOMMsg - The Messaging Layer.** A DOMMsg object implements the
    messaging protocol using the exchange of packets between the surface
    and the DOM.

3)  **DOMPacket - The Packet Layer.** Implements the sending and
    receiving of serial data in packet form.

4)  **GenericDOMSerial** - **The Serial Communications Layer.**
    Implements the sending and receiving of raw data over a serial
    connection. Has support for Linux (LinuxDOMSerial.pm) and Windows NT
    (Win32DOMSerial.pm, now deprecated).

Each of these layers is implemented by means of a Perl package which
describes an object (e.g., a DOMPacket object) with several methods
(e.g., send() and receive()).

The specifics of each layer will be described in more detail in Section
XXX.

# Getting and Installing the Software

The DOM software resides in a CVS repository on Rust.lbl.gov. Currently,
one needs a login shell account on Rust in order to get the software. If
you have such an account, and are logged into Rust, the command "cvs -d
/usr/local/cvsroot checkout domsoft" will copy the repository into your
current directory.

On a remote machine (at the South Pole, for example), you'll need:

setenv CVS_RSH ssh

cvs -d username@rust.lbl.gov:/usr/local/cvsroot checkout domsoft

Substitute your username on Rust for username. You'll have to give your
Rust password to get the files.

Once you have the repository copied to your directory, you can begin to
look at the Perl code. All the necessary code is in the directories
domsoft/src/domio and domsoft/src/portio. Portio contains code used to
interface with the PC-104 computer in the Test DAQ; portio contains all
the other software. The CVS repository also contains some assorted
documentation, as well as source code for the DOM Boot software. It does
*not* contain the source code to the DOM application.

The DOM surface software has a "release" location on both Rust and on
Fireball.spole.gov (the machine currently used to control the DOMs). The
location of the files is /usr/local/dom/bin and /usr/local/dom/lib. The
former must be in your PATH variable in order to use the release version
of the code (edit \$HOME/.login or \$HOME/.cshrc). If you just want to
use the "release" code and your path is set up correctly, then typing
domtest, domlogger, domtalk or domhv at the command prompt will start
the appropriate program.

The script domsoft/src/domio/install_domtest.pl will copy all the files
in your domio directory into the release directories. DO NOT DO THIS
unless you know what you're doing. This means you if you're just looking
at this manual for the first time!

Once you are comfortable making changes to the software (and, more
importantly, other people working on the DOMs are comfortable with you
making changes...), you can use normal CVS commands to bring the
repository up to date with your modifications. See the CVS manual
(http://www.cvshome.org/docs/manual/) for instructions about how to do
this.

The software is already installed on Rust and on Fireball. See the
author (Jacobsen) or Azriel Goldschmidt (AGoldschmidt@lbl.gov) if you
have additional questions.

# Using the Applications

As mentioned above, the DOM control applications are currently all
text-based programs that can be used from any real or virtual terminal
connected to the Linux control PC (e.g., rust or fireball). You need to
have the directory /usr/local/dom/bin in your path. Starting one of the
applications is then simply a matter of typing its name at the shell
prompt. You can also run the application directly out of your copy of
the domsoft CVS repository.

## Interacting with the DOM Boot program using domtalk

We start with an explanation of the two modes of DOM operation - "boot
mode" and "application mode." In boot mode, plain text commands are give
to the DOM Boot program ("domboot"). One can, for example, list the
current files in the flash file system, read out ADC values, or tell the
DOM to boot an application, at which time the DOM will be in
"application mode." In application mode, one can no longer communicate
using plain text, but must rather use the messaging protocol (explained
in detail below). The messaging protocol was developed to allow for
reliable communications at high speed using a well-defined data
structure that could be "spoken" by either the DOM's FPGA (in the case
of trigger data) or CPU (in the case of slow control information).

When a DOM is in application mode, one can get back to the DOM's boot
mode by power-cycling the DOM, or by issuing the "reboot" command to the
DOM's embedded application using domtest.

Domtalk was the first of the four surface applications to be written,
and is still the simplest. It allows you to communicate with the DOM in
boot mode. Using domtalk, you interact with the DOM by sending it
simple, single character commands, and seeing the result. For those
reading this manual who can remember manually dialing a modem using a
terminal program, the process is similar.

To run domtalk, type "domtalk" at the command line. You will be asked
for the name of a terminal server and a port number. The default
terminal server is at the South Pole; the default port is 3001, which
corresponds to port 1 on the terminal server. As a shortcut, you can
type "domtalk terminal_server port" on the command line, with
terminal_server a valid terminal server and port a number between 3001
and 3032.

You may have to type return to see the boot prompt from the DOM.

With one exception, the keystrokes you type while running domtalk are
sent to the DOM boot program. The exception is the escape sequence
"Control-\]". The escape sequence gives you a series of options:

> c: Continue s: Send file b: Change baud rate q: Quit
>
> B: Boot DOM Application

With the next keystroke, you can tell domtalk what you want to do. The
"Send file" option is used when sending a flash file to the DOM - do not
do this unless you have instructed the DOM Boot program to accept a
file! Otherwise you run the risk of having the DOM interpret the file
you send as a sequence of commands which can have bad side effects such
as the loss of data in the DOM flash file system. When you select "send
file," you can use tab-completion to list and complete file names, much
like in newer Unix shells like tcsh.

The other options are more or less self-explanatory.

This is not a manual for the DOM Boot program, and there currently is
none, but most of the commands you will encounter while interacting with
the DOMs using domtalk are self-explanatory. Also, see the example,
below.

Troubleshooting: if you start domtalk and can't seem to get a prompt
from the DOM Boot program, make sure that:

a)  the DOM is powered on (80 V), and is drawing current (\~ 29 mA). You
    may have to reboot the DOM if it is already booted fully into the
    application (domtalk won't work with a DOM running its application);

b)  you're talking to the right terminal server and port address

c)  if using a test board to communicate with the DOM, the test board
    FPGA is loaded successfully (see the document *Control of the LBNL
    Digital Optical Module Test Boards Using a PC-104 Single-Board
    Computer).*

**Example: Loading a New FPGA Design on a DOM**

In this example, we load an FPGA design file into the flash file system
of the DOM. We assume we have prepared an FPGA design file prepared with
a .fl extension (flash header bytes added using makeflash.pl). We
further assume the DOM is on the first terminal server port of a
terminal server termserv.lbl.gov.

First we connect with the DOM by firing up domtalk on rust.lbl.gov. In
all the examples, text in bold is typed by the user; non-bold text is
output from the program. \<CR\> means return is pressed:

> \$\$ **domtalk domtest.lbl.gov 3001**
>
> Welcome to /usr/bin/domtalk V0.2, by John Jacobsen / LBNL.
>
> Trying to create socket \...OK.
>
> Trying to talk to board domtest.lbl.gov:3001\... press \<return\> to
> wake up DOM.
>
> **\<CR\>**
>
> Domboot 1.16 DOM 16 Enter command (? for menu):

It is assumed that the DOM is already in boot mode or power-cycled just
before return is pressed, above.

We now list the contents of the flash file system using the "l" command:

> Domboot 1.16 DOM 16 Enter command (? for menu): **l**
>
> Filename: dom_hv_intg_application
>
> File ID: 4
>
> Major Version: 0
>
> Minor Version: 0
>
> File Type: Application
>
> Numb. Sectors: 2
>
> Start Offset: 0x00020080
>
> File Size: 240684 (0x0003ac2c)
>
> Filename: dom_test6
>
> File ID: 4
>
> Major Version: 0
>
> Minor Version: 0
>
> File Type: FPGA design
>
> Numb. Sectors: 1
>
> Start Offset: 0x00060080
>
> File Size: 45705 (0x0000b289)

Now we upload the FPGA file:

> Domboot 1.16 DOM 16 Enter command (? for menu): **u**
>
> Enter name of file you will upload:
>
> **dom_fpga_test**
>
> Enter the file ID, major version, minor version:
>
> **0 0 0**
>
> Enter the file type (0 = unknown, 1 = FPGA design, 2 = routine, 3 =
> application):
>
> **1**
>
> Send the flash file\...
>
> c: Continue s: Send file b: Change baud rate q: Quit
>
> B: Boot DOM Application
>
> **s**
>
> Type the name of the file you want. (Use the TAB key
>
> for file completion / directory listings) : **dom_fpga_test\<TAB\>**
>
> Unique match: ./dom_fpga_test.fl
>
> ./dom_fpga_test.fl**\<CR\>**
>
> Sending file ./dom_fpga_test.fl now (61735 bytes)\...
>
> Done sending file!
>
> c: Continue s: Send file b: Change baud rate q: Quit
>
> B: Boot DOM Application
>
> **c**
>
> Continuing\... press RETURN to get DOM prompt\....
>
> Sent = 0x5c50dd64 \-- Calculated = 0x5c50dd64
>
> Sent = 0xebfd2ab6 \-- Calculated = 0xebfd2ab6
>
> Sent = 0x571bbd85 \-- Calculated = 0x571bbd85
>
> *.... (checksums omitted) ....*
>
> Sent = 0x361010a6 \-- Calculated = 0x361010a6
>
> Sent = 0x3873a835 \-- Calculated = 0x3873a835
>
> Done. Wrote 61483 bytes, reached memory location 1018f0ab.
>
> 61483 bytes were loaded.

Now the FPGA design file must be loaded from the DOMs RAM into the flash
file system. The "f" command does this:

> Domboot 1.16 DOM 16 Enter command (? for menu): **f**
>
> Blowing RAM image into flash\...
>
> Sector mask = 0xffffc80f\...
>
> First sector used for the new file will be sector 11
>
> Flash ID = 00010001 22492249 00000000
>
> Done programming RAM buffer into flash.

The "l" command can now be used again to verify that the image has been
added to the flash file system. This is left as an exercise to the
reader.

## Interacting with the DOM Application using domtest

As of this writing, domtest is the program used most for interacting
with the DOMs. It runs in an interactive fashion, by presenting a series
of text-based menus with which the user specifies commands to be issued
to the application sitting in the DOM. When the user selects a
particular action, domtest sends one or more messages to the application
using the communications API outlined below. For each message, a
response is received and the results presented to the user.

Domtest also is used to set up the DOM configuration database,
associating DOM IDs with high voltage values, terminal server addresses,
and test board IDs.

Much more about domtest will follow in future versions of this document.

## Controlling DOM High Voltages with domhv

... More information to appear here soon....

## Automated Data Taking with DOMLogger

... More information to appear here soon....

# The DOM Communications Protocol

Section on the communications protocol developed by Chuck and
Karl-Heinz. ... More information to appear here soon....

# The Communications API

The Perl applications for communicating with and controlling the DOMs
make use of a set of communications layers. Generally speaking, each
layer is implemented by an object (Perl package).  Each object makes use
of the layer directly below it.  For example, the messaging object
(DOMMsg) makes use of a packet object (DOMPacket) to send and receive
chunks of a message.  

All the source code lives in the domsoft/src/domio directory on CVS. 
The code is written to work on a host PC running either Windows NT or
Linux.  All platform dependencies are taken care of at the low-level,
generic serial layer.

**Heirarchy of communications layers/object classes:**  

  ----------------------------------------------- -----------------------
  Functional Layer (DOMSet)                       

  Messaging Layer (DOMMsg)                        

  Packet Layer (DOMPacket)                        

  GenericDOMSerial layer - Linux or               Windows NT

  *Physical Hardware talking to the DOM: Serial   
  ports, terminal servers*                        
  ----------------------------------------------- -----------------------

# Detailed Descriptions of the Layers of the Communications API

## The Functional Layer (DOMSet)

The functional layer implements all functions for interacting with a set
of DOMs.  Uses DOMMsg objects to talk to the DOMs.

Class Methods\
 

+------------+-----------------+---------------+----------------------+
| **Function | **Arguments**   | **Return      | **Purpose**          |
| Name**     |                 | Values**      |                      |
|            | **(scalar,      |               |                      |
|            | unless          | **(scalar,    |                      |
|            | otherwise       | unless        |                      |
|            | noted)**        | otherwise     |                      |
|            |                 | noted)**      |                      |
+------------+-----------------+---------------+----------------------+
| new        | 1)  Mode:       | 1)  new       | Constructor of a     |
|            |     \"tty\" or  |     object    | DOMSet object        |
|            |                 |     reference |                      |
|            |    \"termserv\" |               |                      |
|            |                 | 2)  error     |                      |
|            | 2)  a reference |     string,   |                      |
|            |     to a hash   |     if object |                      |
|            |     of the form |     ref.      |                      |
|            |     given for   |     undefined |                      |
|            |     R_PORT_HASH |               |                      |
|            |     (see        |               |                      |
|            |     Fields,     |               |                      |
|            |     below).     |               |                      |
+------------+-----------------+---------------+----------------------+
| incremen   | the DOM\'s ID   | Incremented   | Increments the ID of |
| tMessageID | number          | message ID    | DOM                  |
+------------+-----------------+---------------+----------------------+
| ge         | the DOM\'s ID   | the current   | Gets current message |
| tMessageID | number          | message ID    | ID                   |
+------------+-----------------+---------------+----------------------+
| Sin        | 1)  The DOM\'s  | 1)  DAC value | Reads the last value |
| gleDACRead |     ID number   |               | written to the DAC   |
|            |                 | 2)  the error | channel              |
|            | 2)  the channel |     string,   |                      |
|            |     of the DAC  |     if DAC    |                      |
|            |     to read     |     val.      |                      |
|            |                 |     Undefined |                      |
+------------+-----------------+---------------+----------------------+
| Sing       | 1)  the DOM\'s  | 1)  Boolean   | Write a value to a   |
| leDACWrite |     ID number   |     success   | single DAC channel   |
|            |                 |     value     |                      |
|            | 2)  the channel |               |                      |
|            |     to write to | 2)  Error     |                      |
|            |                 |     string,   |                      |
|            | 3)  the value   |     if        |                      |
|            |     in DAC      |     failure   |                      |
|            |     units to    |               |                      |
|            |     write       |               |                      |
+------------+-----------------+---------------+----------------------+
| Singl      | 1)  DOM ID      | 1)  Number of | Read an ADC channel  |
| eADCStream |                 |     samples   | multiple times       |
|            | 2)  Channel ID  |               |                      |
|            |                 | 2)  Error     |                      |
|            | 3)  Time delay  |     string,   |                      |
|            |     in msec     |     if num.   |                      |
|            |     between     |     samples   |                      |
|            |     samples     |     undefined |                      |
|            |                 |               |                      |
|            |                 | 3)  Array of  |                      |
|            |                 |     ADC       |                      |
|            |                 |     values    |                      |
+------------+-----------------+---------------+----------------------+
| Sin        | 1)  DOM ID      | 1)  ADC value | Read an ADC value    |
| gleADCRead |                 |               | once                 |
|            | 2)  Channel ID  | 2)  Error     |                      |
|            |                 |     string,   |                      |
|            |                 |     if ADC    |                      |
|            |                 |     value     |                      |
|            |                 |     undefined |                      |
+------------+-----------------+---------------+----------------------+
| SetHVLimit | 1)  DOM ID      | Error string; | Set the maximum      |
|            |                 | \"ok\" if     | allowed anode and    |
|            | 2)  Max anode   | success       | dynode voltages      |
|            |     value (DAC  |               |                      |
|            |     units)      |               |                      |
|            |                 |               |                      |
|            | 3)  Max dynode  |               |                      |
|            |     value (DAC  |               |                      |
|            |     units)      |               |                      |
+------------+-----------------+---------------+----------------------+
| GetHVLimit | DOM ID          | 1)  Current   | Fetches the max.     |
|            |                 |     max anode | allowed anode and    |
|            |                 |     value     | dynode voltages      |
|            |                 |     (DAC      |                      |
|            |                 |     units)    |                      |
|            |                 |               |                      |
|            |                 | 2)  Current   |                      |
|            |                 |     max       |                      |
|            |                 |     dynode    |                      |
|            |                 |     value     |                      |
|            |                 |     (DAC      |                      |
|            |                 |     units)    |                      |
+------------+-----------------+---------------+----------------------+
| Ini        | DOM ID          | 1)  Challenge | Enables the setting  |
| tiateEnabl |                 |     value     | of HV (requires      |
| eHVRequest |                 |               | subsequent call to   |
|            |                 | 2)  Error     | VerifyEnableHV).     |
|            |                 |     string,   |                      |
|            |                 |     if        | USE WITH CARE.       |
|            |                 |     challenge |                      |
|            |                 |     value     |                      |
|            |                 |     undefined |                      |
+------------+-----------------+---------------+----------------------+
| Veri       | 1)  DOM ID      | Error string; | Verifies the request |
| fyEnableHV |                 | \"ok\" if     | to enable HV         |
|            | 2)  Challenge   | success       |                      |
|            |     value plus  |               | USE WITH CARE.       |
|            |     offset      |               |                      |
+------------+-----------------+---------------+----------------------+
| InitiateSe | 1)  DOM ID      | 1)  Challenge | Initiates a request  |
| tHVRequest |                 |     value     | to set the high      |
|            | 2)  Anode HV    |               | voltage on a DOM     |
|            |     (DAC units) | 2)  Error     | (must be             |
|            |                 |     string,   | successfully enabled |
|            | 3)  Dynode HV   |     if        | using                |
|            |     (DAC units) |     challenge | Ini                  |
|            |                 |     value     | tiateEnableHVRequest |
|            |                 |     undefined | and VerifyEnableHV;  |
|            |                 |               | requires subsequent  |
|            |                 |               | call to              |
|            |                 |               | VerifySetHV).        |
|            |                 |               |                      |
|            |                 |               | USE WITH CARE.       |
+------------+-----------------+---------------+----------------------+
| V          | 1)  DOM ID      | Error string; | Verify challenge     |
| erifySetHV |                 | \"ok\" if     | value and completes  |
|            | 2)  Anode HV    | success       | the request to set   |
|            |     (DAC units) |               | high voltage.        |
|            |                 |               |                      |
|            | 3)  Dynode HV   |               | USE WITH CARE.       |
|            |     (DAC units) |               |                      |
|            |                 |               |                      |
|            | 4)  Challenge   |               |                      |
|            |     Value plus  |               |                      |
|            |     offset      |               |                      |
+------------+-----------------+---------------+----------------------+
| DisableHV  | DOM ID          | Error string; | Disable high-voltage |
|            |                 | \"ok\" if     | on the DOM.          |
|            |                 | success       |                      |
+------------+-----------------+---------------+----------------------+
| T          | 1)  DOM ID      | 1)  Error     | Test reads the       |
| rigDiscrim |                 |     string;   | output of the        |
| inatorTest | 2)  Direction   |     \"ok\" if | discriminator for    |
|            |     (\"up\" or  |     success   | either single or     |
|            |     \"down\")   |               | multi photo electron |
|            |                 | 2)  Array of  | channel.             |
|            | 3)  Channel     |     values    |                      |
|            |     (\"spe\",   |     from the  |                      |
|            |     \"mpe\",    |     test      |                      |
|            |     \"spebar\", |               |                      |
|            |     \"mpebar\") |               |                      |
+------------+-----------------+---------------+----------------------+
| TrigD      | 1)  DOM ID      | 1)  Number of | Read out the result  |
| iscriminat |                 |               | of an FPGA test of   |
| orRateTest | 2)  Channel     | discriminator | the trigger          |
|            |     (\"spe\",   |     firings   | discriminator.  Must |
|            |     \"mpe\",    |               | set the appropriate  |
|            |     \"spebar\", | 2)  Error     | SPE or MPE           |
|            |     \"mpebar\") |     string;   | discriminator DAC    |
|            |                 |     \"ok\" if | first.               |
|            |                 |     success   |                      |
+------------+-----------------+---------------+----------------------+
| ComDiscrim | 1)  DOM ID      | 1)  Error     | Causes the           |
| inatorTest |                 |     string;   | application to       |
|            | 2)  Direction   |     \"ok\" if | histogram the Com.   |
|            |     (\"up\" or  |     success   | discriminator output |
|            |     \"down\")   |               | as a function of     |
|            |                 | 2)  Array of  | varying input        |
|            | 3)  Channel (0  |     values    | voltage.             |
|            |     .. 3)       |     from the  |                      |
|            |                 |     test      |                      |
+------------+-----------------+---------------+----------------------+
| Loc        | DOM ID          | 1)  Result    | Method causes FPGA   |
| alCoinTest |                 |     from      | test program to test |
|            |                 |     test:     | local coincidence    |
|            |                 |     single    | circuitry            |
|            |                 |     byte      |                      |
|            |                 |     pattern   |                      |
|            |                 |     from FPGA |                      |
|            |                 |     test      |                      |
|            |                 |     program,  |                      |
|            |                 |     or undef  |                      |
|            |                 |     if test   |                      |
|            |                 |     fails     |                      |
|            |                 |               |                      |
|            |                 | 2)  Error     |                      |
|            |                 |     string;   |                      |
|            |                 |     \"ok\" if |                      |
|            |                 |     success   |                      |
+------------+-----------------+---------------+----------------------+
| StartWa    | 1)  DOM ID      | Error String: | Begin a test of the  |
| veformTest |                 | \"ok\" if     | ATWD or slow ADC,    |
|            | 2)  Test Type : | success       | compiling statistics |
|            |     pick        |               | bin-by-bin for a     |
|            |     numeric     |               | number of iterations |
|            |     test type   |               | or triggers          |
|            |     from        |               |                      |
|            |                 |               |                      |
|            |  SymbolTrans.pm |               |                      |
|            |     (currently, |               |                      |
|            |     ranges from |               |                      |
|            |     0 to 30)    |               |                      |
|            |                 |               |                      |
|            | 3)  Poll Delay  |               |                      |
|            |     (msec)      |               |                      |
|            |                 |               |                      |
|            | 4)  Repetition  |               |                      |
|            |     count       |               |                      |
+------------+-----------------+---------------+----------------------+
| StopWa     | DOM ID          |               | NOT YET IMPLEMENTED  |
| veformTest |                 |               |                      |
+------------+-----------------+---------------+----------------------+
| G          | DOM ID          | 1)  Error     | Check on the status  |
| etWaveform |                 |     string :  | of an                |
| TestStatus |                 |     \"ok\" if | already-running test |
|            |                 |     success   |                      |
|            |                 |               |                      |
|            |                 | 2)  Numerical |                      |
|            |                 |     test id   |                      |
|            |                 |               |                      |
|            |                 |  (corresponds |                      |
|            |                 |     to \"test |                      |
|            |                 |     type\" in |                      |
|            |                 |     Start     |                      |
|            |                 | WaveformTest) |                      |
|            |                 |               |                      |
|            |                 | 3)  Current   |                      |
|            |                 |     state     |                      |
|            |                 |               |                      |
|            |                 |    (\"idle\", |                      |
|            |                 |               |                      |
|            |                 |  \"testing\", |                      |
|            |                 |     \"done\"  |                      |
|            |                 |     or        |                      |
|            |                 |               |                      |
|            |                 |    \"error\") |                      |
|            |                 |               |                      |
|            |                 | 4             |                      |
|            |                 | )  Repetition |                      |
|            |                 |     count:    |                      |
|            |                 |     how many  |                      |
|            |                 |     tests     |                      |
|            |                 |     have been |                      |
|            |                 |     performed |                      |
|            |                 |     so far    |                      |
+------------+-----------------+---------------+----------------------+
| GetWavefo  | DOM ID          | 1)  Error     | Fetches waveform     |
| rmTestData |                 |     string:   | test data in the     |
|            |                 |     \"ok\" if | default format       |
|            |                 |     success   | (E.g. tests such as  |
|            |                 |               | \"                   |
|            |                 | 2)  Numeric   | TT_ATWD0_CH0_HIST\") |
|            |                 |     test id   |                      |
|            |                 |               |                      |
|            |                 | 3)  Poll      |                      |
|            |                 |     Delay     |                      |
|            |                 |     (msec)    |                      |
|            |                 |     given at  |                      |
|            |                 |     start     |                      |
|            |                 |               |                      |
|            |                 | 4             |                      |
|            |                 | )  Repetition |                      |
|            |                 |     count     |                      |
|            |                 |               |                      |
|            |                 | 5)  Number of |                      |
|            |                 |     Bins      |                      |
|            |                 |               |                      |
|            |                 | 6)  Four      |                      |
|            |                 |               |                      |
|            |                 |    references |                      |
|            |                 |     to arrays |                      |
|            |                 |     of the    |                      |
|            |                 |     length    |                      |
|            |                 |     given by  |                      |
|            |                 |     \"Number  |                      |
|            |                 |     of        |                      |
|            |                 |     Bins\":   |                      |
|            |                 |     Minimum   |                      |
|            |                 |     values,   |                      |
|            |                 |     maximum   |                      |
|            |                 |     values,   |                      |
|            |                 |     sum of    |                      |
|            |                 |     values,   |                      |
|            |                 |     sum of    |                      |
|            |                 |     squares   |                      |
|            |                 |     of values |                      |
+------------+-----------------+---------------+----------------------+
| GetSpectr  | DOM ID          | 1)  Error     | Fetches channel      |
| umTestData |                 |     string:   | spectrum data for    |
|            |                 |     \"ok\" if | tests such as        |
|            |                 |     success   | \"TT_ATWD0           |
|            |                 |               | _CH0_INTEGRAL_HIST\" |
|            |                 | 2)  Numeric   |                      |
|            |                 |     test id   |                      |
|            |                 |               |                      |
|            |                 | 3)  Poll      |                      |
|            |                 |     Delay     |                      |
|            |                 |     (msec)    |                      |
|            |                 |     given at  |                      |
|            |                 |     start     |                      |
|            |                 |               |                      |
|            |                 | 4             |                      |
|            |                 | )  Repetition |                      |
|            |                 |     count     |                      |
|            |                 |               |                      |
|            |                 | 5)  Number of |                      |
|            |                 |     Bins      |                      |
|            |                 |               |                      |
|            |                 | 6)  Reference |                      |
|            |                 |     to array  |                      |
|            |                 |     of the    |                      |
|            |                 |     length    |                      |
|            |                 |     given by  |                      |
|            |                 |     \"Number  |                      |
|            |                 |     of Bins\" |                      |
|            |                 |               |                      |
|            |                 |    containing |                      |
|            |                 |     spectrum  |                      |
|            |                 |     for the   |                      |
|            |                 |     desired   |                      |
|            |                 |     channel   |                      |
+------------+-----------------+---------------+----------------------+
| PerformEc  | 1)  DOM ID      | Error string  | Sends data down the  |
| hoBackTest |                 | : \"ok\" if   | hole and sees if it  |
|            | 2)  Scalar data | success       | comes back intact    |
|            |     to send and |               |                      |
|            |     receive     |               |                      |
+------------+-----------------+---------------+----------------------+
| Get        | DOM ID          | 1)  Error     | Gets status of       |
| FPGAStatus |                 |     string:   | FPGA.  If            |
|            |                 |     \"ok\" if | \"unloaded\",        |
|            |                 |     success   | version IDs and      |
|            |                 |               | filename are         |
|            |                 | 2             | undefined            |
|            |                 | )  \"loaded\" |                      |
|            |                 |     or        |                      |
|            |                 |               |                      |
|            |                 |  \"unloaded\" |                      |
|            |                 |               |                      |
|            |                 | 3)  Major     |                      |
|            |                 |     version   |                      |
|            |                 |     ID        |                      |
|            |                 |               |                      |
|            |                 | 4)  Minor     |                      |
|            |                 |     version   |                      |
|            |                 |     ID        |                      |
|            |                 |               |                      |
|            |                 | 5)  Board ID  |                      |
|            |                 |               |                      |
|            |                 | 6)  FPGA ID   |                      |
|            |                 |               |                      |
|            |                 | 7)  FPGA      |                      |
|            |                 |     filename  |                      |
+------------+-----------------+---------------+----------------------+
| Lis        | DOM ID          | 1)  Error     | Sends a sequence of  |
| tFPGAFiles |                 |     string:   | DSC_FPGA_LIST_FILES  |
|            |                 |     \"ok\" if | messages to generate |
|            |                 |     success   | the list of current  |
|            |                 |               | FPGA files which are |
|            |                 | 2)  Array     | programmed into the  |
|            |                 |     with      | flash                |
|            |                 |     names of  |                      |
|            |                 |     files     |                      |
+------------+-----------------+---------------+----------------------+
| Lo         | 1)  DOM ID      | Error string: | Load the named file  |
| adFPGAFile |                 | \"ok\" if     | into the FPGA        |
|            | 2)  File name   | success       |                      |
+------------+-----------------+---------------+----------------------+
| Unlo       | DOM ID          | Error string: | Unload whatever is   |
| adFPGAFile |                 | \"ok\" if     | in the FPGA          |
|            |                 | success       |                      |
+------------+-----------------+---------------+----------------------+
| SetTime    | 1)  DOM ID      | Error string: | Set the bits of the  |
| TickParams |                 | \"ok\" if     | FPGA register        |
|            | 2)  Value of    | success       | responsible for      |
|            |     Time Tick   |               | configuring time     |
|            |     Byte        |               | ticks (see Jerry\'s  |
|            |                 |               | DOM FPGA API         |
|            |                 |               | document)            |
+------------+-----------------+---------------+----------------------+
| GetTi      | DOM ID          | 1)  Error     | Get various pieces   |
| meTickInfo |                 |     string:   | of information about |
|            |                 |     \"ok\" if | time ticks sent from |
|            |                 |     success   | and received by DOM  |
|            |                 |               |                      |
|            |                 | 2)  lower     |                      |
|            |                 |     4-byte    |                      |
|            |                 |     longword  |                      |
|            |                 |     of time   |                      |
|            |                 |     in DOM    |                      |
|            |                 |     when time |                      |
|            |                 |     pulse was |                      |
|            |                 |     captured  |                      |
|            |                 |               |                      |
|            |                 | 3)  upper     |                      |
|            |                 |     longword  |                      |
|            |                 |     of same   |                      |
|            |                 |               |                      |
|            |                 | 4)  longword  |                      |
|            |                 |     PMT       |                      |
|            |                 |     trigger   |                      |
|            |                 |     capture   |                      |
|            |                 |     time      |                      |
|            |                 |               |                      |
|            |                 | 5)  longword  |                      |
|            |                 |     time of   |                      |
|            |                 |               |                      |
|            |                 |  transmission |                      |
|            |                 |     to        |                      |
|            |                 |     surface   |                      |
|            |                 |               |                      |
|            |                 | 6             |                      |
|            |                 | )  pretrigger |                      |
|            |                 |     depth     |                      |
|            |                 |     read from |                      |
|            |                 |     DOM FPGA  |                      |
|            |                 |               |                      |
|            |                 | 7)  value of  |                      |
|            |                 |     time tick |                      |
|            |                 |     parameter |                      |
|            |                 |     register  |                      |
|            |                 |     at last   |                      |
|            |                 |     write via |                      |
|            |                 |     slow      |                      |
|            |                 |     control   |                      |
+------------+-----------------+---------------+----------------------+

Class Data for DOMSet objects

R_PORT_HASH : Reference to table of IDs / Port names in the form

{ 1 = \"domtest.lbl.gov:80\",\
   2 = \"termserv32.spole.gov:81\" }\
where the first scalar is the OM ID and the second is either IP
address:IP port or serial device file name.\
  R_MSG_HASH : Reference to table of DOMMsg objects

## The Messaging Layer (DOMMsg)

The DOMMsg layer implements the DOM Message Passing protocol, using a
DOMPacket object.

Fields

-   PORT : DOMPacket object

-   MSG_ERROR : String

Methods

-   new (\$mode, \$port)

-   msgError : query last message error type

-   type

-   subtype

-   msgID

-   msgStatus

-   msgStatusSeverity

-   msgErrorLogging

-   dataRef

-   dataLen

-   DOMid

-   sync

-   send

-   recv

>  

## The Packet Layer (DOMPacket) 

Implements the 8+1 byte DOM packet protocol (documented elsewhere?),
using a GenericDOMSerial object.

Fields

-   serialObject : GenericDomSerial object

-   PACKET_ERROR : Packet error type

-   timeoutSeconds

Methods

-   new

-   packetError : query last packet error type

-   outputPkt(\$pkt) : output packet \$pkt over the serialObject

-   inputPkt : reads (and modifies) packet from the serialObject;
    returns undef if troubles ensue.

##    The Serial Communications Layer (GenericDOMSerial) 

This is the lowest level object handles input and output over a serial
connection.  Functionality includes local serial port access or access
to the serial lines of a terminal server, via TCP/IP (currently Linux
only).  To handle the connection in a system-independent way, the
methods of the class are implemented with either Win32DOMSerial (Windows
NT code) or LinuxDOMSerial (Linux/Unix code).

Although some functionality has been built in for direct serial I/O (as
opposed to the more standard TCP/IP I/O using terminal servers), and for
Windows NT, these options are not fully tested and debugged as of this
writing.

Fields

-   mode (\"tty\", \"termserv\" or \"network\")

-   deviceName (e.g. \"COM1\", \"/dev/ttyS0\", \"128.104.238.212:80\")

Methods

-   new

-   initSerial

-   readNBytes

-   readSerialUntilTimeout

-   readSerial

-   writeSerial