Unlock the Full Potential: Setup Your FreeStyle Libre 2 as a Continuous Glucose Monitor
Update: In november 2024 Abbott announced an update to the Freestyle Libre 2 arm patch that will allow it to be used as a continuous glucose monitoring device. Also See: https://www.freestyle.abbott/ie-en/freestyle-libre-2-update.html?srsltid=AfmBOooeZUD0Kqy6cGxto8Ky8oorRA_LMzJpm4O0DQn8Rg2lgPR95dNN
Introduction
What are the Freestyle libre arm patch and app?
The Freestyle Libre sensor is a 5cm radius flat device that persons with type 1 diabetes attach to their upper arm and use to measure their glucose levels. The sensor attached to the arm and is refreshed every 14 days. Freestyle Libre sensors are free in some countries if you have type 1 diabetes or bad regulated type 2 diabetes. If you do not satisfy the criteria for a free sensor you can buy them online for around 50 euros.
The sensor is used in combination with a Freestyle Libre app that can be installed on a smartphone. The app can be used to scan the sensor and get information about glucose levels over the last 8 hours. It is an improvement compared to the old way of glucose level measurements in which a blood sample is used with a fingerprick and placed on a test strip 3-5 times per day. It is however also different from a more advanced continuous glucose measurement device (CGM), which as the word says, gives you continuous insight into glucose levels and can therefore be used for a hybrid or fully closed-loop.
Why can't I get a continous glucose monitoring device?
The devices that continously measure your glucose levels are expensive and in most countries therefore only provided to persons with diabetes that satisfy stringent criteria such as:
- Very badly regulated glucose levels with high Hba1c (a measure of average glucose levels over the last months).
- Dangerous incidents during hypoglycemia (low glucose levels).
- Low-aged children who for whatever reason might benefit from it.
Can the Freestyle Libre be used as a continous glucose monitor?
The app used to be part of embedded software on a third separate small scanning device. In the latest versions, the app can be installed on a smartphone. The Near Field Communication (NFC) scanner on a smartphone is used to scan the patch and get results over the last 8 hours. The newest version of the Freestyle Libre 2 arm patch also establishes a Bluetooth connection with the smartphone that continuously transmits information about glucose levels via Bluetooth and lets the app sound an alarm in case of out-of-range values.
It is this Bluetooth connection that can be used to transform the Flash monitoring into a continuous glucose monitoring system. The Do It Yourself (DIY) Pancreas community, an online community that has taken the lead in trying to improve the healthcare of type 1 diabetics, published a protocol to retrieve this continuous Bluetooth data flow from the Freestyle libre glucose sensor. By doing so it's possible to transform the Freestyle libre arm patch and app into a continuous glucose monitoring device, a device that can be used to achieve a closed-loop system.
What other options are there?
Other options you could look into are the MiaoMiao and the Bubble. These are devices that can be attached to the Freestyle Libre sensor and that can be used to transmit the glucose levels to a smartphone. The MiaoMiao and Bubble are not officially supported by Abbott, the company behind the Freestyle Libre, and therefore are not officially supported by the Freestyle Libre app.
Diabox is another app that can be used to read glucose levels from the Freestyle Libre sensor. It can be downloaded via this link.
More information can be found on the AndroidAPS website
Is changing the functionality of the Freestyle Libre legal?
To make the smartphone part of a hybrid closed-loop system the Freestyle app is “patched” (modified). The patched version of the app used to be downloadable online but has been taken down as Abbott, the company behind the Freestyle libre, has commanded to remove the online version based on the Digital Millennium Copyright Act.
I am not a lawyer so do not use what I write over here as legal advice but if you want to use the Freestyle Libre you have to patch it yourself due to legislative rules. The European Union Computer Programs Directive controls the legal protection of computer programs under the copyright law of the European Union. Their most recent report in the official journal of the European Union states the following about decompilation or reverse engineering (one of the steps in patching the original app) in article 6:
So you can patch the Freestyle libre software
- as long as you have purchased the software or the device that includes the software,
- as long as you use it to create a communication link that can not be achieved otherwise and
- as long as you do not distribute a patched version of the software.
Drawbacks
Using the Freestyle libre off-label can have significant disadvantages that can lead to medical risks. The most important ones are:
- The self-created CGM has a significant time delay of up to 25 minutes (blood glucose level -> tissue glucose levels -> sensor measured glucose level -> transmitted glucose level -> in the app registered glucose level). If glucose levels decrease then waiting with taking action until a near-hypo state occurs can be dangerous.
- Because of this time delay, predictions made by a closed-loop algorithm may have a large prediction error. This is especially the case when there are large changes (>delta 0.5) in glucose measurements.
The protocol
Let's take a look at the protocol. The GitHub code of the step process for creating the patched app can be found here and in this video. I will go through the steps for a Mac in a more detailed fashion for educational purposes. My goal is to help as many people as possible understand the process. I will throw in some really basic information here and there about open-source software, version control, and how to use a command prompt. If you need help with these technical parts we can provide you with guidance. Be aware that we will only provide guidance but not provide a patched app and we will also not do this for you. You really have to do it yourself.
Installing xDrip
Correctly installing xDrip from the Nigthscout Foundation page before starting the patching process helps to know if the patched Freestyle libre app is working correctly once you've installed it.
Installing Git
Git is the standard software used by software engineers to work in collaboration with other software engineers on the same collection of code. During the software engineering process, different developers can be working on their computers at the same time on the same piece of code and therefore have different versions on their computers. Working in a team like this can lead to complex interactions. To be able to keep an overview of who contributed what at which moment in time the engineers use Git to keep track of the versions on their computers and in online repositories.
If there is a conflict between versions then Git offers ways to resolve these. Git is used for downloading (referred to as "cloning”) the code and applying the patch during the Freestyle libre app patching process. To install the latest version of Git, open a terminal (press command and spacebar and type “terminal” on a mac) and then type the following in the terminal:
brew install git
Copying the GitHub repository files
The cloning function of git is used to copy the code. The patch code is cloned from GitHub which is, simply said, an online storage place for code with version control through above mentioned Git, and the option to make the code open-source. GitHub also provides social media link user options, such as following developers, creating a group project and making a profile to showcase your code. To clone the extra Freestyle Libre app code for the patched version type:
The tree software package can be used to see what your directory looks like.
brew install tree
Then show the tree with the command “tree”, and you should see something like this:
└── Libre2-patched-App
├── README.md
├── sources
│ ├── APKExtractor.smali
│ ├── CrashReportUtil.smali
│ ├── ForegroundService.smali
│ ├── ThirdPartyIntegration.smali
│ └── sika
├── xdrip2.git.patch
└── xdrip2.patch
Uninstalling the original app on the phone
This means going to settings and finding the app management option and then removing it.
Downloading the original app in the right version
Get the suitable version of the Freestyle Libre App and copy it to the right directory.
The directory on your computer now looks like this:
├── Libre2-patched-App
│ ├── README.md
│ ├── sources
│ │ ├── APKExtractor.smali
│ │ ├── CrashReportUtil.smali
│ │ ├── ForegroundService.smali
│ │ ├── ThirdPartyIntegration.smali
│ │ └── sika
│ ├── xdrip2.git.patch
│ └── xdrip2.patch
└── com.freestylelibre.app.de_2019-04-22.apk
Checking the integrity of the downloaded file
Check if the downloaded version of the Freestyle libre is exactly the same as the one that the patched app is made for. This is done through a mathematical algorithm applied to the original app. This algorithm is called MD5 checksum. On the Mac it is installed with:
brew install md5sha1sum
Calculating a checksum is done with the following command:
md5 com.freestylelibre.app.de_2019-04-22.apk
According to the patched app GitHub page, the result should be the following string:
420735605bacf0e18d2570079ebaa238
Installing a reverse engineering tool
To compare the original app with the patch it's necessary to first reverse-engineer the original app. In other words, the app was downloaded in readable code for machines but now we have to make it readable for humans. To do this you have to install the APK tool. APK is “An Android Package Kit (APK for short) is the package file format used by the Android operating system for distribution and installation of mobile apps.” The APK tool is installed with brew:
brew install apktool
On Windows the process is a bit more complex, check out this page.
Decompiling
The next step is to use the APK tool to decode the Librelink application into more human-readable code:
apktool d -o Libre2-patched-App/librelink com.freestylelibre.app.de_2019-04-22.apk
In which:
- d = decoding/decompile
- o = output
- “Libre2-patched-App/librelink” = output directory
- “com.freestylelibre.app.de_2019-04-22.apk” = app-file
There should now be 1041 directories and 20035 files. The structure on a high level looks as follows:
├── Libre2-patched-App
│ ├── README.md
│ ├── librelink -> folder with the decompiled apk file
│ ├── sources
│ │ ├── APKExtractor.smali
│ │ ├── CrashReportUtil.smali
│ │ ├── ForegroundService.smali
│ │ ├── ThirdPartyIntegration.smali
│ │ └── sika
│ ├── xdrip2.git.patch
│ └── xdrip2.patch
└── com.freestylelibre.app.de_2019-04-22.apk
Patching the application
Go to the Librelink folder with the cd (change directory) command:
cd Libre2-patched-App/librelink
The actual patching process uses git again:
git apply ../xdrip2.git.patch
Renaming the old file
Rename the downloaded APK to “original.apk”
mv com.freestylelibre.app.de_2019-04-22.apk original.apk
The command mv stands for move.
Changing the location of the old file to the assets folder of the patched app
mv original.apk Libre2-patched-App/librelink/assets
Navigating to a subfolder of the patched app
cd Libre2-patched-App/librelink/smali_classes2/com/librelink/app/
Copying smali files from GitHub to this folder
The most reliable way to modify the java code of the application kit is to modify the computer-readable (and hardly human-readable) .smali code file. They are in the patch directory and they can be copied to the current directory with:
cp ../../../../../sources/*.smali ./
in which *.smali means all smali files.
Rebuilding the application
Give the Apktool the instructions to create a new machine-readable apk-file that can be used by your smartphone to create a working application:
apktool b -o librelink.apk librelink
In which:
- b = build/recompile
- o = output
- librelink.apk = new apk file
- librelink = directory of input for making new file
Generating a signing Keystore
Apps have to be signed to run on your phone. The signing process has the goal to prevent the spread of potentially malicious software on smartphones. Signing an app as a developer first requires creating keystores. A keystore is a storage mechanism for security certificates. The first step is to install the Java Development Kit (JDK) with the help of this link and create a keystore:
keytool -genkey -v -keystore librelink.keystore -alias librelink -keyalg RSA -keysize 2048 -validity 10000
and answer the questions that appear.
The second step is to sign the application with the command:
jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore librelink.keystore librelink.apk librelink
Installing the new APK
The file “librelink.apk” has to be copied to your google drive and installed on your phone by downloading the file from Google drive.
Did I configure all settings right?
Now, check all settings before scanning a sensor:
- Was the original app removed from your phone?
- Is NFC (Near Field Communication) enabled on your phone? Go to settings and search for NFC and turn it on.
- Are app permissions enabled for location permission and storage permission?
- Time and time zone are set on automatic?
- Are all the alarms within the app activated (you can redisable them later)?
- Is Bluetooth switched on?
- Are the app notifications enabled?
- Is sound enabled for the app?
- Are lock screen notifications enabled?
Starting the sensor
Start the sensor by flashing it over the patch on the arm and wait 60 min. Glucose measurements should be transferred continuously (every 5 min) to the patched version of the Freestyle libre app. The patched Freestyle libre app does not have the function to show the continuous measurements, so you have to start up xDrip+ to evaluate if everything works well and see the values.
Where to find help
When you run into problems you can find Github tickets (“issues” in Github terminology) to post your problems. Others can respond. The poster of the issue and all responders get a message when a new response is placed. You can have a look at the questions that were already asked about the patching process on this page:
Libre 2 — (xDrip+ + LibreLink patched) vs. (xDrip+ + MiaoMiao2) · Issue #1394 ·…
If you need more personalized help you can reach out to us
