Quick Start Guide

This guide assumes that you’re planning to Loop with a Dexcom G6, G7, ONE, or ONE+ and Omnipod DASH.  When you complete this 7-day process, you will have Nightscout, Loop, LoopFollow, LoopCaregiver, an Apple Watch app, and be able to use Loop’s remote commands.  Nightscout, LoopFollow and LoopCaregiver are not required but are strongly recommended.  Most caregivers end up using these “optional” tools, so it’s easier just to follow this guide and set them up as part of your initial process. 

Print out this Quick Start Guide and check off each section that you complete so that you’ll remember where you left off.  This guide is designed to be completed in approximately 7-days.  These days do not need to be consecutive, but you’ll need to set aside around 3 hours per day.

For your first time reading this Quick Start Guide, read these few pages without clicking on any links.

Note:  There are lots of options that aren’t covered in this guide.  If you prefer to use the Mac-Xcode build method to build Loop, LoopFollow, and LoopCaregiver, or are using another CGM, such as EU Libre 2, or a different pump such as Medtronic, you can still use this guide, but you’ll need to modify it for your exact set up.

Table of Contents

Once you’ve decided that Loop is right for you and your family, we will spend 7 days building and learning to operate Loop, as well as LoopFollow and LoopCaregiver. We’ll create a GitHub organization, build and install our apps, test settings and learn to use Loop’s remote commands.  Think of these 7 days as a multi-day baking process, similar to getting ready for a big holiday meal.

Learn About Loop – Before we even start the 7-day countdown, please decide whether Loop is right for you and your family.  This step is similar to scouring recipe books looking for just the right items to serve at your holiday meal.

DAY ONE – Initial Steps (about 3-5 hours, depending upon whether you build or buy Nightscout)

DAY TWO – Getting Ready to Build (about 3 hours)

DAY THREE – Build your Apps. (about 3-4 hours)

DAY FOUR – Installing and Onboarding (about 3 hours)

DAYS FIVE AND SIX – Test Settings

DAY SEVEN  – Test Remote Commands

What’s Next

Helpful Links

Flow Chart

Learn About Loop (about 10 hours)

Take your time, read, watch videos and ask questions. This should take about 10 hours, but please take as much time as you need – your T1D journey is a marathon, not a sprint.  If at any point during this process, you decide that Loop is not right for you or your family, there are other automated insulin delivery systems to consider.

Since there are lots of different types of learners, here are a few options to start your Loop journey.

LoopDocs – the Looping community’s most detailed documentation.  If you have a Loop question, it’s most likely addressed in LoopDocs.

Loop and Learn Starting Loop Series – a more detailed starting guide than the Quick Start Guide

Starting Loop YouTube Playlist – watch all or some of these videos that cover everything from how to build Loop to how to analyze Nightscout.

DAY ONE–  Initial Steps (about 3-5 hours, depending upon whether you build or buy Nightscout)

1. Gather your Gear:  You’ll need an iPhone running iOS 15.1 or higher, Dexcom G6, G7, ONE, or ONE+, Omnipod DASH, and a computer or tablet for building.  Be sure to request any needed prescriptions from your health care provider.  [Note:  Loop only requires iOS 15.1 or higher and LoopFollow only requires iOS 15.6 or higher, but LoopCaregiver requires iOS 16.  We recommend iOS 17 to new Loopers since it is unclear how much longer these lower versions of iOS will be supported by the Loop, LoopFollow and LoopCaregiver developers]
2. Apply for the Apple Developers Program.  While you’re waiting for your confirmation email from Apple, move forward with Nightscout.
3. Build or Buy Nightscout.  Nightscout is a website that captures glucose, carbohydrate, and insulin delivery history.  For all Loopers, Nightscout is very helpful for analyzing your Loop settings.  Mentors can use Nightscout to explain how your settings are impacting your results.  For caregivers/parents, it is a great tool to monitor your loved ones’ glucose, carbohydrates and insulin delivery on a real time basis, and Nightscout is required if you want to use Loop’s remote commands.  Your Nightscout site will have a number of configuration variables, also known as config vars.  Here is some information about common Loop config vars.  It refers to Heroku, which is one of the many Nightscout options, detailed in this comparison of some of your options.
   [Optional] Enter your Dexcom share config vars in Nightscout so that you can begin to use Nightscout to monitor glucose levels and become familiar with the site.  When you start to Loop, you’ll remove these config vars. 

