..  _demo_study_control:

Study Control
=============

The study control application was implemented to support you during your study process. There are already enough things to organize and to coordinate during studies where this component can help you to make at least the technical workload as low as possible. For this you can implement start, stop and condition script to trigger routines between your study runs and to get directly informed if the setup is ready so your participants can start.

.. figure:: /images/study-control_recording.png
    :scale: 100 %
    :alt: study-control

.. _system_help:

Related resources
-----------------

**Component repository:** https://github.com/csra/study-control.git

**System startup:** ``study-control``


**System help:** ``study-control --help``

.. code-block:: bash

    usage: study-control [--condition-script-directory 'DIRECTORY'] [--conditions '0..N'] [--data-prefix 'STRING'] [--name
        'STRING'] [--participant-id 'STRING'] [--start-record-script 'FILE'] [--stop-record-script 'FILE'] [-h |
        --help] [-v 'BOOLEAN' | --verbose 'BOOLEAN']

    where:
        --condition-script-directory 'DIRECTORY' [Default: --condition-script-directory /tmp]
     	    Property can be used to specify the location of study condition scripts which will be executed before the recording
    	    starts. The provided file name should be like ${CONDITION_NAME}.sh
        --conditions '0..N' [Default: --conditions [1, 2]]
     	    Property can be used to specify the conditions of this study.
        --data-prefix 'STRING' [Default: --data-prefix /vol/csra/data/persistent/study]
     	    Property can be used to specify the data path where all the recordings should be stored. Be aware that this path is just a
    	    prefix and the study name  + condition + participant id are automatically added as sub folders.
        --name 'STRING' [Default: --name ]
     	    Property can be used to specify the name of the study.
        --participant-id 'STRING' [Default: --participant-id ]
     	    Property can be used to specify initial participant id.
        -h | --help [Default: -h null]
     	    Print this help screen.
        -v 'BOOLEAN' | --verbose 'BOOLEAN' [Default: -v false]
     	    Prints more information during execution to stdout.

**Related projects:** rsbag-record-server, video-recorder, generic-display

.. attention:: Its your responsibility to **make sure your participants has sign the data privency** form before you start the recoding.

.. _start_stop_routine:

Start and Stop Routine
-----------------------

What happens if the record button is pressed?

1. Execute Condition Script
2. Execute Start Script
3. Start RSBag Recording
4. Start Video Recording


What happens if the stop button is pressed?

1. Execute Stop Script
2. Stop RSBag Recording
3. Stop Video Recording

Control Scripts
---------------

The study control application supports a **start**, **stop** and a **condition** bash script. Those scripts can for example be used to prepare study specific setups, start and stop vdemo components or backup further log files. Within the scripts the following environment variables are provided:

* ``${STUDY_NAME}`` The defined name of the study.
* ``${STUDY_PARTICIPANT_ID}`` The participant id of the current run.
* ``${STUDY_CONDITION}`` The condition of the current run.
* ``${STUDY_RECORD_PATH}`` The path where the recording is stored.
* ``${STUDY_RECORD_FILE}`` The filename prefix used for this run.

Please have a look at section :ref:`start_stop_routine` to figure out when which script is executed.

The script header should set the ``-e`` and ``-o pipefail`` flags. By this the script execution is directly canceled in case one of the commands has failed:

.. code-block:: bash

    #!/bin/bash

    set -e
    set -o pipefail

VDemo base components can be started or stopped via the following command:

.. code-block:: bash

    rsb-send [start|stop] $COMPONENT_NAME /vdemo/base

To inform your participant about the study start or giving them condition related instructions, you can use the generic display remote to send messages on all screens which are providing a generic display server.

.. code-block:: bash

    generic-display-send -m "Du kannst mit dem ${STUDY_CONDITION}. Studienteil beginnen"

.. note:: Because of some ssh fingerprint and handshake issues within the csra network infrastructure it is recommended to switch of the ssh publish key verification and known host checks via ``ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no``) if you trigger any remote actions. Otherwise it happens quite often that your scripts block until timeouts are reached before the actions are finally canceled.

In the following are two example scripts listed to get an idea how they can look like.
A complete start script example:

