RemoteGroup#

class lsst.ts.observatory.control.RemoteGroup(components, domain=None, log=None, intended_usage=None, concurrent_operation=True)#

Bases: object

High-level abstraction of a collection of salobj.Remote.

A salobj.Remote provides a communication abstraction for Commandable SAL Componentes (CSCs). CSCs represents entities in the LSST observatory system that performs actions such as controlling/interfacing with hardware, logical operations and/and coordination of other CSCs. In general CSCs operate in logical groups to achieve certain kinds of operation; like slewing the telescope and taking images.

Parameters:

components (list [str]) – A list of strings with the names of the SAL components that are part of the group.
domain (salobj.Domain) – Optional domain to use for the remotes. If None (Default), create a new remote.
log (logging.Logger) – Optional logging class to be used for logging operations. If None, creates a new logger. Useful to use in salobj.BaseScript and allow logging in the class use the script logging.
intended_usage (int) – Optional bitmask that maps to a list of intended operations. This is used to limit the resources allocated by the class by gathering some knowledge about the usage intention. By default allocates all resources.
concurrent_operation (bool, optional) – If False, tasks like enable and other concurrent tasks will be done sequentially. Default=True.

components#

List with the names of the CSCs that are part of the group. Format is the same as that used to initialize the salobj.Remotes, e.g.; “MTMount” or “Hexapod:1”.

Type:: list of str

components_attr#

List with the names of the salobj.Remotes for the CSCs that are part of the group. The name of the component is converted to all lowercase and indexed component have an underscore instead of a colon, e.g. MTMount -> mtmount, Hexapod:1 -> hexapod_1.

Type:: list of str

valid_use_cases#

usages#

rem#

Namespace with Remotes for all the components defined in the group. The name of the component is converted to all lowercase and indexed component have an underscore instead of a colon, e.g. MTMount -> mtmount, Hexapod:1 -> hexapod_1.

Type:: types.SimpleNamespace

check#

Allow users to specify if a component should be part of operations. For each component in rem, there will be an equivalent (with same name) in this namespace, with a boolean value. When subclassing, users may use this flag to skip components in different kinds of operations as well.

Type:: types.SimpleNamespace

Notes

The components list also accept indexed components, e.g. [“Test:1”, “Test:2”].

The intended_usage is a bitwise operation which allows users to construct use-cases by combining them, e.g.

BaseUsages.StateTransition | BaseUsages.MonitorHeartBeat

Also, note that intended_usage=None is different then intended_usage=BaseUsages.All. When set to None the class will load all available resources. When set to BaseUsages.All, the class will load the resources needed for all defined operations.

Attributes Summary

`components`	List of components names.
`components_attr`	List of remotes names.
`usages`	Define class usages.
`valid_use_cases`	Define valid usages.

Methods Summary

`assert_all_enabled`([message])	Check if all components are in the enabled state.
`assert_liveliness`()	Assert liveliness of components belonging to the group.
`cancel_not_done`(tasks)	Cancel all coroutines in `coro_list`.
`check_comp_heartbeat`(component)	Monitor heartbeats from the specified component and raises and exception if not.
`check_component_state`(component[, desired_state])	Monitor the summary state of a component and raises an exception if it is or goes to a state different than the desired state.
`close`()
`components_to_check`()	Return components for which check is enabled.
`disable_checks_for_components`(components)	Disables checks for a list of components.
`enable`([overrides])	Enable all components.
`expand_overrides`([overrides])	Expand an overrides dict with entries for every component.
`get_heartbeat`(component)	Get last heartbeat for component.
`get_identity`()	Get user identity.
`get_required_resources`(component, intended_usage)	Return the required resources based on the intended usage of the class.
`get_simulation_mode`([components])	Return a list with the simulation mode for components in the group.
`get_software_versions`([components])	Return a list with the software versions for components in the group.
`get_state`(component[, ignore_timeout])	Get summary state for component.
`get_work_components`([components])	Parse input into a list of valid components from the group.
`next_heartbeat`(component)	Get next heartbeat for component.
`next_state`(component)	Get summary state for component.
`offline`()	Put all CSCs in offline.
`process_as_completed`(tasks)	Process tasks are they complete.
`reset_checks`()	Reset all checks, enabling check for all components.
`set_rem_loglevel`(level)	Set remotes log level.
`set_state`(state[, overrides, components])	Set summary state for all components.
`standby`()	Put all CSCs in standby.