Initial settings are important. Review your current pump settings, write them down, and review the settings advice here.   Many new Loopers who transition from traditional pump therapy find that their basal and Carb Ratio (CR) are too high for Loop, and Insulin Sensitivity Factor (ISF) is too low.  Your Diabetes May Vary (YDMV). 

Recommendations for initial settings:  Your diabetes may vary (YDMV); these are just suggestions and not medical advice.  Always listen to your healthcare provider.  Even if your settings resulted in 100% TIR (time in range) using your prior insulin delivery method, they will most likely need to be adjusted to work with the Loop algorithm.

• Use a single basal rate, Carb Ratio (CR), and Insulin Sensitivity Factor (ISF).  You will add more rates over the next few weeks.
• Single basal rate based upon your pump’s lowest scheduled basal rate
• Single CR that is equal to your average CRs
• Single ISF that is a multiple of your chosen CR
  • How much does a single gram of carbohydrates increase your new Looper’s glucose? Set your initial ISF as your CR multiplied by this amount.  For example, if 1g carbs raises your BG 5 mg/dL and your CR is 16 g/U, then a reasonable starting ISF in Loop might be 16 * 5 = 80 mg/dL/U.
  • Use your best estimate of what this impact is for your new Looper. As you add more CRs and ISFs to your settings, you’ll want to keep this important relationship in mind and make sure that your ISF is set as a multiple of your CR.
  • For those using mg/dL, a single ISF that is approximately 5 to 12 times your CR
  • For those using mmo/L a single ISF that is approximately 0.28 to 0.67 times your CR
  • For younger children, this number will be higher (for example, 12 mg/dL or 0.67 mmol/L)
  • For teenagers and adults, the number may be lower (for example, 5 mg/dL or 0.28 mmol/L).

5. Enter settings into Nightscout
   • Click on the lock symbol in the upper right corner of Nightscout and enter your API Secret
   • Click on Profile Editor
   • Use the green + symbol to add your settings
   • Click Save when finished

DAY TWO – Getting Ready to Build (about 3 hours)

We recommend the Browser Build Method.  You will need the Apple Developers’ license (mentioned on Day One) to complete these steps.

1. Create a Secrets Reference File in a text editor which won’t change formatting, like Notepad.
2. Create a free GitHub account.  Be sure to save your new GitHub username, password and other helpful information at the very bottom of your Secrets Reference File.
3. Create a GitHub Organization.
4. Collect your Secrets and add them to your Secrets Reference File.  These secrets are unique to you and help to link GitHub (where your code is stored) to your Apple developer account.
5. Install TestFlight app on any phone that you plan to use for the Loop ecosystem, which typically includes the Looping phone and both parents’ iPhones if the new Looper is a child.  Parents need TestFlight to install LoopFollow and LoopCaregiver, as well as a backup copy of Loop.  TestFlight is available in the App Store.

DAY THREE – Build your Apps. (about 3-4 hours)

Build  your Loop, LoopFollow and LoopCaregiver apps

1. Add your Secrets to your GitHub organization.  This is a one-time action.  You will add these secrets to the organization rather than to each repository, which will save time and reduce the chance of copy/paste errors.  You should think of a “repository” as a box that has the developers’ code in it.  You make a copy of their box when you “fork” their repository.  You update that box for the latest code when you “sync” to that repository.  You’ll see the words “repository”, “fork” and “sync” over and over again.
2. Build Loop.  Loop is an iPhone app that gets installed on the Looper’s phone.  Loop should also be installed on a backup phone (such as a parent’s phone or spare phone).  You’re going to build Loop within your new GitHub organization using these instructions and this video. The video is indexed with time-references which make it easy to repeat steps that you find confusing.  There are a few updates that occurred after the video was released; these comments are in the video notes, but putting them here too so that you don’t miss these important points:
   • Loop 3.4 was released, so keep that in mind while following the video.
   • NFC Tag Reading is now required for the “com.TEAMID.loopkit.Loop” identifier, so be sure to keep that checked.
   • For the API Key, instead of clicking “Keys”, now click “Integrations” instead, or use this link.
