.. _TF_protocol_switches:

States and possible state switches
==================================

The |Company protocol name| offers two control interfaces: a web browser-based graphical user interface and a TCP-based interface. The web interface will enable the operator to invoke all state-switching methods. As a result, from |Company name| side, it should not be assumed that the state cannot change unless requested via TCP.

Current implementations of the |Company protocol name| will have these possible states:

.. list-table::
   :widths: 5 25 70
   :header-rows: 0 
 
   * - ``1``
     - "CONNECTED"
     - The |Company protocol name| is activated, the TCP server is running and ready to listen for requests. It is awaiting the ``"SystemStart"`` request.
   * - ``2``
     - "STARTING"
     - This state indicates that there was a recent request for the |Company protocol name| to perform ``"SystemStart"``, but the process is not yet complete. The connected sensors are currently undergoing the startup sequence, self-diagnostics, and other related tasks. The duration of this transitional state is not strictly deterministic, as it depends on various external factors. Since this procedure cannot be interrupted, the |Company protocol name| will ignore any further state-switching requests until the startup sequence is finished. Once completed, the |Company protocol name| will switch to **NOT_LOGGING**.
   * - ``3``
     - "NOT_LOGGING"
     - The |Company protocol name| is ready for data collection. Once ``"StartLogging"`` is called, it will switch to **LOGGING**. If ``"SystemStop"`` is invoked, the |Company protocol name| will switch to **STOPPING** and then, after completing the stopping sequence, transition to **CONNECTED**.
   * - ``4``
     - "LOGGING"
     - The |Company protocol name| is currently collecting data. Once ``"StopLogging"`` or ``"SystemStop"`` is called, data collection will cease. If ``"StopLogging"`` is invoked, the |Company protocol name| will switch to NOT_LOGGING. If ``"SystemStop"`` is called, it will switch to **STOPPING**, and after the stopping sequence is complete, it will transition to **CONNECTED**.
   * - ``5``
     - "STOPPING"
     - This state indicates that a recent request for the |Company protocol name| to perform ``"SystemStop"`` has been initiated but is not yet complete. All active sensors are currently undergoing the stopping sequence. Similar to the **STARTING** state, the duration of this transitional state is not strictly deterministic. Since this procedure cannot be interrupted, the |Company protocol name| will ignore any further state-switching requests until the stopping sequence is finished. Once completed, the |Company protocol name| will switch to **CONNECTED**.
   * - ``6-9``
     - undefined 
     - reserved for later use
   * - ``10``
     - "ERROR"
     - Some error has occurred in the |Company protocol name|, and the self-diagnostics have identified the issue. The |Company protocol name| is unable to continue functioning. Transitioning to this state can occur at any point during the workflow.

| 

The following simplified state diagram excludes the **ERROR** state for visual clarity. The complete version is provided at the end of the chapter.

.. image::  ../../pics/protocol/TF_protocol_state_diagram.png

| 

When |Company name| first connects to the |Company protocol name|, it is generally expected to be in the **CONNECTED** state.

While in the **CONNECTED** state, the only request that can be made is ``"SystemStart"``, which switches the state to **STARTING**. Once the sensor startup sequence is complete, the |Company protocol name| will transition to **NOT_LOGGING**.

When the |Company protocol name| is in the **NOT_LOGGING** state, ``"StartLogging"`` can be called, which will transition it to **LOGGING** and initiate data collection with minimal delay (the exact delay will need to be determined through testing). Additionally, ``"SystemStop"`` can be invoked while in the **NOT_LOGGING** state, which will switch the |Company protocol name| to **STOPPING**, and subsequently to **CONNECTED**.

When the |Company protocol name| is in the **LOGGING** state, ``"StopLogging"`` can be called to swiftly halt data collection and transition the state to **NOT_LOGGING** with minimal delay. This action does not initiate any stopping sequence for the sensors, allowing them to remain prepared for a quick return to **LOGGING**.

When ending work with the |Company protocol name|, ``"SystemStop"`` should be called. This can be done from both the **LOGGING** and **NOT_LOGGING** states. It will transition the state to **STOPPING**, initiate the sensor stopping sequence, and then switch back to **CONNECTED**.

The following full state diagram includes the **ERROR** state, which can be transitioned to from any state. This state will be visible to |Company name| through the ``"GetState"`` request and error details will be provided in the ``"message"`` field.

.. image::  ../../pics/protocol/TF_protocol_state_diagram_full.png