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

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.

Table of Contents

Once you’ve decided that Loop is right for you and your family, we will spend 8 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 8 days as a multi-day baking process, similar to getting ready for a big holiday meal.

Learn About Loop – This step is similar to scouring recipe books looking for just the right items to serve at your holiday meal, and occurs before we even start the 8-day countdown. During this process, you will make a decision whether or not Loop is right for you and your family.

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

DAY TWO – Buy or Build Nightscout

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

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

DAY FIVE – Installing and Onboarding (about 3 hours)

DAYS SIX & SEVEN – Test Settings

DAY EIGHT  – Test Remote Commands

What’s Next

Helpful Links

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.

As you’re reading documents, watching videos and following along on Facebook, keep track of your questions, “save” posts that you think are particularly helpful, and pay attention to the feedback on the various Nightscout options.

DAY ONE–  Initial Steps (about 2-3 hours)

Gather your Gear: 

1. iPhone.  We recommend iOS 17 to new Loopers since it is unclear how much longer these lower versions of iOS will be supported by developers
   • Loop requires iOS 15.1 or higher
   • LoopFollow requires iOS 15.6 or higher
   • LoopCaregiver requires iOS 16 or higher
2. CGM
   • Dexcom G6, G7, ONE, or ONE+
3. Pump
   • Omnipod DASH
4. Computer or tablet for building

Apply for the Apple Developers Program

DAY TWO – Build or Buy Nightscout (1-3 hours, depending upon whether you build or buy)

• Nightscout is a website that captures glucose, carbohydrates, and insulin delivery history.
• Simplified comparison of Nightscout options.  You’ve been following along on Facebook, so you may already have an idea as to which Nightscout option that you’re going to select.
• For all Loopers,
  • Nightscout is very helpful for analyzing your Loop settings.
  • Mentors use Nightscout to explain how your settings are impacting your results.
• For caregivers/parents
  • Nightscout is a great tool to monitor your loved ones’ glucose, carbohydrates and insulin delivery on a real time basis.
  • Nightscout is required if you want to use Loop’s remote commands.
• Configuration Variables
  • 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 the Dexcom share config vars.

DAY THREE – 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 (where your identifiers, certificates and apps are stored).  Don’t worry if you don’t know what an identifier or certificate is – we’ll give you the steps.

DAY FOUR – 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.
   • Add these secrets to the organization rather than to each repository, which will save time and reduce the chance of copy/paste errors.
   • 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.
   • 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
     • Add Users:
       • 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 so that 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.

• 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.
  • Time-Saver:  You can skip past the instructions to add Secrets to your LoopCaregiver repository, and to Validate Secrets since you’re using a GitHub organization
• 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.
  • Time-Saver:  You can skip past the instructions to add Secrets to your LoopCaregiver repository, and to Validate Secrets since you’re using a GitHub organization

DAY FIVE – Installing and Onboarding (about 3 hours)

Install Loop using TestFlight

1. Install the 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, and the parents/caregivers are iPhone users.  Parents need TestFlight to install LoopFollow and LoopCaregiver, as well as a backup copy of Loop.  TestFlight is available in the App Store.
2. Install Loop
   • To 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.
   • To  a backup phone (such as a parent’s phone or spare phone); this phone will become the Looping phone in case of emergency where the Loop phone is lost, stolen, broken or goes for a swim.  Optional: mimic the Loper’s settings, and add a simulator pump and simulator.

Loop Onboarding

The process is straighforward, but here are a few tips (in the order in which they appear during the onboarding process)

Nightscout:  Be sure to add your Nightscout URL and API secret.

Therapy  settings are important. Review your current pump settings, write them down, and review the settings advice here.

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

• Glucose Safety Limit:  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.  You’ll adjust this later.
• Correction Range:  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).  Again, you will adjust this range later.
• Pre-Meal Range:  Set this the same as your correction range.  It’s very easy to accidentally click this button, so a pre-meal override is a preferred strategy.
• Use a single basal rate, Carb Ratio (CR), and Insulin Sensitivity Factor (ISF).  You will add more rates over the next few weeks.
• Carb Ratios:  Single CR that is equal to your average CRs
• Basal Rates:  Single basal rate based upon your current lowest scheduled basal rate
• Maximum Basal Rate:  2-3x your scheduled basal rate
• Maximum Bolus:  Your largest meal bolus.  This setting has added importance because it also sets your maximum IOB, which is 2x your maximum bolus.  Loop will never automatically deliver insulin if IOB would exceed maximum IOB.  This is true whether your insulin delivery method is temporary basal or automatic bolus. If you’re unsure what number to choose, for now, choose one that ‘s a little lower.  For example, if you sometimes have meals that require 5 units, but most meals require 2-3 units, then choose 3 units as your maximum bolus.
• Insulin Sensitivities:  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).
• Duration of Insulin Action (DIA):  You will not be asked to set your 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.
• Apple Watch:  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.

•  Medical Device:  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 SIX & SEVEN – 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 its algorithm predicts that you will not drop below your glucose safety limit.  If your scheduled basal keeps your glucose steady in the absence 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 EIGHT  – Test Remote Commands  [Optional: Only if 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.  The ordering of these tests is important.  Complete each test before moving onto the next.

Test One:  Test Loop override–>Nightscout  

Enable an override on the Looper’s phone and observe it on the Nightscout site. Cancel that override on the Looper’s phone by touching the override (heart) symbol in the Loop toolbar.

Test Four:  LoopCaregiver–>Loop

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.

1. Test a Remote Override to make sure that it is received on the Looper’s phone.  Turn it off from the Looper’s phone
2. Test a Remote Carbs of 1 gram to make sure that it is received on the Looper’s phone.
3. 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 (you can even rebuild from. your phone):

• 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