.. __app-runcycle:

=======================================
App Run Cycle
=======================================

.. toctree::
   :maxdepth: 2

``LOADING`` --> ``READY TO RUN`` --> ``PREPARING TO RUN`` --> ``RUNNING`` --> ``POSTWORK`` --> ``FINISHED``

---------------------------------------
Functions in Detail
---------------------------------------
When a user selects an app on the dashboard, it executes the corresponding functions:

1. LOADING: ``init()``
2. READY TO RUN: ``check_status()``
3. PREPARING TO RUN: ``on_start()``
4. RUNNING: ``run_in_loop()``
5. POSTWORK: ``on_stop_event()``

**LOADING**

1. When the app is selected in the dashboard, the ``init()`` function is called.

**STARTING THE APP // RUNNING**

When the user clicks the "Start" button, the following happens:

:1. PREPARING TO RUN:

   | 1.1 ``check_status()``: This fuction ensures enough nodes are connectd in order to successfully run the app.
   | 1.2 ``on_start_event()``: If the ``check_status()`` function return ``True``, then the system prepares to run the app. If you would like custom code to run before the app starts streaming data you can put that in you may override ``on_start_event()`` to add that functionality.

----

:2. RUNNING:
   2.1. ``run_in_loop()``: Once all the setup is completed (usually less than 1 second if no custom code is added in the ``on_start_event()``). This function will contune to execute at the specificed data rate -- usually 100 times per second. 

        **Streaming Data**

         Data is streamed to the dashboard with the ``send_stream_data(data, my_data)`` function call. where ``data`` is a dictionary of all the raw sensor data, and ``my_data`` is a dictionary of the custom data to be sent to the dashboard. 

            - **Raw Data Fields:** ``data = self.my_sage.get_next_data()`` (See Below for detailed example)
            - **Calculated Fields (aka: User Fields):** ``my_data`` should be structured as follows: ``my_data = {'key': [value], 'key': value'}`` An example is below:
         
         **Saving Data**

         Data is saved to the trial data file with the ``self.my_sage.save_data(data, my_data)`` function call.
        
      .. Note:: If at any time ``False`` if returned from this app, then it will stop the app and move the next step. 


----
   
:3. CLICKING STOP:
   ``on_stop_event()``: Once all the user clicks the ``STOP`` button on the dashboard, the ``on_stop_event()`` is called. 
   You can use this funcion to perform any post processing needs you have, such as summary calcuations of the data set, transmitting the data automatically or custom reporting.