What is FreeAPS?
FreeAPS is a version of Loop forked by Ivan Valkou and Kirill Chekanov. FreeAPS provides an alternative implementation of automatic bolusing (called SMB in FreeAPS) along with some additional in-app selectable options, and provides support for more types of CGM.
Because FreeAPS was widely used, the Loop and Learn team took over maintenance after Ivan announced he was freezing his fork in early 2021.
The release notes for FreeAPS, after it was moved to the loopnlearn github repository, can be found at FreeAPS Releases
Warning – FreeAPS sunset is approaching
- There will be limited support for FreeAPS in the future
- There is the chance that the next iOS or Xcode update could “break” FreeAPS and you would need to migrate to another Loop branch or fork.
- Please build Loop 3
FreeAPS has been removed from the Build Select Script in favor of a customized version of Loop.
FreeAPS cannot be built with the GitHub method available for Loop or Loop with Patches.
This is a good time to remind everyone that Loop and the FreeAPS fork are DIY and almost entirely dependent upon volunteer developers.
You can still build FreeAPS if you want. Be aware it is based off of Loop 2.2.x and does not have some of the new features of Loop 3.
Copy and paste this entire line into a terminal to build FreeAPS (with DASH support).
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/loopnlearn/LoopBuildScripts/main/BuildFreeAPS.sh)"
FreeAPS Chat and News
If you want to use FreeAPS, you should join the Telegram Channel for FreeAPS Chat and Help and FreeAPS News.
If you want to help with translations to other languages, please use the FreeAPS Crowdin project. Updates to translations will be accepted at intervals without change to FreeAPS version number. Please see Tags to decide if you want to rebuild to get new translations.
With FreeAPS v2.2 (204), more of the strings found in the app have added to Crowdin and translated.
The latest translations can be obtained by going to FreeAPS Crowdin and following directions. (There may be a delay before translation updates are incorporated in the freeaps branch – the Crowdin link may be more up to date.) The current status of the translation for all languages is shown by this graphic:
Don’t worry when you see the localized number go down – that probably means a new language was added.
Why Would I Want Free APS?
FreeAPS has Unique Features
FreeAPS has unique features that are not included in other versions of Loop. The most commonly used features are listed here, but there are less commonly used features that are covered in the sections that follow. All of these features are easily utilized with the click of a checkbox. No special coding skills required.
- Set your bolus % and positive temporary basal rates, known as Partial Bolus Application (PBA) and Basal Rate Multiplier (BRM).
- Enable Basal-only override that lets you walk away from your radio-link, known as the Open Loop Manual Temporary Basal Rate (Loop 3 has a different and, for pods, better Manual Temp Basal method)
- Set-up multiple profiles and easily backup settings to the cloud, see details in the section on Export and Import Settings
- Utilize additional CGM options
- xDrip4iOS (available with Loop with Patches)
- GlucoseDirect (available with Loop with Patches)
Kate Farnsworth did a good writeup of the FreeAPS branch in a Facebook Looped post.
Words of Caution
Do It Yourself, But Not Do It Alone
As with any branch, please note that FreeAPS is Do It Yourself (DIY), and do at your own risk. It is not Do It Alone- there are volunteer resources available on FaceBook, Telegram and GitHub that are available to help you. Please be safe, research a lot and be careful with your decisions. FreeAPS relies on automated MBs for all or a portion of insulin delivery — be sure that your settings are correct because FreeAPS is more sensitive to mistakes than either traditional pump therapy or non-automatic bolusing versions of Loop.
If you previously used either the Master or the Automatic-bolus branch of Loop, please review Compare Branches to make sure you fully understand how these differ from FreeAPS.
The extra settings you can choose within FreeAPS can be a double-edged sword – more ways to have settings offset each other. If you’re new to FreeAPS, please take the suggestions in this document seriously. Start simple and then add features as you need them. The remainder of this document is dedicated to explaining FreeAPS features and how to utilize them safely.
So, you’ve decided to try FreeAPS, but aren’t quite sure how to build it
- Update MacOS, Xcode, iOS, and WatchOS. FreeAPS only supports iOS 14 and higher.
- Do Not Delete your Loop app. FreeAPS will build on-top of Loop and all settings will carryover, and if you’re using Omnipod, you will be able to keep using your existing Pod. If you delete your Loop app, you will need to re-enter your settings and change your Pod.
- The one exception is if you are coming from Loop 3; in that case you have to completely delete the app before building FreeAPS (or Loop master). Time it for a pod change if you use Omnipod.
- Open Loop by going to your Settings and then clicking the Closed Loop checkbox so that it is grey.
- You can follow the updating instructions in LoopDocs
- Use Loop and Learn’s script as described at the top of the page to download and build FreeAPS to your local drive and open it in Xcode – FreeAPS is no longer included in the build select script
When you first install FreeAPS
Please leave Microboluses disabled in FreeAPS settings AND disable Adaptive Nonlinear Carb Model in iPhone settings (see instructions below). This set-up will give you a branch very similar to the Master branch plus the additional CGM options.
When you’re ready to proceed with the setup process, click on the Settings icon in your FreeAPS app and click on the Closed Loop checkbox so that it’s green. Then click on Microboluses and begin your setup process.
If you have never used AB
If you have never used the Automatic-Bolus (AB) branch, you should ease your way into FreeAPS microbolusing. Click on Settings – Microboluses- Enable Without Carbs, and then set your Partial Bolus Application (PBA) to 20% and your Basal Rate Multiplier (BRM) to a number consistent with your Maximum Basal Rate. This will give you a chance to double-check your settings before fully deploying microboluses.
With these settings, you will record meals just as you ordinarily would in Master and you’ll manually bolus. Over time, you can Enable With Carbs, increase your PBA and decrease your BRM.
If you are an experienced AB Looper
Click on Settings – Microboluses – Enable With Carbs and Enable Without Carbs and set your PBA to 40% and your BRM to x1. This set-up will give you a branch very similar to the current AB branch, plus the additional continuous glucose monitor described in the Nightscout CGM section below.
Over time, you can increase your PBA and adjust your BRM.
The adjustments described above will get you to a branch similar to AB, but may not be identical due to the timing of when various branches are released. A description of each FreeAPS setting is explained in more detail in the sections that follow.
Enable With Carbs and Enable Without Carbs
Microbolusing can be enabled separately with and without carbs
Your decision will be based upon whether you want to enact MBs only when you have carbs on board (COB) or with no COB or both.
By leaving Enable Without Carbs off (grey), you only get MBs with carbs. The rest of the time, FreeAPS relies on temporary basals to keep you within target range. This option may be particularly helpful for newly diagnosed or younger FreeAPS users because temporary basals are less aggressive than MBs.
FreeAPS provides the option to use both boluses (see Partial Bolus Application) and temporary basals (see Basal Rate Multiplier) to deliver insulin. The extent to which you use boluses vs temporary basals is defined by you, the FreeAPS user.
To receive only temp basals, click on Settings – Microboluses – and click Enable With Carbs and Enable Without Carbs so that their checkboxes are no longer green.
FreeAPS Unique Settings - Partial Bolus Application and Basal Rate Multiplier
Partial Bolus Application (PBA)
The PBA rate is the percentage of recommended bolus that will be applied automatically at every 5 minute Loop interval. For example, the Automatic-Bolus (AB branch) uses 40% as its PBA. The higher your PBA, the more accurate your settings must be.
Basal Rate Multiplier (BRM)
The BRM determines the extent to which you receive extra insulin via temp basals versus microboluses. If the BRM is x1, then only microboluses are used and all of your increased insulin needs above your scheduled basals will be delivered via MB. However, if BRM is greater than x1, temporary basals are applied before MBs are delivered. With lower BRM, more of your insulin corrections are provided by MBs. With higher BRM, more of your insulin corrections are delivered by temporary basals. If the BRM is set to Max basal limit (scroll down to the bottom of the BRM screen), then any Recommended Bolus will be delivered via temp basals up to the amount of your Maximum Basal Rate – as long as Loop determines that your insulin needs (above your scheduled basal) can be met with temporary basals within a 30 minute period, you will get no MBs.
The table below shows how much insulin gets delivered via BRM vs MB over a 30 minute period. Notice how as the BRM increases, the amount of insulin that gets delivered via MB decreases. This example assumes a PBA of 100% even though a PBA of 100% is not recommended in order to provide a simpler example. For lower PBA %s, the amount of insulin delivered via MBs over a 30 minute period would be lower. In all 5 Scenarios, the Recommended Bolus is 2.1u [(Eventual BG-Target BG)/SF], the Eventual blood glucose (BG) is 300, the Target BG is 90, the ISF is 100, and Scheduled Basal Rate is 1.
Please also note the following:
- BRM value cannot exceed your Maximum Basal Rate setting in Delivery Limits
- BRM setting is ignored if MBs are disabled
Disable MB by enabling temporary override
To enable this optional feature, click the checkbox and set the threshold.
Once enabled, whenever you set a temporary override with a target range greater or equal to that threshold, MBs won’t be enacted. For example, if you set this at 100 and then select an override with a target BG range of 110-120, no MB would be delivered while that override is in effect.
IF YOU ENABLE THIS FEATURE, PLEASE INPUT A “GIVEN VALUE”. DO NOT LEAVE THE DEFAULT “GIVEN VALUE” OF ZERO. IF YOU DON’T CHANGE THE DEFAULT VALUE, YOU WILL GET NO MBs WHEN YOU ENABLE A TEMPORARY OVERRIDE.
For more information on override strategies, click here.
Export and Import Settings
Create multiple profiles
FreeAPS gives you the ability to export settings to iCloud and import them back into FreeAPS. This essentially allows profile switching which is incredibly helpful for hormones or fluctuating insulin needs. The Import and Export Settings feature is located at the bottom of your main FreeAPS settings screen below SERVICES. In FreeAPS v174 and earlier versions, importing a settings profile that was created while in a different time zone can cause your FreeAPS app to crash due to the Time Zone Bug.
Open Loop Manual Temporary Basal Rate
For those times, when you’re going to be away from your radio-link
To use this feature, go into Open Loop mode by going into Settings and sliding the Closed Loop checkbox to the left, click Done and then click on the Temp Basal icon in the top center of the HUD (main FreeAPS display screen). The Open-Loop TBR manual setting allows you to pick your TBR and duration. This feature is helpful to those who are going out of range of their radio-link for more than 30 minutes. For example, this feature is helpful for swimming or other sports where it’s not practical to carry your radio-link with you.
FreeAPS has many built-in safety features.
By default the following safety features are in effect
Basals and MBs are disabled whenever:
- Any BG within the 6-hour prediction is below your target range
- Eventual predicted BG is below your target range
- Current BG is lower than your target range
In all other circumstances, MBs are limited by your settings. Two of these Safety settings can be disabled and MBs will be delivered as long as you’re getting data from Apple Health. This flexibility is built into FreeAPS because individuals’ diabetes and their FreeAPS technology set-ups vary.
Allow MBs when the sensor value is invalid
In the default/off position, no MBs are delivered if the CGM sensor value has more than a 20% or 2.5 mmol/l (45 mg/dl) difference from your current BG reading. This built-in safety feature can be disabled by sliding the checkbox to the right.
Allow MBs when glucose is below target range
In the default/off position, no MBs are delivered if current or predicted BG is below target range. This built-in safety feature can be disabled by sliding the checkbox to the right.
Settings - Microbolus
Curious as to why a Microbolus wasn’t given?
Last Event is located by clicking on Settings – Microboluses, and then scrolling to the bottom of the screen below OTHER OPTIONS.
This log provides details of the time when your last MB was enacted, how much was given and what percentage of the recommended bolus was given.
If you click on the the carrot to the right of the LAST EVENT details, you will see how FreeAPS has treated other MB events since you last shut down your iPhone.
If an MB was not delivered, it will give an explanation as to why not.
Open bolus screen after carbs on watch
Toggle this checkbox on if you’d like your watch’s bolus screen to open after you’ve entered carbs.
Minimum MB amount
This setting allows you to set a minimum bolus size. Setting a minimum MB amount may help with pump battery life issues by issuing fewer bolus commands, but this is debatable.
Other FreeAPS Settings
Show required carbs on the app badge
When you enable this feature, a small # will appear on your FreeAPS app badge when you are predicted to need glucose to stay within your target range. The value is calculated based upon your current CR and ISF.
WARNING -If you downloaded FreeAPS code before Mar 04, 2022, you must ensure that the pump time and looping phone time are in the same time zone if you enable this feature. If not, the required carbs badge will trigger the time-zone bug and cause FreeAPS to crash. The time zone bug is fixed as of the hotfix released on March 04, 2022. Please do not assume that because you’re using v2.2 (204) you have the time zone bug fix, you need to verify your download date. If you used the Build Select Script to build FreeAPS, you can check your download date by going into Finder/Downloads/BuildLoop; each download is coded by the date, for example, 220304 (March 4, 2022).
Retrospective Correction interval
This is an experimental feature that allows you to increase or decrease the retrospective correction (RC) interval. The standard Loop retrospective correction interval is 30 minutes and is a comparison of glucose prediction vs actual continued with decay over 60 minutes.
Extending the RC time is equivalent to multiplying the RC effect in the prediction, which could result in a larger or a smaller correction in cases when the model errors are positive or negative, respectively.
Adjusting the RC interval should not impact post-meal BG because RC is effectively suppressed during the times when carbs are absorbed relatively fast. It may help with prolonged highs, for example due to unannounced carbs+protein+fat effects. [This is based upon feedback from Dragan that was posted in Telegram.]
Adaptive Rate Non-Linear Carb Model
An Optional Carb Model
Adaptive Rate Non-Linear Carb model uses the EXACT absorption time that you enter, rather than the 1.5x absorption time that is used in Loop’s Non-Linear carb model. That means, if your food impact lasts longer than you enter, Loop won’t know that it is carbs. As a result of using the absorption time you enter, the curve will be more aggressive (higher). If the carb impact rises FASTER than the prediction (in the first 50% of the meal), the model assumes you didn’t enter enough carbs. So, it adds more carbs and gives more insulin.
Remember that any change to this setting (in the main iPhone settings) does NOT take place until you quit and restart your FreeAPS app.
Most FreeAPS users leave this checkbox grey so that this feature is disabled. As of FreeAPS v2.2 (201), this setting is disabled by default.
Note: this setting is found within your iPhone’s settings and not within the FreeAPS app.
Additional CGM Options
The opportunity to use a CGM, other than Dexcom
In addition to all of the CGM options that can be used with Loop main and dev branches, the following additional CGM’s can be used with the FreeAPS Fork:
- Nightscout CGM
- Spike and other local apps that support the same API as the Nightscout CGM. This requires no internet connection. To use Spike as a BG source:
- In Spike Settings- integration enable internal HTTP Server
- In FreeAPS, set Nightscout CGM as BG source, use http://127.0.0.1:1979 as a URL and
- Disable Sync to remote service checkbox
- Nightscout CGM (other than mentioned above) requires an internet connection.
- Spike and other local apps that support the same API as the Nightscout CGM. This requires no internet connection. To use Spike as a BG source:
- For help please read the docs for Xdrip 4ios
For help, see GlucoseDirect README.md page.
Using Libre with xDrip4iOS heartbeat
Users of Libre with xDrip4iOS now have the heartbeat option (allows FreeAPS to work with the phone locked).
Instructions for use:
FreeAPS now has an option to make a bluetooth connection to the CGM transmitter, which will then work as a heartbeat.
If you have older code (before 10 Jun 2022), you MUST download new code using the FreeAPS Build Script above. You must have a recent version of xDrip4iOS as well.
It is disabled by default. Can be enabled in xDrip4iOS user interface (UI).
Note for Libre 2 users : the reading will run 1 minute behind.
If you haven’t setup your CGM yet in xDrip4iOS :
- Force close FreeAPS
- In xDrip4iOS make sure you have made a first connection to the CGM
- Force close xDrip4iOS
- Reopen FreeAPS
- Select xDrip4iOS as CGM and open the xDrip4iOS UI (within FreeAPS)
- Enable “use CGM as heartbeat”
- Keep the app in the foreground and wait till the text under the UISwitch changes to
- Did connect to CGM, You can now run both xDrip4iOS and Loop
- Once you see this text, you can reopen xDrip4iOS
What is a heartbeat and why should it come from a CGM?
For optimum performance, the app should be driven by the continuous glucose monitor (CGM) so the Loop cycle starts with the most recent glucose information available, updates the glucose prediction and then sends commands to the pump, if needed, to modify insulin delivery.
When the phone is locked, a mechanism is required to “wake” up the app out of background mode so it can keep that loop symbol a nice green color.
A Bluetooth connection is used by Loop (or FreeAPS) to perform this waking from background while the phone is locked. This is called the heartbeat.
- Best case – this comes from the CGM
- Second best case – this comes from the RileyLink device (for Eros or Medtronic)
- With DASH pods, there is no reliable heartbeat that works all of the time when the phone is locked
In order to solve this problem, the folks who work with Libre sensors make the Bluetooth connection available to FreeAPS. This is an area where more progress may happen, but for now, it is xDrip4iOS that has this feature working with FreeAPS-dev.