Rick Fisher, September 2000
INTRODUCTION
This document is intended for the glish programmer who wants to add a
new device to the GBT's observer interface (GBT Observe). All of the
glish code is checked into the GBT Monitor and Control CVS version
control system so code check-in/out and installation works the same
way as it does for C++ code. The code development directory structure
is described in another section below.
A device is usually a specific hardware module in the GBT system, such
as the antenna, a spectrometer, or a receiver front-end. Each device
requires three new glish scripts plus a few additions to existing
scripts that are common to all devices. The device-specific scripts
are the parameter definitions, 'go_xxx_params.g' in the Include
directory, the GUI panel definition, 'go_xxx.g' in the Panels
directory, and a simulator script, 'go_sim_xxx.g' in the Simulator
directory, where xxx is the device mnemonic. A fourth script,
'run_xxx.g' in the Panels directory is usually handy for testing the
device's observer interface on its own before tying it into the GBT
Observe main panel.
The best order for writing the device scripts is simulator, parameter,
panel, and finally test since this is their dependency hierarchy. The
simulator and test scripts are not strictly necessary, but they make
debugging the interface much faster. The simulator script is
particularly handy since it circumvents the necessity of getting time
on the hardware to debug code until final integration. The simulator
should be considered part of the final GBT Observe package since it
can be exported to other sites where observers can debug their
observing programs on a functional replica of the GBT control system.
SIMULATOR SCRIPT
A device simulator is a functional substitute for the glish client
connection to the M&C software for that device. It accepts parameter
value setup events, returns parameter value events as verification, and
runs through a sequence of states (Ready, Activating, Committed,
Running, Stopping, Ready) when a scan is initiated. Most of the
device client functions defined in /home/MU/glish/ygor.g are
duplicated in the simulator, although some of these functions may be
effectively no-ops since they don't have much use in the observer
interface. Each device has its own simulator script found in the
Simulator/ development directory.
A glish device simulator can be as sophisticated as one wishes as long
as it looks like the real thing to the observer interface. The
antenna simulator contains quite a bit of antenna slewing and scanning
logic and a positional display to present a fairly realistic picture
of GBT actions to the user when running GBT Observe with the
simulator. Since the antenna is usually the pacing device in a scan
sequence, its simulator is used as a key element in the simulator
structure, but otherwise the device simulators are largely
independent, as are the devices in the real GBT M&C architecture.
Adding more sophistication to the simulators might be useful to
observers in program preparation, but this can wait until the demand
warrants.
The simulator keeps its own internal clock, which is initiated to the
current wall clock time when the simulator is started. However, this
clock is incremented only when the antenna is slewing to a new
position or running a scan. After a scan ends and before the next
scan start command this clock is stopped. The assumption is that the
simulator will be used to test a sequence of scans with little dead
time between them. Also, the simulator may be run at three times real
time or as fast as the computer can processes the scan sequence
functions and antenna motion simulations, so the simulator clock is
expected to get out of sync with the wall clock. The simulator clock
may be changed by entering new values in the MJD and UTC fields at the
top of the antenna simulator panel.
A simulator includes its own GUI panel for displaying parameter values
as it is aware of them. This was useful in the initial stages of
constructing the observer interface, but it has mostly fallen into
disuse. As a result, the formatting functions for the simulator
display widget sets have not been developed to cover a few of the more
complex parameter values. Hence, only the beginning of a few of the
parameter record values may be displayed. Because there would be far
too many GUI panels on the screen if the simulator displays were
shown, all but the antenna position display are normally turned off.
The first step in building a new simulator script is to get a list of
the M&C parameters and typical values for the device. This can be
done with the script Ccode/devices.g. First, set up your UNIX
environment with
$ . /home/MU/gbt.bash
or
% source /home/MU/gbt.csh
Then run
$ glish -l /devices.g
This will produce glish output that looks something like
Devices:
LO1
ScanCoordinator Archivist SwitchingSignalSelector
DCR Holography SpectralProcessor
Spectrometer Antenna ActiveSurface
IFManager LO1 RcvrPF_1
Rcvr1_2 Rcvr2_3 Rcvr4_6
Rcvr8_10 Rcvr12_18 Rcvr18_26
IFRack ConverterRack AnalogFilterRack
MotorRack PF_SupportRack ResetBox
Weather
Managers:
LO1 LO1A LO1B
LO1Counter LO1Router
Exit the glish interpreter. Edit the devices.g file to put the name
of the device for which you are writing a simulator in the ygor
function argument, e.g.,
device := ygor('RcvrPF_1')
and re-execute
$ glish -l /devices.g
Then at the glish prompt execute the show_parameters function
- show_parameters(device, mgr)
from which you will see something like the following output:
Parameter count(manager=RcvrPF_1): 65
Parameters(RcvrPF_1):
1 asap(Bool): F
2 requestedStartTime(structure): [seconds=0, MJD=0, flags=0, \
refFrame=1, units=1]
3 requestedStopTime(structure): [seconds=0, MJD=0, flags=0, \
refFrame=1, units=1]
4 estimatedStartTime(structure): [time=[seconds=0, MJD=0, flags=0, \
refFrame=1, units=1], expiration=[seconds=0, MJD=0, flags=0, \
refFrame=1, units=1]]
5 startTime(structure): [seconds=0, MJD=0, flags=0, refFrame=1, units=1]
6 predictedStartTime(structure): [time=[seconds=0, MJD=0, flags=0, \
refFrame=1, units=1], expiration=[seconds=0, MJD=0, flags=0, \
refFrame=1, units=1]] p
7 scanLength(structure): [seconds=60, MJD=0, flags=0, refFrame=1, units=1]
8 nextScanNumber(int): 1
9 scanNumber(int): 0
10 projectId(String[16]): test
11 source(String[32]): test
12 scanId(String[32]): test
:
etc.
Save this listing in a file, e.g., rcvrpf_1.list, in the Ccode
directory since it can be edited to make an input list for the
creation of a device parameter template script. Each line contains
the following: the parameter index number, the M&C parameter name, the
C++ variable type in parentheses, and the current parameter value.
The C++ variable types (structure) and (enum) usually translate to
glish types record and string, respectively.
The first 16 parameters, 'asap' through 'status', are generally common
to all devices so these can be used as the basis for a simulator
template glish script in the file go_sim_template.g. See the comments
in this file for an explanation of the various simulator components.
The go_sim_gbt.g script file contains explanations of the functions
used to initiate parameter values and, if requested, display them on
simulator displays.
If you run the template tests script, 'test_templ_sim.gt', from the
Simulator directory, you will see the beginning of a device simulator
display screen. Use the command
$ glish -l test_templ_sim.gt
Finally, the scan coordinator simulator must be made aware of your new
device. Everywhere that you find the character string 'lo1' in the
script go_sim_sc.g you must add glish code following the examples set
by the code for existing devices. For examples, where you find the
line
new_state := max(gs.ant_state, gs.dcr_state, gs.sp_state, gs.lo1_state,
gs.conv_state);
change it to
new_state := max(gs.ant_state, gs.dcr_state, gs.sp_state, gs.lo1_state,
gs.conv_state, gs.XXX_state);
and where you find the lines
if (has_field(__gbt_simulator, 'lo1')) {
__gbt_simulator.lo1.agent->set_state(sim_state);
}
add the lines
if (has_field(__gbt_simulator, 'XXX')) {
__gbt_simulator.XXX.agent->set_state(sim_state);
}
where XXX is the new device's mnemonic. There are about a dozen
places in this file where additions are required.
PARAMETER SCRIPT
Device parameters known to GBT Observe are defined in a file named
go_XXX_params.g in the Include/ development directory, where XXX is
the device mnemonic. In most cases there is a one-to-one
correspondence between a GBT Observe parameter and an M&C device
parameter, and most M&C parameters are visible to GBT Observe.
However, additional GBT Observe parameters may be defined to present
the device setup in a way that is more natural to an observer or to
add higher level capability to the observer interface. In a few cases
device parameters interact, and this complexity must be handled in the
parameter script.
The parameter script assigns a name to each of its parameters which is
usually very similar to the corresponding M&C parameter name, but it
need not be. The GBT Observe parameter names are all lower case
without underscores or other special characters to follow the example
of Aips++. (Note that the GBT Observe table parser converts all
parameter name characters to lower case and deletes underscores, so
upper case and underscores may be used by observers for readability.)
A new device parameter script may be generated with the program
'gen_parm_file' in the Ccode development directory. The C++ source
code for this program is in the same directory. Program execution
arguments are the name of the file containing device parameter names
and an output file name for the parameter script template. For
example,
$ gen_parm_file rx12_list go_rx12_params.g
To create an example template for the purposes of this documentation,
the 'rx12' mnemonic has been changed to 'XXX' and the output file is
named go_templ_params.g.
The format for the input parameter list file is
:
etc.
For example,
XXX
start_time requestedStartTime
stop_time requestedStopTime
scan_length scanLength
scan_number scanNumber
proj_id projectId
source_name source
:
status status
state state
actual_start_time startTime
:
etc.
Three of the parameter names are required to be exactly as shown above
because thet are hardwired into the start/stop time GUI:
start_time requestedStartTime
stop_time requestedStopTime
actual_start_time startTime
The local parameter name in this file contains underscores to
distinguish the glish variable name from the parameter name used by
the observer. The underscores are deleted in assigning a GBT Observe
name. One way to get a list of M&C parameter names is to edit the
text saved from executing the 'show_parameters(device, mgr)' as
described above. The following common device parameters are not of
much concern to the observer interface so they may be deleted from
your list:
asap
estimatedStartTime
predictedStartTime
recipientNumber
debugLevel
Some of the other M&C parameters may not be of much interest to the
observer, but these will vary from device to device. An operational
understanding of the device is required to decide which parameters to
ignore. When in doubt, leave the parameter in the list. When
assigning local names to parameters keep in mind that the observer
only needs to enter the unique beginning of a parameter name, so the
unique part of the name might want to be moved to the front. For
example, M&C names noiseSourceSwR and noiseSourceSwL could be given
local names of right_sw_noise_source and left_sw_noise_source.
The file 'go_templ_params.g' in the Include/ development directory
shows the output of the 'gen_parm_file' program using the parameters
for the 12-18 GHz receiver (Rcvr12_18). In the creation of a real
device parameter for the 12-18 GHz receiver file 'go_rx12_params.g'
would then need to be edited according to the comments that have been
added to 'go_templ_params.g'.
After you have edited the parameter file for this device, add the
following three lines to go_sc_params.g in the scan coordinator's
control flag parameter set() function:
if (has_field(__go_parameters, 'XXX')) {
__go_parameters.XXX.control_flag.set(new_value);
}
where XXX is the device mnemonic. These statement enable the device's
control whenever the scan coordinator's control is enabled.
GUI SCRIPT
The last glish script that must be written for a new device is the GUI
panel definition. For simple devices a single panel will suffice, but
for more complex devices, like the spectral processor or spectrometer,
a number of subpanels may be appropriate to make efficient use of
screen space. A device's main panel needs to be made accessible from
the main GBT Observe panel as described below.
The panel definition scripts are in the Panels/ code development
directory. The file names are usually go_XXX.g, where XXX is the
device mnemonic. In the file Panels/go_templ.g is a template for a
new device panel script. See the comments set of by '##' for a
description of the essential parts of this template.
Before building the device's panel definition script, add the panel's
name to the Include/go_params.g list of panels by adding two lines
__go_panels.NNN := [=];
__go_panels.NNN.exists := F;
where NNN is the name that you choose for this panel. In the
go_templ.g file we have used XXX_setup for the panel name.
Initializing __go_panels.NNN.exists to boolean F keeps parameter
updates from writing to the panel before it is created.
All GUI widgets associated with GBT Observe parameters must be
initialized with one of the make_xxxx() functions defined in
Include/go_make_panel_fns.g. A make_xxxx() function creates a
subframe for the widget, places a label in the subframe, attaches the
parameter's help text to the label "button", creates the entry
field(s) or selection button(s) as appropriate, and adds a value units
field, if required. This function also creates an update() function
that must be used by the whenever statement in the parameter
definition script to update the displayed parameter value when an
event is received from M&C. Finally, the make_xxxx() function creates
a whenever statement for handling the event generated by user input to
the parameter widget, e.g., press or entry.
Before calling one of the make_xxxx() functions for a parameter to be
added to a panel, the parameter name must be added to the panel's
list of parameters using exactly the same name as was used for this
parameter in its definition file. This name identity is what links
the parameter to its entry widget.
When a parameter is added to a panel, its update function call must be
added to the whenever statement for this parameter in its definition
file. See, for example, the code surrounded by +++++++++ lines in the
Include/go_templ_params.g file. A parameter may appear on more than
one panel, and each placement requires a separate entry in the
whenever statement. With this mechanism, changing a parameter value on
any panel will cause it to be updated on all panels where it appears.
Notice that each update() call is protected by an 'if' statement to
make sure that the panel is being displayed. Note that the entry and
button update() functions are located in separate subrecords of the
__go_panels.XXX master record, so this may need to be modified in the
automatically generated parameter definition script.
To make the new device's panel accessible from the Main GBT Observe
panel it must be added to the list of "Other Panels" as described by
the ## comments in the sub_system parameter code in the
Include/go_sc_params.g script.
Finally, the device's parameter and panel definition scripts need to
be added to the Panels/go_main.g list of scripts to be run at startup
of GBT Observe. The lines to be added are marked by the placeholders
#include spaste(__go_directory.obs_gui, 'go_XXX_params.g');
and
#include spaste(__go_directory.obs_gui, 'go_XXX.g');
To test the new parameter and panels scripts without invoking all of
GBT Observe you can create an abbreviated main script by copying and
modifying the file Panels/run_templ.g to run your device code. It can
be run either with your simulator or connected to the real device
according to the value of the UNIX environment variable GBT_SIMULATOR.
Just be careful that you don't try to control a device being used by
someone else.
With the normal UNIX environment set for running GBT Observe the
run_templ.g file should produce a skeleton device panel that responds
to button presses and value entries, although not necessarily without
producing a few error messages due to incomplete code for this phantom
device.
DOCUMENTATION
The user's documentation of device and procedure parameters is
currently contained in the HTML file
~rfisher/public_html/Glish/gbt_procedures.html. When a new device is
added to GBT observe, it should be added to the table of contents of
this file and the parameter descriptions entered in the same format
shown for other devices. Most of the parameter descriptions are
modified text from the help strings in the parameter definition script,
so a good starting place is to copy these pieces text into the HTML
file.
DIRECTORY STRUCTURE
The code development directory structure is as follows:
Ccode
The key file in this directory is 'gen_parm_file.cc', which
contains C++ code for a program to generate a template glish
parameter script from a file that lists the M&C parameter
names and the corresponding GBT Observe parameter names.
Other files in this directory are mostly input or output files
for this program for different devices. The 'devices.g' file
is a glish script of device parameter access routines. The
file 'doppler.g' contains functions for computing various
doppler shift quantities.
Clients
Contains other directories which house C++ code for glish
clients built especially for GBT Observe.
GOmisc
This directory contains a glish client for handling a number
of utility functions that are not available (or were not
available when this project was begun), like string length,
binary file access, and tab conversion to spaces.
Sidelobes140
This directory contains code obtained from Ed Murphy for
computing approximate far sidelobe levels for the 140-ft. A
similar client should be developed for the GBT to aid
observers in planning observations to avoid having the sun in
strong sidelobes.
SolarSystem
This directory contains other directories that contain the JPL
solar system ephemeris glish client code along with a bunch of
test routines for the core C++ code that reads the ephemeris
data file.
SolSys
This directory contains the C++ code for accessing the JPL
ephemeris file and for a number of time and delay computation
functions. A library, libSolSys.a, is generated here.
SolSysClient
This directory contains the C++ code for the JPL ephemeris
glish client main program.
Table
This directory contains an old observing table parser that was
used before Darrell Schiebel wrote a more formal table parser
client, called 'obsparse'. The code in this directory is
obsolete.
Doc
Contains miscellaneous documentation files concerned with GBT
Observe programming, such as this one.
Include
This directory contains all of the glish scripts that define
the GBT Observe parameters and their connection to the M&C
device parameters. The parameters for each device are in a
separate script file, and there are a number of files that
contain common or similar information and functions for all
devices.
Panels
This directory contains files for glish scripts that define
the GUI panels for each device and for the main observing
panel. Each device, the procedure subpanel, and the table
parser have their own script file, and there are a few script
files that are common to all panels. File names beginning with
'run_' are stand-alone observer interface files for specific
devices.
RFImeas
This directory contains a subset of glish scripts for the
spectral processor that have been modified for use of the
spectral processor in connection with anechoic chamber RFI
measurements. These are not part of GBT Observe.
Simulator
This directory contains the glish script files for each of the
GBT device simulators plus a common 'ygor' simulator script.
Tests
Contains a miscellaneous collection of test scripts.
bin
This is a small subset of /home/MU/bin containing GBT
Observe client executables required for testing code locally.
The files here are symbolic links to the executables in the
origin client directories.
etc
This is a small subset of /home/MU/etc containing GBT
Observe resource files required for testing code locally.
glish
This is a substantial subset of /home/MU/glish containing GBT
Observe resource files required for testing code locally. All
of the flies are symbolic links to the origin files in the
Include, Panels, and Simulator directories