3. [Optional] Customize Loop.  You can customize your Loop app using some pre-configured options.   As a new Looper, you should consider the following customizations:
   • Upload Readings: Uploads CGM readings  to Nightscout
   • Profiles:  Establish multiple sets of settings for weekday vs weekend, for example.  You may not use this feature right away, but you’ll be glad to have it as an option.
   • Overrides:  Increase minimum override % to 50%.  This is an important safety customization since overrides lower than 50% are known to cause havoc on glucose forecasts and should be avoided.
   • For safety reasons, you should not Disable Authentication Requirements if your Looper is a child.

As you follow along in LoopDocs and/or the build video, you’ll be asked to add Users for your new Loop app.  If your Looper is under 13, you will not enter your Looper as a User.  Typically, one parent owns the Apple Developer account, so just add the other parent’s name and email address.  You will want to have the Loop app available in TestFlight on another iPhone because if the Looper’s phone is lost, stolen, broken or goes for a swim, this other iPhone can be a temporary Looping device.  You’d need to change your pod, but at least you’d be able to continue to Loop.

[Optional]  LoopFollow and LoopCaregiver do not need to be built if parents are using Android phones, or if the Looper is an adult.  However, even adult Loopers may want to use LoopFollow for the layout, stats, alarm capabilities and for a loved to follow glucose with improved alarms in comparison to the Dexcom app.

3. Build LoopFollow.  LoopFollow is an iPhone app that typically gets installed on a caregiver/parent/spouse’s phone.  LoopFollow uses Nightscout (or Dexcom Share) data to provide an easy-to-read dashboard with everything that you need to know about Loop’s status, and it has great alarms.  You can set up LoopFollow and begin using it right away.You are going to build LoopFollow within your new GitHub organization using these instructions and this video.  Skip past the instructions to add Secrets to your LoopFollow repository since you’ve already added them to your GitHub organization.
4. Build LoopCaregiver.  LoopCaregiver is an iPhone app that typically gets installed on a caregiver/parent/spouse’s phone. For using Loop’s remote command features, it provides a beautiful interface and makes authentication of remote commands easier.  LoopCaregiver requires Nightscout.  You’re going to build LoopCaregiver within your new GitHub organization using these instructions and this video.  Skip past the instructions to add Secrets to your LoopCaregiver repository since you’ve already added them to your GitHub organization.

DAY FOUR – Installing and Onboarding (about 3 hours)

Install Loop and LoopFollow using TestFlight

Install Loop on the Looper’s phone using TestFlight.  If your Looper is under 13, you’ll need to follow these instructions.  You will be guided through the Onboarding process, where you add your settings and devices.  This onboarding process will make sense as you move through it and LoopDocs has lots of details if you get stuck.  A few things to draw your attention to.

• Be sure to add your Nightscout URL and API secret.
• Select an extra wide correction range that is higher than you’re used to. For example, 120-180 mg/dL (6.6 – 10.0 mmol/L).  You will adjust this range later.
• Select a glucose safety limit that is up to 20 mg/dL (1.1 mmol/L) below the bottom of your correction range. For example, 100mg/dL or 5.5 mmol/L.   Again, you’ll adjust this later.
• You will not be asked to set your Duration of Insulin Action (DIA).  Loop uses an exponential decay model based upon insulin manufacturers’ testing. You do not have the option to modify your DIA within the Loop app.
• If you have an Apple Watch, open up the Watch app on your iPhone, scroll down to Loop and click Install.  Of course, the Watch app will only work when you’re in Bluetooth range of your iPhone, but it’s still a great option to have.

•  Your Looping phone is now a medical device, and you need to protect it .

