Shell clients

There is a set of low level utilities night_exposure, night_temperature, night_filter, night_power and telescope together with next level ones night_control, night_flats, night_darks and some internal utilies (their names are not important). The shell utilities offers to control of the camera and the telescope completelly. The low-level utilities are meant to be used as a basement for other (next, high-level) utilities. All others clients (including graphics clients) does not use the devices directly, but they calls the ones as a kind of subprocess. The night_control and etc. are only wrappers of the base set of utilities to provide a tool for a serie of astronomical images with different exposure times, filters and some another parameters.

All utilities has command-line interface with a similar set of control switches. The common options of all commands are an internet address of the server and the -h help option. The -host option is defaulted to a appropriate local socket. Run selected utility without any parameters to get short description of its own options.

night_exposure

Night_exposure is intended to acquire a single shot (exposure) on a connected CCD camera. It is invoked with parameters:

night_exposure - make a single exposure on a camera
Usage: night_exposure [-t time] [-s shutter on|off] [-b 1|2|3] [-o output]
options:
         -t    exposure time in seconds
         -s    shutter state, on - open, off - close for dark frame
         -r    select region by format: (x1,y1,x2,y2), default: full area
         -b    binning, 1 - 1x1, 2 - 2x2, 3 - 3x3, default: 3 
         -c    select chip, I - imaging (default), T - tracking
         -m    readout mode (see output of 'night_power info')
         -o    name of an output file, default to nightview.fits
         -name object's name
         -obsname observer's name
         -p    show progress indicator
         -pn   show progress indicator (on new line)
         -host address:port internet address server, default: local connect
Use Ctrl-C to interrupt the exposure or download in progress.
Setting of environment variable NIGHTVIEW_HOST is equivalent to -host option.

