========================
SKASubarray Tango Device
========================

    A generic subarray device for SKA.

    :class:`~ska_tango_base.subarray.subarray_device.SKASubarray` inherits from
    the :class:`~ska_tango_base.obs.obs_device.SKAObsDevice` and
    :class:`~ska_tango_base.subarray.subarray_interface.AbstractSubarrayInterface`, and
    expects a component manager to be provided by implementing the
    :meth:`~ska_tango_base.base.base_device.SKABaseDevice.create_component_manager`
    method.
    

Properties
----------
.. index::
	single: CapabilityTypes; SKASubarray.CapabilityTypes

.. py:attribute:: CapabilityTypes
	:module: SKASubarray

	Types of capability supported by this subarray.

	:data type: DevVarStringArray

.. index::
	single: GroupDefinitions; SKASubarray.GroupDefinitions

.. py:attribute:: GroupDefinitions
	:module: SKASubarray

	Each string in the list is a JSON serialised dict defining the ``group_name``, ``devices`` and ``subgroups`` in the group. A Tango Group object is created for each item in the list, according to the hierarchy defined. This provides easy access to the managed devices in bulk, or individually.

	:data type: DevVarStringArray

.. index::
	single: LoggingLevelDefault; SKASubarray.LoggingLevelDefault

.. py:attribute:: LoggingLevelDefault
	:module: SKASubarray

	Default logging level at device startup.

	:data type: DevUShort
	:default value: 4

.. index::
	single: LoggingTargetsDefault; SKASubarray.LoggingTargetsDefault

.. py:attribute:: LoggingTargetsDefault
	:module: SKASubarray

	Default logging targets at device startup.

	:data type: DevVarStringArray
	:default value: ['tango::logger']

.. index::
	single: SkaLevel; SKASubarray.SkaLevel

.. py:attribute:: SkaLevel
	:module: SKASubarray

	Indication of importance of the device in the SKA hierarchy to support drill-down navigation: 1..6, with 1 highest.

	:data type: DevShort
	:default value: 4

.. index::
	single: SubID; SKASubarray.SubID

.. py:attribute:: SubID
	:module: SKASubarray

	Unique identifier for this subarray.

	:data type: DevString

Attributes
----------
.. index::
	single: State; SKASubarray.State

.. py:attribute:: State
	:module: SKASubarray

	The operational state of the device as enumeration.

	:access: READ
	:data type: DevState
	:data format: SCALAR

.. index::
	single: Status; SKASubarray.Status

.. py:attribute:: Status
	:module: SKASubarray

	More detailed textual information about the device's status.

	:access: READ
	:data type: DevString
	:data format: SCALAR

.. index::
	single: activationTime; SKASubarray.activationTime

.. py:attribute:: activationTime
	:module: SKASubarray

	The time of activation in seconds since Unix epoch.

	:access: READ
	:data type: DevDouble
	:data format: SCALAR
	:unit: s

.. index::
	single: adminMode; SKASubarray.adminMode

.. py:attribute:: adminMode
	:module: SKASubarray

	The Admin Mode of the device.

	It may interpret the current device condition and condition of all managed devices to set this.

	:access: READ_WRITE
	:data type: DevEnum
	:data format: SCALAR

.. index::
	single: assignedResources; SKASubarray.assignedResources

.. py:attribute:: assignedResources
	:module: SKASubarray

	The resources assigned to the device.

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 512

.. index::
	single: buildState; SKASubarray.buildState

.. py:attribute:: buildState
	:module: SKASubarray

	Read the Build State of the device.

	:access: READ
	:data type: DevString
	:data format: SCALAR

.. index::
	single: commandedObsState; SKASubarray.commandedObsState

.. py:attribute:: commandedObsState
	:module: SKASubarray

	The last commanded stable Observation State of the device.

	Initial value is EMPTY.  The only stable states it can
	change to are EMPTY, IDLE, READY or ABORTED, following the start
	of any state transition command.

	:access: READ
	:data type: DevEnum
	:data format: SCALAR

