Appendix A. caobs reference
Prev		Next

caobs reference

Revision History
Revision 1.3	2021 Nov 12	jbs
Fix incorrect description of how cain cal works.
Revision 1.2	2021 Oct 19	jbs
Remove screen line for chat. Remove reference to caobs having a bell, which was removed after it was discovered it caused major problems with caobs in the latest Linux. Remove incorrect advice about the CA06 subreflector. Update advice on the use of the init command. Add a warning about starting a UTC schedule early.
Revision 1.1	2014 Apr 1	jbs
Cleanup the text, remove some commands and add some new ones.
Revision 1.0	2014 Mar 20	jbs
Initial Docbook revision

caobs is the primary interface between the observer and the telescope. It coordinates the functions of the antennas and the correlator. It runs on xbones in a screen session, and is normally available from the main observing computer pericles and a VNC display from xbones.

Figure A.1. A typical caobs display.

caobs will normally already be running before you start observing. If you cannot find caobs, try the following.

Check that cacor is running. (The cacor GUI is usually displayed in a separate VNC display from caccc1.) If it is not, start cacor as described in Appendix B.
Login to xbones and check for the normal screen session that is used to run caobs.
```
atcaobs@xbones:~$ screen -ls
```
The output from this command might look something like the following:
```
There are screens on:
        16310.catag	(06/03/14 15:26:40)	(Attached)
        5001.caobs	(05/03/14 15:07:17)	(Attached)
3 Sockets in /var/run/screen/S-atcaobs.
	
```
If you can see a screen session that is labelled with caobs, then you can reconnect to it:
```
atcaobs@xbones:~$ screen -x caobs
```
If you don't see a caobs screen session, then you can start one:
```
atcaobs@xbones:~$ screen -S caobs
```
Once connected to the caobs screen session, it should look something like Figure A.1. If it doesn't, then you can start caobs:
```
atcaobs@xbones:~$ caobs
```
Wait about one minute while caobs refers to its database and initialises.

A.1. Using caobs

Observers interact with caobs through a command line interface. Though there are many commands (see the Section A.1.1 section), there are only a handful that are used often.

caobs> set file filename: Loads the schedule file specified as the filename. All ATCA schedule files have the extension .sch, but you don't need to supply this extension as part of filename.
caobs> track #: Tracks the source specified by scan # of the schedule file forever (or until the source sets).
caobs> stop: Stops observing. This involves stopping the movement of the antennas, and stopping the correlator.
caobs> start #/n: Starts observing scan # of the schedule and proceeds to subsequent scans after each scan finishes. It will cycle through the entire schedule n times before stopping, or until the stop command is given.
caobs> corr command: Sends the command command to the correlator GUI cacor, as if the command was entered into the GUI directly.
caobs> stow: Stows all the antennas that are attached and enabled in caobs.

A.1.1. caobs Commands

Many of the commands that were part of the caobs command set pre-CABB are now executed in the cacor processes. Other commands are no longer appropriate. cacor commands can be executed from within caobs by prefixing corr in the caobs command. The following list of caobs commands includes the cacor commands that are often executed from within caobs.

attach ca0#|all

Connect caobs either to antenna # only, or all antennas. This command will fail for an antenna if the ACC in that antenna is dead or otherwise unavailable. Use this command to reconnect antennas that caobs reports as “OFF-LINE”.

Related commands: detach, disable, enable.

cain cal prescale code continuous

This command allows you to control of the noise diode on each of the attached antennas via the ACC. All of the three parameters are non-optional:

prescale: A prescale divider on the 1 MHz timeframe which controls the duration of the cal waveform pulses. This prescale number must be between 0 and 65535, but the actual prescale implemented by the hardware is this number plus 1.
code: This is a further prescale by a factor of 2 to the power of code, where code is between 1 and 8. This can be used to define pulses longer than what could be achieved within the 16-bit limits of the prescale divider by itself. It can also take some special values.
continuous: Whether the waveform should be restarted at the start of each integration cycle (set to 0), or only start it at the start at the first cycle and then continue to run freely at the specified frequency (set to 1).

These numbers combine to give:

waveform cycle period = $(2^{code})\times$ (prescale + 1) microseconds
waveform pulse duration = cycle period ÷ 2

