.. _scanlow:

=======
Scan
=======

1. The Subarray node provides API for **Scan workflow**.
2. Input JSON is as per schema detailed at : https://developer.skao.int/projects/ska-schemas/en/latest/schemas/tmc/ska-low-tmc-scan.html
3. The Sub-array node **accepts the command** if :-

    A. Admin mode reported by each of the system - CSP,SDP subarray are in **ONLINE/ENGINEERING/RESERVED**
    B. Operational state of the Sub-array node is **ON/OFF/INIT/STANDBY/ALARM**

4. The Sub-array Node **rejects the command** if-

    A. Admin mode reported by each of the system - CSP,SDP Sub-array are in **OFFLINE** or **NOT FITTED**.
    B. Operational state of central node is **FAULT/UNKNOWN/DISABLE** .

5. The Input JSON is validated as below, and Command is `'Rejected'` with **exception message if they are not met** :-

    A. JSON should not be empty or malformed
    B. JSON validation against the schema specified in the Telescope Model ( https://developer.skao.int/projects/ska-schemas/en/latest/schemas/tmc/ska-low-tmc-scan.html)

6. The following **state requirements** are applied for the **command execution** :-

    A. TMC Subarray is in `'observation state'` **READY** .
    B. :term:`isSubarrayAvailable` is checked to ensure the subsystems (CSP, SDP and MCCS) are :term:`available`

7. The command execution involves below key operations

    A. Below updates are done in each of the interface before sending JSON to each of the interface.
        + **MCCS updates**

            a. MCCS Scan Interface details are added  
            b. subarray_id,transaction_id and is deleted before sending Json  

        + **CSP updates**

            a. TMC-CSP Scan Interface details are updated.
            b. subarray id is introduced
            c. lowcbf.scan_id is populated
   
        + **SDP Updates**

            SDP Scan Interface details are updated.

    B. The command is then invoked on the relevant TMC CSP, SDP, MCCS leaf Nodes.

        + If leaf node rejects configure command , command failure is reported as **'RESULT_CODE - FAILED'** on Long Running Command Result attribute of the TMC Subarry node.Command will not be sent to remaining subsystems in this case if multiple subsystems are involved .
        + If all leaf node accept command , the TMC Subarry node will wait for command completion.
        + Scan timer is started using the stored scan duration .The scan timer will later trigger automatic termination (EndScan) once timer is over.

8. The Sub-array node monitors the progress of command via the Sub-array node ObsState transitions and the long running command results.

    A. Command is successful when all 3 leaf nodes send **'RESULT_CODE - OK'** on Long Running Command Result attribute of respective leaf nodes.This is reported as **'RESULT_CODE - OK'** on Long Running Command Result attribute of the Subarray node.
    B. Command failure is reported in any of the below cases as **'RESULT_CODE - FAILED'** on Long Running Command Result attribute of the Subarray node.
        
        + The CSP Leaf node/SDP Leaf node/MCCS Leaf node reports **'RESULT_CODE - FAILED'** on its Long Running Command Result attribute
        + The command times out if TMC SubarrayNode does not get **'RESULT_CODE - OK'** from all 3 subsystems within the timeout period specified by `CommandTimeOutDefault` property specified in helm chart of the TMC Subarry Node .

9. On success the system is performing scanning observation; on failure it may revert to **READY** or **FAULT** depending on severity.