diff --git a/tangostationcontrol/docs/source/devices/antennafield.rst b/tangostationcontrol/docs/source/devices/antennafield.rst
index e91a3ba71ec4b417fdadc7a9183baef16e75bf31..13700c1d544b616deeafc3bfc07f468b2e608d80 100644
--- a/tangostationcontrol/docs/source/devices/antennafield.rst
+++ b/tangostationcontrol/docs/source/devices/antennafield.rst
@@ -1,4 +1,4 @@
-antennfield
-====================
+AntennaField
+--------------------
``antennafield == DeviceProxy("STAT/AntennaField/1")``
diff --git a/tangostationcontrol/docs/source/devices/beamlet.rst b/tangostationcontrol/docs/source/devices/beamlet.rst
index 39e2a588776a2e3da8adf5f030687f81492c4a45..21ad55ec0a7c1096dfd4eb1d33b122533b9ca013 100644
--- a/tangostationcontrol/docs/source/devices/beamlet.rst
+++ b/tangostationcontrol/docs/source/devices/beamlet.rst
@@ -1,5 +1,5 @@
Beamlet
-====================
+--------------------
The ``beamlet == DeviceProxy("STAT/Beamlet/1")`` device controls the creation and emission of beamlets. Each beamlet is a signal stream characterised by:
diff --git a/tangostationcontrol/docs/source/devices/bst-sst-xst.rst b/tangostationcontrol/docs/source/devices/bst-sst-xst.rst
index 90bc0df19a4bbcaea7b5b24df72b095395a88477..c319c71e9cf83fae9fc35cec51c4dfe4832a189c 100644
--- a/tangostationcontrol/docs/source/devices/bst-sst-xst.rst
+++ b/tangostationcontrol/docs/source/devices/bst-sst-xst.rst
@@ -1,5 +1,5 @@
BST, SST, and XST
-====================
+--------------------
The ``bst == DeviceProxy("STAT/BST/1")``, ``sst == DeviceProxy("STAT/SST/1")`` and ``xst == DeviceProxy("STAT/XST/1")`` devices manages the BSTs (beamlet statistics) SSTs (subband statistics) and XSTs (crosslet statistics), respectively. The statistics are emitted piece-wise through UDP packets by the FPGAs on the Uniboards in SDP. By default, each device configures the statistics to be streamed to itself (the device), from where the user can obtain them.
@@ -16,11 +16,11 @@ See the following links for a full description of the BST, SST, and XST monitori
- https://plm.astron.nl/polarion/#/project/LOFAR2System/wiki/L2%20Interface%20Control%20Documents/SC%20to%20SDP%20ICD
BST Statistics attributes
-------------------------------
+``````````````````````````````
SST Statistics attributes
-------------------------------
+``````````````````````````````
The SSTs represent the amplitude of the signal in each subband, for each antenna, as an integer value. They are exposed through the following attributes:
@@ -43,7 +43,7 @@ The SSTs represent the amplitude of the signal in each subband, for each antenna
Typically, ``N_ant == 192``, and ``N_subbands == 512``.
XST Statistics attributes
-------------------------------
+``````````````````````````````
The XSTs represent the cross-correlations between each pair of antennas, as complex values. The phases and amplitudes of the XSTs represent the phase and amplitude difference between the antennas, respectively. They are exposed as a matrix ``xst[a][b]``, of which only the triangle ``a<=b`` is filled, as the cross-correlation between antenna pairs ``(b,a)`` is equal to the complex conjugate of the cross-correlation of ``(a,b)``. The other triangle contains incidental values, but will be mostly 0.
@@ -83,7 +83,7 @@ Conversely, to calculate the block index for an antenna pair ``(a,b)``, use::
return baseline_index(a // 12, b // 12)
Configuring the XSTs
-`````````````````````````````
+"""""""""""""""""""""""""""""
The XSTs can be configured with several settings:
@@ -102,7 +102,7 @@ The XSTs can be configured with several settings:
:type: ``uint32[N_fpgas][8]``
Subscribe to statistics streams
----------------------------------
+``````````````````````````````````
The TCP stream interface allows a user to subscribe to the statistics packet streams, combined into a single TCP stream. The statistics will be streamed until the user disconnects, or the device is turned off. Any number of subscribers is supported, as bandwidth allows. Simply connect to the following port:
diff --git a/tangostationcontrol/docs/source/devices/configure.rst b/tangostationcontrol/docs/source/devices/configure.rst
index e6ed339a17c76a50c19a2e8b4b169c166759a986..0ed05a0fba41d10c9a73a91da355ddbf3f192b97 100644
--- a/tangostationcontrol/docs/source/devices/configure.rst
+++ b/tangostationcontrol/docs/source/devices/configure.rst
@@ -1,5 +1,5 @@
Device Configuration
-=========================
+-------------------------
The devices receive their configuration from two sources:
@@ -9,7 +9,7 @@ The devices receive their configuration from two sources:
.. _tangodb:
TangoDB
--------------------------
+````````````````````````````
The TangoDB database is a persistent store for the properties of each device. The properties encode static settings, such as the hardware addresses, and default values for control attributes.
diff --git a/tangostationcontrol/docs/source/devices/digitalbeam.rst b/tangostationcontrol/docs/source/devices/digitalbeam.rst
index 332e47993e3000259749e58be5840d0ae7f778ab..7f3624c7b72de285c1d4521e5c861fb992caa525 100644
--- a/tangostationcontrol/docs/source/devices/digitalbeam.rst
+++ b/tangostationcontrol/docs/source/devices/digitalbeam.rst
@@ -1,4 +1,4 @@
-digitalbeam
-====================
+DigitalBeam
+--------------------
``digitalbeam == DeviceProxy("STAT/DigitalBeam/1")``
diff --git a/tangostationcontrol/docs/source/devices/overview.rst b/tangostationcontrol/docs/source/devices/overview.rst
index c0851322d8b5b0004a437f65b09c92adc6e2fa1f..c1db108117f629507f59dc9f4ebcdf57c46e6396 100644
--- a/tangostationcontrol/docs/source/devices/overview.rst
+++ b/tangostationcontrol/docs/source/devices/overview.rst
@@ -1,4 +1,4 @@
-Overview
+Devices
=====================================
This package implements the *Station Control (SC)* part of a LOFAR2.0 station, the core of which implements several Tango devices that connect to the station's hardware as well as to each other. In the following graph, green components are implemented in this package, the gray components are external:
diff --git a/tangostationcontrol/docs/source/devices/psoc.rst b/tangostationcontrol/docs/source/devices/psoc.rst
index bccb7b0d487aec270be78393625da2d00c1d1b24..c3265005fd41bdd9dca078b0fe1d60860a4e848e 100644
--- a/tangostationcontrol/docs/source/devices/psoc.rst
+++ b/tangostationcontrol/docs/source/devices/psoc.rst
@@ -1,7 +1,6 @@
.. _psoc:
PSOC
-====================
+--------------------
-The ``psoc == DeviceProxy("STAT/PSOC/1")`` device controls the Power Distribution
-Unit (PSOC)
+The ``psoc == DeviceProxy("STAT/PSOC/1")`` device controls the Power Distribution Unit (PSOC).
diff --git a/tangostationcontrol/docs/source/devices/recv.rst b/tangostationcontrol/docs/source/devices/recv.rst
index aaa5dd91435647b9e02700975f764e804167efe7..3bf2e1ba090b96c1cd49b77708f127de0c60c259 100644
--- a/tangostationcontrol/docs/source/devices/recv.rst
+++ b/tangostationcontrol/docs/source/devices/recv.rst
@@ -1,5 +1,5 @@
RECV
-====================
+---------------------
The ``recv == DeviceProxy("STAT/RECV/1")`` device controls the RCUs, the LBA antennas, and HBA tiles. Central to its operation are the masks (see also :ref:`attribute-masks`):
@@ -14,7 +14,7 @@ The ``recv == DeviceProxy("STAT/RECV/1")`` device controls the RCUs, the LBA ant
Typically, ``N_RCUs == 32``, and ``N_antennas_per_RCU == 3``.
Error information
----------------------
+`````````````````````
These attributes summarise the basic state of the device. Any elements which are not present in ``FPGA_mask_RW`` will be ignored and thus not report errors:
diff --git a/tangostationcontrol/docs/source/devices/sdp.rst b/tangostationcontrol/docs/source/devices/sdp.rst
index 6386dd851b178ce44b0b1b53968ba0f219fe5140..8b2cadda2ee6b3a7403d954091e8ce1548eaa90c 100644
--- a/tangostationcontrol/docs/source/devices/sdp.rst
+++ b/tangostationcontrol/docs/source/devices/sdp.rst
@@ -1,5 +1,5 @@
SDP
-====================
+---------------------
The ``sdp == DeviceProxy("STAT/SDP/1")``` device controls the digital signal processing in SDP, performed by the firmware on the FPGAs on the Uniboards. Central to its operation is the mask (see also :ref:`attribute-masks`):
@@ -15,7 +15,7 @@ See the following links for a full description of the SDP monitoring and control
- https://plm.astron.nl/polarion/#/project/LOFAR2System/wiki/L2%20Interface%20Control%20Documents/SC%20to%20SDP%20ICD
Basic configuration
----------------------
+`````````````````````
The following points are significant for the operations of this device:
@@ -28,7 +28,7 @@ The following points are significant for the operations of this device:
:type: ``bool[N_fpgas]``
Data-quality information
----------------------------
+```````````````````````````
The following fields describe the data quality (see also :doc:`../signal_chain`):
@@ -41,7 +41,7 @@ The following fields describe the data quality (see also :doc:`../signal_chain`)
:type: ``double[N_fpgas][N_ants_per_fpga]``
Error information
----------------------
+```````````````````````````
These attributes summarise the basic state of the device. Any elements which are not present in ``FPGA_mask_RW`` will be ignored and thus not report errors:
@@ -54,7 +54,7 @@ These attributes summarise the basic state of the device. Any elements which are
:type: ``bool[N_fpgas]``
Version Information
----------------------
+```````````````````````````
The following fields provide version information:
@@ -71,7 +71,7 @@ The following fields provide version information:
:type: ``str[N_fpgas]``
Waveform Generator
----------------------
+```````````````````````````
The antenna input of SDP can be replaced by an internal waveform generator for debugging and testing purposes. The generator is configured per antenna per FPGA:
@@ -94,7 +94,7 @@ The antenna input of SDP can be replaced by an internal waveform generator for d
:type: ``float32[N_fpgas][N_ants_per_fpga]``
Usage example
-```````````````````````
+"""""""""""""""""""""""
For example, the following code inserts a wave on LBA subband 102 on FPGAs 8 - 11::
diff --git a/tangostationcontrol/docs/source/devices/temperature-manager.rst b/tangostationcontrol/docs/source/devices/temperature-manager.rst
index c4f919377d5fbcb79338b0ea28e24c4cbf35c975..2228aa38ae58fbd353443e037abaca67cea1881a 100644
--- a/tangostationcontrol/docs/source/devices/temperature-manager.rst
+++ b/tangostationcontrol/docs/source/devices/temperature-manager.rst
@@ -1,4 +1,4 @@
-temperature-manager
-====================
+TemperatureManager
+--------------------
``temperature_manager == DeviceProxy("STAT/TemperatureManager/1")``
diff --git a/tangostationcontrol/docs/source/devices/tilebeam.rst b/tangostationcontrol/docs/source/devices/tilebeam.rst
index 1df29562f605039cad0f77ad284b1f0d3b562f0b..dfa2372e56051b8f46be1079f3c2c89ec5f85f08 100644
--- a/tangostationcontrol/docs/source/devices/tilebeam.rst
+++ b/tangostationcontrol/docs/source/devices/tilebeam.rst
@@ -1,10 +1,10 @@
-Beam
-====================
+TileBeam
+--------------------
The ``tilebeam == DeviceProxy("STAT/TileBeam/1")`` device sets up the beamforming on the station. It configures the HBA tile beam former, which adds the signals of its 16 elements within the tile. These element signals can be delayed a configurable amount of time, allowing their sum to become more sensitive in a certain direction. Each tile can have their own pointing direction configured.
Beam Tracking
---------------------
+````````````````````
Beam tracking automatically recomputes and reapplies pointings periodically, and immediately when new pointings are configured. It exposes the following interface:
@@ -25,7 +25,7 @@ Beam tracking automatically recomputes and reapplies pointings periodically, and
:type: ``float[N_ant][3]``
Beam Steering
---------------------
+````````````````````
The beam steering is responsible for pointing the beams at a target, by converting pointings to ``recv.HBAT_bf_delay_steps``. The beam steering is typically controlled by the beam tracker. To point the antennas in any direction manually, you should disable beam tracking first:
@@ -38,14 +38,14 @@ The beam steering is responsible for pointing the beams at a target, by converti
:returns: ``None``
Computation Parameters
------------------------
+```````````````````````
To form a beam from a set of antennas in a certain direction, the signals coming from each antenna needs to be aligned, such that signals coming from that direction become coherent. In tile beam forming, this is accomplished by proportionally delaying the signals from the antennas that are closer to the target.
To compute the required delays, both the direction of the source and the position of the antennas are required. Furthermore, a *reference position* is used, a virtual position towards which the antenna signals are aligned. The reference position is typically in the center of the set of antennas.
HBA positions
-```````````````````````
+"""""""""""""""""""""""
For the tile beam, these positions are stored as follows in the ``recv`` device:
@@ -60,12 +60,12 @@ For the tile beam, these positions are stored as follows in the ``recv`` device:
NB: A LOFAR antenna field is constructed such that all tiles lie within the same plane, instead of following the curvature of the Earth. This means that the relative offsets of the elements with an HBA tile in ITRF is the same for every tile in the antenna field.
HBA delays
-```````````````````````
+"""""""""""""""""""""""
Each HBA tile is steered by configuring the number of *delay steps* to introduce for each element.
Direction information
-```````````````````````
+"""""""""""""""""""""""
We use `python-casacore <https://casacore.github.io/python-casacore/index.html>`_ to compute the direction of a given pointing with respect to our antennas and reference positions. Casacore in turn uses *measures* tables for the precise measurements of celestial positions, geodetical information, and time calibrations (f.e. leap seconds). These tables need to be installed and periodically updated to maintain the pointing accuracy:
diff --git a/tangostationcontrol/docs/source/devices/using.rst b/tangostationcontrol/docs/source/devices/using.rst
index 6eff9278eb74fc06a66b0d5b90f09d4f58eb0008..96881178bfa260acd182397ff4fd80a0794e3763 100644
--- a/tangostationcontrol/docs/source/devices/using.rst
+++ b/tangostationcontrol/docs/source/devices/using.rst
@@ -1,5 +1,5 @@
Using Devices
-=============
+----------------
The station exposes *devices*, each of which is a remote software object that manages part of the station. Each device has the following properties:
@@ -13,7 +13,7 @@ The station exposes *devices*, each of which is a remote software object that ma
The devices are accessed remotely using ``DeviceProxy`` objects. See :doc:`../interfaces/control` on how to do this.
States
-------------
+````````````````
The state of a device is then queried with ``device.state()``. Each device can be in one of the following states:
@@ -115,7 +115,7 @@ See also :ref:`boot`, which provides functionality to initialise all the devices
.. _attributes:
Attributes
-------------
+````````````````
The device can be operated in ``ON`` state, where it exposes *attributes* and *commands*. The attributes can be accessed as python properties, for example::
@@ -133,7 +133,7 @@ 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. Reading them returns the last requested value.
Meta data
-`````````````
+"""""""""""""""""""""
A description of the attribute can be retrieved using::
@@ -142,7 +142,7 @@ A description of the attribute can be retrieved using::
.. _attribute-masks:
Attribute masks
----------------------
+````````````````
Several devices employ *attribute masks* in order to toggle which elements in their hardware array are actually to be controlled. This construct is necessary as most control points consist of arrays of values that cover all hardware elements. These array control points are always fully sent: it is not possible to update only a single element without uploading the rest. Without a mask, it is impossible to control a subset of the hardware.