As an example, the default ATCA waveform parameters are prescale=31999, code=2, which gives a 128,000 μs cycle period. The ATCA cal waveform restarts at the beginning of each integration cycle, so the default is set by:

cain cal 31999 2 0

caobs will reset this parameter to the default values automatically at every change of observing project ID or at caobs restart.

cain cycle p|default

Set cycle period to p seconds, or to the default 10 seconds. For non-mosaicing observations, the cycle time can be set as low as 1.024 seconds, but when mosaicing the cycle time must be larger than or equal to 6 seconds, otherwise on-source flagging will not work.

Note: The cycle time is generated in the ACC on each antenna, and this command will only be sent to the antennas that are attached at the time. If this command is given while some antennas are not attached, those antennas will have a different cycle time if they are later attached. Reissue this command to fix the inconsistency.

Related commands: attach, detach

cancel

Stops the current pattern (POINTing or mosaic).

Related commands: point

corr[elator] command

Any cacor command can be executed from within caobs by prefixing the command with corr[elator]. Commands that are often executed in caobs are documented here. See Appendix B for more complete information on cacor commands.

corr[elator] acal [s1 s2] [a]

Request that cacor perform an amplitude calibration.

s1 and s2 are flux density values for frequency 1 and frequency 2 respectively. If the source is PKS1934-638 or PKS0823-500, the flux density values are not required. For any other source, you can instruct cacor to calculate the likely flux density of the source (based on the expected system temperature) by using s1=0 and s2=0.

The “a” switch is now optional - the correlator will apply calibration by default. (To prevent the correlator from applying the corrections, replace “a” with any other letter).

Related commands: set reference

corr[elator] close[file]]

Request that cacor close the current file. caobs must be stopped before executing this command.

cacor's display will show display “FITS FILE: CLOSED” if this command succeeds. A new data file will be opened automatically when a scan is started, if a file is not already open.

Related commands: stop

corr[elator] dcal [a]

Request that cacor perform the corrections required to make the phase flat across the band (i.e. caclulates geometric delay offsets).

The “a” switch is now optional - the correlator will apply calibration by default. (To prevent the correlator from applying the corrections, replace “a” with any other letter).

Related commands: set reference

corr[elator] pcal [a]

Request that cacor set the astronomical phases to zero.

The “a” switch is now optional - the correlator will apply calibration by default. (To prevent the correlator from applying the corrections, replace “a” with any other letter).

Related commands: set reference

detach ca0#|all

Disconnect caobs from either antenna # or all antennas. No further commands will be sent to the disconnected antennas, until they are reattached.

Related commands: attach

disable|enable parameter

Disable or enable caobs or antenna-based functionality, depending on the parameter specified. These parameters are:

disable|enable ca0#|all

Disable or enable the drive machinery and turret rotator for either antenna CA0# or all antennas. This will leave everything else as though it was observing.

If an antenna is disabled via this command, caobs will show its status as “DISABLED”.

Related commands: attach, detach

disable|enable correlator

Disable or enable correlation in cacor. If disabled, caobs will drive the antennas as normal, but the correlator will not output any data.

disable|enable lo

Disable or enable the setting of the local oscillators and frequency conversion switches throughout the array. If disabled, the oscillators and switches stay in the state they were when this command was given, and do not change automatically with frequency changes in the schedule.

