CCDSH

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

The program ccdsh is a modular command line interface (CLI) for controlling hardware elements related to astronomical observations: CCD cameras, telescope mount, dome and other optional related stuff (e.g. focuser, meteorological data acquisition devices and so on). This program is a user-interface fronted to various modules and it is aimed to provide a simple shell for controlling these pieces of hardware from the same environment as well as making an inter-connection between them according to the requirements of the observations.

This document describes briefly the main features of this ccdsh program. Please note that the aspects of the currently installed ccdsh environments are described in separate documents.

Software, hardware environment and requirements

By default, ccdsh do not provide any specific control for the hardware elements, thus ccdsh acts like a simple command-line ephemeris service program. The hardware elements and other features are managed via external modules that are usually loaded upon the initialization of ccdsh. However, independently from the actual type of the peripheral device, the generic control commands are the same in all environments. Using such modules, the features of ccdsh can be extended both by adding another hardware components and by adding functionalities aiding the telescope operation itself.

Hardware modules

The currently supported classes of hardware elements that can be controlled by ccdsh are the following:

imaging detectors (CCD cameras);
telescope mounts;
domes;
filter sets and filter wheels; and
focusers.

Although it is not necessary to know the underlying software stack of the hardware controlling programs (beyond these modules), it is worth to have some information about it since failures and errors are easier to be tracked and resolved if one knows how the system works in general.

Operation modules

The currently supported classes of modules that add other operational functionalities to ccdsh are the following:

command modules (making new commands available in addition to the built-in ccdsh commands);
object name resolves (i.e. adding support to figure out current coordinates of moving or fixed celestial objects); and
external loggers (i.e. logging the activities done with ccdsh).

As we will see later on, these modules (both control modules and operation modules) are loaded during run-time using the command module.

General usage and built-in features

The program ccdsh and all of the related modules and servers are installed to a control computer. Mostly, this computer has a public SSH access as well, so authorized users can access the program and data and control the whole observation process remotely.

The camera, dome, telescope mount, focuser and filter wheel are controlled via a command line shell (provided by ccdsh) by issuing simple commands for the specific hardware elements. There are both higher and lower levels of commands that can be used for observing and writing simple scripts. For instance, the full dome position control is implied via the commands related to the telescope mount motion commands. Namely, these higher level commands that slew the telescope to a given celestial position automatically computes the respective dome azimuth and moves the dome accordingly (so the telescope will look through the dome slit). However, commands on a lower level allows the user to set the dome slit position azimuth by hand or off from the telescope pointing. This is useful while taking dome flats or when the dome is moved to a home position after the observations.

The images acquired by the camera are stored and saved in the well-known common FITS format. In order to display these images, ccdsh communicates with the program DS9.

Getting started: Launching `ccdsh`

The program ccdsh can be started from any terminal, by typing ccdsh to the command line prompt. After a successful start of the program, we got a prompt,

CCD>

and the commands should be typed right after this prompt. The initialization process might require a few seconds (depending on the actual installation and hardware/software environment), so we might have to wait a littlebit after launching ccdsh.

Any time while running ccdsh, external system shell commands can be issued by preceding the command by an exclamation mark. For instance, starting DS9 from the ccdsh environment is simply:

CCD> ! ds9 &

In the following, this section describes briefly the available built-in commands.

The `help` command

This command shows the list of the available other commands (in some random order, currently). A more detailed description for a given command can be asked by typing the name of the command itself right after help:

help get
usage:  get dome {azimuth|status|slit} 
        get mount {position|setpoint|status} [-d|--degrees]
        get ccd status
        get focus
        get temperature
        get filter
        get location [-x]
        get modes}

The `status` command

The status command prints the status the currently loaded modules and module nodes:

CCD> status
CCD:      ready # 0 idle
Mount:    error # -1 unreachable dtime=48681
Dome:     error # -1 unreachable 0x0
Filter:   busy  #  1 busy (wait_wgotox)
Focuser:  error # -1 unreachable
Logger:   ready # 0 idle
Logger:   ready # 0 idle
Resolver: ready # 0 idle
Resolver: ready # 0 idle
Command:  ready # 0 idle
CCD>

Module nodes marked with the green ready are up and ready to be used, nodes marked with yellow busy are currently in operation and expected to be ready soon while the nodes marked with red error have some kind of error that does not allow the given functionality to be used without dissolving the problem. This brief status is followed usually by the full status message as reported by the module. The first number of this status message is always an integer status code. It is zero, positive or negative in the cases of ready, busy and error, respectively. The reasons of the errors are likely to be figured out from the full status message, that is followed by the status code.

