CS 639 — GE Healthcare: Patient Device Association "PatientSync"

An app that aims to allow nurses to quickly and easily associate a patient with a GE Connect+ device.

Link to GitHub repository: https://github.com/cxhuy/cs639-gehealthcare-1

Note

This document will outline the basic steps on how to get the project running. These instructions were written under the assumption that you are using a Windows 10 or 11 device to host the Expo server and the placeholder Bluetooth devices, and using a separate Linux (or WSL) machine to run the placeholder backend, but this is not the only option available. All components (with the exception of Zadig, which is only used to manage drivers when using a real Android device) are compatible with macOS and Linux, but you'll need to adapt the instructions slightly.

This project was initially created using expo's pnpx create-expo-app with Node.js version 20.5.1, and npm version 9.8.0.

Overview

This project contains three components:

1. Mobile app
   • Built using React Native
   • Tested and demoed on Android 14, untested but should be buildable on iOS
   • Contents of this component are the majority of this repository
2. Placeholder ("Fake") GE Connect+ device
   • Built in Python using Google's bumble module
3. Placeholder backend
   • Built using Flask

It is perfectly fine to host all three services on one machine, it is also okay to completely seperate them.

Components

Mobile App

• There are two options for running the app, complete steps for each option are listed below
• It is only necessary to complete the steps under the installation sections once per machine
• The mobile app's contents are the majority of the directories and loose files in this repository, excluding the bumble_custom and flask_server directories

Placeholder / Fake GE Connect+ Device

Note

Due to an apparent limitation of Google's bumble module, it is only possible to launch one Placeholder GE Connect+ device per USB adapter using this implementation. If you choose to use the app inside of an Android Virtual Device, then you may launch several Placeholder GE Connect+ devices at once. If you'd like to launch more than once device, make sure to set the LAUNCH_MULTIPLE_DEVICES variable at the top of bumble_custom/gehc_sample_devices.py to True

• The files associated with the placeholder device(s) are located in the bumble_custom directory, with the exception of the two firmware (.bin) files floating free in the root folder of the repository
• There are also two options for launching this device, which directly map to your choice for how you plan to run the mobile app; the functionality of the device remains the same across options
• A sample configuration file for these devices is located at bumble_custom/multiple_devices.json
  • See also these sample configuration files from Bumble itself for more device-specific configuration options: [1] [2] [3]
