1.1   System Requirements¶

These are the collection of requirement documents and the requirements that drives the discussion of this tech-note.

1.2   Interface definition¶

Assuming the architecture specified in LSE-150 [LSE-150] for the configuration system (database or version controlled), we must now make sure enough information is captured to satisfy the traceability requirements specified in LSE-62 [2].

LSE-209 [1] specifies the global interface a component must implement to be a valid resource of the system, including a set of events to satisfy the aforementioned configuration requirements, e.g.; settingVersions and settingsApplied events. At the time of this writing, the information contained in LSE-209 [1] is insufficent to guide the development of the interfaces.

The diagram in Figure 1 illustrates the agreed upon interface for handling CSC configuration and satifying the system requirements.

Figure 1 Configurable CSC start process.

git describe --all --long --always --dirty --broken

2.1   Salobj Derived CSCs¶

Salobj is the framework provided by Telescope & Site to develop CSCs in Python. Extensive development documentation is available, especially on how to create configurable CSCs.

Components that are written using the framework will automatically inherit the standard behaviour implemented in the library. The main points regarding Salobj CSCs are:

1. Definition of the configuration repo. In general CSC configuration should be grouped according to the overall system architecture. For instance, ts_config_attcs hosts configurations for all the ATCS configurable components.
2. The configuration package is specified in the CSC code by overriding the method get_config_pkg.
3. The CSC defines a schema for its configuration, which lives with the CSC repository.

The configuration for a CSC is stored in the configuration repository in a directory with the same name as the CSC, e.g. ATAOS in ts_config_attcs stores the configuration files for the ATAOS CSC.

The first level inside a CSC configuration package will have the schema version, e.g., ATAOS/v1 and ATAOS/v2.

Inside a schema version the user can find the available configurations and a labels file. The labels will provide the mapping between the recommendedSettingsLabels and the configuration.

Note that some configuration files are not linked to any label. They can be either removed from the most recent version of the configuration or kept there for historical or testing purposes. Since the repository setup is published by the CSC in the settingVersions event, the user can aways go back to a set of configurations.

2.2   Camera CSCs¶

These CSCs will also specify a set of labels to recommendedSettingsLabels. A given label will point to N available versions that will be published via recommendedSettingsVersion. As an example, if a label called normal is present, that label may be present as the following versions: normal-1.1, normal-1.2, normal-2.0, normal-3.0.

2.3   Other Handcrafted CSCs¶

Unfortunately, not all CSCs provided by Telescope and Site are developed with a framework like Salobj that handles most of the system architecture details. Some CSCs where developed by external vendors which did not have a framework to work with at the time the contract started. In other cases the CSC was developed in-house using a different programming language due to performance requirements.

In these “handcrafted CSCs” the developer is in charge of constructing their own solution to the problem. Here we gather some information about those CSCs.

2.4   Non-Configurable CSCs¶

Some CSCs will not be configurable at all. Examples are sparse in our current architecture but, the from Salobj point of view, a CSC can be developed on top of a BaseCSC which makes it a non-configurable component.

A non-configurable CSC will ignore the settingsToApply attribute of the start command, as it does not contain any true meaning to it. Likewise these CSCs will not output any of the configuration-related events.

2.5   Examples¶

The most simple (and probably most common) case is for those where the CSC has only a single recommended setting. For example, for the ATDome CSC we have:

recommendedSettingsLabels: test
recommendedSettingsVersion: v0.3.0-0-g6fbe3c7
settingsUrl: file:///home/saluser/repos/ts_config_attcs/ATDome/v1

Some CSCs may also have multiple recommended settings, one of them being the preferred or default and another being secondary and so on. In this case, the purpose of those configurations should be spelled out. As an example, the ATAOS has a couple of available options for look-up tables. In this case, we may have something like:

recommendedSettingsLabels: current,constant_hex,high_degree
recommendedSettingsVersion: v0.3.0-0-g6fbe3c7
settingsUrl: file:///home/saluser/repos/ts_config_attcs/ATAOS/v2

Note how the recommendedSettingsVersion from both CSCs have the same value. Both configurations reside in the same repository: ts_config_attcs.

