# ts_watcher documentation¶

A CSC which monitors other SAL components and uses the data to generate alarms for display by LOVE. The point is to provide a simple, uniform interface to handle alarms.

The alarms are generated by rules which are defined in this package. The CSC configuration specifies which of the available rules are used and the configuration for each rule.

## Using lsst.ts.watcher¶

The fundamental objects that make up the Watcher are rules and alarms. Rules monitor topics from remote SAL components and, based on that information, set the severity of alarms. Alarms contains the state of an alarm, including the current severity, whether the alarm has been acknowledged, and the maximum severity seen since last acknowledgement. Rules are instances of subclasses of base.BaseRule. Alarms are instances of base.Alarm.

There is a one to one relationship between rules and alarms: every rule contains one associated alarm.

The set of rules used by the Watcher and the configuration of each rule is specified by the CSC configuration. The configuration options for each rule are specified by a schema provided by the rule. A typical Watcher configuration file will specify most available rules, and will likely be large. The Watcher configuration also has a list of disabled SAL components, for the situation that a subsystem is down for maintenance or repair. Rules that use a disabled SAL component are not loaded.

## Other Classes¶

Model manages all the rules that are in use. It is the model that uses the watcher configuration to construct rules, construct salobj remotes and topics and wire everything together. The model also disables rules when the Watcher CSC is not in the ENABLED state.

In order to reduce resource usage, remotes (instances of lsst.ts.salobj.Remote) and topics (instances of lsst.ts.salobj.topics.ReadTopic) are only constructed if a rule that is in use needs them. Also remotes and topics are shared, so if more than one rule needs them, only one is constructed.

Since rules share remotes and topics, the rule’s constructor does not construct remotes or topics (which also means that a rule’s constructor does not make the rule fully functional). Instead a rule specifies the remotes and topics it needs by constructing RemoteInfo objects, which the Model uses to construct the remotes and topics and connect them to the rule.

TopicCallback supports calling more than one rule from a topic. This is needed because a salobj topic can only call back to a single function and we may have more than one rule that wants to be called.

Rules are isolated from each other in two ways, both of which are implemented by wrapping each remote with multiple instances of RemoteWrapper, one instance per rule that uses the remote:

• A rule can only see the topics that it specifies it wants. This eliminates a source of surprising errors where if rule A if uses a topic specified only by rule B then the topic will only be available to rule A if rule B is being used.
• A rule can only see the current value of a topic; it cannot wait on the next value of a topic. That prevents one rule from stealing data from another rule.

## Contributing¶

lsst.ts.watcher is developed at https://github.com/lsst-ts/ts_watcher. You can find Jira issues for this module using labels=ts_watcher.

## Python API reference¶

### lsst.ts.watcher Package¶

#### Functions¶

 get_rule_class(classname) Get a rule class given its name.

#### Classes¶

 Alarm(name) A Watcher alarm. BaseRule(config, name, remote_info_list) Base class for watcher rules. Clock(config) Monitor the system clock of a SAL component using the heartbeat event. Enabled(config) Monitor the summary state of a CSC. Heartbeat(config) Monitor the heartbeat event from a SAL component. Model(domain, config[, alarm_callback]) Watcher model: constructs and manages rules and alarms. RemoteInfo(name, index[, callback_names, …]) Information about a remote SAL component. RemoteWrapper(remote, topic_names) Simple access to the current value of a specified set of topics. RuleDisabled Raised by BaseRule’s constructor if the rule is disabled. TopicCallback(topic, rule, model) Call one or more rules when a salobj topic receives a sample. WatcherCsc([config_dir, initial_state]) The Watcher CSC.

### lsst.ts.watcher.rules Package¶

#### Classes¶

 Clock(config) Monitor the system clock of a SAL component using the heartbeat event. Enabled(config) Monitor the summary state of a CSC. Heartbeat(config) Monitor the heartbeat event from a SAL component.

### lsst.ts.watcher.rules.test Package¶

#### Classes¶

 ConfiguredSeverities(config) A test rule that transitions through a specified list of severities, repeatedly. NoConfig(config) A minimal test rule that has no configuration and no remotes.