Controller subpackage

This subpackage implements MCCS controller functionality.

It includes a controller Tango device and a CLI.

class ControllerComponentManager(*args: Any, **kwargs: Any)[source]

A component manager for an MCCS controller.

This component manager has three jobs:

  • Monitoring of the devices in the MCCS subsystem

  • Powering the MCCS subsystem off and on

  • Allocating resources to subarrays

__init__(subarray_trls: Iterable[str], station_trls: Iterable[str], subarray_beam_trls: Iterable[str], station_beam_trls: Iterable[str], logger: Logger, obs_command_timeout: int, communication_state_callback: Callable[[ska_control_model.CommunicationStatus], None], component_state_callback: Callable[[...], None], event_serialiser: ska_low_mccs_common.EventSerialiser | None = None) → None[source]

Initialise a new instance.

Parameters:

  • subarray_trls – TRLS of all subarray devices

  • station_trls – TRLS of all station devices

  • subarray_beam_trls – TRLS of all subarray beam devices

  • station_beam_trls – TRLS of all station beam devices

  • obs_command_timeout – the default timeout for obs commands in seconds.

  • logger – the logger to be used by this object.

  • communication_state_callback – callback to be called when the status of the communications channel between the component manager and its component changes

  • component_state_callback – callback to be called when the component state changes

  • event_serialiser – an optional event serialiser to use when serialising events

abort_subarray(subarray_id: int, task_callback: Callable | None = None) → tuple[ska_control_model.TaskStatus, str][source]

Abort an MCCS subarray.

Parameters:

  • subarray_id – an integer subarray_id.

  • task_callback – Update task state, defaults to None

Returns:

A tuple of (TaskStatus, message string).

allocate(task_callback: Callable | None = None, *, interface: str | None = None, subarray_id: int, subarray_beams: list[dict]) → None[source]

Allocate and distribute a set of unallocated MCCS resources to a subarray.

The kwargs argument specifies the overall sub-array composition in terms of which stations should be allocated to the specified subarray_beam. It contains: :param interface: the schema version this is running against. :param subarray_id: int, ID of the subarray which requires allocation :param subarray_beams: list of dictionaries, each sepcifying a beam allocation :param task_callback: callback to signal end of command

static calculate_target_adc(epoch_time: float | None = None) → float[source]

Calculate the targert RMS for ADC Equalisation.

In order to maintain the optimal range for ADC RMS value the telescope requires re-equalisation as the average power received by the antennas changes during sidereal time. This function calculates a target value for ADC re-equalisation, based on the sidereal time.

More details can be found in Memo 4: https://confluence.skatelescope.org/pages/viewpage.action?spaceKey=LC&title=Memo+004+-+Antenna+ADC+RMS+target+vs+LST

Parameters:

epoch_time – Time in seconds since the epcoh. Exists for testing.

Returns:

target ADC RMS value in ADUs

cleanup() → None[source]

Cleanup proxies and task executor.

get_health_trl(trl: str) → ska_control_model.HealthState | None[source]

Return the health of a subdevice with given TRL.

Parameters:

trl – TRL of device to return health of

Returns:

health of device given by TRL

Raises:

ValueError – if TRL is for an invalid device

get_healths(device_type: str = 'all') → dict[str, dict[str, str | None]][source]

Return subdevice healths.

Parameters:

device_type – the type of device to return the health state of its instances.

Returns:

dictionary of [device_type: [TRL : HealthState]] for each device of that device type, or all devices if called without an argument.

Raises:

ValueError – if device_type is not a valid device type.

get_resources(subarray_id: int) → str[source]

Return a dictionary of the resources assigned to a given subarray.

Parameters:

subarray_id – The subarray ID of the resources

Returns:

json formatted dictionary

Raises:

ValueError – if subarray_id is not valid

off(task_callback: Callable | None = None, task_abort_event: Event | None = None) → None[source]

Turn off the MCCS subsystem.

This is simpler than turning ON MCCS, we simply need to command all MccsStations to turn off and wait for it to happen.

Parameters:

  • task_callback – Update task state, defaults to None

  • task_abort_event – Check for abort, defaults to None

on(task_callback: Callable | None = None, task_abort_event: Event | None = None) → None[source]

Turn on the MCCS subsystem.

