How to setup FreeStyle Libre 2 and OOP2 to use a native Bluetooth connection in xDrip+

Updated: Nov 14, 2021


Summary


First a big THANK YOU to @tzachi-dar for developing this application so that all of us with a FreeStyle Libre 2 can enjoy receiving and calibrating readings without the need for a 3rd party device. You have made all of our lives more enjoyable.


How OOP2 Works

A method has been created that facilitates the process of starting a FreeStyle Libre 2 sensor with the official or even the patched version of the LibreLink app in a way that will permit xDrip+ to create a Bluetooth bond and receive encrypted raw blood glucose values from the Libre 2 sensor. This is accomplished by using an NFC scan to initialize the Libre 2 sensor via the official or patched version of the LibreLink app. After the 1 hour warm up period is finished, another NFC scan using xDrip+ will start the sensor initialization process in xDrip+. Selecting “Start Sensor” from the xDrip+ menu and then conducting another NFC scan about 60 seconds later will create a shared key that will be used to decrypt the encrypted Libre2 bluetooth readings.


A second application called OOP2 (Out of Process algorithm) is installed on the phone. Its purpose is to receive the encrypted raw values, which are collected by the xDrip+ bluetooth connection to the Libre2 sensor, and then decrypt these values in a closed source software version of the exact algorithm that exists in the hardware on the Libre 2 sensor itself.


Once OOP2 has decrypted the raw values, they are returned to xDrip+ to be calibrated and entered in the blood glucose table, plotted and displayed in the xDrip+ interface. At this point, that blood glucose value can be used (just like any other BG value from other devices or applications) with the internal xDrip+ calibrations (if you want to, but it is not required), broadcast to other applications (like AAPS) and used in plot predictions by retrieving the Libre 2 backfill sensor values history.


NOTE: A list of definitions exists at the bottom of this document. If you are unfamiliar with any terms or abbreviations feel free to jump below for clarification.

Configuration


Hardware

FreeStyle Libre (FSL)

(OPTIONAL) FreeStyle Libre Reader

  • FreeStyle Libre Reader 1 (with updated firmware)

  • FreeStyle Libre Reader 2

NOTE: If you plan to use the FreeStyle Libre Reader in this solution, you MUST START the sensor with the READER FIRST. If you do not do this you will not be able to use the reader to gather readings from the activated sensor. After the sensor has warmed up, you can then take readings from the LibreLink application or xDrip+.


Software

OOP - Out of Process Algorithm, an external Android APK application that assists in retrieving raw Libre sensor data to obtain blood glucose values. xDrip+ sends gathered FSL2 BT raw data to OOP and blood glucose values are returned to xDrip+.

  • OOP1

  • Works with Libre 1 and Libre2 sensors.

  • 2 versions of OOP1 - One for European Libre 2 sensors and another for Libre2 US Sensors

  • Retrieves values from Libre sensors and applies an algorithm to convert raw Libre sensor data to obtain corrected / calibrated blood glucose values.

  • NOTE: OOP1 has stopped working on most phones running Android 10


  • OOP2

  • Works with European Libre 2 sensors only

  • Closed source (not available on GitHub)

  • Purpose is to decrypt the encrypted raw Libre2 values and return them to xDrip+. Then xDrip+ is responsible for the translation and calibration of these values into usable blood glucose values.

LibreLink

xDrip+

  • Nightly latest source code built each night. Not thoroughly tested

  • Stable latest stable tested release.

  • NOTE: any release after 13/12/2020 should work with OOP2 as that is when it was first integrated into xDrip+.

Process

Before You Start

It is my strong recommendation that this process is done with a new sensor. While it has been reported that a connection can be made with a running sensor (see below), the chance that the LibreLink app or the Reader will create a new private share key for communication during connection is highly likely. This means that after bonding, xDrip+ is not aware of the new key and will not be able to communicate with the sensor. Attempt a connection with a running sensor at your own risk, preferably towards the end of the sensor's life.


First download and install the apps below


  • OOP2 - Latest version of the oop2 can be found at:

oop2.apk


  • xDrip+ - latest version can be found at:

xdrip.apk


Uninstall Possible Conflicting Apps