Imagine now that during a test run, someone connects to the computer running the ATAOS CSC and edits the configuration. The recommendedSettingsVersion would reflect that change with something like:

recommendedSettingsVersion: v0.3.0-0-g6fbe3c7-dirty

Even though it may be useful to edit configurations on the fly for testing, the process should be avoided as much as possible. When this happen, it prevents us from precisely identifying what configuration was used. Alternatively, the user could create a branch on their work machine, make the required changes, commit, push it to github and pull/check out the new configuration in the CSC machine.

For a CSC that uses a configuration database, like the ATCamera, we may have something like:

recommendedSettingsLabels: normal,highgain_fast,lowgain_fast,highgain_slow,lowgain_slow
recommendedSettingsVersion: 1.1,1.2,2.0,3.0
settingsUrl:  sqlite:///home/camuser/config/config.db

It might be the case where the configuration is hosted in a sql database which enables remote connection. Is this case, we could have something like:

settingsUrl: mysql://10.0.100.104:3306/CONFIG

4.1   Default configuration vs. default label¶

It is important to highlight that there is an important distinction between the default configuration and default label. The default configuration is the one encoded by developers into the component main code base, in general, using appropriate default values which would allow the component to operate safely. For Salobj CSC these are present in the configuration schema, which is in the root of the CSC repository (e.g. ts_atdome). The default configuration is loaded when the settingsToApply entry in the start command is empty.

A default label on the other hand, is the label that should be loaded by default. Right there is no way to specify/enforce what the “default label should be. As mentioned in Section 1.2.1   settingVersions, the high-level control software is designed such that it will select the first entry in the recommendedSettingsLabels attribute of the settingVersions event. Although it is very useful to allow autonomous startup, this is also potentially dangerous, in case users forget to specify the default configuration label as the first in the list. One alternative would be to force users to provide a label called default and that would be the one selected by the high-level control software. It would also make it clear for users which label is intended to be used as the default.

4.2   Use of “recommended” in settingVersions event¶

The use of “recommended” in both the main attributes of settingVersions event is a bit of a misnomer. The recommendedSettingsLabels actually specify available labels and recommendedSettingsVersion specify the version of the available configuration.

One suggestion would be to rename those to labels and version only, see 4.5   Topic renaming furthermore.

4.3   Configuration mapping¶

The mapping between label, configuration file, and branch description is not sufficiently straightforward, especially when trying to analyse configurations used in the past.

For instance, to perform a full reconstruction using the current framework on a salobj CSC, the user needs to know the configuration repository (which is specified in settingVersions.settingsUrl), the label used to configure the CSC (specified in start.settingsToApply command) and the version of the configuration (specified in both settingVersions.recommendedSettingsVersion and settingsApplied.settingsVersion). To get the label to configuration file mapping the user then need to go to the configuration repository, find the version that matches the one used by the CSC at that time, check the _label.yaml file so they can finally find out what configuration was used.

This information should probably be present in both settingVersions and settingsApplied. For instance settingVersions should contain an additional entry, e.g. mapping, with the names of the files the labels maps to (in case of git-based configuration) or any other appropriate mapping information (e.g. for database configuration). Then, settingsApplied should also have an entry for label and mapping that will contain information about the selected label.

4.4   Available vs. selected¶

The settingsApplied and settingsVersion events represent what is available and what was selected, respectively. These topics should have nearly identical attributes; available labels vs selected label, available mapping vs selected map, available branch description vs. selected branch description and so on.

4.5   Topic renaming¶

The interface would be much clear if we rename some topics and attributes to reflect more closely their true meaning.

The following is a renaming suggestion for discussion:

1. Rename settingsVersions``to``configurationsAvailable

   1. Rename recommendedSettingsLabels to labels.
   2. Rename recommendedSettingsVersion to version or branchDescription.
   3. Rename settingsUrl to url.
   4. Add mapping or filename. Filename might not be suitable for database based configuration.

2. Rename settingsApplied``to ``configurationApplied

   1. Add label.
   2. Add version or branchDescription.
   3. Add mapping or filename.
   4. Add url.
   5. Rename otherSettingsEvent -> otherInfo.

References