.. code-block:: bash

    #!/bin/bash

    set -e
    set -o pipefail

    export HOME="/homes/csracontrol"

    source $HOME/study/bcomfy//bcomfy_study_config.sh
    source /vol/csra/releases/xenial/lsp-csra-nightly/etc/vdemo_scripts/lsp-csra-config.sh

    generic-display-send -m "BComfy Studie"

    echo "Creating new directory on ${STUDY_PC_RECORDING} to allow video recording..."
    ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_RECORDING} "mkdir -p ${STUDY_RECORD_PATH}"

    echo "Resetting database on ${STUDY_PC_BCO} and checking out new branch for participant ${STUDY_PARTICIPANT_ID} and condition ${STUDY_CONDITION}..."
    ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_BCO} "/home/csracontrol/study/bcomfy/bcomfy_study_database_start.sh ${STUDY_PARTICIPANT_ID} ${STUDY_CONDITION}"

    echo "Deleting BCO log on ${STUDY_PC_BCO} to initialize a new log..."
    ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_BCO} "rm -f /tmp/log/csracontrol/VDEMO_component_bco_openhab.base-cube-one.log"

    echo "Starting BCO..."
    rsb-send start bco_openhab /vdemo/base

    echo "Starting video recording for participant ${STUDY_PARTICIPANT_ID} and condition ${STUDY_CONDITION} on phab 2 pro over ${STUDY_PC_ADB}..."
    ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_ADB} "screen -dmS record_video bash -c './record_video.sh ${STUDY_PARTICIPANT_ID} ${STUDY_CONDITION}'"

    echo "Starting log recording of phab 2 pro on ${STUDY_PC_ADB} for participant ${STUDY_PARTICIPANT_ID} and condition ${STUDY_CONDITION}..."
    ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_ADB} "screen -dmS record_log bash -c './record_log.sh ${STUDY_PARTICIPANT_ID} ${STUDY_CONDITION}'"

    echo "Starting bcomfy application on phab 2 pro over ${STUDY_PC_ADB}..."
    ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_ADB} "adb shell monkey -p org.openbase.bco.bcomfy 1"

    generic-display-send -m "Du kannst den ${STUDY_CONDITION} Teil beginnen"

A complete stop script example:

.. code-block:: bash

    #!/bin/bash

    set -e
    set -o pipefail

    export HOME="/homes/csracontrol"

    source $HOME/study/bcomfy/bcomfy_study_config.sh
    source /vol/csra/releases/xenial/lsp-csra-nightly/etc/vdemo_scripts/lsp-csra-config.sh

    echo "Stopping bcomfy application on phab 2 pro over ${STUDY_PC_ADB}..."
    ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_ADB} "adb shell am force-stop org.openbase.bco.bcomfy"

    echo "Shutting down log recording of phab 2 pro on ${STUDY_PC_ADB}..."
    if ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_ADB} "screen -list" | grep -q "record_log quit"; then
        ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_ADB} "screen -X -S record_log quit"
    else
        echo "Log recording of phab 2 pro not running..."
    fi

    echo "Shutting down video recording on phab 2 pro over ${STUDY_PC_ADB}..."
    if ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_ADB} "screen -list" | grep -q "record_video quit"; then
        ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_ADB} "screen -X -S record_video quit"
    else
        echo "Video recording of phab 2 pro not running..."
    fi

    echo "Stopping BCO on ${STUDY_PC_BCO}..."
    rsb-send stop bco_openhab /vdemo/base

    echo "Waiting for BCO on ${STUDY_PC_BCO} to quit..."
    set +e
    while ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_BCO} "screen -list" | grep -q "bco_openhab.base-cube-one"; do sleep 3; done
    set -e
    echo "BCO on ${STUDY_PC_BCO} stopped."

    echo "Copying BCO log from ${STUDY_PC_BCO} to study record path on ${STUDY_PC_RECORDING}..."
    ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_BCO} "scp -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no /tmp/log/csracontrol/VDEMO_component_bco_openhab.base-cube-one.log csracontrol@${STUDY_PC_RECORDING}:${STUDY_RECORD_PATH}/bco-condition-${STUDY_CONDITION}.log"

    echo "Copying BComfy log from ${STUDY_PC_ADB} to study record path on ${STUDY_PC_RECORDING}..."
    scp -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no csracontrol@${STUDY_PC_ADB}:/home/csracontrol/${STUDY_PARTICIPANT_ID}_${STUDY_CONDITION}.log /tmp/${STUDY_PARTICIPANT_ID}_${STUDY_CONDITION}.log
    scp -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no /tmp/${STUDY_PARTICIPANT_ID}_${STUDY_CONDITION}.log csracontrol@${STUDY_PC_RECORDING}:${STUDY_RECORD_PATH}/bcomfy-condition-${STUDY_CONDITION}.log
    rm -f /tmp/${STUDY_PARTICIPANT_ID}_${STUDY_CONDITION}.log

    echo "Committing new database on ${STUDY_PC_BCO} for participant ${STUDY_PARTICIPANT_ID} and condition ${STUDY_CONDITION}..."
    ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no ${STUDY_PC_BCO} "/home/csracontrol/study/bcomfy/bcomfy_study_database_stop.sh ${STUDY_PARTICIPANT_ID} ${STUDY_CONDITION}"

    generic-display-send -m "Teil ${STUDY_CONDITION} ist abgeschlossen"

