Start Up Guide
This startup guide is meant as a supplement to the iAPS Documentation and the Loop and Learn iAPS walkthrough videos. This guide is an attempt to summarize the highlights of the information you need when setting up iAPS. It is not a complete A-Z guide and you will have to consult the iAPS Documentation for details when you are in doubt.
Last updated: November 24th 2023
iAPS version used: Main 2.2.7
-
What you need to have:
A relatively new iPhone (full device list)
A supported insulin pump (full pump list)
A supported CGM (full CGM list)
An Apple Watch (optional!) (version 3 and newer)
An Apple Developer account
Using a free account requires you to re-build the app every weekA Github account
If you want to build and update iAPS using your web browserTime
What you need to know:
Here are some terms and abbreviations that are commonly used.DIY: Do It Yourself, synonymous with taking control of your diabetes
BG: Blood Glucose
Profile Basal Rate: This is your preset rate of basal insulin, in units / hour
ISF: Insulin Sensitivity Factor (also known as Correction Factor)
CR: Carb Ratio (also known as Insulin to Carbohydrate Factor)
COB: Carbohydrate On Board (how many grams of carbohydrates are still active in your body)
IOB: Insulin On Board (how many units of insulin are still active in your body in addition to your basal insulin)
Temp Basal: when needed, iAPS will temporarily change your basal rate for a limited time. This is called a temporary basal rate
SMB: Super Micro Bolus. When needed, iAPS will automatically bolus for you. An SMB is usually followed by a zero temporary basal rate (“zero-temp”). This is intentional and expected behavior
UAM: Unannounced Meal. iAPS can detect an unexpected BG rise and treat it as an unannounced meal
TDD: Total Daily (insulin) Dosage. The total amount of insulin (basal + bolus) for an entire day
Core Settings: Profile Basal Rate, CR, and ISF
What you need to do:
You can’t download iAPS from the App Store because this app is DIY. By installing the app yourself, you are taking ownership of and responsible for using iAPS. We are here to help, but implementing any and all changes is ultimately your decision.To get started, you need to build the iAPS app. The source code is “open source,” free to download and install on your iPhone.
Build instructions can be found here. If you run into problems when building the app, reach out to the iAPS Community on Facebook or Discord.
The rest of this guide assumes that you have a compatible iPhone, pump, and CGM and have built and installed the iAPS app on your phone.
-
Build and install iAPS
If you have another DIY loop app installed on your iPhone, please remove CGM and Pump from that app before you continue.Allow Notifications
If you want to customize iAPS notifications, go to Settings -> NotificationsAdd your CGM
Then, force-quit and restart iAPS. Wait for iAPS to pick up CGM readings. It might take up to 15 minutes. Nightscout is not a valid CGM for looping.Add your Pump
Remember to select the right insulin type to get an accurate insulin curve.Add Nightscout (optional)
Nightscout is not required for iAPS to work. However, it is a great tool for reporting and remote features.Add Apple Health (optional)
Apple Health is not required for iAPS to work. However, it is a great tool for reporting.Add Basal Profile
If you are uncertain, consult your endo or diabetes nurse. More information here.Set your Target Glucose
If you are uncertain, consult your endo or diabetes nurse. More information here.Add Insulin Sensitivities (ISF)
If you are uncertain, consult your endo or diabetes nurse.Add Carb Ratios (CR)
If you are uncertain, consult your endo or diabetes nurse. More information here.Select Glucose Units
Default is mmol/L; change to mg/dL if needed.Set your Recommended Bolus Percentage
This number will be applied as a factor in the bolus recommendations. A number below 100% will limit the bolus recommendation. More information here.Set your Max Basal and Max Bolus in Pump Settings
Max Basal is a limitation that ensures iAPS will never set a higher basal rate. Max Bolus is a limitation that ensures iAPS will not administer a bolus higher than this. There are several other limiting factors, but these are hard limits that will never be automatically exceeded. More information here.Raise Max IOB
to allow iAPS to dose insulin. This is a hard limit. If IOB is above this limit, iAPS will not automatically dose insulin. There are several other limiting factors, but these are hard limits that will never be automatically exceeded. More information here.Check Bolus Increment
Default is 0.1U. Omnipod and Medtronic x22 use 0.05U. Medtronic x23 uses 0.025U.Enable SMB
With COB
(iAPS is allowed to give SMBs when there are carbs entered and onboard )With Temp Target
(iAPS is allowed to give SMBs when there is a temporary target)After Carbs
(iAPS is allowed to give SMBs after carbs are added )With High BG
(iAPS is allowed to give SMBs when BG is high, as defined by the setting “...When Blood Glucose is over (mg/dl)”. Note that this setting is in mg/dl! Default is 110 mg/dl.)
Change the Max Delta-BG Threshold SMB to 0.3
to allow iAPS to use SMB when BG is rising quickly.Enable UAM
to allow iAPS to detect unannounced meals and dose insulin when needed.Do not enable any Dynamic Settings yet!
iAPS needs time to accumulate data before the dynamic features can work properly.Close Loop
Change your app icon in Preferences 🙂
You should now see that iAPS is looping every 5 minutes. The loop circle should be green, adjusting your basal rates and giving you SMBs.
The prediction lines in iAPS should be ignored for the first 24 hours. They do not have adequate data to be reliable. They are only used in dynamic calculations. For this reason, do not turn on dynamic settings in the first 24 hours.
In the first 24 hours, iAPS will likely keep lows away, and the night will be awesome. Meals and highs, however, will be hard to handle without manual intervention. You should enter carbs and bolus for meals. Use the “Bolus” feature to add the insulin you need if your BG is high. No need to add fake carbs to treat highs. Wait 24 hours while iAPS gathers enough information about your BG and TDD (Total Daily Insulin Dosage). This information is necessary before enabling dynamic features.
-
Tuning core settings
Because #WeAreNotWaiting, you probably want to turn on all the dynamic features by now. Before you do, please note that the dynamic features work much better if your core settings (ISF, CR, and Basal Rates) are fairly accurate.
The recommendation is to spend 2-7 days on this step. Some are ready to move on after a few days; others must spend more time adjusting settings.
Many users of other DIY solutions have assumed that their current core settings would work fine in iAPS. While existing core settings can be a good starting point, please be open to changing them. Each DIY algorithm utilizes the core settings in varying ways. What works in one may not work as well in another.
Your core settings should also be comparable in aggressiveness for iAPS to function optimally.
Tuning SMB and UAM
iAPS uses SMB and UAM to give you insulin when your BG rises. The amount of insulin you need is calculated with every loop cycle (5 minutes), but there are several safety limitations to ensure you do not get too much insulin.
The settings Max SMB Basal Minutes and Max UAM SMB Basal Minutes will limit how much insulin can be delivered in one SMB. The first is used when corrections above a temp basal adjustment are needed, and the second is when iAPS detects unannounced carbs.
The default setting for both is 30, meaning one SMB is limited to 30 minutes of your current basal rate. To calculate this limit, use the formula: (Max SMB Minutes/60) x current basal rate. If your basal rate is 1 U/h, SMBs will be limited to (30/60) x 1 = 0.5U. This is a delivery cap; it will only give up to 0.5U.
These default settings are conservative for many adult users. Consider raising them if you constantly get SMBs that max out the limitation.
Look at the Common Scenarios and ideas on how to solve them. We’ve added these under Guides - Common Scenarios.
When you are happy with your results, enable dynamic features.
-
Enable Dynamic ISF
iAPS will dynamically adjust your ISFEnable Dynamic CR
iAPS will dynamically adjust your CRDon’t touch the Adjustment Factor yet
This is a safety feature that limits how much impact the dynamic features can haveDisable Autosens features that will be handled by Dynamic ISF
Disable High Temptarget Raises Sensitivity
Disable Low Temptarget Lowers Sensitivity
Disable Sensitivity Raises Target
Disable Resistance Lowers Target
Wait for 24 hours and watch how iAPS handles things before adjusting more settings.
You can see how iAPS adjusts your ISF and CR at any time by tapping the loop status. You will see ISF: X -> Y and CR: X -> Y. This means that iAPS is dynamically adjusting your ISF and CR.
-
Here are some settings that may need tuning.
Autosens Max
This is a multiplier cap for autosens, autotune, and other dynamic features. The default setting is 1.2 (120%). The affected features will be limited to making your settings 20% more aggressive than your profile settings when BG is above target. Changing this setting to, e.g., 1.5 means that the affected features will be limited to making your settings 50% more aggressive than your profile settings.Autosens Min
This is a multiplier cap for autosens, autotune, and other dynamic features. The default setting is 0.7 (30% reduction). The affected features will be limited to making your settings 30% less aggressive than your profile settings when BG is below target. Changing this setting to, e.g., 0.6 (40% reduction) means that the affected features will be limited to making your settings 40% less aggressive than your profile settings.Adjustment Factor
The adjustment factor is a safety feature. It allows you to specify a value between 0.1 and 3 (10% - 300%). A lower adjustment factor will make ISF less aggressive (increasing your ISF number). A higher adjustment factor will make ISF more aggressive (decreasing your ISF number).The Sigmoid Formula requires a lower starting point for the adjustment factor. Because of that, the default value has been set to 0.5. If you are not using the Sigmoid formula, the recommended starting point is 0.7-0.8.
Max SMB and UAM Basal Minutes
These settings will limit how much insulin can be delivered in one SMB. The first is used when there’s COB, and the second is when iAPS detects an unannounced meal.The default setting for both is 30, meaning one SMB is limited to 30 minutes of your current hourly basal rate. If your basal rate is 1 U/h, SMBs will be limited to 0.5U. This is a limitation; it does not mean that 0.5U will be given.
These default settings are conservative for many adult users. Consider raising them if you constantly get SMBs that max out the limitation.
SMB Delivery Ratio
This is another safety feature intended to avoid dosing too much insulin. Then iAPS calculates how much insulin you need, the resulting SMB will be multiplied with this factor. The default value is 0.5, meaning half the calculated amount can be delivered. The amount will also be limited by Max SMB/UAM Basal Minutes.Please remember that iAPS does a new calculation with every loop cycle (5 minutes). This setting does not necessarily need to be changed.
Sigmoid or Logarithmic formula
By default, iAPS uses a Logarithmic formula for the dynamic ISF feature. This is the default and recommended setting for new users because it is built on documented research and has been tested for over a year in the AndroidAPS community. By not activating the Sigmoid formula, you are using the Logarithmic formula.The Sigmoid formula is a different approach to determining dynamic ISF. Rather than looking at historical data to determine ISF, the Sigmoid feature will change your ISF depending on how far away your current BG is from your target BG. While some users have successfully used the Sigmoid feature, it is still considered highly experimental and does not yet have a long track record.