Overview
========

The ``RcalEmulatorDevice`` is a Tango Device designed to provide real-time calibration (RCal)
emulator for the Square Kilometre Array (SKA) LOW CBF testing purpose.

It emulates the generation of Jones calibration matrices for multiple beams, stations,
and frequencies, and streams the results with associated metadata.

This device supports configuration of calibration parameters, execution of the
calibration emulator, and integration with Kafka for data transport.


Attributes
==========

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - Attribute Name
     - Type
     - Description
   * - ``kafka_address``
     - String
     - URL and port number of the Kafka server to which calibration data is sent.
   * - ``list_of_frequencies``
     - Array[int]
     - List of SPS frequencies used during calibration. Configurable via ``configure_rcal``.
   * - ``list_of_stations``
     - Array[String]
     - List of stations/substations included in calibration. Configurable via ``configure_rcal``.
   * - ``rotate_degrees``
     - Float
     - Rotation angle (in degrees) applied to both X and Y polarisations.
   * - ``list_of_beams``
     - Array[Int]
     - List of PST beams to be calibrated. Configurable via ``configure_rcal``.
   * - ``updating_period``
     - Float
     - Period (in seconds) at which calibration matrices are generated and sent.
   * - ``max_message``
     - Integer
     - Max Message size proxy where Kafka message_max_bytes=max_message * 2^20.


Commands
========

configure_rcal
--------------

**Input:** JSON string

**Output:** Tango Result → *Ok if configuration done, else FAILED.*

**Description:**

Configures the lists of SPS frequencies, stations, and PST beams.

**Example JSON:**

.. code-block:: json

   {
       "frequencies": [64, 65],
       "stations": ["1/1", "2/1"],
       "beams": [1, 2]
   }


start_calibration
-----------------

**Input:** Topic name

**Output:** Tango Result

**Description:**

Starts the calibration emulator. Once started, the device will generate and send
Jones matrices every ``updating_period`` seconds.

**Workflow:**

1. Prepare one Jones matrix per beam:

   - If ``cal_count % 2 == 0`` → use unity matrix.
   - Else → apply rotation matrix with ``rotate_degrees``.

2. Attach metadata to the calibration data.
3. Send calibration results to Kafka as an ``xarray.DataArray``.


stop_calibration
----------------

**Input:** None

**Output:** Tango Result

**Description:**

Stops the calibration process. Allow for one full updating period before restarting.


Data Format
===========

The calibration results are sent as an ``xarray.DataArray`` object:

.. code-block:: python

   xarray_to_return = xarray.DataArray(
       data,
       coords={
           "antenna": list_of_stations,
           "frequency": list_of_frequencies,
           "polarisation": polarisations.split(","),  # e.g., ["XX", "XY", "YX", "YY"]
       },
       attrs={
           "cal_interval_start": interval_start_time,
           "cal_interval_end": interval_end_time,
           "cal_count": count,
       },
   )

- ``data`` contains the generated Jones matrices.
- ``coords`` provide mapping to beams, stations, frequencies, and polarisations.
- ``attrs`` carry timing and counter metadata for traceability.


Example Workflow
================

1. **Configure the device:**

   .. code-block:: python

      json_config = '{"frequencies": [64, 65], "stations": ["1/1", "2/1"], "beams": [1, 2]}'
      rcal = tango.DeviceProxy(f"{TANGO_DB_HOST}/low-cbf/rcal/0")
      rcal.configure_rcal(json_config)

2. **Adjust attributes if necessary:**

   .. code-block:: python

      rcal.rotate_degrees = 45.0
      rcal.kafka_address = "test-kafka.rcal-jou008.svc.cluster.local:9092"
      rcal.updating_period = 10.0

3. **Start calibration:**

   .. code-block:: python

      rcal.start_calibration("my-topic")

4. **Receive results:**

   Jones matrices are received every ``updating_period`` seconds in the Kafka stream.