6.1. 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.

6.1.2. Start and Stop Routine¶

What happens if the record button is pressed?

Execute Condition Script
Execute Start Script
Start RSBag Recording
Start Video Recording

What happens if the stop button is pressed?

Execute Stop Script
Stop RSBag Recording
Stop Video Recording

6.1.3. 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 Start and 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:

#!/bin/bash

set -e
set -o pipefail

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

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.

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:

#!/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:

#!/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"

6.1.4. Study specific Preparations¶

6.1.4.1. 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:

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 Related resources for more details about the meaning of each parameter.

6.1.4.2. 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.

6.1.5. 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.

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

Press the Record button.

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

Do your study run.
Press the Stop button.
Wait until the feedback box is blue (“Recording Stopped”) to make sure all stop routines are finished.

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.

Note

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

6.1.6. Issues¶

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

6.1. Study Control¶

6.1.1. Related resources¶

6.1.2. Start and Stop Routine¶

6.1.3. Control Scripts¶

6.1.4. Study specific Preparations¶

6.1.4.1. Create your Study Configuration¶

6.1.4.2. Setup Depending Components¶

6.1.5. Usage Guidelines¶

6.1.6. Issues¶