TOROS Manager’s Documentation¶

The TOROS Manager is a collection of installable daemons (services) to automize telescope operations.

The communication between modules is done using the XML-RPC protocol over sockets. This allows the modules to be distributed on different machines, as well as a single computer.

Contents:¶

Installing TOROS Manager¶

Requirements¶

To install this software you need

Python >=3.6 installed, preferably in a virtual environment or a local installation.
Linux or MacOS operating system.
Root or sudo access.

Installation¶

To install, clone the TOROS Manager repo and run the makefile. Preferably use a virtual environment:

$ git clone https://github.com/toros-astro/torosmanager.git
$ cd torosmanager
$ mkvirtualenv -p python3 toros
(ctmo)$ make
(ctmo)$ sudo make install

Installation requires root privilege. Root is only used to install the systemd or launchd services.

Depending on your operating system, this will install system services (currently only preprocessor) under /etc/systemd/system (the default path to install services in Linux) or /Library/LaunchAgents (the default path to install services in MacOS); and a configuration file under /etc/toros

Uninstall¶

To clean (delete intermediate files) and uninstall:

$ make clean
$ sudo -H make uninstall

Configuring your system¶

Before you start the services you may have to configure your manager to work with your system.

Configuration file¶

Open the configuration file located in /etc/toros/toros.conf.yaml. Inside you will find a YAML configuration file for the services.

Preprocessor Address¶

HTTP: The full address and port to locate the preprocessor service on the net.

IP: The IP address of the server running the preprocessor service.

Port: The port for the address of the server running the preprocessor service.

Logging¶

File: File path to the log file that will be used to log. Default is /etc/toros/logs/toros.log.

Log Level: One of DEBUG, INFO, WARNING, ERROR. Default: INFO.

Database¶

Specify database connection parameters (TBD).

System Services¶

Starting the services¶

Once the system is properly configured (see Configuring your system), you can start, stop or restart any of the services.

The operations to do so are different in Linux and MacOS. Both require root or sudo privilege.

Linux¶

On Linux, to start the preprocessor service you would run:

$ systemctl start preprocessor

and similarly for other modules. Now the system is ready to receive work orders through the network.

For more information, visit systemd wikipedia page or the official documentation.

MacOS¶

On MacOs, to start the scheduler service you would run:

$ launchctl load /Library/LaunchAgents/org.toros.preprocessor.plist

and similarly for other modules. To stop, use the unload command.

For more information, see launchd’s page or Apple’s official documentation.

Services¶

Preprocessor: Preprocess CCD exposures.

More will be added in the future.

XML-RPC Interface¶

Each service will run as a daemon (background process) and work on a specific port specified in the configuration file using the XML-RPC protocol.

Each service responds to a single function called front_desk which accepts a “Work Order”.

Work Orders (WO) are dictionaries with a specific structure described in Work Orders.

Warning

Work orders may not be used in the future. It is left here just in case.

Work Orders¶

The basic structure of a work order is as follows:

work_order = {
    "ID": "1",
    "WOType": "Observation",
    "Priority": None,
    "Datetime": "2019-03-05T14:34:54.234",
    "User": "Main Module",
    ...
}

WOType should be one of the following: Observation. Priority is assigned by the scheduler module when receiving the WO. It will be a float number in the range 0-10.

Telescope WO Format¶

Work Orders sent to a telescope must contain the WOType keyword set to the string Observation as well as other keywords relevant to an observation.

Below is an example.

{
    "ID": "1",
    "WOType": "Observation",
    "Priority": 1.3,
    "Datetime": "2019-03-05T14:34:54.234",
    "User": "Main Module",
    "Telescope Name": "CTMO",
    "RA": 23.1,
    "Dec": 13.2,
    "Filter": "I",
    "Exposure Time": 30.0,
    "Number of Exposures": 1,
    "Type of job": "Research",
    "Type of object": "Galaxy",
    "Calibration Frames": "Yes",
    "Output": "Analysis",
}

Dome WO Format¶

{
    "ID": "1",
    "WOType": "Dome",
    "Priority": 2,
    "Datetime": "2019-03-05T14:34:54.234",
    "User": "John Doe",
    "Blink01": True,
}