Attributes Documentation

components#

List of components names.

The name of the CSC follow the format used in the class constructor, e.g. CSCName or CSCName:index (for indexed components), e.g. “Hexapod:1” (for Hexapod with index=1) or “ATHexapod”.

Returns:: components – List of CSCs names.
Return type:: list of str

components_attr#

List of remotes names.

The remotes names are reformatted to fit the requirements for object attributes. It will be the name of the CSC (as in components) in lowercase, replacing the colon by an underscore, e.g. “Hexapod:1” -> “hexapod_1” or “ATHexapod” -> “athexapod”.

Returns:: components_attr – List of remotes attribute names.
Return type:: list of str

usages#

Define class usages.

This property defines what remote resources are needed for each class usages. Each item in the dictionary contain a list of components, if the remotes will be used for “read only” operations an which topics will be required. The “key” of the dictionary is the usage enumeration value.

Returns:: usages – Dictionary with class usages.
Return type:: dict

valid_use_cases#

Define valid usages.

When subclassing, overwrite this method to return the proper enum.

Returns:: usages
Return type:: enum

Methods Documentation

async assert_all_enabled(message='')#

Check if all components are in the enabled state.

Parameters:: message (str) – Additional message to append to error.
Return type:: None

async assert_liveliness()#

Assert liveliness of components belonging to the group.

The assertion is done by waiting for a new heartbeat from the component. The check feature will apply to the assertion so components marked with check=False will be skipped.

Raises:: AssertionError – If cannot get heartbeat for one or more components.
Return type:: None

async static cancel_not_done(tasks)#

Cancel all coroutines in coro_list.

Remove futures from input tasks list and cancel them.

Parameters:: tasks (list [futures]) – A list of coroutines to cancel.
Return type:: None

async check_comp_heartbeat(component)#

Monitor heartbeats from the specified component and raises and exception if not.

This method will run forever as long as the component continues to send heartbeats. The intention is that this can run alongside an operation, to make sure the component remains responsive.

Parameters:: component (str) – Name of the component to follow. The name of the CSC follow the format CSCName or CSCName:index (for indexed components), e.g. “Hexapod:1” (for Hexapod with index=1) or “ATHexapod”.
Raises:: RuntimeError – If the component does not send heartbeats in self.fast_timeout seconds.
Return type:: None

async check_component_state(component, desired_state=State.ENABLED)#

Monitor the summary state of a component and raises an exception if it is or goes to a state different than the desired state.

This method will run forever as long as the summary state remains unchanged. The intention is that this can run alongside an operation that require the component to be in a certain state, when the operation is completed, the task can be canceled.

Parameters:

component (str) – Name of the component to follow. Must be one of: atmcs, atptg, ataos, atpneumatics, athexapod, atdome, atdometrajectory
desired_state (salobj.State) – Desired state of the CSC.

Raises:

RuntimeError – If state is not desired_state.
KeyError – If component is not found.

Return type:

None

async close()#

Return type:: None

components_to_check()#

Return components for which check is enabled.

Returns:: Components to check.
Return type:: list of str

disable_checks_for_components(components)#

Disables checks for a list of components.

The elements of components that are not part of the CSC group will be ignored.

Parameters:: components (list of str) – A list of strings that indentifies the components to disable the check. The names can be eather in attribute format (e.g. “mtmount” or “hexapod_1”) or in salobj remote name format (e.g. “MTMount” or “Hexapod:1”).
Return type:: None

async enable(overrides=None)#

Enable all components.

This method will enable all group components. Users can provide overrides for the start command (in a dictionary).

Parameters:: overrides (dict) – Dictionary with overrides to apply. If None use recommended overrides.
Return type:: None

async expand_overrides(overrides=None)#

Expand an overrides dict with entries for every component.

Any components that have no specified override are set to “”.