In order to start the observations successfully, all of the modules and module nodes must be in a ready status. Usually, modules are loaded upon initialization (see #Startup procedure and software stack) by the command module (see #The module command for more details). Usually, the end-user does not really manage the modules directly. In general, the system administrator sets up the global startup scripts (Sec. #Global startup commands), in which the modules are loaded. However, it is recommended to test the status of the modules at least before the observations.

The `wait` command

This command suspends further CCDSH script or command execution until any of the loaded modules is in a busy state. Modules that are error state during the execution of the wait command are ignored. In an interactive CCDSH session, this wait command can simply be cancelled by pressing Ctrl+C.

The `date` command

This command prints the current date and time information for the current observing location:

CCD> date 
 LD=2010.11.02 LT=16:32:39.1 UT=15:32:39.1 JD=2455503.147674 ST=19:36:05.6

Here, LD is the local date (in YYYY.MM.DD format, years, months and days, respectively), LT is the local time, UT is the universal time, JD is the Julian day and ST is the sidereal time for the current location.

The `sky` command

This command computes and prints the celestial and apparent coordinates of celestial objects. By default (i.e. simply typing sky), the program reports information about the Sun and the Moon:

CCD> sky
# Object                 RA       Dec         tau      Alt      Az
Sun              14:31:46.6 -14:55:35 +11:14:27.2   -56.11  +159.99
Moon             11:36:17.5 -03:27:45 -09:50:03.8   -37.85  -137.24

By specifying the switch -p or --planets, the program prints information for the planets:

CCD> sky --planets
# Object                 RA       Dec         tau      Alt       Az
Mercury          15:12:10.6 -18:53:15 +10:34:57.1   -56.57  +141.48
Venus            13:54:29.7 -17:01:23 +11:52:38.0   -59.51  +176.53
Mars             16:07:45.0 -21:31:57 +09:39:22.7   -51.68  +120.25
Jupiter          23:40:04.4 -03:48:17 +02:07:03.3   +31.64   +38.09
Saturn           12:46:26.0 -02:35:27 -10:59:18.4   -43.24  -158.97
Uranus           23:50:03.4 -01:55:09 +01:57:04.3   +34.38   +36.30
Neptune          21:52:45.4 -13:23:28 +03:54:22.3    +9.90   +57.44

If the name or alias for a pre-defined object follows the command line switch of -j or --object, these information are reported for this particular object:

CCD> sky --object m31
# Object                 RA       Dec         tau      Alt       Az
m31              00:42:44.3 +41:16:09 +01:05:28.6   +76.79   +67.99

Before slewing the telescope to a given object, it is recommended to check the visibility of the object by comparing the apparent coordinates (horizontal altitude and azimuth) with the telescope mount and dome limitations.

The `get` command

This command allows us to obtain information about the CCD camera, telescope mount and dome as well as some other data that highly influence the observations.

Chip temperature and cooling: `get temperature`

The command get temperature reads the current CCD cooling parameters, such as the actual chip temperature, the expected (set) temperature, ambient temperature (if available) and the cooling power:

CCD> get temperature 
ccd=-9.8 amb=25.00 set=-9.8 power=16%

Focuser: `get focus`

This command simply prints the current position of the focuser:

CCD> get focus 
25.55

The units of the focuser position might depend on the actual telescope system. The focuser can be altered using the command set focus ... (see #Focuser: set focus).

Filter wheel: `get filter`

The command get filter reads the current filter wheel position. The position is an integer number that must be between 1 and N_filter (that is the currently available slots in the filter wheel). If the filter wheel is moving, the position is off from this interval (in principle it should be zero). The position and status codes are followed by the filter aliases, that are easy-to-remember names of the filters.

CCD> get filter 
position=2 name="V" name="Bessel V"

See also the command set filter about more details on switching between different filters.

CCD readout modes: `get modes`

The command get modes asks the camera and chip capabilities about different exposing and readout modes. These information include the internal mode identifier, the gain parameters, the effective resolution and the effective pixel sizes. The binning parameters of the image acquisition commands (see also the commands acquire and sequence later on) must be in accordance with the available readout modes listed here:

CCD> get modes 
# id sx   sy   gain  px     py
   00 4008 2672  0.78   9.00   9.00
   01 2004 1336  1.56  18.00  18.00
   02 1336  890  1.56  27.00  27.00
   03 4008    0  0.78   9.00   9.00
   04 2004    0  1.56  18.00   9.00
   05 1336    0  1.56  27.00   9.00
   06 4008 2672  0.78   9.00   9.00
   07 2004 1336  1.56  18.00  18.00
   08 1336  890  1.56  27.00  27.00
   09  445  296  1.56  81.00  81.00

Dome: `get dome`

The command

CCD> get dome azimuth

reads the current dome azimuth and print it (in degrees). The command

CCD> get dome status

checks the current status of the dome. If the dome does not do anything, the status is idle. If the dome tracks a given celestial position, the status is tracking. If the dome has not reached the desired azimuthal position, its status is rotating.

If the dome driver has support for opening and closing the dome slit door, the status of this slit door can be checked with the command

CCD> get dome slit

This command prints the dome slit door position, that is usually a number between 0 and 1. 0 means that the dome is fully closed (implying that the whole instrumentation is protected from the weather) while 1 means that the dome is fully opened (thus, it is ready to use and the observations can be started). Fractions between 0 and 1 mean that the dome slit door is partially opened only and might be in motion at this time. Any other values (negative ones, mostly) or status messages other than a real number between 0 and 1 (inclusively) imply that there is a failure with the dome slit door.

Telescope mount: `get mount`

The command

CCD> get mount position

reads the current celestial position of the telescope mount while the command

CCD> get mount setpoint

prints the current setpoint of the telescope. See also the commands slew and match for more details about telescope positioning.

The command

CCD> get mount status

checks the current status of the mount. It is useful while waiting for a slewing to be completed. The mount should be idle before real observations start.

The `set` command

Using this command we can either explicitly control the CCD camera, the telescope mount and the dome and/or imply some automatic features.

Current location: `set location`

This command configures the CCDSH environment in order to perform astronomic computations assigned to a certain geographic location. For example, the command

CCD> set location longitude=13:23 latitude=52:31

sets the current location to Berlin, Germany: <math>\lambda=13^{\circ}23^\prime</math>, <math>\varphi=52^{\circ}31^{\prime}</math>. The directive

CCD> set location fixed

disables further alternation in the longitude and latitude settings in the current CCDSH session. Since invalid geographic information could lead to failures in astronomic observations, it is recommended to use this command in a system-wide startup script that inevitably runs once a user initiates a CCDSH sessions.

In order to assign a certain timezone, commands having the form of

CCD> set location timezone=2:00

sets the current timezone to a specific value, for instance UTC+02:00 here in the example above. The command

CCD> set location timezone=local

reads the current system configuration in order to obtain the timezone information. This call is useful when daylight savings time is in use, i.e. users do not require to manually change the timezone offsets. Contrary to the settings of geographic location, this timezone offset is merely an informal value. Hence, it can be altered even if the location is fixed.

Temperature regulation: `set temperature`

This command sets the regulated temperature value:

CCD> set temperature -30

Due to the thermal inertia of the CCD chip, the regulated temperature is not obtained instantly and one has to wait a few minutes until this temperature is reached. After the regulation is set, one can track the current temperature by issuing the get temperature command. In order to have a stable thermal environment, it is worth not to go above a regulating power of 60 -- 70%. If the power is above these limits, even very small increments in the ambient temperature FOOTNOTE:(That can be caused by the camera itself if the air or water circulation is insufficient!) may lead to instabilities and the desired temperature regulation setpoint cannot be reached and more importantly, the actual chip temperature will not be constant at all.

In order to completely switch off the temperature regulation, use the command

CCD> set temperature off

Focuser: `set focus`

This command allows the alternation of the focuser (focal plane position). The tokens set focus must be followed by the desired focus position, in the units of the current system:

CCD> set focus 25.65

Use the command get focus to check if the position setpoint has been reached.

In order to assign a specific focus value simultaneously with filter changes, use the directive

CCD> set focus auto on

while the command

CCD> set focus auto off

turns this feature off. Use the command define focus <filter> <position> to assign a certain focus value for a given filter.

Filter wheel: `set filter`

The actual filter can be set by the set filter command. By default numeric filter identifiers can be specified here, however, by defining filter aliases (see also define filter ..., below), one can use more descriptive identifiers for the filters. Note that the filter wheel always needs a little time to move to position, thus the current status of the filter positioning should be monitored with get filter before issuing any serious command.

CCD> set filter V

Low level mount control: `set mount`

By default, the movements of the telescope mount is controlled by the slew command. In order to control the mount on a lower level, some commands are available starting as set mount ....

If the current slewing operation should be stopped due to some reasons, the mount can be stopped using the command

CCD> set mount stop

If the mount driver supports turning off or on the sidereal tracking, use the command

CCD> set mount track off

or

CCD> set mount track on

to turn off or turn on the sidereal tracking, respectively.

Dome: sidereal tracking, azimuth and slit door control: `set dome`

Automatic sidereal tracking

By issuing the command

CCD> set dome auto on

ccdsh will move the dome slit automatically so it will always follow the telescope. In most of the cases, this is fine. The this automatic behavior can be turned off by issuing

CCD> set dome auto off

Manual rotation

If the dome position should be adjusted manually, first switch off this automatic movement (set dome auto off). In order to move the dome to a given azimuth, use the command

CCD> set dome azimuth=<A>

where <A> is the desired azimuth angle in degrees (0^o is south, 90^o is west, -90^o is east and so on). The dome rotation can explicitly be stopped by issuing

CCD> set dome stop

anytime.

Manual start of sidereal tracking

The dome control mechanism is capable to track fixed celestial targets by issuing set dome track, followed by the declaration of the celestial position. See also slew and match commands how such celestial positions are defined in ccdsh. For example, for asking the dome controller to follow the apparent location of the object M31, use

CCD> set dome track -j m31

Some notes on asymmetrical telescope mounts (e.g. German equatorial mounts): it is important to know that both this explicit dome tracking and the previously mentioned automatic tracking expect that the telescope mount piering is proper. Namely, objects that are on the east side of the meridian (i.e. rising objects, before culmination) are observed from west pier side while objects on the west side of the meridian (i.e. setting objects, after culmination) are observed from east pier side. In order to override this default behavior, use the command line switches -e and -w to expect east pier side and west pier side, respectively. Note that objects that have been started to track before culmination are observed in west pier side, however, following culmination (at τ=0) the telescope mount does not switch between the pier sides automatically and continue the tracking in west pier side. This might yield an unexpectedly large telescope slew (due to switching between the pier sides) even for a very small absolute mount position correction. Of course, if the dome driver knows that the telescope mount is a symmetric (e.g. fork) mount, these command line switches (-e and -w) are simply ignored.

The dome tracking can be turned off by issuing set dome stop and automatic dome movements (see set dome auto on) also override the latest dome track command.

Slit door control

If the dome driver has support for controlling the dome slit door, it can be opened using the command

CCD> set dome slit open

Similarly, the dome slit door can be closed using the command

CCD> set dome slit close

while the command

CCD> set dome slit stop

stops any motion of the dome slit door. We refer here to the command get dome slit, that can be used to check the dome slit door status (#Dome: get dome).

User interface settings: `set verbosity` and `set xpa`

Verbosity

These commands can be used to change some of the user interface behaviors. The command set verbosity ... sets the verbosity level of some of the other commands (e.g. acquire or sequence). The higher the number number given here, the more the number of messages printed by these commands:

CCD> set verbosity 1

Displaying images using DS9 and the XPA protocol

The command set xpa ... can be used to turn on or off the default XPA usage: if the command

CCD> set xpa on

is issued, the subsequent acquire or sequence commands will try to use the XPA interface to display the acquired images (mainly using the program DS9). This can be turned off by issuing

CCD> set xpa off

as well.

The command set xpa template ... sets the default XPA template string. For example, an alternate XPA connection point can be defined by

CCD> set xpa template localhost:5137

Such a configuration is useful if the DS9 display is tunnelled via SSH or multiple DS9 instances have been launched on the same host.

The `acquire` command

With this command, one can acquire single images. The filter wheel and temperature regulation must be set and checked accordingly before issuing this command. By default, this command acquires a full frame with the highest available resolution (i.e. with a binning of 1×1 pixels), one second of exposure time and tries to display it in the DS9 window. Of course, this default behavior is not adequate for most of the cases, so further tuning of this command is available via command line arguments:

-h|--help: shows a brief list of available options for the command acquire, with the basic syntax of these;
-V|--verbose: be verbose during image acquisition, so displays in the screen what is going on currently (exposing, readout, ...);
-t|--time :: the total integration/exposure time , in seconds;
-o|--output <file>: the name of the output file into which the image is saved in FITS format. Note that if we do not provide such a file, the program does not save it, only displays in DS9 (if available);
-b|--bin <bx>,<by>: the effective binning during readout will be <bx>×<by> -- only those binning resolutions can be provided here that are supported by the underlying camera hardware (see also: get modes);
-d|--dark: during image acquisition, the camera does not open the shutter;
-a|--auto-dark: :; 'after acquiring a normal frame, a dark image is also acquired with the same parameterization (i.e. binning and exposure time) that is automatically subtracted from the original frame;
-s|--size <sx>,<sy>, -f|--offset <x0>,<y0>: the image is read out only from the sub-frame [<x0>:<x0>+<sx>,<y0>:<y0>+<sy>]. This might be useful during focusing or making images with a smaller field-of-view and also yields a (proportionally) faster readout time;
-x|--xpa: the image is displayed in a DS9 window, independently whether it is saved or not.

Some examples

Acquire an image with 10 seconds of integration time, with a binning of 3×3 and the image is saved in the file test.fits and also displayed in the DS9 window:

CCD> acquire -b 3,3 -t 10 -o test.fits -x

Acquire a sub-frame in the section [400:500,1700:1800] of the chip with the highest available resolution while the image is not saved, just displayed in DS9:

CCD> acquire -b 1,1 -t 5 -f 400,1700 -s 100,100

The `sequence` command

This command is for creating a series of individual images. Although its syntax is a bit complex, one can create almost arbitrary sequences of images with various additional constraints. There are some common options with the command acquire that are also described above.

-h|--help: Shows a brief list of available options for the command acquire, with the basic syntax of these;
-V|--verbose: Be verbose during image acquisition, so displays in the screen what is going on currently (exposing, readout, ...);
-b|--bin <bx>,<by>: The effective binning during readout will be <bx> × <by> -- only those binning resolutions can be provided here that are supported by the underlying camera hardware (see also: get modes);
-s|--size <sx>,<sy>, -f|--offset <x0>,<y0>: The image is read out only from the sub-frame [<x0>:<x0>+<sx>,<y0>:<y0>+<sy>]. This might be useful during focusing or making images with a smaller field-of-view and also yields a (proportionally) faster readout time;
-x|--xpa: The image is displayed in a DS9 window, independently whether it is saved or not.
-n|--basename <file-base>: The resulted images are saved in files named accordingly to <file-base>. This base filename is followed by the filter name and the image sequence number, each of these are separated with an underscore (_) character and the files will have an extension of .fits. Like the command line argument of -o|--output in the case of acquire command, if this command line option is omitted, the resulted images are not saved, just displayed in DS9. Be careful.
-j|--object flat|name=<name>,ra=<RA>,dec=<DEC>: This switch defines the properties of the observed object by implying that the camera really observes this celestial position. This option is merely informal: it does not have any "side effects", just write the coordinates and the name of the object in the appropriate FITS headers.
<frame>|<N>*(<sequence>),...: This general term defines the image sequence itself. It is a comma-separated list of tags where each tag can be either an individual image or a repetition number followed by a sub-sequence. Each sub-sequence must be put between parentheses (like (...) this) while options for the individual frames are defined in square brackets (like [...] this, see below. The operations that move the telescope or alter the focus must be written between curly brackets, see also below.
[dark|bias|time=|filter=<filter>|delay=<d>|<filter>|]: The syntax for acquiring a single image frame. Between the square brackets, one should specify at least the image type or the integration time if the image type is not a bias frame and optionally a filter name. For short, a single number will imply the integration time and a single alphabetic term will imply the filter name. For instance, the declarations [filter=V,time=10] and [V,10] are equivalent, both yield a light frame, using V filter with 10 seconds of exposure time. Therefore, for short, the declaration [0] can be used to take bias frames as well. The filter specification can either be a numeric filter identifier or a declared filter name (see also the command set filter, #Filter wheel: set filter). Note that if the filter is specified by the numeric filter identifier, one should explicitly use filter=..., since a single integer would imply the exposure time instead of a filter identifier. See some examples below.
{focus=<focus>|ra=<ra>,dec=<dec>|object=<object>}: The syntax for controlling the focus and telescope between frames. Between the curly brackets, one can either alter the focuser position using the term focus=... (see also the command set focus ..., #Focuser: set focus), or alter the telescope position. The latter can be done by either explicitly setting the coordinates or using a pre-defined object name. See also some examples below (#Some examples 2).

Some examples

Create 10 bias frames with a binning of 3×3, and these bias frames are saved in the files bias_<N>.fits, where <N> is the sequence number (between 1 and 10):

CCD> sequence -b 3,3 -x -n bias 10*([bias])

Create 20 dark frames with an integration time of 5 seconds, also with a binning of 3×3. The frames are saved as dark_<N>.fits, where <N> is the sequence number (here, between 1 and 20):

CCD> sequence -b 3,3 -n dark 20*([dark,time=5])

Create a series of 2×100 images from the object M13 with a binning of 3×3 and altering between V and R filters. The exposure times are 10 and 20 seconds for these filters, respectively. The files are named as m13_<N>_V.fits and m13_<N>_R.fits, for each filter where <N> is the current image sequence number (between 1 and 200):

CCD> sequence -b 3,3 -V -x -n m13 -j name=M13 \
        100*([time=10,filter=V],[time=20,filter=R])

Note that this command only implies that the telescope points to the object M13, it does not slew to the desired position. For short, one can write simply:

CCD> sequence -b 3,3 -n m13 -j name=M13 100*([V,10],[R,20])

Observe two adjacent fields 10 times:

CCD> sequence -n scan 10*({ra=11:20,dec=+25},[I,10],{ra=11:20,dec=+26},[I,10])

Alter the focus between the filters:

CCD> sequence -n target 10*({focus=25.62},[B,20],{focus=25.50},[V,15])

The `slew` command

This command moves the telescope to the desired celestial position. The position argument can either be a celestial coordinate (in the form of right ascension and declination), an alias for a planet or pre-defined object or a valid object name that can be resolved by any of the externally loaded resolver modules. For example:

CCD> slew ra=00:42:44.3 dec=+41:16:09
CCD> slew -j m31
CCD> slew -p moon
CCD> slew ceres

The first command slews the telescope to the coordinates <math>\alpha=00^{\rm h}42^{\rm m}44^{\rm s}.3</math>, <math>\delta=+41^\circ16^\prime09^{\prime\prime}</math>, the second slews to the object having the name or alias "m31", the third one slews the telescope to the Moon while the last one slews to the current apparent position of Ceres (the dwarf planet). Of course, the second example expects that the object alias "m31" has previously defined by the user while the last one expects that a resolver module like mod_resolv_mpc.so has previously been loaded (see e.g. #The MPC resolver).

During the slewing of the telescope, the current position of the mount can be tracked using

CCD> get mount position

and the status of the mount slewing can be tracked using

CCD> get mount status

If the slew is completed, this position should be within a few arcseconds from the slewing setpoint:

CCD> get mount setpoint

Note that some telescope mounts have a noticeable inaccuracy in the positioning, even greater (tens of arcminutes) if the movement was large (tens of degrees or even more).

The `match` command

Some of the telescope control hardwares do not provide information about the absolute position of the mount (i.e. the hour angle and/or declination cannot be obtained without some kind of initialization and synchronization). For such mount drivers, ccdsh provides this match commands that aids this position matching between the telescope mount and the sky.

This command matches the telescope mount coordinates with the given celestial position. Like in the case of the slew command, the position can either be a celestial coordinate (in the form of right ascension and declination) or an alias for a planet or pre-defined object:

CCD> match -j vega

This command is useful at the beginning of the observations when the telescope is adjusted manually to a bright star.

Note that like most of the telescope mounts, the GTO-CPx mounts can also be controlled via an intelligent remote controller unit. If the observer uses ccdsh and this controller unit nearly simultaneously, the coordinates might not be synchronized, depending on the actual telescope mount hardware. In order to retrieve the current position of the mount and synchronize it with ccdsh, use the command

CCD> match --sync

or simply

CCD> match -y

This command is equivalent by reading the current position using

CCD> get mount position
ra=11:22:33.4 dec=+55:44:33}
and use the <code>match</code> command with the obtained coordinates:
 <nowiki>CCD> match ra=11:22:33.4 dec=+55:44:33

Subsequent call of the match command might be useful after larger telescope slews (see the note above at the end of the previous subsection), if the positioning is not so accurate.

Note that some telescope mount modules (e.g. the mod_pschtcm.so module, that controls the fork mount and the respective PSCHTCM electronics of the Piszkés/Schmidt telescope) have a complete support for absolute positioning, that is completely independent from the "past" of the mount positioning. Therefore, such mounts and the respective modules simply ignore these match commands.

The `resolve` command

If ccdsh has modules that support object name resolution, the command resolve can be used to obtain object coordinates via these modules. The command is simply followed by the name of the object, while ccdsh prints the object coordinates and reference epoch for this object:

CCD> resolve M31
M31 ra=00:42:44.32 dec=+41:16:07.5 epoch=2000.0

Note that a single resolve command can resolve only a single object. If more arguments are given after resolve, the program simply concatenates them with spaces and use this concatenated name for the object name resolution queries. If an object is not found in any of the databases supported by resolver module(s), ccdsh prints a warning message:

CCD> resolve NGC 6823 
"NGC 6823" ra=19:43:10.00 dec=+23:17:53.9 epoch=2000.0 
CCD> resolve NGC 9999
ccdsh: resolve: no object with the name 'NGC 9999' has resolvable coordinates.

Changing directories: the `cd` and `pwd` commands

Like in most of the shells, in the ccdsh environment, the cd and pwd commands change or print the current working directory:

CCD> pwd
/home/johnsmith
CDD> cd /data/johnsmith
CCD> pwd
/data/johnsmith

As of this writing, ccdsh does not have any built-in commands to create new directories (and like so, remove directories or files), however, one can use the plain shell itself to create new directories:

CCD> pwd
/data/johnsmith
CCD> ! mkdir 20110825 
CDD> cd 20110825
CCD> pwd
/data/johnsmith/20110825

Since the system-level command for changing working directories alter only the directory of the currently running process, escaping to the shell and change the directory outside won't alter the working directory of ccdsh itself:

CCD> pwd
/data/johnsmith/20110825
CCD> ! cd /data/johnsmith 
CCD> pwd
/data/johnsmith/20110825

In order to manage the files easily, the user can invoke system shell commands like ls from the ccdsh command line. Like so, higher level utilities, such as a Midnight Commander (mc) or other terminal windows (xterm, for example) can also be started and run from the ccdsh prompt.

Startup procedure and software stack

After starting ccdsh, the commands found in the files /usr/local/ccdsh/startup.ccdsh and $HOME/.ccdsh_startup are executed automatically in this order. The first file contains commands for the global startup (that is, de facto executed for all ccdsh users) and the latter one may contain some local definitions that is suitable for the user who started the ccdsh environment (for instance, definitions for personally interested celestial objects).

The `module` command

The purpose of the module command is to load, manage or remove external modules during run-time. By simply typing the command module, it lists the currently loaded modules in loading order:

CCD> module
mod_log_file.so      [logger]
mod_log_passive.so   [logger]
mod_pschtcm.so       [mount] [dome] [focus]
mod_resolv_sesame.so [resolver]
mod_resolv_mpc.so    [resolver]
mod_staralt.so       [command]
mod_qpaso2server.so  [ccd]
mod_ifw_serial.so    [filter]
CCD>

Using the command line argument -f or --full-list gives a more detailed list of information about the loaded modules:

CCD> module --full-list
[...]
mod_log_passive.so:
        Capabilities:  [logger]
        Command line:  mod_log_passive.so --port 8998
        Description:   A passive forwarding logger module
mod_pschtcm.so:
        Capabilities:  [mount] [dome] [focus]
        Command line:  mod_pschtcm.so --port 193.225.174.141:8873
        Description:   Wrapper module to the customized PSCHTCM server backend
        Documentation: http://ccdsh.konkoly.hu/
mod_resolv_sesame.so:
        Capabilities:  [resolver]
        Command line:  mod_resolv_sesame.so
        Description:   A wrapper to the CDS Sesame resolver
        Documentation: http://cdsweb.u-strasbg.fr/doc/sesame.htx
[...]

In order to remove running modules, use the command line argument -r or --remove for the command module, that is followed by the name of the module (full name of the shared object file, e.g. mod_pschtcm.so). Although modules can safely be removed and inserted at any time, it is worth to consult experienced users before doing so.

Global startup commands

As of this writing, these commands below are found in /usr/local/ccdsh/startup.ccdsh and executed inevitably for all ccdsh users.

This global startup script is installation-specific since it mostly loads the respective modules, initializes them and specify some constants and declarations (location coordinates, filter aliases and so on). See also the following section about more details on some environments and features.

Local startup commands

After the execution of the commands found in /usr/local/ccdsh/startup.ccdsh, the program seeks for a .ccdsh_startup file in the user's home directory. If this file exists, the commands found in this script file are also executed. This file might be used to define some additional objects that makes the whole observation easier and more convenient. For instance, a set of definitions for some well-known Messier objects can be:

define  object  M57     ra=18:53:35.1 dec=+33:01:45 epoch=2000.0 alias=m57
define  object  M27     ra=19:59:36.3 dec=+22:43:16 epoch=2000.0 alias=m27
define  object  M31     ra=00:42:44.3 dec=+41:16:09 epoch=2000.0 alias=m31
define  object  M74     ra=01:36:41.8 dec=+15:47:01 epoch=2000.0 alias=m74
define  object  M45     ra=03:47:24.0 dec=+24:07:00 epoch=2000.0 alias=m45

See also define object ... for further details.

Operation modules

This section briefly describes the modules and their functionality that are part of the ccdsh main source tree. Hence, these modules are likely to be available independently from the current observing and hardware environment (if loaded appropriately during startup or manually).

Resolvers

The Sesame resolver

The Sesame resolver, available in the file mod_resolv_sesame.so as a [resolver] class of module uses the CDS databases Simbad, Vizier and NED via the common query interface names Sesame. See also the page at http://cdsweb.u-strasbg.fr/doc/sesame.htx for more details about the Sesame service.

The Sesame resources are accessed via TCP/IP and persistent internet connection is required to successfully operate this module.

The MPC resolver

The Minor Planet Center (MPC) resolver, available in the file mod_resolv_mpc.so as a [resolver] class of module uses the Minor Planet Center's Minor Planet & Comet Ephemeris Service to resolve coordinates of small bodies in the Solar System.

Since these small bodies in the Solar System move relatively fast, all queries initiated by this module contains the current time as well, so the resolved coordinates are always up-to-date. The epoch of these coordinates are usually for J2000.0.

The MPC ephemeris services are queried via TCP/IP and persistent internet connection is required to successfully operate this module.

The Natural Satellites Ephemeris Service resolver

The Natural Satellites Ephemeris Service is also provided by Minor Planet Center. The module mod_resolv_natsat.so is a [resolver] class of module uses the MPC's Natural Satellites Ephemeris Service to resolve coordinates of irregular natural satellites of gas giant planets of the Solar System.

Since these natural satellites move relatively fast, all queries initiated by this module contains the current time as well, so the resolved coordinates are always up-to-date. The epoch of these coordinates are usually for J2000.0.

The Natural Satellites Ephemeris Service of MPC is queried via TCP/IP and persistent internet connection is required to successfully operate this module.

Loggers

The full source tree of the ccdsh package is shipped with two logger modules, mod_log_passive.so and mod_log_file.so. These modules log the ccdsh actions to clients that are connected to the logger module (as done by mod_log_passive.so) or writes the log entries to separate files (as it is done by mod_log_file.so).

The logger module mod_log_passive.so is passive in the following sense, by default: it does not write any log information unless TCP/IP clients are connected to its port. The default port is *:8998. This module is usually used by archivers: archiving scripts or programs tries to connect to this port, and if successfully connected, these scripts or programs retrieve information from ccdsh and do the necessary steps to archive the images acquired by the user.

The `staralt` command

A simple object visibility graph drawn by the staralt command which is provided by the mod_staralt.so module. Note that the coordinates of the two objects given in the command line arguments, Eris and NGC 6823 are resolved by external modules (mod_resolv_mpc.so and mod_resolv_sesame.so, respectively).

With the staralt command, provided by the module mod_staralt.so, one is able to generate object visibility graphs. These graphs are similarto the well-known service of the IAC, as it is available on the web page http://catserver.ing.iac.es/staralt/. Unlike the previously described resolver modules, this module does not require an internet connection, so it just generates something similar to the Staralt service of IAC/ING. However, this module is able to use the resolvers available to ccdsh, so plotting visibility graphs for objects of which name is resolved upon calling this command might require internet connection due to the needs of the resolver itself.

This module uses the gnuplot plotting tool to display the graphs, therefore a proper installation of this program is also required on the host that runs ccdsh.

The usage of the staralt command is simple, the arguments followed by the command are the names and/or coordinates of the objects that should be plotted on the visibility graph. Each object must be a single argument, thus objects with names containing spaces must be put in quotation marks. The optional -n or --night arguments can be used to specify other nights than the current one. The nights are specified in the format YYYY.MM.DD, meaning the night between this day and the next day:

CCD> staralt -n 2011.08.24 Eris "NGC 6823"

The graph given by this small example above are shown in Fig. REF:fig:staralt. Note that the location information is extracted from ccdsh, as well as the current timezone. These can also be altered via command line arguments to the command staralt, using the switches -l, --location and -z, --timezone, respectively. If the object name is replaced by two coordinates (either in traditional sexagesimal or in simply degrees), separated by comma, the visibility of this coordinate point is also plotted to the chart.

CCDSH

Software, hardware environment and requirements

Hardware modules

Operation modules

General usage and built-in features

Getting started: Launching ccdsh

The help command

The status command

The wait command

The date command

The sky command

The get command

Chip temperature and cooling: get temperature

Focuser: get focus

Filter wheel: get filter

CCD readout modes: get modes

Dome: get dome

Telescope mount: get mount

The set command

Current location: set location

Temperature regulation: set temperature

Focuser: set focus

Filter wheel: set filter

Low level mount control: set mount

Dome: sidereal tracking, azimuth and slit door control: set dome

User interface settings: set verbosity and set xpa

The acquire command

Some examples

The sequence command

Some examples

The slew command

The match command

The resolve command

Changing directories: the cd and pwd commands

Startup procedure and software stack

The module command

Global startup commands

Local startup commands

Operation modules

Resolvers

The Sesame resolver

The MPC resolver

The Natural Satellites Ephemeris Service resolver

Loggers

The staralt command

Navigation menu

Search

Getting started: Launching `ccdsh`

The `help` command

The `status` command

The `wait` command

The `date` command

The `sky` command

The `get` command

Chip temperature and cooling: `get temperature`

Focuser: `get focus`

Filter wheel: `get filter`

CCD readout modes: `get modes`

Dome: `get dome`

Telescope mount: `get mount`

The `set` command

Current location: `set location`

Temperature regulation: `set temperature`

Focuser: `set focus`

Filter wheel: `set filter`

Low level mount control: `set mount`

Dome: sidereal tracking, azimuth and slit door control: `set dome`

User interface settings: `set verbosity` and `set xpa`

The `acquire` command

The `sequence` command

The `slew` command

The `match` command

The `resolve` command

Changing directories: the `cd` and `pwd` commands

The `module` command

The `staralt` command