.. _configuremid:

============
Configure
============

    1. The Subarray node provides API for **Configure workflow**.
    2. **Input JSON** is as per schema detailed at : https://developer.skao.int/projects/ska-schemas/en/latest/schemas/tmc/ska-tmc-configure.html
    3. Configure prepares already assigned mid-frequency array resources (**DISH, CSP, SDP** context) so the subarray can start scans; **success** moves the observation state to **READY**.
    4. 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**

    5. The Sub-array Node **rejects the command** if :-

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

    6. 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. **For Holography observations** -

            - Ensures each group has a supported **trajectory pattern** and valid **receptor assignments**.
            - Enforces **receptor uniqueness** across groups.
            - Requested receptors must **match** already **assigned resources**

        C. Ensures **mandatory keys** like "pointing","dish","csp","sdp","tmc" are present in json
        D. **ska-tmc-cdm** is used to **validate** the JSON

    7. The following **state requirements** are applied for the **command execution**

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

    8. The **command execution** involves below **key operations** :-

        A. **K Value Validations** are performed .K-values must be either **all same** or **all different** for all the dishes.
        B. **Input jsons are prepared** for each of the subsystems as follows -

            * **CSP preparation**
                
                #. If the configuration includes a value for **dish.band5_downconversion_subband**, that value is used to populate ["csp"]["common"]["band5_downconversion_subband"].
                #. A new string is built using the CSP device name, followed by /delayModel. This becomes the delay model subscription identifier.
                #. If the **TMC version is 4.0 or newer** and If the **CSP version is at least 0.4** :-

                    - In **common** section **subarray_id** is introduced
                    - It sets the delay model subscription point under the **midcbf** section.
                    - For each **processing** region in the **correlation** section:

                        **output_link_map** is updated to [["sdp_start_channel_id"], 1]

                #. If the **TMC version is below 4.0** :-

                    - The delay model subscription point is added under **cbf** instead
                
                #. Once Assign resource command is **completed**, **receiveAddresses** attribute gets populated from SDP Subarray node.This information is used to populate SDP visibility destinations for mid CBF
                #. If the **CSP interface version is 3.0 or older**:

                    - The **interface version** is explicitly set to **version 3.0**.
                    - For each **FSP (Frequency Slice Processor)** in the **configuration**:

                        Two settings — **zoom_factor** and **zoom_window_tuning** — are removed, because they're **not needed in older versions**.

                    - If the configuration includes a **subarray** section, **that is also removed**.

                #. When the **AssignResources** command includes a **layout data link**, the Subarray Node retrieves the layout data and stores it during execution. Later, **during the Configure command**, if this layout data is **present**, the Subarray Node extracts the relevant **dish antenna information** which is assigned to the subarray and **forwards** it to CSP under the `'layout_data'` key.

            * **SDP preparation**

                **No keys are added, removed, or renamed before sending** , only SDP section is extracted from input json and sent to SDP Leaf node.

            * **Dish preparation**

                #. If **`no`** **pointing.groups** key or **pointing.target** key specified in the JSON :-

                    All receptors (dishes) are configured using the input Dish JSON

                #. if **pointing.groups** are specified in the JSON then for each group :-

                    - if group["receptors"] is **available** use it as receptors list, **Otherwise** assigned dish resources list is used as receptors
                    - **group-specific json** is built by including **field, trajectory, projection, wrap_sector** (if present)
                    - **Final json** is created by **merging** full dish config with group-specific pointing section
                    - Configuration is sent to Dishes specified in receptors.

                #. if **partial configuration** is **enabled** :-

                    - If the scan is **mapping scan** with **trajectory** key specified :-

                        a. **pointing.groups** → removed from the json and merged into pointing
                        b. Configuration is sent to trajectory dishes.

                    - If the scan is **mapping scan** and a group of dishes doing **normal pointing/observations**:

                        a. **pointing.trajectory.attrs.x/y** → set to 0.0 
                        b. **pointing.projection** → removed
                        c. Configuration is sent to normal trajectory dishes.

                #. When the **AssignResources** command includes a **layout data link**, the Subarray Node retrieves the layout data and stores it during execution. Later, during the **Configure** command, if this layout data is **present**, the Subarray Node extracts the relevant dish antenna information and **forwards** it to the corresponding dish devices under the **'layout_data'** key.
        
        C. The command is then invoked on the relevant TMC CSP, SDP, Dish 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.

    9. 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 the TMC Subarray Node transitions to **READY** ObsState. 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/Dish Leaf node reports **'RESULT_CODE - FAILED'** on its Long Running Command Result attribute
            * The **command times out** if TMC SubarrayNode **does not transition** to **READY** within the **timeout period** specified by `CommandTimeOutDefault` property specified in helm chart of the TMC Subarray node .

    10. On **success** the system is **ready for Scan**; on **failure** it may revert to **IDLE** or **FAULT** depending on severity.