.. include:: colors.rst

======================================
Mpod s/w device states and transitions
======================================

The device state transition diagram (STD) implemented is shown below, where ovals are states,
boxes are transitions, and diamonds are branching points. The colours used follow those
used in the GUI client. Note that the ERROR state can be reached from any state or transition
and the lines to it are not shown. 

.. digraph:: device_states_and_transitions

   node [shape=box];
   { rank = same; "instantiate" }
   { rank = same; "STARTING"; "ACTIVE"; "disable"; }
   { rank = same; "decide"; "reset"; "ERROR"; }
   { rank = same; "STOPPING"; "PASSIVE"; "enable"; }

   "enable"[shape=box style=filled, fillcolor=beige]
   "disable"[shape=box style=filled, fillcolor=beige]
   "PASSIVE"[shape=oval style=filled, fillcolor=grey]
   "ACTIVE"[shape=oval style=filled, fillcolor=green]
   "STARTING"[shape=oval style=filled, fillcolor=blue]
   "STOPPING"[shape=oval style=filled, fillcolor=blue]
   "STOPPING" -> "PASSIVE"
   "ACTIVE" -> "disable" -> "STOPPING"
   "PASSIVE" -> "enable" -> "STARTING"
   "STARTING" -> "ACTIVE"

   "instantiate" -> "decide" -> "STARTING"
   "instantiate"[shape=box]
   "reset"[shape=box style=filled, fillcolor=beige]
   "decide"[shape=diamond, style=filled, fillcolor=yellow]
   "ERROR"[shape=oval style=filled, fillcolor=red]
   "ERROR" -> "reset" -> "decide" -> "STOPPING"

=======================================
LV or HV channel states and transitions
=======================================

The state of a channel is driven by setting ``operator`` or ``switch`` to the
appropriate value (e.g. to 'on' or 1, 'off' or 0, respectively) and not, as in
the s/w device, by pressing a button to start a transition. Despite this
difference the same diagram elements are used to show the the channel STD, but
using orange fill of a box to indicate a property change.

The STD shown is for the case where ``autoRearm`` is False and latched
interlocks on HV channels must be cleared by pressing the ``Clear interlocks``
button.

If ``autoRearm`` is True, the latched interlock is cleared automatically thus
aligning it to LV channel interlock behaviour and it is sufficient to enter
'off' or 0 at the ``operator`` or ``switch`` switch to go to OFF. Clearly, if
the interlock condition (signal) is still being applied then the channel state
will return immediately to INTERLOCKED without going through OFF.

The channel's state if UNKNOWN if the channel f/w bit status does not
correspond to a real state - this has never been observed and is not
interpreted as an ERROR.

The ERROR state is set if the channel is tripped, current limited, etc., when
the reason is shown in ``stateInWords``. Additionally on disable the poll loop
is terminated, all channel states are set to ERROR and the schema is kept. The
latter is driven by the requirement of seeing the last state of device and
channels, on enable the schema is rebuilt.

.. digraph:: channel_states_and_transitions

   node [shape=box];
   { rank = same; "on"; "RAMPING_UP"; "ON"; "off"; "RAMPING_DOWN"; "OFF"; }
   { rank = same; "ERROR"; "INTERLOCKED"; }
   { rank = same; "UNKNOWN" }

   "on"[shape=box style=filled, fillcolor=orange]
   "off"[shape=box style=filled, fillcolor=orange]
   "clear_trips"[shape=box style=filled, fillcolor=beige]
   "clear_interlocks"[shape=box style=filled, fillcolor=beige]
   "OFF"[shape=oval style=filled, fillcolor=grey]
   "RAMPING_UP"[shape=oval style=filled, fillcolor=blue]
   "ON"[shape=oval style=filled, fillcolor=green]
   "RAMPING_DOWN"[shape=oval style=filled, fillcolor=blue]
   "on" -> "RAMPING_UP" -> "ON" -> "off" -> "RAMPING_DOWN" -> "OFF" -> "on"
   "ERROR"[shape=oval style=filled, fillcolor=red]
   "ERROR" -> "clear_trips" -> "OFF"
   "INTERLOCKED"[shape=oval style=filled, fillcolor=purple]
   "INTERLOCKED" -> "clear_interlocks" -> "OFF"

   "UNKNOWN"[shape=oval style=filled, fillcolor=pink]