.. index::
	single: commandedState; SKASubarray.commandedState

.. py:attribute:: commandedState
	:module: SKASubarray

	The last commanded Operating State of the device.

	Initial string is "None".  Only other strings it can change to is "OFF", "STANDBY" or "ON", following the Off(), Standby() or On() commands. If the state transition commands are long running commands the commanded state will only update when the long running command starts executing.

	:access: READ
	:data type: DevString
	:data format: SCALAR

.. index::
	single: configurationDelayExpected; SKASubarray.configurationDelayExpected

.. py:attribute:: configurationDelayExpected
	:module: SKASubarray

	The expected configuration delay of the device in seconds.

	:access: READ
	:data type: DevUShort
	:data format: SCALAR
	:unit: seconds

.. index::
	single: configurationProgress; SKASubarray.configurationProgress

.. py:attribute:: configurationProgress
	:module: SKASubarray

	The percentage configuration progress of the device.

	:access: READ
	:data type: DevUShort
	:data format: SCALAR
	:unit: %

.. index::
	single: configuredCapabilities; SKASubarray.configuredCapabilities

.. py:attribute:: configuredCapabilities
	:module: SKASubarray

	The configured capabilities of the device.

	For example, ["Correlators:512", "PssBeams:4", "PstBeams:4", "VlbiBeams:0"].

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 10

.. index::
	single: controlMode; SKASubarray.controlMode

.. py:attribute:: controlMode
	:module: SKASubarray

	The control mode of the device.

	A Tango Device accepts only from a 'local' client and ignores commands and queries received from TM or any other 'remote' clients. The local client has to release LOCAL control before REMOTE clients can take control again.

	:access: READ_WRITE
	:data type: DevEnum
	:data format: SCALAR

.. index::
	single: healthInfo; SKASubarray.healthInfo

.. py:attribute:: healthInfo
	:module: SKASubarray

	('Read the Health Info of the device.\n\nIt provides an explanation for the currently reported Health State',)

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 256

.. index::
	single: healthState; SKASubarray.healthState

.. py:attribute:: healthState
	:module: SKASubarray

	Read the Health State of the device.

	It interprets the current device condition and condition of all managed devices to set this.

	:access: READ
	:data type: DevEnum
	:data format: SCALAR

.. index::
	single: loggingLevel; SKASubarray.loggingLevel

.. py:attribute:: loggingLevel
	:module: SKASubarray

	Read the logging level of the device.

	Initialises to LoggingLevelDefault on startup.
	See :py:class:`~ska_control_model.LoggingLevel`

	:access: READ_WRITE
	:data type: DevEnum
	:data format: SCALAR

.. index::
	single: loggingTargets; SKASubarray.loggingTargets

.. py:attribute:: loggingTargets
	:module: SKASubarray

	Read the additional logging targets of the device.

	Note that this excludes the handlers provided by the ska_ser_logging
	library defaults - initialises to LoggingTargetsDefault on startup.

	:access: READ_WRITE
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 4

.. index::
	single: longRunningCommandIDsInQueue; SKASubarray.longRunningCommandIDsInQueue

.. py:attribute:: longRunningCommandIDsInQueue
	:module: SKASubarray

	Read the IDs of the long running commands in the queue.

	Every client that executes a command will receive a command ID as response.
	Keep track of IDs currently allocated.
	Entries are removed ``self._command_tracker._removal_time`` seconds
	after they have finished.

	**DEPRECATED**: A client can check for the queued command(s) in 'lrcQueue'.

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 32

.. index::
	single: longRunningCommandInProgress; SKASubarray.longRunningCommandInProgress

.. py:attribute:: longRunningCommandInProgress
	:module: SKASubarray

	Read the name(s) of the currently executing long running command(s).

	Name(s) of command and possible abort in progress or empty string(s).

	**DEPRECATED**: A client can check for the command(s) in progress in
	'lrcExecuting'.

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 2

.. index::
	single: longRunningCommandProgress; SKASubarray.longRunningCommandProgress

