L2SS-434: Add devices description

docs/source/devices/devices.rst

+Devices
+=============
+
+The station exposes the following devices:
+
+To access a device, one creates a `Device` object. For example::
+
+    device = Device("LTS/RECV/1")
+
+States
+------------
+
+The state of a device is then queried with `device.state()`. Each device can be in one of the following states:
+
+- `DevState.OFF`: The device is not operating,
+- `DevState.INIT`: The device is being initialised,
+- `DevState.STANDBY`: The device is initialised and ready to be configured further,
+- `DevState.ON`: The device is operational.
+- `DevState.FAULT`: The device is malfunctioning. Functionality cannot be counted on.
+- The `device.state()` function can throw an error, if the device cannot be reached at all. For example, because it's docker container has not been started.
+
+Each device provides the following functions to change state:
+
+- `off()`: Turn the device `OFF` from any state.
+- `initialise()`: Initialise the device from the `OFF` state, to bring it to the `STANDBY` state.
+- `on()`: Mark the device as operational, from the `STANDBY` state, bringing it to `ON`.
+
+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::
+
+    recv = Device("LTS/RECV/1")
+
+    # turn on all LED0s
+    recv.RCU_LED0_RW = [True] * 32
+
+    # 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.

docs/source/devices/recv.rst

+RECV
+=======
+
+The `recv == Device("LTS/RECV/1")` device controls the RCUs, the LBA antennas, and HBA tiles. Central to its operation are the masks:
+
+- The `RCU_mask_RW` attribute is an array of `bool[N_RCUs]`. It controls which RCUs will actually be configured, when fields referring to RCUs are set. Any RCU for which the mask is False will not be configured when RCU control points are set.
+- The `Ant_mask_RW` attribute is an array of `bool[N_RCUs][N_Antennas_per_RCU]`. It controls which antennas will actually be configured, when fields referring to antennas are set. Any antenna for which the mask is False will not be configured when antenna control points are set.
+
+Typically, `N_RCUs == 32`, and `N_Antennas_per_RCU == 3`.

docs/source/index.rst

@@ -12,6 +12,8 @@ Welcome to LOFAR2.0 Station Control's documentation!
 
    usage/installation
    usage/remote_interfaces
+   devices/devices
+   devices/recv
 
 
 Indices and tables