Skip to content

Onboarding

New Looper

New Loopers Should NOT Use Loop-dev Before it is Released

Once Loop-dev is released, these Loop 3 pages will be moved to the Set Up section of LoopDocs.

To make life easier for those of us preparing the new documentation, the wording on many pages in the Loop 3 section is set in the future - after the release.

This is not an invitation for brand-new loopers to build Loop-dev as their first looping adventure.

Please review this page, and the rest of the Loop 3 Section (which will become the Set Up section once Loop-dev is released), before pressing any buttons on your phone with your new Loop 3 app.

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.

Click on this Video of Onboarding link to watch the onboarding process for a pre-release version tested in March 2022.

Entering and Editing Values

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

  • For more information on a specific therapy setting, tap on the information icon on the screen or review the detailed Therapy Settings page in LoopDocs
  • Some screens only have one value for a given quantity
    • In that case, you can tap on and edit that value
    • If you tap on the value and the Confirm Setting or Save button is inactive, move the picker value to make the button active,
  • Some screens allow different values for different times of day
    • Scheduled entries must start at midnight and at least one entry is required
    • During onboarding, new loopers must tap the + sign to get the initial midnight time slot
    • When one or more entries are present, tap the + sign to add an entry
      • Choose any time-slot without an entry
      • Enter desired value
      • Tap Add to include this entry in your schedule
    • Tap on a time-slot with an entry to edit it
      • You can change the time within the range of half hour after the slot immediately before and half hour before the slot after the slot under edit
      • You can edit the value to any allowed value
    • To delete one or more entries, tap on Edit
      • Then tap the red icon to the left of the time-slot you want to delete and select delete
      • Continue until done, then tap Done

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.

  • If the Apple Health units are mg/dL and you try to enter therapy settings suitable for mmol/L, or vice versa, the guardrails in Loop will prevent your entries
  • If this happens:

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 correct. You may need time to identify which settings need to be adjusted.

If you need help with your settings adjustment, head over to LoopTips for some initial settings help.

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:

  • Tap on the Share with Apple Heath button
  • Tap on the Turn On All button in the middle
  • Tap on the Allow button at upper right

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 using this link.

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
  • If you have do not have a Nightscout site, or choose not to use it, select Setup Loop without Nightscout and skip ahead to Therapy Settings (Onboarding)

  • If you have a Nightscout site, select Use Nightscout with Loop to connect Loop to your site and download your profile (Therapy Settings) from Nightscout for review.

Nightscout screens when onboarding if select Use Loop with Nightscout

If you select Use Nightscout with Loop:

  • The right side of the graphic above shows the screen used to enter your Nightscout URL (remember to use https: with the "s") and API_SECRET.
  • Once those credentials are accepted, choose whether you want to import your settings from your Nightscout profile (including any overrides previously saved).
  • Every Therapy Setting downloaded from Nightscout is presented for review.

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 correct, the predictions will not be correct.

  • Therapy Settings
    • An informational graphic is shown before you are asked to enter or confirm each therapy setting
    • This Onboarding Page provides a brief summary of each therapy setting.
      • Each onboarding therapy setting has a link to a more detailed description of the Therapy Settings.
      • If you follow a link, click on your browser back button to return to your place on this Onboarding page
    • While onboarding, you will see, in order:
      • Glucose Safety Limit
      • Correction Range
      • Pre-Meal Range
      • Basal Rates
      • Delivery Limits
        • Maximum Basal Rate
        • Maximum Bolus
      • Carb Ratios
      • Insulin Sensitivites

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 yellow indications with a grain of salt

  • It's OK to ignore "yellow" warnings when being conservative
  • Experienced loopers may choose to ignore "yellow" warnings to be more aggressive

A red limit cannot be exceeded without modifying the code itself.

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).

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.

  • This is only if you manually request a bolus recommendation.
  • Loop will not automatically provide extra insulin, via high temp basal or automatic bolus, until your current glucose is higher than the bottom of your correction range.

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 get you to 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.

Basal Rates

Only one Basal Rate schedule may be configured in the Loop app and the schedule must start at midnight.

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:

  • The values entered here will overwrite whatever is in your Medtronic pump when you first connect it
  • For those who build Loop 3 over an existing Loop app with a Medtronic pump attached - you will just be confirming values you used previously
  • If you have values in a Loopable Medtronic pump that you plan to attach after onboarding - please record those values if they are important to you

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:

  • The values entered here will overwrite whatever is in your Medtronic pump when you first connect it
  • Make sure that the Delivery Limit values in the Medtronic pump are equal to or greater than the values you enter while onboarding or you will not be allowed to connect to the pump.

Maximum Basal Rate

Maximum Basal Rate will cap the 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 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.

Carb Ratios

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

  • At least one carb ratio (CR) must be entered
  • A daily schedule with varying CR can be entered

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 different than the correction factor used with shots or manual pumping. Loop uses your ISF every 5 minutes when calculating predicted glucose levels.

  • At least one insulin sensitivity factor (ISF) must be entered
  • A daily schedule with varying ISF can be entered

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 the most 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.

  • Notifications are necessary for safety reasons while Looping.

  • Bluetooth lets Loop get data from your CGM and talk to your Pump.

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.

Medtronic CGM

If you plan to use a Medtronic Enlite sensor for your CGM, you must first add that pump to Loop before the sensor will be shown as an option.

If you built Loop 3 over an existing app, your CGM and pump selections should have carried over.

Experienced Loopers

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

  • If you build Loop 3 over Loop 2.2.x, the onboarding remembers the settings, previously saved overrides and your current pod or pump information is maintained. (Yes, you can build Loop 3 and keep using the same pod.)

  • If you build Loop 3 onto a device without an existing Loop app and you have a Nightscout site, you can enter your Nightscout URL (remember to use https: with the "s") and API_SECRET and it will ask if you want to import your settings from your Nightscout profile. This includes all the overrides you have previously saved.

  • If you are building on a device that does not have an existing Loop app and you choose not to use Nightscout, then follow the new Looper Onboarding Steps.

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 with Loop 2.x.x
  • Overrides: verify these are populated as expected
  • Pumps that use a RileyLink: confirm the device is selected and active in the Pump settings screen
  • Insulin Type: ensure the correct insulin type is selected

Carb Absorption Time Update

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

Loop-dev 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-dev 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, will be added to the documentation later. For now search in zulipchat.

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.

Back to top