L2SS-434: Added configuring device properties.

docs/source/devices/configure.rst

+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*.
+
+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.
+
+Each device queries the TangoDB for the value of its properties during the ``initialise()`` call. Default values for control attributes can then be applied by explicitly calling ``set_defaults()``. The ``boot`` device also calls ``set_defaults()`` when initialising the station. The rationale being that the defaults can be applied at boot, but shouldn't be applied automatically during operations, as not to disturb running hardware.
+
+Device interaction
+````````````````````````````
+
+The properties of a device can be queried from the device directly::
+
+  # get a list of all the properties
+  property_names = device.get_property_list("*")
+
+  # fetch the values of the given properties. returns a {property: value} dict.
+  property_dict = device.get_property(property_names)
+
+Properties can also be changed::
+
+  changeset = { "property": "new value" }
+
+  device.put_property(changeset)
+
+Note that new values for properties will only be picked up by the device during ``initialise()``, so you will have to turn the device off and on.
+
+Command-line interaction
+``````````````````````````
+
+The content of the TangoDB can be dumped from the command line using::
+
+  bin/dump_ConfigDb.sh > tangodb-dump.json
+
+and changes can be applied using::
+
+  bin/update_ConfigDb.sh changeset.json
+
+.. note:: The ``dsconfig`` docker container needs to be running for these commands to work.
+
+Jive
+``````````````````````````
+
+The TangoDB can also be interactively queried and modified using Jive. Jive is an X11 application provided by the ``jive`` image as part of the software stack of the station. It must however be started on-demand, with a correctly configured ``$DISPLAY``::
+
+  cd docker-compose
+  make start jive
+
+If Jive does not appear, check ``docker logs jive`` to see what went wrong.
+
+For information on how to use Jive, see https://tango-controls.readthedocs.io/en/latest/tools-and-extensions/built-in/jive/.
+
+.. note:: If you need an X11 server on Windows, install `VcXsrv <https://sourceforge.net/projects/vcxsrv/>`_, disable access control during its startup, and use ``export DISPLAY=host.docker.internal:0`` in WSL.
+

docs/source/devices/devices.rst

@@ -120,6 +120,7 @@ The easiest way to capture this stream is to use our ``statistics_writer``, whic
 
 The correct port will automatically be chosen, depending on the given mode. See also ``statistics_writer.py -h`` for more information.
 
-The writer can also parse a statistics stream stored in a file, so the stream can be captured and processed later using the writer. Capturing the stream could be done using ``netcat``::
+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/index.rst

@@ -14,6 +14,7 @@ Welcome to LOFAR2.0 Station Control's documentation!
    remote_interfaces
    devices/using
    devices/devices
+   devices/configure
    control
    monitoring
    logs