.. highlight:: bash

.. _site_config_user:

======================
OCS Site Configuration
======================

Overview
========

This page describes the OCS configuration file. This file describes all the
Agents running in an observatory across all hosts.

.. _ocs_site_config_file:

OCS Site Config File
====================

The OCS Site Config File (SCF) is a single YAML file that defines connection
parameters for the crossbar server, as well as the Agents that will run on each
host, whether on the host system, or in a Docker container. The SCF may be
shared between multiple hosts, providing distinct configurations for each one.

Example Config
--------------
Here is an example of an SCF for a site with two hosts, and 4 agent
instances (running two different classes of agent):

.. code-block:: yaml

  hub:

    wamp_server: ws://10.10.10.3:8001/ws
    wamp_http: http://10.10.10.3:8001/call
    wamp_realm: test_realm
    address_root: observatory

  hosts:

    host-1: {

      # Directory for logs.
      'log-dir': '/simonsobs/log/ocs/',

      # Description of host-1's Agents.
      # We have two readout devices; they are both Lakeshore 240. But they can
      # be distinguished, on startup, by a device serial number.

      'agent-instances': [
        {'agent-class': 'Lakeshore240Agent',
         'instance-id': 'thermo1',
         'arguments': ['--serial-number', 'LSA11AA',
                       '--mode', 'idle']},
        {'agent-class': 'Lakeshore240Agent',
         'instance-id': 'thermo2',
         'arguments': ['--serial-number', 'LSA22BB',
                       '--mode', 'acq']},
      ]
    }

    host-1-docker: {

      # Address of crossbar within Docker (based on service name)
      'wamp_server': 'ws://crossbar:8001/ws',
      'wamp_http': 'http://crossbar:8001/call',

      # Description of host-1's Agents running with Docker containers.
      # We have one readout device; a Lakeshore 372.

      'agent-instances': [
        {'agent-class': 'Lakeshore372Agent',
         'instance-id': 'LSARR00',
         'arguments': ['--serial-number', 'LSARR00',
                       '--ip-address', '10.10.10.55']},
      ]
    }

    host-2: {

      # Crossbar start-up instructions (optional).
      'crossbar': {'config-dir': '/simonsobs/ocs/dot_crossbar/'},

      # Directory for logs.
      'log-dir': '/simonsobs/log/ocs/',

      # Description of host-2's Agents.
      # We have two devices; another Lakeshore 240, and the OCS g3 file
      # Aggregator.

      'agent-instances': [
        {'agent-class': 'Lakeshore240Agent',
         'instance-id': 'thermo3',
         'arguments': ['--serial-number', 'LSA33CC',
                       '--mode', 'init']},
        {'agent-class': 'AggregatorAgent',
         'instance-id': 'aggregator',
         'arguments': ['--initial-state', 'record',
                       '--time-per-file', '3600',
                       '--data-dir', '/data/']},
      ]
    }

The `hub` section defines the connection parameters for the crossbar server.
This entire section will likely remain unchanged, except for the
``wamp_server`` and ``wamp_http`` IP addresses.

The `address_root` setting determines the leading token in all agent
and feed addresses on the crossbar network.  While "observatory" is
the default, it can be changed as long as the crossbar configuration
is also updated to permit operations on the `{address_root}.` uri.

.. warning::
   The hub settings must match the crossbar configuration.  If you
   change `wamp_realm` or `address_root`, especially, be sure to
   update your crossbar configuration accordingly.  (If using the
   ocs-crossbar docker image, this can be done through environment
   variables in the ``docker-compose.yaml`` file.)

Under `hosts` we have defined a three hosts, `host-1`, `host-1-docker`, and
`host-2`. This configuration example shows a mix of Agents running directly on
hosts and running within Docker containers.

.. note::
    The hostname within a Docker container is configurable in the
    ``docker-compose.yaml`` file. While you could configure it to be identical to
    the host system, we recommend naming the docker hosts with the convention
    "hostname"-"docker" to distinguish which Agents are running in Docker
    containers in the SCF.

.. note::
    To determine your host name, open a terminal and enter ``hostname``.

Each item under a given host describes the OCS Agents which can be run. For
example look at the first 372 Agent::

        {'agent-class': 'Lakeshore372Agent',
         'instance-id': 'LSARR00',
         'arguments': ['--serial-number', 'LSARR00',
                       '--ip-address', '10.10.10.55']},

The ``agent-class`` is given by the actual Agent which will be running. This
must match the name defined in the Agent's code. The ``instance-id`` is a
unique name given to this agent instance. Here we use the Lakeshore 372 serial
number, `LSARR00`. Finally the arguments are used to pass default arguments to
the Agent at startup, which contains the serial number again as well as the IP
address of the 372.

