1.1, 28 November 1996
The coding and functions of the A&G Box (AGB) server, as implemented in 1996 for the INT ICS, are described below for the benefit of engineers intending to test or modify the server. Information here refers entirely to internal details. Details of the external interfaces are contained in reference [1]. Reference [3] outines how to build install and configure the AGB server as part of the oberving system.
1.2 Scope and Overview
The AGB server is responsible for controlling the A&G box, and maintaining status information for all the various mechanisms for displaying on the Mimic and storing in the FITs header. The system is implemented as a set of Drama tasks.
Section 2 describes conventions and technologies used to build the system. The subtleties of the AGB server itself are outined in section 3. Section 4 described the operation of the clients and the mimic. Section 5 describes the source code components of the server itself, and section 6 those for the clients and mimic. A description of the serial port messages used to communicate with the AGB MMS are shown in Appendix A.
1.3 References
[1] Interfaces to the AGB server ING/RGO document INT-AGB-2, by Daniel Matthews
[2] IDS server detailed design ING/RGO document INT-IDS-3, by Daniel Matthews
[3] Transfer of DAS and ICS ING/RGO document
[4] DTCL Tcl interface to Drama AAO DRAMA software report 12
[5] srv Facility ING/RGO document , by Guy Rixon
All C code is compileable by ANSI compilers. Where possible, library calls are limited to ANSI and POSIX functions. Any non-POSIX calls should be carefully documented.
The starlink coding standards were loosely followed. Modifcations should follow the ING C coding standard.
2.2 Documentation standards
Technical documentation is produced using the ESA standards as a guide. They are produced in Interleaf format, and are maintained in the general ING catalogue of documentation.
Manuals for use by the observer, should also be available, on-line, in HTML format.
2.3 Naming conventions
The following naming conevntion was used throughout:
Names of compiled servers are lower case
Variable and function names are mainly lowercase, with uppercase letters inserted where words are concatenated eg: idsUpdateSlitShut()
Names of data types have the suffixe "_t" unless they are structure type in which case they have the suffix "_T", eg insParameterType_t and insClientDef_T
Constants, notably those declared as macros, are named in uppercase.
Source file names are in mixed case with the subsystem name as a prefix, eg agbComm.c
Names of Drama actions and parameters are all in uppercase.
2.4 Developement tools
The compiler and debugger from SPARCworks Professional C was used for developement. The lint provided with this package was also used. Version control used sccs, part of the Solaris deistribution. The "bom" facility is used for maintaining releases. The tools provided with DRAMA were also used, particularly ditscmd, sdslist and cleanup.
2.5 Infrastructure requirements
These are outined in the reference [3].
The portInit function is called by the INS facility as part of the initialisation at the start of main(). This initialises the communications port to the AGB. It sets it to 9600 buad, 7 bit, parity enabled. It also sets the port to canonical input, meaning, among other things, the server will only be notified of an arrived message when a line has arrived. That is line by line read, rather than character by character. This works because the AGB MMS terminates it's lines with a carraige return line feed. The initialisation sets up a file pointer to the port which is then made available to the write function (agbMechInfo()) through the global portPtr.
The portInit function also starts the "requestStatus" cycle, which then becomes self maintaining. It does this by setting a Drama timeout, and arranging for itself to be called on the timeout. When the function is called, it sends a "global status request' to the AGB MMS, which replies with the status of every mechanism. These replies are handled by the portRead function.
The INS facility arranges to call the portRead function whenever an input line (since we are in canonical mode) arrives from the AGB MMS. These arrive in the format described in Appendix A. The position and status of every mechanism is extracted from the return message and all the update functions are called to ensure the parameter system and outstanding actions get notified.
3.2 Comparison lamps
The AGB returns the state of the comparison lamps as bitmapped fields in the status return message. These are interpretted into the states of the individual lamps. The mountables database is accessed for each of the lamps indicated as on, and a parameter is maintained that is the concatenation of the names of all these lamps. The string is left blank if no lamps are on.
The argument to the AGB_LAMPS action is a string concatenation of the lamps required on, the same as that generated above. If no lamps are required, this string should be "off", other wise the exact name as entered in the invocation field in the mountables database for the required lamp should be entered - with a "+" between the names. The mountables database is checked for the position of the required lamps and the appropriate command compiled.
In order for this mechanism to work, the lamps must have different names, even if they are of the same type. For example, if there are two ThAr lamps in use, they should be called ThAr1 and ThAr2 in the invocation field of the mountables database. This can be checked using the change_agb command.
3.3 Filters
Although the mountables database is used to maintain the filter names, the absolute filter wheel position should be given as the argument to the Drama action. All filters wheel ranges are set so that position 0 is clear.
The contents of each filter wheel is maintained in an SDS file. These are kept in /ing/etc and can be read with sdslist.
3.4 TV Shutter
Infront of the TV camera is a shutter. It is usually best to ensure that this shutter is closed whenever you are not positively looking at the TV. But most importantly it should be arranged for the shutter to be closed whenever the comparrison mirror is in, to ensure that light from the comparison lamps doesn;t get to the TV when it's gain is turned up. This can be ensured using an alias for the compmirror comand.
All except the change command and the mimic (described below) are implemented using the INS client facility, described in reference 2. A table is used to define all the clients. When this is compiled wit the INS facility, one executable is generated - AGB_CLIENT. When the install target of the is made ("make -f agbClients.mk install") this executable is moved to the observing system binary directory (pointed to by the environment variable OBSSYS). The soft links to this executable are generated also with in the OBSSYS/bin directory. These soft links are named "ascf", "autoxy" etc, and are what the user executes. When the AGB_CLIENT starts executing it extracts the command name used to invoke it - this will be the name of the link - eg "ascf". It then matches this name with one in the table to retrieve the appropriate information - how many arguments to expect and of which type and the action within the AGB server to initiate.
4.2 Change command
The change_agb command is implemented with the agbChange.tcl script. It is written using the Drama extention to Tcl. When it starts, it retrieves the current configuration from the agbSettings file, found in /ing/etc. This is used to set the values for the various internal parameters.
With the two above slit filter slides, the user is offered the choice of 3 possible slides. This is because there are a selection of filled slides available to insert into the mechanism. Datafiles are stored on disk defining the contents of each of the slides. Once a slide has been selected, the corresponding data file is loaded, and the contents of the slide can be viewed by hitting the "View slide conents". This shows the contents of the data file read from disk. All the fields shown can be modified. When the "Change" button is clicked, the conents of the data file describing this particular slide is re-written with the modified contents. The FITs descriptor written into the header is the concatenation of Id, WaveBand and PhotSys - although this is handled from within the AGB server itself.
To generate a new slide description file, the "dtcl" command line interface could be used. This enables you to create and define the Sds structure and write it to a file, using SdsWrite. A small executable could also be made to create the file. If this file is to be available as an option to the change command, it will have to be added in the change script.
The two comparison lamp filter wheels (AFARC and BFARC) and the TV and autoguider filters wheels do not have alternative wheels to insert. The contents of the slide can be viewed by clicking on the "View slide contents" button, and the contents can be modified as above.
The comparison lamps are considered filters, with one in each of the three available "slots". The positions should be 1 2 and 3. The invocation names should all be unique even if the lamps are equivalent - for example use ThAr1 and ThAr2.
When the user clicks on the "Save changes" button at the top of the window, the internal variables are converted to an SDS structure and written to the agbSettings file in the /ing/etc directory. The AGB server is then sent an AGB_INIT action which causes it to reload the agbSettings file. There is no other link between the change command and the server. This means that any changes become the default startup configuration.
4.3 autoProbe command
The guide probes are under the control of the AGB server. With the non-array autoguider, the TCS must move the guide probes during the acquire stage to get the target guide star in the centre of the image to allow guiding. This is done by the TCS sending a movement request down the Inter Processor Link (IPL). These movement requests are only relative positions as the TCS does not know the position of the autoguider probe. The IPL is connected to the instrumnet control Sparc running the TCS Drama task. The TCS Drama task maintains a Drama parameter of the value of these requested values. When ever a new request from the TCS arrives, these values will be updated. A command can also be entered at the TCS to request an absolute XY position for the autoguider probe. This is also sent as a message down the IPL which is interpretted by the TCS Drama task which maintains them as parameters,
The autoProbe.tcl script sets up a monitor on the parameters in the TCS server that hold the requested relative movements and the requested absolute XY positions. If any of these change, the local copies in the autoProbe task get updated, and the AGB_AUTOPROBE action in the AGB server is invoked with the appropriate position. The autoProbe task must also maintain a local copy of the current autoguider XY position to work out the desired position when the TCS sends relative positions.
4.4 Mimic
This is detailed in reference [2].
As well as the INS components listed in reference [2]. the AGB server has the following components
agbServerMain.c Provides the action map and parameter database
agb.h Provides interfaces to the AGB server that might be required by external clients.
agbInternal.h Provides definitions and macros that are required internally to the AGB server only.
agbComm.c Provides the portRead function to receive lines from the serial port, and agbMechInfo which is used to send movement requests down the serial port.
agbFilters.c Implements the AGB_ASCF, AGB_ASND, AGB_AGFILT, AGB_TVFILT, AGB_AFARC and AGB_BFARC actions, and the corresponding update functions to maintain the parameters for these mechanisms
agbInit.c Implements the AGB_INIT action, which causes the agbSettings file to be reloaded.
agbLamps.c Implements the AGB_COMPLAMPS action and the corresponding update function for maintaining the related parameters
agbMirrors.c Implements the AGB_FLIP and AGB_COMP actions for moving the mirrors, and provides the update functions for maintaining the related parameters
agbProbes.c Implements the AGB_AGXY and AGB_TVXY actions and provides the corresponding update functions for maintaining the related parameters
agbTVShutter.c Implements the AGB_TVS action and provides the corresponding update functions for maintaining the related parameters
agb.mk Makefile for the AGB server - creating the "agb" executable.
agb.bom Bill of Materials for a release of the AGB server. Used by the bom utility to make a release.
5.2 Component relationships
The makefile agb.mk makes the AGB server by compiling all the above C files, as well as those in the INS facility and the srv facility, and linking into the "agb" executable.
A release is defined by the version numbers of all the components listed in agb.bom. A release can be made by giving this list to the "bom" utility, as described in reference [3].
5.3 agbServerMain.c
TYPE:
C source-code file: two public functions.
PURPOSE:
To provide facilities for the AGB server:
starting the parameter system.
defining the action handlers
FUNCTION:
This component defines the AGB server parameter system and action table.
startParamSys starts the parameter system, adds all the parameters required
for the AGB server, and initialises then
startActions defines the action handlers corresponding to the DITS
actions
The C entry function main is implemented in insMain.c
SUBORDINATES:
None
DEPENDENCIES:
DitsInit should have been called before the startActions function
is called.
INTERFACES:
Call from C:
void startParamSys( StatusType *status)
void startActions( StatusType *status)
REFERENCES:
"Interfacing with the AGB servers"
RGO/ING document INS-AGB-1
5.4 agb.h
TYPE:
C source-code: include-file.
PURPOSE:
Defines values needed by external clients of the agb server, either for
limit checking for for interpretation of the AGB parameters.
FUNCTION:
Defined the following:
AGB_IN AGB_OUT AGB_BETWEEN - position of shutters and comp mirror
AGB_FLIPFIELD AGB_FLIPSLIT - position of Flip mirror
AGB_ASCFMIN AGB_ASCFMAX - Above slit colour filter wheel limits
AGB_ASNDMIN AGB_ASNDMAX - Above slit ND filter wheel limits
AGB_AGFILTMIN AGB_AGFLITMAX - Autoguider filter wheel limits
AGB_TVFILTMIN AGB_TVFLITMAX - TV filter wheel limits
AGB_AFARCMIN AGB_AFARCMAX - Comparison filter wheel A limits
AGB_BFARCMIN AGB_BFARCMAX - Comparison filter wheel B limits
AGB_TVXMAX AGB_TVXMIN - TV probe movement limits
AGB_TVYMAX AGB_TVYMIN
AGB_AGXMAX AGB_AGXMIN - Autoguider probe movement limit
AGB_AGYMAX AGB_AGYMIN
SUBORDINATES:
None.
DEPENDENCIES:
None.
5.5 agbInternal.h
TYPE:
C source-code: include-file.
PURPOSE:
Defines values used internally the agb server.
FUNCTION:
Enumerated type:
AGB_Mech_t - lists the mechanisms of the A&G Box
Definitions and macros:
AGBTO_ASCF AGBTO_ASND - Mechanism timeouts in seconds
AGBTO_AFARC AGBTO_BFARC
AGBTO_AGFILT AGBTO_TVFILT
AGBTO_TVPROBE AGBTO_AGPROBE
AGBTO_FLIPMIRROR AGBTO_COMPMIRROR
AGBTO_TVSHUTTER AGBTO_COMPLAMPS
AGB_TVVZXU AGB_TVVZXO - Defines region of TV vignetting
AGB_TVVZYU AGB_TVVZYO
AGB_AGVZXU AGB_AGVZXO - Defines region of AG vignetting
AGB_AGVZYU AGB_AGVZYO
AGB_TVXCENTRE AGB_TVYCENTRE - Defines TV probes central position
AGB_AGXCENTRE AGB_AGYCENTRE - Defines AG probes central position
AGB_TVXPARK AGB_TVYPARK - Defines TV probes park position
AGB_AGXPARK AGB_AGYPARK - Defines AG probes park position
AGB_AGTOL AGB_TVTOL - Tolerance in AG and TV probe positions
AGBTO_REQSTATUS - Time in milliseconds between status polls
SUBORDINATES:
None.
DEPENDENCIES:
Depends on some definitions from agb.h which should be included before this
5.6 agbComm.c
TYPE:
C source-code file: three public functions, two private
PURPOSE:
Interprets messages arriving from the AGB MMS, and compiles
messages to send to the server.
FUNCTION:
The portInit function initialises the named serial port device
for communication with the AGB MMS. It also triggers the requestStatus_
function which reschedules itself every AGBTO_REQSTATUS milliseconds, and
sends a full status request message. This ensures that the server
has up-to-date status information regarding the mechanisms. Polling
may be slightly more time consuming, but relying on "monitor-mode"
messages has apparently been found to be unreliable.
When a message arrives - presumably as a result of the requestStatus_
it is interpretted, by decomposing to the status bytes.
The interpretation of each status byte is dependent
on the mechanism. The appropriate update function is then notified
of the new position and status of the mechanism.
When the server requests a mechanism move, the idsMechInfo function
is called with the mechanism name and the required position. The
format of the message sent to the controller (MMS) is dependent on
the mechanism.
SUBORDINATES:
Included:
ciaBoolean.h ins.h agbInternal.h agb.h insErr.h
Called:
agbUpdateASCF agbUpdateASND agbUpdateAfarc agbUpdateBfarc
agbUpdateAGFilt agbUpdateTVFilt agbUpdateFlip agbUpdateComp
agbUpdateTVShutter agbUpdateCompLamps agbUpdateTVXProbe
agbUpdateTVYProbe agbUpdateAGXProbe agbUpdateAGYProbe
msgLog
Global data accessed:
extern int portPtr - File descriptor of the serial port
DEPENDENCIES:
portInit should have been called, and the global portPtr should have
been initialised before idsMechInfo is called.
INTERFACES:
Call from C:
void portRead( int *portFD , StatusType *status)
Where portFD is the file descriptor for the serial port stream
status is the inherited status
void portInit(char *port_, int *portFD, StatusType *status)
Where port_ is the name of the port, eg "/dev/term/a"
portFD is the return file descriptor
status is the inherited status
void idsMechInfo(AGB_Mech_t Mechs, ulong Pos, StatusType* status)
Where Mechs is the mechanism the move is requested for
Pos is the position requested
status is the inherited status
INS facility:
portRead should be the call back function when data arrives down the
serial port.
REFERENCES:
"Interfacing with the AGB server"
RGO/ING document INS-AGB-1
5.7 agbFilters.c
TYPE:
C source-code file: 12 public functions, none private.
PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the
various filters in the A and G box, these are:
Above slit colour filter (ASCF)
Above slit neutral density (ASND)
Arc filter A (compfilta - formerly Afarc)
Arc filter B (compfiltb - formerly Bfarc)
TV filter (TVFilt)
Autoguider filter (AGFilt)
FUNCTION:
This component of the IDS server implements the AGB_ASCF
AGB_ASND AGB_AFARC AGB_BFARC AGB_TVFILT and AGB_AGFILT DRAMA actions
and provides the facility for the position/state feedback to the
parameter system for all these mechanisms
abgASCF agbASND agbAfarc agbBfarc agbAGFilt agbTVFilt
These functions implement the correspoonding DRAMA tasks by
sending off a request to the AGB MMS, reschedules awaiting
the postion update. If this does not occur before the timeout,
the action returns with a mechanism timeout error. If it does
return before the timeout, then if the status shows it is still
moving, the action reschedules, if the status shows a mechanism
failure, the action returns a MECHFAIL error, otherwise, if the
status shows the mechanism has stopped movement, and the mechanism
is in the requested position, the action will return normally.
If the mechanism has stopped moving but is not in the requested
position, a mechanism failure is reported. If the action is kicked,
the action will terminate with an ABORT error. This can be used to
terminate actions before timeouts.
abgUpdateASCF agbUpdateASND agbUpdateAfarc agbUpdateBfarc
agbUpdateAGFilt agbUpdateTVFilt
These functions are called whenever the status or position
of the corresponding mechanism arrives from the MMS. The
position and state parameters for the mechanism will be updated
and, if the corresponding DRAMA action (above) is running, it
will be notified of the change. The textual name of the filter
in the beam is extracted from the mountables database using
the insMatchCode utility. The FITS descriptor is put into
the appropriate NAME parameter for extraction with the
ARCHIVE drama action.
SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h agbInternal.h
Called:
msgLog abgMechInfo insMatchCode
DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.
INTERFACES:
Call from C:
void agbUpdateASCF( long pos, long state, StstusType *status)
void agbUpdateASND( long pos, long state, StstusType *status)
void agbUpdateAfarc( long pos, long state, StstusType *status)
void agbUpdateBfarc( long pos, long state, StstusType *status)
void agbUpdateAGFilt( long pos, long state, StstusType *status)
void agbUpdateTVFilt( long pos, long state, StstusType *status)
DITS action:
Invoke the AGB_ASCF action, with the following parameters:
Name: "Argument1" Type: Integer, Contents: Required position
Invoke the AGB_ASND action, with the following parameters:
Name: "Argument1" Type: Integer, Contents: Required position
Invoke the AGB_AFARC action, with the following parameters:
Name: "Argument1" Type: Integer, Contents: Required position
Invoke the AGB_BFARC action, with the following parameters:
Name: "Argument1" Type: Integer, Contents: Required position
Invoke the AGB_TVFILT action, with the following parameters:
Name: "Argument1" Type: Integer, Contents: Required position
Invoke the AGB_AGFILT action, with the following parameters:
Name: "Argument1" Type: Integer, Contents: Required position
5.8 agbInit.c
TYPE:
C source-code file: 1 public function, 1 private
PURPOSE:
Provides facilities to initialise the AGB server
FUNCTION:
This component of the AGB server implements the AGB_INIT DRAMA action.
agbInit implements the DRAMA task, which installs the filter wheel contents
for all the filter wheels in the A&G box, and the comparison lamp names.
SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h agb.h mdb.h
Called:
msgLog
DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.
INTERFACES:
DITS action:
Invoke the AGB_INIT action, with no parameters
5.9 agbLamps.c
TYPE:
C source-code file: 2 public functions.
PURPOSE:
To provide facilities for the control and monitoring of the
state (ON/OFF) and the status (stable, moving,failed) of the
comparison lamps in the A and G box.
FUNCTION:
This component of the AGB server implements the AGB_LAMPS DRAMA action
and provides the facility for the state/status feedback to the
parameter system.
agbCompLamps implements the DRAMA task, which sends off a request to
the AGB MMS, to turn the complamps on or off.
If this occurs within the alotted time, the action will timeout with an
error, otherwise it will terminate quietly.
agbUpdateCompLamps will be called whenever the state or status of the
comparison lamps arrives from the IDS MMS. The state and status
parameters in the DRAMA parameter system are updated, and the
AGB_LAMPS action (above) is notified, if it was running.
SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h
Called:
msgLog agbMechInfo insMatchCode mdbMatchInvocation
DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.
INTERFACES:
Call from C:
void agbUpdateCompLamps( long pos, long state, StstusType *status)
The "pos" parameter is the bitmapped state of all the
comparison lamps, each bit will be 1 if the lamp is on:
Bit 1 (0x01) corresponds to the lamp 1
Bit 2 (0x02) corresponds to the lamp 2
Bit 3 (0x04) corresponds to the lamp 3 (Tungsten usually)
DITS action:
Invoke the AGB_LAMPS action, with the following parameters:
Name: "Argument1" Type: String,
Contents: This containg a list of the required calibration lamps
with a "+" between them, such as "W+CuNe". It should read
"off" if no lamps are required.
5.10 agbMirrors.c
TYPE:
C source-code file: four public functions, none private.
PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the
mirrors in the A and G box, that is the flip mirror and the compmirror
FUNCTION:
This component of the AGB server implements the AGB_FLIP and
AGB_COMPMIRROR DRAMA actions
and provides the facility for the position/state feedback to the
parameter system.
agbFilt implements the AGB_FLIP DRAMA task, which sends off a request
to move the flip mirror, and reschedules awaiting the position update.
If this occurs within the alotted time, the action will timeout with an
error, otherwise it will terminate quietly.
agbCompmirror implements the AGB_COMPMIRROR DRAMA task, which sends off
a request to move the comparison lamp mirror, and reschedules
awaiting the position update.
If this occurs within the alotted time, the action will timeout with an
error, otherwise it will terminate quietly.
idsUpdateFlip will be called whenever the position/status of the flip
mirror arrives from the AGB MMS. The position and state parameters in
the DRAMA parameter system are updated, and the AGB_FLIP action (above) is
notified, if it was running.
idsUpdateComp will be called whenever the position/status of the comp
mirror arrives from the AGB MMS. The position and state parameters in
the DRAMA parameter system are updated, and the AGB_COMPMIRROR action (above) is
notified, if it was running.
SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h agbInternal.h agb.h
Called:
msgLog agbMechInfo
DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.
INTERFACES:
Call from C:
void agbUpdateFlip( long pos, long state, StstusType *status)
Where `pos` == AGB_FLIPFIELD when in the field view posn
or AGB_FLIPSLIT when in the slit view position (both defined in
ids.h)
void agbUpdateComp( long pos, long state, StstusType *status)
Where `pos` == AGB_IN when in the comp feed position
or AGB_OUT when not (both defined in ids.h)
DITS action:
AGB_FLIP action is invoked with the following parameter:
Name: "Argument1" Type: Integer,
Contents: AGB_FLIPFIELD (0) for field, AGB_FLIPSLIT (1) for slit viewing
AGB_COMPMIRROR action is invoked with the following parameter:
Name: "Argument1" Type: Integer,
Contents: 1 for mirror in, 0 for mirror out
5.11 agbProbes.c
TYPE:
C source-code file: four public functions, none private.
PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the
TV and autoguider probes in the A and G box.
FUNCTION:
This component of the AGB server implements the AGB_TVPROBE and
AGB_AGPROBE DRAMA actions
and provides the facility for the position/state feedback to the
parameter system.
agbTVProbe implements the AGB_TVPROBE DRAMA task, which sends off a request
to move the TV probe, and reschedules awaiting the position update.
If this occurs within the alotted time, the action will timeout with an
error, otherwise it will terminate quietly.
agbAGProbe implements the AGB_AGPROBE DRAMA task, which sends off
a request to move the autoguider probe, and reschedules
awaiting the position update.
If this occurs within the alotted time, the action will timeout with an
error, otherwise it will terminate quietly.
idsUpdateTVProbe will be called whenever the position/status of the TV
probe arrives from the AGB MMS. The position and state parameters in
the DRAMA parameter system are updated, and the AGB_TVPROBE action
(above) is notified, if it was running.
idsUpdateAGProbe will be called whenever the position/status of the autoguider
probe arrives from the AGB MMS. The position and state parameters in
the DRAMA parameter system are updated, and the AGB_AGPROBE action (above) is
notified, if it was running.
SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h agbInternal.h
Called:
msgLog agbMechInfo
DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.
INTERFACES:
Call from C:
void agbUpdateTVXProbe( long pos, long state, StatusType *status)
void agbUpdateTVYProbe( long pos, long state, StatusType *status)
void agbUpdateAGXProbe( long pos, long state, StatusType *status)
void agbUpdateAGYProbe( long pos, long state, StatusType *status)
DITS action:
AGB_TVPROBE action is invoked with the following parameters:
Name: "Argument1" Type: Integer, Contents: X position
Name: "Argument2" Type: Integer, Contents: Y position
AGB_AGPROBE action is invoked with the following parameters:
Name: "Argument1" Type: Integer, Contents: X position
Name: "Argument2" Type: Integer, Contents: Y position
5.12 agbTVShutter.c
TYPE:
C source-code file: two public functions, none private.
PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the
TV shutter position in the AGB.
FUNCTION:
This component of the AGB server implements the AGB_TVS DRAMA action
and provides the facility for the position/state feedback to the
parameter system.
agbTVShutter implements the DRAMA task, which sends off a request to move
the TV shutter position, and reschedules awaiting the position update.
If this occurs within the alotted time, the action will timeout with an
error, otherwise it will terminate quietly.
idsUpdateTVShutter will be called whenever the position/status of the
TV shutter arrives from the IDS MMS. The position and state parameters
in the DRAMA parameter system are updated, and the IDS_TVS action (above)
is notified, if it was running.
SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h
Called:
msgLog agbMechInfo
DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.
INTERFACES:
Call from C:
void agbUpdateTVShutter( long pos, long state, StstusType *status)
Where 'pos' in IDS_IN when the shutter is in position, ie
stopping light getting to the TV, and IDS_OUT when out.
(both these are defined in ids.h)
DITS action:
Invoke the IDS_TVS action, with the following parameters:
Name: "Argument1" Type: Integer,
Contents: 0 for Closed, 1 for Open
5.13 agb.mk
# TYPE:
# makefile
#
# PURPOSE:
# makes the agb server
#
# FUNCTION:
# The main targets are:
#
# build This builds the final executable, sccd
#
# install If the execuatable hasn't been built, it is first build
# and then copied into the bin subdirectory os the
# dirctory indicated by the OBSSYS environment variable
#
# clean This removes the intermeadiate files generated byy a build
# and also all the source modules - should leave the
# working dirctory clear
#
# lint Lints the target instead of building.
#
# If no target is given - 'build' is assumed.
#
# If the environment variable PROJECT_DIR has been defined, the
# source code modules will be extracted from the SCCS directory
# before each is compiled. This should not be done for a release
# - as BOM should be used to extract.
#
# SUBORDINATES:
# agbServerMain.c
# agbFilters.c
# agbMirrors.c
# agbTVShutter.c
# agbComm.c
# agbLamps.c
# agbProbes.c
# agbInit.c
# srvArchive.c
# srvFindFile.c
# insArchive.c
# insMain.c
# srvPingExit.c
# mdbMount.c
# mdbMatch.c
# srvTalk.c
# insErr.msgt
# srvErr.msgt
# agbInternal.h
# ciaBoolean.h
# agb.h
# srv.h
# mdb.h
# ins.h
#
# DEPENDENCIES:
# dramastart should have been run to define the locations of the DRAMA
# elements - libraries and headers.
5.14 agb.bom
# Bill of materials to build server for the AGB at v1.3
#
#
# Set ${ING} to indicate the root of the source tree before building.
# You must have libcia installed to build this package.
# ${OBSSYS} must be correctly defined for the build to work.
#
# @(#) Component agb.bom 1.3 /ing/src/SCCS/s.agb.bom 96/11/19 15:24:21
Component ciaBoolean.h 1.1 sccs ${ING}/src
Component agb.h 1.7 sccs ${ING}/src
Component agbInternal.h 1.14 sccs ${ING}/src
Component agbComm.c 1.28 sccs ${ING}/src
Component agbFilters.c 1.8 sccs ${ING}/src
Component agbInit.c 1.3 sccs ${ING}/src
Component agbLamps.c 1.8 sccs ${ING}/src
Component agbMirrors.c 1.7 sccs ${ING}/src
Component agbProbes.c 1.10 sccs ${ING}/src
Component agbServerMain.c 1.8 sccs ${ING}/src
Component agbTVShutter.c 1.7 sccs ${ING}/src
Component ins.h 1.4 sccs ${ING}/src
Component insArchive.c 1.10 sccs ${ING}/src
Component insMain.c 1.9 sccs ${ING}/src
Component mdbMatch.c 1.3 sccs ${ING}/src
Component mdbMount.c 1.2 sccs ${ING}/src
Component srv.h 1.8 sccs ${ING}/src
Component srvArchive.c 2.2 sccs ${ING}/src
Component srvFindFile.c 1.1 sccs ${ING}/src
Component srvPingExit.c 1.2 sccs ${ING}/src
Component srvTalk.c 2.4 sccs ${ING}/src
Component insErr.msg 1.3 sccs ${ING}/src
Component srvErr.msg 1.1 sccs ${ING}/src
Component ciaActions.h 1.1 sccs ${ING}/src
Component mdb.h 1.1 sccs ${ING}/src
Component agb.mk 1.11 sccs ${ING}/src
Tag agb 1.3 TAG.c
Makefile agb.mk agb
As well as those components listed in reference. the AGB clients has the following components
agbClientTable.c Provides the table for generating the AGB clients with the INS client facility.
agbClients.mk Makefile for the AGB clients, produces the AGBS_CLIENT executable and installs with all required links to produce the full range of clients.
abgClients.bom Bill of materials for a release of the AGB_CLIENT. Can be used by the "bom" facility to generate the executable.
agbChange.tcl Provides the change_agb client
autoProbe.tcl Provides the mechanism for forwarding autoguider probe move requests from the TCS to the instrument.
6.2 Component relationships
The makefile agbClients.mk builds from agbClientTable.c and insClient.c, including assorted header files, creating the AGB_CLIENT executable.
The bill of materials agbClients.bom defines a release of the AGB_CLIENT executable. This can be given to the "bom" utility to generate the a released version.
The agbChange.tcl command needs the following datafiles in /ing/etc:
agbSettings Persistance file containing current contents of mechanisms
ASCF-0 Contents of above slit colour filter slide 0
ASCF-1 Contents of above slit colour filter slide 1
ASCF-2 Contents of above slit colour filter slide 2
ASND-0 Contents of above slit ND filter slide 0
ASND-1 Contents of above slit ND filter slide 1
ASND-2 Contents of above slit ND filter slide 2
AFARC Contents of comparison filter wheel A
BFARC Contents of comparison filter wheel B
AGFILT Contents of the autoguider filter wheel
TVFILT Contents of the TV filter wheel
LAMPS Comparison lamp names
6.3 agbClientTable.c
TYPE:
C source-code file: produces a table for insClient.c
PURPOSE:
Lists the actions, arguments and lock for the simple AGB actions/clients
FUNCTION:
Defines the arrays and variables required when using the
INS client facility.
Variables declared:
serverName - name of server to connect to - "AGB"
cmdTable1 - Used to interpret required position of hartmann shutter
cmdTable2 - Used to interpret required position of other shutters
insCommand - The command table describing each command available
SUBORDINATES:
None
DEPENDENCIES:
None
INTERFACES:
See reference [1]
REFERENCES:
INS-IDS-2 Interfaces to the IDS server (includes desciption of INS)
6.4 agbClients.mk
# TYPE:
# makefile
#
# PURPOSE:
# To build the clients for use with the AGB system.
#
# FUNCTION:
# The main targets are:
#
# build This builds the final executable, AGB_CLIENT
#
# install If the execuatable hasn't been built, it is first build
# and then copied into the bin subdirectory of the
# dirctory indicated by the OBSSYS environment variable,
# Finally all the softlinks are generated in the OBSSYS/bin
# that the user actually types
#
# clean This removes the intermeadiate files generated byy a build
# and also all the source modules - should leave the
# working dirctory clear
#
# lint Lints the target instead of building.
#
# If no target is given - 'build' is assumed.
#
# If the environment variable PROJECT_DIR has been defined, the
# source code modules will be extracted from the SCCS directory
# before each is compiled. This should not be done for a release
# - as BOM should be used to extract.
#
#
# SUBORDINATES:
# agbClientTable.c Client table specific to the AGB clients
# insClient.c INS facility for clients
# ciaErr.msg CIA messages
# insErr.msg INS messaged
# ciaRpc.h CIA RPC header
# ciaTalk.h CIA talker interface
# ciaBoolean.h CIA header for boolean_t and TRUE/FALSE
# ins.h INS interface header
#
# DEPENDENCIES:
# dramastart should have been run to define the locations of the DRAMA
# elements - libraries and headers.
#
# The CIA library should have been built.
6.5 agbClients.bom
# Bill of materials to build client programs for the AGB at v1.2:
# several are built.
#
# Set ${ING} to indicate the root of the source tree before building.
# You must have libcia installed to build this package.
# ${OBSSYS} must be correctly defined for the build to work.
#
# @(#) Component agbClients.bom 1.2 /ing/src/SCCS/s.agbClients.bom 96/11/19 15:27:03
Assembly libcia 6.3 ${OBSSYS}/lib/libcia.a
Component insClient.c 1.2 sccs ${ING}/src
Component agbClientTable.c 1.5 sccs ${ING}/src
Component ciaBoolean.h 1.1 sccs ${ING}/src
Component ciaRpc.h 2.1 sccs ${ING}/src
Component ciaTalk.h 1.4 sccs ${ING}/src
Component ins.h 1.4 sccs ${ING}/src
Component ciaErr.msg 2.2 sccs ${ING}/src
Component insErr.msg 1.3 sccs ${ING}/src
Component agbClients.mk 1.5 sccs ${ING}/src
Tag AGB_CLIENT 1.2 AGB_CLIENT.TAG.c
Makefile agbClients.mk AGB_CLIEN
6.6 agbChange.tcl
# TYPE:
# Dtcl script (TCL with Drama extensions)
#
# PURPOSE:
# Provides a graphical method for seeing the contents of the
# echangeable optics installed in the INT A&G box, and of changing
# them.
#
# FUNCTION:
# The following functions are defined:
#
# showConents - displays the contents of a filter wheel in a
# table that allows all the aspects of a 'filter' to be displayed
# and modified. This is also used for the dekker.
#
# changeFilterDefn - this is called when the 'change' button on
# the table produced by showContents is clicked. This verifies
# the user wishes to change the file on disk, if this is confirmed
# the file is re-written with any changes. It should be remembered
# this is not the persistence file that the server loads of startup
# but the definition file for that particular slide. For example
# changing the name of filter 1 in the ASCF slide 1, changes the
# file ASCF-1. For this to be installed into the server, the
# "save changes" button must be clicked on the uppermost screen.
#
# agbChange - is called when the 'save changes' button is clicked on
# the top level screen. This causes the displayed filters etc to
# be started into the persistence file idsSettings, and the AGB
# server to be sent the AGB_INIT action to cause the file to be
# reloaded.
#
# agbLoadStartup - this is called when this script first starts. It
# reads the persistence file that the server used to initialise, and
# so ensures that the displayed contents of the filters is correct, or
# at least the same as the server thinks. All the various internal
# variables are initialised in this function.
#
# agbInitDisplay - draws the various boxes and buttons that makes up
# the display - including making the list of options when the
# buttons are pressed
#
# Initialisation code:
# The other code starts up the main window, adding the exit and
# save buttons along the top, provides names for the icon and a title
# then calls agbLoadStartup and agbInitDisplay
#
# SUBORDINATES:
# The AGB server should be running if it is required to save any changes
#
# The following files must be present in the directory indicated by
# fileSource:
# ASCF-0 ASCF-1 ASCF-2
# ASND-0 ASND-1 ASND-2
# LAMPS AFARC BFARC TVFILT AGFILT
6.7 autoProbe.tcl
# TYPE:
# tcl script
#
# PURPOSE:
# Forwards guide probe moves from TCS to AGB servers
#
# FUNCTION:
# Monitors the TCS parameters that are changed when a move
# is requested, and sends an obey message to the AGB server,
# requesting the guide probes to move. If the GD_X or GD_Y
# parameters on the TCS change, then the absolute positions
# of the guide probes are being requested. If however the
# GDOF_X or GDOF_Y parameters change, then this is a delta
# movement commend, typically issued when the TCS is trying
# to pull in the probes. This will have the current position
# added to the requested offset before being forwarded to the
# AGB server.
#
# USAGE:
# autoProbe.tcl -n PROBES -b 50000
#
# SUBORDINATES:
# None.
Appendix A. Low level Communications
The MMS communicates via an RS232 connection. The protocol used is briefly described below. A global status request is made every AGBTO_REQSTATUS microseconds. This is set in agbInternal.h to 1 second (1000000 usecs). These commands are defined in reference [1], but there have been a few modifications to mechanism, and this briefly describes the commands used by the agb server.
Commands
ASCF @A00000a a = required position
ASND @B00000a a = required position
Comparison mirror @C00000a a = required position, 2 for in, 1 for out
TV Shutter @D00000a a = required position, 2 for in, 1 for out
AFARC @U00000a a = required position
BFARC @E00000a a = required position
Flip mirror @F00000a a = required position 2 for in, 1 for out
Auto filter @G00000a a = required position
TV filter @H00000a a = required position
Comp lamps @I00000a a = required position (Bit mapped)
TV X probe @K0a a = required position
TV Y probe @M0a a = required position
Autoguider X probe @O0a a = required position
Autoguider Y probe @Q0a a = required position
Status
This is returned in one long string with each mechanism allocated a position in this string. The string is of the form:
@aabbccddeeffgghhiijjkkkkllmmnnnnooppqqqqrrssttttuuvvww
Where:
aa corresponds to ASCF position
bb corresponds to ASND position
cc corresponds to comparison mirror position
dd corresponds to TV shutter position
ee corresponds to BFARC position
ff corresponds to flip mirror position
gg corresponds to guide filter position
hh corresponds to TV filter position
ii corresponds to comparison lamps
jj is unused (graticule illumination)
kkkk corresponds to TV X probe position
ll is unused
mm is unused
nnnnn corresponds to TV Y probe position
oo is unused
pp is unused
qqqq corresponds to Autoguider X probe position
rr is unused
ss is unused
tttt corresponds to Autoguider Y probe position
uu is unused
vv is unused
ww corresponds to AFARC position
Appendix B. Document History
Issue 1.1 1996-11-28 Informally released as INS-AGB-3 with incorrect references.
Issue 1.1 1997-02-05 Formally released as INT-AGB-3 with corrected references.