Configuration File

The device is configured via a configuration file on it's micro-SD card. Make sure the micro-SD card is formatted as FAT32. The configuration file needs to be called config.json and be placed in the micro-SD card's root directory. This is the name and location the device will expect, so anything else will not work.

We recommend using our Configuration Tool (found at https://github.com/KL-Psychological-Methodology/TWatch-2020-ESM-Configuration-App) to generate the configuration files.

Configuration File Format

The configuration file is written in JSON format (JavaScript Object Notation). It is a plain text file, and can be opened and edited with any text editor, although we recommend a code editor that recognizes the format if you want to edit it directly, as even small errors can cause invalid JSON syntax and thus unexpected behavior of the device. A good code editor will alert you to syntactic errors in the format.

The following is an example of a minimal configuration file (you can find this file at https://github.com/KL-Psychological-Methodology/TWatch-2020-ESM/blob/main/doc/code/config.json):

{
  "study_name": "ExampleStudy",
  "data": [
    {
      "name": "Questionnaire 1",
      "active": true,
      "event": false,
      "alarms": [
        {
          "H": 9,
          "M": 0,
          "dur": 59,
          "exp": 5,
          "repeat": 2
        }
      ],
      "items": [
        {
          "item": "item 1",
          "type": "likert",
          "prompt": "Do you like this configuration format?",
          "res": 5,
          "l_lab": "not at all",
          "r_lab": "very much"
        }
      ]
    }
  ]
}

The root object has two keys:

• study_name sets the study name. This name will be used in the file names of the log and response files.
• data is an array containing objects for the individual questionnaires.

A note on optional keys

Some of the keys used are optional. Whenever the device tries to read a value that isn't present it will read it as 0, false, an empty string, or an empty array, depending on the expected data type (if not noted otherwise). This means that setting "event": false and skipping the event key will have the same effect.

Questionnaire Configuration

Questionnaires are objects in the data array. The following keys are used to define Questionnaires:

• name is the questionnaire's name, used to identify it in the log and response files. This name will also be used in notifications and/or event lists shown displayed to the participants, so it is recommended to choose something expressive. Questionnaire names must be unique, as the device will use the name to find configurations for the appropriate questionnaire.
• active: Whether or not the questionnaire is used in the study. If set to false the questionnaire will be ignored by the device. This can be useful if you want to disable a configured questionnaire but want to keep the configuration for a later study, etc...
• event: For event-based scheduling. Will add the questionnaire to a list of event-based questionnaires that are always available for the participant to select. Use this if the participant should be able to start the questionnaire on their own. Can be used in addition to notifications.
• alarms: An array of the time configurations for when notifications for the questionnaire should be triggered. See further down below how these times are configured.
• items: An array with definitions for individual items. See the entry for Item Definitions for details.
• randomize: An array of arrays defining ranges of items to be randomized. Each subarray needs to have exactly two integer members, defining the start index and end index of the randomization range (with the first item being counted as item 1). Items in these ranges will be presented in a randomized order. E.g., if the first and seventh item have instruction text, and should always be presented at those positins, but the five items following each of those (i.e., items 2 to 6 and items 8 to 12) should be presented in random order, then this can be defined using "randomize": [2, 6], [8, 12](/KL-Psychological-Methodology/TWatch-2020-ESM/wiki/2,-6],-[8,-12).

Notification Configuration

Each questionnaire can configure multiple times that notifications should trigger. Notifications will alert the participant to their presence using the vibration motor, and display an option to either start the corresponding questionnaire or cancel them.

Notifications are defined as objects in the alarm array. The device allows both for fixed time notifications an random notifications in a time interval. These can be defined as follows:

• H and M: The hour and minute each day the notification should occurr (for fixed times) or the random interval should start (for random time points).
• dur: The duration of the random interval. If set to zero or if omitted, then the notification will be elicited directly at the time defined by H and M. Otherwise this sets the maximum number after that time the notification can trigger (i.e., the nothfication will trigger somewhere between H:M and H:M+dur minutes).
• exp: The expiry time of the notification in minutes. If the device's screen is turned off after a notification is elicited, and then reactivated before the notification is expired, the notification will be displayed again. E.g., if exp is set to 5, and the participant initially ignores or misses the notification they have 5 minutes to activate the device on their own and thus still reach the triggered questionnaire, before the notification will not be displayed again on wakeup. Note that if exp is omitted the expiry time will be set to 15 minutes per default.
• repeat: The number of times the notification should be repeated on it's own after expiry. This can be used for reminders to trigger the vibration signal again in case the participant missed it before. This will happen as often as defined, each time after the expiry time is reached, or the participant has reacted. E.g., if repeat is set to 2 and exp is set to 5, then the notification will trigger again after 5 minutes, and then again five minutes later (provided the participant did not react). After five additional minutes it will normally expire, without another notification. Therefore in this case participants would have a total of 15 minutes to react to the questionnaire, and wound receive the notification three times. Note that the repeated notifications are logged as "repeat", rather than the usual "signal" that notifications are entered as.