diff --git a/CDB/stations/DTS_Outside_ConfigDb.json b/CDB/stations/DTS_Outside_ConfigDb.json
index e5a9ad8da17392ad8869e93edad0e0d823353999..fab3e930cfb239c74d0d59e9d0a6a4a401504d70 100644
--- a/CDB/stations/DTS_Outside_ConfigDb.json
+++ b/CDB/stations/DTS_Outside_ConfigDb.json
@@ -151,18 +151,18 @@
"STAT/RECV/1"
],
"HBAT_Control_to_RECV_mapping": [
- "1", "24",
+ "1", "27",
"0", "-1",
"0", "-1",
- "1", "25",
- "1", "26"
+ "1", "28",
+ "1", "29"
],
"HBAT_Power_to_RECV_mapping": [
- "1", "27",
+ "1", "24",
"0", "-1",
"0", "-1",
- "1", "28",
- "1", "29"
+ "1", "25",
+ "1", "26"
],
"Antenna_Field_Reference_ETRS": [
"3839371.416", "430339.901", "5057958.886"
diff --git a/tangostationcontrol/docs/source/beam_tracking.rst b/tangostationcontrol/docs/source/beam_tracking.rst
deleted file mode 100644
index a9860420af79ffa6ddc9e348abfb122911a8efc9..0000000000000000000000000000000000000000
--- a/tangostationcontrol/docs/source/beam_tracking.rst
+++ /dev/null
@@ -1,85 +0,0 @@
-Beam Tracking
-====================
-
-A primary function of the station is to combine its antenna signals to create a more sensitive signal. The antennas are typically aimed at celestial sources moving across the sky, but can also be aimed at stationary targets, for example to point at Earth-bound signals or to let the sky pass through the beam instead.
-
-Given a certain direction, and knowing the speed of light, one can compute the differences in arrival time for light from the observed source (its wave front) towards each antenna. The antenna signals are then aligned towards the source by delaying the signal inputs based on these differences. The antennas closest to the source get the largest delay. For celestial sources, the light is assumed to be infinitely far away and thus travel in parallel towards each antenna, greatly simplifying the calculations involved.
-
-In practice, antenna signals can only be coarsely delayed. Fine delay compensation consists of rotating the signal inputs to compensate for the remaining differences in phase. The amount of rotation is frequency dependent. The aligned signals are subsequently added, creating a single signal output of higher sensitivity towards the observed source, albeit with a narrower field of view.
-
-Beam tracking therefor requires the *pointing* direction in which to observe, as well as the *positions* of the antennas involved. Finally, the antennas need to be periodically realigned to track moving sources.
-
-Terminology
---------------------
-
-We distinguish the following concepts:
-
-- *Beam forming* is combining individual element signals into one. This is performed by the HBAT hardware and SDP firmware,
-- *Beam steering* is uploading the delays or weights to the beam-forming hardware, in order to point the beam in a certain direction,
-- *Beam tracking* is updating the beam steering over time to track a celestial target, compensating for the Earth's movement through space.
-
-Pointing
---------------------
-
-A *pointing* describes the direction in the sky, and consists of a set of coordinates and the relevant coordinate system. They are represented as a tuple of 3 strings: ``("coordinate_system", "angle1", "angle2")``, where the interpretation of ``angle1`` and ``angle2`` depends on the coordinate system used. For example:
-
-- ``("AZELGEO", "0deg", "90deg")`` points at Zenith (Elevation = 90°, with respect to the Earth geode),
-- ``("J2000", "0deg", "90deg")`` points at the North Celestial Pole (Declination = 90°),
-- ``("SUN", "0deg", "0deg")`` points at the centre of the Sun.
-
-For a full list of the supported coordinate systems, see https://casacore.github.io/casacore/classcasacore_1_1MDirection.html
-
-Coordinates in a celestial coordinate system result in a different direction depending on the time. Each pointing is associated with a *timestamp* for when it was or is to be applied. When not specified, ``datetime.datime.now()`` is used.
-
-Positions
---------------------
-
-The positions of the antennas are required in ITRF, a carthesian geocentric coordinate system ("XYZ" with its origin at the center of the Earth). These coordinates provide an absolute 3D position on Earth and form the basis for most delay computations. These positions are not stationary however, due to the tectonic plate movement. Instead, we use source coordinates in ETRS89 (also carthesian geocentric), and convert those to ITRF using updated and extrapolated tectonic models (see ``tangostationcontrol.tilebeam.geo.ETRS_to_ITRF``).
-
-:recv.HBAT_reference_ETRS: (property) The reference position of each HBA tile, in ETRS89.
-
- :type: ``float[96][3]``
-
-:recv.ITRF_Reference_Frame: (property) The ITRF system to convert coordinates to (default: ITRF2005).
-
- :type: ``str``
-
-:recv.ITRF_Reference_Epoch: (property) The year to extrapolate the ITRF system to (typically half-year increments, such as 2015.5).
-
- :type: ``float``
-
-:recv.HBA_reference_ITRF_R: The computed refence positions of each HBA tile, in ITRF.
-
- :type: ``float[96][3]``
-
-NB: It is also possible to explicitly specify ITRF positions in the ``recv.HBAT_reference_ITRF`` property to side step the calculations based on ETRS.
-
-HBAT element positions
-````````````````````````
-
-The positions of the elements within an HBA tile are handled differently. Instead of storing the positions of each of the 16 elements in each tile, we use the fact that the relative positions of the elements within each tile is fixed, and that in LOFAR stations, all the HBA tiles of a station are on the same plane (instead of following the curvature of the Earth). This plane is given its own station-local coordinates, the PQR system:
-
-- It's origin is at a chosen center of the station,
-- The Q axis is aligned with an absolute North (not the North of the station, which would be a different direction per station),
-- The P axis is roughly East,
-- The R axis is roughly down,
-- The HBA tiles on a station all lie on the same PQ plane, so R == 0.
-
-These facts allow us to use the following information to calculate the absolute position of each tile element. The conversion takes the relative offsets of the elements within a tile, rotates them in PQR space, rotates those into relative ETRS offsets, and finally into absolute positions in ETRS. See ``tangostationcontrol.tilebeam.hba_tile`` for these computations.
-
-:recv.HBAT_base_antenna_offsets: (property) The relative offsets of each element within a tile, with respect to the tile's reference position (the center of the ground plane).
-
- :type: ``float[16][3]``
-
-:recv.HBAT_PQR_rotation_angles_deg: (property) The horizontal rotation of each HBA tile in the PQ plane, in degrees (Q -> P).
-
- :type: ``float[96]``
-
-:recv.HBAT_PQR_to_ETRS_rotation_matrix: (property) The 3D rotation matrix to convert PQR coordinates into relative ETRS coordinates.
-
- :type: ``float[3][3]``
-
-:recv.HBAT_reference_ETRS: (property) The absolute reference position of each HBA tile, in ETRS89.
-
- :type: ``float[96][3]``
-
diff --git a/tangostationcontrol/docs/source/devices/antennafield.rst b/tangostationcontrol/docs/source/devices/antennafield.rst
index e91a3ba71ec4b417fdadc7a9183baef16e75bf31..d9c36a0148fab3b74b8cf1311b0d8c4369686da9 100644
--- a/tangostationcontrol/docs/source/devices/antennafield.rst
+++ b/tangostationcontrol/docs/source/devices/antennafield.rst
@@ -1,4 +1,99 @@
-antennfield
-====================
+AntennaField
+--------------------
+
+The ``antennafield == DeviceProxy("STAT/AntennaField/1")`` device represents a set of *antennas* or *tiles* that collectively form an antenna field. It represents a selection of inputs from one or more ``RECV`` devices, annotated with metadata such as positional information.
+
+:nr_tiles_R: The number of antennas or tiles in the antenna field.
+
+ :type: ``uint32``
+
+It provides many settings that map onto the ``RECV`` device directly, serving as a funnel:
+
+:HBAT_ANT_mask_RW: Which antennas are configured when writing settings.
+
+ :type: ``bool[N_tiles]``
+
+.. warning:: Any antennas in the field that are not connected to any ``RECV`` device will return default values (f.e. ``False`` or ``0``).
+
+Positions
+````````````````````
+
+The following attributes expose positional information about the individual antennas in the field, in different formats:
+
+:HBAT_reference_GEO_R: Reference position of each HBA tile, in latitude/longitude (degrees).
+
+ :type: ``float64[N_tiles][2]``
+
+:Antenna_Field_Reference_GEO_R: Reference position of the antenna field, in latitude/longitude (degrees).
+
+ :type: ``float64[2]``
+
+Additionally, the ``ITRF`` and ``GEOHASH`` variants provide the same information, but in ITRF (x/y/z, metres), and in Geohash strings, respectively.
+
+Also, the offsets of the elements within each HBA tile are provided:
+
+:HBAT_antenna_ITRF_offsets_R: Relative position of each HBA tile element with respect to the tile reference.
+
+ :type: ``float64[N_tiles][N_elements * 3]``
+ :shape: ``float64[N_tiles][N_elements][3]``
+
+Configuration
+````````````````````
+
+The antennas represented by the antenna field are selected by the following properties:
+
+:RECV_devices: The list of ``RECV`` devices from which antennas are selected.
+
+ :type: ``str[]``
+
+:HBAT_Power_to_RECV_mapping: Pairs of numbers ``(recv_idx, ant_idx)`` describing the inputs on which the HBAT *power* is connected. The ``recv_idx`` is the index in ``RECV_devices``, starting at 1. The ``ant_idx`` is the absolute index of the antenna in the ``RECV`` device. A value of ``-1`` means the antenna is not connected at all.
+
+ :type: ``int32[]``
+ :shape: ``int32[][2]``
+
+:HBAT_Control_to_RECV_mapping: Pairs of numbers ``(recv_idx, ant_idx)`` describing the inputs on which the HBAT *control* is connected. The ``recv_idx`` is the index in ``RECV_devices``, starting at 1. The ``ant_idx`` is the absolute index of the antenna in the ``RECV`` device. A value of ``-1`` means the antenna is not connected at all.
+
+Positions
+""""""""""""""""""""
+
+The positions are given in ETRS, using the following properties:
+
+:HBAT_reference_ETRS: Reference position of each HBA tile, in ETRS (x/y/z, metres).
+
+ :type: ``float64[N_tiles][3]``
+
+:Antenna_Field_Reference_ETRS: Reference position of the antenna field, in ETRS (x/y/z, metres).
+
+ :type: ``float64[3]``
+
+:ITRF_Reference_Frame: Reference frame to use for converting ETRS to ITRF (f.e. "ITRF2005").
+
+ :type: ``str``
+
+:ITRF_Reference_Epoch: Epoch towards which to extrapolate the ITRF frame, typically in half-year increments (f.e. 2015.5).
+
+ :type: ``float32``
+
+For the ETRS positions, there is an alternative to provide them using the respective ``ITRF`` property, which overrides the automatic ETRS-to-ITRF conversion.
+
+HBAT element positions
+````````````````````````
+
+The positions of the elements within an HBA tile are handled differently. Instead of storing the positions of each of the 16 elements in each tile, we use the fact that the relative positions of the elements within each tile is fixed, and that in LOFAR stations, all the HBA tiles of a station are on the same plane (instead of following the curvature of the Earth). This plane is given its own station-local coordinates, the PQR system:
+
+- It's origin is at a chosen center of the station,
+- The Q axis is aligned with an absolute North (not the North of the station, which would be a different direction per station),
+- The P axis is roughly East,
+- The R axis is roughly down,
+- The HBA tiles on a station all lie on the same PQ plane, so R == 0.
+
+These facts allow us to use the following information to calculate the absolute position of each tile element. The conversion takes the relative offsets of the elements within a tile, rotates them in PQR space, rotates those into relative ETRS offsets, and finally into absolute positions in ETRS. See ``tangostationcontrol.tilebeam.hba_tile`` for these computations.
+
+:recv.HBAT_PQR_rotation_angles_deg: (property) The horizontal rotation of each HBA tile in the PQ plane, in degrees (Q -> P).
+
+ :type: ``float[96]``
+
+:recv.HBAT_PQR_to_ETRS_rotation_matrix: (property) The 3D rotation matrix to convert PQR coordinates into relative ETRS coordinates.
+
+ :type: ``float[3][3]``
-``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
deleted file mode 100644
index 332e47993e3000259749e58be5840d0ae7f778ab..0000000000000000000000000000000000000000
--- a/tangostationcontrol/docs/source/devices/digitalbeam.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-digitalbeam
-====================
-
-``digitalbeam == DeviceProxy("STAT/DigitalBeam/1")``
diff --git a/tangostationcontrol/docs/source/devices/overview.rst b/tangostationcontrol/docs/source/devices/overview.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c1db108117f629507f59dc9f4ebcdf57c46e6396
--- /dev/null
+++ b/tangostationcontrol/docs/source/devices/overview.rst
@@ -0,0 +1,103 @@
+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:
+
+.. graphviz::
+
+ digraph logical_layout {
+ fontname="Helvetica,Arial,sans-serif"
+ node [fontname="Helvetica,Arial,sans-serif" fontsize="20pt" style=filled]
+ edge [fontname="Helvetica,Arial,sans-serif" fontsize="20pt"]
+
+ subgraph clusterSC {
+ label = "SC";
+
+ node [shape=ellipse color=aquamarine];
+
+ ObservationControl -> Observation;
+ Observation -> SDP;
+ Observation -> AntennaField;
+ Observation -> TileBeam;
+ Observation -> DigitalBeam;
+
+ AntennaField -> RECV;
+ TileBeam -> AntennaField;
+ DigitalBeam -> Beamlet;
+ DigitalBeam -> AntennaField;
+
+ SST -> SDP;
+ XST -> SDP;
+ BST -> SDP;
+
+ APSCT;
+ APSPU;
+ UNB2;
+
+ PSOC;
+ }
+
+ subgraph clusterSDP {
+ label = "SDP";
+
+ SDPTR -> Firmware;
+ UNB2TR -> Uniboard2;
+ }
+ SDP -> SDPTR;
+ Beamlet -> SDPTR;
+ SST -> SDPTR;
+ XST -> SDPTR;
+ BST -> SDPTR;
+ UNB2 -> UNB2TR;
+
+ subgraph clusterRECV {
+ label = "RECV";
+
+ RECVTR -> RCU -> HBAT;
+ }
+ RECV -> RECVTR;
+
+ subgraph clusterAPSCT {
+ label = "APSCT";
+
+ APSCTTR;
+ }
+ APSCT -> APSCTTR;
+
+ subgraph clusterAPSPU {
+ label = "APSPU";
+
+ APSPUTR;
+ }
+ APSPU -> APSPUTR;
+
+ subgraph clusterPSOC {
+ label = "PSOC";
+ }
+ PSOC -> clusterPSOC;
+ }
+
+A brief description of each of these devices:
+
+* `ObservationControl` device spawns new Observation devices, given an observation specification,
+* `Observation` device sets up the software and hardware on the station to execute a given specification,
+* `AntennaField` device controls a set of antennas and their properties (f.e. their positions),
+* `RECV` device represents the hardware that controls the antennas in the station,
+* `TileBeam` device steers the beam of the HBA tiles, actively tracking any source,
+* `SDP` device represents generic functionality of the firmware that digitally combines antenna inputs,
+* `SST`, `XST`, and `BST` devices control and expose statistics generated by the SDP firmware,
+* `Beamlet` device controls the observation output data (beamlets) that stream out of the station (in LOFAR, to CEP),
+* `DigitalBeam` device steers the beam formed in SDP, actively tracking any source.
+
+Auxilliary devices that control hardware are:
+
+* `APSCT` device controls the ASPCT clock selection and distribution board,
+* `APSPU` device controls the APSPU 48V distribution board,
+* `UNB2` device controls the Uniboards that hold the SDP FPGAs (and thus firmware).
+* `PSOC` device controls the power sockets (230V distribution).
+
+Finally, the stack holds the auxilliary devices that control the software devices. They connect to too many devices to draw:
+
+* `Docker` device controls the Docker containers of the software stack,
+* `Boot` device controls the proces for booting up the devices and initialising the hardware,
+* `TemperatureManager` device acts on temperature alarms originating from the hardware.
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-digitalbeam.rst b/tangostationcontrol/docs/source/devices/tilebeam-digitalbeam.rst
new file mode 100644
index 0000000000000000000000000000000000000000..4089d082f4b5a62fd663673983ad03c8fa0f4710
--- /dev/null
+++ b/tangostationcontrol/docs/source/devices/tilebeam-digitalbeam.rst
@@ -0,0 +1,141 @@
+TileBeam, DigitalBeam
+------------------------
+
+A primary function of the station is to combine its antenna signals to create a more sensitive signal. The antennas are typically aimed at celestial sources moving across the sky, but can also be aimed at stationary targets, for example to point at Earth-bound signals or to let the sky pass through the beam instead.
+
+Given a certain direction, and knowing the speed of light, one can compute the differences in arrival time for light from the observed source (its wave front) towards each antenna. The antenna signals are then aligned towards the source by delaying the signal inputs based on these differences. The antennas closest to the source get the largest delay. For celestial sources, the light is assumed to be infinitely far away and thus travel in parallel towards each antenna, greatly simplifying the calculations involved.
+
+In practice, antenna signals can only be coarsely delayed. Fine delay compensation consists of rotating the signal inputs to compensate for the remaining differences in phase. The amount of rotation is frequency dependent. The aligned signals are subsequently added, creating a single signal output of higher sensitivity towards the observed source, albeit with a narrower field of view.
+
+Beam tracking therefor requires a *pointing* direction in which to observe, as well as the *positions* of the antennas involved. Finally, the antennas need to be periodically realigned to track moving sources. We distinguish the following concepts:
+
+- *Beam forming* is combining individual element signals into one. This is performed by the HBAT hardware and SDP firmware,
+- *Beam steering* is uploading the delays or weights to the beam-forming hardware, in order to point the beam in a certain direction,
+- *Beam tracking* is updating the beam steering over time to track a celestial target, compensating for the Earth's movement through space.
+
+The ``tilebeam == DeviceProxy("STAT/TileBeam/1")`` device configures the HBA beam former in each HBA tile, which adds the signals of its 16 elements within the tile. The output signal of these tiles is used as input for the digital beam former (just like the direct output of an LBA).
+
+The ``digitalbeam == DeviceProxy("STAT/DigitalBeam/1")`` device configures the digital beam formed in SDP from antenna or tile inputs. The output signal in SDP are *beamlets*, which can
+
+Both devices beamform the antennas configured in its associated ``AntennaField`` device, but differ in what they beamform and with respect to which position:
+
+- TileBeam:
+
+ - Beamforms HBA elements in the HBA tiles of its AntennaField device,
+ - Uses ``antennafield.HBAT_Reference_ITRF_R`` as the reference position for each tile,
+ - Allows a different pointing per HBA tile,
+ - ``N_output := antennafield.nr_tiles_R``,
+ - Uploads the computed weights to ``antennafield.HBAT_bf_delay_steps_RW``,
+ - These weights are actually *delay steps* to be applied in the tile for each element.
+
+- DigitalBeam
+
+ - Beamforms all the antennas or tiles of its AntennaField device,
+ - Uses ``antennafield.Antenna_Field_Reference_ITRF_R`` as the reference position,
+ - Allows a different pointing per beamlet,
+ - ``N_output := NUM_BEAMLETS = 488``,
+ - Uploads the computed weights to ``beamlet.FPGA_bf_weights_xx_yy_RW``,
+ - These weights are actually complex *phase rotations* to be applied on each antenna input.
+
+Common functionality
+`````````````````````
+
+The following functionality holds for both TileBeam and DigitalBeam.
+
+Beam Tracking
+"""""""""""""""""""""""""""""""""
+
+Beam tracking automatically recomputes and reapplies pointings periodically, and immediately when new pointings are configured. It exposes the following interface:
+
+:Tracking_enabled_R: Whether beam tracking is running.
+
+ :type: ``bool``
+
+:Pointing_direction_RW: The direction in which the beam should be tracked for each antenna. The beam tracker will steer the beam periodically, and explicitly whenever the pointings change.
+
+ :type: ``str[N_output][3]``
+
+:Pointing_direction_R: The last applied pointing of each antenna.
+
+ :type: ``str[N_output][3]``
+
+:Pointing_timestamp_R: The timestamp for which the last set pointing for each antenna was applied and set (in seconds since 1970).
+
+ :type: ``float[N_output][3]``
+
+A pointing describes the direction in the sky, and consists of a set of coordinates and the relevant coordinate system. They are represented as a tuple of 3 strings: ``("coordinate_system", "angle1", "angle2")``, where the interpretation of ``angle1`` and ``angle2`` depends on the coordinate system used. For example:
+
+- ``("AZELGEO", "0deg", "90deg")`` points at Zenith (Elevation = 90°, with respect to the Earth geode),
+- ``("J2000", "0deg", "90deg")`` points at the North Celestial Pole (Declination = 90°),
+- ``("SUN", "0deg", "0deg")`` points at the centre of the Sun.
+
+For a full list of the supported coordinate systems, see https://casacore.github.io/casacore/classcasacore_1_1MDirection.html
+
+Beam Steering
+"""""""""""""""""""""""""""""""""
+
+The beam steering is responsible for pointing the beams at a target, by converting the pointing to hardware-specific weights and uploading them to the corresponding device. The beam steering is typically controlled by the beam tracker. To point the antennas in any direction manually, you should disable beam tracking first:
+
+:Tracking_enabled_RW: Enable or disable beam tracking (default: ``True``).
+
+ :type: ``bool``
+
+:set_pointing(pointings): Point the beams towards the specified ``pointings[N_output][3]`` for all outputs.
+
+ :returns: ``None``
+
+Celestial and geographical models
+"""""""""""""""""""""""""""""""""
+
+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:
+
+:measures_directory_R: Directory of the active set of measures tables. The directory name includes the timestamp denoting their age.
+
+ :type: ``str``
+
+:measures_directories_available_R: List of installed sets of measures tables.
+
+ :type: ``str[64]``
+
+:download_measures(): Download (but do not activate) the latest measures tables from ftp://ftp.astron.nl. Returns the directory name in which the measures were installed.
+
+ :returns: ``str``
+
+:use_measures(dir): Activate the measures tables in the provided directory. This necessitates turning off and restarting the TileBeam device, so the command will always appear to fail. Turn the device back and the selected measures tables will be active.
+
+ :returns: ``(does not return)``
+
+DigitalBeam
+`````````````````````
+
+The DigitalBeam device applies the following configuration to compute each beamlet. Here, ``N_ant := antennafield.nr_tiles_R`` and ``N_beamlet := NUM_BEAMLETS == N_output``.
+
+:antenna_select_RW: Which beamlets to form with which antenna. ``True`` by default, except for antennas which are not mapped on any FPGA input (see "Configuration" below).
+
+ :type: ``bool[N_ant][N_beamlet]``
+
+:beamlet.subband_select_RW: Which subband to beamform for each beamlet.
+
+ :type: ``uint32[N_beamlet]``
+
+:sdp.clock_RW: Which clock to use (in Hz, default: 200e6).
+
+ :type: ``uint32``
+
+:sdp.antenna_type_R: Which antenna type is connected: "LBA" or "HBA". Configurable through the ``sdp.Antenna_Type`` property.
+
+ :type: ``str``
+
+:sdp.nyquist_zone_R: Relevant Nyquist zone (0, 1 or 2), based on the clock and antenna type.
+
+ :type: ``uint32``
+
+Configuration
+"""""""""""""""""""""
+
+The following properties configure the DigitalBeam:
+
+:Input_to_Antenna_Mapping: Which antenna from the AntennaField is the input for each antenna input of the FPGAs.
+
+ :type: ``uint32[96]``
+
diff --git a/tangostationcontrol/docs/source/devices/tilebeam.rst b/tangostationcontrol/docs/source/devices/tilebeam.rst
deleted file mode 100644
index 1df29562f605039cad0f77ad284b1f0d3b562f0b..0000000000000000000000000000000000000000
--- a/tangostationcontrol/docs/source/devices/tilebeam.rst
+++ /dev/null
@@ -1,86 +0,0 @@
-Beam
-====================
-
-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:
-
-:Tracking_enabled_R: Whether beam tracking is running.
-
- :type: ``bool``
-
-:Pointing_direction_RW: The direction in which the beam should be tracked for each antenna. The beam tracker will steer the beam periodically, and explicitly whenever the pointings change.
-
- :type: ``str[N_ant][3]``
-
-:Pointing_direction_R: The last applied pointing of each antenna.
-
- :type: ``str[N_ant][3]``
-
-:Pointing_timestamp_R: The timestamp for which the last set pointing for each antenna was applied and set (in seconds since 1970).
-
- :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:
-
-:Tracking_enabled_RW: Enable or disable beam tracking (default: ``True``).
-
- :type: ``bool``
-
-:set_pointing(pointings): Point the beams towards the specified ``pointings[N_ant][3]`` for all antennas (for which ``recv.ANT_mask_RW`` is set).
-
- :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:
-
-:recv.HBAT_antenna_itrf_offsets_R: The relative offsets of the elements within each HBA tile with respect to its reference position, in ITRF.
-
- :type: ``double[16][3]``
-
-:recv.HBAT_reference_itrf_R: The absolute reference position for an HBA tile, in ITRF.
-
- :type: ``double[96][3]``
-
-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:
-
-:measures_directory_R: Directory of the active set of measures tables. The directory name includes the timestamp denoting their age.
-
- :type: ``str``
-
-:measures_directories_available_R: List of installed sets of measures tables.
-
- :type: ``str[64]``
-
-:download_measures(): Download (but do not activate) the latest measures tables from ftp://ftp.astron.nl. Returns the directory name in which the measures were installed.
-
- :returns: ``str``
-
-:use_measures(dir): Activate the measures tables in the provided directory. This necessitates turning off and restarting the TileBeam device, so the command will always appear to fail. Turn the device back and the selected measures tables will be active.
-
- :returns: ``(does not return)``
diff --git a/tangostationcontrol/docs/source/devices/using.rst b/tangostationcontrol/docs/source/devices/using.rst
index 9e5d053b616a9102a04db8c2c497600e06a61f73..71e413c9791e440bd6a59e1b27ddafe2be6fce0c 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:
@@ -121,7 +121,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::
@@ -139,7 +139,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::
@@ -148,7 +148,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.
diff --git a/tangostationcontrol/docs/source/index.rst b/tangostationcontrol/docs/source/index.rst
index b3b686818cc758f1ed662f07bff5d4f0095b1920..07c5fb4ac45444e941b31b3869198b2504284389 100644
--- a/tangostationcontrol/docs/source/index.rst
+++ b/tangostationcontrol/docs/source/index.rst
@@ -18,22 +18,21 @@ Even without having access to any LOFAR2.0 hardware, you can install the full st
installation
interfaces/overview
+ devices/overview
devices/using
- devices/tilebeam
- devices/beamlet
- devices/digitalbeam
devices/antennafield
- devices/boot
- devices/docker
- devices/psoc
+ devices/tilebeam-digitalbeam
+ devices/beamlet
devices/recv
devices/sdp
devices/bst-sst-xst
+ devices/boot
+ devices/docker
+ devices/psoc
devices/temperature-manager
devices/configure
configure_station
signal_chain
- beam_tracking
developer
faq
diff --git a/tangostationcontrol/tangostationcontrol/devices/sdp/xst.py b/tangostationcontrol/tangostationcontrol/devices/sdp/xst.py
index 19068ff768dcf0eda9782dc213cf293bcb0ed004..4fe5292b638fd346da9bf772c0ce2c7e529bddae 100644
--- a/tangostationcontrol/tangostationcontrol/devices/sdp/xst.py
+++ b/tangostationcontrol/tangostationcontrol/devices/sdp/xst.py
@@ -122,8 +122,8 @@ class XST(Statistics):
FPGA_xst_ring_rx_clear_total_counts_RW = attribute_wrapper(comms_id=OPCUAConnection, comms_annotation=["FPGA_xst_ring_rx_clear_total_counts_RW"], datatype=bool, dims=(N_PN,), access=AttrWriteType.READ_WRITE)
FPGA_xst_ring_rx_clear_total_counts_R = attribute_wrapper(comms_id=OPCUAConnection, comms_annotation=["FPGA_xst_ring_rx_clear_total_counts_R"], datatype=bool, dims=(N_PN,))
- FPGA_xst_rx_align_stream_enable_RW = attribute_wrapper(comms_id=OPCUAConnection, comms_annotation=["FPGA_xst_rx_align_stream_enable_RW"], datatype=numpy.uint32, dims=(N_PN,), access=AttrWriteType.READ_WRITE)
- FPGA_xst_rx_align_stream_enable_R = attribute_wrapper(comms_id=OPCUAConnection, comms_annotation=["FPGA_xst_rx_align_stream_enable_R"], datatype=numpy.uint32, dims=(N_PN,))
+ FPGA_xst_rx_align_stream_enable_RW = attribute_wrapper(comms_id=OPCUAConnection, comms_annotation=["FPGA_xst_rx_align_stream_enable_RW"], datatype=bool, dims=(N_PN,P_SQ), access=AttrWriteType.READ_WRITE)
+ FPGA_xst_rx_align_stream_enable_R = attribute_wrapper(comms_id=OPCUAConnection, comms_annotation=["FPGA_xst_rx_align_stream_enable_R"], datatype=bool, dims=(N_PN,P_SQ))
FPGA_xst_ring_rx_total_nof_packets_received_R = attribute_wrapper(comms_id=OPCUAConnection, comms_annotation=["FPGA_xst_ring_rx_total_nof_packets_received_R"], datatype=numpy.uint32, dims=(N_PN,))
FPGA_xst_ring_rx_total_nof_packets_discarded_R = attribute_wrapper(comms_id=OPCUAConnection, comms_annotation=["FPGA_xst_ring_rx_total_nof_packets_discarded_R"], datatype=numpy.uint32, dims=(N_PN,))
FPGA_xst_ring_rx_total_nof_sync_received_R = attribute_wrapper(comms_id=OPCUAConnection, comms_annotation=["FPGA_xst_ring_rx_total_nof_sync_received_R"], datatype=numpy.uint32, dims=(N_PN,))