The procedure involves turning on all Stations.

Parameters:

  • task_callback – Update task state, defaults to None

  • task_abort_event – Check for abort, defaults to None

property power_state: ska_control_model.PowerState | None

Return my power state.

Returns:

my power state

release(task_callback: Callable | None = None, task_abort_event: Event | None = None, *, subarray_id: int, **kwargs: Any) → None[source]

Release a subarray’s resources.

Parameters:

  • subarray_id – ID of the subarray which requires release

  • task_callback – Update task state, defaults to None

  • task_abort_event – Check for abort, defaults to None

  • kwargs – additional arguments

release_all(task_callback: Callable | None = None, task_abort_event: Event | None = None) → None[source]

Release all subarrays resources.

Parameters:

  • task_callback – Update task state, defaults to None

  • task_abort_event – Check for abort, defaults to None

restart_subarray(subarray_id: int, task_callback: Callable | None = None, task_abort_event: Event | None = None) → None[source]

Restart an MCCS subarray.

Parameters:

  • subarray_id – an integer subarray_id.

  • task_callback – Update task state, defaults to None

  • task_abort_event – Check for abort, defaults to None

standby(task_callback: Callable | None = None, task_abort_event: Event | None = None) → None[source]

Put the MCCS subsystem into low power standby mode.

Parameters:

  • task_callback – Update task state, defaults to None

  • task_abort_event – Check for abort, defaults to None

start_communicating() → None[source]

Establish communication with the station components.

stop_communicating() → None[source]

Break off communication with the station components.

trigger_adc_equalisation(task_callback: Callable | None = None, task_abort_event: Event | None = None, *, station_args: list[dict]) → None[source]

Trigger adc equalisation.

Parameters:

  • station_args – a list of station ids

  • task_callback – callback to signal end of command

  • task_abort_event – Check for abort, defaults to None

class ControllerHealthModel(*args: Any, **kwargs: Any)[source]

A health model for a controller.

__init__(component_state_callback: Callable[[...], None], station_trls: Sequence[str], subarray_beam_trls: Sequence[str], station_beam_trls: Sequence[str], thresholds: dict[str, float]) → None[source]

Initialise a new instance.

Parameters:

  • component_state_callback – callback to be called whenever there is a change to this this health model’s evaluated health state.

  • station_trls – the TRLs of this controller’s stations

  • subarray_beam_trls – the TRLs of this controller’s subarray beams

  • station_beam_trls – the TRLs of this controller’s station beams

  • thresholds – The thresholds for number of sub devices healthy

evaluate_health() → tuple[ska_control_model.HealthState, str][source]

Compute overall health of the controller.

The overall health is based on the fault and communication status of the controller overall, together with the health of the stations, subarray beams and station beams.

This implementation simply sets the health of the controller to the health of its least healthy component.

Returns:

an overall health of the controller

station_beam_health_changed(station_beam_trl: str, station_beam_health: ska_control_model.HealthState | None) → None[source]

Handle a change in station beam health.

Parameters:

  • station_beam_trl – the TRL of the station beam whose health has changed

  • station_beam_health – the health state of the specified station beam, or None if the station beam’s admin mode indicates that its health should not be rolled up.

station_health_changed(station_trl: str, station_health: ska_control_model.HealthState | None) → None[source]

Handle a change in station health.

Parameters:

  • station_trl – the TRL of the station whose health has changed

  • station_health – the health state of the specified station, or None if the station’s admin mode indicates that its health should not be rolled up.

subarray_beam_health_changed(subarray_beam_trl: str, subarray_beam_health: ska_control_model.HealthState | None) → None[source]

Handle a change in subarray beam health.

Parameters:

  • subarray_beam_trl – the TRL of the subarray beam whose health has changed

  • subarray_beam_health – the health state of the specified subarray beam, or None if the subarray beam’s admin mode indicates that its health should not be rolled up.

class ControllerResourceManager(subarrays: Iterable[str], subarray_beams: Iterable[str], station_beams: Iterable[str], channel_blocks: Iterable[int])[source]

A resource manager for the controller component manager.

__init__(subarrays: Iterable[str], subarray_beams: Iterable[str], station_beams: Iterable[str], channel_blocks: Iterable[int]) → None[source]

Initialise a new instance.

Parameters:

  • subarrays – all subarrays to be managed by this resource manager

  • subarray_beams – all subarray beams to be managed by this resource manager

  • station_beams – all station beams to be managed by this resource manager (as a resource pool)

  • channel_blocks – all channel blocks to be managed by this resource manager

allocate(subarray: str, **resources: Iterable[Hashable]) → None[source]

Allocate resources to a subarray.

Parameters:

  • subarray – the subarray to which resources are to be allocated

  • resources –

    the resources to allocate. Each keyword specifies a resource type, with the value a list of the resources of that type to be allocated. For example:

    controller_resource_manager.allocate(
    "low-mccs/subarray/01",
    stations=[
        ["low-mccs/station/001", "low-mccs/station/002"]
    ],
    station_beams=[["low-mccs/beam/01", "low-mccs/beam/02"]]
    channel_blocks=[2, 3],
)

deallocate(**resources: Iterable[Hashable]) → None[source]

Deallocate resources (regardless of what subarray they are allocated to.

Parameters:

resources –

the resources to deallocate. Each keyword specifies a resource type, with the value a list of the resources of that type to be deallocated. For example:

controller_resource_manager.deallocate(
    stations=[
        "low-mccs/station/001", "low-mccs/station/002"
    ],
    channel_blocks=[2, 3],
)

deallocate_from(subarray: str) → None[source]

Deallocate all resources from a subarray.

Parameters:

subarray – the subarray to which resources are to be allocated

get_allocated(subarray: str) → Mapping[str, Iterable[str]][source]

Return the resources allocated to a given subarray.

Parameters:

subarray – TRL of the subarray for which the allocated resources are to be returned

Returns:

the resources allocated to the subarray.

set_ready(subarray: str, is_ready: bool) → None[source]

Set the health of a resource.

Parameters:

  • subarray – the subarray to be set as ready

  • is_ready – whether the subarray is ready or not

class MccsController(*args: Any, **kwargs: Any)[source]

An implementation of a controller Tango device for MCCS.

AbortSubarray(argin: int) → tuple[list[ska_control_model.ResultCode], list[str]][source]

Abort an MCCS subarray.

Parameters:

argin – an integer subarray_id.

Returns:

A tuple containing a return code and a string message indicating status. The message is for information purpose only.

Allocate(subarray_id: int, subarray_beams: list[dict] | None = None, interface: str | None = None) → ska_tango_base.type_hints.TaskFunctionType[source]

Allocate a set of unallocated MCCS resources to a sub-array.

The JSON argument specifies the overall sub-array composition in terms of which stations should be allocated to the specified Sub-Array.

Parameters:

  • subarray_id – integer subarray ID

  • subarray_beams – list of subarray beam allocation dicts

  • interface – schema interface version string

Returns:

A tuple containing a return code, a string message indicating status and message UID. The string message is for information purposes only, but the message UID is for message management use.

Example:

>>> proxy = tango.DeviceProxy("ska-low-mccs/control/control")
>>> proxy.Allocate(
        json.dumps(
        {
            "interface":
                "https://schema.skao.int/ska-low-mccs-controller-allocate/3.0"
            "subarray_id": 1,
            "subarray_beams": [
                {
                    "subarray_beam_id": 3,
                    "apertures": [
                        {"station_id": 1, "aperture_id": "1.1" },
                        {"station_id": 2, "aperture_id": "2.2" },
                        {"station_id": 2, "aperture_id": "2.3" },
                        {"station_id": 3, "aperture_id": "3.1" },
                        {"station_id": 4, "aperture_id": "4.1" },
                    ],
                }
                "number_of_channels": 32,
            ],
        }
        )
    )
GetAssignedResources(subarray_id: int) → str[source]

Return a dictionary of the resources assigned to a given subarray.

Parameters:

subarray_id – The subarray ID of the resources

Returns:

json formatted dictionary

GetHealthTrl(argin: str) → str | None[source]

Return health of device given by TRL.

Parameters:

argin – TRL of device to return health of.

Returns:

health of device given by TRL.

Release(subarray_id: int, interface: str | None = None) → ska_tango_base.type_hints.TaskFunctionType[source]

Release resources from an MCCS Sub-Array.

Parameters:

  • subarray_id – integer ID of the subarray to release

  • interface – schema interface version string

Returns:

A tuple containing a return code, a string message indicating status and message UID. The string message is for information purposes only, but the message UID is for message management use.

Example:

>>> proxy = tango.DeviceProxy("ska-low-mccs/control/control")
>>> proxy.Release(
        json.dumps(
            {
            "subarray_id": 1
            }
        )
    )
ReleaseAll() → ska_tango_base.type_hints.TaskFunctionType[source]

Release all resources from an MCCS Array.

Returns:

A tuple containing a return code, a string message indicating status and message UID. The string message is for information purposes only, but the message UID is for message management use.

Example:

>>> proxy = tango.DeviceProxy("ska-low-mccs/control/control")
>>> proxy.ReleaseAll()
RestartSubarray(argin: int) → ska_tango_base.type_hints.TaskFunctionType[source]

Restart an MCCS subarray.

Parameters:

argin – an integer subarray_id.

Returns:

A tuple containing a return code and a string message indicating status. The message is for information purpose only.

StandbyFull() → tuple[list[ska_control_model.ResultCode], list[str]][source]

Put MCCS into standby mode.

Some elements of SKA Mid have both low and full standby modes, but SKA Low has no such elements. We just need a Standby command, not separate StandbyLow and StandbyFull.

Returns:

A tuple containing a return code and a string message indicating status. The message is for information purpose only.

StandbyLow() → tuple[list[ska_control_model.ResultCode], list[str]][source]

Put MCCS into standby mode.

Some elements of SKA Mid have both low and full standby modes, but SKA Low has no such elements. We just need a Standby command, not separate StandbyLow and StandbyFull.

Returns:

A tuple containing a return code and a string message indicating status. The message is for information purpose only.

TriggerAdcEqualisation(station_args: list[dict]) → ska_tango_base.type_hints.TaskFunctionType[source]

Trigger ADC equalisation.

Parameters:

station_args – list of per-station dicts

Returns:

A tuple containing a return code and a string message indicating status. The message is for information purposes only.

Example:

>>> proxy = tango.DeviceProxy("ska-low-mccs/control/control")
>>> proxy.TriggerAdcEqualisation(
        json.dumps(
                {
                    "station_args":
                        [
                            {
                                station_id: 1,
                                target_adc: 17,
                                bias: 1,
                            },
                            {
                                station_id: 2,
                                target_adc: 1,
                            },
                        ]
                }
            )
    )
>>> # For all stations:
>>> proxy.TriggerAdcEqualisation(
        json.dumps("")
    )
__init__(*args: Any, **kwargs: Any) → None[source]

Initialise this device object.

Parameters:

  • args – positional args to the init

  • kwargs – keyword args to the init

buildState() → str[source]

Read the Build State of the device.

Returns:

the build state of the device

create_component_manager() → ControllerComponentManager[source]

Create and return a component manager for this device.

Returns:

a component manager for this device.

execute_Off() → ska_tango_base.type_hints.TaskFunctionType[source]

Put the Controller OFF.

Returns:

A tuple containing a return code and a string message indicating status.

execute_On() → ska_tango_base.type_hints.TaskFunctionType[source]

Put the Controller ON.

Returns:

A tuple containing a return code and a string message indicating status.

execute_Standby() → ska_tango_base.type_hints.TaskFunctionType[source]

Put the Controller into STANDBY.

Returns:

A tuple containing a return code and a string message indicating status.

healthModelParams(argin: str) → None[source]

Set the params for health transition rules.

Parameters:

argin – JSON-string of dictionary of health states

healthReport() → str[source]

Get the health report.

Returns:

the health report.

healthThresholds(argin: str) → None[source]

Set the params for health transition rules.

Default health thresholds:

“devices”: (f2f, d2f, d2d),
tuple(int, int, int): Number of devices failed before health failed,

Number of devices degraded before health failed, Number of devices degraded before health degraded

Valid devices are: “subarrays”, “stations”, “subarraybeams”, “stationbeams”.

Parameters:

argin – JSON-string of dictionary of health thresholds

init_device() → None[source]

Initialise the device.

is_Off_allowed(request_type: LRCReqType | None = ska_tango_base.long_running_commands.LRCReqType.ENQUEUE_REQ) → bool[source]

Return whether the OFF command is allowed.

Parameters:

request_type – The request type

Returns:

True if OFF command is allowed

Raises:

CmdNotAllowedError – if there are no devices to turn off

is_On_allowed(request_type: LRCReqType | None = ska_tango_base.long_running_commands.LRCReqType.ENQUEUE_REQ) → bool[source]

Return whether the On command is allowed.

Parameters:

request_type – The request type

Returns:

False if command is not allowed by base class

Raises:

CmdNotAllowedError – if there are no subservient devices

is_Release_allowed(request_type: LRCReqType | None = ska_tango_base.long_running_commands.LRCReqType.ENQUEUE_REQ) → bool[source]

Return whether the Release command is allowed.

Parameters:

request_type – The request type

Returns:

False if command is not allowed by base class

Raises:

CmdNotAllowedError – if there are no subservient devices

is_RestartSubarray_allowed(request_type: LRCReqType | None = ska_tango_base.long_running_commands.LRCReqType.ENQUEUE_REQ) → bool[source]

Return whether the Release command is allowed.

Parameters:

request_type – The request type

Returns:

False if command is not allowed by base class

Raises:

CmdNotAllowedError – if there are no subservient devices

is_StandbyFull_allowed(request_type: LRCReqType | None = ska_tango_base.long_running_commands.LRCReqType.ENQUEUE_REQ) → bool[source]

Return whether the StandbyFull command is allowed.

Parameters:

request_type – The request type

Returns:

False if command is not allowed by base class

Raises:

CmdNotAllowedError – if there are no subservient devices

is_StandbyLow_allowed(request_type: LRCReqType | None = ska_tango_base.long_running_commands.LRCReqType.ENQUEUE_REQ) → bool[source]

Return whether the StandbyLow command is allowed.

Parameters:

request_type – The request type

Returns:

False if command is not allowed by base class

Raises:

CmdNotAllowedError – if there are no subservient devices

is_Standby_allowed(request_type: LRCReqType | None = ska_tango_base.long_running_commands.LRCReqType.ENQUEUE_REQ) → bool[source]

Return whether the Standby command is allowed.

Parameters:

request_type – The request type

Returns:

False if command is not allowed by base class

Raises:

CmdNotAllowedError – if there are no subservient devices

missedEvents() → int[source]

Get the amount of missed change events.

Some commands rely on change events from sub-devices, sometime we miss these events, this attribute keeps track of how many we know we have missed.

Returns:

the amount of missed change events

resourceSummary() → str[source]

Return a detailed summary of all resources managed by the controller.

This attribute provides comprehensive information about the allocation and availability status of all resources in the system, structured as a JSON object.

The summary includes: 1) Total resources present in the system (inventory of all managed resources) 2) Resources currently in use, including which subarray they’re allocated to 3) Available resources that are not currently allocated 4) Detailed breakdown of resources by station/location

