L2SS-434: Documentation update: split devices, expanded on problem with...

L2SS-434: Documentation update: split devices, expanded on problem with HOSTNAME. Expanded SDP description

docs/source/devices/boot.rst

+.. _boot:
+
+Boot
+====================
+
+The ``boot == DeviceProxy("LTS/Boot/1")`` device is responsible for (re)starting and initialising the other devices. Devices which are not reachable, for example because their docker container is explicitly stopped, are skipped during initialisation. This device provides the following commands:
+
+:initialise_station(): Stop and start the other devices in the correct order, set their default values, and command them to initialise their hardware. This procedure runs asynchronously, causing this command to return immediately. Initialisation is aborted if an error is encountered.
+
+  :returns: ``None``
+
+The initialisation process can subsequently be followed through monitoring the following attributes:
+
+:initialising_R: Whether the initialisation procedure is still ongoing.
+
+  :type: ``bool``
+
+:initialisation_progress_R: Percentage completeness of the initialisation procedure. Each succesfully configured device increments progress.
+
+  :type: ``int``
+
+:initialisation_status_R: A description of what the device is currently trying to do. If an error occurs, this will hint towards the cause.
+
+  :type: ``str``
+
+A useful pattern is thus to call ``initialise_station()``, wait for ``initialising_R == False``, and then check whether the initalisation was succesful, if ``initialisation_progress_R == 100``. If a device fails to initialise, most likely the :doc:`../interfaces/logs` will need to be consulted.

docs/source/devices/configure.rst

@@ -4,7 +4,7 @@ Device Configuration
 The devices receive their configuration from two sources:
 
 - The TangoDB database, for static *properties*,
-- Externally, from the user, or a control system, that set *control attributes* (see :doc:`devices` for what to set, and :ref:`attributes` for how to set them).
+- Externally, from the user, or a control system, that set *control attributes* (see the section for each device for what to set, and :ref:`attributes` for how to set them).
 
 .. _tangodb:
 

docs/source/devices/docker.rst

+.. _docker:
+
+Docker
+====================
+
+The ``docker == DeviceProxy("LTS/Docker/1")`` device controls the docker containers. It allows starting and stopping them, and querying whether they are running. Each container is represented by two attributes:
+
+:<container>_R: Returns whether the container is running.
+
+  :type: ``bool``
+
+:<container>_RW: Set to ``True`` to start the container, and to ``False`` to stop it.
+
+  :type: ``bool``
+
+.. warning:: Do *not* stop the ``tango`` container, as doing so cripples the Tango infrastructure, leaving the station inoperable. It is also not wise to stop the ``device_docker`` container, as doing so would render this device unreachable.
+
+

docs/source/devices/recv.rst

+RECV
+====================
+
+The ``recv == DeviceProxy("LTS/RECV/1")`` device controls the RCUs, the LBA antennas, and HBA tiles. Central to its operation are the masks (see also :ref:`attribute-masks`):
+
+:RCU_mask_RW: Controls which RCUs will actually be configured when attributes referring to RCUs are written.
+
+  :type: ``bool[N_RCUs]``
+
+:Ant_mask_RW: Controls which antennas will actually be configured when attributes referring to antennas are written.
+
+  :type: ``bool[N_RCUs][N_antennas_per_RCU]``
+
+Typically, ``N_RCUs == 32``, and ``N_antennas_per_RCU == 3``.
+

docs/source/devices/sdp.rst