disable|enable turret [ca0#]

Disable or enable rotation of the turret for antenna CA0# if named, or the entire array if the argument is omitted. If disabled, the turret will not rotate automatically with frequency changes in the schedule.

Note: Data will be flagged if the turret is in the wrong position, regardless of whether it is intentional.

disable|enable wvr [ca0#]

Disable or enable the calibration of the water vapour radiometers on the named antenna, or on the entire array if the antenna is not specified. Calibration of the WVRs is done via a paddle on the mm receiver.

Note: Calibration of the WVR affects 7mm observations since the WVR paddle passes in front of the 7mm feed horn when it gets put in, or taken out.

Note: Calibration of the WVR is not actually required for effective use of the WVR data, and enabling the calibration is not recommended.

exit

Exit from caobs and return to the command line. You will need to stop the observations before issuing this command.

Note: You will need to exit caobs if you need to change cacor versions, or restart the atdaemon. If you are simply trying to exit the screen session that caobs is running in without affecting the operation of caobs, then you should use the key combination Ctrl+a d to detach from the session.

Related commands: stop

extend

Stop cycling through scans in a schedule file and continue the current scan indefinitely.

Related commands: next, track, start

focus {ca0# pos|default}

Move the antenna subreflectors in order to focus the receivers. You can use this command in two different ways.

If you want to move the subreflector on a single antenna # to the position pos (in mm, from -24.0 to 24.0) then specify both the antenna and position.
Example: focus ca01 10
If instead you wish to move the subreflectors on all the antennas to the positions recommended to focus each of them for the current observing frequency, simply give the argument default.
Example: focus default

Note: Only attached and enabled antennas can be focussed.

init

Initialise all caobs parameters to default values, and send initialisation commands to the antennas.

Treat this command with caution. It is very rarely useful outside of maintenance activities.

Related commands: reset

next

Move to the next entry in the schedule, i.e., move to the next scan. This command will cancel an extend command and has no effect in mosaic mode.

Related commands: extend, start, track

park [ca0#]

Drives either the antenna CA0#, or all antennas (if no argument is given to this command) to an azimuth of 90° and an elevation of 90°. Brakes are applied to the drives once this position has been reached. Observations must be stopped before this command will work. Only attached and enabled antennas will be parked.

Note: This is the required position for antennas that are to be moved during a reconfigure. The antennas cannot be moved to this position if any of the mm receivers are on axis.

Related commands: stop, stow

point n

Runs a pointing scan on source n in schedule. The actual definition of the scan in the schedule is irrelevant; only the source position and frequencies are used.

Note: The program catag must be running for the pointing corrections to be calculated.

Related commands: cancel, set point_pattern, set point_ifflag, set point_antennas

ppfix n

Loads the pointing parameters determined by the pointing scan with the catag number n. Any scans with pointing type “Offset” will now use this pointing solution, until a new pointing solution is made.

Related commands: ppglobal, point

ppglobal

Loads the global pointing solution, as specified in the file pparams.dat, into the ACCs. Any scans with pointing type “Offset” will now use the global pointing solution, until a new pointing solution is made.

Related commands: ppfix, point

offset ca0#|all daz del

Force either antenna CA0# or all antennas to track a position offset from that specified by the schedule file; daz and del are the azimuth and elevation offsets in arcminutes. The offsets cease to apply at the next drive request (i.e., at the next start or track command or when the next scan starts).

reconfig parameter

The reconfig commands are used when initialising and calibrating the array after a reconfiguration of the antennas. This is the only time when these commands should be used, and only by staff who have been trained in their use. Using these commands inappropriately could destroy your observations, and it might take several hours to recover.

Each parameter is described below.

reconfig array name

Selects new antenna array. The name must be identifiable with an entry in the configs.dat file. The positions of the antennas are changed to the appropriate station coordinates.

reconfig bszero

Sets the antenna offsets from the station coordinates to zero, by zeroing the file station_errors.file. Before this command is executed, you should set the reference antenna to an antenna that hasn't moved; for most reconfigurations it should be set to CA06.

Related commands: set reference

reconfig clear

Clears global delays, and delay and phase offsets.

reconfig ppinit

Resets global azimuth and elevation pointing offsets to defaults for the station posts used in this configuration.

redraw

Refresh the screen. This command is useful for fixing the caobs display if it has become corrupted. If the display seems unresponsive, it might be because someone has issued a terminal stop command; in this situation redraw will not work, and you should try pressing Ctrl+q instead.

reload

Reload the schedule file.

reset ca0#|all

Resets the ACC for antenna #, or all ACCs. Do not restart your observations until after the antenna image in the atdrivemon display has returned to normal.

set|show parameter

Set or show persistent caobs configuration parameters, or control antenna-based hardware. Not all parameters can be used with both set and show. The parameters are:

set|show atten ca0# a b

Set the receiver module's attenuation levels for whichever receiver is currently being used (i.e. for the central frequency of the current scan). This includes the mm receivers, so this command can be used instead of the set mm command. Unlike the CABB attenuators, the first attenuator setting (a) is applied to both “A” polarisations (A1 and A2) and the the second setting (b) is applied to both “B” polarisations (B1 and B2). Each attenuator step introduces (or removes) 1dB of attenuation to the signal path. There are 16 receiver attenuator steps (0-15).

In general, this command should be executed while caobs is observing (i.e. the correlator is in the “GO” state).

With the installation of the 16cm and 4cm receivers on the array, all receivers now have controllable receiver attenuators.

Related commands: set mm

set|show aver n

Average your data over n integration cycles in time. You must stop the scan before using this command. When observing large fields you should be careful not to average so much that you significantly distort your image (azimuthal smearing caused by time averaging increases linearly with distance from the phase centre). Refer to Appendix D of Killeen (1993) for details. The current averaging time is displayed on the caobs screen.

Note: Time averaging can also be set in the schedule file.

It is not recommended that this parameter be used, since the data saved by cacor will be averaged by this amount and the unaveraged data cannot be recovered. It is better that you average the data later in data reduction if required.

Related commands: cain cycle

set|show band1_antennas ##

If you are attempting to use the ATCA's split-band observing capability, then you can use this command to specify which antennas should be allocated to each band. The set of antennas listed in ## will be allocated to the band specified by the IF1 central frequency, and all other antennas will be allocated to the IF2 band.

Example: The command “set band1_antennas 245” will allocate antennas CA02, CA04 and CA05 to IF1, while CA01, CA03 and CA06 will be allocated to IF2.

This setting only has effect if the IF1 and IF2 central frequencies would put them in different bands.

set diode on|off|switching

Control the noise diodes on the antennas. For normal observations, this should be set to “switching”. The “on” and “off” settings are only useful for maintenace.

Note: The current state of the diodes cannot be shown in caobs, but is easily ascertainable by examining spd.

set|show el_limit n

Define the elevation limit to be n degrees. The hardware limit is 12°. You can use this command to skip sources in your schedule file below the specified elevation.

Please reverse this setting at the end of your run so you don't surprise the next observer.

Related commands: set rise_time

set|show file filename

Load the schedule file filename, which must be in the directory /atca/sched on xbones. The filename does not need to include the .sch extension.

The schedule filename will appear on the topmost section of the caobs screen.

set|show frequency n c

Set the central frequency of IFn (1 or 2) to be c MHz. All the normal frequency restrictions apply.

set genset_on all|cb|ca0#

Turn on all generators, or the generator for the control building only, or the generator for antenna CA0#, respectively.

This can be done without stopping observing, however it is important to monitor that the generator you commanded actually starts.

Only generators on attached antennas can be turned on.

Related commands: attach, detach, set genset_off, show status

set genset_off all|cb|caO#

Turn off all generators, or the generator for the control building only, or the generator for antenna CA0#, respectively.

This can be done without stopping observing, however it is important to monitor progress to make sure that the antenna or building you commanded returns to mains power successfully.

The power source will not automatically switch back to mains if a generator fails to start after it is commanded to start by the genset_on command. If the generator fails to start, you will actually have to request that the generator be turned off with the set genset_off command.

Related commands: set genset_on, attach, detach, show status

set|show hold n

The hold parameter is used to inhibit correlation only during those cycles affected by antenna movement. This command sets the hold period to n times the automatically-determined hold increment for every cycle (normally 512ms), irrespective of antenna drives.

To return to automatic hold calculation, given the command set hold 0.

show length

Display the length of the current scan.

set|show mm ca0# a b

Set the attenuation levels in the mm receiver. This command only works for the 15mm, 7mm and 3mm receivers. Unlike the CABB attenuators, the first attenuator setting (a) is applied to both “A” polarisations (A1 and A2) and the second setting (b) is applied to both “B” polarisations (B1 and B2). Each attenuator step introduces (or removes) 1dB of attenuation to the signal path. There are 16 receiver attenuator steps (0-15).

In general this command should be executed while caobs is observing (i.e. the correlator is in the “GO” state).

Related commands: set atten

show mode

Display the epoch currently being used by caobs.

show name

Display the name of the current source.

set|show paddle in|out

Operates the room temperature paddle attached to the 3mm receiver. Normally, operation of the paddle is automatically done via the schedule file. This command should only be used for maintenance purposes.

set|show point_antennas ##

Defines which antennas catag will use to calculate pointing corrections.

Example: set point_ant 234 would allow pointing corrections to be calculated for antennas CA02, CA03 and CA04.

Note: There appears to be a bug in catag such that if an antenna is added to the point_antennas set, the first pointing scan done after this command is given will not compute corrections for the added antenna. You can simply redo the pointing scan to compute the corrections.

Related commands: point, set point_pattern, set point_ifflag

set|show point_ifflag ##

Defines which IF channels catag will use to calculate pointing corrections. Pointing corrections are not made as a function of polarisation or frequency, so this parameter just allows you to average more data to get a higher signal-to-noise ratio and therefore a more accurate solution.

Example: set point_if 12 would make catag use polarisations A and B in IF1.

At mm frequencies, this parameter should normally be set to 1234. If the IF1 frequency differs from the IF2 frequency by more than 30%, then the primary beam in one IF will be too different to the other IF to use them both simultaneously to calculate pointing corrections. In this case, catag will automatically change this setting to 12.

Related commands: point, set point_pattern, set point_antennas

set|show point_pattern n

Specify the number of cycles (n) caobs will direct the antennas to spend on each offset position during a pointing scan.

If n is a positive number, the “selfcal” pointing procedure is used, whereby all the antennas move to each offset point at the same time. There must be at least four antennas enabled for this mode of pointing to work.

If n is a negative number, holography mode pointing is performed. In this case, all the antennas but one (a reference antenna) move to the offset positions. After the first round of pointing is done, a new reference antenna is chosen, and the process is repeated; in this way the pointing corrections are calculated for all the antennas, but it takes twice as long as selfcal mode. Use this pointing procedure only if you have fewer than three antennas available.

Note: The actual value of n is usually set to 2. catag only requires one integration at each offset point to do the pointing correction calculations, but two will increase the signal-to-noise-ratio. With CABB's bandwidth, n rarely needs to be set higher than 2. In the past, a pointing correction used to fail if one antenna did not make it on source in time for at least one cycle at any particular offset position; caobs now ensures that this can no longer occur, by adding extra cycles when required to allow the antenna to get on source.

Related commands: point, set point_ifflag, set point_antennas

set|show reference #

Set the reference antenna to be CA0#. This will communicate the change automatically to the correlator. Using this command in caobs is required for holography-type experiments, where one antenna does not participate in an offset pointing program, and during the reconfiguration process.

set|show rise_time n

If a source is below the horizon when it is scheduled to be observed, caobs will wait for up to n minutes for the source to rise. If the source will not be up in that time, the array skips this source and moves to the next source in the schedule file.

Related commands: set el_limit

set scanlength h:m:s

If you set the position to be observed using the track 0 command, you can set the length of the scan with this command.

Related commands: track

set source sourcename

If you set the position to be observed using the track 0 command, you can modify the source name with this command.

Related commands: track

show start

Display when the current scan started, as UTC.

show status

Display general array information. Normally, the top panel of caobs will look as it does in Figure A.1. If you turn the generators on or off though, the top panel will be replaced with a warning about generator operation. To make caobs display the normal top panel again, use this command.

start [n[,k][-m][/l]]

Commence automatic scheduled observations once you have used the “set file” command to load your schedule file. The schedule file will then control the activity of the telescope.

This command can be used in a number of different ways:

If you are running a schedule that has scan starting times defined as UTC datetimes, then simply issuing the “start” command will start with the scan that should be currently running, and change scan as required.
Note: With a UTC schedule, any arguments to the “start” command will be ignored, and caobs will follow the schedule exactly as defined.
If you are running a schedule that does not have absolute UTC scan start times, issuing the “start“ command with no arguments will make caobs start with scan 1 and continue running the schedule file until there are no further scans.
Note: This is equivalent to giving the command “start 1/1”.
If you wish to start the observation with a scan defined in the schedule file as scan number n, then you can supply this scan number n as the first argument.
Example: “start 2” will start observing on the second scan defined in the current schedule file, and continue observing until the end of the schedule file is reached.
If you wish to start the observation with a scan defined in the schedule file as scan number n, and continue until the scan defined as scan number m is finished, then you can supply both the n and -m arguments.
Example: “start 2-8” will start observing on the second scan defined in the current schedule file, and continue observing until the end of the eighth scan is reached.
If you want to begin observing with a scan on a position defined in a mosaic file, that is not the first source defined in the mosaic file, then you can include the optional ,k argument, where k is the line in the schedule file (not including comment lines) that the source is defined on.
Example: “start 2,3” will start observing with the third position defined in the mosaic file that is referenced in the second scan of the schedule file. caobs will then continue observing until the end of the schedule file is reached.
If you want to make caobs loop repeatedly over a set of scans, starting with the first defined scan and ending with the last defined scan before repeating the process, then you can use the optional /l argument, where l is the number of times to loop over the scan range.
Example: “start 2/10” will start observing on the second scan defined in the current schedule file. When the last scan in the schedule is finished, caobs will continue observing starting with the first scan defined in the schedule file. After the last scan defined in the schedule is observed for the tenth time, caobs will stop observing.
Example: “start 2-8/10” will start observing on the second scan defined in the current schedule file. When the eighth scan in the schedule is finished, caobs will continue observing starting with the second scan defined in the schedule file. After the eighth scan defined in the schedule is observed for the tenth time, caobs will stop observing.
Example: “start 2,3/10” will start observing with the third position defined in the mosaic file that is referenced in the second scan of the schedule file. When the last scan in the schedule is finished, caobs will continue observing starting with the first scan defined in the schedule file. Subsequently, whenever the mosaic referenced in the second scan is observed, it will start at the first defined position. After the last scan defined in the schedule is observed for the tenth time, caobs will stop observing.

There are several caveats to using the “start” command.

If the source that is next in the schedule is below the elevation limit set by the “set el_limit” caobs command, and the source will rise within the time defined by the “set rise_time” command, then caobs will move the antennas to intercept the source as it rises above the elevation limit. During this time, the correlator will be ready to run, but will not be producing data; you may see an error message in assistance stating that there is no recent data from the correlator.
If the source won't rise within the rise time limit, then caobs will simply skip the source and continue to the next one in the schedule. If there are no sources in the schedule that are above the elevation limit, and won't rise within the rise time limit, then the behaviour of caobs may be strange; expect plenty of beeps.
If the source that caobs is tracking sets during the scan, caobs will move to the next source in the schedule, if possible.
If you command caobs to start a UTC schedule before the start time of the earliest scan, then it will prepare the correlator, but will not direct it to produce data, and the antennas will not move. Until the UTC of the first scan, you may see an error message in assistance stating that there is no recent data from the correlator.
WARNING: In this case, the correlator will NOT start until the start time of the scan you have started. Even if you stop the scan in caobs and start another, the correlator is waiting for the previous start time and cannot be interrupted. In other words, DO NOT START A UTC SCHEDULE BEFORE THE START TIME OF ITS EARLIEST SCAN.

Related commands: stop, track, point, set rise_time, set el_limit, attach, detach, enable, disable

stop

Stops the current scan. The antennas will stop moving and the correlator will stop producing data. Use the “correlator closefile” command to close the data file. A stop command is always sent to all attached and enabled antennas, even if no scan is underway.

Related commands: start, track, corr closefile

stow [ca0#]

Drives either the antenna CA0#, or all antennas (if no argument is given to this command) to an azimuth of 90° and an elevation of 85°. Brakes are applied to the drives once this position has been reached. Observations must be stopped before this command will work. Only attached and enabled antennas will be stowed.

Note: This is the preferred position for idle antennas. This command should be given at the end of your observation if the next observer is not ready to begin, or if there is no observing scheduled to begin within 30 minutes of your observations ending. This is also the recommended position for antennas during periods of high wind or during storms.

Related commands: stop, park

track [n]

Track the source described in scan n of the current schedule file, until either a stop command is issued or the source sets. If n is omitted, the first source in the schedule file will tracked.

If n is “0”, caobs will track a position using the current settings (usually from the previously-tracked source). The current caobs settings can be modified by a number of set commands.

Related commands: start, stop, set source, set frequency

wrap north|south

Specify the antenna azimuth wrap that should be used to track the next specified source. This command will only have an effect if caobs is stopped at the time, and if the next command given is “start” or “track”. Anything else will cancel the request.

You can demand the antenna wrap on a per-source basis in the schedule, using the “Wrap” parameter (an advanced parameter) in the CABB web scheduler.

Related commands: start, track

Prev		Next
4.4. Publishing Results	Home	Appendix B. cacor reference