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

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):

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/',

    # List of additional paths to Agent plugin modules.
    'agent-paths': [
      '/simonsobs/ocs/agents/',
    ],

    # 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/',

    # List of additional paths to Agent plugin modules.
    'agent-paths': [
      '/simonsobs/ocs/agents/',
    ],

    # 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

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:

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.

usage:  [-h] [--site SITE] [--site-file SITE_FILE] [--site-host SITE_HOST]
        [--site-hub SITE_HUB] [--site-http SITE_HTTP]
        [--site-realm SITE_REALM] [--instance-id INSTANCE_ID]
        [--address-root ADDRESS_ROOT] [--registry-address REGISTRY_ADDRESS]
        [--log-dir LOG_DIR] [--working-dir WORKING_DIR]
        [--crossbar-timeout CROSSBAR_TIMEOUT]

Site Config Options

--site: Instead of the default site, use the configuration for the specified site. The configuration is loaded from $OCS_CONFIG_DIR/{site}.yaml. If --site=none, the site_config facility will not be used at all.
--site-file: Instead of the default site config, use the specified file. Full path must be specified.
--site-host: Override the OCS determination of what host this instance is running on, and instead use the configuration for the indicated host.
--site-hub: Override the ocs hub url (wamp_server).
--site-http: Override the ocs hub http url (wamp_http).
--site-realm: Override the ocs hub realm (wamp_realm).
--instance-id: Look in the SCF for Agent-instance specific configuration options, and use those to launch the Agent.
--address-root: Override the site default address root.
--registry-address: Deprecated.
--log-dir: Set the logging directory.
--working-dir: Propagate the working directory.
--crossbar-timeout: Length of time in seconds that the Agent will try to reconnect to the crossbar server before shutting down. Note this is set per Agent in an instance’s arguments list.

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

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

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