From e0053c7bda752af30876fa062a85638ef84d4e8b Mon Sep 17 00:00:00 2001
From: Jan David Mol <mol@astron.nl>
Date: Thu, 7 Oct 2021 18:56:02 +0200
Subject: [PATCH] L2SS-434: Improved XST and device descriptions

---
 docs/source/devices/devices.rst | 29 ++++++++++++++---------------
 docs/source/devices/using.rst   |  9 +++++++--
 2 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/docs/source/devices/devices.rst b/docs/source/devices/devices.rst
index dfe7f011e..588ce3245 100644
--- a/docs/source/devices/devices.rst
+++ b/docs/source/devices/devices.rst
@@ -59,14 +59,6 @@ Complex values which cannot be represented in Tango attributes. Instead, the XST
 
   :type: ``float32[N_ant][N_ant]``
 
-:xst_blocks_R: Blocks of crosslet statistics, as received from the FPGA (see below).
-
-  :type: ``int64[N_blocks][block_size]``
-
-:xst_conjugated_R: Whether the block contains conjugated data. If so, it must be conjugated again on interpretation.
-
-  :type: ``bool[N_blocks]``
-
 :xst_timestamp_R: Timestamp of each block.
 
   :type: ``int64[N_blocks]``
@@ -75,9 +67,9 @@ Complex values which cannot be represented in Tango attributes. Instead, the XST
 
   :type: ``float32[N_blocks]``
 
-Typically, ``N_ant == 192``.
+Typically, ``N_ant == 192``, and ``N_blocks == 136``.
 
-The metadata refers to the *blocks*, which are emitted by the FPGAs to represent the XSTs between 12 x 12 antennas. The following code converts block numbers to the indices of the first antenna pair in a block::
+The metadata refers to the *blocks*, which are emitted by the FPGAs to represent the XSTs between 12 x 12 consecutive antennas. The following code converts block numbers to the indices of the first antenna pair in a block::
 
   from common.baselines import baseline_from_index
 
@@ -90,9 +82,7 @@ Conversely, to calculate the block index for an antenna pair ``(a,b)``, use::
   from common.baselines import baseline_index
 
   def block_nr(a: int, b: int) -> int:
-      return baseline_index(a / 12, b / 12)
-
-The ``block_size`` is equal to the number of antennas, times two for the real and imaginary parts (stored consecutively), so ``12*12*2``.
+      return baseline_index(a // 12, b // 12)
 
 TCP stream
 ``````````
@@ -118,8 +108,8 @@ The writer can also parse a statistics stream stored in a file, so the stream ca
 
   nc localhost 5101 > SST-packets.bin
 
-Performance monitoring
-`````````````````````````
+Performance monitoring and debugging
+`````````````````````````````````````
 
 All statistics expose attributes that provide general statistics about the data received. The counters are set to 0 when the device is initialised:
 
@@ -158,3 +148,12 @@ Note that nominally::
                          + sum(nof_payload_errors_R)
                          + sum(nof_valid_payloads_R)
 
+The XSTs also expose the raw blocks as they were received from the FPGAs:
+
+:xst_blocks_R: Blocks of crosslet statistics, as received from the FPGA (see below). Each block is easier to interpret after a ``.reshape((12,12,2))``, representing the first & second antenna within the block, and the real/imaginary components.
+
+  :type: ``int64[N_blocks][block_size]``
+
+:xst_conjugated_R: Whether the corresponding block contains conjugated data. If so, it must be conjugated again on interpretation.
+
+  :type: ``bool[N_blocks]``
diff --git a/docs/source/devices/using.rst b/docs/source/devices/using.rst
index afc753773..f170135f4 100644
--- a/docs/source/devices/using.rst
+++ b/docs/source/devices/using.rst
@@ -11,7 +11,9 @@ The station exposes *devices*, each of which is a remote software object that ma
 
 To access a device, one creates a ``Device`` object. For example::
 
-    device = Device("LTS/RECV/1")
+    recv = Device("LTS/RECV/1")
+
+See :doc:`control` on how and where to execute this code.
 
 States
 ------------
@@ -44,4 +46,7 @@ The device can be operated in ``ON`` state, where it exposes *attributes* and *c
     # retrieve the status of all LED0s
     print(recv.RCU_LED0_R)
 
-The attributes with an ``_R`` suffix are monitoring points, reflecting the state of the hardware, and are thus read-only. The attributes with an ``_RW`` suffix are control points, reflecting the desired state of the hardware. They are read-write, where writing requests the hardware to set the specified value, and reading returns the last requested value.
+The attributes with an:
+
+- ``_R`` suffix are monitoring points, reflecting the state of the hardware, and are thus read-only.
+- ``_RW`` suffix are control points, reflecting the desired state of the hardware. They are read-write, where writing requests the hardware to set the specified value. Reading them returns the last requested value.
-- 
GitLab