where -t time is an exposure time in seconds (real number). -o output gives name of the output file (default: nightview.fits). The binning can be -b 1,2,3 with meaning of 1x1 (full resolution), 2x2 (half resolution) and 3x3 (every pixel of image is composition of 9 chip's pixels). This option does not change an area for a readout. The readout area can be changed by using of -r option. The -s switch controls a shutter (useful for dark frames). Also, you can specify an object (observer) name for use in OBJECT (OBSERVER) keyword of the FITS file header (defaulted to no keyword will be used). The -p and -pn options invoke of the print of a text status progess bar. The -p variant is meant for use in interactive terminal (add no new line control character) and -pn for use in scripts. Use Ctrl-C to interrupt the exposure or download in progress.

The readout area is selected by four integer numbers enclosed in braces. The coordinates starts at left bottom corner according to the standard mathematical convention (eg. no stupid computer graphics convention is used). The (1,1,100,100) selects a left bottom part of image. Don't forget use of apostrophes, your shell may interpret braces differently than you are supposing.

The switch -r (region) is useful for a faster downloading of only some part of an image. For example, it can be used for acquiring of the serie of the exposures with a fine time resolution (useful for measuring of a periodic error of a mount or an observation of an eclipse?), when a download time is important.

The options after -o and -name requires a string. If you use a multi word name or an exotic character (please, suppose that all other a-z, A-Z and 0-9 are an exotic for your shell) enclose this string to apostrophes like this: 'BL Lac'.

night_filter

Night_filter utility controls behauviour of a colour wheel. It is intended to set of selected filter and to get list of possible filters. It is invoked with

night_filter - select filter or print current
Usage: night_filter [-f filter] [-list]
options
         info print current filter
         -f  set filter, one from list, may be: U,B,V,R,I 
         -list list of defined filters
         -init (re)initialize filter wheel
         -p    show progress indicator
         -host address:port internet address server, default: local connect
Setting of environment variable NIGHTVIEW_HOST is equivalent to -host option.

A basic action is to list all possible filters by use of -list option. After it, you can select any filter from presented set by use of -f option. The currently selected filter will show with info option. The list of filters is generated by nightviewd server so only the superuser can define the names of filters in the server's configure file.

night_power

Nigh power utility controls of basic functions of a camera. It includes the functions: switch-up, switch-down, a power. Also, one prints a basic information. It is invoked by

night_power - control the power of camera
Usage: night_power {on|off|info} [-host address]
options:
         on      switch on camera, failed if cammera not connected
         off     switch off camera
         info    print short info about camera
         -host address:port internet address server, default: local connect
Setting of environment variable NIGHTVIEW_HOST is equivalent to -host option.

Without parameters prints help. The 'on' option connect to the camera and to switch one on. The 'off' option switch of the camera to switch one down. The 'info' option prints a basic camera info (firmware description, number of pixels, pixel's sizes and so on) if camera has been switch to on.

night_temperature

Night_temparature utility controls a temperature regulation on a camera. The one provides to set of the temperature checkpoint and to print the current value of temperature(s) and a cooling power. It is invoked with

night_temperature - controls the camera temperature
Usage: night_temperature [get|set] [-t temperature] [-off] [-host address]
options
         get:
                 -t   print ccd current temperature in degrees of Celsius
                 -ta  print air current temperature in degrees of Celsius
                 -ts  print temperature setpoint in degrees of Celsius
                 -r   print current cooling power (relatively, in percents)
                 -f   print current status of fan, on or off
                  without switches print all available cooling information
         set:
                 -t temperature   set cooler temperature on value
                 -off             set temperature regulation off

         -host address:port internet address server, local connect is default
Setting of environment variable NIGHTVIEW_HOST is equivalent to -host option.

The main modes of this command are an informational 'get' (print of temperature of a ccd and an ambient temperature, a fan status and a cooling power) and 'set' (to set the ccd temperature to a specified value or to set off temperature regulation). Note, one is recomended to turn off regulation, but the fan leave to switch-on for a while.

night_batch & etc.

night_control, night_flats and night_darks are intended to make of whole series of images.

night_batch - non-interactive snapshoting with CCD camera
Usage: night_control [options] exptime1,filter1 [exptime2,filter2] ...
        -oo output filename mask, default: ''
        -o output prefix name, default: 'image'
        -n number of exposures, default=0
        -obsname,-observer observer's name
        -name,-object object's name
        -d auto-dark substract, dark interval, default: 0 no darks
        -w wait for specified num. of seconds, integer, default: 1
        -b binning, default=3
        -r select region by format: (x1,y1,x2,y2), default: full area
        -c select chip, I - imaging (default), T - tracking
        -v view exposed image with xnightview
        -p <x,y> point mode
        -pr radius to locate pointer star on image in pixels (default: 30)
        -pp toleration for pointer mode in arc seconds (default: 10)
        -host address:port internet address server, default: local connect
        -h print help

Setting of environment variable NIGHTVIEW_HOST is equivalent to -host option.
List of possible filters: 'B' 'V' 'R' 'I' 'C' 'None' 

The night_[control,flats] needs follows the twices of values for an exposure duration and a filter for to grab the serie of exposures. At least, one twice is required, but a more the one twice can be used. The full set of exposure, filter combinations will be used in one control loop.

The -r, -c, -name, -obsname has the same meaning as in night_exposure utility.

When filter will not changed, dont't use it. In this case, use blank character as supplement of filter (see examples).

The valid parameters are -n, -d, -v, -t. The -n represents number of exposures in serie, the script will be make dark frame after specified number of images and subtract its from a scientific images with -d option. It starts before first image. The -v parameters invokes xnightview for show a current image. The parameters and behaviour on base its can be tested with -t parameter.

The -o parameter specify the prefix of an output name. The resultant shape is prefix+number+character, where number designate the order in series and last character is a selected filter. For example, the 10th image over R filter of the object (with prefix cluster) will be cluster_10R.fits.

The shape of the output name can be changed with -oo option. The characters and so on can be arbitrary except: the integer format must precede the character and both must be presented.

Note for non-C programmers. The format "%d" will be print integers without leading zeros. The format "%02d" will be print integers with two decimal places: 01,02,03,04..09,10,11..99. Analogically for "%03d" and so on. The format "%s" will be print any string.

Example 1: An astronomer wants 100 exposures of PR Del, each 15 second in V filter, low resolution:

night_control -n 100 -name 'PR Del' -b 3 -o 'prdel' 15,V

Example 2: An astronomer wants 100 exposures of PR Del, each 15 seconds on V filter, automatically show image after download, every 20th exposure will be dark:

night_control -v -n 100 -d 20 -name 'PR Del' -o 'prdel' 15,V

Example 3: An astronomer wants 100 exposures of PR Del, each 15 seconds in V and 10 seconds in R filter, every 20th exposure dark:

night_control -n 100 -d 20 -name 'PR Del' -o 'prdel' 15,V 10,R

Don't change filter. The filter will not changed or unknown.

night_control -n 100 -d 20 -name 'PR Del' -o 'prdel' 15,

Technical note. The night_control search all binaries in standard system directories by default. If you need a run they from some non-standard place, add your bin directory to the system variable PATH. Especially, the binaries night_dark and night_keylist are required for night_control's correct run.

telescope

The main utility to control of the telescope is telescope. It's command line driven. No any config files are supposed. Telescope provide setting or getting many important characteristics of the dome, telescope or date. Transparently adds support for the local or Internet connection. The on-line help is provided with invoking it without parameters:

Telescope mount position control 0.3.0
telescope - mount control
Use: telescope [options] [set | get] [commands]

         get:    (specify nothing, one or more option)
                 -ra   print Right Ascension in degrees
                 -dec  print Declination in degrees
                 -a    print Azimuth (180 deg = sud)
                 -z    print Altitude
                 -ha   print Hour Angle
                 -jd   print Julian date
                 -synchro   sychronisation,(1=values are probably correct)
                 -status   print status of moving telescope
                 -velstat  RA and Dec velocities in format current/max

         set:    (every option needs additional argument(s))
                 -coo RA Dec set the Equatorial coordinates in degrees
                 -coa HA Dec set the Equatorial coordinates (I. kind) in degrees
                 -cal RA Dec calibrate Equatorial the coordinates in degrees
                 +ra [ddd.d..] add value (may be negative) to R.A. in degrees
                 +dec [ddd.d..] add value (may be negative) to Dec in degrees
                 +ra [+|-] for continue slew without endpoint
                 +dec [+|-] for continue slew without endpoint
                 +ra ! stop slew in Right Ascension
                 +dec ! stop slew in Declination
                 -vra   set velocity of Right Ascension in degrees per second
                 -vdec  set velocity of Declination in degress per seconds
                 -vclock set velocity of the hour clock
                 -c on   start the hour clock
                 -c off  stop the hour clock
         options:
                 -host address[:port] hostname of server, default to local
                 -q don't print telescope status during setting of telescope
                 -pn   show progress indicator (on new line)
                 -h print this info

Setting of environment variable TELESCOPE_HOST is equivalent to -host option.

Two main modes are supported. The get mode for getting all or specified characteristics and set mode to set and calibrate values. The key set or get should be used to identify the mode. The additional parameters can follow.

Status of telescope

The get option switchs to get mode. Than user can specify one, more or nothing option and required values will be printed. The format of the output list is list of items, each in the shape

name = value

where name is a name (can include spaces) of the characteristics and value as a float number. If any parameter from set (jd, ra, dec...) follows the parameter as printed without leading name and a equal sign. Only float is printed.

When you specify the get option on the command line without others parameters all of characteristics will be printed:

debian:~/nightview/mount$ telescope get
Right Ascension =   1.015
Declination     =  48.254
Apparent R.A.   =   1.036
Apparent Dec    =  48.262
Azimuth         = 296.456
Altitude        =  45.895
Hour angle      =  69.403
Dome            =   0.000
Julian date     = 2454459.39114
Siderical time  =    4.6945
Synchronized    = 0

The one (or more) parameters can be added:

debian:~/nightview/mount$ telescope get -jd
2452372.364

Calibration of coordinates

The setting of various coordinates is more exciting. The coordinates are calibrated by using the -cal (abbreviation of calibrate) options follows by two float numbers meaning the current coordinates. This command print 1 on success and 0 in failure and return code is set. For example, you cantered telescope to some bright star by hand and you need tell to server when the coordinates of this star are the current. This options will be frequently used at start of observation.

debian:~/nightview/mount$ telescope set -cal 10 10
1

Setting of telescope

When the coordinates were calibrated, we can point the telescope to some interesting object with -coo option (abbreviation of coordinate) followed by the two float numbers as required coordinates again. This command print 1 on success and 0 in failure and return code is set. The motors will be switched on and telescope will be moving. The utility prints text pseudo-progress bars when telescope is moving, with switch -q this behaviour is off-ed and this routine exits immediately.

debian:~/nightview/mount$ telescope set -coo 11 11
1

The moving velocity in both axes should be separately set before any moving is executed with parameters -vra (velocity RA) and -vdec (velocity dec) followed by float numbers. This velocity is directly passed to low-level subroutines already described. This parameters should be used together with -coo option. When velocity isn't specified is set to 1 degrees per second.

debian:~/nightview/mount$ telescope set -vra 1 -vdec -coo 11 1
1

The relative difference can be specified too. Then use switches +ra and +dec (+ mean addition to current coordinates). The differences in degrees will be add to current coordinates. The moving velocity can be specified, otherwise is set to 1 deg per second. The utility prints text pseudo-progress bars when telescope is moving, with switch -q this behaviour is off-ed and this routine exits immediately.

Emergency stop

The move of telescope can be interrupted with the option stop at any time. The command can be useful when the any failure is appear. The coordinate of the telescope are undefined after this command so the new calibration is required. Practicaly, the position of the telescope will close to coordinates reported by the daemon because, the mount server continuously save a current position with a small time grid.

debian:~/nightview/mount$ telescope set stop

Siderical clock

The switch -c followed value from a set (on, off, park) controls the clock. The option on switch up the clock, off stops the clock and park move telescope to park position (azimuth 0, height 90). This command print 1 on success and 0 in failure and return code is set.

debian:~/nightview/mount$ telescope set -c on
debian:~/nightview/mount$ telescope set -c off

Environmental variables

All shell utilities gets a set-up information from environmental variables NIGHTVIEW_HOST and TELESCOPE_HOST. The command line options replaces the environmental setting.

Example. The command

export NIGHTVIEW_HOST="my.camera.net"

will set the host with camera conected to my.camera.net.

The authetification can be passed to remote host via environment variable in usuall manner:

export NIGHTVIEW_HOST="kokot:neco@my.camera.net"

Read-only flag of output images

Generally, every image from a CCD astronomical camera is unique. No repeating of heaven's mysteries is possible. That's the way, why all utilities of Nightview package saves every image as read-only by default. (Technically, the unmask mode is set to 444 on Unix systems.) There is no possibility to clear of the feature (except patching and re-compilation of sources). If you can rewrite or delete your data (NOT RECOMMENDED), use chmod command on the images.

The feature has been added after author's mistake when all images of the 1998WT24 asteroid, BL Lac observations and time series of SAX xxxx+xxx has been lost. Please, be careful.

Last modification: 2009-01-22 16:05:57