Some apps take control of Bluetooth functions and disturb the setup of the Libre 2 sensor. It is recommended to start by removing these apps if you have them installed. You can try to add them back one by one later. This list may grow in the future as more users check in. If you want to risk starting a sensor with the apps installed, it is your choice but be aware that removing them gives a better chance of success.

  • Amazon Alexa

  • Tile

What if my sensor is already started? Can I still get reading in xDrip+? YES!

Many people have asked if this method can be used with an already active sensor and I can say with a resounding YES, you can start an actively running sensor.

  1. FIRST, make sure you have made the configuration changes and settings to xDrip+ and installed and configured OOP2 as shown below.

  2. THEN, proceed to Step 5 and MAKE SURE you have force closed LibreLink before you start. Then follow the process to completion.

NOTE: You will not be able to use your activated FreeStyle Libre 2 sensor with the FreeStyle Libre Reader IF IT was not started with the FreeStyle Libre Reader first. If it WAS started with the FreeStyle Libre Reader first, then you will be able to scan the sensor and retrieve readings from BOTH the sensor and apps like LibreLink and xDrip+.

How to Start a FreeStyle Libre 2 Sensor in Bluetooth Native mode using LibreLink and xDrip+


NOTE: If there are settings in the screenshots that are not called out with a BOX specifically and are UNCHECKED (IE, disabled) then PLEASE KEEP THEM DISABLED. The screenshots are reflective of a working configuration for ALL settings shown. If you want to experiment turning other features on/off after you have a working sensor, you are free do to so at your own risk.


Step 1: Application Installation and Configuration

Install and configure OOP2 and see that it works by just opening the app.





Settings

  • Use service on

  • Use foreground service on (optional)

  • This may need to be enabled if it is not working right away. This keeps the service open in the foreground

  • Timer Duration 5 min

  • This should be enough. Change to 1 sec if you are not getting results fast enough but be warned this increases battery usage..

Install xDrip+ latest nightly version (link above). OOP2 functionality exists in xDrip+ starting after 13.12.2020. (Remember to backup your settings and DB, and uninstall the old version first). Further documentation on xDrip+ installation and setup can be found here.


Step 2: xDrip+ Settings Configuration


Hardware Data Source: Libre Bluetooth



NFC Scan features: settings not mentioned are assumed to be turned off. This applies to “faster multiblock” setting as well. Do not enable this as NFC scanning will NOT work.

  • Use NFC feature: on

  • Starting bluetooth connection with libre 2 sensor: Always connect to libre2 sensors

  • Sensor Age or Expiry: on

  • Scan when not in xDrip+: on


Less Common Settings -> Advanced Calibration

  • Double Calibrations: on (optional but recommended)

  • Non-fixed Libre slopes: on

  • Check Libre Serial: on


Less Common Settings -> Bluetooth Settings (these are important and can vary with your phone/setup)

  • Turn bluetooth on: on

  • Trust Auto-Connect: on

  • Use Background Scans: on

  • Always discover services: on

  • Allow bluecon unbonding: on

NOTE: Wakelocks, Close GATT and watchdog timers may be needed to be turned on if your phone needs aggressive BT resetting.



Advanced settings for Libre 2 (optional but helpful)

  • show Raw values in Graph: on

  • show Sensors infos in Status: on

Extra Logging Settings (needed to debug if not working correctly)

  • Extra tags for logging: enter this value

BgReading:d,xdrip librereceiver:v,LibreOOPAlgorithm:v,jamorham nsemulator:v,DexCollectionService:v

Less Common Settings -> Other misc options

  • Smooth Libre data: on

  • Retrieve Libre History: on

  • OOP algorithm calibration: THIS IS GREYED OUT AND CANNOT BE CHECKED, THIS IS NORMAL BEHAVIOUR

  • Settings for OOP2 Configuration

  • Out of process Libre algorithm: OFF

(MAKE SURE THIS IS OFF FOR OOP2 OTHERWISE YOU WILL NOT GET READINGS!)


Step 3: Physically insert the Libre sensor


Step 4: Start the LibreLink App and start sensor with very first NFC Scan


Start the LibreLink app, then scan the newly inserted sensor, then close and disable or uninstall the LibreLInk app. You still need to wait for the sensor to warm-up the full 60 minutes before proceeding and starting the sensor in xDrip+. It can be started as early as 20 minutes but I would not recommend this as the sensor is still internally calibrating and the values vary wildly.


Step 4a (OPTIONAL, Use FreeStyle Libre Reader):