1. 1. Turn on Parental Controls on your Looper’s phone.  Some young Loopers will advance the time on their phone to play games or accidentally delete their Loop app.   You can avoid these issues by following this advice
   2. If you initially set up your Looping phone to not use Passcode, Face ID, or Touch ID (for iPhone 8 and older), enable this important safety feature now.  Enabling this feature will reduce the likelihood of accidentally bolusing insulin or making changes to Loop’s settings.  Go to Settings > Face ID & Passcode [or Settings > TouchID for older phones].
      • Set up Passcode
        • Tap Turn Passcode On,
        • Enter a passcode,
        • Confirm
      • Set up Face ID
        • Tap  Set Up Face ID. Follow the on-screen instructions, including positioning your face in the frame and moving your head in a circle. If you have physical limitations, you can tap Accessibility Options.
        • Use Face ID for other functions
          • Go to Settings > Face ID & Passcode, and turn on the switch for the functions you want to use, such as iPhone Unlock, iTunes & App Store, Apple Pay, or very importantly, your Loop app.

[Optional]  LoopFollow is not needed if the Looper is an adult.  All others should install LoopFollow using TestFlight and add your Nightscout URL as your data source. You may be asked for an authentication token.

This guide will help you get started faster but ultimately, you need to slow down and learn about Loop before you actually connect a pump and CGM to use open source software to automate insulin delivery in Closed Loop mode on a full-time basis. 

DAYS FIVE AND SIX – Test Settings

All new Loopers should start in Open Loop mode. The first step is to test basal. Basal rates should keep your glucose steady in the absence of food, exercise, illness, etc.

In Open Loop mode, Loop will only deliver scheduled basal automatically.  Any correction or meal boluses are up to you.

Meals are tricky in Open Loop mode.  Loop is designed to be operated in Closed Loop mode and Loop’s algorithm will recommend upfront insulin and adjust insulin delivery to manage glucose levels.  This adjustment will not happen in Open Loop.  Instead, Loop will calculate Recommended Insulin (which you can accept or modify) and then continue to deliver scheduled basal, which may result in too much insulin.  For safety, you use the pizza emoji (5 hour absorption) so that Loop will recommend less upfront insulin.  It’s up to you whether to accept Loop’s recommendation or modify it to a lower amount.

Quiz:
1. Is your glucose steady (+/- 30 mg/dL or 1.65 mmol/L) over 4 hours in the absence of food? If you notice your glucose trending down or up outside of these parameters (+/- 30 mg/dL or 1.65 mmol/L), then adjust your basal rates up or down by a small amount a few hours before you see this climb or fall.  Once basal is producing desired results, then go on to Question 2.

2.  Choose a well known meal with predictable glucose effects – so don’t try a new pizza place when you’re doing this test.  Did your glucose level return to pre-meal levels within 3 to 4 hours after the meal?  If yes, then your CR is reasonable for now, otherwise adjust it up or down accordingly- by a small amount.  You’ll refine your settings most efficiently if you don’t move any setting by more than 5-10% at a time.

When you’re ready, click on Closed Loop so that it turns green.  You’ve set up a wide target range so Loop should protect you from both low and high glucose levels.  Initially, you can opt to stay in Closed Loop for a few hours at a time, extending the time period as you experience success in keeping your glucose within range.  You can even try Closed Loop overnight basal testing.  

Loop will deliver scheduled basal as long as it’s algorithm predicts that you will not drop below your glucose safety limit.  If your scheduled basal keeps your glucose steady in the abscence of food and exercise, then slowly narrow that range as you experience success.  If your glucose is steady, then try recording your next meal and accepting Loop’s recommendation.

This is a great time to set up your most important override.  You can edit it later, but for now, call it Low BG, and give it a target of 300 mg/dL (17.6mmol/L) and a duration of 1 hour.  You can use this after a low treatment to ensure that Loop doesn’t deliver more insulin than needed as glucose starts to climb.  Of course, as you become a proficient Looper, you should need fewer low glucose treatments, but T1D is so variable that they will unfortunately still happen.

This process may take between two and seven days. You are the best judge of when YOU are ready to move forward.

You may notice that in Closed Loop, you are seeing lots of variability or that your glucose is above or below the target range. These are both signs that your settings need some work.

