Provided by: callisto_1.1.0-2build2_amd64 bug

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>

SEE ALSO

       callisto-sunschedule(1)

       http://www.e-callisto.org/

       http://www.e-callisto.org/Software/Callisto-Software.html