Study specific Preparations
---------------------------

Create your Study Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create your study specific preconfigured vdemo component in the study tab of the lsp-csra-supplementary vdemo script. Here is an example config:

.. code-block:: bash

   study-control, ${PC_WORK_CONTROL_TOUCH}, -l -x -n -L 8 -g study -v STUDY_NAME=bcomfy -v CONDITIONS=\"1 2\" -v START_SCRIPT=/homes/csracontrol/study/bcomfy/bcomfy_study_start_procedure.sh -v STOP_SCRIPT=/homes/csracontrol/study/bcomfy/bcomfy_study_stop_procedure.sh -t study-bcomfy:

Available environment variables provided by the ``component_study-control`` script are the following:

* ``-v STUDY_NAME``
* ``-v CONDITIONS``
* ``-v CONDITION_SCRIPT_DIRECTORY``
* ``-v START_SCRIPT``
* ``-v STOP_SCRIPT``

Those variables are just used to pass through the values as startup parameter, please have a look in section :ref:`system_help` for more details about the meaning of each parameter.

Setup Depending Components
^^^^^^^^^^^^^^^^^^^^^^^^^^

The study control application depends on some recorder vdemo components to control the rsbag and video recording if enabled. To guarantee a proper performance please verify the following steps within the default tab of the lsp-csra-base vdemo script:

* The core spread daemons should be started.
* The ``rsb_recordserver`` is started.
* The ``auto-record`` is stopped and its recommended to exclude it from the autostart.
* The ``video-recorder`` is started.
* The ``video-autorecord`` is stopped and its recommended to exclude it from the autostart.

Usage Guidelines
----------------

.. note:: It is recommended to start the study control application on machine ``syd`` because those has a touch screen attached. Furthermore its recommended to display the apartment cams on the 4K screen via the machine ``fra`` which is already configured by default.

1. Enter the participant id of the next run.
2. Choose your condition

.. figure:: /images/study-control_setup.png
    :scale: 100 %
    :alt: study-control

3. Press the ``Record`` button.

.. figure:: /images/study-control_prepare.png
    :scale: 100 %
    :alt: study-control

4. Wait until the feedback box is red ("Recording Started") to verify that the recording has been successfully started.

.. figure:: /images/study-control_recording.png
    :scale: 100 %
    :alt: study-control
    
5. Do your study run.
6. Press the ``Stop`` button.
7. Wait until the feedback box is blue ("Recording Stopped") to make sure all stop routines are finished.

.. figure:: /images/study-control_stopped.png
    :scale: 100 %
    :alt: study-control

In case an error occurs during any step the feedback box is chanches its color to orange.
Check out the displayed log messages to find out whats happened.

.. figure:: /images/study-control_warn.png
    :scale: 100 %
    :alt: study-control

.. note:: If the record light in the control room is reachable, all states are visualized here as well.

Issues
------

Issues can be reported via github: https://github.com/csra/study-control/issues/new