| |
|
|
|
3 REFERENCE
3.1 TCS Interface program
The tifControl program forms the central command interface between the
various TCS modules (preset, tracking, mode switching, ...) and the users
of the TCS, e.g. instrumentation software. The purpose of the tifControl
program is to unify the interface to the TCS.
There will be one instance of the tifControl program for each focus, named
"tifNA" for Nasmyth A, "tifNB" for Nasmyth B and "tifCA" for Cassegrain.
Note that the tif instances must run in the same CCS environment as all TCS
processes.
The users send all their commands for the TCS to the appropriate tifControl
instance "tifNA", "tifNB" or "tifCA" which routes them to the proper TCS
module, gets the replies from and passes them back to the original caller.
The optional argument dbRoot is the root point of the TCS paket DB branch.
If omitted it is defaulted to value of the TCS_DBPOINT environment variable
or, if even this not defined, hard-coded to ":Appl_data:TCS".
The optional argument processName is the name under which the tif instance
registers with the CCS and hence the destination process name for commands
to it. If omitted, the instance registers with CCS with the same name with
which it was started, i.e. with its UNIX process name.
The optional argument -c 1|0 defines if checking must be performed on
commands sent. By default commands are always checked before sending
unless the environment variable TIF_CMD_CHECK is set to 0
TCS_DBPOINT specifies the root point of the TCS database branch
TIF_CMD_CHECK (0|1) specifies if check on commands sent must be performed.
If not set, commands ARE checked (default value is 1).
All the standard commands are provided and handled internally, i.e. affect
the tif itself but are not routed. For other commands see the documentation
of the corresponding TCS module and the tif Command Definition Table
tifControl.cdt.
If several tif instances are run in the same environment they must be
started with different process names and different DB root points.
shell> tifControl -n tifNA -r :testDB:TCS &
Starts a tif instance with process name tifNA (for Nasmyth A focus) and
specifies ":testDB:TCS" as the TCS branch root point.
3.2 COMMANDS
This section describes all publicly available TCS commands. In this version of the document only a sub-set of commands, due to the sub-set of already implemented modules is provided. The list will be extended as more modules become available.
The commands are described by man pages. In addition to that the command definition table is given.
Move the guide box to the guide star position, then start guiding.
The current position of the selected guide star is selected
as the guiding reference point so no telescope movement is
required.
errorMax: Maximum error in the error vectors in arcsec (0.0 - 10.0)
to consider the guide star centered on the reference point
Default: 0.0
repFreq: if provided, defines at which frequency the agServer
process shall report error vectors to WS in Hz (0.0 - 10.0).
This feature is used for testing purposes.
Default 0
at: if provided defines the time when to start auto-guiding.
Currently it is ignored, since not supported by the TCCD
and always started immediately.
The string shall comply ISO8601, ie YYYY-MM-DDThh:mm:ss.uuu
Default: now
mode: one of AG, FS SF
The parameter is used to select between Auto Guiding and
Field Stabilisation (or Rapid Guiding) mode.
"SF" instruct the system to use the mode specified
in the current setup file.
This is used only by the Field Stabilisation module.
Default: AG
Select the operational mode for dome rotation.
mode: dome rotation operational mode
AUTO: automatic position update (default)
SEMI: position reference calculated every second but preset only on request
COMMAND: position reference calculated and preset only on request
Default: AUTO
The tifControl process with all it's sub-processes are terminated.
This does not affect modules that are addressed by TIF, like PRS or
TRKWS. Only the connection to them is terminated.
Release permission for performing Rapid Guiding from an instrument.
ATTENTION: Implemented only in Field Stabilisation module.
Request permission for performing Rapid Guiding.
If OK, receives back the booking Id to be used to comunicate with M2
as a string, to be converted in integer by the user.
The command is accepted only if NO Auto Guiding is taking place.
ATTENTION: Implemented only in Field Stabilisation module.
Retrieve configuration parameters for the selected instrument
Is no parameter is given, the configuration of the current
instrument is returned.
insId: String up to 32 character, ins+detector id (IsaacLw)
ASCII formatted command reply with the following (comma separated)
fields:
insId: String up to 32 character, ins+detector id (IsaacLw)
insMode: String up to 32 character, ins mode id
focusStation: String with the focus station name for the instrument
offsetRot: Rotator offset in degrees (DD.fff)
offsetFocus: Optimal focus offset (mm)
pixelSizeX: Detector pixel sizs in X direction (arcsec/pixel)
pixelSizeY: Detector pixel sizs in Y direction (arcsec/pixel)
vigAreaSizeX: Vignetting area size along X direction (arcsec)
vigAreaSizeY: Vignetting area size along Y direction (arcsec)
vigAreaCntX: Center in X of vignetting rectangle with respect to center
of field (arcsec)
vigAreaCntY: Center in Y of vignetting rectangle with respect to center
of field (arcsec)
pointAxisOffX: Offset of pointing axis in X (arcsec)
pointAxisOffY: Offset of pointing axis in X (arcsec)
detectorLcu: Str up to 256 ch. Environment + process name (@env:proc)
refX, refY : Reference pixel on chip
adapterFocus: Optimal adapter focus in mm
or error structure
New fields will be added in a next release, in particular to handle
detector vignetting, pointing axis and detector focus.
INIT has to be called once when the application starts.
This causes database and file paths to be initialized in the
applications underlying TIF. During operation INIT can be used
to cause rereading of the settings if they have been changed,
eg. in the database.
The devName parameter is not used.
Kills all processes of TIF. Use this command only when EXIT does not
work any more because the system is messed up.
offsetRot: Modify image orientation with respect to
deafult in degrees (-360.0 - 360.0)
Modify image orientation with respect to deafult
It is an absolute value, not accumulated.
Switches the TIF module (not the modules tif uses) from any other
state to state LOADED
In this state only standard commands (like STANDBY) can be used.
The parameter devName is not used.
offsetAlt: altitude offset in arcseconds (-3600.0 - 3600.0)
offsetAz: azimuth offset in arcseconds (-3600.0 - 3600.0)
Offset from the current telescope fixed coordinates.
Offsets work incremental. They are forgotten when new coordinates are
issued.
offsetAlpha: RA offset in arcseconds (-3600.0 - 3600.0)
offsetDelta: declination offset in arcseconds (-3600.0 - 3600.0)
Offset from the current sky coordinates.
Offsets work incremental. They are forgotten when new coordinates are
issued.
offsetAlpha: RA offset in arcseconds (-3600.0 - 3600.0)
offsetDelta: declination offset in arcseconds (-3600.0 - 3600.0)
Combined offset from the current sky coordinates.
The Guide Probe is counter-moved to compensate for the telescope
movement and to stay on the original sky coordinates.
Offsets work incremental. They are forgotten when new coordinates are
issued.
Absolute or differential M2 position settings along Z axis.
typeSettings: type of M2 position.
DIFF for differential (def)
ABS for absolute
offset: M2 offset in mm (-30.0 - 30.0)
offsetAlpha: RA offset in arcseconds (-1800.0, +1800.0)
offsetDelta: declination offset in arcseconds (-1800.0, +1800.0)
This command is typically used for "secondary guiding", i.e. to
correct for slow motions due to instrument flexure or similar. The command
is given when the telescope is tracking and guiding, and to allow guiding to
continue un-disturbed, the requested offset steps should be small, less than
a few arcseconds (depending on actual size of the guiding box).
Offsets work incremental. They are forgotten when new coordinates are
issued.
offsetRot: Rotator ofset in degrees (-360.0 - 360.0)
Offset the rotator from the current position.
Offsets work incremental. They are forgotten when new coordinates are
issued.
offsetX: X offset in arcseconds (-3600.0 - 3600.0)
offsetY: Y offset in arcseconds (-3600.0 - 3600.0)
Offset from the current telescope sky coordinates.The X/Y directions
are in a plane parallel to the focal plane. The directions are speci-
fied with the command SETXY.
Offsets work incremental. They are forgotten when new coordinates are
issued.
Absolute M1 force and M2 position settings.
Forces and positions are calculated from pre-computed
calibration data (force X zenith angle X mode )
typeSettings: (Def 0)
Switches the TIF module (not the modules tif uses) from any other
state to ONLINE
Only in ONLINE state user commands can be executed.
The parameter devName is not used.
PRGS - Select the next suitable guide star in the internal
catalogue and position the probe to it. If no more
un-tried entry is available an error is returned.
Select the next suitable guide star in the internal catalogue and
position the probe to it. If no more un-tried entry is available
an error is returned.
alt: altitude in degrees, format dd.ffff (0.0 - 90.0)
az: azimuth in degrees, format ddd.ffff (-180.0 - 360.0)
Preset the telescope to a fixed alt/az position.
South is considered 0 deg of azimuth, angles increase counterclockwise.
PRSCOOR alpha,delta,epochSystem,epoch,equinox,pma,pmd,radvel,parallax,
coordinateType,wavelength,offsetAlpha,offsetDelta
This command immediately presets the telescope to the given position
sky position and execute a complete preset sequence to start tracking.
for Auto Guiding, Active Optics and other auxiliary systems behaves
following the instructions in the current setup file.
It returns when preset is completed or with an error msg.
alpha: right ascension of the sky object in hhmmss.ffff (0-240000)
no correction of cos delta to be applied!
delta: declination of the sky object in ddmmss.ffff
(-900000 - +900000 deg)
epochSystem: J for Julian or B for Besselian
epoch: years (-2000.0 - 3000.0)
equinox: years (-2000.0 - 3000.0)
pma: proper motion in alpha (arcseconds per year)
pmd: proper motion in delta (arcseconds per year)
radvel: radial velocity (km/s)
parallax: (arcseconds)
coordinateType: A for Apparent Places, M for Mean Places
wavelength: (nanometers)
offsetAlpha: Offset from the given coordinate (arcseconds)
offsetDelta: Offset from the given coordinate (arcseconds)
offsetRot: Rotator offset in degrees (-360.0 - 360.0)
If trailing parameters are omitted, they are defaulted with values
taken from the CDT.
Preset the telescope to a fixed alt/az position by name.
TCS has defined names like "zenith" or "park" for often needed
positions.
posName: identifier for well known position
Select the instrument rotator tracking mode.
mode: "NORMAL" is for normal tracking
"ALTAZ" if for tracking in alt/az mode
"NONE" if for not tracking at all with the rotator
file: Valid slx setup filename
Saves the contents of the current setup file into a copy under the
name "file".
The file is stored following the standard search path and
naming rules defined by the INS Setup File Handling library
file: Valid slx setup filename
Saves the contents of the current setup file into a copy under the
name "file".
The file is stored following the standard search path and
naming rules defined by the INS Setup File Handling library
Not used in the current version. Returns always OK
The command is only implemented for consistancy with standards.
This command is used to select the observing instrument.
After this command the
selected instrument gets the light beam and TCS is configured with all
the parameters for this instrument.
If required by the newly selected instrument,
also a change of focus station is performed.
All instrument configuration data can be changed at any time with the
SETINSD command, with the exception of the focus station for the
currently selected instrument.
offsetAlpha: velocity relative to RA in arcsec/sec (-15.0 - 15.0)
offsetDelta: velocity relative to declination in arcsec/sec (-15.0 - 15.0)
Move the telescope with a constant velocity on the sky relative to
the basic coordinates.
The offset is NOT incremental.
The velocity is forgotten when a new coordinate is given.
wavelength: in nanometers
Set observed wavelength for correct computation of atmospheric
refraction .
Sets configuration parameters for the selected instrument
insId: String up to 32 character, ins+detector id (IsaacLw)
insMode: String up to 32 character, ins mode id
focusStation: String with the focus station name for the instrument
"UNDEFINED", "NA","NB","CA","CO","IM"
offsetRot: Rotator offset in degrees (DD.fff)
offsetFocus: Optimal focus offset (mm)
pixelSizeX: Detector pixel sizs in X direction (micron)
pixelSizeY: Detector pixel sizs in Y direction (micron)
vigAreaSizeX: Vignetting area size along X direction (arcsec)
vigAreaSizeY: Vignetting area size along Y direction (arcsec)
vigAreaCntX: Center in X of vignetting rectangle with respect to center
of field (arcsec)
vigAreaCntY: Center in Y of vignetting rectangle with respect to center
of field (arcsec)
pointAxisOffX: Offset of pointing axis in X (arcsec)
pointAxisOffY: Offset of pointing axis in X (arcsec)
detectorLcu: Str up to 256 ch. Environment + process name (@env:proc)
refX, refY : Reference pixel on chip
adapterFocus: Optimal adapter focus in mm
New fields will be added in a next release, in particular to handle
detector vignetting, pointing axis and detector focus.
limit: time in seconds
Issues a warning "limit" seconds before the telescope would run into
any limit and would have to stop tracking.
This value is preserved if new coordinates are issued.
SETUP expoId,[<File1> <File2> ...,
[ <Function1> <Value1> <Function2> <Value2>...,[noMove,[check]]]]
set-up some functions, as part of the preparation of an exposure
expoId: exposure Id
Filex: the filename of a setupfile
Functionx: the (Short-FITS) name of an instrument function
Valuex: the value to set <Functionx> to
noMove: Flag telling whether the data should be only stored or
whether a new preset should be executed.
check: Check for correctness of setup data
Functionx and Valuex together constitute a single parameter value
of the parameter named function.
If "check" is specified, the setupFile and/or list of parameters
is checked for semantic validity (i.e. if such a setting could
be done and would make sense), without storing values or moving
the telescope.
If "noMove" is specified, the functions contained in the setupFile
and/or list of parameters are not sent to the telescope, but
otherwise the values are fully processed.
In all other cases the values will be stored and the telescope will
be moved.
Not used in the current version. The functionality is covered
by TCSSIM.
The command is only implemented for consistancy with standards.
Switches the TIF module (not the modules tif uses) from any other
state to STANDBY
In STANDBY state no user commands that are distributed to other
applications are accepted, only standard commands like ONLINE.
The parameter devName is not used.
Start Auto Guiding.
It acepts two optional parameters:
repFreq: if provided, defines at which frequency the agServer
process shall report error vectors to WS in Hz (0.0 - 10.0). T
his feature is used for testing purposes.
at: if provided defines the time when to start auto-guiding.
The time parameter <at> shall comply ISO8601, ie YYYY-MM-DDThh:mm:ss.uuu
mode: Used to select between Auto Guiding and
Field Stabilisation (or Rapid Guiding) mode.
"SF" instruct the system to use the mode specified in
the current setup file.
This is used only by the Field Stabilisation module.
All motion of the telescope is stopped in a controlled way.
The parameter "function" of the command is not used.
Auto Guiding is stopped, is active
If not active, an error is returned.
force: forces to send an explicit STOP
to subsystems (CCD and AG LCU) even if Auto
Guiding is not currently running.
This is used internally and to exit
from dirty situations.
Stop chopping
When the STOPCHP command is received, chopping is not stopped
immediately to allow other modules to get synchronised.
The actual stop time is returned to the caller.
Not used in the current version. The functionality is covered
by TCSSIM.
The command is only implemented for consistancy with standards.
All motion of the telescope is stopped in a controlled way.
The parameter "function" of the command is not used.
Start chopping
It returns the time the first chopping cycle will actually start
When the STRTCHP command is received, chopping is not started
immediately to allow other modules to get synchronised.
The actual stop time is returned to the caller.
time for first actual chop cycle .
or error structure
The returned value complies ISO8601, ie YYYY-MM-DDThh:mm:ss.uuu*
Perform a complete test of the software module
No specific implementation in the current release.
The parameter function is not used.
Return the module version ID as a string in the reply.
Allowed in any state.
Can be used instead of PING to check for TIF being alive.
Select the operational mode for dome windscreens.
mode: windscreens operational mode
AUTO: automatic position update (default)
SEMI: position reference calculated every second but preset only on request
COMMAND: position reference calculated and preset only on request
3.3 DATA QUERY LIBRARY
The following section contains man pages for the C++ functions that can be used to access TCS data.
#include <tif.h>
ccsCOMPL_STAT tifGetFitsStart(const char *imageFile, ccsERROR *error = NULL)
ccsCOMPL_STAT tifGetFitsEnd(const char *imageFile, ccsERROR *error = NULL)
These functions are used to generate an ASCII file with the FITS
header keywords from TEL and ADA categories.
tifGetFitsStart- get TCS FITS header with keywords at start of exposure
tifGetFitsEnd - get TCS FITS header with keywords at end of exposure
imageFile <IN> name of the fits file holding the final data and header.
tif uses this name with the added extension .tcs as the
output in form of an ASCII file with TCS keywords
error <OUT> error stack. If NULL is passed the default eccs error
stack is used.
The <imageFile>.tcs is created in directory $INS_ROOT/$INS_USER/DETDATA/.
If it already exists it is deleted by tifGetFitsStart.
Keywords are collected in an oslxSETUP object and dumped to ASCII
file by tifGetFitsEnd.
The observation software (OS) is expected to call tifGetFitsStart at start
of exposure and tifGetFitsEnd at end of exposure to obtain the standard
FITS keywords for header from TCS and ADA. The result from calling these
query functions is the ASCII file <imageFile>.tcs, which OS should merge
with similar files from ins and det.
TCS_ENVNAME specifies the environment in which TCS runs
TCS_DBPOINT specifies the root point of the TCS database branch
INS_ROOT to find path where to dump ASCII file
INS_USER to find path where to dump ASCII file
#include <tif.h>
ccsCOMPL_STAT tifGetPosition(tifPOSITION *position, ccsERROR *error = NULL)
ccsCOMPL_STAT tifGetStates(tifSTATES *states, ccsERROR *error = NULL)
ccsCOMPL_STAT tifGetStatus(tifSTATUS *status, ccsERROR *error = NULL)
ccsCOMPL_STAT tifGetByName(char *nameIndex, char *buffer,
dbTYPE *type = NULL,
ccsERROR *error = NULL)
These functions form the TCS data query library. They return data items
which are stored in the TCS database branch, thus hiding the database
structure before the user.
tifGetPosition - get actual telescope position
tifGetStates - get TCS global state and sub-state
tifGetStatus - get telescope status information
tifGetByName - get single data item by name
position <OUT> current actual telescope position in (RA,dec) and (alt,az)
struct tifPOSITION
{
vltDOUBLE HA; // hour angle (HHMMSS.F)
vltDOUBLE RA; // right asc. mean place of J2000 (HHMMSS.F)
vltDOUBLE dec; // declin. mean place of J2000 (DDMMSS.F)
vltDOUBLE alt; // altitude (deg)
vltDOUBLE az; // azimuth (deg, S=0 E=90)
};
states <OUT> current TCS state and sub-state
What follows is the current definition for the
tifSTATES structure:
struct tifSTATES
{
vltINT32 tcsState; // TCS global state
vltINT32 tcsSubstate; // TCS sub-state
};
status <OUT> current telescope status (TBD)
What follows is the current definition for the
tifSTATUS structure:
struct tifSTATUS
{
// TBD
};
nameIndex <IN> a literal, specifying a named data item
type <OUT> the data type of this data item. If a NULL pointer is given,
it is ignored.
buffer <OUT> a user buffer, receiving the binary data item value
The user must take care os passing a buffer big enough
to store all the requested data.
error <OUT> error stack. If NULL is passed the default eccs error
stack is used.
The tifGetByName() returns the type of the specified data item in <type>
and its binary value in the passed user <buffer>. The data item <name> is
specified by a string. Convenience defines are provided in the
tif.h header file.
TCS_ENVNAME specifies the environment in which TCS runs
TCS_DBPOINT specifies the root point of the TCS database branch
All TCS Interface Library functions take care of calling this
intializzation function to initialyze the library environment.
error <OUT> error stack. If NULL is passed the default eccs error
stack is used.
TCS_ENVNAME specifies the environment in which TCS runs
TCS_DBPOINT specifies the root point of the TCS database branch*
3.4 ONLINE DATABASE ACCESS
This section contains man pages for the on-line database classes and the related scan script.
This file contains the definition of the tifTCS_PUBLIC database class which
defines the public TCS database structure.
It defines a set of attributes that TCS defines as publicly accessible.
A user willing to access some of these attributes must:
- put an instance of this class in its own environment
- create the proper set of scan link using the tifTcsScanSetup tool
- activate the scan links for the attributes he needs
By default the scan links created by tifTcsScanSetup will be all
defined in terms of database attributes and scanning parameters
(polling, on change, dead bands, frequencies...) but disabled.
For performance considerations it is left to the client the
responsibility of enablind the used ones.
Protection is achieved allowing only predefined workstation to scan from
the TCS workstation by configuring properly the TCS ws scan system.
Changing the configuration of scanning parameters with respect to the provided
script or scanning of other TCS attributes is considered illegal.
This file contains the definition of the tifTCS_LOCAL database class which
allows to create instances of the TCS public database structure inside the TCS
envionment itself.
It is derived from the tifTCS_LOCAL class and just uses the Calculation Engine
to directly retrieve the defined values from their proper places in the TCS
database instead of establishing scan links.
Look at the man page of tifTCS_PUBLIC for details on the exported attributes.
tifTcsScanSetup - (DE)-Activating and setting scan link for
a TCS public branch in a remote environment
Initialize or deletes the scan system and all the scan links to mirror
TCS public data in a local point of type tifTCS_PUBLIC.
The local point must exist in the local environment and scan devices
must be properly configured.
It cannot be used inside the TCS environment itself.
Use an instance of the tifTCS_LOCAL class in this case.
-del turn off scan devices and delete scan-links
-dev issue also a scan device On/Off
-l localEnv Local environment, where to scan the values.
By default $RTAPENV
-p point Pathname of the point of type tifTCS_PUBLIC
where to establish the scan links.
-r dbRoot The optional argument dbRoot is the root point
of the TCS package DB branch.
If omitted it is defaulted to value of the
TCS_DBPOINT environment variable or, if even this
is not defined, hard-coded to ":Appl_data:TCS".
-t tcsEnv TCS environment, where TCS is running.
If omitted it is defaulted to the value of the
TCS_ENVNAME environment variable or, if even this
is not defined, to the value of RTAPENV.
-v verbose mode
RTAPENV - specifies local WS target database
TCS_DBPOINT - if defined, specifies the default TCS root point
TCS_ENVNAME - if defined, specifies the default TCS environment name
The local and TCS environments cannot be the same.
During to current limitations of the CCS Scan System, only
one workstation can scan from the TCS workstation.
3.5 EVENT CONFIGURATION LIBRARY
The following section contains man pages for the C++ functions that can be used to handle TCS events.
include <tif.h>
ccsCOMPL_STAT tifAttachEvent(char *nameIndex, evtEVENT_ID *eventId,
ccsERROR *error = NULL)
ccsCOMPL_STAT tifDetachEvent(evtEVENT_ID *eventId, ccsERROR *error = NULL)
The TCS Database Event Library provides a mechanism to attach to a
certain functional event, from the users point of view. Internally
the functional event is connected to the change of a database value
under a specific filtering. The mechanism is based on the CCS event
system, i.e. the user process is notified of an event by a message
of type msgTYPE_EVENT, see the CCS User Manual for more details.
tifAttachEvent attaches an event
tifDetachEvent detaches an event
nameIndex <IN> specifies a functional event. String identification names
for all events are defined in the tif.h header file.
eventId <OUT> event identifier structure (see the CCS User Manual)
error <OUT> error stack. If NULL is passed the default eccs error
stack is used.
TCS_ENVNAME specifies the environment in which TCS runs
TCS_DBPOINT specifies the root point of the TCS database branch
3.6 M2 Communication Library
The following section contains man pages for the C functions that can be used to perform Rapid Guiding from an instrument by driving m2 via the Rapid Guiding LAN.
These functions can be used from WS (CCS and NO CCS) and LCU applications.
The m2comConnect() is part of the m2com library, available both
on Workstation and LCU for sending field stabilisation and rapid
guiding corrections to the m2 control software.
It is used to establish the connection with the m2 control software
and returns the file descriptor for the opened connection, to be
used with m2comSend(3) and m2comDisconnect(3).
int *fd <OUT> - file descriptor for the connection
char *host <IN> - name of the m2 host.
ccsERROR *error <OUT> - returned error structure.
The host parameter is used to resolve the TCP/IP address of the
m2 host.
- Under UNIX it must be a known host defined in /etc/hosts or
resolvable by the name server
- Unser VxWorks must be defined in the host table by using
for example the hostAdd command.
Example: -> hostAdd "lte50", "134.171.12.185"
SUCCESS if everything is OK. fd contains the file descriptor
FAILURE in case of ERROR, fd = -1
Top of error stack:
m2comERR_NULL_PTR - fd was a NULL pointer
m2comERR_RESOLVE_HOST - host name cannot be resolved
m2comERR_CREATE_SOCKET - socket cannot be created
m2comERR_CONNECT_SOCKET - connection to socket cannot be opened
Under UNIX, host name bust be known to /etc/host or to the name server
Under VxWorks it must be known to the LCU host table.
The m2comDisonnect() is part of the m2com library, available both
on Workstation and LCU for sending field stabilisation and rapid
guiding corrections to the m2 control software.
It is used to close the connection with the m2 control software
int fd <IN> - file descriptor for the connection
ccsERROR *error <OUT> - returned error structure.
SUCCESS if everything is OK. fd contains the file descriptor
FAILURE in case of ERROR, fd = -1
Top of error stack:
m2comERR_CLOSE_SOCKET - fd was not a proper opened connection
The m2comSend() is part of the m2com library, available both
on Workstation and LCU for sending field stabilisation and rapid
guiding corrections to the m2 control software.
It is used to send corrections to the m2 control software
through a connection opened by calling m2comConnect(3).
int fd <IN> - file descriptor for the connection,
returned by m2comConnect(3)
m2tcFS_SEND_BUF *data <IN> - name of the m2 host.
ccsERROR *error <OUT> - returned error structure.
The structure m2tcFS_SEND_BUF contains the correction data and is defined
as follow:
typedef struct { A pair of M2 correction offsets
vltDOUBLE alpha; alpha offset in arcsec
vltDOUBLE delta; delta offset in arcsec
} m2tcFS_OFFSET;
typedef struct { Complete correction structure
int bookId; booking id for the message
int relative; corrections are relative/absolute
m2tcFS_OFFSET offset; pair of correction values
} m2tcFS_SEND_BUF;
SUCCESS if everything is OK. fd contains the file descriptor
FAILURE in case of ERROR, fd = -1
Top of error stack:
m2comERR_SEND_SOCKET - error sending data
This test program emulates the behaviour of m2 software when receiving
field stabilisation corrections.
Used together with the companion program m2comTestReceive(1) provides
statistical data over message transmission time and latency.
It is available both on Workstation and on LCU.
On the Workstation: run the executable
On the LCU : load the program and call the entry point function:
m2comTestReceive()
The lcu must be configured to include the m2com library
The program then start waiting for a connection.
A client program (typically m2comTestSend(1)) handle the connection
using the functions provided by the m2com library:
m2comConnet(3) - to establish the connection
m2comSend(3) - to sent correction data
m2comDisconnect(3) - to close the connection
Data are sent filling a m2comTEST_SEND_BUF union (m2comTest.h).
This union superimposes two structures:
m2tcFS_SEND_BUF fs;
m2comFS_TIME_BUF tm;
These structures shares as a first fiels an integer called bookId,
that once filled can be used on both components
m2tcFS_SEND_BUF is the standard field stabilisation socket packet
and is filled when talking to the real M2 FS software
and whenever normal FS data has to be sent.
m2comFS_TIME_BUF is a special structure used to sent on the other side
of the socket a timestamp (as a ccsTIMEVAL) to be used
for fly time statistics.
The receiver uses the value of the bookId field to identify if the incoming
data must be interpreted as m2tcFS_SEND_BUF (any value >=0, typically
M2TC_DEFAULT_BOOK_ID) or as m2comFS_TIME_BUF (M2COM_FLYTIME_ID).
In order to insure the complete compatibility of this packet with standard M2 FS
packets, the code imposes and checks that
sizeof(m2comFS_TIME_BUF) <= sizeof(m2tcFS_SEND_BUF)
The bookId field is also used by this test program as a command
keyword to perform some specific actions.
- normal data are expected with bookId == M2TC_DEFAULT_BOOK_ID == 1 (m2com.h)
- bookId == M2COM_VERBOSE_ID toggles ON/OFF verbose mode
- bookId == M2COM_EXIT_ID forces the program to exit
- bookId == M2COM_FLYTIME_ID assumes that the packt contains send timestamp
- any other value generates an error fo illegal bookId
Once the connection is established, the program expect a bunch of
correction data sets.
In verbose mode every correction message is printed on standard output.
When the connection is closed (or an error occurrs), it prints a statistic
of the received buch of corrections:
- number of messages received
- total time between firt and last message
- mean lap time between messages
- max lap time between messages
- min lap time between messages
If some message contained timestamps, also the following statics
are printed:
- mean messages fly time
- max messages fly time
- min messages fly time
For these statistics to be meaninfull, it is required that the sending
and receiving hosts are properly synchronized via the time bus
with tim boards or, at least with NTP.
After that it start waiting for another connection.
This test program provides an interactive user interface to send
field stabilisation corrections to m2 software (or to test software
emulating the m2 tip/tilt fast correction interface,
see m2comTestReceive(1)).
Used together with the companion program m2comTestReceive(1) provides
statistical data over message transmission time and latency.
It is available both on Workstation and on LCU.
On the Workstation: run the executable
On the LCU : load the program and call the entry point function:
m2comTestSend()
The lcu must be configured to include the m2com library
and the host containing the m2 software must be configured
in /etc/host (UNIX) or in the LCU host table (LCU).
See m2comConnect(3) for details.
The m2 software must have field stabisisation enabled (with the ENAFS command)
and have the proper booking Id set (with the SETBID command).
The program then display a character oriented menu with the available options.
Sending of single corrections:
"Open connection [O]"
Open a connection with m2 via the rapid guiding LAN
"Send a single correction [1]"
Send a single correction to m2 using the connection
opend via the [O] option.
The following parameters must be set:
- Booking Id
- Relative/absolute
- Alpha in arcseconds
- Delta in arcseconds
"Close connection [C]"
Close the connection opened using the [O] option
Emulating a flow of corrections:
"Read FS Data from File [D]"
Read a set of field stabilisation values from an external file.
Each line must contain one pair <alpha, delta>
in a format suitable for the scanf format "%lf %lf".
Previously loaded data are dropped.
"Create Sine [S]"
Creates a sine wave usable as field stabilisation
input. Parameters for the sine are asked interactively and are
the following: Amplitude, Frequency, Phase. These values are
asked one after another. You may enter no, one, or two values
for each. No value uses the one previously given, one value
sets the same for both alpha and delta, and two values give
separate values for them (alpha, delta). A sequence of 1000 values
is then generated which will give the frequency entered when
replayed at 1000 samples per second.
The phase is given in the interval [0..1] with 1 meaning 360
degrees phase shift, and 0.25 meaning 90 degrees.
If a filename is given, the table is also saved in the file.
"List FS Data [L]"
Prints the current data table
"Run 'm' packets [N]"
Creates a table with the given number of entries, with
values just equal to the the corresponding table index, and
send as many samples as selected to the m2 software, using the created table
as a circular buffer.
"Run Field Stabilisation [R]"
Send as many samples as selected to the m2 software, using the
current table as a circular buffer.
"Testmgs fly time [F]"
Send as many samples as selected to the m2 software,
Each buffer contains a timestamp and is interpreted by the
companion m2comTestReceive() to evaluate statistics on the
time spent by the message on the network (fly time).
ontrol of companion test program m2comTestReceive:
"Toggle server verb. mode [V]"
Send a special packet to the m2comTestReceive(1) companion.
It is interpreted as a request to toggle verbose mode ON/OFF.
"Exit from server [E]"
Send a special packet to the m2comTestReceive(1) companion.
It is interpreted as a request to EXIT.
"Set send wait time usec [T] - now: waitTim"
Defines the time, in microseconds, to wait between 2 consecutive
messages. For example the value 10000 means that while sending
a table it waits 10 milliseconds between any two samples.
The current value is displayed.
Generic options:
"Set destination [P] - now: destHost"
Defines the hostname for the destination host.
The current value is displayed.
"Quit [Q]"
Exit.
This test client program handles the connection
using the functions provided by the m2com library:
m2comConnet(3) - to establish the connection
m2comSend(3) - to sent correction data
m2comDisconnect(3) - to close the connection
Data are sent filling a m2comTEST_SEND_BUF union (m2comTest.h).
This union superimposes two structures:
m2tcFS_SEND_BUF fs;
m2comFS_TIME_BUF tm;
These structures shares as a first fiels an integer called bookId,
that once filled can be used on both components
m2tcFS_SEND_BUF is the standard field stabilisation socket packet
and is filled when talking to the real M2 FS software
and whenever normal FS data has to be sent.
m2comFS_TIME_BUF is a special structure used to sent on the other side
of the socket a timestamp (as a ccsTIMEVAL) to be used
for fly time statistics.
The receiver uses the value of the bookId field to identify if the incoming
data must be interpreted as m2tcFS_SEND_BUF (any value >=0, typically
M2TC_DEFAULT_BOOK_ID) or as m2comFS_TIME_BUF (M2COM_FLYTIME_ID).
In order to insure the complete compatibility of this packet with standard M2 FS
packets, the code imposes and checks that
sizeof(m2comFS_TIME_BUF) <= sizeof(m2tcFS_SEND_BUF)
The bookId field is also used by this test program as a command
keyword to perform some specific actions.
- normal data are expected with bookId == M2TC_DEFAULT_BOOK_ID == 1 (m2com.h)
- bookId == M2COM_VERBOSE_ID toggles ON/OFF verbose mode
- bookId == M2COM_EXIT_ID forces the program to exit
- bookId == M2COM_FLYTIME_ID assumes that the packt contains send timestamp
- any other value generates an error fo illegal bookId
Once the connection is established, the program sends a bunch of
correction data samples.
When the connection is closed (or an error occurrs), it prints a statistic
of the sent samples:
- number of messages sent
- total time between firt and last message
- mean lap time between messages
- max lap time between messages
- min lap time between messages
Under UNIX it is possible to send the USR1 signal to stop data sending:
kill -USR1 pid
3.7 SCRIPTS FOR SIMULATION
The following section contains man pages for shell script user to start, stop and control the TCS Simulation Package.
Sends a PING command to all TCS simulation processes.
The CCS environment in which the TCS shall be started must be specified
in the TCS_ENVNAME environment variable. If not defined the default RTAP
environment is used (see $RTAPENV).
Starts the TCS simulation setup 1, i.e. the tif instances in command
simulation mode and nothing else. The environment variable TCS_ENVNAME
defines the CCS environment in which the simulation shall be started.
Run this script from another bourne-shell (script) by the dot command
". tcssimStartSetup1" otherwise the defined environment variable would
not become effective.
Starts the TCS simulation setup 2. The real tif is used while all other
TCS processes are simulated by the command manager.
The CCS environment in which the TCS shall be started must be specified
in the TCS_ENVNAME environment variable. If not defined the default RTAP
environment is used (see $RTAPENV).
TCS_ENVNAME: the CCS environment in which TCS shall be simulated
TCS_DBPOINT: root point of the TCS database branch
Run this script from another bourne-shell (script) by the dot command
". tcssimStartSetup3" otherwise the defined environment variable would
not become effective.
Starts the TCS simulation setup 3. The real tif, msw, prs and trkws
modules are used, the ad and trk modules are replaced by dummies and
the ag and fs modules are simulated by the command manager.
The CCS environment in which the TCS shall be started must be specified
in the TCS_ENVNAME environment variable. If not defined the default RTAP
environment is used (see $RTAPENV).
Option -t lets the script start each TCS process in an individial xterm
window. Option -f redirects the standard output and standard error of
TCS processes into the specified <file>.
TCS_ENVNAME: the CCS environment in which TCS shall be simulated
TCS_DBPOINT: root point of the TCS database branch
Run this script from another bourne-shell (script) by the dot command
". tcssimStartSetup3" otherwise the defined environment variable would
not become effective.
Stops the TCS simulation setup 3. The tif processes are killed and the
command simulation is stopped. The message system is switched back to
normal mode.
Stops the TCS simulation setup 3. All TCS processes are killed and the
command simulation is stopped. The message system is switched back to
normal mode.
3.8 STAR CATALOG INTERFACE
The following section contains man pages for the catif functions.
ccsCOMPL_STAT catifErrAdd ( ccsERROR *error,
const ccsMODULEID moduleId,
vltINT16 errorNumber,
const ccsLOC_ID locId,
... )
Add the error message generated by the star catalog library to the
current error stack.
error <IN> Error Structure containing the error context.
moduleId <IN> Module Identifier
errorNumber <IN> Error Number
locId <IN> Name of the routine/function generating the error
The preprocessor directive __FILE__ can be used.
... <IN> Variable list of run time parameters.
Error numbers are identified by mnemonics with the following format :
- catifERR_<mnemonic> , where <mnemonic> describes the type of error
A new error is processed as follows :
- Log previous error (if the stack not empty).
- Get a new stack identifier (if stack empty).
- Increase the error sequence number.
- Set current error structure according to the new error condition.
The error message is read from the error definition and it looks like a
'printf format' containing conversion specifications to be applied to the
run time parameters.
The catalog interface error definition file is called catif_ERRORS
Its content can be displayed by using the errEditor utility
SUCCESS A log is issued in the following cases :
- error structure is a NULL pointer.
- moduleId is not existing.
- the error number does not have the corresponding error format.
AcHandle catHandle;
char **colNames = NULL;
char **colTypes = NULL;
char *myCatalog = "gsc@eso";
int numCols;
if ((catHandle = acOpen(myCatalog)) == 0)
{
catifErrAdd(&error,"catif",catifERR_OPEN,__FILE__,myCatalog);
return(FAILURE)
}
if (acGetDescription(catHandle,&numCols,&colNames,&colTypes))
{
catifErrAdd(&error,"catif",catifERR_GET_DESCRIPTION,__FILE__,myCatalog);
return(FAILURE)
}
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|