CRADLE VSA System: Android Application

Android application for the CRADLE VSA System, a technological health care system to improve maternal care and reduce preventable maternal deaths in Ugandan villages.

The Cradle VSA (Vital Signs Alert) is a portable medical device that can read a patient’s blood pressure and heart rate, mainly used to detect abnormalities during pregnancy. The Cradle VSA application can record the readings taken by the Cradle VSA device and upload it to the server. Our application is designed for remote areas with an unstable internet connection, so we implemented an SMS feature.

Setup

The app mostly uses Kotlin with some Java code leftover.

Install Android Studio and import the project by cloning the Git repository.

You will need to set up Platform in order to set up Mobile! https://github.sfu.ca/bfraser/415-Cradle-Platform/blob/main/docs/development.md

Useful Documentation:

• Cradle Mobile Onboarding https://docs.google.com/document/d/1okJHo1OMfRZbkep-37rOIpApkXmZgxp1Uwmf_Evaguo/edit

• Mobile Testing with Local CradlePlatform https://docs.google.com/document/d/1ohbJqzYMEzDeSj_EVndMZvnp9ShB1A1q682QIcr-hNE/edit

Spring 2024 Set Up:

• File -> Project Structure -> Project
  • Android Gradle Plugin Version: 8.2.1
  • Gradle Version: 8.2
• File -> Settings -> Build, Execution, Deployment -> Build Tools -> Gradle
  • Gradle JDK: JetBrains Runtime version 17
  • If it's not one of the options, click on "Download JDK" and select the version mentioned above

Before you log in you must open app settings and change the following:

• Make sure the "Use HTTP" switch is OFF
• Hostname: 10.0.2.2
• Port: 5000

Architecture

We use various components from Android Jetpack and other libraries:

• Room is used for managing the SQLite3 database.
• ViewModels are used to handle the bulk of the logic code in some areas of the app so that the Activities / Fragments focus on UI-related code.
• The Data Binding Library is used in areas to reduce the amount of boilerplate code.
• WorkManager is used to run syncing in the background.
• The Paging 3 library is used with Room for pagination of RecyclerViews.
• The Navigation component is used in some places such as the new patient / reading creation Activity to navigate between fragments.
• Espresso is used for UI tests. Also we use mockk for mocking in unit tests.

Pre-push Git hook

The pre-push hook can be found in hooks/pre-push.sh. When the Git hook is setup, it ensures that the static code analysis and the unit tests pass before pushing to the remote repo. If one of those verification tasks fail, your commits won't be pushed to the repo, and Android Studio or the command line will notify you about it. The issues uncovered would've been caught by the CI pipelines anyway. (There are options in the push modal in Android Studio to not run Git hooks, but this isn't recommended.)

Follow the below instructions for your development environment to setup the Git pre-push hook. After setting it up, you can verify that it is setup properly by trying to push a commit via the command line / terminal: git push. It should display the static code analysis and unit tests in the window before pushing. Android Studio has the ability to also run these hooks using the Git push interface in Android Studio, but it's not as verbose about it unless there's a failure.

Mac and Linux

Run the setup-hooks.sh script, which should set up the symbolic links targeted in .git/hooks automatically:

hooks/setup-hooks.sh

Windows

Run the following command as an Admin

mklink .git\hooks\pre-push ..\..\hooks\pre-push.sh

Or, for PowerShell, run the following command as an Admin

New-Item -ItemType SymbolicLink -Path .\.git\hooks -Name pre-push -Value .\hooks\pre-push.sh

Tests

Unit tests

The app has some unit tests that can be run directly on a host computer via Android Studio or the command ./gradlew test.

These unit tests are run by the CI pipelines to verify merge requests and commits on master. They're useful in ensuring there haven't been any regressions. Make sure the hooks from above are setup to make it so that the unit tests are run automatically before you push to the remote repo.

Instrumented tests

The app has some instrumented tests meant to be run on a physical or emulated device. These can also be run directly in Android Studio, or via the command ./gradlew connectedAndroidTest.

These tests are not run automatically, and these tests are not run by the CI pipelines. Nevertheless, they're important, as they test various things such as database migrations and UI flows automatically. These should be run often (at least once before a new release).

UI tests

The UI tests need special setup on the device to be run.

1. Follow the Set up your test environment instructions outlined in https://developer.android.com/training/testing/espresso/setup#set-up-environment:

   To avoid flakiness, we highly recommend that you turn off system animations on the virtual or physical devices used for testing. On your device, under Settings > Developer options, disable the following 3 settings

   • Window animation scale
   • Transition animation scale
   • Animator duration scale

2. Uninstall or log out of the app if it's already installed. The UI tests LoginActivity, and those tests can fail if already logged in.

Pinning TLS certificate public keys

We're currently pinning TLS public keys for the server. There are two ways to setup pinning: by following OkHttp's guide or by using the bash script located in scripts/x509-subject-pubkey-hash.sh. If you're paranoid, try both ways and see if the pins match up.

Other links

Check Wiki for technical details