+SDP
+====================
+
+The ``sdp == DeviceProxy("LTS/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`):
+
+:TR_fpga_mask_RW: Controls which FPGAs will actually be configured when attributes referring to FPGAs are written.
+
+  :type: ``bool[N_fpgas]``
+
+Typically, ``N_fpgas == 16``.
+
+See the following links for a full description of the SDP monitoring and control points:
+
+- https://support.astron.nl/confluence/pages/viewpage.action?spaceKey=L2M&title=L2+STAT+Decision%3A+SC+-+SDP+OPC-UA+interface
+- 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:
+
+:FPGA_processing_enable_R: Whether the FPGA is processing its input.
+
+  :type: ``bool[N_fpgas]``
+
+:TR_fpga_communication_error_R: Whether the FPGAs can be reached.
+
+  :type: ``bool[N_fpgas]``
+
+Data-quality information
+---------------------------
+
+The following fields describe the data quality:
+
+:FPGA_signal_input_mean_R: Mean value of the last second of input (in ADC quantisation units). Should be close to 0.
+
+  :type: ``double[N_fpgas][N_ants_per_fpga]``
+
+:FPGA_signal_input_rms_R: Root means square value of the last second of input (in ADC quantisation units). ``rms^2 = mean^2 + std^2``. Values above 2048 indicate strong RFI.
+
+  :type: ``double[N_fpgas][N_ants_per_fpga]``
+
+Version Information
+---------------------
+
+The following fields provide version information:
+
+:FPGA_firmware_version_R: The active firmware images.
+
+  :type: ``str[N_fpgas]``
+
+:FPGA_hardware_version_R: The versions of the boards hosting the FPGAs.
+
+  :type: ``str[N_fpgas]``
+
+:TR_software_version_R: The version of the server providing the OPC-UA interface.
+
+  :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:
+
+:FPGA_wg_enable_RW: Whether the waveform generator is enabled for each input.
+
+  :type: ``bool[N_fpgas][N_ants_per_fpga]``
+
+:FPGA_wg_phase_RW: The phases of the generated waves (in degrees). The generator needs to be turned off and on if this is changed, in order to bring the generators in sync.
+
+  :type: ``float32[N_fpgas][N_ants_per_fpga]``
+
+:FPGA_wg_frequency_RW: The frequencies of the generated waves (in Hz). The frequency of a subband ``s`` is LBA: ``s * 200e6/1024``, HBA low band: ``(512 + s) * 200e6/1024``, HBA high band: ``(1024 + s) * 200e6/1024``.
+
+  :type: ``float32[N_fpgas][N_ants_per_fpga]``
+
+:FPGA_wg_amplitude_RW: The amplitudes of the generated waves. Useful is a value of ``0.1``, as higher risks clipping.
+
+  :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::
+
+  # configure FPGAs to control
+  sdp.TR_fpga_mask_RW = [False] * 8 + [True] * 4 + [False] * 4
+
+  # configure waveform generator
+  sdp.FPGA_wg_phase_RW     = [[0] * 12] * 16
+  sdp.FPGA_wg_amplitude_RW = [[0.1] * 12] * 16
+  sdp.FPGA_wg_frequency_RW = [[102 * 200e6/1024] * 12] * 16
+
+  # enable waveform generator
+  sdp.FPGA_wg_enable_RW = [[True] * 12] * 16

docs/source/devices/devices.rst → docs/source/devices/sst-xst.rst

-Devices
-============
-
-.. _boot:
-
-Boot
----------
-
-The ``boot == DeviceProxy("LTS/Boot/1")`` device is responsible for (re)starting and initialising the other devices. Devices which are not reachable, for example because their docker container is explicitly stopped, are skipped during initialisation. This device provides the following commands:
-
-:initialise_station(): Stop and start the other devices in the correct order, set their default values, and command them to initialise their hardware. This procedure runs asynchronously, causing this command to return immediately. Initialisation is aborted if an error is encountered.
-
-  :returns: ``None``
-
-The initialisation process can subsequently be followed through monitoring the following attributes:
-
-:initialising_R: Whether the initialisation procedure is still ongoing.
-
-  :type: ``bool``
-
-:initialisation_progress_R: Percentage completeness of the initialisation procedure. Each succesfully configured device increments progress.
-
-  :type: ``int``
-
-:initialisation_status_R: A description of what the device is currently trying to do. If an error occurs, this will hint towards the cause.
-
-  :type: ``str``
-
-A useful pattern is thus to call ``initialise_station()``, wait for ``initialising_R == False``, and then check whether the initalisation was succesful, if ``initialisation_progress_R == 100``. If a device fails to initialise, most likely the :doc:`../interfaces/logs` will need to be consulted.
-
-.. _docker:
-
-Docker
----------
-
-The ``docker == DeviceProxy("LTS/Docker/1")`` device controls the docker containers. It allows starting and stopping them, and querying whether they are running. Each container is represented by two attributes:
-
-:<container>_R: Returns whether the container is running.
-
-  :type: ``bool``
-
-:<container>_RW: Set to ``True`` to start the container, and to ``False`` to stop it.
-
-  :type: ``bool``
-
-.. warning:: Do *not* stop the ``tango`` container, as doing so cripples the Tango infrastructure, leaving the station inoperable. It is also not wise to stop the ``device_docker`` container, as doing so would render this device unreachable.
-
-
-RECV
-----------
-
-The ``recv == DeviceProxy("LTS/RECV/1")`` device controls the RCUs, the LBA antennas, and HBA tiles. Central to its operation are the masks (see also :ref:`attribute-masks`):
-
-:RCU_mask_RW: Controls which RCUs will actually be configured when attributes referring to RCUs are written.
-
-  :type: ``bool[N_RCUs]``
-
-:Ant_mask_RW: Controls which antennas will actually be configured when attributes referring to antennas are written.
-
-  :type: ``bool[N_RCUs][N_antennas_per_RCU]``
-
-Typically, ``N_RCUs == 32``, and ``N_antennas_per_RCU == 3``.
-
-SDP
------------
-
-The ``sdp == DeviceProxy("LTS/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`):
-
-:TR_fpga_mask_RW: Controls which FPGAs will actually be configured when attributes referring to FPGAs are written.
-
-  :type: ``bool[N_fpgas]``
-
-Typically, ``N_fpgas == 16``.
-
 SST and XST
------------
+====================
 
 The ``sst == DeviceProxy("LTS/SST/1")`` and ``xst == DeviceProxy("LTS/XST/1")`` devices manages the 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.
 
@@ -82,8 +8,13 @@ The statistics are exposed in two ways, as:
 - *Attributes*, representing the most recently received values,
 - *TCP stream*, to allow the capture and recording of the statistics over any period of time.
 
+See the following links for a full description of the SST and XST monitoring and control points:
+
+- https://support.astron.nl/confluence/pages/viewpage.action?spaceKey=L2M&title=L2+STAT+Decision%3A+SC+-+SDP+OPC-UA+interface
+- https://plm.astron.nl/polarion/#/project/LOFAR2System/wiki/L2%20Interface%20Control%20Documents/SC%20to%20SDP%20ICD
+
 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:
 
@@ -106,13 +37,13 @@ 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.
 
 Complex values which cannot be represented in Tango attributes. Instead, the XST matrix is exposed as both their carthesian and polar parts:
 
-:xst_power_R, xst_phase_R: Amplitude and phase of the crosslet statistics.
+:xst_power_R, xst_phase_R: Amplitude and phase (in radians) of the crosslet statistics.
 
   :type: ``float32[N_ant][N_ant]``
 
@@ -145,8 +76,8 @@ Conversely, to calculate the block index for an antenna pair ``(a,b)``, use::
   def block_nr(a: int, b: int) -> int:
       return baseline_index(a // 12, b // 12)
 
-TCP stream
-``````````
+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:
 
@@ -176,4 +107,3 @@ The correct port will automatically be chosen, depending on the given mode. See
 The writer can also parse a statistics stream stored in a file. This allows the stream to be captured and processed independently. Capturing the stream can for example be done using ``netcat``::
 
   nc localhost 5101 > SST-packets.bin
-

docs/source/devices/using.rst

@@ -75,7 +75,7 @@ Most devices provide the following commands, in order to configure the hardware
 
 :initialise_hardware(): For devices that control hardware, this command runs the hardware initialisation procedure.
 
-Typically, ``set_defaults()`` and ``initialise_hardware()`` are called in that order in the ``STANDBY`` state. The :ref:`boot` device runs these commands as part of its station initialsation sequence.
+Typically, ``set_defaults()`` and ``initialise_hardware()`` are called in that order in the ``STANDBY`` state. See also :ref:`boot`, which provides functionality to initialise all the devices.
 
 .. _attributes:
 

docs/source/faq.rst

@@ -7,12 +7,19 @@ Connecting to devices
 My device is unreachable, but the device logs say it's running fine?
 ``````````````````````````````````````````````````````````````````````````````````````````````````````````````
 
-The ``$HOSTNAME`` may have been incorrectly guessed by ``docker-compose/Makefile``, or you accidently set it to an incorrect value. See :ref:`corba`.
+The ``$HOSTNAME`` may have been incorrectly guessed by ``docker-compose/Makefile``, or you accidently set it to an incorrect value. If you have ``$HOSTNAME`` set in the shell running ``make``, try::
+
+  unset HOSTNAME
+  make build
+  make stop
+  make start
+
+If this does not work, you need to set ``$HOSTNAME`` to something that resolves to your machine, both for external parties and for docker containers. See :ref:`corba`.
 
 I get "API_CorbaException: TRANSIENT CORBA system exception: TRANSIENT_NoUsableProfile" when trying to connect to a device?
 ````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````
 
-The ``$HOSTNAME`` may have been incorrectly guessed by ``docker-compose/Makefile``, or you accidently set it to an incorrect value. See :ref:`corba`.
+See the previous answer.
 
 Docker
 --------------------------------------------------------------------------------------------------------------

docs/source/index.rst

@@ -19,7 +19,11 @@ Even without having access to any LOFAR2.0 hardware, you can install the full st
    installation
    interfaces/overview
    devices/using
-   devices/devices
+   devices/boot
+   devices/docker
+   devices/recv
+   devices/sdp
+   devices/sst-xst
    devices/configure
    configure_station
    developer