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

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>