Skip to content
  • Home
  • Nightscout Overview
  • New Nightscout
  • Nightscout with Loop
  • Nightscout Troubleshooting
  • Nightscout Cross Ref
  • Remote Overview
  • Remote Configuration
  • Remote Commands
  • Remote Errors
    • LoopCaregiver
  • Translation

    • Onboarding

    Onboarding

    As soon as your app builds on your phone, you are guided through the onboarding (set up) process. You will see information screens for each Therapy Setting and must acknowledge each screen. You can review those informational screens later by clicking the Therapy Settings screen after a pump has been added.

    Entering and Editing Values

    This section explains how to enter and edit values with Loop 3.

    Screens

    With version 3 of the Loop app, the primary button, with an associated information message, is visible at the bottom of even small screens for many actions. You may need to scroll to see intermediate rows.

    There are other screens, like the Onboarding and Therapy Settings screens, where you are expected read all the provided information. Those screens require you to scroll to the bottom before being able to hit Continue or Save.

    Glucose Units

    First time connecting a glucose monitoring device to your phone's Apple Health app? If so, the units on the phone might not be in the units you want, i.e., mg/dL or mmol/L. Loop uses the units in Apple Health.

    Onboarding Steps

    Each onboarding step is presented in order on this page. Please follow this document while entering values into your app for the first time.

    Settings Help

    Please stay in Open Loop until you verify that your settings (basal rates, insulin sensitivity, carb ratio, etc) are properly adjusted to work with the Loop algorithm. You may need time to evaluate and perhaps identify settings to adjust.

    If you need help with your settings adjustment, you may find useful tips in the companion website, LoopTips at this link: LoopTips: Settings tab.

    Welcome to Loop

    The first screen you will see is the Welcome to Loop screen shown in the graphic below. Tap on Let's Go to continue.

    initial welcome screens when onboarding

    Apple Health Permissions

    Next, you need to give Loop permission to read and write to Apple Health. In the graphic below, from left to right, tap on the buttons highlighted with red boxes to configure permissions:

    You need to enable Health Permissions for Loop to work.

    setting up Apple Health permissions with Loop 3

    You can review the permissions screen later. FAQS: How Do I Modify Apple HealthKit Permissions.

    Usage Data Sharing

    Language?

    If the instructions on this screen are not your preferred language, make sure you built the released code.

    Next, you will be asked your preference for Usage Data Sharing, with the default automatically set to Share Version Only as shown in the graphic below:

    choose whether to share usage data with Loop developers

    If you choose to share usage data, it is collected anonymously. The choices are:

    Share Usage Data

    If you select Share Usage Data you may wonder types of information is available to the Loop Developers.

    The Loop Developers are the only ones with access to this data.

    Connect Loop to Nightscout

    The next screen, shown on the left of the graphic below, enables the user to both connect Loop to Nightscout and to download existing Loop settings from Nightscout.

    Nightscout

    • Nightscout is not required for Loop
    • It can be added later

    Loop 3 with Nightscout Requires API_SECRET

    • Even if you used Nightscout with Loop 2, you will neeed to add it again and you must include your API_SECRET

    Nightscout screens when onboarding if select Use Loop with Nightscout

    If you select Use Nightscout with Loop:

    Therapy Settings (Onboarding)

    The next onboarding screens take you through the therapy settings one at a time.

    The therapy settings are the heart of how Loop makes predictions. If your settings are not close, the predictions will not be correct.

    Guardrails While Onboarding

    Warning - Outside Typical?

    The Therapy Settings have "guardrails" to warn you if your settings are unusual.

    • Some indications are based on surveys of experienced Loopers
    • Some indications are for safety
    • It's fine to put Glucose Safety or Correction Ranges higher than "is typical"
    • It's fine to put Delivery Limits lower than "is typical"

    Take the yellow (and red) indications with a grain of salt. You will get an extra modal screen that you must acknowledge. Simply confirm your choice and keep going.

    A red limit cannot be exceeded without modifying the code itself. But values that show up as red can be saved - they are valid therapy selections.

    The Guardrails for Settings are summarized on the Therapy Settings page.

    Glucose Safety Limit

    If Loop predicts that your glucose will go below the Glucose Safety Limit at any time in the next 3 hours and Loop is in Closed Loop, it will set a temporary basal rate of 0 U/hr in an attempt to prevent that future low.

    If you ask Loop for a bolus recommendation, and loop predicts your glucose will go below the Glucose Safety Limit at any time in the next 3 hours, no bolus will be recommended.

    The Glucose Safety Limit can never be higher than the lowest of these related settings: Correction Range and Pre-Meal Range.

    Correction Range

    Loop uses the Correction Range as the goal when it recommends a bolus and makes automated adjustments to insulin dosing.

    Correction Range vs Time in Range

    For example, you may choose a correction range of 100-110 mg/dL (5.6-6.1 mmol/L) for Loop, but you may monitor your "success" or Time in Range using 70-180 mg/dL (3.9-10 mmol/L).

    Manual vs Automated Dosing

    Loop estimates future glucose over the next 6 hours (DIA) and, when in closed loop, adjusts insulin dosing. Loop uses or recommends the smallest amount of insulin that will bring you to your target (Correction Range midpoint) over the whole forecast.

    If you ask Loop for a manual Bolus recommendation while your current glucose is below the bottom of the correction range and above the glucose safety limit, Loop will recommend a value that should keep your glucose above the safety limit.

    Pre-Meal Range

    The Pre-Meal Range, which is optional, gives you a small amount of insulin before a meal to help control post-meal glucose spikes. The Pre-Meal icon is inactive if you choose not to enter a range.

    Example

    If your normal range is 100-110 mg/dL (5.6-6.1 mmol/L) and pre-meal range is 80-80 mg/d L (4.4 mmol/L), Loop will give you extra insulin to move you towards the lower range number before the meal. This early insulin brings you into the meal with a mini-prebolus. The pre-meal range, when activated by pressing on the pre-meal icon in the toolbar, will stay active for one hour, until carbs are entered, or until it is manually cancelled...whichever comes first.

    Carb Ratios

    Your Carb Ratio is the number of grams of carbohydrates covered by one unit of insulin.

    Basal Rates

    You must provide a Basal Rate schedule and the schedule must start at midnight. Loop does not provide the option for having more than one profile saved that you can switch between.

    If you onboard basal rates before a pump is added, you are limited to increments of 0.05 U/hr for basal rates and 0.00 U/hr is not allowed. Enter values close to what you actually use because the values determine your maximum basal rate in the Delivery Limits.

    Once a pump is added, the basal increments will match those on your pump. The onboarding basal rates will be saved to your added pump. Return to Therapy Settings to adjust the Basal rates to your pump increments.

    Medtronic Pump Users

    If you will be connecting a Medtronic pump after onboarding:

    Delivery Limits

    The maximum basal rate and maximum bolus settings are collectively referred to as Delivery Limits.

    The Maximum Basal Rate the app allows you to choose will be limited based on the basal rate schedule you just entered as well as pump limits, so make sure you put in sensible values. (There is a back button if you need it.)

    Medtronic Pump Users

    If you will be connecting a Medtronic pump after onboarding:

    Maximum Basal Rate

    Maximum Basal Rate will cap the maximum temporary basal rate that Loop issues to meet your correction range when you are in Closed Loop with a Dosing Strategy of Temp Basal Only.

    For safety, new loopers should start with a max basal set 2-3 times their highest scheduled basal rate. If you choose 2 times your highest scheduled basal, you may get a message informing you this is "lower than typical." Ignore this to put safety first as a new looper.

    Experienced loopers typically set their maximum basal rate around 3-4 times their highest scheduled basal rate. Loop 3 app will not allow you to exceed 6.4 times your highest scheduled rate.

    Maximum Bolus

    Maximum Bolus is the highest bolus amount Loop can recommend at one time to cover carbs or bring down high glucose.

    For safety, don't set a maximum bolus limit any higher than your typical large meal bolus. Many people like to set a value less than 10 U, for example, 9 or 9.9 U, to avoid accidentally typing in a bolus of 10 instead of 1.0 U.

    This setting also limits how much automated dosing is allowed. Loop will not automatically increase the user's IOB above two times the Maximum Bolus. This is true with Dosing Strategy of Temp Basal Only or Automatic Bolus.

    Insulin Sensitivities

    Your Insulin Sensitivity Factor is the drop in glucose expected from one unit of insulin over the entire duration of insulin activity. It may be a different value than what you used as the Correction Factor with shots or manual pumping. Loop uses your ISF every 5 minutes when calculating predicted glucose levels.

    Loop works best if you have tested and optimized your ISF settings for accuracy. Insulin sensitivities can change for many reasons including waiting too long to change your infusion set. Loop will not auto-detect changes in ISF.

    Incorrectly set ISF is a common cause of roller coaster glucoses for new Loop users. You may need to raise (increase) your ISF value/number to help smooth a roller coaster glucose trend. You can read about that topic more over in LoopTips here.

    Therapy Settings Review

    Once these are all entered, the Therapy Settings screen is shown for your review. You must scroll down to see all settings and reveal the Save Settings button. Only the top and bottom portions are shown, the other settings were not captured for this graphic.

    verify that all therapy settings are correct

    Notifications and Bluetooth

    Once you save settings, Loop asks to send notifications and use Bluetooth. You must allow both for Loop to work properly.

    enable notifications and BLE

    CGM and Pump

    For new Loopers, it is now time to add a CGM and a pump. Follow these links for instructions.

    If you built a new version of Loop over an existing app, your CGM and pump selections should have carried over, so long as the app was built with the same Apple developer ID.

    Experienced Loopers

    Insulin Type

    Insulin Type is in Pump Settings (not therapy settings) and will NOT be imported.

    After you finish onboarding, you must select Insulin Type on your pump settings screen. Without an insulin type, closed loop might not work or a different insulin type might be selected.

    The first time you build Loop 3 on a device, you will need to go through the onboarding process too.

    You will be presented with an information screen describing the setting (with a continue button) followed by your current settings (if available), which you must confirm to keep - or can modify and then confirm to change. Depending on the device you are using, you may need to scroll down to see the Continue or Save buttons for each setting.

    What is in my Nightscout Profile

    To check what is in your Nightscout profile that Loop would use as part of onboarding, follow these instructions.

    Note: you will get a json file - look that up using your favorite internet search method.

    1. Open your Nightscout URL
    2. Click in the URL address and append this text "/api/v1/profile.json"
    3. You can download the file and examine it if you are interested

    Check Imported Settings

    WARNING

    The new onboarding forces you to check all your imported Therapy Settings (Onboarding Summary) but there may be other settings you need to check as well.

    • Dosing Strategy: may be at the default value of Temp Basal Only, even if you were using Automatic Bolus before
    • Overrides: verify these are populated as expected
    • Pumps that use a RileyLink: confirm the device is selected and active in the Pump settings screen
    • If you use Nightscout, make sure the site is getting Loop updates

    HIGHLIGHTING THIS ONE - A LOT OF PEOPLE MISSED THIS:

    Carb Absorption Time Update

    If you used earlier versions of Loop, please be aware that absorption times have changed.

    Loop 3 Carb Absorption Times

    Loop uses the absorption time for the carbs, along with your glucose readings, ISF and CR to recommend insulin dosing and estimate over time the carbs absorbed and carbs expected. See Algorithm: Prediction for more details.

    • Loop 3 uses absorption times of 30 minute, 3 hours and 5 hours for the Candy, Taco, Pizza icons
      • Loop 2.2.x used 2 hours, 3 hours and 4 hours
    • The 30 minute (candy) time is for rapid acting carbs only

    If you selected the candy icon for a complex meal, you told Loop to expect your glucose to rise rapidly. When that rapid rise does not materialize, you may find Loop predicts an unexpectedly low glucose because the algorithm assumes something must be affecting your glucose downward in a strong way.

    If this happens to you, edit the carb entry to have a longer absorption time and Loop will recalculate the prediction.

    Carb Data Source

    Loop 3 does not read non-Loop carbohydrate entries from Apple Health, as previous versions did. It still writes to Apple Health. Some experienced loopers want to modify the code to enable Loop to read carbohydrate records from Apple Health with the full understanding of how that works. The instructions for this code customization option, using a flag set in the LoopConfigOverride.xcconfig file, see the Customize: Build-Time Features section.

    Users who build Loop 3 over Loop 2.2.x, may find a permission switch to give Loop permission to read carb data from health, but without making the customization mentioned above, changing permission does not change the behavior of Loop.