What is FreeAPS?
FreeAPS is an experimental branch of Loop forked created by Ivan Valkou and Kirill Chekanov. FreeAPS provides the user with a lot of options. It can deliver microboluses (MBs) and temporary basal rates (TBRs) to manage your insulin needs. MBs are based upon your settings and Loop’s algorithm. The algorithm will suggest boluses when basal change is not enough, but FreeAPS forces part of that dosage as a microbolus (MB) at the beginning of every Loop interval.
As of March 21, 2021, FreeAPS was frozen by its developer, Ivan Valkou, who is focusing his talents on FreeAPS X, which is an iOS-based DIY APS utilizing the OpenAPS algorithm. For more information about FreeAPS X, please check out Telegram.
Because FreeAPS is widely used, the Loop and Learn team forked Ivan’s fork and are updating it with improvements in a limited fashion. For example, the pump code updates (from Loop) have been incorporated in the loopnlearn github version of FreeAPS. 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. As a best practice, you should be prepared to download both FreeAPS and another Loop branch or fork to your Mac in case of the need for an emergency rebuild. (That means if you use a CGM provided by FreeAPS but not a standard Loop branch, you need to identify what fork of Loop is an option.)
Yes – the Build Select Script points to the loopnlearn repository so you can still build FreeAPS with that script and get the latest released version.
This is a good time to remind everyone that since Loop and the FreeAPS fork are DIY and almost entirely dependent upon volunteer developers, the one certainty is that there is no certainty.
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
- 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
- Dexcom Share
- Nightscout CGM
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 13 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.
- Open Loop by going to your Settings and then clicking the Closed Loop checkbox so that it is grey.
- If you’re using Omnipod, please access your Loop Settings and click on Change Time Zone to make sure that your Pod and Looping phone are using the same time zone. Failure to update your time zone, may result in your FreeAPS app crashing even though you are able to build successfully. If you’re reading this page because you’re experiencing the Time Zone crash, please go to the Loop Time Change page.
- Use Loop and Learn’s Build Select Script to clone FreeAPS to your local drive and open it in Xcode.
As of September 2021, FreeAPS was updated to be consistent with the rileylink_ios (pump interface) portion of Loop v2.2.6.
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
- MBs are disabled whenever:
- Any BG within the 6-hour prediction is below your suspend threshold or target range
- Eventual predicted BG is below your suspend threshold or target range
- Current BG is lower than your suspend threshold
- Maximum MB amount is limited to 30 basal minutes when current BG is below the 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 – When this feature is enabled, you must ensure that the pump time and looping phone time are in the same time zone. If not, this will cause the time-zone bug which causes FreeAPS to crash.
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 Master, Dev and AB Branches, the following additional CGM’s can be used with the FreeAPS Fork:
- Dexcom Share
- Requires internet connection
- Nightscout CGM
- Requires internet connection
- Allows connectivity of any CGM that can be uploaded to Nightscout and loads the readings from Nightscout into Loop
- Spike and other local apps that support the same API as the Nightscout CGM
- Requires no internet connection
- Allows use of the Libre with the Bubble Transmitter into the Diabox app