From c371e275feba8381f5fbd209719433de345f9478 Mon Sep 17 00:00:00 2001
From: Jan David Mol <mol@astron.nl>
Date: Thu, 7 Oct 2021 23:47:54 +0200
Subject: [PATCH] L2SS-434: Explain hardware initialisation functions

---
 docs/source/devices/using.rst | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/source/devices/using.rst b/docs/source/devices/using.rst
index c41f64cbf..8c2a58ca8 100644
--- a/docs/source/devices/using.rst
+++ b/docs/source/devices/using.rst
@@ -61,14 +61,22 @@ typically involves the following sequence of commands::
   # 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:`../interfaces/logs` of the device in question.
 
+Initialise hardware
+````````````````````
+
+Most devices provide the following commands, in order to configure the hardware with base settings:
+
+:set_defaults(): Upload default attribute settings from the TangoDB to the hardware.
+
+:initialise_hardware(): For devices that control hardware, this command runs the hardware initialisation procedure.
+
+Typically, ``set_defaults()`` and ``initialise_hardware()`` are called in that order in the ``STANDBY`` state. The :ref:`boot` device runs these commands as part of its station initialsation sequence.
+
 .. _attributes:
 
 Attributes
-- 
GitLab