.. py:attribute:: longRunningCommandProgress
	:module: SKASubarray

	Read the progress of the currently executing long running command(s).

	ID, progress of the currently executing command(s).
	Clients can subscribe to on change event and wait
	for the ID they are interested in.

	**DEPRECATED**: A client can check the progress of command(s) in 'lrcExecuting'.

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 4

.. index::
	single: longRunningCommandResult; SKASubarray.longRunningCommandResult

.. py:attribute:: longRunningCommandResult
	:module: SKASubarray

	Read the result of the completed long running command.

	Reports unique ID and json-encoded result.
	Clients can subscribe to on change event and wait for
	the ID they are interested in.

	**DEPRECATED**: A client can check for the result of a command in 'lrcFinished'.

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 2

.. index::
	single: longRunningCommandStatus; SKASubarray.longRunningCommandStatus

.. py:attribute:: longRunningCommandStatus
	:module: SKASubarray

	Read the status of the currently executing long running commands.

	ID, status pairs of the currently executing commands.
	Clients can subscribe to on change event and wait for the
	ID they are interested in.

	**DEPRECATED**: A client can check for the status of a command in the
	'lrcQueue', 'lrcExecuting' and 'lrcFinished' attributes.

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 64

.. index::
	single: longRunningCommandsInQueue; SKASubarray.longRunningCommandsInQueue

.. py:attribute:: longRunningCommandsInQueue
	:module: SKASubarray

	Read the long running commands in the queue.

	Keep track of which commands are that are currently known about.
	Entries are removed ``self._command_tracker._removal_time`` seconds
	after they have finished.

	**DEPRECATED**: A client can check for the queued command(s) in 'lrcQueue'.

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 32

.. index::
	single: lrcExecuting; SKASubarray.lrcExecuting

.. py:attribute:: lrcExecuting
	:module: SKASubarray

	A list of info JSON blobs of the currently executing commands.

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 2

.. index::
	single: lrcFinished; SKASubarray.lrcFinished

.. py:attribute:: lrcFinished
	:module: SKASubarray

	A list of info JSON blobs of the finished long running commands.

	:access: READ
	:data type: DevString
	:data format: SPECTRUM
	:max_dim_x: 100

.. index::
	single: lrcProtocolVersions; SKASubarray.lrcProtocolVersions

.. py:attribute:: lrcProtocolVersions
	:module: SKASubarray

	Return supported protocol versions.

	:access: READ
	:data type: DevLong64
	:data format: SPECTRUM
	:max_dim_x: 2

.. index::
	single: lrcQueue; SKASubarray.lrcQueue

.. py:attribute:: lrcQueue
	:module: SKASubarray

	A list of info JSON blobs of the commands in queue.

	:access: READ
	:data type: DevString
	:data format: SPECTRUM

.. index::
	single: obsMode; SKASubarray.obsMode

.. py:attribute:: obsMode
	:module: SKASubarray

	The Observation Mode of the device.

	:access: READ
	:data type: DevEnum
	:data format: SCALAR

.. index::
	single: obsState; SKASubarray.obsState

.. py:attribute:: obsState
	:module: SKASubarray

	The Observation State of the device.

	:access: READ
	:data type: DevEnum
	:data format: SCALAR

.. index::
	single: simulationMode; SKASubarray.simulationMode

.. py:attribute:: simulationMode
	:module: SKASubarray

	When TRUE the device is using a simulator.

	:access: READ_WRITE
	:data type: DevEnum
	:data format: SCALAR

.. index::
	single: testMode; SKASubarray.testMode

.. py:attribute:: testMode
	:module: SKASubarray

	If TEST the device is using testing logic.

	:access: READ_WRITE
	:data type: DevEnum
	:data format: SCALAR

.. index::
	single: versionId; SKASubarray.versionId

.. py:attribute:: versionId
	:module: SKASubarray

	Read the Version Id of the device.

	:access: READ
	:data type: DevString
	:data format: SCALAR

Commands
--------
.. index::
	single: Abort; SKASubarray.Abort

