diff --git a/docs/source/devices/using.rst b/docs/source/devices/using.rst index 3641f5f0416878cd20299d4d42aa32fabadfa3c6..7eafa202a0f25f11c450716683c398de77b7f9b6 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: