Document states of a motor

[reszelaz]

I open this issue after our discussion from the sardana-followup meeting 2021-06-10:

• Hang scan due to the counter/timer controller timeout in StateOne() - How to deal with exceptions in the controllers: Review the docs? MaxIV reported that bringing an element to FAULT state will, as it should, stopp the scan. Before they were using the State UNKNOWN, this is why the scan was hanging. This should be added to the recomendations. In ALARM the scan will continue but without data for that channel. For MaxIV UNKNOWN and FAULT will indicate that the element is not useful, in ALARM the connection to the hardware is there but there is some problem. A table about the states will be created to be discussed in github.

The following table lists the possible Motor states and describes in which circumstances these should be used:

State	Description
ON	Motor is on and ready to moving
MOVING	When it is moving
ALARM	When it has reached one of the limit switches
FAULT	If its controller software is not available (impossible to load it) or if a fault is reported from the hardware controller.
UNKNOWN	If an exception occurs during the communication between the pool and the hardware controller.

These states corresponds one-to-one to the Tango states:

State	Description
ON	This state could have been called OK or OPERATIONAL. It means that the device is in its operational state. (E.g. the powersupply is giving its nominal current, the motor is ON and ready to move, the instrument is operating). This state is modified by the Attribute alarm checking of the DeviceImpl:dev_state method. i.e if the state is ON and one attribute has it’s quality factor to ALARM, then the state is modified to ALARM
MOVING	The device is in a transitory state. It is the case of a device moving from one state to another.( E.g a motor moving from one position to another, a big instrument is executing a sequence of operation, a macro command is being executed.)
ALARM	The device is operating but one of this attribute is out of range. It can be linked to alarm conditions set by attribute properties or a specific case. (E.g. temperature alarm on a stepper motor, end switch pressed on a steppermotor, up water level in a tank, etc…) In alarm, usually the device does it’s job but the operator has to perform an action to avoid a bigger problem that may switch the state to FAULT.
FAULT	The device has a major failure that prevents it to work. For instance, A powersupply has stopped due to over temperature A motor cannot move because it has fault conditions. Usually we cannot get out from this state without an intervention on the hardware or a reset command.
UNKNOWN	The device cannot retrieve its state. It is the case when there is a communication problem to the hardware (network cut, broken cable etc…). It could also represent an incoherent situation

If you agree, I will add the first table to the docs.

[reszelaz]

Also, based on the feedback from #1601 I would extend the list of the possible states with OFF. So the table would look like this:

State	Description
ON	Motor is on and ready to moving
OFF	Motor is powered off and can not be moved
MOVING	When it is moving
ALARM	When it has reached one of the limit switches
FAULT	If its controller software is not available (impossible to load it) or if a fault is reported from the hardware controller.
UNKNOWN	If an exception occurs during the communication between the pool and the hardware controller.

And its Tango corresponding state:

State	Description
OFF	The device is in normal condition but is not active. e.g thepowersupply main circuit breaker is open; the RF transmitter has nopower etc…

Please comment on the addition of the OFF state independently.