.. _environment_setup:

Environment Setup
-----------------
By default the system will look for site files in the path pointed to
by environment variable ``OCS_CONFIG_DIR``. To define this, add the following
to your ``.bashrc`` file::

    export OCS_CONFIG_DIR='/path/to/ocs-site-configs/<your-institution-directory>/'

The default site filename is ``default.yaml``.  In practice, it is recommended
to name the configuration file after a given site, i.e. ``yale.yaml``, and symlink to
``default.yaml``::

    $ ln -s yale.yaml default.yaml

During development, multiple YAML files may be in active use; then users will
identify their config file through command line arguments when launching Agents
and Control Clients (see below).

.. note::
    If you're proceeding in the same terminal don't forget to source your
    ``.bashrc`` file.

Crossbar Connection Timeout
---------------------------
If an Agent loses connection to the crossbar server it will be unable to
publish any values to its Feeds. By default, the Agent stays online for 10
seconds, waiting to remake the connection to crossbar. If it fails to do so, it
will stop all running processes and shutdown.

There may be instances where you would like the Agent to continue running its
Processes, even if the connection to crossbar is lost for some amount of time
or indefinitely. For these cases there is the ``crossbar-timeout`` argument.
This can be set at the Host level, at the individual Agent level, passed on the
commandline, or set via an environment variable. Setting the timeout to 0
disabled the timeout, allowing the Agent to run indefinitely without a crossbar
connection.

.. note::
    A crossbar connection is still required for initial startup of the Agent.

To set at the host level:

.. code-block:: yaml

  hosts:
    host-1: {

      # Set timeout to 20 seconds for all Agents on this host
      'crossbar-timeout': 20,

      'agent-instances': [
        # crossbar timeout set to 30 seconds
        {'agent-class': 'Lakeshore240Agent',
         'instance-id': 'thermo1',
         'arguments': ['--serial-number', 'LSA11AA',
                       '--mode', 'idle',
                       '--crossbar-timeout', 30]},
        # crossbar timeout disabled
        {'agent-class': 'Lakeshore240Agent',
         'instance-id': 'thermo2',
         'arguments': ['--serial-number', 'LSA22BB',
                       '--mode', 'acq',
                       '--crossbar-timeout', 0]},
      ]
    }

Commandline Arguments
=====================
There are several built in commandline arguments that can be passed to Agents
when running. Agent Developers can also add custom arguments to their Agents.
If running an Agent directly on a host these can be thrown when running the
Agent manually, or configured in the 'arguments' section of your SCF. The built
in arguments for all Agents are listed here, followed by some examples.

.. note::
    OCS users deploying Agents within Docker containers should be aware that
    commandline options may be thrown by default within the Docker container. These
    can be overridden by a user within their `docker-compose.yaml` file using
    the CMD instruction.

.. argparse::
    :ref: ocs.site_config.add_arguments
    :prog:

.. _ocs_agent_cmdline_examples:

Examples
--------
In the following examples, consider the "LS240_agent.py", which implements an
Agent for talking to Lakeshore240 devices.  Suppose these are being run on a
host called "host-1".  Refer to the example site configuration listed above.
*(Note that to run these in the example tree you will usually need to add the
options that select the example SCF and host, namely:* ``--site-file
telescope.yaml --site-host host-1`` *. One exception to this is when using*
``--site=none``. *)*

1. Because there are two instances of "Lakeshore240Agent" registered
   in the SCF, we must somehow pick one when running the agent::

     $ python LS240_agent.py --instance-id=thermo1
     I am in charge of device with serial number: LSA11AA

2. We can ask our agent to connect to a different WAMP realm, for
   testing purposes (note this realm would need to be enabled in
   crossbar, probably)::

     $ python LS240_agent.py --instance-id=thermo1 --site-realm=my_other_realm
     I am in charge of device with serial number: LSA11AA

3. Run an instance of an Agent, but force all configuration matching
   to occur as though the Agent were running on a host called
   "host-2"::

     $ python LS240_agent.py --site-host=host-2
     I am in charge of device with serial number: LSA33CC

   Note that we do not need to specify an ``--instance-id``, because
   the SCF only lists one Lakeshore240Agent instance.

4. To avoid referring to a SCF at all, pass ``--site=none``.  Then
   specify enough information for the agent to connect and run::

     $ python LS240_agent.py --site=none \
     --site-hub ws://localhost:8001/ws --site-realm debug_realm \
     --address-root=observatory --instance-id=thermo1 \
     --serial-number=LSA11AA --mode=testing
     I am in charge of device with serial number: LSA11AA