From 24bbf3f9ac82a22817fd8d350e70ba31471f1b7e Mon Sep 17 00:00:00 2001
From: Jan David Mol <mol@astron.nl>
Date: Thu, 7 Oct 2021 20:03:50 +0200
Subject: [PATCH] L2SS-434: Explain how to deal with FAULT
---
docs/source/devices/using.rst | 33 ++++++++++++++++++++++++++++-----
1 file changed, 28 insertions(+), 5 deletions(-)
diff --git a/docs/source/devices/using.rst b/docs/source/devices/using.rst
index 3641f5f04..7eafa202a 100644
--- a/docs/source/devices/using.rst
+++ b/docs/source/devices/using.rst
@@ -34,18 +34,41 @@ Each device provides the following functions to change 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``.
+FAULT
+``````````
+
+If a device enters the ``FAULT`` state, it means an error occurred that is fundamental to the operation of the software device. For example, the connection
+to the hardware was lost.
+
+Interaction with the device in the ``FAULT`` state is undefined, and attributes cannot be read or written. The device needs to be reinitialised, which
+typically involves the following sequence of commands::
+
+ # turn the device off completely first.
+ device.off()
+
+ # setup any connections and threads
+ device.initialise()
+
+ # reconfigure the hardware to reach a known state
+ device.set_defaults()
+
+ # turn on the device
+ device.on()
+
+Of course, the device could go into ``FAULT`` again, even during the ``initialise()`` command, for example because the hardware it manages is unreachable. To debug the fault condition, check the :doc:`../logs` of the device in question.
+
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")
+ recv = Device("LTS/RECV/1")
- # turn on all LED0s
- recv.RCU_LED0_RW = [True] * 32
+ # turn on all LED0s
+ recv.RCU_LED0_RW = [True] * 32
- # retrieve the status of all LED0s
- print(recv.RCU_LED0_R)
+ # retrieve the status of all LED0s
+ print(recv.RCU_LED0_R)
The attributes with an:
--
GitLab