.. py:method:: Abort() -> DevVarLongStringArray
	:module: SKASubarray

	Abort any executing long running command(s) and empty the queue.

	:returns: [ResultCode.STARTED][Command ID]

.. index::
	single: AbortCommands; SKASubarray.AbortCommands

.. py:method:: AbortCommands() -> DevVarLongStringArray
	:module: SKASubarray

	Empty out long running commands in queue.

	**DEPRECATED**: A client should call the tracked 'Abort' long running command instead.

	:returns: [ResultCode.STARTED]['Aborting commands']

.. index::
	single: AssignResources; SKASubarray.AssignResources

.. py:method:: AssignResources(DevString) -> DevVarLongStringArray
	:module: SKASubarray

	Assign resources to this subarray.

	:parameter: The resources to be assigned

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: CheckLongRunningCommandStatus; SKASubarray.CheckLongRunningCommandStatus

.. py:method:: CheckLongRunningCommandStatus(DevString) -> DevString
	:module: SKASubarray

	Check the status of a long running command by ID.

	:returns: Status of the asynchronous task.

.. index::
	single: Configure; SKASubarray.Configure

.. py:method:: Configure(DevString) -> DevVarLongStringArray
	:module: SKASubarray

	Configure the capabilities of this subarray.

	:parameter: The scan configuration specification

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: DebugDevice; SKASubarray.DebugDevice

.. py:method:: DebugDevice() -> DevUShort
	:module: SKASubarray

	Enable remote debugging of this device.

	:returns: The TCP port the debugger is listening on.

.. index::
	single: End; SKASubarray.End

.. py:method:: End() -> DevVarLongStringArray
	:module: SKASubarray

	End the scan block of this subarray.

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: EndScan; SKASubarray.EndScan

.. py:method:: EndScan() -> DevVarLongStringArray
	:module: SKASubarray

	End the current scan with this subarray.

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: GetVersionInfo; SKASubarray.GetVersionInfo

.. py:method:: GetVersionInfo() -> DevVarStringArray
	:module: SKASubarray

	Get the version information of the device.

	:returns: The device class name and its package information.

.. index::
	single: Init; SKASubarray.Init

.. py:method:: Init() -> DevVoid
	:module: SKASubarray

	Reinitialise the Tango device.

.. index::
	single: ObsReset; SKASubarray.ObsReset

.. py:method:: ObsReset() -> DevVarLongStringArray
	:module: SKASubarray

	Reset the current observation process.

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: Off; SKASubarray.Off

.. py:method:: Off() -> DevVarLongStringArray
	:module: SKASubarray

	Turn the device off.

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: On; SKASubarray.On

.. py:method:: On() -> DevVarLongStringArray
	:module: SKASubarray

	Turn the device on.

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: ReleaseAllResources; SKASubarray.ReleaseAllResources

.. py:method:: ReleaseAllResources() -> DevVarLongStringArray
	:module: SKASubarray

	Release all resources to tear down to an empty subarray.

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: ReleaseResources; SKASubarray.ReleaseResources

.. py:method:: ReleaseResources(DevString) -> DevVarLongStringArray
	:module: SKASubarray

	Delta release of assigned resources from this subarray.

	:parameter: The resources to be released

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: Reset; SKASubarray.Reset

.. py:method:: Reset() -> DevVarLongStringArray
	:module: SKASubarray

	Reset the device.

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: Restart; SKASubarray.Restart

.. py:method:: Restart() -> DevVarLongStringArray
	:module: SKASubarray

	Restart the subarray by deconfiguring and releasing all resources.

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: Scan; SKASubarray.Scan

.. py:method:: Scan(DevString) -> DevVarLongStringArray
	:module: SKASubarray

	Start scanning with this configured subarray.

	:parameter: The per-scan configuration

	:returns: [ResultCode][Status message or command ID]

.. index::
	single: Standby; SKASubarray.Standby

.. py:method:: Standby() -> DevVarLongStringArray
	:module: SKASubarray

	Put the device into standby mode.

	:returns: [ResultCode][Status message or command ID]