Resources tracked include: - Channel blocks: Frequency channels allocated to stations for processing - Station beams: Beamforming resources that process signals from tiles - Subarray beams: Higher-level beams that combine data from station beams

This attribute is useful for: - Monitoring system capacity and utilization - Diagnosing resource allocation issues - Planning observations based on available resources - Verifying the success of allocation/release operations

Returns:

A JSON-formatted string containing detailed resource information organized by resource type with allocation statistics

stationBeamHealths() → str[source]

Read the health of station beams controlled by the device.

Returns:

health of station beams in a json format

stationHealths() → str[source]

Read the health of stations controlled by the device.

Returns:

health of stations in a json format

subDeviceHealths() → str[source]

Read the health of all subdevices controlled by the device.

Returns:

health of subdevices in a json tree format

subarrayBeamHealths() → str[source]

Read the health of subarray beams controlled by the device.

Returns:

health of subarray beams in a json format

subarrayHealths() → str[source]

Read the health of subarrays controlled by the device.

Returns:

health of subarrays in a json format

useNewHealthModel(argin: bool) → None[source]

Set a flag indicating whether this controller is using the new health model.

Parameters:

argin – a flag indicating whether this controller is currently using the new health model.

versionId() → str[source]

Read the Version Id of the device.

Returns:

the version id of the device