Start the FreeStyle Libre 2 sensor by scanning it with the FreeStyle Libre Reader with very first NFC Scan


If you want to be able to use the FreeStyle Libre Reader as well as the LibreLink app or xDrip+ to read values from the FreeStyle Libre 2 sensor, then you will need to scan the newly inserted FreeStyle Libre 2 sensor with the FSL Reader FIRST. After the sensor warmup is complete you can then use the LibreLink app or xDrip+ to scan readings.


NOTE: The LL app is only needed for the VERY FIRST NFC scan after sensor insertion. It serves to send the warmup initialization signal, afterwards the app MUST be disabled (app settings->force close) or uninstalled. You can use the Patched 2.3 app, Official 2.4.2 or Official 2.5.3 versions, it does not matter. The main thing is to prevent the LL app from running when xDrip+ is trying to start the BT bonding process with the sensor as the LL app interferes with the bluetooth reconnection process by disrupting communication.

UPDATE: It has been reported that simply turning off the location permission in the LibreLink app Android system settings is enough to prevent it from interfering with the connection. This has been reported by a few users to be successful. Again I recommend disabling or uninstalling the app but you can try this if you want to experiment.



Step 5: Open xDrip+ and NFC SCAN the Libre 2 sensor


(Reminder! Ensure LibreLink is disabled (location turned off) or uninstalled AND you have waited the entire 60 minutes for the sensor to warmup and internally calibrate.) NFC SCAN the Libre 2 sensor. This sends a signal to the sensor to turn on Bluetooth pairing in order to start the bonding process. A small notification will appear briefly on the bottom of the xDrip+ Overview screen with the text Scanning followed by the notification Scanned OK! upon a successful NFC scan of the Libre2 sensor.


Step 6: Start the new sensor in xDrip+


In the xDrip+ Overview screen press the hamburger menu in the upper left corner. Then choose Start Sensor.


On the Start New Sensor screen press Start Sensor. A prompt will ask Did you insert it today? Respond by pressing NOT TODAY.


NOTE: If you accidentally clicked "YES, TODAY" then you will need to "stop sensor" from the xDrip+ main menu followed by "start sensor" by proceeding with Step 5 again.


Step 7: Wait 60 seconds and NFC Scan the sensor again


A second NFC scan is needed in order to ADD the sensor as the Bluetooth device from which xDrip+ will use to retrieve the readings. Once complete you will see a notification stating NEW SENSOR STARTED. The Collect Initial Readings dialog will appear displaying the steps completed and in progress along with time estimations for completion.


A 60 second waiting period is enforced because the sensor can’t be scanned during this process more than once per minute. If the sensor is scanned too early the warning Not so quickly, wait 60 seconds is displayed in the xDrip Overview screen.



Step 8: Data Collection between 3 and 15 Minutes


Between 3 and 15 minutes enough data is collected (3 full reading retrievals) and the Calibrate Sensor? prompt will ask you to enter an initial calibration. Press Calibrate to proceed through the initial calibration process. If you are still not receiving readings at this time, sometimes it helps to reboot the phone.



Step 9: Calibrate


When enough data has been collected to create 3 full readings, you will be prompted to enter your initial calibration. You must calibrate with an actual blood glucose reading from your blood glucose meter of choice, I use Contour NEXT One which has a very accurate MARD. If you have the double calibration option enabled in xDrip+ then 2 blood glucose readings will need to be taken. Enter each blood glucose reading result and press DONE when finished.


After entering the readings, your Libre 2 sensor is now bonded to xDrip+ as a Bluetooth device and will actively deliver readings at 5 minute intervals.


Readings are actively collected each minute and you can view them by pressing the 3 dot menu in the upper right corner of the xDrip+ Overview screen and selecting View Events Log.


Step 10: Verify Sensor is connected and delivering data


Press the Hamburger menu in the upper left of the xDrip+ Overview screen and select System Status. On the System Status screen the active Bluetooth Device: field displays the FSL2 Bluetooth naming convention of ABBOTTXXXXXXXXXXX, where the XXX’s represent the sensor serial number. The Connection Status field displays Connected and the Sensor Start: field displayed the time the sensor was started.


On the BT Device (swipe left) screen you can verify further connection details of the sensor as well as use this screen for troubleshooting connections. Below is a list of fields and their purposes to assist in connection troubleshooting.