• The devices serve a simple GATT server with a couple modifiable attributes
• The device does not support more than one simultaneous connection on purpose and does not currently implement a connection or disconnection timeout; this means that, if the app crashes (hopefully it doesn't!), the user leaves their phone somewhere for a long period of time, or for some reason the connection between the app and device is not destroyed, the device will not appear in the app; restart the placeholder device to resolve this

Warning

There is no use of encryption, security, or authentication in the transfer of data to or from the placeholder Bluetooth device. This placeholder device should absolutely not be used in an untrusted or unsecured environment.

Launching the Placeholder GE Connect+ Device(s)

Launch the devices with python3 bumble_custom/examples/gehc_sample_devices.py (device configuration file) (interface) (path to data directory)

• If using Android Studio with an Android Virtual Device, use android-netsim for (interface)
• If using a real Android device, use usb:(id) for (interface), where (id) is replaced by the ID of the Bluetooth device as reported by bumble's usb_probe app, which was downloaded along with the bumble source files during installation
  • The firmware files for the USB adapter you're using must be located in the directory that you launch the gehc_sample_devices.py file from; we've included the firmware files for the adapter we used (see the relevant prerequisites for a link to purchase this exact adapter)
• The device configuration file defines the starting values for devices, as well as which devices should be used
• The data directory defines where the device's GATT information should be stored
  • This includes information about the device's most recently connected patient (their MRN), the most recent time of change, along with a few other attributes
  • To clear a device's saved information (associated patient, for example), simply delete its corresponding file in the data directory
• Example using an Android Virtual Device (executed from the topmost repository directory): python3 bumble_custom/examples/gehc_sample_devices.py bumble_custom/examples/multiple_devices.json android-netsim data
  • Example using a real Android device (also executed from the topmost repository directory): python3 bumble_custom/examples/gehc_sample_devices.py bumble_custom/examples/multiple_devices.json usb:0 bumble_custom/examples/data

Flask Server / Placeholder API

Note

In the current implementation of this simple server, changes to the patients.json file are not taken into account, you must restart the service for these changes to be applied.

• This simple Flask server serves patient data when given an MRN. It is not recommended to use any kind of solution similar to this in a production scenario, as this lacks any notion of security
• The system that this runs on must support Python (version >= 3.12 recommended), as Flask is a Python module
• The system that this runs on must be reachable from the mobile device that the mobile app is running on

Launching the Flask Server

Important

The following instructions assume that the server host is a Linux machine (or using WSL). Please adapt the instructions if you are using another operating system to host the Flask server.

1. Copy the flask_server directory onto the host
2. While in the flask_server directory, start the server with nohup python3 main.py
   • To stop the server, use ps to find the process ID and then use kill -9 [pid]

Option 1: Using Android Studio with an Android Virtual Device

Prerequisites

• Node.js and npm
• Android Studio (version >= 2023.2.1)
  • The following SDK Tools are recommended (install or make changes by launching Android Studio, then on the Projects tab, select 'More Actions', and then 'SDK Manager'):
    • Android SDK Build-Tools
    • NDK
    • Android SDK Command-line Tools
    • CMake
    • Android Emulator
    • Android Emulator hypervisor driver (installer)
    • Android SDK Platform-Tools
    • Google Play Licensing Library
    • Google Play services
• Python 3.12 or later (for the placeholder devices and Flask server)
• Somewhere to run a Flask server (see requirements in above section)

Caution

Trying to open the native camera while using the Android Virtual Device and Expo will cause the app to crash. This is due to a limitation in either Expo, Android's Virtual Device framework, or the combination of the two. To avoid this, please use manual input when using a Virtual Device.

Installation

1. Download Google's bumble module to a separate directory, and navigate to that directory
2. Install bumble's dependences: python -m pip install ".[test,development,documentation]"
3. Install the bumble module to your system: python -m pip install -e .
4. Navigate to this project's directory and nstall this project's packages: npm i
5. Install eas-cli: npm i -g eas-cli
6. Log into Expo App Services: eas login
7. Build the .apk: eas build -p android --profile preview
   • You can also run a plain eas build -p android to get an .aab file, which can be uploaded to the Google Play store
   • You can ALSO run a plain eas build for the option to build to iOS (untested!)
8. Create and start an Android Virtual Device through Android Studio
   • Project was tested on the Pixel 8 API 34 (Android 14.0 "UpsideDownCake"), and it's recommended you use this version or later
   • You may need to enable developer mode and USB device connections on the device
9. Download the .apk from Expo
10. Install the .apk on the Android Virtual Device by dragging and dropping
11. You are now ready to launch!

Launching

1. Ensure that the Flask backend is launched using the instructions in the section 'Launching the Flask Server' above
2. Launch the placeholder Bluetooth device using the instructions in the section 'Launching the Placeholder GE Connect+ Device(s)' above
3. Start the Android Virtual Device through Android Studio, and wait for it to fully boot
4. Start the Expo server for the mobile app with npm run android
   • This should automatically launch the app
   • If this doesn't launch the app, you can try pressing 'a', or opening it manually on the virtual device and inputting the IP address of the machine that the Expo server is hosted on
5. The app should now stream the required resources from the Expo server and afterwards load

Option 2: Using a real Android Device

Prerequisites

• Node.js and npm
• Android device (Android >= 14 recommended)
• Compatible Bluetooth adapter
  • Bluetooth adapters must have a Realtek radio chip to be compatible with the bumble module
  • You must be able to locate the .bin firmware associated with it
  • Some Realtek firmware DL sources: (1), (2), (3)
  • The Bluetooth adapter we used for this project and our demos is this one
• Python 3.12 or later (for the placeholder devices and Flask server)
• Somewhere to run a Flask server (see requirements in above section)

Important

It is recommended that you back up or locate the existing driver that's associated with your Bluetooth adapter before proceeding, or alternatively create a restore point on your machine. Use of a Bluetooth dongle with the fake device requires the installation of a libusb driver onto your device using Zadig, which will overwrite the current driver association on your machine. This should not damage or otherwise harm the internal workings of the Bluetooth adapter, only changing the driver used with it.

Installation

1. Download Google's bumble module to a separate directory, and navigate to that directory
2. Install bumble's dependences: python -m pip install ".[test,development,documentation]"
3. Install the bumble module to your system: python -m pip install -e .
4. Navigate to this project's directory and nstall this project's packages: npm i
5. Install eas-cli by executing npm i -g eas-cli
6. Log into Expo App Services by executing eas login
7. Build the .apk by executing eas build -p android --profile preview
   • You can also run a plain eas build -p android to get an .abb file, which can be uploaded to the Google Play store
   • You can ALSO run a plain eas build for options to build to iOS (untested!)
8. Download the .apk from Expo
9. Transfer the .apk to the Android device that you're using
10. Navigate to the download point, and install the .apk on the Android device
    • You may need to enable developer mode and (optionally) USB device connections on the Android device that you're using
    • You may need to go through several UAC prompts
11. Download and extract Zadig
    • We'll use this tool to install the libusb driver onto the Bluetooth dongle
12. Launch Zadig and under the 'Options' toolbar, select 'List All Devices'
13. Select your Bluetooth adapter, and select libusb-win32, leave all other settings on their default
    • This project uses version 1.2.7.3 of libusb-win32, it is recommended to use this, or a more recent, version
14. Press 'Replace driver' and wait for the driver installation to finish
15. You are now ready to launch!

Launching

1. Ensure that the Flask backend is launched using the instructions in the section 'Launching the Flask Server' above
2. Launch the placeholder Bluetooth device using the instructions in the section 'Launching the Placeholder GE Connect+ Device(s)' above
3. Start the Expo server for the mobile app with npm run android
4. Open the app on your Android device
   • If the device is connected to your host device with a USB cable, this may automatically launch the app on your device; you can also press 'a' to trigger this after launch
5. The app should now stream the required resources from the Expo server and afterwards load

What Works?

All features presented to the user in our app are functional.

What Doesn't?

There are several features that we had on our stretch list and were hoping to add but did not get around to (some are listed below this, in the Further Steps section). In addition to these, we ran into a short list of limitations based on libraries and modules we used:

• Trying to use or open the camera within the Android Virtual Device will crash the app
• When scanning a barcode, the barcode must be mostly flat, or it will not be recognized and fail to scan

Apart from these, there are no functions advertised to the user in the app that are not functional.

Further Steps (to-dos)

• Implement encryption or authentication for placeholder devices
• Integrate application with an EMR
  • User authentication, patient record retrieval, audit logging, etc.
  • We were looking at using OpenEMR but felt its wide featureset was unnecessary for our simple use
• Implement a longer-tracking audit log for placeholder devices
• Add support for variable-length barcodes in a settings menu of the app
• Add debugging mode or display for raw information sent/received to and from the placeholder devices
• Add further animation and gesture support
• Improve UI features and make the app look more appealing
• Ensure cross-compatibility with iOS
• Add a field to include a reason for unlinking or overriding a patient (or even linking too!)
  • ex. New patient arrival, patient room change, patient discharge