CALLISTO(1)

👑 CALLISTO(1) — the Unix glow-up of the e-Callisto software 💖

okay bestie, sit down, grab a strawberry 🍓, because we're about to read the callisto manual page and it's actually iconic. This is the General Commands Manual entry for callisto, and yes it lives in section 1, and yes we're gonna go through every single line together. no skimming. periodt. 💅

---

✨ NAME ✨

callisto — the Unix version of the e-Callisto software. that's it, that's the name, she's simple and she knows it 🎀

---

✨ SYNOPSIS ✨

callisto [ options ]

like, that's the whole vibe. you run her with options and she does her thing 🌸

---

✨ DESCRIPTION ✨

So the Unix version of the e-Callisto software is a daemon program that can record uncalibrated data and spectral overviews from the Callisto hardware. 🛰️

heads up bestie: the data comes out uncalibrated. if you want calibration, you gotta do it afterwards by other means. no cap.

The recorded data gets 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. glow-up era fr fr ✨

The program operation can be controlled by a schedule file, and also directly via a command server listening on a TCP port. two ways to run the show, main character energy 💅

---

✨ 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 (the frequency file and the schedule) are assumed to live if you don't give them with an absolute file name. so the path you pick here is doing double duty, she's multi-talented 💖
• -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. so like, don't just do it for fun, bestie 🙈
• -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. cute lil combo meal 🍓
• -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. she stays right there in your terminal, no ghosting 💀
• -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. double it for the aesthetic 💅✨
• -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. (yes, the original says "Longitude" here too — we keep it exactly as written, no editing the queen's words 😭)
• 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. > don't try to be different bestie, mode 3 or bust 💀
• 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. (she literally does not care 🙈)

---

✨ 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. ⚠️ math check bestie

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. so clean, so structured, we love a tidy protocol 💅

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. nope, not happening, don't ask 🙅

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. 😭 plot twist

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. 💀

fr fr bestie: one TERM is a polite goodbye, two TERMs is a rage quit and you might lose your data. be gentle. 🥺

---

✨ 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 💻

---

and that's the whole page, bestie, you ate it 💅✨ this was callisto, from the General Commands Manual, dated February 2017, and yeah the footer literally just says callisto and February 2017 and CALLISTO(1) again — she's consistent, she's iconic, she's done. 🎀💖🦋