Ubuntu Manpage: callisto - Unix version of the e-Callisto software

Provided by: callisto_1.1.0-2build2_amd64

NAME

       callisto - Unix version of the e-Callisto software

SYNOPSIS

       callisto [ options ]

DESCRIPTION

       The  Unix  version  of  the  e-Callisto  software  is  a  daemon  program  that can record
       uncalibrated data and spectral overviews from the Callisto hardware. If calibration of the
       data  is desired, it must be done afterwards by other means. The recorded data is saved as
       FITS files into the configured directory. Version 1.1.0 of the software supports  Callisto
       firmware versions 1.5, 1.7 and 1.8. Previous versions supported only firmware version 1.5.

       The  program  operation  can  be  controlled  by  a schedule file, and also directly via a
       command server listening on a TCP port.

OPTIONS

-c, --config FILE
Use the specified configuration file instead of /etc/callisto/callisto.cfg. The
location of the configuration file also specifies the configuration directory,
which is where other configuration files (frequency file and schedule) are assumed
to be in if they are not specified with an absolute file name.

-o, --datadir DIR
Specify the directory where the recorded data is stored as FITS files. This
overrides the value set in the configuration file.

-O, --ovsdir DIR
Specify the directory where spectral overview result files are written. This
overrides the value set in the configuration file.

-s, --schedule FILE
Use the given schedule file instead of scheduler.cfg in the configuration
directory.

-u, --user USER
Run as the given user.

-L, --load-channels
Upload the channel frequency data into the EEPROM. This is not normally done to
conserve EEPROM write cycles, and also to speed up program start. The data only
needs to be uploaded if the channel frequencies have changed.

-C, --check-only
Try to reset and identify Callisto hardware, and exit with status 0 if Callisto is
detected, and with status 1 otherwise. The check is done after channel upload, so
-L and -C can be used together for channel upload.

-P, --pidfile FILE
Write program PID in the specified file.

-d, --debug
Do not fork into background and turn on verbose debug messages. Logging is output
to stderr.

-D, --serial-debug
Print serial port traffic into stderr. Give this option twice to enable colors: red
color for data going to Callisto and blue for data coming from Callisto. This
option implies --debug.

-V, --version
Print program version.

-h, --help
Print program help text showing available options.

CONFIGURATION FILE

The Unix callisto uses the same configuration file format as the Windows software: entries
are in the format [variable]=value and comments start with // or /*. The variables are
compatible with the Windows software, except of course those that refer to file paths.

The following variables must be defined:

rxcomport
Full path of the serial port device where the Callisto hardware is connected to
this computer, e.g. /dev/ttyS0.

instrument
Short instrument code, appears as the first component of the FITS file names.

origin Location of the instrument (e.g. the institute/observatory).

frqfile
The channel frequency file to use. the file name is either an absolute path, or
relative to the configuration directory.

datapath
The directory where FITS files of the recorded data are stored.

longitude
Longitude of the instrument location in degrees, in the form of E,12.3 or W,45.6.

latitude
Longitude of the instrument location in degrees, in the form of N,12.3 or S,45.6.

height Height above sea level of the instrument location, in meters.

filetime
The time in seconds to record into one FITS file.

focuscode
The focuscode to use.

The following variables may be defined:

ovspath
The directory where spectral overview files are stored. Default is the value of
datapath.

chargepump
Whether PLL charge pump should be on or off. Default is 1 (on).

agclevel
PWM level for tuner AGC. Default is 120.

clocksource
Which source to use as the sampling clock. 1 for internal clock, 2 for external 1
MHz clock. Default is 1 (internal clock).

mmode Select the measurement mode. As only mode 3 is supported, setting this to any other
value will cause an error on callisto startup. Defaults to 3.

autostart
If set to 1, recording is automatically started on program startup. If set to 0,
recording is not automatically started. If not defined or set to a negative value,
the autostart value is deduced from the schedule, or set to 1 if there is no
schedule. Default is -1 (deduce from schedule).

The following variables are specific to the Unix version:

net_port
Start the command server on this TCP port. If not defined, the command server is
not started.

Variables not listed above are ignored.