Parameters:: overrides (dict or None) – A dictionary with (component name, overrides) pair or None. The component name is as it appears in the components_attr attribute, which is the name of the CSC in lowercase, replacing “:” by “_” for indexed components, e.g. “Hexapod:1” -> “hexapod_1” or “ATHexapod” -> “athexapod”.
Returns:: complete_overrides – Dictionary with overrides for every component in the group. Unspecifies components have override “”.
Return type:: dict
Raises:: RuntimeError – If an item in the parameter overrides dictionary is not a CSC in the group.

async get_heartbeat(component)#

Get last heartbeat for component.

Parameters:: component (str) – Name of the component.
Returns:: Last component heartbeat.
Return type:: heartbeat

get_identity()#

Get user identity.

Returns:: Identity.
Return type:: str

get_required_resources(component, intended_usage)#

Return the required resources based on the intended usage of the class.

When subclassing, overwrite this method to add the child class use cases.

Parameters:

component (str) – Name of the component, with index as it appears in components_attr attribute (e.g. test_1 for the Test component with index 1).
intended_usage (int or None) – An integer constructed from the self.valid_use_cases. Usages can be combined to enable combined operations (see base class documentation). If None, returns appropriate values to load all resources.

Returns:

resources – A simple namespaces with the following attributes:

add_this: bool: Should this remote be added to the collection?
readonly: bool: Create the remote for this component in readonly mode? Some operations does not require commanding.
include: list [str]: What topics should be included?

Return type:

types.SimpleNamespace

Raises:

KeyError – If component is not in the list of components.:

async get_simulation_mode(components=None)#

Return a list with the simulation mode for components in the group.

Parameters:: components (list of str, optional) – List with the name of components to get the simulation mode. If None (default) return the values for all components.
Returns:: simulation_mode – Dictionary with the name of the component and the value of simulation mode.
Return type:: dict

async get_software_versions(components=None)#

Return a list with the software versions for components in the group.

Parameters:: components (list of str, optional) – List with the name of components to get the software versions. If None (default) return the values for all components.
Returns:: software_versions – Dictionary with the name of the component and the value of software versions.
Return type:: dict

async get_state(component, ignore_timeout=False)#

Get summary state for component.

Parameters:

component (str) – Name of the component.
ignore_timeout (bool) – If True will return None in case it times out getting the state. Default is False, which means raise TimeoutError.

Returns:

state – Current state of component.

Return type:

salobj.State or None

Raises:

asyncio.TimeoutError – If can not get state in self.fast_timeout seconds.

get_work_components(components=None)#

Parse input into a list of valid components from the group.

Parameters:: components (list of str or None) – Input list of components to process or None. If None return a list with all components.
Returns:: work_components – List of valid components.
Return type:: list of str
Raises:: RuntimeError – If a component in the components input list is not part of the group.

async next_heartbeat(component)#

Get next heartbeat for component.

Parameters:: component (str) – Name of the component.
Returns:: Last component heartbeat.
Return type:: heartbeat

async next_state(component)#

Get summary state for component.

Parameters:: component (str) – Name of the component.
Returns:: state – Current state of component.
Return type:: salobj.State

async offline()#

Put all CSCs in offline.

Return type:: None

async process_as_completed(tasks)#

Process tasks are they complete.

If the first task that finishes completes successfully, it will cancel all other tasks in the list, empty the input list and return the value of the task. If the task results in an exception, it will cancel all other tasks, empty the list and raise the exception.

Parameters:: tasks (list`[`asyncio.Tasks]) – List of asyncio tasks to process.
Returns:: ret_val – Return value from the first completed task.
Return type:: object

reset_checks()#

Reset all checks, enabling check for all components.

Return type:: None

set_rem_loglevel(level)#

Set remotes log level.

Useful to prevent the internal salobj warnings when read queues are filling up.

Parameters:: level (int) – Log level.
Return type:: None

async set_state(state, overrides=None, components=None)#

Set summary state for all components.

Parameters:

state (salobj.State) – Desired state.
overrides (dict or None) – Settings to apply for each component.
components (list[`str]`) – List of components to set state, as they appear in self.components_attr.

Raises:

RuntimeError –

If a component in components is not part of the group. * If it fails to transition one or more components.

Return type:

None

async standby()#

Put all CSCs in standby.

Return type:: None