Take a look through these settings resources:
https://loopkit.github.io/loopdocs/build/test-settings/#test-settings

The LnL Starting Loop Playlist has great video content for fine-tuning your settings.

DAY SEVEN  – Test Remote Commands  [Optional if not using remote commands]

 Now that you’ve been in Open Loop and have experimented with Closed Loop for several hours at a time, let’s focus on using Loop’s remote commands.

To utilize Loop’s remote commands, you need to set up new Nightscout config vars.
LOOP_APNS_KEY
LOOP_APNS_KEY_ID
LOOP_DEVELOPER_TEAM_ID
LOOP_PUSH_SERVER_ENVIRONMENT  [Note:  this config var is not required for Mac-Xcode builders]

Because you’ve used the Browser Build method, you will set the LOOP_PUSH_SERVER_ENVIRONMENT to production.  Be sure to save these config vars to the bottom of your Secrets Reference File.

To test Loop’s remote commands, pick a time when your Looper is with you.  We’re going to test remote commands in Nightscout first in order to make troubleshooting easier.

It is finally time to install LoopCaregiver on the parents’/caregivers’ phones using TestFlight.  Follow the LoopCaregiver onboarding process in LoopDocs.  To add your Looper to your LoopCaregiver app, you’re going to tap on the OTP (Loop/Settings/Services/Nightscout) to access the QR code.

Test a Remote Override to make sure that it is received on the Looper’s phone.  Turn off from Loop phone

Test a Remote Carbs of 1 gram to make sure that it is received on the Looper’s phone.

Test a Remote Bolus of 0.05u [or the lowest permitted by your pump] to make sure that it is received on the Looper’s phone.

If it succeeds, congratulations.  If it fails, try to troubleshoot it yourself.  If you are unable to resolve this on your own, just post a screenshot on FaceBook and provide details about iOS and Nightscout versions, as well as any troubleshooting steps that you’ve already taken; the more descriptive language that you use, the faster that your issues will be resolved.

[Optional] Before you settle in, if you have an Apple Watch, open up the Watch app on your iPhone, scroll down to LoopCaregiver and click Install.  Of course, the LoopCaregiver Watch app will only work when you’re in Bluetooth range of your iPhone, but it’s still a great option to have.

What’s Next?

Stay up to date!

Keep your apps up to date.  Loop will automatically update at least once per month on the first day of each month.  You just need to install it from TestFlight at least every 90 days.  LoopFollow and LoopCaregiver need to be manually rebuilt at least every 90 days.  LoopDocs has the detailed instructions, but here’s the summary version:

• Check Apple account status for new agreements, expired credit card info, etc. (5 min)
• Check if you need to renew distribution certificates (once a year only).  You should get an email from Apple 30 days beforehand.
• Log into your GitHub account and update your LoopFollow and LoopCaregiver repositories.  Both of these apps are under active development, so you should expect to need an update (5 min)
  • Click on Code in the upper left corner
  • In the center of the screen you should see
    • This branch is xx commits behind [repository name], or
    • This branch is up to date with [repository name]
  • If your branch is behind, just click Sync Fork 
• Run the Action>Build (5 min)
• Wait for the build to complete and appear in the TestFlight app on your phone (1 hour)
  • timing depends on GitHub, Apple and TestFlight
• Install from TestFlight onto your phone (5 min) 

Keep your Loop knowledge up to date.  At least once per week, follow along on Loop and Learn or Looped for important announcements, and subscribe to the Loop and Learn Newsletter.  You will learn new strategies for dealing with blood glucose management, how other Loopers are using Loop’s features, and be informed of any bugs that occur.  Be sure to ask lots of questions.

Helpful Links

This document is loaded with Helpful Links, but here are a few more.

Nightscout:  If you’re building your own Nightscout app, this template may help with your config vars.  It has a special section just for those building Nightscout using Google Cloud.

LoopFollow: How to use LoopFollow
LoopCaregiver:  How to use LoopCaregiver

Flow Chart

The Loop lifecycle involves learning about the algorithm, building and using it, then analyzing your settings.  Each successive turn around this cycle will be easier and take up less of your time.