FREQUENCY FILE

       The frequency file has the same syntax as the configuration file. The following  variables
       must be defined:

       target This must have the value CALLISTO.

       number_of_measurements_per_sweep
              The number of channels to use, from 1 to 512.

       number_of_sweeps_per_second
              How  many  channel  sweeps  to  perform  per  second.  The sample rate derived from
              multiplying the number of channels by this value should not exceed 1000.

       The following variable may be defined:

       external_lo
              Frequency of the frontend downconverter local oscillator in MHz. Defaults to 0.

       Additionally there must be an entry in the form [NNNN]=FFF.FFF,L for  each  channel  used,
       where NNNN is the channel number, from 1 onwards, FFF.FFF is the channel frequency in MHz,
       and L is the number of lightcurve samples (ignored by the Unix version).

OUTPUT AND LOGGING

       The FITS files have a file name in the format CCC_YYYYMMDD_hhmmss_FF.fit, where CCC is the
       instrument  code  specified  by the configuration variable instrument, YYYYMMDD and hhmmss
       are the (UTC) starting date and time of the data in the file,  and  FF  is  the  focuscode
       used.

       Spectral overview file names have the format OVS_CCC_YYYYMMDD_hhmmss.prn.

       Logging   is  done  to  the  daemon  facility  of  syslog,  which  typically  ends  up  in
       /var/log/daemon.log.

COMMAND SERVER

The command server listens at the TCP port specified by the configuration file variable
net_port. When a connection is established, the server prints a banner line "e-Callisto
for Unix V.V.V", where V.V.V is the program version. After that it will accept commands.
Responses to commands consist of a status line beginning either with OK or ERROR, followed
by zero or more data lines, and terminated by an empty line. The following commands are
available.

start Start data recording. If a spectral overview is in progress, recording is started
after it finishes. If recording is already in progress, a new FITS file is started
at the end of the current channel sweep. This command never fails.

stop Stop data recording. If a spectral overview is in progress, recording is not
(re)started after it finishes. This command never fails.

overview
Start a spectral overview. If an overview is already in progress, this command is
ignored. After the overview has finished, the recording state is restored to its
previous value (unless start or stop commands were issued during the overview).
This command never fails.

get Get the data from the latest complete channel sweep. The first data line printed is
in the format t=NNNNNNNNNN.NNNNNN, giving the start time of the sweep in Unix epoch
time. The rest of the data lines have the format chNNN=FFF.FFF:XXX, where NNN is
the channel number, from 001 to 512, FFF.FFF is the channel frequency in MHz, and
XXX is the channel value (in A/D converter units). This command may fail if there
is no data in the buffer.

quit Close connection to the command server. This command never fails.

SCHEDULING

       Scheduled operation of the program is supported via a schedule file. The default  schedule
       file  is  scheduler.cfg in the configuration directory. The schedule file contains entries
       in the format hh:mm:ss,FF,A, which specifies the UTC time hh:mm:ss of the schedule  entry,
       the  focuscode  FF  for which it is valid for, and the action A to take. Supported actions
       are start (3), stop (0) and overview (8).

       The Unix version of callisto does not support changing the focuscode or the frequency file
       (which would be the optional fourth field of the schedule entry) on the fly.

       If  there  is  no  schedule file, the program remains in manual control, possibly starting
       recording automatically on startup. The schedule file is checked for existence or  changes
       every  minute.  If  the schedule file appears or has changed, it is (re)loaded and the new
       schedule becomes active. If the program is in scheduled operation, and the  schedule  file
       disappears,  is  empty,  or  cannot  be  read,  the  program reverts to manual control and
       recording is started.

       The helper script callisto-sunschedule(1) can be used to create schedule files that record
       data only between sunrise and sunset.

SIGNALS

       Sending  the  HUP  signal to the callisto program has the same effect as issuing the start
       command via the command server.

       When the program receives the TERM signal, it  tries  to  exit  cleanly  by  stopping  the
       Callisto  hardware  and  writing any pending data buffers to disk. If a second termination
       signal is sent before the clean exit has finished, the program exits immediately, possibly
       causing the latest data to be lost.

FILES

       /etc/callisto
              Default configuration directory.

       /etc/callisto/callisto.cfg
              Default configuration file.

       /etc/callisto/scheduler.cfg
              Default schedule file.

AUTHOR

       Juha Aatrokoski <jha@kurp.hut.fi>