AWARE-Light is a lightweight implementation of AWARE, with a core set of sensors and a focus on experience sampling, that only requires researchers to set up a MySQL database. AWARE-Light runs on Android devices, and those devices directly upload data to MySQL server, without any intermediate servers or cloud services.

Requirements

  • AWARE-Light runs on Android devices only (iOS not supported for now).
  • You will need a MySQL server that is accessible over the Internet, a database on that server, and administrator credentials. Your organisation may already manage MySQL servers, or you can opt for Amazon AWS, Microsoft Azure, or configure your own server user Docker.

Resources

  • The source code for AWARE-Light is available on Github.
  • The package to be installed on participants’ devices is here.
  • AWARE-Light configuration page.

How to run a study with AWARE-Light

  1. Visit the AWARE-Light configuration page. There, you can enter the details for your experiment. Once you have configured your study, you are able to download the configuration file onto your computer.
  2. Publish the configuration file. This file needs to be accessible by your participants. For example, you can use Dropbox or Google Drive to generate a link to the configuration file. Or you can upload this file to a website.
  3. Install AWARE-Light on participants’ device. Share this link with participants and ask them to install it, or you can do it yourself. The link is here.
  4. Load the configuration file. Send your participants a link to the configuration file (from Step 2). They will then need to open the AWARE-Light application, and paste the link into it. This will give them information about the study they are about to join, and will require them to consent to it.
  5. Data is received by your MySQL server. The software will upload data from participants’ phones to the server. Participants can only do a small number of things with the AWARE-Light client: see which sensors are being recorded on their device, opt out of the study, force-upload their data, and selectively disable sensors (if allowed by the study configuration).
  6. End the study. Instruct your participants to use the AWARE-Light application, and click the button to exit the study. At this point they will no longer be uploading their data to your server.

How to configure a study

When you visit the AWARE-Light configuration page, you will be taken through a series of forms where you define the parameters of your study, such as which sensors to use, which ESM questions to ask, and where to upload the data. This page does not permanently store any of the information you enter. When you have completed the configuration, the page will offer you to download a configuration file, which will contain all your desired settings.

When you visit the configuration page, click “Design your own study”.

At the next page, enter the information for your study.

  • The “Study Information” data is what the participants will see when they are asked to consent to take part in the study.
  • The “Database Configuration” is used by the page to initialise your database.
    • Enter you database server’s IP address, port number, and database name.
    • Enter the “INSERT-only” username and password that you would like to use. You can enter anything you want here, since the system will create these credentials.
    • Enter the ROOT username and password. These should be given to you by whoever set up your database server.
    • Press the “Initialise Database” button to allow the system to connect to your database and set it up.
    • Press the “Test Connection” button to ensure that the setup has been completed correctly.
    • NOTE: The root credentials are not permanently stored by the page.

In the next step you are able to define the ESM questions that will be triggered during your study. You can create multiple independent questions. For each question, you can determine its instructions, type (e.g. single choice, multiple choice, etc), and other relevant parameters.

Next, you can create schedules that trigger your questions. There is a range of scheduling options. You can create multiple schedules, and each schedule can include multiple questions. Any given question can be associated to multiple schedules. The questions are triggered in the order that they appear in the schedule.

Next, you can define which sensor data will be reported by participants’ devices. You can define when & how the data is uploaded, and you can activate any sensor that is available in the list. When certain sensors are selected, there are additional parameters that need to be defined. Please read the AWARE documentation to get more details regarding the sensors and their behaviour.

There are certain important settings that you need to consider. “Offload frequency” determines the frequency at which the mobile app will try to send the collected data to the database. “Config update frequency” is the frequency at which the mobile app will try to fetch the study config to see if there is any updates to the study. “Enable settings update” allows the participants to selectively disable sensors on their phone.

In the final step, you are able to see an overview of the configuration. Click the “Download” button to download the configuration file onto your computer. This is a file in .json format, and contains all the above configuration settings. You need to publish this file, and send a link to this file to your participants. For example, you can use Dropbox or Google Drive to generate a link to this file.

For instance, to publish the configuration file using Google Drive, you can store the file in your Google Drive directory, right-click on the file, and select “Get Shareable Link”.

Finally, you need to send this link to your participants. They will first have to download and install AWARE-Light, and launch it. They, they will need to enter the link into the AWARE-Light app in order to join the study. Your participants need to click in the app the “Sign Up” button, and then they will be asked to provide the URL of the configuration file.

Next, your participants will be able to see the details of the study, and will also have the opportunity to provide an “onboarding” code. This can be their name, a participant code that you have given them, or any string. This string can help you disambiguate the data from all your participants. Note that even if two participants enter the same on boarding code, the underlying software will still generate a long unique ID that is used to tag all data uploaded to your server.

Now that your participants are onboarded and enrolled in your study, they will be able to see which sensors are being recorded, as well as quit the study. In addition, they are able to force the phone to check for an updated version of the configuration file, and force the phone to upload all collected data.

How to update an existing study

The AWARE-Light configuration page allows you to update an existing study. On the main page click on “Update an existing study”. You will then be prompted to upload your current configuration file. Once that happens, then the pages are populated with your settings, and you are able to update them as you wish, and download the updated configuration file.

It is also possible to also manually edit the configuration file. For example, this can be helpful if you have made a spelling mistake. You can open the configuration file with a text editor (such as Notepad), and edit the file directly. WARNING: By doing so, it is possible that you accidentally damage the configuration file, for example if you damage the syntax of the file. Only use this approach if you know what you are doing.

Once you have a new configuration file, then you can publish it at the same URL where the previous configuration was published. In this way, all your participants’ devices will eventually read the new configuration file and update their behaviour. If you use Dropbox or Google Drive, then please overwrite the previous configuration file with the updated configuration file.