Establish a health research system using Samsung Health Research Stack
Objective
Learn how to create a health research system that collects data from mobile and wearable devices and visualizes the collected data in a web portal using Samsung Health Research Stack.
Overview
Samsung Health Research Stack is an open-source toolset that helps collect and analyze data from devices in Android and Wear OS environments. It provides tools and infrastructure for developing and deploying health studies, ranging from medical research to clinician services and more.
The framework consists of four components:
-
backend services - offers API endpoints to access and interact with a robust data engine
-
web portal - a customizable interface for creating surveys, managing team members, tracking subjects, and analyzing data.
-
App SDK - an SDK for building Android and Wear OS apps capable of collecting data from wearable devices.
-
starter app - a health research app with mobile and wearable versions created using basic features provided by the App SDK.
For detailed information, see Samsung Health Research Stack.
Set up your environment
You will need the following:
-
Android Studio (latest version recommended)
-
Samsung Galaxy mobile device with updated Health Connect app and Samsung Health app installed
-
Samsung Galaxy Watch synced to the mobile device
-
Docker Desktop
Sample Code
To start your learning experience, download the project files of the Samsung Health Research Stack starter mobile and wearable app.
NoteDepending on your preferred development style, you can either download or clone the repository of the project files to your local computer. Feel free to edit and customize this project for your own purposes, including this Code Lab activity.
Set up your Galaxy mobile and watch device
-
Connect your Galaxy mobile device to your PC and enable adb debugging.
-
Next, connect your Galaxy Watch to Android Studio over Wi-Fi.
-
Lastly, enable the developer mode of the Health Platform app on your watch by following these steps:
a. Go to Settings.
b. Tap on Apps.
c. Select Health Platform.
d. Quickly tap on Health Platform several times until [Dev mode] appears.
NoteThe Samsung Health Developer Mode is only intended for testing or debugging your application. It is not for application users.
Deploy the backend and web portal locally
Download the backend-config-files.zip file and unzip it. The folder contains the docker-compose.yaml
file.
Open the terminal window of Docker Desktop.
In the terminal, go to the directory where your docker-compose.yaml
file is located, and run the following command:
$ docker compose up –d
The script deploys the backend and the web portal to your local computer, and it includes 6 services:
-
redis
- Redis watcher for the backend Casbin service.
-
mongo
- for saving data from the backend.
-
postgres
- for SuperTokens database and the backend Casbin database.
-
supertokens
- for username and password authentication
-
backend
- backend for the Samsung Health Research Stack.
-
portal
- web portal for the Samsung Health Research Stack.
You can change the port number, username, and password for each database.
With the default setting, you can access the web portal in your browser at localhost:80.
The script file has simple settings for easy deployment.
To add more features, you can change the environment in the docker-compose.yaml
file's services > backend > environment
part.
You can enable uploading and downloading features by setting the following AWS environment variables:
-
AWS_BUCKET_NAME
-
AWS_REGION
-
AWS_ACCESS_KEY_ID
-
AWS_SECRET_ACCESS_KEY
-
AWS_SESSION_TOKEN
You can follow the instructions in Using the Default Credential Provider Chain for setting up AWS credentials.
To enable Google OpenID Connect (OIDC) login, you can set the following environment variables.
You can refer to OpenID Connect for more information about setting Google OIDC.
Create a new study
The health research system has two user groups:
- Investigators - conduct research studies and use the web portal for managing studies and analyzing data.
- Subjects - participate in studies by answering surveys and performing tasks through the mobile app, as well as collecting health data from wearable apps.
To start your research study, as an investigator, follow the steps below:
- Create an account and sign in to the web portal page you deployed.
- Fill out the form with your information.
- On the Study Collection page, click the Create study button.
NoteAll enrolled investigators can create a study. The creator becomes the Study Admin.
- In the Basic Info tab, input the details of the study.
5.For the Study scope, choose Public.
NoteYou can set the study scope as either public or private. If you choose private, you need to input a participation code that subjects must enter into the mobile app to join. However, for the ease of testing in this Code Lab, it is recommended to set the scope as Public.
- For the Study requirements field, you can input any text and click Next.
-
Go to Participation requirements tab and select the data types to collect in Wear category. For this Code Lab, choose:
-
Wear Accelerometer
-
Wear ECG
-
Wear Heart Rate
- The logo and title of the created study show on the Study Collection page.
Connect the mobile app to backend system
To connect the starter mobile app to the backend system, follow these steps:
NoteTo ensure that the Galaxy mobile device can connect to the machine where the backend system is deployed, it is recommended to connect both the machine and the mobile device to the same network.
-
Open the downloaded project file in Android Studio and go to samples > starter-mobile-app.
-
In the local.properties
file, set the SERVER_ADDRESS
to the IP address of the machine where the backend system is deployed.
SERVER_ADDRESS ="input IP address here"
TipYou can check your IP address using the command line:
- Windows: In Command Prompt, type
ipconfig
and find the IP address under IPv4 Address.
- Mac: In Terminal, type
ifconfig
and look for the IP address under inet
next to en0
.
- Next, set the
SERVER_PORT
to 50001
if you used the default values in the provided docker-compose.yaml
file for deployment. If not, use the port number you set.
SERVER_PORT=50001
Set authentication method
The App SDK supports three types of authentication methods for registration:
-
samsung
utilizes Samsung Account
-
cognito
incorporates Amazon Cognito authentication
-
super-tokens
enables anonymous login.
To allow research participants to register and log in using their personal emails, set the SIGN_IN_MODE
as super-tokens
in the local.properties
file.
SIGN_IN_MODE="super-tokens"
Upload wearable data via gRPC
When synchronizing wearable device data, the App SDK offers two approaches: utilizing gRPC for high-performance remote procedure calls or synchronization through files.
Each approach has advantages and disadvantages regarding factors such as battery life and server workload.
However, it is advisable to utilize gRPC during local development. To configure the mobile application to upload wearable data via gRPC rather than files, add the following code in the local.properties
file:
ENABLE_UPLOAD_WEARBLE_DATA_BY_FILE=false
After configuring the mobile app, modify the wearable app to meet the requirements of your study.
Go to samples > starter-wearable-app and open the local.properties
file.
The wearable app features a Sync button, which can be displayed or hidden. When this button is pressed, it synchronizes the collected data with the backend system instantly.
To show the Sync button, set the value of ENABLE_INSTANT_SYNC_BUTTON
as below:
ENABLE_INSTANT_SYNC_BUTTON=true
NoteThis instant sync feature can negatively affect the battery consumption of both apps, so it is recommended to remove the Sync button when you publish your app. The Samsung Health Research Stack has an optimized data synchronization process that minimizes battery consumption.
Set data measurement parameters
You can customize the data collection and storage process of the wearable app by setting the values of the following data measurement parameters:
-
PASSIVE_DATA_INSERT_INTERVAL_IN_SECONDS
sets the data measurement buffer. The buffer saves data in an in-memory database before the interval expires. Then, at regular intervals, the data from the buffer is stored in persistent memory.
-
DATA_SPLIT_INTERVAL_IN_MILLIS
specifies the size of segmented data in persistent memory.
If these values are not specified, the wearable app uses its default values.
To verify that the data is being measured and synchronized instantly, you can set the values as follows:
PASSIVE_DATA_INSERT_INTERVAL_IN_SECONDS=12
DATA_SPLIT_INTERVAL_IN_MILLIS=30000
Run the starter mobile and wearable app
After configuring the local properties of both starter apps, build and run your app in Android Studio by following these steps:
Run the starter mobile app
-
Select your mobile app (starter-mobile-app) from the run configurations menu in the toolbar.
-
Choose a connected Galaxy mobile device as the target device for running the app.
-
Click Run to install the app.
-
After installation, clear the app's data.
Run the starter mobile app
-
Follow the same steps as for the starter mobile app but select starter-wearable-app instead.
-
Choose a connected Galaxy Watch device for running the app.
-
Allow the app to access physical activity, sensor data, and send notifications when prompted.
- Ensure that the Galaxy Watch is connected with the Galaxy mobile device.
Register and join a study
Since you have set super-tokens
as the authentication method, you can now register and log into the app at once.
- Open the starter mobile app and sign up with an unregistered email address.
- After logging in and accepting permissions, the app displays the study you created from the web portal. Tap on the study card to view its details and click Join Study.
NoteIf a study is set to private and you wish to join it, press Enter the study code located at the top of the screen and input the assigned participation code in the Study Code field.
-
Agree to data collection and terms of research. You can see that the sensor data to be collected are dependent upon the selection made in the web portal while creating the study.
-
Sign and click Next to complete the study onboarding process.
Measure and collect health data
In the starter wearable app, you can see a list of on-demand measurements that you can contribute to health research.
- For this Code Lab, choose ECG and click Measure.
- Follow the onscreen measurement instruction.
- After measuring successfully, scroll to the bottom of the wearable app and press the Sync button to synchronize the data with the mobile app.
- In the mobile app, go to Data tab, click the more button, and click Sync to transfer the collected data to the web portal.
Visualize the collected data in web portal
You can display the collected data as a graph in any way you choose for further analysis of the study.
- From the Overview page of the study in the web portal, navigate to the Dashboard page.
- Click on the Add chart button.
- Provide a title for the chart and select the desired chart type. Then, edit the Chart source.
-
Choose the database where the data is stored.
-
For this Code Lab, enter the following query to display only the first ten heart rate data from wearHeartRate
table.
SELECT * FROM wearHeartRate LIMIT 10
- Click Run Query and Save.
-
Select value and timestamp for the Value and Category columns respectively.
-
Check the preview of the graph.
- Finally, click Save to display the graph into the Dashboard.
You're done!
Congratulations! You have successfully achieved the goal of this Code Lab. Now, you can create your own health research system by yourself!
To learn more, see Samsung Health Research Stack.