From e4e5018be5255ea68edf72f8b12f71701a37a7fb Mon Sep 17 00:00:00 2001 From: ebouchut Date: Tue, 19 Mar 2024 16:58:08 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20LoopKit/?= =?UTF-8?q?loopdocs@0e820bd643e4b5ce01426998c82765ce17fbd4a6=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- faqs/glossary/index.html | 1 + operation/algorithm/prediction/index.html | 4 ++-- search/search_index.json | 2 +- sitemap.xml.gz | Bin 127 -> 127 bytes 4 files changed, 4 insertions(+), 3 deletions(-) diff --git a/faqs/glossary/index.html b/faqs/glossary/index.html index 117e409532e..e61f92bf7a4 100644 --- a/faqs/glossary/index.html +++ b/faqs/glossary/index.html @@ -3359,6 +3359,7 @@

GlossaryDosing Strategy  (Dosing Strategy): chosen method for increased insulin dosing: (1) High Temp Basal or (2) Automatic Bolus with scheduled basal

dynos  (dynos): used to reboot a Nightscout Site

EmaLink  (EmaLink): radio-frequency device Loop uses to control Eros pods (aka. Gen 3) and older Medtronic pumps

+

EGP  (EGP): Endogenous Glucose Production: glucose produced by the body from its reserves (mainly glycogen in the liver)

Event History  (Event History): record of pump events (bolus or temp basal) reported and used by Loop

Expiration Date  (Expiration Date): your Loop app has a finite life, the app warns you starting 3 weeks before the expiration date

fastlane  (fastlane): used as part of the github Build Action method that enables building Loop without a Mac computer or Xcode

diff --git a/operation/algorithm/prediction/index.html b/operation/algorithm/prediction/index.html index 64ef118ccc0..e2b2583cc33 100644 --- a/operation/algorithm/prediction/index.html +++ b/operation/algorithm/prediction/index.html @@ -3733,7 +3733,7 @@

Insulin Effect on Blood GlucoseFor this example, assuming a user’s blood glucose was 205 mg/dL at the time of insulin delivery, Loop would predict a drop in blood glucose due to the two units delivered at 12 pm as shown in the figure below.

two unit example

Scheduled Basal Rates

-

In traditional basal/bolus pump therapy, basal rates are set to accommodate the user's endogenous glucose production (EGP) that causes blood glucose to rise. If a user's basal settings were exactly right in traditional pump therapy, the user would have perfectly flat blood glucose all day, all other factors being equal.

+

In traditional basal/bolus pump therapy, basal rates are set to accommodate the user's endogenous glucose production (EGP) that causes blood glucose to rise. If a user's basal settings were exactly right in traditional pump therapy, the user would have perfectly flat blood glucose all day, all other factors being equal.

In reality, people with type 1 diabetes, and their caregivers, know that basal settings are never exactly right. Every day is a little different, and a myriad of factors that affect blood glucose (e.g., including stress, hormones, sleep, etc.) may affect insulin needs. Some people have different basal profiles to accommodate these variations. Some people regularly tune and adjust their basal rates, and/or do so at their endocrinology clinic visits.

Since the Loop algorithm assumes that the user-set basal rates are correct, it calculates the effect of insulin relative to scheduled basal rates. If basal rates are not entirely correct, Loop can compensate a bit through the retrospective correction and blood glucose momentum effects, discussed later in this page.

The insulin delivery chart below displays a bar-graph history of the temporary basal rates enacted by Loop. The display is relative to the scheduled basal rates entered in the Loop settings. A rate displayed in this chart as +0 would indicate that no temporary basal rate was set and that the basal rate being delivered was the scheduled basal rate. Positive values indicate a temporary basal rate was set above the scheduled basal rate (i.e., more insulin delivered), and negative values indicate that a temporary basal rate was set below the scheduled basal rate (i.e., less insulin delivered).

@@ -3748,7 +3748,7 @@

Total

Loop's iob and temp basals

The insulin effect can be expressed mathematically:

\[ \Delta BG_{I}[t] = ISF[t] \times IA[t] \]
-

where BG is the expected change in blood glucose with the units (mg/dL/5min), ISF is the insulin sensitivity factor (mg/dL/U) at time t, and IA is the insulin activity (U/5min) at time t. Insulin activity can also be thought of as a velocity or rate of change in blood glucose due to insulin. The insulin activity accounts for the EGP and any active insulin from basals and boluses.

+

where BG is the expected change in blood glucose with the units (mg/dL/5min), ISF is the insulin sensitivity factor (mg/dL/U) at time t, and IA is the insulin activity (U/5min) at time t. Insulin activity can also be thought of as a velocity or rate of change in blood glucose due to insulin. The insulin activity accounts for the EGP and any active insulin from basals and boluses.

Carbohydrate Effect

Carbohydrates will raise blood glucose, but the speed and degree to which they impact blood glucose are dependent on the type of carbohydrates. High glycemic index (GI) carbohydrates will raise blood glucose quickly over a shorter time, whereas low GI foods will raise blood glucose more slowly over a longer period. Foods like candy, juice, and fruits tend to be high GI foods, while pizza, burritos, and quesadillas are usually lower GI foods. Digestion issues like gastroparesis may also contribute to variations in carbohydrate absorption.

Because carbohydrate absorption can be quite variable, Loop has a model that dynamically adjusts the expected remaining time of carbohydrate absorption. To start with, Loop allows the user to input a rough guess of how long they think the food or drink will take to absorb. The user’s guess is used as a middle of the road estimate, and Loop’s algorithm will shorten or lengthen it based on observed blood glucose change.

diff --git a/search/search_index.json b/search/search_index.json index aa4fd2e332f..75885bb12bc 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"

Welcome to the LoopDocs website where you can learn about the Loop app.

"},{"location":"#what-is-the-loop-app","title":"What is the Loop App?","text":"

The Loop app is an automated insulin delivery application that you build and operate on an iPhone.

"},{"location":"#what-isloopvideo","title":"What is\u00a0Loop\u00a0Video","text":"

Loop\u00a0Video

"},{"location":"#what-are-my-next-steps","title":"What are my next steps?","text":"

This site shows you step-by-step how to build, set up and operate the Loop app.

In order to become proficient with the app, you should learn the information on this site. Consider doing this over a period of time and reviewing the materials more than once.

There is a common saying in our community:

Do It Yourself (DIY) does not mean Do It Alone!

Once you are using the app, you should regularly follow one or more support forums for important updates on the Loop app. Spending this time is important for success in building and operating the Loop app safely.

This website is updated regularly to keep pace with development of the Loop app and Apple releases.

"},{"location":"#important-disclaimer","title":"Important Disclaimer","text":"

Please consult with your health care professional regarding your diabetes management.

"},{"location":"#volunteer-community","title":"Volunteer Community","text":"

The Loop app has been, and continues to be, developed and supported by volunteers. From the code to this website, you are able to use this app because many volunteers continue to give their personal and family time.

Please add your time by reading this website before embarking on your Loop journey.

"},{"location":"translate/","title":"Translation","text":""},{"location":"translate/#language-list","title":"Language List","text":"

\u0639\u0631\u0628\u064a

\u0411\u044a\u043b\u0433\u0430\u0440\u0441\u043a\u0438

\u010ce\u0161tina

Deutsch

Dansk

\u0395\u03bb\u03bb\u03b7\u03bd\u03b9\u03ba\u03ac

Espa\u00f1ol

\u65e5\u672c

Suomi

Fran\u00e7ais

\u05e2\u05d1\u05e8\u05d9\u05ea

Hrvatski

\u0939\u093f\u0902\u0926\u0940

Italiano

\ud55c\uad6d\uc5b4

Norsk

Nederlands

Polski

Portugu\u00eas

Rom\u00e2n\u0103

\u0420\u0443\u0441\u0441\u043a\u0438\u0439

Sloven\u010dina

Svenska

Turkish

\u4e2d\u6587\uff08\u7b80\u4f53)

\u4e2d\u6587\uff08\u7e41\u9ad4)

"},{"location":"translate/#google-translate-links","title":"Google Translate Links","text":"

Click on a language on the list of links above to turn on Google's automatic translation.

"},{"location":"translate/#change-language","title":"Change Language","text":"

To modify the language choice for the whole site, copy the line below, and paste it into the URL, and then choose the desired language from the list above.

Copy and Paste in Browser URL to return to original version
https://loopkit.github.io/loopdocs/translate\n

OR

Use the Google Translation three-dot menu and select Go to Original URL while on the Translation page.

"},{"location":"translate/#more-information","title":"More Information","text":"

Automatic Translation

These links connect this site to the Google Translation service.

"},{"location":"translate/#google-translate-tool-instructions","title":"Google Translate Tool Instructions","text":"

Once Google Translate has been turned on, clicking on a language link above shows a \"Google Translate: Can't translate this page error\".

The graphic below shows the Google Translate Tool when maximized (default) for a browser and mobile display. The tool can be minimized by tapping on the up/down carets at the right of the tool. This is very useful if the tool obstructs part of the original screen. Additional options can be selected with the three-dot menu as shown in the graphic.

"},{"location":"build/apple-developer/","title":"Apple Developer Program","text":""},{"location":"build/apple-developer/#enroll-in-apple-developer-program","title":"Enroll in Apple Developer Program","text":"

Time Estimate

Summary

There are two options: Paid ($99/year) or Free (re-build weekly, Xcode only)

FAQs

"},{"location":"build/apple-developer/#loopers-need-their-own-apple-id","title":"Loopers Need Their Own Apple ID","text":"

The Apple ID is DIFFERENT than the Apple Developer ID.

Apple ID

Parents should set up a different Apple ID for each of their looper children and looper children should not use the parent Apple ID. Use Apple's Instructions for Create an Apple ID for your child.

The Apple Health record is a convenient record of blood glucose, insulin and carbohydrates and should be associated with only one individual.

Sharing an Apple ID among two or more loopers can cause safety issues. You don't want Sally to be dosed for Joe's lunch in addition to her own and vice versa.

"},{"location":"build/apple-developer/#developer-account","title":"Developer Account","text":"

To build the Loop app on a phone, you must use an Apple developer account associated with an adult (minimum age of 18). This Apple developer account is tied to the email address associated with your Apple ID. You can build apps on phones for everyone in your family with a single Apple Developer Account tied to the Apple ID of an adult.

You have two options for an individual account: free or paid.

"},{"location":"build/apple-developer/#free-developer-account","title":"Free Developer Account","text":"

If you decide to use a FREE developer account, here's what you need to know:

  1. You must use the Build with Mac method to build Loop.
  2. Loop apps signed with a free developer account will expire after 7 days. On the 7th day, your Loop app will simply turn white when you open it and then immediately close. To rebuild the Loop app, you will have to find a computer and rebuild the app onto your iPhone again. You cannot rebuild the app on day 5 (when it is convenient, for example), hoping to reset the 7-day clock. The app will still expire on the 7th day from when it was first signed and created.
  3. If you decide to switch to a paid account after trying out the free account, you will need to rebuild your Loop app to sign it with the new paid account. Furthermore, switching from a Free to a Paid account requires entering all the settings again (and starting a fresh pod).
  4. You will have to do an extra step during the build process to remove Siri and Apple Push capabilities to build with free accounts. Because free accounts do not have access to Apple Push notifications, you will also not be able to use Remote Commands through Nightscout.
"},{"location":"build/apple-developer/#paid-developer-account","title":"Paid Developer Account","text":"

If you decide to use a PAID developer account, here's what you need to know:

  1. The paid developer account is $99 per year. The default setting is to auto-renew annually. You can change that selection in your developer account settings at any time.
  2. If your household has multiple Loop users, only one developer account is needed. That one developer account can be used to build Loop on multiple phones.
  3. If you use the Browser Build method
    • You must Update with Browser the build once every 90 days
    • You must have a Paid Developer account
  4. If you use the Build with Mac method
    • If you have a paid developer account, you must build at least once a year
    • If you have a free account, you must build every 7 days
"},{"location":"build/apple-developer/#switching-from-free-to-paid-memberships","title":"Switching from Free to Paid Memberships","text":"

You can try a free account first before buying a paid developer account. If you start with a free account, you'll build a Loop app (let's call it FreeLoop). When you switch to a paid account, you'll be building a totally new and separate Loop app onto your phone (let's call it PaidLoop).

The two apps will look identical on your phone and they will both have the name Loop with the same icon, but they will be functionally separate from each other. Make sure you are successful building the PaidLoop app before deleting the FreeLoop app from your phone. Use the search feature on your phone to find both apps. One will have your configuration settings (FreeLoop), the other will not (PaidLoop).

Before deleting the FreeLoop, either record all the settings or take screenshots of all the relevant settings screens.

PaidLoop will know nothing about the settings and information you had stored in FreeLoop, so you will need to re-enter all your settings (basal rates, ISF, carb ratios, etc.) and configurations into the new PaidLoop. It will also not connect or control any pods you are currently using with the old FreeLoop app. The one exception is Nightscout credentials, which are stored in your keychain. If you entered your Nightscout credentials into FreeLoop, they will persist across app removal and be used by PaidLoop.

With Loop 3, if you use Nightscout, you can import settings that were uploaded to Nightscout by FreeLoop into PaidLoop, so that simplifies the transition.

Once PaidLoop is working, delete the FreeLoop instance from your phone to avoid confusion. If you followed the directions when building, you may have configured your phone to prevent deletion of Loop. Head over to Protect that App, reverse the steps, delete FreeLoop, then do the steps again to protect PaidLoop.

"},{"location":"build/apple-developer/#enrolling","title":"Enrolling","text":"

To enroll in an individual paid Paid account, go to the Apple's Developer Program website Apple Developer website.

Be sure to use the credit card already associated with the email you are using for the developer account. If you switch credit cards, it can cause delays.

If you choose to use the free account, you don't have to do anything on that website. You'll just wait for the instructions on the Xcode Settings page and get your free account then.

"},{"location":"build/apple-developer/#next-steps","title":"Next Steps:","text":"

Take the time to read the next three articles. You will be reminded again when you begin to set up your app.

"},{"location":"build/build-app/","title":"Build Loop","text":""},{"location":"build/build-app/#summary","title":"Summary","text":"

Time Estimate

Summary

You will:

FAQs

"},{"location":"build/build-app/#build-video","title":"Build Video","text":"

The Loop and Learn team prepared this YouTube video showing how to build Loop 2.2.x including the steps required to update if you previously built. The steps are different now. The video may be worth watching, but once you've reviewed it, work through the new build process described on this page.

If you do watch this video, please note that you no longer are required to delete provisioning profiles as a separate step and the overall building process is streamlined.

"},{"location":"build/build-app/#build-with-browser","title":"Build with Browser","text":"

If you previously used Build with Browser to install Loop on this phone, you should Disable Automatic Install from TestFlight to be sure the version of the app on the phone is the one you build with Xcode.

"},{"location":"build/build-app/#developer-mode","title":"Developer Mode","text":"

If you are running iOS 15/watchOS 8, you do not have Developer Mode and can skip ahead to Download Loop.

"},{"location":"build/build-app/#upgrade-from-ios-15-to-newer-version","title":"Upgrade from iOS 15 to newer version","text":"

If you upgrade an iOS 15 phone to iOS 16 or 17, the Loop app will not open until you enable Developer Mode on that phone.

You will see a message similar to the next graphic.

If you are running iOS 16 or 17 with watchOS 9 or newer, you must enable Developer Mode to run or build Loop directly from Xcode. (This is true for any app created by Xcode directly on your device.) If you want to know more, click on this Apple Link about Developer Mode.

"},{"location":"build/build-app/#prepare-your-phone-and-watch","title":"Prepare your Phone and Watch","text":"

If you have never built an app with Xcode on a particular phone, Developer Mode will not show up in the iOS Settings, Privacy & Security menu until you connect that phone to Xcode.

To keep all the steps in one place, the instructions for configuring phone and watch are kept in this one section. If you have never built with Xcode to this phone, skip ahead to Download Loop for now and return at the appropriate part of the script instructions below. A clear message with a link will bring you back here.

When Xcode is open and you plug in your phone, you will not be able to select the phone until you have enabled Developer Mode. The phone will show up, but be an \"Unavailable Device\" as shown in the graphic below.

"},{"location":"build/build-app/#developer-mode-on-iphone","title":"Developer Mode on iPhone","text":"

Once your phone has been plugged in to the computer while Xcode is opened and you accepted have the Trust this Computer option, you will be able to enable Developer Mode.

  1. Open your phone settings, choose Privacy & Security
  2. Scroll to the bottom of the screen and examine the Developer Mode row
    • If it says On - no further action is required
    • If it says Off, then tap on the row
  3. Slide the slider to the green (enabled) position
  4. Choose Restart
  5. After reboot, choose to Turn on Developer Mode
  6. You are now ready to begin building from Xcode onto this phone

If you are in the middle of building on a new phone, return to Initial Xcode Screens to continue.

"},{"location":"build/build-app/#developer-mode-on-watch","title":"Developer Mode on Watch","text":"

Build, Enable, Build

Reports from users indicate that when you are building to a new Apple Watch - you must first build the app with Xcode before the developer mode will be available. So plan to build with Watch paired, and then enable Developer Mode and build again.

This must be configured on the watch itself (not the watch app on the iPhone). To determine if Developer Mode is enabled, look at the watch face icons and find the Settings icon. Tap on it and scroll to and tap the Privacy & Security icon. Then scroll to the bottom and tap on Developer Mode. If you don't see the Developer Mode row under Privacy & Security, see the Extra Watch Instructions.

"},{"location":"build/build-app/#enable-watch-widgetkit-developer-mode","title":"Enable Watch WidgetKit Developer Mode","text":"

With the latest watchOS, there are now options that show up after you enable Developer Mode. Go on and configure those now. Select the Settings icon on the watch, but instead of tapping on Privacy & Security, scroll all the way to the bottom and there is now a Developer row at the very bottom of the watch Settings. If you don't see this row, reboot the watch again.

"},{"location":"build/build-app/#extra-watch-instructions","title":"Extra Watch Instructions","text":"

There have been a lot of reports of trouble getting Developer Mode to show up on a new Apple watch and then having further trouble getting the Loop app to show up on the watch. Previously, just having the watch paired to the phone when you build once followed, by enabling Developer Mode on the watch and building again, was enough. If you have problems, here are extra steps to try.

These steps have been reported on Facebook and have not been tested in a controlled environment. They may not all be necessary.

  1. Restart watch, phone and computer
  2. Watch should be paired to your phone and on your wrist
  3. Go to Privacy & Security on watch and enable developer mode (didn\u2019t see prior to restart)
  4. Plug phone into computer and open Xcode
  5. Select Window (top menu) and choose Devices & Simulators
    • The watch should appear as a Disconnected device
    • Click on the watch and if it connects - you are done
  6. Otherwise manually add the UDID to your Developer Account
    • Copy UDID (right-click or control-click and choose Copy Identifier)
  7. Go to the Apple developer website, devices page and manually add the watch (using the UDID)
  8. With phone plugged into computer and watch on wrist, follow these steps on the build errors page: Apple Watch Loop App not running on Watch to build the watch app directly.

At this point, be sure to reboot the watch.

"},{"location":"build/build-app/#download-loop","title":"Download Loop","text":"

This page has the detailed steps to run the Build Select Script to download the Loop code, prepare your computer and build Loop.

Every attempt was made to put messages directly in the script for each step. The next few sections of this page walk you through what you will see when you run the script.

"},{"location":"build/build-app/#open-terminal","title":"Open Terminal","text":"

Go to the Finder app, click on Applications, then open the Utilities folder. Locate the Terminal app and double-click Terminal to open a terminal window. The terminal window is very plain looking when you open it. That is normal.

"},{"location":"build/build-app/#build-select-script","title":"Build Select Script","text":"

With the release of Loop 3, the build process is different and simpler

These instructions show each step needed to download Loop using the Build Select Script.

Copy the line below that starts with /bin/bash by hovering the mouse near the bottom right side of the text and clicking the copy icon (should say Copy to Clipboard when you hover over it). When you click the icon, a message that says Copied to Clipboard will appear on your screen.

Copy and Paste to start the Build Select Script
/bin/bash -c \"$(curl -fsSL \\\n  https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildSelectScript.sh)\"\n

Paste the line of text into Terminal. Be sure to click anywhere in the terminal before trying to paste. (Ways to paste: Cmd+V ; or Ctrl click and select from menu or Edit-Paste at top of Mac screen.)

You will be informed of the menu options as shown in the graphic below. You will choose Option 1 to Build Loop.

You will be informed that you are downloading open source software. Type 1 and return if you understand the warning and agree.

The next screen informs you of what you will be downloading. Type 1 and return to begin the download or 2 to return to the main menu.

"},{"location":"build/build-app/#wait-for-download-to-complete","title":"Wait for Download to Complete","text":"

This download can take from 3 minutes to 30 minutes depending on your download speed. You can leave the room and return later to check on progress. When you read the words in the terminal, as the script runs, you may see terminology you do not understand - don't worry - you do not need to understand enumeration or submodule or cloning. You only need to review the display to look for any error messages.

New Feature

The Build-Script automatically reports when the download is successful.

The next graphic shows terminal messages for the beginning of a successful download.

If the download was successful, your terminal will be similar to the following graphic. Continue with the Download was Successful section.

If you see a failure message, scroll up in the terminal to find the error message(s) and go to Xcode Errors with Build-Select.

"},{"location":"build/build-app/#download-was-successful","title":"Download was Successful","text":"

If there are no errors, hit return to continue. The next step involves signing the targets.

"},{"location":"build/build-app/#sign-targets","title":"Sign Targets","text":"

What does Sign Targets Mean?

\"Sign Targets\" in Xcode identifies who built the app. You cannot deploy an app to a phone if you do not sign each target associated with that app.

Experienced Builders

This replaces several of the steps that used to be required to build Loop.

If you have never built an Xcode app using your developer ID on this computer, then the first time you use the script, you will be asked how you want to sign the targets.

I did not get this question

The script searches for your developer ID for you and skips this question if it finds it.

Skip ahead to Review LoopConfigOverride.xcconfig.

The next question, as shown in graphic below, is whether you will (1) Sign Automatically or (2) Sign Manually.

"},{"location":"build/build-app/#paid-developer-account","title":"Paid Developer Account","text":"

Continue with this page only if you have a paid developer account.

"},{"location":"build/build-app/#create-permanent-loopconfigoverridexcconfig","title":"Create Permanent LoopConfigOverride.xcconfig","text":"

The following graphics show the terminal display after selecting option 1 to use Apple Developer ID.

After hitting return, the user can verify the entry.

"},{"location":"build/build-app/#review-loopconfigoverridexcconfig","title":"Review LoopConfigOverride.xcconfig","text":"

Once the permanent signing file is configured, the review step is the same each time.

"},{"location":"build/build-app/#problem-with-the-id","title":"Problem with the ID?","text":"

If there is a problem with the ID that is stored on your computer, you can modify it before continuing. The instructions, shown in the terminal message if you select option 2, Editing Instructions, are repeated here:

To edit the LoopConfigOverride.xcconfig file with a different developer ID:

  1. Open finder, navigate to Downloads/BuildLoop
  2. Locate and double click on LoopConfigOverride.xcconfig
    • This will open that file in Xcode
  3. Edit in Xcode and save file

You can now return to the terminal and hit return for the next step.

"},{"location":"build/build-app/#ensure-a-year","title":"Ensure a Year","text":"

The next question asks if you want to ensure a year with your new app. Unless you have a good reason, you should enter 1 and continue.

"},{"location":"build/build-app/#build-loop","title":"Build Loop","text":"

Build to Simulator

If you are an experienced builder and plan to build to a simulator on your Mac before building to your phone, you do not need to plug in your phone yet. You will need to select a simulator manually once Xcode opens.

For first time builders - go on and build to your phone.

"},{"location":"build/build-app/#plug-in-your-phone","title":"Plug in Your Phone","text":"

Refer to the graphic below. The messages in the terminal instruct you to:

The next action of the script is to

If this is a new phone that has never had an app built from Xcode, return to Prepare your Phone and Watch. After you get developer mode turned on for the phone continue with the build instructions. If you also want to set up the watch, you'll need to build one time, follow directions in Developer Mode on Watch and then build again.

It is suggested that you wait until you've successfully built the app before closing the terminal.

"},{"location":"build/build-app/#initial-xcode-screens","title":"Initial Xcode Screens","text":"

Refer to the graphic below. Your intial Xcode screen should be similar.

"},{"location":"build/build-app/#start-build","title":"Start Build","text":"

If there is a red x in the dashed-blue rectange region on your Xcode screen you need to click over to the Build Error page

"},{"location":"build/build-app/#first-time","title":"First Time","text":"

The first time you build, there will be steps that will not be required for subsequent builds. These are clearly marked in the intructions with the word First-Time. Do not get confused when you are asked to enter your password multiple times, see Codesign / Keychain Access. Be sure to enter your Mac login password and select Always Allow every time it is requested.

"},{"location":"build/build-app/#all-builds","title":"All Builds","text":"

Refer to the GIF below:

If the app opened on your phone, the next two sections for first-time builders are not needed. Skip ahead to Successful Build.

If you got red error messages, skip ahead to Build Failed?

"},{"location":"build/build-app/#codesign-keychain-access","title":"Codesign / Keychain Access","text":"

First Time Using Developer ID on Computer

During your first build with a given Developer ID on your computer, you will see a codesign/keychain access prompt, as shown in the graphic below. Enter the same password you use to log in to the mac, select \"Always Allow\" and then do it again each time you are asked.

It is normal for this prompt to come up repeatedly even after you enter the correct password (once for each target Loop needs to sign).

In frustration, people think the prompt must be broken because it keeps reappearing and press deny or cancel. Don't press deny. Keep entering your computer password and pressing the \"Always Allow\" button as many times as it takes. The build will then continue.

FYI: codesign is for code sign - nothing to do with design.

"},{"location":"build/build-app/#update-settings-for-developer","title":"Update Settings for Developer","text":"

First Time Building on a New Device?

If this is the first time you have installed an app on your iPhone using a free account, you will see warnings in both Xcode and on your phone after a successful build and install on your phone.

Don't worry, dismiss the messages and do this extra step on the phone. These instructions are valid for iOS 15:

"},{"location":"build/build-app/#what-if-the-automatic-signing-failed","title":"What if the Automatic Signing Failed?","text":"

Sometimes, something goes wrong with the automatic signing. Just the fact that you clicked on a few places in Xcode can change a particular file required to enable automatic signing. It is possible to reset that file, but it is easier to sign manually.

"},{"location":"build/build-app/#build-failed","title":"Build Failed?","text":"

No red error messages? Skip ahead to Successful Build.

Red Errors

If you get a message that your build failed and see RED ERROR messages:

FAQ: But what about those yellow or purple warnings that remain in Xcode? Should I worry about them?

If you see yellow or purple warnings after your build is done...those are not an issue. Don't try to resolve them or fret about them. They mean nothing to the successful use of your Loop app.

NOTE: purple warnings are still warnings and can be ignored.

"},{"location":"build/build-app/#clear-the-error-message","title":"Clear the Error Message","text":"

Once you've resolved a build error and start the build process again, Xcode will continue to show a red indicator on the top line from the previous failure. If you don't like seeing that, clean the build folder to clear the error. Otherwise, as long as the steps of the build are showing across the top line, Xcode is still working on the build. When the build succeeds, the red circle will disappear.

Clean Build Folder

"},{"location":"build/build-app/#successful-build","title":"Successful Build","text":"

After you see the Loop app open on your phone, you can unplug your phone and acknowledge the Xcode message: Lost connection to the debugger on . . .. The square icon next to the play button goes away as soon as you unplug your phone from Xcode.

The Loop app on your phone closes (but does not quit) when you unplug the phone. Open the Loop app on your phone just to be sure.

Congratulations!

If you plan to build again on a backup phone, or want to try a customization, easiest for you to leave Xcode open. Otherwise, you can quit out of Xcode now.

But wait - there's more.

"},{"location":"build/build-app/#protect-that-app","title":"Protect that App","text":"

Protect Against Deletion

Prevent your Loop app from being deleted accidentally.

If you, or a child, deletes the app from the home screen, it is gone - you have to rebuild and reenter all settings and start a new pod or add back in your Medtronic pump.

The steps vary depending on iOS. With iOS 15 and 16, it is under Screen Time, Content & Privacy Restrictions, iTunes & App Store Purchases, Deleting Apps. Choose Don't Allow. If those steps don't help, do an internet search like this, where you use your current phone iOS version number:

Follow the instructions to prevent deletion of what is now a critical medical app.

"},{"location":"build/build-app/#important-safety-reminder","title":"IMPORTANT SAFETY REMINDER","text":""},{"location":"build/build-app/#new-to-loop-3","title":"New to Loop 3","text":"

If this is your first build with Loop 3, head to the Set Up tab starting here: Loop 3 Overview.

Pro Tip: Read Along in LoopDocs as you Onboard

One of the goals for Loop 3 is to make the app robust even if you don't read the documentation, but a lot of questions may be resolved if you read along in LoopDocs as you onboard.

All those mentors who answer questions are volunteers.

Even if you don't read all the pages under the Set Up tab now, these links are important.

Add a Calendar Reminder

"},{"location":"build/build-app/#optional-steps","title":"Optional Steps","text":""},{"location":"build/build-app/#code-customizations","title":"Code Customizations","text":"

New Loop users: Customizations are not a required part of any Loop build. As you gain experience using your Loop app, you may want to customize some of the features. First time builders are encouraged to build with the standard, default code. You can always update your Loop app to add customizations at a later time, using the same download. Subsequent build time is much faster than the initial build for a given download.

Pro Tip

With a fresh download of code, it's always best to build to a simulator without customization to ensure the build works without errors. Then add the customizations and check the build again. Now you are ready to build to your phone to update your existing app.

To add custom configurations to your Loop or Loop Apple Watch apps, follow the step-by-step instructions on the Code Customizations page and then build the app again.

"},{"location":"build/build-app/#apple-watch","title":"Apple Watch","text":"

Existing Apple Watch users: Please update your watchOS prior to building the Loop app. The minimum iOS for Loop 3 is iOS 15.1, which means watchOS 8.1. When running iOS 16.x, you will need a watchOS of 9.x.

New Apple Watch users: If you have an Apple watch and want to use it with Loop, first pair the watch with the iPhone before continuing to the next steps. If you get a new watch after building the Loop app, you'll need to redo your Loop build.

For more information, please see Operate: Apple Watch

"},{"location":"build/build-app/#build-again-with-this-download","title":"Build Again with this Download","text":"

Follow the Find My Downloaded Loop Code instructions if you later wish to build with this same dowload. Plug in an unlocked phone and start at the Start Build section of this page. You may need to select the phone you just plugged in. Everything else should be ready for you the start the build process.

Don't use a really old download

Do not use a really old download.

Check the date of your download against the latest Current Release date and decide whether to get a fresh download instead.

"},{"location":"build/build-app/#xcode-errors-with-build-select","title":"Xcode Errors with Build-Select","text":"

The errors shown below should be prevented - the script will attempt to correct them automatically - follow the directions in the script.

If this is not successful, the script told you the download failed and exited. Scroll up in the terminal to find the error message(s):

WARNINGS

If you see errors like these . . .

You missed one of these steps:

"},{"location":"build/build-dev-mac/","title":"Build Loop dev with Mac","text":""},{"location":"build/build-dev-mac/#overview","title":"Overview","text":"

This page is only relevant when building the dev branch with a Mac.

For Browser Build, please see: Build Loop dev with Browser

No matter the method used to build Loop-dev, you are testing development code. Please read this link now before continuing.

"},{"location":"build/build-dev-mac/#buildloopdev-script","title":"BuildLoopDev Script","text":"

There is a script to assist in building the dev branch. It gives you the option to choose the tip of the dev branch or to build a lightly tested commit. If you have not used the Build Select Script to build Loop previously, you may want to review that page. The command below can be pasted into the terminal of your Mac. Read the directions in the script.

Copy and Paste to start the BuildLoopDev script

/bin/bash -c \"$(curl -fsSL \\\n  https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildLoopDev.sh)\"\n
Both the dev branch and the lightly tested branch of dev have Libre support.

"},{"location":"build/build-dev-mac/#buildloopdev-other-branches","title":"BuildLoopDev Other Branches","text":"

You can use the BuildLoopDev script to build a specific development branch, other than dev. See the example below that would build other-branch, if such a branch existed. This is just an example. You need to substitute the branch you desire for other-branch. There must be a space after the final quote, followed by a hyphen, another space and then the branch name.

Example using other-branch with the BuildLoopDev script
/bin/bash -c \"$(curl -fsSL \\\n  https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildLoopDev.sh)\" - other-branch\n
"},{"location":"build/build-dev-mac/#update-loop-dev","title":"Update Loop-dev","text":"

While Loop-dev is under active development, you should monitor zulipchat and update frequently.

Checking for updates every week is a good idea. Also - subscribe to all the streams on Loop Zulipchat to make sure you don't miss critical information.

You may choose to download fresh each time you update.

You may prefer to use commands to fetch and pull the latest code without making a new clone.

"},{"location":"build/build-dev-mac/#loop-dev-version","title":"Loop-dev Version","text":"

The version of code that shows up under the Loop Settings screen does not change when the dev branch is modified.

If you need help with your app, the mentors need more information. Please issue a Loop Report when asking for help. Refer to Support for how to issue a Loop Report. If you want to keep track yourself, refer to Identify Loop-dev Version

"},{"location":"build/build-dev-mac/#identify-loop-dev-version","title":"Identify Loop-dev Version","text":"

The version of code that shows up under the Loop Settings screen will remain fixed until Loop-dev is released. In order to identify which version of dev you have on your phone, you need the commit.

The commit is identified by a 7-digit alphanumeric code. That code was also appended to the folder name of the downloaded code under Downloads/BuildLoop as shown in the graphic above. You can use finder to view the folder name after the script completes. It also appears in the Loop Report, refer to Support for instructions on issuing a Loop Report. After you issue the Loop Report, look at the workspaceGitRevision number near the beginning of the report.

"},{"location":"build/build-errors/","title":"Oh dear! Build errors?","text":""},{"location":"build/build-errors/#build-errors","title":"Build Errors","text":"

Important

These are only relevant when building with a Mac and Xcode. For Building with Browser Build errors, please see: Errors with Browser

There are two types of build indications that may be seen: they are warnings (yellow or purple icons) and red errors. You'll see the warnings and errors in the left-hand column of the Xcode window.

Yellow and Purple warnings do not cause the build to fail, those are just warnings. You will often see yellow and purple icons. Ignore those. Do not try to do anything to fix those.

Red errors will have to be resolved before you can successfully build the app. The steps below explain how to resolve them based on the messages you are seeing.

"},{"location":"build/build-errors/#xcode-not-responding","title":"Xcode Not Responding","text":"

Sometimes, Xcode stops responding. You have to fix this before any of the other steps on this page will help. The signature is that Xcode shows a colorful spinning icon and does not respond to anything you do.

This can happen sometimes. You just need to force quit Xcode. Sometimes rebooting the Mac may be required, but start with force quit. Then just open up Xcode again and keep going.

"},{"location":"build/build-errors/#start-with-the-obvious-error-causes","title":"Start with The Obvious Error Causes","text":"

New Loop Builders

This page contains build error help for people updating their Loop app as well as brand new Loop app builders. Review the \"obvious\" errors causes first. If that doesn't help, then, skim the page until you reach Find Your Error Message or search the page (Cmd+F) or search LoopDocs for your error. Once you've identified your error message, try to resolve it. Still stuck? Read Posting for Help

Before you start trying to resolve your red errors, start with the most obvious things that can cause a red error message:

  1. For older builds, before 3.2.0, you had to select Loop(WorkSpace) The first time you build after downloading new code, you had to manually select Loop (Workspace) instead of Loop in Xcode.

    • Starting with Loop 3.2.0 and newer versions, the target name and xcworkspace file names are now automatically LoopWorkspace - no special action needed when building.

  2. Did you check that you have the minumum Xcode version for your iOS? This is critical. If you are updating your Loop app, please review the iOS driven requirements for minimum version of macOS and Xcode.

  3. Did you check your Apple developer account for new license agreement? Periodically, Apple will release a new developer license agreement that you need to sign before you can build new apps. You will get a build failure if there is a pending license agreement to sign. Login to your Apple developer account to check if there's a new license agreement.

  4. Do you have a new computer, never used to build Loop? Did you Add Apple ID to Xcode?

  5. Did you reboot, i.e., restart, your computer after updating Xcode? You should reboot following Xcode installation or update and you must make sure your command line tools match the version of Xcode you just installed. Xcode Command Line Tools

  6. Did you get a fresh download of Loop code? If you tried to build with an old download that you used a long time ago, that old version may not be compatible with the new iOS and Xcode versions. Check also, that you are actually using the new download in Xcode. When you use the Build Select Script, it automatically opens Xcode using the new download.

    If you want to build using a recent download, this section tells you how to Find My Downloaded Loop Code.

  7. Are you are using a free developer account? Make sure you finished the removal of Siri and Push Notification capabilities described in the Free Account link.

  8. DO NOT USE BETA VERSIONS If you are using an iOS beta version or an Xcode beta version, Loop might not build. Deleting iOS beta from a phone is a pain...so don't install it unless you know what you are doing.

"},{"location":"build/build-errors/#fix-95-of-errors","title":"Fix 95% of errors","text":"

If you have checked all those steps above and think you have a true build error, here's a tip that resolves 95% of all build errors when updating Loop code.

  1. Open your project in Xcode as normal. Then go to the menu bar at the top of the screen and find the Product menu item. Use the drop down selection for Clean Build Folder or press Shift+Cmd+K. Either will work the same. Wait for the clean to finish before trying to build again.
  2. On the far right, next to the name Full Path is the folder name that Xcode will be using to build. Make sure it is the new code you just downloaded and not an older folder.
  3. If you are updating Loop and did not Delete Old Provisioning Profiles, do it now
  4. Return to Xcode and try building your app again.
  5. Still failing for phone or watch or both? Try the Unpair and Reboot procedure.
"},{"location":"build/build-errors/#unpair-and-reboot","title":"Unpair and Reboot","text":"

This is reported to fix a variety of watch building errors and cannot prepare phone for development errors:

  1. Open Xcode (if not already open)
  2. Plug phone into computer and make sure it is unlocked
  3. Using the Xcode menu, select
    • Windows
    • Devices and Simulators
    • On left side, Right-Click (or Control-Click) on your phone
    • Choose Unpair Device

It may not be necessary, but the suggestion is to reboot phone, (watch) and Mac - in other words, you can try to build without rebooting, but if that fails, repeat the steps and reboot before trying again.

The next time you plug this phone into your computer, you will be asked to trust the computer on the phone (and watch). Note this is unpairing the device from Xcode and your computer, not the same as, and much faster than, unpairing your watch from your phone.

If the build fails again, look through the list below and see if you can match your error message with one of the error messages listed later in this page. If you really can't find your solution, then post for help. But help us help you.

"},{"location":"build/build-errors/#new-with-xcode-15","title":"New with Xcode 15","text":""},{"location":"build/build-errors/#cycle-inside-loop","title":"Cycle inside Loop","text":"

If you build any older version of Loop with Xcode 15, you will see this error: Cycle inside Loop: building could produce unreliable results.

Solution: Build Loop 3.2.3 or later

What about other forks

Other forks are not being maintained.

If you are using FreeAPS or Loop with Patches (from the loopnlearn GitHub username), it is time to switch to released code.

"},{"location":"build/build-errors/#new-with-xcode-14","title":"New with Xcode 14","text":"

This may change, but for now, the watchOS simulator is not automatically included with the Xcode 14.x download and install. Some version of the watchOS simulator is required to build Loop, independent of whether you use a watch.

You will be asked if you want to download & install. Make sure watchOS is selected.

If you are getting watch errors or having trouble with your watch, try this:

Tap on the Xcode name on the menu bar and select Settings.

Choose the Platform tab. If there is a missing watchOS simulator that you think might help, then download it using the GET button. Use the minus icon (bottom left) to remove simulators that are no longer being used. (The watchOS 9.0 is required to build with Xcode 14.0.1. The watchOS 9.1 was downloaded with a release candidate for Xcode 14.1 - your screens may look different.)

"},{"location":"build/build-errors/#posting-for-help","title":"Posting for help","text":"

STOP!! Read this section! Important!

Before you post in a Loop Social Media site asking for help with build errors, do your work first. The build errors listed below (and the checks listed above) will fix most of the problems you may encounter.

PLEASE READ THIS PAGE. The volunteers answering questions online would love to spend more time helping people use Loop and less time answering questions that can be addressed by using this page.

Therefore, try to resolve your build error yourself. Then, if you need to post for help, please include enough information with the post so the volunteers know where you are in your troubleshooting attempts.

Your Post Must Include:

"},{"location":"build/build-errors/#screenshots","title":"Screenshots","text":"

Please take screenshots of your issue and use them in your posts. On an Apple computer, press Shift+Cmd+4 keys at the same time followed by pressing the space bar Space and then click on the window of interest. The screenshot will be saved to your desktop with a file name starting with the name \"Screen Shot\". Use screenshots instead of cell phone images or words whenever possible. Screenshots are higher resolution and easier to read.

Use the whole Xcode window screenshot when posting for build help.

"},{"location":"build/build-errors/#find-your-error-messages","title":"Find Your Error Message(s)","text":"

To begin fixing the error, use the Report Navigator view to find your error message.

The key is to (1) READ THE ERROR MESSAGE and then (2) FIND YOUR MESSAGE IN ONE OF THE TOPICS BELOW.

Here's a super tip: Merely seeing the \"exit code\" in Xcode is not enough information to discern what error is causing your build to fail; some exit codes have multiple causes. Look at the detailed message to guide your search for the matching solution.

Notice the screenshots below have red circles highlighting certain error messages. Read your error message(s) from your screen, being guided by the red circles in the screenshots. Once you find your error message (hint: not \"exit code\"), you can either:

For example, if you see \"Invalid active developer path (/Library/Developer/CommandLineTools)\" in your error message, use the search tool in LoopDocs with \"invalid active\". You will get a couple of links and one is the Command Line Tools fix for that error message. Click on the link and you'll find the solution.

"},{"location":"build/build-errors/#specific-error-messages","title":"Specific Error Messages","text":""},{"location":"build/build-errors/#unable-to-read-included-file-loopconfigoverridexcconfig","title":"Unable to read included file LoopConfigOverride.xcconfig","text":"

Error Message: This error occurs inside Xcode with the build halting at the line that reads the LoopConfigOverride.xcconfig file.

Solution:

Modify the permissions for Xcode in your macOS.

The graphic below has steps labeled 1 through 4 to guide you to the setting that must be enabled for you to build the app with Xcode.

  1. Open the macOS settings (Apple icon) and navigate to Privacy & Security
  2. Select Files and Folders
  3. Select Xcode
  4. Ensure that Downloads Folder is enabled

"},{"location":"build/build-errors/#no-devices-from-which-to-generate-a-provisioning-profile","title":"No devices from which to generate a provisioning profile","text":"

Error Message: This error occurs during the Build target WatchApp or Build target WatchApp Extension.

Communication with Apple failed: Your team has no devices from which to generate a provisioning profile. Connect a device to use or manually add device IDs in Certificates, Identifiers & Profiles. https://developer.apple.com/account/

No profiles for 'com.XXX.loopkit. Loop. LoopWatch' were found: Xcode couldn't find any iOS App Development provisioning profiles matching 'com.XXX.loopkit.Loop.LoopWatch'.

Solution:

"},{"location":"build/build-errors/#run-destination-is-not-valid-failed-to-prepare-the-device","title":"Run Destination is Not Valid; Failed to Prepare the Device","text":"

Error Message:

The run destination for name's phone is not valid for running the scheme \"Loop (Workspace)\"

Solution:

First make sure your Xcode version is new enough to work with your phone iOS version and make sure developer mode is turned on for iOS 16 or newer. If so, then try this procedure:

"},{"location":"build/build-errors/#packageresolved-file-corrupted-or-malformed","title":"Package.resolved file corrupted or malformed","text":"

Error Message:

Package.resolved file is corrupted or malformed; fix or delete the file to continue: unsupported schema version 2

This error is new with Loop 3, which uses Package Dependencies.

There are 2 problems shown here

  1. The version of Xcode is out of date
  2. The graphic was acquired using a camera instead of a screenshot, and yes - that was a joke - using a camera does not cause a build error

Solution:

Update Xcode, which may require you to update macOS.

"},{"location":"build/build-errors/#couldnt-get-revision-for-package-dependency","title":"Couldn't Get Revision for Package Dependency","text":""},{"location":"build/build-errors/#many-search-143-for-this-error","title":"Many Search 1.4.3 for this Error","text":"

This error is new with Loop 3, which uses Package Dependencies.

Error Message:

Text in error:

Solution:

Refer to the graphic below

  1. Click on the folder icon (indicated by red square)
  2. Hold down the Control-Key and click the Package Dependencies row to display the dropdown menu (shown in the inset)
  3. Select Reset Package Caches from the dropdown menu and wait for Xcode to finish the reset process
  4. Once the package reset completes (updates in upper right of xcode will stop or say indexing), the red x should vanish
  5. You can start the build as soon as the Indexing message appears

"},{"location":"build/build-errors/#unable-to-read-included-file","title":"Unable To Read Included File","text":"

This error has been seen with Loop 3. The permanent xcconfig file, created by the build script and used to sign targets, is written to a folder where the user does not have read permission.

Error Message:

Text in error:

Solution:

No need to quit Xcode. If your build script terminal is still open, use it. Otherwise, open a new terminal window.

Copy the lines below that start with ls -l by hovering the mouse near the right side of the text and clicking the copy icon (should say Copy to Clipboard when you hover over it). When you click the icon, a message that says Copied to Clipboard will appear on your screen.

Copy and Paste to add read permissions to xcconfig file
ls -l ~/Downloads/BuildLoop/LoopConfigOverride.xcconfig\nchmod +r ~/Downloads/BuildLoop/LoopConfigOverride.xcconfig\nls -l ~/Downloads/BuildLoop/LoopConfigOverride.xcconfig\n

Paste the lines into the terminal. The response to the first line will be something like this:

--w-------  1 marion  staff  490 Nov  8 04:58 /Users/marion/Downloads/BuildLoop/LoopConfigOverride.xcconfig\n

There will be no response after the second line - although if an error is reported, please grab a screenshot.

The response to the last line will be something like this:

-rw-r--r--  1 marion  staff  490 Nov  8 04:58 /Users/marion/Downloads/BuildLoop/LoopConfigOverride.xcconfig\n

The addition of r where there used to be - on the left side, means you now have permission to read that file.

Final step is to return to Xcode and clean the build folder. Otherwise Xcode remembers it could not read the file and it won't try again.

  1. From the Product menu (of Xcode), select Clean Build Folder
  2. Press the Build Button (play icon)
"},{"location":"build/build-errors/#cycle-dependency","title":"Cycle Dependency","text":"

This error is new with Xcode 13.3 (late Sep 2021) which has a new requirement

Error Message:

Text in error:

Solution:

No need to quit Xcode - follow these steps using the Xcode Menu bar. (It's possible that only Step 1 is required, but sometimes all steps are needed.)

  1. From the Product menu (of Xcode), select Clean Build Folder
  2. From the File menu, select Close Workspace
  3. From the File menu, select Open Recent and choose the top line
  4. Press the Build Button (play icon)
"},{"location":"build/build-errors/#entitlements-error","title":"Entitlements Error","text":"

Error Message:

Text in error message can be either of these:

Entitlements file \"WatchApp Extension.entitlements\" was modified . . .

or

Entitlements file \"Loop.entitlements\" was modified . . .

Solution:

No need to quit Xcode - follow these numbered steps as indicated in the graphic below.

  1. Click on the Loop icon under PROJECT
  2. From the Product menu (of Xcode), select Clean Build Folder
  3. Press the Build Button (play icon)

It turns out that

"},{"location":"build/build-errors/#compileassetcatalog-error","title":"CompileAssetCatalog Error","text":"

This error is found when there is a space embedded in the path name to your LoopWorspace folder. The good news is that LoopWorkspace seems to be able to build from an iCloud or Dropbox drive.

Text in error message:

Command CompileAssetCatalog failed with a nonzero exit code. . .

Solution:

This is very similar to the steps for the WatchApp Entitlements Error but you need to repeat it for 2 targets: Loop and WatchApp - the graphic below matches the step numbers in the list.

  1. Click on Loop folder
  2. Click on Loop target
  3. Click on the General tab
  4. Click on the App Icons Source dropdown menu
  5. Click on the item already selected (the line will change from red to blank)

"},{"location":"build/build-errors/#carthage-error","title":"Carthage Error","text":"

For older builds only. With Loop 3.2.0 and newer, the default selection is already LoopWorkspace.

You should not see carthage errors, but if you do, you probably did not select Loop (Workspace) at the top of the Xcode window. Review the graphic from the Prepare to Build Instructions.

Or maybe you are trying to build using an old download; some older versions did require carthage. Best practice is to download new code.

Error Message:

Wrong Version of Carthage Error

Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/lipo: one of -create, -thin , -extract , -remove , -replace , -verify_arch \u2026 , -archs, -info, or -detailed_info must be specified.

Solution: Download fresh code with Build Select Script.

"},{"location":"build/build-errors/#could-not-locate-device-support-files","title":"Could Not Locate Device Support Files","text":"

Error Message: \"Could not locate device support files.\" That message is telling you that your iOS on the Loop phone requires you to get a newer version of Xcode to be able to build Loop onto that phone.

Solution: Update your Xcode version; this may also require a macOS update. Please review the phone iOS driven requirements for Xcode and macOS.

"},{"location":"build/build-errors/#no-such-module-loopkit-or-similar-message","title":"No Such Module 'LoopKit' or Similar Message","text":"

Error Message: If you see a Cartfile failure and several other red errors (in particular saying there is \"no such module 'LoopKit'\").

Solution: Read the Carthage Error section above.

"},{"location":"build/build-errors/#developer-license-update-pla-update","title":"Developer License Update (PLA Update)","text":"

Error message: The Apple Developer Program License Agreement has been updated, In order to access certain membership resources, you must accept the latest license agreement. Or you may see Unable to process request - PLA Update available. You currently don't have access to this membership resource. To resolve this issue, agree to the latest Program License Agreement in your developer account.

Solution: You'll need to log onto your Apple Developer account at developer.apple.com and accept the latest license agreement.

"},{"location":"build/build-errors/#could-not-get-a-container-directory-url","title":"Could Not Get a Container Directory URL","text":"

Error message: \"Could not get a container directory URL. Please ensure App Groups are set up correctly in entitlements.\"

Solution: To resolve this error, you will need to click on the Loop target's signing area and then the plus-sign in the App Groups area under the signing. Copy and paste the bundle indentifier into the new container that starts with group. and then add Group to the end of the name. Click OK to save. Note, the line will start with lower case group. followed by your bundle identifier and an upper case Group added to the end of the bundle identifier.

The final App Group should now have a blue check box, the name should start with group and end with LoopGroup. See the screenshot as an example. Click the build button after your App Group is setup similarly and you should be good.

"},{"location":"build/build-errors/#missing-command-line-tools","title":"Missing Command Line Tools","text":"

Error message: \"Invalid active developer path (/Library/Developer/CommandLineTools)\"

Solution: Go to your Xcode -> Settings and under the Locations tab, select your Xcode version (the figure shows 14.0.1 - yours should match your Xcode version) in the dropdown menu for Command Line Tools.

"},{"location":"build/build-errors/#device-management-could-not-launch-loop","title":"Device Management Could Not Launch Loop","text":"

Error message: \"Could not launch \"Loop\". Verify the Developer App certificate for your account is trusted on your device. Open Settings and navigate to General -> Device Management, then select your Developer App certificate to trust it.\"

New Solution First try the Unpair and Reboot process above. If that doesn't work, then try the solution listed below.

Solution: If you get this message and are unable to find the Device Management option in your phone settings, then we need to do a little extra step to clear out some old info.

  1. Plug the phone into the computer and open Xcode
  2. Click the \"Window\" menu item in Xcode and then choose \"Devices and Simulators\"
  3. Right click your phone on the left and pick \"Show Provisioning Profiles\"
  4. Delete all of the items in the list that have Loop in the name
  5. Go to your four signing targets and change the signing team back to \"None\" for a quick bit, and then change back to your regular signing team name again.
  6. Rebuild Loop

That should clear the out, problematic profiles and allow a successful build.

If your problem persists after that, then you might need to do total reset of your phone to clear out the pesky problem. Before you do this, you may want to Post for Help to make sure it is really necessary:

  1. Wipe the iPhone clean and set it up as a new device
    • FIRST - write down or screenshot all your settings
    • Pod users - you will have to start a fresh pod after this
    • If you want your old pod to continue giving you basal rate, don't replace the pod before wiping your phone. Once the phone is reset and a new Loop app is added, you must start a new pod. The old pod should have the sound connection broken before being discarded because you won't be able to deactivate the pod.
  2. Delete all certificates from your Developer account (you'll need to login to your Developer account to do that)
  3. Delete your old Loop code download and get a new one.
  4. Rebuild Loop on the phone with the new download of Loop code.
  5. Start a new pod with the new Loop app on the reset phone.
"},{"location":"build/build-errors/#pending-certificate-request","title":"Pending Certificate Request","text":"

Error message: \"You already have a current iOS Development certificate or a pending certificate request.\"

Solution: This error message has recently started to appear for some new Loop builders. To resolve the issue, please log in to your Developer account at developer.apple.com and then click on \"Certificates, Identifiers & Profiles\". Under that screen, you will see \"Development\" under the \"Certificates\" section in the column on the left. You will need to click on the certificates, and choose \"revoke\" from the options that show after you click on the certificate. Confirm the warning message that will appear asking \"Do you want to revoke the certificate?\"

After you do that, return to Xcode and open up Xcode -> Settings and choose the Accounts tab. Highlight your Apple ID and click on the minus sign to delete your Apple ID.

Re-enter your Apple ID (yes...add that account right back that you literally just deleted), return to your Loop's target signing areas in Xcode and your error message should have resolved as a new certificate will have been issued and a provisioning profile should have been created automatically.

You can verify the iOS development certificates are working by clicking on \"Manage Certificates\" in Xcode -> Settings, Accounts tab and viewing the iOS Development Certificates. You should have one for your account that has a clean status similar to the screenshot below.

"},{"location":"build/build-errors/#command-codesign-failed","title":"Command CodeSign Failed","text":"

Error message: \"errSecInternalComponent, Command CodeSign failed with a nonzero exit code\"

Solution: This error message is likely due to inadvertently saying \"no\" to allowing Keychain Access or changing your computer or AppleID password. Regardless, the solution is as follows:

  1. Close Xcode
  2. Open your Keychain Access application (found in Applications within the Utilities folder)
  3. In the upper left corner of keychain access, make sure you have the keychain login highlighted and then right-click the lock next to the login. Click the lock closed, and then click the lock to open it again. You will be prompted for a password. Enter your computer admin password. Close Keychain Access app.

  1. Open your Loop project again in Xcode.
  2. In the main Xcode menu (grey menu bar at the very top of your Apple display area), select Product and then select the option for Clean. (Keyboard shortcut is Shift+Cmd+K)
  3. Now try rebuilding your Loop app. If you ever get prompted again to allow Xcode access to Keychain, make sure to click on the option to Always Allow.
"},{"location":"build/build-errors/#unrecognized-arguments","title":"Unrecognized Arguments","text":"

Error message: \"Unrecognized arguments: --cache-builds\"

Solution: This is a homebrew / carthage error, so I don't think you'll see this. If you do, download a fresh copy of Loop code and try again. If it repeats, it is time to request assistance. Please read Posting for Help.

"},{"location":"build/build-errors/#abort-with-payload","title":"Abort with Payload","text":"

Error message: \"Abort with payload\" Your app will only open briefly with a white screen and then close, if you build with this error.

Solution: This error message is caused by having the Loop download folder in an iCloud mapped drive when doing the zip download. Move your Loop download folder back to the Downloads folder, then rebuild. LoopWorkspace builds with Xcode 13 appear to work fine with an iCloud drive. You may run into the spaces in your path name problem - which has a different solution.

"},{"location":"build/build-errors/#apple-watch-issues","title":"Apple Watch Issues","text":""},{"location":"build/build-errors/#apple-watch-loop-app-not-appearing","title":"Apple Watch: Loop App Not Appearing","text":"

Error: Apple watch app is not appearing.

Solution: This error usually appears because you have not updated the watchOS prior to building Loop, or you didn't have your Apple watch paired at the time of building Loop.

Don't forget to open the iPhone's Watch app, select My Watch tab on the bottom left, scroll all the way down, and click Install for the Loop app listed at the very bottom under \"available apps\".

"},{"location":"build/build-errors/#apple-watch-loop-app-not-installing","title":"Apple Watch: Loop App Not Installing","text":"

Before trying this solution, see if the Unpair and Reboot procedure works.

Error: The Loop app appears on the list of apps available to install on the watch, but when you press \"install\", and it goes through the animation of filling in the circle while it's installing, but then at the end it just toggles back to saying \"INSTALL\".

Solution: Plug your iPhone into the computer and start Xcode. On your watch, look for a prompt that says \"Trust this computer\". Scroll down on the watch face and select the \"Trust\" button. In Xcode, go to the top menu bar and select \"Clean Build Folder\" from the Product menu option, and then rebuild your Loop app.

If the watch app still fails to install properly, the next section should work.

"},{"location":"build/build-errors/#apple-watch-loop-app-not-running-on-watch","title":"Apple Watch: Loop App Not Running on Watch","text":"

Error: Tapping the Loop app icon on the watch results in flash of the watch screen and then return to the Loop app icon or a brief display of the watch interface and then return to the Loop app icon.

Solution: Plug in your iPhone, with the watch already paired, into the computer and start Xcode with your current build folder. In Xcode, from the list of schemes where you normally choose Loop (Workspace) (with Loop 3.2.x and newer, LoopWorkspace is the default), choose the WatchApp scheme (near the bottom of the list) and then select your watch (not a simulator) from the device list, see the graphics below. Press the play button to build and deploy the WatchApp directly to your watch. It will launch correctly and will not crash when you subsequently launch it from the complication or your watch Home Screen..

Warning: Make sure your watchOS is up to date with respect to your phone iOS. If not, you may need to update to be successful. On pressing clicking build/play, some people report receiving an error stating \u201ciPhone/Apple Watch are ineligible because the OS on the watch doesn\u2019t support WatchKit App Products\u201d or similar wording. This is a known issue with some Mac USB ports. Fixes in preference order are: 1) swap which USB port is in use; 2) unplug and replug the USB cable from both the iPhone and Mac; or 3) as a last resort, reboot the iPhone and Mac.

Don't forget to select Loop(Workspace) after building to the watch before trying to build to a phone.

"},{"location":"build/build-free-loop/","title":"Build Free Loop","text":""},{"location":"build/build-free-loop/#prepare-to-sign","title":"Prepare to Sign","text":"

This page is not stand-alone. You typically get here after choosing to Sign Manually after a successful download using the Build Select script.

Normally this option is chosen by people building the app with the Free option or if you want to build to a simulator on your computer.

If you have a paid developer account and are building Loop 3, you are far better off choosing to configure the permanent override file with your Apple Developer ID. Refer to Sign Targets.

The instructions found on this page are for the first build. With the Free version, you need to build every week. Refer to Build Again with this Download.

"},{"location":"build/build-free-loop/#select-the-loop-folder","title":"Select the Loop Folder","text":"

Don't touch that button!

You will be told exactly where on each screen you should click. Please only click in the designated places.

Follow the directions and compare your Xcode screen to the graphics as you walk through the steps.

As shown in the GIF below:

"},{"location":"build/build-free-loop/#select-your-phone","title":"Select Your Phone","text":"

If this is the First Time your phone or watch has been connected to Xcode, you will need to tell the phone and watch to \"Trust this Computer\".

The GIF (not updated for Loop 3.2.x) below shows:

I don't see my phone

"},{"location":"build/build-free-loop/#build-to-a-simulator","title":"Build to a Simulator","text":"

Skip this section if building to a phone and proceed to Select Signing & Capabilities Tab.

If you want to build to a simulator, follow the directions in this section and skip the rest of this page.

"},{"location":"build/build-free-loop/#select-signing-capabilities-tab","title":"Select Signing & Capabilities Tab","text":"

What does Signing Targets Mean?

\"Signing Targets\" in Xcode identifies who built the app. You cannot deploy an app to a phone without signing each target associated with that app.

The graphic below indicates in red the three places you need to click in order to begin signing targets.

Click Only where Instructed

"},{"location":"build/build-free-loop/#sign-the-targets","title":"Sign the Targets","text":"

It is time to Sign the Targets with your Apple ID.

If you chose to sign manually but have a paid account, you can skip the Free Account steps below.

You will be building multiple targets to make a complete app and must sign each one. With Loop 2.2.x, there are 4 targets. With Loop 3, there are 5 targets.

Start with the Loop target, the first one on the target list. Choose your Apple ID.

"},{"location":"build/build-free-loop/#free-account","title":"Free Account","text":"

This section is required if you are using the free account.

Some features of Loop are not available with the Free option, so as you sign, you will need to remove features that are not supported.

  1. You must remove unsupported capabilities from 2 targets, this is best done as you sign each target:
    • Loop Target: Push Notifications; Siri and Time Sensitive Notifications
    • Watch App Extension Target: Siri
  2. Add the keyword SIRI_DISABLED to the LoopConfigOverride.xcconfig file
    • Click on the filename in the left pane of Xcode and view it in the Xcode editor
    • Examine the file and find the line that starts with SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited)
    • Insert the new keyword (separated by a space) anywhere after $(inherited) and before the slashes near the end of the line
    • When done, that line should be similar to:SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited) SIRI_DISABLED

Details about removing unsupported capabilities:

"},{"location":"build/build-free-loop/#end-of-free-account-steps","title":"End of Free Account Steps","text":"

Click on each of the three remaining targets shown in the red box below, and repeat the signing steps by choosing the same team name as you selected in the first target. The targets that must be signed prior to building are Loop, Loop Status Extension, Watch App, and WatchApp Extension for Loop 2.2.x, with the addition of Loop Intent Extension for Loop 3.

After signing the targets, click on the Loop icon under the PROJECTS heading. (Refer to the bright blue box in graphic above - click on that Loop icon.)

"},{"location":"build/build-free-loop/#signing-complete","title":"Signing Complete","text":"

Now that you have signed your app, return to the Build Loop page at Start Build.

"},{"location":"build/cgm/","title":"Compatible CGM","text":""},{"location":"build/cgm/#compatible-cgm","title":"Compatible CGM","text":"

Time Estimate

Summary

The Loop app is compatible with:

FAQs

"},{"location":"build/cgm/#continuous-glucose-monitor-cgm","title":"Continuous Glucose Monitor (CGM)","text":"

The Loop app uses your CGM glucose readings, carbohydrate input and therapy settings, to model your current glucose trend, predict future glucose and automatically adjust insulin dosing. A compatible CGM is essential to operation of the Loop app.

"},{"location":"build/cgm/#dexcom-g5-g6-and-one-cgm","title":"Dexcom G5, G6 and ONE CGM","text":"

The Dexcom G5, G6 and ONE CGM transmits data directly to the Dexcom app on your iPhone via Bluetooth.

The Dexcom ONE, available in some countries, acts just like the G6 as far as the Loop app is concerned. The Dexcom ONE app does not provide some features, such as Dexcom Share, that come with the G6. When you set up the Loop app, select Dexcom G6 as your CGM to use Dexcom ONE CGM with the Dexcom ONE app installed on your phone.

Dexcom ONE+ is not yet compatible

There are reports that Dexcom is transitioning to the ONE+ based off the G7 platform. These devices cannot be used with the Loop app at this time.

Pay attention to social media - an early indication is that a simple patch will allow this to work, but that patch is not available - more testing is needed.

Only available in some countries. This link is for Poland Dexcom ONE+

If the Dexcom app is on the same device as the Loop app, your system can function without an internet connection. See Offline Use below.

Dexcom G5 Support

Dexcom has stopped supporting the G5 system in the US. In the US, and some other countries, the G5 is not available for download from the Apple Store. There are countries in which Dexcom does supply and support G5. The G5 capability will continue to be supported in Loop.

There are third party apps, which interface with G4 and G5 transmitters, supported by some forks of Loop. The version of the Loop app supported by these documents only works with the Dexcom apps.

"},{"location":"build/cgm/#dexcom-g7-cgm","title":"Dexcom G7 CGM","text":"

Dexcom G7 is supported with version 3 or greater of the Loop app.

"},{"location":"build/cgm/#medtronic-cgm","title":"Medtronic CGM","text":"

The Minimed Enlite CGM, available with the Medtronic 522/722, 523/723, and 554/754, wirelessly sends glucose readings to the pump. The Loop app can read the Medtronic CGM data directly from the pump using a RileyLink compatible device.

"},{"location":"build/cgm/#offline-use","title":"Offline Use","text":"

\"Offline Use\" means using the Loop app when there is no cell data or internet available. The Loop app does not require any special setup to operate offline.

For offline use, the iPhone's Bluetooth still needs to be active; and for Dexcom users, the G5, G6 or G7 app also needs to be running on the same phone as the Loop app. If you put your iPhone into Airplane mode, remember to turn Bluetooth back on to keep both the CGM and the Loop app running. If your offline use is failing, chances are you have forgotten to update your transmitter ID in the Loop app settings when you changed transmitters.

"},{"location":"build/cgm/#dexcom-share","title":"Dexcom Share","text":"

The Loop app can download Dexcom Share data for use in modeling glucose. However, this is not a typical configuration and requires internet connection for both the phone with the Dexcom app and the phone with the Loop app. The steps for adding a CGM explain that you usually enter the Dexcom transmitter ID and leave the Dexcom Share setting blank.

Dexcom ONE

The Dexcom ONE app does not support Share.

"},{"location":"build/cgm/#nightscout-as-a-remote-cgm","title":"Nightscout as a Remote CGM","text":"

Version 3 or later of the Loop app can use Nightscout as a remote source for CGM data. This requires cell or WiFi connection.

"},{"location":"build/cgm/#cgms-not-supported-in-the-loop-app","title":"CGMs Not Supported in the Loop App","text":"

Libre Support (for some Libre sensors) is available with Loop-dev or by adding customizations.

Currently, there are no solutions for Eversense, Guardian or Libre 3 CGM to be used directly with the Loop app, but some Uploaders to Nightscout are available using an Android phone. Version 3 or later of the Loop app allows the use of Nightscout as a CGM source.

"},{"location":"build/cgm/#next-step","title":"Next Step","text":"

If your compatible pump is Medtronic or Omnipod (not DASH)

If your compatible pump is Omnipod DASH

"},{"location":"build/community/","title":"Meet the Community","text":""},{"location":"build/community/#meet-the-community","title":"Meet the Community","text":"

Time Estimate

Summary

FAQs

"},{"location":"build/community/#online-groups","title":"Online Groups","text":"

There's a wonderful community of Loopers who are willing to help you through the process. This link on Social Media Options walks you through those groups and how to join.

Volunteers provide assistance on building and using the Loop app at these sites. None of the people are paid to answer questions or spend time troubleshooting. They simply want to help others. Please decrease their support burden by doing your homework and providing the information they need when requesting help. Please click the image below to watch this video full of tips to make the most of your online resources.

Please watch this video (just under 7 minutes) to learn about using announcements and searches in Facebook groups and the LoopDocs pages.

Note, the LoopDocs menus were reorganized after this video was prepared to make it easier to progress through the pages.

"},{"location":"build/community/#screenshots","title":"Screenshots","text":"

Please take screenshots of your issue and include them in your posts. On an Apple computer, press Shift+Cmd+4 keys at the same time and a little crosshairs tool will appear. Click-and-drag across the area you'd like to include in the screenshot. When you let go of the button, the screenshot will be saved to your desktop with a file name starting with the name Screen Shot. To capture an entire window, press Shift+Cmd+4 keys at the same time followed by pressing Space (the space bar) and then click on the window of interest.

Use screenshots instead of cell phone images whenever possible. Screenshots are higher resolution and easier to read.

Take a wide screenshot (full window capture) when asking for help with settings or Xcode build errors. Nightscout and Xcode have lots of valuable information off-to-the-side that can be valuable for troubleshooters.

"},{"location":"build/community/#descriptive-language","title":"Descriptive Language","text":"

Use descriptive language - the most accurate, detailed words possible - when asking for help. Try to avoid the word \"it\" and instead use details and information to explain why you're asking for help, what you've already tried, and what happened when you tried those things (including screenshots). Let's illustrate with a couple of examples.

"},{"location":"build/community/#example-1","title":"Example 1","text":"

The Loop app no longer allows you to enter your correction range in the wrong order, i.e., 110 to 90; but it once did and the Loop app would stop working. We're using that problem as an example below.

Bad: \"It's not working.\" <----makes me wonder what \"it\" is? What part of \"it\" isn't working exactly? The app? The glucose control? The pump integration? Alarms? Bolusing? CGM

Ok: \"My Loop app won't open.\" <---- Ok, so now I know the Loop app itself seems to be the problem, but still don't know if this is a build error or an error that has happened after building. The solutions might be different.

Better: \"My Loop app was working yesterday just fine, and now today it's not doing the things like I expect.\" <----- Getting closer. Now, I know this is not a build error and that it sounds like a more recent issue. I'm starting to narrow down the potential causes. This is about as much detail as it takes for me, as a volunteer, to consider helping. I might not have to ask 42 questions, but instead only 4 questions to find the remaining information for troubleshooting. If there were more details, it would save time.

Awesome: \"My Loop app was working yesterday. Around lunch time, I went into the settings screen and made some adjustments and ever since it just turns white and closes no matter what I try.\" <---- DEFINITELY getting closer. Now I have a strong suspicion about where the bug is happening and can help with a couple links.

GOLD MEDAL WORTHY: \"My Loop app was working yesterday. Around lunch time, I went into the settings screen and made some adjustments to correction ranges. Ever since I did that, the app immediately turns white and shuts down. I have tried restarting my phone, but it has not fixed the problem. I tried searching the docs for 'loop closing' but didn't see results that matched my issue.\" <----- This person is doing an outstanding job of describing the problem. Lots of good details. Has shown initiative to try to use the resources already. This person did an excellent job of helping all of us help them.

"},{"location":"build/community/#example-2","title":"Example 2","text":"

This example is not quite as old, but does refer to details from older Loop and iOS versions. It exemplifies the details needed to assist someone with a build error.

Build with Browser

If you are using the Build with Browser method, we still need descriptive details but we do not need screenshots. All that is required is to list your GitHub user name. The volunteers can then read your publicly available log files. (All private information is automatically redacted in those logs.)

Bad: \"My Loop app won't build.\" <----- What step are you on? What is the iOS on your phone? What kind of computer are you using? What macOS? What Xcode version? Have you built successfully before or is this new?

Ok: \"I'm trying to update my Loop app and am getting a few errors that I don't understand.\" <----- Wow, sure would be nice to know what those error messages are. Are they red or yellow? A screenshot sure would help here.

Awesome: \"I have a macOS Big Sur 11.5.3 computer with Xcode 12.5.1 and my phone is running iOS 14.7.1. Downloaded Loop-master (2.2.6) this morning and I'm getting some red errors about an exit code that I don't understand. I've tried everything in the docs and nothing worked.\" <---- While I'm super happy they \"tried everything\", I'm no closer to knowing what the exact error message is nor which \"stuff\" exactly they tried. But all the version numbers are included.

GOLD MEDAL WORTHY: \"I have a macOS Big Sur 11.5.3 computer with Xcode 12.5.1 and my phone is running iOS 14.7.1. Downloaded Loop-master (2.2.6) this morning and I'm getting some red errors about an exit code 645 that I don't understand. Here's the screenshot of the error message. I tried searching the docs for \"exit code 645\" and didn't see any responses that helped.\" <---- This is the kind of detail that will get you to an answer very fast.

"},{"location":"build/community/#be-ok-with-links","title":"Be OK with Links","text":"

Often, the best answer to your question is sending a link to the answer in LoopDocs or LoopTips. This provides you a quick, accurate and complete answer. We understand that there is so much information in these sites that it can be hard to find answers. Mentors know the docs well, are experts at using the search tools and will send direct links to the sections that best answer your question.

If you've searched the docs and read relevant info already, please include that in your post or your reply. That way you don't get linked back to the part you are confused about. And if you have already read the specific section a mentor just linked, be specific about why your problem is not addressed by that link. Or just say \"I'm confused when the doc says this\". Letting us know when these docs can be improved is very useful.

"},{"location":"build/community/#next-step","title":"Next Step","text":"

Now you are ready to build or continue with setting up the Loop app.

"},{"location":"build/community/#return-to-set-up","title":"Return to Set Up","text":"

If you are a new looper who got to these pages from the Set Up app page - congratulations. Now that you've reviewed these introductory pages, please continue with the Brand New Loopers section of the Set Up Overview page.

"},{"location":"build/community/#build-with-browser","title":"Build with Browser","text":"

Click here if you want to Build with Browser.

"},{"location":"build/community/#build-with-mac","title":"Build with Mac:","text":"

Click here if you want to Build with Mac.

"},{"location":"build/computer/","title":"Compatible Computer","text":""},{"location":"build/computer/#compatible-computer","title":"Compatible Computer","text":"

Time Estimate

If you are building with a Mac and Xcode:

Hint: OS stands for Operating System

Build with Browser

If you do not have a Mac, you can build\u00a0Loop 3\u00a0with any computer using a browser. If you want to use that method, review this list and head over to Build with Browser.

Summary

Your computer, iPhone and Xcode must have compatible versions to build the Loop app using a Mac.

If you are buying a Mac specifically to use the build with Mac method, chose one with capabably of being updated to the Sonoma (macOS 14) operating system and at least 256 GB (512 GB is better). The Build with Browser method works on any computer or tablet.

FAQs

If you have access to a computer with MacOS 13.5 or newer, you can skip ahead to Check Space Available.

"},{"location":"build/computer/#compatible-versions","title":"Compatible Versions","text":"

The current development version and the next release of\u00a0Loop\u00a0will require Xcode version 15 regardless of the iOS on the phone. This requires macOS 13.5 or higher. As an alternative, use Build with Browser, which supports iOS 15, 16, and 17.

When this page was last updated, macOS 14.0 and Xcode 15.0 were tested to successfully build the app for phones with iOS 15 through iOS 17.0.2.

The table below lists the minimum requirements to build the current release of\u00a0Loop 3.2.3. If your macOS or Xcode version is higher, you can build with Mac.

Find your phone iOS in the table below. If your iOS is not listed, e.g., 16.6, choose the first row that is less than your iOS.

iOS Version minimum Xcode minimum macOS 17.0 15.0 13.5 16.4 14.3 13.0 16.2 14.2 12.5 15.1 14.1 12.5

iOS Dictates Your Computer Needs

The more up-to-date you keep your phone iOS, the more up-to-date your computer and macOS needs to be to build the Loop app with the Mac build method. A new build is required at least once a year. More information on iOS is on the Xcode Version page.

There are important security updates that go along with iOS updates. Please install those iOS updates as soon as you can.

Do not use any of the beta macOS versions. (If you don't know what that means, you aren't using one.)

"},{"location":"build/computer/#check-your-macos-version","title":"Check Your macOS Version","text":"

To find your macOS version, click on the Apple icon in the computer's upper left corner and select About this Mac. The graphic below highlights the macOS version with a red rectangle. Your computer can be a MacBook, iMac, macMini, etc. It will work to build Loop if it has the minimum required macOS version and enough storage.

With the Ventura macOS version, the About this Mac display changed. For Ventura, when you tap on the More Info icon, it opens the General -> About screen from the System Settings menu. This is very similar to the phone Settings -> General -> About screen.

Sonoma, macOS 14.0, is expected to be released 26 September 2023.

If you do not have the required minimum macOS version

Apple says upgrading to macOS Ventura requires 26 GB of available storage.

"},{"location":"build/computer/#check-the-space-available","title":"Check the Space Available","text":"

You need to have 50 GB free space in order to install Xcode as directed on the Xcode Version page. At the top of the menu on the graphic above, click on the Storage Tab highlighted with a red rectangle, or, if running Ventura, tap on More Info to open the About screen (under System Settings->General), which includes storage at the bottom of the display.

To free up space, move things like photos to an external drive. The Xcode application cannot be run from an external drive.

If you are evaluating a used computer, it's best to have at least 256 GB total disk space (more is better).

"},{"location":"build/computer/#which-macs-are-compatible-with-macos-ventura","title":"Which Macs Are Compatible with macOS Ventura?","text":"

Ventura is required for building the Loop app on a phone running iOS 16.4 or higher with the Mac method. You can install Ventura on the following:

"},{"location":"build/computer/#older-macs","title":"Older Macs","text":"

Look into building with GitHub Actions - no need to worry about versions for Mac OS or Xcode - all done for you on GitHub (some configuration required). Works with any computer (PC or Mac or Tablet).

"},{"location":"build/computer/#next-step","title":"Next Step:","text":"

If you already have an Apple Developer ID or you are using a free ID, next step is Xcode Version.

Free ID

The free ID method only works when using the build with Mac method. The Build with Browser method requires a paid developer ID ($99/year) but does not require a Mac computer.

"},{"location":"build/custom-mac/","title":"Customize using Mac","text":""},{"location":"build/custom-mac/#overview","title":"Overview","text":"

This page is only relevant when building with a Mac.

For Building with a Browser, please see: Customize using Browser

For new Loopers, please build the code before you make any changes. Start with Open Loop and familiarize yourself with the interface. Later, you can make the customization(s) you desire and build again. The second build will be much easier than your first build.

These customizations require you to modify the code used to build the Loop app and then build the app again with the modified code.

You take responsibility

You are responsible when you decide to use customizations.

Be sure to report what changes you made if you need to ask for assistance with your app.

"},{"location":"build/custom-mac/#customizations-prepared-for-you","title":"Customizations Prepared for You","text":"

Some customizations are the same for everyone and have been prepared for easy use.

The Loop and Learn team is committed to maintaining these prepared customizations and provides an easy method to add your selection from these customizations to your version of Loop.

Please read the documentation for these on the Loop and Learn: Customization Select Page:

"},{"location":"build/custom-mac/#add-libre-support-to-323","title":"Add Libre Support to 3.2.3","text":"

If you are using main branch to build Loop 3.2.3 and rely on either xDrip4iOS or GlucoseDirect to read your CGM and transfer the readings to the Loop app, you need to review this section of the Loop and Learn customization page.

Alternatively, you can switch to the dev branch, which already supports Libre. Build Loop dev with Mac

"},{"location":"build/custom-mac/#personal-customizations","title":"Personal Customizations","text":"

Some customizations must be created for yourself. These are of two basic types: Custom Edits and Build-Time Flag.

The information needed to modify the code to make these customizations is found in the Versions tab because the information is independent of build method (think of these as your personal versions). The links are found below.

When preparing these personal edits using a Mac, there is a page explaining how to open Xcode to the correct folder (where code is stored on your Mac) and incorporate those changes into your personal copy of LoopWorkspace on your Mac before building.

"},{"location":"build/custom-mac/#details-at-links","title":"Details at Links","text":"

The code changes required for these customizations are the same regardless of the build method. The pages that provide the documentation on modifying and incorporating these changes are found at the links above.

"},{"location":"build/edit-mac/","title":"Custom Edits with Mac","text":""},{"location":"build/edit-mac/#overview","title":"Overview","text":"

When applying a customization using Mac, the downloaded code should be fairly recent. If you are not sure, get a fresh download. If you know your downloaded code is the Current Release, you can skip the download and use the same folder as last time.

"},{"location":"build/edit-mac/#find-my-downloaded-loop-code","title":"Find My Downloaded Loop Code","text":"

Refer to the graphic below. The Downloads folder in Finder is highlighted on the upper left. The full path to Loop.xcworkspace is highlighted along the bottom.

Loop to LoopWorkspace

Note that the directory Loop.xcworkspace has been renamed to LoopWorkspace.xcworkspace in the released code. For experienced builders - you realize this is good because the build process is easier.

The words were updated, but it will take time for the graphics to be updated.

Experienced Builders

Experienced builders will often build a fresh download to a simulator for their phone iOS (not their phone) to ensure download is good and is compatible with macOS, Xcode and phone iOS. Once the build is successful, they apply their customizations and build again to the simulator. Last step is to build the customized version to their real phone.

"},{"location":"build/edit-mac/#instructions-for-finding-the-lines","title":"Instructions for Finding the Lines","text":"

For each customization, you are given landmarks to find the correct location in the code when you review Version: Custom Edits. You can choose to search using the Key_Phrase or navigate to the file in the folder structure and look for ( Cmd+L # ) the line number.

"},{"location":"build/edit-mac/#key_phrase","title":"Key_Phrase","text":"Example of a Key_Phrase
use the copy button at right, paste into search\nThe copy button for this exampe is just for practice\nDo not paste the result anywhere\n

To search using the Key_Phrase (see graphic below for clarification):

"},{"location":"build/edit-mac/#module-folder-file","title":"Module, Folder, File","text":"

Each customization will also show Module, Folder and File bullet below the key phrase.

"},{"location":"build/edit-mac/#open-a-terminal-in-loopworkspace-folder","title":"Open a Terminal in LoopWorkspace Folder","text":"

If you use the Loop and Learn: Customization Select Script, it automatically locates your most recent download, makes the customization you select in that download and then opens Xcode for you.

But sometimes, you need to find your downloaded code and make your own changes in Xcode. This section tells you how to do this.

Refer to the graphic below. The Downloads folder in Finder is highlighted on the upper left. The full path to Loop.xcworkspace is highlighted along the bottom. Double clicking on that file opens Xcode; but to apply customizations, you need to type commands in the terminal.

This new terminal window is ready to accept commands as needed when the instructions say to start a terminal in the LoopWorkspace folder.

To confirm you are in the correct location, type pwd and return in the terminal. The response must end in LoopWorkspace. For example, using the graphic below, the response to pwd should be similar to:

/Users/marion/Downloads/BuildLoop/Loop-20220803-1145/LoopWorkspace

"},{"location":"build/edit-mac/#folders-and-icons","title":"Folders and Icons","text":"

The folders listed in the code customization steps are the actual directory names as stored on your computer. However, a shortened name is used for some folders when being displayed as icons in Xcode. Some people prefer to search through the folder icons to find a file instead of using the Find in Workspace feature.

In the graphic below, the user searched for an item found for both Eros and DASH pods (in two different files). The top part of the graphic shows the result of the search with user clicking on one instance. On the right side of the top graphic (highlighted by red rectangle) is the name of the selected file on the computer with the full directory name.

These folder icon names are different from the directory names on the computer:

Folder Icon Name Directory Name ShareClient dexcom-share-client-swift RileyLink rileylink_ios Amplitude Amplitude-iOS

All other icons and directory names match.

"},{"location":"build/edit-mac/#modify-and-save","title":"Modify and Save","text":""},{"location":"build/health/","title":"Loop 2 Health Permissions","text":""},{"location":"build/health/#health-data","title":"Health Data","text":"

The Loop app uses the Health app to record blood glucose, insulin, and carbohydrate data. The blood glucose, insulin, and carbohydrate data stored in the Health app can also be accessed and uploaded by the Tidepool Mobile app which enables the display of your data on the Tidepool web-based display tool. Please review the settings below to ensure you have the proper settings.

"},{"location":"build/health/#loop-permissions","title":"Loop Permissions","text":"

You need to set up Loop's permissions to read and write some data in the Health app. When you finish building your first Loop app, the Health app screen for Loop permissions automatically appears. (People who have been looping a while should be aware that the permissions are slightly different now.) Do not enable permission for Loop to read carbohydrates from the Apple Health app.

You can also get to this screen (for iOS 15) by iPhone -> Settings -> Health (heart icon) -> Data Access & Devices -> Loop.

New Instructions

Loop does not need to read carbohydrates from the Health app.

The old instructions suggested turning on all switches. This is NOT necessary for carbohydrates and can be dangerous if

  1. A different app writes carbohydrates to the Health app
  2. If two Loopers use the same Apple ID - PLEASE - do not do this; Loopers need their own Apple ID

Blood Glucose: Permission to Write and Read

Carbohydrates: Permission to Write ONLY

Insulin Delivery: Permission to Write and Read

Sleep: Permission to Read

"},{"location":"build/health/#dexcom-permissions","title":"Dexcom Permissions","text":"

You also need to enable your Dexcom Mobile app to write to the Health app. The steps shown in the figure below are valid for iOS 12.

For iOS 13/14, the menu items are: iPhone -> Settings -> Health (heart icon) -> Data Access & Devices -> Dexcom app. Make sure Dexcom has permission to write Blood Glucose (after the 3 hour delay). If you do not do this, you will have a maximum history of 3 hours displayed in the Loop Glucose screen.

"},{"location":"build/loop-data/","title":"Loop Data","text":""},{"location":"build/loop-data/#make-plans-for-your-loop-data","title":"Make Plans for your Loop Data","text":"

Time Estimate

Summary

FAQs

"},{"location":"build/loop-data/#data-options","title":"Data Options","text":"

Take some time to familiarize yourself with these data options and choose your preferred system(s). Many Loopers use all three for various aspects.

Nightscout options include free or nominal cost sites you build yourself or there are several Nightscout as a Service vendors who provide turn-key sites for a monthly fee. Links to the options are found in the Nightscout: Documentation.

Nightscout provides a secure, real-time Dashboard with status of the Loop app visible to anyone with access codes and the internet. It is required for remote commanding.

If you plan to use remote commanding with Nightscout, please read these links with additional information:

"},{"location":"build/loop-data/#next-step-meet-the-community","title":"Next Step: Meet the Community","text":"

Now you are ready to Meet the Community.

"},{"location":"build/overview/","title":"Mac Overview","text":""},{"location":"build/overview/#build-with-mac-requirements","title":"Build with Mac Requirements","text":"

The complete requirements for building Loop with a Mac and Xcode are summarized below. The first list contains the common requirements that are the same regardless of build method. The second list contains the additional requirements for building with a Mac and Xcode.

Each requirement in the list is linked to the LoopDocs pages with more information.

"},{"location":"build/overview/#common-requirements","title":"Common Requirements","text":"
  1. Compatible iPhone
  2. Compatible Pump
  3. Compatible CGM
  4. RileyLink Compatible Device (not needed for Omnipod DASH)
  5. Apple Developer Membership (not needed if you rebuild weekly using the Mac method)
"},{"location":"build/overview/#build-with-mac-additional-requirements","title":"Build with Mac Additional Requirements","text":"
  1. Compatible Computer
  2. Xcode (a free Apple application)

If using a Mac to build to a Simulator to try things out, the only requirements are a computer and Xcode.

"},{"location":"build/overview/#getting-ready-to-build","title":"Getting Ready to Build","text":"

Review the Common Requirements pages, listed above.

Then review the Build pages for the method you have chosen. Read the top three boxes on each page: icons for those boxes are displayed below for reference. On a desktop, you can use n for next and p for previous.

Time Estimate

Summary

FAQs

Next, read pages completely and skim Oh dear! Build errors?. Most of the mistakes you can make when building with Xcode and a Mac have already been made. The Build Errors page shows how to fix them.

When you are ready to proceed, complete the tasks on each page. You can do one a day, take a week per page or blaze through them quickly. Just be sure to read carefully and if you are confused - reach out for help: How to Find Help.

After you build Loop on your phone, keep following along in the docs as you Set up and Operate your Loop app.

"},{"location":"build/overview/#what-if-i-get-stuck","title":"What if I get stuck?","text":"

Try to:

"},{"location":"build/phone/","title":"Compatible iPhone","text":""},{"location":"build/phone/#overview","title":"Overview","text":"

Time Estimate

Summary

FAQs

"},{"location":"build/phone/#which-devices-are-compatible","title":"Which Devices Are Compatible?","text":"

The Loop app requires an Apple device and uses the Apple Health app to store and retrieve your blood glucose and insulin data and to store your carbohydrate records. Older iPads do not support Apple Health which is required for the Loop app. It may be possible with newer iPads and newer iOS, but this has not been tested.

You need a minimum version of the mobile operating software, called the iOS, to be installed on your iPhone. The Loop app is compatible with iPhone devices with iOS 15.1 or newer.

"},{"location":"build/phone/#compatible-device","title":"Compatible Device","text":"

These devices are compatible.

These devices are compatible (now), but are limited to iOS 16.

These devices are compatible (now), but are limited to iOS 15.

"},{"location":"build/phone/#find-your-ios","title":"Find Your iOS","text":"

Your iOS version can be found under the phone Settings -> General -> About display as shown below. The iOS number is found on the Software Version line.

Do not use any of the beta iOS versions. (If you are uncertain what that means, then you are not using one.)

"},{"location":"build/phone/#developer-mode-mac-build-only","title":"Developer Mode - Mac Build Only","text":"

When you build the Loop app using Build with Browser, you are not required to enable Developer Mode on the phone or watch.

With iOS 16 or newer and watchOS 9 or newer, Apple added a feature. If you want to know more, click on this Apple Link about Developer Mode.

When you build the Loop app on your phone from Xcode directly and then transition to or start with iOS 16 or newer, you need to have Developer Mode enabled. This is also a requirement to use the Loop app on a watch paired to your phone running watchOS 9 or newer. You will be told to enable it in the Build the Loop App: Prepare your Phone and Watch instructions.

Developer Mode with iOS 16 or newer, watchOS 9 or newer

If you already have the Loop app built with Xcode on your phone/watch when you update to iOS 16 or newer/watchOS 9 or newer or newer, you will be told that the Loop app requires Developer Mode to run.

You will not be able to run the Loop app on your phone (or watch) until you have enabled Developer Mode on the device(s).

"},{"location":"build/phone/#battery-health","title":"Battery Health","text":"

Make sure the battery on your phone is solid. Your phone will become a critical health device - you want it to keep working.

Low Power Mode

With newer iOS, some people have reported the Loop app continues working in the background (phone locked) even in Low Power Mode. Others have reported they still get red loops. You can experiment to determine if your phone/iOS/app is able to maintain green loops in low-power mode. Otherwise, the best practice is to avoid Low Power Mode.

"},{"location":"build/phone/#use-automatic-time","title":"Use Automatic Time","text":"

Be sure to set the phone to automatic time. Do not try to defeat a game by modifying time on the same phone used to control your insulin.

Please read: The Loop Phone Must be on Automatic Time.

"},{"location":"build/phone/#turn-off-automatic-updates","title":"Turn Off Automatic Updates","text":"

Apple provides updates regularly to the iOS. Often, these updates include critical security patches in addition to improved new features.

Please be proactive - install updates as soon as the all-clear is given for using the Loop app with that iOS update.

If a limitation on your Mac prevents you from updating your phone to the latest iOS, consider using Build with Browser.

"},{"location":"build/phone/#why-turn-off-automatic-updates","title":"Why Turn off Automatic Updates?","text":"

When iOS updates are released, the Loop and Learn Version Updates page is typically updated faster than LoopDocs. Check to see if a new update is causing an issue with the Loop app or your CGM before accepting the update from Apple.

Within a few days, the \"All-Clear\" or (very rare) the \"WAIT there is a problem\" message will be posted.

"},{"location":"build/phone/#next-step-compatible-pump","title":"Next Step: Compatible Pump","text":"

Now you are ready to check if you have a Compatible Insulin Pump.

"},{"location":"build/pump/","title":"Compatible Pump","text":""},{"location":"build/pump/#compatible-pump","title":"Compatible Pump","text":"

Time Estimate

Summary

FAQs

"},{"location":"build/pump/#pumps-compatible-with-loop","title":"Pumps Compatible with Loop","text":"

There are three types of pumps compatible with Loop.

"},{"location":"build/pump/#check-medtronic-pump-version","title":"Check Medtronic Pump Version","text":"

If you have one of the pumps listed above, you are good to go on Loop! Congrats!

"},{"location":"build/pump/#extra-details-on-medtronic","title":"Extra Details on Medtronic","text":"

There are a number of Medtronic insulin pumps manufactured between 2006 \u2013 2012 which are compatible with the Loop app. Compatibility has two requirements: (1) pump model and (2) firmware.

"},{"location":"build/pump/#medtronic-pump-model","title":"Medtronic Pump Model","text":"

To determine your pump model, look at the backside of your pump. There should be a sticker on the underside of the pump. On the right-hand side of the sticker, it says REF MMT-XXXXXX

Some pumps may have an \u201cL\u201d or \u201cS\u201d or \"R\" before the pump region, e.g. a model number like MMT-722LNAS. This does not affect compatibility with the Loop app.

"},{"location":"build/pump/#medtronic-pump-firmware","title":"Medtronic Pump Firmware","text":"

A pump\u2019s firmware is the internal software that runs your pump. Older Medtronic firmware allows the Loop app to act as a \u201cremote control\u201d to set temp basals and report back pump data. Newer firmware disabled that \u201cremote control\u201d access and therefore cannot be used with these DIY closed-loop systems. There is currently no ability to downgrade a pump\u2019s firmware or replace it with older firmware. Before you buy a used pump, make sure you are getting one with compatible firmware.

The firmware on all 515/715 and 522/722 model Medtronic pumps is compatible with Loop. You will only need to check the firmware version for 523/723 and 554/754 model Medtronic pumps.

To find your pump\u2019s firmware you will need to power it on. If the pump has not been powered on for some time (i.e., has been in storage without a battery for a while), it will run through a start-up count and the firmware version will appear on the bottom right of the pump\u2019s screen. Don\u2019t turn away, as the version number will only be displayed for a little while before the screen moves onto other information displays.

If the pump has been active recently or has a reservoir installed, follow these steps:

  1. Press the button on your pump.

  2. Scroll down with the button to the bottom of the status display.

  3. Read the bottom line of the display.

"},{"location":"build/pump/#medtronic-pump-differences","title":"Medtronic Pump Differences","text":"

If you are in the position of being able to shop around for different pump models, there are some slight differences between the Loop-compatible Medtronic pumps.

500 vs 700: The difference between the Medtronic 500 series and the 700 series pumps is the size of the insulin reservoirs. The 500 series pumps use a 180 unit reservoir, and the 700 series pumps use a 300 unit reservoir (or smaller 180 unit reservoir, if you want).

x15/x22 vs x23/x54: The differences noteworthy between the x15 and x22 pumps versus the x23 and x54 series pumps are:

Pump Model Basal increments Bolus increments Range 515/715and522/722 0.050.1 0.10.1 deliveries of less than 10 unitsgreater than 10 units 523/723and554/754 0.0250.050.1 0.025 0.05 0.1 between 0.025 to 0.975 unitsbetween 1 to 9.95 unitsgreater than 10 units "},{"location":"build/pump/#finding-a-medtronic-pump","title":"Finding a Medtronic Pump","text":"

Finding a compatible Medtronic pump is probably the most difficult part for most new Loopers. Our suggestions:

The most success appears to come from either one-on-one discussions with fellow diabetics/doctors or using apps (Craigslist, NextDoor, LetGo, HelpAround). If you are using Craigslist, you may wish to use an app on your iPhone to make the searching easier. There are apps to search multiple cities at once for your keywords and set up alerts.

"},{"location":"build/pump/#safe-purchasing","title":"Safe Purchasing","text":"

If you choose to purchase from a remote or unknown seller, here are some tips for safe purchasing:

Red flags that may indicate a scam:

"},{"location":"build/pump/#pump-supplies","title":"Pump Supplies","text":"

Medtronic will not typically sell pump supplies directly to customers who have not previously purchased a registered Medtronic pump. Ask your insurance about purchasing pump supplies through a durable medical equipment (DME) provider. Typically, the DME provider will coordinate with your insurance and doctor's office to get the necessary insurance approval and prescriptions for the supplies. If you are brand new to Medtronic infusion sites, you may want to ask for help from friends to try a variety of infusion sets before purchasing a full 90-day supply of any type in particular.

"},{"location":"build/pump/#omnipod-pumps","title":"Omnipod Pumps","text":"

Reminder and Disclaimer

The use of Omnipod pumps with the Loop app is not supported by Insulet, although they are aware it is happening. Do not call Insulet asking for help with your Loop app build, setup, or operation. You are fully responsible for your use of the Loop app and do so at your own risk. Please read these documents and familiarize yourself with the Loop app before using it.

"},{"location":"build/pump/#omnipod-eros","title":"Omnipod Eros","text":"

Eros pods (also known as Gen 3) were launched in 2013 and continue to be sold by Insulet. Insulet has announced they will stop providing Eros pods in the US in December 2023. As far as we know, there are no timelines announced for the discontinuation of Eros pods for other countries. Insulet doesn't specifically call these \"Eros\" anymore, they just use the term \"omnipod system\". For clarity, from Insulet's webpage:

Alternative Names for Omnipod Eros Pump and Pods

Eros pump is also known as Classic, or UST400, or Omnipod Insulin Management System.

Pharmacy sites sometimes may refer to the Eros pods as Gen 3 but they are the same exact pods.

Eros system has a big Personal Diabetes Manager (PDM) that does not look like a phone.

"},{"location":"build/pump/#omnipod-dash","title":"Omnipod DASH","text":"

The DASH system has the newer, slimmer locked-android Personal Diabetes Manager (PDM) and built-in BLE communications in the pod, so there is no requirement for a RileyLink compatible device.

A RileyLink-compatible device is not required to use DASH with the Loop app. The communication with your iPhone uses Bluetooth.

Loop 3.0 and later works with DASH pods. If your version of the Loop app is 2.2.9 or earlier, you cannot use DASH pods.

"},{"location":"build/pump/#omnipod-5","title":"Omnipod 5","text":"

Loop does not support Omnipod 5 pods.

"},{"location":"build/pump/#next-step-compatible-cgm","title":"Next Step: Compatible CGM","text":"

Now you are ready to check if you have a Compatible CGM.

"},{"location":"build/rileylink/","title":"RileyLink","text":""},{"location":"build/rileylink/#order-a-rileylink-compatible-device","title":"Order a RileyLink Compatible Device","text":"

Not needed for DASH

Time Estimate

Summary

FAQs

"},{"location":"build/rileylink/#what-is-a-rileylink-compatible-device","title":"What is a RileyLink Compatible Device","text":"

The RileyLink compatible device is required to allow your phone to talk to compatible Medtronic and Omnipod Eros pumps. It is not needed for Omnipod DASH pumps.

Details for RileyLink

The RileyLink compatible device is an open-source hardware device that can bridge Bluetooth Low Energy (BLE) to the radio-frequency wireless communication used by compatible Medtronic and Omnipod Eros pumps.

Loop 3 has Omnipod DASH support, among other new features. When using Omnipod DASH, the RileyLink compatible device is not necessary. If you are using Medtronic or Omnipod Eros (not DASH), you still need the device regardless of which version of Loop you are running.

Medtronic and Omnipod Eros pumps require a RileyLink compatible device.

"},{"location":"build/rileylink/#rileylink-compatible-devices","title":"RileyLink Compatible Devices","text":"

The RileyLink protocol defines a specific Bluetooth interface and way of opening a Sub-GHz radio channel to pumps. All RileyLink compatible devices follow the RileyLink protocol.

There used to be just one option, the original RileyLink. Now there are more options, so you have to make a decision. Depending on your choice, be sure to have the correct charger and cables or batteries handy and add spare compatible supplies to your diabetes go-bag.

"},{"location":"build/rileylink/#more-information","title":"More information","text":"

There is an entire FAQs page on RileyLink Compatible Devices.

Sections of interest include:

"},{"location":"build/rileylink/#waiting-for-your-rileylink-compatible-device","title":"Waiting for your RileyLink Compatible Device","text":"

While you are waiting for the RileyLink compatible device to arrive, you can proceed with these build directions and can try one of the Simulated Loop options. After that, unless you are using Omnipod DASH, you'll have to wait for your device.

The population of DIY loopers (Loop and Android APS) has grown enough that you might be able to find someone local to loan you their spare.

"},{"location":"build/rileylink/#next-step-enroll-in-apple-developer-program","title":"Next Step: Enroll in Apple Developer Program","text":"

Now you are ready to enroll in the Apple Developer Program.

"},{"location":"build/test-settings/","title":"Test Settings","text":""},{"location":"build/test-settings/#test-settings","title":"Test Settings","text":"

Time Estimate

Summary

FAQs

Loop is just a fancy calculator underneath the hood. The math problems it solves depend on the settings you provide. So test settings before using the Loop app.

"},{"location":"build/test-settings/#basal-rates","title":"Basal Rates","text":"

Correct basal rates keep your blood glucose steady without food present. The standard method is to test your basal by having a relaxing 4-6 hours without eating at least two hours before you begin the test. Does your blood sugar stay steady? Or do you climb and need a correction? Or do you go low and need to eat? Setting basal is a crucial step to setting yourself up for success with the Loop app. It determines how much of the insulin delivered (from basal and bolus) is counted as insulin on board (IOB).

Basal Tricks

The Loop app keeps track of how much more or less insulin than your scheduled basal rates are required to keep glucose in target. Once you become a proficient looper, you can tune your basal by looking at IOB overnight or when food and exercise are not involved.

"},{"location":"build/test-settings/#insulin-sensitivity-factor","title":"Insulin Sensitivity Factor","text":"

The Insulin Sensitivity Factor (ISF), sometimes called Correction Factor, is how much one unit of insulin will bring down your glucose. The higher the value of this setting, the more sensitive to insulin you are. An ISF of 50 or 100 (2.8 or 5.5) means one unit of insulin lowers your glucose 50 or 100 mg/dL (2.8 or 5.5 mmol/L) in the absence of food or activity, when basal rates are correct.

Test ISF after you test and determine your basal rates. Simply bring yourself to a higher glucose with a glucose tab or choose a time when you are \"stuck\" higher than your target.

"},{"location":"build/test-settings/#carb-ratio","title":"Carb Ratio","text":"

The Carb Ratio (CR) is the amount of carbs covered by one unit of insulin. Ideally, a good carb ratio will restore your glucose close to its starting point within 3 hours of the meal. (High fat/protein meals may cause glucose to be impacted longer.)

If you are spiking higher than you\u2019d like after a meal, but still coming back to the starting glucose, consider pre-bolusing your meal earlier (maybe by 15-20 minutes) rather than changing the carb ratio.

"},{"location":"build/test-settings/#other-resources","title":"Other Resources","text":"

Check the companion site LoopTips. Several direct links to discussions are provided below:

If you\u2019re fascinated by this topic, read the book 'Think Like A Pancreas' by Gary Scheiner for a really great discussion.

"},{"location":"build/test-settings/#next-step-make-plans-for-loop-data","title":"Next Step: Make Plans for Loop Data","text":"

Now you are ready to make plans for Loop Data.

"},{"location":"build/testflight-xcode/","title":"TestFlight from Xcode","text":""},{"location":"build/testflight-xcode/#introduction","title":"Introduction","text":"

There are several different methods for making use of TestFlight:

This guide can also be followed to install other apps you build with Xcode via TestFlight. Examples include Loop Follow, Loop Caregiver, xDrip4iOS and GlucoseDirect.

Some useful features of using TestFlight to install Loop:

Since apps built with TestFlight expire after 90 days, it is suggested you also setup a build using the Build with Browser method even if you don't plan on using it. The GitHub build can be updated in a few minutes from any browser and is an extra layer of protection in these scenarios if you do not have access to your Mac for a rebuild:

In all cases, except accidental deletion of Loop or loss of phone, the Loop you install from TestFlight builds over your existing app and you keep all your settings including your pump.

"},{"location":"build/testflight-xcode/#build-to-testflight-via-xcode","title":"Build to TestFlight via Xcode","text":""},{"location":"build/testflight-xcode/#initial-steps","title":"Initial Steps","text":"

Before creating the app or uploading it to TestFlight, use the Build with Mac guide to sign your targets and build Loop to a simulator phone in Xcode. This checks to ensure the app you upload to your TestFlight will work as expected.

"},{"location":"build/testflight-xcode/#archive-the-project","title":"Archive the Project","text":"

Change the build target to from building to a simulated phone to LoopWorkspace > Any iOS Device (arm64) like the image below.

Now go to the top menu and choose Product > Clean Build Folder. Once it's done, it should say \"Clean Finished\".

Go back to the top menu and choose Product > Archive. This will build Loop into a file rather than a phone or simulator. It should take about the same amount of time as building to a phone or simulator does.

"},{"location":"build/testflight-xcode/#upload-the-archive","title":"Upload the Archive","text":"

Once the archive finishes building, it should automatically open the Archives window. If you want to open this window without re-archiving, click the following in the top menu: Xcode > Window > Organizer.

Select the archive and click Distribute App. If you've archived the project before, be sure to select the archive you intend to upload - most likely the one with the most recent Creation Date.

On the next screen, App Store Connect is selected by default. Click Next.

On the next screen, Upload is selected by default. Click Next.

"},{"location":"build/testflight-xcode/#first-time-archive-upload","title":"First-Time Archive Upload","text":"

If you have already created a TestFlight for Loop via Xcode or the GitHub Build method, the next screen will not be shown, so skip ahead to Subsequent Archive Upload.

If this is the first time you're creating a TestFlight for Loop, enter the following on the next screen and click Next:

"},{"location":"build/testflight-xcode/#subsequent-archive-upload","title":"Subsequent Archive Upload","text":"

On the next screen, leave everything checked and click Next.

On the next screen, leave it set to Automatically manage signing and click Next. You will see a few messages as it performs some tasks. Be patient.

When you see the next screen, click Upload.

Wait until uploading is finished. Don't be alarmed if you see the following screen, just click Done.

"},{"location":"build/testflight-xcode/#deploy-app","title":"Deploy App","text":"

Now that it's uploaded to TestFlight, it will take a little bit before it finishes processing and becomes available for installation on your iPhone. You can check appstoreconnect.apple.com/apps to find it's progress by clicking Test Flight and then iOS under Builds in the upper left. Once it no longer says \"Processing\" and instead says \"Ready to Submit\" next to the build's number, it should be available and ready to install on your iPhone.

To install Loop from TestFlight onto your iPhone, follow the instructions on the GitHub Deploy page.

"},{"location":"build/testflight-xcode/#update-app","title":"Update App","text":"

Apps installed via TestFlight are only valid for a maximum of 90 days, so you must upload a new build to TestFlight at least every 90 days.

To update, simply repeat all the steps on this page.

Add a Calendar Reminder

Note that the built-in Loop Notification for expiration has not been modified to read TestFlight expiration, yet.

So, please add a calendar reminder.

"},{"location":"build/updating/","title":"Update/Rebuild with Mac","text":""},{"location":"build/updating/#overview","title":"Overview","text":"

This page is only relevant when building with a Mac and Xcode.

For Browser Build, please see: Update/Rebuild with Browser

Time Estimate

Summary

Summary of tasks to prepare for and update your app:

In each of the sections below, follow links to sections of other build pages then hit the back button on your browser to return to this page.

FAQs

"},{"location":"build/updating/#when-to-update-loop","title":"When to Update Loop","text":"

Under ordinary circumstances, you do not have to update your Loop app until it expires (1 year for a paid account). However, we encourage regular updates when a new version of iOS, or of Loop, is released because they often contain bug fixes or improvements which may increase operational stability.

"},{"location":"build/updating/#ios-updates","title":"iOS Updates","text":"

Under ordinary circumstance, updating the iOS on your phone does not require a rebuild of the app on your phone. However, it's important to be prepared in case of an emergency, such as a lost phone.

Best Practice

It is good practice to first check if your computer (macOS or Xcode) will require an update to support building Loop to your phone BEFORE applying an iOS update to your Looping phone.

Follow these \"safe Looping\" steps for updating your iOS:

  1. Check which version of macOS and Xcode is required for the phone iOS you intend to install.
  2. Update macOS / Xcode if needed
  3. Check Loop: Current Release status - if there is new code, you should download it
  4. Build app to your iPhone
  5. Then update your iPhone iOS

Loop Releases provides information about current and previous Loop versions.

Updating to iOS 16 (watchOS 9 or newer) requires enabling Developer Mode. Your existing app will not open until you take this step. Once enabled, the app opens again. A rebuild is not required.

"},{"location":"build/updating/#loop-is-no-longer-available","title":"\"Loop\" is No Longer Available","text":"

The apps built and signed by you in Xcode with a paid developer account will last for 12 months; then they expire and must be rebuilt. At least once per year you will have to rebuild your app and go through this update process. If you do not update and the \"provisioning profile\" on your phone expires, you will see the \"Loop\" is No Longer Available message. You will be given multiple Loop App Expiration Notifications on the Loop phone, but might miss them if you are a caregiver.

When you see \"Loop\" is No Longer Available on your phone, the only solution is to rebuild the app. All of your settings are still present on your phone, but your \"provisioning profile\" expired and you need to generate a new one. Once you build Loop on your phone, following the instructions on this page, all your settings will be maintained - assuming you build with the same Apple Developers ID that was used initially.

"},{"location":"build/updating/#macos-and-xcode-versions","title":"macOS and Xcode Versions","text":""},{"location":"build/updating/#determine-required-xcode-and-macos-versions","title":"Determine Required Xcode and macOS Versions","text":"

Between Loop app builds, there's a high likelihood that Apple has updated one or more of the systems involved in your Loop app. If you don't have the minimum Xcode version required for your phone iOS, you cannot build on that phone. Sometimes you must also update the macOS version to allow you to use the required Xcode version.

Based on the iOS on your phone, or the iOS you plan to install on your phone, determine the required macOS and Xcode versions. Click on this link versions for iOS, macOS and Xcode to determine the versions needed and then hit the back button in your browser to finish the steps on this updating page.

If you are tired of the macOS and Xcode version update requirements, check out the Build with Browser option.

First macOS and Then Xcode

Your macOS must meet the minimum requirement for the Xcode version you need to support your current iOS as detailed in that link above.

Don't be that person. Follow the directions.

Minimum means you need to have at least that version - newer versions build just fine.

"},{"location":"build/updating/#verify-update-macos","title":"Verify / Update macOS","text":""},{"location":"build/updating/#verify-update-xcode","title":"Verify / Update Xcode","text":"

Click on this link Check your Xcode Version to find your Xcode version number.

If you need to update your Xcode, follow the instructions at this link Install Xcode and continue through Xcode Settings.

Advanced users: If you are finding installation of Xcode from the App Store incredibly slow, try the alternate method of Direct Download of Xcode.

Direct Download

"},{"location":"build/updating/#what-about-a-new-computer","title":"What about a New Computer?","text":"

Make sure your new computer has the macOS and Xcode required by your phone iOS. Be sure Xcode Command Line Tools are installed and that you Add Apple ID to Xcode.

"},{"location":"build/updating/#missing-xcode-or-command-line-tools","title":"Missing Xcode or Command Line Tools","text":"

WARNING

If you fail to have Xcode or Xcode Command Line Tools installed, you will get one of these errors (or something similar) when you attempt to run the Build Select Script:

Follow Xcode Settings page after updating Xcode

Make sure to restart your computer after updating Xcode and follow the instructions on the Xcode Settings page. There's a known issue that happens often enough to be frustrating if you skip those steps. It's not always required...but this is a good easy ounce of prevention step.\n
"},{"location":"build/updating/#check-your-developer-account","title":"Check your Developer Account","text":"

Apple updates its License Agreement for the Developer Program frequently. You need to login to your developer account to manually check if there is a new agreement to accept. If you see a big red or orange banner across the top of your Developer Account announcing a new license agreement like shown below...please read and accept it before building Loop.

"},{"location":"build/updating/#ready-to-build-loop","title":"Ready to Build Loop","text":"

As long as there are no errors, you are now ready to proceed to Build the Loop App: Developer Mode

After building the new app, you may choose to return to this page and follow the instructions to Delete Old Copies. This is optional, but cleans up space on your computer.

"},{"location":"build/updating/#delete-old-copies","title":"Delete Old Copies","text":"

This step is optional, but if your computer is low on space, it helps to clean up old downloads your are no longer using.

There is an easy way to do this. The Build Select Script used to download and build Loop provides Maintenance Utilities to help free up disk space.

Please review Loop and Learn: Build Select Script for more information.

Copy the line below that starts with /bin/bash by hovering the mouse near the bottom right side of the text and clicking the copy icon (should say Copy to Clipboard when you hover over it). When you click the icon, a message that says Copied to Clipboard will appear on your screen.

Copy and Paste to start the Build Select Script
/bin/bash -c \"$(curl -fsSL \\\n  https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildSelectScript.sh)\"\n

Paste the line of text into Terminal. Be sure to click anywhere in the terminal before trying to paste. (Ways to paste: Cmd+V ; or Ctrl click and select from menu or Edit-Paste at top of Mac screen.)

If you prefer to clean up old downloads yourself, keep reading.

Where is the old folder?

Assuming you used the Build Select Script, your downloads are in the ~/Downloads/BuildLoop folder as shown in the graphic below. If you are tight on space, the older folders can be deleted. Best practice, download fresh and build Loop; and then go back and delete all but the most recent copy. The nice thing about the Build Select script is it automatically generates the folder name with the date and time of the download. Delete each unwanted folder, one at a time.

If you see a file (not a folder) in ~/Downloads/BuildLoop called LoopConfigOverride.xcconfig, keep that around. If you delete it, you'll need to recover it from the trash, regenerate it (if you know how) or sign your targets manually for your current download.

The Scripts folder can also be left alone, but if you delete it, it is regenerated with the next use of the Build Select Script.

"},{"location":"build/updating/#background-information","title":"Background Information","text":"

New Loopers do not need to read the rest of this page.

Experienced Loopers may wonder what happened to deleting derived data.

"},{"location":"build/updating/#frequent-builder","title":"Frequent Builder","text":"

If you build frequently, you do not have to delete the profiles every time. When the build script asks if you want to \"Ensure a Year?\", you can skip that step.

On the other hand, you may need to delete the provisioning profiles or saved Xcode information about a version of LoopWorkspace (or other app) currently on your computer. The maintenance utilities found in the BuildSelectScrip can be run to delete your provisioning profiles or clear derived data. Or you can use the individual commands in the next sections to do the same thing.

"},{"location":"build/updating/#delete-provisioning-profiles","title":"Delete Provisioning Profiles","text":"

You can delete your provisioning profiles by copying this command and pasting it into any terminal. This does not affect any build you currently have on your phone - this just forces your current computer to generate a new one next time you build with Xcode.

Copy and Paste to manually remove your Provisioning Profiles on your computer
rm ~/Library/MobileDevice/Provisioning\\ Profiles/*.mobileprovision\n
"},{"location":"build/updating/#delete-derived-data","title":"Delete Derived Data","text":"

If you build using the same clone on your computer and then update that clone, sometimes you want to remove derived information that Xcode remembers and force it to start fresh.

First quit out of Xcode. The following command will delete all derived information for all your clones, so next time you build any app from an existing clone on your computer, the build will take longer. All dependencies will download again. So wait until you see the \"indexing\" indication on Xcode before trying to build.

Copy and Paste to manually force Xcode on your computer to start fresh
rm -rf ~/Library/Developer/Xcode/DerivedData\n
"},{"location":"build/updating/#revoke-certificate-issue","title":"Revoke Certificate Issue","text":"

What does it look like if you run into the Revoke Certificate message? When you prepare to Sign the Targets with Xcode, you'll see the message highlighted in the figure below.

More information is shown in the orange box below.

Revoke certificate

The important part of this message is:

WAIT - You might not need to revoke your certificate

  1. You might get this if you logged in as a different user, have a new computer or if your computer had to undergo a factory reset
    • You can transfer your keychain to your new computer (or just revoke and keep going)
    • To transfer your keychain, check this Apple Documentation Link
  2. Your version of Xcode is way out-of-date
    • Mentors have seen this with people trying to build with Xcode 11.4 or earlier
    • Update Xcode to the most recent version

If you revoke and keep going:

Be aware that you will have to rebuild to every device that used the certificate you just revoked and if you have other apps built with this certificate, they will stop working too.

"},{"location":"build/updating/#direct-download-of-xcode","title":"Direct Download of Xcode","text":"

Many people find updating Xcode from the App Store to be incredibly slow - especially when a new version has just been released. This method still takes time and enough space on your disk but is faster than going through the App Store. Depending on your internet speed, this download can be done in about an hour. Then once it is downloaded, expect another fifteen minutes to several hours (depending on the speed of your computer) for the \"xip\" file to \"expand\".

The instructions do not hold your hand.

Here are the different steps you need to follow when doing the Direct Download instead of the App Store method:

  1. Login to your Apple developer account
    • Examine the menus (on my computer there are buttons on the left-hand side)
    • Click on Downloads (under Additional Resources)
    • Look at menu items (on my computer there are buttons at the top) that say Beta, Release, Profiles and Logs, and More
    • Click on More
    • Scroll down until you find the item you want (for example, Xcode 13)
    • Click on View Details and click on the Download button for the \"xip\" file
  2. Wait for Download to complete
  3. Expand the file by clicking on it in Finder
  4. Move the Xcode icon to Applications after the expansion completes
  5. Check the Command Line Tools setting under Xcode->Settings
    • The selection cannot be blank or Build-Script will fail to open Xcode automatically
    • It should be the same version as your Xcode
  6. Reboot the computer
"},{"location":"build/xcode-settings/","title":"Xcode Settings","text":""},{"location":"build/xcode-settings/#xcode-settings","title":"Xcode Settings","text":"

Time Estimate

Summary

FAQs

"},{"location":"build/xcode-settings/#xcode-version","title":"Xcode Version","text":"

Open Xcode from your Applications folder. If it offers to start a new project with you, just close that window.

Click on the Xcode->About Xcode menu item. The version number is displayed.

"},{"location":"build/xcode-settings/#privacy-settings","title":"Privacy Settings","text":"

This is not typical, but it does happen.

Some people have their macOS privacy settings configured so that Xcode does not have permission to access their ~/Downloads folder. This will cause a lot of grief when trying to use the Build Select Script to build an app with Xcode. This will be mentioned on the build errors page, but this is a good time to check. The graphic below has steps labeled 1 through 4 to guide you to the setting that must be enabled for you to build the app with Xcode.

"},{"location":"build/xcode-settings/#watchos-simulators","title":"watchOS Simulators","text":"

Yes, watchOS simulators are required to build Loop. If Xcode asks if you want to download them - say yes. It's slow but you cannot build Loop without the simulator.

"},{"location":"build/xcode-settings/#command-line-tools","title":"Command Line Tools","text":"

The very first time you open Xcode it may install a package of command line tools. Wait patiently until it finishes. The command line tools may have installed without asking.

"},{"location":"build/xcode-settings/#add-apple-id","title":"Add Apple ID","text":"

Go to the Xcode Settings window from above, click on the Accounts tab and then press the + in the lower-left corner to add an Apple ID account.

"},{"location":"build/xcode-settings/#xcode-accounts-tab","title":"Xcode Accounts Tab","text":"

The Xcode Accounts Tab, shown in the graphic (from Xcode 13) below allows you to have more than one account available to choose from when you sign your targets (another new term that is explained later). Normally, you would only have one.

In the graphic, whichever item is selected on the left side (highlighted by Xcode in blue) shows up with more details on the right side of the display. If the Free account had been selected, the information shown in the red inset would have been displayed.

Free and Paid

The graphic below shows examples for a paid account and a free account. You will only see one.

"},{"location":"build/xcode-settings/#free-developer-account","title":"Free Developer Account","text":"

If you want to use a free developer account, you will simply enter your Apple ID in this section and Xcode will automatically enroll your Apple ID in the free developer program. It will show up with the (Personal Team) and User indication.

"},{"location":"build/xcode-settings/#paid-developer-account","title":"Paid Developer Account","text":"

If you enrolled in the paid account already and have confirmation that your account is active, enter the Apple ID of the paid developer account. It will show up with just your name and the Admin indication. If you have enrolled and are waiting, the (Personal Team) and User indication shows up until the paid account is confirmed by Apple.

Description

The description line is initially empty. You can add your own description or just leave the line blank. Text added to the decription line shows up in two places: To the left, just above the email address and to the right once that Apple ID is selected.

You are now done setting up Xcode. Great job! You will not need to redo the account setup steps on any subsequent builds or updates of your Loop app. Xcode will remember these settings.

"},{"location":"build/xcode-settings/#next-step-build-loop","title":"Next Step: Build Loop","text":"

Now you are ready to Build the Loop App.

"},{"location":"build/xcode-version/","title":"Xcode Version","text":""},{"location":"build/xcode-version/#install-required-xcode-version","title":"Install Required Xcode Version","text":"

Time Estimate

Summary

FAQs

"},{"location":"build/xcode-version/#what-is-xcode","title":"What is Xcode?","text":"

Xcode is a free application for Apple computers. You will use Xcode to turn the \"raw\" Loop source code into an iOS application and install it onto your iPhone. Which version of Xcode you install on your computer depends on the iOS version you have on the iPhone you are going to be installing Loop on and the macOS version you have on your computer.

Because of the complexity of these dependencies, please read this entire page.

Or - look into building with GitHub Actions - no Mac computer required, no need to worry about versions for Mac OS or Xcode - all done for you on GitHub (some configuration required).

"},{"location":"build/xcode-version/#which-version-of-xcode-do-i-need","title":"Which version of Xcode do I need?","text":"

First, choose a version of Xcode appropriate for your iOS device. Then, determine the minimum macOS version required for that Xcode version. Update to at least that minimum macOS version. Then follow the instructions to download and install Xcode (or update an existing installation):

"},{"location":"build/xcode-version/#version-relationship-overview","title":"Version Relationship Overview","text":"

Have you turned off automatic updates on your iOS device?

Loop and iOS Updates

Please Read: Turn Off Automatic Updates

Before manually accepting an iOS update, be sure you have compatible versions of Xcode and MacOS.

Minimum Xcode Version

The minimum version of Xcode you need depends on the iOS version you have on your phone.

Please Read: Minimum Version List

Can't find the required Xcode version

Don't be the person who posts for help saying, \"I'm trying to update my Loop app but am getting errors.\" When asked what Xcode version they have and if they've updated, they respond, \"I don't have any Xcode updates available in the App Store, so I must be running the most current version.\"

Actually, they forgot to check for macOS updates and therefore cannot see the needed Xcode update yet.

"},{"location":"build/xcode-version/#after-update-reboot","title":"After Update - Reboot","text":"

After any update of macOS or Xcode, it is always a good idea to reboot your computer.

"},{"location":"build/xcode-version/#how-do-all-the-minimum-versions-relate-to-each-other","title":"How do all the minimum versions relate to each other?","text":""},{"location":"build/xcode-version/#compatible-versions","title":"Compatible Versions","text":"

The current development version and the next release of\u00a0Loop\u00a0will require Xcode version 15 regardless of the iOS on the phone. This requires macOS 13.5 or higher. As an alternative, use Build with Browser, which supports iOS 15, 16, and 17.

When this page was last updated, macOS 14.0 and Xcode 15.0 were tested to successfully build the app for phones with iOS 15 through iOS 17.0.2.

The table below lists the minimum requirements to build the current release of\u00a0Loop 3.2.3. If your macOS or Xcode version is higher, you can build with Mac.

Find your phone iOS in the table below. If your iOS is not listed, e.g., 16.6, choose the first row that is less than your iOS.

iOS Version minimum Xcode minimum macOS 17.0 15.0 13.5 16.4 14.3 13.0 16.2 14.2 12.5 15.1 14.1 12.5"},{"location":"build/xcode-version/#wikipedia-chart-for-apple-versions","title":"Wikipedia Chart for Apple Versions","text":"

This graphic (copied from Wikipedia and last updated March 2023) is not updated with every iOS update - use it as a map to read the minimum requirements. Every attempt will be made to update the words in the Minimum Version List promptly - that's much easier than updating a graphic.

Follow this link to Wikipedia and scroll down to the current version of this figure - the graphic shown below is a map of how to read the current version of this figure at Wikipedia.

"},{"location":"build/xcode-version/#what-happens-if-you-try-using-too-old-of-xcode","title":"What happens if you try using too old of Xcode?","text":"

It isn't some catastrophic failure if you try to build with an outdated Xcode without realizing it. If the build fails, nothing happens to your phone (or Loop on your phone if you are rebuilding). Nothing is copied from the computer to the phone until after you see the Build Succeeded message. You'll see a pretty obvious error message during your Loop build. Check Oh dear! Build errors?.

Some error messages that have shown up in earlier updates:

Package.resolved file corrupted or malformed\n

This is for trying to select an iOS 17 phone when building with Xcode 14:

Could not locate device support files\n

This is for building development code with Xcode 14 instead of Xcode 15:

Loop Widget errors like:\nCommand SwiftCompile failed with a nonzero exit code\nCannot infer contextual base in reference to member 'widget'\n
"},{"location":"build/xcode-version/#next-step-xcode-settings","title":"Next Step: Xcode Settings","text":"

Now you are ready to set up Xcode Settings.

"},{"location":"faqs/algorithm-faqs/","title":"Algorithm FAQs","text":""},{"location":"faqs/algorithm-faqs/#does-loop-learn-or-detect-changes-in-your-insulin-needs","title":"Does Loop \"learn\" or detect changes in your insulin needs?","text":"

The answer is both Yes and No.

Yes in that:

No in that:

Perhaps in subsequent versions of Loop, auto-adjustment of settings or machine learning could be incorporated. Until then, you will need to tell Loop if your underlying settings change or make temporary adjustments for short term issues.

The use of Overrides can be quite helpful for short-term changes.

"},{"location":"faqs/algorithm-faqs/#what-does-negative-active-insulin-mean","title":"What does negative Active Insulin mean?","text":"

When Loop withholds or suspends some of your scheduled basal insulin, that starts an accumulation of insulin deficit. If you have a kinked cannula and insulin is not delivered, you'd call yourself \"lacking insulin\" (negative IOB).

When Loop reports negative IOB, it is a sign that Loop has been actively helping you prevent a low blood sugar. If you find significant negative IOB regularly, you probably need to adjust/test your settings. Glucose that continues to decrease (away from a meal) when IOB goes negative is typically a sign that the scheduled basal rate is too high.

Developer Notes

Scheduled basal rates are meant to counteract your endogenous glucose production. Another way of saying this is that Loop expects your body to be producing an amount of glucose at a rate that is handled by your basal insulin settings.

Your body doesn't really produce glucose at a fixed rate, but that's how it's modeled in Loop.

\"All models are wrong, but some are useful.\" (Quote attributed to British statistician George E. P. Box.)

"},{"location":"faqs/algorithm-faqs/#how-is-iob-calculated","title":"How is IOB calculated?","text":"

Insulin on board (IOB) is calculated from the amount of insulin delivered above or below the scheduled basal rate. For each dose of insulin, the insulin model is used to determine how much of that insulin is active over time. Loop is adding up all the amounts over the full Duration of Insulin Action (DIA). The DIA is 6 hours for most rapid insulin in the models used by Loop.

IOB is plotted on the Active Insulin Chart in the main Loop display.

"},{"location":"faqs/algorithm-faqs/#how-do-delivery-limits-affect-automatic-dosing","title":"How do Delivery Limits Affect Automatic Dosing?","text":"

With each cycle, Loop\u00a0generates a glucose prediction and a recommended dose (positive or negative) to bring you to your correction range.

Let \\(\\mathit{dose}\\) be the amount the app thinks you need for this cycle before considering Delivery Limits. The relationship between \\(\\mathit{dose}\\), delivery limits: \\(\\mathit{maximumBolus}\\) and \\(\\mathit{maximumBasalRate}\\), and current IOB: \\(\\mathit{currentIOB}\\) are detailed in the following sections:

"},{"location":"faqs/algorithm-faqs/#manual-dose","title":"Manual Dose","text":"

In this case, where you are manually requesting a bolus recommendation by using the double orange triangles (circled below) in the toolbar at the bottom of the Loop status screen, only the \\(\\mathit{maximumBolus}\\) Delivery Limit is considered.

"},{"location":"faqs/algorithm-faqs/#automatic-dose","title":"Automatic Dose","text":"

Because this will be an automatic dose, the app will not provide a dose that would exceed an IOB of 2 times the \\(\\mathit{maximumBolus}\\). The term automatic dose refers to insulin the app automatically delivers above your scheduled basal rate.

\\[ autoDose = minimum (dose, {2*maximumBolus} - currentIOB) \\]

Note that a manual dose can exceed \\(\\mathit{autoDose}\\). There will be no warning if this happens. But no additional automatic dosing will happen until IOB is below \\(\\mathit{2*maximumBolus}\\). As long as the prediction is above the correction range, scheduled basal continues regardless of IOB.

"},{"location":"faqs/algorithm-faqs/#automatic-bolus-constant-partial-application-factor","title":"Automatic Bolus: Constant Partial Application Factor","text":"

There is a new feature coming with the next release, available now with customization or the development version, called Glucose Based Partial Application Factor. This feature is disabled by default. When disabled, the Partial Application Factor is a constant 40%.

"},{"location":"faqs/algorithm-faqs/#automatic-bolus-glucose-based-partial-application-factor","title":"Automatic Bolus: Glucose Based Partial Application Factor","text":"

When Glucose Based Partial Application Factor is enabled, the application factor is modified based on the current glucose level. The value ranges from 20% at lower glucose to 80% at higher glucose. Let \\(\\mathit{gbpa\\%}\\) represent the application factor, then:

"},{"location":"faqs/algorithm-faqs/#temp-basal-only","title":"Temp Basal Only","text":"

This automatic method uses both Delivery Limits: \\(\\mathit{maximumBasalRate}\\) and \\(\\mathit{maximumBolus}\\). As explained above, the \\(\\mathit{maximumBolus}\\) is used to calculate \\(\\mathit{autoDose}\\).

The desired dose, \\(\\mathit{autoDose}\\), is multiplied by two (to get an hourly rate) and then added to the scheduled basal rate to determine the desired temporary basal rate (\\(\\mathit{BR_temp}\\)) with a duration of half-an-hour to provide that amount of insulin. This calculated \\(\\mathit{BR_temp}\\) is compared to \\(\\mathit{maximumBasalRate}\\).

"},{"location":"faqs/algorithm-faqs/#more-algorithm-information","title":"More Algorithm Information","text":"

There is more detail about the Loop Algorithm at the bottom of the Operate tab.

"},{"location":"faqs/apple-health-faqs/","title":"Apple Health FAQs","text":""},{"location":"faqs/apple-health-faqs/#how-does-loop-use-apple-healthkit","title":"How does Loop use Apple HealthKit?","text":"

Loop uses Apple HealthKit as long term storage for glucose, insulin and carbohydrates. But there is more going on than simple storage.

It is important that permissions for Loop be properly configured for the Health app.

To view the list of data stored in Health

To Set Blood Glucose, Carbohydrates and Insulin as Favorites

"},{"location":"faqs/apple-health-faqs/#healthkit-plots","title":"HealthKit Plots","text":"

The health app on the Loop phone provides useful plots of data since you started to Loop with that Apple ID. Examples for insulin delivery and carbohydrates are shown in the graphic below. New versions of iOS modified details of the display with the same or improved capabilities.

"},{"location":"faqs/apple-health-faqs/#healthkit-details","title":"HealthKit Details","text":""},{"location":"faqs/apple-health-faqs/#glucose-and-apple-healthkit","title":"Glucose and Apple HealthKit","text":"

For Dexcom users with the Dexcom app on the Loop phone, the Dexcom app writes the value to Health with a 3-hour delay.

Loop reads the Dexcom information at the same time the Dexcom app gets the reading from the transmitter. It uses the glucose value to update predictions and stores it in Health.

If you look at your Health glucose readings, you'll notice the Loop icon for the last 3 hours and the Dexcom icon for times earlier than that.

All other CGM readings are reported with the Loop icon and there is no transition after 3 hours.

"},{"location":"faqs/apple-health-faqs/#carbohydrates-and-apple-healthkit","title":"Carbohydrates and Apple HealthKit","text":"

In Loop* 2.2.x, if you set Apple Health app permissions to allow it, Loop will read carbohydrates from the Health app. If you give a third-party app permission to store carbohydrate data in Health, and do not realize that Loop reads that information, you might get unexpected insulin delivery based off those carbs. To avoid that unanticipated behavior, the directions tell you to set permissions to allow Loop to write to carbohydrate storage but not read.

In Loop 3, the option to read from Health carbohydrates is explicitly disabled and can only be enabled by setting up special parameters when you build the app. The insructions for the code customization are not in LoopDocs yet. If it is important to you to use a third-party app to record carbohydrates and have Loop read the information and automatically dose with insulin, ask for help in zulipchat.

"},{"location":"faqs/apple-health-faqs/#insulin-and-apple-healthkit","title":"Insulin and Apple HealthKit","text":"

The relationship between Loop and Apple HealthKit is very important to understand if you ever need to do one of these actions:

Be Cautious

Allowing users to delete events is fairly risky. If a user deletes a dose accidentally, or does not understand the IOB impact while in closed loop is enabled, then Loop may start giving insulin that is not needed.

One method to deal with insulin that wasn't given is to go disable closed loop for 3 to 6 hours. However, if you take care, you can remove insulin from Loop.

Developer Notes: Pump Events and Insulin Delivery

Loop stores Pump Events separately from Insulin Delivery. With permissions set to allow Loop to read insulin from Health (recommended), the Insulin Delivery store contains doses entered from Health as well as the subset of pump events that represent doses.

Pump Events are displayed by tapping an insulin chart on the main screen and viewing the Event History tab.

When you delete a pump event using the Event History interface in Loop, the associated entry in Insulin Delivery is not deleted.

"},{"location":"faqs/apple-health-faqs/#bolus","title":"Bolus","text":"

Pro Tip

Write on a piece of paper the times and values you think you should delete.

Look at those values in both Event History and Health Insulin data list.

Record what Loop is reporting as IOB.

Review the values one more time, and then delete those entries in both places. Review IOB again. If you made a mistake, you can refer to that written list and adjust appropriately.

"},{"location":"faqs/apple-health-faqs/#basal","title":"Basal","text":"

Loop keeps track of how much basal is delivered so the IOB is properly reported. In older versions of Loop, there may be occasional display glitches, but the internal accounting is correct and updates every Loop Cycle.

Developer Notes: Scheduled Basal is Not a Pump Event

Scheduled basal is not a pump event so you will not see it listed in the Event History tab.

Scheduled basal does not affect IOB when delivered as scheduled.

The Insulin Delivery store keeps track of the insulin delivered via scheduled basal.

Loop updates the amount of insulin delivered through basal (both scheduled and temporary) to Health at regular intervals - this does not happen every Loop Cycle when basal rates are not changing. The updates to Health happen:

A simple example to illustrate this - for a pump with smallest insulin delivery of 0.05 U:

Schedule Temp Basal (TB) Health Explanation 12:00 AM0.4 U/hr --- --- Start of Day / Start of Example 06:00 AM0.5 U/hr --- 06:00 AMBasal2.4 U Loop reports insulin delivered by basal for the last 6 hours when the scheduled basal rate has a new entry --- 07:15 AM0.0 U/hr 07:15 AMBasal0.6 U Loop reports insulin delivered by basal since last report up to time TB starts --- 07:45 AMTB expires 07:45 AMBasal0 U No insulin was delivered during TB 08:00 AM0.4 U/hr --- 08:00 AMBasal0.1 U Loop reports insulin delivered by basal since last report; the scheduled basal rate has a new entry"},{"location":"faqs/apple-health-faqs/#tidepool-and-apple-healthkit","title":"Tidepool and Apple HealthKit","text":"

If you have a Tidepool account and use the Tidepool uploader on your Loop phone, the data in Health is uploaded to your Tidepool database where you can view displays with the Tidepool web browser tool.

"},{"location":"faqs/apple-health-faqs/#how-do-i-modify-apple-healthkit-permissions","title":"How Do I Modify Apple HealthKit Permissions","text":""},{"location":"faqs/apple-health-faqs/#loop-health-permissions","title":"Loop Health Permissions","text":"

You can review and modify the Apple HealthKit permissions for the Loop app.

Open the Apple Health app ( icon)

At this point, you can review and modify the settings.

"},{"location":"faqs/apple-health-faqs/#cgm-health-permissions","title":"CGM Health Permissions","text":"

If you choose to, you may add permission for your CGM app to write to Apple Health. Loop will read glucose from Apple Health, but only while the phone is unlocked and the app is open.

Note that if a glucose value is added to Apple Health \"now\", Loop will pick up that value and use it for the glucose prediction. This can happen with a finger-stick entry or some Libre third-party apps, but not with Dexcom, which has a 3-hour delay before writing to Health.

"},{"location":"faqs/apple-health-faqs/#dexcom","title":"Dexcom","text":"

The Dexcom app for both G6 and G7 has a 3-hour delay before writing to the Health app. If you tap Glucose data in Health, scroll to the bottom to select Show All Data and then scroll back in time, notice the Loop icon is replaced by either the G6 or G7 icon starting 3 hours ago.

If you happen to wear a Dexcom G6 and G7 sensor at the same time, then starting 3 hours in the past, both sensor traces will show up in the Loop Glucose chart.

Loop only uses data from the CGM you selected as your CGM for closed-loop insulin delivery, but don't be surprised at the double trace if you want to wear both during the transition from G6 to G7.

Add Permission to Health for Dexcom to Write Glucose

If either the G6 or the G7 has permission to write to Apple Health, then Loop will delete the Loop glucose data in Apple Health that are older than 3 hours and newer than 1 week. The Dexcom app will write its glucose values to Health when each value is 3 hours old.

If you transition from G6 to G7 (or alternate back and forth), be sure that at least the app you are currently using has permission to write to health. (I inadvertently forgot to turn on health permission for G7. By the time I noticed, I had a gap of several days in my Apple Health storage of glucose values.)

"},{"location":"faqs/apple-health-faqs/#libre","title":"Libre","text":"

There are several choices for reading Libre sensors.

With Loop dev (will be Loop 3.4.x after release), LibreTransmitter is integrated with the Loop app.

The frequent updates (1-minute glucose data) provided by Libre did cause some issues with released versions (Loop 3.0 and Loop 3.2.x with customizations that use various third-party apps to read the Libre). These were fixed initially by modifying the third-party apps to limit how frequently they supplied glucose data.

With Loop dev (will be Loop 3.4.x after release), the Loop app only initiates a closed-loop cycle automatically following a new glucose value if it has been more than 4.2 minutes since the last one.

Loop 3.0 and Loop 3.2.x versions do not have that limitation on how frequently Loop responds to a new glucose reading. There is a Customization that incorporates the 4.2 minute interval check which can be applied to Loop 3.2.2.

"},{"location":"faqs/apple-health-faqs/#how-do-i-change-glucose-units","title":"How Do I Change Glucose Units?","text":"

The glucose units (mg/dL or mmol/L) Loop uses match what is in Apple Health. Once you connect a device that reports glucose to the phone, make sure the units match the device. Note - you can change units for Dexcom Share and it translates units for you - not sure about other devices.

"},{"location":"faqs/cgm-faqs/","title":"CGM FAQs","text":""},{"location":"faqs/cgm-faqs/#which-cgms-are-supported-by-the-loop-app","title":"Which CGMs are supported by the Loop app?","text":"

The next release of the Loop app and the current Loop-dev branch includes Libre support in addition to the CGM listed below.

The Loop app supports G5, G6, G7, Dexcom ONE, Dexcom Share, Nightscout and the Medtronic CGM systems compatible with Looping pumps.

Libre Support (for some Libre sensors):

There are more details on the Compatible CGM page.

"},{"location":"faqs/cgm-faqs/#do-i-need-wait-for-a-new-sensor-session-to-start-loop","title":"Do I need wait for a new sensor session to start Loop?","text":"

No, you can start Looping mid-sensor session. There's no need to do anything special with regards to your CGM session when starting or ending the Loop app.

"},{"location":"faqs/cgm-faqs/#what-do-i-do-when-sensor-is-in-warm-up","title":"What do I do when sensor is in warm-up?","text":"

The Loop app will stop automatically adjusting insulin when the most recent glucose value is older than 15 minutes. This is indicated by seeing three dashes in place of the glucose reading on the HUD.

With no recent glucose readings, your pump returns to the scheduled basal delivery (within 30 min or less).

Loop continues to accept carb entries and manual bolus commands. Manual Temp Basal can also be commanded.

"},{"location":"faqs/cgm-faqs/#dexcom-g7-warmup","title":"Dexcom G7 Warmup","text":"

The Dexcom G7 begins warming up as soon as you insert the device and completes in less than half an hour. Many Loopers use the combination of this warmup upon insertion and the 12-hour grace period offered by the G7 to have continuous CGM readings with no gap.

"},{"location":"faqs/cgm-faqs/#what-do-i-do-when-i-switch-dexcom-transmitters","title":"What do I do when I switch Dexcom transmitters?","text":"

When you change transmitters (prior to Dexcom G7), you will need to update the transmitter ID in your Loopsettings. The instructions for Dexcom are provided below:

If you don't update your transmitter ID when you change active transmitters, and you included your Dexcom share credentials, then the Loop app uses your Dexcom Share server to get your CGM data and will not work without cell or wifi connection. When the Loop app is using data from Dexcom Share servers, a small cloud will appear above the BG reading in the Loop app and should tip you off that maybe you forgot to update your transmitter ID. It's best not to enter Share Credentials. This makes it really obvious that you need to update the CGM settings in the Loop app at transmitter change time.

"},{"location":"faqs/cgm-faqs/#dexcom-g7","title":"Dexcom G7","text":"

With Dexcom G7, the Loop app automatically picks up the active sensor/transmitter pair from the Dexcom G7 app on the phone. Once Dexcom G7 is added to the Loop app as the CGM, the Looper does not need to do anything to the Loop app after selecting the new sensor/transmitter pair in the Dexcom G7 app.

"},{"location":"faqs/cgm-faqs/#dexcom-g5-g6-and-one","title":"Dexcom G5, G6 and ONE","text":"

The diagram below illustrates the steps needed to switch transmitters on Dexcom G5, G6, and ONE (for the version of ONE based on G6). This typically needs to be done every three months when a new transmitter is started.

sequenceDiagram\n    actor       user     as User\n    participant dexcom   as Dexcom App\n    participant loop_app as Loop App\n\n    autonumber\n    user     ->>  loop_app: Delete CGM\n    user     ->>  dexcom:   Stop old Sensor\n    activate      dexcom\n    Note over     dexcom:   Switching sensors and transmitters... \u23f1\ufe0f\n    user     -->> user:     Remove old Sensor and old Transmitter\n    user     ->>  dexcom:   Enter/Scan new Transmitter ID\n    user     ->>  dexcom:   Enter/Scan new Sensor Code\n    user     -->> user:     Insert new Sensor then attach new transmitter\n    user     ->>  dexcom:   Pair then Start new Sensor\n    deactivate    dexcom\n    dexcom   -->> user:     New Sensor warming up... \n    activate      dexcom\n    Note over     dexcom:   New sensor warmup... \u23f1\ufe0f\n    user     ->>  loop_app: Add CGM\n    user     ->>  loop_app: Enter new Transmitter Serial Number\n    user     ->>  loop_app: Enable Remote Upload\n    dexcom   -->> user:     New Sensor operational\n    deactivate dexcom
"},{"location":"faqs/cgm-faqs/#can-i-use-libre-sensors-with-a-reader-like-miao-miao","title":"Can I use Libre sensors with a reader like Miao Miao?","text":"

If you use Loop dev code, then any Libre sensor supported by LibreTransmitter can be used with the Loop app.

See Which CGMs are supported by the Loop app?.

"},{"location":"faqs/cgm-faqs/#can-i-use-eversense","title":"Can I use Eversense?","text":"

There is a method to upload Eversense to Nightscout using an Android phone, but there is no method to read an Eversense directly with an iPhone at this time.

You can use Nightscout as a CGM with Eversense, but that requires internet access.

"},{"location":"faqs/cgm-faqs/#can-the-loop-app-read-cgm-data-from-nightscout","title":"Can the Loop app read CGM data from Nightscout?","text":"

Yes.

"},{"location":"faqs/cgm-faqs/#what-other-cgm-apps-can-be-used-with-loop","title":"What other CGM apps can be used with Loop?","text":"

If you are willing to build a development version of Loop, the dev branch incorporates LibreTransmitter into the Loop app itself. Please read about Loop Development before building dev and using the dev app.

You can add xDrip4iOS and GlucoseDirect as a CGM option to the Loop app by applying a code customization.

Please read the docs for xDrip4iOS and Glucose Direct. You must build these apps yourself to Loop; you cannot use the TestFlight pre-built versions.

"},{"location":"faqs/glossary/","title":"Glossary","text":"

Each item in the glossary is also a Tooltip. The word or phrase is repeated in parentheses to assist those using Google Translate.

When Google Translate is selected:

Actions\u00a0 (Actions): a custom application for the GitHub Actions platform that performs a complex but frequently repeated task; specifically used to build Loop from a browser

Activated\u00a0 (Activated): for Omnipod: time at which insulin was injected into pod and 2 beeps were heard

Anchor Links\u00a0 (Anchor Links): any header on a LoopDocs page can be used as a link, tap on the paragraph symbol at the end of the header to view the link in the URL

API_SECRET\u00a0 (API_SECRET): password (min 12 characters) needed to access Nightscout Site

API\u00a0 (API): Application Programming Interface

APN\u00a0 (APN): Apple Push Notification service, required for issuing remote command via Nightscout

App Group\u00a0 (App Group): a unique identifier that Apple users for a given app, yours has your TEAMID embedded in it, group.com.TEAMID.loopkit.LoopGroup

Automatic Bolus\u00a0 (Automatic Bolus): provide a fraction of the recommended insulin automatically with each updated CGM reading (default 40%)

BAGE\u00a0 (BAGE): pump battery age on Nightscout site

Big Sur\u00a0 (Big Sur): older version for operating system for Mac, macOS 11.x

BLE\u00a0 (BLE): Bluetooth low energy, used for communication by phones, CGM and some pumps

Build Select Script\u00a0 (Build Select Script): by running a command in your terminal, this menu-driven tool assists in building Loop

branch\u00a0 (branch): version of code within a single repository or workspace repository

CAGE\u00a0 (CAGE): cannula (or pump site) age on Nightscout site

carthage\u00a0 (carthage): a program that used to be required to build Loop - no longer needed

Catalina\u00a0 (Catalina): older version for operating system for Mac, macOS 10.x

Certificate\u00a0 (Certificate): Apple certificate is used to sign your iOS or Mac apps - tied to but different from your permanent Developer ID

CGM\u00a0 (CGM): continuous glucose monitor, wearable medical device that measures and reports glucose in interstitial fluid

Closed Loop\u00a0 (Closed Loop): Loop will make automated adjustments of insulin delivery using predictions based off user entries, settings, IOB and COB

Open Loop\u00a0 (Open Loop): Loop will not make automated adjustments of insulin delivery but predictions and recommendation features are available

clone\u00a0 (clone): create a copy of a repository on your computer including revision history and ability to update using git commands

COB\u00a0 (COB): Carbs on Board, affects automated insulin delivery: the g of carbohydrates that Loop expects to be absorbed and uses for glucose prediction

commit\u00a0 (commit): a formal change to files in a repository; each commit has an alphanumeric identifier (SHA-1)

Config Vars\u00a0 (Config Vars): configuration parameters for a Nightscout Site

Correction Factor\u00a0 (Correction Factor): how many points your blood sugar will drop for each unit of insulin; Loop calls this Insulin Sensitivity Factor (ISF)

Correction Range\u00a0 (Correction Range): Loop recommends changes to basal and / or bolus to bring glucose predictions into this range

CR\u00a0 (CR): Carb Ratio; how many grams of carbs are covered by one unit of rapid-acting insulin

Delivery Limits\u00a0 (Delivery Limits): max bolus and max basal rates allowed by your therapy settings

Developer Mode\u00a0 (Developer Mode): Extra security for iOS 16 and newer; this must be turned on to allow an app built from Xcode directly to the phone to run on a phone or watch

DIA\u00a0 (DIA): Duration of Insulin Action, the full time insulin is active including a long, low-level tail

DIY\u00a0 (DIY): Do it yourself, a common acronym for the open-source software community (and the maker community)

Dosing Strategy\u00a0 (Dosing Strategy): chosen method for increased insulin dosing: (1) High Temp Basal or (2) Automatic Bolus with scheduled basal

dynos\u00a0 (dynos): used to reboot a Nightscout Site

EmaLink\u00a0 (EmaLink): radio-frequency device Loop uses to control Eros pods (aka. Gen 3) and older Medtronic pumps

Event History\u00a0 (Event History): record of pump events (bolus or temp basal) reported and used by Loop

Expiration Date\u00a0 (Expiration Date): your Loop app has a finite life, the app warns you starting 3 weeks before the expiration date

fastlane\u00a0 (fastlane): used as part of the github Build Action method that enables building Loop without a Mac computer or Xcode

Finder\u00a0 (Finder): graphical folder and file display on Mac

fork\u00a0 (fork): a copy of code in a github repository other than the original

GBPA\u00a0 (GBPA): Glucose Based Partial Application: modification to Automatic Bolus Dosing Strategy

GIF\u00a0 (GIF): Graphics Interchange Format (GIF) can be used for small animations and low-resolution video clips

git\u00a0 (git): a tool for version control

GitHub\u00a0 (GitHub): an online service for storing repositories, accessible from a browser

github.com\u00a0 (github.com): an online service for storing repositories, accessible from a browser

GitHub Personal Access Token\u00a0 (GitHub Personal Access Token): used to enable Browser Build of Loop

Glucose Chart\u00a0 (Glucose Chart): Display of measured and predicted glucose values

Glucose Safety Limit\u00a0 (Glucose Safety Limit): Loop will not suggest insulin delivery when glucose prediction (in next 3 hours) goes below this limit; in Loop 2 this was called Suspend Threshold

GMT\u00a0 (GMT): Greenwich Mean Time is mean (average) solar time at 0 degrees longitude, see UTC

Guardrails\u00a0 (Guardrails): limits in the code for user selected settings, recommended and absolute limits are provided

Hamburger Menu\u00a0 (Hamburger Menu): three parallel lines that, when tapped, open a new menu

HUD\u00a0 (HUD): Heads-Up Display at top of Loop main screen, phone in portrait mode

ICE\u00a0 (ICE): Insulin Counteraction Effect - Loop models the expected glucose change based on carbs entered, absorption time and your settings; and adjusts based on measured glucose

Identifiers\u00a0 (Identifiers): names of modules found on your Apple Developer Identifiers page that are required for GitHub build method

IOB\u00a0 (IOB): Insulin on Board, affects automated insulin delivery: the current active insulin (above or below the basal rate) that Loop calculates and uses for glucose prediction

iOS\u00a0 (iOS): operating system used by Apple Mobile devices (iPhone, iPod, iPad)

IRC\u00a0 (IRC): Integral Retrospective Correction: Optional alternative to Retrospective Correction that integrates glucose deviations over a longer time frame

ISF\u00a0 (ISF): Insulin Sensitivity Factor; how many points your blood sugar will drop for each unit of insulin; sometimes called Correction Factor

Issue\u00a0 (Issue): On github - a formal method to report a problem, either code behavior or documentation

JSON\u00a0 (JSON): JavaScript Object Notation; a standard data interchange format that is text-based and human readable

macOS\u00a0 (macOS): operating system for Mac computer

Lock your Phone\u00a0 (Lock your Phone): click the button on the side of the phone to lock it - prevent accidental touch, i.e., accidental Loop command

Loop 3\u00a0 (Loop 3): Latest release with major updates

Loop Cycle\u00a0 (Loop Cycle): typically 5 minutes: new CGM reading, prediction update, pump update and, if in Closed Loop, dosing update if needed

Loop Caregiver\u00a0 (Loop Caregiver): An app you can build to provide remote commands to Loop using Nightscout

Loop Follow\u00a0 (Loop Follow): An app you can build to provide extra alarms and views of important information - can use Dexcom Share or Nightscout to include Loop information

Loop\u00a0 (Loop): With a capital L, Loop is one of several do-it-yourself artifical pancreas systems

Match-Secrets\u00a0 (Match-Secrets): a private repository you must create in your github account, stores keys required to build with github Build Actions

MTB\u00a0 (MTB): Manual Temp Basal: user initiated temporary basal, Omnipod Common feature

MDT\u00a0 (MDT): common abbreviation for Medtronic pumps

modal\u00a0 (modal): message or alert appearing in front of app that must be acknowledged to return to app

Modules\u00a0 (Modules): the Loop code uses a number of modules to handle different components of the entire app

Monterey\u00a0 (Monterey): operating system for Mac, macOS 12.x

Nightscout\u00a0 (Nightscout): a personal website used to view your glucose and diabetes management data, Loop can upload to Nightscout

Onboarding\u00a0 (Onboarding): familiarize new, and existing, Loop users with settings in Loop 3 and ensure the Therapy Settings are all entered and are within safety guardrails

Omnipod\u00a0 (Omnipod): Insulet tubeless insulin pump; Loop supports Eros (with RileyLink) and DASH. Eros is also known as Classic, UST400, and System.

OrangeLink\u00a0 (OrangeLink): radio-frequency device Loop uses to control Eros pods (aka. Gen 3) and older Medtronic pumps

OTP\u00a0 (OTP): one-time password, this is used to enable caregivers to securely execute remote commands to a Looper's phone

Override\u00a0 (Override): a modification to Loop settings that can change the correction range, the sensitivity (basal, ISF and CR) or both

Package Dependencies\u00a0 (Package Dependencies): packages that must be downloaded by Xcode (once) to build the app after downloading the LoopWorkspace to your computer

pill\u00a0 (pill): on Nightscout, small boxes with information, tap for extra details

PR\u00a0 (PR): Pull Request - a formal method to request changes to a repository

prebolus\u00a0 (prebolus): take some or all of a meal bolus before eating

Pre-Meal Range\u00a0 (Pre-Meal Range): modify the correction range for up to one hour by tapping on an icon in the toolbar

Provisioning Profile\u00a0 (Provisioning Profile): associates your app with your Developer ID and limits app lifetime to 1 year (paid) or 1 week (free)

Pull Request\u00a0 (Pull Request): formal method to request changes to a repository

QR\u00a0 (QR): a machine-readable code consisting of an array of black and white squares

Quit the Loop App\u00a0 (Quit the Loop App): quit out of the app - different from closing the app - typically you swipe up in the app switcher

repository\u00a0 (repository): contains project files and each file's revision history

RileyLink\u00a0 (RileyLink): radio-frequency device Loop uses to control Eros pods (aka. Gen 3) and older Medtronic pumps

RC\u00a0 (RC): Retrospective Correction: part of the Loop model that considers actual glucose compared to earlier predictions

SAGE\u00a0 (SAGE): sensor age on Nightscout site

Secrets\u00a0 (Secrets): a method to securely embed personal information into your fork of LoopWorkspace to enable GitHub to have access required to build Loop

TEAMID\u00a0 (TEAMID): One of 6 Secrets: Apple Developer account member number

FASTLANE_ISSUER_ID\u00a0 (FASTLANE_ISSUER_ID): One of 6 Secrets: the issuer ID is associated with your Apple Developer ID and never changes

FASTLANE_KEY_ID\u00a0 (FASTLANE_KEY_ID): One of 6 Secrets: Key ID provided when you create an API key in App Store Connect; it is associated with the FASTLANE_KEY

FASTLANE_KEY\u00a0 (FASTLANE_KEY): One of 6 Secrets: Really long key (several lines); it and FASTLANE_KEY_ID are generated together

GH_PAT\u00a0 (GH_PAT): One of 6 Secrets: Generated with your GitHub account; set it to never expire

MATCH_PASSWORD\u00a0 (MATCH_PASSWORD): One of 6 Secrets: password you make up but must save and cannot change without deleting the Match-Secrets repository

SHA-1\u00a0 (SHA-1): Secure Hash Algorithm 1; used to generate an alphanumeric code for commits in git (github)

Sign Targets\u00a0 (Sign Targets): associate a Developer ID with an app; must sign all targets for a given app

submodules\u00a0 (submodules): for Loop, submodules are repositories defined in the Workspace repository that are required to build the app

Table of Contents\u00a0 (Table of Contents): (TOC) is the list of level 2 and 3 headers on a given page; the title at the top of the page is a level 1 header

Temp Basal Only\u00a0 (Temp Basal Only): provide the recommended insulin automatically using an increase in temp basal over half an hour (limited by max temp basal)

Temp Basal\u00a0 (Temp Basal): modify the scheduled basal rate for a pump

Terminal\u00a0 (Terminal): interface for entering commands to the computer

TestFlight\u00a0 (TestFlight): a method to distribute apps without direct connection

Therapy Settings\u00a0 (Therapy Settings): Basal Rates, ISF, CR, correction and safety ranges and delivery limits

Tokens\u00a0 (Tokens): on Nightscout, configure access permissions using tokens

Tooltip\u00a0 (Tooltip): brief definitions provided for important terms and abbreviations on the website

URL\u00a0 (URL): website address (Uniform Resource Locator)

UTC\u00a0 (UTC): Coordinated Universal Time is a time standard for civil time and time zones worldwide

Ventura\u00a0 (Ventura): operating system for Mac, macOS 13.x

watchOS\u00a0 (watchOS): Apple watch operating system; must be compatible with phone iOS

workflow\u00a0 (workflow): a set of instructions to GitHub to perform an action; the instruction files are found in the .github/workflows folder of the repository

Workspace\u00a0 (Workspace): a grouping of several repositories into a complete package

Xcode Preferences\u00a0 (Xcode Preferences): older name for Xcode Settings

Xcode Settings\u00a0 (Xcode Settings): as of Xcode 14, Xcode menu uses Settings instead of Preferences

Xcode\u00a0 (Xcode): program used to build an app

"},{"location":"faqs/loop-faqs/","title":"Loop FAQs","text":""},{"location":"faqs/loop-faqs/#what-do-i-need-to-loop","title":"What do I need to Loop?","text":"

Please click on the Requirements link.

"},{"location":"faqs/loop-faqs/#can-i-download-the-loop-app-from-the-app-store","title":"Can I download the Loop app from the App store?","text":"

No. The Loop app is not available for download. You must build your own Loop app. The Loop app app will not be available in the Apple App store because that would be distribution of a medical device, and we are not in that \"business\". You can build yourself, but we are not distributors.

Each step needed to successfully build your Loop app is found in these docs. The harder part will be having the patience to read all the documents before you start. New Loop users are so excited to get started that they often skip reading all the great info that these docs contain. As you begin the build...please include time to read the documents that follow what happens after you successfully build your Loop app.

If you have any questions, use the Search feature to find topics in LoopDocs.

"},{"location":"faqs/loop-faqs/#can-i-use-an-android-phone-or-ipad-for-loop","title":"Can I use an android phone or iPad for Loop?","text":"

Loop requires an Apple device. Older iPads do not support Apple Health which is required for Loop. It may be possible with newer iPads and newer iOS, but this has not been tested.

There is open source software that runs on Android phones. Check out AndroidAPS Documention.

"},{"location":"faqs/loop-faqs/#do-i-have-to-be-tech-smart-to-build-loop","title":"Do I have to be \"tech-smart\" to build Loop?","text":"

No. You do not need any experience in code or computers to build Loop. If you already own a computer or tablet and an iPhone, you already have the required level of experience. Beyond that, simply read the directions slowly and diligently...all the information you will need are in these documents.

Often times the non-tech people do better than the tech people in building Loop. Why? Because the non-tech people take the time to read slowly and look at the screenshots in the directions. The tech people often skim and miss steps...which then leads to build errors that have to be retraced and fixed.

"},{"location":"faqs/loop-faqs/#is-there-a-cheat-sheet-for-a-school-nurse-to-use","title":"Is there a cheat sheet for a school nurse to use?","text":"

Sure, you can give this one a try. School nurse's cheat sheet download

"},{"location":"faqs/loop-faqs/#how-long-does-it-take-to-build-loop","title":"How long does it take to build Loop?","text":"

The answer is varied, but a few hours from start to finish, depending on where you are starting and how comfortable you are with your computer.

Start at the Requirements Overview to decide which build method you wish to use. Each method starts with an overview page.

Once you choose your method, you can break the required steps into shorter bits of effort.

"},{"location":"faqs/loop-faqs/#does-the-loop-app-cost-money","title":"Does the Loop app cost money?","text":"

Yes, there are some costs, beyond the obvious costs of owning a pump and CGM.

There are no other costs, ongoing or initial, to use the Loop app beyond what you already pay for your CGM, pump supplies and insulin.

"},{"location":"faqs/loop-faqs/#rileylink-options","title":"RileyLink Options","text":"

This is not required for DASH users.

There are several options for RileyLink Compatible Devices at this time. They typically cost around $150. This is a one-time cost and the devices should last for years (unless it goes swimming, goes through the wash, gets run over by a car, etc.). It's fine to buy one device and make sure you want to Loop, but if you can afford it, go on and get two or get two different kinds. Once you Loop, you'll want a backup.

Many used devices are available in the community. You may find posts for resale on this Facebook Group Looping in a time of covid. This is a private FB group where you must agree to the rules.

Posts offering to buy or sell items in the support FB groups like The Looped Group, Loop and Learn or Little Loopers will be immediately taken down, or you will be directed to the appropriate location and comments will be turned off. FB can shut down groups without warning if they detect sales and the support groups are too important to risk.

"},{"location":"faqs/loop-faqs/#free-developer-account-options","title":"Free Developer Account Options","text":"

The Apple Developer License can be done for free, however, you will have to rebuild your Loop app every 7 days and you must use a computer with Xcode, Build with Mac. That could get very tedious. The $99 annual Apple Developer program enrollment is an excellent investment.

"},{"location":"faqs/loop-faqs/#do-i-need-to-own-my-own-apple-computer","title":"Do I need to own my own Apple computer?","text":"

You no longer need to own an Apple computer - see Build with Browser.

If you chose Build with Mac, then you still don't have to own an Apple computer, but you do need to at least borrow one - or you can build using a virtual Mac if you have a PC with Intel chips (see next section).

If you are borrowing an Apple computer, look at the required minimum settings associated with your iPhone Compatible Computer and Xcode Version. It would be really good to have the longer-term ability to borrow that computer again for updating Loop later when needed.

"},{"location":"faqs/loop-faqs/#can-i-use-a-pc-or-windows-computer-to-build","title":"Can I use a PC or Windows computer to build?","text":"

You can build the Loop app using just a browser on any device: Build with Browser.

If you want to use Build with Mac, there is a hacked way of installing macOS on a Windows computer called a Virtual Machine. This link provides some helpful information. This Virtual Machine method will not work on PCs that have AMD processors, only Intel. Double-check that your computer uses an Intel processor before attempting the virtual machine method. If you want to try this, there are mentors on The Looped Facebook Group who can assist.

"},{"location":"faqs/loop-faqs/#how-often-do-i-need-to-get-on-the-computer-for-loop","title":"How often do I need to get on the computer for Loop?","text":"

When you use the Browser Build method, you need to access a browser at least once every 90 days to Update with Browser. This is simple enough to do that you can do the steps on your phone in just a few minutes. Several people are already working on automated methods so that won't be required, but a manual Build Actions step is required for now.

When you use Build with Mac: the short answer is (1) when you first build and (2) once per year minimum after that. (If you decide to use a free Apple Developer Account, you will need to get on the computer every 7 days.)

Loop code is updated periodically to include new features and bug fixes. When those updates are released, you'll need access to a browser or an Apple computer again to update your Loop app.

Loop updates are not available through the iPhone's app store...instead you do the app update yourself

In general, there are updates to the Loop app released a few times a year - these can occur more frequently after a major release.

"},{"location":"faqs/loop-faqs/#will-i-need-to-build-a-new-loop-app-if-i-switch-between-medtronic-and-omnipod","title":"Will I need to build a new Loop app if I switch between Medtronic and Omnipod?","text":"

No. The Loop app lets you move between different pump types from within the same Loop app. See Change Pump Type.

"},{"location":"faqs/loop-faqs/#can-i-use-my-apple-developer-account-to-build-for-others","title":"Can I use my Apple Developer account to build for others?","text":"

If there is more than one Looper in the family, you only need to have one Apple Developer ID and only one annual payment. The developer must be an adult.

It's a good idea to let someone else in the family know how to build and have access to your Apple password (and for Browser Build, your GitHub password) in case you're out of town. It's also a good idea to build the Loop app on a backup phone especially for travel.

The Apple Developer ID and the Apple ID are two different things. PLEASE read this: Loopers Need Their Own Apple ID.

"},{"location":"faqs/loop-faqs/#what-happens-when-i-switch-apple-developer-id","title":"What happens when I switch Apple Developer ID?","text":"

The Loop app on the phone is different if the build uses a different Apple Developer ID from the one currently on the phone. So if the Apple Developer ID used for a new Loop build is different from the one used for the existing Loop app, there will be two Loop apps on the phone. The Looper will have to on-board the new app, enter all the settings again and delete the old app.

"},{"location":"faqs/loop-faqs/#can-i-use-someone-elses-apple-developer-account","title":"Can I use someone else's Apple Developer account?","text":"

It's best that you build your own Loop app using your own Apple Developer ID.

One developer account can only be \"linked\" to a limited number of devices. So one person \"loaning out\" their developer license to a lot of people will quickly exceed the number of allowed devices. In those cases, that person will be told they need to revoke the certificates on some devices (essentially dropping old ones to make room for new ones). If they revoke your device certificate (and they can do that without you knowing through their developer portal), your Loop app will immediately stop working and not even open.

Your Loop app will also die immediately if their developer account is not renewed or expires.

Moral of the story, out of all the ways to save money...borrowing someone's developer account is not a good place to save money. You don't want your Loop app to suddenly stop working.

"},{"location":"faqs/loop-faqs/#how-can-i-find-a-compatible-pump-supplies","title":"How can I find a compatible pump? supplies?","text":"

You can use Omnipod DASH and Eros pumps with the Loop app. You do not need the Omnipod Personal Diabetes Manager (PDM), just the pod supplies. Your insurance or pharmacy coverage may cover some of the cost. See Which pods work with the Loop app? for more details.

There is a whole page with detailed information about Medtronic pumps; how to find them, how to find supplies, and assessing whether your Medtronic pump is compatible. Please check out that page for more info.

Some Looping equipment can be found on this Facebook Group Looping in a time of covid. This is a private FB group where you must agree to the rules.

"},{"location":"faqs/loop-faqs/#can-i-pay-someone-else-to-do-build-the-app-for-me","title":"Can I pay someone else to do build the app for me?","text":"

We do not know whether someone who builds the app for you incurs legal responsibility if something goes wrong while you are using a version they built for you.

There are a few companies that provide the Loop app as a service.

Best Practice: Learn to Build

You are strongly encouraged to build the Loop app for yourself.

"},{"location":"faqs/loop-faqs/#what-if-i-lose-my-rileylink-compatible-device","title":"What if I lose my RileyLink Compatible Device?","text":"

For Medtronic users, you simply go back to old school pump use until you get a new RileyLink compatible device. You can either let your temp basal finish by itself (30 minutes or less) or cancel the temp basal on the pump's menu. For bolusing, you'd go back to using the pump's bolus commands. When you get a device (either finding your old one or getting your backup device out) and the Loop app running again, you'll want to do one thing. Enter in any carbs to the Loop app that you may have eaten in the recent past that could still be affecting blood glucose. While the Loop app will read whatever insulin deliveries had happened while the RileyLink compatible device was missing, it will not read any carbs you entered into the pump...so make sure to add those to the Loop app and backdate them to the time they were eaten. That will help make the transition back to closed loop smoother.

For Pod users, your Pod will finish any currently running temporary basal rate (maximum of 30 minutes) and then revert back to your scheduled basal rate. Without a RileyLink compatible device, you will be receiving normal basals, but will need to pull out pens/syringe for boluses. If you have a backup device, you can simply connect to the new device on the same Loop app and it will work with the existing pod session. If you don't have a backup device, you'll have to remove the pod and start a new pod paired with your PDM until you get a new device.

"},{"location":"faqs/loop-faqs/#what-if-i-lose-or-get-a-new-iphone","title":"What if I lose or get a new iPhone?","text":"

If you lose your phone - follow the same dosing protocol as if you lost your rileylink.

When you get a new iPhone, you can plan ahead. There's a whole FAQs page about transferring your Loop information to a new phone. New Phone.

"},{"location":"faqs/loop-faqs/#what-about-other-pumps-when-will-they-loop","title":"What about other pumps? When will they Loop?","text":"

Hey now...let's be grateful for what we have first. The ability to use the Loop app is the result of tremendous amounts of effort, time, and sacrifice by volunteers. Cracking the pumps for the Loop app use is a large undertaking. If and when another set of people spend a large amount of time figuring out other pumps, then they could conceivably be added to Loop. But you don't need to let us know that you'd love to see more pumps compatible with Loop. There is just an awful lot of work that needs to happen and it is neither quick nor easy.

"},{"location":"faqs/loop-faqs/#can-i-have-more-than-one-loop-app-on-a-phone","title":"Can I have more than one Loop app on a phone?","text":"

Yes, this is technically possible. You can have multiple Loop apps built onto the same iPhone. However, having multiple Loop apps on a single phone may lead to unexpected conflicts that can negatively affect your Loop's ability to stay green (keep looping). Additionally, your Pod will only work on one Loop app at a time anyways. So for smooth looping, just keep one Loop app on any phone for looping use.

"},{"location":"faqs/loop-faqs/#will-i-be-able-to-the-loop-app-on-a-plane-or-in-the-mountains","title":"Will I be able to the Loop app on a plane? Or in the mountains?","text":"

Yes. The Loop app does not require internet or cell coverage to work. So long as the Loop user has Bluetooth enabled on the iPhone, then the CGM and DASH pod (or RileyLink for Eros or Medtronic pumps) will still be able to do their work with the Loop app and your pump/Pod.

One exception - if you've chosen to use a CGM source that does require the internet, you will need to have cell or internet coverage. This ability is provided as a service to folks who cannot get their CGM data any other way. It is also a convenience for people testing the code.

"},{"location":"faqs/loop-faqs/#what-happened-to-freeaps","title":"What happened to FreeAPS?","text":"

FreeAPS hasn't really had an owner to develop it for several years, but many depended on it. Because of that, the Loop and Learn team kept it on life-support. It was updated in early 2023 to include DASH, but that was the last improvement. It is strongly recommended people switch to Loop 3 or iAPS. Do not use an application without an owner.

Many features people used with FreeAPS are now included in Loop 3 or can be added with customization. The dev branch has Libre support, see Build Loop Dev.

The addition of customizations has been simplified.

Please do not blindly apply customizations. First read the documentation provided at the links above carefully.

"},{"location":"faqs/new-phone/","title":"New Phone Tips","text":""},{"location":"faqs/new-phone/#overview","title":"Overview","text":"

Time Estimate

At least a few hours.

You can choose to keep Looping on the old phone and swap later. Most vendors give you more than a week to turn in your old device for credit.

Phone Transition Overview - Detailed steps below

Don't start right before a meal:

Keep your old phone (if you can, connected to WiFi) and use it for the Loop app:

Two methods to transfer your phone information (plan for 1 hour, may be faster):

  1. Do direct phone-to-phone transfer
    • You will not be able to use your old or new phone during the transfer
    • Both phones need to stay close to each other and on the same WiFi network
  2. Use iCloud backup from old phone to transfer information to the new phone
    • You will not be able to use your new phone during the transfer

What happens after you transfer your phone information:

When ready to start using the new phone to control your app:

Plan to stay in Open Loop until all Glucose, Insulin and Carbohydrate Apple Health records transfer:

Plan Ahead

"},{"location":"faqs/new-phone/#steps-required","title":"Steps Required","text":"

Changing phones means you have to rebuild the Loop app onto the new phone. When you transfer information from your old phone to your new one, all your\u00a0Loop\u00a0information is included and the\u00a0Loop\u00a0icon will appear, but the app will not open until you install\u00a0Loop\u00a0from either TestFlight or Mac with Xcode.

The records on the new phone are from the time you started the transfer from the old phone to the new phone. The more recent records are transferred via Apple Health. You may want to adjust carbs after the transfer because those are not read by the Loop app. But if you enter them again and you are uploading to Nightscout or Tidepool - they will show up twice. Best to have COB and IOB close to zero when you start using your new phone.

Some people don't have access to their old phone. There are instructions for handling that on this page. It makes the whole process more stressful, but remember, pods continue to deliver basal rate and Medtronic pumps can be controlled on the pump itself. Use your backup plan until you can get\u00a0Loop\u00a0running on a new phone.

"},{"location":"faqs/new-phone/#forced-ios-update","title":"Forced iOS Update","text":"

When you change phones, Apple will force you to the latest iOS version available for your new phone.

"},{"location":"faqs/new-phone/#prepare-before-upgrade","title":"Prepare Before Upgrade","text":"

If you are using Dexcom, record the transmitter or sensor number in case it doesn't transfer

If you still have your old phone, you can prepare before switching to the new phone.

If you don't have your old phone, hopefully you have an iCloud backup and can use that to transfer your information to your new phone.

Keep the Old Phone Until the Loop app is Working on the New One

Even if you plan to turn your old phone in for a rebate, you can ask to keep the old one for a week or two. Most vendors will agree to this.

Update your old phone to the latest iOS the hardware supports - this simplifies the automatic transfer process Apple provides to move all your data and apps from your old phone to your new phone.

New Phone Checklist for Build with Browser

New Phone Checklist for Build with Mac

"},{"location":"faqs/new-phone/#different-developer-id","title":"Different Developer ID","text":"

Different Developer ID

If you need to build the Loop app with a different developer ID on the new phone, the settings and pump information will not transfer.

"},{"location":"faqs/new-phone/#procure-a-new-phone","title":"Procure a New Phone","text":"
  1. Procure the new phone and keep the old one (if possible)
    • Use the Old Phone until it is convenient to switch to the new phone
  2. Transfer your information to your new phone. Your options are:
    1. Use both devices with Quick Start to transfer from the old to the new phone
    2. Use an iCloud back-up for the transfer
    3. Let the new phone vendor help you
"},{"location":"faqs/new-phone/#use-the-old-phone-until-ready","title":"Use the Old Phone until Ready","text":"

If you cannot keep the old phone, or it is not available, then skip ahead to the Use the New Phone.

"},{"location":"faqs/new-phone/#use-the-new-phone","title":"Use the New Phone","text":""},{"location":"faqs/new-phone/#install-the-loop-app","title":"Install the Loop App","text":"

It is easier if you transfer information from the old phone to the new phone before you install and open\u00a0Loop\u00a0on the new phone. If this is not possible, then you will do the normal Onboarding for a new\u00a0Loop\u00a0app.

  1. When you transfer information from your old phone to your new phone, all the\u00a0Loop\u00a0settings files get copied to the new device including information about the pod
    • If the timing works, you can keep the pod when you switch to using the new phone for\u00a0Loop\u00a0after the information transfer and before changing pods with the old phone
    • If this is not possible, you will need to start a new pod with the new phone
    • Medtronic users will have all their information transferred but will only have one phone connected to the RileyLink
  2. Install\u00a0Loop\u00a0on the new phone (all your settings should be there)
    • Install from TestFlightor
    • Build using Mac
  3. As soon as you install the Loop app on the new phone, go ahead and disable Closed Loop.
    • Keep Closed Loop disabled until you complete the full transfer and checkout.
"},{"location":"faqs/new-phone/#install-from-testflight","title":"Install from TestFlight","text":""},{"location":"faqs/new-phone/#build-using-mac","title":"Build using Mac","text":"

Preparatory steps:

When building:

If you have trouble finding the new phone in Xcode or trouble building, you should try to reboot phone, watch, quit Xcode, restart computer, delete old provisioning profiles and then ask for help

"},{"location":"faqs/new-phone/#prepare-to-change-phone-used-for-the-loop-app","title":"Prepare to Change Phone used for the Loop App","text":"

On old phone (if available):

  1. Loop\u00a0app, turn off the slider for the RileyLink if using Medtronic or Eros Pods
    • Do not delete the pump; if using pods, this cannot be reversed
  2. Phone Settings, Bluetooth
    • Forget the connections to the CGM (Dexcom or Libre)
    • Do not forget anything that says TWI_BOARD or NXP_BLE(this is your DASH* pod)
  3. Phone Settings, Bluetooth: Disable Bluetooth
"},{"location":"faqs/new-phone/#transfer-pump","title":"Transfer Pump","text":"

Bluetooth must be off on the old phone.

"},{"location":"faqs/new-phone/#transfer-cgm","title":"Transfer CGM","text":"

It is now time to transfer the CGM to the new phone.

"},{"location":"faqs/new-phone/#dexcom-cgm","title":"Dexcom CGM","text":"

The Dexcom app might have transferred successfully, but it\u2019s not a bad idea to install that fresh from the App Store on the new phone. Doing so may be required.

"},{"location":"faqs/new-phone/#librecgm","title":"Libre CGM","text":"

Placeholder for\u00a0Libre CGM instructions. Suggested procedures from the community are encouraged.

"},{"location":"faqs/new-phone/#check-out-the-transfer","title":"Check out the Transfer","text":"

  1. Stay in Open Loop (closed loop disabled) until you complete the full transfer and checkout.

    Check Every Setting

    • Make sure all the basal, ISF, CR, Insulin Selection and ranges are correct
    • Check Dosing Strategy selection
    • Check permissions and notification settings
    • Check Focus mode settings - make sure\u00a0Loop\u00a0and CGM apps have permission for all Focus modes

  2. Do a manual bolus of the smallest possible amount to make sure\u00a0Loop\u00a0and pump are working.

  3. Monitor CGM values to ensure new readings are coming in.

  4. Check Glucose, Insulin and Carbohydrate records

    Apple Health\u00a0History

    Your Glucose, IOB and COB may not have correct history on your new phone.

    Loop\u00a0 reads from\u00a0Apple Health\u00a0and will restore Glucose and Insulin records if health is stored on iCloud and synchronized between old and new phone - but this can take a long time to synchronize

    The Loop app does not read Carbohydrates from Apple Health, so stay Open Loop if you have high COB from an entry on the old phone

    Be prepared to spend 3 to 6 hours in Open Loop.

  5. Once you are happy with the configuration of\u00a0Loop\u00a0on your new phone, your glucose is being read and your COB and IOB on the new phone is valid, then you can restore Closed Loop.

"},{"location":"faqs/new-phone/#old-phone","title":"Old Phone","text":"

Once you are using\u00a0Loop\u00a0on your new phone, you can delete the pump from the old phone.

You can either keep the Old Phone as a backup, reset it and turn it in for credit or give it to some deserving individual.

"},{"location":"faqs/omnipod-faqs/","title":"Omnipod FAQs","text":""},{"location":"faqs/omnipod-faqs/#which-pods-work-with-the-loop-app","title":"Which pods work with the Loop app?","text":"

You can use DASH and Eros Omnipod pods with the Loop app. You cannot use Omnipod 5 pods.

You do not need the Omnipod Personal Diabetes Manager (PDM), just the pod supplies. Your insurance or pharmacy coverage may cover some of the cost.

Alternative Names for Omnipod Pods

All three types of pods can be packaged five to a box, don't let the 5-pack indication confuse you.

DASH pumps communicate with the phone via Bluetooth so they do not require a RileyLink compatible device.

"},{"location":"faqs/omnipod-faqs/#what-about-tidepool-loop","title":"What about Tidepool Loop?","text":"

Tidepool Loop was approved by the FDA in Jan 2023, but at the current time, there are no announced pump or CGM partners. What does this mean?

Tidepool Loop, cleared by the FDA, is the first:

With this approval, there is now an FDA-approved pathway for independent selection of an app, a pump, and a CGM. Stay tuned for updates at https://tidepool.org/tidepool-loop.

"},{"location":"faqs/omnipod-faqs/#do-i-still-need-a-pdm-with-omnipod-loop","title":"Do I still need a PDM with Omnipod Loop?","text":"

No, pods are monogamous little creatures. They will pair with only one device at a time for safety reasons...so a pod is either paired with a PDM or your Loop app on your iPhone. In other words, your PDM can stay in the diabetes closet while you are Looping. You cannot use the PDM for a pod that has been activated with the Loop app. That doesn't mean you should get rid of your PDM if you have one. Instead, keep it for backup situations if you lose your phone. See below for what to do if you lose your phone or RileyLink.

"},{"location":"faqs/omnipod-faqs/#can-i-cancel-a-bolus","title":"Can I cancel a bolus?","text":"

Yes, you can cancel a bolus in progress. In fact, because it is very easy to cancel, make sure your phone is locked prior to being put away to avoid inadvertently cancelling a bolus. (This behavior is very similar to the Insulet PDM - which also needs to be locked once a bolus has started.)

As soon as a bolus is initiated, look at your phone in portrait orientation. You will see a bolus message indicating the progress of the bolus. This message is highlighted with a red rectangle in the graphic below. If you tap on this part of the display, the bolus is immediately cancelled.

"},{"location":"faqs/omnipod-faqs/#can-i-cancel-a-temp-basal","title":"Can I cancel a temp basal?","text":""},{"location":"faqs/omnipod-faqs/#cancel-temp-basal-with-the-loop-app","title":"Cancel Temp Basal with the Loop app","text":"

With Loop 3, disabling the setting for Closed-Loop immediately restores the basal rate on the pump to the scheduled basal rate, which effectively cancels the temp basal.

You can tap on disable Closed-Loop and then immediately tap on enable Closed-Loop if all you want to do is cancel the current temp basal. If you do restore Closed-Loop, then Loop will resume automatic insulin delivery adjustments within 5 minutes.

Bolus in progress

Even if a bolus is in progress, you can still switch to Open-Loop and restore scheduled basal. The current bolus continues unless you separately cancel the bolus.

"},{"location":"faqs/omnipod-faqs/#cancel-temp-basal-with-loop-v22x","title":"Cancel Temp Basal with Loop v2.2.x","text":"

If you are running Loop v2.2.x, the method for canceling a temp basal is to suspend the pump and then resume delivery. This also interrupts any bolus that might be in progress.

Be sure to follow the suspend with the resume command. Otherwise, all insulin delivery is stopped and remains stopped until the user either clicks on the \"Tap to Resume\" command from the main screen or the \"resume delivery\" command accessed in the pump settings display. The resume insulin delivery command returns insulin delivery to your scheduled basal rate.

If a bolus was interrupted, the bolus will not resume.

As long as you are in closed-loop mode, the Loop app will resume automatic insulin delivery adjustments within 5 minutes.

"},{"location":"faqs/omnipod-faqs/#can-i-set-my-own-temp-basal-on-loop","title":"Can I set my own temp basal on Loop?","text":"

With version 3, the Loop app provides a Manual Temp Basal feature.

"},{"location":"faqs/omnipod-faqs/#what-if-i-lose-my-phone-or-rileylink","title":"What if I lose my phone or RileyLink?","text":"

For pod users, your pod will finish any currently running temporary basal rate and then revert back to your scheduled basal rate. Without a phone or RileyLink, however, you will not be able to affect any pod use; no basal change, suspend, cancel, or bolus. To do anything other than let basals continue, you will need to take action depending on the situation.

"},{"location":"faqs/omnipod-faqs/#is-there-an-increase-in-pod-failures-on-loop","title":"Is there an increase in pod failures on Loop?","text":"

There is more communication between the pod and the controller (your Loop phone) than is typical with the PDM (Insulet provided controller). This increases the load on the pod battery. Most people have no increase in pod failures, but there are steps to take to limit \"extra pod battery use\". Every time the Loop app requests an update of the pod state or issues a command (bolus, basal schedule, temp basal), messages are exchanged with the pod.

"},{"location":"faqs/omnipod-faqs/#what-do-i-do-if-a-pod-fails-to-pair","title":"What do I do if a pod fails to pair?","text":"

If you get a pod that is failing to pair, please see this page for steps on how to fix the problem. Follow these steps before filling and trying another pod. If the pod is not screaming, you can probably recover it.

"},{"location":"faqs/omnipod-faqs/#what-do-you-do-to-stop-a-screaming-pod","title":"What do you do to stop a screaming pod?","text":"

Screaming pods indicate the pod is out of insulin or out of time (80 hours) or there has been a critical pod fault. In all these cases, there is no more delivery of insulin.

The first step is to use your phone to Deactivate the pod. You may need to go to the pod settings and tap on the Replace Pod row or the app may take you to the screen with a Deactivate button directly. This only works if the app is able to communicate with the pod. Sometimes this is not possible. After you attempt to deactivate two times, the app will \"discard\" the pod as active if communication fails and enable you to pair a new pod. But you still need to make that noise go away.

If you are not successful at deactivating a pod and you've tried the steps at Reset-Loop-to-Pump-Communications, make sure the old pod is removed from the area before trying to connect a new pod. (Placing it in a microwave temporarily prevents the phone from detecting that pod.) The paperclip trick (next paragraph) only breaks the sound connection, the pod electronics is still active.

Once you have removed the screaming pod, it can be silenced using a paperclip. Simply put the paperclip in the small hole that is on the bottom (the side opposite where the cannula is) of the pod as shown. Push the paperclip in until you hear a little click, that click is breaking the circuit that connects the speaker to the electronics.

"},{"location":"faqs/overview-faqs/","title":"FAQs Overview","text":""},{"location":"faqs/overview-faqs/#frequently-asked-questions-faqs-overview","title":"Frequently Asked Questions (FAQs) Overview","text":"

The FAQs tab of LoopDocs contains pages with safety tips, frequently asked questions and the Glossary.

Map to this section:

"},{"location":"faqs/rileylink-faqs/","title":"RileyLink FAQs","text":""},{"location":"faqs/rileylink-faqs/#rileylink-compatible-device-faqs","title":"RileyLink Compatible Device FAQs","text":"

A RileyLink compatible device is required to use the Loop app with Medtronic pumps or Omnipod Eros pods.

A rileylink is not required with DASH pods.

The device uses the RileyLink protocol to communicate information to/from your pump by radio communications and to/from your iPhone using Bluetooth. You will need the device within range of your phone and pump so that these communications can happen. Put it in a purse, pocket, SPIbelt. Clip it to a backpack, belt, or bra...but please do bring it with you..

Purchase information for these devices is found in RileyLink Compatible Devices

"},{"location":"faqs/rileylink-faqs/#adding-or-changing-rileylink","title":"Adding or Changing RileyLink","text":"

You can add or change the RileyLink compatible device in use without affecting the pump that is connected to the Loop app. You can even have more than one connected, although only one will be used at a time.

If you are connecting to a new Medtronic pump or switching between Medtronic and Omnipod, please follow the Modify Pump instructions under Set up App.

Change Connected Devices:

"},{"location":"faqs/rileylink-faqs/#using-more-than-one-device","title":"Using More Than One Device","text":"

You can have more than one RileyLink compatible device turned on and connected. Loop only uses one device at a time. Remember - if you do have two devices in use, make sure they are both charged (or have batteries).

Example of using more than one device:

"},{"location":"faqs/rileylink-faqs/#communications","title":"Communications","text":"

All the RileyLink compatible devices communicate with the pump through radio frequency communications and with the phone through Bluetooth.

Bluetooth (BT) Troubleshooting

If your iPhone has BT issues, your Loop will have failures. There have been reports of BT audio devices (such as BT pairings in your car or home audio BT speakers) interfering with the Loop. If you are finding Loop failures frequently happening at a particular location, you may try to troubleshoot if there are BT problems in the area.

Your BT signal strength can be seen in the Loop settings, Pump settings, Device menu, on the Signal Strength line. As you move closer and further away from your phone, you can watch that number dynamically change. This line is not displaying the signal strength of your pump RF communications, just BT between the RileyLink compatible device and the phone.

You will notice the Signal Strength is a negative number and in units of dB. Remember that number line from elementary school? A signal strength of -50\u00a0dB is a stronger signal than -80\u00a0dB.

"},{"location":"faqs/rileylink-faqs/#range","title":"Range","text":"

The range at which RileyLink compatible devices will function is dependent on the environment that you are in and the specific device design. Both the OrangeLink and some sizes of the EmaLink have reported longer ranges than RileyLink (typically 10 to 20 ft) - but they still need to be \"near enough\".

What influences this distance for a given device? The biggest external influences are (1) body-blocking and (2) \"noisy\" environments. The human body is a lot of water, and water is an excellent blocker of wireless communication. So, sleeping on a pod and smothering it entirely with your body can decrease the ability of the device to communicate with the pod. Environments with a high concentration of wireless signals can also interfere with device communications and make closer proximity a benefit. Where might those kinds of situations happen? Concerts, conferences, and sporting arenas are pretty prone to interference.

Many people keep their device on the same side of their body as their pump during the day. They use a pocket, carabiner, lanyard, SPIbelt - the options are endless. What you don't want to do is put it in a blocking bag that has RFID blocking (some travel fanny packs have that).

"},{"location":"faqs/rileylink-faqs/#what-happens-if-loop-loses-communication","title":"What happens if Loop loses communication?","text":"

While you are out of the communication range for your RileyLink compatible device(s), any running temp basal will keep going until it finishes (the longest temp basal that Loop sets are for 30 minutes duration...so within 30 minutes or less your pump would go back to your regularly scheduled basal). When you come back into range of your device, Loop will pick back up within 5-10 minutes without you needing to do anything.

"},{"location":"faqs/rileylink-faqs/#are-these-devices-waterproof","title":"Are these devices waterproof?","text":"

The electronics are not waterproof but there are waterproof cases available and some have wireless charging available. Check with the manufacturer.

RileyLink Compatible Device Information

"},{"location":"faqs/rileylink-faqs/#firmware-version","title":"Firmware version","text":"

In Loop settings, tap on your pump, find your device (RileyLink or other) and tap on that menu. The figure below shows firmware specific to the RileyLink. If you have another type of device, the firmware value reported will be different. (Note - the displays for Ema, Orange and Riley have been updated to include device-specific features as shown in the RileyLink Display page. The graphic below shows the original RileyLink display.)

With RileyLink, the firmware displayed should match or be a higher version number than what is shown in the figure above, e.g., subg_rfspy 2.2/ble_rfspy 2.0. (If you are running with a very old RileyLink from pre-Aug 2018, it might be a lower number.) Check it when the device is working well and make a note of what it says. If you're having Red Loops, you might want to check firmware and connected state. Make sure, after power cycling your device, that the correct firmware is displayed AND that there are two items shown.

HINT: You might need to quit the Loop app. (Don't just close it, actually quit.) Then do the power cycle on the RileyLink compatible device to attempt to have both sets of firmware boot up. When you restart the Loop app, it may show the correct firmware. Don't give up after one failure, try several times.

If several power cycles do not make the correct firmware show up, contact the manufacturer for assistance.

"},{"location":"faqs/rileylink-faqs/#orangelink-firmware","title":"OrangeLink Firmware","text":"

The OrangeLink devices allow the user to update the firmware on the device using an app on the phone itself (available for iPhone 7 and later devices).

A number of OrangeLink Pro devices were shipped with FW2.6 and for people who already had OrangeLink devices, a version of FW2.6 was offered for download. However, this firmware did not work well with Loop (or AndroidAPS).

Firmware/Hardware Labeling

Earlier versions of the OrangeLink firmware did not put the hardware (HW) version and the firmware version (FW) in the \"correct\" location to hand off to Loop for interpretation. Do not worry if you are running on any FW version 1.x or 2.x and your HW version number doesn't say 1.0 or 1.1. This has been fixed for FW versions 3.x.

"},{"location":"faqs/rileylink-faqs/#emalink-and-orangelink-features","title":"EmaLink and OrangeLink Features","text":"

Some of the features of the OrangeLink were added to the RileyLink Display with Loop 2.2.x. However, as mentioned above, the FW and HW information in some OrangeLink firmware was inconsistent in earlier versions. The consequence is that the OrangeLink Pro screen does not show the Find Device feature that many people want to use with the versions of firmware that provide good communication with Loop. The patch listed below fixes this issue.

The EmaLink features were not added with Loop 2.2.x. The patch listed below adds some EmaLink features.

"},{"location":"faqs/rileylink-faqs/#emalink-and-orangelink-patch","title":"EmaLink and OrangeLink Patch","text":"

A patch was developed to update the RileyLink screen of the Loop app that detects the OrangeLink hardware for all versions of the OrangeLink firmware and adds the battery level reporting and notification to the EmaLink screen. Click on the link below. There are detailed instructions on how to use this patch for Loop 2.2.x.

"},{"location":"faqs/rileylink-faqs/#rileylink-information","title":"RileyLink Information","text":"

Since the RileyLink version of the communication link device has been around the longest, some additional information about that device has been added to LoopDocs throughout the years. The rest of this page is specific just to the RileyLink device.

"},{"location":"faqs/rileylink-faqs/#rileylink-assembly","title":"RileyLink Assembly","text":"

Your RileyLink will come with the Lithium-ion Polymer (LiPo) battery disconnected and the parts not already inside the case. It will be up to you to put the RileyLink in the case and attach the battery.

Make sure the LiPo battery is well-plugged into the connection. Line up the little ridge appropriately, and push fairly firmly to get the connection tight. Poor battery cable connection can make the Loop communications fail. See photos below, for example.

Common new user errors

The most common two errors for new RileyLink owners are (1) not fully pushing in the LiPo battery cable connection and (2) failing to charge the RileyLink. Compare your LiPo battery cable with the photos; it takes a bit of oomph to push that plug fully in like the photos shown below. Remember to charge your RileyLink each night.

Loose battery cable on left. Proper battery cable on right

Finally, the board and the battery fit into the slim case fairly tightly as well. Click on the image below to watch a helpful assembly video.

"},{"location":"faqs/rileylink-faqs/#rileylink-lights","title":"RileyLink Lights","text":"

The RileyLink has several lights that you may notice from time to time. There is no 'power' light. If you suspect that your RileyLink is not being powered, try turning it off and on using the small sliding switch. You should see lights in the middle of the board flash when you do this. If they flash, that means the board has power.

A solid blue light that consistently remains lit on the board could mean one of two things:

If your blue light remains on despite trying a restart, it is time to pull out your backup RileyLink.

"},{"location":"faqs/rileylink-faqs/#rileylink-charging","title":"RileyLink Charging","text":"

The battery that comes with RileyLink is not charged completely when it is shipped, so be sure to charge it up before initial use. RileyLink takes about 2 hours to fully charge (the red light will turn off when fully charged, read note above about red light patterns) and should easily last at least a full day of constant Loop use. Typically, it can go into the 30-hour range without any problems. Most people charge their RileyLink each night when they are sleeping. You don't have to worry about leaving the RileyLink plugged in \"too long\" for charging. It will automatically stop charging the battery when it is fully charged.

Since the best practice is to charge your RileyLink overnight while you sleep, and the battery lasts safely over 24 hours, there is no battery level indicator for the RileyLink. The RileyLink's charge level is not viewable on Nightscout, nor within the Loop app. If you forget to charge your RileyLink overnight, you can recharge it with a portable USB battery in a pinch. A short mini-USB cable could be a good addition to a small gear bag.

"},{"location":"faqs/rileylink-faqs/#what-are-the-differences-between-the-rileylink-medtronic-and-omnipod-antennas","title":"What are the differences between the RileyLink Medtronic and Omnipod Antennas?","text":"

There are two types of antennas for RileyLinks; each antenna is optimized for the pump you are using. Otherwise they are identical. See RileyLink Compatible Devices for other devices. The OrangeLink has both antennas included in its design and can talk to either Medtronic or Omnipod. The EmaLink requires selection for type of pump.

The color of the RileyLink circuit board in the photos below is irrelevant.

"},{"location":"faqs/rileylink-faqs/#what-will-happen-if-your-rileylink-has-the-wrong-antenna","title":"What will happen if your RileyLink has the wrong antenna?","text":"

You can technically use that RileyLink with either pump on Loop. But, you will have significant frustrations and probably a lot of red loops. With mismatched antenna/pump, the device needs to be very close (think inches) and in clear line-of-sight to pump/pod. This makes everyday living (and sleeping) a bit hard. If you use the appropriate-antenna-for-your-pump device, the distances the pump/pod and RileyLink can tolerate from each other is much more \"real world\" friendly and stable. The OrangeLink contains both antennas so will work with either pump. This may be a good choice if you like to switch between Medtronic and Omnipod.

In a pinch, if you have a RileyLink that you used with a Medtronic pump and have switched to Omnipod, it might work as a backup, but you won't love it.

"},{"location":"faqs/rileylink-faqs/#how-long-will-my-rileylink-go-between-charging","title":"How long will my RileyLink go between charging?","text":"

RileyLinks can go about 30-36 hours on a single charge. There is no way to see the remaining charge level, so most people just get into the habit of charging overnight while they sleep. The actual time to fully recharge is about 1 or 2 hours; you'll know it is fully charged when the red light turns off. After a full charge, the red light will turn off and then periodically turn on for short times while it \"tops off\" while still on a charger.

"},{"location":"faqs/rileylink-faqs/#how-can-i-tell-how-much-charge-my-rileylink-has","title":"How can I tell how much charge my RileyLink has?","text":"

You can't. There is no charge level indicator. Just charge it nightly, and you won't have a problem. Full battery charge should last about 30-36 hours depending on battery health. Charging takes less than 2 hours.

"},{"location":"faqs/rileylink-faqs/#how-long-will-my-rileylink-battery-last","title":"How long will my RileyLink battery last?","text":"

Eventually, Lithium-ion Polymer (LiPo) batteries will lose charging capacity. You would want to replace if you notice the battery not lasting the full day. Many people report using their battery for more than 2 years without issue.

Be aware that if a battery is failing, it may swell. If you notice that the RileyLink battery is swollen, remove the swollen battery from your home and place in a fire-safe area and recycle it properly. Either order a new battery or pull out your spare.

After a year of use (and a year of being dropped), the antenna may no longer be securely soldered. If you are getting a lot of red loops, it might be a poor antenna connection instead of a failing battery. Check the solder joint at the antenna. The solder should be shiny and the antenna base should be firmly attached to the board.

"},{"location":"faqs/rileylink-faqs/#rileylink-battery","title":"RileyLink Battery","text":"

Keep your RileyLink and its Lithium-ion Polymer (LiPo) battery protected from damage. LiPo batteries are unsafe when damaged or punctured, so the case is an important part of safe Looping. If your battery is damaged in some way, please disconnect it immediately, and dispose of it (it should be recycled). You can order new RileyLink batteries on the GetRileyLink website

"},{"location":"faqs/rileylink-faqs/#rileylink-battery-removal","title":"RileyLink Battery Removal","text":"

To remove the LiPo battery from the RileyLink, please do so slowly and patiently. Work the battery connection side to side slowly to loosen it from the plug. Some people have reported success using small, curved needle-nose pliers such as hemostats. Others have used small flathead screwdrivers as shown in this video.

"},{"location":"faqs/safety-faqs/","title":"Safety Tips","text":""},{"location":"faqs/safety-faqs/#know-your-settings","title":"Know your settings","text":"

Do not enter settings that you are unsure of. For example, if you haven't any idea what your carb ratio is, please don't enter a wild guess. Instead, test your settings and talk to your health care provider about what your appropriate settings should be.

"},{"location":"faqs/safety-faqs/#ios-focus-notifications","title":"iOS Focus Notifications","text":"

iPhones have Focus modes to enable maximum flexibility for notifications. These modes must be configured by each user to allow important notifications from your diabetes apps.

Set up every Focus mode you use to allow glucose alerts or you will not get them.

Critical notifications, for example, urgent low from Dexcom, are enabled regardless of your Focus settings. But regular low and high glucose notifications might be suppressed. Open source apps, like the Loop app, can only be allowed to notify during a Focus mode when configured by the user.

Under iOS Settings, select Focus, then choose the Focus mode you want to adjust.

The graphic below has numbered highlights to follow along for configuring Sleep focus initially:

  1. Enable Time Sensitive Notifications (disabled by default)
  2. Tap on the + sign to add Apps that are allowed to notify in this mode
  3. Use the search feature to find apps of interest
  4. Tap on the radio button to select apps of interest, the check mark means that app will be added
    • If you use additional apps to provide alerts, be sure to add them to Focus as well

The little clock icon indicates that time-sensitive notifications are enabled. The other icons represent the apps you added to have permission to notify you when in this Focus mode.

Be sure to do this for every Focus mode you use.

"},{"location":"faqs/safety-faqs/#understand-the-app-displays","title":"Understand the App Displays","text":"

If you do not understand the components displayed in the graphic below, please spend time reviewing the information at Displays.

"},{"location":"faqs/safety-faqs/#carb-entry-and-insulin-delivery","title":"Carb Entry and Insulin Delivery","text":"

If you configured the app with closed-loop enabled:

If you entered carbs and then changed your mind on the amount or the time at which they were eaten, use these instructions to delete or edit them. This will make\u00a0Loop\u00a0better able to predict blood glucose and adjust insulin delivery appropriately.

"},{"location":"faqs/safety-faqs/#how-to-cancel-a-bolus","title":"How to Cancel a Bolus","text":"

Once a bolus starts, the progress of that bolus appears in the HUD Status Row. Note that the phone must be held in portrait mode to see this. Simply tap on the row that shows the delivery to halt the bolus.

"},{"location":"faqs/safety-faqs/#understand-delivery-limits","title":"Understand Delivery Limits","text":"

With each cycle, Loop\u00a0generates a glucose prediction and a recommended dose (positive or negative) to bring you to your correction range.

For more information, please read How do Delivery Limits Affect Automatic Dosing?.

"},{"location":"faqs/safety-faqs/#health-app-permissions","title":"Health app permissions","text":"

For older versions of\u00a0Loop, or if you customized\u00a0Loop 3\u00a0to read carbohydrates from third-party apps, be aware that you cannot edit those entries inside the\u00a0Loop\u00a0app.

If you let other apps, such as MyFitnessPal, write carbohydrates to the Health app, Loop\u00a0could read those carbohydrates and you could be dosed for those carbohydrates.

"},{"location":"faqs/safety-faqs/#glucose-prediction-is-scary","title":"Glucose Prediction is Scary","text":"

Users often reach out if the glucose prediction shown on the Loop app screen is very low - negative even.

"},{"location":"faqs/safety-faqs/#scenario-1-extreme-override","title":"Scenario 1: Extreme Override","text":"

It is pretty common for new users to think a 10% override setting should behave similarly to a 10% temporary basal rate setting on a manual pump. This is not true.

Read this section on the override page for information: Avoid Extreme Insulin Needs Setting

"},{"location":"faqs/safety-faqs/#scenario-2-entry-error-into-apple-health","title":"Scenario 2: Entry Error into Apple Health","text":"

With version 3 of the Loop app, it is no longer necessary to enter glucose or insulin manually into the Apple Health app for the Loop app to read. There are methods within the Loop app for entering a fingerstick value or non-pump insulin.

However, some people are used to entering information into Apple Health directly - and it still works. The Loop app will read entries from Apple Health. But if you do this:

A recent user entered a fingerstick value into the insulin record in Apple Health. They use mmol/L glucose units, so it wasn't as obvious as it would have been for someone using mg/dL. At any rate, they could not figure out why their child had such a high IOB and were afraid the pump had delivered 10 U of insulin! Once they deleted the incorrect entry from Apple Health, the Loop app was able to make the appropriate prediction.

"},{"location":"faqs/safety-faqs/#beware-the-medtronic-easy-bolus-button","title":"Beware the Medtronic Easy Bolus button","text":"

Medtronic's easy bolus button has been the cause of several accidental boluses when the pump has been carried in a pocket. Best practice would be to disable the Easy Bolus button since you will be doing boluses from the phone anyways.

"},{"location":"faqs/safety-faqs/#finish-your-medtronic-priming","title":"Finish your Medtronic priming","text":"

After a site change and reservoir rewind, Medtronic's pump will have a menu on the pump screen related to finishing your prime. Make sure you complete that screen and always return to the main menu. Medtronic's pump won't resume basal insulin delivery until that priming screen is completed.

"},{"location":"faqs/time-faqs/","title":"Time FAQs","text":""},{"location":"faqs/time-faqs/#the-loop-phone-must-be-on-automatic-time","title":"The Loop Phone Must be on Automatic Time","text":"

The Loop Phone is a Medical Device

There have been several instances where a Looper disabled automatic time to change the time on their Loop phone.

As of January 2023, this change in time is detected and the Loop app stops all automatic dosing of insulin other than your scheduled basal rates and begins to aggressively warn the user.

One scenario should be enough to convince you not to do this:

"},{"location":"faqs/time-faqs/#force-automatic-time","title":"Force Automatic Time","text":"

You can configure the iPhone to only allow automatic time.

The ability to use anything other than automatic time is disabled as long as that iOS setting has a passcode. Parents can use this for children. Adults can use this too in case they need a reminder not to change the time - you must first disable the passcode.

This does not affect automatic time zone changes, those are handled by the phone without need for interaction.

"},{"location":"faqs/time-faqs/#remove-future-glucose","title":"Remove Future Glucose","text":"

If you have future glucose from a manual time change or just entering something into Apple Health with the wrong timestamp:

The Loop app is very aggressive at warning you if you make this mistake. you will get a notification - even when you are in a different app. The graphic below shows the alert when you next view the Loop app after turning off automatic time and changing the time. Even if you respond right away, you may have at least one glucose reading in the future when you see this alert. Please Remove Future Glucose.

The rest of this page is about changing time zones.

This is safe because the Loop app keeps track of records internally using UTC.

"},{"location":"faqs/time-faqs/#time-zones-daylight-savings-time-summer-time","title":"Time Zones, Daylight Savings Time, Summer Time","text":"

The Loop app operates across time zones and time changes. The phone that is running the Loop app will automatically update the time, but you choose when to modify the time zone for \"pump time\".

What Therapy Settings are set by \"pump time\"?

Time Change comments:

Medtronic Users

Do not use the Medtronic pump menus to change your pump's time when Looping.

"},{"location":"faqs/time-faqs/#iphone","title":"iPhone","text":"

The Loop app will warn you if your phone does not have time configured to automatically update. The configuration is under iOS Settings -> General -> Time & Date.

Do not ever adjust the time manually on your Looping phone to \"defeat\" time-based rules for a game. Your phone with the Loop app is now a critical medical device - make sure anyone who uses your phone understands this.

"},{"location":"faqs/time-faqs/#minimed-pump-and-cgm","title":"Minimed Pump and CGM","text":"

The Minimed pump doesn't expose a universal clock, instead it exposes the components of a date (YMDHIS). It has no concept of political time zones, and just continues to increment its components on schedule. Therefore, the Loop app assumes that the pump's date, until changed, remains at a fixed offset from UTC.

That offset is stored by the Loop app the first time the pump ID is changed, and every time the pump's time is changed using the \"Change Time Zone\" command.

"},{"location":"faqs/time-faqs/#dexcom-cgm","title":"Dexcom CGM","text":"

No particular input is needed on your part for the Loop app to work with Dexcom CGM data. All times use UTC. However for Dexcom receiver users, at time changes you may want to manually change your receiver's time setting just so the time visually appears correct when you are viewing the screen.

"},{"location":"faqs/time-faqs/#airports","title":"Airports","text":"

RileyLinks, pumps and CGM have no problem going through any of the airport security systems. You can carry it with you in the airplane cabin and it can go through the x-ray scanner that your carry-on bags go through.

"},{"location":"faqs/time-faqs/#airplane-mode","title":"Airplane Mode","text":"

Nothing wrong with airplane mode, but many people forget about it at the time they travel. So, you can do this simple preparation step now:

Turn airplane mode on. Then make sure your Bluetooth is still slid \u201con\u201d. If Bluetooth isn\u2019t on, then go slide it on again. Now go ahead and turn airplane mode off again.

Why did we just do that? Because in older versions of iOS, airplane mode turned off Bluetooth the first time you ever use it. New iOS don't do that, but worth checking.

But, if you remember to turn Bluetooth back on while in airplane mode, two things happen (1) your CGM and the Loop app will work while in airplane and (2) airplane mode will \u201cremember\u201d the next time that you like Bluetooth left on in airplane mode and will not turn it off the next time you slide airplane mode on. So now you\u2019ve just prevented yourself from forgetting to turn Bluetooth on the next time you fly and are in a hurry to meet your lovely seat mate and stow your luggage. You can safely follow cabin instructions and put phone in airplane mode without losing access to the Loop app or CGM.

"},{"location":"faqs/update-faqs/","title":"Update/Rebuild Loop FAQs","text":""},{"location":"faqs/update-faqs/#overview","title":"Overview","text":"

First, please take a minute to understand what the words mean.

In both cases, you build the code to install over an existing app on your phone or onto a new device.

Check Apple Developer Account

If you have an updated agreement, be sure to accept it before you update or rebuild.

Slow Internet / Slow Mac? (click to open/close)

If you have a very slow download speed or if you do a lot of customizations, it may be worth your time to decide if you need a new download.

"},{"location":"faqs/update-faqs/#what-if-im-changing-phones","title":"What if I'm changing phones?","text":"

There's a whole page devoted to just this topic: New Phone

"},{"location":"faqs/update-faqs/#when-should-i-update","title":"When Should I Update?","text":""},{"location":"faqs/update-faqs/#steps-to-update","title":"Steps to Update","text":"

Updating the Loop app is the same idea as what happens to your other apps on your iPhone when you update them from the App Store on the phone. A newer version of the same app appears on the phone, simply updating-in-place the same the Loop app you were using with an updated version.

"},{"location":"faqs/update-faqs/#typical-apple-update-schedule","title":"Typical Apple Update Schedule:","text":""},{"location":"faqs/update-faqs/#where-should-i-start-when-i-want-to-update-my-loop","title":"Where should I start when I want to update my Loop?","text":""},{"location":"faqs/update-faqs/#check-your-developer-account","title":"Check your Developer Account","text":"

Regardless of the build method, always check your Apple Developer Account status.

Apple updates its License Agreement for the Developer Program frequently. You need to log in to your developer account to manually check if there is a new agreement to accept. If you see a big red or orange banner across the top of your Developer Account announcing a new license agreement like shown below...please read and accept it before building Loop.

"},{"location":"faqs/update-faqs/#updates-with-the-browser-build-method","title":"Updates with the Browser build method:","text":"

Go to Update/Rebuild with Browser and follow the instructions.

"},{"location":"faqs/update-faqs/#updates-with-the-build-with-mac-method","title":"Updates with the build with Mac method:","text":"

ALWAYS start with the Update/Rebuild with Mac before any new build with Mac. That page is important because it will offer information on the updates you may need for your Mac and Xcode before building.

Do not simply build with your old downloaded folder from months ago. There is a high likelihood that your original code from awhile ago is outdated and might not build with the current phone iOS. Grab new code and you will get the compatible version that has all the latest and greatest features and bug fixes.

"},{"location":"faqs/update-faqs/#will-i-have-to-delete-my-old-loop-app","title":"Will I have to delete my old Loop app?","text":"

No. Do not delete your old Loop app. In fact, that is a bad idea as you will lose your currently paired pod and/or settings if you do that. So, don't delete.

"},{"location":"faqs/update-faqs/#does-update-make-a-separate-second-loop-app","title":"Does update make a separate, second Loop app?","text":"

No. The Loop app is simply updated in-place, written right over the old version.

The only exception to this is if you update/build using a different developer signing team than your current Loop app.

"},{"location":"faqs/update-faqs/#will-my-settings-be-saved-when-i-update","title":"Will my settings be saved when I update?","text":"

Yes. That's why we don't delete the app. Your settings will be saved so long as you use the same developer ID.

"},{"location":"faqs/update-faqs/#will-my-pod-still-work-when-i-update","title":"Will my pod still work when I update?","text":"

Yes. So long as you use the same developer ID as you originally built the app with before.

"},{"location":"faqs/update-faqs/#how-can-i-confirm-what-version-was-installed","title":"How can I confirm what version was installed?","text":"

The Loop app version is given at the top of the Loop settings page.

There is more detailed information about how the Loop app was built at the top of the Issue Report as shown in the graphic in the next section.

"},{"location":"faqs/update-faqs/#when-will-my-app-expire","title":"When will my app expire?","text":"

The information in the graphic below shows the Build Details included at the very beginning of a Loop Report (Loop, Setting, Support, Issue Report).

Up through version 3.2.3, the Browser Build versions do not report the correct date in the Expiration Alert. The date reported is correct with Mac Build or later versions using the Broswer Build.

"},{"location":"faqs/update-faqs/#what-if-i-change-the-branch-or-fork","title":"What if I change the branch or fork?","text":"

Does not matter. Changing the branch and even the fork is an update action. Nothing about the information above changes with the following exception.

The exception to the rule is if you build Loop 3 on your phone and want to return to Loop 2.2.x or any FreeAPS fork.

"},{"location":"faqs/update-faqs/#how-long-does-it-take","title":"How long does it take?","text":"

Assuming your macOS and Xcode updates are done, then plan on about 30 minutes for a Mac build. The Browser build steps are very fast, but then you need to wait about an hour for the build to complete and appear in TestFlight.

"},{"location":"gh-actions/automatic/","title":"Automatic Update & Build","text":""},{"location":"gh-actions/automatic/#overview","title":"Overview","text":"

After the next release of the Loop app (version 3.4.0), this page will be required for all versions when building with a browser.

Before that release, this page is only relevant when building the dev branch with a browser and only when the dev branch is the default branch.

"},{"location":"gh-actions/automatic/#modify-automatic-building","title":"Modify Automatic Building","text":"

For someone using development code for their own use, they probably want to decide when to update their fork to the most recent commit. They can still have the advantage of automatic building without automatic updates. There may be other configurations someone would choose. These options are added to Loop 3.3.0 (dev branch) and later.

You can affect the default behavior:

  1. Modify Automatic Schedule
  2. Disable Automatic Actions
"},{"location":"gh-actions/automatic/#modify-automatic-schedule","title":"Modify Automatic Schedule","text":"

You can modify the automation by creating and using some variables.

To configure the automated build more granularly involves creating up to two environment variables: SCHEDULED_BUILD and/or SCHEDULED_SYNC. See How to configure a variable.

Note that the weekly and monthly Build Loop actions will continue, but the actions are modified if one or more of these variables is set to false. A successful Action Log will still appear, even if no automatic activity happens.

SCHEDULED _SYNC SCHEDULED _BUILD Automatic Actions true (or NA) true (or NA) keep-alive, weekly update check (auto update/build), monthly build with auto update true (or NA) false keep-alive, weekly update check with auto update, only builds if update detected false true (or NA) keep-alive, monthly build, no auto update false false no automatic activity, no keep-alive"},{"location":"gh-actions/automatic/#how-to-configure-a-variable","title":"How to configure a variable","text":"
  1. Go to the \"Settings\" tab of your LoopWorkspace repository.
  2. Click on Secrets and Variables.
  3. Click on Actions
  4. You will now see a page titled Actions secrets and variables. Click on the Variables tab
  5. To disable ONLY scheduled building, do the following:
    • Click on the green New repository variable button (upper right)
    • Type SCHEDULED_BUILD in the \"Name\" field
    • Type false in the \"Value\" field
    • Click the green Add variable button to save.
  6. To disable scheduled syncing, add a variable:
    • Click on the green New repository variable button (upper right)
      • Type SCHEDULED_SYNC in the \"Name\" field
    • Type false in the \"Value\" field
    • Click the green Add variable button to save

Your build will run on the following conditions:

"},{"location":"gh-actions/automatic/#disable-automatic-actions","title":"Disable Automatic Actions","text":"

To enable the scheduled build and sync, the GH_PAT must hold the workflow permission scopes. This permission serves as the enabler for automatic and scheduled builds with browser build. To disable this, follow these steps:

  1. Go to your FastLane Access Token
  2. If it says repo, workflow next to the FastLane Access Token link, then automatic building is enabled
  3. To disable automatic update and build, click on the link to open the token detail view
    • Click to uncheck the workflow box
    • Click to check the repo box
  4. Scroll all the way down to and click the green Update token button
  5. Your token now holds only the repo permission

If you choose not to have automatic building enabled, be sure the GH_PAT has repo scope or you won't be able to manually build.

"},{"location":"gh-actions/automatic/#stop-building","title":"Stop Building","text":"

What if I decide I don't want the automatic building feature?

"},{"location":"gh-actions/build-dev-browser/","title":"Build Loop dev with Browser","text":""},{"location":"gh-actions/build-dev-browser/#overview","title":"Overview","text":"

This page is only relevant when building the dev branch with a browser.

For Mac, please see: Build Loop dev with Mac

No matter the method used to build Loop-dev, you are testing development code. Please read this link now before continuing.

"},{"location":"gh-actions/build-dev-browser/#build-development-version","title":"Build Development Version","text":"

For Experienced Builders

Building the development (dev branch) is not typically used for your first attempt at building the Loop app.

The instructions on this page assume you are familiar with building the Loop app using a browser as detailed on Configure to use Browser

You can build any desired branch (available at LoopKit/LoopWorkspace) using the GitHub Browser build method. This section is suitable if you have already built either dev or main branch using the GitHub First-Time instructions.

The graphics on this page show the dev branch. If you want a different branch, just substitute that branch name for dev.

Overview of what you will do

  1. Your LoopWorkspace fork must have the branch you want
    • You will either add it or make sure it is up to date
    • You cannot just rename your existing branch to dev - you must get the dev branch from LoopKit
  2. When you select the action 4. Build Loop and then click on the Run Workflow dropdown, you must select dev there before clicking the green Run workflow button - see Build Branch
"},{"location":"gh-actions/build-dev-browser/#check-current-branch","title":"Check Current Branch","text":"

Your LoopWorkspace fork is at https://github.com/username/LoopWorkspace where you substitute your actual GitHub username. You need to be logged into GitHub. Review the graphic below as you go through the steps.

  1. Click on the branch icon to display the branches as shown in the lower half of the graphic below:
    • If the branch you want is not listed, then continue with Step 2
    • Otherwise, skip ahead to Update Branch
  2. Click on the New branch button and follow the Add Branch steps

"},{"location":"gh-actions/build-dev-browser/#add-branch","title":"Add Branch","text":"

Each step in the list below matches with the number in the graphic. In the top half of the graphic, the left side shows the initial display and the right side shows the display after making the indicated selections:

  1. Click on the drop down menu labeled 1 in the graphic and choose LoopKit/LoopWorkspace as show in the top right graphic
  2. Click on the drop down menu labeled 2 in the graphic and choose dev
  3. Click on the Branch name box labeled 3 in the graphic and type dev
    • The branch name in your fork should always match the branch name you are adding; check that you type it correctly
  4. Review the dialog items to make sure everything is correct and then tap on Create branch

"},{"location":"gh-actions/build-dev-browser/#update-branch","title":"Update Branch","text":"

Tap the Code button (upper left) and ensure this branch in your fork is up to date.

"},{"location":"gh-actions/build-dev-browser/#one-time-changes","title":"One-Time Changes","text":"

Look in this section for one-time changes for building dev with a browser that require special, one-time actions.

If you have already completed the One-Time Changes, skip ahead to Build Branch.

"},{"location":"gh-actions/build-dev-browser/#transition-to-dev","title":"Transition to dev","text":"

When updating from\u00a0Loop\u00a03.2.x to dev, you will need to take some extra steps.

You have a choice:

Here is a summary of the extra steps; each step has an associated link. This assumes you have already updated your fork and are at the correct branch.

  1. Confirm the status of your \u00a0GitHub Personal Access Token
    • It should be configured with permission scope of repo, workflow and to never expire
    • You can check this using directions at GitHub Token
  2. Next, follow along in this section to perform these steps before you build
    • Add and Update New Indentifier
    • Create Certificates
"},{"location":"gh-actions/build-dev-browser/#automatic-creation-of-alive-branch","title":"Automatic Creation of alive branch","text":"

What about the alive branch

"},{"location":"gh-actions/build-dev-browser/#add-and-update-new-identifier","title":"Add and Update New Identifier","text":"

The bundle ID for the \"widget\" changed from \"SmallStatusWidget\" to the more descriptive \"LoopWidgetExtension\".

All other identifiers should be already set up. If they are not, please go through the steps on the Configure to Use Browser page to figure out what you are missing.

NAME IDENTIFIER Loop Widget Extension com.TEAMID.loopkit.Loop.LoopWidgetExtension "},{"location":"gh-actions/build-dev-browser/#create-certificates-and-build","title":"Create Certificates and Build","text":"

You must create certificates again to cover the new Identifier name and to provide support for the addition of the Libre sensors. (This step is required whether you use Libre or not - Loop needs permission to have that capability). Once the certificate action succeeds, then run the action to build Loop.

  1. Run the Action for Create Certificates - be sure that you run this for the dev branch
  2. Run the Action for Build Loop (see Build Branch)
"},{"location":"gh-actions/build-dev-browser/#build-branch","title":"Build Branch","text":"

If you want a branch to be the one you build all the time, you may choose to Change Default Branch. This is not necessary except for special cases.

If you have one branch as default, for example main, and choose to build a different branch, there is an extra step when you Build Loop. Refer to step 4 in the graphic below. Use the branch dropdown menu to select the branch you want before hitting the green Run workflow button.

!!!

"},{"location":"gh-actions/build-dev-browser/#change-default-branch","title":"Change Default Branch","text":"

There can be several reasons why you would change your default branch.

These are the steps to modify the default branch.

For this example, we show how to change from a default branch of main to a default branch of dev. Note - only the owner of the repository can take this action and they must be logged in. Otherwise the Settings tab does not appear.

For the numbered steps below, refer to the graphic found under each group of steps.

  1. Click on the Settings Icon near the top right of your LoopWorkspace

    • You may need to scroll down to see the Default Branch as shown in the graphic
    • Do not tap on the Branches tab to the left under Code and Automation, that is not the correct menu

  2. To the right of the default branch name there is a pencil and a left-right arrow icon

    • Tap on the left-right arrow icon to bring up the Switch default branch to another branch dialog
  3. Click on the dropdown next to the current default branch, in this example, main
  4. Select the desired default branch, in this example, dev

  5. Click on the Update button

  6. You will be presented with an are-you-sure question.

    • Click on the red I understand, update the default branch. button

Your default branch has been changed.

"},{"location":"gh-actions/build-dev-browser/#automatic-update-build","title":"Automatic Update & Build","text":"

The automatic update and build features of the development branch are only available if you set the dev branch as your default branch. Be sure to read the Automatic Update & Build if you did this.

"},{"location":"gh-actions/custom-browser/","title":"Customize using Browser","text":""},{"location":"gh-actions/custom-browser/#overview","title":"Overview","text":"

This page is only relevant when building with a browser.

For Mac, please see: Customize with Mac

For new Loopers, please build the code before you make any changes. Start with Open Loop and familiarize yourself with the interface. Later, you can make the customization(s) you desire and build again. The second build will be much easier than your first build.

These customizations require you to modify the code used to build the Loop app and then build the app again with the modified code.

You take responsibility

You are responsible when you decide to use customizations.

Be sure to report what changes you made if you need to ask for assistance with your app.

"},{"location":"gh-actions/custom-browser/#customizations-prepared-for-you","title":"Customizations Prepared for You","text":"

Some customizations are the same for everyone and have been prepared for easy use.

The Loop and Learn team commits to maintaining these prepared customizations and provides an easy method to add your selection from these customizations to your version of Loop.

Please read the documentation for these on the Loop and Learn: Customization Select Page:

"},{"location":"gh-actions/custom-browser/#add-libre-support-to-323","title":"Add Libre Support to 3.2.3","text":"

If you are using main branch to build Loop 3.2.3 and rely on either xDrip4iOS or GlucoseDirect to read your CGM and transfer the readings to the Loop app, you need to review this section of the Loop and Learn customization page.

Alternatively, you can switch to the dev branch, which already supports Libre. Build Loop dev with Browser

"},{"location":"gh-actions/custom-browser/#personal-customizations","title":"Personal Customizations","text":"

Some customizations must be created for yourself. These are of two basic types: Custom Edits and Build-Time Flag.

The information needed to modify the code to make these customizations is found in the Versions tab because the information is independent of build method (think of these as your personal versions). The links are found below.

When preparing these personal edits using a browser, there is a page explaining how to get these edits into your personal fork of LoopWorkspace prior to building.

"},{"location":"gh-actions/custom-browser/#details-at-links","title":"Details at Links","text":"

The code changes required for these customizations are the same regardless of the build method. The pages that provide the documentation on modifying and incorporating these changes are found at the links above.

"},{"location":"gh-actions/edit-browser/","title":"Custom Edits with Browser","text":""},{"location":"gh-actions/edit-browser/#hot-topics","title":"Hot Topics","text":"

Pro Tip

The method on this page allows you to create a set of personalized customizations that you can use in addition to the Loop and Learn: Prepared Customizations. You can use (and re-use) your customizations with either Browser Build or Mac builds so you don't have to repeat the customization with every update.

Modules vs Submodule

This page has instructions to set up your own fork for the Modules, otherwise known as submodules, associated with\u00a0LoopWorkspace\u00a0that are needed for a selected customization.

Each Module has its own GitHub repository;and you will be working with your fork of that Module at https://github.com/username/Module, where username is your username.

What is a SHA-1?

SHA-1 means Secure Hash Algorithm 1; which is used to generate an alphanumeric code.

Each time you save a change to your\u00a0GitHub repository, a unique SHA-1 is created. That identifier is used to tell GitHub a specific change that you want applied or identifies a specific version for that repository. These work for any compatible fork from the original\u00a0GitHub repository.

"},{"location":"gh-actions/edit-browser/#do-not-make-a-pull-request-to-loopkit-github-username","title":"Do Not Make a Pull Request to LoopKit GitHub Username","text":"

Ignore\u00a0Compare & pull request\u00a0Prompts

Please do not click on boxes that GitHub might show you that ask if you want to Compare & pull request.

This would be an attempt to merge changes from your fork back to the original version that everyone uses. These changes are for you only. Ignore those prompts.

"},{"location":"gh-actions/edit-browser/#overview","title":"Overview","text":"

Time Estimate

Summary

FAQs

"},{"location":"gh-actions/edit-browser/#how-to-customize-build-with-browser","title":"How to Customize Build with Browser","text":"

You do this using any browser on a computer or laptop. (Phone is not recommended - screen is too small.)

There is some background information at the bottom of this page starting at\u00a0LoopWorkspace\u00a0if you want to know what you are doing. Otherwise, just follow the steps like a cookbook.

"},{"location":"gh-actions/edit-browser/#decide-which-modules-you-want-to-modify","title":"Decide Which Modules You Want to Modify","text":"

Decide which Version: Custom Edits changes you want to make. Each customization lists a Module name.

Look also at the Stable line for the desired customization:

"},{"location":"gh-actions/edit-browser/#outline-of-what-happens-in-the-module","title":"Outline of What Happens in the Module","text":"

Review Only

Review this section so you know what to expect. The actual steps will come later, starting with Create your Fork for Selected Module or Edit Module in Browser.

In the next sections, the exact process for making changes will be documented. But the steps may feel confusing. There are no links here because you are supposed to review the steps before taking action in the next section.

  1. First time for this module:
    • Make a fork
    • If the customization you want is not \"Stable\" and you are building main
      • Create a new branch for your fork using the SHA-1 table
  2. Change the line(s) of code desired for your customization(s) in your fork
  3. Save the change(s) using descriptive comments
  4. Repeat until done with this Module

Later, you will use information from your fork to create your customizations. (Suggestion - use same file as your Secrets, or at least keep the customization file in the same folder). Details are found at the Prepare the Customizations section.

"},{"location":"gh-actions/edit-browser/#error-committing-your-changes","title":"Error Committing Your Changes","text":"

What should you do if you see the message:

This is fairly rare, but it can happen. A user got this error when editing a file using GitHub:

The solution was to make sure the email address in their GitHub profile was correct. See GitHub Discussions for more information.

"},{"location":"gh-actions/edit-browser/#create-your-fork-for-selected-module","title":"Create your Fork for Selected Module","text":"

Choose your link:

"},{"location":"gh-actions/edit-browser/#code-updates","title":"Code Updates","text":"

New Release

If you have previously used this process for a prior release, use the same Modules you already copied.

You can often reuse customizations that you created earlier even with a new release. Attempt to use your existing patches before creating new ones.

If a customization did not work, then

  1. Go to your fork of each Module
  2. Make sure you are on the Default Branch for that Module
  3. Sync that Module to get the most recent version

Skip ahead to Personalized Customization for this Module.

"},{"location":"gh-actions/edit-browser/#new-fork","title":"New Fork","text":"

If you want a modification that uses a particular Module, you must make a fork of that module to your account in GitHub. You will repeat the Fork and Modify steps for each module.

  1. Log into your GitHub account
  2. Click the URL in the Module Table
  3. This opens a new browser tab at the URL of the module you need to fork
  4. Click on\u00a0Fork, your fork will show up in the browser
"},{"location":"gh-actions/edit-browser/#module-table","title":"Module Table","text":"

This table lists all the modules referred to on the Code Customization page linked above:

Module Fork From Loop https://github.com/LoopKit/Loop LoopKit https://github.com/LoopKit/LoopKit OmniBLE (for DASH) https://github.com/LoopKit/OmniBLE OmniKit (for Eros) https://github.com/LoopKit/OmniKit

Remember - you can only have a single fork of a given\u00a0GitHub repository. If you already have a fork, you don't need another one; but it must be a linked to the URL listed the Module Table.

I already have a fork

Go to Existing Fork for Module and follow the directions.

"},{"location":"gh-actions/edit-browser/#default-table","title":"Default Table","text":"

When you\u00a0\"fork a repository\", the default\u00a0branch\u00a0is the one that should be forked.

username/Repository Default LoopKit/Loop dev LoopKit/LoopKit dev LoopKit/OmniBLE dev LoopKit/OmniKit main"},{"location":"gh-actions/edit-browser/#create-branch-if-needed","title":"Create branch if needed","text":"

Open your browser to your https://github.com/username/Module URL. If you already created the branch you need, you do not need to create a new one.

If you are customizing a released version, use the Table of SHA-1 under your version number below. Copy the SHA-1 for your Module so you can paste it into the URL in Step 2 below. Notice the suggested branch name for that table. You will use this in Step 3.3 below.

You should create a branch following the numbered steps and watching the GIF. Each Frame in the GIF corresponds to a numbered step below.

  1. Click on URL line as indicated by the arrow
  2. Add the text /tree/SHA-1 where you change SHA-1 to be the value in the table below and hit return
  3. Create a new branch in three steps
    • 3.1: Click on the dropdown under the branch icon
    • 3.2: Type the suggested new branch name in the blank space
    • 3.3: Click on the create branch button
  4. You should see a screen similar to the example below
    • Do not click on the Create Pull Request button that is marked with a big X

"},{"location":"gh-actions/edit-browser/#table-of-sha-1","title":"Table of SHA-1","text":"

This will be updated with each release. The versions for the dev branch are not reported here because they are frequently updated. If customizing dev, use the default branch for each Module and sync that branch if needed.

"},{"location":"gh-actions/edit-browser/#version-323","title":"Version 3.2.3","text":"

Suggested branch name is v-3.2.3

Repository SHA-1 LoopWorkspace 81a3d9b03305a4b2a844bd6bac14a14f27626fef Loop c6b058b4276681600979aaeba518c635f06ac135 LoopKit 9835a29f1bac9f75023f39c376479a2e6a6c8ccd OmniBLE f21360781c0b8eee26c531d20f1b0aa192a227f2 OmniKit c1e0d395975c93d15b3f84ac21097e40b7d5d93f"},{"location":"gh-actions/edit-browser/#personalized-customization-for-this-module","title":"Personalized Customization for this Module","text":"

Navigate to the file you need to modify (using the instructions to find the lines from the Version: Custom Edit page)

Pro Tip

Look at the files you want to change - if more than one change is desired for a single file - do them at the same time.

This section provides the steps to make a single customization for the Module. If you need more than one, just repeat the process and make additional\u00a0\"\"patch\" branches.

"},{"location":"gh-actions/edit-browser/#example-gif","title":"Example GIF","text":"

The GIF showing the creation of one customization is shown below. Please review the 4 frames of the GIF, read the detailed instructions below and then review the GIF again. In case you are concerned by the\u00a0\"Pull Request\u00a0shown here; this is to your own fork, not back to the original.

"},{"location":"gh-actions/edit-browser/#detailed-instructions","title":"Detailed Instructions","text":"

You will be using the \"pencil\" tool in the browser display for your fork.

Are there detailed instructions?

For more information about editing with GitHub:

The bullets below go with Frame 1 of the GIF above:

The bullets below go with Frame 2 of the GIF above:

Between Frame 2 and 3 of the GIF, your display will look similar to the graphic below:

You see there an opportunity to\u00a0\"Compare & pull request\"

The\u00a0branches\u00a0selection is highlighted with a brown rectangle in the graphic above.

Your screen should now look like Frame 3 of the GIF above:

Now your display should look like Frame 4 of the GIF above:

For example:

# OmniBLE: Increase insulin at insert by 0.35 U\nSHA-1 = 5e9f4f407ff5544663f496d2e3a5ed8aa4f32a68\n

Warning - that is not a valid SHA-1 for this change. Do not try to copy it and use it. You must make your own personalized changes.

Later on, you will create the actual command needed to insert into build_loop.yml so you can add this customization when your build the app.

Repeat this process until you've done all your customizations for this Module and then move on to the next Module.

"},{"location":"gh-actions/edit-browser/#prepare-the-customizations","title":"Prepare the Customizations","text":"

Once you prepare the commands, then you will edit the build_loop.yml file of your fork of\u00a0LoopWorkspace.

Ensure your fork is from\u00a0LoopKit/LoopWorkspace

If your\u00a0LoopWorkspace fork\u00a0did not come from\u00a0LoopKit/LoopWorkspace, then delete your existing fork and make a new one. See Already Have\u00a0LoopWorkspace?.

For each customization you want to include, create a pair of lines consisting of the comment (must start with a #) followed by the\u00a0curl\u00a0statement pointing to the SHA-1 that has the customization.

Save the customization lines in your text file for later use in the build_loop.yml file.

Customization Template:
# Module: File: code customization description\ncurl https://github.com/username/Module/commit/SHA-1.patch | git apply -v --directory=Module\n

where:

To view the exact code change associated with that patch, open a browser at the URL of\u00a0https://github.com/username/Module/commit/SHA-1.

"},{"location":"gh-actions/edit-browser/#updateloopworkspace","title":"Update\u00a0LoopWorkspace","text":"

The final step is to update your\u00a0LoopWorkspace fork\u00a0to apply these customizations by adding those customization lines into the build_loop.yml file.

Return to your\u00a0GitHub fork for LoopWorkspace\u00a0and make sure to sync it if needed.

Paste into build_loop.yml
      # Customize Loop: Download and apply patches\n      - name: Customize Loop\n        run: |\n\n          # For each patch, edit comment line (keep the #) then update curl (and remove the #)\n\n          # Submodule Loop patches:\n          # Loop: Filename: customization details\n          #curl https://github.com/username/Loop/commit/SHA-1.patch | git apply -v --directory=Loop\n\n          # Submodule LoopKit patches:\n          # LoopKit: Filename: customization details\n          #curl https://github.com/username/LoopKit/commit/SHA-1.patch | git apply -v --directory=LoopKit\n\n          # Submodule xxxxx patches: Follow prototype above\n
"},{"location":"gh-actions/edit-browser/#add-personal-customizations-to-build_loopyml","title":"Add Personal Customizations to build_loop.yml","text":"

Open the text file in which you saved the customization lines.

For a given submodule, paste the comment / curl command as indicated in the template above.

The indenting needs to match, so tab or (shift-tab) to line up the columns.

Once you are done with all the edits for build_loop.yml you will commit the changes to your fork directly.

When you are ready, it's time to build with your customizations.

"},{"location":"gh-actions/edit-browser/#build-with-customizations","title":"Build with Customizations","text":"

At the top of the display, click on\u00a0Actions.

Wait about 2 minutes before walking away to make sure there are no errors. If you get an error, then look for the first \"did not apply\" error message and fix the customization right before that line.

In about 1 hour, your customized app will be available for installation on your phone via TestFlight.

"},{"location":"gh-actions/edit-browser/#customization-and-sha-1","title":"Customization and SHA-1","text":"

When you commit your customization to your branch of your fork, there is a new SHA-1 associated with that step. The SHA-1 for a given branch, typically main or dev identifies to a mentor exactly which version of code you used for your build.

The SHA-1 for customized code will not be recognized by a developer or mentor. If you are having a problem and need to ask for help you need to identify what the SHA-1 was before you added your customizations.

If you are on main branch and it is up-to-date, this is less of an issue. If you are on dev branch, that can require some investigation.

"},{"location":"gh-actions/edit-browser/#ask-for-help-to-identify-your-base-version","title":"Ask for Help to Identify Your Base Version","text":"

The easy method is to provide a mentor with your GitHub username and they can figure out the base version you are using aside from customization. They can also identify the customizations you added.

"},{"location":"gh-actions/edit-browser/#identify-your-base-version","title":"Identify Your Base Version","text":"

If you want to do this yourself, this section explains the steps.

"},{"location":"gh-actions/edit-browser/#special-cases","title":"Special Cases","text":""},{"location":"gh-actions/edit-browser/#existing-fork-for-module","title":"Existing Fork for Module","text":"

What if you already have a fork of one of the modules?

Your existing fork is from a username other than LoopKit

Instructions to delete a repository are found at\u00a0GitHub Docs

Once deleted, go to Create Your Fork for Selected Module.

"},{"location":"gh-actions/edit-browser/#background-information","title":"Background Information","text":""},{"location":"gh-actions/edit-browser/#loopworkspace","title":"LoopWorkspace","text":"

The\u00a0LoopWorkspace repository\u00a0is the umbrella organization holding all the pieces needed to build the Loop app. It provides a list of pointers to a specific version for each of the Modules used in the workspace.

You are telling GitHub to apply specific customizations when it builds your app for you. It extracts from GitHub all the code needed, applies your specific customizations and then starts the build.

"},{"location":"gh-actions/gh-deploy/","title":"Install on Phone","text":""},{"location":"gh-actions/gh-deploy/#general-installation-information","title":"General Installation Information","text":"

This is only available with\u00a0Loop 3.

The Loop app must be built at least every 90 days when using a browser to build.

After you Build the Loop App with a browser and it has automatically uploaded to the TestFlight app, you are ready to install on as many phones as you and your family members need.

"},{"location":"gh-actions/gh-deploy/#install-testflight","title":"Install TestFlight","text":"

If you already have the TestFlight app installed on your phone, skip ahead to Install App with TestFlight.

To install TestFlight, refer to the GIF below:

"},{"location":"gh-actions/gh-deploy/#install-app-with-testflight","title":"Install App with TestFlight","text":"

Once you get an email that the TestFlight processing completed, you can install the app on your phone. Note this can be half-hour to an hour after the build displays the green check mark on your browser.

The first time you use TestFlight on any phone associated with a given email, you must Redeem the code sent to that email inviting you to test the app. The GIF below is for someone who has never used TestFlight.

If you already have the\u00a0Loop\u00a0app on the phone, you'll see the warning about possible loss of data. Don't worry, all your settings remain. Go ahead with the installation.

"},{"location":"gh-actions/gh-deploy/#subsequent-times-on-phone","title":"Subsequent Times on Phone","text":""},{"location":"gh-actions/gh-deploy/#automatic-update-build-install","title":"Automatic Update, Build, Install","text":"

Automatic features will be available when the next version is released and are available now in 3.3.0 (when\u00a0dev is the default branch). The instructions on the Configure to Use Browser page will, unless you make a change, automatically take the following actions when you update to the next release or use dev:

It is already true that, unless you make a change, the default setting will:

"},{"location":"gh-actions/gh-deploy/#recommendation","title":"Recommendation","text":"

Recommended settings:

If you are running the development code, you may prefer to turn off the automatic update, but keep the automatic build. To read more about modifying automatic update and build options, please read Modify Automatic Building.

"},{"location":"gh-actions/gh-deploy/#disable-automatic-install-from-testflight","title":"Disable Automatic Install from TestFlight","text":"

Once the app is installed one time, you can adjust whether it is automatically installed when updated versions are available. We recommend you disable automatic installation so you can choose when to switch to a newer build, which in some cases, may be a newer version.

Go back to the TestFlight app on your phone and tap on your app name in the list to see an expanded screen similar to the graphic below. The row to enable or disable automatic updates is highlighted in the graphic, which shows the feature disabled. This is recommended for all users.

When you are ready to install, just open the TestFlight app and click Install to get the most recent build and then click Open when it completes the installation. All your settings and connections to CGM and Pump are maintained.

If you tap on the bottom row that says Previous Builds, highlighted by the dashed-green rectangle, you can view and choose an older build (as long as it has not expired).

"},{"location":"gh-actions/gh-deploy/#testflight-for-a-child","title":"TestFlight for a Child","text":"

The adult (Apple Developer Account owner) can log into Media & Purchase (see steps below) without affecting the child Apple ID associated with a phone (and thus their health records used by\u00a0Loop). After the adult installs or updates the app using TestFlight, they probably should reverse those steps to remove their credentials from Media & Purchase.

Media & Purchase affects access to the App Store, Books, Music and Podcasts.

On the Child phone:

"},{"location":"gh-actions/gh-deploy/#change-the-app-store-connect-name","title":"Change the App Store Connect Name","text":"

Suppose you really don't like the name you picked initially for the\u00a0Loop\u00a0app that shows up in the TestFlight app.

You can change it.

Open this link: App Store Connect Apps and log in as needed.

"},{"location":"gh-actions/gh-errors/","title":"Errors with Browser","text":""},{"location":"gh-actions/gh-errors/#help-with-errors","title":"Help with Errors","text":"

If you get an error when building with a browser, use this page to figure out what to do.

If you are still unsuccessful, then post your request for help along with your GitHub username. Mentors can go to your public\u00a0GitHub repository, check the status and then view your log files directly.

Username, Not Pictures

If you've been around the DIY community for a while, you know the mantra about screenshots. Well, when using a browser to build, screenshots are close to useless.

All that is needed to assist is your GitHub username.

But first - try to diagnose it yourself using this page.

"},{"location":"gh-actions/gh-errors/#most-common-mistakes","title":"Most Common Mistakes","text":"

These are some of the most common errors to date.

  1. You made a spelling error when adding Secrets
    • Each secret must be spelled exactly the way it is presented in the instructions
    • If you are using an automatic translation, please keep an original page open too and copy from it to make sure there are no spelling errors in the secret name
  2. You did not add the App Group Identifier to all 4 of the required identifiers in this step: Add App Group to Identifiers
  3. You used a smart editor instead of a text-only editor to save your information
    • It only takes one letter to be changed from lower-case to upper-case by your smart editor to ruin your day
    • The alpha-numeric values used for GH_PAT, FASTLANE_ISSUER_ID and FASTLANE_KEY contain both upper and lower-case characters and all the values are case-sensitive
  4. When saving TEAMID, you typed what you thought you saw instead of using copy and paste
  5. You skipped running one of the actions
  6. You need to sign a program license agreement or update a credit card at\u00a0Apple Developer
    • Be sure to read Misleading Error Message

If you are running development code, skip ahead to Preview for Next Version.

"},{"location":"gh-actions/gh-errors/#misleading-error-message","title":"Misleading Error Message","text":"

If there are Apple Developer agreements you have not accepted, you may get errors when you try to Build that indicate your Apple Secrets are incorrect even if they are not.

If you need detailed instructions, click on this Apple Program License Agreement Help Page.

You can also get this message if the credit card used to purchase the Developer account is not current, e.g., no longer valid or expiration date has passed.

One user reported: The expiration date on the credit card used for auto-renew of my developer account was updated and the value in the Apple account did not match the new one. After updating my account with the new expiration date - Browser Build succeeded again.

"},{"location":"gh-actions/gh-errors/#find-your-error","title":"Find Your Error","text":"

For Version 3.2.3 and earlier - later versions have an improved method for display errors.

There is a separate section for each step in the process. First, you must follow the Examine the Error instructions to view the record of the failed action. Then go to the section for the Action you were trying to complete to look for possible error strings to copy into the search box.

  1. Action: Validate Secrets
  2. Action: Add Identifiers Errors
  3. Action: Create Certificates Errors
  4. Action: Build Loop Errors before a successful build
  5. Repeat Build Loop Errors after a successful build

If you discover a new error, please reach out to help us update the documentation.

"},{"location":"gh-actions/gh-errors/#examine-the-error","title":"Examine the Error","text":"

It doesn't matter which action you are running; after the action completes, you will either see a green check mark for success or a red x mark for failure. The graphic below shows an example for the Add Identifiers action.

If you click on the action name, it opens a secondary screen as shown below.

Click on the top link to view the record of the failed action as shown in the graphic below. You will be pasting strings into the search box (highlighted with a green rectangle) to look for a documented error. Please read the instructions below the graphic.

Where to find my GitHub username?

You can find it:

As your GitHub username is case-sensitive, use copy and paste.

"},{"location":"gh-actions/gh-errors/#action-validate-secrets-errors","title":"Action: Validate Secrets Errors","text":"

To generate the graphic below, some items were deliberately set to be incorrect in the Secrets list. Representative error messages are shown when running the validate secrets action.

"},{"location":"gh-actions/gh-errors/#action-add-identifiers-errors","title":"Action: Add Identifiers Errors","text":"

Use the Examine the Error instructions to find your error message.

There are two errors that we are familiar with at this point. Look for text matching what is listed below and view what has caused this error to be seen.

"},{"location":"gh-actions/gh-errors/#error-credentials-missing-invalid","title":"Error: credentials missing / invalid","text":"

Copy the words on the line below and paste them into the search function for your action log.

Authentication credentials are missing or invalid\n

The full error looks like this:

Authentication credentials are missing or invalid. - Provide a properly configured and signed bearer token, and make sure that it has not expired. Learn more about Generating Tokens for API Requests https://developer.apple.com/go/?id=api-generating-tokens`

This can be caused by an error in the value (or spelling) of one of these keys:

Use a Text-Only Editor

If you used a \"smart\" editor when saving your Secrets in an archive file before pasting them into the repository Secrets, it might have changed a lowercase letter to an uppercase letter.

If even one character is capitalized when it should not be, you will not succeed at the Add Identifiers step.

"},{"location":"gh-actions/gh-errors/#error-invalid-curve-name","title":"Error: Invalid curve name","text":"

If you see:

invalid curve name\n

This was caused by an error in the format of the value entered for the FASTLANE_KEY.

Make sure you copy in a text editor from the first hyphen to the last hyphen.

"},{"location":"gh-actions/gh-errors/#action-create-certificates-errors","title":"Action: Create Certificates Errors","text":"

Use the Examine the Error instructions to find your error message.

"},{"location":"gh-actions/gh-errors/#error-wrong-teamid-in-secrets","title":"Error: Wrong TEAMID in Secrets","text":"

Copy the words on the line below and paste them into the search function for your action log.

error: No profile for team '***' matching 'match AppStore\n

If that phrase is found, then:

Follow these steps:

Open each link below in a separate tab

It is best to open each link below in a separate tab so you can return to this list and keep using the links in each step.

  1. Delete all the identifiers that you can, following the steps in Configure to Use Browser: Delete Identifiers

    • Delete all the other identifiers first, then try to delete the Loop identifier with the wrong TEAMID
    • It is fine to just ignore identifiers with the wrong TEAMID, but do not use them

  2. Enter your TEAMID correctly in the repository Secrets

    • Make sure you use copy and paste from your Apple Developer Membership page for that TEAMID.
    • Follow the update instructions here (this example is for GH_PAT, you'll do the same but for TEAMID) Update Secrets

  3. Run Action: Configure to Use Browser: Add Identifiers again

  4. Follow all the steps in this section with the correct TEAMID Configure to Use Browser: Configure Identifiers for Loop but when you get to the Configure to Use Browser: Create Loop App in App Store Connect, you need to return to this page and follow the instructions below to remove the app and add a new one.

The first time through, you created an app with a Bundle ID that does NOT include your TEAMID.

You will remove that app and create a new one.

"},{"location":"gh-actions/gh-errors/#remove-app-with-incorrect-teamid","title":"Remove App with Incorrect TEAMID","text":"

Go to App Store Connect / Apps and follow the numbered steps in the graphic below.

  1. Find the Loop app you created earlier and click on it
  2. On the left side, under General, click on App Information
    • Confirm that the value listed under Bundle ID is the incorrect one
    • The Bundle ID says: com.NOT_YOUR_TEAMID.loopkit.Loop
  3. Scroll to the bottom of the page and tap on Remove App
  4. The dialog box, similar to the one in the graphic below, should appear and you tap Remove
    • After the App is removed, you'll see a very similar screen, where you can tap on Restore App
  5. But since you want that App removed, tap on Apps at the very top of the screen and proceed to the next step

That App with the wrong Bundle ID remains in the App store but it is hidden so it won't confuse you.

"},{"location":"gh-actions/gh-errors/#add-app-with-correct-teamid","title":"Add App with Correct TEAMID","text":"

Now click on the Add Apps button or the (plus sign) if you have other apps in the App Store.

Follow the Configure to Use Browser: Create Loop App in App Store Connect directions with these additions:

"},{"location":"gh-actions/gh-errors/#create-certificates","title":"Create Certificates","text":"

You should be able to continue with the Configure to Use Browser Steps to Create Certificates and then proceed from there with Build Loop and keep going.

"},{"location":"gh-actions/gh-errors/#error-missing-repository-access","title":"Error: Missing Repository Access","text":"

Copy the words on the line below and paste them into the search function for your action log.

Error cloning certificates\n

The full error looks like this:

Error cloning certificates repo, please make sure you have read access to the repository you want to use

or

Error cloning certificates git repo, please make sure you have access to the repository - see instructions above

If you see this phrase, the fastlane package that is utilized during the 3. Create Certificates action cannot access your repository to create certificates for your Loop app. This is due to insufficient repository access rights that were not granted during the creation of your GH_PAT token.

To fix this error:

After you have clicked Update token you should see the token overview again with the message Some of the scopes you\u2019ve selected are included in other scopes. Only the minimum set of necessary scopes has been saved. (You can dismiss the message using the X near the upper right side if it appears).

NOTE: for next release or if using the dev branch - you want GH_PAT to have repo, workflow scope. So click on the workflow scope now and save yourself a step later.

"},{"location":"gh-actions/gh-errors/#create-certificates_1","title":"Create Certificates","text":"

You should be able to continue with the Configure to Use Browser Steps to Create Certificates and then proceed from there with Build Loop and keep going.

"},{"location":"gh-actions/gh-errors/#error-could-not-create","title":"Error: Could not create","text":"

Copy the words on the line below and paste them into the search function for your log file.

Could not create another Distribution certificate\n

The full error message is:

Could not create another Distribution certificate, reached the maximum number of available Distribution certificates

These steps are needed to make room for a Certificate:

  1. Delete an old Distribution Certificate
    • Apple limits you to two Distribution Certificates
    • Use this link to view your Apple Developer Certificates
      • Carefully examine the Type column - do not delete a Development Certificate
      • If you accidentally delete a Development Type certificate associated with an Xcode build for your Loop app - it will stop working and you will be very sad
    • Click on the oldest Distribution Certificate and revoke it
      • You will get an email informing you the certificate was revoked
  2. To create a new Certificate:
    • Return to GitHub and your fork
    • Run the Action: Create Certificates
  3. You are now ready to run the Action: Build Loop

But what about TestFlight builds?

Previous builds using this method that are already in TestFlight are not affected by deleting the Distribution Certificate.

"},{"location":"gh-actions/gh-errors/#error-could-not-decrypt","title":"Error: Could not decrypt","text":"

Copy the words on the line below and paste them into the search function for your log file.

decrypt the repo\n

The full error message is:

Couldn't decrypt the repo, please make sure you enter the right password

If you know you entered the incorrect MATCH_PASSWORD in your repository Secrets, go and fix it now and try again.

Otherwise, you need to follow the steps to Reset Match-Secrets.

"},{"location":"gh-actions/gh-errors/#action-build-loop-errors","title":"Action: Build Loop Errors","text":"

Run Create Certificates First

You must run Action: Create Certificates before attempting to run Action: Build Loop

Use Examine the Error

For each section below, copy the phrase into the search function of the log. If you find it, solve that error. If not, move on to the next one.

"},{"location":"gh-actions/gh-errors/#could-not-find-an-app-on-app-store-connect","title":"Could not find an app on App Store Connect","text":"

Copy the words on the line below and paste them into the search function for your action log.

Could not find an app on App Store Connect\n

If that phrase is found, then:

"},{"location":"gh-actions/gh-errors/#error-provisioning-profile","title":"Error: Provisioning Profile","text":"

Copy the words on the line below and paste them into the search function for your action log.

error: Provisioning profile \"match AppStore\n

If that phrase is found one, or more times, it means you missed a step when configuring the Loop identifier or missed associating your Loop App Group with one or more identifiers.

For example, if you see:

error: Provisioning profile \"match AppStore com.***.loopkit.Loop\" doesn't include the com.apple.developer.usernotifications.time-sensitive entitlement.

Go back to First-Time: Add or Review Configuration for Loop Identifier and make sure you enabled the Time-Sensitive notification for Loop.

For example, you might see:

Return to Add App Group to Other Identifiers and fix the missing items.

You must create certificates again before you can build Loop:

"},{"location":"gh-actions/gh-errors/#a-new-one-cannot-be-created-because-you-enabled","title":"A new one cannot be created because you enabled","text":"

Copy the words on the line below and paste them into the search function for your action log.

A new one cannot be created because you enabled\n

If that phrase is found with lines similar to the following:

[31mA new one cannot be created because you enabled `readonly`\u001b[0m\n[31mProvisioning profiles in your repo for type `appstore`:\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.statuswidget.mobileprovision'\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.SmallStatusWidget.mobileprovision'\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.mobileprovision'\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.LoopWatch.mobileprovision'\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.Loop-Intent-Extension.mobileprovision'\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.LoopWatch.watchkitextension.mobileprovision'\u001b[0m\n

This tells you, the Bundle ID you selected in First-Time: Create Loop App in App Store Connect does NOT have your TEAMID embedded in the name.

Once you have created an app in the App Store that is not based on your TEAMID, you cannot delete it, but you can Remove it (i.e. hide it so that it is no longer visible on this page and you don't accidentally click on it).

  1. Open this link: App Store Connect / Apps to view your apps; log in if needed.
  2. Find the App with the wrong Bundle ID and click on it
  3. On the left-hand side, click on App Information (under General)
    • Confirm the Bundle ID listed does not include your TEAMID
    • Scroll all the way to the bottom
    • Tap on Remove App
    • New dialog window appears, select Remove

At this point, get your correct TEAMID, fix your Secrets file to have the correct TEAMID and then return to First-Time: Configure Secrets. This time you will be updating TEAMID in the repository secret list.

"},{"location":"gh-actions/gh-errors/#repeat-build-loop-errors","title":"Repeat Build Loop Errors","text":"

This section is only for people who have successfully built using GitHub Build Actions.

Use the Examine the Error instructions to find your error message.

"},{"location":"gh-actions/gh-errors/#could-not-install-wwdr-certificate","title":"Could not install WWDR certificate","text":"

Assuming you have successfully built using the Browser-Build / GitHub method before:

"},{"location":"gh-actions/gh-errors/#reset-match-secrets","title":"Reset Match-Secrets","text":"

This is not the first thing to try, but sometimes it is the best approach.

There might be several reasons to do this:

These steps are needed to reset your Match-Secrets:

  1. Delete your Match-Secrets Repository
    • Instructions to delete a repository are found at GitHub Docs
  2. Create a new private Match-Secrets Repository
    • main branch: follow the directions First-Time: Create Match-Secrets
    • dev branch: the Action: Validate Secrets automatically creates a new private Match-Secrets repository if you don't have one
  3. In your fork of LoopWorkspace:
    • Run the Action: Create Certificates
    • If this fails, click on this link for the most likely Error: Could not create
    • If that doesn't help, check all your Secrets and try again
  4. You are now ready to run the Action: Build Loop

Other Apps

All DIY iOS apps that have an associated GitHub Browser Build method require the same 6 Secrets.

If you add an app to your GitHub username (by forking the repository and adding Secrets) and then build it, it encrypts your Certificate using MATCH_PASSWORD.

If you already have the other apps configured and then you delete Match-Secrets and add a new one, you will need to run Create Certificates for each app before the next time you build each app - go ahead and do that now so you don't forget.

"},{"location":"gh-actions/gh-errors/#preview-for-next-version","title":"Preview for Next Version","text":"

Error annotations are available for Version 3.3.0 and later. These were contributed by community volunteers along with the improvements to enable automatic updates and automatic builds.

"},{"location":"gh-actions/gh-errors/#examine-annotation","title":"Examine Annotation","text":"

If a\u00a0GitHub Action\u00a0fails, you will see a clear notification.

First consider the following results from the\u00a0GitHub Action: 1. Validate Secrets.

Your screen may look similar to the graphic below. The name in parentheses refers to the branch used to develop these wonderful messages. Yours may be (dev) or (main), once 3.4.0 is released.

But there are so many reasons why this could happen. The first step is to click on the link highlighted by the red rectangle in the graphic above. This opens a new detailed view. The GIF below shows two different error messages. The first frame shows the error in the Annotation box at the bottom (you may need to scroll down to see this), and you may need to click on \"Show More\" to see the full message as seen in the second frame. The third frame of the GIF shows a different message. Each one these messages is designed to make it easier for you to diagnose your own problem.

Notice that\u00a0GitHub Action: 1. Validate Secrets\u00a0is broken into three jobs each of which will either pass and show a green check or fail and show a red check. The secrets are validated with each action, so you will see this a lot.

For example, the graphic below shows a failure of\u00a0GitHub Action: 3. Create Certificates\u00a0.

This is an example of a message that is not terribly descriptive - which is why it is shown here. In this case, you can click on just the one job that failed. There will be less to sort through to find your error. The most likely reason for this error is Error: Could not Create.

If you run across an error that does not have a nice message, be sure to post as discussed in Help with Errors. You may be contributing to future improvements for this process.

"},{"location":"gh-actions/gh-first-time/","title":"Configure to use Browser","text":""},{"location":"gh-actions/gh-first-time/#build-the-loop-app-using-github","title":"Build the Loop App using GitHub","text":"Time Estimate (click to open/close) Page Summary with Links (click to open/close)

There is a lot of introductory information on this page.

A narrated video is available:

Once you have Apple Developer and GitHub accounts, the steps below are a high-level summary with links to the detailed section of this LoopDocs page.

You can think of the first part as a scavenger hunt where you find or generate and save six Secrets.

Now it's time to use those Secrets to build the Loop app

FAQs (click to open/close) "},{"location":"gh-actions/gh-first-time/#tips-and-tricks","title":"Tips and Tricks","text":"

This page contains fully detailed steps including graphics, which makes it incredibly long.

Responding to a user request, step number indicators were added to this page.

Some sections have a Section Summary:

An automatic table of contents (TOC) should appear for each page on the right side of your browser (if the browser is \"wide\" enough). If not, tap on the hamburger menu (upper left) and then this page name to see the TOC.

For sparse instructions, click on the link below:

"},{"location":"gh-actions/gh-first-time/#how-to-video-to-build-with-a-browser","title":"How-to Video to Build with a Browser","text":"

In addition to this page, there is a narrated video of each step needed to build using a browser.

Click in the comments for a full index of topics. If you have issues with a part of this page, use the index to advance to the relevant part of the video. Subtitles are in English. You can choose a different language but the automatic translation feature may provide translations that are not completely accurate.

"},{"location":"gh-actions/gh-first-time/#step-1-of-12","title":"Step 1 of 12","text":"

Step 1 of 12 is Prerequisites, things you must complete before you start.

"},{"location":"gh-actions/gh-first-time/#prerequisites","title":"Prerequisites","text":""},{"location":"gh-actions/gh-first-time/#prerequisites-to-build-the-loop-app","title":"Prerequisites to Build the Loop App","text":"

There are two prerequisites to build the Loop app using GitHub Browser Build.

  1. Paid Apple Developer account ($99/year)
  2. Free GitHub account
"},{"location":"gh-actions/gh-first-time/#prerequisites-to-install-loop","title":"Prerequisites to Install Loop","text":"

To install Loop, you need the free TestFlight app, from the Apple App Store, installed on your Compatible Phone.

"},{"location":"gh-actions/gh-first-time/#prerequisites-to-use-loop","title":"Prerequisites to Use Loop","text":"

To use Loop, you need a Compatible Pump and Compatible CGM. For pumps other than Omnipod DASH, you also need a RileyLink Compatible Device.

"},{"location":"gh-actions/gh-first-time/#new-terms-with-github-browser-build","title":"New Terms with GitHub Browser Build","text":"

You can read details about new terms with GitHub build or skip ahead to Save Your Information.

The GitHub Browser Build may use new and unfamiliar terms.

Some of these terms have ToolTips, so hover your mouse over those - or review them in the Glossary.

If this summary of terms is confusing, finish reviewing the whole page and then come back.

"},{"location":"gh-actions/gh-first-time/#save-your-information","title":"Save Your Information","text":"

Everyone needs to read this section!

You need to keep a digital copy of your 6 Secrets.

Archive Your Information

To complete the steps on this page, you will need a username, email address, and password for Apple and GitHub. You will find, generate or make up six Secrets as instructed.

Be sure to use a Text-Only editor like NotePad (PC) or TextEdit (Mac) to archive your information.

A Note about Capitalization and Spaces

In places, you use a name like \"FastLane API Key\" or \"FastLane Access Token\". Please copy from the docs to use those exact names.

The Secrets that you add use names that are capitalized and use underscore _ instead of spaces. Be precise and careful.

Use a Text-Only Editor

Be sure to use a Text-Only editor like NotePad (PC) or TextEdit (Mac) to archive your information.

If you use a \"smart\" editor, it may change lower-case letters to upper-case letters at the beginning of a line when you paste items into your archive file.

If even one character is capitalized when it should not be, you will get Errors with Browser Build.

If you use a smart editor to store your FASTLANE_KEY, you are likely to get the mysterious invalid curve name error.

"},{"location":"gh-actions/gh-first-time/#step-2-of-12","title":"Step 2 of 12","text":"

Step 2 of 12 is Save Six Secrets.

The creation of accounts at Apple and GitHub, if you don't already have them, are not numbered. Using those accounts, there are 5 Substeps for Step 2.

"},{"location":"gh-actions/gh-first-time/#save-six-secrets","title":"Save Six Secrets","text":"Section Summary (click to open/close)

You require 6 Secrets (alphanumeric items) to use the GitHub Browser Build method and if you use the GitHub Browser Build method to build more than Loop, e.g., Loop Follow or Loop Caregiver, you must use the same 6 Secrets for each app you build with this method.

Each secret is identified with ALL_CAPITAL_LETTER_NAMES.

To skip the detailed instructions, click on Collect the Four Apple Secrets

You need to save your information digitally, so you can copy and paste. The information is created in one place and used in another. Refer to Configure Secrets for how the Secrets are used. In addition to the 6 Secrets, other important information to keep handy (like usernames and passwords) is listed below. Be sure to keep this file secure.

Created at developer.apple.com

Created at github.com

Created yourself

"},{"location":"gh-actions/gh-first-time/#collect-the-four-apple-secrets","title":"Collect the Four Apple Secrets","text":"Section Summary (click to open/close)

You will be saving 4 Secrets from your Apple Account in this step.

  1. Sign in to the Apple Developer portal page.
  2. If you need to accept a new agreement (happens about twice a year), be sure to do so now
    • Need help? Look at this section on the update page: Accept Agreements
  3. Copy the Team ID from the upper right of the screen. Record this as your TEAMID.
  4. Go to the App Store Connect interface, click the \"Integrations\" tab, and create a new key with \"Admin\" access. Give it the name: \"FastLane API Key\".
  5. Record three more secrets
    • Record the issuer id; this will be used for FASTLANE_ISSUER_ID.
    • Record the key id; this will be used for FASTLANE_KEY_ID.
    • Download the API Key itself, and open it in a text editor. The contents of this file will be used for FASTLANE_KEY. Copy the full text, including the \"-----BEGIN PRIVATE KEY-----\" and \"-----END PRIVATE KEY-----\" lines.

To skip the detailed instructions, click on Collect the GH_PAT Secret

This section provides detailed instructions for the four Secrets associated with your Apple Developer ID.

Name Description TEAMID This 10-character identifier is associated with your Apple Developer ID and never changes FASTLANE_ISSUER_ID The issuer ID is associated with your Apple Developer ID and never changes FASTLANE_KEY_ID Key ID provided when you create an API Key in App Store Connect; it is associated with the FASTLANE_KEY FASTLANE_KEY Copy the full key from the text file you downloaded when generating the API Key - Filename has FASTLANE_KEY_ID value embedded in it.Include everything in the file from -----BEGIN PRIVATE KEY-----and ending in -----END PRIVATE KEY-----"},{"location":"gh-actions/gh-first-time/#new-apple-developer-account","title":"New Apple Developer Account","text":"

If you have an Apple Developer Account, skip ahead to Find TEAMID.

If not, you need to purchase one ($99 annual fee). It may take a few days for the account to be enabled.

"},{"location":"gh-actions/gh-first-time/#substep-21-for-step-2","title":"Substep 2.1 for Step 2","text":"

Next section, Find TEAMID, is Substep 1 out of 5 for Step 2.

"},{"location":"gh-actions/gh-first-time/#find-teamid","title":"Find TEAMID","text":"

Sign in to your Apple Developer account at this link: Apple Developer portal page.

  1. Click Account in the top menu bar
  2. If you need to accept a new agreement (happens about twice a year), be sure to do so now
    • Need help? Look at this section on the update page: Accept Agreements

  3. Click the Membership Details icon

  4. Next to the Team ID field, is a 10-character ID number. This is your Apple Developer TEAMID.

Record this for use as TEAMID in your Secrets file. You will also need it when you Create \u00a0App Group.

"},{"location":"gh-actions/gh-first-time/#substep-22-for-step-2","title":"Substep 2.2 for Step 2","text":"

Next section, Generate API Key, is Substep 2 out of 5 for Step 2.

"},{"location":"gh-actions/gh-first-time/#generate-api-key","title":"Generate API Key","text":"

Paid Apple Developer Account is Required

To generate the API Key, you must have a paid Apple Developer account.

If you are waiting for Apple to enable your account, you can skip ahead to create a New GitHub Account and Create GitHub Personal Access Token. You then pause at Configure Secrets until your Apple account is active.

  1. Click this link to open in a new tab: App Store Connect/Access/Integrations/API

    • The top of the display is shown in the graphic below

    • Click the Integrations tab as indicated in the graphic above

      • If this is your first time here, you will see:

        \"Permission is required to access the App Store Connect API. You can request access on behalf of your organization.\"

        • Click on Request Access and follow directions until access is granted

      • Once access is granted, click on the Generate API Key button

    • If you did not get routed through the permission is required screens click the blue + sign

    • A new Generate API Key dialog box will appear as shown in the graphic below

    • Enter the name of the key as \"FastLane API Key\" and choose Admin in the access drop-down menu
    • Confirm the name and that \"Admin\" is selected and then click on the \"Generate\" button.
"},{"location":"gh-actions/gh-first-time/#substep-23-for-step-2","title":"Substep 2.3 for Step 2","text":"

Next section, Copy API Key Secrets, is Substep 3 out of 5 for Step 2. In this Substep you are dealing with 2 of the Apple Secrets.

"},{"location":"gh-actions/gh-first-time/#copy-api-key-secrets","title":"Copy API Key Secrets","text":"

The Integrations screen appears again with content similar to the graphic below; the key information is blanked out for security.

Review the graphic and then follow the directions below to save more parameters you will need to Configure Secrets

  1. A button labeled Copy is always adjacent to the Issuer ID above the word Active (this is the same for all keys that you generate with this Apple Developer ID)
    • Tap on the Copy button - this copies the Issuer ID into your paste buffer
    • In the file where you are saving information, paste this with the indication that it is for FASTLANE_ISSUER_ID
  2. Hover to the right of the Key ID and the Copy Key ID button shows up
    • Tap on the Copy Key ID button - this copies the Key ID into your paste buffer
    • In the file where you are saving information, paste this with the indication that it is for FASTLANE_KEY_ID

  3. Click on the Download API Key button - you will be warned you can only download this once.

  4. Find your AuthKey download in your downloads folder. The name of the file will be \"AuthKey_KeyID.p8\" where KeyID matches your FASTLANE_KEY_ID

    • Double-click to open it and you will be presented a message asking how you'd like to open it (The message shown is for a Mac - translate these directions to whatever computer you are using)
    • Click on \"Choose Application...\" and then select \"TextEdit\" (on a Mac, NotePad on a PC, or any text-only editor you prefer)

  5. The contents of this file will be used for FASTLANE_KEY

    • Copy the full text, including the \"-----BEGIN PRIVATE KEY-----\" and \"-----END PRIVATE KEY-----\" lines
      • On a Mac, use Cmd+A, then Cmd+C to copy all the contents
      • On a PC, use Ctrl+A , then Ctrl+C to copy all the contents
    • In the file where you are saving information, paste this with the indication that it is for FASTLANE_KEY

"},{"location":"gh-actions/gh-first-time/#do-not-confuse-your-keys","title":"Do Not Confuse Your Keys","text":"

API Key\u00a0 vs\u00a0APN Key

If you use Remote Commands with Nightscout, you may notice the Application Programming Interface (API) key has the same type of format as the Apple Push Notification (APN) key. The keys for both of these purposes are p8 keys, but they should not be confused with each other.

The Secrets for building with GitHub use the\u00a0API Key.

The config vars for Nightscout use the\u00a0APN Key.

"},{"location":"gh-actions/gh-first-time/#done-with-apple-secrets","title":"Done with Apple Secrets","text":"

In summary, from this section, you have found or generated the following and saved copies for later use

Time for a Break?

This is a good place to pause if you need to. Just note where you are on the page so you can return later.

"},{"location":"gh-actions/gh-first-time/#collect-the-gh_pat-secret","title":"Collect the GH_PAT Secret","text":"

If you already have a GitHub Account, skip ahead to Create GitHub Personal Access Token.

"},{"location":"gh-actions/gh-first-time/#new-github-account","title":"New GitHub Account","text":"

If you do not already have a GitHub account, you need to create one. Be sure to record the email, password, and username for your GitHub account.

Decide on a couple of usernames that you will be happy with - this will get embedded into your GitHub URL. Your first choice might not be available, so be prepared with several candidates. Your personal URL will be: https://github.com/username.

The free level comes with plenty of storage and compute time to build the Loop app.

"},{"location":"gh-actions/gh-first-time/#substep-24-for-step-2","title":"Substep 2.4 for Step 2","text":"

Next section, Create GitHub Personal Access Token, is Substep 4 out of 5 for Step 2.

"},{"location":"gh-actions/gh-first-time/#create-github-personal-access-token","title":"Create GitHub Personal Access Token","text":"Section Summary (click to open/close)

Log into your GitHub account to create a personal access token, which you will save as GH_PAT.

Click to create a new personal access token:

To skip the detailed instructions, click on Make up a Password.

You must be logged into your GitHub account before starting this step. If you are continuing, you are already logged in.

  1. You will be creating a new GitHub Personal Access Token and giving it the name \"FastLane Access Token\"

  2. Open this link: https://github.com/settings/tokens/new

    • Referring to the graphic
      • Note that Tokens (classic) is highlighted
      • Most Looper will use the classic Token
        • If you are a developer who needs to use fine-grained tokens, that is fine
      • Edit the note box to be FastLane Access Token
    • The default Expiration time is 30 days - but you should select No expiration (use the drop-down menu to select)
      • GitHub will show a yellow warning when you do this
      • It is ok to ignore the warning
    • Add a check beside the workflow permission scope
    • A check will automatically appear in the repo scope as well - this is normal
    • Scroll all the way to the bottom and click Generate token (it's a long way, ignore all other settings, do not check anything else)

  3. A new screen appears showing your access token

    • Copy the token and record it - once you leave this screen you can't see it again
    • You will use this for GH_PAT when you set up your Secrets
    • You can Regenerate Personal Access Token for GH_PAT if you lose it, but then you have to update that in the Secrets for all repositories using GitHub Build.

"},{"location":"gh-actions/gh-first-time/#substep-25-for-step-2","title":"Substep 2.5 for Step 2","text":"

Next section, Make up a Password, is Substep 5 out of 5 for Step 2.

"},{"location":"gh-actions/gh-first-time/#make-up-a-password","title":"Make up a Password","text":"

If you have not already made up a password, do it now and record it as MATCH_PASSWORD.

"},{"location":"gh-actions/gh-first-time/#step-3-of-12","title":"Step 3 of 12","text":"

Step 3 of 12 is Prepare your Repositories. This step has 2 Substeps.

"},{"location":"gh-actions/gh-first-time/#prepare-your-repositories","title":"Prepare your Repositories","text":""},{"location":"gh-actions/gh-first-time/#substep-31-for-step-3","title":"Substep 3.1 for Step 3","text":"

Next section, Create Match-Secrets, is Substep 1 of 2 for Step 3. This is done only one time for a given GitHub username.

"},{"location":"gh-actions/gh-first-time/#create-match-secrets","title":"Create Match-Secrets","text":"Section Summary (click to open/close)

The creation of the Match-Secrets repository is a common step for all GitHub Browser Builds; do this step only once. You must be logged into your GitHub account.

Click on the link to create a new empty repository titled Match-Secrets. It should be private.

Once created, you will not take any direct actions with this repository; it needs to be there for GitHub to use as you progress through the steps.

To skip the detailed instructions, click on Fork LoopWorkspace

Open your github.com URL (this is https://github.com/username), (username is the name you chose above).

Create a new private repository - you can either click on the link below or follow the instructions with the first graphic:

or

This shows you a screen similar to the following graphic which has 3 regions highlighted:

A screen will appear with a lot of options - do not do anything on this screen.

You will not directly interact with your Match-Secrets repository.

"},{"location":"gh-actions/gh-first-time/#substep-32-for-step-3","title":"Substep 3.2 for Step 3","text":"

Next section, Fork LoopWorkspace, is Substep 2 out of 2 for Step 3.

If you are creating an app other than the Loop app, you substitute the appropriate URL for the app you are building.

"},{"location":"gh-actions/gh-first-time/#fork-loopworkspace","title":"Fork LoopWorkspace","text":"Section Summary (click to open/close)

Fork https://github.com/LoopKit/LoopWorkspace into your account.

To skip the detailed instructions, click on Configure Secrets

Existing Fork

If you already have a fork of LoopWorkspace, click on Already Have LoopWorkspace to decide what to do. That section provides links to return you to these instructions.

  1. Open this link https://github.com/LoopKit/LoopWorkspace to open the LoopWorkspace repository owned by LoopKit.
  2. Review the highlighted locations of the graphic below (yours won't look quite like this yet, but the Fork button is in the same place)
  3. At the upper right side of the screen, click on the word Fork
    • If you already have a fork, you cannot proceed, see Already Have LoopWorkspace

  4. Now your screen should look like the graphic below

    • Your username will be automatically filled in as the owner (Owner)
    • LoopWorkspace is the repository name (Repository Name)
    • Leave the selection that says \"Copy the main branch only\" checked
    • Click on the green Create fork button

"},{"location":"gh-actions/gh-first-time/#successful-fork","title":"Successful Fork","text":"

After creating the \u00a0fork, your screen should be similar to the next graphic - it will say main for the branch instead of dev because this graphic was prepared before the release of Loop 3. You may or may not see the messages you are told to dismiss in the next two bullets. No worries if you don't see them.

Carefully compare your screen to the graphic below paying attention to the highlighted sections.

Time for a Break?

This is a good place to pause if you need to. Just note where you are on the page so you can return later.

"},{"location":"gh-actions/gh-first-time/#step-4-of-12","title":"Step 4 of 12","text":"

Step 4 of 12 is Configure Secrets. This step does not have Substeps, however, you must enter all 6 SECRETS.

Feeling confident? Planning to build more than one app? Click to see more.

If you are already feeling overwhelmed - skip this tip.

If you plan to build more that one app, you will making a fork of each repository associated with each app, and then you must add the 6 Secrets to each repository. It is not hard but it can get tiresome.

There is a way to enter the 6 Secrets only one time for all your repositories, but this requires setting up a free GitHub organization. This is also not hard, but it modifies some of displays you see on GitHub. If you are interested, refer to Use a GitHub Organization Account

"},{"location":"gh-actions/gh-first-time/#configure-secrets","title":"Configure Secrets","text":"Section Summary (click to open/close)

These Secrets are the same for any repository for which you use GitHub Browser Build.

For each of the following Secrets, tap on \"New repository secret\", then add the name of the secret, along with the value you recorded for it:

To skip the detailed instructions, click on Validate Secrets.

Branches and Repositories

"},{"location":"gh-actions/gh-first-time/#prepare-to-enter-secrets","title":"Prepare to Enter Secrets","text":"

Log into GitHub.

  1. Return to your forked copy of LoopWorkspace

    • Click on your personal icon at the upper right to see the drop-down menu and select \"Your repositories\"

  2. You should see (at least) 2 repositories: Match-Secrets and LoopWorkspace

  3. Click on LoopWorkspace to open that repository

  4. Click on the Settings Icon near the top right of your LoopWorkspace

    • If you don't see \u2699\ufe0f Settings, make your browser wider or scroll to the right
    • If you still don't see \u2699\ufe0f Settings, then you are not on your fork or you need to sign in to your GitHub account

    • After you click on \u2699\ufe0f Settings, your screen should look like the graphic below

  5. On the left side, find the Secrets and variables dropdown and choose Actions

    • After you select Actions, your screen should look like the graphic below

"},{"location":"gh-actions/gh-first-time/#enter-the-secrets","title":"Enter the Secrets","text":"
  1. Tap on the green button at the top right of your screen labeled New repository secret (highlighted above)
    • A new screen appears as shown in the first graphic below
    • Do not do anything until reading the sub-bullets, examining the graphics, and proceeding to the next section where each Secret name is provided for you to copy and paste
      • Under Name *, click on YOUR_SECRET_NAME and paste one of the 6 secret names, as directed in Enter Each Secret
      • Click inside the Secret * box and paste the value for that secret
      • Once you click on Add Secret, the secret will be added
      • The second graphic below shows TEAMID added and ready for save
"},{"location":"gh-actions/gh-first-time/#enter-each-secret","title":"Enter Each Secret","text":"

Enter the name of each Secret found in Save Your Information and your value for that Secret.

You can copy the names of the Secrets by hovering to the right of each word below until you see the copy button (). Click on the button to copy the Secret name and paste it into GitHub where you see YOUR_SECRET_NAME. This avoids spelling errors. 

TEAMID\n
FASTLANE_ISSUER_ID\n
FASTLANE_KEY_ID\n
FASTLANE_KEY\n
GH_PAT\n
MATCH_PASSWORD\n

Once all six Secrets have been added to your LoopWorkspace, your screen should look similar to the graphic below.

Time for a Break?

This is a good place to pause if you need to. Just note where you are on the page so you can return later.

"},{"location":"gh-actions/gh-first-time/#step-5-of-12","title":"Step 5 of 12","text":"

Step 5 of 12 is Validate Secrets. This step has 2 Substeps.

"},{"location":"gh-actions/gh-first-time/#substep-51-for-step-5","title":"Substep 5.1 for Step 5","text":"

Next section, First Use of Actions Tab, is Substep 1 out of 2 for Step 5. This is done only once for a given repository.

"},{"location":"gh-actions/gh-first-time/#first-use-of-actions-tab","title":"First Use of Actions Tab","text":"

Near the top middle of your LoopWorkspace fork\u00a0 is an Actions tab. This section provides detailed directions to enable Actions.

Click on the Actions tab of your LoopWorkspace repository.

The workflows are now displayed on the left side as shown in the graphic below. (Dismiss the Actions Enabled message using the X near the upper right side if it appears).

"},{"location":"gh-actions/gh-first-time/#substep-52-for-step-5","title":"Substep 5.2 for Step 5","text":"

Next section, Validate Secrets, is Substep 2 out of 2 for Step 5. This should only be needed one time, unless you modify any of your Secrets.

"},{"location":"gh-actions/gh-first-time/#validate-secrets","title":"Validate Secrets","text":"Section Summary (click to open/close)

This step validates most of your six Secrets and provides error messages if it detects an issue with one or more.

  1. Click on the \"Actions\" tab of your LoopWorkspace repository and enable workflows if needed
  2. On the left side, select 1. Validate Secrets.
  3. On the right side, click \"Run Workflow\", and tap the green Run workflow button.
  4. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.
  5. The workflow will check if the required Secrets are added and that they are correctly formatted. If errors are detected, please check the run log for details.

To skip the detailed instructions, click on Add Identifiers

Near the top middle of your LoopWorkspace fork, click on the Actions tab.

Refer to the graphic below for the numbered steps:

  1. Click on the Actions tab of your LoopWorkspace repository
  2. On the left side, click on 1. Validate Secrets
  3. On the right side, click Run Workflow to show a drop-down menu
    • You will see your default branch (typically this is main)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says Run workflow.

The Validate Secrets Action\u00a0 should succeed or fail in a few minutes. Do not continue to the next step until this one succeeds.

"},{"location":"gh-actions/gh-first-time/#step-6-of-12","title":"Step 6 of 12","text":"

Step 6 of 12 is Add Identifiers. This step has no Substeps.

This should only be needed one time, unless the developers add or modify an identifier.

For example going from version 3.2.x to version 3.3 or higher requires this to be repeated. There will be clear instructions on to update page when you need to do this.

"},{"location":"gh-actions/gh-first-time/#add-identifiers","title":"Add Identifiers","text":"Section Summary (click to open/close)
  1. Click on the \"Actions\" tab of your LoopWorkspace repository.
  2. On the left side, select \"2. Add Identifiers\".
  3. On the right side, click \"Run Workflow\", and tap the green Run workflow button.
  4. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.

To skip the detailed instructions, click on Configure Identifiers for Loop.

Refer to the graphic below for the numbered steps:

  1. Click on the Actions tab of your LoopWorkspace repository
  2. On the left side, click on 2. Add Identifiers
  3. On the right side, click Run Workflow to show a drop-down menu
    • You will see your default branch (typically this is main)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says Run workflow.

The Add Identifiers Action\u00a0 should succeed or fail in a few minutes. Do not continue to the next step until this one succeeds.

"},{"location":"gh-actions/gh-first-time/#step-7-of-12","title":"Step 7 of 12","text":"

Step 7 of 12 is Configure Identifiers for Loop. This step has 2 Substeps, some of which may not be required but are numbered so you can check them off.

This should only be needed one time, unless the developers add or modify an identifier.

For example going from version 3.2.x to version 3.3 or higher requires this to be repeated. There will be clear instructions on to update page when you need to do this.

"},{"location":"gh-actions/gh-first-time/#configure-identifiers-for-loop","title":"Configure Identifiers for Loop","text":"

Some steps can be skipped if you previously built the Loop app with a Mac using Xcode.

Please read carefully to avoid confusion.

"},{"location":"gh-actions/gh-first-time/#substep-71-for-step-7","title":"Substep 7.1 for Step 7","text":"

Next section, Create App Group, is Substep 1 out of 2 for Step 7. This is only required one time and can be skipped if you previously built this app with Xcode.

"},{"location":"gh-actions/gh-first-time/#create-app-group","title":"Create App Group","text":"Section Summary (click to open/close)

If you have already built the Loop app via Xcode using this Apple ID, skip ahead to Previous Xcode Builders.

  1. Go to Register an App Group on the Apple Developer site.
  2. For Description, use \"Loop App Group\".
  3. For Identifier, enter \"group.com.TEAMID.loopkit.LoopGroup\", substituting your team id for TEAMID.
  4. Click \"Continue\" and then \"Register\".

To skip the detailed instructions, click on Add App Group to Identifiers

The Loop App Group already exists if you previously built the Loop app using Xcode with this Apple Developer ID. In that case, skip ahead to Previous Xcode Builders.

If you have never built the Loop app with Xcode using your TEAMID, you need to create an App Group associated with your TEAMID.

  1. Open this link: Register an App Group on the Apple Developer site.
  2. For Description, use Loop App Group.
  3. For Identifier, enter group.com.TEAMID.loopkit.LoopGroup, substituting your team id for TEAMID.
  4. Double-check the spelling - your TEAMID must be correct and the Loop App Group must match the format shown in the previous step
    • A mistake here means you will not be able to build the Loop app until you fix it
  5. Click Continue and then Register.
"},{"location":"gh-actions/gh-first-time/#identifiers-for-the-loop-app-32x-and-before","title":"Identifiers for the Loop app (3.2.x and before)","text":"

If you ever built the Loop app using Mac, skip ahead to Previous Xcode Builders.

"},{"location":"gh-actions/gh-first-time/#new-builders","title":"New Builders","text":"

Click this link: Certificates, Identifiers & Profiles: Identifiers List on the Apple Developer site.

If you never built using Xcode, then after the Add Identifiers Action, you will see the six items under NAME in the table below with the associated IDENTIFIER information. Your Developer ID replaces the TEAMID in the identifier.

Skip ahead to Table with Name and Identifier for Loop 3.

"},{"location":"gh-actions/gh-first-time/#previous-xcode-builders","title":"Previous Xcode Builders","text":"

Click this link: Certificates, Identifiers & Profiles: Identifiers List on the Apple Developer site.

Because you built the Loop app using Xcode, then the NAME associated with at least the Loop identifier will appear as XC com.TEAMID.loopkit.Loop under the NAME column. Ignore the NAME column and key off what you see under the IDENTIFIER column of the table. Only the six listed in the table below need to appear when building Loop 3.

"},{"location":"gh-actions/gh-first-time/#table-with-name-and-identifier-for-loop-3","title":"Table with Name and Identifier for Loop 3","text":"NAME IDENTIFIER Loop com.TEAMID.loopkit.Loop Loop Intent Extension com.TEAMID.loopkit.Loop.Loop-Intent-Extension Loop Status Extension com.TEAMID.loopkit.Loop.statuswidget Small Status Widget com.TEAMID.loopkit.Loop.SmallStatusWidget WatchApp com.TEAMID.loopkit.Loop.LoopWatch WatchAppExtension com.TEAMID.loopkit.Loop.LoopWatch.watchkitextension

Loop dev Builders

The name and identifier for \"Small Status Widget\" has been renamed to \"Loop Widget Extension\". This only affects those using the dev branch until the next release. At that time, this table will be updated.

If you are building with the dev branch, follow the directions at One-Time Changes.

"},{"location":"gh-actions/gh-first-time/#substep-72-for-step-7","title":"Substep 7.2 for Step 7","text":"

Next section, Add or Review Configuration for Loop Identifier, is Substep 2 out of 2 for Step 7.

This should only be needed one time, unless the developers add or modify an identifier.

For example going from version 3.2.x to version 3.3 or higher requires this to be repeated. There will be clear instructions on to update page when you need to do this.

"},{"location":"gh-actions/gh-first-time/#add-or-review-configuration-for-loop-identifier","title":"Add or Review Configuration for Loop Identifier","text":"Section Summary (click to open/close)

Note 1 - If you previously built with Xcode, the Names listed below may be different, but the Identifiers will match. A table was provided above that lists both Names and Identifiers. The Add Identifier Action that you completed above generates 6 identifiers, but only 4 need to be modified as indicated in this step.

Note 2 - Depending on your build history, you may find some of the Identifiers are already configured - and you are just verifying the status; but in other cases, you will need to configure the Identifiers.

  1. Go to Certificates, Identifiers & Profiles on the Apple Developer site.
  2. For each of the following identifier names:
    • Loop
    • Loop Intent Extension
    • Loop Status Extension
    • Small Status Widget (released code) / Loop Widget Extension (dev branch)
  3. Click on the identifier's name.
  4. On the \"App Groups\" capabilities, click on the \"Configure\" button.
  5. Select the \"Loop App Group\"
  6. Click \"Continue\".
    • For the Loop Identifier only, you must add a check box next to Time Sensitive Notifications
    • This is only required for released code, it is automatically selected for the dev branch
  7. Click \"Save\".
  8. Click \"Confirm\".
  9. Remember to do this for each of the identifiers above.

To skip the detailed instructions, click on Create Loop App in App Store Connect

Find and click on the row for the Loop identifier on the Certificates, Identifiers & Profiles: Identifiers List page. Look in the IDENTIFIER column to find com.TEAMID.loopkit.Loop. The name in the NAME column may be different than Loop.

NAME IDENTIFIER Loop com.TEAMID.loopkit.Loop

The Edit Your App ID Configuration screen will open. Take two actions for the Loop identifier.

  1. In the App Services column, scroll down to the App Groups row
    • Ensure the check box (under the Capabilities column) for App Groups is checked
    • (XC Loop) - If the word Edit shows up under NOTES, move on to step 2 below
    • If the word Configure shows up, tap on it
      • This opens the App Group Assignment screen
      • Check the box by Loop App Group that uses your TEAMID in group.com.TEAMID.loopkit.LoopGroup and then Continue

  2. Continue scrolling down to the Time Sensitive Notifications row

    • Make sure the box next to Time Sensitive Notifications is checked as shown in the following graphic
    • This is only needed for the Loop identifier

  3. Now scroll slowly back up to the top of the page. As you go, confirm that each of these is configured with a check mark; if any are missing, click to enable.

    • Time Sensitive Notifications
    • Siri (formerly known as SiriKit)
    • Push Notifications
    • HealthKit
    • App Groups (enabled with group.com.TEAMID.loopkit.LoopGroup)

If you modified settings for an identifier, the Save button at the top right will become active. Click on Save before leaving this page - otherwise, the change does not take effect.

If you did not need to make changes, the Save button will not be active.

The full list of Identifiers should be displayed again.

"},{"location":"gh-actions/gh-first-time/#add-app-group-to-identifiers","title":"Add App Group to Identifiers","text":"

You will now be checking the status for 3 more identifiers to ensure the App Group is configured to use the Loop App Group. You must add or confirm the App Group for these 3 identifiers (for released code):

NAME IDENTIFIER Loop Intent Extension com.TEAMID.loopkit.Loop.Loop-Intent-Extension Loop Status Extension com.TEAMID.loopkit.Loop.statuswidget Small Status Widget com.TEAMID.loopkit.Loop.SmallStatusWidget

Double-check when finished with this step

When you think you have completed this step, double check to make sure all 4 Identifiers listed in the table have the App Group added.

If not, Create Certificates will succeed but Build Loop will fail.

"},{"location":"gh-actions/gh-first-time/#building-dev-branch","title":"Building dev branch?","text":"

If you are building the dev branch, the Small Status Widget was renamed. Look for it and add the App Group to it now.

NAME IDENTIFIER Loop Widget Extension com.TEAMID.loopkit.Loop.LoopWidgetExtension"},{"location":"gh-actions/gh-first-time/#back-to-how-to-instruction-for-main-or-dev","title":"Back to How-to Instruction for main or dev","text":"

Find and click on a given identifier row on the Certificates, Identifiers & Profiles: Identifiers List page.

The Edit Your App ID Configuration screen will open. Take one action for each of these three identifiers.

Looking at the App Services column, scroll down to the App Groups row

If you had to modify a given identifier, the Save button at the top right will become active

If you did not need to make changes, the Save button will not be active.

The full list of Identifiers should be displayed again.

"},{"location":"gh-actions/gh-first-time/#step-8-of-12","title":"Step 8 of 12","text":"

Step 8 of 12 is Create Loop App in App Store Connect. This step has no Substeps. It is only required one time.

If you are building other apps using this page as a guide, you must complete this step one time for each app.

"},{"location":"gh-actions/gh-first-time/#create-loop-app-in-app-store-connect","title":"Create Loop App in App Store Connect","text":"Section Summary (click to open/close)

If you have created a Loop app in App Store Connect before, skip ahead to Create Certificates.

  1. Click on the link apps list to open App Store Connect and click the blue \"plus\" icon to create a New App.
    • Select \"iOS\".
    • Select a name: this will have to be unique, so you may have to try a few different names here, but it will not be the name you see on your phone, so it's not that important.
    • Select your primary language.
    • Choose the bundle ID that matches com.TEAMID.loopkit.Loop, with TEAMID matching your team id.
    • SKU can be anything; e.g. \"123\".
    • Select \"Full Access\".
  2. Click Create

You do not need to fill out the next form. That is for submitting to the app store.

To skip the detailed instructions, click on Create Certificates.

If you have created a Loop app in App Store Connect before, skip ahead to Create Certificates.

If you have previously used some kind of remote build, like diawi or TestFlight, you may have your Loop in the App Store but can't see it. Don't worry - there are instructions for this case.

  1. Open this link: App Store Connect / Apps to view your apps; log in if needed.

    • If you have never added an app to App Store Connect, you will not see the icons inside the red rectangle and should keep going, although some people report the search icon shows up for them
    • If you have an app that is not shown, you will see a search icon and the All Statuses dropdown. If you get to step 3 and cannot find your com.TEAMID.loopkit.Loop in the Bundle ID drop-down, this means you need to follow Find My Loop.

  2. Click the Add Apps button or the blue \"plus\" icon ( ) and select New App as shown in the graphic below

  3. The New App dialog box opens and should appear similar to the graphic below. Before you fill anything out, make sure your Bundle ID is available in the dropdown menu (it shows as Choose in the graphic below). If you do not see com.TEAMID.loopkit.Loop, with TEAMID matching your TEAMID in the dropdown menu; back out of this screen and follow the directions in Find My Loop instead.

    • Select iOS.
    • Enter a name: this will have to be unique
      • You could start with Loop_ABC where ABC are your initials
      • If that is already taken, you can add a number, for example, Loop_ABC_123
      • This name is what you see on the App Store Connect list and in the TestFlight app
      • Once installed on your phone, you will see the Loop app with the standard Loop Logo
      • You can Change the App Store Connect Name later if you want
    • Select your primary language.
    • Choose the Bundle ID that matches com.TEAMID.loopkit.Loop
    • SKU can be anything; for example 123.
    • Select \"Full Access\".

  4. One last check - if the Bundle ID has a number other than your actual 10-digit TEAMID embedded in it, you will be creating an App in the App Store that you cannot use

    • In this case, do NOT select Create
    • Instead, go back and put the correct value into the TEAMID Secret and follow the steps in Delete Identifiers
  5. Click Create but do not fill out the next form. That is for submitting to the app store and you will not be doing that.

You are done with this activity and can close the browser tab. It's time to head back to your GitHub account and Create Certificates

"},{"location":"gh-actions/gh-first-time/#find-my-loop","title":"Find My Loop","text":"

This section is for people who were not able to follow the instructions in the last section because com.TEAMID.loopkit.Loop, with TEAMID matching your TEAMID, was not in the dropdown menu for Bundle ID.

There are two possible reasons:

  1. You did not complete Add App Group to Identifiers or one of the predecessor steps; review those steps
  2. Your app is already in App Store Connect, but you cannot see it

You may have no memory of ever setting up Loop in App Store Connect. If you previously used some kind of remote build, like diawi, your Loop may be there as a Removed App.

"},{"location":"gh-actions/gh-first-time/#step-9-of-12","title":"Step 9 of 12","text":"

Step 9 of 12 is Create Certificates. This step has no Substeps.

The next section will be required again in the future for these cases:

"},{"location":"gh-actions/gh-first-time/#create-certificates","title":"Create Certificates","text":"Section Summary (click to open/close)
  1. Go back to the \"Actions\" tab of your LoopWorkspace repository in GitHub.
  2. On the left side, select \"3. Create Certificates\".
  3. On the right side, click \"Run Workflow\", and tap the green Run workflow button.
  4. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.

To skip the detailed instructions, click on Build the Loop App

Refer to the graphic below for the numbered steps:

  1. Click on the \"Actions\" tab of your LoopWorkspace repository
  2. On the left side, click on \"Create Certificates\"
  3. On the right side, click \"Run Workflow\" to show a drop-down menu
    • You will see your default branch (typically main)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says \"Run workflow\".

  5. Wait a minute or two for the action to finish

    • If this action fails, head over to Action: 3. Create Certificates Errors
    • Once you've resolved the error, repeat the Actions Add Identifiers and then Create Certificates. (The Add Identifiers might not be required but it is fast and should be done as a matter of routine.)
"},{"location":"gh-actions/gh-first-time/#step-10-of-12","title":"Step 10 of 12","text":"

Step 10 of 12 is Build the Loop App. This step has no Substeps.

The next section is repeated every time you need to manually build. With the next release, building can be configured to be automatic, but for now, plan to run this once a month so you always have a fresh build in your TestFlight app.

"},{"location":"gh-actions/gh-first-time/#build-the-loop-app","title":"Build the Loop App","text":"Section Summary (click to open/close)
  1. Click on the \"Actions\" tab of your LoopWorkspace repository.
  2. On the left side, select \"4. Build Loop\".
  3. On the right side, click \"Run Workflow\", and tap the green Run workflow button.
  4. You have some time now. Go enjoy a coffee. The build should take about 20-30 minutes.
  5. You should get several emails
    • one says the build succeeded (or failed)
    • one says TestFlight is ready (typically half-hour after the build succeeds)
    • Ignore the one that says you need to fix \"issues\" in your app. You are not selling the app in the app store; so no action is required. The app you built is for personal use for you or a family member.
  6. Your app should eventually appear on App Store Connect.
  7. For each phone/person you would like to support:
    • Add them in Users and Access on App Store Connect.
    • Add them to your TestFlight Internal Testing group.

To skip the detailed instructions, click on Set Up Users and Access (TestFlight).

Refer to the graphic below for the first four steps:

  1. Click on the \"Actions\" tab of your LoopWorkspace repository.
  2. On the left side, click on \"4. Build Loop\".
  3. On the right side, click \"Run Workflow\" to show a drop-down menu
    • You will see your default branch (typically main)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says \"Run workflow\".

  5. Wait a few minutes to make sure there is not an early failure

    • If this action fails, head over to Action: Build Loop Errors
    • Once you've resolved the error, it's a good idea to repeat all three steps in this order:
      • Add Identifiers
      • Create Certificates
      • Build Loop
  6. If the process appears to be happening without an error, go do something else for a while. The build should take about 20-30 minutes.
  7. You should get several emails
    • one says the build succeeded (or failed)
    • one says TestFlight is ready (typically half-hour after the build succeeds)
    • Ignore the one that says you need to fix \"issues\" in your app
  8. Your app should eventually appear on App Store Connect.
"},{"location":"gh-actions/gh-first-time/#apple-email-to-ignore","title":"Apple Email to Ignore","text":"

You can ignore an email from Apple that there are things you must fix in your app:

"},{"location":"gh-actions/gh-first-time/#build-failed","title":"Build Failed?","text":"

Did you get a red X? Head over to the Errors with Browser to page find a solution.

"},{"location":"gh-actions/gh-first-time/#successful-build","title":"Successful Build","text":"

Congratulations

If you get the green check mark, your app successfully built. Just a few more steps.

"},{"location":"gh-actions/gh-first-time/#step-11-of-12","title":"Step 11 of 12","text":"

Step 11 of 12 is Set Up Users and Access (TestFlight). This step has no Substeps.

The next section is repeated if you need to add a User to your account. For example, you want to add another adult who can install the app on your child's phone or you want a spouse or friend to have a copy of the app on their phone as backup for a trip.

As a developer, you are already included as a user with the Role of Account Holder, Admin.

"},{"location":"gh-actions/gh-first-time/#set-up-users-and-access-testflight","title":"Set Up Users and Access (TestFlight)","text":"

Once the first build completes, you will be able to configure TestFlight for the app.

Add Each Users One Time

Once you add a user to have access to your TestFlight for this app, you don't need to do it again - it remains available to them across rebuilds and different versions for that app.

You are configuring a private capability for your family using an Internal Testing group. You need the Apple ID email address for each adult installing from your build. When building for a child, you will use your own Apple ID, not theirs. See TestFlight for a Child.

  1. First you need to add the email address(es) to your App Store Connect Access Users list:

    • Open this link: Users and Access
      • You must provide a role for each person - Customer Support is a good choice
      • Once you have added them here, you'll be able to select them in the TestFlight group for your app

  2. Open this link: App Store Connect / Apps to view your apps; log in if needed. Then select your Loop app. Click on the TestFlight tab then click the blue plus button () next to Internal Testing to add a group.

  3. Fill out the name you want for the Internal Testing group

    • Be sure to check the box Enable automatic distribution
    • Click Create when done (this can always be modified later)

  4. As soon as you create the group, you'll be asked who should be included

    • Click in the box beside each person you want to include
    • Each person in this group will get an email each time you update (build again) using the GitHub Browser Build method
    • Click Add when you are done
    • If building for a child, you will send the invitation to yourself because you will install for your child: See TestFlight for a Child

"},{"location":"gh-actions/gh-first-time/#step-12-of-12","title":"Step 12 of 12","text":"

Step 12 of 12 is Install on Phone. This step has no Substeps.

The next section is repeated for every phone that you want to install a given build from TestFlight. Because a TestFlight app only last 90 days, you should probably build and install at least every 60 days.

"},{"location":"gh-actions/gh-first-time/#install-on-phone","title":"Install on Phone","text":"

The Install on Phone page walks you through the steps to use the TestFlight app to install the Loop app on a phone.

But wait - there's more.

"},{"location":"gh-actions/gh-first-time/#extra-steps","title":"Extra Steps","text":"

Most people won't need the information on the rest of this page.

"},{"location":"gh-actions/gh-first-time/#already-haveloopworkspace","title":"Already Have\u00a0LoopWorkspace?","text":"

Some people may already have a copy of LoopWorkspace.

If your copy is not from LoopKit, follow the Delete and Start Fresh directions.

If your copy is from LoopKit:

"},{"location":"gh-actions/gh-first-time/#delete-and-start-fresh","title":"Delete and Start Fresh","text":"

If your fork is not from LoopKit:

"},{"location":"gh-actions/gh-first-time/#delete-identifiers","title":"Delete Identifiers","text":"

When you have already built the Loop app with Xcode, the Identifier names will not match the directions and you might have trouble deciding which ones to configure. Your existing Loop identifier will have a name that starts with XC as shown below, where your 10-digit TEAMID is used.

The Identifier that is associated with the Loop identifier cannot be deleted if it is already in the App Store but all others can. If you attempt to delete the XC Loop identifier, you may be told it cannot be deleted because it is in use in the app store. That's OK. Same for other identifiers (if you build a bunch of Apps). If a Bundle ID has ever been associated with an app in the App Store, you cannot delete the Identifier.

To make it easy when configuring the identifiers, go through and delete as many as you can.

If coming here from the Errors with Browser page because you enter the wrong TEAMID in Secrets - return to that page once you've deleted as many identifiers as you can: Errors: Wrong TEAMID in Secrets.

If you were just trying to clean up the identifiers, then follow these steps:

"},{"location":"gh-actions/gh-other-apps/","title":"Build Other Apps with Browser","text":""},{"location":"gh-actions/gh-other-apps/#build-other-apps-using-a-browser","title":"Build Other Apps using a Browser","text":"

Once Loop 3 was released with the ability to build using a browser, a lot of other apps in the DIY universe added the same feature.

Only apps that are companions to\u00a0Loop\u00a0are included on this page.

If you want to build another DIY app that is not included here, look for the file fastlane/testflight.md in the GitHub repository associated with that app and open it in a browser. The instructions for that app should be located in that file.

The same technique is used and the same six Secrets are applied to each repository. Those secrets are tied to your Apple Developer ID and your GitHub account.

"},{"location":"gh-actions/gh-other-apps/#update-to-build-with-browser-for-the-loop-caregiver-app","title":"Update to Build with Browser for the Loop Caregiver App","text":"

The Loop Caregiver App Requires an App Group

As of 2023 December 8, the updated version of the Loop Caregiver app requires the addition of an App Group to an expanded list of Identifiers.

"},{"location":"gh-actions/gh-other-apps/#optional-build-method","title":"Optional Build Method","text":"

Optional - Set up a Organization Account

If you are going to be building a lot of different apps, you can choose to set up a free organization account with GitHub and use that to build.

Pros:

Cons:

For more information, see Use a GitHub Organization Account.

"},{"location":"gh-actions/gh-other-apps/#multiple-copies-of-loop-follow","title":"Multiple Copies of Loop Follow","text":"

For the convenience of caregivers who use Loop Follow to monitor multiple people, updates were added in v2.1.2 to make this more convenient. This works regardless of the build method. (Build with Browser or Build with Mac).

"},{"location":"gh-actions/gh-other-apps/#prerequisites","title":"Prerequisites","text":"

Use the repository for the application you are building

Many graphics on this page show\u00a0LoopWorkspace, just remember to use the repository for the app you want to build, that is either\u00a0Loop Caregiver\u00a0or \u00a0Loop Follow.

"},{"location":"gh-actions/gh-other-apps/#fork-and-add-secrets","title":"Fork and Add Secrets","text":""},{"location":"gh-actions/gh-other-apps/#table-of-app-repositories","title":"Table of App Repositories","text":"App Fork from this Address Documentation Loop Caregiver https://github.com/LoopKit/LoopCaregiver LoopDocs: Loop Caregiver Loop Follow https://github.com/loopandlearn/LoopFollow Loop Follow

The two repositories below are only if you need to follow a second or third looper. All others should use just the table above. The instructions for the second and third looper are otherwise identical to the first looper. Note that LoopCaregiver can follow multiple Loopers; you select the person inside the app.

Special Case Fork from this Address Loop Follow for a Second Looper https://github.com/loopandlearn/LoopFollow_Second Loop Follow for a Third Looper https://github.com/loopandlearn/LoopFollow_Third"},{"location":"gh-actions/gh-other-apps/#update-the-repository","title":"Update the Repository","text":"

If you just created the fork, you can skip this section.

If you are returning to this page to update an app, please follow these steps. Each step has a link to instructions on the Update LoopWorkspace page. Follow the Update Fork directions for the repository of the app you are updating:

  1. Accept Agreements for the Apple Developer account
  2. Update Fork

Then return to this page.

Normally you skip ahead to Build App after an update.

If you are updating the LoopCaregiver app after the 2023 December 8 update, you need to go to Add Identifiers after updating the fork.

"},{"location":"gh-actions/gh-other-apps/#configure-secrets-for-this-app","title":"Configure Secrets for this App","text":"

If you choose to use the optional GitHub organization method, you can skip this section:

After successfully creating your fork of the repository for this app:

"},{"location":"gh-actions/gh-other-apps/#add-existing-secrets","title":"Add Existing Secrets","text":"

MATCH_PASSWORD

An early version of GitHub First-Time had incorrect information about the need to save MATCH_PASSWORD.

If you did not save your MATCH_PASSWORD in your file with all your Secrets, you will need to delete your Match-Secrets repository, create a new one and then add all your Secrets into all you repositories again and run all the Actions again.

Instructions are found at Reset Match-Secrets.

Open the text file in which you maintain a copy of your 6 Secrets so you can copy each value into the Secrets for this repository.

  1. Click on the repository for your app

  2. Click on the Settings Icon near the top right of your repository

    • On the left side, tap on Secrets and variables dropdown and choose Actions
    • After you select Actions, your screen should look like the graphic below

  3. Tap on New repository secret and add each of the 6 Secrets

    • You will notices the New secret dialog looks a little different
    • As soon as you click on the Name* Box, the 6 Secret Names may show up as a dropdown as shown in the graphic below
    • Select each one in turn and paste the secret value into the Secret* box and hit Add secret
    • If they do not appear in a dropdown, enter them exactly as shown (suggest copy / paste from your text file)

Once all six Secrets are added, proceed to the first Action to validate your secrets.

"},{"location":"gh-actions/gh-other-apps/#validate-secrets","title":"Validate Secrets","text":"

The first action step is to Validate Secrets. Near the top middle of your Repository fork, click on the Actions tab.

The workflows are now displayed: look at the list on the left side similar to that shown in the graphic below. (You can dismiss the Actions Enabled message using the X near the upper right side if it appears).

This step validates most of your six Secrets and provides error messages if it detects an issue with one or more.

  1. Click on the \"Actions\" tab of your Loop Follow or Loop Caregiverrepository and enable workflows if needed
  2. On the left side, click on 1. Validate Secrets
  3. On the right side, click Run Workflow to show a drop-down menu
    • You will see your default branch (main for LoopFollow, dev for LoopCaregiver)
    • You can select a different branch, but typically, you run the default
  4. Tap the green button that says Run workflow.

The Validate Secrets Action\u00a0 should succeed or fail in a few minutes. Do not continue to the next step until this one succeeds.

"},{"location":"gh-actions/gh-other-apps/#add-identifiers","title":"Add Identifiers","text":"

Near the top middle of your Repository fork, click on the \"Actions\" tab.

Refer to the graphic below for the numbered steps:

  1. Click on the \"Actions\" tab of your repository
  2. On the left side, click on \"Add Identifiers\"
  3. On the right side, click \"Run Workflow\" to show a drop-down menu
    • You will see your default branch (main for LoopFollow, dev for LoopCaregiver)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says \"Run workflow\"

The Add Identifier Action\u00a0 should succeed or fail in a few minutes.

"},{"location":"gh-actions/gh-other-apps/#review-app-identifier","title":"Review App Identifier","text":"

Open this link: Certificates, Identifiers & Profiles: Identifiers List on the apple developer site.

After successfully performing the Add Identifiers Action, you will see the identifier for your app with a Name and Bundle ID matching that in the table below. You will see your unique TEAMID embedded in the identifier. (If you previously built this App with Xcode, the name may start with XC but the ending should match.)

App Name Name Bundle ID Loop Caregiver LoopCaregiver com.TEAMID.loopkit.LoopCaregiver Loop Follow LoopFollow com.TEAMID.LoopFollow

If you build from a second or third repository for Loop Follow, the Name will end in Second or Third and Bundle ID will have .Second or .Third at the end.

The Loop Caregiver app requires updates to the Identifiers after they are generated.

The Loop Follow app does not require this extra step. You can skip ahead to Create App in App Store Connect.

"},{"location":"gh-actions/gh-other-apps/#add-app-group-to-loopcaregiver","title":"Add App Group to LoopCaregiver","text":"

As of 2023 December 8, the Loop Caregiver app requires the addition of an App Group to an expanded list of Identifiers. Follow these steps one time to be able to build the Loop Caregiver app after this update.

"},{"location":"gh-actions/gh-other-apps/#check-if-app-group-exists","title":"Check if App Group Exists","text":"

Open this link to view your applicationGroup Identifiers: App Group Identifiers

"},{"location":"gh-actions/gh-other-apps/#create-app-group-for-the-loop-caregiver-app","title":"Create App Group for the Loop Caregiver App","text":"

Open this link: Register an App Group on the Apple Developer site.

  1. For Description, use LoopCaregiver App Group
  2. For Identifier, enter group.com.TEAMID.loopkit.LoopCaregiverGroup, substituting your team id for TEAMID.
  3. Double-check the spelling - your TEAMID must be correct and the LoopCaregiverGroup App Group must match the format shown above
    • A mistake here means you will not be able to build the LoopCaregiver app until you fix it
  4. Click Continue and then Register.
"},{"location":"gh-actions/gh-other-apps/#add-app-group-to-identifiers","title":"Add App Group to Identifiers","text":"

Click to open this link in a new tab: Certificates, Identifiers & Profiles: Identifiers List on the Apple Developer site.

"},{"location":"gh-actions/gh-other-apps/#table-with-name-and-identifier-for-loopcaregiver","title":"Table with Name and Identifier for LoopCaregiver","text":"

All five of these identifiers should be found after running the Add Identifier action on GitHub.

If you do not see them, please sync your LoopCaregiver repository and then run the Add Identifier action. The NAME might begin with an XC if you previously built with Xcode. However, the IDENTIFIER column value should match.

NAME IDENTIFIER LoopCaregiver com.TEAMID.loopkit.LoopCaregiver LoopCaregiverIntentExtension com.TEAMID.loopkit.LoopCaregiver.IntentExtension LoopCaregiverWatch com.TEAMID.loopkit.LoopCaregiver.watchkitapp LoopCaregiverWatchWidgetExtension com.TEAMID.loopkit.LoopCaregiver.watchkitapp.WidgetExtension LoopCaregiverWidgetExtension com.TEAMID.loopkit.LoopCaregiver.WidgetExtension"},{"location":"gh-actions/gh-other-apps/#add-loopcaregivergroup-to-each-identifier","title":"Add LoopCaregiverGroup to each Identifier","text":"

Find and click on the row for the LoopCaregiver on the Certificates, Identifiers & Profiles: Identifiers List page. Look in the IDENTIFIER column to find com.TEAMID.loopkit.LoopCaregiver. The NAME might begin with an XC if you previously built with Xcode. However, the IDENTIFIER column value should match.

NAME IDENTIFIER LoopCaregiver com.TEAMID.loopkit.LoopCaregiver

The Edit Your App ID Configuration screen will open.

  1. In the App Services column, scroll down to the App Groups row
    • Ensure the check box (under the Capabilities column) for App Groups is checked
    • Tap on the word Edit or Configure, whichever shows up
      • This opens the App Group Assignment screen
      • Check the box by LoopCaregiver App Group that uses your TEAMID in group.com.TEAMID.loopkit.LoopCaregiver
      • If the box by Loop App Group is checked, you should uncheck it
      • If you made any changes, tap Continue, otherwise, tap Cancel

If you modified settings for an identifier, the Save button at the top right will become active. Click on Save before leaving this page - otherwise, the change does not take effect.

If you did not need to make changes, the Save button will not be active.

The full list of Identifiers should be displayed again.

Continue down the list until every identifier in the table below has the App Group for LoopCaregiver App Group added to it. (DO NOT SELECT the Loop App Group) If you miss any, the GitHub action to 3. Create Certificates will succeed but the GitHub action to 4. Build LoopCaregiver will fail.

NAME IDENTIFIER LoopCaregiver com.TEAMID.loopkit.LoopCaregiver LoopCaregiverIntentExtension com.TEAMID.loopkit.LoopCaregiver.IntentExtension LoopCaregiverWatch com.TEAMID.loopkit.LoopCaregiver.watchkitapp LoopCaregiverWatchWidgetExtension com.TEAMID.loopkit.LoopCaregiver.watchkitapp.WidgetExtension LoopCaregiverWidgetExtension com.TEAMID.loopkit.LoopCaregiver.WidgetExtension"},{"location":"gh-actions/gh-other-apps/#create-app-in-app-store-connect","title":"Create App in App Store Connect","text":"

You will be following the directions below to create an App in App Store Connect if you don't already have one.

This requires you to provide some information. Examine the table below for the bundle ID associated with your app.

App Name Bundle ID Loop Caregiver com.TEAMID.loopkit.LoopCaregiver Loop Follow com.TEAMID.LoopFollow

If you build from a second or third repository for Loop Follow, the Bundle ID will have .Second or .Third at the end.

  1. Open this link: App Store Connect / Apps to view your apps; log in if needed.

  2. If this App already exists, you can continue to Create Certificates

  3. Click the Add Apps button or the blue \"plus\" icon and select New App as shown in the graphic below

  4. The New App dialog box opens and should appear similar to the graphic below. Before you fill anything out, make sure your Bundle ID is available in the dropdown menu. If you do not see the Bundle ID for your app; back out of this screen and follow the directions in Configure to Use Browser: Find My Loop, where you'll be finding App Name instead of Loop.

    • Select \"iOS\". For Loop Follow you can also select \"macOS\" if you own a Mac with macOS 11 or later.
    • Enter a name: this will have to be unique
      • You could start with \"App Name ABC\" where ABC are your initials
      • If that is already taken, you can add a number, for example, \"App Name ABC 123\"
      • This name is what you see on the App Store Connect list and in the TestFlight app
      • Once installed on your phone, you will see the actual app name
      • You can Change the App Store Connect Name later if you want
    • Select your primary language.
    • Choose the bundle ID for your app
    • SKU can be anything; for example \"123\" but must be unique across all your apps, so try 1234 or 12345 depending on how many apps you build with this method
    • Select \"Full Access\".

  5. Click Create but do not fill out the next form. That is for submitting to the app store and you will not be doing that.

You are done with this activity. Before you close this browser window, note the TestFlight tab at the top of the page. You'll be using that tab after you complete the next two actions.

"},{"location":"gh-actions/gh-other-apps/#create-certificates","title":"Create Certificates","text":"

Refer to the graphic below for the numbered steps:

  1. Click on the \"Actions\" tab of your Repository repository
  2. On the left side, click on \"Create Certificates\"
  3. On the right side, click \"Run Workflow\" to show a drop-down menu
    • You will see your default branch (main for LoopFollow, dev for LoopCaregiver)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says \"Run workflow\".

  5. Wait a minute or two for the action to finish

    • If this action fails, head over to Action: Create Certificates Errors
    • Once you've resolved the error, repeat the Actions Add Identifiers and then Create Certificates. (The Add Identifiers might not be required but it is fast and should be done as a matter of routine.)
"},{"location":"gh-actions/gh-other-apps/#build-app","title":"Build App","text":"

The graphic below is an example from Loop, your screen will show your app and associated repository

If you are building the Loop Caregiver app, skip ahead to Build Action.

"},{"location":"gh-actions/gh-other-apps/#display-name-customization-for-loop-follow","title":"Display Name Customization for Loop Follow","text":"

If you build Loop Follow for one, two or three loopers, you may choose to customize your fork or forks to insert a custom display name.

Continue to build as instructed below. After you install the app on your phone, iPad or Mac via TestFlight, that custom name is what is displayed. The prefix LF is suggested to make it easier to find the custom named Loop Follow app in the list of apps, but is not required.

"},{"location":"gh-actions/gh-other-apps/#build-action","title":"Build Action","text":"

Refer to the graphic below for the first four steps:

  1. Click on the \"Actions\" tab of your Repository repository.
  2. On the left side, click on \"Build App Name\".
  3. On the right side, click \"Run Workflow\" to show a drop-down menu
    • You will see your default branch (main for LoopFollow, dev for LoopCaregiver)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says \"Run workflow\".

  5. Wait a few minutes to make sure there is not an early failure

    • If this action fails, head over to Action: Build Loop Errors
    • Once you've resolved the error, it's a good idea to repeat all three steps in this order:
      • Add Identifiers
      • Create Certificates
      • Build Loop
  6. If the process appears to be happening without an error, go do something else for a while. The build should take about 20-30 minutes.
  7. Your app should eventually appear on App Store Connect.
"},{"location":"gh-actions/gh-other-apps/#add-users-to-testflight-for-app","title":"Add Users to TestFlight for App","text":"

Once the first build completes, you will be able to configure TestFlight for the app - follow the template for setting up TestFlight for Loop found in Configure to Use Browser: Set Up Users and Access (TestFlight).

"},{"location":"gh-actions/gh-other-apps/#install-on-phone","title":"Install on Phone","text":"

The Install on Phone walks you through the steps to install the app to a phone. When going through those steps, replace your App Name for\u00a0Loop. Everything else is the same.

"},{"location":"gh-actions/gh-other-apps/#use-a-github-organization-account","title":"Use a GitHub Organization Account","text":"

This section is optional. It is provided to assist:

"},{"location":"gh-actions/gh-other-apps/#set-up-a-free-github-organization","title":"Set up a Free GitHub Organization","text":"

Prerequisite: You need a personal GitHub account.

In the instructions below, use your GitHub username instead of my-name.

  1. Follow the directions below to create a new GitHub organization account with a username of my-name-org (of course naming is up to you)
    • There is documentation at this link, New GitHub Organization, or you can follow the bullets below
    • Log into my-name and click on your icon (at upper right) and choose Settings
    • On the left side-bar, click on Organizations
    • In the new view, click on New Organization and choose Free for the plan by clicking on Create a free organization.
    • In the Set up your organization screen:
      • Enter my-name-org into the Organization name box
      • Enter the same email you use for my-name account
      • Select this organization belongs to My personal account
      • Check the box to accept the terms of service
      • Tap on the next button
  2. You now see a Welcome screen
    • Unless you plan to collaborate with others, just tap Complete setup
    • You can always add others at a later time
  3. Confirm access by entering the same password as you use for my-name
GH_PAT comes from personal my-name account

The GitHub personal access token used as one of the 6 Secrets is associated with your personal account (my-name); so if you already have one, you just keep using it.

"},{"location":"gh-actions/gh-other-apps/#use-the-free-github-organization","title":"Use the Free GitHub Organization","text":"

There are three steps to using this account moving forward:

  1. One-time only: You need to add your 6 Secrets to this organization account (instructions are in next section)

  2. One-time only: Create a Match-Secrets repository in the my-name-org account

    • Start out at the top-level of your organization (github.com/my-name-org)
    • Click on Repositories
    • Click on New repository
    • Choose my-name-org as owner and enter Match-Secrets as the name
    • Make sure to choose Private and tap on the Create button
    • If you want to see graphics for the steps above, refer to the instructions written for a personal (instead of organization) account in Create Match-Secrets

  3. For each repository: you need to fork for each app you wish to build to the new my-name-org account

    • When you do the fork, there will be a drop-down menu under Owner for you to select the account for the fork
    • Choose the organization account
    • Other than that extra step, follow the standard fork directions
      • This link provides instructions to Fork LoopWorkspace
      • Refer to the Table of App Repositories when building apps other than the Loop app

Then, for every build, you will use just the organization account. The original account is maintained to give you access to GitHub and holds your GitHub personal access token.

WARNING - If you have forks of DIY apps in your original my-name account that are configured to build automatically, you want to disable that and have only the my-name-org account be configured for automatic building. Refer to Disable Building for Personal GitHub account.

"},{"location":"gh-actions/gh-other-apps/#add-secrets-to-your-github-organization","title":"Add Secrets to your GitHub Organization","text":"

Adding the Secrets to an organization is similar to adding them to each repository for a personal GitHub account. The difference is you add them at the organization level and then they are available to each repository in that organization.

Follow the directions below to prepare to add secrets to the organization and then skip (when provided the link) to the per-repository directions for more details about adding each secret.

Make sure you are in the organization for GitHub:

The GitHub personal access token used as one of the 6 Secrets is associated with your personal account (my-name); so if you already have one, you just keep using it. If not, follow these instructions to get or configure a new one.

"},{"location":"gh-actions/gh-other-apps/#disable-building-for-personal-github-account","title":"Disable Building for Personal GitHub account","text":"

Once you have your apps building as you expected from the my-name-org organization account, you should configure your personal account to stop any automatic building that may be taking place.

"},{"location":"gh-actions/gh-other-apps/#option-1-delete-repository","title":"Option 1: Delete repository","text":"

You can delete the DIY repositories from your personal account

"},{"location":"gh-actions/gh-other-apps/#option-2-disable-build-action","title":"Option 2: Disable Build Action","text":"

You can disable the build actions from the repositories in your personal account

"},{"location":"gh-actions/gh-overview/","title":"Browser Overview","text":""},{"location":"gh-actions/gh-overview/#build-with-a-browser","title":"Build with a Browser","text":""},{"location":"gh-actions/gh-overview/#advantages-of-building-with-a-browser","title":"Advantages of Building with a Browser","text":""},{"location":"gh-actions/gh-overview/#considerations-for-building-with-a-browser","title":"Considerations for Building with a Browser","text":""},{"location":"gh-actions/gh-overview/#requirements","title":"Requirements","text":"

To build the\u00a0Loop\u00a0app using a browser, you need:

  1. Free GitHub account (instructions included in Configure to use Browser)
  2. Apple Developer Membership
    • Must be a paid developer account
    • If building for a family member, review this section:
      • Loopers Need Their Own Apple ID
    • If building for a child (age depends on the country), review this section:
      • TestFlight for a Child

Once you have the\u00a0Loop\u00a0app in TestFlight, you need:

  1. Compatible iPhone
  2. Compatible Pump
  3. Compatible CGM
  4. RileyLink Compatible Device (not needed for Omnipod DASH)
"},{"location":"gh-actions/gh-overview/#configuration-to-build-with-a-browser","title":"Configuration to Build with a Browser","text":"

Steps that must be completed to configure for building with a browser are found at:

This is a very long page because there are a lot of steps and each step is explained with graphics of what you will see when you work through the steps.

"},{"location":"gh-actions/gh-overview/#how-to-video-to-build-with-a-browser","title":"How-to Video to Build with a Browser","text":"

In addition to the webpage linked above, there is a narrated video of each step needed to build using a browser.

Click in the comments for a full index of topics. If you have issues with a step, use the index to advance to the relevant part of the video. Subtitles are in English. You can choose a different language but the automatic translation feature may provide translations that are not completely accurate.

"},{"location":"gh-actions/gh-overview/#install-on-phone","title":"Install on Phone","text":"

Instructions to install on your phone are found at:

"},{"location":"gh-actions/gh-overview/#update-the-app","title":"Update the App","text":"

Instructions to make updates are found at:

There is also a helpful video for this process:

"},{"location":"gh-actions/gh-overview/#errors-while-building","title":"Errors while Building","text":"

If you get an error, please consult:

"},{"location":"gh-actions/gh-overview/#building-the-development-version-of-the-app","title":"Building the Development Version of the App","text":"

For experienced and/or advanced users who want to build the development version of the app, there is additional information at the link below. If you have not built using the browser build method before, it is suggested you first build the released version. Once you have a successful build, then follow the steps for the development version. Building the app is independent of installing the app on your phone from TestFlight.

"},{"location":"gh-actions/gh-overview/#what-if-i-get-stuck","title":"What if I get stuck?","text":"

Try to:

"},{"location":"gh-actions/gh-update/","title":"Update/Rebuild with Browser","text":""},{"location":"gh-actions/gh-update/#overview","title":"Overview","text":"

This page is only relevant when building with a browser.

For Mac, please see: Update/Rebuild with Mac

Time Estimate (click to open/close)

Build the Loop App

Once a Year Renew Certificate

Page Summary (click to open/close)

The Loop app must be built at least every 90 days when you build with a browser - this is TestFlight requirement.

Most users will start at How to Update or Rebuild.

If your GitHub Personal Access Token has expired, we recommend you update it with No Expiration as explained at GitHub Token.

If you are running Loop-dev, be sure to review these instructions but modify for the branch you are using: refer to Build Loop dev with Browser

FAQs (click to open/close) "},{"location":"gh-actions/gh-update/#when-to-update-or-rebuild","title":"When to Update or Rebuild","text":"

Under ordinary circumstances, you do not have to rebuild or update your Loop app until TestFlight forces you to (90 days). However, there is no harm in building more frequently.

"},{"location":"gh-actions/gh-update/#how-to-update-or-rebuild","title":"How to Update or Rebuild","text":"

Summary of Update Steps

  1. Accept Agreements
  2. Renew Certificate (once a year)
  3. Update Fork
  4. Build the Loop App
  5. Wait for TestFlight
  6. Install on Phone

Ignore the email that says you need to fix \"issues\" in your app. You are not selling the app in the app store; so no action is required. The app you built is for personal use for you or a family member.

There is also a helpful video for updating (it does not include the Renew Certificates step, which is only done once a year):

"},{"location":"gh-actions/gh-update/#accept-agreements","title":"Accept Agreements","text":"

This is Step 1 of 6 - it may not always be necessary, but please check every time.

Sign in to your Apple Developer account. If there are agreements you have not accepted, you will get errors when you try to Build that indicate your Apple Secrets are incorrect - that is very unlikely. You may also need to update your credit card information if it has changed, for example, if there is a new expiration date.

If you need detailed instructions, click on this Apple Program License Agreement Help Page.

Wait After You Agree

It typically takes 15 minutes before your updated agreement is available so you can complete your build.

If your build with browser fails, wait longer. An hour wait was reported by one person.

"},{"location":"gh-actions/gh-update/#renew-certificate","title":"Renew Certificate","text":"

This is Step 2 of 6 - it is only needed once a year - you should get an email from Apple 30 days before your Distribution Certificate expires. (Don't worry if you did not see the email.)

Apps in TestFlight are not affected when a certificate expires or is revoked.

Do you want to know more? (Click to open/close)

This is only a summary - please follow the detailed steps below carefully.

"},{"location":"gh-actions/gh-update/#manual-steps-to-renew-your-distribution-certificate","title":"Manual Steps to Renew Your Distribution Certificate","text":"

Delete and Create

Do not miss the final step in this section. After you delete certificates, you must run the Action for Create Certificates before you can build an app again.

  1. Use this link to view your Apple Developer Certificates
    • If your screen shows no Certificates and you see a message \"Getting Started with Certificates\", your certificate already expired and was removed by Apple; so skip ahead to Step 2: Navigate to your Match-Secrets Repository
    • Carefully examine the Type column - do not delete a Development Certificate
      • If you do not have any rows that say Distribution Certificate, your certificate already expired and was removed by Apple; so skip ahead to Step 2
      • If your certificate has an expiration date several months in the future - you can wait and renew your certificate later; skip ahead to Update Fork
    • Click each row that has a Distribution Certificate and revoke it
    • You will get an email informing you the certificate was revoked

  2. Navigate to your Match-Secrets Repository

    • You can do this several ways, but one method is demonstrated by the GIF below
    • Open the URL for your GitHub account (address is https://github.com/username where username is replaced by your GitHub username
    • Click on the Repositories Tab
    • Select Match-Secrets

  3. Delete the certs/distribution folder of your Match-Secrets repository using these instructions. The GIF below indicates the places to click with numbered red rectangles:

    • Frame 1: Click 1 on the folder called certs/distribution
    • Frame 2: Click 2 and 3 on the three dots in the upper right and then Delete directory
    • Frame 3: Click 4 and 5 on Commit changes in the upper right and then accept the suggested choice by clicking on Commit changes in the lower right

    Deleting the certs/distribution folder did not work for me

    Some people reported trouble with this step. The other option is to delete and create a new Match-Secrets repository: see Reset Match-Secrets

  4. While still within your Github account, navigate to your fork of LoopWorkspace.

    • You can do this several ways, but one method is demonstrated by the GIF below
    • Click on your username and then Repositories and select LoopWorkspace
    • Once you are on your LoopWorkspace repository, click on the link below and follow the instructions provided to create your certificates.
    • Run the Action: Create Certificates

Other Apps

If you build other apps using the build with browser method, they have just had their certificates revoked.

"},{"location":"gh-actions/gh-update/#update-fork","title":"Update Fork","text":"

This is Step 3 of 6 - it may not always be necessary, but please check every time.

Open your GitHub account and select your LoopWorkspace repository from your repositories list.

Building a different branch

Do I need to do anything special to build a different branch?

Yes: please follow instructions at Build Development Version

"},{"location":"gh-actions/gh-update/#build-the-loop-app","title":"Build the Loop App","text":"

This is Step 4 of 6 - this is always required.

Refer to graphic below as you follow the steps to build the Loop app.

"},{"location":"gh-actions/gh-update/#what-if-the-build-fails","title":"What if the Build Fails","text":"

If a new release is announced at Current Release, look to see if there are instructions about extra steps required with the release. (The release after 3.2.3 will certainly have extra instructions.)

If you are using the dev branch, head over to Build Development Version for information.

Otherwise, head over to Errors with Browser.

"},{"location":"gh-actions/gh-update/#apple-email-to-ignore","title":"Apple Email to Ignore","text":"

You can ignore an email from Apple that there are things you must fix in your app:

"},{"location":"gh-actions/gh-update/#wait-for-testflight","title":"Wait for TestFlight","text":"

You'll receive an App Store Connect email confirming that the build has completed processing, and a TestFlight email confirming the new app is ready to test.

"},{"location":"gh-actions/gh-update/#install-the-loop-app-on-the-phone","title":"Install the Loop app on the phone","text":"

This is Step 6 of 6 - once you finish this, you are done and your app will last 90 days.

Open the TestFlight app on the Loopers phone and install the most recent version of the Loop app. Most Loopers have automatic update disabled on their phones, so this is a manual process. Don't forget.

The updated Loop app will show up in your TestFlight app on the Looper's phone.

Calendar Reminder

This is a good time to put a calendar reminder in your favorite app.

Set it up for a few days before the TestFlight app will expire.

"},{"location":"gh-actions/gh-update/#automatic-update-disabled","title":"Automatic Update Disabled","text":"

Option 1: If you chose to Disable Automatic Install from TestFlight, you control when to install the app on the phone.

"},{"location":"gh-actions/gh-update/#automatic-update-enabled","title":"Automatic Update Enabled","text":"

We strongly recommend you toggle off Automatic Updates to allow you to be in full control over when the app is updated. This is even more important if you're using automatic builds from GitHub for version 3.3 or later.

Option 2: If you chose to enable Automatic Updates from TestFlight for the Loop app, the updated build will be installed over your existing app as soon as it uploaded to TestFlight.

"},{"location":"gh-actions/gh-update/#choose-previous-build","title":"Choose Previous Build","text":"

If you are a typical user who just builds a single version for yourself or your child, you do not need to read this section.

This section provides detailed instructions if you want to choose a previous build to install on your phone. Typically, the most recent build is selected but there may be special cases:

This section covers two topics.

  1. Optional: Add Test Details to the TestFlight build
  2. Select a Previous Build
"},{"location":"gh-actions/gh-update/#add-test-details","title":"Add Test Details","text":"

About half an hour after the build action completes, the new build will appear in the TestFlight screen at this link: App Store Connect / Apps

Select the build to which you wish to add testing notes. When you tap on that icon, it opens a screen similar to that in the next graphic.

Click inside the box under Test Details. Insert the text you want to see on the phone before you install this version of the app. Tap the Save button at upper right and then < iOS Builds at upper left.

In this example, the branch and commit number are included followed by an indication that this version includes the customizations preferred by this person. Your test details can be as simple as \"Use this for Charlie\".

Commit Number

If your build includes customizations, your commit number will not match what the developer expects to see if you need to ask for help.

Use this section Customization and SHA-1 to determine the SHA-1 before customization.

"},{"location":"gh-actions/gh-update/#select-a-previous-build","title":"Select a Previous Build","text":"

First open the TestFlight app on your phone and select the Loop app.

Near the bottom of the screen is a row labeled previous builds.

The following graphic shows the view seen in the TestFlight app on the phone. By adding test details (as explained in the previous section), the desired build is clear. For most people - they will just use the most recent build. This procedure is useful for those who build often or who support multiple family members.

"},{"location":"gh-actions/gh-update/#the-loop-app-build-details","title":"The Loop App Build Details","text":"

In the Loop app, once installed on your phone, tap on Settings -> Support -> Issue Report. The graphic below shows an example of the Build Details included in the report.

"},{"location":"gh-actions/gh-update/#github-token","title":"GitHub Token","text":"

Your GitHub Personal Access Token should be configured:

If you are not logged in to GitHub and have not logged in recently, then you may see the authentication screen when doing the steps below.

Authenticate if requested by clicking on the green Send SMS button or entering your password.

Once you are authenticated, you will have access to view your personal access token.

"},{"location":"gh-actions/gh-update/#modify-personal-access-token","title":"Modify Personal Access Token","text":"

If your Personal Access Token has not expired but does not have the correct permission, you should modify it. Do not regenerate it.

Click on the link to view your token and compare it to the graphic below.

The graphic above has a blue rectangle added to indicate where you should see your token. If yours does not look like this, click on the link (FastLane Access Token) to open a new display. Watch the GIF below - there are 4 frames, the last one has the Update token button.

  1. Click on the link (FastLane Access Token) to open a new display
  2. This example has no workflow or repo checks in it
  3. Add a check to the workflow box
  4. Scroll all the way to the bottom of the screen and click on the green Update token button

After you click on the Update token button, your FastLane Access Token should now show repo, workflow and look like the earlier graphic above.

The only reason to regenerate a token is if it is set to expire. Do not do the next section unless you have to.

"},{"location":"gh-actions/gh-update/#regenerate-token","title":"Regenerate Token","text":"

If your Personal Access Token has expired or has an expiration date, you can regenerate the new one at any time.

Update new GH_PAT to Secrets

After you get your new token, immediately add it to your Secrets for any app you build with this method. You don't have to rebuild the app, but it's a good idea to at least run Action 1. Validate Secrets for each repository to make sure you did not make a mistake.

You can regenerate your GitHub Personal Access Token at any time by clicking on the link below. (it will open in a new browser tab.)

The FastLane Access Token is a clickable link.

After you click on FastLane Access Token your screen should be similar to the graphic below.

Your existing TestFlight builds are fine

The yellow GitHub warning by the Regenerate Token button is for new builds you make in the future.

Previous builds are still available in TestFlight and are not affected by this action.

Note - selecting the workflow check box below is new. If yours does not show that selection, add it before you click on Regenerate token (red highlight in graphic below).

Click on Regenerate token (red highlight in previous graphic) to see screen similar to next graphic.

Be sure to change the Expiration from 30 days to No Expiration. When you select No Expiration a GitHub warning appears. Click on the green Regenerate Token button (red highlight in following graphic).

The next screen shows your new token. Copy the token using the copy icon and save it along with your other secret settings.

The next step is to update GH_PAT in your Secrets. (If you build other apps with this method - update the GH_PAT for all of them right now - do not forget.)

"},{"location":"gh-actions/gh-update/#update-secrets","title":"Update Secrets","text":"

This example is for updating GH_PAT in the Secrets for your repository, but the same method can be applied when changing any of the Secrets.

Open the repository for which you will update Secrets. On the far right is a Settings selection. If you don't see Settings (if last item on row is Insights), then you are not on your fork or you need to sign in to your GitHub account. You should see username/LoopWorkspace with forked from LoopKit/LoopWorkspace underneath.

Refer to the GIF for help. There are 3 frames.

  1. Tap on Settings, then scroll down until you see Secrets and variables on the left side and click on the drop down indicator to display Actions.
  2. Keep scrolling on the same screen, past the Action secrets / New repository secret row, until you see the list of your current Secrets.
  3. Click on the GH_PAT, tap on the pencil and enter the new token in the form. Click on Update Secret to complete the action.

Scroll all the way to the top of the screen and tap on your LoopWorkspace link. Then follow the How to Update or Rebuild instructions to start a new build.

"},{"location":"gh-actions/gh-update/#build-development-version","title":"Build Development Version","text":"

The information to build a development (dev or any other branch) has been moved to a new page: Build dev with Browser

"},{"location":"intro/loopdocs-how-to/","title":"LoopDocs How-to","text":""},{"location":"intro/loopdocs-how-to/#how-to-find-help","title":"How to Find Help","text":"

Volunteers generously provide support for Loop via online platforms. You have several options for joining conversations on Loop and asking for help. Links to the main platforms are listed below. Non-US Loop users in Italy, Australia, and several other countries have also formed Facebook (FB) groups.

"},{"location":"intro/loopdocs-how-to/#how-to-ask-for-help","title":"How to Ask for Help","text":"

If you are having trouble building or using your Loop app, there are some important steps to get responses to your question, while also being considerate of our volunteers' time.

  1. Always search in both LoopDocs and your favorite support group.
    • Confused about how to search in a Facebook group? Here is a video to help.
  2. If you use Facebook, click on the Featured posts (at the top of the page); many posts asking for help are already answered there.
  3. Don't post a duplicate question in multiple groups (mentors monitor many groups). Only post to a different group if you have had no responses for several hours.
  4. If a LoopDocs search, FB or Zulipchat search, and a check of Looped Group featured posts pinned to the top of the page haven't answered your question, then post for help. Review the tips for how to post for help so that our volunteers get all the information they'll need to help you, without needing to ask 40 questions first.
  5. Leave your question posted even after you've gotten an answer, but edit the original post to add the word RESOLVED at the beginning of the original post.
    • This helps other Loopers who have the same question
    • This helps mentors know they don't need to respond to help you
"},{"location":"intro/loopdocs-how-to/#how-to-use-loopdocs","title":"How to use LoopDocs","text":""},{"location":"intro/loopdocs-how-to/#website-short-cuts","title":"Website Short Cuts","text":"

One of our awesome Loop volunteers captured the domain names loopdocs.org and looptips.org. So you can find these valuable websites by simply typing loopdocs or looptips followed by .org in your browser. In other words, you don't need to remember or type https://loopkit.github.io/loopdocs/.

"},{"location":"intro/loopdocs-how-to/#website-navigation","title":"Website Navigation","text":"

There are a lot of links you can click on this website.

If you click on the link, you are moved to the new location and must hit the back button on your browser to return.

You can choose to open that link in a new window or new tab.

Keyboard Navigation

When viewing the site at a computer, you can use keys as shortcuts:

The website navigation depends on whether you are on a mobile device or a computer (with browser width > 1220 pixels).

"},{"location":"intro/loopdocs-how-to/#website-search","title":"Website Search","text":"

It is not uncommon to have a question about Loop. But, it is exceptionally rare to have the question not already answered in LoopDocs, so please search for answers by selecting the Search tool (upper right) or typing s then a search term at a computer. As you begin to type, suggested completions and links to pages are displayed. Click on the item you think answers your question.

"},{"location":"intro/loopdocs-how-to/#how-to-improve-loopdocs","title":"How to Improve LoopDocs","text":"

Please submit suggestions for updates and improvements to this documentation. There are many pages of content and we welcome reviewers to help find typos and outdated info/links. If you notice a typo, poor word choice or some explanation that could be improved or clarified, there are a few options. The first two options use github, a website where open-source code and documentation is often shared. You can only use github if you have an account (it's free).

  1. You can issue a Pull Request (best option if it is a simple typo or wording update)
  2. You can open an Issue (best option if a major rewrite is needed or you think a conversation would help), or
  3. You can post on Facebook or Zulipchat
"},{"location":"intro/loopdocs-how-to/#pull-requests-and-issues","title":"Pull Requests and Issues","text":"

If you decide to do a GitHub Pull Request (PR) or create an Issue, first look to see if someone has already opened a PR or Issue on the topic so you don't create a duplicate.

"},{"location":"intro/loopdocs-how-to/#facebook-or-zulipchat","title":"Facebook or Zulipchat","text":"

Helpful tips for providing LoopDocs feedback through Facebook and/or Zulipchat:

"},{"location":"intro/overview-intro/","title":"LoopDocs Overview","text":"

Take a deep breath

It is totally understandable if the thought of building and operating your own\u00a0Loop\u00a0app feels intimidating.

As you learn the information explained in\u00a0LoopDocs, this will start feeling more comfortable.

"},{"location":"intro/overview-intro/#loopdocscontents","title":"LoopDocs\u00a0Contents","text":"

The\u00a0LoopDocs\u00a0website is organized as follows

"},{"location":"intro/overview-intro/#using-links","title":"Using Links","text":"

You will notice many links in the LoopDocs pages pointing to detailed information.

"},{"location":"intro/overview-intro/#using-tooltips","title":"Using Tooltips","text":"

The LoopDocs pages contain words that may be unfamiliar. For a definition of any word with a dashed underline, simply hover your mouse over the word, or tap on the word on a mobile device, to view the definition. For example, Omnipod has a tooltip.

Every tooltip definition is also found in the Glossary - so head over there if you have trouble reading a tooltip.

"},{"location":"intro/overview-intro/#buildingloop","title":"Building\u00a0Loop","text":"

The process for building the\u00a0Loop\u00a0app is divided into short segments (sections or pages) in the Build tabs of\u00a0LoopDocs.

Best Practice: Learn to Build

You are strongly encouraged to build\u00a0Loop\u00a0for yourself.

"},{"location":"intro/overview-intro/#use-a-simulator","title":"Use a Simulator","text":"

You can build\u00a0Loop\u00a0and practice with a simulated phone, CGM and/or pump. You can \"dose\" the simulated pump and your real pump at the same time and watch the glucose predictions.

Starting with a simulator can help you decide if you want to move forward with purchasing additional items required to use the app. You can:

Locked Phone or App in Background

Do not expect the simulator to work when the phone is locked or the app is in the background. The app relies on a real insulin pump or a real CGM to wake up the app when the phone is locked or the app is in the background. The simulator cannot do this.

Please review Simulator Build for more information.

"},{"location":"intro/overview-intro/#operatingloop","title":"Operating\u00a0Loop","text":"

A significant amount of content is provided on this website and via link to other sources.

Please review these pages when initially setting up and learning to use\u00a0Loop.

Some techniques are specific to\u00a0Loop, but the general concepts of how man-made insulin works and strategies to test basal, carb ratios and insulin sensitivity apply to all the hybrid closed-loop systems, commercial and open source.

"},{"location":"intro/overview-intro/#development-history","title":"Development History","text":"

Loop\u00a0is an open-source, shared project. The entire project has been, and continues to be, done by volunteers. From the code to the website, you're getting all this because dozens of volunteers have given their time, so please add your time by reading this website thoroughly before embarking on your\u00a0Loop\u00a0journey.

Here are development history links to other resources for you to explore.

"},{"location":"intro/requirements/","title":"Requirements Overview","text":""},{"location":"intro/requirements/#two-ways-to-build-the-app","title":"Two Ways to Build the App","text":"

With the release of\u00a0Loop 3\u00a0, there are two ways to build the app.

The Build Steps have been split into two tabs:

There are some requirements common to both methods. Some requirements are specific to only one method.

"},{"location":"intro/requirements/#common-requirements","title":"Common Requirements","text":"

These requirements are independent of how you build the Loop app:

  1. Compatible iPhone
  2. Compatible Pump
  3. Compatible CGM
  4. RileyLink Compatible Device
    • Not needed with Omnipod DASH
    • Required for Medtronic and Omnipod Eros
  5. Apple Developer Membership
    • If building for a child, be sure to read Loopers Need Their Own Apple ID
    • Build with Browser - requires a paid developer account
    • Build with Mac - can build a free version with some limitations and must rebuild weekly
"},{"location":"intro/requirements/#added-requirements-to-build-with-browser","title":"Added Requirements to Build with Browser","text":"

If you plan to build using the Build with Browser instructions, you also need:

  1. A free GitHub account

Detailed instructions are included in the link above.

"},{"location":"intro/requirements/#added-requirements-to-build-with-mac","title":"Added Requirements to Build with Mac","text":"

If you plan to build using the Build with Mac instructions, you also need:

  1. Compatible Computer
  2. Xcode (a free Apple application)
"},{"location":"intro/requirements/#getting-ready-to-build","title":"Getting Ready to Build","text":"

Go through the Common Requirements to see what you need to actually Loop.

Simulator Option

If you want to test the Loop app without attaching CGM or pump hardware, you can run a simulated CGM or simulated pump. You can use actual CGM data using Dexcom Share or Nightscout as a Remote CGM.

These simulators are part of the Loop app and are available with either build method you choose.

Check out the Simulator page.

Once you have chosen your Build Method, go through the pages for that build method several times before beginning, especially if this is new to you.

When you are ready to proceed, work through the tasks on each page. Take your time. You can do one a day, take a week per page or blaze through them quickly. Just be sure to read carefully and if you are confused - reach out for help: How to Find Help.

After you build Loop on your phone, keep following along in the docs as you Set up and Operate your Loop app.

"},{"location":"intro/requirements/#next-steps","title":"Next Steps:","text":""},{"location":"intro/requirements/#review-the-common-requirements","title":"Review the Common Requirements","text":"

Before you start either build method, review the Common Requirements. First one is Compatible iPhone. On each page, keep clicking Next (or n) until you've finished with the Intro pages and are ready to Build.

"},{"location":"intro/requirements/#build-with-browser","title":"Build with Browser","text":"

Click on the link if you are done reviewing the common requirements and you want to skip ahead to Build with Browser.

"},{"location":"intro/requirements/#build-with-mac","title":"Build with Mac","text":"

Click on the link if you are done reviewing the common requirements and you want to skip ahead to Build with Mac.

"},{"location":"loop-3/add-cgm/","title":"Add CGM","text":""},{"location":"loop-3/add-cgm/#cgm-choices","title":"CGM Choices","text":"

A CGM can be added from the Heads-Up-Display (HUD) or from the Loop Settings screen \u2699\ufe0f.

The HUD will look like the graphic below if no CGM or Pump is connected with Loop:

Loop can be connected to the following CGMs:

"},{"location":"loop-3/add-cgm/#add-cgm","title":"Add CGM","text":"

To add a CGM, go to the Settings screen \u2699\ufe0f, tap on Add CGM, and tap on your CGM.

If you later decide to use a different CGM type, you must first delete the CGM and then add CGM to choose the new one.

Set up Focus Mode

Don't forgot to check your iOS Focus Notifications when you add or change your CGM.

"},{"location":"loop-3/add-cgm/#remote-upload-from-loop","title":"Remote Upload from Loop","text":"

Loop provides an option to upload CGM values to a remote service like Nightscout or Tidepool. In many cases this can be a preferred solution.

With Loop 3, the data-store on the Loop phone keeps a full week of data. If there is an interruption in the upload, when it is restored, Loop will fill in up to 1-week of CGM data that was not previously uploaded.

Some people use Dexcom Share to feed their remote services. There have been outages with Share. When those occur, the data is not back-filled like it is with Loop.

This is the reason why there's a comment under each CGM below to select Upload Readings.

"},{"location":"loop-3/add-cgm/#dexcom-g5-g6-one","title":"Dexcom G5, G6, ONE","text":"

To use the Dexcom G5, G6 or ONE:

"},{"location":"loop-3/add-cgm/#where-to-get-the-transmitter-id-for-dexcom-g6","title":"Where to get the Transmitter ID for Dexcom G6?","text":"

You can find the transmitter ID in your Dexcom G6 app or on the back of the transmitter box (please refer to the below screenshots).

It is suggested that you enable Remote Upload from Loop.

"},{"location":"loop-3/add-cgm/#change-dexcom-sensor","title":"Change Dexcom Sensor","text":"

When you change a Dexcom G5, G6 or ONE sensor, you do this in the Dexcom app. When the sensor completes warmup and CGM values are once again reported in the Dexcom app, Loop picks these values up because you are using the same Dexcom Transmitter.

"},{"location":"loop-3/add-cgm/#change-dexcom-transmitter","title":"Change Dexcom Transmitter","text":"

When you change the Dexcom G5, G6 or ONE Transmitter, you need to delete your CGM selection from Loop and then add it back after you complete the pairing with the transmitter in your Dexcom app.

FYI: When You Change Dexcom Transmitters (click to open)

Before you change Dexcom transmitters, select the Delete CGM button at the very bottom of the CGM info page in Loop. If you leave the transmitter connected in Loop, you may have trouble pairing your new transmitter. If pairing does work, then Loop will not get CGM data from the Dexcom app on your phone.

Follow the instructions here: What do I do when I switch Dexcom transmitters?.

The Dexcom G7 is handled differently - Loop automatically detects when a new sensor/transmitter pair is added to the Dexcom G7 app.

Your selection to enable Remote Upload from Loop must be repeated with each new Transmitter. The default setting is disabled.

"},{"location":"loop-3/add-cgm/#about-dexcom-share-credentials","title":"About Dexcom Share credentials","text":"

You do NOT need your Share account info listed in Loop settings if you are using a G5 or G6 system. The transmitter ID is sufficient. In fact, you should leave your Share credentials blank so that you don't accidentally become internet-dependent for CGM data if you forget to update your transmitter ID when you start a new transmitter.

"},{"location":"loop-3/add-cgm/#dexcom-g7","title":"Dexcom G7","text":"

This is only available on Loop 3.

You must have the G7 app on the same phone as Loop. When the G7 app switches to the next sensor/transmitter assembly, Loop automatically switches too.

It is suggested that you enable Remote Upload from Loop.

Don't forget Health Permissions

For those switching from Dexcom G6 to Dexcom G7, you might forget to add permission for the G7 app to write to Apple Health. If you want long-term history of those CGM readings to persist in Apple Health, turn on the permission for the Dexcom app to write glucose to Health.

If either the G6 or the G7 has permission to write to Apple Health, then Loop will delete the Loop glucose data in Apple Health that are older than 3 hours and newer than 1 week. The Dexcom app will write its glucose values to Health when each value is 3 hours old.

"},{"location":"loop-3/add-cgm/#medtronic-enlite-cgm","title":"Medtronic Enlite CGM","text":"

The Medtronic Enlite CGM is only available if you have connected it to your compatible Medtronic Pump.

"},{"location":"loop-3/add-cgm/#dexcom-share-as-a-cgm","title":"Dexcom Share as a CGM","text":"

If you need to use Dexcom Share

If the dexcom is on another phone, you can use Share if internet / cell coverage is good.

Dexcom Share is not available for Dexcom ONE CGM.

The Dexcom Share credentials (in other words, account login) is the same as what you used to log in to the active Dexcom app on your iPhone. Dexcom Share account is not always the same login info as your Dexcom Clarity account. The information is entered when you first log in to the app and then is never displayed again, nor visible under any information screens. If you have forgotten your G5/G6 account info, you can delete the Dexcom app and redownload it to try logging in again. This will not cause a restart of any sensor sessions in progress.

If you do not enter your Share credentials correctly into Loop, you will get an error when Loop tries to access your Share account to backfill CGM data. An example of the error message is shown in the graphic below. If you see that message, delete your Share account from Loop settings and try again.

"},{"location":"loop-3/add-cgm/#nightscout-remote-cgm","title":"Nightscout Remote CGM","text":"

If the user is already uploading CGM data to their Nightscout URL, they can select that as a source for CGM data for Loop. The user must acknowledge they understand the risks of using a remote source that requires internet, as shown in the graphic below.

In addition to the risks of missing data if the internet is not reliable, you must also make sure the CGM data sent to Nightscout is reliable.

DANGER - Make sure Nightscout CGM Data is Reliable

Just because you can use Nightscout as a CGM source does not mean you should.

If you decide to use Nightscout as a CGM source, make sure the data stored in Nightscout is reliable. If the app you choose uploads bad results to Nightscout, you don't want Loop to use that bad data.

Sensors that can be added to Nightscout via other apps include Dexcom, some Libre and some Medtronic sensors. Please refer to Nightscout Docs: Configure your Uploader.

There are third party apps that bring Libre data to your Loop phone and there are customization instructions starting at Libre Support for Loop 3.2.x Code that explain how to modify Loop 3 to use one of those apps. Please use these steps to get a version of Loop that does not rely on internet access to work.

It is suggested that you use Open Loop during warmup until the new sensor begins to provide reasonable data. This is especially important with European Libre 2 using direct bluetooth connection.

The xDrip4iOS app (which can also be found in the app store under the name Shuggah) may have a problem during warmup of a new sensor (European Libre 2 using direct bluetooth connection). There were two instances of crazy high values being reported and picked up by Loop 3. One Shuggah user and one xDrip4iOS user who connected via Nighscout as a CGM with Loop 3 had serious overdose of insulin because of bad readings with a new sensor. The developers of xDrip4iOS fixed their application - so make sure you have the latest version. Those developers have no control over what is provided by Shuggah.

The user must enter both the URL and API_SECRET for their site to ensure the security of the data. The URL must start with https:// and cannot have any extra spaces in the line.

When using Nightscout Remote CGM, if the user needs to change credentials or switch to a different CGM, the user must go through the Loop->Settings \u2699\ufe0f->CGM menu.

"},{"location":"loop-3/add-cgm/#change-cgm","title":"Change CGM","text":"

To change CGMs, delete your existing CGM and then add a new CGM.

"},{"location":"loop-3/add-cgm/#change-a-nightscout-remote-cgm","title":"Change a Nightscout Remote CGM","text":"

For Nightscout Remote CGM, the Nightscout URL is opened when tapping on the CGM icon in the Heads-Up Display, while the credential sections with the Delete CGM row are shown when tapping on Loop Settings \u2699\ufe0f, and selecting CGM.

After deleting a CGM, the Head-Up-Display at the top of the Loop main screen will show the Add CGM icon.

"},{"location":"loop-3/add-cgm/#change-other-cgm","title":"Change Other CGM","text":"

Other CGM, you can tap on the CGM from either the Heads-Up Display or tap on Settings \u2699\ufe0f, and select your CGM.

Scroll to the bottom of the screen and select Delete CGM.

For some CGM that can be added to Loop 3 with a patch, the words may be different, but the steps are the same.

"},{"location":"loop-3/add-cgm/#dexcom-g5-g6-and-one-not-g7","title":"Dexcom G5, G6 and One (not G7)","text":"

For older Dexcom sensors, the transmitter is replaced separately about once every three months. In order to enter a new transmitter number, you must first delete the CGM and then add the CGM.

Detailed instructions are found at CGM FAQs: What do I do when I switch Dexcom transmitters?.

Once the Dexcom G7 has been added to Loop, the user only needs to let the Dexcom G7 app know when to use the new sensor. The Loop app automatically switches to the new sensor with no additional steps required by the Looper.

"},{"location":"loop-3/add-pump/","title":"Add Pump","text":""},{"location":"loop-3/add-pump/#pump-choices","title":"Pump Choices","text":"

You can choose a pump from the Heads-Up-Display (HUD) or from the Loop Settings screen.

The HUD looks like the graphic below if no CGM or Pump is chosen:

Switching Pumps?

To change the pump connected to Loop go to Change Pump Type.

Loopers can choose from 3 pumps and a simulator:

Omnipod Terms

The Loop app and LoopDocs use these terms:

"},{"location":"loop-3/add-pump/#summary-of-steps-to-add-a-pump","title":"Summary of Steps to Add a Pump","text":"

Here is an overview of the different steps for adding each pump. Before changing pumps, you need to delete the old pump first. See Change Pump Type section below.

"},{"location":"loop-3/add-pump/#steps-for-omnipod","title":"Steps for Omnipod","text":"
  1. Omnipod Common 1 (choose default notifications)
  2. Insulin Type
  3. Select RileyLink
  4. Omnipod Common 2 (Pair Pod)
"},{"location":"loop-3/add-pump/#steps-for-omnipod-dash","title":"Steps for Omnipod DASH","text":"
  1. Omnipod Common 1 (choose default notifications)
  2. Insulin Type
  3. Omnipod Common 2 (Pair Pod)
"},{"location":"loop-3/add-pump/#steps-for-medtronic","title":"Steps for Medtronic","text":"
  1. Insulin Type
  2. Select RileyLink
  3. Medtronic
"},{"location":"loop-3/add-pump/#add-pump","title":"Add Pump","text":"

Tap on Add Pump in the Settings screen to see pump options (shown in the graphic below).

Tap on your Pump.

Medtronic pump users - skip ahead to Insulin Type.

"},{"location":"loop-3/add-pump/#omnipod-common-1","title":"Omnipod Common 1","text":""},{"location":"loop-3/add-pump/#pod-nofication-defaults","title":"Pod Nofication Defaults","text":"

Here are the common screens for adding Omnipod or Omnipod DASH showing the default settings. You can change the default settings later.

After you complete these screens, you select the insulin type.

"},{"location":"loop-3/add-pump/#insulin-type","title":"Insulin Type","text":"

For all pumps, you can choose from the insulin types below.

To add a Omnipod DASH pump, skip ahead to Omnipod Commom 2.

Omnipod and Medtronic users should continue to select a RileyLink compatible device.

"},{"location":"loop-3/add-pump/#omnipod-or-medtronic","title":"Omnipod or Medtronic","text":""},{"location":"loop-3/add-pump/#select-rileylink","title":"Select RileyLink","text":"

For Omnipod and Medtronic pumps, you need a RileyLink compatible device to Loop. The Device and your phone must be kept close to your pump for Loop to work.

A new RileyLink compatible device is not listed next to its slider until after you connect the device to Loop. Find the little toggle in the device list, switch on that toggle, and the RileyLink will appear after the toggle is green.

You can personalize the name once it is connected to Loop.

All RileyLink compatible devices in the nearby area, not already connected to a Loop app, will display in the RileyLink Setup screen. Select your RileyLink by sliding the toggle to display green and then press the blue Continue button at the bottom of the screen.

If your device does not appear:

If you are adding a Medtronic pump, skip ahead to Medtronic.

"},{"location":"loop-3/add-pump/#omnipod-common-2","title":"Omnipod Common 2","text":"

After selecting a RileyLink for Omnipod, all other actions for Omnipod and Omnipod DASH are the same. Once a pod is paired, the Pump display is the same, except the Omnipod screen has a RileyLink Devices section.

For Omnipod (left) and Omnipod DASH (right), you should see the Pair Pod screen.

At this point - you should hit Cancel (upper right of screen) and review the Omnipod Common page before pairing a pod.

New Looper / New Podder

Carefully review the Pair Pod instructions and the rest of the Omnipod Common page before continuing. Then, when you are ready, pair a pod.

If you are not ready to fill and attach a pod with insulin, try filling a pod with water and let it drip into a ziplock bag to test running Loop on the pod. (Be sure the pod is not near anything when you hit \"Insert Cannula\".)

You may enjoy reading Rufus the Bear.

"},{"location":"loop-3/add-pump/#medtronic","title":"Medtronic","text":"

If you followed this page to add your Medtronic pump, you have completed the first three steps. If not, you can prepare your pump now, then do those first three steps using Loop (follow the links). All other steps be completed before you Connect the Pump.

  1. Select Minimed 500/700 Series as your pump
  2. Select Insulin Type
  3. Select RileyLink
  4. Prepare Medtronic Pump
  5. Connect Pump to Loop
"},{"location":"loop-3/add-pump/#prepare-medtronic-pump","title":"Prepare Medtronic Pump","text":"

Loop requires these settings on your Medtronic pump.

Check with your users guide (can be found online if you don't have one) for more detailed instructions on your model of pump if you're not sure how to accomplish these steps.

If you have basal rates, insulin to sensitivity factor and carb ratios in your pump - these will be overwritten (using the Therapy Setting values) when you connect your pump to Loop. If those rates are important to you, record them prior to continuing.

"},{"location":"loop-3/add-pump/#connect-pump-to-loop","title":"Connect Pump to Loop","text":"

The final step is to connect your Medtronic pump to Loop.

Max setting exceeded

It turns out the \"Max setting exceeded\" error might be displayed even when Max Bolus and Max Basal Rate are already set appropriately on the pump.

"},{"location":"loop-3/add-pump/#bolus-in-progress","title":"Bolus in Progress","text":"

If you get an error Bolus in progress on the pump when trying to connect, you probably need to rewind and load insulin into the reservoir.

If the pump has alerted that it is out of insulin, you cannot pair to Loop as a new pump.

"},{"location":"loop-3/add-pump/#final-steps","title":"Final steps","text":"

Once you have successfully connected to the Medtronic pump, click on Continue:

For x23 and x54 Medtronic pump users only

For x23 and x54 Medtronic pump users, there is a packet of information special to those pumps called MySentry messages. If you have never setup this part of the pump previously, you may see a screen, called \"Pump Broadcasts\", at this point in the setup process.Follow the directions on the screen. They will require you to take some manual steps on your pump to \"pair\" it with your Loop app.Basically, you will need to go to your pump's main menu, scroll down to Utilities, then Connect Devices, then Other Devices, turn that setting On, and then select Find Device. Once you do that, click on the Continue button in Loop app and the pairing will take place. This will allow those MySentry packets of information to flow to Loop app.This step does not apply for x22 or x15 pump users, since those pumps do not have MySentry capabilities.

Now that your pump is paired with Loop, you should select the type of battery you are using and decide whether to use My Sentry:

  1. Select your pump's battery type (lithium or alakine)
    • There is a whole page about Medtronic pump batteries
  2. Leave the Preferred Data Source on Event History
  3. If you have a x23 or x54 pump, choose whether to use My Sentry (saves phone battery) or not (saves OrangeLink battery)
    • For other Medtronic pumps, adjusting this setting does not do anything

The Medtronic status and commands available are shown in the Pump Setting page.

"},{"location":"loop-3/add-pump/#change-pump-type","title":"Change Pump Type","text":"

Before changing from one pump type to another pump type, you must delete the old pump type.

The Head-Up-Display at the top of the Loop main screen will now show the add pump icon.

"},{"location":"loop-3/displays-v3/","title":"Displays","text":"

This page has detailed information about Loop 3 Displays.

If you are running Loop v2.2.x, follow this link: Loop v2.2.x Displays.

"},{"location":"loop-3/displays-v3/#main-loop-screen","title":"Main Loop Screen","text":"

The main Loop screen contains a Heads-Up Display (HUD) at the top (when in portrait mode) with various charts in the middle and a toolbar at the bottom. As part of the HUD, important messages will appear in the Status Row location.

"},{"location":"loop-3/displays-v3/#landscape","title":"Landscape","text":"

When the device is in landscape mode, the HUD is no longer visible, but the chart history is increased. In landscape, the exact number of hours varies by phone, but on my test phone, each chart displays the last 8 hours of history along with the next 6 hours of glucose prediction. The toolbar is always visible while the chart display can be scrolled up and down to view charts of interest.

"},{"location":"loop-3/displays-v3/#heads-up-display","title":"Heads-Up Display","text":"

The Heads-Up Display (HUD) shows 3 icons:

There is a Status Row underneath those three icons that is used to display bolus progress, some alerts and important messages. The Status Row is also a button that performs an action depending on the message. These are described in the table in the HUD Status Row section. The Status Row is only visible in portrait mode, so make sure to orient your device to look for these messages.

"},{"location":"loop-3/displays-v3/#charts","title":"Charts","text":"

There are several charts on the main screen to help you navigate and understand Loop. Tapping on a chart on your phone opens up additional information.

"},{"location":"loop-3/displays-v3/#glucose-chart","title":"Glucose Chart","text":"

The Glucose Chart displays glucose values in your preferred units.

mg/dL or mmol/L

If your preferred glucose unit is not selected, follow these instructions to change Glucose Units.

The vertical scale is automatically adjusted by Loop to be as useful as possible while including the highest and lowest readings in the chart.

The horizontal axis is set to go forward from the current time through your DIA (insulin duration), so you can see what Loop thinks glucose will be eventually. It then goes back in time as far as there is room, based upon the width in pixels of your screen. Note, if you turn your device to landscape mode you will have more screen real estate and thus will be able to see further back in time.

The glucose Correction Range is shown as a blue bar on the glucose chart. Single-value ranges (such as 100-100 mg/dL), will have a narrower blue bar. When a temporary override range is enabled, a darker blue bar indicates the correction range during that override.

Negative Glucose Prediction

If you have a crazy negative glucose prediction - it is likely that you set an Override with a tiny Overall Insulin Needs percentage.

Best approach:

If you tap on the Glucose Chart itself, it will open the Predicted Glucose chart described below.

"},{"location":"loop-3/displays-v3/#predicted-glucose-chart","title":"Predicted Glucose Chart","text":"

The predicted glucose view is a great way to gain insight into the various components\u2019 importance in Loop\u2019s prediction of eventual glucose.

The graph at the top of this view will match your Glucose Chart. Below this chart you will see an explanation of the variables Loop takes into account in predicting your future glucose value: Carbohydrates, Insulin, Glucose Momentum and Retrospective Correction. You can tap on any of the entries to see the effects of that component by looking at the dashed lines.

Display Only

These elements are not turned on and off in the Loop predictions. They just modify the graph so you can view the relative effects.

"},{"location":"loop-3/displays-v3/#active-insulin-chart","title":"Active Insulin Chart","text":"

The Active Insulin chart displays the total insulin contribution from both temp basals and boluses. Active IOB can be either positive or negative. Negative IOB results from the suspension of normally scheduled basals.

The active insulin displayed in the upper right corner of the chart updates as soon as Loop issues a command to your pump.

It may later be modified and the Event History updated if:

There are some times when communication is interrupted at a critical moment in the communication cycle. When that happens the Loop Alert - Unable to Reach Pump modal screen appears on your device. Typically, this resolves by itself. Click the link above for more information.

Medtronic Only: So long as you have Event History as the Preferred Data Source in Loop settings, primed insulin deliveries (e.g., cannula fills or manual primes) will not be counted towards IOB.

"},{"location":"loop-3/displays-v3/#insulin-delivery-chart","title":"Insulin Delivery Chart","text":"

The Insulin Delivery chart displays a history of the temp basals enacted by Loop. The display is relative to the scheduled basal rates entered in the Loop settings. So, a rate displayed in this chart as +0 units would indicate no temp basal was set, and Loop defaulted to the scheduled basal rate. Individual boluses are indicated by an orange triangle on the chart (shown in the graphic above, near the left-most time). The total insulin delivered since midnight, including all basals and boluses AND (Medtronic Only) priming insulin, is given in the upper right corner of the graph.

Please note that for safety reasons, Loop will assume a bolus was successful, even if it is not sure that the pump responded as expected. Once the communications with the pump settle down, Loop will (almost always) be able to reconcile whether a dose went through as expected. Occasionally, the bolus may be temporarily rendered (drawn) as a very high temp basal rate vs. a (triangle) discrete bolus event. This does NOT mean that the Loop actually enacted a high temp basal rate...only that the bolus is being drawn on the chart as the equivalent of a high temp basal rate.

"},{"location":"loop-3/displays-v3/#event-history-reservoir-and-non-pump-insulin","title":"Event History, Reservoir and Non-Pump Insulin","text":"

Clicking on either the Active Insulin or Insulin Delivery charts will open your Insulin Delivery history. The top of the screen will display the current IOB and the total insulin delivered for the day since midnight (or since the time the loop became active if you started Loop after midnight). There are three tabs that can be viewed, with Event History shown by default:

Previous Pod Insulin History

For those who want to delete some recorded insulin near the end of a pod because the site was not absorbing properly, this can be done in Apple Health.

Before attempting that modification, please read this entire section on How does Loop use Apple HealthKit in detail.

Pay special attention to Insulin and Apple HealthKit section.

"},{"location":"loop-3/displays-v3/#active-carbohydrates-chart","title":"Active Carbohydrates Chart","text":"

The Carbohydrate chart displays the carbs used by Loop to predict glucose changes. The active COB is displayed in the upper right corner of the chart. Clicking on the chart will open the Carb Entries history and you can edit/delete any previous entries through that screen. Please read the Meal Entry page for more information about entering and editing carb entries.

"},{"location":"loop-3/displays-v3/#ice-chart","title":"ICE Chart","text":"

Click this link for even more details about Insulin Counteraction Effects. It's a good idea to read both the Meal Entry and ICE pages - this is an important concept.

"},{"location":"loop-3/displays-v3/#toolbar","title":"Toolbar","text":"

The toolbar is always found at the bottom of the main Loop screen in both portrait and landscape orientation. By tapping on one of these icons, you can begin a Meal Entry, start a Pre-Meal Range, initiate a Manual Bolus, select an Override or go to the Loop Settings screen.

From left to right, the icons are:

"},{"location":"loop-3/displays-v3/#hud-details","title":"HUD Details","text":"

Very Detailed Section

This section is packed with an incredible amount of detail. Remember it exists and come back when you need a reference to Loop 3 icons and messages.

If you are a new looper your eyes may glaze over the first time through. Don't worry. But do come back and read this section again after you've used the system in Open Loop mode (before you enable Closed Loop mode). And then come back again after a day or so of closed loop testing.

Experienced loopers need to read the detail on this page. There are important changes from Loop 2.2.x.

The Heads-Up-Display, visible in portrait mode, shows the Glucose Status on the left, the Loop Status in the middle and the Pump Status on the right. Once a CGM and pump have been added to Loop, the Loop Status icon will update and ideally be similar to the graphic below.

"},{"location":"loop-3/displays-v3/#loop-status-icon","title":"Loop Status Icon","text":"

The Loop Status Icon is the colored circle in the center of the main Loop display. The three colors displayed are Green, Yellow or Red. In all cases, more information is displayed by tapping on the Loop Status Icon, which brings up a modal message indicating the last time a loop cycle completed and other descriptive text.

"},{"location":"loop-3/displays-v3/#loop-cycle","title":"Loop Cycle","text":"

A complete Loop cycle, at high level, includes these steps:

This table shows examples of Loop Status Icons and what each icon means.

Icon Meaning A green circle indicates the app is in Closed Loop mode and it completed a cycle within the last 5 minutes. A yellow circle indicates the app is in Closed Loop mode and it has completed a cycle in the last 5-15 minutes.It is not unusual to have a few instances of yellow loops per day. They can be caused by being out of range (physically), Bluetooth or RileyLink \u201cnoise\u201d interference, or even that the pump was giving a bolus.Most yellow loops will self-resolve without needing any special troubleshooting. A red circle indicates the Loop has not completed in over 15 minutes.This is not a typical state, and you should troubleshoot the problem.In this case, either the Glucose Icon or the Pump Icon or both will display an alert graphic. When the circle is open at the top, Loop is operating in \u201copen-loop\u201d mode. The color code is the same as for closed loop except the cycle involves updating predictions from available blood glucose values and obtaining pump status; but the app will not make any automated changes in insulin delivery.While Manual Temp Basal (MTB) is active, the Open Loop icon will be displayed until MTB expires or is cancelled. Note that MTB is only implemented in Loop 3 for Omnipod and Omnipod DASH, at the current time.

Fun Fact

The loop status icon will pulse slightly when Loop is communicating with the pump. The pulsing will stop when the communication has completed (green loop) or given up (yellow or red loop).

"},{"location":"loop-3/displays-v3/#example-loop-status-modal-messages","title":"Example Loop Status Modal Messages","text":"

When you tap on the Loop Icon on the main screen, you will see a message similar to one of those shown below. The message content depends on:

On your phone, you should see the green, yellow or red icon in the background - the color is not captured when taking screenshots of the modal message.

"},{"location":"loop-3/displays-v3/#glucose-status-icon","title":"Glucose Status Icon","text":"

The table below shows examples of the Glucose Status Icon and what each icon means. The Glucose Color Code is provided below the table.

Icon Meaning The current glucose reading is displayed. It can be from the CGM or from a finger stick. The value must have been updated within the last 15 minutes to be displayed.For the example shown, a valid trend arrow is available and is blue. Color codes are explained at this link. The last glucose reading from the CGM or from a finger stick is stale, i.e., it was acquired more than 15 minutes ago. In this case, the glucose prediction will stop updating.The HUD Status Row message enables user to enter fingerstick glucose value if desired.If in closed-loop mode, no changes will be made to insulin delivery. If a temporary basal is running, it continues running for the scheduled duration. Once the temporary basal expires, the pump resumes the scheduled basal rate.When the app issues a temporary basal, the duration is always 30 minutes.The user can enter a manual temporary basal duration up to the limits of their pump. If no CGM is currently selected, the Add CGM icon is displayed. The user can add a CGM following these instructions. If no CGM is currently selected, but a glucose value was acquired within the last 15 minutes (from fingerstick or a different CGM), that value is displayed along with a plus sign. By tapping on the icon, the user can add a CGM following these instructions."},{"location":"loop-3/displays-v3/#glucose-color-code","title":"Glucose Color Code","text":"Glucose Range Glucose Value Color Trend Arrow Color 55 mg/dL (3.0 mmol/L) or below red regardless of background color red 56 to 79 mg/dL (3.1 and 4.4 mmol/L) black (light mode) / white (dark mode) yellow 80 to 199 mg/dL (4.4 to 11.0 mmol/L) black (light mode) / white (dark mode) blue 200 mg/dL (11.1 mmol/L) or above black (light mode) / white (dark mode) yellow"},{"location":"loop-3/displays-v3/#cgm-display","title":"CGM Display","text":"

Tapping on the CGM icon in the HUD shows more information about the last CGM reading.

For Dexcom G5/G6 and Share, the same screen is obtained by tapping on Loop Settings->CGM.

For Nightscout Remote CGM, the Nightscout URL is opened when tapping on the CGM icon in the HUD, while the credential sections is shown when tapping on Loop Settings->CGM.

The graphic below shows the result of tapping on the CGM icon when using a Dexcom G6. It includes the time of the last reading to the nearest second, along with other information about that sensor and transmitter. It also has an option to go to the Dexcom app on the same device.

"},{"location":"loop-3/displays-v3/#pump-status-icon","title":"Pump Status Icon","text":"

The nominal pump icon displays high-level status information for the pump with two main components: left side is the basal delivery status and right side is the reservoir status. For Pods, a lifecycle line is displayed underneath the pump icon during the last 24 hours of nominal pod life.

The table below shows examples for a few nominal Pump Status Icons and Alert messages that might be shown. In all cases, tapping on the Pump Status Icon opens the Pump Settings screen with more information.

Icon Meaning This nominal pump status graphic is for a Pod with temp basal less than scheduled basal rate and no reported reservoir level. This nominal pump status graphic is for a Medtronic pump running scheduled basal rate and with a half-full reservoir.For a Pod, the reservoir shows full until pod estimates reservoir is below 50 U remaining. This nominal pump status graphic is for a pump running a high temp basal rate with the reservoir level reported. When the reservoir level is above the notification level, the reservoir graphic is orange. This pump status graphic indicates 2 alerts: (1) the 15 U reservoir level is less than the notification level of 20 U selected by this user and (2) a small clock icon is added to the display to indicate the phone time zone and pump time zone do not match. When the reservoir level is below the notification level, the reservoir graphic is yellow.Follow the link for time zone information. This alert message indicates the reservoir reports 0 U. Although pumps will continue to deliver some insulin after this point (max of 4 U for pods, or until all insulin is gone for both pods and Medtronic), the user should be aware that insulin delivery could stop at any moment.Note that if you see a display of 0 U in yellow, that means there is 0.5 U or less reported by the pump. This alert message indicates no pod is currently paired so no insulin is being delivered.Tap on the icon to reach the pod setting screen and pair a new pod, or switch to a different source for providing insulin. This alert message indicates all insulin delivery has been suspended. A Status Row message appears to enable the user to resume delivery with one tap. Alternatively, insulin can be resumed by tapping on the Pump Icon to enter the Pump Setting display and resume from that screen. This alert message indicates the user has initiated a manual temp basal (MTB). While the MTB is active, the Loop Icon Status will also display an Open Loop symbol to indicate no automatic adjustments are made until MTB expires or is canceled. The lifecycle indicator across the bottom of the pod status indicates a pod within the final 24 hours of nominal life.Tapping on the icon takes the user to the pump settings display where the rate and duration of the MTB are displayed. This alert message indicates it has been more than 15 minutes since the app was able to communicate with the pump.Follow these troubleshooting steps. This alert message indicates no pump has been added. Follow the instruction for adding a pump."},{"location":"loop-3/displays-v3/#time-zone","title":"Time Zone","text":"

Loop allows your pump to have a different time zone from your phone.

Your daily schedule for basal rates, correction ranges, insulin sensitivity factors and carb ratios is displayed with respect to midnight on \"pump time\". When you first Add Pump to Loop, the pump and phone are in the same time zone, but it's important to understand what happens when the time zone changes on the phone.

The display to modify time zone is slightly different for Loop 2.2.x and Loop 3 (links below):

You can choose to leave the pump and phone time zones different; the pump icon on the HUD (Loop 3 only) will show the clock icon to remind you. Many people do this for short trips.

"},{"location":"loop-3/displays-v3/#other-time-changes","title":"Other Time Changes","text":"

What about other time changes? Suppose the iOS -> General -> Time & Date is modified to manually change the time, but the time zone is not adjusted. (Sometimes this is done to defeat limits on games. Do Not do this on a Looping phone. If you have an \"old\" glucose reading in the \"future\" - Loop will not predict correctly which may have dangerous consequences.) There will not be an obvious display in the HUD or Omnipod screen (which keys off time zone) but you will get regular warnings that phone does not have automatic time set.

Loop 3 will display this warning modal screen if it detects a problem with the Phone time. It leaves it up the user to decide what action should be taken. To make this warning stop, go to iOS -> General -> Time & Date and enable Set Automatically.

"},{"location":"loop-3/displays-v3/#hud-status-row","title":"HUD Status Row","text":"

The Status Row is located immediately below the CGM, Loop and Pump Icons and is used to provide status, action buttons and information. The messages in the table are in order of priority. For example, a No Recent Glucose message is displayed even when an Override is active.

Bolus In Progress

The bolus messages are displayed with the highest priority:

Status Row / Meaning When the user issues a manual bolus through the app, a Starting Bolus information message is displayed. Tapping on this message has no action.As soon as the app issues a command to the pump (or sends it to the RileyLink to be delivered to the pump), the bolus in progress message appears. As soon as a bolus is started, from either a manual command or an automatic bolus, the bolus in progress message is displayed. Tapping on the Status Row causes the app to attempt to cancel the bolus. The app can only cancel a bolus if communication is active between the app and the pump.The message says BolusedvalueoftotalU. The value is based on a timer, so it is possible for an occlusion or other fault to occur while the app indicates bolus is in progress.In case of a fault, the user can tap on the pump icon to force a new pump status reading. For the case of pods, this allows you to silence a screaming pod quickly. Once the app communicates with the pump, the actual delivery status will be updated. If the user taps on the bolus in progress message in the Status Row, the message changes to Canceling Bolus. Tapping on this message has no action. As soon the app determines that the pump is suspended, the Insulin Suspended, Tap to Resume message is displayed. Tapping on the Status Row resumes scheduled basal delivery if communication is active between the app and the pump.Medtronic pump users who suspend directly on the pump will notice a delay before this message is displayed. It is best to use the app Pump Settings screen to suspend the pump. If a higher priority message is not displayed in the Status Row and the glucose value is stale (more than 15 minutes old), the No Recent Glucose, Tap to Add message is displayed. Tapping on the Status Row opens the Manual Bolus screen for entry of a Fingerstick Glucose. Note that if you choose not to accept a recommended bolus on this screen but you want to save the Fingerstick value, you need to tap the Bolus line to force it to 0 U and then tap Save Without Bolusing. However, be aware that, in Closed Loop mode, the app will use that glucose value for the next 15 minutes and may adjust insulin delivery accordingly. If a higher priority message is not displayed in the Status Row and an override is active, the override symbol and name, along with the time at which the override expires, is displayed. Tapping on the Status Row opens the screen for that particular override to enable the user to edit the override. Note that any changes made to that override are applied just to the current session. If you want the override permanently modified, refer to the Overrides instructions. If a higher priority message is not displayed in the Status Row and the Pre-Meal Range is active in the toolbar, the Pre-meal Preset, until time stamp is displayed. Tapping on the status row has no effect for this message.New with Loop 3: The Pre-Meal Preset can be engaged with an Override. When both are active, the Pre-Meal Range supersedes the range of the active Override, but the other settings for that Override still apply. When both are active, the Status Row message reflects the Override with both the Pre-Meal and Override icons in the toolbar highlighted."},{"location":"loop-3/features/","title":"Features","text":""},{"location":"loop-3/features/#work-in-progress","title":"Work in Progress","text":"

work in progress

This page will be deleted after all the relevant information is incorporated into the appropriate locations as part of the development process for Loop 3.

Now that Loop 3 has been released, this page may be updated, but leaving it alone for now.

This page discusses updated versions of Loop features as well as new capabilities provided with Loop 3.

Loop 3 Displays

One thing you may notice on some screens is the primary button, with associated information message, is always visible at the bottom of even small screens. You may need to scroll to see intermediate rows.

For example, if the default action on a bolus screen is to deliver the recommended bolus, that button is visible and active. The button remains fixed as other portions of the screen are scrolled up and down. When you make changes to selections, then the information displayed and the button label updates to reflect the action taken if you tap on the button.

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

"},{"location":"loop-3/features/#non-pump-insulin","title":"Non-Pump Insulin","text":"

If insulin is taken from a different source and the user wants to let Loop know, there is a new method in Loop 3.

With Loop 2.2.x, the user manually entered the Insulin dose into the Apple Health app. Loop then imported that value.

With Loop 3, the \"old\" method still works, but there is a new method for entering this information. This method enables the user to indicate the type of insulin so that the appropriate model is used by Loop. An updated Glucose prediction chart is displayed prior to saving the dose.

"},{"location":"loop-3/features/#enter-non-pump-insulin-before-carbs","title":"Enter non-pump insulin before carbs","text":"

WARNING

If you are planning to enter non-pump insulin to cover carbs and you do NOT want Loop to automatically start increasing insulin based on the carb entry, enter the non-pump insulin first and then add the carbs.

To find out what Loop recommends, without actually dosing with Loop:

  1. Tap on either of the insulin charts (Active Insulin or Insulin Delivery) on the home screen to display the Insulin Delivery Screen. This screen has 3 tabs.

    • Event History (default) is similar to Loop 2.2.x; however, the event history from a prior pod is not displayed once it is deactivated
    • Reservoir is similar to Loop 2.2.x; however, the reservoir value from a prior pod is not displayed once it is deactivated
    • Non-Pump Insulin is a new feature with Loop 3

  2. Select the Non-Pump Insulin tab to bring up the graphic shown below

    • Tap on the + sign (green solid lines)
    • Log Dose screen is displayed showing the current Glucose prediction
    • The default insulin type is that used by the pump
    • To modify Insulin Type, tap on that row (red dashed lines)
      • Picker wheel allows other insulin types to be selected
      • Note that some insulin types, such as Afrezza are only available for non-pump insulin selection
    • Tap on the Bolus row (blue dash-dot lines) to bring up a keyboard
      • The Glucose prediction chart updates automatically based on the value entered in the Bolus row
      • Tip, add 0.001 to the actual dose to make it easier to see if reviewing in Apple Health
      • Once the user selects Done on the keyboard display, the entered value is displayed on the Bolus row and the Log Dose button changes from gray to blue
      • Tap on Log Dose to record or Cancel to quit

"},{"location":"loop-3/features/#bolus-entry","title":"Bolus Entry","text":"

The bolus following carbs (Meal Bolus) and manual bolus (Bolus) screens are updated from Loop 2.2.x version. There is still a predicted Glucose chart that actively updates as the bolus value is updated and various buttons.

Blue Means Active

"},{"location":"loop-3/features/#meal-bolus","title":"Meal Bolus","text":"

When the Meal Bolus screen is entered following a carb entry or edit action, the active button might be Save and Bolus or, if no bolus was recommended, Save without Bolusing. The Save refers to saving the Carb entry or Carb edit that led to this screen in addition to saving the amount that might be bolused. It can also refer to saving a fingerstick value entered in the Meal Bolus screen.

"},{"location":"loop-3/features/#accept-recommendation","title":"Accept Recommendation","text":"

In the graphic below, the user enters carbs and taps continue to display the Meal Bolus screen.

If a CGM entry arrives while in this screen, a Bolus Recommendation Updated modal message will be displayed and must be acknowledged.

"},{"location":"loop-3/features/#modify-bolus","title":"Modify Bolus","text":"

This section is a continuation of the information presented in the Accept Recommendation portion of the Meal Bolus section. In the graphic below, the user overrides the recommended bolus.

"},{"location":"loop-3/features/#manual-bolus","title":"Manual Bolus","text":"

When the Bolus screen is entered directly from the toolbar, the button choices are Enter Bolus if none is recommended, Deliver if a value is on the Bolus row, or Cancel using the button on the upper left. The user can also tap on the value on the Bolus row to bring up a keyboard to modify that amount. When doing that, the value is automatically set to zero.

Other alert messages might be displayed if the pump or CGM is not active. Those are found on the Loop 3 Displays page.

The two graphics below are examples of manual bolus screens.

"},{"location":"loop-3/features/#remote-carb-bolus","title":"Remote Carb / Bolus","text":"

Loop 3 includes a feature for remote input of Carbohydrates and Bolus, enabling caregivers who are not physically present to better assist the individual who requires support in managing Loop.

Please read the documentation about this feature carefully to ensure proper configuration and use: * Remote Command Overview

WARNING

You will be using this feature at your own risk, like any other Loop code you build. It is very important you completely read and re-read the Remote Command Overview before getting started.

There are validation and troubleshooting steps for each section of the guide.

Please make sure not to skip sections as this makes it difficult to troubleshoot.

Be aware:

"},{"location":"loop-3/features/#new-with-loop-3","title":"New with Loop 3","text":"

The Loop 3 app, building off work by Tidepool and DIY contributors, provides a major upgrade in user safety, user experience, and user interface with the same great Loop algorithm.

Here are some highlights:

"},{"location":"loop-3/loop-3-overview/","title":"Overview","text":""},{"location":"loop-3/loop-3-overview/#loop-3-set-up-overview","title":"Loop 3 Set Up Overview","text":"

Congratulations on Building Loop!

The first time you build Loop 3, the app takes you through the Onboarding process. Review this page before using your app.

Suggestion

"},{"location":"loop-3/loop-3-overview/#brand-new-loopers","title":"Brand New Loopers","text":""},{"location":"loop-3/loop-3-overview/#experienced-loopers","title":"Experienced Loopers","text":""},{"location":"loop-3/loop-3-overview/#all-loopers","title":"All Loopers","text":"

These pages have a lot of detailed Loop information.

And a lot of detailed information about Status and Commands for:

Medtronic Users

You must select Insulin Type on your pump settings screen after updating from Loop 2 to Loop 3 and completing the onboarding. Without an insulin type, closed loop will not work.

"},{"location":"loop-3/loop-3-overview/#safety","title":"Safety","text":"

Please be informed so you can Loop safely.

Consult with your health care professional regarding your diabetes management.

Open Source

"},{"location":"loop-3/medtronic/","title":"Medtronic Pump","text":""},{"location":"loop-3/medtronic/#pump-settings","title":"Pump Settings","text":"

To bring up the Pump Settings display, tap on the pump icon in the Heads Up Display (HUD) or your connected pump in the Loop Settings screen.

"},{"location":"loop-3/medtronic/#medtronic-status-and-commands","title":"Medtronic Status and Commands","text":"

Medtronic status and commands are found in the Pump Settings screen shown in the graphic below. The bottom section with Pump ID, Firware Version and Region is configured at the time the pump is connected to Loop. You cannot edit those lines.

"},{"location":"loop-3/medtronic/#suspend-delivery","title":"Suspend Delivery","text":"

Tapping on the Suspend Delivery row will suspend all insulin delivery: basals, temp basals, and boluses in progress. When you press Suspend Delivery, the label changes to Suspending while Loop is communicating with the pump. When the label changes to Resume Delivery, all insulin delivery is stopped until the user resumes using the HUD Status Row, the Pump Settings screen or on the pump itself.

As long as the spinning icon is spinning, Loop is trying to execute the Suspend or Resume command. If it fails to complete, a modal alert will appear that says \"Error Suspending\" or \"Failed to Resume Insulin Delivery\" which you must acknowledge. You must then repeat the command to try again. Make sure your RileyLink device is powered on and close to the phone and pump.

When the phone is in portrait mode, so the HUD is visible:

You can still suspend and resume insulin on the pump itself. It may take until the next Loop cycle (typically less than 5 minutes), but Loop will detect that the pump is suspended or basal is resumed and the HUD Status Row will update.

If you request a manual bolus with Loop while the pump is suspended, Loop resumes basal delivery as well. No automated boluses are initiated while suspended, only manual ones.

"},{"location":"loop-3/medtronic/#insulin-type","title":"Insulin Type","text":"

You select insulin type when connecting to a new Medtronic pump.

If you install Loop 3 over Loop 2 with the pump already configured, be sure to set the Insulin Type on the pump settings screen. If no insulin type is set, you will get red loops.

Use this row if you switch to a different type of insulin.

"},{"location":"loop-3/medtronic/#pump-battery-type","title":"Pump Battery Type","text":"

The type of battery used in the Medtronic pump affects how Loop interprets the battery level for the pump.

"},{"location":"loop-3/medtronic/#preferred-data-source","title":"Preferred Data Source","text":"

Leave the Preferred Data Source set to on Event History.

"},{"location":"loop-3/medtronic/#use-mysentry","title":"Use MySentry","text":"

The Use My Sentry row only shows up on pumps that support it.

Using the MySentry feature on some Medtronic pumps when using an OrangeLink causes the batteries to die quickly. This option allows you to turn off MySentry within the Loop app.

"},{"location":"loop-3/medtronic/#devices","title":"Devices","text":"

This allows access to the RileyLink screen for each connected RileyLink compatible device.

"},{"location":"loop-3/medtronic/#pump-battery-remaining","title":"Pump Battery Remaining","text":"

Loop uses the Pump Battery Type to estimate Pump Battery Remaining. For information about the method, review MDT Pump Battery.

"},{"location":"loop-3/medtronic/#pump-time","title":"Pump Time","text":"

Loop keeps the pump time up to date with the phone time automatically. As shown in the graphic in the next section, Loop allows differences in time zone. The user can decide when and if to modify the pump time zone, if different from the phone time zone. If the Pump Time shows as yellow, then the time zones do not match.

"},{"location":"loop-3/medtronic/#change-time-zone","title":"Change Time Zone","text":"

During normal operation, Loop automatically keeps phone time and pump time aligned. In the case of time zone or daylight savings time changes, Loop allows the differences to persist until the user chooses to Change Time Zone. Please review Time Zone for more details.

When the time zone for the pump and phone are not the same, you will notice a small clock symbol in the upper right of the pump status icon.

Navigate to the Pump Settings screen. Right below the Pump Battery Remaining and Pump Time rows, there is a new row Sync to Current Time. When you tap that row, the time for the Medtronic pump is updated to the current Loop phone time.

"},{"location":"loop-3/medtronic/#delete-pump","title":"Delete Pump","text":"

If you want to switch to a different pump you must first delete this one:

For more information, follow this link: Modify Pump.

"},{"location":"loop-3/omnipod/","title":"Omnipod Pump","text":""},{"location":"loop-3/omnipod/#omnipod-and-omnipod-dash-pump","title":"Omnipod and Omnipod DASH Pump","text":"

The information and user interface for Omnipod (Eros) and DASH pods is the same, except Omnipod DASH pods do not require a RileyLink compatible device. They communicate directly with the phone through Bluetooth.

"},{"location":"loop-3/omnipod/#pair-pod","title":"Pair Pod","text":"

Max Fill is 200 Units

When you fill the Pod do not exceed 200 units.

If you overfill the pods, you may get a pod fault right after priming.

Pod Filling and Insertion

The Pod filling and insertion instructions are the same with the Loop app as they are for the PDM. These videos: Filling a Pod with Insulin and Inserting the Cannula, may be useful.

For DASH Pods:

For Eros Pods:

You'll be pairing a pod every 2 or 3 days (max pod life is 80 hours).

You'll see this screen every time you ask Loop to Pair New Pod.

The Omnipod Common pairing protocol is the same for all pods. The difference is that Omnipod requires a RileyLink compatible device and Omnipod DASH does not. There are also slight differences in some of the text and graphics, e.g., Omnipod DASH uses a blue needle cap and Omnipod has a clear needle cap.

Graphic below shows the Pair Pod screen for Omnipod (left) and Omnipod DASH (right).

Loop walks you through each step of the filling, pairing, priming, attaching and insertion process.

It makes sure you are really ready to do the insertion.

Please watch the video of the Loop app screen when pairing a DASH pod to see the full process before pairing your first pod. In this video, once the pod starts priming, you may want to skip forward (it takes about a minute to prime).

Keep Gear Close

"},{"location":"loop-3/omnipod/#insert-cannula-slider","title":"Insert Cannula Slider","text":"

New Insert Cannula Control

For version 3.3.0 and later, (which means the dev branch right now), there is a new slider to control insertion of the cannula instead of a button to tap. It looks like the graphic below. You place your finger on the darker blue icon and, while keeping your finger in contact with the screen, drag all the way to the right. After the drag operation, as soon as you lift your finger off the phone, the cannula insertion command is sent to the pod.

The Screen that says Setup Complete allows you to change the Scheduled Reminder for this pod if you want a different reminder time (including none) from your usual setting.

"},{"location":"loop-3/omnipod/#pod-status","title":"Pod Status","text":"

The Pod Status screen is shown in the graphic below. The dashed green outline indicates the Device portion that is found only for the Omnipod. All other features of the screen are common for Omnipod and Omnipod DASH.

"},{"location":"loop-3/omnipod/#play-beeps","title":"Play Beeps","text":"

If you want to make sure Loop can talk to your pod, click on the sound icon (highlighted by the red box) in the graphic above. If the icon is greyed out - that means Loop is having a communication issue reaching your pod. Follow the usual Troubleshoot: Pump is Not Responding steps to resolve this problem.

Other Uses

"},{"location":"loop-3/omnipod/#pod-expires","title":"Pod Expires","text":""},{"location":"loop-3/omnipod/#basal-report","title":"Basal Report","text":"

The next row changes the label depending on the situation. In all cases, the current basal rate is reported.

Label Description Scheduled Basal Pod is running the scheduled basal rate Insulin Delivery Pod is running an automated or manual temporary basal rate"},{"location":"loop-3/omnipod/#insulin-remaining","title":"Insulin Remaining","text":"

Pods start reporting reservoir values when 50 U are left.

Value Meaning 50+ U Pod reservoir is greater than 50 U Value U Pod reservoir is estimated to be at least as great as the indicated value. 0 U Pod will attempt to deliver up to 4 U after it reports 0 U. This is not guaranteed. The pod senses when it is not successful delivering pulses and that can happen before 4 U have been delivered."},{"location":"loop-3/omnipod/#activity","title":"Activity","text":""},{"location":"loop-3/omnipod/#suspend-delivery","title":"Suspend Delivery","text":"

You may want to consider using a Manual Temp Basal of 0 U/hr instead of suspend.

Tapping on Suspend Delivery brings up a timed reminder screen. You can choose to be reminded (via a beep on the pod itself) with 4 choices (or you can cancel the request):

After you select the reminder time, Loop issues a command to the pod to halt all insulin delivery: basals, temp basals, and boluses in progress. The label on the Suspend Delivery row changes to Suspending while Loop is communicating with the pump. When the label changes to Resume Delivery, all insulin delivery is stopped until the user resumes using the HUD Status Row or the Pod Status screen.

As long as the spinning icon is spinning, Loop is trying to execute the Suspend or Resume command. If it fails to complete, a modal alert will appear that says \"Error Suspending\" or \"Failed to Resume Insulin Delivery\" which you must acknowledge. You must then repeat the command to try again. For Omnipod, make sure your RileyLink device is powered on and close to the phone and pod.

When the phone is in portrait mode, so the HUD is visible:

"},{"location":"loop-3/omnipod/#no-manual-bolus-while-pod-is-suspended","title":"No Manual Bolus While Pod is Suspended","text":"

If you request a manual bolus with Loop while a pod is suspended, Loop will send a notification that Bolus Failed with instructions that Pump is Suspended, Resume Delivery. In other words, you must resume delivery before you will be allowed to bolus with pods.

"},{"location":"loop-3/omnipod/#suspend-timer-reminder","title":"Suspend Timer Reminder","text":"

At the end of the reminder time, an alert beep is issued by the pod and a modal alert will be provided on the Loop app. You must acknowledge the modal alert on the phone to silence future pod alerts.

Manually Resume Insulin Delivery

The halt of all insulin delivery continues until you manually resume. There is no automatic resumption of basal insulin from a suspend command.

If you select a Manual Temp Basal command of 0 U/hr instead of Suspend:

"},{"location":"loop-3/omnipod/#manual-temp-basal","title":"Manual Temp Basal","text":"

Tap on the Set Temporary Basal Rate to select a Manual Temp Basal.

This brings up the Temporary Basal screen shown on the left of the graphic below.

In other words, you can leave your phone behind and the selected basal rate continues for the selected basal duration. There will be no automated adjustments of delivery for the temp basal duration.

"},{"location":"loop-3/omnipod/#during-manual-temp-basal","title":"During Manual Temp Basal","text":"

This Pod Only

The manual temp basal command from Loop tells the pod to initiate a temp basal for the designated rate and duration.

Deactivating this pod and pairing a new one interrupts the temp basal.

If you still need that basal rate, you must initiate it on the new pod.

Once the manual temp basal command is sent to the pod, Loop changes to Open Loop mode and updates displays as shown in the graphic above

So long as you were in Closed Loop before requesting the Temp Basal, Loop returns to Closed Loop automatically when the duration ends or you cancel the temporary basal.

Automatic Resumption of Scheduled Basal

The phone does not need to be in contact with the pod for insulin delivery to return to scheduled basal at the end of the selected duration. That duration is commanded along with the temporary rate. Once the pod accepts that command, and you'll get an error message if it does not, the pod will resume scheduled basal rate without further commanding if there is insulin in the reservoir and a pod fault does not occur.

For situations where you need a modification of your insulin needs that is not dependent on a particular pod, review the information on the Overrides page.

"},{"location":"loop-3/omnipod/#devices","title":"Devices","text":"

For Omnipod, there is a Devices section used to access the RileyLink status and commands screen.

"},{"location":"loop-3/omnipod/#pod-details","title":"Pod Details","text":"

The Pod Details table, shown in the graphic below, reports:

Time Drift

The pod will expire when it thinks it has been 80 hours. The pod clock may drift a few seconds with respect to phone time during the pod life. The Expiration time gets updated when the pod reports how long it thinks it has been since it was activated.

"},{"location":"loop-3/omnipod/#device-details","title":"Device Details","text":"

Some additional details from the most recent pod status response message are displayed if you tap the Device Details row, as shown in the graphic below. Most people will not need to view this.

The graphic shows an example for Omnipod on the left, Omnipod DASH (TWI BOARD) in the middle and Omnipod DASH (NXP BLE) on the right. Do not worry about the different board styles (Device Name) for DASH. The developers did that for you. If you are asking for help from a mentor - they may request this information.

"},{"location":"loop-3/omnipod/#replace-pod","title":"Replace Pod","text":"

When you tap on the Replace Pod row, the Deactivate Pod screen, shown below, is displayed.

"},{"location":"loop-3/omnipod/#configuration","title":"Configuration","text":""},{"location":"loop-3/omnipod/#notification-settings","title":"Notification Settings","text":"

When you tap on the Notifcation Settings row, the graphic below is displayed. The notifications are a combination of beeps on the pod with associated modal alerts on the phone app that must be acknowledged to prevent future beeps.

"},{"location":"loop-3/omnipod/#confidence-reminders","title":"Confidence Reminders","text":"

When you tap on the Confidence Reminder row, the graphic below is displayed. You can choose from three levels of audible responses that Loop requests from the pod:

"},{"location":"loop-3/omnipod/#insulin-type","title":"Insulin Type","text":"

You selected insulin type when connecting to this pump.

Tap on this row if you switch to a different type of insulin.

"},{"location":"loop-3/omnipod/#pump-time","title":"Pump Time","text":"

Click on Time Zone to understand how Loop treats \"pump\" time for pods.

When the Pump time zone matches the phone time zone, the Pump Time is displayed with black font.

When the phone time zone and pump time zone do not match, there is a clock icon on the main screen in the Pump Status Icon of the HUD.

"},{"location":"loop-3/omnipod/#other-time-changes","title":"Other Time Changes","text":"

What about other time changes? Suppose the iOS -> General -> Time & Date is modified to manually change the time, but the time zone is not adjusted. (Sometimes this is done to defeat limits on games. Do Not do this on a Looping phone. If you have an \"old\" glucose reading in the \"future\" - Loop will not predict correctly which may have dangerous consequences.) There will not be an obvious display in the HUD or Omnipod screen (which keys off time zone) but you will get regular warnings that phone does not have automatic time set.

Loop 3 will display this warning modal screen if it detects a problem with the Phone time. It leaves it up the user to decide what action should be taken. To make this warning stop, go to iOS -> General -> Time & Date and enable Set Automatically.

"},{"location":"loop-3/omnipod/#previous-pod-information","title":"Previous Pod Information","text":"

When you tap on the Previous Pod Information row, a graphic similar to those shown below is displayed. This provides summary information about the pod before the one currently in use.

If the previous pod had a fault and you choose to report it to Insulet, this screen reports the PDM reference code that Insulet uses in their tracking system.

Do Not Call Insulet about -049 (0x31) Faults

If you should happen to get a fault where the last 3 digits of the PDM ref code are \"-049\" (the Hex Designation is fault code 0x31), do not report this to Insulet and do not ask for a replacement. This means Loop did not ensure the pod was in the correct state to accept a command. In other words, it was a bug in the Loop code.

We believe the code has been updated to prevent these faults. There was a brief period during development in which at least one of these happened - this was fixed July 3, 2022. If this happens to you, report it on zulipchat for the developers, save a Loop Report and rebuild if you have an older version of the development code.

With Loop 3, do not leave the screen open and unlocked for long periods of time without first reading Is there an increase in pod failures on Loop?

"},{"location":"loop-3/omnipod/#pod-error-messages","title":"Pod Error Messages","text":"

This section presents some of the error message screens you may see specific to pods.

"},{"location":"loop-3/omnipod/#pod-faults","title":"Pod Faults","text":"

You are likely to hear a pod fault before Loop notices. If your phone is locked, Loop only checks status every 5 minutes for Omnipod or 3 minutes for Omnipod DASH.

Unlock your phone, open Loop, navigate to the Pod Status screen and tap on Deactivate Pod to stop the noise. The pod fault - even if it does not show up in the HUD or the Pod Status screen, will be picked up by the process of hitting Deactivate Pod. You can then view the Fault information in the Previous Pod Information screen.

"},{"location":"loop-3/onboarding/","title":"Onboarding","text":""},{"location":"loop-3/onboarding/#onboarding","title":"Onboarding","text":"

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.

"},{"location":"loop-3/onboarding/#entering-and-editing-values","title":"Entering and Editing Values","text":"

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

"},{"location":"loop-3/onboarding/#glucose-units","title":"Glucose Units","text":"

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.

"},{"location":"loop-3/onboarding/#onboarding-steps","title":"Onboarding Steps","text":"

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.

"},{"location":"loop-3/onboarding/#welcome-to-loop","title":"Welcome to Loop","text":"

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

"},{"location":"loop-3/onboarding/#apple-health-permissions","title":"Apple Health Permissions","text":"

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.

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

"},{"location":"loop-3/onboarding/#usage-data-sharing","title":"Usage Data Sharing","text":"

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:

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

"},{"location":"loop-3/onboarding/#share-usage-data","title":"Share Usage Data","text":"

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.

"},{"location":"loop-3/onboarding/#connect-loop-to-nightscout","title":"Connect Loop to Nightscout","text":"

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

Loop 3 with Nightscout Requires API_SECRET

If you select Use Nightscout with Loop:

"},{"location":"loop-3/onboarding/#therapy-settings-onboarding","title":"Therapy Settings (Onboarding)","text":"

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.

"},{"location":"loop-3/onboarding/#guardrails-while-onboarding","title":"Guardrails While Onboarding","text":"

Warning - Outside Typical?

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

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.

mmol/L

People using mmol/L should avoid the red (the min or max end points) glucose values for their settings. They sometimes cause a crash.

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

"},{"location":"loop-3/onboarding/#glucose-safety-limit","title":"Glucose Safety Limit","text":"

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.

"},{"location":"loop-3/onboarding/#correction-range","title":"Correction Range","text":"

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

"},{"location":"loop-3/onboarding/#manual-vs-automated-dosing","title":"Manual vs Automated Dosing","text":"

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.

"},{"location":"loop-3/onboarding/#pre-meal-range","title":"Pre-Meal Range","text":"

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.

"},{"location":"loop-3/onboarding/#carb-ratios","title":"Carb Ratios","text":"

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

"},{"location":"loop-3/onboarding/#basal-rates","title":"Basal Rates","text":"

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.

"},{"location":"loop-3/onboarding/#medtronic-pump-users","title":"Medtronic Pump Users","text":"

If you will be connecting a Medtronic pump after onboarding:

"},{"location":"loop-3/onboarding/#delivery-limits","title":"Delivery Limits","text":"

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

"},{"location":"loop-3/onboarding/#medtronic-pump-users_1","title":"Medtronic Pump Users","text":"

If you will be connecting a Medtronic pump after onboarding:

"},{"location":"loop-3/onboarding/#maximum-basal-rate","title":"Maximum Basal Rate","text":"

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.

"},{"location":"loop-3/onboarding/#maximum-bolus","title":"Maximum Bolus","text":"

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.

"},{"location":"loop-3/onboarding/#insulin-sensitivities","title":"Insulin Sensitivities","text":"

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.

"},{"location":"loop-3/onboarding/#therapy-settings-review","title":"Therapy Settings Review","text":"

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.

"},{"location":"loop-3/onboarding/#notifications-and-bluetooth","title":"Notifications and Bluetooth","text":"

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

"},{"location":"loop-3/onboarding/#cgm-and-pump","title":"CGM and Pump","text":"

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.

"},{"location":"loop-3/onboarding/#experienced-loopers","title":"Experienced Loopers","text":"

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
"},{"location":"loop-3/onboarding/#check-imported-settings","title":"Check Imported Settings","text":"

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.

HIGHLIGHTING THIS ONE - A LOT OF PEOPLE MISSED THIS:

"},{"location":"loop-3/onboarding/#carb-absorption-time-update","title":"Carb Absorption Time Update","text":"

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.

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.

"},{"location":"loop-3/onboarding/#carb-data-source","title":"Carb Data Source","text":"

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.

"},{"location":"loop-3/services/","title":"Optional: Services","text":"

## Loop Services

Near the bottom of your Loop settings screen is a section called \"Services\".

Sevices are Optional

The services are added by tapping on the + sign and choosing the service from the list. Services are shown alphabetically. The most common services are Nightscout and Tidepool.

"},{"location":"loop-3/services/#nightscout","title":"Nightscout","text":"

There is a whole section in LoopDocs about Nightscout. Please follow this link to the Using Nightscout with Loop section of LoopDocs. That also has the links you might need to the official Nightscout Documentation (different website).

If you have an existing Nightscout site, it's still a good idea to review that section, but here's the quick summary of how to add your Site URL and API_SECRET to have your Loop data transmitted to your Nightscout site. If you can\u2019t remember your API_SECRET, it can be found under Settings, Reveal Config Vars for Heroku sites (or Application Settings, Connection Strings for Azure sites).

The two most common errors in filling out this section are:

  1. Failure to use https:// in the site URL. If you use http:// (see how that doesn't have the \"s\" at the end?), you will get an error message about an App Transport Security policy.
  2. Having a trailing slash on the end of the URL (or an embedded space). If you copy and paste from a web browser, make sure to delete the trailing slash on the URL entry.

More Tips about Nightscout

"},{"location":"loop-3/services/#tidepool","title":"Tidepool","text":"

With Loop 3.2.x and newer versions, data can be directly uploaded from Loop to Tidepool.

User Beware

Don't use the Loop Tidepool uploader yet unless you want to help the developers work through some known issues. The Tidepool Mobile app still works to upload some of your Loop data from Health.

Please refer to the LoopTips: Data: Tidepool page for more information about Tidepool. The Tidepool display browser is undergoing some updates; the information on these pages will be updated after changes happen.

The Tidepool Mobile app serves 2 purposes:

  1. Allow notes to be recorded with associated glucose, carbs, and insulin record for a snap shot in time
  2. Upload Loop data stored in Health to the Tidepool database for display in their browser tool; when the Connect to Health feature is enabled

With the new Loop Service to upload to Tidepool, additional information that is not stored in Health can be made available to Tidepool. However, this is a work in progress.

At the current time:

When you add the Tidepool Service to Loop, be sure to disable Tidepool Mobile ability to read from Apple Health.

You can still use the note taking feature with Tidepool Mobile when Health is not connected, although you must have internet connectivity for this to work.

Tidepool Support is available to help troubleshoot issues or answer questions about using Tidepool. Contact them via email at support@tidepool.org.

"},{"location":"loop-3/services/#loggly","title":"Loggly","text":"

Loggly is a free logging service. If you sign up for an account, you'll need to go under Source Setup and then Customer Tokens. Copy and paste your customer token into your Loop App settings for Loggly.

"},{"location":"loop-3/services/#amplitude","title":"Amplitude","text":"

Amplitude is a remote event monitoring service and can be used to quickly identify errors and events with Loop. Amplitude stores the events and allows you to view those events as points in time. To retrieve the details of the events you will need to look at corresponding mLab data entries to get a complete picture of the issues. If you sign up for a free account with Amplitude, you will be given an API Key that you can enter here to have Loop integration setup.

"},{"location":"loop-3/services/#next-step-loop-displays","title":"Next Step: Loop Displays","text":"

Great job, almost finished! Now that you have completed your services, let's move onto understanding your Loop Displays.

Loop displays is a valuable tool for understanding your Loop and a great page to review when troubleshooting.

"},{"location":"loop-3/settings/","title":"Settings","text":""},{"location":"loop-3/settings/#loop-settings-screen","title":"Loop Settings Screen","text":"

The Settings screen, shown in the graphic below, is reached by tapping the gear icon in the Toolbar on the Main Loop Screen.

Each section and row on the Settings screen is described below.

"},{"location":"loop-3/settings/#closed-loop","title":"Closed Loop","text":"

The user can select closed loop or open loop using this slider. When you first start Loop, we encourage you to leave this slider disabled and become familiar with the app using Open Loop mode.

As soon as Closed Loop is enabled, Loop will begin automatic adjustment of insulin dosing. Please ensure the settings you entered are appropriate for the Loop algorithm.

No automatic (closed loop) adjustment of insulin will occur and the slider will be disabled under the following conditions.

"},{"location":"loop-3/settings/#recommended-insulin","title":"Recommended Insulin","text":"

With every loop cycle - typically every 5 minutes - Loop updates the glucose prediction using

Based on this prediction, Loop calculates a modification to insulin dosing to bring the user into the desired correction range. This can be a reduction in basal to raise the glucose prediction or a recommended bolus, subject to Delivery Limits, to lower the prediction. The glucose prediction is shown in the Glucose Chart along with the measured glucose values.

If you find this confusing, read how to Think Like a Loop on the LoopTips website.

"},{"location":"loop-3/settings/#dosing-strategy","title":"Dosing Strategy","text":"

This row gives you the ability to select Dosing Strategy. The Dosing Strategy only affects the method by which the recommended bolus - if any - is delivered. The current selection is noted underneath the Dosing Strategy label. The default (initial) value for this setting is Temp Basal Only. Tap on the arrow to the right to modify your selection.

Words in Graphic

Temp Basal Only: Loop will set temporary basal rates to increase and decrease insulin delivery.

Automatic Bolus: Loop will automatically bolus when insulin needs are above scheduled basal, and will use temporary basal rates when needed to reduce insulin delivery below scheduled basal.

Regardless of the Dosing Strategy selected, when glucose is below target or predicted to go below target, Loop decreases basal insulin using Temporary Basal.

Temp Basal Only: Subject to your Delivery Limits, Loop will deliver the Recommended Bolus over 30 minutes using positive temp basals (i.e., increase over your scheduled basal rate) to increase your IOB.

Automatic Bolus: Subject to your Delivery Limits, you receive 40% of the Recommended Bolus at every loop cycle.

"},{"location":"loop-3/settings/#automatic-bolus","title":"Automatic Bolus","text":"

When you first start Loop, we encourage you to leave Dosing Strategy set to Temp Basal Only until you are sure your settings are dialed in.

The Automatic Bolus selection causes Loop to provide 40% of the recommended dose as a bolus at the beginning of each Loop cycle (when a CGM reading comes in). This is a faster method of getting the recommended insulin delivered. When Loop delivers extra insulin, the scheduled basal rate continues unchanged.

As with all Loop versions, you can manually bolus at any time by pressing the Bolus icon in the center of Loop's Main Screen. Any bolus recommendation that you see when you press the Bolus icon will be 100% of the Recommended Bolus.

"},{"location":"loop-3/settings/#configuration","title":"Configuration","text":"

The Configuration section allows entry to the following screens:

"},{"location":"loop-3/settings/#therapy-settings","title":"Therapy Settings","text":"

There's a LoopDocs page devoted to therapy settings. Click on the link to get to that page: Therapy Settings.

"},{"location":"loop-3/settings/#add-pump-for-therapy-settings","title":"Add Pump for Therapy Settings","text":"

But I don't see Therapy Settings!

Therapy Settings is only accessible in the Settings screen when you have a pump connected to Loop.

"},{"location":"loop-3/settings/#option-1-prep-for-pods","title":"Option 1: Prep for Pods","text":"

If you add an Omnipod (requires RileyLink) or Omnipod DASH up to the Pair Pod screen and then cancel, Loop will use the common Omnipod details to allow you to modify your Therapy Settings.

"},{"location":"loop-3/settings/#option-2-prep-for-medtronic","title":"Option 2: Prep for Medtronic","text":"

If you need to modify Therapy Settings before connecting to a Medtronic pump:

"},{"location":"loop-3/settings/#option-3-simulate-loop","title":"Option 3: Simulate Loop","text":"

If you want to use Loop in parallel with your current method of dosing insulin.

"},{"location":"loop-3/settings/#usage-data-sharing","title":"Usage Data Sharing","text":"

iOS 15

If you are running an iOS 15 device, this screen is shown in German regardless of the language you choose for Loop. That is an accident that will be fixed by the next release. The English version is shown below.

You can review and modify your preference for Usage Data Sharing as shown in the graphic below:

If you change the check mark, it is immediately modified. Tap on Settings in upper left to return to the main Settings screen.

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

"},{"location":"loop-3/settings/#pump","title":"Pump","text":"

The information about the pump section is detailed on several different pages. Follow the links below:

"},{"location":"loop-3/settings/#cgm-settings","title":"CGM Settings","text":"

The information about the CGM is found on the Add or Modify CGM page.

"},{"location":"loop-3/settings/#services","title":"Services","text":"

The Services section allows additions of other services such Nightscout, Tidepool, Loggly and Amplitude.

Please refer to the Optional: Service page.

"},{"location":"loop-3/settings/#support","title":"Support","text":"

The Support section enables the user to provide output data (Loop Report and/or Critical Logs) about the app. This information can be very helpful to folks trying to assist with problem reports.

The graphic below shows the screen provided when you tap on the Support row at the bottom of the Settings screen.

"},{"location":"loop-3/settings/#issue-report","title":"Issue Report","text":"

Tap on the Issue Report row, on the graphic above, to create a Loop Report text file with a lot of useful information for the mentors or developers if they need to assist you in solving a problem. This covers 84-hours (to enable a full pod history for users of Omnipod or Omnipod DASH). When you tap that row, you'll see a message that the file is loading. That message never goes away but the rest of the page fills in fairly quickly. After that happens, use the up arrow to see various options to save the report.

Issue vs Issue Report

Be aware:

It's a good idea to use the Issue Report button and save it along with a screenshot if you think you will ask for help. You can always discard these if you resolve the problem on your own.

Pro Tip

The Loop Reports can be saved in the Files section on your iPhone. I have a folder on my phone Files named Loop Reports.

You can upload them to zulipchat from your phone (new feature) using the paperclip in the zulipchat app. (Don't see a paperclip - update your app.)

"},{"location":"loop-3/settings/#submit-bug-report","title":"Submit Bug Report","text":"

Tap on the Submit Bug Report row to bring up one of the two views shown in the graphic below. The left view is if you do not have a github account (or the phone is not signed in to your account). The right view is if your github credentials are available.

In either case, the first action should be to add a term or phrase to the search box (red rectangle) to see if your issue has already been reported and to read the status if it has been reported. Please refer to the GitHub Issues section for more information.

Not for Build or Settings Help

Submit Bug Report should be used when you believe there is an error in the code.

"},{"location":"loop-3/settings/#export-critical-event-logs","title":"Export Critical Event Logs","text":"

The last row under Support creates a zip (compressed file) with detailed app information over a 7-day period. It is stored in a different format from the Loop Report and provides critical information to the developers when troubleshooting. Once the compressed file is created, you can save it and later share it with the developers if they request it. You can always discard these if you resolve the problem on your own.

Pro Tip

The Critical Logs zip file can be saved in the Files section on your iPhone. I have a folder on my phone Files named Critical Logs.

You can upload them to zulipchat from your phone (new feature) using the paperclip in the zulipchat app. (Don't see a paperclip - update your app.)

"},{"location":"loop-3/settings/#critical-log-format","title":"Critical Log Format","text":"

The critical logs use a JSON (JavaScript Object Notation) format.

Each day (in user's local time) has the following files:

The JSON file for each day are zipped into one file for that day and then the zip files are again zipped into a single file that you can save. The current day (up to the current time) is combined with the previous day's data.

The time stamps within the JSON files use UTC.

"},{"location":"loop-3/settings/#app-profile","title":"App Profile","text":"

The Profile Expiration is reported at the bottom of the Settings display along with the number of days remaining before Loop stops working.

The link for How to update (LoopDocs) is provided for build with Mac.

In fine print, the exact date and time of the expiration is reported in your local time zone.

The Profile Expiration is different for GitHub Browser Build method. A feature request is in place (but not yet added to the code) to report the TestFlight expiration for that build method.

"},{"location":"loop-3/therapy-settings/","title":"Therapy Settings","text":""},{"location":"loop-3/therapy-settings/#loop-therapy-settings","title":"Loop Therapy Settings","text":"

During Onboarding, all of your therapy settings were entered.

After onboarding, the Therapy Settings screen is reached by going through the Loop Settings screen after a pump has been added.

When building Loop 3 over Loop 2.2.x, the existing values from Loop 2.2.x are kept where possible and presented to the user as the \"default\" value when moving through each screen.

This page provides more details about each of your Therapy Settings.

"},{"location":"loop-3/therapy-settings/#authorization-required","title":"Authorization Required","text":"

All the settings configured under Therapy Settings are protected by the same authorization method (FaceID, Fingerprint or Passcode) used to enable the app to issue a manual bolus.

"},{"location":"loop-3/therapy-settings/#details-for-therapy-settings","title":"Details for Therapy Settings","text":"

Loop 3 has Guardrails for some Therapy Settings. These are grouped in the Guardrails for Settings section of this page.

New Loopers

New Loopers may prefer settings that show up outside the \"typical\" range.

For example, choosing a Correction Range that is higher than \"typical\" when starting to learn Loop is fine. Once you are comfortable with how the system works, the range can be adjusted if desired - entirely up to you in consulatation with your health care professional.

Therapy Settings are used for automated insulin delivery when Loop is in Closed-Loop mode.

"},{"location":"loop-3/therapy-settings/#screens-displayed","title":"Screens Displayed","text":"

Some screens displayed on this page were acquired during Onboarding.

"},{"location":"loop-3/therapy-settings/#glucose-safety-limit","title":"Glucose Safety Limit","text":"

Loop will deliver basal and recommend bolus insulin only if your glucose is predicted to be above the Glucose Safety Limit for the next three hours.

The graphic below shows the information screen presented during onboarding or when user taps the information icon, \u24d8.

The GIF below shows two screens for Glucose Safety Limit.

If you feel more comfortable with a higher limit, do not let the yellow font influence you. Once you've used Loop for a while, you can revisit this setting.

Note

The value you select for Glucose Safety Limit will dictate the lowest value on the glucose picker that is available for Correction Range and Pre-Meal Range. Those cannot be lower than the Glucose Safety Limit.

Guardrails for Glucose Safety Limit

"},{"location":"loop-3/therapy-settings/#correction-range","title":"Correction Range","text":"

Your Correction Range is the glucose value (or range of values) that you want Loop to aim for in adjusting your basal insulin and helping you calculate your boluses.

The graphic below shows the information screen presented during onboarding or when user taps the information icon, \u24d8.

The GIF below shows four screens when first adding and selecting a correction range. The red box indicates where the user taps.

Do not let the yellow font discourage you if you want to have a \"higher than typical\" range to start with. Once you've used Loop for a while, you can revisit this setting.

Guardrails for Correction Range

"},{"location":"loop-3/therapy-settings/#manual-vs-automated-dosing","title":"Manual vs Automated Dosing","text":"

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.

"},{"location":"loop-3/therapy-settings/#pre-meal-range","title":"Pre-Meal Range","text":"

Your Pre-Meal Range is used to temporarily lower your glucose target before a meal to impact post-meal glucose spikes.

The graphic below shows the information screen presented during onboarding or when user taps the information icon, \u24d8.

The GIF below shows three screens from various scenarios. The red box indicates where the user taps. If the user chooses to leave Pre-Meal not set, the Pre-Meal icon in the tool bar is disabled. Some users prefer this.

Note

Guardrails for Pre-Meal Range

"},{"location":"loop-3/therapy-settings/#carb-ratios","title":"Carb Ratios","text":"

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

Guardrails for Carb Ratios

"},{"location":"loop-3/therapy-settings/#basal-rates","title":"Basal Rates","text":"

Your Basal Rate of insulin is the number of units per hour that you want to use to cover your background insulin needs.

Guardrails for Basal Rates

"},{"location":"loop-3/therapy-settings/#delivery-limits","title":"Delivery Limits","text":"

Delivery Limits are safety guardrails for your insulin delivery.

"},{"location":"loop-3/therapy-settings/#maximum-basal-rate","title":"Maximum Basal Rate","text":"

Maximum Basal Rate is the maximum automatically adjusted basal rate that Loop is allowed to enact to help reach your correction range. Some users choose a value 2, 3, or 4 times their highest scheduled basal rate. Work with your healthcare provider to choose a value that is higher than your highest scheduled basal rate, but as conservative or aggressive as is comfortable.

If the Dosing Strategy is configured to Temp Basal Only, then the maximum basal rate can be used to limit how much extra insulin can be supplied automatically.

Guardrails for Maximum Basal Rate

"},{"location":"loop-3/therapy-settings/#maximum-bolus","title":"Maximum Bolus","text":"

Maximum Bolus is the highest bolus amount that you will allow Loop to recommend at one time to cover carbs or bring down high glucose. The value the user selects for Maximum Bolus is also used to set a maximum level of IOB for automated dosing.

  1. Maximum Bolus is the largest single bolus that Loop will recommend or allow the user to bolus in a single action
  2. Maximum Automatic IOB is two times the value of Maximum Bolus
    • The Loop algorithm will not automatically dose any value that would cause the user's IOB to exceed Maximum Automatic IOB
    • The user can exceed Maximum Automatic IOB with a manual bolus
    • The recommended manual bolus amount is limited by Maximum Bolus

If you manually enter a value in the Bolus screen that is greater than the Maximum Bolus setting and press Deliver, Loop will show a warning message and refuse to bolus that amount.

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.

If the Dosing Strategy is configured to Automatic Bolus, then the maximum bolus that is automatically supplied is 40% of the maximum bolus, but this can be applied at 5-minute intervals. Automatic dosing is limited to keep the user's IOB less than two times the Maximum Bolus setting.

Guardrails for Maximum Bolus

"},{"location":"loop-3/therapy-settings/#insulin-sensitivities","title":"Insulin Sensitivities","text":"

Your Insulin Sensitivities refer to the drop in glucose expected from one unit of insulin over the full duration of the insulin action time. You may have also seen the term Correction Factor or Insulin Sensitivity Factor (ISF). These are all referring to the same setting.

Guardrails for Insulin Sensitivities

"},{"location":"loop-3/therapy-settings/#guardrails-for-settings","title":"Guardrails for Settings","text":"

Loop has guardrails for Therapy Settings.

Experienced Loopers

The guardrails for each therapy setting used by Loop can be modified with Code Customization.

mmol/L

People using mmol/L should avoid the red (the min or max end points) glucose values for their settings. They sometimes cause a crash.

The font color in the value picker has the following meaning:

Mobile Device

"},{"location":"loop-3/therapy-settings/#guardrails-for-glucose-safety-limit","title":"Guardrails for Glucose Safety Limit","text":"Units limit min max limit mg/dL 67 74 80 110 mmol/L 3.7 4.2 4.4 6.0

Glucose Safety Limit Info

Top value available on the picker limited by lowest of:

"},{"location":"loop-3/therapy-settings/#guardrails-for-correction-range","title":"Guardrails for Correction Range","text":"Units limit min max limit mg/dL 87 100 115 180 mmol/L 4.8 5.6 6.3 10.0

Correction Range Info

Bottom value available on the picker limited by highest of:

"},{"location":"loop-3/therapy-settings/#guardrails-for-pre-meal-range","title":"Guardrails for Pre-Meal Range","text":"Units limit min max limit mg/dL n/a safety 106 130 mmol/L n/a safety 5.9 7.2

Pre-Meal Range Info

Bottom value available on the picker limited by highest of:

"},{"location":"loop-3/therapy-settings/#guardrails-for-basal-rates","title":"Guardrails for Basal Rates","text":""},{"location":"loop-3/therapy-settings/#guardrails-for-maximum-basal-rate","title":"Guardrails for Maximum Basal Rate","text":""},{"location":"loop-3/therapy-settings/#guardrails-for-maximum-bolus","title":"Guardrails for Maximum Bolus","text":"

The maximum bolus is limited by your pump, but it is a good idea to limit it to the maximum you use for a common \"big\" meal. This limits the bolus for a single manual dose.

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.

"},{"location":"loop-3/therapy-settings/#guardrails-for-carb-ratios","title":"Guardrails for Carb Ratios","text":"

Remember, CR goes in the denominator when calculating insulin dose for carbs. So the min - max values in the table below correspond to stronger - weaker values for CR.

Units limit min max limit g/U 2.0 4.0 28.0 150.0"},{"location":"loop-3/therapy-settings/#guardrails-for-insulin-sensitivities","title":"Guardrails for Insulin Sensitivities","text":"

Remember, ISF goes in the denominator when calculating insulin dose for a correction. So the min - max values in the table below correspond to stronger - weaker values for ISF.

Units limit min max limit mg/dL/U 10 16 399 500 mmol/L/U 0.6 0.9 22.1 27.8"},{"location":"nightscout/loop-caregiver/","title":"Loop Caregiver","text":""},{"location":"nightscout/loop-caregiver/#the-loop-caregiver-app","title":"The Loop Caregiver App","text":"

The Loop Caregiver app is under development to make remote commands easier to implement and monitor.

"},{"location":"nightscout/loop-caregiver/#minimum-requirements","title":"Minimum Requirements:","text":"
  • Loop\u00a0version 3.2.0 or newer
    • version 3.0 works but is not recommended for other reasons
    • version 3.3 and higher offers improved feedback to the Loop Caregiver user
  • iOS 16 or newer for Loop Caregiver phone
  • Nightscout version 14.2.6
"},{"location":"nightscout/loop-caregiver/#prerequisites","title":"Prerequisites:","text":"
  • Complete all 4 steps on the Remote Configuration page:
    • Step 1: Update the Looper's iPhone settings
    • Step 2: Apple Push Notifications
    • Step 3: Add APN to Nightscout
    • Step 4: Test Remote Overrides
  • Read the Remote Commands page and pay special attention to these 2 sections
    • FAQs on Remote Overrides
    • Warnings on Remote Commands

Older Nightscout Versions

If you ignore this minimum version requirement - what happens:

  • If you attempt to use the carb entry in the past or future, the caregiver app accepts it but the remote commands accepted by the Loopers phone show up at the current time - not when the caregiver intended to insert carbs
  • Please take the time to update your Nightscout site to master
  • Nightscout 14.2.6 was released 30-Sep-2022 as Classic Liquorice

If you use Loop Caregiver, please join Loop Caregiver App Zulipchat stream.

As with all development code, monitor Zulipchat for announcements, report any problems you experience, be prepared to build frequently, and pay attention.

"},{"location":"nightscout/loop-caregiver/#build-the-loop-caregiver-app","title":"Build the Loop Caregiver App","text":"

You can build the Loop Caregiver app using the Build with Browser method or the Build with Mac method.

"},{"location":"nightscout/loop-caregiver/#build-with-browser","title":"Build with Browser","text":"

The Build with Browser method is documented on the Build Other Apps with Browser page.

"},{"location":"nightscout/loop-caregiver/#build-with-mac","title":"Build with Mac","text":"

A build script is available to assist in building Loop Caregiver. This should be straightforward for anyone who has previously built \u00a0Loop 3\u00a0 using the script.

  • Open a terminal window.
  • Spot the line below that starts with /bin/bash
  • Click the gray copy button () located near the bottom right side of that line (should say Copy to Clipboard when you hover the mouse over it). Once clicked, a confirmation message that says Copied to Clipboard will appear on your screen. Copy and Paste to start the BuildLoopCaregiver script
    /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildLoopCaregiver.sh)\"\n
  • Important: Click anywhere in the terminal before trying to paste
  • Paste the line into the Terminal window.
    • on Mac, you can do this in one of the following ways:
      • Press Cmd+V
      • or Press Ctrl+click and select Paste from the menu
      • or select Edit => Paste (i.e. click the Edit menu at the top of the Mac screen then click Paste).
    • on PC (Virtual Mac):
      • Press Ctrl+V
  • Once the line is pasted, hit Return (Enter) to execute the script.
  • The script displays the directions for downloading and building. Please read them carefully.

Read Carefully

The output you see in the Terminal may look very similar to when you build the Loop app from a script.

It is pulling down a clone from a different location (LoopKit/LoopCaregiver). It uses some modules from Loop. The target and scheme are automatically selected for Loop Caregiver and if you follow directions for a paid Developer account, the signing is automatic.

"},{"location":"nightscout/loop-caregiver/#use-the-loop-caregiver-app","title":"Use the Loop Caregiver App","text":"

Some limited directions for using the Loop Caregiver app are provided - please also read the Zulipchat stream to stay up-to-date with improvements - especially if you are using a development branch of \u00a0Loop.

"},{"location":"nightscout/loop-caregiver/#add-looper-to-the-loop-caregiver-app","title":"Add Looper to the Loop Caregiver App","text":"

You must add a Looper to continue with the Loop Caregiver app as shown in the graphic below.

  • On the\u00a0Loop\u00a0phone:

    • Tap on Loop -> Settings -> Services -> Nightscout
    • Tap on the One-Time-Password row to see the QR code

    Pro-tip

    Take a screenshot of the QR code and store it on your computer.

    You can then add the QR code to Loop Caregiver without bothering your Looper.

    • Keep the screenshot secure
    • Do not share the QR screenshot when asking for help

  • On the Loop Caregiver phone:

    • Tap on Loop Caregiver -> Settings
    • Enter the name of the Looper, the Nightscout URL (use \u00a0 https://\u00a0) and API_SECRET
    • Touch the QR code row - this opens the camera - point the camera at the QR code from Looper's phone

You can add additional more people under settings. (*Loop Caregiver * can monitor more than one Looper).

"},{"location":"nightscout/loop-caregiver/#main-screen-of-the-loop-caregiver-app","title":"Main Screen of the Loop Caregiver App","text":"
  • Loop Caregiver uses a lot of features from\u00a0Loop\u00a0with some Nightscout-like features in the Timeline.

The Timeline:

  • Autoscales the vertical display for glucose reported over the last 24 hours (plus the forecast if that is turned on)
    • Show Prediction for Timeline is turned off in the graphic below.
  • Horizontal display can be adjusted using the dropdown hours selector and scrolling left/right.
  • A double tap on the Timeline alternates between 1 and 6 hour display

You can also use the Loop Caregiver -> Settings screen to modify:

  • Units used for glucose display: mg/dL or mmol/L
  • Include the\u00a0Loop\u00a0forecast display on the Timeline chart as well as the Glucose chart of the main display (Show Prediction is turned off in the graphic above)
"},{"location":"nightscout/loop-caregiver/#issue-remote-commands-with-the-loop-caregiver-app","title":"Issue Remote Commands with the Loop Caregiver App","text":"

You issue override, carb, and bolus commands using a toolbar similar to the one seen on\u00a0Loop. In the example graphic above, the carb and bolus entries visible were issued remotely.

Carb and bolus commands each require authorization before they are accepted. The authorization (FaceID, Fingerprint, or passcode) matches that required to unlock the Loop Caregiver 's phone.

The use of Loop Caregiver makes remote commands much easier and more reliable.

Go back and review the details about Remote Commands before using the app.

"},{"location":"nightscout/loop-caregiver/#troubleshooting","title":"Troubleshooting","text":"

Troubleshooting steps are found on the Remote Errors page.

"},{"location":"nightscout/new-user/","title":"New Nightscout","text":""},{"location":"nightscout/new-user/#why-nightscout","title":"Why Nightscout?","text":"

Nightscout is not required, but is recommended for Loop

  • A Nightscout site provides a dashboard for remote viewing of Loop actions including the temporary basal rates Loop is setting, the current insulin on board, or a recent bolus and carb entry
  • A Nightscout site provides reports for retrospective review of your settings
  • You will want a Nightscout site:
    • If you are a parent of a little Loop user
    • If you want to see Loop's actions anywhere other than the Looper's iPhone
    • If you want to ask a mentor for help adjusting your settings
    • If you want to prepare reports to evaluate your own settings
    • If you want to prepare reports to hand to your doctor
"},{"location":"nightscout/new-user/#setup-nightscout","title":"Setup Nightscout","text":"

Please visit Nightscout: Documentation to read about Nightscout. There are several options, mentioned in that documentation, for setting up your Nightscout site.

  • You can choose one of many free (except for your time) DIY methods
  • You can choose one of many DIY methods where you pay a monthly fee for data storage
  • You can choose a managed site (for a monthly fee) that creates your site, keeps the software up to date and provides data storage
  • Social Media sites for announcements, help and discussion:
    • CGM in the Cloud Facebook group
    • Nightscout Discord Channel

Once your Nightscout site is operational and you've read the information about using your site, return to LoopDocs to follow the directions on the LoopDocs: Nightscout with Loop page.

Comments

Most of the free DIY methods provide sufficient storage for a single Loop user, but will require you to delete older data after a year or two of use. The one exception is the Google Cloud method which includes multiple GB of storage.

If there are multiple Loopers in your family and you want to stay in the \"free\" tier, each will need their own site to stay under the monthly usage limitations. That means an account for each user under different email addresses for each user.

\"Free\" sites might potentially stop being \"free\" in the future.

One of the Nightscout as a Service providers will not allow you to put in your own Apple Push Notification variables, you must use theirs. If you have no plans to use remote commands via Nightscout, this will not affect you. If you decide to use remote commands, you may need to switch to a different service or get Loop through that same provider for an extra monthly fee.

"},{"location":"nightscout/new-user/#configure-nightscout-to-use-with-loop","title":"Configure Nightscout to use with Loop","text":"

There are a few Loop-specific variables you should configure to get the most out of your Nightscout site. Follow the instructions on the LoopDocs: Nightscout with Loop page.

"},{"location":"nightscout/new-user/#add-nightscout-to-loop","title":"Add Nightscout to Loop","text":"

Once you finish setting up your new Nightscout site, don't forget to enter your website URL and API_SECRET into your Loop settings, LoopDocs: Services - Nightscout. This way Loop will have access to your Nightscout site to upload all the wonderful data.

"},{"location":"nightscout/new-user/#nightscout-troubleshooting","title":"Nightscout Troubleshooting","text":"

If your Nightscout site is not showing CGM (and Loop, if you are Looping) data within about 10 minutes of finishing your setup, then please follow the steps on the Nightscout: Troubleshooting page.

"},{"location":"nightscout/ns-crossref/","title":"Nightscout Cross Ref","text":""},{"location":"nightscout/ns-crossref/#nightscout-documentation","title":"Nightscout Documentation","text":"

A number of pages that used to be in LoopDocs have been moved to the Nightscout documentation. To prevent duplication and inconsistency, those pages have been removed from LoopDocs. A cross-reference to the Nightscout pages is provided below.

  • You can always use the search function of Nightscout: Documentation to find any topic
"},{"location":"nightscout/ns-crossref/#remote-notifications","title":"Remote Notifications","text":"

While the Loop app sends notifications locally on the Loop user's iPhone, parents and caregivers may want those messages on their phones, too. We can achieve this functionality through a combination of Nightscout, IFTTT, Google, and Pushover.

  • Please see
    • Nightscout: Configurations: Pushover
    • Nightscout: Remote Notifications
"},{"location":"nightscout/ns-crossref/#loop-follow","title":"Loop Follow","text":"

Loop Follow was created by Jon Fawcett who took ideas from multiple other apps to create a single app to assist in his caregiving role. It is popular with Loopers who like the display and notifications as well as Loop caregivers. It can work with just the Dexcom Share credentials and/or the Nightscout URL and allows for easy customization of alerts and alarms. Jon handed over maintenance of this app to the Loop and Learn team.

  • Please see
    • Loop and Learn: Loop Follow page
    • Loop and Learn Facebook group
"},{"location":"nightscout/ns-crossref/#pebble-watch","title":"Pebble Watch","text":"

LoopDocs had a page specifically about the Pebble Watchface called SkyLoop Predict, which is no longer being supported. The Nightscout Documentation provides information about many methods for displaying your Nightscout data on a variety of wearable devices.

  • Please see
    • Nightscout: On Your Watch
"},{"location":"nightscout/ns-crossref/#reports","title":"Reports","text":"

Nightscout offers some fantastic data-crunching report tools.

  • Please see
    • Nightscout: Reports
"},{"location":"nightscout/overview/","title":"Nightscout Overview","text":""},{"location":"nightscout/overview/#overview","title":"Overview","text":"

Nightscout is an excellent tool for remotely viewing Loop actions. Nightscout can act as a stand-alone tool or be integrated with Loop. (Nightscout also integrates with other open-source hybrid closed loop systems such as OpenAPS, AndroidAPS and iAPS. LoopDocs focuses on Loop.)

When integrated with Loop, Nightscout provides monitoring of Loop activities such as viewing history of glucose, carbs, boluses, temp basals and overrides; troubleshooting Loop errors; and provides extensive reports for analyzing data trends and patterns. These reports assist when Loop Therapy Settings need to be adjusted.

For caregivers, Nightscout enables remote monitoring and even the ability to issue remote commands through Nightscout when both Loop and Nightscout are properly configured. There are several pages starting at LoopDocs: Remote Overview that provide documentation on this feature. If you are a caregiver, this summary of remote capabilities may encourage you to look into Nightscout.

Remote Commands

  • Loop 2.2.x
    • Overrides can be enabled and disabled
  • Loop 3
    • Overrides can be enabled and disabled
    • Carbs can be entered
    • Boluses can be commanded
    • Loop Caregiver app (under development, iOS only) enables the following from the caregiver's phone
      • monitor Loop
      • issue remote commands for carbs, bolus, and overrides

If you plan to use remote commanding with Nightscout, please read these links with additional information:

  • Set Up Remote for Nightscout
    • Paid Providers and Remote Configuration

Nightscout is useful for many who use Loop. Adults who take care of themselves find the reports and analysis methods from Nightscout provide effective tools to monitor their settings and provide reports for their health care provider. It also stores Loop configurations so they can be reviewed. With Loop 3, the saved Nightscout profiles can be downloaded to a new Loop installation or a new phone for quick onboarding, should you ever need to start fresh.

Setting up a Nightscout site is described in a separate web site: Nightscout: Documentation.

There are Nightscout apps in your iPhone App Store that allow you to view the Nightscout site after you've configured it, or you can use a web browser to view the data. The app alone is not enough - you need to follow the steps to configure your own Nightscout site and obtain your specific Nightscout URL.

  • Nightscout is highly recommended for Loop users, especially for caregivers helping someone use Loop
  • Nightscout displays are often the easiest way to troubleshoot Loop settings if you are having problems and seeking input from others
  • Nightscout provides reporting features for longer-term review and preparing information for your physician
"},{"location":"nightscout/overview/#nightscout-documentation","title":"Nightscout Documentation","text":"

There used to be a lot of Nightscout information found only in LoopDocs, but that was transferred and subsequently updated in Nightscout: Documentation. The information that remains in LoopDocs about Nightscout is Loop specific. So you may be jumping back and forth between the two sets of documents.

  • If you see the Nightscout Owl logo in upper left you are in the Nightscout website
  • If you see the LoopDocs green-loop logo in upper left you are in the LoopDocs website
  • While in the Nightscout tab of LoopDocs, most links have a Nightscout or LoopDocs in the link name
  • Suggestion: open the Nightscout: Documentation in a separate tab or window of your browser for easy access to both websites
"},{"location":"nightscout/overview/#nightscout-with-loop","title":"Nightscout with Loop","text":"

This page provides a general discussion about the Nightscout display, as well as some Loop-specific display information. Over time, interactions between Loop and Nightscout were improved. The information on this page has been updated for Loop 3 and Nightscout version 14.2.6 (or later). Older versions may exhibit some differences in the display of Loop information on the Nightscout site.

"},{"location":"nightscout/overview/#loop-uploads-to-nightscout","title":"Loop Uploads to Nightscout","text":"

The Nightscout display updates when the Loop phone is connected to the internet via WiFi or cellular service. When the uploads stop, the Loop pill becomes \"stale\" (cannot open it) after 15 minutes.

Pills are the little information boxes. They are Nightscout: Plugins that must be enabled with configuration variables and then the display for each pill can be turned on or off within your Nightscout site.

If upload to Nightscout is interrupted, Loop 3 stores up to 7 days of Nightscout information in a local buffer on the phone, and will attempt to upload later when access is restored. Once access is restored, a stale Loop Pill may require 15 minutes before it will open to display additional Loop information.

The Carb pill on the Nightscout site is populated by Loop when Loop is actively uploading to Nightscout - but it may lag the value displayed in the Loop pill by one loop cycle and it will display 0 COB within 5 to 10 minutes if the upload is interrupted. In other words, if the COB pill shows 0 unexpectedly and Loop pill is active, you can believe the value shown in the Loop pill.

"},{"location":"nightscout/overview/#loop-2-red-loop-warning","title":"Loop 2 Red Loop Warning","text":"

With Loop 2.2.9 and earlier versions, when a Nightscout site is selected in Loop Services and is unable to upload messages to that site, Loop keeps trying to upload the buffer of stored messages. This could lead to sluggish behavior in Loop or even cause a \u00a0Red Loop. This can happen if the Nightscout site is not accessible (no WiFi or cellular coverage) or if the database is full and not accepting messages.

Step 1: Remove Nightscout URL from Loop Services

Step 2: Figure out why the Nightscout site is not accepting uploads from Loop and fix that problem.

  • Nightscout: Troubleshooting
  • Nightscout: Database Management

Step 3: Add Nightscout URL to Loop Services

Note - the method used by Loop 3 is not subject to this same problem.

Do you want to know more? (Click to open)

For those who want to know more:

There is a big architectural change between Loop 2 and Loop 3 for remote data services like Nightscout.

It used to be that Loop would keep trying to upload data to Nightscout. If a site could not be reached or would not accept data, that could cause large backlogs. Loop 2 could slow down by trying to keep uploading the backlog. The new system does not allow for this. Uploaders individually keep track of where they are in the upload stream via a lightweight \u201cquery handle\u201d, and if the data in Loop data store expires before upload, that data will be missing in Nightscout.

Loop 3 saves 7 days of information in the data store.

"},{"location":"nightscout/overview/#nightscout-dashboard","title":"Nightscout Dashboard","text":""},{"location":"nightscout/overview/#blood-glucose","title":"Blood Glucose","text":"

Glucose readings from the CGM are shown in green, yellow, or red in the main Dashboard of Nightscout. (The graphic above was generated with Colors enabled in Nightscout; there are other display options.) You can adjust your high and low glucose alarm thresholds in Nightscout by modifying configuration variables. This is optional - defaults are provided if you do not set them. The alarm thresholds affect the color of the displayed CGM data points and, if enabled, determine when an audible and visible alarm sounds. The Nightscout alarm thresholds will not affect Loop performance. Loop only uses the glucose correction ranges in the Loop app settings.

The main dashboard (upper section) for Nightscout displays the time duration you have selected (in the example above, 12 hours). The bottom of the screen shows the last 48-hours of glucose trends. You can scan backward by dragging the bottom timeline to the left, if you want to review specific Loop actions or data in the last two days.

"},{"location":"nightscout/overview/#sage-cage-bage","title":"SAGE, CAGE, BAGE","text":"

The SAGE, CAGE, and BAGE pills are for Sensor Age, Cannula Age, and (pump) Battery Age. These optional pills track the time since your CGM sensor, Pump site, and Pump battery were last changed. You can set up custom alerts to remind you when it is time to change the devices, or simply use the visuals to keep track of your particular timing for site/sensor changes. When these items do not auto-upload, you can use the Nightscout Careportal to input the changes.

  • Loop 3.3.0 or newer: The SAGE and CAGE fields are automatically uploaded
  • Loop 3.2.x or older: None of the fields are automatically uploaded
"},{"location":"nightscout/overview/#carbs","title":"Carbs","text":"

Carbs are automatically uploaded to Nightscout by the Loop app. The amount of carbs on board (active carbs or COB) can be seen by clicking the Loop pill. The size of a white carb dot on the graph is proportional to the amount of carbs entered...bigger meals get bigger dots. Loop does not read carbs from Nightscout for use in looping calculations, it only uploads carbs to Nightscout that have been entered in the Loop app.

"},{"location":"nightscout/overview/#boluses","title":"Boluses","text":"

Insulin boluses are automatically uploaded to Nightscout by the Loop app. The bolus is shown as a filled-in blue lower-half of the dot, and the specific amount of the bolus is also shown. There may be a separation between the bolus and the carb entry, especially if the user preboluses a meal.

The bolus is uploaded to Nightscout as soon as it starts and Insulin on board (active insulin or IOB) is updated in the Loop pill. Should the bolus be interrupted, the Nightscout information is updated when the Loop information updates (assuming internet access is active).

"},{"location":"nightscout/overview/#temp-basals","title":"Temp Basals","text":"

Your current basal profile is automatically updated to Nightscout whenever it is changed by Loop. The dashed blue line represents the scheduled basal profile. The solid blue lines indicate the actual basal amounts set for a given time...so as Loop sets temp basals higher or lower than your scheduled basal rate. If the graph and Loop pill do not agree, you should believe the Loop pill.

"},{"location":"nightscout/overview/#predicted-glucose","title":"Predicted Glucose","text":"

The purple line to the right of the glucose is Loop predicted glucose. Watching the behavior of that purple line can help you understand why Loop is making decisions regarding high or low temps. You can read more on that topic in the LoopDocs: Algorithm section of these docs. If you don't see the prediction (and all other Nightscout and Loop settings are configured), tap on the 3 dots to the right of the 24 to reveal the choice to display AR2 prediction or Loop prediction. Adjust the check boxes to show just the Loop prediction.

"},{"location":"nightscout/overview/#loop-pill","title":"Loop Pill","text":"

The Loop pill is the little display box which, when hovered over or clicked, will provide additional information about recent Loop activities and status. Information included is the last time Loop ran, the temp basal set, IOB, and COB. Looking at the Loop pill is a quick method for assessing if your loop is currently active, as well.

Loop Pill status indicator symbols

X Error in Loop

\u03d5 Recommending basal or bolus, but not enacting (open loop or pump suspended)

\u2301 Enacted a new temp basal

\u21bb Loop is continuing with last temp basal, no change

\u26a0 Warning indicating Loop is either red or has failed to upload to Nightscout for a longer period of time.

Mouse over or touch the Loop pill to view a tooltip containing one or more of the latest status messages. The most up-to-date Nightscout also includes information in the Loop pill for the minimum and maximum predicted glucose, eventual and predicted glucose.

"},{"location":"nightscout/remote-commands/","title":"Remote Commands","text":""},{"location":"nightscout/remote-commands/#requirements","title":"Requirements","text":"

All remote commands require the configuration steps from Remote Configuration.

  • A new One-Time Password (OTP) is required for each remote command that issues a bolus or adds a carb entry
    • The OTP updates every 30 seconds
    • Both the sending device and the Loop phone must have automatic time enabled
  • Remote Overrides do not require a One-Time Password (OTP)
    • There are some versions of Nightscout that provide a row for entry of an OTP for Temporary Override in the Nightscout Careportal
    • Leave that row blank

Do I have to use Loop Caregiver ?

There are a number of methods for using remote commands.

Things everyone needs to know are covered on this page, so you should read it regardless of how you plan to issue remote commands.

If you decide on Loop Caregiver , review both this page and \u00a0Loop Caregiver page.

"},{"location":"nightscout/remote-commands/#qr-code","title":"QR Code","text":"

On the\u00a0Loop\u00a0phone, Nightscout must be included under the Loop -> Settings -> Services section. Navigate to Services and select Nightscout. Tap on the One-Time Password row to view the QR code.

When you need to configure your authentication method, you can either use a saved QR screenshot or scan the QR on the\u00a0Loop\u00a0phone.

Options:

  • Have your Looper (or at least their phone) available
  • Save a screenshot of their QR code
    • Keep this secure
    • Do not share the QR screenshot when asking for help

While you are on the Settings -> Services -> NightScout screen, notice that the 6-digit number on the One-Time Password row updates every 30 seconds.

"},{"location":"nightscout/remote-commands/#set-up-an-authentication-app","title":"Set up an Authentication App","text":"

You need to set up an authentication app to generate one-time-passwords for remote bolus and carbs.

One of the nice features of Loop Caregiver is that it handles the one-time password (OTP) requirements for you.

But even if you choose to use Loop Caregiver , you should configure an authentication app for cases where you don't have access to your Loop Caregiver phone.

There are several authentication apps that support one-time passwords.

"},{"location":"nightscout/remote-commands/#apple-keychain","title":"Apple Keychain","text":"

If you are using an iPhone or a Mac to issue remote commands through a browser or Nightscout app, you can use the \u00a0Apple Keychain\u00a0 which has native support to store passwords and generate one-time passwords.

To set up your Nightscout credentials in \u00a0Apple Keychain:

On the Caregivers device (iPhone or Mac):

  • Go to Apple Settings -> Passwords

  • Tap the + Button up top to add a new Password

  • You will enter your Nightscout credentials

    • Website: Enter a portion of the Nightscout URL, without the leading \u201chttps://\u201d
    • Username: Enter the full Nightscout URL including the leading \u201chttps://\u201d part
    • Password: Enter the API_SECRET for the Looper's Nightscout site
    • Tap Done
  • Next, you are offered a screen that allows you to set up a Verification Code
    • If you need to come back later, you can find that screen again
    • Go to Apple Settings -> Passwords -> Tap the row with your Nightscout URL
  • Tap \u201cSetup Verification Code\u201d
    • This is where you can scan your QR code from the\u00a0Loop\u00a0phone or the saved QR screenshot
    • As soon as the camera reads the QR code, an OTP will begin to appear
    • If the\u00a0Loop\u00a0phone is handy, wait a cycle or two and ensure the 6-digit OTP on the password screen matches that on the\u00a0Loop\u00a0phone and they update at the same time
    • Click Passwords on the upper left to return to the previous screen
  • Select Passwords Options
    • Enable the Autofill Passwords and check Keychain
"},{"location":"nightscout/remote-commands/#using-safari","title":"Using Safari","text":"
  • When you use Safari to view your Looper's Nightscout site and choose the Careportal ()
    • Choose a remote command from the Event Type drop-down menu (remote commands are at the bottom of the list)
    • The OTP will be offered to you for every row - ignore it when entering Carb amount or Absorption Time, or Bolus Amount
    • Select it for the OTP row
    • Note that OTP is not required for Remote Overrides - leave that row blank
"},{"location":"nightscout/remote-commands/#other-authentication-apps","title":"Other Authentication Apps","text":"

There are other Authentication apps available. Here are a few options that you can download from your phone\u2019s app store:

  • 1Password
  • Authenticator
  • Authy
"},{"location":"nightscout/remote-commands/#faqs-for-all-remote-commands","title":"FAQs for all Remote Commands","text":"

  1. If I have multiple Nightscout sites because I support multiple people with T1D looping, do I need multiple APNs Keys? Answer: No. If you support multiple people, you can use the one APNs key in each of their Nightscout sites.

  2. How can I tell if it worked? Answer: You should see your override pill in Nightscout, with the NEXT Loop\u00a0cycle, reflecting that the desired remote action took place. If you are near the\u00a0Loop\u00a0phone, you should see the new override within less than 30 seconds or so.

"},{"location":"nightscout/remote-commands/#faqs-on-remote-overrides","title":"FAQs on Remote Overrides","text":"

Don't forget to read Loopdocs: Overrides.

For remote overrides in particular:

  1. Can I set a different override in Nighscout than I have programmed into\u00a0Loop\u00a0app? Answer: No. You will only be able to enact override presets already programmed into the Loop app.

  2. If I didn't start the override in Nightscout (it was started in\u00a0Loop\u00a0itself), can I still use Nightscout to cancel it? Answer: Yes. You can cancel an override set in\u00a0Loop\u00a0with a Nightscout-set cancel \"temporary override\" command in the careportal.

  3. Can I replace an override set in\u00a0Loop\u00a0with an override set in Nightscout? Answer: Yes.

  4. Can I see on Nightscout when a temporary override has been set using the looper\u2019s phone? Answer: Yes. There will be a grey bar with the name of the override noted and the Loop pill will display the targets and duration. Remember, there is a KNOWN issue with the grey bars, so use the pill as your best guide.

  5. Can a looper cancel a remote override? Answer: Yes. They can tap the heart icon in\u00a0Loop\u00a0so that it is no longer highlighted. This turns off the override, regardless of where it was initiated.

  6. I set a remote override in Nightscout but the Looper tapped the heart symbol in the Loop app, so the override turned off. Will the override get reinstated the next time\u00a0Loop\u00a0completes with internet access? Answer: No. The APN is only sent once. You can set the remote override again if need be.

  7. Can I schedule a remote override ahead of time using Nightscout? Answer: No. When you set a remote override in Nightscout, it starts immediately and lasts for the duration programmed for that override in the Loop app. You can only set an override in advance using the Loop app.

"},{"location":"nightscout/remote-commands/#remote-commands","title":"Remote Commands","text":"

Remote Commands to deliver a bolus or add a carb entry require a \u00a0One Time Passcode\u00a0 (OTP).

Minimum Versions: Loop 3\u00a0 and \u00a0Nightscout 14.2.6

If your Nightscout version does not meet that minimum requirement, remote commands might be accepted but if they are, the time for the commands is always the current time. In other words, Carbs in the Past or Future might be accepted, but would be entered at the current time on the\u00a0loop\u00a0phone.

"},{"location":"nightscout/remote-commands/#warnings-on-remote-commands","title":"Warnings on Remote Commands","text":"

Duplicate Delivery Risk

We want to highlight a very important risk before you get started.

For safety, always assume a previous remote carbs/bolus was delivered. For motivation think of the following example:

  • You send a 5-unit remote bolus.
  • The bolus is delivered to the Looper.
  • Nightscout is having a temporary technical issue and doesn't show the bolus was received.
  • You are watching Nightscout and you don\u2019t see a delivery so you assume it failed.
  • You send another remote 5-unit bolus.
  • The second 5-unit bolus is delivered to the Looper (10 Units total).

You can see the danger of sending duplicate bolus/carbs so be careful. If a remote bolus/carb entry doesn\u2019t show in Nightscout, use your own judgment on whether enough time has passed to try again.

"},{"location":"nightscout/remote-commands/#remote-bolus-then-remote-carb","title":"Remote Bolus, Then Remote Carb","text":"

If sending both, choose Bolus then Carbs

If you plan to send a carb command remotely and later decide to issue a bolus command - STOP and consider.

There are 2 scenarios of concern that could lead to too much insulin:

  • Dosing Strategy is Temp Basal Only (temporary basal)
    • Loop\u00a0will initiate a max Temp Basal when it receives the carbs remote command
    • Your bolus is accepted next and takes place in addition to the high temporary basal
  • Dosing Strategy is Automatic Bolus
    • Loop\u00a0will initiate a percentage of the recommended dose when it receives the carbs remote command
    • Your bolus will be accepted and take place in addition to an automatic boluses or be rejected because a bolus is already in progress

Typically, sending a remote carb entry alone is sufficient for\u00a0Loop\u00a0to know about the carbs and begin to dose for them.

If you really want to both bolus for carbs and enter carbs, then do it in that order.

  1. The bolus, when accepted, may start a zero Temp Basal (temporary basal) (which is \"safer\")
  2. The carbs, when accepted, will cause the app to respond to the carbs
  3. In this case, the prediction includes both carbs and bolus

\u2757\ufe0f Remember - you should pause at least 60 seconds between remote commands or the One-Time-Password (OTP) will be rejected as having already been used.

"},{"location":"nightscout/remote-commands/#use-unique-times-for-remote-carbohydrate-entries","title":"Use Unique Times for Remote Carbohydrate Entries","text":"

Use unique times for remote carbohydrate entries

Instead of adding a second remote carbohydrate entry at an identical time, add one minute to the second entry.

This ensures that Nightscout keeps both entries.

Any Caregiver entering remote carbohydrates needs to be aware of how Nightscout decides what carbohydrates treatments are unique. If two entries have the same hour:minute:second time, Nightscout keeps only one of the entries.

  • It does not affect how the Loop app handles the remote carbohydrate entries it receives
    • The Loop app assigns a unique identifier to each entry; it doesn't depend just on the timestamp
  • It will affect Nightscout and thus LoopCaregiver displays
    • This might lead to the Caregiver thinking they need to send the remote carbohydrate again
    • But Loop has both entries

One example scenario:

  • A caregiver enters 10 g for lunch with a timestamp of 11:30, then waits for child to eat and glucose to start rising
  • They then want to \"edit\" that entry to 15 g, but that is not possible with remote carbohydrates
    • Instead they can add a new 5 g entry
    • They should enter the second entry at 11:31

Second example scenario:

  • A caregiver wants to enter two different absorption times using remote carbohydrates
    • The first entry eating time is at 11:30 for 10 g with 2 hour absorption
    • The second entry eating time is at 11:31 for 15 g wtih 4 hour absorption

The LoopCaregiver app was recently modified to use the seconds from when the new entry was created, instead of using hour:minute:00. This change makes it less likely that two entries with the same timestamp will collide. (One chance in 60.)

Any remote carbohydrate entry from the Nightscout careportal using the same hour:minute time, however, will be entered with 0 seconds.

  • If a second entry is made from the Nightscout careportal with the same hour:minute selection:
    • The Loop app accepts the second entry and treats it as a unique event
    • When the entry is reported to Nightscout from the Loop app as a carbohydrate event, the new event replaces the previous event in the Nightscout record

For more information, see:

  • Carb treatments disappearing in Nightscout
"},{"location":"nightscout/remote-commands/#using-remote-commands","title":"Using Remote Commands","text":"

There are four ways you can trigger your commands remotely; \u00a0Loop Caregiver (link takes you to a new page), Nightscout Careportal, Shortcuts, and IFTTT.

"},{"location":"nightscout/remote-commands/#loop-caregiver","title":"Loop Caregiver","text":"

Click the link above to read more about Loop Caregiver .

"},{"location":"nightscout/remote-commands/#nightscout-careportal","title":"Nightscout Careportal","text":"

To use remote commands in the \u00a0Careportal, you must configure Nightscout site according to the directions here in \u00a0Loopdocs\u00a0 in addition to setting up the Remote Configuration.

Pay particular attention to these entries in the ENABLE line: override careportal Loop. The order of the words in the ENABLE line is not important.

You'll also need to have your site authenticated so that your \u00a0Careportal\u00a0 is active to send remote overrides .

Once authenticated by entering your API_SECRET, there is a plus sign () in the upper right corner of your site. That is your Careportal. Tap the Careportal plus sign () and then scroll down in the event type menu to find Temporary Override. Within there, you will find all your\u00a0Loop\u00a0override presets already loaded for you.

"},{"location":"nightscout/remote-commands/#start-and-end-remote-override","title":"Start and End Remote Override","text":"

The Looper will see a banner notification that a remote command has been sent with details about that command and whether it succeeded (or not).

Canceling an override through Nightscout careportal is as simple as selecting the event type Temporary Override Cancel and submitting.

"},{"location":"nightscout/remote-commands/#command-remote-bolus-or-carb-entry","title":"Command Remote Bolus or Carb Entry","text":"

Open your Nightscout site in a browser or app.

  • Tap the Careportal plus sign () and then scroll down in the event type dropdown menu to find Remote Carb Entry or Remote Bolus Entry
  • Fill out the treatment log until you get to the OTP row
    • When using Safari, the OTP code is automatically offered - might need to tap twice
    • For other authentication apps (Authenticator, 1Password, etc)
      • Tap on the code in the authentication app and copy it to your clipboard
      • In Nightscout, paste that code into the OTP box
    • Click \u201cSubmit Form\u201d

Note that Loop will honor both the current OTP code and the one that just expired.

If the Looper is with you, you can see the notification on their phone. You can see the entry on the\u00a0Loop\u00a0carbohydrate or the insulin displays to see if it went through.

If the Looper is not with you, you should see the result in the Nightscout dashboard within 5 minutes.

"},{"location":"nightscout/remote-commands/#shortcuts","title":"Shortcuts","text":"

If you want to make your life SUPER AMAZING, check out using the iPhone's Shortcuts app. The Shortcuts app is for making little automations (like mini apps) that can integrate parts of your life. In this case, we've written a couple of shortcuts for you that integrate\u00a0Loop\u00a0overrides with Nightscout.

Important Note

Before you click on the download file below...save yourself some trouble.

  1. Download the Shortcuts app if you don't have it yet
  2. Choose to run any shortcut from the Gallery. It can be the laundry timer...I don't care, just pick one shortcut and run it.
  3. THEN, go to download the shortcut of your choice below. \u2139\ufe0f The shortcuts that aren't run through the Gallery option are called \"untrusted\". And you need a slider in your iPhone to trust the \"untrusted\" shortcuts you would be downloading here. But...in a lovely iOS glitch...that slider doesn't appear unless you've run a trusted shortcut first. So, run one now.
  4. Then, this slider will now be visible in the iPhone Settings app under the Shortcuts app menu.
  5. When you will see the message \"This shortcut cannot be opened because your Shortcuts security system settings don't allow untrusted shortcuts\"
  6. Open iPhone Settings and scroll down the list and tap the Shortcuts menu to turn on \"Allow Untrusted Shortcuts\".

Click these links on your iPhone and you'll be prompted to download the premade shortcuts (assuming you open the links in Safari browser on iPhone):

Comprehensive\u00a0Loop\u00a0Shortcut includes Set Remote Override, Cancel Override, Loop Troubleshooting Tips, Quick Text options, Manual BG entry, Bookmarks to websites, etc.

And if you want to save one click to get to these one functions more directly: these shortcuts are simplified to offer only one function:

Set Remote Override only shortcut

Cancel Override\u00a0 only shortcut

A couple notes about these shortcuts:

You need to open those links in the Safari browser on your iPhone. A confirmation will show to initiate the download.

After the download finishes, tap the button marked AA near your Safari address bar and tap Downloads (downloads) to find and open the downloaded Shortcut.

Wait a bit, and the shortcut's inner guts will be there...scroll ALL the way down to the bottom to click the button to save the untrusted shortcut

  1. When you enter your Nightscout URL in \u00a0the URL field\u00a0 of the\u00a0Loop\u00a0shortcut setup, make sure you don't include a \u00a0trailing /, or the API calls to Heroku will error out.
  2. When a remote override is set properly, you'll see an ok message displayed. If there is an error, you'll see an error message. Most errors will be that you have an API_SECRET wrong (make sure there isn't a space at the end of your API_SECRET that you don't see) or you failed to do the steps to setup Nightscout and update your\u00a0Loop\u00a0app as described in steps 1-3 above.
  3. You can absolutely customize these bits and pieces within the shortcut. Change the text messages, and change the links... It is totally up to you.
"},{"location":"nightscout/remote-commands/#ifttt","title":"IFTTT","text":"

If you want to walk uphill both ways in the snow carrying bags of uneven groceries, you can also set overrides remotely by using If This, Then That (IFTTT) integration. By using IFTTT, you can have single button presses on your phone that will set an override, log a cannula change, log a sensor change and much more.

  • Please see
    • Nightscout: Configurations: IFTTT Maker
    • Nightscout: IFTTT
"},{"location":"nightscout/remote-config/","title":"Remote Configuration","text":"

Page Summary

  1. Update the Looper's iPhone Settings
  2. Create a Key for an Apple Push Notifications service (APNs)
  3. Update Nightscout site and add some \"config vars\" lines in Nightscout site settings
  4. Test Remote Overrides
"},{"location":"nightscout/remote-config/#set-up-remote-for-nightscout","title":"Set Up Remote for Nightscout","text":"

You can use the Nightscout site to remotely set and cancel override presets remotely in the Loop app.

With \u00a0Loop 3, you can also send remote commands to add carbs and command a bolus. Remote bolus/carb commands have a minimum requirement of \u00a0Nightscout 14.2.6. If your Looper's Nightscout version does not meet that minimum requirement, remote commands might be accepted, but the time for the commands is always the current time. In other words, Carbs in the Past or Future might be accepted, but would be entered at the current time on the\u00a0Loop\u00a0phone.

After you complete the configuration, read the entire Remote Commands page - pay attention to the warnings and caveats. Test this while your Looper is sitting next to you so you can watch their phone.

Remote Nightscout Interface Caveats

  • Must use a paid \u00a0Apple Developer\u00a0 account to build\u00a0Loop
    • Apple Push Notifications\u00a0 (APN) service is not available with a Free account
  • When you build \u00a0Loop, the required APN information is tied to your Apple Developer account
    • You add your APN information to your Looper's Nightscout site
    • If you support multiple Looper's, you add the same APN variables to each of their Nightscout sites
  • There are many choices for building your own or paying someone to build a Nightscout site
    • The directions for only one of the options is documented on this page
    • Use that as a guide for your site
  • Nightscout Docs: Comparison Table
    • Warning: examine the Loop remote carbs/bolus row: subscription refers to a monthly fee
    • If a green check is missing, it might just be too new for evaluation
"},{"location":"nightscout/remote-config/#paid-providers-and-remote-configuration","title":"Paid Providers and Remote Configuration","text":"

There are several options to pay for a turn-key Nightscout service.

  • In order to enable remote commanding, your Nightscout site must be configured with information associated with the Apple Developer ID used to build the Loop app
    • Most Nightscout options allow you full access to your Nightscout configuration variables so you can add the required information
  • Please check out Nightscout: New User for up-to-date information about your Nightscout options
    • If you use the wizard, you can see more options when you select No to the question about contributing to research and development
    • If you choose T1Pal and want to use remote commands, you must also purchase your Loop app from them for an additional monthly fee - contact T1Pal for details

The rest of this page assumes that you built your Loop app and you have full access to the configuration variables for your Nightscout site.

"},{"location":"nightscout/remote-config/#step-1-update-the-loopers-iphone-settings","title":"Step 1: Update the Looper's iPhone settings","text":"

For remote commands to successfully deploy to a Looper's iPhone when the phone is locked, they must have Background App Refresh enabled.

  • The slider in iPhone -> Settings -> General -> Background App Refresh -> Loop must be enabled

Consequence if Looper's phone is not configured correctly:

  • If Background app refresh is not enabled, the remote overrides might only enact if the Loop app is open and the phone is unlocked

Keep Notifications Turned on for Looper's Phone

Typically, the Looper's phone has Notifications enabled for \u00a0Loop. In fact, if they don't, a red warning bar is prominently displayed.

There may be times when you really need\u00a0Loop\u00a0to be quiet, so you can turn off Notifications. The remote commands still go through but the Looper does not see a notification that this happened.

Best practice is to keep\u00a0Loop\u00a0Notifications enabled.

"},{"location":"nightscout/remote-config/#step-2-apple-push-notifications","title":"Step 2: Apple Push Notifications","text":"

The step is required for the Loop app to give permissions to your Nightscout site to remotely interact with it. To enable this, you need to create a key and grant it access to the \u00a0Apple Push Notification Service (APNS).

Reminder

This only works with the paid Apple Developer ID.

  1. To get started, go to the Keys section under Apple Developer's Certificates, Identifiers & Profiles and login with the Apple ID associated with your developer team that you used to build the Loop app.
  2. If not already open in your browser (compare with the below screenshot),
    • Click on Keys (located in the left-hand column).
    • Either click on the blue Create a new key button OR the plus button () to add a new key.

  3. In the form that appears, do the following:
    • Click the checkbox for enabling Apple Push Notifications service (APNs)
    • Enter a name for the key such as Nightscout (you can name it however you want, just make sure you know what the key is for by the name you choose).
    • Then click the Continue button in the upper right of the screen.

  4. In the screen that follows, click the blue Register button.

  5. In the screen that follows, click the blue Download button. This step will download a file with a name that starts with AuthKey and ends with .p8.

  6. Find your AuthKey downloaded file in your downloads folder. Double-click to open it and you will be presented a message asking how you'd like to open it. The graphic and instructions below are for a Mac. Make sure your editor does not change any characters in your APN key; use a text-only editor like NotePad (PC) or TextEdit (Mac). Click on Choose Application... and then select TextEdit as your application to open it with.

  7. When the file opens, it will look similar to the screenshot below. In a few minutes, after we do a few other steps first, we will need to highlight ALL OF THE CONTENTS of that file and copy it because we will be pasting it in Heroku or whichever Nightscout provider you are using. Yes, allllll of the contents. So, the easiest way is to:

    • Click inside that file
    • Highlight all the text, and then
    • Copy all the text to the clipboard (Cf. screenshot below).
      • On a Mac, press Cmd+A to select all, then press Cmd+C to copy the selection.
      • On a PC, press Ctrl+A to select all, then press Ctrl+C to copy the selection.

    You don't have to do it right now...just keep that window open in the background for now until we need it a little further down. Then we will copy all that text.

"},{"location":"nightscout/remote-config/#step-3-add-apn-to-nightscout","title":"Step 3: Add APN to Nightscout","text":""},{"location":"nightscout/remote-config/#update-nightscout-site","title":"Update Nightscout Site","text":"

You'll need to make sure your Nightscout site version is version 13.0.1 or newer for remote overrides and version 14.2.6 or newer for access to all the remote command features.

What is my Nightscout Version Number?

To find your Nightscout version number:

  • Tap on (\u2630) the hamburger button (3 horizontal lines stacked on each other) at the upper right, near the authentication button.
  • A context menu slides in from below the hamburger.
  • Scroll to the very bottom of this menu.
  • The version is located in the About section after the Settings section, (below the Save button).

This link should be used if you want to Nightscout: Update your Nightscout site.

Note for Google Cloud Users

The Nightscout with Google Cloud instructions include information about updating your site. Scroll down to the line (on that page) that says Update Nightscout.

"},{"location":"nightscout/remote-config/#add-apn-variables-to-nightscout","title":"Add APN Variables to Nightscout","text":"

In order to use remote overrides, you must add a couple of new variables. If you don't know how to update your Nightscout configuration, review Nightscout: Setup Variables and then come back.

The instructions in this section show Heroku images. If you are using a different method, you should be able to \"translate\" the steps.

Go to the Settings tab near the top of the screen on your Heroku app and then click on Reveal Config Vars.

Scroll down the bottom of the Config Vars lines until you find the last blank one. You are going to add three new rows of config vars for remote overrides as shown below:

KEY VALUE LOOP_APNS_KEY Enter the ENTIRE contents of the downloaded .p8 file including the BEGIN and END lines. Here's where you can use the Cmd+A and Cmd+C to highlight and copy all the text in that file so you can paste it into Heroku here for this new variable you are creating. LOOP_APNS_KEY_ID String of characters on the .p8 download file immediately following the underscore (_) and not including the file extension (.p8), or you can get it from your saved key in your developer account as shown next step, too. This is a part of the downloaded filename located after the underscore (_) and before the file extension (.p8). LOOP_DEVELOPER_TEAM_ID Get this value from the Loop app signing or in your \u00a0Apple Developer\u00a0 account's top right corner under your name LOOP_PUSH_SERVER_ENVIRONMENT (optional) Set this to production if you installed\u00a0Loop\u00a0remotely such as with TestFlight, Diawi, AppCenter, or an IPA. If you built directly to your phone in XCode with your phone plugged into to your computer, do not include this variable."},{"location":"nightscout/remote-config/#remote-build-config-var-requirement","title":"Remote Build Config Var Requirement","text":"

That last row of the table above is needed if you are using a remote build option such as LoopDocs: GitHub Build Actions or downloaded an archived file via Loop and Learn: Remote Build with Diawi. If you later return to a direct Xcode build to your phone, you must remove that config var or remote commands will not work.

When executed properly, you should have something that looks like this for the three (or four) new variables that you added:

"},{"location":"nightscout/remote-config/#baddevicetoken","title":"BadDeviceToken","text":"

When the Nightscout config var LOOP_PUSH_SERVER_ENVIRONMENT does not match the Loop app build method; the error message contains the phrase APNs delivery failed: BadDeviceToken.

  • If\u00a0Loop\u00a0was installed remotely (typically from TestFlight following GitHub Browser Build), you must have Nightscout config var LOOP_PUSH_SERVER_ENVIRONMENT set to production
  • If\u00a0Loop\u00a0was built using Mac, you cannot have LOOP_PUSH_SERVER_ENVIRONMENT as one of your Nightscout config vars
"},{"location":"nightscout/remote-config/#do-not-confuse-your-keys","title":"Do Not Confuse Your Keys","text":"

API Key vs APN Key

If you build with the Build with Browser, you may notice \u00a0the \u00a0Application Programming Interface (API)\u00a0 key\u00a0 has the same type of format as \u00a0the \u00a0Apple Push Notification (APN)\u00a0 key. The keys for both purposes are of type p8, but should not be confused.

The Secrets for building with GitHub use the API Key.

The config vars for Nightscout use the APN Key.

  • If you are using remote commands with Nightscout and building with the GitHub Browser build method, you must also add the config var of LOOP_PUSH_SERVER_ENVIRONMENT with a value of production to your Nightscout site or the remote commands will not work.
  • If you are using the Mac build method, you should not have a config var of LOOP_PUSH_SERVER_ENVIRONMENT entered - remove it if it is present.
"},{"location":"nightscout/remote-config/#step-4-test-remote-overrides","title":"Step 4: Test Remote Overrides","text":"

If remote overrides do not function, remote commands for delivering a bolus or adding a carb entry will not work either.

After you finish setting up your Nightscout site:

  1. Use the Looper's phone to set an override
  2. Make sure that override shows up on the Nightscout site
  3. Then using the \u00a0Nightscout Careportal, test that you can turn off that override
"},{"location":"nightscout/remote-config/#things-to-check","title":"Things to Check:","text":"
  • Remote overrides will not start working until after you activate an override in the app at least once
    • Activating an override from the\u00a0Loop\u00a0interface will upload the necessary push notification token to Nightscout which will enable remote commands to work
    • If your Looper gets a new phone - be sure to activate an override from the new phone before trying to use remote commands
  • Notifications must be allowed in\u00a0Loop
  • Give loop access to all health data
  • Enable Background App Refresh
  • Double check your Nightscout credentials
  • Low Power Mode may prevent background notifications from working
  • Some have found that activating the \u201cFocus\u201d and Do-Not-Disturb features on iOS can prevent push notifications from being delivered
    • Turn these off when troubleshooting to eliminate this as a source of problems
  • iOS 15.3.x: Note there are reports of Remote notifications not being received to the Loopers device for iOS version 15.3 and 15.3.1; this is fixed in iOS version 15.4
  • If you distribute the app remotely (i.e. TestFlight, Diawi, AppCenter), you must set a special Nightscout variable, LOOP_PUSH_SERVER_ENVIRONMENT to \u201cproduction\u201d, to enable push notifications
    • See Remote Build Config Var Requirement
"},{"location":"nightscout/remote-errors/","title":"Remote Errors","text":""},{"location":"nightscout/remote-errors/#loop-data-is-not-showing-in-nightscout","title":"Loop data is not showing in Nightscout","text":"
  • This is a\u00a0Loop\u00a0and/or Nightscout issue, not related to remote configuration
    • Review the LoopDocs: Nightscout with\u00a0Loop page
    • Check out links on the LoopDocs: Nightscout Troubleshooting page
  • Make sure Looper's phone is connected to the internet so it can upload to Nightscout
"},{"location":"nightscout/remote-errors/#remote-commands-stopped-working","title":"Remote Commands Stopped Working","text":"

This section is for people who were using remote commands and they suddenly stopped working.

If you are using LoopCaregiver, try the remote command directly from Nightscout to see if they work there. If they are not working there as well, check out your account status first before attempting the fixes on the rest of this page.

  • Your Apple Developer account must be in good standing for the push notifications to work
  • Log in to your Apple Developer account and see if there are agreements you need to accept
"},{"location":"nightscout/remote-errors/#improper-configuration","title":"Improper Configuration","text":""},{"location":"nightscout/remote-errors/#nightscout-config-and-loop-build-method","title":"Nightscout Config and Loop Build Method","text":"

Ensure your Nightscout version is at least version 14.2.6.

Verify that you performed all the Remote Configuration steps for the Nightscout site including sending an override from the\u00a0Loop\u00a0phone to Nightscout.

"},{"location":"nightscout/remote-errors/#baddevicetoken","title":"BadDeviceToken","text":"

When the Nightscout config var LOOP_PUSH_SERVER_ENVIRONMENT does not match the\u00a0Loop\u00a0app build method; the error message contains the phrase APNs delivery failed: BadDeviceToken.

  • If\u00a0Loop\u00a0was installed remotely (typically from TestFlight following GitHub Browser Build), you must have Nightscout config var LOOP_PUSH_SERVER_ENVIRONMENT set to production
  • If\u00a0Loop\u00a0was built using Mac, you cannot have LOOP_PUSH_SERVER_ENVIRONMENT as one of your Nightscout config vars

If you attempt to issue a command from Nightscout Careportal; after you hit submit and then OK, you will see the error message:

Error: APNs delivery failed: BadDeviceToken\n

If you attempt to issue a command using Loop Caregiver ; after you authenticate the command, you will see the error message listed below and shown in the screenshot.

HTTP Error\nStatus Code: 500\nbody: APNs delivery failed: BadDeviceToken\n

"},{"location":"nightscout/remote-errors/#loop-remote_overrides_disabled","title":"Loop REMOTE_OVERRIDES_DISABLED","text":"

You can build Loop with Build-Time Features as part of code customization.

If you added this Build-Time Flag: REMOTE_OVERRIDES_DISABLED

You will not see any errors, but nothing will happen when you issue any kind of remote command.

Solution: Remove REMOTE_OVERRIDES_DISABLED from LoopConfigOverride.xcconfig file and rebuild the\u00a0Loop\u00a0app.

"},{"location":"nightscout/remote-errors/#incorrect-password-otp-error","title":"Incorrect Password (OTP) Error","text":"

The references to Caregiver below is the person sending the commands. There are specific Loop Caregiver app insructions that you modify for your authenticator. You must have the\u00a0Loop\u00a0phone with you to troubleshoot this problem.

  • The Apple clock should be set to automatic on both the Looper's phone and Caregiver\u2019s device.
    • If the clock is incorrect, even slightly, remote commands will fail.
  • Check if One-Time Passwords (OTP) align between Caregiver and\u00a0Loop.
    • In\u00a0Loop: Settings -> Services -> Nightscout
    • In Loop Caregiver : Settings -> Tap on Loopers Name
    • Observe the 6-digit OTP as they change
  • If the OTP don't match, you can reset it:
    • Warning: If there are multiple devices (or people) sending remote commands, this procedure resets the OTP for all
    • Loop: Settings -> Services -> Nightscout -> One-Time Password -> Tap Reload button
      • The QR code is different as soon as you hit Reload
    • Loop Caregiver: Delete the Looper's profile from Loop Caregiver and add the Looper again by scanning their new QR code
    • Authenticators for every device used to send remote commands must be updated
      • Delete the OTP configuration
      • Add the new QR code
"},{"location":"nightscout/remote-errors/#undelivered-or-expired-commands","title":"Undelivered or Expired Commands","text":"

Apple Push Notifications will often not make it to an app, either due to your settings or intentional limitations by Apple. This error can appear in various forms:

  • Push notification banner never shows on Looper\u2019s device.
  • Push notification banner shows but nothing happens in\u00a0Loop (no error or success message afterwards)
  • Error message shows that Password (OTP) is expired

While\u00a0Loop\u00a0does not have control over Push Notification timely delivery, there are things that can be done to mitigate these issues. Note that rebuilding\u00a0Loop, Loop Caregiver or Nightscout is generally not going to help.

Check these settings on the Looper\u2019s device, not the Caregivers. Several of these are related to Apple suppressing notifications.

  • Notifications
    • Settings -> Notifications ->\u00a0Loop
    • Turn on \u201cAllow Notifications\u201d
    • Turn on \u201cTime Sensitive Notifications\u201d
  • Focus Modes
    • For all focus modes (ex: Do Not Disturb, Sleep), make sure\u00a0Loop\u00a0is listed as an app allowing Notifications.
    • To Adjust
      • Settings -> Focus
      • Select the focus mode (ex: Do Not Disturb, Sleep)
      • Under \u201cAllow Notifications, tap \u201cApps\u201d
      • Add \u201c\u00a0Loop\u00a0\u201d to the list.
      • Turn on \u201cTime Sensitive Notifications\u201d.
  • Background App Refresh
    • Settings -> General -> Background App Refresh
    • Select \u201cOn\u201d up top
    • Activate\u00a0Loop\u00a0toggle in list
  • Lower Power Mode
    • Turn off if able

Some other things to try on the Looper\u2019s phone:

  • Reboot phone
    • This sometimes resets Apple\u2019s push notification limit.
  • Try wifi instead of cellular, if able
    • Apple may not deliver notifications on cellular as often as wifi.
  • Charge the phone
    • If the battery is low, iOS may not deliver notifications to save battery life.
  • Limit the number of\u00a0Loop\u00a0commands you send in a short period. Apple may throttle notifications if too many are received. (i.e. no more than 1 or 2 per hour may help).
  • Consider disabling \u201cspammy\u201d notifications from other apps. This is only a theory, but it is possible that other apps can cause the system to throttle all notifications, including\u00a0Loop.
  • Wait 24 hours or so as it often just takes time for the push notification limits to \u201creset\u201d.
  • iOS 15.3.x: Note there are reports of Remote notifications not being received to the Loopers device for iOS version 15.3 and 15.3.1. This is fixed in iOS version 15.4.
"},{"location":"nightscout/remote-errors/#how-to-ask-for-help","title":"How to Ask for Help","text":"

This is helpful information to share when requested by helpers. If you are not using Loop Caregiver, review the response seen on the Nightscout site.

  1. Activate an override from within\u00a0Loop . Does Nightscout show the active override?
  2. Activate an override from Nightscout . Does it change the active override in\u00a0Loop?
  3. Do errors show in Loop Caregiver or Nightscout Careportal when you send a remote command?
    • Share screenshots of error if any
  4. Do errors show in iOS Notifications on the Looper\u2019s device?
    • Check their Notification history in iOS by swiping down
    • Share screenshots of errors if any
  5. What\u00a0Loop\u00a0version are you using? Released (main) or development (dev)? Approximately when did you update last?
    • The minimum version that support remote bolus and carbs is\u00a0Loop\u00a03
  6. What iOS version is being used on the Looper\u2019s device?
    • Note that iOS 15.3.x had notification issues
    • Update to a newer version
  7. How did you build\u00a0Loop?
    • Build with Xcode to device (typical)?
    • Using AppCenter or Diawai? A special environment variable must be set LOOP_PUSH_SERVER_ENVIRONMENT=production

Mention which troubleshooting steps you have completed so we know whether to ask about these again.

"},{"location":"nightscout/remote-errors/#other-errors","title":"Other Errors","text":"

Once you've set up remote commands, you may encounter errors when trying to run them via Nightscout or iOS Shortcuts. Below are the most common and typical solutions.

  1. Error: Loop notification failed: Could not find deviceToken in loopSettings You might see this in either Nightscout or Shortcuts. The error is most commonly caused by\u00a0Loop\u00a0not pointing to the right Nightscout instance or you haven't yet run an override locally (with the\u00a0Loop app) before trying to run one remotely. Solution: Confirm the Loop app is pointing to the right Nightscout site (and there are no extra spaces or a slash (/) at the end, and always run an override for a few seconds in the Loop app before you try to run one remotely.
  2. Error: cannot POST/api/v2/notifications/loop You might see this in iOS Shortcuts. This means Nightscout is not updated correctly and you are running a version of Nightscout that doesn't yet support remote overrides. Solution: Follow the Remote Configuration documentation.
  3. Error: {\u201cstatus\u201d:401,\u201dmessage\u201d:\u201dUnauthorized\u201d,\u201ddescription\u201d:Invalid\\\\/Missing\u201d} You might see this in iOS Shortcuts. This is caused by having an incorrect API_SECRET in the shortcut. Solution: Double check the API_SECRET is correct and that there are no spaces at the end.
  4. Error: APNs delivery failed: InvalidProviderToken You might see this in either Nightscout or Shortcuts. This is caused because your LOOP_APNS_KEY_ID and LOOP_DEVELOPER_TEAM_ID are swapped in Heroku. Solution: Double check what's listed in your Apple Developer Account and compare it to the config variables in Heroku. Your Team_ID is next to your name in the top right corner. The other code is your Key_ID. Get the IDs in the correct location in Heroku to resolve the error.
"},{"location":"nightscout/remote-overview/","title":"Remote Overview","text":""},{"location":"nightscout/remote-overview/#remote-caregivers","title":"Remote Caregivers","text":"

With\u00a0Loop\u00a03, a caregiver can provide remote commands to assist in diabetes care, including modifying overrides, issuing remote bolus commands and adding remote carb entries. With\u00a0Loop\u00a02, only overrides can be turned on or off remotely.

Remote commands to the\u00a0Loop\u00a0phone go through their Nightscout site. For security, any command to deliver a bolus or add a carb entry requires a one-time-password (OTP) to be used with each remote command. These codes are unique to your combined\u00a0Loop\u00a0and Nightscout configuration. An authentication app needs to be installed on the device sending the remote boluses/carbs. The Loop Caregiver app can be used. It handles authentication requirements and offers a\u00a0Loop\u00a0-like user interface.

"},{"location":"nightscout/remote-overview/#remote-commanding-requirements","title":"Remote Commanding Requirements:","text":"
  • Loop\u00a0version 3.2.0 or newer
    • version 3.0 works but is not recommended for other reasons
  • Apple Push Notifications\u00a0 ( APN\u00a0) created with the \u00a0Apple Developer ID\u00a0 that built the\u00a0Loop\u00a0app
  • Nightscout version 14.2.6 or newer
    • Several configuration variables must be added
  • Ability to generate a One-Time-Password (OTP)

What about Older Versions?

Caregivers for those using older versions of Loop can modify Overrides remotely but cannot send remote bolus or carb commands.

If your Nightscout site is an older version, you should limit your remote commands to Overrides, even with \u00a0Loop 3.

Loop Caregiver

There is a new companion app, \u00a0Loop Caregiver that makes remote commands and reviewing the status of your looper much easier.

"},{"location":"nightscout/remote-overview/#how-does-this-work","title":"How does this work?","text":"

Loop\u00a0and Nightscout work using \u00a0Apple Push Notifications\u00a0 (APN).

  • The \u00a0Apple Developer ID\u00a0 used to build the\u00a0Loop\u00a0app must be configured to enable \u00a0Apple Push Notifications
    • If you built Nightscout and\u00a0Loop\u00a0yourself, follow the directions to set up Remote Configuration
  • Most providers who supply Nightscout as a service or Hosted Nightscout will assist you, if needed, in getting your APN information added to your Nightscout variables
    • Nightscout Docs: New User
    • Nightscout Docs: Comparison Table
      • Warning: examine the Loop remote carbs/bolus row: subscription refers to a monthly fee
"},{"location":"nightscout/remote-overview/#warning-nightscout-remote-carbohydrate-entries","title":"Warning: Nightscout Remote Carbohydrate Entries","text":"

Use unique times for remote carbohydrate entries

Instead of adding a second remote carbohydrate entry at an identical time, add one minute to the second entry.

This ensures that Nightscout keeps both entries.

For more information, see:

  • Use Unique Times for Remote Carbohydrate Entries
"},{"location":"nightscout/remote-overview/#next-steps","title":"Next Steps","text":"

There are several steps to follow to set this up. Each page is linked below:

"},{"location":"nightscout/remote-overview/#set-up-remote-for-nightscout","title":"Set Up Remote for Nightscout","text":""},{"location":"nightscout/remote-overview/#using-remote-commands","title":"Using Remote Commands","text":""},{"location":"nightscout/remote-overview/#remote-errors","title":"Remote Errors","text":""},{"location":"nightscout/remote-overview/#loop-caregiver-app","title":"Loop Caregiver App","text":""},{"location":"nightscout/troubleshoot/","title":"Nightscout Troubleshooting","text":""},{"location":"nightscout/troubleshoot/#setup-troubleshooting","title":"Setup Troubleshooting","text":"

If you have just tried to set up your Nightscout site and have problems with seeing all your data, please check out the Nightscout: Troubleshooting page.

"},{"location":"nightscout/troubleshoot/#dexcom-data-not-showing","title":"Dexcom data not showing","text":"

If you use a Dexcom and get your CGM data into Nightscout using Dexcom Share (bridge in Nightscout) and everything is working but the Dexcom data stops showing, please review Nightscout: Dexcom bridge Troubleshooting.

As part of that troubleshooting, you may need to remove the Nightscout service credentials from Loop. You may need to remove Dexcom credentials from all third-party apps that get data from Dexcom Share. Be sure to add them back after the CGM data to Nightscout is restored.

You do not need to use Share or bridge with Nightscout. You can choose to have Loop update your CGM readings to Nightscout directly. There's a check box in the Loop CGM setting screen to select this. You must select that check box every time you update your transmitter for Dexcom G5 or G6.

"},{"location":"nightscout/troubleshoot/#loop-data-not-showing","title":"Loop data not showing","text":"

If your BG data is showing, but Loop data is not (like Loop pill is empty and carbs and boluses are not showing), please delete your Nightscout account in Loop settings area. Enter the information in Loop again. Make sure to use https:// to start the site URL. Make sure there is no trailing slash at the end of the URL. Enter your API_SECRET correctly. Make sure you have loop on the ENABLE line in Heroku settings.

"},{"location":"nightscout/update-user/","title":"Nightscout with Loop","text":""},{"location":"nightscout/update-user/#adding-loop-to-existing-nightscout-site","title":"Adding Loop to Existing Nightscout Site","text":"

Many people may already have an existing Nightscout site setup from before adding Loop to their management strategies. In order to make the most of your Looping setup, you will need to modify your existing Nightscout site a bit specifically for Loop. The process is pretty easy and should not take long.

The graphics on this page are from a Heroku implementation for DIY Nightscout. When you read the Nightscout documents, you'll notice there are a lot more options than just Heroku. When Heroku announced that the \"free\" tier for Heroku would be disabled in November 2022, the #WeAreNotWaiting community developed a lot of options - both free DIY, nominal cost DIY and there were already several companies that provide Nightscout as a service. If your site is not with Heroku, you need to translate how to adjust the configuration variables.

"},{"location":"nightscout/update-user/#variables-for-loopers","title":"Variables for Loopers","text":"

Once you have created a Nightscout site, there are some Nightscout Config Vars specific to Loop.

  • First the Config Vars need to be added to the Nightscout site.

  • For each instance of viewing the Nightscout site (i.e., on broswer or phone app), you can individually select which of those configured items are displayed. This is on a per-view basis. However, Config Vars like the SHOW_PLUGINS line allow you to preconfigure what will be shown by default.

"},{"location":"nightscout/update-user/#editadd-config-vars","title":"Edit/Add Config Vars","text":"

These instructions are for people using Heroku, because that is the most common choice. If your Nightscout site is not on Heroku, this page provides a guide for the Config Vars used by Loop.

Login to your Heroku account, select the Settings tab near the top of the screen on your Heroku app.

Click on Reveal Config Vars. Scroll down the bottom of the Config Vars lines until you find the last blank one. You are going to add several additional lines of config vars for Loop use; the DEVICESTATUS_ADVANCED and ENABLE lines are required, the others just make Nightscout more useful when Looping.

Omnipod Users can skip the Config Vars that begin with PUMP_. Those are useful for Medtronic users.

ENABLE bridge loop pump iob cob basal careportal sage cage bage override dbsize (Note: If you are an existing NS user, you likely already have an ENABLE line in this section of Heroku. Don't add a new one. Simply find the existing ENABLE line, click on the little pencil icon to the right of it, and add the words shown on the ENABLE line above to the existing words already on the enable line. Avoid duplicates. The remainder of the lines are likely going to be brand new additions to your Heroku settings.) DEVICESTATUS_ADVANCED true PUMP_FIELDS battery reservoir clock status PUMP_RETRO_FIELDS battery reservoir clock status SHOW_FORECAST loop SHOW_PLUGINS loop pump cob iob sage cage careportal basal override dbsize PUMP_ENABLE_ALERTS true PUMP_URGENT_BATT_U 30(This is the pump battery percentage that will trigger a red, urgent alert in NS.) PUMP_URGENT_BATT_V 1.25(This is the pump battery voltage that will trigger a red, urgent alert in NS.) PUMP_URGENT_RES 10(This is the reservoir volume that will trigger a red, urgent alert in NS.) PUMP_URGENT_CLOCK 30 LOOP_ENABLE_ALERTS true LOOP_WARN 20(This is the minutes since Loop last successfully looped, the t1d will have a similar notification at this time through the Loop app. This will be a yellow alert in NS.) LOOP_URGENT 60(Same as the alert above, but will be red in color and have a shorter snooze option.) BASAL_RENDER default

Click on Open App in the top right corner of your Heroku site.

"},{"location":"nightscout/update-user/#plugins-selection","title":"Plugins Selection","text":"

Once you are viewing an instance of your Nightscout site (browser or app), you can adjust what this instance of the display will show.

Click on the \"hamburger\" menu - those three horizontal lines in the upper right corner of the main NS display.

Different sets of documentation call the three horizontal lines in the upper right of the Nightscout display different things such as:

  • Settings
  • Hamburger Menu
  • Drawer Menu

The graphic below shows some of the check boxes you can select. Make sure your basal render is selected to either default or icicle (personal preference for how the temp basals show as blue lines in NS site), adjust alarms (on or off), check the boxes that you\u2019d like display as pills in the SHOW PLUGINS section (usually all of them), and then click save. (You are saving your display preferences, not modifying anything in the NS database.)

Note - Nightscout has been updated since this figure was generated.

"},{"location":"nightscout/update-user/#authenticate-site","title":"Authenticate Site","text":"

If the current display of your NS site has been not authenticated, you will not be able to access certain portions of Nightscout such as the careportal, administration tools and remote overrides. There are two ways to authenticate.

  • Use API_SECRET to access all features of Nightscout

  • Use Tokens to generate a URL that opens with predefined role(s)

The use of tokens is documented at this link to the security page in the Nightscout documentation.

  • Please see Nightscout: Tokens

You can authenticate with your API_SECRET using either of these methods:

  • Click on the hamburger menu and scroll all the way to the bottom, click on authenticate and add your API_SECRET

  • Click on the Lock symbol on upper right on main display (requires careportal plugin to be enabled) and add your API_SECRET

An authenticated site, with careportal plugin enabled, will show a + at upper right of the main display instead of a lock symbol. Tapping on the + gives you access to the careportal.

"},{"location":"nightscout/update-user/#nightscout-version-update","title":"Nightscout Version Update","text":"

If you are new to Loop and haven\u2019t updated your Nightscout site for a while, check to see if there's an available update. Visit Nightscout: Update Instructions for directions on updating.

"},{"location":"nightscout/update-user/#more-variables-for-loopers","title":"More Variables for Loopers","text":"

The list of Variables for Loopers above can be expanded if you want your site to automatically open with specific values and alarm settings.

This Loop and Learn: Nightscout Variables page, created for folks using the Google Cloud method to create a Nightscout site, has a convenient, expanded list.

"},{"location":"operation/overview/","title":"Loop 2 Set Up Overview","text":"

This section of LoopDocs will be maintained during the transition to Loop 3. These pages are specific to Loop 2.2.x and some forks based off that older version.

Be aware that older versions and forks will probably not be updated as the Apple environment changes.

With Loop 2.2.x, you must manually step through every Loop setting and fill out the appropriate values. If you miss some, you may get errors in the app. If this happens to you, review every setting carefully.

You need to work through the steps listed in the headings under this page one by one. Please follow along with each page's information to make sure that you don't miss any valuable information about your Loop's settings and function.

You can work through each page completely and click on the link at the bottom of the page to proceed to the next page. Or you can use the back button on your browser to return to this page and click on the link for the page of interest.

"},{"location":"operation/overview/#permissions","title":"Permissions","text":"

Make sure that Loop has permission to send you notifications. For example, you will want to know if Loop has stopped working for more than 20 minutes.

Make sure Loop has permission to access Bluetooth devices. You'll need that for your CGM and to connect a pump to Loop.

"},{"location":"operation/overview/#loop-2-health-permissions","title":"Loop 2 Health Permissions","text":"

Follow the instructions on the Loop 2 Health Permission page. Note that the Carbohydrate read permission should be turned off after enabling all.

"},{"location":"operation/overview/#loop-2-add-pump","title":"Loop 2 Add Pump","text":"

Select and configure your insulin pump. There are separate pages for setting up a Medtronic (MDT) pump or an Omnipod Eros pump (aka \"pods\"). Click on one of the pages to go straight to that page's guide.

Loop 2 Add Medtronic Pump

Loop 2 Add Omnipod Pump

"},{"location":"operation/overview/#loop-2-add-cgm","title":"Loop 2 Add CGM","text":"

Follow direction on the Loop 2 Add CGM page. If you are wondering which CGMs are supported natively by Loop, check Compatible CGM.

"},{"location":"operation/overview/#loop-2-configurations","title":"Loop 2 Configurations","text":"

Configure Loop's settings. Within this section, you will be entering many settings that you are already familiar with such as basal rates, carb ratios, and insulin sensitivity factor (aka correction factor). There are also several new terms that you may be unfamiliar with like insulin model selection, suspend threshold, and override ranges. Make sure to refer to the Loop 2 Configurations while entering values - DO NOT GUESS.

"},{"location":"operation/overview/#loop-2-services-optional","title":"Loop 2 Services (Optional)","text":"

You are not required to use services although many Loopers use Nightscout. If you do not yet have Nightscout configured and want to add it later, just return to the Services page when you are ready. Note that Loop 3 and Loop 2 use the same documentation page for Services. Services can be added at any time.

"},{"location":"operation/overview/#loop-2-displays","title":"Loop 2 Displays","text":"

After you are done entering your settings, you should familiarize yourself with the information displays. The Loop 2 Displays page will help you recognize and begin to understand what all the icons, graphs, and data mean.

It is a good idea to remain in Open Loop while becoming familiar with the app.

"},{"location":"operation/overview/#loop-2-pump-settings-screen","title":"Loop 2 Pump Settings Screen","text":"

The pump settings screens for Loop 3 were updated. The older interface used by Loop 2 is documented at Loop 2 Pump Settings

"},{"location":"operation/overview/#rileylink-screen","title":"RileyLink Screen","text":"

The documentation for Loop 3 and Loop 2 is the same for the RileyLink screen. This screen is only available after configuring a pump that uses a RileyLink Compatible Device.

After a pump that uses a RileyLink is connected to the app, tap on a RileyLink name in the pump settings screen to bring up the displays and commands found on the RileyLink Menu screen.

"},{"location":"operation/algorithm/bolus/","title":"Bolus Recommendations","text":""},{"location":"operation/algorithm/bolus/#loop-manual-bolus","title":"Loop Manual Bolus","text":"

Loop will recommend bolus insulin corrections when the eventual blood glucose is greater than the correction target and the active insulin plus any active 30-minute temporary basal will not be sufficient to cover the predicted excursion above correction target.

These recommendations are not proactively sent to the Loop user through any notification or banner alert; the recommendation is only viewable when the user clicks on the bolus tool. Note that Loop never issues a bolus command automatically while using the default Temp Basal Dosing Strategy; all boluses are initiated by the user unless the Automatic Bolus dosing strategy is enabled. With automatic bolus enabled, each automatic bolus is limited to 40% of the recommended amount or the maximum bolus setting, whichever is smaller.

The bolus dose calculation is identical to the dose equation given in the basal recommendations section, with the exception that:

  • the insulin contribution from the currently running temporary basal set by Loop is removed or subtracted from the recommended bolus amount, and
  • the delta is calculated for the top of the correction range, rather than the average of the correction range.

For recently saved carbohydrates where the projected carbohydrate absorption will outlast the insulin activity duration (e.g., very slow-digesting meals like pizza or pasta), Loop\u2019s algorithm will inherently decrease the initial meal bolus \u2014 to prevent hypoglycemia events that often occur after these meals \u2014 by only recommending enough bolus to prevent minimum predicted glucose from going below the suspend threshold. As described above, the Loop algorithm computes the recommended bolus such that predicted glucose will not dip below the suspend threshold. This may result in future blood glucose levels predicted above correction range, but will prevent a hypoglycemia event shortly after the meal (as it sometimes occurs for people giving a \"pizza bolus\" in traditional pump therapy). Loop will then later make corrections by issuing a command to temporarily Increase Basal Rate or provide an automatic bolus. In effect, this algorithm behavior mimics traditional pump therapy of \u201cextended\u201d or \u201cdual wave\u201d bolusing, but with the benefit of added information about actual carbohydrate absorption effects as time goes by.

Finally, Loop checks that the result of the calculations is below the maximum single bolus the Loop user specified in their settings. If the calculated bolus is less than the maximum single bolus setting, then the recommended bolus will be displayed in Loop\u2019s bolus tool.

Bolusing safety feature

If the current blood glucose, or any predicted blood glucose, falls below the suspend threshold, Loop will not return a recommended bolus. When the minimum blood glucose rises above the suspend threshold, the bolus tool will provide a recommended bolus.

"},{"location":"operation/algorithm/bolus/#algorithm-section-menu","title":"Algorithm Section Menu","text":"
  • Algorithm Overview
    • Bolus Recommendations
    • Blood Glucose Prediction
    • Temp Basal Adjustments
"},{"location":"operation/algorithm/overview/","title":"Algorithm Overview","text":""},{"location":"operation/algorithm/overview/#loop-algorithm","title":"Loop Algorithm","text":"

Loop\u2019s algorithm for adjusting insulin delivery is oriented around making a blood glucose prediction. Every five minutes, triggered by new blood glucose data, it generates a new prediction. Both bolus recommendations and temporary basal rate adjustments are set based on this prediction.

"},{"location":"operation/algorithm/overview/#algorithm-terminology","title":"Algorithm Terminology","text":"

This graph and legend illustrates terms commonly used in discussing Loop's algorithm, and shows them in the context of historical and forecasted blood glucose in style similar to the status screen of Loop.

Insulin activity duration The insulin activity duration is the duration of the insulin activity curve, and describes the point at which the delivered insulin dose no longer affects blood glucose. The insulin activity duration is 6 hours for Loop's rapid-acting and ultra-rapid insulin models. Correction range The correction range is the blood glucose range Loop uses to determine corrective actions (e.g., between 90 and 120 mg/dL in the figure). NOTE: Loop\u2019s correction range is a user setting and should not be confused with the target range, typically 70-180 mg/dL, used for the purpose of calculating the percent time in range. Correction minimum The lower or minimum value of the user\u2019s correction range, which is 90 mg/dL in the figure. Correction maximum The upper or maximum value of the user\u2019s correction range, which is 120 mg/dL in the figure. Correction target The correction target is the average value of the correction range. In the overview figure, this is 105 mg/dL given that the correction minimum is 90 mg/dL and the correction maximum is 120 mg/dL. Predicted blood glucose Loop makes a prediction of blood glucose values out for a length of time equal to your insulin action duration. The predicted blood glucose is the basis for how Loop makes its insulin delivery recommendations and actions. Eventual blood glucose The last value of the predicted glucose curve, in other words the very last blood glucose predicted at the end of your insulin action duration. In the figure above, this is 85 mg/dL. Minimum predicted blood glucose The lowest blood glucose value at any point in time within the prediction. In the figure above, this is 77 mg/dL. Delta The delta is the difference between the eventual blood glucose and the correction target. In the overview figure, the eventual blood glucose is 85 mg/dL and the correction target is 105 mg/dL, which means that the delta is -20 mg/dL. Suspend Threshold The suspend threshold is a safety feature of the Loop algorithm. If any predicted blood glucose is below this threshold, the Loop algorithm will issue a temporary basal rate of 0 CGM data Blood glucose readings made by a continuous glucose monitor. Insulin sensitivity factor A configuration value that provides an estimate of how much blood glucose will drop given a unit of insulin. Active insulin Active insulin, often referred to as Insulin-on-Board (IOB), is the remaining amount of insulin activity from boluses and temporary basal rates relative to a user\u2019s scheduled basal rates. More specifically, it is the total amount of insulin activity due to all bolus and basal insulin delivered within the last N hours, where N is determined by the insulin activity duration. The amount of \u201cactive\u201d insulin depends upon the insulin activity curve, and also accounts for the insulin withheld via basal suspensions. As such, it is possible that the active insulin can be negative. Negative active insulin will result in an increase in predicted blood glucose. The active insulin displayed in Loop's main display does not reflect the currently enacted temporary basal rate, as that basal rate may be canceled or modified before completion over the next 30 minutes. In others words, Loop doesn't count chickens before the eggs hatch...insulin delivery must be confirmed before being added to the active insulin reporting."},{"location":"operation/algorithm/overview/#algorithm-section-menu","title":"Algorithm Section Menu","text":"
  • Algorithm Overview
    • Bolus Recommendations
    • Blood Glucose Prediction
    • Temp Basal Adjustments
"},{"location":"operation/algorithm/prediction/","title":"Glucose Prediction","text":""},{"location":"operation/algorithm/prediction/#blood-glucose-prediction","title":"Blood Glucose Prediction","text":"

Loop uses an algorithm to maintain blood glucose in a correction range by predicting the contributions from four individual effects (insulin, carbohydrates, retrospective correction, and blood glucose momentum) at any time t to recommend temporary basal rate corrections and boluses.

\\[ BG[t] = Insulin[t] + Carb[t] + RetrospectiveCorrection[t] + Momentum[t] \\]

Note that the Momemtum term does not just add to the other effects as implied in the simple formular above; it is blended with the other terms as described in more detail in the Momemtum section below).

You can see the individual contributions of these effects by tapping on the predicted blood glucose chart on Loop's status screen. Loop updates this blood glucose prediction every five minutes when a new CGM value has been received and the pump's status has been updated.

Just a note, this whole section is fairly technical. While perhaps not the most interesting topic for many readers, if you are seeking the detailed view of the Loop algorithm this discussion is quite useful. If you want a more surface understanding, the overview and temporary basal recommendations sections alone are probably sufficient.

"},{"location":"operation/algorithm/prediction/#overview","title":"Overview","text":"

Before we delve into each of the four individual effects, a general overview figure may be a helpful start. There are four effects summed together to produce Loop's final predicted blood glucose curve. Each individual effect, along with their combined effect, is illustrated in the figure below. Insulin, from boluses and temporary basals, will have a decreasing effect on the prediction. Carbohydrates will have an increasing effect on the prediction. Blood glucose momentum effect can have a positive or negative effect, depending on how blood glucose is trending in the most recent CGM values. As shown in the example below, blood glucose is trending slightly upwards at the time of the prediction. Therefore, the blood glucose momentum effect\u2019s contribution is pulling up the overall prediction from the other three effects for a short time. Retrospective correction is lowering the prediction, indicating that the recent rise in blood glucose was not as large as had been predicted by Loop in the recent past.

The sections below provide detailed information on each of the four contributions.

"},{"location":"operation/algorithm/prediction/#insulin-effect","title":"Insulin Effect","text":"

Most traditional pump users and caregivers are already familiar with the concept of an insulin activity curve, where the insulin\u2019s effect is time-dependent. Insulin takes a little while to affect blood glucose. The insulin effect typically peaks around one hour after giving insulin and then gradually decays.

Loop 2.x provides users with two different classes of insulin models (i.e., an exponential model and the Walsh model). All of the exponential models have an insulin activity duration of 6 hours, whereas the insulin activity duration is customizable for the Walsh model. The rapid-acting and Fiasp insulin activity curves are modeled as exponential curves that match the shape of the insulin activity curves from insulin labeling, and as observed in both adults and children.

Loop 3 drops the Walsh model and, by default, does not include the concept of child versus adult for \"rapid\" acting insulin, i.e., Humalog, Novalog and Apidra. Loop 3 adds the concept of non-pump insulin to account for injections or inhaled insulin. The Afrezza model is added as a non-pump insulin. The Insulin Type is selected in the Pump Settings screen. All insulin types are modeled by selecting parameters in the exponential model. See also Exponential Insulin Curve on the Code Customization page.

"},{"location":"operation/algorithm/prediction/#insulin-effect-remaining","title":"Insulin Effect Remaining","text":"

The amount of insulin effect remaining, or percent of remaining active insulin after an insulin bolus is delivered, is modeled mathematically in Loop with an exponential decay curve.

If a user\u2019s insulin sensitivity factor (ISF) is 50 mg/dL per 1 unit of insulin and the user gives 2 units of insulin, then the user\u2019s blood glucose would be expected to drop 100 mg/dL within the 6 hours following the insulin delivery. This insulin effect can be visualized in several different ways: the expected active insulin, expected drop in blood glucose every 5 minutes after delivery, and the expected cumulative drop in blood glucose. The figures below use the Rapid Acting - Adult insulin model in Loop.

"},{"location":"operation/algorithm/prediction/#active-insulin","title":"Active Insulin","text":"

This figure shows that 2 units of insulin are given initially, and the corresponding active insulin (i.e., insulin on board IOB) decays according to the curve below.

The active insulin at any time is the product of original insulin delivered and the percent of insulin activity remaining. Knowing the expected active insulin over the next 6 hours, and the insulin sensitivity factor (50 mg/dL, in this case), Loop can calculate the expected drop in blood glucose from that dose of insulin as shown in the figure below.

NOTE: ISF is also a function of time, which means if the user\u2019s scheduled ISF changes during the insulin activity time, it will change the expected drop in blood glucose due to the insulin effect.

"},{"location":"operation/algorithm/prediction/#expected-change-in-blood-glucose","title":"Expected Change in Blood Glucose","text":"

Lastly, taking the first derivative (i.e., the rate of change) of the cumulative drop in the blood glucose curve yields the expected change in blood glucose over the insulin activity duration. For each dose of insulin given, Loop calculates the expected discrete drop in blood glucose at each 5-minute period for the insulin activity duration, as shown below.

"},{"location":"operation/algorithm/prediction/#insulin-effect-on-blood-glucose","title":"Insulin Effect on Blood Glucose","text":"

For this example, assuming a user\u2019s blood glucose was 205 mg/dL at the time of insulin delivery, Loop would predict a drop in blood glucose due to the two units delivered at 12 pm as shown in the figure below.

"},{"location":"operation/algorithm/prediction/#scheduled-basal-rates","title":"Scheduled Basal Rates","text":"

In traditional basal/bolus pump therapy, basal rates are set to accommodate the user's endogenous glucose production (EGP) that causes blood glucose to rise. If a user's basal settings were exactly right in traditional pump therapy, the user would have perfectly flat blood glucose all day, all other factors being equal.

In reality, people with type 1 diabetes, and their caregivers, know that basal settings are never exactly right. Every day is a little different, and a myriad of factors that affect blood glucose (e.g., including stress, hormones, sleep, etc.) may affect insulin needs. Some people have different basal profiles to accommodate these variations. Some people regularly tune and adjust their basal rates, and/or do so at their endocrinology clinic visits.

Since the Loop algorithm assumes that the user-set basal rates are correct, it calculates the effect of insulin relative to scheduled basal rates. If basal rates are not entirely correct, Loop can compensate a bit through the retrospective correction and blood glucose momentum effects, discussed later in this page.

The insulin delivery chart below displays a bar-graph history of the temporary basal rates enacted by Loop. The display is relative to the scheduled basal rates entered in the Loop settings. A rate displayed in this chart as +0 would indicate that no temporary basal rate was set and that the basal rate being delivered was the scheduled basal rate. Positive values indicate a temporary basal rate was set above the scheduled basal rate (i.e., more insulin delivered), and negative values indicate that a temporary basal rate was set below the scheduled basal rate (i.e., less insulin delivered).

For example, if the user\u2019s scheduled basal rate is 1 U/hr, and Loop gives a temporary basal rate of 3 U/hr, then it will calculate the expected drop in blood glucose due to +2 U/hr of insulin.

Similarly if Loop sets a temporary basal rate of 0 U/hr for 1 hour, then the insulin effect will also be relative to the current scheduled basal rate of 1 U/hr, and Loop would predict the user\u2019s blood glucose to increase by the amount of change from -1 U/hr of insulin. If the user\u2019s ISF is 50 mg/dL, then Loop would predict blood glucose to rise 50 mg/dL over the insulin activity duration (6 hours).

Here is a real-world example where Loop is setting many temporary basal rates over the course of the day. The light orange bars are the temporary basal rates delivered and the solid orange line is the active insulin at any given time during the day.

"},{"location":"operation/algorithm/prediction/#total-insulin-effect-combining-boluses-and-temporary-basal-rates","title":"Total Insulin Effect (combining boluses and temporary basal rates)","text":"

Loop will combine or stack the active insulin of all the discrete (individual) boluses and temporary basal rates over the past insulin activity duration (6 hours), to predict the active insulin for the next 6 hours. As demonstrated above, using the predicted active insulin Loop can predict the blood glucose drop over the next 6 hours.

Lastly, the combined effect of bolus and basal insulin are visually represented for the user by Loop\u2019s insulin charts:

The insulin effect can be expressed mathematically:

\\[ \\Delta BG_{I}[t] = ISF[t] \\times IA[t] \\]

where BG is the expected change in blood glucose with the units (mg/dL/5min), ISF is the insulin sensitivity factor (mg/dL/U) at time t, and IA is the insulin activity (U/5min) at time t. Insulin activity can also be thought of as a velocity or rate of change in blood glucose due to insulin. The insulin activity accounts for the EGP and any active insulin from basals and boluses.

"},{"location":"operation/algorithm/prediction/#carbohydrate-effect","title":"Carbohydrate Effect","text":"

Carbohydrates will raise blood glucose, but the speed and degree to which they impact blood glucose are dependent on the type of carbohydrates. High glycemic index (GI) carbohydrates will raise blood glucose quickly over a shorter time, whereas low GI foods will raise blood glucose more slowly over a longer period. Foods like candy, juice, and fruits tend to be high GI foods, while pizza, burritos, and quesadillas are usually lower GI foods. Digestion issues like gastroparesis may also contribute to variations in carbohydrate absorption.

Because carbohydrate absorption can be quite variable, Loop has a model that dynamically adjusts the expected remaining time of carbohydrate absorption. To start with, Loop allows the user to input a rough guess of how long they think the food or drink will take to absorb. The user\u2019s guess is used as a middle of the road estimate, and Loop\u2019s algorithm will shorten or lengthen it based on observed blood glucose change.

For all carbohydrate entries, Loop assumes carbohydrates will not start absorbing for 10 minutes, so there is a 10-minute period of no absorption that is modeled prior to the absorption modeled in the next sections.

"},{"location":"operation/algorithm/prediction/#linear-carbohydrate-absorption","title":"Linear Carbohydrate Absorption","text":"

Loop takes a conservative view of how fast the remaining carbohydrates will absorb. Because it is safer to under-deliver insulin for long-duration meals, Loop starts out at a minimum rate of absorption based on extending the entered carbohydrate duration by 50%. Said another way, the minimum carbohydrate absorption rate is the total number of grams of carbohydrates over 150% of the entered duration.

Using this initial minimum absorption rate, the remaining carbohydrates are modeled to absorb linearly. For example, if the user enters a 72g carbohydrate meal, and selects an estimated absorption time of 4 hours, then Loop will forecast a 12g/hr absorption rate for the next 6 hours. This rate can be termed the minimum absorption rate, which can be represented mathematically as:

\\[ MAR[t] = \\frac{CA[t]}{1.5 \\times d} \\]

where MAR is the minimum absorption rate (g/hr), CA is the number of carbohydrates (g) and d is the expected duration (hr) it will take the carbohydrates to absorb.

"},{"location":"operation/algorithm/prediction/#dynamic-carbohydrate-absorption","title":"Dynamic Carbohydrate Absorption","text":"

The linear model above is modulated by an additional calculation that uses recently observed blood glucose data to estimate how fast carbohydrates have been absorbing. The expected change in blood glucose due to insulin effects alone is compared to the actual observed changes in blood glucose. This difference is termed the insulin counteraction effect (ICE):

\\[ ICE[t] = OA[t] + IA[t] \\]

where, ICE (mg/dL/5 min) is the insulin counteraction effect, OA is the observed activity (mg/dL/5min) or observed change in blood glucose at time t, and IA is the insulin activity (mg/dL/5min).

Insulin counteraction effects are caused by more than just carbohydrates, and can include exercise, sensitivity changes, or incorrectly configured insulin delivery settings (e.g., basal rate, ISF, etc.). However, since the effect of carbohydrates is often dominant (after insulin), Loop can still make useful ongoing adjustments to its carbohydrate model by assuming that the increase in blood glucose is mainly carbohydrate absorption in the period following recorded meal entries.

The insulin counteraction effect is converted into an estimated carbohydrate absorption amount by using the current carbohydrate-to-insulin ratio and the insulin sensitivity factor at the time of the recorded meal entry.

\\[ AC[t] = ICE[t] \\times \\frac{CIR[t]}{ISF[t]} \\]

where AC is the number of carbohydrates absorbed (g/5min), ICE is the insulin counteraction effect, CIR is the carbohydrate-to-insulin ratio (g/U), and ISF is the insulin sensitivity factor (mg/dL/U) at time t.

If multiple meal entries are active (i.e., still absorbing), the estimated absorption is split between each carbohydrate entry in proportion to each carbohydrate entry\u2019s minimum absorption rate. For example, if 72g carbohydrates with an expected absorption time of 4 hours was consumed at 12 pm, and another 72g of carbohydrates with an expected absorption time of 2 hours was consumed at 3 pm, then the minimum absorption rate (see MAR equation above) would be 12 g/hr and 6 g/hr respectively, or 1 g/5min and 0.5 g/5min.

\\[ MAR[t = 12pm] = \\frac{ 72g }{ 1.5 \\times 4hr } = 12 \\frac{ g }{ hr } = 1 \\frac{ g }{ 5min } \\] \\[ MAR[t = 3pm] = \\frac{ 72g }{ 1.5 \\times 2hr } = 24 \\frac{ g }{ hr } = 2 \\frac{ g }{ 5min } \\]

Examining just the simple linear carbohydrate effect of these two meals:

If we further expand this example, by assuming the following at 4pm:

  • that there are still carbohydrates left to be absorbed from both meals,
  • that the estimated insulin counteraction effect (ICE) is \\(+15 \\frac{mg/dL}{5min}\\), and
  • the user\u2019s CIR is \\(10 \\frac{g}{U}\\) and the ISF is \\(50 \\frac{mg/dL}{U}\\),

then the estimated amount of carbohydrates absorbed at 4pm would be 3g:

\\[ AC[t = 4pm] = 15 \\frac{mg/dL}{5min} \\times \\frac{10 \\frac{g}{U}}{50 \\frac{mg/dL}{U}} = 3 \\frac{g}{5min} \\]

Those 3g of carbohydrates would then be split amongst the meals proportional to their minimum absorption rates:

\\[ \\text{Proportion to Meal1} = \\frac{MAR_{meal1}}{MAR_{meal1} + MAR_{meal2}} = \\frac{12}{12+24}=\\frac{1}{3} = 33.3\\% \\] \\[ \\text{Proportion to Meal2} = \\frac{MAR_{meal2}}{MAR_{meal1} + MAR_{meal2}} = \\frac{24}{12+24}=\\frac{2}{3} = 66.6\\% \\]

resulting in 1g of absorption being attributed to Meal 1 and 2g attributed to Meal 2.

"},{"location":"operation/algorithm/prediction/#minimum-carbohydrate-absorption-rate","title":"Minimum Carbohydrate Absorption Rate","text":"

If the estimated carbohydrate absorption of a meal entry is less than what would have been absorbed using the minimum absorption rate, then the minimum absorption rate is used instead. This is to ensure that meal entries expire in a reasonable amount of time.

"},{"location":"operation/algorithm/prediction/#modeling-remaining-active-carbohydrates","title":"Modeling Remaining Active Carbohydrates","text":"

After the estimated absorbed carbohydrates have been subtracted from each meal entry, the remaining carbohydrates (for each entry) are then forecasted to decay or absorb using the minimum absorption rate. Loop uses this forecast to estimate the effect (active carbohydrates, or carbohydrate activity) of the remaining carbohydrates. The carbohydrate effect can be expressed mathematically using the terms described above:

\\[ \\Delta BG_{C}[t] = MAR[t] \\times \\frac{ISF[t]}{CIR[t]} \\]"},{"location":"operation/algorithm/prediction/#retrospective-correction-effect","title":"Retrospective Correction Effect","text":"

The retrospective correction effect allows the Loop algorithm to account for effects that are not modeled with the insulin and carbohydrate effects, by comparing historical predictions to the actual blood glucose.

In addition to the modeled effects of insulin and carbohydrates, there are many other factors that affect blood glucose (e.g., exercise, stress, hormones, etc.). Many of these effects are active for a period of time. By observing its own forecast error, Loop can estimate the magnitude of these effects and, by assuming that they will continue for some short period of time, incorporate them into the forecast to improve forecast accuracy.

To do this, Loop calculates a retrospective forecast with a start time of 30 minutes in the past, ending at the current time. Loop compares the retrospective forecast to the actual observed change in blood glucose, and the difference is used to determine a blood glucose velocity or rate of difference:

\\[ BG_{vel}=\\frac{1}{6} \\times \\left(BG[0] - RF[0]\\right) \\]

where BGvel is a velocity term (mg/dL per 5min) that represents the average blood glucose difference between the retrospective forecast (RF) and the actual blood glucose (BG) over the last 30 minutes. This term is applied to the current forecast from the insulin and carb effects with a linear decay over the next hour. For example, the first forecast point (t=5) is 100% of this velocity, the forecast point one-half hour from now is adjusted by approximately 50% of the velocity, and points from one hour or more in the future are not affected by this term.

The retrospective correction effect can be expressed mathematically:

\\[ \\Delta BG_{RC}[t] = BG_{vel} \\times \\left(1-\\frac{t-5}{55}\\right) \\]

where BG is the predicted change in blood glucose with the units (mg/dL/5min) at time t over the time range of 5 to 60 minutes, and the other term gives the percentage of BGvel that is applied to this effect.

The retrospective correction effect can be illustrated with an example: if the BGvel over the past 30 minutes was -10 mg/dL per 5min, then the retrospective correction effect over the next 60 minutes would be as follows:

Minutes relative to now (t=0) Percent of \\(BG_{vel}\\) Applied to RC Effect \\(\\Delta BG_{RC}[t]\\) 5 100% -10 10 91% -9.1 15 82% -8.2 20 73% -7.3 25 64% -6.4 30 55% -5.5 35 45% -4.5 40 36% -3.6 45 27% -2.7 50 18% -1.8 55 9% -0.9 60 0% 0

The example below that shows the retrospective correction effect when the BGvel over the past 30 minutes was -3 mg/dL/5min.

"},{"location":"operation/algorithm/prediction/#blood-glucose-momentum-effect","title":"Blood Glucose Momentum Effect","text":"

The blood glucose momentum effect incorporates a prediction component based on the assumption that recent blood glucose trends tend to persist for a short period of time. In other words, the best predictor of the future is the recent past.

The blood glucose momentum portion of the algorithm gives weight or importance to recent blood glucose to improve the near-future forecast. Loop calculates the slope of the last 3 continuous CGM readings (i.e., the last 15 minutes) using linear regression. Using multiple points helps filter out noise in the CGM data while still responding fast to changing situations. That momentum slope (Mslope) is the approximate or average rate of change over the last 15 minutes, though it is normalized to 5 minutes so that the units are (mg/dL/5min).

The momentum slope is then blended into the next 20 minutes of predicted blood glucose from the other effects (i.e., insulin, carbohydrates, and retrospective correction effects). This, in essence, makes the next 20 minutes of blood glucose prediction more sensitive to recent blood glucose trends. The blending of the recent trend slope into the next 20 minutes is weighted so that the first prediction point (5 minutes into the future) is highly influenced by the slope, and the influence of the slope gradually decays over the 20 minute time period. The momentum effect can be expressed mathematically as:

\\[ \\Delta BG_{M}[t] = M_{slope} \\times \\left( 1 - \\frac{t-5}{15} \\right) \\]

NOTE: The term \\(\\left(\\frac{t-5}{15}\\right)\\) is also applied to the combined insulin, carbohydrates, and retrospective correction effects to get the delta blood glucose prediction.

The momentum effect can be illustrated with an example: if the last 3 blood glucose readings were 100, 103, and 106 mg/dL, then the slope would be 3 mg/dL per 5 minutes (0.6 mg/dL per minute). The amount of that recent trend or slope applied to the next 20 minutes of predictions (i.e., the next 4 predictions from the other effects) is roughly 100% (3 mg/dL per 5 min) at 5 minutes, 66% (2 mg/dL per 5 min) at 10 minutes, 33% (1 mg/dL per 5 min) at 15 minutes, and 0% (0 mg/dL per 5 min) at 20 minutes.

Also, if the combined effect from the insulin, carbohydrates, and retrospective correction is assumed to be a constant 6 mg/dL/5min over the next 20 minutes, then the expected overall effect and the predicted blood glucose can be calculated as follows.

Minutes relative to now (t=0) Percent of Slope Applied to Momentum Effect Momentum Effect (3mg/dL/5min) Percent of Other Effects Applied Overall Effect Other Effects (Insulin, Carbohydrate, and Retrospective Correction) Overall Effect (mg/dL/5min) Predicted BG (mg/dL) 5 100% 3 0 6 3 109 10 66.6% 2 33.3%< 6 4 113 15 33.3% 1 66.6% 6 5 118 20 0% 0 100% 6 6 124

This example is illustrated in the figure below.

It is also worth noting that Loop will not calculate blood glucose momentum in instances where CGM data is not continuous (i.e., must have at least three continuous CGM readings to draw the best-fit straight line trend). It also will not calculate blood glucose momentum when the last three CGM readings contain any calibration points, as those may not be representative of true blood glucose momentum trends.

"},{"location":"operation/algorithm/prediction/#predicting-glucose","title":"Predicting Glucose","text":"

As described in the momentum effect section, the momentum effect is blended with the insulin, carbohydrate, and retrospective correction effects to predict the change in blood glucose:

\\[ \\Delta BG[t] = \\Delta BG_{M}[t] + \\left(\\Delta BG_{I}[t] + \\Delta BG_{C}[t]+ \\Delta BG_{RC}[t] \\right) \\times min\\left(\\frac{t-5}{15}, 1\\right) \\]

Lastly, the forecast or predicted blood glucose BG at time t is the current blood glucose BG plus the sum of all blood glucose effects BG over the time interval [t5, t]:

\\[ \\widehat{BG}[t] = BG[t_{o}] + \\sum_{i=5}^{t} \\Delta BG[t_{o+i}] \\]

Each individual effect along with the combined effects are illustrated in the figure below. As shown, blood glucose is trending slightly upwards at the time of the prediction. Therefore, the blood glucose momentum effect\u2019s contribution is pulling up the overall prediction from the other three effects for a short time. Retrospective correction is lowering the current prediction, indicating that the recent rise in blood glucose was not as great as had been predicted in the recent past.

"},{"location":"operation/algorithm/prediction/#algorithm-section-menu","title":"Algorithm Section Menu","text":"
  • Algorithm Overview
    • Bolus Recommendations
    • Blood Glucose Prediction
    • Temp Basal Adjustments
"},{"location":"operation/algorithm/temp-basal/","title":"Automated Adjustments","text":""},{"location":"operation/algorithm/temp-basal/#calculated-dose","title":"Calculated Dose","text":"

The Loop algorithm takes one of four actions depending upon the eventual blood glucose, predicted glucose, target range and glucose safety threshold when Closed Loop operation is enabled.

The recommended insulin dose (positive or negative) is calculated first, then the Temp Basal or Automatic Bolus to be enacted is modified based on the recommended dose, dosing strategy, maximum Temp Basal and maximum Bolus settings. The automated dosing (increase or decrease) is updated with every CGM value - typically every 5 minutes.

Dosing Strategy: Temp Basal Only

All temporary basal rate commands are issued for 30 minutes, however they may be updated (re-issued) every 5 minutes. Said another way, Loop may enact a new temporary basal rate every 5 minutes. But, if communication with the pump is lost, the last issued temporary basal rate will last for at most 30 minutes before the pump reverts to the user\u2019s scheduled basal rates.

Dosing Strategy: Automatic Bolus

If the Looper has selected Automatic Bolus Dosing Strategy and an increase in insulin dose is recommended, then the Four Actions discussion below applies to the automatic bolus decision.

"},{"location":"operation/algorithm/temp-basal/#no-automatic-dosing","title":"No Automatic Dosing","text":"

If glucose is entirely below the correction range but above glucose safety level, no automatic increase in insulin delivery will be enacted. The Looper can tap on the manual bolus tool and get a recommendation, but no automatic bolus or high temp basal will be issued automatically until the glucose level is higher than the minimum value of the correction range.

The Pre-Meal button or a named override can be configured with a correction range lower than the scheduled correction to assist in getting insulin delivered automatically after meals.

"},{"location":"operation/algorithm/temp-basal/#four-possible-actions","title":"Four Possible Actions","text":"

Loop implements one of four possible temporary basal actions: decrease, increase, suspend, or resume a scheduled basal rate.

Automatic Bolus

If you are using an Automatic-Bolus Dosing Strategy in closed Loop mode and Loop predicts you need an increase in insulin; this increase is provided as a percentage of the recommended bolus instead of an increased temporary basal. The default percentage is 40%.

"},{"location":"operation/algorithm/temp-basal/#decrease-basal-rate","title":"Decrease Basal Rate","text":"

If the eventual blood glucose is less than the correction range and all of the predicted glucose values are above the suspend threshold, then Loop will issue a temporary basal rate that is lower than the current scheduled basal rate to bring the eventual blood glucose up to the correction target.

"},{"location":"operation/algorithm/temp-basal/#increase-basal-rate","title":"Increase Basal Rate","text":"

If the eventual blood glucose is greater than the correction range and all of the predicted glucose values are both above the suspend threshold and equal to or above the correction range, then Loop will issue a temporary basal rate that is higher than the current basal rate to bring the eventual blood glucose down to the correction target.

"},{"location":"operation/algorithm/temp-basal/#suspend-basal-rate","title":"Suspend Basal Rate","text":"

If the minimum predicted blood glucose goes below the suspend threshold, then Loop will issue a temporary basal rate of zero units per hour, regardless of the eventual blood glucose.

"},{"location":"operation/algorithm/temp-basal/#resume-basal-rate","title":"Resume Basal Rate","text":"

There are three situations where the Loop algorithm will resume the current scheduled basal rate.

If the eventual blood glucose is within the correction range, and all of the predicted glucose values are above the suspend threshold, then Loop will resume the current scheduled basal rate.

If the eventual blood glucose is above the correction range, and the predicted glucose values have a temporary excursion below the correction range but still above the suspend threshold, then Loop will resume the current scheduled basal rate.

If the Loop algorithm does not have ALL of the data it needs to make a prediction, it will let the remaining temporary basal rate run its duration (maximum of 30 minutes), and then the basal rate will default back to the current scheduled basal rate, thus returning to the same therapy pattern that they would receive using a traditional insulin pump.

"},{"location":"operation/algorithm/temp-basal/#determining-the-temporary-basal-rate","title":"Determining the Temporary Basal Rate","text":"

To determine the corrective temporary basal rate to implement, Loop calculates a \u201cdose\u201d in the same way doses are calculated in both open-loop and traditional insulin pump therapy. It's also the same math many people on multiple-daily injection therapy use. The benefit of Loop (and all other close-loop algorithms) is that it does this math every 5 minutes, and is far less prone to error than humans doing the math. Loop also does its math based on predicting into the future, which traditional pumps and humans, do not always have the time or inclination to do.

The amount of insulin needed, or dose, is calculated using the desired reduction in blood glucose and the user\u2019s ISF. For the Loop algorithm, the desired reduction in blood glucose is the delta between the eventual blood glucose and the correction target:

\\[ \\mathit{dose} = \\frac{\\mathit{BG_{eventual}} - \\mathit{BG_{target}}}{\\mathit{ISF}} \\]

Loop Dose Calculation

A major difference between traditional pump therapy and how the Loop calculates dose is that in pump therapy the current blood glucose is used to estimate the dose, whereas in the Loop algorithm the eventual and minimum blood glucose predictions are also used in determining dosing decisions.

Loop then converts the dose into a basal rate using the Loop\u2019s temporary basal rate duration of 30 minutes:

\\[ \\mathit{BR_correction} = \\frac{\\mathit{dose}}{30 \\mathrm{min}} = \\frac{\\mathit{dose}}{\\frac{1}{2} \\mathrm{hr}} = \\frac{2 \\times \\mathit{dose}}{\\mathrm{hr}} \\]

where \\(\\mathit{BR_correction}\\) is the basal rate ( \\(\\mathrm{\\frac{U}{hr}}\\) ), which is the amount of insulin needed over the next 30 minutes to bring the eventual blood glucose to the correction target. The basal rate, however, is the amount of basal rate needed beyond the user\u2019s scheduled basal rate. As such, the required basal rate can be determined by:

\\[ \\mathit{BR_required} = \\mathit{BR_scheduled} + \\mathit{BR_correction} \\]

Finally, Loop compares the \\(BR_{required}\\) with the user-specified maximum temporary basal rate \\(BR_{max}\\) setting to determine the temporary basal to issue:

\\[ \\mathit{BR_temp} = \\max(\\min( \\mathit{BR_required}, \\mathit{BR_max} ), 0) \\]

After running the temporary basal calculation described above, Loop checks whether there is already an appropriate basal running with at least 10 minutes remaining. If so, Loop will not reissue the temporary basal. However, if the recommended temporary basal differs from the currently running temporary basal \u2014 or the current scheduled basal if no temporary is running \u2014 then Loop will replace the current basal rate with the recommended temporary basal rate.

As mentioned at the beginning of this section, the process of determining whether a temporary basal should be issued is repeated every 5 minutes.

"},{"location":"operation/algorithm/temp-basal/#temporary-basal-rate-calculation-example","title":"Temporary Basal Rate Calculation Example","text":"

To illustrate how the Loop calculates the temporary basal rate to issue, consider the calculation for the following scenario:

  • \\(\\mathit{BG_eventual} = 200 \\mathrm{\\frac{mg}{dL}}\\)
  • \\(\\mathit{BG_target} = 100 \\mathrm{\\frac{mg}{dL}}\\)
  • \\(\\mathit{ISF} = 50 \\mathrm{\\frac{\\frac{mg}{dL}}{U}}\\)
  • \\(\\mathit{BR_scheduled} = 1 \\mathrm{\\frac{U}{hr}}\\)
  • \\(\\mathit{BR_max} = 6 \\mathrm{\\frac{U}{hr}}\\) (set by user in Loop)

First, calculate the dose:

\\[ dose = \\frac{\\mathit{BG_eventual} - \\mathit{BG_target}}{\\mathit{ISF}} = \\frac{200 \\mathrm{\\frac{mg}{dL}} - 100 \\mathrm{\\frac{mg}{dL}}}{50 \\mathrm{\\frac{\\frac{mg}{dL}}{U}}} = 2 \\mathrm{U} \\]

Then, convert the dose into a basal rate to be issued for the next 30 minutes:

\\[ \\mathit{BR_correction} = \\frac{2 \\times \\mathit{dose}}{\\mathrm{hr}} = \\frac{2 \\times 2 \\mathrm{U}}{\\mathrm{hr}} = 4 \\mathrm{\\frac{U}{hr}} \\]

Next, calculate the required basal rate:

\\[ \\mathit{BR_required} = \\mathit{BR_scheduled} + \\mathit{BR_correction} = 1 \\mathrm{\\frac{U}{hr}} + 4 \\mathrm{\\frac{U}{hr}} = 5 \\mathrm{\\frac{U}{hr}} \\]

Lastly, compare the required basal rate to the maximum temporary basal rate, and find that Loop will enact a temporary basal rate of \\(5 \\mathrm{\\frac{U}{hr}}\\) for 30 minutes since this temporary basal rate is below the maximum temporary basal rate of \\(6 \\mathrm{\\frac{U}{hr}}\\), which was set by the user in Loop app settings.

\\[ \\mathit{BR_{temp}} = \\max(\\min( \\mathit{BR_{required}}, \\mathit{BR_max}), 0) = \\max(\\min( 5 \\mathrm{\\frac{U}{hr}}, 6 \\mathrm{\\frac{U}{hr}} ), 0) = 5 \\mathrm{\\frac{U}{hr}}\\]"},{"location":"operation/algorithm/temp-basal/#more-examples","title":"More Examples","text":"

Consider the following values as fixed values for our calculation:

  • \\(\\mathit{BG_target} = 100 \\mathrm{\\frac{mg}{dL}}\\)
  • \\(\\mathit{ISF} = 50 \\mathrm{\\frac{\\frac{mg}{dL}}{U}}\\)
  • \\(\\mathit{BR_scheduled} = 1 \\mathrm{\\frac{U}{hr}}\\)
  • \\(\\mathit{BR_max} = 6 \\mathrm{\\frac{U}{hr}}\\)

The table below shows the \\(\\mathit{BR_temp}\\) for different \\(\\mathit{BG_eventual}\\). \\(\\mathit{BR_temp}\\) should never turn negative and should never be greater than \\(\\mathit{BR_max}\\).

\\(\\mathit{BG_eventual}\\) \\(\\mathrm{(\\frac{mg}{dL}})\\) \\(\\mathit{dose}\\) \\(\\mathrm{(U)}\\) \\(\\mathit{BR_correction}\\) \\(\\mathrm{(\\frac{U}{hr}})\\) \\(\\mathit{BR_required}\\) \\(\\mathrm{(\\frac{U}{hr}})\\) \\(\\mathit{BR_temp}\\) \\(\\mathrm{(\\frac{U}{hr})}\\) 300 4.0 8.0 9.0 6.0 200 2.0 4.0 5.0 5.0 100 0.0 0.0 1.0 1.0 90 -0.2 -0.4 0.6 0.6 75 -0.5 -1.0 0.0 0.0 50 -1.0 -2.0 -1.0 0.0"},{"location":"operation/algorithm/temp-basal/#algorithm-section-menu","title":"Algorithm Section Menu","text":"
  • Algorithm Overview
    • Bolus Recommendations
    • Blood Glucose Prediction
    • Temp Basal Adjustments
"},{"location":"operation/features/battery/","title":"MDT Pump Battery","text":""},{"location":"operation/features/battery/#medtronic-pump-battery","title":"Medtronic Pump Battery","text":"

One common confusion point for new Loop users is how to interpret their pump's battery levels and whether they need to change their pump batteries based on which pieces of information.

"},{"location":"operation/features/battery/#discharge-curves","title":"Discharge Curves","text":"

There are generally two different types of AAA batteries that we use in these Medtronic pumps; alkaline or lithium.

To understand pump battery levels, you first need to know a little about battery discharge curves. It's not a hard concept...basically how a battery dies over time as it is used or sits in a drawer. More technically said, a battery discharge curve is the measure of volts that a battery puts out over time. Batteries start at a higher voltage output and slowly that voltage output degrades over time (or use) until the battery no longer provides enough \"ummph\" to keep the electronic gadget going. BUT, alkaline batteries and lithium batteries have different discharge curves due to the chemistry inside them, and the curves can be slightly different depending on the environment (temperature) and battery manufacturer.

Alkaline batteries have a relatively steady voltage drop over time, as shown below. Notice the shape of the curve has a significant amount of time in the 1.3 to 1.2 volts range, and a relatively smooth decline to about 1.2 volts.

Lithium batteries have a much steadier voltage output over time, as shown below. Notice how the shape of the curve is relatively flat for a large portion of the battery life before suddenly off around 1.3 volts.

What does the above information mean in terms of Looping? A lithium battery at 1.3v is going to have a much quicker time to death than an alkaline battery sitting at 1.3v. You might only get a couple of hours of looping left when a lithium battery is at 1.3v, but an alkaline battery at 1.3v might go for several more days. So when we talk about setting alarm levels in either system, your battery type is an important consideration.

"},{"location":"operation/features/battery/#medtronic-pump-battery-level-indicator","title":"Medtronic Pump Battery Level Indicator","text":"

If you read Medtronic's literature, it will tell you to use Energizer alkaline batteries in their pumps. Why would that be? Hint: the answer doesn't mean that Duracell batteries are inherently worse than Energizer or that lithium batteries won't work in Medtronic pumps.

The answer is all about the accuracy of their little pump battery level indicator on their pump's screen. Medtronic calibrated their pump battery level indicator to:

  • Energizer alkaline batteries
  • Normal (non-Loop) uses
  • Temperatures between 37\u00b0F (3\u00b0C) to 104\u00b0F (40\u00b0C).

In other words, Medtronic ran experiments to see exactly how long an Energizer alkaline battery will last in normal pump use and made their own discharge curve. They programmed their pump battery level indicator to change from 4 bars to 3 bars to 2 bars to 1 bar based on that particular discharge curve.

However, Loop users are slightly more demanding on the pump's battery/voltage than simply delivering insulin. We are also asking for the pump to perform radio communications, in addition to delivering insulin. Those radio communications need a slightly higher voltage than the typical \"normal\" pump use. So while a non-Looper might be ok running their pump until a voltage of about 1.12 for insulin delivery, radio communications might stop at a voltage output of about 1.17. If you experiment with your Looping pump, you'll find Loop will turn red from failed pump comms before the pump actually fails at insulin delivery. This difference between \"failure\" voltages needs to be considered when determining how much useful battery life is left for a pump battery.

In summary, that little pump battery indicator on the Medtronic pump screen is ONLY useful if you are:

  • not using the pump for Looping,
  • using Energizer alkaline batteries, and
  • in the temperature environment similar to their testing.

Loop users should not rely on their Medtronic pump screen's pump battery indicator, and instead use the Loop's pump battery level indicator.

"},{"location":"operation/features/battery/#loops-pump-battery-level-indicator","title":"Loop's Pump Battery Level Indicator","text":"

Keeping the information about battery discharge curves in mind, Loop developers tested various battery brands and types to develop discharge curves for Loop users. These discharge curves form the basis of the pump battery level indicator found in the top right of the Loop's main display screen and the pump battery notifications provided by the Loop app. The pump battery level indicator will also report in %.

  • For x23 and x54 model users, the Loop's pump battery level will move in 25% increments.
  • For x15 and x22 model users, the Loop's pump battery level will move in discrete % increments.

Based on the battery type selected and the pump model being used, the Loop's pump battery level notifications are designed to give the user about 8 hours of notice before pump communications are likely to fail. The Loop user should have some additional time after pump comms fail before actual insulin delivery would stop.

"},{"location":"operation/features/battery/#nightscout-pump-battery-display","title":"Nightscout Pump Battery Display","text":"

The Nightscout information regarding pump battery levels will depend on pump model being used.

  • If you use an x23 or x54 pump and MySentry, the pump levels are reported as a percent to NS, because that's how MySentry reports the data to Loop. The packets use 100%, 75%, 50%, and 25% increments, and the Loop's main display matches the NS pump display.
  • If you use an x22 or x15 pump, the pump levels are reported as voltage readings to NS because Loop has to specifically request the voltage reading from the pump. The Loop's main display will show pump battery level as discrete %, not the individual voltage measurement.
  • No matter what pump you are using, you can always get the current pump battery's voltage by using the RileyLink's Read Pump Status command.
  • The extra communications effort for non-MySentry model pumps will mean slightly shorter battery life vs. MySentry model pumps.
"},{"location":"operation/features/battery/#nightscout-pump-battery-alarms","title":"Nightscout Pump Battery Alarms","text":"

The Nightscout alarms are based on the Heroku settings that you have input specifically. If you don't specifically set them, Nightscout will use the default settings for pump battery alerts as shown below:

Nightscout pump battery levels, if you leave things at default installation, will not trigger alarms. If however you add a setting of PUMP_ENABLE_ALERTS to true, you will receive pump battery notifications according to the levels shown in the parenthesis above. For example, your x23 pump is reporting its levels in percent, therefore you'd receive a yellow warning alarm at 30% and an urgent red alarm at 20%. Your x22 pump however is reporting its levels at voltage readings, therefore you'd receive a warning yellow alarm at 1.35v and an urgent red alarm at 1.30v.

Are the default NS alarm levels going to work for you? The answer depends on what type of battery level you are using, what model pump you are using, and how much advance notification you want to receive before needing to change a pump battery. There is a bit of personal preference and experimentation to finding what works for you.

For x22 or x15 pump users, the NS alert settings that may need to be adjusted are the ones based on voltage.

Generally speaking, for a x22 or x15 pump using alkaline batteries, the default NS alarm levels will be too early to be useful and lead you to change out your battery too frequently. Alkaline batteries can go to low 1.2s or high 1.1s before Looping starts to have communication problems. How much lower than the default voltage 1.35/1.30 alarm levels you want to go will depend on how far in advance you want to be warned about an upcoming battery change.

If however, you are using a x22 or x15 pump with lithium batteries, the default 1.35v/1.30v alarm levels may be completely appropriate. Remember how the lithium battery curves at the start of this discussion died off quickly around 1.3v? You won't get hardly any heads-up notice for a lithium battery if you set the alarm below 1.3v.

For x23 or x54 pump users, the NS alert settings that may need to be adjusted are the ones based on percentage settings.

Alkaline and lithium batteries should have automatically had their percentage-remaining based on the correct battery type in your Loop settings. So, generally speaking the default NS alert levels don't generally need adjusting. However, if you are using lithium batteries, the drop off between 75% to 25% can be quite dramatic and not be easy to anticipate (especially if the drop happens overnight).

As an alternative method of tracking pump battery changes, you could use the insulin age (IAGE) plug-in to anticipate your pump battery changes as well. For example, after tracking pump battery life on my 723 using energizer batteries lithium batteries for the last several months, I know that we get about 15 days plus a handful of hours. The amount of hours more beyond 15 days varies depending on how much we've interacted with the pump buttons directly, whether we've looped the full 15-days solid, and if the pump has been in extreme weather (cold weather can sap pump battery life). By tracking the pump battery changes with NS's careportal \"insulin cartridge change\", I can see in advance if we are nearing an overnight on a 15 day battery and decide to change batteries before overnight to prevent any middle-of-night battery issues.

  • Lithium batteries will get a significantly longer life than an alkaline battery.
  • Experiment and track your particular pump model and battery type to understand what NS settings will work best for you.
  • Do not rely on the pump's on-screen pump battery indicator, especially when using lithium batteries.
"},{"location":"operation/features/bolus/","title":"Bolus","text":""},{"location":"operation/features/bolus/#bolus","title":"Bolus","text":"

This page was updated with information for Loop 3.

"},{"location":"operation/features/bolus/#loop-2-and-3-differences","title":"Loop 2 and 3 Differences","text":"

Most of the information is the same for Loop 2.2.x and Loop 3.

Loop 2 and 3 differences:

  • Loop 3 uses the setting name of Glucose Safety Limit, which has the same meaning as Suspend Threshold in Loop 2
  • With Loop 3.2 and later
    • Loop automatic delivery of insulin is limited when users IOB is two times the Maximum Bolus amount
  • Bolus Row:
    • With Loop 3.0 and later
      • The Recommended Bolus is provided AND the default for the Bolus is the recommended value
      • If the user taps on the Bolus row, the amount is modified to 0 and the keyboard is opened for entry
    • With Loop 2.2.x
      • The Recommended Bolus is provided but the default for the Bolus value is 0
      • If the user taps on the Recommended Bolus row, the recommended amount is transferred to the Bolus row
"},{"location":"operation/features/bolus/#meal-bolus","title":"Meal Bolus","text":"

The Meal Bolus screen is entered following a carb entry or edit action, the active button might be Save and Bolus or, if no bolus was recommended, Save without Bolusing.

The Save refers to saving the Carb entry or Carb edit that led to this screen in addition to saving the amount that might be bolused. It can also refer to saving a fingerstick value entered in the Meal Bolus screen (Loop 3 only).

You can review the carb information at the Meal Entry link.

Carbs are Saved in Meal Bolus Screen

Carbs are saved when the Save and Bolus or Save without Bolusing button is tapped in Meal Bolus Screen. When the button is tapped, carbs are saved even if the bolus does not go through to the pump.

If you see a Bolus Issue notification (Bolus in progress, etc) after saving a carb entry, check the state of Loop carb entries.

Do not just add the carbs again.

"},{"location":"operation/features/bolus/#accept-recommendation","title":"Accept Recommendation","text":"

The graphic below shows the Meal Bolus screen after the user entered carbs and tapped continue:

  • The left graphic shows a case where a bolus is recommended - tapping on the Save and Deliver button saves the carbs and delivers the bolus
  • The right graphic shows a case where no bolus is recommended - tapping on the Save without Bolusing saves the carbs
  • These graphics are taken from a small phone - the left graphic shows all the information at once whereas the right graphic has an extra information message that requires the user to scroll to see the Recommended Bolus and Bolus rows
  • For both graphics
    • Active Carbs and Active Insulin are displayed above the Glucose prediction graph - these are accurate at the time this screen is entered (before carbs or bolus are saved)
    • The Bolus Summary is presented below the Glucose prediction graph with three rows:
      • Carb Entry, the proposed carbs with the time to add the carbs and the absorption time displayed - to modify that information, tap on the < Carb Entry button at upper left
      • Recommended Bolus displays what Loop recommends for that proposed Carb Entry
      • Bolus default display is what Loop recommends, but user can edit that value

If a CGM entry arrives while in this screen, a Bolus Recommendation Updated modal message will be displayed and must be acknowledged.

"},{"location":"operation/features/bolus/#modify-bolus","title":"Modify Bolus","text":"

This section is a continuation of the information presented in the Accept Recommendation section above. In the graphic below, the user overrides the recommended bolus.

  • The left side shows a modified bolus less than the recommended bolus
  • The right side shows a modified bolus greater than the recommended bolus
  • The Glucose prediction graph updates with changes to the Bolus value, giving the user the opportunity to accept or change their proposed value before tapping Save and Deliver
  • At the next Loop cycle, the app modifies insulin delivery based on the saved information
    • For the example with bolus less than recommended amount:
      • Loop will NOT begin to automatically increase insulin delivery until the current glucose is above the bottom of the Correction range
      • The recommendation to add insulin when the current glucose is below the Correction Range is only offered as a manual feature and is limited to an amount predicted to maintain glucose above the Safety Threshold
    • For the example with bolus greater than recommended amount:
      • Loop will probably issue an automatic temp basal of 0 U/hr
      • This is a common \"super-bolus\" scenario; in other words, \"borrow\" basal for the meal bolus to limit post meal spikes
  • Remember - the Glucose prediction is what happens if you Save and Deliver and then no further adjustments are made to insulin delivery by Loop

"},{"location":"operation/features/bolus/#manual-or-correction-bolus","title":"Manual (or Correction) Bolus","text":"

To start a bolus entry, tap on the double orange triangles (circled below) in the toolbar at the bottom of the Loop status screen.

The Loop app will open to the Bolus screen. This looks similar to the Meal Bolus screen without the Carb Entry row. Loop considers the Glucose Safety Limit and Predicted Glucose when determining the recommended bolus.

In the graphic below, the current glucose is under the Correction Range. Loop allows you to dip below the correction range but its recommended bolus will be limited by the glucose prediction and the Glucose Safety Limit. Check back once your glucose starts to rise and there will probably be a bigger recommendation.

This screen behaves differently for Loop 2.2.x and Loop 3. The graphics and instructions on this page are for Loop 3 version. Click on the Loop 2.2.x link above to view the Loop 2 version.

When the Bolus screen is entered directly from the toolbar, the button choices are Enter Bolus if none is recommended, Deliver if a value is on the Bolus row or Cancel using the button on the upper left. The user can also tap on the value on the Bolus row to bring up a keyboard to modify that amount. When doing that, the value is automatically set to zero.

The two graphics below are examples of manual bolus screens.

  • In the first graphic, no bolus was recommended
    • If you tap on the Enter Bolus button at the bottom, it brings up a screen to enable you to type in an amount and then Deliver it.
    • Alternatively, you can tap the 0 amount in the Bolus row and perform the same action as the Enter Bolus button
    • If you do not want to override the recommendation, hit the Cancel button at upper left.

  • In the second graphic, a recommended amount is shown
    • If you tap on Deliver that recommended dose is delivered
    • If you tap on the value on the Bolus row, you can override the amount
    • The amount displayed on the Bolus row is modified to 0 U with the first tap - at that point, you may enter a new value or tap Cancel using the button at upper left of the screen

"},{"location":"operation/features/bolus/#recommended-bolus","title":"Recommended Bolus","text":"

Loop updates the glucose prediction every time a new glucose reading is detected, typically every 5 minutes. If Loop predicts your glucose will be above the high end of your Correction Range at the end of the Duration of Insulin Activity (DIA) and the predicted glucose is above the Glucose Safety Threshold, it will provide a Recommended Bolus. Loop will not give an alert when a bolus is being recommended, the bolus entry tool must be clicked to check for one. The Loop pill in Nightscout will display when Loop is recommending a bolus.

  • If your Dosing Strategy is set to Temp Basal (default)

    • Loop will provide increased temporary basal rates until it has delivered enough insulin to bring predicted glucose into range
    • The increased temporary basal rates are subject to your Delivery Limits.

  • If your Dosing Strategy is set to Automatic Bolus

    • Loop will recalculate the correction bolus at each successive loop interval, i.e., every 5 minutes
    • Loop will then automatically deliver 40% of that new correction value
    • Each automatic bolus is subject to your Delivery Limits
"},{"location":"operation/features/bolus/#bolus-status-line","title":"Bolus Status Line","text":"

Lock Phone During Bolus

Once the bolus has started, you should lock your phone to avoid inadvertently cancelling a bolus.

When the phone is in portrait mode, a bolus status line will appear below the Heads Up Display when Loop has a bolus in progress. The \"starting bolus\" indicator is shown in the left screenshot above - this is when Loop is communicating with the RileyLink. Once the message has been sent to the RilyLink, even if a response from the pump did not make it back to Loop, the bolused xx of yy with the circle display begins, as shown in the right screenshot above. If you change your mind, just click on the bolus status line while the bolus is in progress to cancel your bolus, as shown in the screenshot below. (Newer versions of Loop explicitly state: Tap to Stop on this line.) The amount bolused shown in this display is based on time. Loop reconciles the bolus amount with messages received from the pump once the bolus completes.

If you see a 'pump is suspended notice' in the bolus status line after cancelling your bolus, just tap on it to resume pump operations.

"},{"location":"operation/features/bolus/#bolus-failure-notifications","title":"Bolus Failure Notifications","text":"

On occasion, you will receive a notification that a bolus may have failed. If your Dosing Strategy is set to Automatic Bolus, this can happen when an automatic bolus is in progress. In some of these cases, the bolus was delivered. On a Medtronic pump, you should check the pump screen to verify the bolus status before attempting to redeliver a failed bolus. Omnipod users can hear the clicks if the room is quiet enough.

If you get an uncertain delivery message, you may still see the \"bolused xx of yy\" display continue for as long as it would have taken to actually deliver the bolus. This display is driven by a timer and logic on the phone. (Loop is not asking the pump repeatedly - \"are you done yet?\"). You may want to interrupt an uncertain bolus if it is large, evaluate status and then resume with a fresh bolus. Loop should update the status the next time it contacts the pump. It can determine whether that bolus actually went through or not and will update the screen. Look at the Event History screen (accessed by tapping the Active Insulin or Insulin Delivery plots). Turn your phone to landscape orientation and you should see either \"Certain\" or \"Uncertain\" at the end of each Bolus record. (If you tap on the specific record, even more detail is displayed.)

If an \"uncertain\" delivery is not resolved:

  • Make sure the RileyLink compatible device is communicating properly
  • You can try to turn off Bluetooth and then turn it back on again
  • Quit the Loop app and restart it. (Note - this is different from a power cycle of the phone which remembers settings within an app that was running before the power cycle.)

If that does not resolve the issue, please tap on Loop Settings, Issue Report and email it to yourself. Then post on Facebook or Zulipchat, explain what happened and say you have an Issue Report. Someone should reach out to you.

There are other alert messages that might be displayed if the pump or CGM is not active. Those are found on the Loop 3 Displays page.

"},{"location":"operation/features/bolus/#loop-2-bolus-screen","title":"Loop 2 Bolus Screen","text":"

  • Loop 2.2.x shows the recommended bolus but the bolus row is initially set to 0

    • You can tap on the Recommended line and that value will be transferred to the Bolus line
    • OR
    • You can tap on 0.0u on the Bolus row and type in your desired bolus amount
    • As soon as a value is entered on the Bolus row, the Deliver button turns blue and can be tapped to deliver that amount via your pump.

"},{"location":"operation/features/carbs/","title":"Meal Entries","text":""},{"location":"operation/features/carbs/#meal-entry","title":"Meal Entry","text":"

This page was updated with information for Loop 3.

"},{"location":"operation/features/carbs/#loop-3-updates","title":"Loop 3 Updates:","text":"
  • Time: Loop 3 adds the +/- 15 minute buttons to adjust time for entry
  • Food Type: emoji keyboard
    • Loop 3 initially displays Medium emojis and the association of some emojis with absorption time has been improved
    • Loop 2.2.x initially displays Fast emojis
  • Absorption Time: values for fast, medium and slow
    • Loop 3 uses 30 minutes, 3 hr, 5 hr
    • Loop 2.2.x uses 2 hr, 3 hr, 4 hr
  • Meal Bolus: Loop 3 fills in the Bolus row with Recommended Bolus
  • Large Meal Warning
    • The warning limit of 99 g was chosen to assist in catching mistakes such as entering 115 grams instead of 15 grams
  • Override Active Warning
    • A warning is presented when entering carbs while an override with sensitivity other than 100% is active
"},{"location":"operation/features/carbs/#meal-entry-fast-version","title":"Meal Entry - Fast Version","text":"

To start a new meal entry, tap on the green plate icon (circled below) in the toolbar at the bottom of the Loop status screen. Your Loop app will open to the Add Carb Entry screen.

Loop assumes carbs saved will be absorbed and Loop will adjust recommended insulin, and, when Closed Loop is enabled, Loop will adjust automated dosing based on those carbs.

  • Loop updates the carb estimate dynamically based on your glucose while meal is active
  • Approximate entry is \"good enough\"; better to underestimate carbs than to overestimate
  • The Loop recommended bolus can be modified by editing the Bolus amount after tapping the Continue button on the Add or Edit Carb Entry screen.

Beginner's Tip

  • Add some amount of carbs when you normally would dose before or at a meal
    • Make sure the amount of insulin recommended is not more than you expect
    • If the amount seems too large, you might need to reduce Amount Consumed entry or adjust settings
  • Accept the defaults as directed below
"},{"location":"operation/features/carbs/#meal-entry_1","title":"Meal Entry","text":"

The steps and graphics in this section are for users of Loop 3. To view the version used by Loop 2.2.x, click on this link.

Tap the meal entry icon on the toolbar to open the Add Carb Entry screen:

  1. Enter number of grams of carbs in the Amount Consumed row (keyboard appears automatically)
  2. Tap continue to advance to the Meal Bolus screen (as shown in the graphic below)
  3. Tap Save and Deliver to Save the carbs and Deliver the recommended bolus

The carbs are not saved until the Meal Bolus screen is completed.

  • If no bolus is recommended in the Meal Bolus screen:
    • A No Bolus Recommended warning appears with the reason why
    • The blue button on the Meal Bolus screen says Save without Bolusing
    • In this case, carbs are saved when the Save without Bolusing button is tapped

Carbs are Saved in Meal Bolus Screen

Carbs are saved when the Save and Bolus or Save without Bolusing button is tapped in Meal Bolus Screen. When the button is tapped, carbs are saved even if the bolus does not go through to the pump.

If you see a Bolus Issue notification (Bolus in progress, etc) after saving a carb entry, check the state of Loop carb entries.

Do not just add the carbs again.

By tapping on the Active Carbohydrates chart on the main Loop display, previously entered carbs can be edited, refer to Edit Meals.

"},{"location":"operation/features/carbs/#meal-entry-row-by-row","title":"Meal Entry Row by Row","text":"

Do you want to know more? This section discusses each row in turn.

"},{"location":"operation/features/carbs/#amount-consumed","title":"Amount Consumed","text":"

When entering the Add Carb Entry screen, the number keypad is deployed and when you start typing, that value is entered into the Amount Consumed row.

Tapping on any other row dismisses the number keypad. It can be restored by tapping on the Amount Consumed row.

Some value must be entered into the Amount Consumed row to continue.

Many Loopers increase the carbohydrate amount to cover the expected effect of protein and fat in their meal entry. For simplicity, the rest of this page only refers to carbs because all the figures show carbs or carbohydrates in the menus. You should consider the whole meal, including fat and protein, especially if you eat lower carb.

Loopers who consume mostly carbs in a given meal, might do better entering just the carbs.

"},{"location":"operation/features/carbs/#time","title":"Time","text":"

Modifying the Time for a new meal entry from the default value of \"now\" is optional.

  • Each tap on the \u2212 icon changes the time earlier in 15 minute increments
  • Each tap on the + icon changes the time later in 15 minute increments
  • Tap on the time to bring up a picker wheel for desired time

The 15 minute increments, which are also available on the watch interface, can be handy if the Looper chooses to prebolus.

Reasons to modify the time when entering a meal:

  • Meal is planned for the future, e.g., prebolus now (optional)
    • If meal is planned more than 15 minutes from \"now\", it's a good idea to modify the time to the planned start time
    • In Closed Loop, insulin dosing adjusts for planned carbs while maintaining the Glucose Safety Limit
  • Meal was eaten in the past but carbs were not entered
    • Loop does a better job with predictions if you enter the meal at the time it was eaten
    • Entering a previous meal (now) makes Loop think the carbs will all be in the future (not some of them in the past) and can cause too much insulin to be recommended / delivered
  • Some foods, like pizza, may need entries to start later with a longer absorption time

Limits for time entry of when meal was consumed:

  • The carbs can be entered up to 12 hours earlier or 1 hour later
    • When editing, this limit applies to the time when the carb entry was previously saved
"},{"location":"operation/features/carbs/#food-type","title":"Food Type","text":"

Food Type entries are optional.

The information about the next row: Absorption Time is also important when discussing Food Type entries.

  • The first touch of any icon sets the absorption time to the value associated with that icon
    • This includes the 3 icons (Lollipop, Taco, Pizza) on the Food Type row
    • If you touch the plate icon (or the words Food Type), a new set of icons (food emoji) appear as shown in the graphic below
      • Each emoji is associated with Fast, Medium or Slow absorption time
      • The first emojis presented are medium - scroll in either direction to view the fast and slow emojis or tap on the short-cut tabs at the bottom of the screen
      • The emojis under Other have no effect on absorption time and they do not \"count\" as a first tap; e.g., wine followed by bacon updates absorption time to Slow.
  • Any additional icon touches have no effect on selected absorption time
  • At any time, the Absorption Time picker can be used to adjust the absorption time

Pro Tip

  • If you want to enter food emojis
    • Verify food absorption time when you are done
    • If you know you want to keep the 3 hour absorption time, tap the taco icon on the main screen before entering food emojis

Loop 3 Absorption Times

If you switched to Loop 3 from Loop 2.2.x, please be aware that absorption times for the Lollipop, Taco, Pizza icons have been updated.

  • Loop 3 uses 30 minute, 3 hours and 5 hours
  • Loop 2.2.x used 2 hours, 3 hours and 4 hours

Beware using Lollipop for Complex meals

If you select the Lollipop icon for a large complex meal with Loop 3, you tell Loop to expect glucose to rise rapidly (30 min absorption). When that rapid rise does not materialize, Loop may predict an unexpectedly low glucose because the algorithm assumes something must be affecting 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.

\ud83c\udf6d (Fast) is for simple foods often used for low treatments. Some Loopers use it for coffee.

"},{"location":"operation/features/carbs/#absorption-time","title":"Absorption Time","text":"

Modifying the Absorption Time from the default value of 3 hours is optional.

  • If you touch any icon on the main entry or Food Type row, the absorption time associated with that icon becomes the new absorption time
    • Any additional icon touches have no effect on selected absorption time
  • At any time, the Absorption Time picker can be used to adjust the absorption time

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

Loop assumes a specific model for how those carbs will be absorbed that is spread out over an interval that is 150% of the selected time. This allows for variations in actual absorption. More information about this model is found in the prediction link above.

Many meals can be entered with the medium (3 hour) default absorption time. Learn by experimenting and modify going forward. Evaluate the CR setting, as well as the entries for Amount Consumed and Absorption Time for adjusting meal entries. The amount of up-front insulin recommended is typically similar up through 3 hours absorption and then begins to decrease as absorption time is increased.

Experiment for yourself - how much does Loop recommend compared to a straight Carbs/CR value? Try this at different times; especially when glucose is nominal and flat compared to low and dropping or high and rising.

  • Enter an absorption time and hit continue
  • Examine recommended bolus
  • Tap the < Carb Entry button at upper left
  • Modify the absorption time and hit continue
  • Repeat to get a feel for the up front bolus under different scenarios
"},{"location":"operation/features/carbs/#continue","title":"Continue","text":"

Carbs are not saved in the Add Carb Entry screen until the Continue button is pressed and the user saves those carbs in the Meal Bolus screen, follow the link for details.

"},{"location":"operation/features/carbs/#large-meal-warning","title":"Large Meal Warning","text":"

If the Amount Consumed row exceeds 99 grams when the Continue button is tapped, the user is provided with a modal alert from which they can proceed to the Meal Bolus screen, or return to edit Amount Consumed if that was not the intended amount.

"},{"location":"operation/features/carbs/#override-active-warning","title":"Override Active Warning","text":"

If you have an override active with insulin sensitivity value set to anything other than 100%, a warning message appears at the top of the Add Carb Entry screen.

"},{"location":"operation/features/carbs/#automatic-bolus","title":"Automatic Bolus","text":"

Loopers who are using the Automatic Bolus Dosing Strategy should still prebolus and/or bolus for meals. The amount of Recommended insulin that will appear in the Meal Bolus screen will be the full amount of the bolus Loop recommends (not the 40% partial bolus delivered automatically). As discussed above, you can accept this recommendation or enter a different amount, however, and this is very important, if your Dosing Strategy is set to Automatic Bolus, by entering less than the recommended amount and tapping Deliver or tapping Save Without Bolusing, you are telling Loop to deliver the remaining recommended insulin in the future using 40% of the recommended bolus at each successive Loop interval.

Carb Entry Leads to Insulin Delivery

Note that this same automatic delivery of insulin in response to entered carbs occurs when Dosing Strategy is set to Temp Basal, but the delivery via temporary basal rates is slower, providing more time for an error to be noticed. By the same token, the Automatic Bolus Dosing Strategy responds more quickly to increases in blood glucose, helping to minimize food spikes.

"},{"location":"operation/features/carbs/#edit-meals","title":"Edit Meals","text":"

Adjusting a meal entry can be a particularly useful tool when:

  • You did not finish an entire meal that you bolused for,
  • You did not get to eat the meal at the time you originally expected,
  • You ate more servings than originally entered, or
  • You suspect your carb count was in error because BGs are rising more/less than expected.

From the main Loop screen, tap on the Active Carbohydrates chart to view the Carbohydrates screen (see graphic below).

To adjust an entry, simply tap on it (do not tap the Edit button at the top of the screen). You can change the time, modify carb amounts, or adjust absorption times (even mid-meal). To delete an entry, you first tap Edit and tap on the red circle to the left of the entry that you would like to delete. It is a little counterintuitive, but the Edit button lets you delete, but not edit an entry.

For more information on some of the details reported on this screen, review Dynamic Carb Absorption

"},{"location":"operation/features/carbs/#review-carb-absorption","title":"Review Carb Absorption","text":"

New Loopers, and even experienced Loopers with an unfamiliar meal or activity, should review how Loop reports absorption for the carbs you entered for a meal. If you have perfect dosing for your meal (the mythical flat line), then the carb absorption will match the model perfectly. But sometimes, there might be COB on the Active Carbohydrates Chart Loop 3 / Loop 2 that doesn't reflect your current situation, and you might need to make an adjustment. Note that while Loop is pretty forgiving on exact values and absorption time, you need to learn what works for you. Some common things to consider are listed below.

  • Need to adjust value for carbs or account for fat/protein
  • Need to adjust aborption time
  • Need to review settings
  • Settings, carbs and absorption time are good for this meal but there was more or less activity than normal
  • Stress / Hormones / Exercise
  • Other effects

You can Edit previously saved carbs so Loop has a better idea of how to adjust predicted glucose moving forward. This can head off a low or a high.

"},{"location":"operation/features/carbs/#check-cob-before-adding-more","title":"Check COB Before Adding More","text":"

Loop works better when informed that carbs are coming, but if you have a lot of left-over carbs from an earlier entry - wait before adding more carbs for that next snack. If Loop thinks more carbs are expected, it will dose extra insulin to accommodate. Maybe set a timer and check back in half-an-hour or an hour to see if you really need to add more carbs.

Dosing at a Party

Example - at a party where Looper is eating small amounts at a time, get some carbs entered to get some insulin up front, but pay attention when clicking add carbs (especially when using the watch and accepting recommended dosing).

"},{"location":"operation/features/carbs/#avoid-double-meal-entries","title":"Avoid Double Meal Entries","text":"

Be Aware

If you have accidentally made duplicate entries for the same meal, click on the Active Carbohydrates chart in the main Loop screen and tap Edit to delete the redundant entries. Deleting the meal entry will not impact the insulin that has already been delivered, but it will alert Loop to adjust your BG projection for purposes of calculating future insulin delivery.

"},{"location":"operation/features/carbs/#dynamic-carb-absorption","title":"Dynamic Carb Absorption","text":"

Loop observes the blood glucose impact of the meal within the 150% absorption time window. Loop calculates how many carbs have been absorbed (regardless of how many you entered) based on your BG pattern and your settings.

You can watch the progression of Loop's observations of your meal by tapping on the Active Carbohydrates chart at the bottom of Loop's main screen and watching the insulin counteraction effects (ICE) on the Carbohydrates screen. An example of the screen is on the left side of the figure below. An explanation of the dual lines for each entry and the color coding scheme is explained below the figure. Click on the ICE link for more details and an in-real-life example.

  • Top line of each entry for the graphic on the left (above)
    • Amount you entered, time of entry, absorption time entered
  • Bottom line of each entry (changes with each CGM reading)
    • Amount absorbed, estimated time when amount you entered will be absorbed
    • Color codes while within the 150% absorption time window
      • Green: amount absorbed is less than 10% above the entered amount
      • Yellow: amount absorbed exceeds 10% above the entered amount
    • Color codes after 150% absorption time window expires
      • Grey: amount absorbed is within 10% of the entered amount
      • Yellow: amount absorbed is exceeds 10% above or below the entered amount

The information available on the Carbohydrates screen disappears for any meals older than 12 hours, so if you're looking for details as to how a particular meal absorbed, you may need to screenshot or otherwise capture this information within that window. Previous entries can be modified or deleted through this screen.

"},{"location":"operation/features/carbs/#medtronic-warning","title":"Medtronic Warning","text":"
  • Do not enter carbs into your Medtronic pump
    • If you use your Medtronic pump bolus wizard or carb entry screen, the pump will give you insulin but Loop will not know about the carbs
    • The Loop predictions will be off and next time Loop reads the reservoir history on the pump, it will probably command a temporary basal rate of 0.0 U/hr
"},{"location":"operation/features/carbs/#nightscout-entries","title":"Nightscout Entries","text":"

With Loop 3, a caregiver can add remote carbs and perform remote bolus through Nightscout, but that requires set-up between the caregiver and Loopers phone and use of the Remote Carb and Remote Bolus entries in the Careportal.

If you enter carbs (not remote carbs) into the Careportal, they are not read by Loop and will not be reflected in COB.

  • There may be times you want to do this, e.g., you want to indicate a low treatment you don't want Loop to know about
"},{"location":"operation/features/carbs/#third-party-apps","title":"Third Party Apps","text":"

This is relevant for Loop 2.2.x versions. Loop 3 does not read carbs from Apple Health unless you modified the code.

Please see Loop 2 Permissions.

"},{"location":"operation/features/carbs/#carb-absorption-model","title":"Carb Absorption Model","text":"

For more information about the way Loop models the effects of carbs, insulin, etc., see the algorithm page.

"},{"location":"operation/features/carbs/#loop-2-fast-meal-entry","title":"Loop 2 - Fast Meal Entry","text":"

This section is for users of Loop 2.2.x.

Tap meal entry icon on toolbar

  1. Enter number of grams of carbs in the Amount Consumed row
  2. Tap continue to advance to the Meal Bolus screen
  3. Tap Recommended line to transfer the value to the Bolus line (Loop 2.2.x)
  4. Tap Deliver

The carbs are not saved until the Meal Bolus screen is completed.

By tapping on the Active Carbohydrates chart on the main Loop display, previously entered carbs can be edited, refer to Edit Meals.

"},{"location":"operation/features/ice/","title":"Meal Review","text":"

When on Loop main screen, tapping on the \"Active Carbohydrates\" graph will open up the \"Carbohydrates\" details page that tracks your carb entries for the last 12 hours and how they are absorbed. It can be helpful to review your meals when monitoring settings, troubleshooting past meal entries, and planning future meal entries.

"},{"location":"operation/features/ice/#insulin-counteraction-effects","title":"Insulin Counteraction Effects","text":"

What are Insulin Counteraction Effects (ICE for short)?

Consider the possible effects that counteract insulin (in other words, make glucose levels go up):

  • food
  • stress
  • illness
  • site failure
  • basal too low
  • someone sat too close to you

As we all know, this list can be long; but on \"normal\" days, food is the primary reason glucose levels go up. By \"normal\", we mean basal rates and settings are close to correct, illness is not an issue, and the site is good. We depend on the Loop dynamic carb absorption and other prediction effects to keep glucose in our desired range.

When you have carbs on board, Loop always\u00a0assigns ICE to carbs, not just on a normal day. This is how Loop looks at it. Keep in mind that in situations where you have other positive ICE, like insulin resistance, and carbs on board, Loop will attribute all the positive ICE to carbs until all the entered carbs are considered absorbed. At that point, ICE will start driving RC upward.

Insulin Counteraction Effect (ICE) as explained in Dynamic Carbohydrate Aborption is one very important part of carb absorption as well as a foundational part of Loop Predictions.

"},{"location":"operation/features/ice/#glucose-change-display","title":"Glucose Change Display","text":"

The graph at the top of your \"Carbohydrates\" details page shows the effect Loop expects carbs to have on your glucose (gray bars) compared to the actual effect, or ICE. The units on the graph are mg/dL/5-min or mmol/L/5-min

  • \u2b1c\ufe0f: The gray bars represent the effects of carbohydrates on your blood glucose that Loop is currently modeling.

  • \ud83d\udfe9: As a meal is tracked by Loop, you'll see green bars of observed carb absorption (including ICE).

    How Loop thinks about carbs

    ICE is just one important component of how Loop thinks about carbs. The other parts are the user-entered data (amount of carbs, and absorption speed).

    Sometimes Loop falls back to a default absorption model when ICE is less than the minimum absorption rate.

    In the graphic below, early in the meal timeline, the green bars are below the grey bars. Loop uses the minimum absorption instead of estimating absorption from glucose change. For example, if a pre-bolus was \"perfect\" leading to a constant glucose after a meal, the ideal grey bars will be used by Loop throughout.

When not to Use Glucose Change Display to Understand Meal Absorption?

If you know that other non-carb effects are affecting your insulin sensitivity significantly (sickness, exercise, etc), all the info about carb absorption should be considered skewed, and not be used for trying to understand meal absorption.

"},{"location":"operation/features/ice/#practical-use","title":"Practical use","text":"

Some practical use of the ICE screen is provided in the Meal Entries: Review Carb Absorption section.

Many ways to successfully use Loop

You should choose what works for you.

  • Some people plan ahead and try to get their carbs entries \"good enough\" to not worry about Loop or glucose after they make the initial entry
  • Some people enter typical values for themselves for a given meal and let Loop handle the rest
  • Some people guess and then carb surf if their glucose goes higher than they like

The rest of this page was written by Katie DiSimone before the non-linear carb model was added to Loop in 2019. You may also want to review her blog post from 2017: Loop: Dynamic Carb Absorption.

A lot of the information is still relevant although some of the Loop carb modeling and prediction details have been updated over the years.

Let's take a look at an example day using the screenshot below.

When you make a food entry originally, Loop will save your entry as you've made it. On the line below your original entry, Loop will also start tracking your food entry assuming a 1.5 times longer carb absorption time. This helps Loop track carbs that may actually be absorbing longer than you expected (part of that whole dynamic carb absorption modeling). Loop will be updating that value of \"observed\" carb absorption time as well as absorbed carbs as your meal goes on.

So how can we use this information to make our Looping experience better? The answer is probably best illustrated using a real-world example. Chinese food...in fact, this Chinese dish. General Tso's chicken. As you can see in the recipe, loads of fast carbs with ingredients like hoisin sauce, brown sugar, and cornstarch. But also slower carbs like chicken. Rice can be a difficult one because, for us, it acts fast but also seems to have a long tail.

It was a busy day and I really didn't want to count carbs. Ok, even on the slow days I don't want to count carbs. I just eyeballed the bowl of food and guessed. As I entered the food in originally, I was still trying to come up with a good guess on the ratio of fast:slow carbs but kid was in a hurry to eat. My initial guess around 3:30 pm was 70g of carbs at 5 hours absorption (note: it gets edited to 80g in a little bit), we bolused for that and she started to eat. About 10 minutes later, I decided to add 10g of fast-acting carbs at 1-hour absorption to help with the sauce's speedy carbs.

Watching what was going on a little later...glucose levels were rising at a decent clip and I had a feeling I really didn't cover things super well...so I edited the original 70g entry, adding 10g and making it 80g instead. (That's why there is a 2U bolus around 4:20 pm.) And of course, around 5:40 pm there was a little bit of nibbling on the leftovers as we put them into the fridge. We gave 10g for that. Glucose levels climbed a bit more, not surprising given how we were underestimating fast carbs at this point...but still not so bad at 180 peak glucose. (Anna gave 2 units of correction at the peak because there was dessert coming later that night and she wanted to be ready for it without too much pre-bolus.)

So, how can I use the \"Glucose Change\" graph to make this meal better? I can look at the observed carb information and the observed carb entry Loop has recorded to adjust my insulin bolusing the next time we eat this meal.

For example, the biggest weakness I had in this (and suspected it even as I did the initial bolus) was that I underestimated the sauce's fast carbs. I can see this in the observed carb absorption graph having the early green peaks after the meal, and in the way that the observed carb distribution was more like 7:2 vs my original guess of 8:1 (slow:fast carbs). Overall, it appears that I guess on overall carb content pretty closely (90g vs. 89g observed). Next time we have General Tso's chicken, I will likely bolus it as 70g at 5 hours and 20g at 2 hours.

Check Carbohydrates Page

Remember to check your Carbohydrates page at the end of a meal's absorption. By checking in on the meal's observed behaviors, you'll have a good starting point to fine-tuning any new or unknown carb breakdown.

Note

Remember this conversation is assuming you have basals fairly well set and are not sick. If other factors could be significantly causing your glucose levels to swing that Loop doesn't know about (bad sites, illness, or basal rates that need to be adjusted), they may be attributed in part to ICE when they really aren't food-related. In those cases, address the underlying cause and then use the Carbohydrates page when you've come back to \"normal\".

"},{"location":"operation/features/notifications/","title":"Loop Notifications","text":""},{"location":"operation/features/notifications/#loop-notifications","title":"Loop Notifications","text":"

Loop provides discrete notifications on the iPhone and Watch which will appear on the (locked) screen and vibrate, depending on your notification settings of Loop.

"},{"location":"operation/features/notifications/#loop-alert-unable-to-reach-pump","title":"Loop Alert - Unable to Reach Pump","text":"

With Loop 3, there is a new modal alert that halts all Loop activity until pump communication can be restored.

When you tap on the Learn More button, another screen appears. The only option allowed on the second screen is to give up and discard the pump (or pod) or continue to wait - tap the Back button. The second screen is there if you need to tell Loop you will not be able to restore communication and it should treat the last attempt to send a command as uncertain. Loop will then allow you to add a new pod or new Medtronic pump or switch to a different insulin delivery device.

Only do this if bringing your phone and pump into close proximity, waiting a few minutes and then trying the Reset Loop-to-Pump Communications suggestions are not successful.

Why Stop all Activity?

When communication is interrupted at a critical moment in the communication cycle, Loop cannot provide a reliable calculation for IOB. When that happens a warning screen similar to the graphic above appears on your device. You cannot do anything but wait for Loop to restore communications or give up on that device.

"},{"location":"operation/features/notifications/#loop-app-expiration-notification","title":"Loop App Expiration Notification","text":"

Profile expiration notification was added with Loop 2.2.5.

  • When fewer than 20 days remain until profile expiration, you'll get a notification when you open the app but no more frequently than every 2 days
  • When fewer than 24 hours remain, you'll get a notification when you open the app, once every hour at most
  • Simply tap on the More Info button of the notification to go directly to the LoopDocs Updating page.
"},{"location":"operation/features/notifications/#free-7-day-loop-app-expiration-notification","title":"Free (7-day) Loop App Expiration Notification","text":"

The expiration notification pattern is the same as for the Paid Loop App. You may want to add an Expiration Notification Customization to modify the first appearance and frequency of the notification.

"},{"location":"operation/features/notifications/#loop-app-expiration-date","title":"Loop App Expiration Date","text":""},{"location":"operation/features/notifications/#for-loop-32x-and-newer-versions","title":"For Loop 3.2.x and newer versions","text":"

The expiration date is found in the App Profile section at the bottom of the Loop Settings screen.

"},{"location":"operation/features/notifications/#for-loop-225-through-loop-30","title":"For Loop 2.2.5 through Loop 3.0","text":"

If you want to see the expiration date at any time:

  • Loop 2.2.5 through 2.2.9: tap on Settings, then tap on Issue Report
  • Loop 3.x.x: tap on Settings, scroll down and tap on Support, then tap on Issue Report

The expiration date is near the top of the report (to the right of profileExpiration). If you don't see that, time to rebuild to get that feature. Once you've viewed the expiration date, tap Settings to back out of the Issue Report display. The time uses UTC, so adjust to your time zone if you procrastinated until the last minute.

"},{"location":"operation/features/notifications/#omnipod-beeps","title":"Omnipod Beeps","text":"

Most pod beep alarms are disabled for a more discrete use of pods than is available with the PDM. Only the following audible acknowledgments or alarms are used. Some can be configured in Omnipod: Notification Settings:

  • Pod activated acknowledgment when filling the pod with enough insulin when pairing a new Pod.
  • Pod expiration advisory alarm, which you can configure between 48 and 72 hours (3 days)
  • Pod low reservoir alert
    • Note that the pod may continue delivering after the reservoir reports 0 U
    • The pod will continue until the pod runs out of insulin or 4 U is delivered, which ever comes first
    • Loop will update the actual delivery amounts based on pod reported information
  • Pod deactivation acknowledgment
  • Pod fault alarm (also called a screamer) when reaching the max life of the Pod: 80 hours (3 days + 8 hours), running out of insulin or a fault/occlusion happens
    • Screamers are silenced using the Replace Pod row on the pod settings page
    • The one exception is if communications with the pod is lost and cannot be restored - in that case, you will be offered the chance to discard the pod from Loop but will still want to Silence the Pod
"},{"location":"operation/features/notifications/#notification-settings-for-loop","title":"Notification settings for Loop","text":"

You can customize the way notifications of Loop are behaving in the Settings App of the iPhone:

Loop 3 Notifications Settings:

Mark Loop 3 notifications as time-sensitive and ask for immediate delivery:

  • tick the Immediate Delivery so that notifications are delivered right away
  • enable the TimeSensistive Notifications checkbox

Notification Delivery

You will see the Notification Delivery section only if you previously toggled on Settings / Notifications / Scheduled Summary in order to receive a summary of notifications at a certain time of the day. If this is not what you want, simply ignore it.

Announce Notifications

The Announce Notifications section is displayed only if you previously turned on the toggle Settings / Notifications / Announce Notifications. Use it if you want Siri to read Loop's notifications out loud on CarPlay, and AirPods...

Make sure Loop notifications are allowed in your Focus mode. Edit the focus mode to:

  • add Loop to the list of apps with allowed notifications
  • enable the Time Sensitive Notifications toggle button
"},{"location":"operation/features/notifications/#taking-a-loop-break","title":"Taking a Loop Break","text":"

If you want to take a break from using Loop but want to keep the app on your phone, you'll want to disable Loop Notifications while you are not using Loop. Otherwise, the Loop Failure messages will drive you crazy.

When you are ready to resume using Loop, the main screen will remind you to turn those notifications back on.

Another time you might want to disable notifications is if you are testing with a simulated pump. When the app is closed or phone is locked, the simulated pump is inactive and you would get the Loop Failure notifications.

"},{"location":"operation/features/notifications/#loop-failure","title":"Loop Failure","text":"

At 20, 40, 60, and 120 minutes, there is a Loop Failure notification. This mostly happens when the connection is lost for a longer period of time between the CGM or the Rileylink and Loop.

"},{"location":"operation/features/notifications/#bolus-failure","title":"Bolus Failure","text":"

If Loop detects that a bolus was not able to be delivered, it will provide a notification. Bolus failures are usually due to stale pump data. Try fetching recent history from the RileyLink menu to update pump data. Loop will also notify of partial bolus deliveries.

"},{"location":"operation/features/notifications/#low-reservoir","title":"Low Reservoir","text":"

Medtronic At 20% and 10% remaining reservoir volume, there is a Low Reservoir notification.

Omnipod Select your desired notification level for low reservoir Omnipod: Notification Settings

"},{"location":"operation/features/notifications/#empty-reservoir","title":"Empty Reservoir","text":"
  • Loop 2 will notify when the reservoir is empty.
  • Loop 3 reports No Insulin on the Heads-Up-Display.

Omnipod After the reservoir reports 0 U, the pod attempts to deliver insulin when requested.

  • After 4 U are delivered, the pod alarms and must be changed
  • If during the attempt to deliver the 4 U (below zero), the pod runs out of insulin, the pod alarms and must be changed
  • In both cases, the pod reports it is out-of-insulin
"},{"location":"operation/features/notifications/#low-battery-medtronic","title":"Low Battery (Medtronic)","text":"

Loop will notify when battery levels have approximately 8-10 hours of battery life remaining.

"},{"location":"operation/features/notifications/#remote-notifications","title":"Remote Notifications","text":"

Loop does not have a remote notification to other devices. If you are a remotely monitoring parent, you will want to read here about setting up pushover alerts using your Nightscout site if you want proactive notifications of looping related information.

"},{"location":"operation/features/notifications/#loop-follow","title":"Loop Follow","text":"

Many people use additional apps to assist in following a loved one or to support a loved one who needs help waking up to alarms. One of the more popular options is Loop Follow, written by a parent of a Looper. There are several features to assist in remote monitoring with a variety of options for the source of data.

For more information, please read the Loop Follow documentation. You can build Loop Follow using the same Build Select Script you used to build the Loop app or using the GitHub Browser Build Method.

"},{"location":"operation/features/overrides/","title":"Overrides","text":""},{"location":"operation/features/overrides/#new-loopers-please-read","title":"New Loopers - Please Read","text":"

Please do not use this feature until you understand it.

Many new Loopers interpret Loop Overrides as a one-for-one replacement for manual pump options where a temporary basal was applied for a particular activity. Although Loop Overrides can help in a situation where you previously used a temporary basal rate, overrides are more powerful.

Changing Overall Insulin Needs is NOT like Manual Pump Temp Basal Change

Loop Overrides are not the same as adjusting temporary basal on a manual pump. The easiest way to restrict basal rates with an automated system is to raise your correction target temporarily. In some cases, you may need to also adjust insulin needs, but begin just by changing that target.

When you modify insulin needs, you are affecting basal rates, carb ratios, and insulin sensitivity factors (ISF) for the duration of the override.

A common mistake is to think selecting an override with 10% Overall Insulin Needs is like selecting 10% basal rate with a manual pump. With Loop, that selection modifies all your normal settings by a factor of 10!

"},{"location":"operation/features/overrides/#manual-temp-basal","title":"Manual Temp Basal","text":"

Sometimes you need to set a manual temp basal and you need it to keep working whether you are near your gear. There's a function for that with Loop 3.

  • Pods: use the Manual Temp Basal setting
  • Medtronic: select Open Loop and use your Medtronic pump temp basal feature
"},{"location":"operation/features/overrides/#how-overrides-work","title":"How Overrides Work","text":"

Overrides let Loop know selected settings are modified for the duration of the override. The override can change either the correction range or the overall insulin needs or both. When you set an override on insulin needs, the override adjusts basal schedule, ISF, and CR together. Examples where this can be helpful include hormone cycles, steroid medications, and/or exercise.

Override presets are (1) optional and (2) can be configured within Loop's workout icon (the little blue heart icon in the Loop toolbar). Once override presets are created, they can be turned on/off by using the workout icon as well.

"},{"location":"operation/features/overrides/#features-of-an-override","title":"Features of an Override","text":"

Overrides allow you to specify:

  • an overall insulin needs adjustment
  • a correction target range
  • a duration in 15-minute increments (or indefinite)
  • a start time

The override only works when your Loop gear is with you. For example, if Loop sets a zero temporary basal rate based on an override and then you leave your gear behind; at the end of half an hour, your pump will resume scheduled insulin delivery.

The target range replaces the correction range target for the duration of the override.

  • If the target range is left blank, your scheduled correction range continues to be in effect
  • If the target range is specified, that range is used instead of your scheduled correction range

The overall insulin needs is applied to your basal rates, insulin sensitivities and carb ratios for the duration of the override.

  • If the insulin needs is left at 100%, no change is made to basal rates, ISF or CR
  • If you set an overall insulin needs adjustment below 100%, you are telling Loop you are more insulin sensitive and need a lighter touch.
    • Loop uses basal rates decreased from scheduled rates
    • Loop uses ISF and CR numbers increased from settings
  • If you set an overall insulin needs adjustment above 100%, you are telling Loop you are less insulin sensitive and need a heavier touch.
    • Loop uses basal rates increased from scheduled rates
    • Loop uses ISF and CR numbers decreased from settings
  • While the override is active, the modified basal rates, ISF and CR are applied for every automated or manual insulin delivery and affect the calculation for future IOB while the override is active
    • Those ISF and CR numbers are associated with the carbs and/or insulin delivered during the override
    • As the carbs and/or insulin \"ages\" during their absorption-time/duration-of-action, Loop maintains the sensitivity values associated with those during-the-override entries

For an override to be accepted:

  • You must change either insulin needs or target range
  • A named override can be saved and used again
    • To save the override, you must supply a name and an icon
    • Named overrides can be set to occur at a scheduled time
  • A Custom override is used only once
  • Any override can be edited while it is active
"},{"location":"operation/features/overrides/#future-override","title":"Future Override","text":"

When an override is scheduled to start in the future, it can have an effect earlier than you might think. The closed loop automated insulin increase or restriction at each cycle is calculated to map your predicted glucose to the desired target range over the duration of insulin action (6 hours). If the future override has a higher target, that higher target is factored into the Loop calculations.

Example:

  • At 10 pm, you set an override with a higher correction range target to start the following morning at 6 am
  • At approximately midnight, Loop will begin taking that future target into account in the dosing for each Loop cycle
  • By the time you awaken at 6 am, Loop should have your glucose in that higher target range
  • The insulin needs modification, if any, associated with that override do not affect the Loop prediction until the scheduled start time for the override
"},{"location":"operation/features/overrides/#how-overrides-do-not-work","title":"How Overrides Do NOT Work","text":"

Overrides will work while you are Looping. Sounds obvious, right? But, the thing to remember is that the adjustments (multipliers) that overrides make are not saved back to your Medtronic pump or Omnipod. They only exist in the Loop app.

If you walk away from iPhone and/or RileyLink...

If you stop Looping (i.e., walk away from your gear or your glucose reading is stale), your existing temp basal will complete the remainder of whatever is left of its original 30 minutes and you will return to scheduled basal rates in your Therapy Settings. Your adjusted needs as set-up in any override will not continue if your Loop is not running properly. So you cannot set a 50% override and then hop in the ocean for a 2-mile swim without your iPhone and RileyLink and expect decreased basals of 50%. Just be aware that in situations where you need prolonged lower basals while away from Looping gear, you will need to edit your scheduled basals or use a Manual Temp Basal setting.

"},{"location":"operation/features/overrides/#avoid-extreme-insulin-needs-setting","title":"Avoid Extreme Insulin Needs Setting","text":"

There have been users who select a 10% overall insulin need. This is NOT the same as choosing a 10% temporary basal with the PDM. This changes your basal rates, ISF and CR by a factor of 10!

Scenario for 10% Insulin Need

  • User really wants insulin reduced and chooses 10% insulin need
  • User doesn't think about the 10% and enters carbs while the override is active
    • Loop suggests a tiny bolus and the user accepts
      • User goes high because CR was 10 times higher than Therapy Setting Value
      • User stays high because ISF is also 10 times higher than Therapy Setting Value
        • Automated corrections are 10% of typical corrections
        • Basal supplied is 10% of the Therapy Setting value
    • OR
    • Loop suggests a tiny bolus and the user manually boluses the amount they know the food needs
      • User glucose may be normal BUT
        • Loop predicts a negative eventual glucose (prediction only - this will never happen)
        • Loop immediately withholds all basal until prediction normalizes

Instead of selecting 10%, raise your correction range with a moderate needs adjustment. Loop tends to suspend insulin delivery via temp basals with the next CGM reading.

With Loop 3, there is now a warning message in the meal entry screen when an override is active with an overall insulin needs value other than 100%. The user can decide whether to proceed with the meal entry with the override active.

If you feel the need to immediately halt insulin delivery, consider a Manual Temp Basal or suspend command to the pump. If you choose to suspend, be sure to pay attention to the reminder to resume insulin delivery later.

Extreme Athletes

There are athletes who do need those extreme overall insulin need changes and know how to use them appropriately. This typically involves extreme or prolonged exercise.

"},{"location":"operation/features/overrides/#create-an-override-preset","title":"Create an Override Preset","text":"

To create an override preset, tap on the workout icon. Then click the + sign in the upper right corner to start a new preset entry.

You must select an emoji, name the preset and modify either the overall insulin needs or target range or both to save your new preset

  • Pick an emoji
  • Enter a name for the preset
  • Optional: change insulin needs
    • Default is 100% - no change to your settings
    • You may use the picker wheel or Select 1% Insulin Needs increments
  • Optional: enter a target range
    • If you do not enter a target range, Loop will use your existing scheduled target range
  • Select whether you want the override to run indefinitely or for a finite time

When you've made your selections, save the preset using the \"Save\" button in the upper right corner.

"},{"location":"operation/features/overrides/#select-1-insulin-needs","title":"Select 1% Insulin Needs","text":"

Available with Loop 3.

The selectable Overall Insulin Needs values are not limited by the default picker values of 10%.

  • When adjusting Needs, press and hold the \"orange\" bar, highlighted by the red rectangle in the graphic below
  • Move your finger left and right to adjust by 1%
  • Release to select the desired level

"},{"location":"operation/features/overrides/#activate-an-override","title":"Activate an Override","text":"

To enact your override preset, tap on the workout icon toolbar and select an override from your list of saved presets, create a new one or use the custom override for one-time use.

The heart will be highlighted in a blue square while active and the HUD Status Row will indicate the active override name. The Glucose Chart will show a darker blue bar indicating the active target range and duration.

"},{"location":"operation/features/overrides/#schedule-an-override","title":"Schedule an Override","text":"

You can set up a future start time when selecting a saved override by tapping on the calendar icon to the right of the override. Adjust the \"Start time\" row. Tap the \"Enable\" button in the top right corner.

A Future Override can be very helpful, for example, to set an exercise override the night before your workout. You'll wake up with less insulin on board and at your desired exercise targets.

"},{"location":"operation/features/overrides/#deactivating-an-override","title":"Deactivating an Override","text":"

Tap the heart icon to turn off your override at any time. This happens without confirmation, so be sure to lock your phone when you have an override running to avoid accidentally turning it off.

Override presets with a finite duration will automatically deactivate when the duration is over.

"},{"location":"operation/features/overrides/#apple-watch","title":"Apple Watch","text":"

Saved overrides can be turned on and off by tapping on the blue heart icon on your watch.

"},{"location":"operation/features/overrides/#editing-an-active-override","title":"Editing an Active Override","text":"

Tap on the active override in the HUD Status Row with the phone in portrait orientation. This brings up a screen to edit the override currently running.

This only affects this override during the current period. It is not saved to that named override. For example, you can extend the duration or modify the needs value or target value based on a temporary situation.

Higher Priority Messages

If the HUD Status Row is displaying a higher priority message, you must wait for that message to complete before you'll be able to edit an active override. If you want to edit an active override, you can choose to cancel an active bolus and edit the override immediately. The edited override will then be in effect for the next Loop cycle or manual recommendation.

HUD Status Row messages with higher priority:

  • Bolus starting, in-progress or canceling
  • Pump suspended
  • No recent glucose
"},{"location":"operation/features/overrides/#remote-overrides","title":"Remote Overrides","text":"

You can also use your Nightscout site to activate/deactivate your Loop's override presets. To accomplish this, you will need to do some legwork as outlined on this page for how to set up Remote Overrides in Nightscout and you will need to be using a paid Apple developer account. Remote overrides require Apple Push Notifications service, and that is only available on paid accounts.

"},{"location":"operation/features/premeal/","title":"Pre-Meal Target","text":""},{"location":"operation/features/premeal/#pre-meal-range","title":"Pre-Meal Range","text":"

The Loop toolbar's second icon from the left is a small clock with a knife and fork on the sides. This is the pre-meal tool. The tool will be colored grey until you define a glucose range in Loop settings. Once a pre-meal range is available in Loop Settings, the icon will be colored green and available for use. The background coloring of the Pre-Meal Range icon will turn green when active and there will be a dark blue line on the glucose chart indicating the pre-meal range.

The pre-meal range can be used as an easy way to get a small amount of insulin delivered before a meal in order to help control post-meal blood glucose spikes. It's not designed to replace a traditional pre-bolus, but rather as a more gentle way to build up some pre-meal insulin activity.

If your normal target is 100-110 mg/dL and pre-meal range is 80-80 mg/dL, for example, Loop will give you an extra push to get you to the lower target 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 icon, will stay active for one hour, until carbs are entered, or until it is manually canceled... whichever comes first. Setting an override will also cancel pre-meal range.

Loop will adjust any insulin bolus as needed based on the extra insulin provided during this pre-meal time.

Other Uses

Some people prefer to use this as an easy way to raise the correction range for an hour.

"},{"location":"operation/features/premeal/#how-to-adjust-pre-meal-range","title":"How to Adjust Pre-Meal Range","text":"

Loop 3:

  • In Loop Settings, select Therapy Settings and then tap on Pre-Meal Range to adjust
  • If you prefer not to have that icon active on the Toolbar, you can tap Delete in the upper right corner of the adjustment screen

Loop 2.2.x:

  • In Loop settings, find the Correction Range section. The Correction Range sections stores all targets for Loop over the hours of the day, including Pre-Meal.
"},{"location":"operation/features/premeal/#assessing-the-impact-of-pre-meal","title":"Assessing the impact of pre-meal","text":"

The intent of the pre-meal icon on the toolbar is to provide an eating-soon mode in Loop. Do not set pre-meal limits to any hypoglycemic ranges that may require treatment.

To mitigate the impact of unintentional pre-meal activation:

  • If you are running Loop 3, you can delete the setting to deactivate the icon
  • If you are running Loop 2.2.x, you can set the pre-meal range to the same value as your usual correction range

Custom Pre-Meal Overrides

Some loopers set up a custom override to use instead of the pre-meal icon. This allows enabling the override remotely with Nightscout, permits specifying a custom duration, and will keep the override enabled after carbs are announced.

"},{"location":"operation/features/watch/","title":"Apple Watch","text":""},{"location":"operation/features/watch/#loop-with-apple-watch","title":"Loop with Apple Watch","text":"

The Loop user can directly enter carbs and boluses and turn on or off premeal or override settings from the watch, without needing to pull their iPhone out. There are some caveats when iPhone is not within Bluetooth range - the action requested by the watch will not be enacted until iPhone reconnects.

There are two screens in the Loop watch app, shown in the bottom half of the graphic above. By swiping left or right, the other screen is displayed. The eventual (predicted) glucose feature, shown on both screens in the graphic can be turned off as a feature in Loop 3, but requires the user to rebuild. It is on by default.

The screen on the left side of the graphic shows Loop status, current glucose, trend arrow and eventual glucose with icons to enable carb entry, bolus entry, pre-meal and override selection. If necessary, use the crown (or swipe up and down) to see the full display.

"},{"location":"operation/features/watch/#watch-carb-bolus-overview","title":"Watch Carb / Bolus Overview","text":"

After tapping on the carb or bolus icons, you can adjust the entries using the crown to dial in more/less. See Meal Entry on Watch for more details.

  • The watch carb entry screen allows you to choose the amount and absorption time, using the standard icons, and adjust the time the carbs were or are planned to be consumed. After tapping continue on the carb screen, the meal bolus screen is displayed - carbs are only saved after selecting Save or Save & Bolus on the meal bolus screen.
  • The watch bolus screen displays the recommended bolus. If you want to decrease/increase from the recommended amount, use the digital crown or tap on +/- icons to modify.
  • Once the bolus button is tapped, the bolus command is only delivered after using the digital crown to Spin for Watch Bolus to align the two triangles.
  • If you tap Save & Bolus on the bolus screen when entered from the carb screen AND then fail to turn the digital crown to confirm the bolus or hit Cancel, that means the bolus was not delivered and the carbs might not saved - but check to be sure.
"},{"location":"operation/features/watch/#watch-graph-and-status","title":"Watch Graph and Status","text":"

If you swipe the Apple Watch Loop screen from right-to-left, a second screen, as displayed on the right side of the graphic above, is available. This second screen displays a graph of recent glucose and predicted glucose data. The display can be scrolled with a finger swipe or turn of the crown to display Active Insulin, Active Carbs, Net Basal Rate (with respect to scheduled rate) and in some cases Reservoir Units. (A recently changed pod may show the reservoir level from the prior pod - just ignore that. It goes away within 24 hours.)

  • Check the Recent Carbs List on Watch by tapping the Active Carbs row:
    • If a desired carb entry added by the watch is not present on the watch display, you are safe to try again
    • If the carb entry is present on the watch display, do not enter it again
    • If your phone is not in range of your watch, carbs entered on the watch will be added to the phone carb storage when you reconnect
"},{"location":"operation/features/watch/#watch-graph-windows","title":"Watch Graph Windows","text":"

The windows for history and prediction available on the watch can be modified to suit your preference. The windows can be modified from 2 hours to 12 hours.

  • Double tap on the graph to increase the windows
  • Single tap on the graph to decrease the windows

The selection for the window remains as selected until you change it.

"},{"location":"operation/features/watch/#loop-complication","title":"Loop Complication","text":"

A loop complication exists to show glucose on the watch face but the update rate is limited by Apple. If you have a Loop complication installed in the watch face, you can simply tap the complication to open the Loop watch app.

In some positions and with some watch faces, the complication includes a graph.

  • The windows for the Loop Complication history and prediction are fixed (not modified when you change the Watch Graph Windows)
"},{"location":"operation/features/watch/#loop-watch-features","title":"Loop Watch Features","text":""},{"location":"operation/features/watch/#spin-for-watch-bolus","title":"Spin for Watch Bolus","text":"

To prevent an accidental bolus from your Watch app, don't let your kids hold your watch. Just kidding, we've added an even better solution. After requesting a bolus or accepting a meal entry recommended bolus, the watch face displays a graphic like the one below. As you spin the digital crown, the two triangles will begin to merge. Once they merge, the bolus is confirmed through a little haptic and a white checkmark will appear on the watch screen.

"},{"location":"operation/features/watch/#bolus-cancel-or-spin-fail","title":"Bolus Cancel or Spin Fail","text":"

At this point if you hit cancel, or fail to merge the two triangles, the bolus will not be delivered. You will feel a haptic and may hear a notification when Loop stops waiting. The watch display restores to the nominal screen.

"},{"location":"operation/features/watch/#meal-entry-on-watch","title":"Meal Entry on Watch","text":"

Tap on the Meal entry icon on the watch to view the watch carb entry screen as show in the graphic below.

The watch carb entry screen allows you to choose the amount and absorption time, using the standard icons, and adjust the time the carbs were or are planned to be consumed.

  • While the Amount is highlighted, the + and - buttons add or subtract 5 g of carbs from the amount, or you can use the digital crown to adjust the amount
  • Tap on the time and the + and - buttons add or subtract 15 minutes from the time when the meal was or will be consumed, or you can use the digital crown to adjust the time
  • The default absorption time is 3 hours (taco), but the fast (30 minute, lollipop) or slow (5 hour, pizza) can be selected

After tapping the Continue button on the carb screen, the meal bolus screen is displayed - carbs are only saved after selecting Save or Save & Bolus on the meal bolus screen.

"},{"location":"operation/features/watch/#carb-entry-no-bolus","title":"Carb Entry, No Bolus","text":"

If you enter carbs from the watch and no bolus is recommended or selected, you will see a screen like the graphic below where the Save button is offered. You can choose to Save the carbs, or cancel the entry.

If you choose to modify the zero bolus recommendation, the display changes to the option shown in the graphic in the following section.

If your phone is in communication with your watch, then when you hit the Save button, the carbs will be immediately saved to your phone record as well as your watch.

If your phone is not in range of your watch, then when they are brought into communication later, the carbs will appear on the phone.

"},{"location":"operation/features/watch/#carb-entry-with-bolus","title":"Carb Entry, With Bolus","text":"

If you enter carbs from the watch and a bolus is recommended or selected, you will see a screen like the graphic below where the Save & Bolus button is offered.

You may choose to leave that bolus at the recommended level, tap on the + or - buttons to add or subtract 0.5 U per tap or use the digital crown to adjust the value. Should the value go to zero, then the Save button appears as shown in the graphic in the previous section; but remember, Loop will begin adjusting automatic insulin delivery based on those newly entered carbs, even if you choose not to bolus.

  • If your phone is in communication with your watch

    • When you hit the Save & Bolus button, the carbs will be immediately saved to your phone record as well as your watch
    • Your pump will be commanded to deliver the indicated dose (from your phone)
      • If the pump communication succeeds, the delivery begins
      • If the pump communication fails, the bolus not delivered message will apear on the phone
      • You might want to have confirmation beeps enabled so you can hear if the pump bolus starts

  • If your phone is not in range of your watch

    • The carbs are saved in the watch carb storage
    • When the watch reconnects with the phone, the carbs are added to the phone carb storage
    • The bolus not delivered message will appear on the phone
"},{"location":"operation/features/watch/#recent-carbs-list-on-watch","title":"Recent Carbs List on Watch","text":"

You can review the recent carb entries on the Apple Watch. Simply swipe left to see the blood glucose graph screen on the watch. Scroll down with your finger or the digital crown to the Active Carbs row beneath the graph, and tap that row. You can see the list of recent carb entries.

If you enter carbs on your watch while not connected to the phone, they will appear on this display and, when the phone reconnects, will be transferred to the phone.

Be Cautious - Avoid Double Entry

If the phone and watch are not connected, someone could add entries to the phone manually or via remote commanding and the watch will not know about them. So be careful and check the phone carb record when the phone and watch reconnect. This is especially important if more than one caregiver is involved.

"},{"location":"operation/features/watch/#eventual-glucose-on-watch","title":"Eventual Glucose on Watch","text":"

One feature on the Watch app that can be turned on and off with Loop 3 is the eventual glucose display on the watch. That display is shown on the graphic above with current glucose on left, trend arrow beside it and eventual (from prediction) glucose on the right.

If this is a feature you want turned off, please follow the directions on the Code Customization page (found under the Version tab): Build Time Features.

"},{"location":"operation/features/watch/#adding-a-watch-to-existing-loop","title":"Adding a Watch to Existing Loop","text":"

If you add an Apple Watch after building Loop using Xcode on a computer, you will need to pair your watch to your iPhone and then rebuild Loop to enable the Loop watch app to show up as an available watch app.

If you use the new, Loop 3 only, Build Loop using GitHub Actions process that enables building without needing a Mac, the watch app should work so long as you have the watch paired to your phone when you install from TestFlight.

"},{"location":"operation/features/watch/#watch-hardware-and-os-requirements","title":"Watch Hardware and OS Requirements","text":"

Loop 2.2.9 and FreeAPS is currently supported with all released versions of the Apple Watch and Apple watchOS 4.1 and newer.

Loop 3 requires newer versions of the watch and requires watchOS 8 as a minimum.

The compatibility list below is copied from Apple. Note that some version of iOS require specific versions of watchOS. That level of detail is not captured here. Please review LoopDocs: Wikipedia Chart for Apple Versions.

"},{"location":"operation/features/watch/#watchos-8-compatibility","title":"watchOS 8 Compatibility:","text":"

watchOS 8 requires iPhone 6s or later with iOS 15 or later and one of the following Apple Watch models:

  • Apple Watch Series 3.
  • Apple Watch Series 4.
  • Apple Watch Series 5.
  • Apple Watch SE.
  • Apple Watch Series 6.
  • Apple Watch Series 7.
  • Not all features are available on all devices.
"},{"location":"operation/features/watch/#watchos-9-compatibility","title":"watchOS 9 Compatibility:","text":"

watchOS 9 requires iPhone 8 or later with iOS 16 or later and one of the following Apple Watch models:

  • Apple Watch Series 5.
  • Apple Watch SE.
  • Apple Watch Series 6.
  • Apple Watch Series 7.
  • Apple Watch Series 8.
  • Apple Watch Ultra.
"},{"location":"operation/features/widget/","title":"iPhone Widget","text":""},{"location":"operation/features/widget/#loop-3","title":"Loop 3","text":"

Loop 3 uses the new-style widget is in process. There are a lot of updates with widgets. With the advent of iOS 16, you can add widgets that show up on the lock screen without need to swipe to view. There is work in progress on this - please be patient.

"},{"location":"operation/features/widget/#old-style-loop-widget","title":"Old-Style Loop Widget","text":"

Loop 2.2.x and FreeAPS both include an old-style widget.

With older versions of iOS, the widget is available in the Today view of your iPhone. Swipe right on your iPhone home screen and your widgets will be available. The Loop widget may be at the bottom of your widget list. Scroll down to the bottom of the screen and press the edit button. That opens an \"Add Widgets\" screen. If you hold and drag the three horizontal lines on the Loop widget row, you can drag it up to the order you'd like it to appear on your widget list.

With newer version of iOS, the old-style widgets cannot be moved to the top of the screen. The example graphic below shows the new-style Dexcom G6 widget above the old-style Loop 3 widget.

New to Loop or never added a widget before

  • There is a difference in behavior between \"new-style\" Widgets and \"old-style\" Widgets
    • New-Style Widgets: always appear at the top of your Today View, can be changed by long-pressing on one and then dragging around, or can be added with the + button in edit mode
    • Old-Style Widgets, like that available with Loop: use a different method to install
  • Make sure your phone is unlocked, then swipe from the Home Screen to get to Today View
    • You can't edit the screen if you start from a locked phone
  • Start the Edit mode (where all of the icons are shaking), either by long-pressing on one of the new-style widgets, or by scrolling all the way to the bottom of Today View and pressing Edit.
  • Scroll all the way to the bottom again to find and select the button labeled \"Customize\"
  • Now you can configure (add, remove, rearrange) the \"old-style\" widgets for your screen.
  • The Loop widget should appear in the list available there.

Experienced Looper who already had a widget should not need to modify anything to see it.

"},{"location":"operation/loop/close-loop/","title":"Closed Loop","text":""},{"location":"operation/loop/close-loop/#closed-loop","title":"Closed-Loop","text":"

After you learn what you need from open-loop, this page provides suggestions to smooth the transition to closed loop.

"},{"location":"operation/loop/close-loop/#timing","title":"Timing","text":"

Consider transitioning in steps. Some loopers start closed-loop when there are fewer distractions, possibly on weekends. It can be easier to transition at a time that does not involve food, possibly overnight.

"},{"location":"operation/loop/close-loop/#maximum-basal-rate","title":"Maximum Basal Rate","text":"

When starting closed-loop, it is important to be conservative. Start with the \"Temp Basal Only\" dosing strategy and limit the maximum basal rate. If your Meal Entries or Therapy Settings (basal rates, CR, ISF) are incorrect, this approach limits the risk of getting too much insulin. Typically, experienced loopers set their max closed-loop basal rate at no more than 3-4 times their average basal rate. Wait until you are comfortable with the slower corrections in \"Temp Basal Only\" before transitioning to \"Automatic Bolus\".

Temp Basal Only vs Automatic Bolus

Both Dosing Strategy methods update the prediction with each CGM or glucose reading, typically every 5 minutes, and use the updated prediction to generate a recommended bolus or recommended dosing restriction.

  • \"Temp Basal Only\" provides no more than 17% (per 5 minute interval) of that recommended bolus using temporary basal
  • \"Automatic Bolus\" mode provides 40% of that recommended bolus as an immediate bolus
  • When Loop recommends restricting insulin, both methods use temporary basals that are less than the scheduled basal, often commanding a temp basal of 0 U/hr
"},{"location":"operation/loop/close-loop/#glucose-correction-range","title":"Glucose Correction Range","text":"

If your basal, ISF, or carb ratios are not correct, Loop may give you more insulin than you need to reach the correction you selected. Setting the correction range slightly higher at first helps prevent unexpected low glucose as you adjust your settings.

"},{"location":"operation/loop/close-loop/#watch-the-iob","title":"Watch the IOB","text":"

Watch whether Loop accumulates positive or negative IOB while holding your glucose steady when no food is present. If you consistently have positive or negative IOB, review whether to adjust your basal rate or ISF.

Expert Tip

In the absence of food, glucose trends should flatten out when positive or negative IOB trends to zero.

  • If glucose drops below the correction range and continues to drop while IOB goes negative, basal rates may be too high
  • If glucose remains above the correction range while IOB remains positive, basal rates may be too low

The ISF is also important, but basal should be evaluated first.

"},{"location":"operation/loop/close-loop/#meals","title":"Meals","text":"

Start with meals that you know well. If Loop suggests less or more insulin than expected as a bolus before the meal - consider why this may be true.

  • If glucose is trending down, Loop may be trying to prevent a low glucose event
  • If glucose is trending up, Loop may be trying to add a correction to the meal dose
  • In any case:
    • You can adjust the absorption time and carb amount to see if that modifies the suggested bolus
    • You can override the Loop suggestion
    • Do not be surprised if Loop immediately suspends basal
    • Loop needs to see glucose start to rise before deciding you need more insulin after the initial meal bolus recommendation
    • Loop will not automatically provide more insulin until your glucose is above the lower range of the correction range (but will recommend a manual bolus)

This is definitely an area where YDMV (your diabetes may vary), so don't expect or accept that what works for others will work for you. Test, observe, and adjust as needed.

"},{"location":"operation/loop/close-loop/#automated-dosing","title":"Automated Dosing","text":"

Loop calculates a predicted glucose curve based on your programmed settings for carb ratio (CR) and insulin sensitivity factor (ISF), using your glucose, insulin and carb history.

Two scenarios are given below to help illustrate the closed-loop automatic actions of Loop. A more typical scenario is to enter carbs and then use Loop's recommendation for an appropriate bolus.

  1. Enter a bolus with no carb entry
  2. Enter a carb entry without a bolus
"},{"location":"operation/loop/close-loop/#bolus-with-no-carbs","title":"Bolus with No Carbs","text":"

If you enter a bolus without entering carbs, the prediction will be for your glucose to go low. (The Loop model calculates a negative number for recommended bolus.) For this case, Loop issues a Temp Basal to prevent the low, typically 0.0 U/hr but always less than your scheduled basal rate.

COB and IOB

  • COB is the carbohydrates (g) that Loop expects to be absorbed
  • IOB is the current active insulin (above or below the scheduled basal rate)
"},{"location":"operation/loop/close-loop/#carbs-with-no-bolus","title":"Carbs with No Bolus","text":"

If you enter carbs and select Save without bolusing, you have COB without associated IOB. In that case, Loop predicts your glucose will start rising and updates the recommended bolus, which includes consideration of your Glucose Safety Limit, Correction Range and Maximum Bolus . If that recommended bolus is positive, Loop might deliver some part of that bolus automatically - the exact percentage and timing of that delivery depends on your Dosing Strategy. At each loop cycle (new glucose reading), Loop updates the prediction and calculates a new recommended bolus. When you enter carbs without bolusing, Loop may start delivering some insulin, but if your glucose doesn't start rising as Loop expects, it revises the recommended bolus with each new glucose value.

"},{"location":"operation/loop/close-loop/#when-does-automatic-dosing-happen","title":"When does Automatic Dosing Happen","text":"

Automatic dosing only happens when Closed Loop is enabled in the settings screen.

The Loop app generates a glucose prediction over the next 6 hours (the duration of insulin action), which is why the predicted glucose plot is included on the bolus screen. The Loop app considers glucose prediction with respect to your scheduled Correction Range over the full DIA, weighting closer predictions more than later predictions, when calculating Recommended Bolus.

It is actually easier to answer when Loop will not automatically increase insulin delivery.

In the situations listed below, the prediction at the end of the DIA can be significantly higher than your Correction Range but no automatic increase in insulin delivery will occur:

  • If at any time in the next 3 hours, the Loop app predicts glucose below Glucose Safety Limit, Temp Basal is immediately set to 0.0 U/hr and recommended bolus is set 0 U
  • If the prediction dips below the low-end of your Correction Range, there is no automatic increase over scheduled basal
  • If the current glucose is less than the low-end of your Correction Range, there is no automatic increase over scheduled basal
  • If the current IOB is greater than or equal to two times the Maximum Bolus setting, there is no automatic increase over scheduled basal

Even in cases where Loop does not automatically increase insulin delivery, the recommended bolus might be positive, which you see if you tap on the bolus icon manually.

"},{"location":"operation/loop/looptips/","title":"Loop Tips","text":""},{"location":"operation/loop/looptips/#loop-tips","title":"Loop Tips","text":"

These docs are a great resource for the technical aspects of building your Loop app. However, they don't really cover in detail a lot of the frequently asked questions about USING Loop.

Things such as:

  • How to enter low treatments while using Loop?
  • What to discuss with your Endo?
  • What data reports might be useful?
  • How to deal with failed sites?
  • What about pizza boluses?
  • What do I do when I shower or swim?

All of those usability questions and more are addressed over in the companion site called LoopTips.

Please head over to Looptips in order to read some really helpful tips to make your Looping easier.

"},{"location":"operation/loop/open-loop/","title":"Open Loop","text":""},{"location":"operation/loop/open-loop/#open-loop-introduction","title":"Open Loop Introduction","text":"

Open Loop is the best place to start with Loop.

  • Become familiar with the Loop app by watching it operate with Closed Loop disabled.
  • Take it slow and safe to become a successful Looper.
Menus do not include all Manual Pump Features (Click to learn more)

The Loop app is built around the concept of Closed Loop performance.

If you use a Medtronic pump and want to use a feature not found in the Loop app, simply disable Closed Loop and control delivery with your Medtronic Controller.

If you use an Omnipod pump, keep reading:

There may be a feature, like extended bolus, that you used with an Omnipod Personal Device Manager (PDM) that is not in the Loop app.

Please refer to Extended Bolus.

Practice with Simulators (Click to learn more)

You can build the Loop app without connecting it to any hardware.

  • You can use your phone, a partner's phone or a simulated phone on the computer
  • You can practice with a simulated CGM and / or a simulated pump.
  • You can use Dexcom Share or Nightscout as a CGM to follow your own glucose.
  • You can \"dose\" the simulated pump and your real pump at the same time and watch the glucose predictions.
"},{"location":"operation/loop/open-loop/#glucose-prediction","title":"Glucose Prediction","text":"

Pay attention to the prediction in the Glucose Chart. Practice with the user interface while you manually control your insulin delivery. Compare the recommended insulin after entering carbs for a familiar meal. Be sure you understand the predictions and recommendations before you enable Closed Loop. You may need to adjust settings or learn more about how the app works. The Loop app tries to keep predicted glucose in the Correction Range and, more importantly, above your Glucose Safety Limit.

There's a lot to learn and understand. New loopers may need to adjust the following Therapy Settings, typically in this order:

  1. Basal Rates
  2. Insulin Sensitivity Factor (ISF)
  3. Carb Ratios (CR)

Using an algorithm that updates glucose predictions and adjusts insulin delivery every 5 minutes requires accurate settings. Entering carbs and absorption time is a new skill that takes time to master.

"},{"location":"operation/loop/open-loop/#eventual-glucose","title":"Eventual Glucose","text":"

Watch the eventual glucose, current glucose and prediction curve in the Glucose Chart to understand recommendations for insulin delivery adjustment. The Loop app is looking at current glucose, glucose momentum, carbs on board, insulin on board, and retrospective trends to predict an eventual glucose. Its current decisions are based on actual, predicted and eventual glucose. Predictions for the first three hours of insulin duration of activity are given more emphasis than later predictions when deciding how much insulin should be recommended or withheld from basal.

If there is a dip in the predicted glucose below the Glucose Safety Limit, the Loop app will not recommend insulin even if the eventual glucose is above your Correction Range.

  • In Closed Loop mode, the Loop app automatically decreases insulin delivery using a temp basal of 0 U/hr until the predicted glucose exceeds the Glucose Safety Limit
  • When you tap on the Bolus icon in the Toolbar, the Loop app recommends insulin delivery only after predicted glucose is above Glucose Safety Limit
  • In Closed Loop mode, the Loop app automatically increases insulin delivery only after predicted glucose is above the bottom of the Correction Range

If the Loop predictions don't match your experience, your settings may need to be adjusted.

If you want to issue a manual temp basal, this is done on the pump for Medtronic or using the Manual Temp Basal feature for Omnipod.

"},{"location":"operation/loop/open-loop/#testing","title":"Testing","text":"

Open Loop mode shows you glucose trends without the influence of temporary basal or automatic bolus. This is particularly helpful if you haven't used Medtronic sites/pumps or Omnipod before. You may find that your basal rates and carb ratios can change significantly coming from other brands of pumps or from multiple daily injections (MDI).

The suggestions below work for most people. You need to adjust for your own situation.

Take the time to establish a good basal profile while in Open Loop mode using the pump you plan to use for the Loop app. When using an algorithm, your basal rates needs to be neutral; in other words your glucose, in the absence of food and exercise, should be stable. (When you do basal testing, you should aim to stay at a glucose that is steady within 35 mg/dL (2 mmol/L).)

If you previously ran a high basal rate during the day to cover meals, you may need to adjust your CR (to a smaller value) after your basal rate is adjusted to be neutral.

Test your insulin sensitivity factor (ISF) during Open Loop after your basal rates are established. The Loop app uses your ISF every 5 minutes to update predictions, so it's worth testing before turning on automated insulin dosing with Closed Loop mode. You may need a different, probably higher value, than what you used as a correction factor with manual pumping or MDI.

The algorithm uses the ratio of ISF/CR as part of the prediction while meals are being absorbed. That ratio is approximately how much a single gram of carbohydrate raises your glucose. Experiment by taking a small fast-acting \"low treatment\" when stable with no other food or exercise.

Assume ISF is 75 mg/dL and CR is 15 g/U. When a 4 g glucose tablet is consumed, you expect to see a sharp rise in glucose by about 20 mg/dL over the next half hour to an hour. (Your ISF/CR ratio times the grams eaten should be within a factor of two of how much rise you see in glucose.)

"},{"location":"operation/loop/open-loop/#meal-entry","title":"Meal Entry","text":"

Loop recommends increased insulin dosing as soon as you save carbs.

Meal Entry is an important concept - there's a whole page devoted to it later in the docs - but here's a quick summary. You tap on the plate icon in the Toolbar before you meal to show the Add Carb Entry screen.

  • In the Add Carb Entry screen, you must enter Amount Consumed, defaults are ok for other rows
  • The meal entry is not saved when you tap continue - the Loop app takes you to the Meal Bolus screen
  • In the Meal Bolus screen, you can save the carbs and accept or override the recommended bolus
  • Review the recommended bolus for the meal entry
    • Does the recommendation make sense based on your prior experience
    • Pay attention to the glucose prediction chart embedded in the Meal Bolus tool
    • Practice modifying when the carbs are expected and how long they are expected to last
    • Practice modifying the bolus recommendation - note how the prediction changes
    • When you are confident, you can save the carbs and deliver the bolus
"},{"location":"operation/loop/open-loop/#carb-absorption","title":"Carb Absorption","text":"

Loop uses carb absorption as a component to every meal entry. Most people are successful with the default absorption time of 3 hours. Remember the Loop app updates the prediction every 5 minutes and will adjust if you get the amount or absorption time wrong, as long as you are close.

  • For low-glucose treatment, you can enter using the 30-minute (lollipop) icon
  • For high-fat meals, you can try the 5-hour (pizza) icon

The Active Carbohydrate chart displays how the app thinks your meal is being aborbed. This is affected by your basal rates, ISF and CR. If it looks wrong, examine your settings.

Depending on the type of food you eat, you may increase the carb entry to include some protein or fat.

"},{"location":"operation/loop/open-loop/#manual-or-correction-bolus","title":"Manual (or Correction) Bolus","text":"

At any time, you can enter a bolus using the Bolus (double orange triangles) icon in the Toolbar. The Loop app offers a recommendation if the glucose prediction supports one. Review the Eventual Glucose section above to understand when the app will recommend a bolus. The Loop recommendation can be modified by editing the Bolus amount.

If you tap on the Bolus button (on the Toolbar), does the app recommend more insulin?

  • If so, you can choose to accept if it looks reasonable to you
  • If not, look at the prediction plot to understand the decision

Ask if this is the same decision you would make. This effort will help smooth the transition to Closed Loop.

"},{"location":"operation/loop/open-loop/#troubleshooting","title":"Troubleshooting","text":"

If you use a RileyLink, determine how far the link can be from your phone and pump, and plan where to carry the link. DASH Omnipod users do not need the RileyLink but should determine how far their phone can be from the pod without communication problems.

Learn to troubleshoot Red Loops and the cause of potential loop issues. You'll be less frustrated starting on closed loop if you know how to address these issues.

Familiarize yourself with the Bolus Failure Notifications.

"},{"location":"operation/loop/open-loop/#caregiver-training","title":"Caregiver training","text":"

Caregivers for Loopers should learn how to use the Loop app. School staff or your child need to know how to handle a site change or CGM failure at school. Consider preparing an individualized quick info sheet for your child.

Learn to observe the Nightscout site while your child is with you and you can look at their phone. This will help you help your child if they have problems when they are not with you.

For more reading, there's a whole set of pages on using Nightscout with the Loop app and setting up a secure method for you to provide bolus or carb entries via remote commands.

"},{"location":"operation/loop/open-loop/#apple-health-in-open-loop","title":"Apple Health in Open Loop","text":"

If you are using the Apple Health app to examine insulin given while in Open Loop, basal delivery is not recorded in the Health app promptly. You can force an update from the Loop app to Health by suspending and then resuming the pump. If you do this, keep watching the app to make sure delivery did resume.

"},{"location":"operation/loop/open-loop/#extended-bolus","title":"Extended Bolus","text":"

A menu item to set an extended bolus is not a feature provided by the Loop app at this time. You can make your own extended bolus using the Manual Temp Basal feature with Omnipod.

During the time the Manual Temp Basal command is running, the Loop app will make no automated changes to dosing even if the Closed Loop slider is selected as enabled.

"},{"location":"operation/loop/open-loop/#extended-bolus-equations","title":"Extended Bolus Equations","text":"

This section was added at user request. Once you switch to Closed Loop mode, you should not need this. But before you are ready for that step, you may want to use a tested method for a known meal.

Consider a desired total bolus \\((BolusTotal)\\) given over an extended time with a prompt amount \\((PromptAmount)\\) now and the balance \\((Balance)\\) delivered over the next \\((H)\\) hours with a current scheduled basal rate \\((BR)\\).

First the equations to calculate the desired rate \\((MTB)\\) to enter into the Manual Temp Basal menu and then an example.

\\[ Balance = BolusTotal - PromptAmount \\] \\[ MTB = Balance / H + BR \\]
  1. Turn on a Manual Temp Basal to value of \\(MTB\\) units/hour for \\(H\\) hours
  2. Tap the bolus icon on the main toolbar and enter a bolus for \\(PromptAmount\\) units

The order is important. Sending the Manual Temp Basal request to the pod is a single command and then the Loop app is available for the next command to be entered. The Loop app (and pod) will not respond to any pod commands until the bolus finishes delivering; this takes about 40 seconds per unit requested.

"},{"location":"operation/loop/open-loop/#specific-example","title":"Specific Example","text":"

For this example:

  • \\(BolusTotal\\) is 3 U
  • \\(PromptAmount\\) is 1 U
  • Time in hours, \\(H\\), is 1.5
  • Scheduled basal rate, \\(BR\\), is 0.5 U/hr
\\[ Balance = 3 U - 1 U = 2 U \\] \\[ MTB = (2 / 1.5) U/hr + 0.5 U/hr = 1.55 U/hr \\]

You have your choice of rounding \\(MTB\\) up or down to the nearest \\(0.05 U/hr\\). For this example, the quantity of \\((2/1.5)=1.333\\) was rounded up to \\(1.35 U/hr\\).

Why isn't there a menu item? (Click to see more)

Each item provided by the Loop app needs a volunteer to decide it is important and develop a method to provide that item. If a volunteer steps up to do this work, there is a long process of discussion and code review before such a modification is considered for the development branch.

Most Loopers go to Closed Loop quickly and this feature is not an option at this time.

"},{"location":"operation/loop-settings/cgm/","title":"Loop 2 Add CGM","text":""},{"location":"operation/loop-settings/cgm/#add-cgm","title":"Add CGM","text":"

Now we need to add a CGM source so that Loop has glucose data. From the Loop settings screen, select Add CGM.

The standard selections are:

  • Dexcom G6 (use this for Dexcom ONE)
  • Dexcom G5
  • Dexcom G4
  • Dexcom Share

If you added a compatible Medtronic pump earlier in the setup process, then you will also see an option for the compatible Medtronic sensor that works with that same pump. If you are using a compatible MDT sensor, select that option and the CGM data will be uploaded to Loop when pump status is updated.

"},{"location":"operation/loop-settings/cgm/#about-dexcom-share-credentials","title":"About Dexcom Share credentials","text":"

You do NOT need your Share account info listed in Loop settings if you are using a G4, G5, or G6 system. The transmitter ID is sufficient. In fact, the recommendation is that you leave your Share account empty so that you don't accidentally become internet-dependent for CGM data when you forget to update your transmitter ID when you start a new transmitter. Just leave the Share credentials blank.

If you need to use Dexcom Share

If the dexcom is on another phone and you choose to use Share (not advised), here is some information.

For all selections, the Dexcom Share credentials (in other words, account login) is the same as what you used to log in to the active Dexcom app on your iPhone. Dexcom Share account is not always the same login info as your Dexcom Clarity account. For G4 users, the Share account is found in the account tab on the app. For G5/G6 users, unfortunately, there is no information in the app displaying what your account name is. The information is entered when you first log in to the app and then is never displayed again, nor visible under any information screens. If you have forgotten your G5/G6 account info, you can delete the Dexcom app and redownload it to try logging in again. This will not cause a restart of any sensor sessions in progress.

If you do not enter your Share credentials correctly, you will get an error when Loop tries to access your Share account to backfill CGM data. That error message will look like below. If you see that message, delete your Share account from Loop settings and try again...or just leave it out and depend on your transmitter ID.

"},{"location":"operation/loop-settings/cgm/#dexcom-g5-g6-one","title":"Dexcom G5, G6, ONE","text":"

The Dexcom G5 and G6 options only require the addition of the active transmitter ID, and the matching Dexcom app to be running on the Loop iPhone. Use the G6 options if you are using a Dexcom ONE CGM.

When you change transmitters, you will need to select the Delete CGM button at the very bottom of the CGM info page in Loop. Then you will select your Dexcom system again and add the new transmitter ID. You cannot just tap on your old transmitter ID to update it.

If you don't update your transmitter ID when you change active transmitters, your Loop will not get CGM data from the Dexcom app.

If you did add Share credential, Loop will get data from your Dexcom Share server and will not work without cell or wifi connection. When Loop is using data from Dexcom Share servers, a small cloud will appear above the glucose reading in Loop and should tip you off that maybe you forgot to update your transmitter ID.

"},{"location":"operation/loop-settings/cgm/#dexcom-g4","title":"Dexcom G4","text":"

Dexcom G4 users will need the Dexcom G4 Share2 app active on their iPhone and paired to their Dexcom G4 Share receiver.

"},{"location":"operation/loop-settings/cgm/#dexcom-share","title":"Dexcom Share","text":"

The Dexcom Share selection is primarily for people who wish to test Loop function without a local CGM source and who are not running the Dexcom app on their Loop iPhone. This selection will require login access to a Dexcom Share account with live data and active internet connection in order to work.

Dexcom Share is not available for Dexcom ONE CGM.

"},{"location":"operation/loop-settings/cgm/#libre-and-other-cgm","title":"Libre and Other CGM","text":"

Loop 2 does not natively support Libre CGM.

If you switch to Loop 3, there are additional CGM options:

  • If you choose to build Loop-dev, Libre support has been added.

  • If you can upload your CGM to Nightscout, Loop 3 offers the option to use Nightscout as a CGM source.

  • You can choose to download the Loop with patches option when building with the script.

    • As a prerequisite, you must interface your iPhone to the Libre
    • Please read Libre Support for Loop 3.2.x Code
"},{"location":"operation/loop-settings/cgm/#next-step-loop-2-configuration","title":"Next Step: Loop 2 Configuration","text":"

Now that you have added your CGM source, we need to complete the configuration and settings in your Loop. Please head over to the Loop 2 Configuration page for guidance with this important part of Loop's setup.

"},{"location":"operation/loop-settings/configurations/","title":"Loop 2 Configuration","text":""},{"location":"operation/loop-settings/configurations/#configuration","title":"Configuration","text":"

This page will cover two general parts of the Loop app settings for Loop 2.2.x versions. The sections documented are circled in red in the screenshot below. The headings will match the flow of the screen, top to bottom.

  • The first circled section covers closed/open loop status and how to issue a Loop Report.

  • The second circled section is the configuration section. This section contains a lot of really important settings that control how your Loop will calculate your predicted glucose curve. Given the importance of your predicted glucose curve to Loop's actions, please make sure you read over this page carefully to know how to navigate the selections and entries.

"},{"location":"operation/loop-settings/configurations/#closedopen-loop","title":"Closed/Open Loop","text":"

The user can select closed loop or open loop using this slider. When you first start Loop, we encourage you to leave this slider disabled and become familiar with the app using Open Loop mode.

As soon as Closed Loop is enabled, Loop will begin automatic adjustment of insulin dosing. Please ensure the settings you entered are appropriate for the Loop algorithm.

"},{"location":"operation/loop-settings/configurations/#open-loop-mode","title":"Open Loop Mode","text":"

When the Closed Loop switch is in the (Off) position, Loop WILL NOT modify insulin dosing automatically.

"},{"location":"operation/loop-settings/configurations/#closed-loop-mode","title":"Closed Loop Mode","text":"

When the Closed Loop switch is in the (On) position, Loop WILL automatically modify insulin dosing on the configured insulin pump. This is known as closed loop. Typically, Loop will show the recommended temp basal or automatic bolus just above the blood glucose graph prior to automatically enacting it. It may take a few seconds for Loop to connect to the pump to enact the modified dose.

"},{"location":"operation/loop-settings/configurations/#issue-report","title":"Issue Report","text":"

If you run into problems or errors with your Loop, a Loop Report, generated by tapping on the Issue Report row can be used to help identify where the problem is occurring. The Loop Report can be sent to yourself via text or email. You can then post it on Zulipchat to ask for help.

Frequently, if you seek help with a technical problem, a Loop Report will provide insight for the developers and troubleshooters. Please email yourself a Loop Report anytime you are questioning Loop actions or displays. Acquiring a screenshot of the phone is also useful. You can use the report and graphics later to ask for help or discard them if you figure it out on your own.

"},{"location":"operation/loop-settings/configurations/#select-glucose-units","title":"Select Glucose Units","text":"

Before you continue further, a word about glucose units

Entries into the configuration section will be available in mg/dL or mmol/L automatically, based upon how your blood glucose values are received. By default they are set to mg/dL, however once CGM values arrive in mmol/L these Loop settings can be entered in mmol/L. If you are planning to use mmol/L, be sure to wait to set your entries until after you have started to receive CGM values in Loop. If you do these in the wrong order, then your charts and entries may have incorrect units.

"},{"location":"operation/loop-settings/configurations/#correction-range","title":"Correction Range","text":"

The correction range is your blood glucose range that you would like Loop to correct to. Correction range is not necessarily the same target blood glucose range that you have discussed with your endocrinologist; generally the doctor's range may be much wider. For example, you may keep a correction target of 100-110 for Loop to aim to, but use a desired glucose target range of 80-180 when discussing things with your endo about \"time in range\".

Click the + in the upper right corner to add correction glucose range(s). You can have multiple ranges based on time of day, but the first setting of the day needs to begin at midnight.

Correction ranges can be a single number, such as 100-100 mg/dL, or a range such as 100-120 mg/dL. Generally speaking, if you choose to use a range, keeping the range between about 10-30 mg/dL between the lowest and highest value is a good starting place.

"},{"location":"operation/loop-settings/configurations/#pre-meal-range","title":"Pre-Meal Range","text":"

Below the Correction Range entry is a section called \"Overrides\" with a Pre-Meal setting. While active, the pre-meal targets will replace the usual correction range for Loop's temp basal recommendations. If a pre-meal range is not entered in this section, the icon will remain grey and unusable on the main screen's toolbar.

The pre-meal override target can be used as an easy way to get a small amount of insulin delivered before a meal in order to help control post-meal blood glucose spikes.

If your normal target is 100-110 mg/dL and pre-meal target is 80-80 mg/dL, for example, Loop will give you an extra push to get you to the lower target number before the meal. This early insulin brings you into the meal with a mini-prebolus. The pre-meal target, when activated by pressing on the icon, will stay active for one hour, until carbs are entered, or until it is manually cancelled...whichever comes first.

Loop will adjust any insulin bolus as needed based on the extra insulin provided during this pre-meal time.

"},{"location":"operation/loop-settings/configurations/#suspend-threshold","title":"Suspend Threshold","text":"

The suspend threshold must be set up for successful configuration of Loop. Your Loop will not turn green without setting this value. This value affects both bolus and basal recommendations by Loop.

"},{"location":"operation/loop-settings/configurations/#bolus","title":"Bolus","text":"
  • If you are trying to bolus a meal while any part of the predicted glucose curve is below this suspend threshold value, Loop will not recommend a bolus. Instead, you will need to wait until your prediction curve is above the suspend threshold value in order to bolus.
"},{"location":"operation/loop-settings/configurations/#basal","title":"Basal","text":"
  • If your current or any point on your predicted glucose curve is below the suspend threshold, Loop will always recommend a temporary basal rate of 0 U/hr.

Reasonable settings for suspend threshold will depend on user preference, but recommended not set lower than 65 mg/dL.

"},{"location":"operation/loop-settings/configurations/#basal-rates","title":"Basal Rates","text":"

Note: You cannot enter basal rates until you first add a pump in Loop settings. Your basal rates will be initially populated when you walk through the Add Pump part of the setup at the beginning of this setup guide.

Only one basal schedule may be set in each Loop app. The basal increments are available according to the increments of the particular pump/pod you are using. Not all pumps provide the same increments for basal deliveries. Basal schedule must start at midnight and cannot contain rates of 0 U/hr.

To edit a line in your basal schedule, tap the line and adjust the time and/or amount. To remove a line, select Edit in the top right and delete it. If tapping the line doesn't work, try closing and re-opening the app. When finished editing, click on the Save to Pump... or Sync With Pod button, depending on which pump you are using.

If you make any basal edits and use the Cancel button to go back to the menu without successfully saving/syncing to pump/pod, the changes you made will not be saved. Loop makes saving/syncing to pump a mandatory step to successfully editing basal rates. If you get an error message while trying to save/sync the edited basal rates, please retry until successful.

"},{"location":"operation/loop-settings/configurations/#delivery-limits","title":"Delivery Limits","text":"

The maximum basal rate and maximum bolus settings are collectively referred to as Delivery Limits. This section will have been initially populated when you finished the Add Pump part of the setup previously. For safety, similar to basal schedule, you must keep these values the same on both the Loop app and within the pump/pod settings. If you edit these settings in Loop app, always use the Save to Pump... or Sync With Pod button, depending on which pump you are using.

"},{"location":"operation/loop-settings/configurations/#maximum-basal-rate","title":"Maximum Basal Rate","text":"

Maximum basal rate will cap the maximum temporary basal rate that the Loop is allowed to enact to meet your correction range. Typically, Loop users set their maximum basal rate around 3-4 times their highest scheduled basal rate. When you are first beginning to use Loop, it is wise to start conservative (low) in setting your maximum basal rate. If your settings are incorrect in other areas (basal rates, insulin sensitivity, carb ratio, etc), you may need time to identify where settings need to be adjusted. This process is easier if Loop is given less latitude to set high basal rates. Gradually increase your maximum basal rate as your comfort and confidence in Loop increases. If you need help with your settings adjustment, head over to LoopTips for some initial settings help

"},{"location":"operation/loop-settings/configurations/#maximum-bolus","title":"Maximum Bolus","text":"

Enter your desired single bolus maximum here. For safety, don't set a maximum bolus limit any higher than your typical large meal bolus.

"},{"location":"operation/loop-settings/configurations/#insulin-model","title":"Insulin Model","text":"

There are four insulin models to choose from with Loop 2.x; Walsh, Rapid-Acting Adults, Rapid-Acting Children, and Fiasp. If you want to read the nitty-gritty discussion that went into the development of the Rapid-Acting and Fiasp curves (collectively called \"exponential insulin models\"), you can see that in GitHub here.

Loop 3 Insulin Type

Loop 3 drops the Walsh model and, by default, does not include the concept of child versus adult for \"rapid\" acting insulin, i.e., Humalog, Novalog and Apidra.

  • Insulin Type is selected when the user adds a pump
  • The user can choose to customize Loop 3 to Enable Child Model

We highly recommend selecting one of the exponential insulin models for Loop 2.2.x (in other words, not the Walsh model).

A common new Loop user error is to select Walsh model in order to easily shorten their insulin duration (DIA) to one like they used prior to Looping. This almost invariably leads to insulin stacking. If you would like to read more about why the duration of insulin action is important in Loop vs how you've traditionally used it, please click here to read a blog post about the subject. In summary, choosing Walsh curve just to shorten your DIA will lead to insulin stacking and less than desired bolusing recommendations.

You can click on each model and see what each model's insulin activity curve looks like, active one selected in blue.

The differences between the three exponential models (two Rapid-Acting and Fiasp) models has to do with the timing of the peak insulin activity timing. Not surprising, since Fiasp is marketed as the \"faster acting\" insulin. Currently all the exponential models are defaulted to an insulin duration of 6 hours, but the peak activity of the curves differs:

  • Rapid-acting adult curve peaks at 75 minutes
  • Rapid-acting child curve peaks at 65 minutes
  • Fiasp peaks curve peaks at 55 minutes
"},{"location":"operation/loop-settings/configurations/#dosing-strategy","title":"Dosing Strategy","text":"

This configuration setting gives you the ability to select the Dosing Strategy. (If you do not see this setting, then you are running Loop v2.2.4 or older.) If you tap on that Dosing Strategy, it reveals a selection screen, shown in the graphic below, with some explanation. Note that this Dosing Strategy feature was available for more than a year in the automatic-bolus branch. Users who have been using the automatic-bolus feature should update as soon as possible to get the other improvements recently added, Loop Releases.

The Automatic Bolus selection causes Loop to provide 40% of the recommended dose as a bolus at the beginning of each Loop cycle (when a CGM reading comes in). This is a faster method of getting the recommended insulin delivered. When Loop delivers extra insulin, the scheduled basal rate continues unchanged.

Both Temp Basal Only and Automatic Bolus strategies restrict basal rates to reduce the amount of insulin delivered when appropriate.

"},{"location":"operation/loop-settings/configurations/#temp-basal-only","title":"Temp Basal Only","text":"
  1. When your glucose is at or above target, Loop determines the amount of Recommended Bolus based upon your settings. Subject to your Delivery Limits, Loop will deliver the Recommended Bolus over 30 minutes using positive temp basals (i.e., increase over your scheduled basal rate) to increase your IOB. This decision is re-evaluated during every Loop interval.
  2. When your glucose is below target, negative temp basals (i.e., reduction of your scheduled basal rate) are used to reduce your IOB. This decision is also re-evaluated during every Loop interval.

You can manually bolus at any time by pressing the Bolus icon in the center of Loop\u2019s Main Screen.

"},{"location":"operation/loop-settings/configurations/#automatic-bolus","title":"Automatic Bolus","text":"

When you are first starting Loop, we encourage you to leave automatic boluses disabled until you are sure your settings are dialed in. To enable automatic boluses, click on Settings \u2013 Dosing Strategy \u2013 Automatic Bolus. This Automatic Bolus checkbox turns-off positive temporary basal so that:

  1. When your glucose is at or above target, you receive 40% of the Recommended Bolus at every Loop interval.
  2. When your glucose is below target, negative temp basals (i.e., reduction of your scheduled basal rate) are used to reduce your IOB. This decision is re-evaluated during every Loop interval (same as with the Temp Basal Only dosing strategy).

As with all Loop versions, you can manually bolus at any time by pressing the Bolus icon in the center of Loop's Main Screen. Any bolus recommendation that you see when you press the Bolus icon will be 100% of the Recommended Bolus.

"},{"location":"operation/loop-settings/configurations/#carb-ratios","title":"Carb Ratios","text":"

Click the + in the upper right to add carb ratios for various times of day. Loop works best if you have tested and optimized your carb ratio settings for accuracy.

Beware of other apps writing carbs to Health app

If you are using a third-party app (such as Spike or MyFitness) that can write carbohydrates to the phone's Health app, you will need to double-check permissions to make sure Loop doesn't read those carb entries. Confirm Loop permissions in Health to only write and not read carbs. See see Loop Permissions.

"},{"location":"operation/loop-settings/configurations/#insulin-sensitivities","title":"Insulin Sensitivities","text":"

Insulin Sensitivity Factor (ISF) is the same term as Correction Factor used in some clinics and endocrinology offices. ISF represents the drop in blood glucose levels expected from one unit of insulin. Click the + in the upper right to add insulin sensitivities for various times of day. 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 glucose for new Loop users. You will 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.

"},{"location":"operation/loop-settings/configurations/#loop-2-services-optional","title":"Loop 2 Services (Optional)","text":"

You are not required to use services, although many Loopers use Nightscout. If you do not yet have Nightscout configured and want to add it later, just return to this page when you are ready. This can be added at any time. The same is true for the other services. For more details, click on Loop 2 Services.

"},{"location":"operation/loop-settings/configurations/#next-step-loop-2-displays","title":"Next Step: Loop 2 Displays","text":"

Proceed to the Loop 2 Displays page. Understanding the Loop displays can be a valuable tool to understanding your Loop's actions, and also for troubleshooting, if you are having issues.

"},{"location":"operation/loop-settings/displays/","title":"Loop 2 Displays","text":""},{"location":"operation/loop-settings/displays/#loop-displays","title":"Loop Displays","text":"

This section of the docs describes the Loop displays available and what information they offer. Information about Loop's actions (or inactions) can often be found simply by looking at the visuals presented in the app. (Page last updated for Loop v2.2.4.) For Loop 3, refer to Loop 3 Displays.

"},{"location":"operation/loop-settings/displays/#status-screen","title":"Status Screen","text":"

The Status Screen is the main root navigation screen in Loop. It is broken up into 3 main display areas; Heads Up Display (HUD), Charts, and Toolbar. The HUD is the top area of the screen. This shows the status of the last time loop ran, current BG Reading, current temp basal, and current pump information. The next area is the charting area. This includes, glucose trend and prediction, Active Insulin, Insulin Delivery, and Carbohydrates. The final display area is the toolbar which has buttons for Carbs, Pre-Meal, Bolus, Overrides, and Settings.

"},{"location":"operation/loop-settings/displays/#heads-up-display","title":"Heads Up Display","text":"

The Heads Up Display (HUD) is a very useful quick reference guide to your Loop's status. Every 5 minutes, Loop updates CGM and pump/pod data. Loop timestamps the HUD data with the last data point that came in. If a timestamp goes older than 5 minutes old, that is a valuable indicator to where your Loop is failing to get the needed information. The HUD's first three icons, from left to right, are the same no matter whether you are using a Medtronic pump or Omnipod; status of the last time loop ran, current BG Reading, and current relative temp basal. The last two icons will change depending on what type of pump you are using.

Medtronic users: The last two icons are the most recent (1) pump/reservoir status and (2) pump percentage battery remaining. Details below

Omnipod users: The last two icons are the most recent (1) pod status and (2) hours of pod use. Details below

"},{"location":"operation/loop-settings/displays/#loop-status","title":"Loop Status","text":"

The Loop Status is the colored circle in the upper left corner of the main Loop display. There are four colors that are typically displayed.

A grey circle indicates the Loop is warming up and hasn\u2019t yet completed its initial loop. When the Loop is first activated, it may take about 15-20 minutes to complete the first Loop, and the grey circle will be displayed. It needs CGM data to be gathered, so be patient. When it finally completes its first loop, the circle will turn green. If you can't get your grey loop to turn green, please see the Yellow and Red Loop troubleshooting page for tips. A green circle indicates the Loop has been successfully completed within the last 5 minutes. The time since the loop last completed will be displayed under the circle. A yellow circle indicates the Loop has not completed in the last 5-15 minutes. It is not unusual to have a few instances of yellow circles throughout a day of looping. They can be caused by temporarily getting too far away from RileyLink or iPhone (more than about 3-10 feet depending on conditions), CGM failing to read or being in ???, radio frequency \u201cnoise\u201d interference, and such. Generally, most yellow circles will self-resolve without needing any special troubleshooting. A red circle indicates the Loop has not completed in over 15 minutes. This is not a typical state, and you should troubleshoot why Loop is not completing. Please review the Yellow and Red Loop troubleshooting page for tips on how to get your green Loop back. Clicking on the red circle will also pop-up the last error message to help guide your troubleshooting. When the circle is notched and not complete, that means the Loop is operating in \u201copen-loop\u201d mode. When the \u201cclosed-loop\u201d setting is turned on, the loop status will show a completed circle.

Fun Fact

The loop status icon will pulse slightly when Loop is communicating with the pump. The pulsing will stop when the communication has completed (green loop) or given up (yellow or red loop).

"},{"location":"operation/loop-settings/displays/#glucose","title":"Glucose","text":"The current BG reading from the CGM will display, including trending arrow and time the reading was taken. If the BG is being read straight from the G5/G6 transmitter or G4 receiver, no special symbols will appear. If the BG is being read from the Dexcom Share Servers, a small cloud icon will be in the corner of the BG reading. Internet access is required to run in this mode. When you first start Loop, there may be a small yellow alert next to the BG. This should go away within a short period of time (around 5 minutes or less). If the yellow alert remains, something may be wrong with fetching BG data. You can try restarting the Loop app (double tap home button, up-swipe on the app to close it) to see if BG data will resume. Special note for Dexcom G5/G6 users>, a yellow alert will appear when calibration is needed. The alert will clear once the calibration is given, but typically Loop will work IF the yellow alert is only for a needed G5/G6 calibration."},{"location":"operation/loop-settings/displays/#temp-basal","title":"Temp Basal","text":"The temp basal will display the enacted temp basal change relative to the scheduled basal. So if the scheduled basal was 1.0 units per hour and Loop has set a temp basal of 0.2 units per hour, the temp basal icon will display -0.8 U, as shown in the graphic to the left."},{"location":"operation/loop-settings/displays/#reservoir-medtronic-users","title":"Reservoir (Medtronic Users)","text":"The reservoir icon will remain grey and plain until insulin volume decreases. At 25% reservoir volume remaining, the reservoir icon will turn yellow. At 10% reservoir volume remaining, the reservoir icon will turn red. The remaining units will be displayed when it gets to these lower thresholds."},{"location":"operation/loop-settings/displays/#battery-medtronic-users","title":"Battery (Medtronic Users)","text":"For x54 pumps, the battery icon will show 100/75/50/25% increments just as the pump does. As the battery level decreases, the icon will turn from grey to yellow to red. For x22, x23 pumps, the battery icon will read discrete % values. The warning colors/levels on Loop's battery indicator work in conjunction with the type of battery selected. If you change battery types, please make sure to update your battery selection in the Loop app settings. The pump's on-screen battery indicator is not a good indicator of remaining battery life for the purposes of looping. Loop's pump communications will fail from low battery levels sooner than the insulin delivery will fail. The Loop's battery level warnings are designed to give you approximately 8 hours of notice before the pump battery will need changing."},{"location":"operation/loop-settings/displays/#reservoir-omnipod-users","title":"Reservoir (Omnipod Users)","text":"The pod icon will remain grey and plain until insulin volume decreases. At 50 units or less insulin remaining, the reservoir icon will turn yellow. At 20 units or less remaining, the reservoir icon will turn red. The remaining units will be displayed when it gets to these lower thresholds. When the reading is 0 units, there may be up to 4 units of insulin available but don't count on it. If the pod senses insulin can no longer be delivered, the pod will have a sustained audible alarm (the scream). Tapping Replace Pod in Loop->Pod->Settings should silence the alarm."},{"location":"operation/loop-settings/displays/#pod-age-omnipod-users","title":"Pod Age (Omnipod Users)","text":"The pod's age, typically a 3-day lifespan, is represented by three equal segments of the pod age icon. As the pod ages, the segments are converted to a darker grey color. At 54 hours old, the pod age icon will turn yellow. At 72 hours old, the pod age icon will turn red, the pod will begin the periodic warning beep, and the pod age icon will show a \"replace pod\" message in the HUD. When you reach 80 hours of pod use, the pod will have a sustained audible alarm (the scream) and stops all insulin delivery. Tapping Replace Pod in Loop->Pod->Settings should silence the alarm."},{"location":"operation/loop-settings/displays/#charts","title":"Charts","text":"

There are several charts that help you navigate your Loop actions. Clicking on each of the charts will also open up additional information.

"},{"location":"operation/loop-settings/displays/#glucose-chart","title":"Glucose Chart","text":"

The glucose chart displays BG values in your preferred units. (If not, quit and restart Loop app on your phone.) The vertical scale of the chart is calculated on the fly by Loop to be as useful as possible while including the highest and lowest readings in the chart.

The horizontal axis is set to go forward from the current time until your DIA (insulin duration) forward (so you can see what Loop thinks BG will be eventually). It then goes back in time as far as it can, based upon the width in pixels of your screen. Note, if you turn your device to landscape mode you will have more screen real estate and thus will be able to see further back in time.

The BG correction range is shown as a blue bar on the glucose chart. Single-value range BG range (such as 100-100 mg/dL), will have a narrower blue range. When a temporary override range is enabled, a darker blue bar where the overrides are set will be displayed, as well as the normal correction range in lighter blue.

If you have a crazy negative prediction - it is likely that you set an override with a tiny Overall Insulin Needs setting. Don't do that again. Best approach: Do not panic - this is a prediction only; not reality. Open the loop until the prediction settles down. In future, do not choose a tiny Overall Insulin Needs setting to force less insulin, simply increase the correction range in your override - Loop will reduce your basal rate at the next cycle (within 5 minutes).

The eventual BG displayed on the right side of the chart does NOT take into account a recently enacted temp basal. In other words, if you are above BG range and Loop just enacted a high temp basal to help, the eventual BG does not reflect the expected lowering of BGs that would result from that recently enacted temp basal. Loop waits until the insulin has actually been delivered before it \"uses\" the insulin in its calculations for BG impacts. If you suspended your pump or had a \"no delivery\" alarm shortly after the temp basal was started, you would want that accurately reflected in the insulin on board and associated eventual BG.

If you tap on the Glucose Chart itself, it will open the Predicted Glucose chart described below.

"},{"location":"operation/loop-settings/displays/#predicted-glucose-chart","title":"Predicted Glucose Chart","text":"

The predicted glucose view is a great way to gain insight into the various components\u2019 importance in Loop\u2019s prediction of eventual BG.

The graph at the top of this view will match your Glucose Chart. Below this chart you will see a very detailed explanation of all of the variables that Loop takes into account in predicting your future BG value. Each of those effects (including Carbohydrates, Insulin, Glucose Momentum and Retrospective Correction) includes details of the calculation used. You can tap on any of the entries to turn them off and on for visualization. The resulting changes can be viewed by the changes in the dashed lines.

Note - these elements are not turned on and off in the Loop predictions. They just modify the graph so you can view the relative effects.

"},{"location":"operation/loop-settings/displays/#active-insulin-chart","title":"Active Insulin Chart","text":"

The Active Insulin chart displays the total insulin contribution from both temp basals and boluses. Active IOB can be either positive and negative IOB. Negative IOB results from the suspension of normally scheduled basals. The active insulin displayed in the upper right corner of the chart does NOT include insulin contributions from a recently enacted temp basal or bolus until the (for Medtronic) pump\u2019s reservoir volume is read and confirms a drop in reservoir volume (confirming the insulin has actually been delivered). The opposite is true for Omnipods. If a message is sent from Loop, it assumes the pod got the message and enacted it - even if the acknowledgement is not received. Later, when communication is restored, if a command was not enacted by the pod, the Event History is updated.

Medtronic Only: So long as you have Event History as the Preferred Data Source in Loop settings, primed insulin deliveries (e.g., cannula fills or manual primes) will not be counted towards IOB.

"},{"location":"operation/loop-settings/displays/#insulin-delivery-chart","title":"Insulin Delivery Chart","text":"

The Insulin Delivery chart displays a history of the temp basals enacted by Loop. The display is relative to the scheduled basal rates entered in the Loop settings. So, a rate displayed in this chart as +0 units would indicate no temp basal was set, and Loop defaulted to the scheduled basal rate. Individual boluses are indicated by an orange triangle on the chart (shown in the graphic above, near the left-most time). The total insulin delivered since midnight, including all basals and boluses AND (Medtronic Only) priming insulin, is given in the upper right corner of the graph.

Please be patient for a bolus delivery to appear. There is a lag time from when you press the \u201cdeliver\u201d bolus button to when the orange triangle is drawn sometimes. The insulin has to be delivered and then the (Medtronic Only) pump reservoir needs to be read to confirm delivery, before the triangle will appear and IOB will be added. Occasionally, the bolus may be temporarily rendered (drawn) as a very high temp basal rate vs. a (triangle) discrete bolus event. This does NOT mean that the Loop actually enacted a high temp basal rate...only that the bolus is being drawn on the chart in the equivalent of a high temp basal rate.

"},{"location":"operation/loop-settings/displays/#reservoir-and-event-history","title":"Reservoir and Event History","text":"

Clicking on either the Active Insulin or Insulin Delivery charts will open your Insulin Delivery history. The top of the screen will display the current IOB and the total insulin delivered for the day since midnight (or since the time the loop became active if you started Loop after midnight). There are two viewing options; Reservoir or Event History.

  • Reservoir: Omnipod users should not worry about the reservoir display. Pods do not report or track insulin remaining until their reservoirs get below 50 units remaining. If your pod has more insulin than that - you'll see the reservoir history from the previous pod - ignore that. Medtronic users will have reservoir history displayed in 5-minute increments, unless Loop has been having communication issues.

  • Event History: Event history is a detailed accounting of all pump/pod actions. Both Medtronic and Omnipod users will have a detailed record of event history. If you tap on an event, you get more detail. Turn your phone to landscape to improve readability.

"},{"location":"operation/loop-settings/displays/#active-carbohydrates-chart","title":"Active Carbohydrates Chart","text":"

The Carbohydrate chart displays the carbs used by Loop to predict BG changes. The active COB is displayed in the upper right corner of the chart. Clicking on the chart will open the Carb Entries history and you can edit/delete any previous entries through that screen. Please read the Carb Entry page for more information about editing carb entries.

For more information about the Insulin Counteraction Effects information found in the Carb History, please see here.

"},{"location":"operation/loop-settings/displays/#tool-bar","title":"Tool Bar","text":"

The toolbar is where your inputs to the Loop behavior take place. The individual components of the toolbar are, left to right:

  • Carb entry tool- click on this tool to enter carbs into the Loop app. Loop will not read carb entries from a Medtronic pump or Nightscout, so you must use the carb entry tool in Loop app in order to have carbs accounted for by the Loop. Detailed info regarding how to enter, save, and edit carb entries can be found in the Carb Entry page.

  • Pre-meal range - click this tool to set the Pre-Meal temporary override range. (If you have not configured a pre-meal range under Loop Settings, this icon will be inactive - some people prefer this to avoid accidently tapping it.) This range will remain in effect (1) for 60 minutes, (2) until a carb entry is saved, or (3) until the range is toggled off manually or by tapping on the override icon, whichever comes first. The background coloring of the Pre-Meal range will turn green when active and there will be a dark blue line on the BG chart indicating where the override range is enabled.

  • Bolus tool - click on this tool to bring up the bolus tool. Normally, this screen will automatically open on its own and function as a bolus wizard when a meal is saved on the carb entry tool screen. But you can click on this icon anytime to manually bolus. During rapidly rising BGs, where Loop doesn't have an adequate temp basal rate to cover the pace at which BGs are rising, you may try clicking on the bolus tool to see if Loop is recommending a correction bolus to help control the BG spike. Or if you want to trade bolus now for basal later (super bolus), you can enter a bolus greater than Loop recommends - Loop will set zero Temp Basal next cycle. For more information about the Bolus tool features and use, see the Bolus page.

  • Overrides - click this tool to set an Override.

  • Loop Settings - click on this tool to make changes to any of your Loop settings.

"},{"location":"operation/loop-settings/displays/#next-step-pump-settings","title":"Next Step: Pump Settings","text":"

The pump attached to Loop has a screen to display status and command options. For Loop 2, these are documented in Loop 2 Pump Settings.

"},{"location":"operation/loop-settings/mdt-pump/","title":"Loop 2 Add Medtronic","text":""},{"location":"operation/loop-settings/mdt-pump/#medtronic-pump-users","title":"Medtronic Pump Users","text":"

Your Loop app will have a lot of blank spots until you input some basic settings. The beginning step is to add a pump to your Loop app. If you are using an Medtronic pump, you can follow along for the rest of this page. If you are using an Omnipod pump, please head over to Loop 2 Add Omnipod instead.

"},{"location":"operation/loop-settings/mdt-pump/#prepare-medtronic-pump","title":"Prepare Medtronic Pump","text":"

Before you begin the rest of the setup process, there are several steps on your Medtronic pump that you will need to complete prior to moving on with Loop setup. DO NOT SKIP THESE STEPS OR YOUR LOOP WILL NOT WORK.

  1. Turn off Patterns under the basal menu settings. This will force Loop to use your \"Standard\" basal rate schedule.
  2. Make sure your standard basal rate schedule is up-to-date and accurate. Loop will automatically import your pump's existing standard basal rate schedule when you add your pump in the subsequent parts of this page. If you change basal rates later...make sure to make those changes in the Loop app and use Loop to save the changes back to the pump. If you make changes directly in the pump, Loop will not automatically know about those changes and you will cause a mismatch.
  3. Set your pump's Temp Basal Type to Insulin Rate (U/hr). Do NOT use percentage. Your Loop will not run unless your temp basal type is set to units/hour.
  4. Make sure your maximum basal rate and maximum bolus (those are particular settings in the pump) are reasonably set for your particular needs. For new Loop users, a maximum basal rate equal to approximately 2-4 times your highest scheduled basal rate is a good starting point as you learn Loop and dial in your other settings. You can adjust as your comfort and use of Loop develop.
  5. Set Remote Devices to ON and enter any random ID (010101 will work - avoid using all zeros). This setting is found in the pump's Utilities menu (for x23 continue to Connect Devices, Remotes) and turn ON the Remote Options.
  6. Cancel any currently running extended or dual wave boluses. Loop cannot loop with those running.
  7. Make sure the other settings in your pump, such as bolus wizard settings, are up-to-date so that if you stop using Loop, those settings will be accurate for non-Loop traditional pump use.
"},{"location":"operation/loop-settings/mdt-pump/#select-pump-type","title":"Select Pump Type","text":"

Let\u2019s start by clicking on the Loop Settings button in the tool bar at the bottom of your Loop app. It looks like a little sprocket. On the settings screen that opens, click on Add Pump and select the Medtronic pump option that appears.

"},{"location":"operation/loop-settings/mdt-pump/#connect-pump-to-loop","title":"Connect Pump to Loop","text":"

New RileyLink compatible devices won't have a name listed next to their slider at first. The name will only be displayed after connecting the device to Loop for the first time. So, if all you see in the device list is a little toggle and no \"RileyLink\" name...go ahead and switch that toggle. The default device name will appear after that toggle is green.

You can later personalize the default device name once it is connected to Loop.

Continue with these steps to connect your Medtronic pump to Loop.

  1. Make sure your RileyLink is turned on and nearby, then you will see a RileyLink listed in this area of the settings. Actually, you will see a list of any RileyLinks that are in the nearby area. Slide on the toggle for just one RileyLink.
  2. Add your pump's region, color, and serial number.
    • Note that some Canadian pumps use CM instead of CA for the region code. Just select CA in the dropdown menu.
  3. Click the Continue button to finish the addition of your pump.

For x23 and x54 Medtronic pump users only

For x23 and x54 Medtronic pump users, there is a packet of information special to those pumps called MySentry messages. If you have never setup this part of the pump previously, you may see a screen, called \"Pump Broadcasts\", at this point in the setup process.Follow the directions on the screen. They will require you to take some manual steps on your pump to \"pair\" it with your Loop app.Basically, you will need to go to your pump's main menu, scroll down to Utilities, then Connect Devices, then Other Devices, turn that setting On, and then select Find Device. Once you do that, click on the Continue button in Loop app and the pairing will take place. This will allow those MySentry packets of information to flow to Loop app.This step does not apply for x22 or x15 pump users, since those pumps do not have MySentry capabilities.

Now that your pump is paired with Loop, you will be finishing these steps:

  1. Change your pump time using the Loop app (and read all the info on that screen)
  2. Import your pump's basal rate schedule, maximum basal rate, and maximum bolus (maximums are collectively called \"delivery limits\" in Loop)
  3. Select your pump's battery type (lithium or alkaline)
  4. Leave the Preferred Data Source on Event History

Event History must be selected for Nightscout to display temp basals, carbs, and boluses from Loop. Event History must also be selected in order for prime events to be detected and NOT contribute to IOB during site changes. Please just leave the Preferred Data Source on Event History.

"},{"location":"operation/loop-settings/mdt-pump/#change-time-zone","title":"Change Time Zone","text":"

Loop automatically prompts you to set your pump time using the Loop app as part of initial Loop setup. There will be other times you need to change the time - traveling or daylight savings time start and end. It is important that you use Loop to change time on your pump; do not adjust time on your pump directly once it is attached to Loop.

If you are traveling through time zones, Loop continues to work - just be aware that your basal rate and other configuration settings will be in the original time zone. To change time zones, please follow the Change Time Zone instructions.

Always use the Loop -> Pump -> Change Time command to change pump time. Do not use the Medtronic pump menus to change your pump's time when Looping.

"},{"location":"operation/loop-settings/mdt-pump/#next-step-add-cgm","title":"Next Step: Add CGM","text":"

Congrats! You've added your Medtronic pump to your Loop app. Now, click on the settings button in the upper left corner to take you back to Loop's settings menu. Your next step is to Loop 2 Add CGM to your Loop app. After all, without CGM data, your Loop won't loop.

"},{"location":"operation/loop-settings/omnipod-pump/","title":"Loop 2 Add Omnipod","text":""},{"location":"operation/loop-settings/omnipod-pump/#omnipod-users","title":"Omnipod Users","text":"

Your Loop app will have a lot of blank spots until you input some basic settings. The beginning step is to add a pump to your Loop app. If you are using an Omnipod pump, you can follow along for the rest of this page. If you are using a Medtronic pump, please head over to Loop 2 Add Medtronic Pump page instead.

"},{"location":"operation/loop-settings/omnipod-pump/#select-pump-type","title":"Select Pump Type","text":"

Let\u2019s start by clicking on the Loop Settings button in the toolbar at the bottom of your Loop app. It looks like a little gear. On the settings screen that opens, click on Add Pump and select the Omnipod option.

"},{"location":"operation/loop-settings/omnipod-pump/#select-rileylink","title":"Select RileyLink","text":"

New RileyLink compatible devices won't have a name listed next to their slider at first. The name will only be displayed after connecting the device to Loop for the first time. So, if all you see in the device list is a little toggle and no \"RileyLink\" name...go ahead and switch that toggle. The default device name will appear after that toggle is green.

You can later personalize the default device name once it is connected to Loop.

A list of all RileyLink compatible devices in the nearby area will display in the RileyLink Setup screen. Select your RileyLink by sliding the toggle to display green and then press the blue Continue button at the bottom of the screen. If your RileyLink does not appear, make sure it is charged and turned on: slide the recessed switch toward the case's keyring.

"},{"location":"operation/loop-settings/omnipod-pump/#delivery-limits-and-basals","title":"Delivery Limits and Basals","text":"

The next screen will offer two areas where you will need to enter information:

  • Delivery Limits: Tapping on Delivery Limits presents a screen where you enter your Maximum Basal Rate and your Maximum Bolus.

    • Your Maximum Basal Rate limits how aggressive your Loop app can be in setting temporary basal rates to treat high blood glucose.
    • The recommended value for new users is about 3 times their highest scheduled basal rate.
    • Your Maximum Bolus entry limits the size of a single bolus.
    • The recommended value for new users is the largest bolus typically used for meals.

  • Basal Rates: Enter your scheduled basal rates, beginning at midnight. Consistent with Omnipod use, the scheduled basal rates have a maximum of 24 entries, no 0 u/hr entries are allowed, and the rate increments are 0.05 u/hr.

    • Start by tapping the + at the top right of the Basal Rates screen to enter the first value.
    • Tap + to add rows as needed.
    • When you are done, hit the Back button at the upper left.
    • Note - once a pod is paired to the Loop app, you will press Sync to Pod instead of Back to save your basal rates - you only see Back when no pod is paired.
    • To delete a basal rate or rearrange the order, first tap Edit on upper right and then use standard Apple gestures (for your phone iOS) to delete or move rows.
    • You will not be able to move or delete the row for midnight.
    • You will not be able to add another row if the last row is for 11:30 pm

When you finish entering these values, press the blue Continue button on the bottom of the Pod Settings screen to continue with the next steps of Pod setup.

"},{"location":"operation/loop-settings/omnipod-pump/#pair-pod","title":"Pair Pod","text":"

Max Fill is 200 Units

When you fill the Pod do not exceed 200 units.

If you overfill the pods, you may get a pod fault right after priming.

Pod Filling and Insertion

The Pod filling and insertion instructions are the same with the Loop app as they are for the PDM. These videos: Filling a Pod with Insulin and Inserting the Cannula, may be useful. You will use your phone and RileyLink compatible device instead of the PDM. Be sure to keep the phone and RileyLink close during pairing and insertion because the Pod uses a low-power mode during these activities.

  1. Fill the Pod with insulin until it beeps (minimum fill is 80 units)
  2. Place the Pod about 6 inches from the RileyLink compatible device with the phone within a few feet
  3. Click the Pair button
  4. Loop checks on the radio signal strength (RSSI) reported by the pod when it starts to pair and if it is not within the optimum range, it will ask you to move the RileyLink closer or further away and try again.
  5. Wait while the progress bar for priming completes
  6. Press the Continue button when the blue checkmark confirms priming is complete

"},{"location":"operation/loop-settings/omnipod-pump/#insert-cannula","title":"Insert Cannula","text":"
  1. Prepare your insertion site
  2. Remove the Pod's needle cap and adhesive backing
  3. If the cannula is safely tucked away, apply the Pod to your desired infusion site. If cannula is sticking out, press cancel in the upper right corner of the screen and try a new Pod. (Report this issue to Insulet; it is a Pod problem.)
  4. Press the Insert Cannula button.
  5. Listen to the clicks filling the cannula, wait for insertion and the progress bar to complete. The number of clicks to insertion is not consistent. The cannula will deploy before the progress bar is completed.
  6. Confirm cannula has deployed: you should feel it and there is a pink slide that can be seen on the outside of the pod as shown in this video: Inserting the Cannula.
  7. Proceed to the Expiration Reminder screen to accept or modify the default reminder.
"},{"location":"operation/loop-settings/omnipod-pump/#expiration-reminder","title":"Expiration Reminder","text":"

Finish the setup using the default expiration reminder time (2 hours before a full 3-days of usage). You can modify that expiration reminder at any time, see Expiration Reminder. The notification will come from Loop; your Pod will not beep at this time. Setup is complete and your Pod is ready for use when you press the Continue button.

Range

Now that the priming and insertion steps are complete, the Pod is in normal power mode, so the range between the Pod and RileyLink compatible device is increased.

"},{"location":"operation/loop-settings/omnipod-pump/#pod-settings","title":"Pod Settings","text":"

After the Pod setup is complete, you will be on the Pod Settings screen. The information on this screen is described in Omnipod Pump Commands.

"},{"location":"operation/loop-settings/omnipod-pump/#next-step-add-cgm","title":"Next Step: Add CGM","text":"

Congrats! You've added your Pod to your Loop app. Now, click on the Done button in the upper right corner of your Pump Settings screen to take you back to Loop Settings. Your next step is to Loop 2 Add CGM to your Loop app. After all, without CGM data, your Loop app won't loop.

"},{"location":"operation/loop-settings/pump-commands/","title":"Loop 2 Pump Settings","text":""},{"location":"operation/loop-settings/pump-commands/#pump-settings","title":"Pump Settings","text":"

To bring up the Pod/Pump Settings display, tap on the reservoir icon in the Heads Up Display or the image of the pump in the Loop settings screen.

Omnipod Eros vs DASH

With the addition of DASH pods with Loop 3, you will notice all reference to Eros pods continue to say Omnipod in both the documentation and the code.

Documentation and screens in the app indicate DASH explicitly.

"},{"location":"operation/loop-settings/pump-commands/#change-time-zone","title":"Change Time Zone","text":"

The schedules for the basal rates, correction ranges, insulin sensitivity factors and carb ratios stay at the pump time even if the user and their phone change time zones or when daylight savings time occurs. To bring the pump into the same time zone as the phone, use this command in Loop. (Medtronic users - do NOT adjust time on your pump - always go through Loop.)

Select the Pod/Pump Settings display, scroll down to the Change Time Zone line, example shown in the graphic below. You can leave the time zone offset unchanged or touch it to change to the current time zone. Note that the 24 hour configuration pattern for basal rates, insulin sensitivity factor, carb ratio and correction range are aligned with the time zone shown on this line.

Once the Change Time Zone command is tapped, Loop no longer shifts the 24 hour configuration pattern to the old time zone. Some behavior depends on whether the pump is an Omnipod or Medtronic.

"},{"location":"operation/loop-settings/pump-commands/#omnipod-commands","title":"Omnipod Commands","text":"

To bring up the Pod Settings display, tap on the Pod Age icon on the Heads Up Display or the image of the Omnipod in the Loop settings display to reach the Pod Settings display.

This screen provides important information about your Pod and allows you to issue some commands to the Pod through Loop. There were some recent modifications made to the layout and underlying information for some of the rows.

  • Enable/Disable Confirmation Beeps: moved up to the Configuration section; beeps for all manual pod operations; uses a more efficient implementation

  • Suspend/Resume: Pod will beep every 5 minutes when suspended; the beeps can be silenced by tapping on the Alarms line

"},{"location":"operation/loop-settings/pump-commands/#pod-information","title":"Pod Information","text":"

The first section has the (72 hour) Pod expiration date/time and how long the Pod has been active. These are determined when the Pod is activated by injecting insulin into the reservoir and uses pod active time.

"},{"location":"operation/loop-settings/pump-commands/#bolus-delivery","title":"Bolus Delivery","text":"

This line reports the % progress of any ongoing bolus. This line reports None unless a bolus is actively being delivered when you enter Pod Settings. This line may not update until you tap on the refresh symbol to the right of the Pod image, or exit and re-enter the Pod Settings screen.

"},{"location":"operation/loop-settings/pump-commands/#basal-delivery","title":"Basal Delivery","text":"

This line reports

  • schedule for scheduled basals
  • U/hour for a 30 minute Temporary Basal
  • suspended if the Pod is suspended

"},{"location":"operation/loop-settings/pump-commands/#alarms","title":"Alarms","text":"

This line displays Alerts or Alarms; tapping on it, or on the accompanying banner displayed in the HUD, acknowledges the alert

  • If your Pod is beeping an alert, this line will display information about the alert. Tapping on the alert clears or \"snoozes\" the alert status.
  • If your Pod is screaming, it's time to change it. Tapping on this line stimulates an immediate reading of the actual error (normally this happens at the next CGM reading).
  • There was overwhelming preference during initial testing to minimize the \"beeping\" of Pods. You can turn on additional beeps by enabling Confirmation Beeps. These are the Loop Notifications and Pod beeps you should expect with the default (confirmation beeps disabled) setting:
    • Expiration Reminder - Loop notification only, no Pod beeps
    • 72 Hours Expiration - Loop notification and Pod beeps (Pod beeps continue once per hour until alert is acknowledged)
    • 79 Hour Alert - Loop notification and Pod beeps (Pod beeps continue every 15 minutes until alert is acknowledged)
    • Pod Suspended (v2.2.5 or later): Pod beeps once per 5 minute unless this alarm is cleared

"},{"location":"operation/loop-settings/pump-commands/#reservoir","title":"Reservoir","text":"

Pods do not report the volume of insulin remaining in the reservoir until there are less than 50 units remaining. So, typically you will see \"50+ U\" in this line for quite a while with a new Pod.

"},{"location":"operation/loop-settings/pump-commands/#insulin-delivered","title":"Insulin Delivered","text":"

This line is the basal and bolus insulin delivered by the Pod since the cannula was inserted. It is obtained by taking the reported Pod insulin delivery and subtracting the amount used to prime the Pod and fill the cannula upon insertion (about 3\u00a0U).

"},{"location":"operation/loop-settings/pump-commands/#pod-commands","title":"Pod Commands","text":"

This section contains commands the typical user will use.

"},{"location":"operation/loop-settings/pump-commands/#suspend-delivery","title":"Suspend Delivery","text":"

This command will suspend all insulin delivery; basals, temp basals, and boluses in progress. When you press suspend delivery, all insulin delivery stops indefinitely and the display changes to say Resume Delivery. (If the display does not update, tap the refresh screen icon at the top of the screen to the right of the Pod image.)

A banner notice will appear on the Loop's main screen when phone is in portrait mode when insulin delivery is suspended. Unless you are running v2.2.4 or earlier, a pod beep is initiated with a frequency of every 5 minutes. This can be silenced by acknowledging the alarm.

You will need to press Tap to Resume in the banner or the Resume Delivery button in the Pod Settings to resume your scheduled basal rate and let Loop get back to action. If a bolus delivery was interrupted by the Suspend Pod command, it will not be resumed.

When you resume delivery, the 24 hour Pod basal rate schedule is sent to the Pod. Be sure the Phone, RileyLink and Pod stay close until the message exchange is complete.

"},{"location":"operation/loop-settings/pump-commands/#enable-confirmation-beeps","title":"Enable Confirmation Beeps","text":"

This turns confirmation beeps on for the Pod. The Pod beeps when you enable this, but is silent when you disable it.

  • Bolus Acknowledgement - the Pod beeps when it has received and accepted the bolus command from Loop (manual or automatic) and then beeps again when the bolus is completed.
  • Other - all the manual commands you can issue to the Pod will have an associated confirmation beep when the message is received by the pod, such as updating the basal rate, requesting Pod status, canceling a bolus, suspending or resuming delivery.
"},{"location":"operation/loop-settings/pump-commands/#expiration-reminder","title":"Expiration Reminder","text":"

With the Expiration Reminder you can set a convenient time to get a notification to replace your Pod. Loop sets the default to 70 hours, i.e., two hours before the full 3 days that Insulet guarantees. The allowed range of values is between 1 hour and 24 hours prior to the Pod expiration at 72 hours of Pod life. If you select a date/time outside this range, Loop will modify your selection to the closest allowed value.

As with the PDM, Loop allows the Pod to continue operating after expiration until it reaches the maximum allowed 80 hours of life, at which time, the Pod shuts down and alarms. Loop detects this message the next time it tries to communicate with the Pod. In the event your Pod runs out of insulin before that time, then you will get a \"Pod empty\" notification.

The glitch in setting the Expiration Reminder in v2.2.4 is now fixed.

Loop v2.2.4 has a \"glitch\" in setting the Expiration Reminder. Tap on the line (can't change time), scroll the entire display up or down until the line no longer is visible and then scroll it back. The Expiration Reminder display should now look like the graphic below. The expiration reminder time can now be selected.

"},{"location":"operation/loop-settings/pump-commands/#change-time-zone_1","title":"Change Time Zone","text":"

Use the Change Time Zone command to align your configuration settings with the current time zone. Note that this updates your basal schedule on your Pod. If you start a new Pod session without modifying the time zone here, the original time zone will be used for the new Pod. Please wait until you see Succeeded appear on the page to ensure the command has successfully been received by the Pod.

Make sure the phone, RileyLink compatible device and Pod are kept in close proximity until this command has completed. The time zone is updated by Loop issuing the 24-hour basal rate schedule to the Pod based on the current time.

"},{"location":"operation/loop-settings/pump-commands/#replace-pod","title":"Replace Pod","text":"

This command deactivates a Pod prior to replacing it. Once you tap Replace Pod, another screen appears for you to confirm that you mean it.

"},{"location":"operation/loop-settings/pump-commands/#devices","title":"Devices","text":"

This allows access to the RileyLink screen for each connected RileyLink compatible device.

"},{"location":"operation/loop-settings/pump-commands/#pod-diagnostics","title":"Pod Diagnostics","text":"

This section is labeled Diagnostics, but many Pod users make use of this section.

"},{"location":"operation/loop-settings/pump-commands/#read-pod-status","title":"Read Pod Status","text":"

This command requests the status of the Pod and reports some of the returned information.

  • The line labeled Pulses reports the total number of pulses of insulin delivered by that Pod since activation (adding insulin to the reservoir). To convert this to units of insulin, multiply by 0.05 units/pulse. If you compare this report (for your Pod) to the Insulin Delivered line in Pod settings, for your Pod at the same time, the difference is the insulin used to prime the Pod and fill the cannula at insertion.

  • The line label RSSI reports the Received Signal Strength Indicator (RSSI) between the RileyLink compatible device and the Pod. The RSSI is a positive number with a larger number indicating a stronger signal strength detected by the Pod.

"},{"location":"operation/loop-settings/pump-commands/#play-test-beeps","title":"Play Test Beeps","text":"

This command requests the Pod emit a beep pattern. If you hear it, you know the commands are getting to the Pod. A message appears on your screen to indicate Loop got or did not get an acknowledgment from the Pod.

"},{"location":"operation/loop-settings/pump-commands/#read-pulse-log","title":"Read Pulse Log","text":"

This command reads the pulse log (diagnostic), displays it on the screen and saves the result in the log file. It takes some time, so keep your gear close until command completes. This can be extracted by sending the pulse log to yourself using the send-to icon at the top right of the screen. It is also included in the Issue Report. If you are having communication issues, you can provide this report to an expert who may be able to provide assistance. Post for help in either zulipchat or a Facebook group to request assistance and you'll get information about how to get that log file submitted.

"},{"location":"operation/loop-settings/pump-commands/#test-command","title":"Test Command","text":"

This verifies communication with the Pod. Loop reports success or failure. Use Get Pod Status if you want to see the some of the information returned from the Pod.

"},{"location":"operation/loop-settings/pump-commands/#pod-details","title":"Pod Details","text":"

This section provides some Pod identifying information. The Lot number and TID number are the tiny number stamped on the Pod that Insulet might ask you to report if you happen to call in this Pod for an appropriate failure.

"},{"location":"operation/loop-settings/pump-commands/#medtronic-commands","title":"Medtronic Commands","text":"

Medtronic commands are found in the Pump Settings screen shown in the graphic below. The top section is configured at the time the pump is connected to Loop and can only be modified by deleting the pump and adding a pump. This screen is the same as for earlier versions with the addition of the Use MySentry row.

"},{"location":"operation/loop-settings/pump-commands/#suspend-delivery_1","title":"Suspend Delivery","text":"

This command will suspend all insulin delivery; basals, temp basals, and boluses in progress. When you press suspend delivery, all insulin delivery stops indefinitely and the display changes to say Resume Delivery.

A banner notice will appear on the Loop's main screen when phone is in portrait mode when insulin delivery is suspended.

You will need to press Tap to Resume in the banner or the Resume Delivery button in Pump Settings to resume your scheduled basal rate and let Loop get back to action. If a bolus delivery was interrupted by the Suspend Pod command, it will not be resumed.

"},{"location":"operation/loop-settings/pump-commands/#change-time-zone_2","title":"Change Time Zone","text":"

During normal operation, Loop automatically keeps phone time and pump time aligned. In the case of time-zone or daylight savings time changes, Loop allows the differences to persist until the user chooses to Change Time Zone and accounts for time zones when performing insulin delivery accounting.

"},{"location":"operation/loop-settings/pump-commands/#pump-battery-type","title":"Pump Battery Type","text":"

The type of battery used in the Medtronic pump affects how Loop interprets the battery level for the pump.

"},{"location":"operation/loop-settings/pump-commands/#preferred-data-source","title":"Preferred Data Source","text":"

Leave the Preferred Data Source set to on Event History for proper functioning of Loop.

Event History must be selected for Nightscout to display temp basals, carbs, and boluses from Loop. Event History must also be selected in order for prime events to be detected and NOT contribute to IOB during site changes. Please just leave the Preferred Data Source on Event History.

"},{"location":"operation/loop-settings/pump-commands/#use-mysentry","title":"Use MySentry","text":"

This is a new option. If you don't see this row, consider updating your Loop app. Using the MySentry feature on some Medtronic pumps when using an OrangeLink causes the batteries to die quickly. This option allows you to turn off MySentry within the Loop app.

"},{"location":"operation/loop-settings/pump-commands/#devices_1","title":"Devices","text":"

This allows access to the RileyLink screen for each connected RileyLink compatible device.

"},{"location":"operation/loop-settings/rileylink/","title":"RileyLink Display","text":""},{"location":"operation/loop-settings/rileylink/#rileylink","title":"RileyLink","text":"

The RileyLink (or compatible device) screen is accessed by clicking on the image of your connected pump in Loop settings or the pump icon in the Heads Up Display to bring up the associated pump screen. From that screen, scroll down to the section labeled DEVICES to view the list of connected RileyLink compatible device(s) and tap on the name with a green slider that you want to display. An example is shown in the graphic below.

"},{"location":"operation/loop-settings/rileylink/#signal-loss","title":"Signal Loss","text":"

If there is a problem communicating with that RileyLink compatible device, tapping on the line will show out-of-date or missing information. Go to Troubleshoot: Red Loop: Reset Loop-to-Pump Communications for suggestions.

With Loop 3

  • The Pump Devices display will show the signal loss icon instead of reporting dB as shown in the graphic below.
  • If the problem persists, you'll start to see some Error Messages as well.

"},{"location":"operation/loop-settings/rileylink/#rileylink-status-and-commands","title":"RileyLink Status and Commands","text":"

Tapping on a name with a green slider takes you to the RileyLink Status and Commands screen for that device.

The name at the top center is whatever you named your RileyLink compatible device. The RileyLink screen is the same regardless of the pump you are using.

  • The three graphics below match the display for Loop 3.
  • For Loop 2.2.x - the displays are almost identical when the patch mentioned below the graphic is applied.
  • The firmware displayed is specific to each device.

Patch Required for Loop 2.2.x

Some devices have features not available with other devices. With Loop 2.2.6 some features were added to the OrangeLink, but there is a mismatch of reported hardware for some versions of OrangeLink firmware which prevents the Find Device row from showing up for OL Pro. The EmaLink extra features did not make it into the Loop v2.2.6 release.

  • With Loop 2.2.x, to see the displays shown in the graphics below, please follow instructions in the EmaLink and OrangeLink Feature and Patch sections.
"},{"location":"operation/loop-settings/rileylink/#device","title":"Device","text":"

The lines under the Device section provide information on the device. The two most important lines are the Connection Status and Signal Strength.

  • The Connections Status should say connected if the device is connected to the iPhone's Bluetooth. If the status says connecting or disconnected then you should toggle the iPhone's BT and/or power cycle the device to help reconnect.

  • The Signal Strength is the strength of the Bluetooth signal between the iPhone and the device. It is not the signal strength of the radio communications with the pump/pod.

  • The phone to device Signal Strenth is reported as a negative number so a -50\u00a0dB signal is stronger than -80\u00a0dB. As you move the device and iPhone closer/farther apart, you will be able to see the signal strength change. In a pinch, this can be used to help locate a lost device in the house or at the park after dark.

"},{"location":"operation/loop-settings/rileylink/#personalize-device","title":"Personalize Device","text":"

As soon as you connect the RileyLink compatible device initially - it is strongly encouraged that you rename it from the default name for that device, e.g., RileyLink or OrangeLink or EmaLink.

Once you display the RileyLink Status and Commands screen:

  • Tap on the Name line
  • Enter your desired name
  • Wait a few seconds before doing anything
    • The new name needs to be transferred and saved in the device
    • If you return to the Pump screen too soon, it might not happen - just repeat the process
    • The device must be connected and on to change its name
"},{"location":"operation/loop-settings/services-v2/","title":"Loop 2 Services","text":""},{"location":"operation/loop-settings/services-v2/#loop-services","title":"Loop Services","text":"

Near the bottom of your Loop settings screen is a section called \"Services\".

Sevices are Optional

  • Loop will work whether you use these or not.
  • Nightscout is highly recommended by experienced Loopers but can be added later - you don't need it to get started.

  • For Loop 2.2.x, the services listed in the graphic below can be added by clicking on the Tap to set arrow.

  • Click for Loop 3 Services

"},{"location":"operation/loop-settings/services-v2/#nightscout","title":"Nightscout","text":"

There is a whole section in LoopDocs about Nightscout. Please follow this link to the Using Nightscout with Loop section of LoopDocs. That also has the links you might need to the official Nightscout Documentation (different website).

If you have an existing Nightscout site, it's still a good idea to review that section, but here's a quick summary of how to add your Site URL and API_SECRET to have your Loop data transmitted to your Nightscout site. If you can\u2019t remember your API_SECRET, it can be found under Settings, Reveal Config Vars for Heroku sites (or Application Settings, Connection Strings for Azure sites).

The two most common errors in filling out this section are:

  1. Failure to use https:// in the site URL. If you use http:// (see how that doesn't have the \"s\" at the end?), you will get an error message about an App Transport Security policy.
  2. Having a trailing slash on the end of the URL (or an embedded space). If you copy and paste from a web browser, make sure to delete the trailing slash on the URL entry.

More Tips about Nightscout

  • One family had an app configured to block some websites for their child's phone and accidentally blocked their Nightscout URL - took them a while to figure out that mistake.
"},{"location":"operation/loop-settings/services-v2/#loggly","title":"Loggly","text":"

Loggly is a free logging service. If you sign up for an account, you'll need to go under Source Setup and then Customer Tokens. Copy and paste your customer token into your Loop App settings for Loggly.

"},{"location":"operation/loop-settings/services-v2/#amplitude","title":"Amplitude","text":"

Amplitude is a remote event monitoring service and can be used to quickly identify errors and events with Loop. Amplitude stores the events and allows you to view those events as points in time. To retrieve the details of the events you will need to look at corresponding mLab data entries to get a complete picture of the issues. If you sign up for a free account with Amplitude, you will be given an API Key that you can enter here to have Loop integration setup.

"},{"location":"operation/loop-settings/services-v2/#next-step-loop-displays","title":"Next Step: Loop Displays","text":"

Great job, almost finished! Now that you have completed your services, let's move onto understanding your Loop Displays.

  • Loop 2.2.x - click on this link for Displays

  • Loop 3 - click on this link for Displays.

Loop displays is a valuable tool for understanding your Loop and a great page to review when troubleshooting.

"},{"location":"troubleshooting/loop-crashing/","title":"Loop App Crashes","text":""},{"location":"troubleshooting/loop-crashing/#loop-crashes-upon-opening","title":"Loop Crashes Upon Opening","text":"

If your Loop app crashes immediately upon opening, you have a problem that needs to be fixed. What do I mean by \"crashes\"? Your Loop app immediately turns to a white (light mode) or black (dark mode) screen and then shuts itself down, landing you back at your iPhone's main screen. No amount of tapping will let you keep your Loop app open.

The most likely reason is Your Loop App Expired. But there can be other reasons.

  • If you just updated your phone from iOS 16 to iOS 17 (or a similar major phone update), Apple spends a lot of time indexing your Apple Health data
    • Many people report 5 to 30 minutes during which they cannot open the Loop app but they also cannot open Apple Health
      • Wait until you can open Apple Health and then try to open the Loop app again
  • If you still can't stop the crashes, see Other Reasons and be sure to save the crash log
"},{"location":"troubleshooting/loop-crashing/#your-loop-app-expired","title":"Your Loop App Expired","text":"

Your Loop app has an expiration date. The expiration date will depend on the build method and may also depend on the type of developer account that signed the app.

  • If you build with Browser Build, your app will expire after 3 months
  • If you build with a Mac using a paid account, your app will expire after 12 months
  • If you build with a Mac using a free account, your app will expire after 7 days
"},{"location":"troubleshooting/loop-crashing/#browser-build","title":"Browser Build","text":"

With the current version, 3.2.3, you unfortunately do not get prior warning that the app is about to expire, although you can look in the TestFlight app and it will tell you. An in-app warning will be added to the next release.

Please follow these steps to ensure you can build the app again. How to Update or Rebuild

"},{"location":"troubleshooting/loop-crashing/#mac-using-a-paid-account-1-year","title":"Mac using a Paid account (1 year)","text":"

When your app expires after a year, you need to follow the steps on the Build Updating page. Your phone will probably have a new iOS that may require an updated version of Xcode that may require an updated Mac operating system. All this is explained in the link above. Give yourself time before expiration to prepare yourself.

To make it easy to build when you have to, practice building every 3 to 6 months. This makes the process much lower stress. Also, each time you build, when you follow the link above, you give yourself another full year before rebuilding is required. Please review the Updating FAQS.

"},{"location":"troubleshooting/loop-crashing/#mac-using-personal-team-7-day","title":"Mac using Personal Team (7 day)","text":"

When your app expires, you simply need to open Xcode, reopen the project: File->Open Recent, plug your phone back into the computer and select it in Xcode and press the play button on your project again. This will rebuild. If you want to change to a paid signing team before rebuilding, please make sure to double-check which signing team is selected before building again.

"},{"location":"troubleshooting/loop-crashing/#switching-from-free-to-paid","title":"Switching From Free to Paid","text":"

If you started with a free account and switched to a paid account:

Many people accidentally build with their old free account

  • How can you tell which you're signing with?
  • The free signing team has the (Personal Team) listed after your name in the signing team

Remember that switching from free to paid changes the developer name incorporated into your Loop App

  • A separate Loop app is created - see Switching from Free to Paid Membership for more details
  • Did you select the new app and enter all your settings into it and then delete the 7-day app?
  • The new app issue only happens if you change developer name
  • As long as you stick with the same developer ID, updated Loop apps are built over existing apps and all your settings should be maintained
"},{"location":"troubleshooting/loop-crashing/#other-reasons","title":"Other reasons","text":"

If you experience a crash for any other reason, please gather all the information you can about what was happening before the crash and report it to your favorite Loop Social Media help site - you will need to get some personalized help. Please - choose one site for your post and wait for someone to get back to you. While you are waiting, search on any of the sites and, if on Facebook, read all the announcements.

"},{"location":"troubleshooting/loop-crashing/#save-and-submit-your-crash-logs","title":"Save and Submit your Crash Logs","text":"

If you have continuous crashes, please save the crash logs so the developers can look at it. If you can, log into Zulipchat and post it directly.

  • The crash logs can be found under Settings --> Privacy & Security --> Analytics & Improvements --> Analytics Data
  • Scroll to find the file Loop_DateTime.ips for crash reports
"},{"location":"troubleshooting/omnipod-faults/","title":"Omnipod Faults","text":""},{"location":"troubleshooting/omnipod-faults/#screamers","title":"Screamers","text":"

Pod faults are typically noticed by hearing a high-pitched continuous tone coming from the pod.

Loop will pick up the fault the next time it exchanges messages with the pod:

  • every 3 minutes for DASH
  • every 5 minutes for Eros

Once Loop detects the fault, you will get a Critical Pod Error modal message on the screen that you must acknowlege along with a Pod Error indicator shown in the HUD:

Normal High-Pitched Tone

There are 2 cases in which you hear the high-pitched continuous tone that are not Faults.

  1. Modal Alert says Empty Reservoir, Pod icon displays No Insulin
  2. Modal Alert says Pod Expired, Pod icon displays Pod Expired
"},{"location":"troubleshooting/omnipod-faults/#stop-that-noise","title":"Stop that Noise","text":"

The first action people want to take is to make that noise stop.

  • Tap on the Pod icon and then the Replace Pod row and deactivate the pod
    • The Replace Pod row is highlighted in red in the graphic below
    • Once the pod has been dealt with and you have a new one in place, it's time to get the details for the Pod Fault
"},{"location":"troubleshooting/omnipod-faults/#capture-the-fault","title":"Capture the Fault","text":"
  • Tap on the Pod icon and scroll all the way down and tap on the Previous Pod Information row, highlighted in dashed-blue in the graphic below
    • If there was a Fault, the information is found at the bottom of the screen
    • For any pod, the information about that pod is always available
"},{"location":"troubleshooting/omnipod-faults/#report-the-fault","title":"Report the Fault","text":"

Faults should be reported to Insulet. They may not give you a replacement, but it is important they be informed so they can determine if certain lots are having more failures than others. This helps them improve the quality of the pods.

  • Take a screen shot of the Fault Information
  • Insulet needs the following:
    • The Lot number (Eros found on the screen, DASH is different)
      • The DASH lot number needed by Insulet is the one found on both the box the pod came from and the paper cover from the pod tray
      • The electronic lot number reported by DASH pods to Loop is not helpful to Insulet
    • The Sequence number (also on the pod in tiny print)
    • The Active time (how long you wore the pod)
    • The Ref code - for the example above, the Ref code is: 19-00805-00551-064
    • They will also ask where on your body the pod was placed

Extra Information

The extra information, e.g., Fault Event Code 0x40: Encoder count too high, is only useful for the curious or the developers. Do not report that to Insulet.

The 0x40 is the hex version of the -064 decimal value found at the end of the Ref code.

"},{"location":"troubleshooting/omnipod-faults/#report-049-0x31-to-developers-not-insulet","title":"Report 049 (0x31) to Developers, Not Insulet","text":"

The sole exception to reporting to Insulet is if you get a fault ending in 049 in the Ref code or with the notation Fault Event Code 0x31: Incorrect pod state for command. That particular fault is only seen if there is a mistake in Loop. This happened rarely in earlier versions but should be fixed by the time version 3.4.0 is released. If you do get an 0x31 (049) fault - report that to the Loop developers and include a Loop Report (Loop, Settings, Support, Issue Report).

"},{"location":"troubleshooting/omnipod-faults/#known-pod-fault-codes","title":"Known Pod Fault Codes","text":"

The currently known pod faults are listed here on the openomni wiki page: Pod Fault codes

"},{"location":"troubleshooting/omnipod-faults/#ways-to-reduce-likelihood-of-a-fault","title":"Ways to Reduce Likelihood of a Fault","text":"

The Loop app will put a higher battery load on a pod than the PDM due to its regular and repeated communications. A pod with lower battery level appears to be more likely to fault for conditions like static electricity and occlusions/pump issues the Loop app is not directly causing, like decimal fault codes 052, 061, 064 and 066. Pods always perform safety checks and if a potential problem is found, the pod will end itself by screaming and halt all insulin delivery.

DASH pods have additional Fault Codes associated with the pod Bluetooth communications. The 0xCB, -203 decimal, seems to be pretty common. These should be reported to Insulet for their records.

None of the ways listed here are guaranteed to prevent a screaming pod, but they could be worth considering.

  • Keep the Loop app up to date; newer versions might include improvements to reduce pod battery load
  • Maintain a wider correction range (10 to 20 mg/dL; 0.5 to 1.1 mmol/L) instead of a single number
  • Loop Version 3, for Eros pods when used with a RileyLink Device that has a lot of communication errors, will send many repeated messages trying to resolve uncertain communications
    • Make sure your RileyLink Device is working well
    • Use a 433 Mhz RileyLink for Eros Pods and ensure the antenna is not loose or pinched
"},{"location":"troubleshooting/omnipod-faults/#replacement-pod-situations","title":"Replacement Pod Situations","text":"

Help Insulet Improve their Quality Control

Insulet is aware that pods are used by the DIY community. You can be honest about your use and might receive replacement pods. If your pod fails early, it is worth informing Insulet for their troubleshooting records even if you do not get a replacement.

You can always call Insulet tech support if a pod has a clear failure on the pod, such as:

  • A cannula was sticking out when the end cap was removed.
  • Visual inspection of the pod's cannula window indicating the cannula insertion was not successful.
  • Leaking or kinked cannula was causing insulin delivery issues.
  • The adhesive was not working properly when trying to place it on your body.
  • The pod begins to scream during filling, pairing, priming or insertion

If the pod fails during use with Loop, a replacement might still be possible. The software which communicates with the pod isn't developed or supported by Insulet. Generally speaking, asking for replacement for failed pods on the third day of pod life is a bit of a reach for the DIY community. We acknowledge that Looping may be a contributor in certain faults, especially by the third day.

"},{"location":"troubleshooting/overview/","title":"Troubleshooting Overview","text":"

After you have been using Loop for a while, there's a potential that you will run across a behavior or issue that you wonder if it is normal or intended. When that happens, there are a few things that we'd recommend doing to resolve the issue.

"},{"location":"troubleshooting/overview/#use-automatic-time-on-loop-phone","title":"Use Automatic Time on Loop Phone","text":"

If you have modified the Loop time (not changed time zone, but turned off automatic time and manually changed the time), please read: Loop Phone Must be on Automatic Time.

"},{"location":"troubleshooting/overview/#gather-information","title":"Gather information","text":""},{"location":"troubleshooting/overview/#screenshots","title":"Screenshots","text":"

Take a screenshot of your Loop main display screen, or other screens such as the display when you touch a red loop icon that may help you or troubleshooters better understand your issue. A lot of times a picture is worth a thousand words. Being able to see recent Loop basal adjustments, predicted BG curve and carb entries really help fill in the full story of the current Loop status. If you didn't manage to get a screenshot when the issue was happening, you can also go to Nightscout and scroll back over the previous 48 hours to obtain much of the same information. Try to capture a Nightscout screen from the time period in question.

"},{"location":"troubleshooting/overview/#check-the-docs","title":"Check the Docs","text":"

Loop docs are updated regularly. If you built your Loop app awhile ago, chances are good that more information has been updated and changed since you last read them. Please use the search tool - if there's an error message - search for it. Scan the topics in the Troubleshoot tab of LoopDocs and look for a page that may be applicable. The FAQs pages are definitely worth reviewing too.

"},{"location":"troubleshooting/overview/#issue-report","title":"Issue Report","text":"

Use the Issue Report Loop 3 / Loop 2 command under Loop Settings to generate a Loop Report. This has a lot of detailed information that may help you or a mentor understand your problem.

The Loop Report (a text file) contains important information about actions and status that can be very useful for troubleshooters...particularly with unexplained behaviors. The upper right corner of the Loop Report includes a button so that you can email the Loop Report to yourself (or others).

"},{"location":"troubleshooting/overview/#check-resources","title":"Check Resources","text":""},{"location":"troubleshooting/overview/#github-issues","title":"GitHub Issues","text":"

Check the current list of GitHub Loop Issues for known issues. Many times other users have noticed the same issue previously and opened an Issue so that more information can be added to help develop a solution. If you see the same issue has already been reported, please add it to the open issue instead of creating a new one.

There is a nice search feature on GitHub issues - type a keyword into the box next to Filters: where it says \"is:issue is:open\" in the graphic and the display will show just those open issues that contain the keyword in the title.

"},{"location":"troubleshooting/overview/#zulipchat-and-facebook","title":"Zulipchat and Facebook","text":"

Search in Zulipchat, Looped Facebook Group or LoopandLearn Facebook Group. Quite possibly someone else has already posted about the same issue and perhaps a resolution has already been provided.

"},{"location":"troubleshooting/overview/#ask-for-help","title":"Ask for Help","text":"

If you can't find any information in LoopDocs, GitHub Issues, Zulipchat, or Facebook...PLEASE post and ask for help. GitHub Issues list is an EXCELLENT place to post issues of unexpected Loop behavior (that you believe are errant or need improvement). However, if you are just seeking clarifications on Loop, but don't necessarily expect that there's a problem with the underlying code, then Facebook and Zulipchat are a better place. For example, Zulipchat and Facebook are great for asking about bolus strategies or exercise target use...those aren't really code issues.

When you post, provide a description along with any screenshots of the issue you are having and include the version of Loop you are running and the iOS on your device. (Tap on Loop-Settings and look at the top of the screen to get the Loop version number). You don't necessarily have to tag any particular person, the community is fairly active in replying to messages.

Post in only one place - the same volunteers monitor various sites.

"},{"location":"troubleshooting/pod-pairing/","title":"Pod Pairing Failures","text":""},{"location":"troubleshooting/pod-pairing/#pod-not-found","title":"Pod Not Found","text":"

Have you seen an error message during the pairing process for a new pod? The most common message is No pods found, as shown below. Make sure no other active pods are anywhere near the phone. Reposition the pod and the phone and if using one, the RileyLink, and then try again.

The instructions in the graphic say fill with U-100 insulin. That is the strength of your insulin, 100 U per mL of solution. The Insulet directions say to inject between 85 and 200 U of insulin. In other words, between 0.85 and 2.0 mL of fluid.

There have been a large number of fixes and improvements to reduce various pairing problems and to automatically recover from them when they do occur.

Update regularly to take advantage of improvements

Make sure you stay on top of Loop updates to take advantage of these code improvements. It is strongly recommended to update to a modern stable version (i.e., the current Loop release).

"},{"location":"troubleshooting/pod-pairing/#the-app-crashed-after-pairing-started-and-before-cannula-insertion","title":"The app crashed after pairing started and before cannula insertion","text":"

Sometimes the app will crash while the pod is priming. This is rare but can happen.

  1. Wait for the clicking to stop
    • It takes a full minute for the pod to finish priming once it starts
    • If the crash occurs while the pod is still priming - it is best to wait 30 seconds after clicks stop before reopening the app
  2. As soon as you resume the app, it will inform you that you did not complete the process
    • If you did not wait, you might be given the Insert Cannula screen before the pod is ready
    • Wait 30 seconds after clicking (priming) stops before attempting to insert the cannula
  3. In most cases, the cannula will insert as expected and you can use the pod
"},{"location":"troubleshooting/pod-pairing/#why-do-pod-pairings-fail","title":"Why do pod pairings fail?","text":"

When the pod is paired to a new device, the pod is using low-power mode. That's one reason why placement is important. And you can only have one pod that is not yet paired in the room. Try to get your new pod working before giving up and trying a new one.

Sometimes it is the pod, so if you do need to try a new one, move the one that did not pair far away from your phone.

Move Logically

Let's walk through the pod pairing/replacement process from the very beginning to make sure that we have all the important steps clearly identified even before you attempt to press that Pair button.

"},{"location":"troubleshooting/pod-pairing/#step-0-check-your-loop-version","title":"Step 0: Check your Loop version","text":"

You can check which version of Loop you are running by pressing the gear icon (\u2699\ufe0f) in the bottom right-hand corner of the Loop home screen and then looking at the line under the header.

Upgrade Loop if version prior to v3.2.x

If you are running a version of Loop prior to v3.2.x, it is recommended to update to the current Loop release.

"},{"location":"troubleshooting/pod-pairing/#step-1-verify-the-rileylink-eros-pods-only","title":"Step 1: Verify the RileyLink (Eros Pods Only)","text":"

For DASH pods, skip ahead to Deactivate old Pod.

For Eros pods, let's make sure everything is ok as far as the RileyLink goes:

  1. RileyLink is charged and nearby, and
  2. RileyLink has a green LED light lit (indicating a Bluetooth connection with your iPhone), and
  3. Try toggling the RileyLink off/on at its physical switch if the green light is not on.
"},{"location":"troubleshooting/pod-pairing/#step-2-deactivate-old-pod","title":"Step 2: Deactivate old Pod","text":"

Make sure old pod was deactivated. If you cannot communicate with the old pod in order to deactivate it, try the steps in Reset Loop to Pump Communications.

If you were not able to deactivate the old pod, you need to Discard the old pod. After several failures to deactivate, Loop offers to Discard the pod. This just tells Loop that the pod is no longer connected to the app.

You must still get that pod (that would not deactivate) away from your vicinity. Put it in a microwave or throw it over the fence into the neighbor's backyard (kidding, obviously...but outside trashcan is a good idea).

Eros Pods Only: If you had issues deactivating your pod, review Step 1.

"},{"location":"troubleshooting/pod-pairing/#step-3-start-new-pairing-process","title":"Step 3: Start new pairing process","text":"

You've deactivated your old pod successfully...great! As the first part of pairing a new pod, Loop will prompt you to fill the new pod with insulin. Once a new pod is powered-up by the insertion of at least 85 units of insulin, the pod will emit reminder beeps every 5 or 10 minutes until the entire pod pairing process has completed. This pairing process must be completed within 60 minutes of beeps starting, or the pod will give up and never pair. These activation reminder beeps do not actually indicate that any pod communication is being attempted, just that the activation has not yet been completed and your 60 minute timer is counting down.

Max Pod fill is 200 U

If you put more than 200 U in a pod, you will probably get a pod fault during priming.

Hopefully, your pod pairing continues uneventfully at this point. You'll press the Pair button and the pod pairs, primes, and the cannula insertion is successful. BUT, if not...you'll want to keep reading Steps 4-5 to find out how to recover.

One beeping pod at a time, please

It is very important to not have two pods giving reminder beeps at the same time as this can cause even more confusion for you and for Loop. Continue to work with a single pod at a time, retrying the Pair attempts multiple times if needed as described in Step 4.

If you cannot get the pairing to complete with the single beeping pod (after trying the procedures described below a few times with multiple Pair attempts during each try), then you should completely abandon that pod before attempting to use another pod. \"Completely abandon\" means move that failed-to-pair-no-matter-what-you-tried pod far, far away from you or put it in a not-turned-on-but-door-is-closed microwave. You do not want that beeping-but-not-pairing pod to be able to plague your next pod's communications with Loop during the fresh pairing process.

"},{"location":"troubleshooting/pod-pairing/#step-4-check-the-pod-placement","title":"Step 4: Check the Pod Placement","text":"

Pod pairing failed?

Ok, so you've pressed that Pair button and received an error message like shown at the top of the web page? It's time to start the stepwise process of seeing if we can get it to recover successfully.

"},{"location":"troubleshooting/pod-pairing/#dash","title":"DASH","text":"

The DASH pod can be left in the tray and placed right next to the phone. If the first attempt to pair shows the \"No pods found\" message, place the tray on top of the phone or move the pod a little further away from the phone, then try again.

If you see the Pairing exception message as shown in the graphic below, you need to toggle Bluetooth on the phone:

  • In your phone settings, turn off Bluetooth
  • Turn on Bluetooth
  • Try again

Still not working, reboot the phone and try again.

If none of those steps work, it may be the pod. But try everything one more time before giving up.

"},{"location":"troubleshooting/pod-pairing/#eros-with-rileylink","title":"Eros with RileyLink","text":"

The placement of the pod and the RileyLink relative to each other is a critical variable because the pod operates in a low-power radio mode during pairing which can lead to a number of potential faulty and half-paired pod situations, particularly with earlier versions of Loop.

How close should they be? Most people assume \"the closer the better\", but it has been measured that if the RileyLink and pod are too close together, the RileyLink may not be able to pick up the pairing response. The current recommendation is for the RileyLink to be placed a few inches to the side of the pod being paired.

If Pair fails, move a bit and RETRY

  • If the Pair operation is not succeeding, try repositioning the relative placement of the RileyLink and the pod multiple times. A little closer together if you had them far apart? A bit farther apart if they were really close? RileyLink on its side? Try standing it up with the antenna pointed to the ceiling.
  • If the pairing is still unsuccessful with multiple repositioning attempts, move yourself, the RileyLink, and the pod to another area/room (preferably away from other radio frequency signals that might be interfering), and try Pair again. Again don't be shy to try repositioning the RileyLink and pod's relative position, if needed, in this new area/room too.
  • If you have another available RileyLink, you can also try pairing using that RileyLink instead.
"},{"location":"troubleshooting/pod-pairing/#step-5-eros-pod-pairing-recovery","title":"Step 5: Eros Pod Pairing Recovery","text":"

When you have a pod that continues to appear non-responsive after several retried Pair attempts, it may be possible to recover by forcing Loop to start the pairing process from the beginning.

This section is for Eros pods

  • This section was last updated for Loop version 2.2.x
  • The error messages may be different and some steps might not be effective
  • This section remains for reference, with no guarantees.

To start we will have to press the Cancel button in the upper right corner of the pairing screen. Depending on which state the pod is stuck at in the pairing process...you'll see one of two screens after you select the Cancel button. Follow the directions (Step 5A vs Step 5B) for whichever screen corresponds to what you see after pressing Cancel.

  • Step 5A \"Switch from Omnipod Pumps\": You press Cancel and Loop will send you back to the Pod Settings screen to do the \"Switch from Omnipod Pumps\" method
  • Step 5B \"Deactivate\": You press Cancel and Loop will display a screen giving the option to \"Deactivate\"
"},{"location":"troubleshooting/pod-pairing/#step-5a-switch-from-omnipod-pumps","title":"Step 5A \"Switch from Omnipod Pumps\"","text":"

If you press the Cancel button and see a screen like below, you're going to select Switch from Omnipod Pumps in red. While this appears to confirm that you want to stop using the Omnipod, we will be adding pods back soon. Don't worry.

Don't fret. None of your Loop settings including the basal schedule and delivery limits, will be lost deleting the Omnipod pump. Select Delete Omnipod to proceed which will take you back to the Loop home screen. From here, select the gear icon at the bottom right to go to the Loop \u2699\ufe0f Settings page. Then select Add Pump in blue and then select Omnipod from the Add Pump list displayed.

Verify that the green LED on the RileyLink goes on and off as you touch the switch for RileyLink you are using indicating a successful Bluetooth connection between the RileyLink and your iPhone. Leave the RileyLink enabled with its green LED and slider turned on, and then touch the Continue button on the bottom. The Pod Settings screen should have the previous Basal Rates and Delivery Limits in effect from your previous run which can be verified at this time. Once ready, select Continue at the bottom of the screen.

Finally, you will be back to the Pod Pairing screen.

Instead of filling a new pod with insulin, attempt to pair again using the original pod which was previously filled but unable to complete the pairing process successfully. That pod should still be occasionally giving reminder beeps. Place the RileyLink a few inches to the side of the pod and press the Pair button at the bottom of the screen and hopefully, Loop will be able to successfully pair this time after starting from a fresh slate. If this pairing attempt is still unsuccessful, remember to still exhaust repositioning and Step 4 options before giving up on that pod. If it really won't pair after all that...then mark that loser pod with a Sharpie-drawn sad face and follow the directions in Step 3's colored box so that you don't end up with multiple beeping pods around accidentally.

"},{"location":"troubleshooting/pod-pairing/#step-5b-deactivate-pod","title":"Step 5B \"Deactivate pod\"","text":"

If you press the Cancel button and see an option for \"Deactivate pod\", we're going to do a little differently than Step 5A.

You might lose your pod by attempting this procedure

This is a point of no return for certain pod pairing situations and it is possible that the pod will be lost by attempting this procedure depending on the pod state. Some will recover fine, others may not. Since you can't know in advance if you might lose the pod, it is important to have already exhausted other possibilities described above in Steps 1-4 to try pairing. Specifically, (1) attempting to pair several times using varied relative positions of the RileyLink and pod (2) trying the pairing again but in a different room/location that might have less wireless interference, and (3) verifying your RileyLink is connected and functioning correctly.

For this next part, we want to make sure that the pod doesn't accidentally receive the deactivation command we are about to use. We want Loop to do the command...we just really don't want the pod to hear it. There are two ways we can keep the pod from hearing it, either (1) prevent the RileyLink from hearing Loop's command (and thus the command cannot reach the pod) or (2) prevent the pod from hearing the command from RileyLink. To accomplish our keep-the-pod-ignorant goal, you can try either option like so:

  1. Prevent RileyLink from hearing: Turn your RileyLink off temporarily at its physical switch. Some people worry about accidentally breaking their RileyLink switch, and if that's you...you can instead put the RileyLink far away from your iPhone or put the RileyLink in the microwave. That will keep the RileyLink from hearing the Loop's deactivate pod command. If RileyLink can't hear it, then your pod won't receive it.
  2. Prevent the pod from hearing: Move the beeping pod to a place where the pod is incapable of hearing the command. There are several options depending on what works for you:
    • Put the beeping pod far away...\"shouldn't be able to hear those beeps anymore\" kind of distance.
    • Put the pod in a not-turned-on-but-door-is-closed microwave.
    • Put the pod in a Faraday bag, if you own one.

Ok. Have the pod nice and ignorant? Good. Now press the \"Deactivate Pod\" button. It will take a few attempts, and you will see some failure messages about how the deactivation failed (of course it did...we hid the pod!) Eventually, you'll be given a \"Continue\" button that you'll want to use.

Press the \"Continue\" button. The instructions start with \"fill a new pod with insulin\"...BUT DO NOT! Instead, bring that beeping pod back to the hearing range. Turn that RileyLink back on if you turned it off. Once you get the RileyLink on and the pod back in range, you'll just press the Pair button and hopefully you'll find success with the process. If this pairing attempt is still unsuccessful, remember to still exhaust repositioning and Step 4 options before giving up on that pod. If it really won't pair after all that...then mark that loser pod with a Sharpie-drawn sad face and follow the directions in Step 3's colored box so that you don't end up with multiple beeping pods around accidentally.

"},{"location":"troubleshooting/pod-pairing/#step-6-help-improve-pod-pairing-process","title":"Step 6: Help improve pod pairing process","text":"

To help fix pairing bugs, some improvements have also been made in our ability to save the communications between the pods and Loop app during the pairing process. So, please help us leverage these new improvements and better squash bugs.

If you run into any pairing problems, which required Step 5A or Step 5B to be able to pair, or you had a pod that had to be abandoned, it would be helpful to generate an \"Issue Report\" after you finally get a pod paired (whether it was the original pod or if a different pod) and then post the resulting \"Loop Report\" on Zulipchat here with a short explanation of what happened.

"},{"location":"troubleshooting/pod-pairing/#what-about-other-pod-start-up-failures","title":"What about other pod start-up failures?","text":"

If you have a pod that has already started the priming operation and then has problems either finishing the priming operation or the cannula insertion, review the app crashed after pairing started and before cannula insertion to see if you can save the pod.

If a pod begins to alarm (has a fault) during priming or cannula insertion, the pod is no good and it should be deactivated and disposed of properly.

"},{"location":"troubleshooting/pod-pairing/#what-about-that-insulin","title":"What about that insulin?","text":"

If you have the misfortune of losing a pod during pairing, you can opt to not waste the insulin in that pod. Simply use the same syringe and same fill port on the pod to suck the insulin OUT of the loser pod.

If you do that, good practice is to make sure that you get that loser pod far away from the process as you go forward. Mark a big \"X\" on the failed pod and put it in a microwave, or very far away from you, so that it can't interfere with subsequent pod pairing attempts.

"},{"location":"troubleshooting/pump-errors/","title":"MDT Pump Errors","text":""},{"location":"troubleshooting/pump-errors/#medtronic-pump-errors","title":"Medtronic Pump Errors","text":"

The Medtronic pumps are used and typically not under warranty. Use this section at your own risk. However, that said, some of the most common pump errors are repairable, or not actually a real problem.

"},{"location":"troubleshooting/pump-errors/#a21-error","title":"A21 error","text":"

This error message is common when a pump has been stored for some time without a battery. Most pumps will show an A21 error when you first purchase them on the used market. Not a big deal. Press the down arrow (it also has the symbol of a light bulb on it) and the pump screen message will scroll down to let you know how to clear that error message (press ESC then ACT). If the message is coming up on a pump that hasn't been in storage, pull the battery out and replace it with a fresh, new battery. Chances are your battery or battery cap is old. Look for signs of dirt or rust in the battery cap, give it a little cleaning.

Display Tip

When the pump screen has a little black/white bar on the right side, that is a scroll bar. Use the arrow keys on the right of the pump screen to scroll and see the additional information.

"},{"location":"troubleshooting/pump-errors/#batt-out-limit","title":"Batt Out Limit","text":"

This error message \"battery out of limits\" has to do with the internal pump battery, not the AAA battery you replace. The internal battery cannot be replaced, and unfortunately also has a finite lifespan. The error message is more of an annoyance than a true problem. You can try to change the AAA battery faster. But, the worst-case scenario is that you'll have to re-enter the time and date when you get this message more often. (Don't forget to use RileyLink to set the time after you get this message.)

"},{"location":"troubleshooting/pump-errors/#button-error","title":"Button Error","text":"

The Button Error message usually happens from water, moisture, or dust getting under the pump's button pad and causing button(s) to fail. The fix luckily is quite straight-forward and takes less than 30 minutes. Check out the fix here for a YouTube video or here for photo gallery. There is also a detailed page in the OpenAPS docs.

The solution involves simply prying up the button pad's sticker face to expose the layers beneath.

You can see some evidence of crud/rust on the underside of this button pad which caused the button error.

After you finish your fix, another excellent idea is to make sure you add a length of clear packing tape across the front face of the pump to prevent errant water or dirt from having easy access to the button pad seams.

"},{"location":"troubleshooting/pump-errors/#crackmissing-piece-repairs","title":"Crack/Missing Piece Repairs","text":"

Another common issue on these Medtronic pumps are cracks and/or missing bits of plastic near the battery cap or reservoir sleeve. You can repair these fairly easily. For filling small cracks, Testor's plastic cement or Gorilla epoxy are good choices.

For more extensive repairs to replace missing chunks of plastic, Gorilla epoxy or Sugru are excellent choices.

You can use teflon thread tape on the battery cap to make sure the epoxy or Sugru don't stick to the battery cap, but still recreate the threads. The first photos are of a Sugru repair and second set of photos are Gorilla epoxy repair.

"},{"location":"troubleshooting/pump-errors/#motor-error","title":"Motor error","text":"

Often a motor error is the result of a poorly seated reservoir or tubing cap. If you get a motor error, the first thing you should do is detach from your infusion site. Remove and reseat the reservoir, prime again, and see if the motor error resolves. If it does not, try replacing the tubing cap on the reservoir (new tubing). If that does not resolve the motor error, also replace the entire reservoir.

"},{"location":"troubleshooting/pump-errors/#a33-error","title":"A33 error","text":"

Safety warning

If you get this error, DO NOT push on the bulged-out end cap. Always detach your tubing from your infusion set before addressing this error message. If you push on the end cap in an attempt to get it back flush, you may deliver a dangerous amount of insulin mistakenly.

This error is a bit more involved to repair. The problem is that there is a loose drive support cap. Most of the time this error message will appear during a priming event as the end cap of the drive will slip, releasing the ability of the reservoir plunger to get pressure to deliver insulin. The pump senses the lack of pressure and delivers the A33 error.

The solution is to UNHOOK from your site. See the warning above. Remove the reservoir and put your finger inside the reservoir sleeve. Push on the drive so that the end cap is pushed out the most possible. This will give you the most surface area possible to place the super glue GEL that you will use. (don't use regular super glue...it must be gel.) Remove the sticker that covers the end cap, and save it for later because you can reattach it when the repair is completed.

With the end cap pushed out, take some glue gel with the toothpick and apply it on the outside of the popped-out cap. Be generous cause you can do this only once. Once you are done take a napkin and press hard the cap toward the pump so it can go back inside and keep it pressed for a few seconds. Then remove all the small parts of the napkin that has glued to the pump. Leave the pump to dry for about 10-15 minutes.

Now to test whether the pump was glued well. You have already waited about 10-15 minutes so put your finger back in and press hard the plunger. If you glued it well, the end cap will not move. If the cap goes out again, you have to glue it one more time. If all looks well, put some glue back on top of the pump cap and reattach the sticker that was removed to start.

"},{"location":"troubleshooting/pump-errors/#a32-and-e22-error-loop","title":"A32 and E22 error loop","text":"

From what we know, this set of error codes seems like a pump killer. A call to Medtronic support gave this less-than-hopeful information:

A32 - failure of flash memory E22 - software re-installation is necessary

We don't have any reports of a good fix for these error codes. When seen, usually the E22 error comes up and as soon as it is cleared, the A32 error comes up. And the loop continues with a pump restart.

"},{"location":"troubleshooting/red-loop/","title":"Red Loop","text":""},{"location":"troubleshooting/red-loop/#red-loop-overview","title":"Red Loop Overview","text":"

This page provides help if your Loop icon is red and Loop is not working or only working sometimes.

With Loop 3 - clicking on the Loop icon on the main screen tells you the last time Loop completed, but you need to look at the Pump Status Icon and the Glucose Status Icon for more information. For example, when Glucose is stale (more than 15 minutes old), the Glucose icon shows \"- - -\". For example, when the Pump is having a communication issue, you will see a No Signal icon.

With Loop 2.2.x - clicking on the Loop icon on the main screen provides an error message. If you understand it, great...that should help you fix the problem. If not, grab a screenshot so you can ask for help from a mentor.

Omnipod Users

Do not pull a pod when there is a red loop.

  • Usually the problem is with Loop, not the pod
  • A new pod won't fix a Loop (Bluetooth or RileyLink communication problem)

There are a few times when it is the pod - but try all the steps on this page first.

Medtronic Users

You must select Insulin Type on your pump settings screen after updating from Loop 2 to Loop 3 and completing the onboarding. Without an insulin type, closed loop will not work.

A Red Loop icon means that Loop has not completed a cycle for 15-minutes or more and this is normally because of a communication break-down with one of the systems listed below.

"},{"location":"troubleshooting/red-loop/#typical-causes-for-red-loop","title":"Typical Causes for Red Loop","text":"

Some of the reasons listed below cause Loop to go Red and stay Red until you fix it. Others will cause intermittent Red Loops that come and go.

  1. Reset Loop-to-Pump Communications
  2. Continuous Glucose Monitor (CGM)
  3. Apple Health
  4. Background App Refresh is not enabled for Phone, Loop and/or CGM
  5. Nightscout (optional service)
  6. Phone Storage is Full
  7. Lost Pod Information If running Loop 2.2.x or FreeAPS, read this section first
"},{"location":"troubleshooting/red-loop/#lost-pod-information","title":"Lost Pod Information","text":"

We think this was fixed with Loop 3. If you are running Loop 2.2.x or FreeAPS:

  • Before attempting to resolve a red-loop with a phone reboot; please review this section. It can affect the stored CGM information as well as the stored pump information.

Be Careful with Phone Reboots with Loop 2 or FreeAPS

If you are using an Omnipod, then before rebooting the phone, make sure it is absolutely necessary - try all other methods first. Be prepared to check that the pod is still communicating with Loop following the reboot. If this rare event happens to you, please report it, save and post a Loop Report and be prepared to put on a new pod and possibly re-enter your CGM information.

This could happen to someone using a Medtronic pump, but the consequence is less of a concern because the pump information is not modified as frequently as for Omnipod users.

"},{"location":"troubleshooting/red-loop/#reset-loop-to-pump-communications","title":"Reset Loop-to-Pump Communications","text":"

If the indication is one of these (or something similar), it can probably be fixed by resetting the Loop-to-Pump communication. For DASH, this is Bluetooth only. For Eros or Medtronic, it is a combination of Bluetooth and the RileyLink compatible device.

  • pump history is too old
  • no rileylink could be found
  • pod cannot be reached
  • the Unable to Reach Pump modal screen is visible

Do these steps until one of them fixes the issue:

  • Turn off Bluetooth on your phone and then turn it right back on again.
  • Close your Loop app (upswiping it in the iPhone's app selector) and reopen it.

  • Eros or Medtronic: Turn your RileyLink off/on at its physical power switch located on the side of the RileyLink.

    • If you have a different device, make sure you know how to power-cycle the device.
    • For RileyLink (without wireless charging) use a small pointy object to carefully move the slider away from the charging port and then back up towards the charging port. A paperclip on the keyring can provide the help you need to reach the switch in the recessed case, and double as a screaming pod silencer tool.

This should restore a green Loop within 5 minutes. If you're impatient and are using pods, you can tap on Play Beeps. With Medtronic, you can attempt to suspend/resume the pump. If this is successful, you've established communication again.

Last thing to try is:

"},{"location":"troubleshooting/red-loop/#power-cycle-your-phone","title":"Power cycle your phone.","text":"
  • This suggestion is last because of a rare, intermittent issue (with iOS 15 and Loop 2.2.x) in which power cycling the phone does not load the latest version of Loop information
  • This was fixed with Loop 3
  • Click on the Lost Pod Information link for more information

If this was not successful, check out the Pump is Not Responding section.

"},{"location":"troubleshooting/red-loop/#cgm-values-are-not-being-collected-by-loop","title":"CGM Values Are Not Being Collected by Loop","text":""},{"location":"troubleshooting/red-loop/#new-transmitter","title":"New Transmitter","text":"

If you recently changed a transmitter, you need to also update your Loop settings to reflect the new transmitter ID. Go to the CGM section of Loop settings and Delete CGM (it's a button on the bottom of that page). Then use the Add CGM in Loop settings to include the new transmitter ID.

If you fail to update your Transmitter ID in Loop and you also left Share Credentials in Loop (not recommended), you will see messages such as: Failed to decode SGV when the Share server cannot be reached. That's your notice to update the Transmitter ID (or if you think you already did - check for typos in data entry).

"},{"location":"troubleshooting/red-loop/#delete-share-account","title":"Delete Share Account","text":"

Finally, we see a lot of errors reported because people have problems with their Share server information in Loop app. Please delete your Share account information from within Loop settings. In other words, the credentials portion of the Share account info, as shown in the screenshot below, should say Tap to Set and not have your account info. It is unnecessary to have this portion filled out as local, non-internet spying of a transmitter is the preferred CGM source anyways. In fact, by leaving this information out, it will help you remember to change your transmitter ID when you change transmitters because CGM data won't appear in Loop. By not including Share account in Loop, you will prevent yourself from accidentally becoming internet dependent.

"},{"location":"troubleshooting/red-loop/#firefly-style-transmitter","title":"Firefly-style Transmitter","text":"

Leaving this in for historical interest only. It illustrates the need to keep Loop up-to-date. Who knows what the next hardware change will be. Enough time has passed that everyone's Loop code should be newer.

In July 2019, we started to see a new style of Dexcom G6 transmitters on the market. These new transmitters required a rework of some of the Loop's code to continue to \"spy\" on the transmitter. Without that update, your Loop can not get CGM data unless it is pulling from Share servers (which is not a recommended mode of operation). So, download fresh code for your Loop app if you have a new transmitter type and haven't downloaded since July 2019.

"},{"location":"troubleshooting/red-loop/#apple-health","title":"Apple Health","text":"

Make sure both the Loop app and the Dexcom app have permission to write to Apple Health by checking the Apple Health Permissions

In the early days of iOS 14, there were problems with the Apple HealthKit. The consequence is that some people's database was corrupted. If you tap on the Heart Icon on your phone to go to Apple Health and display data and it is very slow to respond - or never responds, you probably need to get rid of a corrupted database and start fresh. Be sure to go Open Loop if this is needed. Please get help from your favorite Loop Social Media group or from Apple support in this case.

"},{"location":"troubleshooting/red-loop/#background-app-refresh","title":"Background App Refresh","text":"

If you have not enabled background app refresh on your phone, then Loop is likely to stop communicating as soon as the phone is locked.

  1. Phone Settings -> General -> Background App Refresh -> enable
  2. Then scroll down until you find Loop and make sure the green slider is enabled
  3. While you are there - check your CGM app as well

For iOS 15, there is a new feature described by Dexcom

  1. Phone Settings -> Screen Time -> choose Always Allowed -> select an app, tap the plus icon to add to Always Allowed list
    • add Dexcom
    • add Loop
"},{"location":"troubleshooting/red-loop/#nightscout","title":"Nightscout","text":"

If you added your Nightscout URL to Loop and are uploading information to Nightscout, make sure the communication is working properly. For short-term interruptions, Loop will store information to upload to Nightscout later. But if too much information builds up, Loop can slow down and in some cases have a Red Loop.

  1. Check to see that internet service (WiFi or Cell) is operating
  2. Check that Nightscout database size isn't full (more details below)
  3. If Red Loops are resolved by removing the Nightscout URL from Loop; you need to figure out if it's the connection or the database or some other issue

If you opted for the free DIY Nightscout, you will need to clean your database once or twice a year. Follow the Nightscout Database cleanup steps. Make sure you are periodically checking your database size (and that the dbsize keyword is in your ENABLE list and cleaning it.

"},{"location":"troubleshooting/red-loop/#phone-storage-is-full","title":"Phone Storage is Full","text":"

This was reported by a user in November 2021. His phone storage was almost full and the reported error messages for Loop was:

  • Sqlite Error: A Sqlite Error Occurred: (13) Database or Disk is Full

The error message from Dexcom was not as helpful. If you see this, check your phone storage:

  • The Dexcom G6 app has stopped working. Please delete the app from your device and redownload it from the App Store

Solution: clear up space on your phone.

"},{"location":"troubleshooting/red-loop/#other-reasons-for-red-loop","title":"Other Reasons for Red Loop","text":""},{"location":"troubleshooting/red-loop/#pump-is-not-responding","title":"Pump is Not Responding","text":"

The first step is to make sure the phone and if needed, the RileyLink compatible device, is not so far away from the pump or pod that they cannot communicate. Assuming you've addressed this, then you can move on to other steps.

Omnipod Loopers:

If the pod is screaming, it should still be able to communicate with Loop, but sometimes you need to restore communication so you can deactivate the pod and quiet it. Follow the steps below, just do it with the added \"noise\".

The Reset Loop-to-Pump Communications steps almost always fix the issue. It is possible that the pod really had stopped communicating, but try everything else before burning another pod.

Medtronic Loopers: If the pump is not responding with \"decoding\" errors or various other messages about pump responses. Try the following:

  1. Change pump battery. Low pump battery will cause radio communications to fail.
  2. Use the Change Time command in the pump menu to update the pump's clock. If you've accidentally changed the pump's time in the pump itself or if the pump time has drifted, this will get the Loop app and pump time back in sync.
  3. If using a x23 or x54 pump, try deleting all the IDs under the \"Other Devices\" submenu in the pump's \"Connect Devices\" menu. Then go to the RileyLink menu and use the MySentry pairing command to get a fresh ID issued. Follow the directions listed in the MySentry pairing command's screen to scan for devices. A fresh ID can help prevent recurring red loops for x23 and x54 users, particularly if they started to occur after a recent Loop update.
  4. Make sure the following are checked in the pump:
    • Your pump cannot be suspended. Resume insulin deliveries.
    • Temp basal type must be set to unit/hour, not percent, in pump's Basal menu.
"},{"location":"troubleshooting/red-loop/#resolving-frequent-red-loops","title":"Resolving Frequent Red Loops","text":"

Here's some things to check if you have frequent red loops:

  • Try deleting your Nightscout account from Loop settings and see if your Loop stops having red loops. If it does, then you'll need to assess what's going wrong in your Nightscout site and fix it. Most of the time, your database is getting too big and cleanup is required.

  • Is your RileyLink battery plugged in all the way on the board? One Looper recently posted that her RileyLink battery connection needed to be reseated after several years of service.

  • Has your RL been fully charged? Try charging your RL for an hour or two, make sure the red light comes on while charging. Try a new charger or cable.

  • Oddly, some people have found that turning off Siri integrations for Loop and Dexcom apps in your iPhone settings has helped. This may be coincidental, but if you're still having trouble, you might want to try it.

  • Check for sources of wireless interference. If you have a certain environment that seems to have more drops than others, it is likely that there is a source of wireless communication interfering with your Loop. Lots of Medtronic Loopers in a room together will often interfere with each other and get \"cross-talk\" red loop error messages. If it is a bedroom at night causing problems, try moving other wireless devices such as routers or baby monitors farther away from where you and your RileyLink compatible device.

  • In some cases, you may need to clean out Apple Health, or even reset your phone to factory defaults and reload all your personal information and then rebuild the Loop app. Before you do this, you may want to Post for Help (next section).

"},{"location":"troubleshooting/red-loop/#posting-for-help","title":"Posting for Help","text":"

Before you post on Looped group for help with a red loop, please make sure you've reset the RileyLink / Phone.

Before you post for help, please also check your Nightscout status including database size. This step is often overlooked and yet solves a lot of problems.

When posting for help, include two screenshots of Loop's main screen; one with the red loop's error message and the other just the plain Loop main screen. Include a detailed description of what you have tried doing from the troubleshooting list above. For example, state if you've double checked the transmitter ID, deleted the Share account info from Loop settings so that we can rule out some of the causes of CGM issues.

"},{"location":"troubleshooting/red-loop/#what-else","title":"What Else?","text":"

There are a few other things to consider:

  • RileyLink is broken
  • Battery has failed
  • OrangeLink has firmware 2.6
"},{"location":"troubleshooting/red-loop/#rileylink-is-broken","title":"RileyLink is Broken","text":"

How can you tell if your RileyLink has a problem? The answer is mostly within the LED lights that display on the board. Some information is listed below, but also review the FAQs at getrileylink.org.

If you have a different RileyLink compatible device, please check the appropriate site for troubleshooting help.

Red light: comes on during charging and will turn off/on periodically, while still plugged in, after charge is complete.

Green light: Indicates an active BT connection with the phone. You want the green light to stay on all the time on the RileyLink. If the green light is not on, then make sure your iPhone's bluetooth is still switched on.

Blue light: The blue light will flash off/on periodically when the RileyLink and pump are actively communicating...it should NOT be always on. If your blue light is stuck on, that is an indication of a problem on the board. Try looking for signs of damage or debris that may be causing a short on the board. Clean the board with rubbing alcohol (unplug the battery first). If you still can't get the blue light off, then contact GetRileyLink for help or check out RileyLink Compatible Devices for replacement options.

"},{"location":"troubleshooting/red-loop/#battery-has-failed","title":"Battery has Failed","text":"

Both RileyLink and EmaLink use LiPo batteries. If they stop holding charge for as long as they used to, or if they swell (often first noticed as bowing of the case), stop using the battery and replace it as soon as possible.

OrangeLink uses regular batteries, so just change them out.

"},{"location":"troubleshooting/red-loop/#orangelink-firmware","title":"OrangeLink Firmware","text":"

One version of the OrangeLine firmware did not communicate well with Loop (or Android APS).

If you have FW 2.6 on your OrangeLink or OrangeLink Pro, please upgrade to FW 3.2 as soon as possible.

"},{"location":"version/build-dev/","title":"Build Dev","text":""},{"location":"version/build-dev/#building-development-code","title":"Building Development Code","text":"

No matter the method used to build Loop-dev: GitHub actions or git commands, you are testing development code. Please read this link now before continuing.

  • What's going on in the dev branch

There are several methods to build Loop-dev. First review the general information on this page then choose the link for the method of your choice:

"},{"location":"version/build-dev/#update-frequently","title":"Update Frequently","text":"

While Loop-dev is under active development, you should monitor zulipchat and update frequently. Sometimes the dev branch is quiet for a month or more and other times it gets updated daily. Please pay attention.

Checking for updates every week is a good idea. Also - subscribe to all the streams on Loop Zulipchat to make sure you don't miss critical information.

"},{"location":"version/build-dev/#loop-dev-version","title":"Loop-dev Version","text":"

The version of code that shows up under the Loop Settings screen does not change when the dev branch is modified.

If you need help with your app, the mentors need more information. Please issue a Loop Report when asking for help. Refer to Support for how to issue a Loop Report. If you want to keep track yourself, refer to Identify Loop-dev Version

  • Loop Version Numbering
"},{"location":"version/build-dev/#identify-loop-dev-version","title":"Identify Loop-dev Version","text":"

The version of code that shows up under the Loop Settings screen will remain fixed until Loop-dev is released. In order to identify which version of dev you have on your phone, you need the commit.

The commit is identified by a 7-digit alphanumeric code. That code was also appended to the folder name of the downloaded code under Downloads/BuildLoop as shown in the graphic above. You can use finder to view the folder name after the script completes. It also appears in the Loop Report, refer to Support for instructions on issuing a Loop Report. After you issue the Loop Report, look at the workspaceGitRevision number near the beginning of the report.

"},{"location":"version/build-dev/#build-loop-dev","title":"Build Loop dev","text":"
  1. For the Build with Browser method
    • Build dev with Browser
  2. For the Build with Mac method:
    • Build dev with Mac
"},{"location":"version/build-time-flag/","title":"Build-Time Flag","text":""},{"location":"version/build-time-flag/#overview","title":"Overview","text":"

Build-time features are not available with Loop 2.2.x.

With Loop 3, some features are enabled or disabled by default but can be modified by adding a \"flag\" in the LoopConfigOverride.xcconfig file.

If you use Build with Browser, these build-time features can be added to your copy of the LoopConfigOverride.xcconfig file. Use the pencil icon in that file on your copy of LoopWorkspace and then commit the change.

If you use the Build with Mac Method, this is the same file used to automatically sign all your targets. You can edit the version in your LoopWorkspace folder (it shows up as the top item in the Xcode folder view) - or - if you use the build script, you can edit the copy found in ~/Downloads/BuildLoop after the first time you use the script. For that second case, the \"flags\" you add in ~/Downloads/BuildLoop/LoopConfigOverride.xcconfig are applied to all downloads created with the script.

These flags are always upper case with underscore separating words for clarity, for example MY_EXAMPLE_FLAG. If you have more than one flag, they are separated by a space. Do not enter a line break between selections; in other words, do not hit return or enter. Xcode will automatically word-wrap the line for clarity. All values need to be on a single line.

New Instructions

The instructions are more robust than earlier instructions that had you editing a line instead of adding new ones.

Copy the text below, add it to the end of your LoopConfigOverride.xcconfig file and then insert the desired flags in place of MY_EXAMPLE_FLAG. If you want more than one flag, separate them by a space.

Lines to add to end of file
// Add Build-Time features to compilation conditions\nSWIFT_ACTIVE_COMPILATION_CONDITIONS = $(SWIFT_ACTIVE_COMPILATION_CONDITIONS) MY_EXAMPLE_FLAG\n

Code Before Modification

// Put your team id here for signing\n//LOOP_DEVELOPMENT_TEAM = UY678SP37Q\n

The example below is for someone who is using a Free Developer ID - which does not support Siri.

Code After Modification

// Put your team id here for signing\n//LOOP_DEVELOPMENT_TEAM = UY678SP37Q\n\n// Add Build-Time features to compilation conditions\nSWIFT_ACTIVE_COMPILATION_CONDITIONS = $(SWIFT_ACTIVE_COMPILATION_CONDITIONS) SIRI_DISABLED\n

List of some flags and what they do:

FLAG PURPOSE SIRI_DISABLED Required to build Loop from Xcode with a free developer account ADULT_CHILD_INSULIN_MODEL_SELECTION_ENABLED The choice for Child Model is enabled in Therapy Settings. Please read Enable Child Model. REMOTE_OVERRIDES_DISABLED Remote commands: override, carbs or boluses will not be accepted even if all the Remote Command requirements are configuredIf you do configure this and later try to set up remote commands, they will not work and there is no error message. Remote Errors: Loop REMOTE_OVERRIDES_DISABLED OBSERVE_HEALTH_KIT_CARB_SAMPLES_FROM_OTHER_APPS_ENABLED Turns on ability for Loop to read third party carb entries. You must also make sure Health permissions allow Loop to read carbs from Health. Be vigilant if you select this; added carbs lead to added insulin dosing when closed loop is enabled SHOW_EVENTUAL_BLOOD_GLUCOSE_ON_WATCH_DISABLED The Apple Watch screens show current glucose, trend arrow and eventual glucose by default. This flag disables the display of eventual glucose on the watch if you find the display distracting. PREDICTED_GLUCOSE_CHART_CLAMP_ENABLED Chart Clamp ALLOW_ALGORITHM_EXPERIMENTS dev branch onlyThis is enabled by default to show Algorithm Experiments below the Therapy Settings row. This enables the user to separately enable or disable Glucose Based Partial Application and Integral Retrospective Correction"},{"location":"version/build-time-flag/#chart-clamp","title":"Chart Clamp","text":"

What the heck is a chart clamp? It means the range displayed will not be smaller than the clamp but it can be bigger.

Loop automatically scales the glucose charts based on the history shown. Some people don't like to see the vertical axis changing, so they turn on the \"clamp\".

When the PREDICTED_GLUCOSE_CHART_CLAMP_ENABLED build time flag is added:

  • the range shown is never smaller than glucoseChartDefaultDisplayBoundClamped
  • 80 to 240 mg/dL (4.4 to 13.3 mmol/L)

When you do not add that build time flag:

  • the range shown is never smaller than glucoseChartDefaultDisplayBound
  • 100 to 175 mg/dL (5.6 to 9.7 mmol/L)

If glucose within the display history is outside of the bound, the graph range expands to include that glucose level. This prevents glucose readings from being \"hidden\".

You can customize chart display settings if you want. The original lines of code are shown below. You will need to read the rest of this page to figure out how to modify these to meet what you prefer. If you can't figure this out - reach out for help.

  • Module: Loop
  • Loop 3
    • Folder: Loop/Models
    • File: LoopConstants.swift
    • Lines: 32 to 45
    // MARK - Display settings\n\n    static let minimumChartWidthPerHour: CGFloat = 50\n\n    static let statusChartMinimumHistoryDisplay: TimeInterval = .hours(1)\n\n    static let glucoseChartDefaultDisplayBound =\n        HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 100)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 175)\n\n    static let glucoseChartDefaultDisplayRangeWide =\n        HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 60)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 200)\n\n    static let glucoseChartDefaultDisplayBoundClamped =\n        HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 80)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 240)\n
"},{"location":"version/build-time-flag/#enable-child-model","title":"Enable Child Model","text":"

Loop 3, by default, does not include the concept of child versus adult for rapid-acting insulin, i.e., Humalog, Novalog and Apidra.

  • The child model can be enabled following the directions above, adding ADULT_CHILD_INSULIN_MODEL_SELECTION_ENABLED to the LoopConfigOverride.xcconfig file and rebuilding
  • Insulin Model is then found in the Therapy Setting section of Loop 3 with Adult selected by default
  • Insulin Type continues to be associated with the pump and can be modified in the Pump Settings screen
"},{"location":"version/code-custom-edits/","title":"Custom Edits","text":""},{"location":"version/code-custom-edits/#build-then-customize","title":"Build then Customize","text":"

For new Loopers, please build the code before you make any changes. Start with Open Loop and familiarize yourself with the interface. Later, you can make the customization(s) you desire and build again. The second build will be much easier than your first build.

These customizations require you modify the Loop app code and then build the app after making these customizations. This page supports version 3 and greater for the Loop app.

"},{"location":"version/code-custom-edits/#customization-options","title":"Customization Options","text":"

Read about the customizations on this page before applying them.

You take responsibility

You are responsible when you decide to use customizations.

Be sure to report what changes you made if you need to ask for assistance with your app.

Some customizations are the same for everyone and have been prepared for easy use. Refer to the build method that you use for information about applying these prepared changes - the same set is available for both build methods.

  • Customize with Browser
  • Customize with Mac

Other customizations require that you create your own personalized version.

  • On this page are instructions for what modifications are required to your code to achieve a personalized customization (regardless of build method)
  • On Version: Build-Time Flag are details about how to change the default settings for the build-time flags by editing the LoopConfigOverride.xcconfig file.
"},{"location":"version/code-custom-edits/#instructions-for-finding-the-lines","title":"Instructions for Finding the Lines","text":"

The instructions on this page identify the module, Key_Phrase or file and line numbers required to locate the code you need to modify.

Why do I have to jump between pages?

  • The code changes are defined on this page
  • The method to make code changes depends on build method and are found at:
    • Custom Edits with Browser
    • Custom Edits with Mac

Line numbers may change

Every effort will be made to update the line numbers as the code is updated, but there may be times where the screenshots and line numbers differ from the current version of Loop code.

  • You may notice some customizations list line numbers for different branches

  • If you cannot identify a line that looks exactly like the example - do not guess - go to your favorite social media group and ask for help

  • Sometimes there is a bigger change than just line numbers. The git software is really good about finding the \"right\" code that is just at a different line number. When you see the notation Stable: Changed on date, that means you must select the correct version when making your personal customization depending on which version you are modifying.

This page is broken into two halves:

  • Custom Edits Required:

    • The first half of this page is for customizations that require you to edit your own code

  • Custom Edits Optional:

    • The second half of this page provides instructions for some of the prepared customizations included in the Loop and Learn: Customization Select Script
    • Some people prefer to make all their own edits

For each customization, you will be given landmarks to find the correct location in the code. You can choose to search using the Key_Phrase or navigate to the file in the folder structure and look for the line number.

"},{"location":"version/code-custom-edits/#key_phrase","title":"Key_Phrase","text":"Example of a Key_Phrase
use the copy button at right, paste into search\nThe copy button for this exampe is just for practice\nDo not paste the result anywhere\n

To search using the Key_Phrase (see graphic above for an example):

  • A copy button is available when you hover your mouse in the right-hand side of the block below the title Key_Phrase; click on it to copy the phrase into your paste buffer
  • You can paste this into the search function of the tool you are using if desired (warning, you may have to hit back-space to remove a return character from the pasted text)
  • Alternatively, navigate to the required file using Module, Folder, File and line number
"},{"location":"version/code-custom-edits/#module-folder-file","title":"Module, Folder, File","text":"

Stability Information Added

If a customization needs to be modified to work with the dev branch, that will be noted. This means a change that is more than a line number. Instead it is a change that requires a new customization.

For those using the Browser Build method for main branch, this means you will need to use Create branch if needed to create a special branch to prepare a new version of this customization. If you already created a personal customization earlier (before the date noted), you can keep using that customization with main.

For your convenience, see Not Stable List.

Each customization provides the Module, Folder and File bullet below the key phrase.

  • Module: Loop
  • Folder: Loop/subfolder1/subfolder2/etc.
  • File: filename.swift, line number(s)
  • Stable: \"Yes\" or \"Changed on date\"

The customizations below show the original line of code that you will be changing.

There may be a figure illustrating the change.

Below the figure, the original, and in some cases, the modified code will be displayed as text.

  • Sometimes that line is long and you may need to use the scroll bar to see the entire line in LoopDocs
  • In most cases, an example customization is shown to assist you in deciding how to edit the line to meet your needs
"},{"location":"version/code-custom-edits/#not-stable-list","title":"Not Stable List","text":"

This list indicates personalized customization that differ between main and dev

  • 2024 Feb 19: Glucose Guardrails
  • 2023 May 29: Adjust Future Carbs Time Interval
"},{"location":"version/code-custom-edits/#custom-edits-required","title":"Custom Edits Required","text":""},{"location":"version/code-custom-edits/#default-carb-absorption-times","title":"Default Carb Absorption Times","text":"

Loop\u2019s default carb absorption times are based on the high, medium, and low glycemic index absorption curves presented in Think Like A Pancreas by Gary Scheiner. In prior versions of the Loop app, for example version 2.2.x, the lollipop (fast) icon was set for 2 hours, taco (medium) icon for 3 hours, and pizza (slow) icon for 4 hours. This is modified for Loop 3 to 30 minutes, 3 hours and 5 hours respectively. Some people prefer different values.

Do you want to know more? (Click to open/close)

The developers did this because they expect fast to only be used for rapid-acting low treatments. The medium and fast values are for moderate and higher-fat or large meals.

Key_Phrase
defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes\n
  • Module: Loop
  • Folder: Loop/LoopCore
  • File: LoopCoreConstants.swift
  • Line: 19
  • Stable: Yes

For example, if you wanted to change fast to be slightly longer, the edit would be as follows:

_Code Before Modification

public static let defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes = (fast: .minutes(30), medium: .hours(3), slow: .hours(5))\n

_Code After Modification

public static let defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes = (fast: .hours(1.5), medium: .hours(3), slow: .hours(5))\n

Note that if you change fast from 30 minutes to 1.5 hours, you must also change the indication before the parentheses.

"},{"location":"version/code-custom-edits/#adjust-maximum-iob-for-automatic-dosing","title":"Adjust Maximum IOB for Automatic Dosing","text":"

With version 3.2.0, a new safety feature was added. This limits automatic dosing so IOB is no more than two times the \\(\\mathit{maximumBolus}\\) set in your Delivery Limits. (The term automatic dosing refers to insulin the app automatically delivers above your scheduled basal rate.) Manual Bolus, where you initiate the bolus yourself, is not subject to this limit. Please read How do Delivery Limits Affect Automatic Dosing? for detailed information on how this safety feature works.

The default value (\\(\\mathit{2*maximumBolus}\\)) used for this feature is good for the majority of people who use the app. However, there are some individuals who might need to limit the size of any single bolus independent from the maximum IOB they want to set for their app. This is particularly true for those who find large boluses give rise to tunneling and the insulin leaks out along the cannula.

Key_Phrase
automaticDosingIOBLimit = maxBolus\n
  • Module: Loop
  • Folder: Loop/Managers
  • File: LoopDataManager.swift, line: 1690 (main), 1796 (dev)
  • Stable: Yes

The following example is for someone who limits a single bolus to 5 U but frequently needs to achieve an IOB of 15 U for meals. They want that level of IOB to be reached with automatic bolusing. In that case, they may want to modify the factor used to calculate \\(\\mathit{automaticDosingIOBLimit}\\).

Original Code: 

let automaticDosingIOBLimit = maxBolus! * 2.0\n

Modified Code Example: 

let automaticDosingIOBLimit = maxBolus! * 3.0\n

Because the automatic bolus amount is also limited by the partial application factor, it still takes a few cycles to reach the higher IOB of \\(\\mathit{3*maximumBolus}\\); but they can get there without manual intervention.

"},{"location":"version/code-custom-edits/#adjust-percent-bolus-for-automatic-bolus","title":"Adjust Percent Bolus for Automatic Bolus","text":"

If you are mostly happy with the Dosing Strategy of Automatic Bolus but wish it delivered more or less insulin during every Loop interval, then this customization is for you.

This customization changes the percent of the recommended bolus used for automatic delivery. The method for calculating that recommendation is not changed by this modification. The default value is 40% (0.4). It is recommended you take small changes of 0.1 at a time. Once you modify it once and try it out for a while, it\u2019s easy to go back and change it again.

Change just the number and double check that the value is less than 1.

Key_Phrase
let bolusPartialApplicationFactor\n
  • Module: Loop
  • Folder: Loop/Loop/Models
  • File: LoopConstants.swift
  • Line: 53
  • Stable: Yes

Code Before Modification

static let bolusPartialApplicationFactor = 0.4\n

Code After Modification to 50% of recommended insulin

static let bolusPartialApplicationFactor = 0.5\n

Do not exceed 1.0

This number should never be bigger than 1 (you\u2019d be getting more than Loop recommends). If you think you need more than 1, consider your settings and meal entries.

"},{"location":"version/code-custom-edits/#pods-add-extra-insulin-on-insertion","title":"Pods: Add Extra Insulin on Insertion","text":"

The default value is 0.0 U of extra insulin. If you use this customization, start with a small number and work your way up. If you are coming from manual podding and routinely gave yourself an extra bolus with your PDM at pod change time, you may not need nearly as much with Loop - be conservative.

Note that Loop does not include the amount of insulin in the prime or insertion steps in your IOB. The pod reports every pulse that it delivers to Loop. If you look in the Pod Settings insulin delivered row, that is the total delivered by the pod minus the (prime plus insertion) amounts. The only way to know that you successfully made this change is to count the clicks. Normal insertion is 0.5 U (0.5 U / 0.05 U per click = 10 clicks). So if you add 0.35 U to the \"extra\" value, you should get 0.35 / 0.05 = 7 extra clicks. In other words, 17 total clicks after you press insert.

This code change is found in one location for Eros Pods (called Omnipod throughout the app) and DASH Pods (called Omnipod Dash throughout the app). I tend to change both files, but if you're only using one kind of pod, that is really not necessary.

Key_Phrase
let cannulaInsertionUnitsExtra\n
  • Module: OmniBLE (DASH) or OmniKit (Eros)
  • DASH or Eros Pod (Loop 3 only)
    • Folder: OmniBLE/OmniBLE/OmnipodCommon (DASH)
    • Folder: OmniKit/OmniKit/OmnipodCommon (Eros)
    • File: Pod.swift, Line 82 (DASH); Line 87 (Eros);
  • Stable: Yes

Code Before Modification

public static let cannulaInsertionUnitsExtra = 0.0 // edit to add a fixed additional amount of insulin during cannula insertion\n

Code After Modification to add 0.35 U

public static let cannulaInsertionUnitsExtra = 0.35 // edit to add a fixed additional amount of insulin during cannula insertion\n
"},{"location":"version/code-custom-edits/#modify-the-guardrails","title":"Modify the Guardrails","text":"

The Therapy Setting Guardrails are for Loop 3 only.

"},{"location":"version/code-custom-edits/#glucose-guardrails","title":"Glucose Guardrails","text":"

If you build Loop 3 over a version of Loop 2.2.x or FreeAPS where the Correction Range is lower than the default value of 87 mg/dL (4.8 mmol/L), your app requires you to satisfy the new guardrail before you can save that Therapy Setting when you onboard.

Key_Phrase
Guardrail(absoluteBounds:\n
  • Module: LoopKit
  • Folder: LoopKit/Extensions
  • File: Guardrail+Settings.swift
  • Line: 12 for suspendThreshold
  • Line: 26 for correctionRange
  • Stable: Changed on 2024 Feb 19 Version after Update
"},{"location":"version/code-custom-edits/#version-before-update","title":"Version before Update","text":"

Code Before Modification

static let suspendThreshold = Guardrail(absoluteBounds: 67...110, recommendedBounds: 74...80, unit: .milligramsPerDeciliter, startingSuggestion: 80)\n

and

static let correctionRange = Guardrail(absoluteBounds: 87...180, recommendedBounds: 100...115, unit: .milligramsPerDeciliter, startingSuggestion: 100)\n

Modify the absoluteBounds to change the allowed ranges or the recommendedBounds to change the color of the numbers on the picker wheel.

Loop automatically converts from mg/dL to mmol/L. So you must enter values reasonable for mg/dL (18 times higher than for mmol/L).

"},{"location":"version/code-custom-edits/#version-after-update","title":"Version after Update","text":"

This update, merged into dev on 2024 Feb 19 was part of a larger fix to a problem when glucose units were mmol/L. The user could not select two values (min and max) that were the same and equal to the reported absolute range. This was a rounding problem going between mmol/L and mg/dL that has now been resolved. Part of the resolution was to modify the mg/dL absolute ranges to preserve the previously reported mmol/L absolute ranges.

Code Before Modification

static let suspendThreshold = Guardrail(absoluteBounds: (66.1)...(110.9), recommendedBounds: (73.1)...(80.9), unit: .milligramsPerDeciliter, startingSuggestion: 80)\n

and

static let correctionRange = Guardrail(absoluteBounds: (86.1)...(180.5), recommendedBounds: (99.1)...(115.9), unit: .milligramsPerDeciliter, startingSuggestion: 100)\n

Modify the absoluteBounds to change the allowed ranges or the recommendedBounds to change the color of the numbers on the picker wheel.

Loop automatically converts from mg/dL to mmol/L. So you must enter values reasonable for mg/dL (18 times higher than for mmol/L).

"},{"location":"version/code-custom-edits/#modify-guardrails-for-insulin-sensitivity-factor-isf","title":"Modify Guardrails for Insulin Sensitivity Factor (ISF)","text":"

Similar to the instructions for glucose guardrails above, but use this Key_Phrase and modify the absoluteBounds row, next line.

Key_Phrase
static let insulinSensitivity = Guardrail(\n
  • Module: LoopKit
  • Folder: LoopKit/Extensions
  • File: Guardrail+Settings.swift, line: 81
  • Stable: Yes
"},{"location":"version/code-custom-edits/#modify-guardrails-for-carb-ratio-cr","title":"Modify Guardrails for Carb Ratio (CR)","text":"

Similar to the instructions for glucose guardrails above, but use this Key_Phrase and modify the absoluteBounds row, next line.

Key_Phrase
static let carbRatio = Guardrail(\n
  • Module: LoopKit
  • Folder: LoopKit/Extensions
  • File: Guardrail+Settings.swift, line: 88
  • Stable: Yes
"},{"location":"version/code-custom-edits/#adjust-future-carbs-time-interval","title":"Adjust Future Carbs Time Interval","text":"

Loop 3 limits to 1 hours the amount of time in the future that carbs can be entered.

  • The Loop and Learn: Customization Select Script has a customization that changes this to 4 hours in the future
  • If you want something other than 1 hour or 4 hours, you must create a personal customization

The customization varies depending on whether you are building dev or main.

  • Module: Loop
  • Stable: Changed on 2023 May 29

The main branch:

  • Folder: Loop/Loop/View Controllers
  • File: CarbEntryViewController.swift, Line 438

The dev branch:

  • Folder: Loop/Loop/Models
  • File: LoopConstants.swift, Line 28

The changes required for this customization have changed several time for dev. The code provided in Version after Update is for the latest dev code, as of 2023 Aug 20.

"},{"location":"version/code-custom-edits/#version-before-update_1","title":"Version before Update","text":"Key_Phrase
cell.datePicker.maximumDate = date.addingTimeInterval\n

Default shown below (for maximum and minimum):

Code Before Modification

cell.datePicker.maximumDate = date.addingTimeInterval(.hours(1))\ncell.datePicker.minimumDate = date.addingTimeInterval(.hours(-12))\n

Change the maximumDate to the number of hours in the future you desire. Remember that Loop may increase insulin dosing for future carbs - make sure that they actually arrive.

The minimumDate is how far back in the past you can modify time. The default is 12 hours in the past.

"},{"location":"version/code-custom-edits/#version-after-update_1","title":"Version after Update","text":"Key_Phrase
static let maxCarbEntryFutureTime\n

Default shown below:

Code Before Modification

static let maxCarbEntryFutureTime = TimeInterval(hours: 1)\n

Change the maxCarbEntryFutureTime to the number of hours in the future you desire. Remember that Loop may increase insulin dosing for future carbs - make sure that they actually arrive.

"},{"location":"version/code-custom-edits/#adjust-the-watch-crown-sensitivity","title":"Adjust the Watch Crown Sensitivity","text":"

The rate of change of the carb and bolus entry pickers when using the digital crown can be altered as can the rotation required to confirm a bolus on the watch. If you are running an older series watch - you may want to make these customizations. When I switched from Series 3 to Series 7 watch - it was amazing. I got a graph on the main watch screen I didn't even know existed and the bolus acceptance was a breeze!

  • The Loop 3 customization is provided from code inspection and one test - use with care.
"},{"location":"version/code-custom-edits/#loop-3-digital-crown-adjustments","title":"Loop 3 Digital Crown Adjustments","text":"

These are new instructions and the user should take care - and please report back if you have problems.

First - try it with no customization. Then make small changes.

This key phrase will indicate three different files in the same folder as shown in the graphic below - you can adjust each in turn as you desire. When you click on the line, the quantity you change is a few lines below where you find the Key_Phrase, except for the CarbAndDateInput file.

Key_Phrase
.digitalCrownRotation\n
  • Module: Loop
  • Folder: Loop/WatchApp Extension/Views/Carb Entry & Bolus
  • Stable: Yes

"},{"location":"version/code-custom-edits/#modify-bolus-confirmation-motion","title":"Modify Bolus Confirmation Motion","text":"
  • File: BolusConfirmationView.swift, line 59
  • Initial Value for scalingRotationBy is 4
  • Decrease to require less motion to confirm bolus (use whole numbers only), start with 3
"},{"location":"version/code-custom-edits/#modify-bolus-picker-sensitivity","title":"Modify Bolus Picker Sensitivity","text":"
  • File: BolusInput.swift, line 53
  • Initial Value for rotationsPerIncrement is 1/24
  • A change to 1/12 increases the change in picker value for a given motion
"},{"location":"version/code-custom-edits/#modify-carb-and-time-picker-sensitivity","title":"Modify Carb and Time Picker Sensitivity","text":"
  • File: CarbAndDateInput.swift, line 68
  • Initial Value for rotationsPerIncrement is 1/24
  • A change to 1/12 increases the change in picker value for a given motion
"},{"location":"version/code-custom-edits/#expiration-notification-customization","title":"Expiration Notification Customization","text":"

An expiration notification feature has been added to Loop. You get a notification when you open the Loop app to alert you that the expiration is approaching.

  • Read Loop App Expiration Notification to see the expiration reminder
  • Read Loop App Expiration Date if you have an older version of Loop

If you prefer a different notification time and frequency, there are two lines you can modify:

  • Module: Loop
  • Folder: Loop/Managers
  • File: ProfileExpirationAlerter.swift
    • Line 16: modify how long before expiration you get the FIRST notification
    • Line 28: modify how frequently you will be notified
  • Stable: Yes
Key_Phrase
expirationAlertWindow: TimeInterval\n
Key_Phrase
 minimumTimeBetweenAlerts: TimeInterval\n

Default code for line 16: 

    static let expirationAlertWindow: TimeInterval = .days(20)\n

Example modifications to First Notification:

  • 30 days: change .days(20) to .days(30)
  • 12 hours: change .days(20) to .hours(12)

Default code for line 28:

    let minimumTimeBetweenAlerts: TimeInterval = timeUntilExpiration > .hours(24) ? .days(2) : .hours(1)\n

Modify Frequency of Repeated Notifications (Three Values):

  • This phrase: > .hours(24) ? .days(2) : .hours(1)
  • Rewritten as: > Time_A ? Frequency_A : Frequency_B, means:
    • Use Frequency_A if there is more time between now and the expiration date than Time_A
    • Use Frequency_B if there is less time between now and the expiration date than Time_A

You can enter Time or Frequency as .days(value), .hours(value) or .minutes(value).

Free App Users:

An example change that a Free Loop App user (who has to build once a week) might choose is:

     > .hours(4) ? .days(10) : .hours(2)\n
Combined with an .hours(12) on line 16, they would get notified at 12 hours, 4 hours and 2 hours before expiration on the day of expiration and only when the app is opened. Since you'll be building once a week, you can play around with these values until you are happy.

"},{"location":"version/code-custom-edits/#enable-child-model","title":"Enable Child Model","text":"

Please see the Build-Time Flag page for this customization.

"},{"location":"version/code-custom-edits/#insulin-model-customization","title":"Insulin Model Customization","text":"

Each exponential model has 3 parameters that can be adjusted:

  • actionDuration: Duration of insulin activity (minutes)
  • peakActivity: Peak of insulin activity (minutes)
  • delay: Delay before insulin begins to acts after delivery starts (minutes)

Please read the nitty-gritty discussion that went into the development of the \"exponential insulin models\" in this Comment.

If you wish to customize these values, please make sure you know what you are doing. This is not a modification recommended for Loop novices.

Key_Phrase
MARK: - Model generation\n
  • Module: LoopKit
  • Folder: LoopKit/LoopKit/Insulin/ << NOTE new location
  • File: ExponentialInsulinModelPreset.swift
  • Lines:
    • actionDuration (19 to 32)
    • peakActivity (34 to 47)
      • delay (49 to 62)
  • Stable: Yes

This Loop 3 table of default values is provided for convenience. The times are all in minutes.

Model DIA Peak Delay rapidActingAdult 360 75 10 rapidActingChild 360 65 10 fiasp 360 55 10 lyumjev 360 55 10 afrezza 300 29 10"},{"location":"version/code-custom-edits/#loop-logo","title":"Loop Logo","text":"

Mac Instructions

This can be done with Build with Browser but the instructions might need to be adjusted for that case.

If you want an app logo other than the default green circle for your Loop app, you can easily customize this. To make it easy to generate the correct sizes of icons, you can use a site like appicon.build or appicon.co and just drag and drop your source image. The source image needs to be 1024 pixels x 1024 pixels. The site will email you a zip file or automatically download a set of files. Highlight and copy the contents of the Appicon.appiconset that you are sent, including the Contents.json file

  1. Navigate to the LoopWorkspace folder
  2. Open the OverrideAssetsLoop.xcassets folder
  3. Open the AppIcon.appiconset folder
  4. Delete the contents of the Appicon.appiconset and copy/paste your new images and Contents.json file.
  5. Rebuild your app

You may see a yellow warning that there are \u201cunassigned children\u201d depending on the images the app icon generator tool produced. The unassigned children alert will not prevent your app from building, it\u2019s simply because there are more sizes of images than Loop app uses. You can just leave the unassigned children alone (wow...how often do you get to say that phrase?).

And now you'll be the proud new owner of a custom Loop icon.

"},{"location":"version/code-custom-edits/#custom-edits-optional","title":"Custom Edits Optional","text":""},{"location":"version/code-custom-edits/#disable-authentication-for-bolusing","title":"Disable Authentication for Bolusing","text":"

Depending on your iPhone Settings and model, you may have Face ID or Touch ID enabled. Those security features will also be used to authenticate bolus delivery in Loop. You can choose to disable authentication (i.e., not require Face ID, Touch ID, or passcode for bolusing) through the following code customization.

Safety Measure

If you disable this, you are removing an important safety feature.

In addition to authenticating every manual bolus, this helps to protect against sleep bolusing and pocket bolusing.

For Loop 3, this controls the authorization requirement to modify Therapy Settings as well as to confirm bolus delivery.

Key_Phrase
canEvaluatePolicy(.deviceOwnerAuthentication\n
  • Module: LoopKit
  • Folder: LoopKit/LoopKitUI/Extensions/
  • File: Environment+Authenticate.swift, Line 20
  • Stable: Yes

Code Before Modification

if context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) {\n

Code After Modification

if false && context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) {\n
"},{"location":"version/code-custom-edits/#modify-override-insulin-needs-picker","title":"Modify Override Insulin Needs Picker","text":"

Some people want finer settings on the override insulin needs picker (5% instead of 10%) and may want to limit the overall range for overrides \u2013 especially for children.

1% Settings Available without Customization

With the advent of Loop 3, the Override Insulin Needs values are not limited by the default picker values of 10%.

  • Select 1% Insulin Needs

Any override more than a factor of 2 from 100% can cause Loop predictions to be wrong \u2013 especially if a carb count is entered. (An override is NOT the same as a manual temp basal - it changes insulin sensitivity factor and carb ratio in addition to the basal rate needed for zero change in IOB for the duration of the override.)

A Sensitivity of 0% is NOT Valid

Do not set the lower level of the sensitivity range to be 0%.

If you configure to allow that and someone chooses it, they will be telling Loop to divide by zero in some of the calculations. They will see NaN (not a number) in Loop predictions until that override is removed and will continue to see that for the full duration of insulin action (6 hours).

This example customization changes the lower bound for sensitivity to 50% (factor of 2 smaller than 100%) and provides 5% steps. This is the same as the prepared customization offered by the Loop and Learn team.

Key_Phrase
let allScaleFactorPercentages\n
  • Module: LoopKit
  • Folder: LoopKit/LoopKitUI/Views
  • File: InsulinSensitivityScalingTableViewCell.swift, Line 19
  • Stable: Yes

Code Before Modification

private let allScaleFactorPercentages = Array(stride(from: 10, through: 200, by: 10))\n

Code After Modification to 50% to 200% by steps of 5%

private let allScaleFactorPercentages = Array(stride(from: 50, through: 200, by: 5))\n
"},{"location":"version/code-custom-edits/#modify-maximum-and-warning-carb-entry","title":"Modify Maximum and Warning Carb Entry","text":"

Version 3.x of the Loop app has both a maxCarbEntryQuantity and a warningCarbEntryQuantity, found adjacent to each other in the code. The warning value is the level at which you are asked if you really meant to enter that amount:

Key_Phrase
let maxCarbEntryQuantity =\n
  • Module: Loop
  • Folder: Loop/Loop/Models
  • File: LoopConstants.swift, line 18
  • Stable: Yes

Code Before Modification

static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 250) // cannot exceed this value\n\nstatic let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 99) // user is warned above this value\n
"},{"location":"version/code-custom-edits/#low_carb_limit","title":"\"low_carb_limit\"","text":"

This first example might be used by a parent for a child with very small carb entries. It is provided as one of the prepared customizations supplied by the Loop and Learn Customization as \"low_carb_limit\".

Code After Modification to enable the warning at lower levels and limit maximum

static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 99) // cannot exceed this value\n\nstatic let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 49) // user is warned above this value\n
"},{"location":"version/code-custom-edits/#high_carb_limit","title":"\"high_carb_limit\"","text":"

This second example might be used by a person who routinely enters large meals and does not want to be warned with every meal. It is provided as one of the prepared customizations supplied by the Loop and Learn Customization as \"high_carb_limit\".

Code After Modification to warn if entry is between 201 and 300g

static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 300) // cannot exceed this value\n\nstatic let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 200) // user is warned above this value\n
"},{"location":"version/development/","title":"Loop Development","text":""},{"location":"version/development/#overview","title":"Overview","text":"

The early history of the Loop app was touched on in the introductory LoopDocs Overview: Development History section.

The Loop Releases page lists releases since version 2.0 in reverse chronological order.

The next version of the Loop app is developed using branch(es), independent of the released Loop version, which is found in the main branch. The dev branch is used by the developers to push out changes for users to test. You should only test a development branch if you are willing to be both an active participant with the developers to monitor announcements and provide feedback and to build frequently to obtain the latest feature or bug-fix that is being tested. If you are willing to help out - this is the way the next release of Loop is improved.

If you choose to use dev, you accept that this code is not released.

Please read this entire page before using any version of Loop other than the released code.

"},{"location":"version/development/#updates-in-dev","title":"Updates in dev","text":"

This section is an early look at what has been added to dev since Loop 3.2.x\u00a0and will probably be in the next release. After the release, some of the content and graphics in this section will move to the Releases page or the appropriate documentation section.

  • Support for Libre Sensors
  • Modified Simulator Interface
  • Algorithm Experiments
    • Glucose Based Partial Application\u00a0 Factor
    • Integral Retrospective Correction
  • Favorite Foods
  • Updates to Omnipod User Experience
    • Insert Cannula Slider
  • TestFlight Expiration Warning
  • GitHub Browser Build\u00a0 Updates
  • Miscellaneous Code Fixes
"},{"location":"version/development/#support-for-libre-sensors","title":"Support for Libre Sensors","text":"

LibreTransmitter support was merged into the dev branch in July 2023.

If you are using the GitHub / Browser Build method, please review:

  • Browser Build: One-Time Changes: New steps and dates at which the new steps were added
"},{"location":"version/development/#modified-simulator-interface","title":"Modified Simulator Interface","text":"

The simulators for the Pump and CGM, for the dev branch show a new format when first selected. The initial view is a demonstration screen showing a typical CGM or Pump display. In order to view behind the scenes, modify settings, and delete the simulator, you must press and hold (long-press) on the top of the display. Anywhere in the top third works for the long-press, but I like to touch the card as shown in the pump example below. If you've counted to 10 and the display has not updated yet, then return to the main screen, go back to the simulator screen, and try again.

"},{"location":"version/development/#algorithm-experiments","title":"Algorithm Experiments","text":"

Two algorithm experiments have been added to dev. These are \u00a0Glucose Based Partial Application\u00a0 and \u00a0Integral Retrospective Correction. They can be viewed on the Loop Settings screen just below Therapy Settings and Usage Data Sharing as shown in the graphic below:

"},{"location":"version/development/#glucose-based-partial-application-gbpa","title":"Glucose Based Partial Application\u00a0 (GBPA):","text":"
  • Originally proposed in Pull-Request 1988 for Loop.
  • It is only used when Automatic Bolus (AB) is selected for Dosing Strategy
  • This modification does not affect the recommended dose, only how quickly the recommended dose is automatically delivered

When AB is selected and GBPA is enabled, the percentage of the recommended dose delivered per cycle of \u00a0Loop\u00a0 ranges from 20% to 80% based on glucose level and user-selected correction range. (Without GBPA enabled, AB uses a fixed 40% percentage regardless of glucose level.)

  • Partial Application = 20% when glucose is at or below the users correction range lower value (including overrides) plus 10 mg/dL (0.6 mmol/L)
  • Partial Application increases linearly from 20% to 80% up to a glucose level of 200 mg/dL (11.1 mmol/L)
  • Partial Application is 80% when the glucose level is above 200 mg/dL (11.1 mmol/L)
"},{"location":"version/development/#insulin-delivery-using-gbpa","title":"Insulin Delivery Using GBPA","text":"

Loop makes a prediction and recommends an insulin dose based on your settings and your glucose, insulin and carb history. The selected Dosing Strategy (Automatic Bolus with or without GBPA or Temp Basal Only) only changes how quickly that recommended dose is delivered.

This example assumes Loop recommends 1 U (at time 0) and future glucose values match Loop's prediction for each successive 5-minute update. In other words, over half an hour, Loop provides about 1 U of insulin above that delivered by the scheduled basal rate.

The tables below show Automatic Bolus patterns, using a pump minimum bolus increment of 0.05 U, for several application factors. When using GBPA, the application factor can vary with glucose, but that is ignored for this simplified example.

The first table shows the bolus delivered each Loop cycle for several application factors. Higher application factors start with higher boluses, but go to zero (indicated by a dash) more quickly.

Incremental Dose for several application factors when initial recommendation is 1 U

Minutes 20% 40% 60% 80% 0 0.20 0.40 0.60 0.80 5 0.15 0.25 0.25 0.15 10 0.15 0.15 0.10 0.05 15 0.10 0.10 0.05 - 20 0.10 0.05 - - 25 0.05 - - - 30 0.05 - - -

The second table shows the cumulative delivery. A dash shows recommended dose was delivered. Remember, this is a simplified example.

Cumulative Dose for several application factors when initial recommendation is 1 U

Minutes 20% 40% 60% 80% 0 0.20 0.40 0.60 0.80 5 0.35 0.65 0.85 0.95 10 0.50 0.80 0.95 1.00 15 0.60 0.90 1.00 - 20 0.70 0.95 - - 25 0.75 0.95 - - 30 0.80 0.95 - -

The 20% and 40% application factor columns did not reach 1 U in 30 minutes because the requested dose is smaller than this pump will deliver. The 60% application factor only reached 1 U because tiny doses down to 0.03 U were rounded up to 0.05 U.

The Temp Basal Only Dosing Strategy provides about 17% of the recommended bolus each 5-minute interval. The minimum GBPA application factor of 20% was selected to be similar to that rate for lower glucose values. Initially, an application factor of 20% delivers insulin more quickly than Temp Basal Only, but by the end of 30 minutes, the basal program inside the pump keeps track of how much is delivered to reach the rate requested, achieving the full 1 U (for this example).

"},{"location":"version/development/#integral-retrospective-correction-irc","title":"Integral Retrospective Correction\u00a0 (IRC):","text":"
  • Originally proposed in Loop Issue 695
    • This was tested in a few forks but not included into dev until recently
    • Initial merge into dev: Loop PR 2008
  • Updated with a modification to limit stacking of IRC with Glucose Momentum: Loop PR 2028
  • Integral Retrospective Correction, when enabled:
    • changes the Loop app prediction model and thus can affect the recommended dose
    • applies to both Dosing Strategies: Temp Basal or Automatic Bolus

Referring to the Algorithm: Prediction page:

  • When IRC is disabled (default), the equation used to predict glucose continues to be:
\\[ BG[t] = Insulin[t] + Carb[t] + RetrospectiveCorrection[t] + Momentum[t] \\]
  • When IRC is enabled that equation changes to:
\\[ BG[t] = Insulin[t] + Carb[t] + IntegralRetrospectiveCorrection[t] + Momentum[t] \\]

Note that the Momentum\u200b term does not just add to the other effects; it is actually more complicated (and also more challenging to describe in simple math terms).

The Retrospective Correction section of the Predicted Glucose Chart is updated when IRC is enabled, as shown in the graphic below. The Integral effect, inside the lower blue rectangle, is the difference between the IRC and RC calculations.

The IRC term is described in this (updated) comment including plots and equations. Some of the information in that comment is repeated below: Important points about IRC.

If you want to look at the code, the version (as of 14-Aug-2023) is found in LoopKit/LoopKit:

  • RetrospectiveCorrection code: StandardRetrospectiveCorrection.swift
  • IntegralRetrospectiveCorrection code: IntegralRetrospectiveCorrection.swift
"},{"location":"version/development/#important-points-about-irc","title":"Important points about IRC","text":"

  1. Known risk factors compared to standard Loop:

    • With IRC turned on, Loop will likely increase insulin corrections in response to persistent discrepancies between observed and predicted glucose motion, which may increase the risks of hypoglycemia
    • IRC may also lead to increased oscillations (\"roller-coaster\") in glucose responses
    • Both of these risk factors are higher if the user's setting value for Insulin Sensitivity (ISF) is too low
    • Increasing ISF setting value tends to mitigate these risks but it is impossible to offer any guarantees for anything around T1D

  2. Compared to standard RC, IRC is more likely to improve glucose control in the following scenarios:

    • Glucose remaining high or decreasing slower than expected due to temporarily reduced insulin sensitivity or poor site absorption
    • Glucose trending low faster than expected due to temporarily higher insulin sensitivity
    • Glucose spikes due to unannounced meals
    • Glucose remaining high (or trending low) on tail ends of meals where carbs entered were underestimated (or overestimated)
    • Glucose remaining elevated due to unannounced protein+fat effects
    • Glucose staying above (or below) the correction range due to too low (or too high) basal rate settings

  3. In some scenarios IRC does not differ from standard Loop RC

    • Regardless of the current glucose level, neither RC nor IRC is adding to the glucose forecast during the times when the absorption rate of announced carbs is greater than the minimum absorption rate.
    • Neither RC nor IRC effects depend on glucose level; both depend on discrepancies between predicted and actual glucose responses.

  4. Please do not expect immediate or very substantial improvements in blood glucose control. A one-time success after turning IRC on does not really mean that IRC \"works\" - this could just as well be a temporal coincidence. Some ways to decide if IRC could be safe and effective for you include:

    • Responses to unannounced meals - spikes should in general be somewhat lower than those with standard Loop, but there should also be no follow-up lows
    • Nighttime responses over a few weeks - highs or lows should be less frequent compared to the standard Loop; at the wake-up time blood glucose should, in general, be closer to the correction range.
"},{"location":"version/development/#favorite-foods","title":"Favorite Foods","text":"

This feature allows you to save Favorite Foods.

A new row on the\u00a0Loop\u00a0app Settings screen, see graphic below, provides access to create and edit your \u00a0Favorite Foods.

In the example meal entry shown below:

  1. The Favorite Food row (at the bottom) is tapped
  2. The desired Favorite Food is selected

At this point the meal can be saved by tapping the Continue button, or the user can modify the time (typical) or any other of the carb entry rows before tapping Continue.

"},{"location":"version/development/#testflight-expiration-warning","title":"TestFlight Expiration Warning","text":"

The\u00a0Loop\u00a0app has been updated to detect whether the build was uploaded through TestFlight, which implies a 90-day limit until the app expires.

The usual\u00a0Loop\u00a0expiration notification system alerts the user when within 20 days of expiration. In addition to that modal alert, the user can examine the bottom of the Settings screen at any time to see the expected expiration date and time.

"},{"location":"version/development/#github-browser-build-updates","title":"GitHub Browser Build\u00a0 Updates","text":"

The dev branch has several updates merged that make it easier to find errors in configuration and that make the \u00a0GitHub Browser Build\u00a0 automatic.

Note that the automatic build feature is opt-out. In other words, unless you take specific steps, the \u00a0GitHub Browser Build\u00a0 for\u00a0Loop\u00a0will:

  • Automatically build a new version once a month, with automatic update included
  • Automatically update your fork of LoopWorkspace once a week if updates are available

It is suggested that all users of the released code (main branch), maintain this automatic schedule so they are never without a valid and up-to-date\u00a0Loop\u00a0in their TestFlight app.

For users of the dev branch, it is not uncommon to disable the automatic update portion so they can choose when to update their development version, but should probably keep the monthly build portion of the process.

  • Configure GH_PAT
  • Modify Scheduled Building and Synchronization

In addition to the easier to read error messages found with these updates, these additional simplifications include:

  • Actions are broken into logical components, each of which provides an easy to understand error message if it fails which includes a suggested fix
  • A new builder no longer needs to create the \u00a0Match-Secrets repository
    • If it does not exist, one is created for you
    • Only the App Group ID must be added to the Identifiers; all other App services are automatically added
  • For new builders and current 3.2.2 users updating to the next release
    • The \u00a0alive branch needed to enable automatic building is created automatically
    • If their GH_PAT does not have repo, workflow permission, a prominent message is displayed with each Action completed

These sections are still useful for version 3.3.0 dev users:

  • Browser Build for dev: How to use \u00a0GitHub Browser Build\u00a0 for dev branch
  • Browser Build: One-Time Changes: New steps and dates at which the new steps were added
"},{"location":"version/development/#miscellaneous-code-fixes","title":"Miscellaneous Code Fixes","text":""},{"location":"version/development/#g7-sensors-duplicate-cgm-values","title":"G7 Sensors: Duplicate CGM Values","text":"

Fixed with PR 16: Fix parsing of age field of message

  • Most sensors report the time with very little offset between time of arrival and time of sensing
  • If the time discrepancy is large, the error (using one byte instead of two for age of the reading) could cause CGM values to appear as duplicate readings in Loop
"},{"location":"version/development/#remote-services-update","title":"Remote Services Update","text":"

The code that feeds Loop data to remote services like Tidepool and Nightscout have been improved to be more robust.

"},{"location":"version/development/#what-are-git-branches","title":"What are Git Branches?","text":"

There is a lot of discussion about branches with Loop but the concept is simple. Basically, they are all slightly different versions of Loop...kind of like different edits of the same book.

To really understand what branches are, we should probably explain a little more about the software and how development works. You can watch a 30-minute long, classic Katie DiSimone video explanation about branches created when Loop Version 2.0 was newly released. Keep in mind while watching the video that master was the old name for the main branch. The information in this video is still generally useful with the last half focused on automatic-bolus - the automatic-bolus dosing strategy has now been incorporated into Loop main branch. Loop has moved on to using only one stable branch (main), with dev suggested for developers/testers.

"},{"location":"version/development/#loop-github-information","title":"Loop GitHub Information","text":"

Loop developers own an account in GitHub called LoopKit. Within that account, the developers have several repositories that support Loop in particular. A repository\u200b is like a book...let's think of it like a cookbook for now. Within the LoopKit account, there are repositories for Loop\u200b itself, LoopDocs, and various other supporting \"frameworks\" that are helper \u200brepositories\u200b for Loop to build correctly. For example, Loop's \u200brepository\u200b has a lot of info about the app itself; the outward-facing things that you interact with. How information is put to you and taken in from you...that's in Loop repository code. But, there's more than just a user interface for Loop. Loop has to do a lot of complex work like Bluetooth communications, algorithm math, pump communications, etc. The Loop app has help from frameworks to do those other parts. CGMBLEkit\u00a0 for some of the transmitter parts of Loop, RileyLink_ios for the pump managers (talking to the pumps and decoding their information), LoopKit for the algorithm about carbs and insulin curves, etc.

When you build Loop, in the background, Loop pulls those other frameworks (7 in total) into the build process using Carthage. Carthage\u00a0 is like a personal shopper. You give it a shopping list (the cart file in Loop code is that shopping list) and it goes and fetches that for you during the build process. Sometimes your computer has an old shopping list...and that can cause build errors. Hence the carthage update fix in the Build Errors page...that command updates the shopping list to get the right versions of those frameworks.

Anyways...so now you know about the general structure of Loop and LoopKit in GitHub. Now we can discuss Loop itself a little deeper.

So let's imagine Loop as a cookbook. The developers are the authors/chefs of the recipes (code) in the cookbook. The authors spend countless hours testing new recipes, taste testing, and documenting improvements. They send the drafts to the editor, who makes suggestions and eventually, the cookbook is finalized. There are no grammar issues, and no typos, the photos are beautiful and the recipes are yummy. They publish the book and you see a gorgeous final product on the shelves. That is called a release\u200b, and it is the main branch. This book has been well-tested and is super stable. Every time you cook with those recipes, you know exactly what you're getting and lots of people have had a chance before you to make sure that it all tastes good. The main branch is stable and tested.

But then...the chefs/developers go on a trip. They are inspired by new cuisine and want to add new recipes to the old cookbook. (Things like Omnipod\u200b support and the overrides are new \"recipes\" that were developed since the last main release, for example.) But, the process of developing a recipe is arduous. There was a lot of trial and error involved. Lots of tweaking ingredients (code). The editors try out the new recipes and offer feedback (similar to the Issues List on GitHub). While the recipes are being developed, they have a version of the old cookbook that gets marked up...edited in pencil a lot. Scribbles and notes in the side. Revisions happen frequently because that's what testing new recipes is all about. These marked-up versions of the cookbook are called the dev branch. Short for \"development\" branch. Like the name sounds...this is where new developments are happening, new recipes, and tweaks.

After much testing and tweaking, eventually, the recipes get the flavors right (bugs in code are squashed) and enough people have provided feedback and careful observations of results...that the book goes to the publishing house for the next printing. The cookbook is republished with an updated edition number and new recipes are highlighted. When this happens in Loop, Loop's main branch is updated with the new features coming from dev (aka, the dev branch is merged into the main branch). When that happens, the main branch gets another release version. At this point, dev and main are identical. They remain so until the development team for Loop\u00a0 starts working on the next batch of improvements, which could be in the next hour or even days later, but then the cycle starts again. The developers will start editing the code again and dropping those edits in the dev branch for further development.

"},{"location":"version/development/#whats-going-on-in-the-dev-branch","title":"What's going on in the dev branch?","text":"

The dev branch, currently v3.3.0, is where the next version of Loop is being developed and tested.

If you choose to build Loop using a dev branch, you need to be aware that the dev branch may update code frequently and unannounced in the traditional sense that most users in the Looped group or Instagram would see. Developers are not helped by people being in a dev branch if those users mistakenly think of it as a stable main branch with lots of detailed docs to go with it. People should only use a dev branch build if they EDUCATE themselves on the expectations and how to properly manage dev information and updates. People using the dev branch should also have regular access to a computer to be able to rebuild quickly if a new bug/fix is identified.

If you choose to use a dev build, you can stay abreast of developments in a number of ways...but they will all require you to do some legwork and keep yourself informed. This is not a situation where you should expect a fancy Loopdocs page updated regularly with current \"dev updates\"...that's just not the way the dev branch works (at least normally).

"},{"location":"version/development/#subscribe-to-the-zulipchat-channels","title":"Subscribe to the Zulipchat channels","text":"

Use Zulipchat forums for Loop. This forum has several streams of conversations (streams) depending on interest. I highly recommend following all the streams so you do not miss conversations. You can select by stream and by topic within a stream to focus on a given conversation.

Zulip Chat Streams

  • If you are using the dev branch, you must be in the #development stream.
  • If you want to know when LoopDocs gets updated, follow the #documentation stream.
  • Code changes are called commits in GitHub. The #github stream will have an automated post whenever a new commit is made and it will give a brief line description of the commit.

You can also go directly to the git commit history for each of the branches if you'd like.

  • Loop main branch: git commit history
  • Loop dev branch: git commit history

If you click on the commit, you can see exactly what changes to the code were made. It's an interesting learning experience. In red is the old code, and in green is the updated code. The line numbers and file names of the edited code are also there to help.

I don't expect many of you would understand exactly what the edits mean, or how the new code might function. However, I bring up the topic of git commit history so that you can use that to realize just how often the dev branch is updated. Go ahead and look at the number and frequency of commits in that branch. That's why no one would want to maintain a documentation list of the changes in the dev branch. It's just too much of a moving target.

"},{"location":"version/development/#watch-the-loop-repository-and-issues-list","title":"Watch the Loop Repository and Issues List","text":"

Open the Loop repository and subscribe to the Issues.

You can choose to watch the repository so that you get emails when new Issues are reported. This is a good way to find out if other people are reporting odd behavior that you are wondering about. If you use dev and wonder about something you are seeing in Loop, you can check Issues list to see if others are noticing the same. If so, you can help by capturing information and reporting it. Not super helpful to just say \"Yeah, me too...\" but better if you can attach screenshots, Issue Reports from Loop settings, and a thorough description of the problem you are seeing. Be a part of the solution by thoughtfully providing information to help debug.

"},{"location":"version/development/#keep-checking-looped-group","title":"Keep checking Looped group","text":"

Keep watching The Looped Group on Facebook. Major concerns/issues are brought up there...so it doesn't hurt to scroll through and see what's going on there.

"},{"location":"version/development/#become-familiar-with-your-data-sources","title":"Become familiar with your data sources","text":"

Another useful thing if you'll be on dev branches undergoing a lot of active change...know how Loop works and where to look for additional information about what you are seeing. For example, if you see an IOB value that looks odd, you should know to look at the insulin deliveries stored in the Health app.

"},{"location":"version/development/#generate-an-issue-report","title":"Generate an Issue Report","text":"

Know how to generate an Issue Report when you see a problem so you can provide that if asked. An Issue Report is a log file generated by the Loop app that has a lot of information the developers can parse to figure out what Loop was doing when you were having a problem.

  • Loop v2.2.9\u00a0 and earlier:Loop Settings -> Issue Report
  • Loop 3\u00a0 and later: Loop Settings -> Support -> Issue Report

Do not confuse this with reporting an issue with Loop. That is done by logging into GitHub and going to the Issue page to report a new issue. You can read about existing issues without logging in, but to report a new one, you must log in to GitHub.

"},{"location":"version/development/#create-a-debug-report","title":"Create a Debug Report","text":"

This 6-minute long, classic Katie DiSimone video shows how to capture debugging logs. If you are testing a new branch, this is a valuable skill to assist developers in identifying problems. In addition to showing you how to generate and save the debug text information, the video explains how to create a gist with the debug information using your GitHub account and file an official Issue on the Loop GitHub repository. This may be required in some cases. But start by chatting directly on Zulipchat with the developer. What you are experiencing may already be known. If the developers need you to open a new Issue, they will say so on Zulipchat.

"},{"location":"version/development/#repositories-and-code","title":"Repositories and Code","text":"

If you're a developer looking for direct links to the code and documentation in GitHub:

  • Loop
  • LoopDocs

For more information on how to contribute code to the Loop project, please review:

  • How to Contribute to Open Source
  • the LICENSE
  • the CODE_OF_CONDUCT

If you want to contribute code improvements, please join Loop Zulipchat and be sure to subscribe to all the channels. Meet the developers and testers who make this app, and learn about what is coming next.

"},{"location":"version/loopworkspace/","title":"LoopWorkspace","text":""},{"location":"version/loopworkspace/#loop-workspace","title":"Loop Workspace","text":"

This page is for the advanced user. It is a short introduction for folks interested in testing code before it is released, or contributing to that code.

If you wandered over here meaning to build the latest Loop release, the rest of this page might be interesting but you should not follow any of the steps. Head back over to Build Loop App when you are ready to build the app.

LoopWorkspace is now used for all Loop Builds

  • With the release of Xcode 13, Loop builds require LoopWorkspace
  • Loop old-timers may remember the zip-download method - it is no longer available
  • For all Loopers who want the latest
    • Loop Release
    • Follow the step-by-step instructions found at Build Loop App

The typical user who wants to build Loop does not need to know the level of detail on the rest of this page.

"},{"location":"version/loopworkspace/#new-way-to-sign","title":"New Way to Sign","text":"

One of the recent changes to LoopWorkspace is the addition of the file: LoopConfigOverride.xcconfig to the LoopWorkspace folder. The contents of this file are shown in the graphic below.

There are several ways to use this to sign the targets automatically.

  1. Edit the line highlighted by the red rectangle to remove the comment marks (//) from the beginning of the line and replace the indicated TeamID (UY678SP37Q) with your own Team ID
  2. For developers who may have more than one clone for various testing, note the first line of that file, highlighted by the blue-dashed rectangle
    • If a LoopConfigOverride.xcconfig exists up two levels from the current LoopWorkspace folder, it will be included
    • Use a directory structure for clones similar to the example shown in the graphic below where clones were created under ~/Downloads/ManualClones.
    • Make a copy of the LoopConfigOverride.xcconfig in the ~/Downloads/ManualClones folder (from any LoopWorkspace folder) and edit that version with your TeamID
    • All future clones created in this directory grouping are then automatically signed
  3. For users of the Build Select Script, the script automatically generates the copy of LoopConfigOverride.xcconfig in the ~/Downloads/BuildLoop folder the first time the script is run, guides the user into adding their TeamID and then, in subsequent downloads, uses that previously created file

"},{"location":"version/loopworkspace/#team-id","title":"Team ID","text":"

Your Apple Developer ID is the 10-character Team ID found on the Membership page after logging into your account at: https://developer.apple.com/account/#!/membership.

"},{"location":"version/loopworkspace/#what-is-git","title":"What is git?","text":"

Git is a system of \"distributed version control\" that allows remotely (as in not located in the same place) collaborating people to work on one project and still track their changes to the same place. For example, if I sent 5 people one document to proof-read at the same time...it is quite possible that the edits I will get back from those 5 people would conflict with each other. Bob may have entirely deleted a sentence while Mary would have added words to that sentence. Git lets these remotely collaborating people deal with \"resolving conflict\" between versions more easily and merging suggestions (pull requests) into a coordinated space.

So, in using git, we can do things with \"git commands\". Like \"Hey git...make me an exact copy of that guy's work over there.\" or \"Hey git, I'd like to compare my version of this page with Joe's version of the same page.\" Or using my old cookbook analogy...\"Hey git, I'd like to start a new cookbook called Italian Desserts.\"

But yes, git commands take awhile to properly use. And they are not plain English-friendly.

"},{"location":"version/loopworkspace/#what-is-loopworkspace","title":"What is LoopWorkspace?","text":"

There is more information in Loop Development that is not repeated here.

The important fact for this discussion on LoopWorkspace is that Loop developers own an account in GitHub called LoopKit. Within that account, the developers have several repositories that support Loop in particular. A repository is like a book...let's think of it like a cookbook for now. Within the LoopKit account, there are repositories for Loop itself, LoopDocs, and various other supporting \"frameworks\" that are helper repositories for Loop to build correctly. For example, Loop's repo has a lot of info about the app itself; and the outward-facing things that you interact with. How information is put to you and taken in from you...that's in Loop repository code. But, there's more than just a user interface for Loop. Loop has to do a lot of complex work like Bluetooth communications, algorithm math, pump communications, etc. The Loop app has help from frameworks to do those other parts. CGMBLEkit for some of the transmitter parts of Loop, RileyLink_ios for the pump managers (talking to the pumps and decoding their information), LoopKit for the algorithm about carbs and insulin curves, etc.

When you build Loop from LoopWorkspace, each of those repositories is downloaded to your computer. This is slower than the old zip-download as far as downloading Loop - but it is much faster when you build Loop because all the files are already on your computer.

LoopWorkspace uses submodules to define how the frameworks are coordinated for building. The graphic below shows the dev branch at a particular point in time. The precise version, or commit, of each submodule is defined by 7-character hexadecimal codes (look up SHA-1) with the repository for each submodule defined in a text file called .gitmodules.

  • Several key git and other operating system commands will be provided later to assist you
  • These commands will not be explained in detail
  • If you want to know more, search the internet for documentation
  • Often a series of commands is shown on one line, separated by semicolons

The commit identifier for each submodule is important because that repository can be modified after things are set up and working with Loop. When you download the code from that repository you want the exact version that was tested.

  • Later on there will be information about determining your git branch for a given submodule
  • You'll see language: (HEAD detached at #)
  • That # is the commit identifier for the submodule

The commit for the LoopKit submodule is highlighted by the red rectangle in the graphic below. Advanced users testing the dev branch (or other branches or forks) need to know how to tell if their current download is up-to-date.

"},{"location":"version/loopworkspace/#clone-loopworkspace","title":"Clone LoopWorkspace","text":"

To get that LoopWorkspace code to your computer, first open a terminal. Make sure your current path name does not have any embedded spaces. If it does, you will get errors on your build.

If you don't know how to open a terminal and navigate to a directory, reconsider whether you are ready for this page.

You need to use a git clone command LIKE THIS (but not exactly the same...you're going to edit the branch-name part in there):

git clone --branch=branch-name --recurse-submodules https://github.com/LoopKit/LoopWorkspace

Now...look carefully and notice two things...that command (1) is getting the version of LoopWorkspace found in the LoopKit repository and (2) selects the branch you want to start working with when the clone is done.

So, you will need to edit that branch-name before using the command so that you are getting started with the branch you want. If you want to clone from a different fork, the LoopKit will be replaced with the name of the GitHub site for the fork. For example, to test the dev branch (which is under development and has some cool new architecture and features), you would copy/paste:

git clone --branch=dev --recurse-submodules https://github.com/LoopKit/LoopWorkspace\n
"},{"location":"version/loopworkspace/#start-xcode-using-command-line","title":"Start Xcode using command line","text":"

If you want to start the build from the command line, enter the following 2 lines into the terminal.

cd LoopWorkspace\nxed .\n

Remember the warning - if you build the dev branch on your phone from Loop main, it should work fine. Going backward, please delete the app from your phone and enter all your settings again to return to main.

"},{"location":"version/loopworkspace/#start-xcode-using-finder","title":"Start Xcode using Finder","text":"

The cloned version of the LoopWorkspace will go into the current directory in the Terminal app when you execute the command. Terminal app opens in your User account home directory by default when you first open it. Unless you changed to a different directory, check your home directory for the LoopWorkspace folder.

How can you find your home directory?

  1. In Terminal, if you use cd that will take you there automatically.
  2. In Finder, Shift+Cmd+H will open your home folder.

There are a lot of cloned things in this home directory that involve Loop. You may have fewer...but be aware, you can always delete and reclone if you are in doubt or confused. You can also set up a special directory to hold the cloned code - just make sure there are no embedded spaces in the full path name.

For this graphic, the cloned LoopWorkspace is in the home directory.

Loop to LoopWorkspace in dev

Note that the directory Loop.xcworkspace has been renamed to LoopWorkspace.xcworkspace in the dev branch. This change makes LoopWorkspace the default target to simplify the build process.

The words will be updated with the next release. It may take more time for the figures to be updated.

  1. Open Finder and navigate to the location that has LoopWorkspace
  2. Open the LoopWorkspace folder
  3. Search for and double-click on the LoopWorkspace.xcworkspace folder - this automatically opens the Workspace in Xcode

  • Enter your Apple Developers ID in the LoopConfigOverride.xcconfig file that now appears in the top of the folder list (not shown in this graphic)
  • This automatically signs the 5 targets required for the dev branch
  • Choose your device
  • Tap on the build (play) button to build to your selected device
"},{"location":"version/loopworkspace/#updating-loop-using-loopworkspace","title":"Updating Loop using LoopWorkspace","text":"

When it's time to update the copy of LoopWorkspace on your computer - you have choices. You can use the method below or redo the whole cloning process.

Be sure your terminal is in the correct location using Open a Terminal in LoopWorkspace Folder

  1. Make sure you are in the correct branch using this git command: 
    git branch\n
  2. If you are not in the correct branch, for example, dev, then issue this git command (suitably modified for the desired branch) 
    git checkout dev\n
  3. Use the following git commands in the LoopWorkspace folder of your terminal: 
    git fetch\ngit pull --recurse\n

If you are testing the LoopKit dev branch, you need to be on zulipchat and subscribe to at least the #development and #github streams. (It's a good idea to subscribe to all the streams.) When you see repository updates similar to the graphic below, there may also be an announcement in the #development channel that LoopWorkspace is updated and ready to test. If not you can check the commits in LoopWorkspace and see if they've been updated. It's a good idea to wait 24 hours. My procedure is to build dev to my backup phone and then put it on my \"real\" phone. Otherwise, wait for someone else to do it and give the all-clear in zulipchat.

"},{"location":"version/loopworkspace/#updating-loop-to-a-specific-loopworkspace-commit","title":"Updating Loop to a Specific LoopWorkspace commit","text":"

Sometimes, you know a feature you want was added at a specific commit number; however, you know there are other changes later than that commit which you do not want to test. There is a solution.

Be sure your terminal is in the correct location using Open a Terminal in LoopWorkspace Folder. First you have to bring down all the latest dev commits. Then you will back up to the one you want.

  1. Make sure you are in the correct branch using this git command: 
    git branch\n
  2. If you are not in the correct branch, normally the desired branch is dev, then issue this git command (suitably modified for the desired branch) 
    git checkout dev\n
  3. Use the following git commands to bring down all the newer commits to your copy: 
    git fetch\ngit pull --recurse\n

  4. Now you want to \"backup\" to the desired commit:

    • You will need to figure out what that commit should be - there is no copy button here - you need to create this line yourself with the correct commit:
    git checkout <desired commit here>\n
    • Once you have checked out the correct commit, assuming there were no errors, you need to update all the submodules to that commit with this command (which you can copy and paste)
    git submodule update\n

  5. Assuming there were no errors, see Local Modifications Conflict, in the process above, you can now build that commit.

"},{"location":"version/loopworkspace/#build-following-update","title":"Build Following Update","text":"

Sometimes there is a change to the Workspace scheme in Xcode that interferes with building following an update to your local clone. In those cases, these steps typically work. Try the first one, and if that doesn't work, try the first two, etc. Only after trying all three should you post asking for help on zulipchat.

  1. In Xcode Menu, select Product->Clean Build Folder
  2. In Xcode Menu, select File->Close Workspace and then File->Open Recent and select top line (one you just closed)
  3. Quit Xcode and delete derived data, then reopen Xcode (you may need to resolve package versions again)
"},{"location":"version/loopworkspace/#delete-derived-data","title":"Delete Derived Data","text":"

This command deletes derived data stored across all workspaces and projects by Xcode on your computer. If you have multiple clones locally, it deletes derived data from all of them. The derived data will be regenerated next time you build with Xcode using that clone.

Copy and paste this command into a terminal window.

Copy and Paste to Delete Derived Data
rm -rf ~/Library/Developer/Xcode/DerivedData\n
"},{"location":"version/loopworkspace/#compare-your-local-clone-to-loopworkspace","title":"Compare your local clone to LoopWorkspace","text":"

In an ideal world, LoopWorkspace has the most recent compatible submodule identifiers revised at the same time the submodules are updated. You will notice the commit identifiers for the updated submodules are different from the ones you have locally.

You can check your current submodules with the git submodule status command in the LoopWorkspace folder of your terminal:

What are those super-long numbers? Those are the actual SHA-1 (remember - look it up) for the commits. But the first 7 characters are sufficient to uniquely identify the commit you need for the repository and branch identified in .gitmodules. So compare the first 7 characters to the LoopKit / LoopWorkspace number and you know whether you need to update or not.

To determine the commit for a single submodule on your computer, use the following commands in the LoopWorkspace folder:

  cd <submodule-name>; git branch; cd ..\n

The response will be similar to this exchange:

  cd rileylink_ios; git branch; cd ..\n
  * (HEAD detached at 2541c1c)\n    dev\n

The asterick indicates the branch that is currently checked out (active).

The phrase * (HEAD detached at #) allows you to compare your local version with the commit identifier on github.

"},{"location":"version/loopworkspace/#loopworkspace-unchanged","title":"LoopWorkspace Unchanged","text":"

What happens if you update (git pull --recurse) and there are no changes at the LoopWorkspace repository? There will be no change to your current clone on your computer.

  • You'll see a series of responses saying:
    • Fetching submodule submodule-name for each submodule-name
    • followed by Already up to date.
"},{"location":"version/loopworkspace/#loopworkspace-updated","title":"LoopWorkspace Updated","text":"

What happens if you update (git pull --recurse) and there are changes at the LoopWorkspace repository? The changes will be brought down to your clone on your computer.

You'll need to build Loop again to get these changes incorporated in the app on your phone.

  • You'll see a series of responses saying:
    • Fetching submodule submodule-name for each submodule-name
    • One or more will show changes and specify which submodules were changed
      • followed by Submodule path submodule-name: checked out new SHA-1
"},{"location":"version/loopworkspace/#update-locally","title":"Update Locally","text":"

It has happened that you notice changes in one or more repository (in the #github stream) followed by an announcement in the #development stream that changes have been committed and please test. But you get the response shown in the LoopWorkspace Unchanged scenario. You can make a comment in zulipchat, saying please update LoopWorkspace and then wait, or you can download the appropriate commit. If you are a new tester - you probably want to wait.

If you want to go on and test, you can update to the correct commit without waiting for LoopWorkspace to get updated.

First, in zulipchat, in the #github stream of the commit, click on the word pushed and that will take you to the commit. For example, clicking on pushed in zulipchat from the graphic shown above, goes to this website:

https://github.com/ps2/rileylink_ios/compare/8ff4bca2bc5f...2541c1c899a9

This indicates the final commit of that push for rileylink_ios is identified as 2541c1c.

At this point, the commands to get that commit locally on your computer are as follows, starting from the LoopWorkspace folder:

cd rileylink_ios; git fetch; git checkout 2541c1c; cd ..

If you got an error message the # you requested did not match any file(s) known to git, you either typed it incorrectly or you forgot the git fetch command. The fetch command brings down information from github to your computer but doesn't make changes to what you have checked out.

"},{"location":"version/loopworkspace/#local-modifications-conflict","title":"Local Modifications Conflict","text":"

If you have modified anything in a submodule folder on your computer, it might be in conflict with the latest commit.

If you get a message such as this:

  error: Your local changes to the following files would be overwritten by checkout:\n    Loop/Models/LoopConstants.swift\n  Please commit your changes or stash them before you switch branches.\n  Aborting\n

The easiest fix is to type commands similar to the following, where you modify Loop to be whichever folder(s) had the conflict. If more than one folder had a conflict, then issue the stash for each folder. The submodule update command will continue to show errors until you stash all local changes that interfere with the new code:

  cd Loop; git stash; cd ..\n  git submodule update\n

After stashing and updating with no errors, you can try to restore your changes: 

  cd Loop; git stash pop; cd ..\n

If you see errors indicating you cannot use pop, that means you need to manually add your customizations back.

You will need to repeat this for each submodule that has a conflict. Use the lines above (for Loop submodule) as a template to resolve conflict(s) other submodule(s).

"},{"location":"version/loopworkspace/#checking-out-different-branches-within-a-loopworkspace","title":"Checking out different branches within a LoopWorkspace","text":"

More advanced users...I'm not going to explain this in quite so much detail, but yes, you can individually change the branches in a LoopWorkspace.

There are 2 main ways to do this.

  1. If you're already familiar with git, the easiest way is to cd into the appropriate repository (like cd rileylink_ios) and checkout the desired branch.

  2. If you're not as familiar with git, if you edit your .gitmodules directory in LoopWorkspace, you can specify other repos to use (and add a line to specify branches, too). Then if you do a git submodule sync the workspace will sync to new submodules. Then git submodule update --init --recursive --remote will update all the submodules to the right branches and get HEADs detached correctly, etc. Note that the HEADs will be detached at the top of the branch (most recent commit) based off of .gitmodules.

"},{"location":"version/loopworkspace/#branch-tutorial","title":"Branch Tutorial","text":"

This tutorial is pretty nice.

Git Tutorial

When I first started using git, my adult son answered all my questions very politely and then started sending me links to this tutorial instead.

  • Learn Git Branching

There's a section called Main that goes over commands in your local copy (clone) of the code. There's a section called Remote that goes over fetching, pulling, and pushing to remote copies.

For Open Source Software, you might fetch and pull from the LoopKit repositories, but you will only push to your fork.

  • You may need to add git remote add <name> <your-fork-repo> and git push --set-upstream <name> <branch> to your vocabulary.
"},{"location":"version/loopworkspace/#non-loopkit-clones","title":"Non-LoopKit clones","text":"

Average Loopers can skip this whole section...it's for Developers mostly

This whole section about non-LoopKit workspace clones is something almost every Looper can totally skip over. I'm only writing up this section for people who are interested in dabbling in code collaborations/customizations that they would want to maintain separately from LoopKit proper.

Scenario: You have a friend named DeveloperBob who has his own version of LoopWorkspace that he's customized. DeveloperBob wants you to look at his code customizations and collaborate with him. You need to change the \"git clone\" command to get DeveloperBob's version, not LoopKit's version. And, you'd want to make sure you specify the branch that the new feature is on, too. DeveloperBob should usually include the branch name when he posts/shares. So, the command line might be edited to something like:

git clone --branch=new-features --recurse-submodules https://github.com/DeveloperBob/LoopWorkspace

So...if you are trying to grab someone's LoopWorkspace to use it, you'll need to make sure you get the command correct if they don't specify it for you. You can't clone multiple \"LoopWorkspaces\" into the exact same home directory (because they will have the same name), so you may want to create a subdirectory to put them in. Like you could make a folder called \"DeveloperBob\" and then move into that directory in Terminal before you clone DeveloperBob's LoopWorkspace.

How would you do that? Simple cd && mkdir DeveloperBob would make the new folder in your home directory. And then cd DeveloperBob would move your Terminal app to be working inside the new DeveloperBob folder. So if you wanted to clone DeveloperBob's LoopWorkspace, that would be a good way to keep track of where the code came from.

If you ever get in doubt and can't remember where your code was cloned from, you can cd LoopWorkspace to get into the directory and then use git remote -v to tell you where it came from.

"},{"location":"version/loopworkspace/#pushing-commits-from-loopworkspace","title":"Pushing commits from LoopWorkspace","text":"

So you've got a great idea for a new feature, made those changes to your LoopWorkspace, and want to get them into GitHub. Awesome!

To understand how to do this, we'll need to understand a bit more about how git keeps track of changes. In git, developers can have different \"branches\" (see What are Git Branches? on the Loop Development page for more details about what a branch is). There are two different types of branches: remote and local. If you were to fork Loop on GitHub, then the branches that you can see on GitHub are \"remote\" branches - they're hosted on the GitHub server. On the other hand, you can also create \"local\" branches that are stored directly on your computer by \"checking out\" the remote branch. You'll need to \"commit\" your changes to the local branch, and then \"push\" those changes to the remote branch in order to be able to see them in GitHub. There are specific commands that you can type into the command line to do all of these actions, but I'm not going to go into detail because there are different ways and everyone has their own preference.

It's a little easier to think about this with an analogy. Let's say you're working at a company that's creating a cookbook. There's a centralized, production-ready version of the cookbook on their website that all the employees can view. Think of the website version of this cookbook as being like the remote branch. You're assigned to change the pancake recipe in the cookbook. Since the company doesn't want employees to make changes directly to the version of the cookbook that the customers see, you need to make a copy of it on your computer so you can make your changes to the pancake recipe. When you make the personal copy on your computer, it's like \"checking out\" the remote branch. Your copy is like the local branch - you can make whatever changes you want without having to worry about customers accidentally seeing them. When you make an important change to the recipe (like adding a photo or changing the ingredients), you might want to make a note in the edit history so that you can go back to that version of the recipe in case you accidentally make unintended changes - those notes you make would be \"commits\". Once you're happy with the recipe, you'll add it back into the production version of the cookbook on the website, which is similar to what you're doing when you \"push\" your changes.

Where do the submodules fit in? Each submodule is actually a branch, so when you make changes to multiple submodules, you'll need to commit those changes to their respective branches. Let's say you've made changes to Loop and LoopKit. You'll need to go into Loop and commit and push the changes, then go into LoopKit and commit and push the changes.

There are a few different ways to keep track of all these different branches. Some people like using the command line (which is what you're using when you do commands like git clone) because it's very customizable and has the largest variety of commands. Others like to use graphical Git editors, which make it easier to see changes and be able to do a variety of common actions (like cloning, committing, and pushing) with the push of a button. Everyone has their own preferences, but some methods that Loop contributors have used in the past include the command line, Gitkraken, and SourceTree.

"},{"location":"version/overview-version/","title":"Version Overview","text":""},{"location":"version/overview-version/#version-overview","title":"Version Overview","text":"

The Version tab of LoopDocs contains information about releases (versions), code customization and development.

Map to this section:

  • Releases
    • Description of the current released version of the Loop app including when it was released
    • Reverse chronology of earlier releases
  • Information needed to Personalize (Customize) your app (regardless of build method)
    • Custom Edits
    • Build-Time Flag
  • Simulator Build
    • Considerations when using a simulator
  • Loop Development
    • Description of the development process for Loop
    • Information you need if you want to participate
  • Build Dev
    • Considerations when using the dev branch
    • Links to the two build methods
  • LoopWorkspace
    • If you are interested in development, this page goes into more detail
    • The primary focus is on techniques for using git
"},{"location":"version/releases/","title":"Releases","text":""},{"location":"version/releases/#loop-releases","title":"Loop Releases","text":"

The new features added with each Loop release (starting with Loop version 2.0) are provided for reference.

"},{"location":"version/releases/#loop-3-compatibility","title":"Loop 3 Compatibility","text":"

Be aware that Loop 3 is forward compatible:

  • You can build Loop 3 over older versions of Loop and maintain therapy settings as well as your configuration for CGM and pump (including a pod)
  • You can build Loop 3 using a browser on any computer (no Mac required) with Build with Browser
  • Your phone must be running at least iOS 15.1 (although some people report they needed newer iOS than that when building with GitHub Browser Build)

Loop 3 is NOT backwards compatible.\u00a0Once you build Loop 3 or later on your phone, you cannot return to Loop 2.2.x or FreeAPS without some additional work.

  • Be prepared to enter all your settings again and start a new pod
  • If you use Loop Follow, you do not need to delete Loop Follow
  • When downgrading to an older version of Loop from Loop 3, you have to delete all apps with a shared app group ID
    • For more information, click on Remove Apps with Shared App Group
"},{"location":"version/releases/#current-release","title":"Current Release","text":"

The current released version for the Loop app is 3.2.3. The dates and contents for releases are summarized below in reverse chronological order (so newest release information comes first).

"},{"location":"version/releases/#what-version-do-i-have","title":"What Version Do I Have?","text":"

Tap on the Settings icon at the toolbar of the Loop app and look at the version information at upper left. This graphic was generated with an older version.

"},{"location":"version/releases/#is-the-released-version-newer","title":"Is the Released Version Newer?","text":"

Release information is always found on the GitHub LoopKit/Loop\u00a0release page.

Additional information including links is found here, but be aware that updates to\u00a0LoopDocs\u00a0may take some time after a new release comes out.

"},{"location":"version/releases/#loop-version-numbering","title":"Loop Version Numbering","text":"

With the release of Loop 3, there is a new pattern for identifying the releases as distinct from the development work.

Each release uses 3 numbers: Major.Minor.Patch

  • Major is reserved for a significant change in the code, such as occurred going from Loop 2.2.9 to Loop 3.0.0
  • Minor is used when the development branch is released for general use
  • Patch typically indicates a modification to support external events like an Xcode or iOS version update with no feature changes in Loop

To prevent confusion between versions used for development and versions used for release (main branch), the Minor values are even for released code. The Minor value for the development branch (dev) is incremented as part of the release process and is always odd.

For example:

  • Loop 3.0.0 was the first released version of Loop 3
    • Loop 3.1.0 was the development version before Loop 3.2.0 was released
  • Loop 3.2.0 was the next released version
    • Loop 3.2.1, 3.2.2 and 3.2.3 are patches to Loop 3.2.0 without changes to the features of Loop 3.2.x
    • Loop 3.3.0 is the current development version
"},{"location":"version/releases/#loop-3-version-history","title":"Loop 3 Version History","text":""},{"location":"version/releases/#loop-v323","title":"Loop v3.2.3","text":"

Loop v3.2.3 was released on September 19, 2023.

This patch release was required for those who build using the Mac method.

  • There are no changes to app functionality
  • Version 3.2.2 and earlier cannot be built using Xcode 15, see Cycle Inside Loop
"},{"location":"version/releases/#loop-v322","title":"Loop v3.2.2","text":"

Loop v3.2.2 was released on April 24, 2023.

This is a patch release to fix archiving with Xcode 14.3.

"},{"location":"version/releases/#loop-v321","title":"Loop v3.2.1","text":"

Loop v3.2.1 was released on March 20, 2023.

This is a patch release primarily dealing with localization updates.

  • G7 Plugin localization fixed: was defaulting to Spanish in some cases.
  • Updated translations from translators on Lokalise.
  • Many behind-the-scenes fixes for how strings are tracked in the various frameworks that Loop uses, fixing a large number of broken/missing translations.
"},{"location":"version/releases/#loop-v320","title":"Loop v3.2.0","text":"

Loop v3.2.0 was released on March 17, 2023.

There are some important bug fixes and new features, so please rebuild to this version as soon as possible.

Pete's announcment:

Loop 3.2 Is released! This contains some very important bug fixes for everyone. If you are running latest dev, you do not need to update, but everyone else running older 3.x versions of Loop should consider upgrading as soon as you can.

https://github.com/LoopKit/Loop/releases/tag/v3.2.0

Bug Fixes (Please update ASAP):

  • Omnipod bolus tracking issue fixed: link
  • Medtronic temp basal tracking issue fixed: link
  • Crashes caused by large updates from Apple Health fixed
  • Automatic refresh timers for Omnipod (both Dash and Eros) have been removed, to reduce load on pods and reduce frequency of failed pods.

Updates and new Features:

  • Missed Meal Notifications. If you want, Loop will detect situations where it looks like you may have consumed carbs but did not enter them into Loop, and will notify you with an easy option to enter the amount, and the time of eating already estimated for you. Find this option in the Alert Management section of Loop settings.
  • Tidepool Service added. This lets you upload your diabetes data from Loop to Tidepool! It is in early stages, so there may be issues. Please report any issues you have with this integration on DIY Loop forums, like Zulip, GitHub, or the Looped group.
  • Translations! Loop now has very good coverage for several languages, including German, Spanish, Italian, French, Danish, Polish, Dutch, Norwegian, Russian, Turkish, and Romanian!
    • Warning - a few items got overwritten by Spanish - if you can't figure it out, try Google translate
  • A new safeguard restricts automatic dosing to keep your IOB below a limit of 2 times your max bolus. Manual dosing can still be delivered to put your IOB above this amount. link
  • Add missing X-Large watch complications. link
  • \u201cDeactivate Pod\u201d button on some screens changed to not be so alarming, as it doesn\u2019t actually deactivate the pod, but takes you to a screen where you can, and has an option to cancel: link
"},{"location":"version/releases/#loop-v300","title":"Loop v3.0.0","text":"

After several years of development and a lot of testing, Loop 3 is here!

Loop v3.0.0 was released on January 14, 2023.

Link to release notes for Loop 3.0

Use Script not Zip

If you follow that link above, there is an Assets section with a zip link

  • Do not try to build from the zip link
  • For Browser Build, refer to: GitHub Overview
  • For Build with Mac refer to:
    • Updating
    • Build the Loop App

Branch Name Change

The branch name associated with the latest Loop release is main.

  • All new Git repositories on GitHub will be named main instead of master starting October 1, 2020
  • GitHub provides tools to assist in modifying existing repositories to use main
"},{"location":"version/releases/#remove-apps-with-shared-app-group","title":"Remove Apps with Shared App Group","text":"

The storage of data with Loop 3 is not backward compatible. In other words, if you attempt to build Loop 2.2.x (or FreeAPS) on a phone which has been upgraded to Loop 3, you will not be able to run that app. You can successfully build the app, which will overwrite Loop 3 on the phone, but the app will crash and you will not be able to Loop.

At this point, you can restore your Loop 3 build on your phone and continue using Loop 3 or you delete all apps on your phone with a shared app group. This list includes Loop, FreeAPS, FreeAPS X, xDrip4iOS, Glucose-Direct, and the g5 Transmitter Reset app.

If you tried to delete \"all\" the apps and still have something causing an issue; you can follow the directions to Review Provisioning Profiles and then delete the profiles for all the apps by using the - sign.

You do not need to delete Loop Follow, so if you use Loop Follow - do not delete that provisioning profile.

"},{"location":"version/releases/#loop-2-version-history","title":"Loop 2 Version History","text":""},{"location":"version/releases/#loop-v229","title":"Loop v2.2.9","text":"

This release updates Loop to handle Dexcom Share server changes for how glucose trend is parsed. Dexcom used to provide integers that mapped to the meaning for the arrows. They changed that to strings, like \"Flat\" or \"FortyFiveUp\".

Loop v2.2.9 was released on April 4, 2022.

"},{"location":"version/releases/#loop-v228","title":"Loop v2.2.8","text":"

This is a hotfix (no features were modified in the Loop app) to enable the app to be built with Xcode 13.3.

Loop v2.2.8 was released on March 16, 2022.

"},{"location":"version/releases/#loop-v227","title":"Loop v2.2.7","text":"

This is a fix (no features were modified in the Loop app) to enable the app to be distributed via TestFlight.

Loop v2.2.7 was released on Jan 11, 2022.

"},{"location":"version/releases/#loop-v226","title":"Loop v2.2.6","text":"

Several users reported issues with IOB accounting in Loop v2.2.5, where IOB was being under-reported, which could cause Loop to continue recommending increases in insulin delivery. A fix was made and provided as Loop v2.2.6.

This is a serious issue, so updating to this release is strongly recommended for anyone currently running v2.2.5. If you tap on Loop Settings and look at the top, and see LOOP V2.2.5, then rebuild ASAP. The time window when you would have built v2.2.5 is from Aug 22 through Sep 6, 2021.

The issue appears to be the result of a failure to write to Apple HealthKit, which may occur if the Health app on your phone is having problems, or if you have turned off Loop's ability to write Insulin data to HealthKit. The fix involves reverting a change made in v2.2.5. This change was an attempt to reduce overlaps of Reservoir and Pump Event reconciliation which intermittently over estimate insulin delivery. Instead, that issue will be fixed in the next major release of Loop.

Thanks to all who helped with reporting, digging, and testing this quickly. It's great to have such a strong community of people eager to help.

Loop v2.2.6 was released on September 6, 2021.

"},{"location":"version/releases/#loop-v225","title":"Loop v2.2.5","text":"

This is an interim release as we prepare for the major changes currently in development. If you are running an older version of Loop, such as v2.2.4 (master or automatic-bolus branch) or an older version, it is recommended that you update to v2.2.6 to get all these new features. A summary of modifications with respect to Loop v2.2.4 is listed below.

Loop v2.2.5 was released on August 22, 2021.

"},{"location":"version/releases/#new-features","title":"New Features:","text":"

Automatic Bolus (Experimental) Dosing Strategy

  • Users may select Dosing Strategy
  • Default Dosing Strategy continues to be Temp Basal Only
  • Automatic Bolus Dosing Strategy is marked experimental
    • If you used Loop v2.2.4 automatic-bolus branch, this release will behave the same
    • If you used Loop v2.2.4 master branch, approach this feature with caution; it may require changes to settings
    • Tracking automatic vs manual boluses is not yet implemented in the code and databases

Provisioning Profile Expiration Notifications:

  • User gets notified when Loop app expiration date nears
  • Expiration date is included in the issue report

RileyLink Compatible Devices:

  • The RileyLink compatible device displays are pump independent
  • OrangeLink Support added for connection monitoring, battery level alerting, find device, and light/vibration controls
  • Medtronic Pump Settings screen updated with option to disable MySentry use; user can trade Medtronic pump battery for longer RileyLink compatible device battery life

Omnipod Features:

  • Pod Settings layout: improved layout and functionality
  • Fault Codes: PDM style Ref code displayed for pod faults
  • Confirmation beeps: improved and more uniform implementation
  • Pod Suspended: pod beeps once every 5 minutes until delivery is resumed or alarm cleared
"},{"location":"version/releases/#code-fixes","title":"Code Fixes:","text":"

Omnipod Code Fixes:

  • Make insertion more robust (LoopKit issue #1369)
  • Fix \u201cPod already primed\u201d errors when priming cancelled (rileylink_ios issue #661)
  • Prevent 049 pod faults during setup (rileylink_ios issue #627)
  • See RileyLink Pull Request 676 for additional details.

(REMOVED) Insulin Accounting:

  • Reduced occurrences of overlaps in accounting for insulin via reservoir and dose history, which causes temporary overestimation of IOB
  • See Loop Pull Request 344 for details
  • This modification (in v2.2.5) was removed for v2.2.6
    • It worked as advertised during testing, but . . .
    • If the user's phone had trouble communicating with the Apple HealthKit app, this could cause IOB to be under-reported and cause Loop to provide more insulin than needed

Dexcom Non-US Share:

  • Dexcom Share URL for non-US users has been fixed.

For community support, please use one of the Loop Social Media help sites.

"},{"location":"version/releases/#loop-v224","title":"Loop v2.2.4","text":"

Released October 3, 2020 with \"fixes\" introduced without renumbering the version number. Last change was on January 19, 2021.

  • Revert to previous date pickers (Thanks @novalegra!)
  • Pod fault handling improvements (Thanks @itsmojo!)
  • Fix issue with pod status screen not allowing new pod pairing or continuing of interrupted pairing.
  • October 22, 2020, update travis to make it work with Xcode 12
  • January 19, 2021, pin the carthage to 0.36.0. Users no longer required to install homebrew or carthage
"},{"location":"version/releases/#loop-v223","title":"Loop v2.2.3","text":"

Released September 25, 2020

Warning - Rebuild ASAP for Pods

  • A bug was introduced in this version, quickly fixed in v2.2.4.
  • If you use pods, please rebuild using v2.2.6.
  • Fetch pump and cgm data on manual loop retry (when Loop icon is red or yellow)
  • Re-arranged pod status screen to prioritize needed information and actions.
  • Pod pairing fixes for more edge cases.
  • Translation updates.
  • Fix share server integration, pointing to share2.
  • Report RSSI and low gain in Read Pod Status command.
  • Report failure properly when Play Test Beeps command fails.
  • Carthage build fix for Xcode 12.0.1
"},{"location":"version/releases/#loop-v221","title":"Loop v2.2.1","text":"

Released August 9, 2020

  • Include pending insulin in:
    • forecast uploaded to Nightscout
    • status extension forecast
  • Updated translations, fixes for temp override translations, new Arabic translations.
  • Omnipod integration fixes:
    • Avoid suspending during deactivation if pod has a fault, is in setup, or already suspended.
    • Show the correct expected address in invalid address error
    • Reuse same address during attempts to pair with same pod
    • Fix for Medtronic only: when a bolus issued via the Loop interface was canceled by issuing a suspend on the pump itself, Loop will incorrectly track the bolus as if the full amount were delivered
    • Updates for omnipod packet parser
    • Suggest moving RileyLink to new area on multiple pairing failures
  • Minimed updates:
    • Detect temp basal cancellation performed on pump
"},{"location":"version/releases/#loop-v22","title":"Loop v2.2","text":"

Released April 17, 2020

  • Updated carb/bolus screens. Thanks @mpangburn!
    • Carbs and boluses are now entered together, which is a more familiar model to many caregivers.
    • Forecast preview while entering bolus allows you to see potential impact of your bolus before delivering.
  • Improvements in Watch updates; sleep data being used to update complications when you are awake. Thanks @novalegra!
  • Omnipod pairing improvements. Bug fixes, and better error messaging. Thanks @itsmojo!
  • Many performance improvements, especially effecting long time Loop users. Delays in rendering graphs during app launch should be fixed.
  • New device communication logging facility- Additional logging across pod swaps, and logging of CGM communication.
  • Rendering fixes to prevent insulin graph from drawing outside of bounds.
  • Bug fix to align use of 10m insulin delay in dose computation and forecast.
  • Include current bg in suspend threshold evaluation.
"},{"location":"version/releases/#loop-v20","title":"Loop v2.0","text":"

Released December 31, 2019.

For Reference Only

Enough time has passed that this version should no longer be on anyone's phones (the one-year expiration time should take care of that).

There is a lot more detail provided in the Loop v2.0 section because it constituted a significant change to parts of Loop from prior releases. This section and the Omnipod-Testing branch sections are left here for historical interest.

"},{"location":"version/releases/#what-was-new-in-loop-v20","title":"What was new in Loop v2.0?","text":"

This is a highlights reel comparing Loop v2.0 to v1.9.6.

"},{"location":"version/releases/#uploading-of-bgs-to-nightscout","title":"Uploading of BGs to Nightscout","text":"

Loop v2.0 has an option to upload your BG data to Nightscout directly. It is a new slider under the CGM configuration section for Dexcom users. After you add your CGM transmitter ID, go back into the CGM info and you'll see a new slider called \"Upload Readings.\" Technically, Loop's dev branch had that feature for a hot minute before Loop v2.0 was released...but for almost everyone this will be a brand new feature they haven't had before. This feature can help if/when Dexcom's Share servers ever go through another large outage like we had before. If that happens, you can turn on the \"Upload Readings\" switch and your CGM data will now be in Nightscout even without Share servers working properly. Good practice would be to temporarily disable your Share bridge in Nightscout while Loop is responsible for CGM uploading so that you don't get duplicate data. You can disable Share bridge by logging into your Heroku account, going to the Settings tab, clicking on \"reveal config vars\" and then deleting the word \"bridge\" from the ENABLE line.

"},{"location":"version/releases/#a-fix-for-settings-loss","title":"A fix for settings loss","text":"

iOS 13 brought about a quirky little bug where you could suddenly lose settings in Loop. But, it wasn't just limited to Loop, sometimes people lost Dexcom app settings too. The issue is most common when the phone goes through a power cycle, but it has happened at other times, too. There's a fix for that new bug in Loop now...so that's a good reason to update. (If you encounter that bug before you have a chance to update your Loop app, simply restart the Loop app and your settings should reappear.)

"},{"location":"version/releases/#confirmation-beeps-expanded","title":"Confirmation beeps expanded","text":"

Confirmation beeps have been expanded based on user feedback...we heard parents and school nurses really appreciate hearing a beep for not just boluses, but also for suspend/resume commands and editing basal schedule (so you are sure it saved properly). So, confirmation beeps are now for boluses, suspend/resume, and basal schedule edit saves.

"},{"location":"version/releases/#read-pod-status-added","title":"Read Pod Status added","text":"

There's a new command in the RileyLink menu for \"Read Pod Status\" that is analogous to the existing command for Medtronic users. You can query your Pod for its current status info using that command.

"},{"location":"version/releases/#nightscout-profile-uploading-introduced","title":"Nightscout profile uploading introduced","text":"

Loop will upload your basal schedule, ISFs, carb ratios, and override presets from Loop settings to your Nightscout profile. If you ever lose your phone and need to setup Loop brand new...your settings will be easy to find in Nightscout now.

"},{"location":"version/releases/#non-linear-carb-model-introduced-as-default","title":"Non-linear carb model introduced as default","text":"

All branches (master and dev) now use a \"non-linear\" carb model, so let's give some info about the change.

Previously, the carb model Loop used had a linear absorption predicted with dynamic carbs adjustments. What this means is that food absorption was modeled as a flat, even effect (like the straight grey graph that you'll see in the Insulin Counteraction Effects chart after you added a carb entry. But looking at large groups of meals' datasets (and supported by personal, anecdotal experiences), food really has a bit more of a non-linear absorption. Meaning, we usually see more of a food impact up-front than the old carb model in Loop predicted.

What did that mismatch mean for us if the model predicts a linear absorption, but the meal actually behaves differently?

  1. Bolusing: You've probably seen smaller upfront boluses for meals than you would have preferred. This is because the insulin was predicted to over-power the linear (slower) carb model soon after a bolus is given.
  2. Early low temp basals: You've also probably seen a tendency to have early zero basal or low basals set by Loop for the first 30-60 minutes after a meal bolus if you don't have a significant blood glucose spike immediately after the carb entry. This might have been even more obvious for those of you who are regularly waiting to eat after a bolus, too.

With a non-linear absorption model, the carb absorption will more closely match observed blood glucose impacts we've seen after meals. And when the model is more closely matching actual experience, that means the predicted blood glucose curves will do a better job at providing more upfront bolus and not having the tendency to have overly conservative temp basals soon after a meal.

"},{"location":"version/releases/#overrides-introduced","title":"Overrides Introduced","text":"

Loop v2.0 marks the first time Loop master branch has overrides included. Additionally, this release moves overrides setup from the configurations area of Loop settings to the workout icon in the Loop toolbar. There has also been bug squashing in dev branch for overrides over the recent past, so updating is a good idea even if you already have overrides on your current build. Want to learn more about overrides? Read about them here.

"},{"location":"version/releases/#retrospective-correction-always-on","title":"Retrospective Correction always on","text":"

Retrospective correction used to be an optional toggle in the algorithm. It is now on by default all the time. It is an important part of the algorithm (helps Loop look at how good/bad its recent prediction curve has been vs reality), and leaving it on made sense anyways.

"},{"location":"version/releases/#omnipod-support-in-released-code","title":"Omnipod support in Released Code","text":"

Yes, most of you are already using Omnipod with your Loop...but this is the first time that Loop master branch supports Omnipod users. Please update if you have been using Omnipod-testing branch especially...it's time to get all the bug fixes that we've done in Loop.

"},{"location":"version/simulator/","title":"Simulator Build","text":""},{"location":"version/simulator/#simulator-build","title":"Simulator Build","text":"

There are 2 main types of simulators users may want to build. Each of these require less up-front acquisition of hardware and may be desirable as a first step towards becoming a Looper.

Please, review all the Intro and Build pages, even if you will not complete them yet.

"},{"location":"version/simulator/#simulator-using-browser-build","title":"Simulator using Browser Build:","text":"
  • No Mac computer required
  • Must have a paid Apple Developer ID ($99/year)
  • Must have a compatible phone

Follow the normal instructions to build with browser, install the app on a compatible phone and explore the app using the Pump Simulator, CGM Simulator or both.

"},{"location":"version/simulator/#simulator-using-build-with-mac","title":"Simulator using Build with Mac:","text":"
  • Must have a Mac computer (or virtual machine, Intel chips only)
  • Can build the simulator with a free Apple Developer ID
    • Build to Mac (no phone required) or
    • Build to a Compatible Phone using Mac Build
"},{"location":"version/simulator/#build-to-a-simulated-phone-on-mac-computer","title":"Build to a Simulated Phone on Mac Computer","text":"

This simulator requires access to a Mac or virtual computer, see Compatible Computer

  • Build pages to review, but complete later
    • Apple Developer Program (can use a free account)
  • Follow Xcode Version
  • Follow Xcode Settings but can skip the Add Apple ID section
  • Follow Build the Loop App but with the following variation:
    • Skip the section on Developer Mode (that is only when building to a phone)
    • Download the code as directed
    • Choose to Sign Manually in the Signing Targets section
    • Continue with the Build Free Loop page
      • Select a simulator (not your phone) when told to do so
      • Complete the Build to a Simulator section
  • Use the simulated iPhone that will appear on you Mac and set up the app as desired
  • This gives you a feel for the interface, but the simulator on the Mac has limitations
"},{"location":"version/simulator/#build-to-a-compatible-phone","title":"Build to a Compatible Phone","text":""},{"location":"version/simulator/#build-to-a-compatible-phone-using-browser-build","title":"Build to a Compatible Phone using Browser Build","text":"

You don't need to do anything special when you build the app using the Build with Browser instructions. Install the app on your phone from TestFlight. Then select the CGM and/or Pump simulator desired. You must have a paid developer account.

"},{"location":"version/simulator/#build-to-a-compatible-phone-using-mac-build","title":"Build to a Compatible Phone using Mac Build","text":"

When building to a real phone using a Mac, you must have access to a Compatible Computer and a Compatible Phone.

  • You can use a Free Apple Developer account
  • Follow Xcode Version
  • Follow Xcode Settings
    • If you have a developer ID, use it in the Add Apple ID step and follow the normal build directions
    • If you do not have a developer ID, use the Free Developer Account instructions in the Add Apple ID section
  • Follow Build the Loop App using the Free Account instructions
    • If your phone is running iOS 16 or newer, you must enable Developer Mode
    • Download the code as directed
    • Choose to Sign Manually in the Signing Targets section
    • Continue with the Build Free Loop page
  • Once the App is on your phone
    • Follow the set up the app instructions on your phone but choose a simulated pump
    • If you have a compatible CGM on this phone, you can select that or you can use the simulated CGM or enter glucose values on the main Loop screen
"},{"location":"version/simulator/#what-to-expect","title":"What to Expect","text":"

Locked Phone or App in Background

Loop will not work in the background without either a real CGM or a real pump to \"wake\" it up.

The app will only work in the background in these special cases:

  • Loop is on on the same phone as a CGM and you've added that CGM information to Loop
  • Loop is attached to a pump (Pod or Medtronic)
    • You can configure the pump to drip water (instead of being attached to your body)

In all other cases, the phone must be open and unlocked for you to test the app.

These CGM and pump options work to provide glucose readings or accept pump commands while the app is open, but will not \"wake\" the app when in the background or phone is locked:

  • Dexcom Share
  • Nightscout Remote CGM
  • CGM Simulator
  • Pump Simulator

Disable Notifications

When you have the Loop app on your phone to test as a simulator, you may want to disable notifications when you are not actively using it. Even if you quit the app, you will get Loop not Looping notifications while the app is on your phone.

To Disable Notifications:

  1. Tap on iOS Settings -> Notifications -> Loop
  2. Disable Allow Notifications

The Loop app, when open, will be quite aggressive at warning you that you have disabled Notifications, so you can reverse those directions to enable notifications when actually using the app.

"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"

Welcome to the LoopDocs website where you can learn about the Loop app.

"},{"location":"#what-is-the-loop-app","title":"What is the Loop App?","text":"

The Loop app is an automated insulin delivery application that you build and operate on an iPhone.

  • The Loop app uses your settings, meal entries and glucose data to calculate insulin dosing needed to bring your blood glucose within the correction range you set
    • You enter your personal therapy settings (e.g., basal rate schedule, carbohydrate ratio, insulin sensitivity)
    • You indicate your CGM and pump
  • You choose how to operate the Loop app:
    • Closed Loop: Predict, recommend and control insulin dosing
    • Open Loop: Explore interface, test settings, learn to enter meals and dose
"},{"location":"#what-isloopvideo","title":"What is\u00a0Loop\u00a0Video","text":"

Loop\u00a0Video

  • This What is\u00a0Loop video with associated pdf deck was created by the\u00a0Loop and Learn\u00a0team
  • It is a great introduction, created when Reese was using an earlier version of Loop
  • Special thanks to
    • Tina and Reese Hammer for the terrific video
    • Matthew Fouse for his beautiful graphics
"},{"location":"#what-are-my-next-steps","title":"What are my next steps?","text":"

This site shows you step-by-step how to build, set up and operate the Loop app.

  • You do not need a technical or computer background to do this
  • You can choose to build the Loop app several ways:
    • Use a browser on any computer or tablet and install it on your iPhone via TestFlight
    • Use an up-to-date Mac Computer and install it directly on your iPhone

In order to become proficient with the app, you should learn the information on this site. Consider doing this over a period of time and reviewing the materials more than once.

  • You should test and perhaps adjust your settings to be successful with the Loop app (or any hybrid closed-loop system)
  • As you read the documentation, you will find links to a robust volunteer support community
    • You're invited - come introduce yourself
    • Don't be afraid to ask questions, just let us know where in the documentation you got confused so we can make improvements

There is a common saying in our community:

Do It Yourself (DIY) does not mean Do It Alone!

Once you are using the app, you should regularly follow one or more support forums for important updates on the Loop app. Spending this time is important for success in building and operating the Loop app safely.

This website is updated regularly to keep pace with development of the Loop app and Apple releases.

"},{"location":"#important-disclaimer","title":"Important Disclaimer","text":"

Please consult with your health care professional regarding your diabetes management.

  • The Loop app is an open source project used by many, but it is not approved for therapy by any government organization.
  • You take full responsibility for building and running this system and do so at your own risk.
"},{"location":"#volunteer-community","title":"Volunteer Community","text":"

The Loop app has been, and continues to be, developed and supported by volunteers. From the code to this website, you are able to use this app because many volunteers continue to give their personal and family time.

Please add your time by reading this website before embarking on your Loop journey.

"},{"location":"translate/","title":"Translation","text":""},{"location":"translate/#language-list","title":"Language List","text":"

\u0639\u0631\u0628\u064a

\u0411\u044a\u043b\u0433\u0430\u0440\u0441\u043a\u0438

\u010ce\u0161tina

Deutsch

Dansk

\u0395\u03bb\u03bb\u03b7\u03bd\u03b9\u03ba\u03ac

Espa\u00f1ol

\u65e5\u672c

Suomi

Fran\u00e7ais

\u05e2\u05d1\u05e8\u05d9\u05ea

Hrvatski

\u0939\u093f\u0902\u0926\u0940

Italiano

\ud55c\uad6d\uc5b4

Norsk

Nederlands

Polski

Portugu\u00eas

Rom\u00e2n\u0103

\u0420\u0443\u0441\u0441\u043a\u0438\u0439

Sloven\u010dina

Svenska

Turkish

\u4e2d\u6587\uff08\u7b80\u4f53)

\u4e2d\u6587\uff08\u7e41\u9ad4)

"},{"location":"translate/#google-translate-links","title":"Google Translate Links","text":"

Click on a language on the list of links above to turn on Google's automatic translation.

"},{"location":"translate/#change-language","title":"Change Language","text":"

To modify the language choice for the whole site, copy the line below, and paste it into the URL, and then choose the desired language from the list above.

Copy and Paste in Browser URL to return to original version
https://loopkit.github.io/loopdocs/translate\n

OR

Use the Google Translation three-dot menu and select Go to Original URL while on the Translation page.

"},{"location":"translate/#more-information","title":"More Information","text":"

  • Every website page gets automatically translated to the selected language as do links to other websites

  • The Google Translate Tool will appear at the top of each page

    • LoopDocs how-to: Google Translate Tool Instructions
    • Google how-to: Google Translate Help Link

Automatic Translation

These links connect this site to the Google Translation service.

  • No human has reviewed the translated information for accuracy
  • Please use the translation with care
  • Not available in all regions
  • Some links may not work as expected
  • Any \"code\" not protected by blocks may not appear correctly - be sure to click on Original to make sure you are viewing code properly
"},{"location":"translate/#google-translate-tool-instructions","title":"Google Translate Tool Instructions","text":"

Once Google Translate has been turned on, clicking on a language link above shows a \"Google Translate: Can't translate this page error\".

  • To modify the language for a single page, use the Google Translate tool
  • To modify the language for the entire site, see Change Language

The graphic below shows the Google Translate Tool when maximized (default) for a browser and mobile display. The tool can be minimized by tapping on the up/down carets at the right of the tool. This is very useful if the tool obstructs part of the original screen. Additional options can be selected with the three-dot menu as shown in the graphic.

"},{"location":"build/apple-developer/","title":"Apple Developer Program","text":""},{"location":"build/apple-developer/#enroll-in-apple-developer-program","title":"Enroll in Apple Developer Program","text":"

Time Estimate

  • 15-20 minutes to complete the enrollment forms
  • up to 2 days to wait for confirmation email that enrollment has been activated

Summary

There are two options: Paid ($99/year) or Free (re-build weekly, Xcode only)

  • Paid Developer Account: Go to the Apple Developer website to enroll in an individual account.
  • Free: No action required at this time.
    • Free requires the Build with Mac method

FAQs

  • \"Can I use someone else's Apple Developer account?\" Please refer to this Answer.
  • \"Do I use my Apple ID or my child's Apple ID to enroll in the Apple Developer program?\" The Apple ID you use to enroll in the developer program must be associated with an adult. It does not need to be the same Apple ID as the Looper uses on their iPhone. For example, a parent installing the Loop app on their child's iPhone should configure a separate Apple ID for their child, but should use their own Apple ID to build the Loop app for that child.
  • \"How long does it take to have my Apple Development account active after I enroll?\" After you enroll, make sure you look for a confirmation email. Apple says it can take up to 24-48 hours to confirm and setup a new Apple developer account. However, some people have had the process take minutes. One SURE way to make it take longer is to use a different credit card to pay for the Apple Developer account enrollment than is already associated with that Apple ID. When you do that, finishing the enrollment process may be a hassle.
"},{"location":"build/apple-developer/#loopers-need-their-own-apple-id","title":"Loopers Need Their Own Apple ID","text":"

The Apple ID is DIFFERENT than the Apple Developer ID.

Apple ID

Parents should set up a different Apple ID for each of their looper children and looper children should not use the parent Apple ID. Use Apple's Instructions for Create an Apple ID for your child.

The Apple Health record is a convenient record of blood glucose, insulin and carbohydrates and should be associated with only one individual.

Sharing an Apple ID among two or more loopers can cause safety issues. You don't want Sally to be dosed for Joe's lunch in addition to her own and vice versa.

  • Loop 3 does not read Carbohydrates from Apple Health by default, but if you need that feature, you can modify your feature flags.
  • The recommendation for Health Permissions for Loop 2.2.x has changed to no longer provide permission to read Carbohydrates from Apple Health
"},{"location":"build/apple-developer/#developer-account","title":"Developer Account","text":"

To build the Loop app on a phone, you must use an Apple developer account associated with an adult (minimum age of 18). This Apple developer account is tied to the email address associated with your Apple ID. You can build apps on phones for everyone in your family with a single Apple Developer Account tied to the Apple ID of an adult.

You have two options for an individual account: free or paid.

"},{"location":"build/apple-developer/#free-developer-account","title":"Free Developer Account","text":"

If you decide to use a FREE developer account, here's what you need to know:

  1. You must use the Build with Mac method to build Loop.
  2. Loop apps signed with a free developer account will expire after 7 days. On the 7th day, your Loop app will simply turn white when you open it and then immediately close. To rebuild the Loop app, you will have to find a computer and rebuild the app onto your iPhone again. You cannot rebuild the app on day 5 (when it is convenient, for example), hoping to reset the 7-day clock. The app will still expire on the 7th day from when it was first signed and created.
  3. If you decide to switch to a paid account after trying out the free account, you will need to rebuild your Loop app to sign it with the new paid account. Furthermore, switching from a Free to a Paid account requires entering all the settings again (and starting a fresh pod).
  4. You will have to do an extra step during the build process to remove Siri and Apple Push capabilities to build with free accounts. Because free accounts do not have access to Apple Push notifications, you will also not be able to use Remote Commands through Nightscout.
"},{"location":"build/apple-developer/#paid-developer-account","title":"Paid Developer Account","text":"

If you decide to use a PAID developer account, here's what you need to know:

  1. The paid developer account is $99 per year. The default setting is to auto-renew annually. You can change that selection in your developer account settings at any time.
  2. If your household has multiple Loop users, only one developer account is needed. That one developer account can be used to build Loop on multiple phones.
  3. If you use the Browser Build method
    • You must Update with Browser the build once every 90 days
    • You must have a Paid Developer account
  4. If you use the Build with Mac method
    • If you have a paid developer account, you must build at least once a year
    • If you have a free account, you must build every 7 days
"},{"location":"build/apple-developer/#switching-from-free-to-paid-memberships","title":"Switching from Free to Paid Memberships","text":"

You can try a free account first before buying a paid developer account. If you start with a free account, you'll build a Loop app (let's call it FreeLoop). When you switch to a paid account, you'll be building a totally new and separate Loop app onto your phone (let's call it PaidLoop).

The two apps will look identical on your phone and they will both have the name Loop with the same icon, but they will be functionally separate from each other. Make sure you are successful building the PaidLoop app before deleting the FreeLoop app from your phone. Use the search feature on your phone to find both apps. One will have your configuration settings (FreeLoop), the other will not (PaidLoop).

Before deleting the FreeLoop, either record all the settings or take screenshots of all the relevant settings screens.

PaidLoop will know nothing about the settings and information you had stored in FreeLoop, so you will need to re-enter all your settings (basal rates, ISF, carb ratios, etc.) and configurations into the new PaidLoop. It will also not connect or control any pods you are currently using with the old FreeLoop app. The one exception is Nightscout credentials, which are stored in your keychain. If you entered your Nightscout credentials into FreeLoop, they will persist across app removal and be used by PaidLoop.

With Loop 3, if you use Nightscout, you can import settings that were uploaded to Nightscout by FreeLoop into PaidLoop, so that simplifies the transition.

Once PaidLoop is working, delete the FreeLoop instance from your phone to avoid confusion. If you followed the directions when building, you may have configured your phone to prevent deletion of Loop. Head over to Protect that App, reverse the steps, delete FreeLoop, then do the steps again to protect PaidLoop.

"},{"location":"build/apple-developer/#enrolling","title":"Enrolling","text":"

To enroll in an individual paid Paid account, go to the Apple's Developer Program website Apple Developer website.

Be sure to use the credit card already associated with the email you are using for the developer account. If you switch credit cards, it can cause delays.

If you choose to use the free account, you don't have to do anything on that website. You'll just wait for the instructions on the Xcode Settings page and get your free account then.

"},{"location":"build/apple-developer/#next-steps","title":"Next Steps:","text":"

Take the time to read the next three articles. You will be reminded again when you begin to set up your app.

  • Test Settings
  • Loop Data
  • Meet the Community
"},{"location":"build/build-app/","title":"Build Loop","text":""},{"location":"build/build-app/#summary","title":"Summary","text":"

Time Estimate

  • 60-80 minutes for first time builders
  • 10-15 minutes for repeat builders

Summary

You will:

  • Run the Build Select Script to download Loop code
  • Prepare to build the Loop app
  • Press the Xcode Build Button to build Loop
  • Watch in awe as you build your very own Loop app

FAQs

  • Why does Xcode show a colorful spinning icon and not respond to me? Unfortunately, sometimes Xcode gets confused and you need to force quit the application. See Xcode Not Responding for instructions.
  • Many more FAQs for building Loop are in-line with the steps that trigger the questions.
"},{"location":"build/build-app/#build-video","title":"Build Video","text":"

The Loop and Learn team prepared this YouTube video showing how to build Loop 2.2.x including the steps required to update if you previously built. The steps are different now. The video may be worth watching, but once you've reviewed it, work through the new build process described on this page.

If you do watch this video, please note that you no longer are required to delete provisioning profiles as a separate step and the overall building process is streamlined.

"},{"location":"build/build-app/#build-with-browser","title":"Build with Browser","text":"

If you previously used Build with Browser to install Loop on this phone, you should Disable Automatic Install from TestFlight to be sure the version of the app on the phone is the one you build with Xcode.

"},{"location":"build/build-app/#developer-mode","title":"Developer Mode","text":"

If you are running iOS 15/watchOS 8, you do not have Developer Mode and can skip ahead to Download Loop.

"},{"location":"build/build-app/#upgrade-from-ios-15-to-newer-version","title":"Upgrade from iOS 15 to newer version","text":"

If you upgrade an iOS 15 phone to iOS 16 or 17, the Loop app will not open until you enable Developer Mode on that phone.

You will see a message similar to the next graphic.

If you are running iOS 16 or 17 with watchOS 9 or newer, you must enable Developer Mode to run or build Loop directly from Xcode. (This is true for any app created by Xcode directly on your device.) If you want to know more, click on this Apple Link about Developer Mode.

"},{"location":"build/build-app/#prepare-your-phone-and-watch","title":"Prepare your Phone and Watch","text":"

If you have never built an app with Xcode on a particular phone, Developer Mode will not show up in the iOS Settings, Privacy & Security menu until you connect that phone to Xcode.

  • If you are building to a new Apple Watch - you must first pair that watch to the phone, build the app to the phone and then enable Developer Mode on the watch and then build to the phone again while watch is paired and on your wrist.

To keep all the steps in one place, the instructions for configuring phone and watch are kept in this one section. If you have never built with Xcode to this phone, skip ahead to Download Loop for now and return at the appropriate part of the script instructions below. A clear message with a link will bring you back here.

When Xcode is open and you plug in your phone, you will not be able to select the phone until you have enabled Developer Mode. The phone will show up, but be an \"Unavailable Device\" as shown in the graphic below.

"},{"location":"build/build-app/#developer-mode-on-iphone","title":"Developer Mode on iPhone","text":"

Once your phone has been plugged in to the computer while Xcode is opened and you accepted have the Trust this Computer option, you will be able to enable Developer Mode.

  1. Open your phone settings, choose Privacy & Security
  2. Scroll to the bottom of the screen and examine the Developer Mode row
    • If it says On - no further action is required
    • If it says Off, then tap on the row
  3. Slide the slider to the green (enabled) position
  4. Choose Restart
  5. After reboot, choose to Turn on Developer Mode
  6. You are now ready to begin building from Xcode onto this phone

If you are in the middle of building on a new phone, return to Initial Xcode Screens to continue.

"},{"location":"build/build-app/#developer-mode-on-watch","title":"Developer Mode on Watch","text":"

Build, Enable, Build

Reports from users indicate that when you are building to a new Apple Watch - you must first build the app with Xcode before the developer mode will be available. So plan to build with Watch paired, and then enable Developer Mode and build again.

This must be configured on the watch itself (not the watch app on the iPhone). To determine if Developer Mode is enabled, look at the watch face icons and find the Settings icon. Tap on it and scroll to and tap the Privacy & Security icon. Then scroll to the bottom and tap on Developer Mode. If you don't see the Developer Mode row under Privacy & Security, see the Extra Watch Instructions.

  • If Developer Mode is enabled, the slider will be green and no further action is required
  • If Developer Mode is not enabled, the slider will be blank
    • Move the slider so it is green
    • Reboot the device when asked
    • After the reboot, you are asked if you want to turn on Developer mode
    • Tap on the Turn On option
"},{"location":"build/build-app/#enable-watch-widgetkit-developer-mode","title":"Enable Watch WidgetKit Developer Mode","text":"

With the latest watchOS, there are now options that show up after you enable Developer Mode. Go on and configure those now. Select the Settings icon on the watch, but instead of tapping on Privacy & Security, scroll all the way to the bottom and there is now a Developer row at the very bottom of the watch Settings. If you don't see this row, reboot the watch again.

  • Tap on Developer
  • Scroll down to WidgetKit Developer Mode and enable that
  • This might enable faster updates of complications on your watch
"},{"location":"build/build-app/#extra-watch-instructions","title":"Extra Watch Instructions","text":"

There have been a lot of reports of trouble getting Developer Mode to show up on a new Apple watch and then having further trouble getting the Loop app to show up on the watch. Previously, just having the watch paired to the phone when you build once followed, by enabling Developer Mode on the watch and building again, was enough. If you have problems, here are extra steps to try.

These steps have been reported on Facebook and have not been tested in a controlled environment. They may not all be necessary.

  1. Restart watch, phone and computer
  2. Watch should be paired to your phone and on your wrist
  3. Go to Privacy & Security on watch and enable developer mode (didn\u2019t see prior to restart)
  4. Plug phone into computer and open Xcode
  5. Select Window (top menu) and choose Devices & Simulators
    • The watch should appear as a Disconnected device
    • Click on the watch and if it connects - you are done
  6. Otherwise manually add the UDID to your Developer Account
    • Copy UDID (right-click or control-click and choose Copy Identifier)
  7. Go to the Apple developer website, devices page and manually add the watch (using the UDID)
  8. With phone plugged into computer and watch on wrist, follow these steps on the build errors page: Apple Watch Loop App not running on Watch to build the watch app directly.

At this point, be sure to reboot the watch.

"},{"location":"build/build-app/#download-loop","title":"Download Loop","text":"

This page has the detailed steps to run the Build Select Script to download the Loop code, prepare your computer and build Loop.

Every attempt was made to put messages directly in the script for each step. The next few sections of this page walk you through what you will see when you run the script.

"},{"location":"build/build-app/#open-terminal","title":"Open Terminal","text":"

Go to the Finder app, click on Applications, then open the Utilities folder. Locate the Terminal app and double-click Terminal to open a terminal window. The terminal window is very plain looking when you open it. That is normal.

"},{"location":"build/build-app/#build-select-script","title":"Build Select Script","text":"

With the release of Loop 3, the build process is different and simpler

  • Please read each step as if you are a new builder
  • Don't assume you know what you are doing

These instructions show each step needed to download Loop using the Build Select Script.

Copy the line below that starts with /bin/bash by hovering the mouse near the bottom right side of the text and clicking the copy icon (should say Copy to Clipboard when you hover over it). When you click the icon, a message that says Copied to Clipboard will appear on your screen.

Copy and Paste to start the Build Select Script
/bin/bash -c \"$(curl -fsSL \\\n  https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildSelectScript.sh)\"\n

Paste the line of text into Terminal. Be sure to click anywhere in the terminal before trying to paste. (Ways to paste: Cmd+V ; or Ctrl click and select from menu or Edit-Paste at top of Mac screen.)

  • Please read what is on the screen as you progress
  • You can increase font size by holding down Cmd and hitting +

You will be informed of the menu options as shown in the graphic below. You will choose Option 1 to Build Loop.

You will be informed that you are downloading open source software. Type 1 and return if you understand the warning and agree.

The next screen informs you of what you will be downloading. Type 1 and return to begin the download or 2 to return to the main menu.

"},{"location":"build/build-app/#wait-for-download-to-complete","title":"Wait for Download to Complete","text":"

This download can take from 3 minutes to 30 minutes depending on your download speed. You can leave the room and return later to check on progress. When you read the words in the terminal, as the script runs, you may see terminology you do not understand - don't worry - you do not need to understand enumeration or submodule or cloning. You only need to review the display to look for any error messages.

New Feature

The Build-Script automatically reports when the download is successful.

The next graphic shows terminal messages for the beginning of a successful download.

If the download was successful, your terminal will be similar to the following graphic. Continue with the Download was Successful section.

If you see a failure message, scroll up in the terminal to find the error message(s) and go to Xcode Errors with Build-Select.

"},{"location":"build/build-app/#download-was-successful","title":"Download was Successful","text":"

If there are no errors, hit return to continue. The next step involves signing the targets.

"},{"location":"build/build-app/#sign-targets","title":"Sign Targets","text":"

What does Sign Targets Mean?

\"Sign Targets\" in Xcode identifies who built the app. You cannot deploy an app to a phone if you do not sign each target associated with that app.

Experienced Builders

This replaces several of the steps that used to be required to build Loop.

If you have never built an Xcode app using your developer ID on this computer, then the first time you use the script, you will be asked how you want to sign the targets.

I did not get this question

The script searches for your developer ID for you and skips this question if it finds it.

  • You have previously built an app on this computer with your developer ID
  • You have previously run this script

Skip ahead to Review LoopConfigOverride.xcconfig.

The next question, as shown in graphic below, is whether you will (1) Sign Automatically or (2) Sign Manually.

  • If you are building with a paid developers account, choose option 1, and continue on this page
  • If you are building with a Free option or plan to build to a simulator on your computer, choose option 2 and click on Build Free Loop to move to the page with those instructions

"},{"location":"build/build-app/#paid-developer-account","title":"Paid Developer Account","text":"

Continue with this page only if you have a paid developer account.

  • You need to switch to the Loop Free Build page for a free account.
"},{"location":"build/build-app/#create-permanent-loopconfigoverridexcconfig","title":"Create Permanent LoopConfigOverride.xcconfig","text":"

The following graphics show the terminal display after selecting option 1 to use Apple Developer ID.

  • Graphic below:
    • User is presented with instructions for getting Team ID from the Membership page
      • After review, the user hits return

  • Graphic below:
    • The instructions remain on the screen for reference
    • The developer.apple.com web page (not shown) opened automatically in the browser after user hit return
      • User obtains ID
    • User enters ID in terminal and then hits return

After hitting return, the user can verify the entry.

"},{"location":"build/build-app/#review-loopconfigoverridexcconfig","title":"Review LoopConfigOverride.xcconfig","text":"

Once the permanent signing file is configured, the review step is the same each time.

  • Graphic below:
    • The developer ID stored in the permanent file is displayed for review
    • After review, enter 1 to continue
    • OR - enter 2 to modify the ID in the file, see Problem with the ID?

"},{"location":"build/build-app/#problem-with-the-id","title":"Problem with the ID?","text":"

If there is a problem with the ID that is stored on your computer, you can modify it before continuing. The instructions, shown in the terminal message if you select option 2, Editing Instructions, are repeated here:

To edit the LoopConfigOverride.xcconfig file with a different developer ID:

  1. Open finder, navigate to Downloads/BuildLoop
  2. Locate and double click on LoopConfigOverride.xcconfig
    • This will open that file in Xcode
  3. Edit in Xcode and save file

You can now return to the terminal and hit return for the next step.

"},{"location":"build/build-app/#ensure-a-year","title":"Ensure a Year","text":"

The next question asks if you want to ensure a year with your new app. Unless you have a good reason, you should enter 1 and continue.

"},{"location":"build/build-app/#build-loop","title":"Build Loop","text":"

Build to Simulator

If you are an experienced builder and plan to build to a simulator on your Mac before building to your phone, you do not need to plug in your phone yet. You will need to select a simulator manually once Xcode opens.

For first time builders - go on and build to your phone.

"},{"location":"build/build-app/#plug-in-your-phone","title":"Plug in Your Phone","text":"

Refer to the graphic below. The messages in the terminal instruct you to:

  • Unlock your phone
  • Plug Phone into the computer
    • (Optional) If you have an Apple Watch that has never had Loop on it
      • Make sure watch is paired, unlocked and on your wrist
    • If you have never \"Trusted\" this computer with these device(s), do so now
      • A screen will pop up on your phone (and watch) asking if you trust the computer
      • Select \"Trust\"
      • After trusting phone and watch, phone should remain plugged in, but watch does not need to stay in proximity of the phone
  • Now you are ready to hit return in the terminal window

The next action of the script is to

  • Open Xcode

If this is a new phone that has never had an app built from Xcode, return to Prepare your Phone and Watch. After you get developer mode turned on for the phone continue with the build instructions. If you also want to set up the watch, you'll need to build one time, follow directions in Developer Mode on Watch and then build again.

It is suggested that you wait until you've successfully built the app before closing the terminal.

"},{"location":"build/build-app/#initial-xcode-screens","title":"Initial Xcode Screens","text":"

Refer to the graphic below. Your intial Xcode screen should be similar.

  • Wait for packages to download (see messages upper right - blue dashed rectangle)
    • You might see the words downloading or copying
    • Package download is complete when you see the words Indexing or Ready (upper right)
  • Make sure your phone (or simulator if you prefer) is selected in the upper middle

"},{"location":"build/build-app/#start-build","title":"Start Build","text":"

If there is a red x in the dashed-blue rectange region on your Xcode screen you need to click over to the Build Error page

"},{"location":"build/build-app/#first-time","title":"First Time","text":"

The first time you build, there will be steps that will not be required for subsequent builds. These are clearly marked in the intructions with the word First-Time. Do not get confused when you are asked to enter your password multiple times, see Codesign / Keychain Access. Be sure to enter your Mac login password and select Always Allow every time it is requested.

"},{"location":"build/build-app/#all-builds","title":"All Builds","text":"

Refer to the GIF below:

  • Frame 1: Packages are downloaded
    • Xcode is Indexing as seen in dashed-green rectangle region
      • Indexing makes searching faster; it does not need to complete before building
    • Click the \"Play\" button highlighted by red rectangle to start the build
    • First-Time for this Phone: A Device isn't registered screen appears, as shown in the graphic below the GIF
      • This happens for any phone not registered to the selected Developer ID
      • You must be connected to the internet so the device can be registered
      • Click register and then the build will continue (as shown in the GIF)
  • Frame 2: Build has started
    • Xcode is Building as seen in dashed-green rectangle region
    • First-Time on This Computer:
      • Follow the Always Allow Instructions the first time this Developer ID is used on this computer
      • Never hit Deny
  • Frame 3: Build succeeded
    • App is running as seen in dashed-green rectangle region
    • If your phone locked during the build process, you will see a message to unlock your phone, as shown in the graphic below the GIF
      • Simply unlock your phone and Xcode does the rest
      • If you tapped on Cancel Running, just hit the build button again
    • First-Time for this Phone: You may also see a \"Could Not Launch Loop\" message
      • Follow the Update Settings for Developer

If the app opened on your phone, the next two sections for first-time builders are not needed. Skip ahead to Successful Build.

If you got red error messages, skip ahead to Build Failed?

"},{"location":"build/build-app/#codesign-keychain-access","title":"Codesign / Keychain Access","text":"

First Time Using Developer ID on Computer

During your first build with a given Developer ID on your computer, you will see a codesign/keychain access prompt, as shown in the graphic below. Enter the same password you use to log in to the mac, select \"Always Allow\" and then do it again each time you are asked.

It is normal for this prompt to come up repeatedly even after you enter the correct password (once for each target Loop needs to sign).

In frustration, people think the prompt must be broken because it keeps reappearing and press deny or cancel. Don't press deny. Keep entering your computer password and pressing the \"Always Allow\" button as many times as it takes. The build will then continue.

FYI: codesign is for code sign - nothing to do with design.

"},{"location":"build/build-app/#update-settings-for-developer","title":"Update Settings for Developer","text":"

First Time Building on a New Device?

If this is the first time you have installed an app on your iPhone using a free account, you will see warnings in both Xcode and on your phone after a successful build and install on your phone.

Don't worry, dismiss the messages and do this extra step on the phone. These instructions are valid for iOS 15:

  • Open Phone Settings
  • Select General
  • Select VPN & Device Management
  • Under the Developer App section, tap on icon
  • Tap on Trust
  • You should now be able to open the app

"},{"location":"build/build-app/#what-if-the-automatic-signing-failed","title":"What if the Automatic Signing Failed?","text":"

Sometimes, something goes wrong with the automatic signing. Just the fact that you clicked on a few places in Xcode can change a particular file required to enable automatic signing. It is possible to reset that file, but it is easier to sign manually.

  • The instructions to sign manually are found at Build Free Loop
    • As you go through that page, ignore the steps that remove capabilities which require a paid Apple Developer account
    • Make sure you sign all 5 targets
    • Each signed target shows a Bundle Identifier with your 10-digit Apple Developer Membership ID embedded after com.
    • If you don't know how to find that number, there are very clear directions in the Build with Browser: Find TEAMID
"},{"location":"build/build-app/#build-failed","title":"Build Failed?","text":"

No red error messages? Skip ahead to Successful Build.

Red Errors

If you get a message that your build failed and see RED ERROR messages:

  • Go to the Build Errors page to find the steps to fix your build error
  • (Optional) Follow the Clear the Error Message process
  • Return to Start Build to try again

FAQ: But what about those yellow or purple warnings that remain in Xcode? Should I worry about them?

If you see yellow or purple warnings after your build is done...those are not an issue. Don't try to resolve them or fret about them. They mean nothing to the successful use of your Loop app.

NOTE: purple warnings are still warnings and can be ignored.

"},{"location":"build/build-app/#clear-the-error-message","title":"Clear the Error Message","text":"

Once you've resolved a build error and start the build process again, Xcode will continue to show a red indicator on the top line from the previous failure. If you don't like seeing that, clean the build folder to clear the error. Otherwise, as long as the steps of the build are showing across the top line, Xcode is still working on the build. When the build succeeds, the red circle will disappear.

Clean Build Folder

  • In Xcode menu, select Product, then Clean Build Folder
  • Wait for cleaning to complete: you'll see a \"Clean Finished\" message
"},{"location":"build/build-app/#successful-build","title":"Successful Build","text":"

After you see the Loop app open on your phone, you can unplug your phone and acknowledge the Xcode message: Lost connection to the debugger on . . .. The square icon next to the play button goes away as soon as you unplug your phone from Xcode.

The Loop app on your phone closes (but does not quit) when you unplug the phone. Open the Loop app on your phone just to be sure.

Congratulations!

If you plan to build again on a backup phone, or want to try a customization, easiest for you to leave Xcode open. Otherwise, you can quit out of Xcode now.

But wait - there's more.

  • Caregivers who help manage a loved-ones diabetes often use other open-source apps that can be built the same way
  • When you are done building and installing the Loop app, there are instructions on the Loop and Learn website to Download and Build Related Apps
"},{"location":"build/build-app/#protect-that-app","title":"Protect that App","text":"

Protect Against Deletion

Prevent your Loop app from being deleted accidentally.

If you, or a child, deletes the app from the home screen, it is gone - you have to rebuild and reenter all settings and start a new pod or add back in your Medtronic pump.

The steps vary depending on iOS. With iOS 15 and 16, it is under Screen Time, Content & Privacy Restrictions, iTunes & App Store Purchases, Deleting Apps. Choose Don't Allow. If those steps don't help, do an internet search like this, where you use your current phone iOS version number:

  • \"turn off app deletion iOS ##\"
  • \"iOS ## prevent app deletion\"

Follow the instructions to prevent deletion of what is now a critical medical app.

"},{"location":"build/build-app/#important-safety-reminder","title":"IMPORTANT SAFETY REMINDER","text":"
  • STAY IN OPEN LOOP UNTIL YOU UNDERSTAND THE SYSTEM
  • Do NOT skip the Set Up and Operate material; at least skim it.
  • Keep reviewing LoopDocs - some material will be more impactful once you have the app in your hands.
  • Ask questions if you are confused.
  • Learn to use the LoopDocs search feature
"},{"location":"build/build-app/#new-to-loop-3","title":"New to Loop 3","text":"

If this is your first build with Loop 3, head to the Set Up tab starting here: Loop 3 Overview.

Pro Tip: Read Along in LoopDocs as you Onboard

One of the goals for Loop 3 is to make the app robust even if you don't read the documentation, but a lot of questions may be resolved if you read along in LoopDocs as you onboard.

All those mentors who answer questions are volunteers.

Even if you don't read all the pages under the Set Up tab now, these links are important.

  • New Looper: Onboarding
  • Building Loop 3 over Loop 2.2.x: Experienced Looper Onboarding

Add a Calendar Reminder

  • It is good practice to add a reminder to your calendar when the app will expire
  • Be sure to add an alert to that reminder so you have enough time to do all the Loop Updating steps to build the app again before it expires
  • Even better, practice building every 3 to 6 months so you don't forget and keep that expiration date far in the future
"},{"location":"build/build-app/#optional-steps","title":"Optional Steps","text":""},{"location":"build/build-app/#code-customizations","title":"Code Customizations","text":"

New Loop users: Customizations are not a required part of any Loop build. As you gain experience using your Loop app, you may want to customize some of the features. First time builders are encouraged to build with the standard, default code. You can always update your Loop app to add customizations at a later time, using the same download. Subsequent build time is much faster than the initial build for a given download.

Pro Tip

With a fresh download of code, it's always best to build to a simulator without customization to ensure the build works without errors. Then add the customizations and check the build again. Now you are ready to build to your phone to update your existing app.

To add custom configurations to your Loop or Loop Apple Watch apps, follow the step-by-step instructions on the Code Customizations page and then build the app again.

"},{"location":"build/build-app/#apple-watch","title":"Apple Watch","text":"

Existing Apple Watch users: Please update your watchOS prior to building the Loop app. The minimum iOS for Loop 3 is iOS 15.1, which means watchOS 8.1. When running iOS 16.x, you will need a watchOS of 9.x.

New Apple Watch users: If you have an Apple watch and want to use it with Loop, first pair the watch with the iPhone before continuing to the next steps. If you get a new watch after building the Loop app, you'll need to redo your Loop build.

For more information, please see Operate: Apple Watch

"},{"location":"build/build-app/#build-again-with-this-download","title":"Build Again with this Download","text":"

Follow the Find My Downloaded Loop Code instructions if you later wish to build with this same dowload. Plug in an unlocked phone and start at the Start Build section of this page. You may need to select the phone you just plugged in. Everything else should be ready for you the start the build process.

Don't use a really old download

Do not use a really old download.

Check the date of your download against the latest Current Release date and decide whether to get a fresh download instead.

"},{"location":"build/build-app/#xcode-errors-with-build-select","title":"Xcode Errors with Build-Select","text":"

The errors shown below should be prevented - the script will attempt to correct them automatically - follow the directions in the script.

If this is not successful, the script told you the download failed and exited. Scroll up in the terminal to find the error message(s):

  • Read the error message
  • Try to figure out the problem
  • If you need help, reach out to your favorite Loop Social Media site

WARNINGS

If you see errors like these . . .

  • xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
  • xcode-select: Failed to locate 'git', requesting installation of command line developer tools
  • xcode-select: error: tool 'xed' requires Xcode

You missed one of these steps:

  • Install Xcode
  • Xcode command line tools
"},{"location":"build/build-dev-mac/","title":"Build Loop dev with Mac","text":""},{"location":"build/build-dev-mac/#overview","title":"Overview","text":"

This page is only relevant when building the dev branch with a Mac.

For Browser Build, please see: Build Loop dev with Browser

No matter the method used to build Loop-dev, you are testing development code. Please read this link now before continuing.

  • What's going on in the dev branch
"},{"location":"build/build-dev-mac/#buildloopdev-script","title":"BuildLoopDev Script","text":"

There is a script to assist in building the dev branch. It gives you the option to choose the tip of the dev branch or to build a lightly tested commit. If you have not used the Build Select Script to build Loop previously, you may want to review that page. The command below can be pasted into the terminal of your Mac. Read the directions in the script.

Copy and Paste to start the BuildLoopDev script

/bin/bash -c \"$(curl -fsSL \\\n  https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildLoopDev.sh)\"\n
Both the dev branch and the lightly tested branch of dev have Libre support.

"},{"location":"build/build-dev-mac/#buildloopdev-other-branches","title":"BuildLoopDev Other Branches","text":"

You can use the BuildLoopDev script to build a specific development branch, other than dev. See the example below that would build other-branch, if such a branch existed. This is just an example. You need to substitute the branch you desire for other-branch. There must be a space after the final quote, followed by a hyphen, another space and then the branch name.

Example using other-branch with the BuildLoopDev script
/bin/bash -c \"$(curl -fsSL \\\n  https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildLoopDev.sh)\" - other-branch\n
"},{"location":"build/build-dev-mac/#update-loop-dev","title":"Update Loop-dev","text":"

While Loop-dev is under active development, you should monitor zulipchat and update frequently.

Checking for updates every week is a good idea. Also - subscribe to all the streams on Loop Zulipchat to make sure you don't miss critical information.

You may choose to download fresh each time you update.

You may prefer to use commands to fetch and pull the latest code without making a new clone.

  • Some users like to use GitKraken to assist them (link takes you to a tutorial video).
  • Some are comfortable with the command line git commands described on here.
"},{"location":"build/build-dev-mac/#loop-dev-version","title":"Loop-dev Version","text":"

The version of code that shows up under the Loop Settings screen does not change when the dev branch is modified.

If you need help with your app, the mentors need more information. Please issue a Loop Report when asking for help. Refer to Support for how to issue a Loop Report. If you want to keep track yourself, refer to Identify Loop-dev Version

  • Loop Version Numbering
"},{"location":"build/build-dev-mac/#identify-loop-dev-version","title":"Identify Loop-dev Version","text":"

The version of code that shows up under the Loop Settings screen will remain fixed until Loop-dev is released. In order to identify which version of dev you have on your phone, you need the commit.

The commit is identified by a 7-digit alphanumeric code. That code was also appended to the folder name of the downloaded code under Downloads/BuildLoop as shown in the graphic above. You can use finder to view the folder name after the script completes. It also appears in the Loop Report, refer to Support for instructions on issuing a Loop Report. After you issue the Loop Report, look at the workspaceGitRevision number near the beginning of the report.

"},{"location":"build/build-errors/","title":"Oh dear! Build errors?","text":""},{"location":"build/build-errors/#build-errors","title":"Build Errors","text":"

Important

These are only relevant when building with a Mac and Xcode. For Building with Browser Build errors, please see: Errors with Browser

There are two types of build indications that may be seen: they are warnings (yellow or purple icons) and red errors. You'll see the warnings and errors in the left-hand column of the Xcode window.

Yellow and Purple warnings do not cause the build to fail, those are just warnings. You will often see yellow and purple icons. Ignore those. Do not try to do anything to fix those.

Red errors will have to be resolved before you can successfully build the app. The steps below explain how to resolve them based on the messages you are seeing.

"},{"location":"build/build-errors/#xcode-not-responding","title":"Xcode Not Responding","text":"

Sometimes, Xcode stops responding. You have to fix this before any of the other steps on this page will help. The signature is that Xcode shows a colorful spinning icon and does not respond to anything you do.

This can happen sometimes. You just need to force quit Xcode. Sometimes rebooting the Mac may be required, but start with force quit. Then just open up Xcode again and keep going.

  • Hold down these 3 keys Option+Cmd+Esc (or Alt+Cmd+Esc), until the Force Quit menu appears (should be fast)
  • Select Xcode and tap on the Force Quit button

"},{"location":"build/build-errors/#start-with-the-obvious-error-causes","title":"Start with The Obvious Error Causes","text":"

New Loop Builders

This page contains build error help for people updating their Loop app as well as brand new Loop app builders. Review the \"obvious\" errors causes first. If that doesn't help, then, skim the page until you reach Find Your Error Message or search the page (Cmd+F) or search LoopDocs for your error. Once you've identified your error message, try to resolve it. Still stuck? Read Posting for Help

Before you start trying to resolve your red errors, start with the most obvious things that can cause a red error message:

  1. For older builds, before 3.2.0, you had to select Loop(WorkSpace) The first time you build after downloading new code, you had to manually select Loop (Workspace) instead of Loop in Xcode.

    • Starting with Loop 3.2.0 and newer versions, the target name and xcworkspace file names are now automatically LoopWorkspace - no special action needed when building.

  2. Did you check that you have the minumum Xcode version for your iOS? This is critical. If you are updating your Loop app, please review the iOS driven requirements for minimum version of macOS and Xcode.

  3. Did you check your Apple developer account for new license agreement? Periodically, Apple will release a new developer license agreement that you need to sign before you can build new apps. You will get a build failure if there is a pending license agreement to sign. Login to your Apple developer account to check if there's a new license agreement.

  4. Do you have a new computer, never used to build Loop? Did you Add Apple ID to Xcode?

  5. Did you reboot, i.e., restart, your computer after updating Xcode? You should reboot following Xcode installation or update and you must make sure your command line tools match the version of Xcode you just installed. Xcode Command Line Tools

  6. Did you get a fresh download of Loop code? If you tried to build with an old download that you used a long time ago, that old version may not be compatible with the new iOS and Xcode versions. Check also, that you are actually using the new download in Xcode. When you use the Build Select Script, it automatically opens Xcode using the new download.

    If you want to build using a recent download, this section tells you how to Find My Downloaded Loop Code.

  7. Are you are using a free developer account? Make sure you finished the removal of Siri and Push Notification capabilities described in the Free Account link.

  8. DO NOT USE BETA VERSIONS If you are using an iOS beta version or an Xcode beta version, Loop might not build. Deleting iOS beta from a phone is a pain...so don't install it unless you know what you are doing.

"},{"location":"build/build-errors/#fix-95-of-errors","title":"Fix 95% of errors","text":"

If you have checked all those steps above and think you have a true build error, here's a tip that resolves 95% of all build errors when updating Loop code.

  1. Open your project in Xcode as normal. Then go to the menu bar at the top of the screen and find the Product menu item. Use the drop down selection for Clean Build Folder or press Shift+Cmd+K. Either will work the same. Wait for the clean to finish before trying to build again.
  2. On the far right, next to the name Full Path is the folder name that Xcode will be using to build. Make sure it is the new code you just downloaded and not an older folder.
  3. If you are updating Loop and did not Delete Old Provisioning Profiles, do it now
  4. Return to Xcode and try building your app again.
  5. Still failing for phone or watch or both? Try the Unpair and Reboot procedure.
"},{"location":"build/build-errors/#unpair-and-reboot","title":"Unpair and Reboot","text":"

This is reported to fix a variety of watch building errors and cannot prepare phone for development errors:

  1. Open Xcode (if not already open)
  2. Plug phone into computer and make sure it is unlocked
  3. Using the Xcode menu, select
    • Windows
    • Devices and Simulators
    • On left side, Right-Click (or Control-Click) on your phone
    • Choose Unpair Device

It may not be necessary, but the suggestion is to reboot phone, (watch) and Mac - in other words, you can try to build without rebooting, but if that fails, repeat the steps and reboot before trying again.

The next time you plug this phone into your computer, you will be asked to trust the computer on the phone (and watch). Note this is unpairing the device from Xcode and your computer, not the same as, and much faster than, unpairing your watch from your phone.

If the build fails again, look through the list below and see if you can match your error message with one of the error messages listed later in this page. If you really can't find your solution, then post for help. But help us help you.

  • Ignore yellow and purple warning messages - those are not errors - do not try to fix them
  • Confirm it really is an error not already on this page; read this page carefully, including all the circled bits in the images in the Specific Error Messages section
  • Follow the steps in the Posting for Help section
  • WE CANNOT HELP without version numbers and screenshots
  • Do not take pictures of your computer screen with your phone, use screenshots
"},{"location":"build/build-errors/#new-with-xcode-15","title":"New with Xcode 15","text":""},{"location":"build/build-errors/#cycle-inside-loop","title":"Cycle inside Loop","text":"

If you build any older version of Loop with Xcode 15, you will see this error: Cycle inside Loop: building could produce unreliable results.

Solution: Build Loop 3.2.3 or later

What about other forks

Other forks are not being maintained.

If you are using FreeAPS or Loop with Patches (from the loopnlearn GitHub username), it is time to switch to released code.

"},{"location":"build/build-errors/#new-with-xcode-14","title":"New with Xcode 14","text":"

This may change, but for now, the watchOS simulator is not automatically included with the Xcode 14.x download and install. Some version of the watchOS simulator is required to build Loop, independent of whether you use a watch.

You will be asked if you want to download & install. Make sure watchOS is selected.

If you are getting watch errors or having trouble with your watch, try this:

Tap on the Xcode name on the menu bar and select Settings.

Choose the Platform tab. If there is a missing watchOS simulator that you think might help, then download it using the GET button. Use the minus icon (bottom left) to remove simulators that are no longer being used. (The watchOS 9.0 is required to build with Xcode 14.0.1. The watchOS 9.1 was downloaded with a release candidate for Xcode 14.1 - your screens may look different.)

"},{"location":"build/build-errors/#posting-for-help","title":"Posting for help","text":"

STOP!! Read this section! Important!

Before you post in a Loop Social Media site asking for help with build errors, do your work first. The build errors listed below (and the checks listed above) will fix most of the problems you may encounter.

PLEASE READ THIS PAGE. The volunteers answering questions online would love to spend more time helping people use Loop and less time answering questions that can be addressed by using this page.

Therefore, try to resolve your build error yourself. Then, if you need to post for help, please include enough information with the post so the volunteers know where you are in your troubleshooting attempts.

Your Post Must Include:

  • The version of Xcode you are using
  • The version of Loop you are building with
  • The version of iOS on your Loop iPhone
  • Free or paid account, and if free, confirmation that you deleted Siri and Push Notification capabilities
  • Confirmation that you are not using an Xcode beta or iOS beta version (so we don't have to ask, please actually type \"I am not using beta versions\")
  • Screenshots of your WHOLE Xcode window and/or Terminal window showing your error and any messages you've seen while working through the build errors/solutions. Do NOT use phone photographs of your computer screen. See below for instructions on how to capture a screenshot.
  • State which fixes from the list below you have already tried AND post the screenshots of the results of those fix attempts.
"},{"location":"build/build-errors/#screenshots","title":"Screenshots","text":"

Please take screenshots of your issue and use them in your posts. On an Apple computer, press Shift+Cmd+4 keys at the same time followed by pressing the space bar Space and then click on the window of interest. The screenshot will be saved to your desktop with a file name starting with the name \"Screen Shot\". Use screenshots instead of cell phone images or words whenever possible. Screenshots are higher resolution and easier to read.

Use the whole Xcode window screenshot when posting for build help.

"},{"location":"build/build-errors/#find-your-error-messages","title":"Find Your Error Message(s)","text":"

To begin fixing the error, use the Report Navigator view to find your error message.

The key is to (1) READ THE ERROR MESSAGE and then (2) FIND YOUR MESSAGE IN ONE OF THE TOPICS BELOW.

Here's a super tip: Merely seeing the \"exit code\" in Xcode is not enough information to discern what error is causing your build to fail; some exit codes have multiple causes. Look at the detailed message to guide your search for the matching solution.

Notice the screenshots below have red circles highlighting certain error messages. Read your error message(s) from your screen, being guided by the red circles in the screenshots. Once you find your error message (hint: not \"exit code\"), you can either:

  • Take the error message from your Xcode screen and use LoopDoc's search function to enter in some of that phrase to bring up the appropriate solution topic, or

  • Take the error message from your Xcode screen and read through EACH OF THE TOPICS BELOW. Check each of the red circles to see if you have a match. Kind of like a matching puzzle.

For example, if you see \"Invalid active developer path (/Library/Developer/CommandLineTools)\" in your error message, use the search tool in LoopDocs with \"invalid active\". You will get a couple of links and one is the Command Line Tools fix for that error message. Click on the link and you'll find the solution.

"},{"location":"build/build-errors/#specific-error-messages","title":"Specific Error Messages","text":""},{"location":"build/build-errors/#unable-to-read-included-file-loopconfigoverridexcconfig","title":"Unable to read included file LoopConfigOverride.xcconfig","text":"

Error Message: This error occurs inside Xcode with the build halting at the line that reads the LoopConfigOverride.xcconfig file.

Solution:

Modify the permissions for Xcode in your macOS.

The graphic below has steps labeled 1 through 4 to guide you to the setting that must be enabled for you to build the app with Xcode.

  1. Open the macOS settings (Apple icon) and navigate to Privacy & Security
  2. Select Files and Folders
  3. Select Xcode
  4. Ensure that Downloads Folder is enabled

"},{"location":"build/build-errors/#no-devices-from-which-to-generate-a-provisioning-profile","title":"No devices from which to generate a provisioning profile","text":"

Error Message: This error occurs during the Build target WatchApp or Build target WatchApp Extension.

Communication with Apple failed: Your team has no devices from which to generate a provisioning profile. Connect a device to use or manually add device IDs in Certificates, Identifiers & Profiles. https://developer.apple.com/account/

No profiles for 'com.XXX.loopkit. Loop. LoopWatch' were found: Xcode couldn't find any iOS App Development provisioning profiles matching 'com.XXX.loopkit.Loop.LoopWatch'.

Solution:

  • Close Xcode
  • Reopen Xcode
  • Press the build button (\u25b6\ufe0f) again
"},{"location":"build/build-errors/#run-destination-is-not-valid-failed-to-prepare-the-device","title":"Run Destination is Not Valid; Failed to Prepare the Device","text":"

Error Message:

The run destination for name's phone is not valid for running the scheme \"Loop (Workspace)\"

Solution:

First make sure your Xcode version is new enough to work with your phone iOS version and make sure developer mode is turned on for iOS 16 or newer. If so, then try this procedure:

  • Follow the link for the Unpair and Reboot procedure.
"},{"location":"build/build-errors/#packageresolved-file-corrupted-or-malformed","title":"Package.resolved file corrupted or malformed","text":"

Error Message:

Package.resolved file is corrupted or malformed; fix or delete the file to continue: unsupported schema version 2

This error is new with Loop 3, which uses Package Dependencies.

There are 2 problems shown here

  1. The version of Xcode is out of date
  2. The graphic was acquired using a camera instead of a screenshot, and yes - that was a joke - using a camera does not cause a build error

Solution:

Update Xcode, which may require you to update macOS.

"},{"location":"build/build-errors/#couldnt-get-revision-for-package-dependency","title":"Couldn't Get Revision for Package Dependency","text":""},{"location":"build/build-errors/#many-search-143-for-this-error","title":"Many Search 1.4.3 for this Error","text":"

This error is new with Loop 3, which uses Package Dependencies.

  • If you notice a red x in Xcode (as circled in the graphic below)
    • Click on the red x to show the error in the left pane
    • Alternatively, you can click on the icon shown with the red square to see the same information

Error Message:

Text in error:

  • Uncategorized
    • Couldn't get revision . . .

Solution:

Refer to the graphic below

  1. Click on the folder icon (indicated by red square)
  2. Hold down the Control-Key and click the Package Dependencies row to display the dropdown menu (shown in the inset)
  3. Select Reset Package Caches from the dropdown menu and wait for Xcode to finish the reset process
  4. Once the package reset completes (updates in upper right of xcode will stop or say indexing), the red x should vanish
  5. You can start the build as soon as the Indexing message appears

"},{"location":"build/build-errors/#unable-to-read-included-file","title":"Unable To Read Included File","text":"

This error has been seen with Loop 3. The permanent xcconfig file, created by the build script and used to sign targets, is written to a folder where the user does not have read permission.

Error Message:

Text in error:

  • unable to read included file path inserted here

Solution:

No need to quit Xcode. If your build script terminal is still open, use it. Otherwise, open a new terminal window.

Copy the lines below that start with ls -l by hovering the mouse near the right side of the text and clicking the copy icon (should say Copy to Clipboard when you hover over it). When you click the icon, a message that says Copied to Clipboard will appear on your screen.

Copy and Paste to add read permissions to xcconfig file
ls -l ~/Downloads/BuildLoop/LoopConfigOverride.xcconfig\nchmod +r ~/Downloads/BuildLoop/LoopConfigOverride.xcconfig\nls -l ~/Downloads/BuildLoop/LoopConfigOverride.xcconfig\n

Paste the lines into the terminal. The response to the first line will be something like this:

--w-------  1 marion  staff  490 Nov  8 04:58 /Users/marion/Downloads/BuildLoop/LoopConfigOverride.xcconfig\n

There will be no response after the second line - although if an error is reported, please grab a screenshot.

The response to the last line will be something like this:

-rw-r--r--  1 marion  staff  490 Nov  8 04:58 /Users/marion/Downloads/BuildLoop/LoopConfigOverride.xcconfig\n

The addition of r where there used to be - on the left side, means you now have permission to read that file.

Final step is to return to Xcode and clean the build folder. Otherwise Xcode remembers it could not read the file and it won't try again.

  1. From the Product menu (of Xcode), select Clean Build Folder
  2. Press the Build Button (play icon)
"},{"location":"build/build-errors/#cycle-dependency","title":"Cycle Dependency","text":"

This error is new with Xcode 13.3 (late Sep 2021) which has a new requirement

  • For those who care: the new requirement is that for a certain type of instruction file, the line with the Headers keyword must be located before the line with the Sources keyword
  • There used to be many repositories that did not have lines in that order
  • If you are seeing this error, you are building with an older copy and should consider updating

Error Message:

Text in error:

  • Left window (the exact target names are not important):

    • Cycle in dependencies between targets . . .

  • Middle window:

    • Target build order preserved because \"Build Order\" is set to \"Manual Order\" in the scheme settings

Solution:

No need to quit Xcode - follow these steps using the Xcode Menu bar. (It's possible that only Step 1 is required, but sometimes all steps are needed.)

  1. From the Product menu (of Xcode), select Clean Build Folder
  2. From the File menu, select Close Workspace
  3. From the File menu, select Open Recent and choose the top line
  4. Press the Build Button (play icon)
"},{"location":"build/build-errors/#entitlements-error","title":"Entitlements Error","text":"

Error Message:

Text in error message can be either of these:

Entitlements file \"WatchApp Extension.entitlements\" was modified . . .

or

Entitlements file \"Loop.entitlements\" was modified . . .

Solution:

No need to quit Xcode - follow these numbered steps as indicated in the graphic below.

  1. Click on the Loop icon under PROJECT
  2. From the Product menu (of Xcode), select Clean Build Folder
  3. Press the Build Button (play icon)

It turns out that

  • You can start building before indexing completes - just make sure it has started
  • The behavior causing this in Xcode has been reported to Apple
"},{"location":"build/build-errors/#compileassetcatalog-error","title":"CompileAssetCatalog Error","text":"

This error is found when there is a space embedded in the path name to your LoopWorspace folder. The good news is that LoopWorkspace seems to be able to build from an iCloud or Dropbox drive.

Text in error message:

Command CompileAssetCatalog failed with a nonzero exit code. . .

Solution:

This is very similar to the steps for the WatchApp Entitlements Error but you need to repeat it for 2 targets: Loop and WatchApp - the graphic below matches the step numbers in the list.

  1. Click on Loop folder
  2. Click on Loop target
  3. Click on the General tab
  4. Click on the App Icons Source dropdown menu
  5. Click on the item already selected (the line will change from red to blank)

  • Repeat the App Icons Source dropdown menu selection for the WatchApp target
  • (Optional) Clear the Build Error (Menu at top of Xcode: Select Product->Clean Build Folder)
  • Press build
"},{"location":"build/build-errors/#carthage-error","title":"Carthage Error","text":"

For older builds only. With Loop 3.2.0 and newer, the default selection is already LoopWorkspace.

You should not see carthage errors, but if you do, you probably did not select Loop (Workspace) at the top of the Xcode window. Review the graphic from the Prepare to Build Instructions.

Or maybe you are trying to build using an old download; some older versions did require carthage. Best practice is to download new code.

Error Message:

Wrong Version of Carthage Error

Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/lipo: one of -create, -thin , -extract , -remove , -replace , -verify_arch \u2026 , -archs, -info, or -detailed_info must be specified.

Solution: Download fresh code with Build Select Script.

"},{"location":"build/build-errors/#could-not-locate-device-support-files","title":"Could Not Locate Device Support Files","text":"

Error Message: \"Could not locate device support files.\" That message is telling you that your iOS on the Loop phone requires you to get a newer version of Xcode to be able to build Loop onto that phone.

Solution: Update your Xcode version; this may also require a macOS update. Please review the phone iOS driven requirements for Xcode and macOS.

"},{"location":"build/build-errors/#no-such-module-loopkit-or-similar-message","title":"No Such Module 'LoopKit' or Similar Message","text":"

Error Message: If you see a Cartfile failure and several other red errors (in particular saying there is \"no such module 'LoopKit'\").

Solution: Read the Carthage Error section above.

"},{"location":"build/build-errors/#developer-license-update-pla-update","title":"Developer License Update (PLA Update)","text":"

Error message: The Apple Developer Program License Agreement has been updated, In order to access certain membership resources, you must accept the latest license agreement. Or you may see Unable to process request - PLA Update available. You currently don't have access to this membership resource. To resolve this issue, agree to the latest Program License Agreement in your developer account.

Solution: You'll need to log onto your Apple Developer account at developer.apple.com and accept the latest license agreement.

"},{"location":"build/build-errors/#could-not-get-a-container-directory-url","title":"Could Not Get a Container Directory URL","text":"

Error message: \"Could not get a container directory URL. Please ensure App Groups are set up correctly in entitlements.\"

Solution: To resolve this error, you will need to click on the Loop target's signing area and then the plus-sign in the App Groups area under the signing. Copy and paste the bundle indentifier into the new container that starts with group. and then add Group to the end of the name. Click OK to save. Note, the line will start with lower case group. followed by your bundle identifier and an upper case Group added to the end of the bundle identifier.

The final App Group should now have a blue check box, the name should start with group and end with LoopGroup. See the screenshot as an example. Click the build button after your App Group is setup similarly and you should be good.

"},{"location":"build/build-errors/#missing-command-line-tools","title":"Missing Command Line Tools","text":"

Error message: \"Invalid active developer path (/Library/Developer/CommandLineTools)\"

Solution: Go to your Xcode -> Settings and under the Locations tab, select your Xcode version (the figure shows 14.0.1 - yours should match your Xcode version) in the dropdown menu for Command Line Tools.

"},{"location":"build/build-errors/#device-management-could-not-launch-loop","title":"Device Management Could Not Launch Loop","text":"

Error message: \"Could not launch \"Loop\". Verify the Developer App certificate for your account is trusted on your device. Open Settings and navigate to General -> Device Management, then select your Developer App certificate to trust it.\"

New Solution First try the Unpair and Reboot process above. If that doesn't work, then try the solution listed below.

Solution: If you get this message and are unable to find the Device Management option in your phone settings, then we need to do a little extra step to clear out some old info.

  1. Plug the phone into the computer and open Xcode
  2. Click the \"Window\" menu item in Xcode and then choose \"Devices and Simulators\"
  3. Right click your phone on the left and pick \"Show Provisioning Profiles\"
  4. Delete all of the items in the list that have Loop in the name
  5. Go to your four signing targets and change the signing team back to \"None\" for a quick bit, and then change back to your regular signing team name again.
  6. Rebuild Loop

That should clear the out, problematic profiles and allow a successful build.

If your problem persists after that, then you might need to do total reset of your phone to clear out the pesky problem. Before you do this, you may want to Post for Help to make sure it is really necessary:

  1. Wipe the iPhone clean and set it up as a new device
    • FIRST - write down or screenshot all your settings
    • Pod users - you will have to start a fresh pod after this
    • If you want your old pod to continue giving you basal rate, don't replace the pod before wiping your phone. Once the phone is reset and a new Loop app is added, you must start a new pod. The old pod should have the sound connection broken before being discarded because you won't be able to deactivate the pod.
  2. Delete all certificates from your Developer account (you'll need to login to your Developer account to do that)
  3. Delete your old Loop code download and get a new one.
  4. Rebuild Loop on the phone with the new download of Loop code.
  5. Start a new pod with the new Loop app on the reset phone.
"},{"location":"build/build-errors/#pending-certificate-request","title":"Pending Certificate Request","text":"

Error message: \"You already have a current iOS Development certificate or a pending certificate request.\"

Solution: This error message has recently started to appear for some new Loop builders. To resolve the issue, please log in to your Developer account at developer.apple.com and then click on \"Certificates, Identifiers & Profiles\". Under that screen, you will see \"Development\" under the \"Certificates\" section in the column on the left. You will need to click on the certificates, and choose \"revoke\" from the options that show after you click on the certificate. Confirm the warning message that will appear asking \"Do you want to revoke the certificate?\"

After you do that, return to Xcode and open up Xcode -> Settings and choose the Accounts tab. Highlight your Apple ID and click on the minus sign to delete your Apple ID.

Re-enter your Apple ID (yes...add that account right back that you literally just deleted), return to your Loop's target signing areas in Xcode and your error message should have resolved as a new certificate will have been issued and a provisioning profile should have been created automatically.

You can verify the iOS development certificates are working by clicking on \"Manage Certificates\" in Xcode -> Settings, Accounts tab and viewing the iOS Development Certificates. You should have one for your account that has a clean status similar to the screenshot below.

"},{"location":"build/build-errors/#command-codesign-failed","title":"Command CodeSign Failed","text":"

Error message: \"errSecInternalComponent, Command CodeSign failed with a nonzero exit code\"

Solution: This error message is likely due to inadvertently saying \"no\" to allowing Keychain Access or changing your computer or AppleID password. Regardless, the solution is as follows:

  1. Close Xcode
  2. Open your Keychain Access application (found in Applications within the Utilities folder)
  3. In the upper left corner of keychain access, make sure you have the keychain login highlighted and then right-click the lock next to the login. Click the lock closed, and then click the lock to open it again. You will be prompted for a password. Enter your computer admin password. Close Keychain Access app.

  1. Open your Loop project again in Xcode.
  2. In the main Xcode menu (grey menu bar at the very top of your Apple display area), select Product and then select the option for Clean. (Keyboard shortcut is Shift+Cmd+K)
  3. Now try rebuilding your Loop app. If you ever get prompted again to allow Xcode access to Keychain, make sure to click on the option to Always Allow.
"},{"location":"build/build-errors/#unrecognized-arguments","title":"Unrecognized Arguments","text":"

Error message: \"Unrecognized arguments: --cache-builds\"

Solution: This is a homebrew / carthage error, so I don't think you'll see this. If you do, download a fresh copy of Loop code and try again. If it repeats, it is time to request assistance. Please read Posting for Help.

"},{"location":"build/build-errors/#abort-with-payload","title":"Abort with Payload","text":"

Error message: \"Abort with payload\" Your app will only open briefly with a white screen and then close, if you build with this error.

Solution: This error message is caused by having the Loop download folder in an iCloud mapped drive when doing the zip download. Move your Loop download folder back to the Downloads folder, then rebuild. LoopWorkspace builds with Xcode 13 appear to work fine with an iCloud drive. You may run into the spaces in your path name problem - which has a different solution.

"},{"location":"build/build-errors/#apple-watch-issues","title":"Apple Watch Issues","text":""},{"location":"build/build-errors/#apple-watch-loop-app-not-appearing","title":"Apple Watch: Loop App Not Appearing","text":"

Error: Apple watch app is not appearing.

Solution: This error usually appears because you have not updated the watchOS prior to building Loop, or you didn't have your Apple watch paired at the time of building Loop.

Don't forget to open the iPhone's Watch app, select My Watch tab on the bottom left, scroll all the way down, and click Install for the Loop app listed at the very bottom under \"available apps\".

"},{"location":"build/build-errors/#apple-watch-loop-app-not-installing","title":"Apple Watch: Loop App Not Installing","text":"

Before trying this solution, see if the Unpair and Reboot procedure works.

Error: The Loop app appears on the list of apps available to install on the watch, but when you press \"install\", and it goes through the animation of filling in the circle while it's installing, but then at the end it just toggles back to saying \"INSTALL\".

Solution: Plug your iPhone into the computer and start Xcode. On your watch, look for a prompt that says \"Trust this computer\". Scroll down on the watch face and select the \"Trust\" button. In Xcode, go to the top menu bar and select \"Clean Build Folder\" from the Product menu option, and then rebuild your Loop app.

If the watch app still fails to install properly, the next section should work.

"},{"location":"build/build-errors/#apple-watch-loop-app-not-running-on-watch","title":"Apple Watch: Loop App Not Running on Watch","text":"

Error: Tapping the Loop app icon on the watch results in flash of the watch screen and then return to the Loop app icon or a brief display of the watch interface and then return to the Loop app icon.

Solution: Plug in your iPhone, with the watch already paired, into the computer and start Xcode with your current build folder. In Xcode, from the list of schemes where you normally choose Loop (Workspace) (with Loop 3.2.x and newer, LoopWorkspace is the default), choose the WatchApp scheme (near the bottom of the list) and then select your watch (not a simulator) from the device list, see the graphics below. Press the play button to build and deploy the WatchApp directly to your watch. It will launch correctly and will not crash when you subsequently launch it from the complication or your watch Home Screen..

Warning: Make sure your watchOS is up to date with respect to your phone iOS. If not, you may need to update to be successful. On pressing clicking build/play, some people report receiving an error stating \u201ciPhone/Apple Watch are ineligible because the OS on the watch doesn\u2019t support WatchKit App Products\u201d or similar wording. This is a known issue with some Mac USB ports. Fixes in preference order are: 1) swap which USB port is in use; 2) unplug and replug the USB cable from both the iPhone and Mac; or 3) as a last resort, reboot the iPhone and Mac.

Don't forget to select Loop(Workspace) after building to the watch before trying to build to a phone.

"},{"location":"build/build-free-loop/","title":"Build Free Loop","text":""},{"location":"build/build-free-loop/#prepare-to-sign","title":"Prepare to Sign","text":"

This page is not stand-alone. You typically get here after choosing to Sign Manually after a successful download using the Build Select script.

Normally this option is chosen by people building the app with the Free option or if you want to build to a simulator on your computer.

If you have a paid developer account and are building Loop 3, you are far better off choosing to configure the permanent override file with your Apple Developer ID. Refer to Sign Targets.

The instructions found on this page are for the first build. With the Free version, you need to build every week. Refer to Build Again with this Download.

"},{"location":"build/build-free-loop/#select-the-loop-folder","title":"Select the Loop Folder","text":"

Don't touch that button!

You will be told exactly where on each screen you should click. Please only click in the designated places.

Follow the directions and compare your Xcode screen to the graphics as you walk through the steps.

As shown in the GIF below:

  • Frame 1: This is what the Xcode screen looks the very first time it is opened after a fresh download
    • You need to click on the indicated Loop folder icon two times
  • Frame 2: After the 2 clicks, the middle pane of the Xcode window should be similar (for Loop 3.2.x and newer, the top middle bar will show LoopWorkspace, not Loop)

"},{"location":"build/build-free-loop/#select-your-phone","title":"Select Your Phone","text":"

If this is the First Time your phone or watch has been connected to Xcode, you will need to tell the phone and watch to \"Trust this Computer\".

The GIF (not updated for Loop 3.2.x) below shows:

  • Frame 1: Same as end of previous GIF
    • There's a red rectangle around the dropdown menus
    • The menu on the left says \"LoopWorkspace\" for 3.2.x and newer
  • Frame 2: Same as Frame 1 with a zoomed inset of the red rectangle
    • Ignore Frame 2 and 3 for Loop 3.2.x and newer which already shows LoopWorkspace
    • You can see Loop has a check mark beside it
    • Loop (Workspace) is one line below
    • Select Loop (Workspace)
  • Frame 3: Zoomed inset after selecting Loop (Workspace)
  • Frame 4: Desired result should show LoopWorkspace and your phone

I don't see my phone

  • If you don't see your phone in the Devices section, unplug and plug in again
  • Still don't see your phone - reboot the phone - and if that doesn't work - reboot the computer
  • Still don't see your phone - try a different cable or USB slot
"},{"location":"build/build-free-loop/#build-to-a-simulator","title":"Build to a Simulator","text":"

Skip this section if building to a phone and proceed to Select Signing & Capabilities Tab.

If you want to build to a simulator, follow the directions in this section and skip the rest of this page.

  • Simply choose one of the iOS Simulators instead of a phone and build to it
    • The iOS simulator you choose does not need to be the same model as your phone
  • With a simulator, you do not need to sign targets:
  • After a successful build, a simulated phone will appear on your computer and you can interact with the app on that simulated phone
  • Follow this link to Start Build
"},{"location":"build/build-free-loop/#select-signing-capabilities-tab","title":"Select Signing & Capabilities Tab","text":"

What does Signing Targets Mean?

\"Signing Targets\" in Xcode identifies who built the app. You cannot deploy an app to a phone without signing each target associated with that app.

The graphic below indicates in red the three places you need to click in order to begin signing targets.

  • First, click on the tab labeled Signing & Capabilities
  • Second, click on the icon labeled Loop under the word TARGETS
  • Third, click on the dropdown menu (red circle) by the word Team

Click Only where Instructed

  • Make sure All, indicated by dashed blue oval, is selected
    • If Debug or Release is accidentally tapped, you will not be able to build
  • Make sure Automatically manage signing, indicated by dashed blue rectangle, is checked

"},{"location":"build/build-free-loop/#sign-the-targets","title":"Sign the Targets","text":"

It is time to Sign the Targets with your Apple ID.

If you chose to sign manually but have a paid account, you can skip the Free Account steps below.

You will be building multiple targets to make a complete app and must sign each one. With Loop 2.2.x, there are 4 targets. With Loop 3, there are 5 targets.

Start with the Loop target, the first one on the target list. Choose your Apple ID.

"},{"location":"build/build-free-loop/#free-account","title":"Free Account","text":"

This section is required if you are using the free account.

Some features of Loop are not available with the Free option, so as you sign, you will need to remove features that are not supported.

  1. You must remove unsupported capabilities from 2 targets, this is best done as you sign each target:
    • Loop Target: Push Notifications; Siri and Time Sensitive Notifications
    • Watch App Extension Target: Siri
  2. Add the keyword SIRI_DISABLED to the LoopConfigOverride.xcconfig file
    • Click on the filename in the left pane of Xcode and view it in the Xcode editor
    • Examine the file and find the line that starts with SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited)
    • Insert the new keyword (separated by a space) anywhere after $(inherited) and before the slashes near the end of the line
    • When done, that line should be similar to:SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited) SIRI_DISABLED

Details about removing unsupported capabilities:

  • You must disable Push Notification, Siri and Time Sensitive Notifications
    • If the target you are signing does not use one of these attributes, no error message will appear when you select (personal team) for that target
    • If the target you are signing does use one of these attributes, an error message will appear when you select (personal team) for that target
  • The Xcode error message starts with \"Cannot create . . .\" with a list of all the attributes not supported.
    • Scroll down and click on the little trash can icon next to each unsupported attribute
  • Scroll up and both the \"Cannot create . . .\" and \"No profiles for . . .\" error messages are gone
  • You are done with this target
  • Proceed to the next target
"},{"location":"build/build-free-loop/#end-of-free-account-steps","title":"End of Free Account Steps","text":"

Click on each of the three remaining targets shown in the red box below, and repeat the signing steps by choosing the same team name as you selected in the first target. The targets that must be signed prior to building are Loop, Loop Status Extension, Watch App, and WatchApp Extension for Loop 2.2.x, with the addition of Loop Intent Extension for Loop 3.

After signing the targets, click on the Loop icon under the PROJECTS heading. (Refer to the bright blue box in graphic above - click on that Loop icon.)

  • If you skip this step, you may get an \"Entitlements\" Build Error for either Loop or WatchApp
    • Follow this procedure to fix the error: Entitlements Error
    • Much easier to just click on Loop under Projects
"},{"location":"build/build-free-loop/#signing-complete","title":"Signing Complete","text":"

Now that you have signed your app, return to the Build Loop page at Start Build.

"},{"location":"build/cgm/","title":"Compatible CGM","text":""},{"location":"build/cgm/#compatible-cgm","title":"Compatible CGM","text":"

Time Estimate

  • 10 minutes to read this page

Summary

The Loop app is compatible with:

  • Dexcom G4 Share, G5, G6 or ONE CGM systems
    • Dexcom ONE (based off G6 sensor) is available in some countries, but will be discontinued soon
  • Dexcom G7
    • Dexcom ONE+ (based off G7 sensor) is available in some countries
    • At the current time, the Dexcom ONE+ cannot be used with Loop but pay attention to social media - an early indication is that a simple patch will allow this to work, but that patch is not available - more testing is needed
  • Medtronic sensors connected to a Loop-compatible Medtronic pumps
  • Some Libre sensors: dev branch only

FAQs

  • \"What about Libre sensors?\"
    1. Libre support is available in the Loop-dev branch - be sure to read information at that link about running the dev branch
  • \"What about Eversense?\" Refer to CGMs Not Supported in the Loop App
"},{"location":"build/cgm/#continuous-glucose-monitor-cgm","title":"Continuous Glucose Monitor (CGM)","text":"

The Loop app uses your CGM glucose readings, carbohydrate input and therapy settings, to model your current glucose trend, predict future glucose and automatically adjust insulin dosing. A compatible CGM is essential to operation of the Loop app.

"},{"location":"build/cgm/#dexcom-g5-g6-and-one-cgm","title":"Dexcom G5, G6 and ONE CGM","text":"

The Dexcom G5, G6 and ONE CGM transmits data directly to the Dexcom app on your iPhone via Bluetooth.

The Dexcom ONE, available in some countries, acts just like the G6 as far as the Loop app is concerned. The Dexcom ONE app does not provide some features, such as Dexcom Share, that come with the G6. When you set up the Loop app, select Dexcom G6 as your CGM to use Dexcom ONE CGM with the Dexcom ONE app installed on your phone.

Dexcom ONE+ is not yet compatible

There are reports that Dexcom is transitioning to the ONE+ based off the G7 platform. These devices cannot be used with the Loop app at this time.

Pay attention to social media - an early indication is that a simple patch will allow this to work, but that patch is not available - more testing is needed.

Only available in some countries. This link is for Poland Dexcom ONE+

If the Dexcom app is on the same device as the Loop app, your system can function without an internet connection. See Offline Use below.

Dexcom G5 Support

Dexcom has stopped supporting the G5 system in the US. In the US, and some other countries, the G5 is not available for download from the Apple Store. There are countries in which Dexcom does supply and support G5. The G5 capability will continue to be supported in Loop.

There are third party apps, which interface with G4 and G5 transmitters, supported by some forks of Loop. The version of the Loop app supported by these documents only works with the Dexcom apps.

"},{"location":"build/cgm/#dexcom-g7-cgm","title":"Dexcom G7 CGM","text":"

Dexcom G7 is supported with version 3 or greater of the Loop app.

"},{"location":"build/cgm/#medtronic-cgm","title":"Medtronic CGM","text":"

The Minimed Enlite CGM, available with the Medtronic 522/722, 523/723, and 554/754, wirelessly sends glucose readings to the pump. The Loop app can read the Medtronic CGM data directly from the pump using a RileyLink compatible device.

"},{"location":"build/cgm/#offline-use","title":"Offline Use","text":"

\"Offline Use\" means using the Loop app when there is no cell data or internet available. The Loop app does not require any special setup to operate offline.

For offline use, the iPhone's Bluetooth still needs to be active; and for Dexcom users, the G5, G6 or G7 app also needs to be running on the same phone as the Loop app. If you put your iPhone into Airplane mode, remember to turn Bluetooth back on to keep both the CGM and the Loop app running. If your offline use is failing, chances are you have forgotten to update your transmitter ID in the Loop app settings when you changed transmitters.

"},{"location":"build/cgm/#dexcom-share","title":"Dexcom Share","text":"

The Loop app can download Dexcom Share data for use in modeling glucose. However, this is not a typical configuration and requires internet connection for both the phone with the Dexcom app and the phone with the Loop app. The steps for adding a CGM explain that you usually enter the Dexcom transmitter ID and leave the Dexcom Share setting blank.

Dexcom ONE

The Dexcom ONE app does not support Share.

"},{"location":"build/cgm/#nightscout-as-a-remote-cgm","title":"Nightscout as a Remote CGM","text":"

Version 3 or later of the Loop app can use Nightscout as a remote source for CGM data. This requires cell or WiFi connection.

"},{"location":"build/cgm/#cgms-not-supported-in-the-loop-app","title":"CGMs Not Supported in the Loop App","text":"

Libre Support (for some Libre sensors) is available with Loop-dev or by adding customizations.

  • Loop dev adds LibreTransmitter
  • Loop and Learn: Loop Customization

Currently, there are no solutions for Eversense, Guardian or Libre 3 CGM to be used directly with the Loop app, but some Uploaders to Nightscout are available using an Android phone. Version 3 or later of the Loop app allows the use of Nightscout as a CGM source.

"},{"location":"build/cgm/#next-step","title":"Next Step","text":"

If your compatible pump is Medtronic or Omnipod (not DASH)

  • Next step is to Order a RileyLink Compatible Device

If your compatible pump is Omnipod DASH

  • Next step is to enroll in the Apple Developer Program.
"},{"location":"build/community/","title":"Meet the Community","text":""},{"location":"build/community/#meet-the-community","title":"Meet the Community","text":"

Time Estimate

  • Read about your Social Media Options: 5 minutes
  • Join one or more groups: 10 minutes

Summary

  • Learn how to use the search tools explained in How to Ask for Help
  • Learn the motto \"Help us help you\".
  • Learn what information helps in solving a problem in building or in using Loop

FAQs

  • \"I'm worried I'll ask a stupid question\" Don't worry. All the mentors started out as novices. Focus instead on asking a thorough question. A thorough question explains what you've already tried or read, has screenshots of what you are confused by, and any other details you can provide.
"},{"location":"build/community/#online-groups","title":"Online Groups","text":"

There's a wonderful community of Loopers who are willing to help you through the process. This link on Social Media Options walks you through those groups and how to join.

Volunteers provide assistance on building and using the Loop app at these sites. None of the people are paid to answer questions or spend time troubleshooting. They simply want to help others. Please decrease their support burden by doing your homework and providing the information they need when requesting help. Please click the image below to watch this video full of tips to make the most of your online resources.

Please watch this video (just under 7 minutes) to learn about using announcements and searches in Facebook groups and the LoopDocs pages.

Note, the LoopDocs menus were reorganized after this video was prepared to make it easier to progress through the pages.

"},{"location":"build/community/#screenshots","title":"Screenshots","text":"

Please take screenshots of your issue and include them in your posts. On an Apple computer, press Shift+Cmd+4 keys at the same time and a little crosshairs tool will appear. Click-and-drag across the area you'd like to include in the screenshot. When you let go of the button, the screenshot will be saved to your desktop with a file name starting with the name Screen Shot. To capture an entire window, press Shift+Cmd+4 keys at the same time followed by pressing Space (the space bar) and then click on the window of interest.

Use screenshots instead of cell phone images whenever possible. Screenshots are higher resolution and easier to read.

Take a wide screenshot (full window capture) when asking for help with settings or Xcode build errors. Nightscout and Xcode have lots of valuable information off-to-the-side that can be valuable for troubleshooters.

"},{"location":"build/community/#descriptive-language","title":"Descriptive Language","text":"

Use descriptive language - the most accurate, detailed words possible - when asking for help. Try to avoid the word \"it\" and instead use details and information to explain why you're asking for help, what you've already tried, and what happened when you tried those things (including screenshots). Let's illustrate with a couple of examples.

"},{"location":"build/community/#example-1","title":"Example 1","text":"

The Loop app no longer allows you to enter your correction range in the wrong order, i.e., 110 to 90; but it once did and the Loop app would stop working. We're using that problem as an example below.

Bad: \"It's not working.\" <----makes me wonder what \"it\" is? What part of \"it\" isn't working exactly? The app? The glucose control? The pump integration? Alarms? Bolusing? CGM

Ok: \"My Loop app won't open.\" <---- Ok, so now I know the Loop app itself seems to be the problem, but still don't know if this is a build error or an error that has happened after building. The solutions might be different.

Better: \"My Loop app was working yesterday just fine, and now today it's not doing the things like I expect.\" <----- Getting closer. Now, I know this is not a build error and that it sounds like a more recent issue. I'm starting to narrow down the potential causes. This is about as much detail as it takes for me, as a volunteer, to consider helping. I might not have to ask 42 questions, but instead only 4 questions to find the remaining information for troubleshooting. If there were more details, it would save time.

Awesome: \"My Loop app was working yesterday. Around lunch time, I went into the settings screen and made some adjustments and ever since it just turns white and closes no matter what I try.\" <---- DEFINITELY getting closer. Now I have a strong suspicion about where the bug is happening and can help with a couple links.

GOLD MEDAL WORTHY: \"My Loop app was working yesterday. Around lunch time, I went into the settings screen and made some adjustments to correction ranges. Ever since I did that, the app immediately turns white and shuts down. I have tried restarting my phone, but it has not fixed the problem. I tried searching the docs for 'loop closing' but didn't see results that matched my issue.\" <----- This person is doing an outstanding job of describing the problem. Lots of good details. Has shown initiative to try to use the resources already. This person did an excellent job of helping all of us help them.

"},{"location":"build/community/#example-2","title":"Example 2","text":"

This example is not quite as old, but does refer to details from older Loop and iOS versions. It exemplifies the details needed to assist someone with a build error.

Build with Browser

If you are using the Build with Browser method, we still need descriptive details but we do not need screenshots. All that is required is to list your GitHub user name. The volunteers can then read your publicly available log files. (All private information is automatically redacted in those logs.)

Bad: \"My Loop app won't build.\" <----- What step are you on? What is the iOS on your phone? What kind of computer are you using? What macOS? What Xcode version? Have you built successfully before or is this new?

Ok: \"I'm trying to update my Loop app and am getting a few errors that I don't understand.\" <----- Wow, sure would be nice to know what those error messages are. Are they red or yellow? A screenshot sure would help here.

Awesome: \"I have a macOS Big Sur 11.5.3 computer with Xcode 12.5.1 and my phone is running iOS 14.7.1. Downloaded Loop-master (2.2.6) this morning and I'm getting some red errors about an exit code that I don't understand. I've tried everything in the docs and nothing worked.\" <---- While I'm super happy they \"tried everything\", I'm no closer to knowing what the exact error message is nor which \"stuff\" exactly they tried. But all the version numbers are included.

GOLD MEDAL WORTHY: \"I have a macOS Big Sur 11.5.3 computer with Xcode 12.5.1 and my phone is running iOS 14.7.1. Downloaded Loop-master (2.2.6) this morning and I'm getting some red errors about an exit code 645 that I don't understand. Here's the screenshot of the error message. I tried searching the docs for \"exit code 645\" and didn't see any responses that helped.\" <---- This is the kind of detail that will get you to an answer very fast.

"},{"location":"build/community/#be-ok-with-links","title":"Be OK with Links","text":"

Often, the best answer to your question is sending a link to the answer in LoopDocs or LoopTips. This provides you a quick, accurate and complete answer. We understand that there is so much information in these sites that it can be hard to find answers. Mentors know the docs well, are experts at using the search tools and will send direct links to the sections that best answer your question.

If you've searched the docs and read relevant info already, please include that in your post or your reply. That way you don't get linked back to the part you are confused about. And if you have already read the specific section a mentor just linked, be specific about why your problem is not addressed by that link. Or just say \"I'm confused when the doc says this\". Letting us know when these docs can be improved is very useful.

"},{"location":"build/community/#next-step","title":"Next Step","text":"

Now you are ready to build or continue with setting up the Loop app.

"},{"location":"build/community/#return-to-set-up","title":"Return to Set Up","text":"

If you are a new looper who got to these pages from the Set Up app page - congratulations. Now that you've reviewed these introductory pages, please continue with the Brand New Loopers section of the Set Up Overview page.

"},{"location":"build/community/#build-with-browser","title":"Build with Browser","text":"

Click here if you want to Build with Browser.

"},{"location":"build/community/#build-with-mac","title":"Build with Mac:","text":"

Click here if you want to Build with Mac.

"},{"location":"build/computer/","title":"Compatible Computer","text":""},{"location":"build/computer/#compatible-computer","title":"Compatible Computer","text":"

Time Estimate

If you are building with a Mac and Xcode:

  • 5 minutes, if you have a Mac with Ventura (macOS 13.5) or higher (Sonoma)
  • 30-60 minutes, if you need to install macOS updates

Hint: OS stands for Operating System

Build with Browser

If you do not have a Mac, you can build\u00a0Loop 3\u00a0with any computer using a browser. If you want to use that method, review this list and head over to Build with Browser.

  • You need a paid ($99/year)\u00a0Apple Developer Account
  • You need an account (free) with\u00a0GitHub
  • You need a compatible phone to install the app from TestFlight
  • You need a compatible Pump and CGM if you want to actually use the app (and not just explore the app)

Summary

Your computer, iPhone and Xcode must have compatible versions to build the Loop app using a Mac.

  • A summary list of Compatible Versions is found on this page with more detail in a later page

If you are buying a Mac specifically to use the build with Mac method, chose one with capabably of being updated to the Sonoma (macOS 14) operating system and at least 256 GB (512 GB is better). The Build with Browser method works on any computer or tablet.

FAQs

  • \"Do I need a Mac or Virtual Machine?.\" Not any more! You can build Loop 3 with any browser on any computer.
  • \"I want to use the build with Mac method. Can I use a PC or Windows computer? I don't own an Apple computer.\" Yes, you can but only if your PC uses Intel chips. Please read this FAQ about using a Virtual Machine.
  • \"How often do I need to use the computer if I choose the build with Mac method?\" Computer access is required when
    • Initially installing the Loop app
    • Loop app expires (Annually for a paid account or weekly for a free account)
    • Updating to a newer Loop release
    • You do NOT need access to an Apple computer to update your phone iOS, troubleshoot or change Loop settings

If you have access to a computer with MacOS 13.5 or newer, you can skip ahead to Check Space Available.

"},{"location":"build/computer/#compatible-versions","title":"Compatible Versions","text":"

The current development version and the next release of\u00a0Loop\u00a0will require Xcode version 15 regardless of the iOS on the phone. This requires macOS 13.5 or higher. As an alternative, use Build with Browser, which supports iOS 15, 16, and 17.

When this page was last updated, macOS 14.0 and Xcode 15.0 were tested to successfully build the app for phones with iOS 15 through iOS 17.0.2.

The table below lists the minimum requirements to build the current release of\u00a0Loop 3.2.3. If your macOS or Xcode version is higher, you can build with Mac.

Find your phone iOS in the table below. If your iOS is not listed, e.g., 16.6, choose the first row that is less than your iOS.

iOS Version minimum Xcode minimum macOS 17.0 15.0 13.5 16.4 14.3 13.0 16.2 14.2 12.5 15.1 14.1 12.5

iOS Dictates Your Computer Needs

The more up-to-date you keep your phone iOS, the more up-to-date your computer and macOS needs to be to build the Loop app with the Mac build method. A new build is required at least once a year. More information on iOS is on the Xcode Version page.

There are important security updates that go along with iOS updates. Please install those iOS updates as soon as you can.

Do not use any of the beta macOS versions. (If you don't know what that means, you aren't using one.)

"},{"location":"build/computer/#check-your-macos-version","title":"Check Your macOS Version","text":"

To find your macOS version, click on the Apple icon in the computer's upper left corner and select About this Mac. The graphic below highlights the macOS version with a red rectangle. Your computer can be a MacBook, iMac, macMini, etc. It will work to build Loop if it has the minimum required macOS version and enough storage.

With the Ventura macOS version, the About this Mac display changed. For Ventura, when you tap on the More Info icon, it opens the General -> About screen from the System Settings menu. This is very similar to the phone Settings -> General -> About screen.

Sonoma, macOS 14.0, is expected to be released 26 September 2023.

If you do not have the required minimum macOS version

  • For macOS 12.6.1 or earlier, check the Software Update button on the screen shown above
  • For macOS 13.0 or later, click on the Apple and choose System Settings
    • Select General and Software Update, just like you would on the phone interface

Apple says upgrading to macOS Ventura requires 26 GB of available storage.

"},{"location":"build/computer/#check-the-space-available","title":"Check the Space Available","text":"

You need to have 50 GB free space in order to install Xcode as directed on the Xcode Version page. At the top of the menu on the graphic above, click on the Storage Tab highlighted with a red rectangle, or, if running Ventura, tap on More Info to open the About screen (under System Settings->General), which includes storage at the bottom of the display.

To free up space, move things like photos to an external drive. The Xcode application cannot be run from an external drive.

If you are evaluating a used computer, it's best to have at least 256 GB total disk space (more is better).

"},{"location":"build/computer/#which-macs-are-compatible-with-macos-ventura","title":"Which Macs Are Compatible with macOS Ventura?","text":"

Ventura is required for building the Loop app on a phone running iOS 16.4 or higher with the Mac method. You can install Ventura on the following:

  • MacBook Pro introduced in 2017 or later
  • MacBook Air introduced in 2018 or later
  • MacBook introduced in 2017 or later
  • Mac mini introduced in 2018 or later
  • iMac introduced in late 2017 or later
  • iMac Pro
  • Mac Studio
  • Mac Pro introduced in 2019 or later
  • get the full list from Apple for Ventura
"},{"location":"build/computer/#older-macs","title":"Older Macs","text":"

Look into building with GitHub Actions - no need to worry about versions for Mac OS or Xcode - all done for you on GitHub (some configuration required). Works with any computer (PC or Mac or Tablet).

"},{"location":"build/computer/#next-step","title":"Next Step:","text":"

If you already have an Apple Developer ID or you are using a free ID, next step is Xcode Version.

Free ID

The free ID method only works when using the build with Mac method. The Build with Browser method requires a paid developer ID ($99/year) but does not require a Mac computer.

"},{"location":"build/custom-mac/","title":"Customize using Mac","text":""},{"location":"build/custom-mac/#overview","title":"Overview","text":"

This page is only relevant when building with a Mac.

For Building with a Browser, please see: Customize using Browser

For new Loopers, please build the code before you make any changes. Start with Open Loop and familiarize yourself with the interface. Later, you can make the customization(s) you desire and build again. The second build will be much easier than your first build.

These customizations require you to modify the code used to build the Loop app and then build the app again with the modified code.

You take responsibility

You are responsible when you decide to use customizations.

Be sure to report what changes you made if you need to ask for assistance with your app.

"},{"location":"build/custom-mac/#customizations-prepared-for-you","title":"Customizations Prepared for You","text":"

Some customizations are the same for everyone and have been prepared for easy use.

The Loop and Learn team is committed to maintaining these prepared customizations and provides an easy method to add your selection from these customizations to your version of Loop.

Please read the documentation for these on the Loop and Learn: Customization Select Page:

  • List of Customizations Available
  • Customization Select Script
"},{"location":"build/custom-mac/#add-libre-support-to-323","title":"Add Libre Support to 3.2.3","text":"

If you are using main branch to build Loop 3.2.3 and rely on either xDrip4iOS or GlucoseDirect to read your CGM and transfer the readings to the Loop app, you need to review this section of the Loop and Learn customization page.

Alternatively, you can switch to the dev branch, which already supports Libre. Build Loop dev with Mac

"},{"location":"build/custom-mac/#personal-customizations","title":"Personal Customizations","text":"

Some customizations must be created for yourself. These are of two basic types: Custom Edits and Build-Time Flag.

The information needed to modify the code to make these customizations is found in the Versions tab because the information is independent of build method (think of these as your personal versions). The links are found below.

  • Version: Custom Edits
    • The page linked above indicates how you can modify behavior by editing the code
  • Version: Build-Time Flag
    • By enabling or disabling features controlled by a Build-Time Flag, you are turning on or off features included in the code by the developers that they configured to be off or on by default
    • Please read about these flags on the page linked above

When preparing these personal edits using a Mac, there is a page explaining how to open Xcode to the correct folder (where code is stored on your Mac) and incorporate those changes into your personal copy of LoopWorkspace on your Mac before building.

  • Custom Edits with Mac
"},{"location":"build/custom-mac/#details-at-links","title":"Details at Links","text":"

The code changes required for these customizations are the same regardless of the build method. The pages that provide the documentation on modifying and incorporating these changes are found at the links above.

"},{"location":"build/edit-mac/","title":"Custom Edits with Mac","text":""},{"location":"build/edit-mac/#overview","title":"Overview","text":"

When applying a customization using Mac, the downloaded code should be fairly recent. If you are not sure, get a fresh download. If you know your downloaded code is the Current Release, you can skip the download and use the same folder as last time.

"},{"location":"build/edit-mac/#find-my-downloaded-loop-code","title":"Find My Downloaded Loop Code","text":"

Refer to the graphic below. The Downloads folder in Finder is highlighted on the upper left. The full path to Loop.xcworkspace is highlighted along the bottom.

Loop to LoopWorkspace

Note that the directory Loop.xcworkspace has been renamed to LoopWorkspace.xcworkspace in the released code. For experienced builders - you realize this is good because the build process is easier.

The words were updated, but it will take time for the graphics to be updated.

  • Open Finder
  • Navigate to Downloads/BuildLoop and look for your download by name and date
  • Open that folder, for example, Downloads/BuildLoop/Loop-220803-1145, and inside that folder open the LoopWorkspace folder
  • Inside the Downloads/BuildLoop/Loop-220803-1145/LoopWorkspace folder, double-click on LoopWorkspace.xcworkspace (graphic not updated yet)
  • Xcode automatically opens to that particular download
  • You can then make the customizations and build to your phone

Experienced Builders

Experienced builders will often build a fresh download to a simulator for their phone iOS (not their phone) to ensure download is good and is compatible with macOS, Xcode and phone iOS. Once the build is successful, they apply their customizations and build again to the simulator. Last step is to build the customized version to their real phone.

"},{"location":"build/edit-mac/#instructions-for-finding-the-lines","title":"Instructions for Finding the Lines","text":"

For each customization, you are given landmarks to find the correct location in the code when you review Version: Custom Edits. You can choose to search using the Key_Phrase or navigate to the file in the folder structure and look for ( Cmd+L # ) the line number.

  • Either Key_Phrase or Module, Folder, File can be used to find the lines
  • Be sure to save the file when you make a change - otherwise the modification does not get built into your app
  • Some folder icons show different names in Xcode, see Folders and Icons
"},{"location":"build/edit-mac/#key_phrase","title":"Key_Phrase","text":"Example of a Key_Phrase
use the copy button at right, paste into search\nThe copy button for this exampe is just for practice\nDo not paste the result anywhere\n

To search using the Key_Phrase (see graphic below for clarification):

  • A copy button is available when you hover your mouse in the right-hand side of the block below the title Key_Phrase; click on it to copy the phrase
  • In Xcode, tap the Find menu item and select Find in Workspace
  • Paste the text into the Find search-box that opens on upper left of Xcode screen and hit enter
    • If you don't see the phrase in the box, hit backspace - your system copied an extra return
  • You should see a message 1 result in 1 file (for most cases)
    • Some customizations will show more than one result, but that will be explained in the directions for that customization
  • The file in which the line is located is reported showing the line in that file containing the Key_Phrase
  • Click on the one you think is correct and it will display in the main middle window of Xcode with the Keyword highlighted on the line you selected
    • The Key_Phrase was selected to limit the search to just the relevant line (if possible)
    • In some cases, the Key_Phrase gets you close but not exactly on the line where you need to make the modifications - please read carefully

"},{"location":"build/edit-mac/#module-folder-file","title":"Module, Folder, File","text":"

Each customization will also show Module, Folder and File bullet below the key phrase.

  • Module: Loop
  • Folder: Loop/subfolder1/subfolder2/etc.
  • File: filename.swift, line number(s)
"},{"location":"build/edit-mac/#open-a-terminal-in-loopworkspace-folder","title":"Open a Terminal in LoopWorkspace Folder","text":"

If you use the Loop and Learn: Customization Select Script, it automatically locates your most recent download, makes the customization you select in that download and then opens Xcode for you.

But sometimes, you need to find your downloaded code and make your own changes in Xcode. This section tells you how to do this.

Refer to the graphic below. The Downloads folder in Finder is highlighted on the upper left. The full path to Loop.xcworkspace is highlighted along the bottom. Double clicking on that file opens Xcode; but to apply customizations, you need to type commands in the terminal.

  • Open Finder
  • Navigate to Downloads/BuildLoop and look for your download by name and date
  • Open that folder, for example, Downloads/BuildLoop/Loop-220803-1145
  • Find the LoopWorkspace folder icon (dashed-blue rectangle)
  • Hold down the CTRL key and click (or right-click) LoopWorkspace
  • A menu appears - select New Terminal at Folder (near the bottom of the list)

This new terminal window is ready to accept commands as needed when the instructions say to start a terminal in the LoopWorkspace folder.

To confirm you are in the correct location, type pwd and return in the terminal. The response must end in LoopWorkspace. For example, using the graphic below, the response to pwd should be similar to:

/Users/marion/Downloads/BuildLoop/Loop-20220803-1145/LoopWorkspace

"},{"location":"build/edit-mac/#folders-and-icons","title":"Folders and Icons","text":"

The folders listed in the code customization steps are the actual directory names as stored on your computer. However, a shortened name is used for some folders when being displayed as icons in Xcode. Some people prefer to search through the folder icons to find a file instead of using the Find in Workspace feature.

In the graphic below, the user searched for an item found for both Eros and DASH pods (in two different files). The top part of the graphic shows the result of the search with user clicking on one instance. On the right side of the top graphic (highlighted by red rectangle) is the name of the selected file on the computer with the full directory name.

  • Inset 1: User clicked on the folder icon (highlighted by red square) to see the list of icons for folders included in the LoopWorkspace
  • Inset 2: User opens folders under RileyLink icon to open OmniKit, then OmnipodCommon to find the Pod.swift file (NOTE - the Eros information is in a different Module now, OmniKit, but the graphic has not been updated.)

These folder icon names are different from the directory names on the computer:

Folder Icon Name Directory Name ShareClient dexcom-share-client-swift RileyLink rileylink_ios Amplitude Amplitude-iOS

All other icons and directory names match.

"},{"location":"build/edit-mac/#modify-and-save","title":"Modify and Save","text":"
  • Either Key_Phrase or Module, Folder, File method described on Version: Custom Edits can be used to find the lines inside Xcode on your Mac
  • Be sure to save the file when you make a change - otherwise the modification does not get built into your app
  • Some folder icons show different names in Xcode, see Folders and Icons
  • When done with all the desired edits, plug in your phone and select it
    • Click on the \"Play\" button to build your customized code
"},{"location":"build/health/","title":"Loop 2 Health Permissions","text":""},{"location":"build/health/#health-data","title":"Health Data","text":"

The Loop app uses the Health app to record blood glucose, insulin, and carbohydrate data. The blood glucose, insulin, and carbohydrate data stored in the Health app can also be accessed and uploaded by the Tidepool Mobile app which enables the display of your data on the Tidepool web-based display tool. Please review the settings below to ensure you have the proper settings.

"},{"location":"build/health/#loop-permissions","title":"Loop Permissions","text":"

You need to set up Loop's permissions to read and write some data in the Health app. When you finish building your first Loop app, the Health app screen for Loop permissions automatically appears. (People who have been looping a while should be aware that the permissions are slightly different now.) Do not enable permission for Loop to read carbohydrates from the Apple Health app.

You can also get to this screen (for iOS 15) by iPhone -> Settings -> Health (heart icon) -> Data Access & Devices -> Loop.

New Instructions

Loop does not need to read carbohydrates from the Health app.

The old instructions suggested turning on all switches. This is NOT necessary for carbohydrates and can be dangerous if

  1. A different app writes carbohydrates to the Health app
  2. If two Loopers use the same Apple ID - PLEASE - do not do this; Loopers need their own Apple ID

Blood Glucose: Permission to Write and Read

  • Loop eavesdrops on the Bluetooth communication of the Dexcom G4/G5/G6 CGM and writes the values to the Health app for the first 3 hours
  • After 3 hours, the Dexcom CGM app allows other apps (including the Health app) access to its CGM data, so Loop needs to read the older Blood Glucose from the Health app
  • During times when there is no CGM data, the user can enter a finger stick value into the Health app Blood Glucose (BG) screen and Loop will read it, e.g., during sensor warmup

Carbohydrates: Permission to Write ONLY

  • Loop has its own carbohydrate data store and does not need to read carbs from the Health app
  • Once Loop records a carbohydrate entry, it will start to dose insulin to accommodate the expected rise in blood glucose from the carbohydrates consumed
  • If any other app writes carbohydrates to the Health app, you do not want Loop to add them to what you've already entered into the Loop app (resulting in duplicate entries)

Insulin Delivery: Permission to Write and Read

  • Loop writes basal and bolus doses to the Health app
  • Loop reads any manual insulin added to the Health app, e.g., insulin taken by injection

Sleep: Permission to Read

  • Loop uses Sleep information to decide which times of day to use the limited daily allocation from Apple for updates to the Loop watch complication.
"},{"location":"build/health/#dexcom-permissions","title":"Dexcom Permissions","text":"

You also need to enable your Dexcom Mobile app to write to the Health app. The steps shown in the figure below are valid for iOS 12.

For iOS 13/14, the menu items are: iPhone -> Settings -> Health (heart icon) -> Data Access & Devices -> Dexcom app. Make sure Dexcom has permission to write Blood Glucose (after the 3 hour delay). If you do not do this, you will have a maximum history of 3 hours displayed in the Loop Glucose screen.

"},{"location":"build/loop-data/","title":"Loop Data","text":""},{"location":"build/loop-data/#make-plans-for-your-loop-data","title":"Make Plans for your Loop Data","text":"

Time Estimate

  • Apple Health: 0 minutes, already a part of your system
  • Tidepool: 30 minutes to set up an account and then choose how to upload from the Loop app to Tidepool
    • option: add Tidepool Mobile to your phone and upload via Apple Health data
    • option: add upload to Tidepool as a Service in the Loop app
      • You can still use the Mobile app to take notes; but you must disable the Mobile app permission to read Health data - otherwise you get data uploaded twice
  • Nightscout:
    • 1-2 hours to build it yourself if you've never done it before
    • 1 hour to choose and sign up for a service if you want to pay someone

Summary

  • Review the three major systems that can store and show your Loop data.
  • Set up either Tidepool or Nightscout prior to your next endo appointment to provide Looping data to review.

FAQs

  • Do I have to set one of these up? Apple Health is already built into your iPhone and used by Loop, so there's no setup involved.
  • Do I need all three? No, you can choose what suits you best. You can add a data system later.
  • Why do I need any of these? With the Loop app, your PDM (Omnipod) is not used or your pump (Medtronic) does not have sufficient memory for all the commands. Your endo will have nothing to download at your next visit. You need to provide them with the information.
  • Is it worth the time to setup Nightscout? I feel like I'm already doing so much outside my comfort zone. Yes. Loopers find it is definitely worth the time investment. Nightscout provides essential data for evaluating settings and useful alarms and alerts. Some Facebook help sites require Nightscout data to diagnose and suggest steps to address problems. There are fee-based services that will set up Nightscout for you, if you don't want to build it yourself.
"},{"location":"build/loop-data/#data-options","title":"Data Options","text":"

Take some time to familiarize yourself with these data options and choose your preferred system(s). Many Loopers use all three for various aspects.

  • Apple Health app
    • Great resource to view on the Loop phone
    • Not so great for showing your endo
  • Tidepool
    • Some endo offices will use your Tidepool website when you provide them with an invitation
    • Many users of the mobile app like the note-taking ability
      • The mobile app also uploads Apple HealthKit data to Tidepool when the \"Read from Apple Health\" option is selected
      • If you are using the Loop app to upload to Tidepool, be sure to disable the \"Read from Apple Health\" option in the Mobile app
    • With Version 3.2 of the Loop app, you can upload directly as a Service within the Loop app
      • If you use the mobile Tidepool app on your phone for note-taking, be sure to disable the read from Apple Health option in the mobile Tidepool app settings to avoid duplicate uploads
      • If you use the mobile Tidepool app on your phone for uploading only, then it is no longer needed when you upload directly to Tidepool as a Service within the Loop app
  • Nightscout:
    • LoopDocs: Nightscout section of LoopDocs, has Loop-centric information about Nightscout
    • LoopTips: Nightscout link to LoopTips page on Nightscout
    • Nightscout: Documentation official Nightscout site with lots of information about building and using Nightscout
    • Nightscout has a lot of useful alarms and alerts, provides a care portal and detailed reports
    • For those who assist someone who is Looping, Nightscout enables the caregiver to provide remote commands to the Looper's phone
      • Loop 2 allows overrides to be enabled or disabled remotely
      • Loop 3 allows remote commands for carbs, bolus, or overrides
      • The Loop Caregiver app is under development but already has sufficient capabilities to be useful for caregivers to monitor and provide remote commands to their Looper's phone

Nightscout options include free or nominal cost sites you build yourself or there are several Nightscout as a Service vendors who provide turn-key sites for a monthly fee. Links to the options are found in the Nightscout: Documentation.

Nightscout provides a secure, real-time Dashboard with status of the Loop app visible to anyone with access codes and the internet. It is required for remote commanding.

If you plan to use remote commanding with Nightscout, please read these links with additional information:

  • Set Up Remote for Nightscout
    • Paid Providers and Remote Configuration
"},{"location":"build/loop-data/#next-step-meet-the-community","title":"Next Step: Meet the Community","text":"

Now you are ready to Meet the Community.

"},{"location":"build/overview/","title":"Mac Overview","text":""},{"location":"build/overview/#build-with-mac-requirements","title":"Build with Mac Requirements","text":"

The complete requirements for building Loop with a Mac and Xcode are summarized below. The first list contains the common requirements that are the same regardless of build method. The second list contains the additional requirements for building with a Mac and Xcode.

Each requirement in the list is linked to the LoopDocs pages with more information.

"},{"location":"build/overview/#common-requirements","title":"Common Requirements","text":"
  1. Compatible iPhone
  2. Compatible Pump
  3. Compatible CGM
  4. RileyLink Compatible Device (not needed for Omnipod DASH)
  5. Apple Developer Membership (not needed if you rebuild weekly using the Mac method)
"},{"location":"build/overview/#build-with-mac-additional-requirements","title":"Build with Mac Additional Requirements","text":"
  1. Compatible Computer
  2. Xcode (a free Apple application)

If using a Mac to build to a Simulator to try things out, the only requirements are a computer and Xcode.

"},{"location":"build/overview/#getting-ready-to-build","title":"Getting Ready to Build","text":"

Review the Common Requirements pages, listed above.

Then review the Build pages for the method you have chosen. Read the top three boxes on each page: icons for those boxes are displayed below for reference. On a desktop, you can use n for next and p for previous.

Time Estimate

Summary

FAQs

Next, read pages completely and skim Oh dear! Build errors?. Most of the mistakes you can make when building with Xcode and a Mac have already been made. The Build Errors page shows how to fix them.

When you are ready to proceed, complete the tasks on each page. You can do one a day, take a week per page or blaze through them quickly. Just be sure to read carefully and if you are confused - reach out for help: How to Find Help.

After you build Loop on your phone, keep following along in the docs as you Set up and Operate your Loop app.

"},{"location":"build/overview/#what-if-i-get-stuck","title":"What if I get stuck?","text":"

Try to:

  • Scroll back in the directions and see if you missed a paragraph or step.
  • Compare your screen's display with the graphics in the step. Is something different or does yours have an error message? If you have an error message, does it guide you to the problem and solution?
  • If you are still stumped - reach out for help: How to Find Help.
"},{"location":"build/phone/","title":"Compatible iPhone","text":""},{"location":"build/phone/#overview","title":"Overview","text":"

Time Estimate

  • 5 minutes, to check your device and iOS
  • 20 minutes, if need to update your compatible device to a new iOS
  • 10 minutes, if you need to order a Compatible Device
  • 0 minutes, if you own an Android and will not use Apple products; check out AndroidAPS Documention

Summary

  • Check your iPhone against the Compatible Device list
    • For all devices, the newest iOS is strongly recommended
  • Make sure the phone has good battery life
  • Turn off automatic updates

FAQs

  • \"Can I use an android?\" No. Check out AndroidAPS Documention.
  • \"Can I use an iPad?\" No. Older iPads do not support Apple Health which is required for the Loop app. It may be possible with newer iPads and newer iOS, but this has not been tested.
  • \"Does my iPhone need a cell plan?\" No. The Loop app works using communication on your phone with your CGM and your pump; no internet connection required. However, if access to Dexcom Follow or Nightscout monitoring of the Loop app is a priority, then a cell plan may be desired.
  • What watches work with the Loop app? Only Apple watches work with the Loop app. With iOS 17, some of the older Apple watch series are no longer compatible. See: Watch Hardware and OS Requirements
"},{"location":"build/phone/#which-devices-are-compatible","title":"Which Devices Are Compatible?","text":"

The Loop app requires an Apple device and uses the Apple Health app to store and retrieve your blood glucose and insulin data and to store your carbohydrate records. Older iPads do not support Apple Health which is required for the Loop app. It may be possible with newer iPads and newer iOS, but this has not been tested.

You need a minimum version of the mobile operating software, called the iOS, to be installed on your iPhone. The Loop app is compatible with iPhone devices with iOS 15.1 or newer.

  • It is unusual for three different iOS to be supported
  • The developers try to maintain support for the current and one-level earlier iOS
    • Be prepared for your iOS 15 device to no longer be supported in future releases
"},{"location":"build/phone/#compatible-device","title":"Compatible Device","text":"

These devices are compatible.

  • iPhone 15, all variants
  • iPhone 14, all variants
  • iPhone 13, all variants
  • iPhone 12, all variants
  • iPhone 11, all variants
  • iPhone XR, XS, XS max
  • iPhone SE (3rd generation or later model; 2022 first release)
  • iPhone SE (2nd generation; 2020 first release)

These devices are compatible (now), but are limited to iOS 16.

  • iPhone X, without an extra letter
  • iPhone 8, all variants

These devices are compatible (now), but are limited to iOS 15.

  • iPhone 7, all variants
  • iPhone 6s or 6s Plus, note the s
  • iPhone SE (1st generation; 2016 first release)
  • iPod Touch, 7th generation
"},{"location":"build/phone/#find-your-ios","title":"Find Your iOS","text":"

Your iOS version can be found under the phone Settings -> General -> About display as shown below. The iOS number is found on the Software Version line.

Do not use any of the beta iOS versions. (If you are uncertain what that means, then you are not using one.)

"},{"location":"build/phone/#developer-mode-mac-build-only","title":"Developer Mode - Mac Build Only","text":"

When you build the Loop app using Build with Browser, you are not required to enable Developer Mode on the phone or watch.

With iOS 16 or newer and watchOS 9 or newer, Apple added a feature. If you want to know more, click on this Apple Link about Developer Mode.

When you build the Loop app on your phone from Xcode directly and then transition to or start with iOS 16 or newer, you need to have Developer Mode enabled. This is also a requirement to use the Loop app on a watch paired to your phone running watchOS 9 or newer. You will be told to enable it in the Build the Loop App: Prepare your Phone and Watch instructions.

Developer Mode with iOS 16 or newer, watchOS 9 or newer

If you already have the Loop app built with Xcode on your phone/watch when you update to iOS 16 or newer/watchOS 9 or newer or newer, you will be told that the Loop app requires Developer Mode to run.

You will not be able to run the Loop app on your phone (or watch) until you have enabled Developer Mode on the device(s).

"},{"location":"build/phone/#battery-health","title":"Battery Health","text":"

Make sure the battery on your phone is solid. Your phone will become a critical health device - you want it to keep working.

  • Make sure a charger and cord are in your diabetes supplies
  • Consider buying a battery pack, keep it charged, and add it to your travel bag

Low Power Mode

With newer iOS, some people have reported the Loop app continues working in the background (phone locked) even in Low Power Mode. Others have reported they still get red loops. You can experiment to determine if your phone/iOS/app is able to maintain green loops in low-power mode. Otherwise, the best practice is to avoid Low Power Mode.

"},{"location":"build/phone/#use-automatic-time","title":"Use Automatic Time","text":"

Be sure to set the phone to automatic time. Do not try to defeat a game by modifying time on the same phone used to control your insulin.

Please read: The Loop Phone Must be on Automatic Time.

"},{"location":"build/phone/#turn-off-automatic-updates","title":"Turn Off Automatic Updates","text":"

Apple provides updates regularly to the iOS. Often, these updates include critical security patches in addition to improved new features.

Please be proactive - install updates as soon as the all-clear is given for using the Loop app with that iOS update.

If a limitation on your Mac prevents you from updating your phone to the latest iOS, consider using Build with Browser.

"},{"location":"build/phone/#why-turn-off-automatic-updates","title":"Why Turn off Automatic Updates?","text":"
  • Once you accept an iOS phone update, you cannot go backwards
    • Some iOS updates require updates to Xcode and macOS before people can build the Loop app on that device again
    • It is rare, but iOS updates have caused the Loop app to stop working until other updates were made and the Loop app was rebuilt on that phone
  • Turn off automatic updates so you can choose when to update your phone and avoid being caught without your Loop app
  • Google the instructions for your device:
    1. Configure your phone to automatically download the updates
    2. Choose to install the updates manually

When iOS updates are released, the Loop and Learn Version Updates page is typically updated faster than LoopDocs. Check to see if a new update is causing an issue with the Loop app or your CGM before accepting the update from Apple.

Within a few days, the \"All-Clear\" or (very rare) the \"WAIT there is a problem\" message will be posted.

"},{"location":"build/phone/#next-step-compatible-pump","title":"Next Step: Compatible Pump","text":"

Now you are ready to check if you have a Compatible Insulin Pump.

"},{"location":"build/pump/","title":"Compatible Pump","text":""},{"location":"build/pump/#compatible-pump","title":"Compatible Pump","text":"

Time Estimate

  • Omnipod users: 3 seconds to remember which Personal Diabetes Manager (PDM) you've been using.
  • Medtronic users: 10 minutes to put a battery in and look at model and firmware
  • Other pump users: 5 days to email friends asking them to check closets for their old Medtronic pump or call your insurance to start prior authorization for Omnipod

Summary

  • If you have a Medtronic pump, check the Medtronic Pump Version list to ensure compatible model/firmware
  • If you use Omnipod - check which kind

FAQs

  • \"How can I find a compatible Medtronic pump?\" Refer to Finding a Medtronic Pump.
  • \"What are the differences between Medtronic pump models?\" This question is answered in the Extra Details section.
  • \"But what about the other types of pumps?\" No other pumps work with the Loop app at this time.
    • There are other open-source closed loop options such as AAPS: Android Artificial Pancreas System and OpenAPS that support other pumps
  • \"Can I change the firmware of my Medtronic pump?\" No.
"},{"location":"build/pump/#pumps-compatible-with-loop","title":"Pumps Compatible with Loop","text":"

There are three types of pumps compatible with Loop.

  • Older Medtronic pumps
  • Omnipod Eros pumps
  • Omnipod DASH pumps
"},{"location":"build/pump/#check-medtronic-pump-version","title":"Check Medtronic Pump Version","text":"
  • Medtronic 515 or 715 (any firmware)
  • Medtronic 522 or 722 (any firmware)
  • Medtronic 523 or 723 (firmware 2.4 or lower)
  • Medtronic Worldwide Veo 554 or 754 (firmware 2.6A or lower)
  • Medtronic Canadian/Australian Veo 554 or 754 (firmware 2.7A or lower)

If you have one of the pumps listed above, you are good to go on Loop! Congrats!

"},{"location":"build/pump/#extra-details-on-medtronic","title":"Extra Details on Medtronic","text":"

There are a number of Medtronic insulin pumps manufactured between 2006 \u2013 2012 which are compatible with the Loop app. Compatibility has two requirements: (1) pump model and (2) firmware.

"},{"location":"build/pump/#medtronic-pump-model","title":"Medtronic Pump Model","text":"

To determine your pump model, look at the backside of your pump. There should be a sticker on the underside of the pump. On the right-hand side of the sticker, it says REF MMT-XXXXXX

  • MMT ---> Pump Manufacturer Model (MiniMed Medtronic)
  • 722 ---> Pump Model Number
  • NA ---> Pump Region (NA=North America, CA=Canada/Australia, WW=Worldwide)
  • S ---> Pump Color (S=Smoke, L=Clear/Lucite, B=Blue, P=Pink/Purple)

Some pumps may have an \u201cL\u201d or \u201cS\u201d or \"R\" before the pump region, e.g. a model number like MMT-722LNAS. This does not affect compatibility with the Loop app.

"},{"location":"build/pump/#medtronic-pump-firmware","title":"Medtronic Pump Firmware","text":"

A pump\u2019s firmware is the internal software that runs your pump. Older Medtronic firmware allows the Loop app to act as a \u201cremote control\u201d to set temp basals and report back pump data. Newer firmware disabled that \u201cremote control\u201d access and therefore cannot be used with these DIY closed-loop systems. There is currently no ability to downgrade a pump\u2019s firmware or replace it with older firmware. Before you buy a used pump, make sure you are getting one with compatible firmware.

The firmware on all 515/715 and 522/722 model Medtronic pumps is compatible with Loop. You will only need to check the firmware version for 523/723 and 554/754 model Medtronic pumps.

  • Medtronic 515 or 715 --> any firmware
  • Medtronic 522 or 722 --> any firmware
  • Medtronic 523 or 723 --> firmware 2.4 or lower
  • Medtronic Worldwide Veo 554 or 754 --> firmware 2.6A or lower
  • Medtronic Canadian/Australian Veo 554 or 754 --> firmware 2.7A or lower

To find your pump\u2019s firmware you will need to power it on. If the pump has not been powered on for some time (i.e., has been in storage without a battery for a while), it will run through a start-up count and the firmware version will appear on the bottom right of the pump\u2019s screen. Don\u2019t turn away, as the version number will only be displayed for a little while before the screen moves onto other information displays.

If the pump has been active recently or has a reservoir installed, follow these steps:

  1. Press the button on your pump.

  2. Scroll down with the button to the bottom of the status display.

  3. Read the bottom line of the display.

"},{"location":"build/pump/#medtronic-pump-differences","title":"Medtronic Pump Differences","text":"

If you are in the position of being able to shop around for different pump models, there are some slight differences between the Loop-compatible Medtronic pumps.

500 vs 700: The difference between the Medtronic 500 series and the 700 series pumps is the size of the insulin reservoirs. The 500 series pumps use a 180 unit reservoir, and the 700 series pumps use a 300 unit reservoir (or smaller 180 unit reservoir, if you want).

x15/x22 vs x23/x54: The differences noteworthy between the x15 and x22 pumps versus the x23 and x54 series pumps are:

  • The x23/x54 pumps will allow for smaller insulin deliveries in certain situations, if the smaller scroll rate is selected in the Bolus>Setup>Scroll Rate menu.
Pump Model Basal increments Bolus increments Range 515/715and522/722 0.050.1 0.10.1 deliveries of less than 10 unitsgreater than 10 units 523/723and554/754 0.0250.050.1 0.025 0.05 0.1 between 0.025 to 0.975 unitsbetween 1 to 9.95 unitsgreater than 10 units

  • Additionally, because of the way the Loop app fetches information from the pump, the x23/x54 series of pumps are slightly better at conserving battery life through the use of the MySentry packets to collect information from the pump. x22 pumps do not use MySentry.

  • The x23/x54 series pumps are also faster at delivering boluses greater than 10 units. On an x23 pump, a 13-unit bolus takes 5:00 minutes to complete. On an x22 pump, a 13-unit bolus takes 8:40 minutes to complete.

"},{"location":"build/pump/#finding-a-medtronic-pump","title":"Finding a Medtronic Pump","text":"

Finding a compatible Medtronic pump is probably the most difficult part for most new Loopers. Our suggestions:

  • Talk to friends in the diabetic community.

  • Ask your endocrinologist.

  • Ask at a local JDRF chapter meeting if someone has an old backup pump they'd be willing to donate to you.

  • Join diabetic supply groups on Facebook; both for-trade and for-sale groups.

  • Check Craigslist often and be willing to expand your search area to include larger cities.

  • Check out the HelpAround, NextDoor, OfferUp, and/or LetGo apps for pumps.

  • Looping in a time of covid

The most success appears to come from either one-on-one discussions with fellow diabetics/doctors or using apps (Craigslist, NextDoor, LetGo, HelpAround). If you are using Craigslist, you may wish to use an app on your iPhone to make the searching easier. There are apps to search multiple cities at once for your keywords and set up alerts.

"},{"location":"build/pump/#safe-purchasing","title":"Safe Purchasing","text":"

If you choose to purchase from a remote or unknown seller, here are some tips for safe purchasing:

  • Use PayPal and purchase using the \"Goods and Services\" payment option. This costs nothing for the buyer, but the seller will lose 2.95% of the sale to PayPal fees. PayPal offers some protection for both buyer and seller in the event of fraud.

  • Ask for photos of the pump. Check to make sure the serial number of the pump on the backside matches the serial number of the pump showing in the display menu. Ask for a short video of the pump, or at least a photo of the pump turned on, so that you can see the pump's firmware and model number. Cracks and some wear on these pumps are expected. These pumps are not usually free of marks. Many people are successfully looping on pumps that have cracks and rub marks, but you may want to ask if you are concerned about any you see in photos.

  • Beware if the bottom of the reservoir/motor sleeve has the drive support cap pushed out, as shown here. Those pumps will generally not work (or only work intermittently), however some people have successfully repaired those pumps as shown in that link. Just be aware that it should be checked in advance.

  • Repairs to cracks or missing bits of plastic on battery cap area and reservoir caps are possible and not very difficult in most situations. You can read more about how to repair those here.

  • Ask for shipping that includes a tracking number. USPS Priority Mail's smallest box is a great option. It's only $7.20 domestically in the US and includes tracking. Ask the seller to add a small bit of packing protection such as bubble wrap around the pump to keep it safe during shipping. Make sure you get a tracking number within a reasonable period of time after you have paid.

Red flags that may indicate a scam:

  • Asking for payment through \"friends and family\" on PayPal, especially if you don't know the person or have any solid references for them. Paying in that way offers you no buyer protection. It's just like giving the seller cash, so you had better trust the seller.

  • Offering an \"almost new\" pump is a big red flag. These pumps should be at least 5-years-old by now. Do you really think a 5 year old pump should be unused and sitting in shrink wrap at this point? This seems highly suspicious. There are some out there, but they are very infrequent.

  • Not able to provide new pictures of the pump when requested. Sure they posted some pictures with the ad, but what if they just downloaded them from other people's ads? The seller should be able to furnish a couple of \"new\" photos at your request. A good one to ask for is the battery and reservoir tops so you can see the condition of those.

"},{"location":"build/pump/#pump-supplies","title":"Pump Supplies","text":"

Medtronic will not typically sell pump supplies directly to customers who have not previously purchased a registered Medtronic pump. Ask your insurance about purchasing pump supplies through a durable medical equipment (DME) provider. Typically, the DME provider will coordinate with your insurance and doctor's office to get the necessary insurance approval and prescriptions for the supplies. If you are brand new to Medtronic infusion sites, you may want to ask for help from friends to try a variety of infusion sets before purchasing a full 90-day supply of any type in particular.

"},{"location":"build/pump/#omnipod-pumps","title":"Omnipod Pumps","text":"

Reminder and Disclaimer

The use of Omnipod pumps with the Loop app is not supported by Insulet, although they are aware it is happening. Do not call Insulet asking for help with your Loop app build, setup, or operation. You are fully responsible for your use of the Loop app and do so at your own risk. Please read these documents and familiarize yourself with the Loop app before using it.

"},{"location":"build/pump/#omnipod-eros","title":"Omnipod Eros","text":"

Eros pods (also known as Gen 3) were launched in 2013 and continue to be sold by Insulet. Insulet has announced they will stop providing Eros pods in the US in December 2023. As far as we know, there are no timelines announced for the discontinuation of Eros pods for other countries. Insulet doesn't specifically call these \"Eros\" anymore, they just use the term \"omnipod system\". For clarity, from Insulet's webpage:

Alternative Names for Omnipod Eros Pump and Pods

Eros pump is also known as Classic, or UST400, or Omnipod Insulin Management System.

Pharmacy sites sometimes may refer to the Eros pods as Gen 3 but they are the same exact pods.

Eros system has a big Personal Diabetes Manager (PDM) that does not look like a phone.

"},{"location":"build/pump/#omnipod-dash","title":"Omnipod DASH","text":"

The DASH system has the newer, slimmer locked-android Personal Diabetes Manager (PDM) and built-in BLE communications in the pod, so there is no requirement for a RileyLink compatible device.

A RileyLink-compatible device is not required to use DASH with the Loop app. The communication with your iPhone uses Bluetooth.

Loop 3.0 and later works with DASH pods. If your version of the Loop app is 2.2.9 or earlier, you cannot use DASH pods.

"},{"location":"build/pump/#omnipod-5","title":"Omnipod 5","text":"

Loop does not support Omnipod 5 pods.

"},{"location":"build/pump/#next-step-compatible-cgm","title":"Next Step: Compatible CGM","text":"

Now you are ready to check if you have a Compatible CGM.

"},{"location":"build/rileylink/","title":"RileyLink","text":""},{"location":"build/rileylink/#order-a-rileylink-compatible-device","title":"Order a RileyLink Compatible Device","text":"

Not needed for DASH

Time Estimate

  • 15-20 minutes to read about RileyLink compatible devices
  • 15 minutes to order a device

Summary

  • Decide what kind of RileyLink compatible device to buy
  • Order your compatible device

FAQs

  • What is a RileyLink Compatible Device? RileyLink refers to both the communication protocol and the name of the original device. Other DIY Loopers have created RileyLink Compatible Devices that use the RileyLink protocol. All these devices can be used interchangeably with the Loop app to support Eros and Medtronic use.
  • Do I have to buy one? These are open-source hardware devices, but it takes special skills to build them yourself. It is recommended you buy one (or two) if you require it. At the current time, new OrangeLink and EmaLink devices are available for purchase. There are many used devices available in the community now that many users have switched to DASH. Not needed for DASH
    • Facebook Group where you may find used items: Looping in a time of covid
  • \"What happens if I lose my RileyLink compatible device or walk away from it?\" Within a half hour, your pump returns to the normal scheduled basal rate
  • \"Can I swap out RileyLink compatible devices at any time?\" Yes, you can. You do not need to start a new pod or rebuild the Loop app. Tap on the pump menu in settings to search for new devices. You can swap between compatible devices.
  • \"How close does the RileyLink compatible device need to be to me? Do I have to carry it with me?\" See RileyLink Compatible Device Range.
"},{"location":"build/rileylink/#what-is-a-rileylink-compatible-device","title":"What is a RileyLink Compatible Device","text":"

The RileyLink compatible device is required to allow your phone to talk to compatible Medtronic and Omnipod Eros pumps. It is not needed for Omnipod DASH pumps.

Details for RileyLink

The RileyLink compatible device is an open-source hardware device that can bridge Bluetooth Low Energy (BLE) to the radio-frequency wireless communication used by compatible Medtronic and Omnipod Eros pumps.

Loop 3 has Omnipod DASH support, among other new features. When using Omnipod DASH, the RileyLink compatible device is not necessary. If you are using Medtronic or Omnipod Eros (not DASH), you still need the device regardless of which version of Loop you are running.

Medtronic and Omnipod Eros pumps require a RileyLink compatible device.

"},{"location":"build/rileylink/#rileylink-compatible-devices","title":"RileyLink Compatible Devices","text":"

The RileyLink protocol defines a specific Bluetooth interface and way of opening a Sub-GHz radio channel to pumps. All RileyLink compatible devices follow the RileyLink protocol.

There used to be just one option, the original RileyLink. Now there are more options, so you have to make a decision. Depending on your choice, be sure to have the correct charger and cables or batteries handy and add spare compatible supplies to your diabetes go-bag.

  • A Comparison Chart is provided by the GetRileyLink organization for all the RileyLink compatible devices listed below
  • RileyLink
    • Designed by Pete Schwamb
    • Rechargeable battery (max 36 hours per charge)
    • No longer available new, check this Facebook Group for used ones:
      • Looping in a time of covid
  • OrangeLink
    • Designed by Vic Wu, available from GetRileyLink
    • Uses 2 AAA batteries, batteries typically last weeks or more, depending on the batteries/pump type
    • Works with either Omnipod or Medtronic
    • Uses new chipsets, reported to have a longer range
    • Matches Apple AirPod form factor, so you can use AirPod cases
  • EmaLink
    • Designed by Sorin Kupas-Spunei to increase range, offer smaller sizes
    • Rechargeable battery (various case/battery sizes available)
      • Micro/Nano: 2 to 3 days
      • Standard: 6 to 7 days
      • Maxx: 12 to 14 days
    • Must order either Omnipod or Medtronic version
    • This EmaLink Information includes photos of various EmaLink configurations as well as photos showing relative sizes of EmaLink, OrangeLink and RileyLink
    • In North America, available from EmaLink.us
"},{"location":"build/rileylink/#more-information","title":"More information","text":"

There is an entire FAQs page on RileyLink Compatible Devices.

Sections of interest include:

  • Firmware Update information on the OrangeLink
  • Ema and Orange Patch to see extra features on the Loop app screens
"},{"location":"build/rileylink/#waiting-for-your-rileylink-compatible-device","title":"Waiting for your RileyLink Compatible Device","text":"

While you are waiting for the RileyLink compatible device to arrive, you can proceed with these build directions and can try one of the Simulated Loop options. After that, unless you are using Omnipod DASH, you'll have to wait for your device.

The population of DIY loopers (Loop and Android APS) has grown enough that you might be able to find someone local to loan you their spare.

"},{"location":"build/rileylink/#next-step-enroll-in-apple-developer-program","title":"Next Step: Enroll in Apple Developer Program","text":"

Now you are ready to enroll in the Apple Developer Program.

"},{"location":"build/test-settings/","title":"Test Settings","text":""},{"location":"build/test-settings/#test-settings","title":"Test Settings","text":"

Time Estimate

  • 2 hours to review the rest of LoopDocs (particularly the Set Up, Operate, and FAQs sections) and LoopTips
  • If you like quizzes, this older quiz has not been updated for version 3 of the Loop app and not all the links work (when your answers are scored), but the questions are still really good and the scoring report provides extra insight into why your answer was right or wrong
    • 15 minutes to take this quiz to confirm you understand the Loop app expected behavior
    • New with version 3 of the Loop app:
      • you can remote bolus
      • you can set a manual temp basal rate
      • DASH pods can be used without a RileyLink
        • restarting your app or turning Bluetooth on and off replaces the Rileylink power cycle trouble-shooting tip
      • Nightscout with Heroku is no longer free, but there are other options
      • you do NOT need a Mac computer if you use Build with Browser
  • 1-3 days to test settings for safety and to get the most out of the Loop app
    • This step can be done after you build the Loop app, just stay in Open Loop while you test

Summary

  • Before you use Closed Loop mode, test and validate your basal rates, ISF (correction factor), and CR (carb ratios)
  • You may need to adjust your settings for the Loop app
  • Accurate settings are vital for success

FAQs

  • \"My endo chose my pump settings, so do I need to test them?\" Yes. Your endo chose your settings in a different context, with different constraints. What is safe and ideal in traditional pump therapy, may not be the best selection for the Loop app. Testing your settings, even for just a couple days, makes a big difference.
  • \"I have great control, why would I need to test my settings?\" \"Great control\" may be due to lots of adjustments - bumps and nudges of insulin or carbs. Those bumps and nudges may be covering for underlying settings that need adjustment. If you are coming from a treatment style that involves memorizing your insulin doses for meals, you may not know your actual CR or ISF. Testing is key to success with the Loop app.
  • \"I can't basal test with my 2-year-old. What can I do?\" That is pretty tough. Consult your endo, watch your patterns, and do the best you can...little kiddos are a difficult group to test settings. Once you become comfortable with the Loop app, there are tricks to adjust settings while staying in closed loop as long as settings are fairly close.

Loop is just a fancy calculator underneath the hood. The math problems it solves depend on the settings you provide. So test settings before using the Loop app.

"},{"location":"build/test-settings/#basal-rates","title":"Basal Rates","text":"

Correct basal rates keep your blood glucose steady without food present. The standard method is to test your basal by having a relaxing 4-6 hours without eating at least two hours before you begin the test. Does your blood sugar stay steady? Or do you climb and need a correction? Or do you go low and need to eat? Setting basal is a crucial step to setting yourself up for success with the Loop app. It determines how much of the insulin delivered (from basal and bolus) is counted as insulin on board (IOB).

Basal Tricks

The Loop app keeps track of how much more or less insulin than your scheduled basal rates are required to keep glucose in target. Once you become a proficient looper, you can tune your basal by looking at IOB overnight or when food and exercise are not involved.

"},{"location":"build/test-settings/#insulin-sensitivity-factor","title":"Insulin Sensitivity Factor","text":"

The Insulin Sensitivity Factor (ISF), sometimes called Correction Factor, is how much one unit of insulin will bring down your glucose. The higher the value of this setting, the more sensitive to insulin you are. An ISF of 50 or 100 (2.8 or 5.5) means one unit of insulin lowers your glucose 50 or 100 mg/dL (2.8 or 5.5 mmol/L) in the absence of food or activity, when basal rates are correct.

Test ISF after you test and determine your basal rates. Simply bring yourself to a higher glucose with a glucose tab or choose a time when you are \"stuck\" higher than your target.

  • Calculate how much insulin is required to lower your glucose to target, take it and observe if your glucose flattens out at your target within 3 hours
    • Do not do this test if you have recently eaten, recovered from a low glucose, engaged in physical activity, are sick or under stress
  • A starting point for ISF is to take total daily dose and divide that into 1800
    • This is just a starting point, many people have higher or lower ISF than this formula suggests
    • Example, you take 30 U a day and have no idea what your ISF should be
      • Start with 60 mg/dL (3.2 mmol/L) and test it
"},{"location":"build/test-settings/#carb-ratio","title":"Carb Ratio","text":"

The Carb Ratio (CR) is the amount of carbs covered by one unit of insulin. Ideally, a good carb ratio will restore your glucose close to its starting point within 3 hours of the meal. (High fat/protein meals may cause glucose to be impacted longer.)

If you are spiking higher than you\u2019d like after a meal, but still coming back to the starting glucose, consider pre-bolusing your meal earlier (maybe by 15-20 minutes) rather than changing the carb ratio.

"},{"location":"build/test-settings/#other-resources","title":"Other Resources","text":"

Check the companion site LoopTips. Several direct links to discussions are provided below:

  • How to check settings
  • Why settings are important
  • What to do when you need to change settings which covers short term and long term reasons

If you\u2019re fascinated by this topic, read the book 'Think Like A Pancreas' by Gary Scheiner for a really great discussion.

"},{"location":"build/test-settings/#next-step-make-plans-for-loop-data","title":"Next Step: Make Plans for Loop Data","text":"

Now you are ready to make plans for Loop Data.

"},{"location":"build/testflight-xcode/","title":"TestFlight from Xcode","text":""},{"location":"build/testflight-xcode/#introduction","title":"Introduction","text":"

There are several different methods for making use of TestFlight:

  • Test an app someone else is developing
  • Use the Build with Browser method to build and distribute your Loop app to your iPhone or that of a family member
  • Use TestFlight as a remote distribution (and backup) for an app you build using Xcode

This guide can also be followed to install other apps you build with Xcode via TestFlight. Examples include Loop Follow, Loop Caregiver, xDrip4iOS and GlucoseDirect.

Some useful features of using TestFlight to install Loop:

  • You don't need to plug your phone into your computer
  • You can update Loop on your kid's phone while they're away at college
  • Reinstalling Loop on the fly is quick and easy from your phone, even if you accidentally delete the app, see Protect that App, or need to install Loop on a brand new phone

Since apps built with TestFlight expire after 90 days, it is suggested you also setup a build using the Build with Browser method even if you don't plan on using it. The GitHub build can be updated in a few minutes from any browser and is an extra layer of protection in these scenarios if you do not have access to your Mac for a rebuild:

  • Your Xcode built Loop in TestFlight expires
  • An urgent update to Loop is released

In all cases, except accidental deletion of Loop or loss of phone, the Loop you install from TestFlight builds over your existing app and you keep all your settings including your pump.

"},{"location":"build/testflight-xcode/#build-to-testflight-via-xcode","title":"Build to TestFlight via Xcode","text":""},{"location":"build/testflight-xcode/#initial-steps","title":"Initial Steps","text":"

Before creating the app or uploading it to TestFlight, use the Build with Mac guide to sign your targets and build Loop to a simulator phone in Xcode. This checks to ensure the app you upload to your TestFlight will work as expected.

"},{"location":"build/testflight-xcode/#archive-the-project","title":"Archive the Project","text":"

Change the build target to from building to a simulated phone to LoopWorkspace > Any iOS Device (arm64) like the image below.

Now go to the top menu and choose Product > Clean Build Folder. Once it's done, it should say \"Clean Finished\".

Go back to the top menu and choose Product > Archive. This will build Loop into a file rather than a phone or simulator. It should take about the same amount of time as building to a phone or simulator does.

"},{"location":"build/testflight-xcode/#upload-the-archive","title":"Upload the Archive","text":"

Once the archive finishes building, it should automatically open the Archives window. If you want to open this window without re-archiving, click the following in the top menu: Xcode > Window > Organizer.

Select the archive and click Distribute App. If you've archived the project before, be sure to select the archive you intend to upload - most likely the one with the most recent Creation Date.

On the next screen, App Store Connect is selected by default. Click Next.

On the next screen, Upload is selected by default. Click Next.

"},{"location":"build/testflight-xcode/#first-time-archive-upload","title":"First-Time Archive Upload","text":"

If you have already created a TestFlight for Loop via Xcode or the GitHub Build method, the next screen will not be shown, so skip ahead to Subsequent Archive Upload.

If this is the first time you're creating a TestFlight for Loop, enter the following on the next screen and click Next:

  • Name: Enter a name that is unique. Most people just use \"Loop\" followed by their initials, so James Kirk would use \"LoopJK\". If he gets an error that the name is already taken, he might try something like \"LoopJTK\" or \"Loop_JTK_1701\".
  • SKU: This can be anything, but it can't be the same SKU that you've used for a different app that you've created a TestFlight for. Ideally, just leave it as the autofilled bundle id.
  • Primary Language: Set this to your primary language.
  • Bundle Identifier: This should already be autofilled. If it's not, it should be \"com.YOUR_TEAM_ID.loopkit.Loop\". Make sure you replace YOUR_TEAM_ID with your actual TEAM ID, which you can find at developer.apple.com/account.

"},{"location":"build/testflight-xcode/#subsequent-archive-upload","title":"Subsequent Archive Upload","text":"

On the next screen, leave everything checked and click Next.

On the next screen, leave it set to Automatically manage signing and click Next. You will see a few messages as it performs some tasks. Be patient.

When you see the next screen, click Upload.

Wait until uploading is finished. Don't be alarmed if you see the following screen, just click Done.

"},{"location":"build/testflight-xcode/#deploy-app","title":"Deploy App","text":"

Now that it's uploaded to TestFlight, it will take a little bit before it finishes processing and becomes available for installation on your iPhone. You can check appstoreconnect.apple.com/apps to find it's progress by clicking Test Flight and then iOS under Builds in the upper left. Once it no longer says \"Processing\" and instead says \"Ready to Submit\" next to the build's number, it should be available and ready to install on your iPhone.

To install Loop from TestFlight onto your iPhone, follow the instructions on the GitHub Deploy page.

"},{"location":"build/testflight-xcode/#update-app","title":"Update App","text":"

Apps installed via TestFlight are only valid for a maximum of 90 days, so you must upload a new build to TestFlight at least every 90 days.

To update, simply repeat all the steps on this page.

Add a Calendar Reminder

Note that the built-in Loop Notification for expiration has not been modified to read TestFlight expiration, yet.

So, please add a calendar reminder.

"},{"location":"build/updating/","title":"Update/Rebuild with Mac","text":""},{"location":"build/updating/#overview","title":"Overview","text":"

This page is only relevant when building with a Mac and Xcode.

For Browser Build, please see: Update/Rebuild with Browser

Time Estimate

  • 25 minutes, if Xcode and macOS are already updated to support the current or desired iOS
  • up to 2 days, if need to install macOS and / or Xcode update(s)

Summary

Summary of tasks to prepare for and update your app:

  • Determine required macOS and Xcode version based on your phone iOS
    • If necessary, update first macOS and then Xcode
  • Check your Developer Account
  • Download Updated Loop code and Build Loop

In each of the sections below, follow links to sections of other build pages then hit the back button on your browser to return to this page.

FAQs

  • \"What is an update?\" Anytime you want to change versions or if the app is about to expire, follow the instructions on this page.
  • \"Do I delete my old Loop app first?\" Definitely not! If you keep your Loop app on your phone, your Loop settings (and existing pod) will continue to work the same after the update. Seamless.
  • \"Do I need to start a new pod when I update?\" No. Your existing pod session will continue seamlessly if you are using the same Developer Account to sign the Loop app targets as you did the last time you built.
  • \"What if I'm using a new/different developer account?\" If you aren't building with the same developer account used when your existing app was built (this includes going from free to paid), then you will be installing a brand new (second) Loop app on your phone. Your existing pod won't work with the new app, so you might want to time this transition when you are due to change pods. Delete the old app once you get the new one all set up.
  • \"What if it is a new computer but the same developer account?\" No big deal...use the Updating Steps to check that your new computer has the required compatible versions and then build your app. This will include installing Xcode, configuring Xcode Settings, and adding your Developer ID to Xcode: refer to What about a New Computer?. There is no need to delete provisioning profiles on a brand new computer, but no harm comes from following the instruction.
"},{"location":"build/updating/#when-to-update-loop","title":"When to Update Loop","text":"

Under ordinary circumstances, you do not have to update your Loop app until it expires (1 year for a paid account). However, we encourage regular updates when a new version of iOS, or of Loop, is released because they often contain bug fixes or improvements which may increase operational stability.

"},{"location":"build/updating/#ios-updates","title":"iOS Updates","text":"

Under ordinary circumstance, updating the iOS on your phone does not require a rebuild of the app on your phone. However, it's important to be prepared in case of an emergency, such as a lost phone.

Best Practice

It is good practice to first check if your computer (macOS or Xcode) will require an update to support building Loop to your phone BEFORE applying an iOS update to your Looping phone.

Follow these \"safe Looping\" steps for updating your iOS:

  1. Check which version of macOS and Xcode is required for the phone iOS you intend to install.
  2. Update macOS / Xcode if needed
  3. Check Loop: Current Release status - if there is new code, you should download it
  4. Build app to your iPhone
  5. Then update your iPhone iOS

Loop Releases provides information about current and previous Loop versions.

Updating to iOS 16 (watchOS 9 or newer) requires enabling Developer Mode. Your existing app will not open until you take this step. Once enabled, the app opens again. A rebuild is not required.

"},{"location":"build/updating/#loop-is-no-longer-available","title":"\"Loop\" is No Longer Available","text":"

The apps built and signed by you in Xcode with a paid developer account will last for 12 months; then they expire and must be rebuilt. At least once per year you will have to rebuild your app and go through this update process. If you do not update and the \"provisioning profile\" on your phone expires, you will see the \"Loop\" is No Longer Available message. You will be given multiple Loop App Expiration Notifications on the Loop phone, but might miss them if you are a caregiver.

When you see \"Loop\" is No Longer Available on your phone, the only solution is to rebuild the app. All of your settings are still present on your phone, but your \"provisioning profile\" expired and you need to generate a new one. Once you build Loop on your phone, following the instructions on this page, all your settings will be maintained - assuming you build with the same Apple Developers ID that was used initially.

"},{"location":"build/updating/#macos-and-xcode-versions","title":"macOS and Xcode Versions","text":""},{"location":"build/updating/#determine-required-xcode-and-macos-versions","title":"Determine Required Xcode and macOS Versions","text":"

Between Loop app builds, there's a high likelihood that Apple has updated one or more of the systems involved in your Loop app. If you don't have the minimum Xcode version required for your phone iOS, you cannot build on that phone. Sometimes you must also update the macOS version to allow you to use the required Xcode version.

Based on the iOS on your phone, or the iOS you plan to install on your phone, determine the required macOS and Xcode versions. Click on this link versions for iOS, macOS and Xcode to determine the versions needed and then hit the back button in your browser to finish the steps on this updating page.

If you are tired of the macOS and Xcode version update requirements, check out the Build with Browser option.

First macOS and Then Xcode

Your macOS must meet the minimum requirement for the Xcode version you need to support your current iOS as detailed in that link above.

  • If the macOS is too old, the Xcode version will not appear in the App Store
  • You might think you don't need to update Xcode (but you do)
  • Your build will fail and mentors might need to help you

Don't be that person. Follow the directions.

Minimum means you need to have at least that version - newer versions build just fine.

"},{"location":"build/updating/#verify-update-macos","title":"Verify / Update macOS","text":"
  • Click on this link Check your macOS Version and follow the instructions on that page if an update is required.
  • After you've reviewed that section, hit the back button on your browser to return here
"},{"location":"build/updating/#verify-update-xcode","title":"Verify / Update Xcode","text":"

Click on this link Check your Xcode Version to find your Xcode version number.

If you need to update your Xcode, follow the instructions at this link Install Xcode and continue through Xcode Settings.

Advanced users: If you are finding installation of Xcode from the App Store incredibly slow, try the alternate method of Direct Download of Xcode.

Direct Download

  • If you previously did a direct download of Xcode, it might not show up in the App Store.
  • Either do another direct download or follow these directions in the Direct Download section to reconfigure so it will show up in the App Store.
    • Direct Download of Xcode
"},{"location":"build/updating/#what-about-a-new-computer","title":"What about a New Computer?","text":"

Make sure your new computer has the macOS and Xcode required by your phone iOS. Be sure Xcode Command Line Tools are installed and that you Add Apple ID to Xcode.

"},{"location":"build/updating/#missing-xcode-or-command-line-tools","title":"Missing Xcode or Command Line Tools","text":"

WARNING

If you fail to have Xcode or Xcode Command Line Tools installed, you will get one of these errors (or something similar) when you attempt to run the Build Select Script:

  • xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
  • xcrun: error: active developer path (\"/Applications/Xcode.app/Contents/Developer\") does not exist
  • xcode-select: Failed to locate 'git', requesting installation of command line developer tools
  • xcode-select: error: tool 'xed' requires Xcode
  • Scripting Bridge could not launch application . . .

Follow Xcode Settings page after updating Xcode

Make sure to restart your computer after updating Xcode and follow the instructions on the Xcode Settings page. There's a known issue that happens often enough to be frustrating if you skip those steps. It's not always required...but this is a good easy ounce of prevention step.\n
"},{"location":"build/updating/#check-your-developer-account","title":"Check your Developer Account","text":"

Apple updates its License Agreement for the Developer Program frequently. You need to login to your developer account to manually check if there is a new agreement to accept. If you see a big red or orange banner across the top of your Developer Account announcing a new license agreement like shown below...please read and accept it before building Loop.

"},{"location":"build/updating/#ready-to-build-loop","title":"Ready to Build Loop","text":"

As long as there are no errors, you are now ready to proceed to Build the Loop App: Developer Mode

After building the new app, you may choose to return to this page and follow the instructions to Delete Old Copies. This is optional, but cleans up space on your computer.

"},{"location":"build/updating/#delete-old-copies","title":"Delete Old Copies","text":"

This step is optional, but if your computer is low on space, it helps to clean up old downloads your are no longer using.

There is an easy way to do this. The Build Select Script used to download and build Loop provides Maintenance Utilities to help free up disk space.

Please review Loop and Learn: Build Select Script for more information.

Copy the line below that starts with /bin/bash by hovering the mouse near the bottom right side of the text and clicking the copy icon (should say Copy to Clipboard when you hover over it). When you click the icon, a message that says Copied to Clipboard will appear on your screen.

Copy and Paste to start the Build Select Script
/bin/bash -c \"$(curl -fsSL \\\n  https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildSelectScript.sh)\"\n

Paste the line of text into Terminal. Be sure to click anywhere in the terminal before trying to paste. (Ways to paste: Cmd+V ; or Ctrl click and select from menu or Edit-Paste at top of Mac screen.)

  • Please read what is on the screen as you progress
  • Choose Option 3. Run Maintenance Utilities

If you prefer to clean up old downloads yourself, keep reading.

Where is the old folder?

Assuming you used the Build Select Script, your downloads are in the ~/Downloads/BuildLoop folder as shown in the graphic below. If you are tight on space, the older folders can be deleted. Best practice, download fresh and build Loop; and then go back and delete all but the most recent copy. The nice thing about the Build Select script is it automatically generates the folder name with the date and time of the download. Delete each unwanted folder, one at a time.

If you see a file (not a folder) in ~/Downloads/BuildLoop called LoopConfigOverride.xcconfig, keep that around. If you delete it, you'll need to recover it from the trash, regenerate it (if you know how) or sign your targets manually for your current download.

The Scripts folder can also be left alone, but if you delete it, it is regenerated with the next use of the Build Select Script.

"},{"location":"build/updating/#background-information","title":"Background Information","text":"

New Loopers do not need to read the rest of this page.

Experienced Loopers may wonder what happened to deleting derived data.

  • Each workspace folder has a unique folder for storing derived data
  • Deleting derived data across all Xcode workspaces and projects for a brand new download is not required to ensure a year for a given build
  • The Clean Derived Data option in the Utilities menu can be required for some special cases, but you probably won't need it
"},{"location":"build/updating/#frequent-builder","title":"Frequent Builder","text":"

If you build frequently, you do not have to delete the profiles every time. When the build script asks if you want to \"Ensure a Year?\", you can skip that step.

On the other hand, you may need to delete the provisioning profiles or saved Xcode information about a version of LoopWorkspace (or other app) currently on your computer. The maintenance utilities found in the BuildSelectScrip can be run to delete your provisioning profiles or clear derived data. Or you can use the individual commands in the next sections to do the same thing.

"},{"location":"build/updating/#delete-provisioning-profiles","title":"Delete Provisioning Profiles","text":"

You can delete your provisioning profiles by copying this command and pasting it into any terminal. This does not affect any build you currently have on your phone - this just forces your current computer to generate a new one next time you build with Xcode.

Copy and Paste to manually remove your Provisioning Profiles on your computer
rm ~/Library/MobileDevice/Provisioning\\ Profiles/*.mobileprovision\n
"},{"location":"build/updating/#delete-derived-data","title":"Delete Derived Data","text":"

If you build using the same clone on your computer and then update that clone, sometimes you want to remove derived information that Xcode remembers and force it to start fresh.

First quit out of Xcode. The following command will delete all derived information for all your clones, so next time you build any app from an existing clone on your computer, the build will take longer. All dependencies will download again. So wait until you see the \"indexing\" indication on Xcode before trying to build.

Copy and Paste to manually force Xcode on your computer to start fresh
rm -rf ~/Library/Developer/Xcode/DerivedData\n
"},{"location":"build/updating/#revoke-certificate-issue","title":"Revoke Certificate Issue","text":"

What does it look like if you run into the Revoke Certificate message? When you prepare to Sign the Targets with Xcode, you'll see the message highlighted in the figure below.

More information is shown in the orange box below.

Revoke certificate

The important part of this message is:

  • \". . . signing certificate . . . private key is not installed in your keychain . . .\"

WAIT - You might not need to revoke your certificate

  1. You might get this if you logged in as a different user, have a new computer or if your computer had to undergo a factory reset
    • You can transfer your keychain to your new computer (or just revoke and keep going)
    • To transfer your keychain, check this Apple Documentation Link
  2. Your version of Xcode is way out-of-date
    • Mentors have seen this with people trying to build with Xcode 11.4 or earlier
    • Update Xcode to the most recent version

If you revoke and keep going:

  • If you do hit Revoke Certificate, you'll be given a new one
  • Even with the new certificate, your Apple Developer ID is not affected
  • You can re-build on the existing Loop app on your device(s) and maintain all your settings with the new certificate.

Be aware that you will have to rebuild to every device that used the certificate you just revoked and if you have other apps built with this certificate, they will stop working too.

"},{"location":"build/updating/#direct-download-of-xcode","title":"Direct Download of Xcode","text":"

Many people find updating Xcode from the App Store to be incredibly slow - especially when a new version has just been released. This method still takes time and enough space on your disk but is faster than going through the App Store. Depending on your internet speed, this download can be done in about an hour. Then once it is downloaded, expect another fifteen minutes to several hours (depending on the speed of your computer) for the \"xip\" file to \"expand\".

The instructions do not hold your hand.

  • Your macOS must be at the minimum version (or newer) to support the version of Xcode you're about the download
  • You need to know how to log into your Apple Developer account and navigate those menus
  • You need to know how to use Finder to navigate to Downloads
  • You need to know how to drag the Xcode icon into your Applications folder (after download and expand completes)
  • After you have done a direct download, the App Store will not show you updates
    • Either repeat the Direct Download or
    • Delete Xcode from Applications folder
      • Open the App Store and search for Xcode
      • Install fresh
      • After you use the App Store for a download, then Updates will show in the future

Here are the different steps you need to follow when doing the Direct Download instead of the App Store method:

  1. Login to your Apple developer account
    • Examine the menus (on my computer there are buttons on the left-hand side)
    • Click on Downloads (under Additional Resources)
    • Look at menu items (on my computer there are buttons at the top) that say Beta, Release, Profiles and Logs, and More
    • Click on More
    • Scroll down until you find the item you want (for example, Xcode 13)
    • Click on View Details and click on the Download button for the \"xip\" file
  2. Wait for Download to complete
  3. Expand the file by clicking on it in Finder
  4. Move the Xcode icon to Applications after the expansion completes
  5. Check the Command Line Tools setting under Xcode->Settings
    • The selection cannot be blank or Build-Script will fail to open Xcode automatically
    • It should be the same version as your Xcode
  6. Reboot the computer
"},{"location":"build/xcode-settings/","title":"Xcode Settings","text":""},{"location":"build/xcode-settings/#xcode-settings","title":"Xcode Settings","text":"

Time Estimate

  • about 10-15 minutes to install the Command Line Tools
  • 5 minutes to add your Apple ID, assuming you remember your password

Summary

  • Verify that Command Line Tools are installed: Xcode-> Settings -> choose Locations tab.
  • Add your Apply ID: Xcode-> Settings -> choose Accounts tab.

FAQs

  • \"I still only see an account with (personal team) beside it even though I enrolled in the paid Developer Account program...what should I do?\" You should check your spam email box in case Apple sent you an email there. Make sure you've waited the 48 hours that Apple says it may take to get your account approved. If it's been 48 hours and you still don't see anything in your email, contact Apple support and ask them about the status of your enrollment. It may be held up by something on their end.
"},{"location":"build/xcode-settings/#xcode-version","title":"Xcode Version","text":"

Open Xcode from your Applications folder. If it offers to start a new project with you, just close that window.

Click on the Xcode->About Xcode menu item. The version number is displayed.

"},{"location":"build/xcode-settings/#privacy-settings","title":"Privacy Settings","text":"

This is not typical, but it does happen.

Some people have their macOS privacy settings configured so that Xcode does not have permission to access their ~/Downloads folder. This will cause a lot of grief when trying to use the Build Select Script to build an app with Xcode. This will be mentioned on the build errors page, but this is a good time to check. The graphic below has steps labeled 1 through 4 to guide you to the setting that must be enabled for you to build the app with Xcode.

"},{"location":"build/xcode-settings/#watchos-simulators","title":"watchOS Simulators","text":"

Yes, watchOS simulators are required to build Loop. If Xcode asks if you want to download them - say yes. It's slow but you cannot build Loop without the simulator.

  • Tap on New with Xcode 14 for more information
"},{"location":"build/xcode-settings/#command-line-tools","title":"Command Line Tools","text":"

The very first time you open Xcode it may install a package of command line tools. Wait patiently until it finishes. The command line tools may have installed without asking.

  • Check that your Command Line Tools installed correctly.
    • First, open Xcode Settings
      • Click on the word Xcode in the top menu bar (just to the right of the Apple icon in the upper-left corner) and select Settings in the drop-down menu
    • Then select the Locations tab in the Settings window to see the dropdown menu for Command Line Tools. Make sure the Xcode version listed matches what you just installed (not the version in this graphic)
  • If it's blank, use the blue arrows to the right of the Command Line Tools row to select it

"},{"location":"build/xcode-settings/#add-apple-id","title":"Add Apple ID","text":"

Go to the Xcode Settings window from above, click on the Accounts tab and then press the + in the lower-left corner to add an Apple ID account.

"},{"location":"build/xcode-settings/#xcode-accounts-tab","title":"Xcode Accounts Tab","text":"

The Xcode Accounts Tab, shown in the graphic (from Xcode 13) below allows you to have more than one account available to choose from when you sign your targets (another new term that is explained later). Normally, you would only have one.

In the graphic, whichever item is selected on the left side (highlighted by Xcode in blue) shows up with more details on the right side of the display. If the Free account had been selected, the information shown in the red inset would have been displayed.

Free and Paid

The graphic below shows examples for a paid account and a free account. You will only see one.

"},{"location":"build/xcode-settings/#free-developer-account","title":"Free Developer Account","text":"

If you want to use a free developer account, you will simply enter your Apple ID in this section and Xcode will automatically enroll your Apple ID in the free developer program. It will show up with the (Personal Team) and User indication.

"},{"location":"build/xcode-settings/#paid-developer-account","title":"Paid Developer Account","text":"

If you enrolled in the paid account already and have confirmation that your account is active, enter the Apple ID of the paid developer account. It will show up with just your name and the Admin indication. If you have enrolled and are waiting, the (Personal Team) and User indication shows up until the paid account is confirmed by Apple.

Description

The description line is initially empty. You can add your own description or just leave the line blank. Text added to the decription line shows up in two places: To the left, just above the email address and to the right once that Apple ID is selected.

You are now done setting up Xcode. Great job! You will not need to redo the account setup steps on any subsequent builds or updates of your Loop app. Xcode will remember these settings.

"},{"location":"build/xcode-settings/#next-step-build-loop","title":"Next Step: Build Loop","text":"

Now you are ready to Build the Loop App.

"},{"location":"build/xcode-version/","title":"Xcode Version","text":""},{"location":"build/xcode-version/#install-required-xcode-version","title":"Install Required Xcode Version","text":"

Time Estimate

  • 45 minutes to 2 hours, depending on internet connection...but you don't need to babysit the download.
  • 0 minutes if you decide to use the Build with Browser method to build Loop

Summary

  • Check iPhone iOS version
    • The iOS version determines minimum Xcode version
    • The minimum Xcode version determines minimum macOS version
    • If necessary, update macOS first and then return to this step
  • Download (or update) Xcode from your computer's App Store application

FAQs

  • \"Why isn't my Xcode installing?\" The two most common reasons are:
    1. Lack of internet connection, or
    2. Not enough space on your hard drive
      • Xcode is a large download, and needs at least 50GB of space to properly unpack and install itself
      • If you do not have enough space on your hard drive, you will have installation failures
      • Check the Space Available
      • Although the download takes a long time, the good news is you can walk away once the download starts. If your laptop goes to sleep when you close the lid or when the screen saver starts, disable the screen saver and leave the laptop open.
      • After Xcode has finished downloading (looks like the progress bar is almost completed), it takes a long time to unpack and install, be patient
  • \"Can I install Xcode on an external drive?\" Unfortunately, no. Xcode needs to be on the Mac hard drive. But other things--like photos and documents--can be moved to an external drive to make room for macOS and Xcode updates.
"},{"location":"build/xcode-version/#what-is-xcode","title":"What is Xcode?","text":"

Xcode is a free application for Apple computers. You will use Xcode to turn the \"raw\" Loop source code into an iOS application and install it onto your iPhone. Which version of Xcode you install on your computer depends on the iOS version you have on the iPhone you are going to be installing Loop on and the macOS version you have on your computer.

Because of the complexity of these dependencies, please read this entire page.

Or - look into building with GitHub Actions - no Mac computer required, no need to worry about versions for Mac OS or Xcode - all done for you on GitHub (some configuration required).

"},{"location":"build/xcode-version/#which-version-of-xcode-do-i-need","title":"Which version of Xcode do I need?","text":"

First, choose a version of Xcode appropriate for your iOS device. Then, determine the minimum macOS version required for that Xcode version. Update to at least that minimum macOS version. Then follow the instructions to download and install Xcode (or update an existing installation):

  • Open the App Store on your computer and search for \"Xcode\"
  • If the version number you need is bigger than what is shown in the App Store, you need to first update your macOS
    • Do not rely on the version number in this graphic

"},{"location":"build/xcode-version/#version-relationship-overview","title":"Version Relationship Overview","text":"

Have you turned off automatic updates on your iOS device?

Loop and iOS Updates

Please Read: Turn Off Automatic Updates

Before manually accepting an iOS update, be sure you have compatible versions of Xcode and MacOS.

Minimum Xcode Version

The minimum version of Xcode you need depends on the iOS version you have on your phone.

Please Read: Minimum Version List

Can't find the required Xcode version

  • If your computer is not running the required minimum macOS, the App Store won't show the required minimum Xcode version
  • You must use iOS to determine which Xcode, which determines which macOS
  • Update your computer to at least that minimum macOS first

Don't be the person who posts for help saying, \"I'm trying to update my Loop app but am getting errors.\" When asked what Xcode version they have and if they've updated, they respond, \"I don't have any Xcode updates available in the App Store, so I must be running the most current version.\"

Actually, they forgot to check for macOS updates and therefore cannot see the needed Xcode update yet.

"},{"location":"build/xcode-version/#after-update-reboot","title":"After Update - Reboot","text":"

After any update of macOS or Xcode, it is always a good idea to reboot your computer.

"},{"location":"build/xcode-version/#how-do-all-the-minimum-versions-relate-to-each-other","title":"How do all the minimum versions relate to each other?","text":""},{"location":"build/xcode-version/#compatible-versions","title":"Compatible Versions","text":"

The current development version and the next release of\u00a0Loop\u00a0will require Xcode version 15 regardless of the iOS on the phone. This requires macOS 13.5 or higher. As an alternative, use Build with Browser, which supports iOS 15, 16, and 17.

When this page was last updated, macOS 14.0 and Xcode 15.0 were tested to successfully build the app for phones with iOS 15 through iOS 17.0.2.

The table below lists the minimum requirements to build the current release of\u00a0Loop 3.2.3. If your macOS or Xcode version is higher, you can build with Mac.

Find your phone iOS in the table below. If your iOS is not listed, e.g., 16.6, choose the first row that is less than your iOS.

iOS Version minimum Xcode minimum macOS 17.0 15.0 13.5 16.4 14.3 13.0 16.2 14.2 12.5 15.1 14.1 12.5"},{"location":"build/xcode-version/#wikipedia-chart-for-apple-versions","title":"Wikipedia Chart for Apple Versions","text":"

This graphic (copied from Wikipedia and last updated March 2023) is not updated with every iOS update - use it as a map to read the minimum requirements. Every attempt will be made to update the words in the Minimum Version List promptly - that's much easier than updating a graphic.

Follow this link to Wikipedia and scroll down to the current version of this figure - the graphic shown below is a map of how to read the current version of this figure at Wikipedia.

"},{"location":"build/xcode-version/#what-happens-if-you-try-using-too-old-of-xcode","title":"What happens if you try using too old of Xcode?","text":"

It isn't some catastrophic failure if you try to build with an outdated Xcode without realizing it. If the build fails, nothing happens to your phone (or Loop on your phone if you are rebuilding). Nothing is copied from the computer to the phone until after you see the Build Succeeded message. You'll see a pretty obvious error message during your Loop build. Check Oh dear! Build errors?.

Some error messages that have shown up in earlier updates:

Package.resolved file corrupted or malformed\n

This is for trying to select an iOS 17 phone when building with Xcode 14:

Could not locate device support files\n

This is for building development code with Xcode 14 instead of Xcode 15:

Loop Widget errors like:\nCommand SwiftCompile failed with a nonzero exit code\nCannot infer contextual base in reference to member 'widget'\n
"},{"location":"build/xcode-version/#next-step-xcode-settings","title":"Next Step: Xcode Settings","text":"

Now you are ready to set up Xcode Settings.

"},{"location":"faqs/algorithm-faqs/","title":"Algorithm FAQs","text":""},{"location":"faqs/algorithm-faqs/#does-loop-learn-or-detect-changes-in-your-insulin-needs","title":"Does Loop \"learn\" or detect changes in your insulin needs?","text":"

The answer is both Yes and No.

Yes in that:

  • There is a short-term retrospective analysis built into Loop which will apply a weighted-correction based on the past 60 minutes of blood glucose changes.
  • Loop works best if you enter an estimate of carbs and absorption time for meals, but it also is fairly forgiving
    • There are discussions on Insulin Counteraction Effect (ICE) on a number of pages within LoopDocs:
      • Dynamic Carb Absorption
      • Carbohydrate Effect
      • Insulin Counteraction Effect

No in that:

  • Loop assumes the settings you've provided are correct.
    • Loop does not adjust or \"learn\" the Therapy Settings portion of Loop parameters directly
      • It keeps those fixed and user controlled, separate from the dynamic part of the Loop algorithm, which does learn based on short-term patterns
      • If outside factors (such as hormones, illness, exercise, medications, etc) affect your underlying Therapy Settings you may need to manually adjust those settings.
  • This LoopTips 3-page section on Settings is recommended.

Perhaps in subsequent versions of Loop, auto-adjustment of settings or machine learning could be incorporated. Until then, you will need to tell Loop if your underlying settings change or make temporary adjustments for short term issues.

The use of Overrides can be quite helpful for short-term changes.

"},{"location":"faqs/algorithm-faqs/#what-does-negative-active-insulin-mean","title":"What does negative Active Insulin mean?","text":"

When Loop withholds or suspends some of your scheduled basal insulin, that starts an accumulation of insulin deficit. If you have a kinked cannula and insulin is not delivered, you'd call yourself \"lacking insulin\" (negative IOB).

When Loop reports negative IOB, it is a sign that Loop has been actively helping you prevent a low blood sugar. If you find significant negative IOB regularly, you probably need to adjust/test your settings. Glucose that continues to decrease (away from a meal) when IOB goes negative is typically a sign that the scheduled basal rate is too high.

Developer Notes

Scheduled basal rates are meant to counteract your endogenous glucose production. Another way of saying this is that Loop expects your body to be producing an amount of glucose at a rate that is handled by your basal insulin settings.

Your body doesn't really produce glucose at a fixed rate, but that's how it's modeled in Loop.

\"All models are wrong, but some are useful.\" (Quote attributed to British statistician George E. P. Box.)

"},{"location":"faqs/algorithm-faqs/#how-is-iob-calculated","title":"How is IOB calculated?","text":"

Insulin on board (IOB) is calculated from the amount of insulin delivered above or below the scheduled basal rate. For each dose of insulin, the insulin model is used to determine how much of that insulin is active over time. Loop is adding up all the amounts over the full Duration of Insulin Action (DIA). The DIA is 6 hours for most rapid insulin in the models used by Loop.

IOB is plotted on the Active Insulin Chart in the main Loop display.

"},{"location":"faqs/algorithm-faqs/#how-do-delivery-limits-affect-automatic-dosing","title":"How do Delivery Limits Affect Automatic Dosing?","text":"

With each cycle, Loop\u00a0generates a glucose prediction and a recommended dose (positive or negative) to bring you to your correction range.

  • The nearest 3 hours has more influence on the recommendation than the later 3 hours, but the entire 6 hours is considered
  • The automated response to a negative recommended dose is to reduce basal rate, typically to zero
  • The automated response to a positive recommended dose depends on your Dosing Strategy and is adjusted by your Delivery Limits

Let \\(\\mathit{dose}\\) be the amount the app thinks you need for this cycle before considering Delivery Limits. The relationship between \\(\\mathit{dose}\\), delivery limits: \\(\\mathit{maximumBolus}\\) and \\(\\mathit{maximumBasalRate}\\), and current IOB: \\(\\mathit{currentIOB}\\) are detailed in the following sections:

  • Manual Dose
  • Automatic Dose
    • Automatic Bolus: Constant Partial Application Factor
    • Automatic Bolus: Glucose Based Partial Application Factor
    • Temp Basal Only
"},{"location":"faqs/algorithm-faqs/#manual-dose","title":"Manual Dose","text":"

In this case, where you are manually requesting a bolus recommendation by using the double orange triangles (circled below) in the toolbar at the bottom of the Loop status screen, only the \\(\\mathit{maximumBolus}\\) Delivery Limit is considered.

  • If \\(\\mathit{dose}\\) > \\(\\mathit{maximumBolus}\\): app recommends \\(\\mathit{maximumBolus}\\)
  • If \\(\\mathit{dose}\\) < \\(\\mathit{maximumBolus}\\): app recommends \\(\\mathit{dose}\\)
"},{"location":"faqs/algorithm-faqs/#automatic-dose","title":"Automatic Dose","text":"

Because this will be an automatic dose, the app will not provide a dose that would exceed an IOB of 2 times the \\(\\mathit{maximumBolus}\\). The term automatic dose refers to insulin the app automatically delivers above your scheduled basal rate.

\\[ autoDose = minimum (dose, {2*maximumBolus} - currentIOB) \\]

Note that a manual dose can exceed \\(\\mathit{autoDose}\\). There will be no warning if this happens. But no additional automatic dosing will happen until IOB is below \\(\\mathit{2*maximumBolus}\\). As long as the prediction is above the correction range, scheduled basal continues regardless of IOB.

"},{"location":"faqs/algorithm-faqs/#automatic-bolus-constant-partial-application-factor","title":"Automatic Bolus: Constant Partial Application Factor","text":"

There is a new feature coming with the next release, available now with customization or the development version, called Glucose Based Partial Application Factor. This feature is disabled by default. When disabled, the Partial Application Factor is a constant 40%.

  • If \\(\\mathit{autoDose}\\) > \\(\\mathit{maximumBolus}\\): app boluses 40% of \\(\\mathit{maximumBolus}\\)
  • If \\(\\mathit{autoDose}\\) < \\(\\mathit{maximumBolus}\\): app boluses 40% of \\(\\mathit{autoDose}\\)
"},{"location":"faqs/algorithm-faqs/#automatic-bolus-glucose-based-partial-application-factor","title":"Automatic Bolus: Glucose Based Partial Application Factor","text":"

When Glucose Based Partial Application Factor is enabled, the application factor is modified based on the current glucose level. The value ranges from 20% at lower glucose to 80% at higher glucose. Let \\(\\mathit{gbpa\\%}\\) represent the application factor, then:

  • If \\(\\mathit{autoDose}\\) > \\(\\mathit{maximumBolus}\\): app boluses \\(\\mathit{gbpa\\%}\\) of \\(\\mathit{maximumBolus}\\)
  • If \\(\\mathit{autoDose}\\) < \\(\\mathit{maximumBolus}\\): app boluses \\(\\mathit{gbpa\\%}\\) of \\(\\mathit{autoDose}\\)
"},{"location":"faqs/algorithm-faqs/#temp-basal-only","title":"Temp Basal Only","text":"

This automatic method uses both Delivery Limits: \\(\\mathit{maximumBasalRate}\\) and \\(\\mathit{maximumBolus}\\). As explained above, the \\(\\mathit{maximumBolus}\\) is used to calculate \\(\\mathit{autoDose}\\).

The desired dose, \\(\\mathit{autoDose}\\), is multiplied by two (to get an hourly rate) and then added to the scheduled basal rate to determine the desired temporary basal rate (\\(\\mathit{BR_temp}\\)) with a duration of half-an-hour to provide that amount of insulin. This calculated \\(\\mathit{BR_temp}\\) is compared to \\(\\mathit{maximumBasalRate}\\).

  • If \\(\\mathit{BR_temp}\\) > \\(\\mathit{maximumBasalRate}\\): app sets rate to \\(\\mathit{maximumBasalRate}\\)
  • If \\(\\mathit{BR_temp}\\) < \\(\\mathit{maximumBasalRate}\\): app sets rate to \\(\\mathit{BR_temp}\\)
"},{"location":"faqs/algorithm-faqs/#more-algorithm-information","title":"More Algorithm Information","text":"

There is more detail about the Loop Algorithm at the bottom of the Operate tab.

  • Algorithm Overview
    • Bolus Recommendations
    • Blood Glucose Prediction
    • Automatic Adjustments
"},{"location":"faqs/apple-health-faqs/","title":"Apple Health FAQs","text":""},{"location":"faqs/apple-health-faqs/#how-does-loop-use-apple-healthkit","title":"How does Loop use Apple HealthKit?","text":"

Loop uses Apple HealthKit as long term storage for glucose, insulin and carbohydrates. But there is more going on than simple storage.

It is important that permissions for Loop be properly configured for the Health app.

  • Loop 3.x.x: See Apple Health Permissions
  • Loop 2.2.x: See Health Permissions
    • If you are still on Loop 2 (or FreeAPS), consider updating to Loop 3

To view the list of data stored in Health

  • Tap on the Health icon to open the app
  • Tap on Blood Glucose, Carbohydrates or Insulin
  • Scroll all the way to the bottom
  • Tap on Show All Data

To Set Blood Glucose, Carbohydrates and Insulin as Favorites

  • Tap on the Health icon to open the app
  • There's a toolbar at the bottom of the screen (always visible in the app)
  • Tap on the Browse icon (bottom right of toolbar)
  • Tap on
    • Other Data for Blood Glucose and Insulin
    • Nutrition for Carbohydrates
  • Tap each item, scroll down to Options section and tap on Add to Favorite
  • Repeat until all three are added
  • Tap on the Summary (bottom left icon of toolbar); Favorites show up first
"},{"location":"faqs/apple-health-faqs/#healthkit-plots","title":"HealthKit Plots","text":"

The health app on the Loop phone provides useful plots of data since you started to Loop with that Apple ID. Examples for insulin delivery and carbohydrates are shown in the graphic below. New versions of iOS modified details of the display with the same or improved capabilities.

"},{"location":"faqs/apple-health-faqs/#healthkit-details","title":"HealthKit Details","text":""},{"location":"faqs/apple-health-faqs/#glucose-and-apple-healthkit","title":"Glucose and Apple HealthKit","text":"

For Dexcom users with the Dexcom app on the Loop phone, the Dexcom app writes the value to Health with a 3-hour delay.

Loop reads the Dexcom information at the same time the Dexcom app gets the reading from the transmitter. It uses the glucose value to update predictions and stores it in Health.

If you look at your Health glucose readings, you'll notice the Loop icon for the last 3 hours and the Dexcom icon for times earlier than that.

All other CGM readings are reported with the Loop icon and there is no transition after 3 hours.

"},{"location":"faqs/apple-health-faqs/#carbohydrates-and-apple-healthkit","title":"Carbohydrates and Apple HealthKit","text":"

In Loop* 2.2.x, if you set Apple Health app permissions to allow it, Loop will read carbohydrates from the Health app. If you give a third-party app permission to store carbohydrate data in Health, and do not realize that Loop reads that information, you might get unexpected insulin delivery based off those carbs. To avoid that unanticipated behavior, the directions tell you to set permissions to allow Loop to write to carbohydrate storage but not read.

In Loop 3, the option to read from Health carbohydrates is explicitly disabled and can only be enabled by setting up special parameters when you build the app. The insructions for the code customization are not in LoopDocs yet. If it is important to you to use a third-party app to record carbohydrates and have Loop read the information and automatically dose with insulin, ask for help in zulipchat.

"},{"location":"faqs/apple-health-faqs/#insulin-and-apple-healthkit","title":"Insulin and Apple HealthKit","text":"

The relationship between Loop and Apple HealthKit is very important to understand if you ever need to do one of these actions:

  • Dose insulin from another source (injection, smart pen)
  • Remove insulin that wasn't really given (failed site or forgot to reattach a tubed pump)

Be Cautious

Allowing users to delete events is fairly risky. If a user deletes a dose accidentally, or does not understand the IOB impact while in closed loop is enabled, then Loop may start giving insulin that is not needed.

One method to deal with insulin that wasn't given is to go disable closed loop for 3 to 6 hours. However, if you take care, you can remove insulin from Loop.

Developer Notes: Pump Events and Insulin Delivery

Loop stores Pump Events separately from Insulin Delivery. With permissions set to allow Loop to read insulin from Health (recommended), the Insulin Delivery store contains doses entered from Health as well as the subset of pump events that represent doses.

Pump Events are displayed by tapping an insulin chart on the main screen and viewing the Event History tab.

When you delete a pump event using the Event History interface in Loop, the associated entry in Insulin Delivery is not deleted.

"},{"location":"faqs/apple-health-faqs/#bolus","title":"Bolus","text":"
  • When Loop commands the pump to provide a bolus, either manual or automatic, it is shown in the Event History and in the Health app insulin data list
    • It may take a loop cycle or two to show up in Health, but it will appear
  • When you add insulin, such as from an injection, to the Health app, Loop reads it and adds it to IOB
    • It will not be added to the Event History because this is not a pump event
    • Loop 3 adds a new feature that allows you to add non-pump insulin from within the app instead of requiring you to add it inside the Health app
  • If you delete an entry from the Event History list, but leave that same entry in Health, Loop reads it back from Health
    • It will not show up in the Event History, but it will still contribute to IOB
    • You must delete a pump event from both Event History and Health data; it is best if you do this within one loop cycle
    • If that dose showed up in Event History but you could not find it in Health, look again after the next loop cycle
  • If you delete an entry from Health, but leave that same entry in Event History, Loop reports it to Health again
    • You must delete a pump event from both the Event History list and Health data; it is best if you do this within one loop cycle

Pro Tip

Write on a piece of paper the times and values you think you should delete.

Look at those values in both Event History and Health Insulin data list.

Record what Loop is reporting as IOB.

Review the values one more time, and then delete those entries in both places. Review IOB again. If you made a mistake, you can refer to that written list and adjust appropriately.

"},{"location":"faqs/apple-health-faqs/#basal","title":"Basal","text":"

Loop keeps track of how much basal is delivered so the IOB is properly reported. In older versions of Loop, there may be occasional display glitches, but the internal accounting is correct and updates every Loop Cycle.

Developer Notes: Scheduled Basal is Not a Pump Event

Scheduled basal is not a pump event so you will not see it listed in the Event History tab.

Scheduled basal does not affect IOB when delivered as scheduled.

The Insulin Delivery store keeps track of the insulin delivered via scheduled basal.

Loop updates the amount of insulin delivered through basal (both scheduled and temporary) to Health at regular intervals - this does not happen every Loop Cycle when basal rates are not changing. The updates to Health happen:

  • At midnight
  • When the scheduled basal rate changes
  • When a temporary basal rate changes

A simple example to illustrate this - for a pump with smallest insulin delivery of 0.05 U:

Schedule Temp Basal (TB) Health Explanation 12:00 AM0.4 U/hr --- --- Start of Day / Start of Example 06:00 AM0.5 U/hr --- 06:00 AMBasal2.4 U Loop reports insulin delivered by basal for the last 6 hours when the scheduled basal rate has a new entry --- 07:15 AM0.0 U/hr 07:15 AMBasal0.6 U Loop reports insulin delivered by basal since last report up to time TB starts --- 07:45 AMTB expires 07:45 AMBasal0 U No insulin was delivered during TB 08:00 AM0.4 U/hr --- 08:00 AMBasal0.1 U Loop reports insulin delivered by basal since last report; the scheduled basal rate has a new entry"},{"location":"faqs/apple-health-faqs/#tidepool-and-apple-healthkit","title":"Tidepool and Apple HealthKit","text":"

If you have a Tidepool account and use the Tidepool uploader on your Loop phone, the data in Health is uploaded to your Tidepool database where you can view displays with the Tidepool web browser tool.

"},{"location":"faqs/apple-health-faqs/#how-do-i-modify-apple-healthkit-permissions","title":"How Do I Modify Apple HealthKit Permissions","text":""},{"location":"faqs/apple-health-faqs/#loop-health-permissions","title":"Loop Health Permissions","text":"

You can review and modify the Apple HealthKit permissions for the Loop app.

Open the Apple Health app ( icon)

  • Find the toolbar at the bottom that says Sharing
  • Scroll to the bottom of Sharing
  • Select Apps
  • Select Loop

At this point, you can review and modify the settings.

"},{"location":"faqs/apple-health-faqs/#cgm-health-permissions","title":"CGM Health Permissions","text":"

If you choose to, you may add permission for your CGM app to write to Apple Health. Loop will read glucose from Apple Health, but only while the phone is unlocked and the app is open.

Note that if a glucose value is added to Apple Health \"now\", Loop will pick up that value and use it for the glucose prediction. This can happen with a finger-stick entry or some Libre third-party apps, but not with Dexcom, which has a 3-hour delay before writing to Health.

"},{"location":"faqs/apple-health-faqs/#dexcom","title":"Dexcom","text":"

The Dexcom app for both G6 and G7 has a 3-hour delay before writing to the Health app. If you tap Glucose data in Health, scroll to the bottom to select Show All Data and then scroll back in time, notice the Loop icon is replaced by either the G6 or G7 icon starting 3 hours ago.

If you happen to wear a Dexcom G6 and G7 sensor at the same time, then starting 3 hours in the past, both sensor traces will show up in the Loop Glucose chart.

Loop only uses data from the CGM you selected as your CGM for closed-loop insulin delivery, but don't be surprised at the double trace if you want to wear both during the transition from G6 to G7.

Add Permission to Health for Dexcom to Write Glucose

If either the G6 or the G7 has permission to write to Apple Health, then Loop will delete the Loop glucose data in Apple Health that are older than 3 hours and newer than 1 week. The Dexcom app will write its glucose values to Health when each value is 3 hours old.

If you transition from G6 to G7 (or alternate back and forth), be sure that at least the app you are currently using has permission to write to health. (I inadvertently forgot to turn on health permission for G7. By the time I noticed, I had a gap of several days in my Apple Health storage of glucose values.)

"},{"location":"faqs/apple-health-faqs/#libre","title":"Libre","text":"

There are several choices for reading Libre sensors.

With Loop dev (will be Loop 3.4.x after release), LibreTransmitter is integrated with the Loop app.

The frequent updates (1-minute glucose data) provided by Libre did cause some issues with released versions (Loop 3.0 and Loop 3.2.x with customizations that use various third-party apps to read the Libre). These were fixed initially by modifying the third-party apps to limit how frequently they supplied glucose data.

With Loop dev (will be Loop 3.4.x after release), the Loop app only initiates a closed-loop cycle automatically following a new glucose value if it has been more than 4.2 minutes since the last one.

Loop 3.0 and Loop 3.2.x versions do not have that limitation on how frequently Loop responds to a new glucose reading. There is a Customization that incorporates the 4.2 minute interval check which can be applied to Loop 3.2.2.

"},{"location":"faqs/apple-health-faqs/#how-do-i-change-glucose-units","title":"How Do I Change Glucose Units?","text":"

The glucose units (mg/dL or mmol/L) Loop uses match what is in Apple Health. Once you connect a device that reports glucose to the phone, make sure the units match the device. Note - you can change units for Dexcom Share and it translates units for you - not sure about other devices.

  • These instructions to change Blood Glucose units are for iOS 15
    • Select the Health app (Heart icon)
    • There's a toolbar at the bottom - select Browse
    • Scroll to find Vitals
    • Select Blood Glucose
    • Scroll to the bottom and select Unit
    • Tap on Unit, if it isn't right, and select the correct units
    • While you are there - go on and select Blood Glucose as a Favorite - it will be easier to find next time
"},{"location":"faqs/cgm-faqs/","title":"CGM FAQs","text":""},{"location":"faqs/cgm-faqs/#which-cgms-are-supported-by-the-loop-app","title":"Which CGMs are supported by the Loop app?","text":"

The next release of the Loop app and the current Loop-dev branch includes Libre support in addition to the CGM listed below.

The Loop app supports G5, G6, G7, Dexcom ONE, Dexcom Share, Nightscout and the Medtronic CGM systems compatible with Looping pumps.

Libre Support (for some Libre sensors):

  • Loop dev adds LibreTransmitter
  • Loop and Learn: Customization

There are more details on the Compatible CGM page.

"},{"location":"faqs/cgm-faqs/#do-i-need-wait-for-a-new-sensor-session-to-start-loop","title":"Do I need wait for a new sensor session to start Loop?","text":"

No, you can start Looping mid-sensor session. There's no need to do anything special with regards to your CGM session when starting or ending the Loop app.

"},{"location":"faqs/cgm-faqs/#what-do-i-do-when-sensor-is-in-warm-up","title":"What do I do when sensor is in warm-up?","text":"

The Loop app will stop automatically adjusting insulin when the most recent glucose value is older than 15 minutes. This is indicated by seeing three dashes in place of the glucose reading on the HUD.

  • A HUD status row message of No Recent Glucose is displayed, making it easier to add the fingerstick value directly in Loop, which also saves it in Apple Health

With no recent glucose readings, your pump returns to the scheduled basal delivery (within 30 min or less).

Loop continues to accept carb entries and manual bolus commands. Manual Temp Basal can also be commanded.

"},{"location":"faqs/cgm-faqs/#dexcom-g7-warmup","title":"Dexcom G7 Warmup","text":"

The Dexcom G7 begins warming up as soon as you insert the device and completes in less than half an hour. Many Loopers use the combination of this warmup upon insertion and the 12-hour grace period offered by the G7 to have continuous CGM readings with no gap.

  • During the 12-hour grace period, start the next sensor but do not connect it to your G7 app on your Looping phone

  • After waiting for the sensor to settle, stop the old sensor and connect to the new sensor

    • The G7 app will show both traces as shown in the graphic below with about 9 hours of settle time
      • The new sensor data is added to the graph along with old sensor readings
      • You cannot see the new sensor until you transition to using it

    • By looking at the trace overlap, you can decide how much you trust the new sensor
"},{"location":"faqs/cgm-faqs/#what-do-i-do-when-i-switch-dexcom-transmitters","title":"What do I do when I switch Dexcom transmitters?","text":"

When you change transmitters (prior to Dexcom G7), you will need to update the transmitter ID in your Loopsettings. The instructions for Dexcom are provided below:

  • In Loop, select the Delete CGM button at the very bottom of the CGM info page
    • You cannot just edit the line with your old transmitter ID
  • It's a good idea to go into your phone Bluetooth settings and delete the old Dexcom transmitter
    • The transmitter starts with Dexcom and ends with the last 2 characters of your old transmitter ID
    • Tap on the (i) next to Not Connected and select Forget This Device
  • Follow the Dexcom instructions for pairing the new transmitter
  • After pairing completes with Dexcom:
    • In Loop, add CGM and select the Dexcom system again
    • Enter the new transmitter ID
    • If you're unsure where to find your transmitter ID, see Where to get the Transmitter ID for Dexcom G6?

If you don't update your transmitter ID when you change active transmitters, and you included your Dexcom share credentials, then the Loop app uses your Dexcom Share server to get your CGM data and will not work without cell or wifi connection. When the Loop app is using data from Dexcom Share servers, a small cloud will appear above the BG reading in the Loop app and should tip you off that maybe you forgot to update your transmitter ID. It's best not to enter Share Credentials. This makes it really obvious that you need to update the CGM settings in the Loop app at transmitter change time.

"},{"location":"faqs/cgm-faqs/#dexcom-g7","title":"Dexcom G7","text":"

With Dexcom G7, the Loop app automatically picks up the active sensor/transmitter pair from the Dexcom G7 app on the phone. Once Dexcom G7 is added to the Loop app as the CGM, the Looper does not need to do anything to the Loop app after selecting the new sensor/transmitter pair in the Dexcom G7 app.

"},{"location":"faqs/cgm-faqs/#dexcom-g5-g6-and-one","title":"Dexcom G5, G6 and ONE","text":"

The diagram below illustrates the steps needed to switch transmitters on Dexcom G5, G6, and ONE (for the version of ONE based on G6). This typically needs to be done every three months when a new transmitter is started.

sequenceDiagram\n    actor       user     as User\n    participant dexcom   as Dexcom App\n    participant loop_app as Loop App\n\n    autonumber\n    user     ->>  loop_app: Delete CGM\n    user     ->>  dexcom:   Stop old Sensor\n    activate      dexcom\n    Note over     dexcom:   Switching sensors and transmitters... \u23f1\ufe0f\n    user     -->> user:     Remove old Sensor and old Transmitter\n    user     ->>  dexcom:   Enter/Scan new Transmitter ID\n    user     ->>  dexcom:   Enter/Scan new Sensor Code\n    user     -->> user:     Insert new Sensor then attach new transmitter\n    user     ->>  dexcom:   Pair then Start new Sensor\n    deactivate    dexcom\n    dexcom   -->> user:     New Sensor warming up... \n    activate      dexcom\n    Note over     dexcom:   New sensor warmup... \u23f1\ufe0f\n    user     ->>  loop_app: Add CGM\n    user     ->>  loop_app: Enter new Transmitter Serial Number\n    user     ->>  loop_app: Enable Remote Upload\n    dexcom   -->> user:     New Sensor operational\n    deactivate dexcom
"},{"location":"faqs/cgm-faqs/#can-i-use-libre-sensors-with-a-reader-like-miao-miao","title":"Can I use Libre sensors with a reader like Miao Miao?","text":"

If you use Loop dev code, then any Libre sensor supported by LibreTransmitter can be used with the Loop app.

See Which CGMs are supported by the Loop app?.

"},{"location":"faqs/cgm-faqs/#can-i-use-eversense","title":"Can I use Eversense?","text":"

There is a method to upload Eversense to Nightscout using an Android phone, but there is no method to read an Eversense directly with an iPhone at this time.

You can use Nightscout as a CGM with Eversense, but that requires internet access.

"},{"location":"faqs/cgm-faqs/#can-the-loop-app-read-cgm-data-from-nightscout","title":"Can the Loop app read CGM data from Nightscout?","text":"

Yes.

"},{"location":"faqs/cgm-faqs/#what-other-cgm-apps-can-be-used-with-loop","title":"What other CGM apps can be used with Loop?","text":"

If you are willing to build a development version of Loop, the dev branch incorporates LibreTransmitter into the Loop app itself. Please read about Loop Development before building dev and using the dev app.

You can add xDrip4iOS and GlucoseDirect as a CGM option to the Loop app by applying a code customization.

Please read the docs for xDrip4iOS and Glucose Direct. You must build these apps yourself to Loop; you cannot use the TestFlight pre-built versions.

"},{"location":"faqs/glossary/","title":"Glossary","text":"

Each item in the glossary is also a Tooltip. The word or phrase is repeated in parentheses to assist those using Google Translate.

When Google Translate is selected:

  • Tooltips, indicated by dashed underline, continue to be shown in English
  • On the Glossary page
    • The first instance (in bold) remains in English
    • The second instance (in parentheses) is translated to your selected language

Actions\u00a0 (Actions): a custom application for the GitHub Actions platform that performs a complex but frequently repeated task; specifically used to build Loop from a browser

Activated\u00a0 (Activated): for Omnipod: time at which insulin was injected into pod and 2 beeps were heard

Anchor Links\u00a0 (Anchor Links): any header on a LoopDocs page can be used as a link, tap on the paragraph symbol at the end of the header to view the link in the URL

API_SECRET\u00a0 (API_SECRET): password (min 12 characters) needed to access Nightscout Site

API\u00a0 (API): Application Programming Interface

APN\u00a0 (APN): Apple Push Notification service, required for issuing remote command via Nightscout

App Group\u00a0 (App Group): a unique identifier that Apple users for a given app, yours has your TEAMID embedded in it, group.com.TEAMID.loopkit.LoopGroup

Automatic Bolus\u00a0 (Automatic Bolus): provide a fraction of the recommended insulin automatically with each updated CGM reading (default 40%)

BAGE\u00a0 (BAGE): pump battery age on Nightscout site

Big Sur\u00a0 (Big Sur): older version for operating system for Mac, macOS 11.x

BLE\u00a0 (BLE): Bluetooth low energy, used for communication by phones, CGM and some pumps

Build Select Script\u00a0 (Build Select Script): by running a command in your terminal, this menu-driven tool assists in building Loop

branch\u00a0 (branch): version of code within a single repository or workspace repository

CAGE\u00a0 (CAGE): cannula (or pump site) age on Nightscout site

carthage\u00a0 (carthage): a program that used to be required to build Loop - no longer needed

Catalina\u00a0 (Catalina): older version for operating system for Mac, macOS 10.x

Certificate\u00a0 (Certificate): Apple certificate is used to sign your iOS or Mac apps - tied to but different from your permanent Developer ID

CGM\u00a0 (CGM): continuous glucose monitor, wearable medical device that measures and reports glucose in interstitial fluid

Closed Loop\u00a0 (Closed Loop): Loop will make automated adjustments of insulin delivery using predictions based off user entries, settings, IOB and COB

Open Loop\u00a0 (Open Loop): Loop will not make automated adjustments of insulin delivery but predictions and recommendation features are available

clone\u00a0 (clone): create a copy of a repository on your computer including revision history and ability to update using git commands

COB\u00a0 (COB): Carbs on Board, affects automated insulin delivery: the g of carbohydrates that Loop expects to be absorbed and uses for glucose prediction

commit\u00a0 (commit): a formal change to files in a repository; each commit has an alphanumeric identifier (SHA-1)

Config Vars\u00a0 (Config Vars): configuration parameters for a Nightscout Site

Correction Factor\u00a0 (Correction Factor): how many points your blood sugar will drop for each unit of insulin; Loop calls this Insulin Sensitivity Factor (ISF)

Correction Range\u00a0 (Correction Range): Loop recommends changes to basal and / or bolus to bring glucose predictions into this range

CR\u00a0 (CR): Carb Ratio; how many grams of carbs are covered by one unit of rapid-acting insulin

Delivery Limits\u00a0 (Delivery Limits): max bolus and max basal rates allowed by your therapy settings

Developer Mode\u00a0 (Developer Mode): Extra security for iOS 16 and newer; this must be turned on to allow an app built from Xcode directly to the phone to run on a phone or watch

DIA\u00a0 (DIA): Duration of Insulin Action, the full time insulin is active including a long, low-level tail

DIY\u00a0 (DIY): Do it yourself, a common acronym for the open-source software community (and the maker community)

Dosing Strategy\u00a0 (Dosing Strategy): chosen method for increased insulin dosing: (1) High Temp Basal or (2) Automatic Bolus with scheduled basal

dynos\u00a0 (dynos): used to reboot a Nightscout Site

EmaLink\u00a0 (EmaLink): radio-frequency device Loop uses to control Eros pods (aka. Gen 3) and older Medtronic pumps

EGP\u00a0 (EGP): Endogenous Glucose Production: glucose produced by the body from its reserves (mainly glycogen in the liver)

Event History\u00a0 (Event History): record of pump events (bolus or temp basal) reported and used by Loop

Expiration Date\u00a0 (Expiration Date): your Loop app has a finite life, the app warns you starting 3 weeks before the expiration date

fastlane\u00a0 (fastlane): used as part of the github Build Action method that enables building Loop without a Mac computer or Xcode

Finder\u00a0 (Finder): graphical folder and file display on Mac

fork\u00a0 (fork): a copy of code in a github repository other than the original

GBPA\u00a0 (GBPA): Glucose Based Partial Application: modification to Automatic Bolus Dosing Strategy

GIF\u00a0 (GIF): Graphics Interchange Format (GIF) can be used for small animations and low-resolution video clips

git\u00a0 (git): a tool for version control

GitHub\u00a0 (GitHub): an online service for storing repositories, accessible from a browser

github.com\u00a0 (github.com): an online service for storing repositories, accessible from a browser

GitHub Personal Access Token\u00a0 (GitHub Personal Access Token): used to enable Browser Build of Loop

Glucose Chart\u00a0 (Glucose Chart): Display of measured and predicted glucose values

Glucose Safety Limit\u00a0 (Glucose Safety Limit): Loop will not suggest insulin delivery when glucose prediction (in next 3 hours) goes below this limit; in Loop 2 this was called Suspend Threshold

GMT\u00a0 (GMT): Greenwich Mean Time is mean (average) solar time at 0 degrees longitude, see UTC

Guardrails\u00a0 (Guardrails): limits in the code for user selected settings, recommended and absolute limits are provided

Hamburger Menu\u00a0 (Hamburger Menu): three parallel lines that, when tapped, open a new menu

HUD\u00a0 (HUD): Heads-Up Display at top of Loop main screen, phone in portrait mode

ICE\u00a0 (ICE): Insulin Counteraction Effect - Loop models the expected glucose change based on carbs entered, absorption time and your settings; and adjusts based on measured glucose

Identifiers\u00a0 (Identifiers): names of modules found on your Apple Developer Identifiers page that are required for GitHub build method

IOB\u00a0 (IOB): Insulin on Board, affects automated insulin delivery: the current active insulin (above or below the basal rate) that Loop calculates and uses for glucose prediction

iOS\u00a0 (iOS): operating system used by Apple Mobile devices (iPhone, iPod, iPad)

IRC\u00a0 (IRC): Integral Retrospective Correction: Optional alternative to Retrospective Correction that integrates glucose deviations over a longer time frame

ISF\u00a0 (ISF): Insulin Sensitivity Factor; how many points your blood sugar will drop for each unit of insulin; sometimes called Correction Factor

Issue\u00a0 (Issue): On github - a formal method to report a problem, either code behavior or documentation

JSON\u00a0 (JSON): JavaScript Object Notation; a standard data interchange format that is text-based and human readable

macOS\u00a0 (macOS): operating system for Mac computer

Lock your Phone\u00a0 (Lock your Phone): click the button on the side of the phone to lock it - prevent accidental touch, i.e., accidental Loop command

Loop 3\u00a0 (Loop 3): Latest release with major updates

Loop Cycle\u00a0 (Loop Cycle): typically 5 minutes: new CGM reading, prediction update, pump update and, if in Closed Loop, dosing update if needed

Loop Caregiver\u00a0 (Loop Caregiver): An app you can build to provide remote commands to Loop using Nightscout

Loop Follow\u00a0 (Loop Follow): An app you can build to provide extra alarms and views of important information - can use Dexcom Share or Nightscout to include Loop information

Loop\u00a0 (Loop): With a capital L, Loop is one of several do-it-yourself artifical pancreas systems

Match-Secrets\u00a0 (Match-Secrets): a private repository you must create in your github account, stores keys required to build with github Build Actions

MTB\u00a0 (MTB): Manual Temp Basal: user initiated temporary basal, Omnipod Common feature

MDT\u00a0 (MDT): common abbreviation for Medtronic pumps

modal\u00a0 (modal): message or alert appearing in front of app that must be acknowledged to return to app

Modules\u00a0 (Modules): the Loop code uses a number of modules to handle different components of the entire app

Monterey\u00a0 (Monterey): operating system for Mac, macOS 12.x

Nightscout\u00a0 (Nightscout): a personal website used to view your glucose and diabetes management data, Loop can upload to Nightscout

Onboarding\u00a0 (Onboarding): familiarize new, and existing, Loop users with settings in Loop 3 and ensure the Therapy Settings are all entered and are within safety guardrails

Omnipod\u00a0 (Omnipod): Insulet tubeless insulin pump; Loop supports Eros (with RileyLink) and DASH. Eros is also known as Classic, UST400, and System.

OrangeLink\u00a0 (OrangeLink): radio-frequency device Loop uses to control Eros pods (aka. Gen 3) and older Medtronic pumps

OTP\u00a0 (OTP): one-time password, this is used to enable caregivers to securely execute remote commands to a Looper's phone

Override\u00a0 (Override): a modification to Loop settings that can change the correction range, the sensitivity (basal, ISF and CR) or both

Package Dependencies\u00a0 (Package Dependencies): packages that must be downloaded by Xcode (once) to build the app after downloading the LoopWorkspace to your computer

pill\u00a0 (pill): on Nightscout, small boxes with information, tap for extra details

PR\u00a0 (PR): Pull Request - a formal method to request changes to a repository

prebolus\u00a0 (prebolus): take some or all of a meal bolus before eating

Pre-Meal Range\u00a0 (Pre-Meal Range): modify the correction range for up to one hour by tapping on an icon in the toolbar

Provisioning Profile\u00a0 (Provisioning Profile): associates your app with your Developer ID and limits app lifetime to 1 year (paid) or 1 week (free)

Pull Request\u00a0 (Pull Request): formal method to request changes to a repository

QR\u00a0 (QR): a machine-readable code consisting of an array of black and white squares

Quit the Loop App\u00a0 (Quit the Loop App): quit out of the app - different from closing the app - typically you swipe up in the app switcher

repository\u00a0 (repository): contains project files and each file's revision history

RileyLink\u00a0 (RileyLink): radio-frequency device Loop uses to control Eros pods (aka. Gen 3) and older Medtronic pumps

RC\u00a0 (RC): Retrospective Correction: part of the Loop model that considers actual glucose compared to earlier predictions

SAGE\u00a0 (SAGE): sensor age on Nightscout site

Secrets\u00a0 (Secrets): a method to securely embed personal information into your fork of LoopWorkspace to enable GitHub to have access required to build Loop

TEAMID\u00a0 (TEAMID): One of 6 Secrets: Apple Developer account member number

FASTLANE_ISSUER_ID\u00a0 (FASTLANE_ISSUER_ID): One of 6 Secrets: the issuer ID is associated with your Apple Developer ID and never changes

FASTLANE_KEY_ID\u00a0 (FASTLANE_KEY_ID): One of 6 Secrets: Key ID provided when you create an API key in App Store Connect; it is associated with the FASTLANE_KEY

FASTLANE_KEY\u00a0 (FASTLANE_KEY): One of 6 Secrets: Really long key (several lines); it and FASTLANE_KEY_ID are generated together

GH_PAT\u00a0 (GH_PAT): One of 6 Secrets: Generated with your GitHub account; set it to never expire

MATCH_PASSWORD\u00a0 (MATCH_PASSWORD): One of 6 Secrets: password you make up but must save and cannot change without deleting the Match-Secrets repository

SHA-1\u00a0 (SHA-1): Secure Hash Algorithm 1; used to generate an alphanumeric code for commits in git (github)

Sign Targets\u00a0 (Sign Targets): associate a Developer ID with an app; must sign all targets for a given app

submodules\u00a0 (submodules): for Loop, submodules are repositories defined in the Workspace repository that are required to build the app

Table of Contents\u00a0 (Table of Contents): (TOC) is the list of level 2 and 3 headers on a given page; the title at the top of the page is a level 1 header

Temp Basal Only\u00a0 (Temp Basal Only): provide the recommended insulin automatically using an increase in temp basal over half an hour (limited by max temp basal)

Temp Basal\u00a0 (Temp Basal): modify the scheduled basal rate for a pump

Terminal\u00a0 (Terminal): interface for entering commands to the computer

TestFlight\u00a0 (TestFlight): a method to distribute apps without direct connection

Therapy Settings\u00a0 (Therapy Settings): Basal Rates, ISF, CR, correction and safety ranges and delivery limits

Tokens\u00a0 (Tokens): on Nightscout, configure access permissions using tokens

Tooltip\u00a0 (Tooltip): brief definitions provided for important terms and abbreviations on the website

URL\u00a0 (URL): website address (Uniform Resource Locator)

UTC\u00a0 (UTC): Coordinated Universal Time is a time standard for civil time and time zones worldwide

Ventura\u00a0 (Ventura): operating system for Mac, macOS 13.x

watchOS\u00a0 (watchOS): Apple watch operating system; must be compatible with phone iOS

workflow\u00a0 (workflow): a set of instructions to GitHub to perform an action; the instruction files are found in the .github/workflows folder of the repository

Workspace\u00a0 (Workspace): a grouping of several repositories into a complete package

Xcode Preferences\u00a0 (Xcode Preferences): older name for Xcode Settings

Xcode Settings\u00a0 (Xcode Settings): as of Xcode 14, Xcode menu uses Settings instead of Preferences

Xcode\u00a0 (Xcode): program used to build an app

"},{"location":"faqs/loop-faqs/","title":"Loop FAQs","text":""},{"location":"faqs/loop-faqs/#what-do-i-need-to-loop","title":"What do I need to Loop?","text":"

Please click on the Requirements link.

"},{"location":"faqs/loop-faqs/#can-i-download-the-loop-app-from-the-app-store","title":"Can I download the Loop app from the App store?","text":"

No. The Loop app is not available for download. You must build your own Loop app. The Loop app app will not be available in the Apple App store because that would be distribution of a medical device, and we are not in that \"business\". You can build yourself, but we are not distributors.

Each step needed to successfully build your Loop app is found in these docs. The harder part will be having the patience to read all the documents before you start. New Loop users are so excited to get started that they often skip reading all the great info that these docs contain. As you begin the build...please include time to read the documents that follow what happens after you successfully build your Loop app.

If you have any questions, use the Search feature to find topics in LoopDocs.

"},{"location":"faqs/loop-faqs/#can-i-use-an-android-phone-or-ipad-for-loop","title":"Can I use an android phone or iPad for Loop?","text":"

Loop requires an Apple device. Older iPads do not support Apple Health which is required for Loop. It may be possible with newer iPads and newer iOS, but this has not been tested.

There is open source software that runs on Android phones. Check out AndroidAPS Documention.

"},{"location":"faqs/loop-faqs/#do-i-have-to-be-tech-smart-to-build-loop","title":"Do I have to be \"tech-smart\" to build Loop?","text":"

No. You do not need any experience in code or computers to build Loop. If you already own a computer or tablet and an iPhone, you already have the required level of experience. Beyond that, simply read the directions slowly and diligently...all the information you will need are in these documents.

Often times the non-tech people do better than the tech people in building Loop. Why? Because the non-tech people take the time to read slowly and look at the screenshots in the directions. The tech people often skim and miss steps...which then leads to build errors that have to be retraced and fixed.

"},{"location":"faqs/loop-faqs/#is-there-a-cheat-sheet-for-a-school-nurse-to-use","title":"Is there a cheat sheet for a school nurse to use?","text":"

Sure, you can give this one a try. School nurse's cheat sheet download

"},{"location":"faqs/loop-faqs/#how-long-does-it-take-to-build-loop","title":"How long does it take to build Loop?","text":"

The answer is varied, but a few hours from start to finish, depending on where you are starting and how comfortable you are with your computer.

Start at the Requirements Overview to decide which build method you wish to use. Each method starts with an overview page.

Once you choose your method, you can break the required steps into shorter bits of effort.

  • The Browser Build method has suggested breakpoints as you work through configuring for the first time
  • The Mac Build method is broken into different pages for steps needed for the Mac and the actual build process
"},{"location":"faqs/loop-faqs/#does-the-loop-app-cost-money","title":"Does the Loop app cost money?","text":"

Yes, there are some costs, beyond the obvious costs of owning a pump and CGM.

  • If you have a pump that requires a RileyLink Compatible Device, expect to spend $150 each (or find a used one). You should have two, one as a spare.
  • Most people use a paid Apple Developer Account ($99/year)
    • With a paid developer account, you can build using the Build with Browser; no Mac required
  • If you build on a Mac using Xcode Build with Mac, you need a Mac or a PC with Intel chips on which you include a virtual Mac
    • The Mac must be kept up to date with recent operating system
    • The Xcode app (from from Apple) must also be updated regular

There are no other costs, ongoing or initial, to use the Loop app beyond what you already pay for your CGM, pump supplies and insulin.

"},{"location":"faqs/loop-faqs/#rileylink-options","title":"RileyLink Options","text":"

This is not required for DASH users.

There are several options for RileyLink Compatible Devices at this time. They typically cost around $150. This is a one-time cost and the devices should last for years (unless it goes swimming, goes through the wash, gets run over by a car, etc.). It's fine to buy one device and make sure you want to Loop, but if you can afford it, go on and get two or get two different kinds. Once you Loop, you'll want a backup.

Many used devices are available in the community. You may find posts for resale on this Facebook Group Looping in a time of covid. This is a private FB group where you must agree to the rules.

Posts offering to buy or sell items in the support FB groups like The Looped Group, Loop and Learn or Little Loopers will be immediately taken down, or you will be directed to the appropriate location and comments will be turned off. FB can shut down groups without warning if they detect sales and the support groups are too important to risk.

"},{"location":"faqs/loop-faqs/#free-developer-account-options","title":"Free Developer Account Options","text":"

The Apple Developer License can be done for free, however, you will have to rebuild your Loop app every 7 days and you must use a computer with Xcode, Build with Mac. That could get very tedious. The $99 annual Apple Developer program enrollment is an excellent investment.

"},{"location":"faqs/loop-faqs/#do-i-need-to-own-my-own-apple-computer","title":"Do I need to own my own Apple computer?","text":"

You no longer need to own an Apple computer - see Build with Browser.

If you chose Build with Mac, then you still don't have to own an Apple computer, but you do need to at least borrow one - or you can build using a virtual Mac if you have a PC with Intel chips (see next section).

If you are borrowing an Apple computer, look at the required minimum settings associated with your iPhone Compatible Computer and Xcode Version. It would be really good to have the longer-term ability to borrow that computer again for updating Loop later when needed.

"},{"location":"faqs/loop-faqs/#can-i-use-a-pc-or-windows-computer-to-build","title":"Can I use a PC or Windows computer to build?","text":"

You can build the Loop app using just a browser on any device: Build with Browser.

If you want to use Build with Mac, there is a hacked way of installing macOS on a Windows computer called a Virtual Machine. This link provides some helpful information. This Virtual Machine method will not work on PCs that have AMD processors, only Intel. Double-check that your computer uses an Intel processor before attempting the virtual machine method. If you want to try this, there are mentors on The Looped Facebook Group who can assist.

"},{"location":"faqs/loop-faqs/#how-often-do-i-need-to-get-on-the-computer-for-loop","title":"How often do I need to get on the computer for Loop?","text":"

When you use the Browser Build method, you need to access a browser at least once every 90 days to Update with Browser. This is simple enough to do that you can do the steps on your phone in just a few minutes. Several people are already working on automated methods so that won't be required, but a manual Build Actions step is required for now.

When you use Build with Mac: the short answer is (1) when you first build and (2) once per year minimum after that. (If you decide to use a free Apple Developer Account, you will need to get on the computer every 7 days.)

Loop code is updated periodically to include new features and bug fixes. When those updates are released, you'll need access to a browser or an Apple computer again to update your Loop app.

Loop updates are not available through the iPhone's app store...instead you do the app update yourself

  • If using Browser build method: use this link: Update with Browser
  • If using build with Mac method: use this link: update instructions

In general, there are updates to the Loop app released a few times a year - these can occur more frequently after a major release.

"},{"location":"faqs/loop-faqs/#will-i-need-to-build-a-new-loop-app-if-i-switch-between-medtronic-and-omnipod","title":"Will I need to build a new Loop app if I switch between Medtronic and Omnipod?","text":"

No. The Loop app lets you move between different pump types from within the same Loop app. See Change Pump Type.

"},{"location":"faqs/loop-faqs/#can-i-use-my-apple-developer-account-to-build-for-others","title":"Can I use my Apple Developer account to build for others?","text":"

If there is more than one Looper in the family, you only need to have one Apple Developer ID and only one annual payment. The developer must be an adult.

  • With the Build with Browser method, you just add each Looper to your TestFlight test group and they get updates whenever you Build a new version on GitHub.

  • With the Build with Mac method, you just plug into your computer each phone on which you want to build the Loop app. (New Xcode and newer iOS phones allow you to build across WiFi after the initial connection with Xcode.)

It's a good idea to let someone else in the family know how to build and have access to your Apple password (and for Browser Build, your GitHub password) in case you're out of town. It's also a good idea to build the Loop app on a backup phone especially for travel.

The Apple Developer ID and the Apple ID are two different things. PLEASE read this: Loopers Need Their Own Apple ID.

"},{"location":"faqs/loop-faqs/#what-happens-when-i-switch-apple-developer-id","title":"What happens when I switch Apple Developer ID?","text":"

The Loop app on the phone is different if the build uses a different Apple Developer ID from the one currently on the phone. So if the Apple Developer ID used for a new Loop build is different from the one used for the existing Loop app, there will be two Loop apps on the phone. The Looper will have to on-board the new app, enter all the settings again and delete the old app.

"},{"location":"faqs/loop-faqs/#can-i-use-someone-elses-apple-developer-account","title":"Can I use someone else's Apple Developer account?","text":"

It's best that you build your own Loop app using your own Apple Developer ID.

One developer account can only be \"linked\" to a limited number of devices. So one person \"loaning out\" their developer license to a lot of people will quickly exceed the number of allowed devices. In those cases, that person will be told they need to revoke the certificates on some devices (essentially dropping old ones to make room for new ones). If they revoke your device certificate (and they can do that without you knowing through their developer portal), your Loop app will immediately stop working and not even open.

Your Loop app will also die immediately if their developer account is not renewed or expires.

Moral of the story, out of all the ways to save money...borrowing someone's developer account is not a good place to save money. You don't want your Loop app to suddenly stop working.

"},{"location":"faqs/loop-faqs/#how-can-i-find-a-compatible-pump-supplies","title":"How can I find a compatible pump? supplies?","text":"

You can use Omnipod DASH and Eros pumps with the Loop app. You do not need the Omnipod Personal Diabetes Manager (PDM), just the pod supplies. Your insurance or pharmacy coverage may cover some of the cost. See Which pods work with the Loop app? for more details.

There is a whole page with detailed information about Medtronic pumps; how to find them, how to find supplies, and assessing whether your Medtronic pump is compatible. Please check out that page for more info.

Some Looping equipment can be found on this Facebook Group Looping in a time of covid. This is a private FB group where you must agree to the rules.

"},{"location":"faqs/loop-faqs/#can-i-pay-someone-else-to-do-build-the-app-for-me","title":"Can I pay someone else to do build the app for me?","text":"

We do not know whether someone who builds the app for you incurs legal responsibility if something goes wrong while you are using a version they built for you.

There are a few companies that provide the Loop app as a service.

Best Practice: Learn to Build

You are strongly encouraged to build the Loop app for yourself.

  • No links to providers who build the Loop app as a service are found in LoopDocs
  • If you choose to use such a service, before you begin, you should:
    • Read all of LoopDocs
    • Know how to Set up, Operate and Troubleshoot Loop
    • These steps are important for your safety
"},{"location":"faqs/loop-faqs/#what-if-i-lose-my-rileylink-compatible-device","title":"What if I lose my RileyLink Compatible Device?","text":"

For Medtronic users, you simply go back to old school pump use until you get a new RileyLink compatible device. You can either let your temp basal finish by itself (30 minutes or less) or cancel the temp basal on the pump's menu. For bolusing, you'd go back to using the pump's bolus commands. When you get a device (either finding your old one or getting your backup device out) and the Loop app running again, you'll want to do one thing. Enter in any carbs to the Loop app that you may have eaten in the recent past that could still be affecting blood glucose. While the Loop app will read whatever insulin deliveries had happened while the RileyLink compatible device was missing, it will not read any carbs you entered into the pump...so make sure to add those to the Loop app and backdate them to the time they were eaten. That will help make the transition back to closed loop smoother.

For Pod users, your Pod will finish any currently running temporary basal rate (maximum of 30 minutes) and then revert back to your scheduled basal rate. Without a RileyLink compatible device, you will be receiving normal basals, but will need to pull out pens/syringe for boluses. If you have a backup device, you can simply connect to the new device on the same Loop app and it will work with the existing pod session. If you don't have a backup device, you'll have to remove the pod and start a new pod paired with your PDM until you get a new device.

"},{"location":"faqs/loop-faqs/#what-if-i-lose-or-get-a-new-iphone","title":"What if I lose or get a new iPhone?","text":"

If you lose your phone - follow the same dosing protocol as if you lost your rileylink.

When you get a new iPhone, you can plan ahead. There's a whole FAQs page about transferring your Loop information to a new phone. New Phone.

"},{"location":"faqs/loop-faqs/#what-about-other-pumps-when-will-they-loop","title":"What about other pumps? When will they Loop?","text":"

Hey now...let's be grateful for what we have first. The ability to use the Loop app is the result of tremendous amounts of effort, time, and sacrifice by volunteers. Cracking the pumps for the Loop app use is a large undertaking. If and when another set of people spend a large amount of time figuring out other pumps, then they could conceivably be added to Loop. But you don't need to let us know that you'd love to see more pumps compatible with Loop. There is just an awful lot of work that needs to happen and it is neither quick nor easy.

  • Tandem pumps are not compatible
  • Omnipod DASH pods are compatible
  • Omnipod 5 pods are not compatible
  • Newer Medtronic pumps are not compatible
"},{"location":"faqs/loop-faqs/#can-i-have-more-than-one-loop-app-on-a-phone","title":"Can I have more than one Loop app on a phone?","text":"

Yes, this is technically possible. You can have multiple Loop apps built onto the same iPhone. However, having multiple Loop apps on a single phone may lead to unexpected conflicts that can negatively affect your Loop's ability to stay green (keep looping). Additionally, your Pod will only work on one Loop app at a time anyways. So for smooth looping, just keep one Loop app on any phone for looping use.

"},{"location":"faqs/loop-faqs/#will-i-be-able-to-the-loop-app-on-a-plane-or-in-the-mountains","title":"Will I be able to the Loop app on a plane? Or in the mountains?","text":"

Yes. The Loop app does not require internet or cell coverage to work. So long as the Loop user has Bluetooth enabled on the iPhone, then the CGM and DASH pod (or RileyLink for Eros or Medtronic pumps) will still be able to do their work with the Loop app and your pump/Pod.

One exception - if you've chosen to use a CGM source that does require the internet, you will need to have cell or internet coverage. This ability is provided as a service to folks who cannot get their CGM data any other way. It is also a convenience for people testing the code.

"},{"location":"faqs/loop-faqs/#what-happened-to-freeaps","title":"What happened to FreeAPS?","text":"

FreeAPS hasn't really had an owner to develop it for several years, but many depended on it. Because of that, the Loop and Learn team kept it on life-support. It was updated in early 2023 to include DASH, but that was the last improvement. It is strongly recommended people switch to Loop 3 or iAPS. Do not use an application without an owner.

Many features people used with FreeAPS are now included in Loop 3 or can be added with customization. The dev branch has Libre support, see Build Loop Dev.

The addition of customizations has been simplified.

  • If you build with a browser, refer to Customize with Browser
  • If you build with a Mac, refer to Customize with Mac

Please do not blindly apply customizations. First read the documentation provided at the links above carefully.

"},{"location":"faqs/new-phone/","title":"New Phone Tips","text":""},{"location":"faqs/new-phone/#overview","title":"Overview","text":"

Time Estimate

At least a few hours.

You can choose to keep Looping on the old phone and swap later. Most vendors give you more than a week to turn in your old device for credit.

Phone Transition Overview - Detailed steps below

Don't start right before a meal:

  • Choose a time when Loop is stable and won't need much attention

Keep your old phone (if you can, connected to WiFi) and use it for the Loop app:

  • Make sure Apple Health from the old phone is uploading to the iCloud
  • If you are using the old phone with your Loop app:
    • Keep the old phone connected to WiFi when convenient
      • The Loop app maintains a 7-day database on the phone and will upload when connected
    • You want the Apple Health records created by the Loop app on the old phone to transfer via the iCloud to the new phone

Two methods to transfer your phone information (plan for 1 hour, may be faster):

  1. Do direct phone-to-phone transfer
    • You will not be able to use your old or new phone during the transfer
    • Both phones need to stay close to each other and on the same WiFi network
  2. Use iCloud backup from old phone to transfer information to the new phone
    • You will not be able to use your new phone during the transfer

What happens after you transfer your phone information:

  • Use your new phone for everything except the Loop app and your CGM app
  • You can keep using your old phone to control your pump and read your CGM until you are ready to switch to the new phone
  • The new phone has the Loop records up until the time the transfer started
    • If you change a pod on the old phone after the transfer
      • Plan to deactivate your pod on the old phone and pair the next pod on the new phone
    • If you change Dexcom on the old phone after the transfer
      • On the new phone, you will need to enter the new Transmitter number (G6) or wait for G7 to automatically connect
    • Glucose, Insulin and Carbohydrate records created on the old phone, after the transfer, will be transferred to the new phone via Apple Health - but this may be slow
  • Plan to be Open Loop when you decide to start using the Loop app on the new phone - the Glucose, Insulin and Carbohydrate records found on the old phone that occurred after the transfer begins will not be included in the Loop records sent to the new phone

When ready to start using the new phone to control your app:

  • First turn off Bluetooth on the old phone
  • Review the IOB, COB and glucose trend on the old phone - that determines how long you need to run Open Loop on the new phone
  • Then build Loop on the new phone
    • Browser Build: Open TestFlight and Install Loop
      • The TestFlight records were transferred to your new phone so no need to redeem a code
    • Mac Build: Plug the new phone into your computer
      • If you recently built to your old phone, you can use the same download - otherwise, you need to Download Loop
      • Your new phone will have the same name as your old phone - might want to change the display names so the two phones are different so you don't get confused in Xcode
      • You will have to trust your computer on your new phone (and watch)
      • You will need to register your new phone (you can do this with Xcode)
      • You may need to enable Developer Mode if it is not already on
      • If you have trouble building, you should try to reboot phone, watch, quit Xcode, restart computer, delete old provisioning profiles and then ask for help

Plan to stay in Open Loop until all Glucose, Insulin and Carbohydrate Apple Health records transfer:

  • This can take hours
  • Loop will pick up the missing records from Apple Health for insulin and glucose (but not carbohydrates)
    • If you upload to Nightscout or Tidepool, the carbohydrates entered with the old phone should be already uploaded so your record will be complete
  • If you have small IOB and COB and glucose is flat, you can probably enable closed loop on the new phone without waiting for the missing records
  • If there are carbs entered on old phone that are still active, plan on a longer time open loop when you transition to the new phone

Plan Ahead

  • Choose when to change from old phone to new phone
    • Stable glucose
    • No meals planned
  • Plan to use Open Loop after the transfer to allow recent Health records to transfer via iCloud
"},{"location":"faqs/new-phone/#steps-required","title":"Steps Required","text":"

Changing phones means you have to rebuild the Loop app onto the new phone. When you transfer information from your old phone to your new one, all your\u00a0Loop\u00a0information is included and the\u00a0Loop\u00a0icon will appear, but the app will not open until you install\u00a0Loop\u00a0from either TestFlight or Mac with Xcode.

The records on the new phone are from the time you started the transfer from the old phone to the new phone. The more recent records are transferred via Apple Health. You may want to adjust carbs after the transfer because those are not read by the Loop app. But if you enter them again and you are uploading to Nightscout or Tidepool - they will show up twice. Best to have COB and IOB close to zero when you start using your new phone.

Some people don't have access to their old phone. There are instructions for handling that on this page. It makes the whole process more stressful, but remember, pods continue to deliver basal rate and Medtronic pumps can be controlled on the pump itself. Use your backup plan until you can get\u00a0Loop\u00a0running on a new phone.

"},{"location":"faqs/new-phone/#forced-ios-update","title":"Forced iOS Update","text":"

When you change phones, Apple will force you to the latest iOS version available for your new phone.

"},{"location":"faqs/new-phone/#prepare-before-upgrade","title":"Prepare Before Upgrade","text":"

If you are using Dexcom, record the transmitter or sensor number in case it doesn't transfer

  • G6: Record the Transmitter number (found in the G6 and the Loop app)
  • G7: Record the 4-digit Sensor number (pairing code) found in the G7 app under Connections, Sensor

If you still have your old phone, you can prepare before switching to the new phone.

  • Be sure to record your\u00a0Loop\u00a0Settings (screenshots work well)

If you don't have your old phone, hopefully you have an iCloud backup and can use that to transfer your information to your new phone.

Keep the Old Phone Until the Loop app is Working on the New One

Even if you plan to turn your old phone in for a rebate, you can ask to keep the old one for a week or two. Most vendors will agree to this.

Update your old phone to the latest iOS the hardware supports - this simplifies the automatic transfer process Apple provides to move all your data and apps from your old phone to your new phone.

New Phone Checklist for Build with Browser

  • The Loop app will install from TestFlight onto the most recent iOS
  • If a new version is available, we recommend updating and building to the latest, see Update with Browser

New Phone Checklist for Build with Mac

  • Are your Mac and Xcode versions compatible with the latest iOS version?
  • If not, you need to install the correct versions on your Mac
  • If you cannot do that, you should consider Build with Browser
"},{"location":"faqs/new-phone/#different-developer-id","title":"Different Developer ID","text":"

Different Developer ID

If you need to build the Loop app with a different developer ID on the new phone, the settings and pump information will not transfer.

  • The new app that you build with the new Developer ID will open and you can Onboard
  • The old app will still be on the phone: find it and delete it to avoid confusion
"},{"location":"faqs/new-phone/#procure-a-new-phone","title":"Procure a New Phone","text":"
  1. Procure the new phone and keep the old one (if possible)
    • Use the Old Phone until it is convenient to switch to the new phone
  2. Transfer your information to your new phone. Your options are:
    1. Use both devices with Quick Start to transfer from the old to the new phone
    2. Use an iCloud back-up for the transfer
    3. Let the new phone vendor help you
"},{"location":"faqs/new-phone/#use-the-old-phone-until-ready","title":"Use the Old Phone until Ready","text":"

If you cannot keep the old phone, or it is not available, then skip ahead to the Use the New Phone.

  • You can use the old phone to\u00a0Loop\u00a0until you are ready to switch
  • Use WiFi with the old phone and use your new phone as a cellular hot-spot as needed
  • Keep the CGM on the old phone
    • If using Dexcom, use the Dexcom app on the old phone
    • If using Libre, the Libre CGM is connected to the old phone
"},{"location":"faqs/new-phone/#use-the-new-phone","title":"Use the New Phone","text":""},{"location":"faqs/new-phone/#install-the-loop-app","title":"Install the Loop App","text":"

It is easier if you transfer information from the old phone to the new phone before you install and open\u00a0Loop\u00a0on the new phone. If this is not possible, then you will do the normal Onboarding for a new\u00a0Loop\u00a0app.

  1. When you transfer information from your old phone to your new phone, all the\u00a0Loop\u00a0settings files get copied to the new device including information about the pod
    • If the timing works, you can keep the pod when you switch to using the new phone for\u00a0Loop\u00a0after the information transfer and before changing pods with the old phone
    • If this is not possible, you will need to start a new pod with the new phone
    • Medtronic users will have all their information transferred but will only have one phone connected to the RileyLink
  2. Install\u00a0Loop\u00a0on the new phone (all your settings should be there)
    • Install from TestFlightor
    • Build using Mac
  3. As soon as you install the Loop app on the new phone, go ahead and disable Closed Loop.
    • Keep Closed Loop disabled until you complete the full transfer and checkout.
"},{"location":"faqs/new-phone/#install-from-testflight","title":"Install from TestFlight","text":"
  • Open TestFlight app on new phone
  • Install the app on your new phone from TestFlight
  • If necessary, review TestFlight for a Child
"},{"location":"faqs/new-phone/#build-using-mac","title":"Build using Mac","text":"

Preparatory steps:

  • Your new phone will have the same name as your old phone - might want to change the display names so the two phones are different so you don't get confused in Xcode
  • If the new phone does not have Developer Mode enabled, wait until you plug it in to try to configure it

When building:

  • Open Xcode
    • Use the same build as you used for the old phone if you built recently
    • Otherwise, do a fresh download and let the BuildSelectScript open Xcode for you
  • Plug in the new phone to the computer
  • You will have to trust the computer on the new phone (and watch)
  • There should be a modal pop-up in Xcode asking if you want to register the new phone
  • You may need to enable Developer Mode if it is not already on
  • Build the app on the new phone

If you have trouble finding the new phone in Xcode or trouble building, you should try to reboot phone, watch, quit Xcode, restart computer, delete old provisioning profiles and then ask for help

"},{"location":"faqs/new-phone/#prepare-to-change-phone-used-for-the-loop-app","title":"Prepare to Change Phone used for the Loop App","text":"

On old phone (if available):

  1. Loop\u00a0app, turn off the slider for the RileyLink if using Medtronic or Eros Pods
    • Do not delete the pump; if using pods, this cannot be reversed
  2. Phone Settings, Bluetooth
    • Forget the connections to the CGM (Dexcom or Libre)
    • Do not forget anything that says TWI_BOARD or NXP_BLE(this is your DASH* pod)
  3. Phone Settings, Bluetooth: Disable Bluetooth
"},{"location":"faqs/new-phone/#transfer-pump","title":"Transfer Pump","text":"

Bluetooth must be off on the old phone.

  • On the new phone, examine the pump status
    • If everything transfered, your new phone should be communicating with your pump
    • If using a RileyLink device and it doesn't show as connected, try a power cycle on the device
    • If you need to start a new pod, do it now
  • If necessary, delete the pump type and add it back
"},{"location":"faqs/new-phone/#transfer-cgm","title":"Transfer CGM","text":"

It is now time to transfer the CGM to the new phone.

  • Dexcom CGM
  • Libre CGM
"},{"location":"faqs/new-phone/#dexcom-cgm","title":"Dexcom CGM","text":"

The Dexcom app might have transferred successfully, but it\u2019s not a bad idea to install that fresh from the App Store on the new phone. Doing so may be required.

  • You need your Dexcom G6 Transmitter ID or G7 4-digit pairing code (Sensor number)
  • On the new phone, in\u00a0Loop, delete Dexcom as your CGM so you can pair the new phone to the Dexcom app

  • On the new phone, open the Dexcom app and pair to the transmitter (G5, G6 or One) or enter the four-digit code for G7

    • You can keep using your current sensor session
    • You indicate you are starting a new sensor (it\u2019s not really new)
      • G5, G6 or ONE, enter transmitter ID
        • If you enter no code, you will be warned that calibrations are required (don't worry)
        • When the app pairs with the tranmistter, it picks up the current session, and calibrations are not required
      • G7, enter 4-digit code if asked, otherwise just wait for it to connect
    • Within 5 to 10 minutes, Dexcom app should read the current session and keep going

  • Wait for Dexcom to connect

  • On new phone, add the CGM to\u00a0Loop
"},{"location":"faqs/new-phone/#librecgm","title":"Libre CGM","text":"

Placeholder for\u00a0Libre CGM instructions. Suggested procedures from the community are encouraged.

  • On the new phone, in\u00a0Loop, delete\u00a0Libre\u00a0as your CGM
  • On the new phone, in\u00a0Loop, add\u00a0Libre\u00a0as your CGM
  • Wait for\u00a0Libre\u00a0to connect
"},{"location":"faqs/new-phone/#check-out-the-transfer","title":"Check out the Transfer","text":"

  1. Stay in Open Loop (closed loop disabled) until you complete the full transfer and checkout.

    Check Every Setting

    • Make sure all the basal, ISF, CR, Insulin Selection and ranges are correct
    • Check Dosing Strategy selection
    • Check permissions and notification settings
    • Check Focus mode settings - make sure\u00a0Loop\u00a0and CGM apps have permission for all Focus modes

  2. Do a manual bolus of the smallest possible amount to make sure\u00a0Loop\u00a0and pump are working.

  3. Monitor CGM values to ensure new readings are coming in.

  4. Check Glucose, Insulin and Carbohydrate records

    Apple Health\u00a0History

    Your Glucose, IOB and COB may not have correct history on your new phone.

    Loop\u00a0 reads from\u00a0Apple Health\u00a0and will restore Glucose and Insulin records if health is stored on iCloud and synchronized between old and new phone - but this can take a long time to synchronize

    The Loop app does not read Carbohydrates from Apple Health, so stay Open Loop if you have high COB from an entry on the old phone

    Be prepared to spend 3 to 6 hours in Open Loop.

  5. Once you are happy with the configuration of\u00a0Loop\u00a0on your new phone, your glucose is being read and your COB and IOB on the new phone is valid, then you can restore Closed Loop.

"},{"location":"faqs/new-phone/#old-phone","title":"Old Phone","text":"

Once you are using\u00a0Loop\u00a0on your new phone, you can delete the pump from the old phone.

  • On the old phone, in the Loop app:
    • Delete the pump
  • If using DASH pods with direct Bluetooth connection to your phone
    • Go into the old phone Settings -> Bluetooth and turn it back on
    • Forget the pod; it will show up as TWI_BOARD or NXP_BLE

You can either keep the Old Phone as a backup, reset it and turn it in for credit or give it to some deserving individual.

"},{"location":"faqs/omnipod-faqs/","title":"Omnipod FAQs","text":""},{"location":"faqs/omnipod-faqs/#which-pods-work-with-the-loop-app","title":"Which pods work with the Loop app?","text":"

You can use DASH and Eros Omnipod pods with the Loop app. You cannot use Omnipod 5 pods.

You do not need the Omnipod Personal Diabetes Manager (PDM), just the pod supplies. Your insurance or pharmacy coverage may cover some of the cost.

Alternative Names for Omnipod Pods

All three types of pods can be packaged five to a box, don't let the 5-pack indication confuse you.

  • Eros pods are also known as Classic or UST400

    • The Reference number on the boxes should be similar to POD-ZXP425
    • They have a clear needle cap
    • Pharmacy sites sometimes may refer to the Eros pods as Gen 3 but they are the same exact pods

  • DASH pods have DASH in the name

    • The Reference number on the box should be similar to POD-BLE-P1-525 (note the P)
    • They have a blue needle cap

  • Omnipod 5 pods have 5 in the name

    • The Reference number on the box should be similar to POD-BLE-H1-525 (note the H)
    • They have a clear needle cap

DASH pumps communicate with the phone via Bluetooth so they do not require a RileyLink compatible device.

"},{"location":"faqs/omnipod-faqs/#what-about-tidepool-loop","title":"What about Tidepool Loop?","text":"

Tidepool Loop was approved by the FDA in Jan 2023, but at the current time, there are no announced pump or CGM partners. What does this mean?

Tidepool Loop, cleared by the FDA, is the first:

  • App that provides automated insulin dosing and is configured to be fully interoperable with pump and CGM partners
  • App that originated as a patient-led initiative

With this approval, there is now an FDA-approved pathway for independent selection of an app, a pump, and a CGM. Stay tuned for updates at https://tidepool.org/tidepool-loop.

"},{"location":"faqs/omnipod-faqs/#do-i-still-need-a-pdm-with-omnipod-loop","title":"Do I still need a PDM with Omnipod Loop?","text":"

No, pods are monogamous little creatures. They will pair with only one device at a time for safety reasons...so a pod is either paired with a PDM or your Loop app on your iPhone. In other words, your PDM can stay in the diabetes closet while you are Looping. You cannot use the PDM for a pod that has been activated with the Loop app. That doesn't mean you should get rid of your PDM if you have one. Instead, keep it for backup situations if you lose your phone. See below for what to do if you lose your phone or RileyLink.

"},{"location":"faqs/omnipod-faqs/#can-i-cancel-a-bolus","title":"Can I cancel a bolus?","text":"

Yes, you can cancel a bolus in progress. In fact, because it is very easy to cancel, make sure your phone is locked prior to being put away to avoid inadvertently cancelling a bolus. (This behavior is very similar to the Insulet PDM - which also needs to be locked once a bolus has started.)

As soon as a bolus is initiated, look at your phone in portrait orientation. You will see a bolus message indicating the progress of the bolus. This message is highlighted with a red rectangle in the graphic below. If you tap on this part of the display, the bolus is immediately cancelled.

  • The displayed amount Bolused is based on the time since the bolus was started
  • The Loop app will present that graphic for the entire time the bolus is in progress with the delivery amount updated based on time
  • Once the bolus completes, the Loop app updates the actual delivery amount based on communication with the pod (taking into account any interruption of that bolus from the user or a pod error)

"},{"location":"faqs/omnipod-faqs/#can-i-cancel-a-temp-basal","title":"Can I cancel a temp basal?","text":""},{"location":"faqs/omnipod-faqs/#cancel-temp-basal-with-the-loop-app","title":"Cancel Temp Basal with the Loop app","text":"

With Loop 3, disabling the setting for Closed-Loop immediately restores the basal rate on the pump to the scheduled basal rate, which effectively cancels the temp basal.

You can tap on disable Closed-Loop and then immediately tap on enable Closed-Loop if all you want to do is cancel the current temp basal. If you do restore Closed-Loop, then Loop will resume automatic insulin delivery adjustments within 5 minutes.

Bolus in progress

Even if a bolus is in progress, you can still switch to Open-Loop and restore scheduled basal. The current bolus continues unless you separately cancel the bolus.

"},{"location":"faqs/omnipod-faqs/#cancel-temp-basal-with-loop-v22x","title":"Cancel Temp Basal with Loop v2.2.x","text":"

If you are running Loop v2.2.x, the method for canceling a temp basal is to suspend the pump and then resume delivery. This also interrupts any bolus that might be in progress.

Be sure to follow the suspend with the resume command. Otherwise, all insulin delivery is stopped and remains stopped until the user either clicks on the \"Tap to Resume\" command from the main screen or the \"resume delivery\" command accessed in the pump settings display. The resume insulin delivery command returns insulin delivery to your scheduled basal rate.

If a bolus was interrupted, the bolus will not resume.

As long as you are in closed-loop mode, the Loop app will resume automatic insulin delivery adjustments within 5 minutes.

"},{"location":"faqs/omnipod-faqs/#can-i-set-my-own-temp-basal-on-loop","title":"Can I set my own temp basal on Loop?","text":"

With version 3, the Loop app provides a Manual Temp Basal feature.

"},{"location":"faqs/omnipod-faqs/#what-if-i-lose-my-phone-or-rileylink","title":"What if I lose my phone or RileyLink?","text":"

For pod users, your pod will finish any currently running temporary basal rate and then revert back to your scheduled basal rate. Without a phone or RileyLink, however, you will not be able to affect any pod use; no basal change, suspend, cancel, or bolus. To do anything other than let basals continue, you will need to take action depending on the situation.

  • Lost RileyLink only: You can replace your missing RileyLink with one from your backup supplies. No problem to switch out to a different Rileylink mid-pod session. If you don't have a backup RileyLink to use, then you will need to remove the pod and put on a new pod paired with your PDM until you can get a new RileyLink. In the interim, you are still getting basal from the pod. If you are taking bolus insulin via injection, just add it to Apple Health under insulin. The Loop app will read it and keep making predictions for you. Once you inject, then add the carbs that go with that injection into Loop.

  • Lost iPhone only: You will need to remove the pod and put on a new pod paired with your PDM or a backup phone (with a copy of the Loop app on it). You cannot use the old pod with a new device. In the interim, the pod will continue to deliver your scheduled basal until the pod reaches 80 hours. See New Phone for more information.

  • Lost both RileyLink and phone: You're having a really bad day. You'll need a hug and to follow the same directions as if you lost the phone as shown in the bullet above.

"},{"location":"faqs/omnipod-faqs/#is-there-an-increase-in-pod-failures-on-loop","title":"Is there an increase in pod failures on Loop?","text":"

There is more communication between the pod and the controller (your Loop phone) than is typical with the PDM (Insulet provided controller). This increases the load on the pod battery. Most people have no increase in pod failures, but there are steps to take to limit \"extra pod battery use\". Every time the Loop app requests an update of the pod state or issues a command (bolus, basal schedule, temp basal), messages are exchanged with the pod.

  • Set your correction range to be 10 to 20 mg/dL (0.5 to 1.1 mmol/L) instead of a single number
    • The number of commands will be reduced
  • An earlier release of Loop, version 3.0.0, pinged the pods more frequently to refresh status more quickly when the phone was unlocked and the Loop app was in the foreground
    • This did cause more failures and was modified for version 3.2.x.
  • The pod state is updated every 3 minutes for DASH and every 5 minutes for Eros
  • If uncertain communications are detected such that the Loop app cannot determine if a dosing command sent to the pod was actually received, the app will try once a minute to get a response
    • The combination of Eros pods with a RileyLink device with poor signal leading to uncertain comms may cause excessive battery use and contribute to pod faults
"},{"location":"faqs/omnipod-faqs/#what-do-i-do-if-a-pod-fails-to-pair","title":"What do I do if a pod fails to pair?","text":"

If you get a pod that is failing to pair, please see this page for steps on how to fix the problem. Follow these steps before filling and trying another pod. If the pod is not screaming, you can probably recover it.

"},{"location":"faqs/omnipod-faqs/#what-do-you-do-to-stop-a-screaming-pod","title":"What do you do to stop a screaming pod?","text":"

Screaming pods indicate the pod is out of insulin or out of time (80 hours) or there has been a critical pod fault. In all these cases, there is no more delivery of insulin.

The first step is to use your phone to Deactivate the pod. You may need to go to the pod settings and tap on the Replace Pod row or the app may take you to the screen with a Deactivate button directly. This only works if the app is able to communicate with the pod. Sometimes this is not possible. After you attempt to deactivate two times, the app will \"discard\" the pod as active if communication fails and enable you to pair a new pod. But you still need to make that noise go away.

If you are not successful at deactivating a pod and you've tried the steps at Reset-Loop-to-Pump-Communications, make sure the old pod is removed from the area before trying to connect a new pod. (Placing it in a microwave temporarily prevents the phone from detecting that pod.) The paperclip trick (next paragraph) only breaks the sound connection, the pod electronics is still active.

Once you have removed the screaming pod, it can be silenced using a paperclip. Simply put the paperclip in the small hole that is on the bottom (the side opposite where the cannula is) of the pod as shown. Push the paperclip in until you hear a little click, that click is breaking the circuit that connects the speaker to the electronics.

"},{"location":"faqs/overview-faqs/","title":"FAQs Overview","text":""},{"location":"faqs/overview-faqs/#frequently-asked-questions-faqs-overview","title":"Frequently Asked Questions (FAQs) Overview","text":"

The FAQs tab of LoopDocs contains pages with safety tips, frequently asked questions and the Glossary.

Map to this section:

  • Safety Tips
  • Loop FAQs
  • Time FAQs
  • Omnipod FAQs
  • CGM FAQs
  • Update/Rebuild Loop FAQs
    • What if I'm Changing Phones
  • New Phone Tips
  • RileyLink FAQs
  • Algorithm FAQs
  • Apple Health FAQs
  • Glossary
"},{"location":"faqs/rileylink-faqs/","title":"RileyLink FAQs","text":""},{"location":"faqs/rileylink-faqs/#rileylink-compatible-device-faqs","title":"RileyLink Compatible Device FAQs","text":"

A RileyLink compatible device is required to use the Loop app with Medtronic pumps or Omnipod Eros pods.

A rileylink is not required with DASH pods.

The device uses the RileyLink protocol to communicate information to/from your pump by radio communications and to/from your iPhone using Bluetooth. You will need the device within range of your phone and pump so that these communications can happen. Put it in a purse, pocket, SPIbelt. Clip it to a backpack, belt, or bra...but please do bring it with you..

Purchase information for these devices is found in RileyLink Compatible Devices

"},{"location":"faqs/rileylink-faqs/#adding-or-changing-rileylink","title":"Adding or Changing RileyLink","text":"

You can add or change the RileyLink compatible device in use without affecting the pump that is connected to the Loop app. You can even have more than one connected, although only one will be used at a time.

If you are connecting to a new Medtronic pump or switching between Medtronic and Omnipod, please follow the Modify Pump instructions under Set up App.

Change Connected Devices:

  • Open the Pump Menu for your connected pump
  • Scroll down to the DEVICES section
  • There should already be at least one device listed
  • Power on your new device and look for a new device to appear in the list
  • If this device has never been connected before, it might appear as a blank line with a slider beside it - if so, slide the slider to turn it green and then the device name should appear
  • You can now turn sliders on or off to select which device you want to use with your connected pump
  • Refer to the RileyLink Menu for instructions on personalizing your device name

"},{"location":"faqs/rileylink-faqs/#using-more-than-one-device","title":"Using More Than One Device","text":"

You can have more than one RileyLink compatible device turned on and connected. Loop only uses one device at a time. Remember - if you do have two devices in use, make sure they are both charged (or have batteries).

Example of using more than one device:

  • One device is kept in the bedroom and another in the kitchen
  • Loop will automatically switch to the device that is within Bluetooth range at the next cycle (Loop stays green)
  • Caveats:
    • The phone needs to be close enough to get the CGM update
    • Do NOT forget to pick up one RileyLink device and take it with you when you leave the house
"},{"location":"faqs/rileylink-faqs/#communications","title":"Communications","text":"

All the RileyLink compatible devices communicate with the pump through radio frequency communications and with the phone through Bluetooth.

Bluetooth (BT) Troubleshooting

If your iPhone has BT issues, your Loop will have failures. There have been reports of BT audio devices (such as BT pairings in your car or home audio BT speakers) interfering with the Loop. If you are finding Loop failures frequently happening at a particular location, you may try to troubleshoot if there are BT problems in the area.

Your BT signal strength can be seen in the Loop settings, Pump settings, Device menu, on the Signal Strength line. As you move closer and further away from your phone, you can watch that number dynamically change. This line is not displaying the signal strength of your pump RF communications, just BT between the RileyLink compatible device and the phone.

You will notice the Signal Strength is a negative number and in units of dB. Remember that number line from elementary school? A signal strength of -50\u00a0dB is a stronger signal than -80\u00a0dB.

"},{"location":"faqs/rileylink-faqs/#range","title":"Range","text":"

The range at which RileyLink compatible devices will function is dependent on the environment that you are in and the specific device design. Both the OrangeLink and some sizes of the EmaLink have reported longer ranges than RileyLink (typically 10 to 20 ft) - but they still need to be \"near enough\".

What influences this distance for a given device? The biggest external influences are (1) body-blocking and (2) \"noisy\" environments. The human body is a lot of water, and water is an excellent blocker of wireless communication. So, sleeping on a pod and smothering it entirely with your body can decrease the ability of the device to communicate with the pod. Environments with a high concentration of wireless signals can also interfere with device communications and make closer proximity a benefit. Where might those kinds of situations happen? Concerts, conferences, and sporting arenas are pretty prone to interference.

Many people keep their device on the same side of their body as their pump during the day. They use a pocket, carabiner, lanyard, SPIbelt - the options are endless. What you don't want to do is put it in a blocking bag that has RFID blocking (some travel fanny packs have that).

"},{"location":"faqs/rileylink-faqs/#what-happens-if-loop-loses-communication","title":"What happens if Loop loses communication?","text":"

While you are out of the communication range for your RileyLink compatible device(s), any running temp basal will keep going until it finishes (the longest temp basal that Loop sets are for 30 minutes duration...so within 30 minutes or less your pump would go back to your regularly scheduled basal). When you come back into range of your device, Loop will pick back up within 5-10 minutes without you needing to do anything.

"},{"location":"faqs/rileylink-faqs/#are-these-devices-waterproof","title":"Are these devices waterproof?","text":"

The electronics are not waterproof but there are waterproof cases available and some have wireless charging available. Check with the manufacturer.

RileyLink Compatible Device Information

"},{"location":"faqs/rileylink-faqs/#firmware-version","title":"Firmware version","text":"

In Loop settings, tap on your pump, find your device (RileyLink or other) and tap on that menu. The figure below shows firmware specific to the RileyLink. If you have another type of device, the firmware value reported will be different. (Note - the displays for Ema, Orange and Riley have been updated to include device-specific features as shown in the RileyLink Display page. The graphic below shows the original RileyLink display.)

With RileyLink, the firmware displayed should match or be a higher version number than what is shown in the figure above, e.g., subg_rfspy 2.2/ble_rfspy 2.0. (If you are running with a very old RileyLink from pre-Aug 2018, it might be a lower number.) Check it when the device is working well and make a note of what it says. If you're having Red Loops, you might want to check firmware and connected state. Make sure, after power cycling your device, that the correct firmware is displayed AND that there are two items shown.

  • In the example above:
    • subg_rfspy 2.2 is the sub-gigahertz radio frequency firmware that talks to the insulin pump (if this does not show up, the device will talk to the phone but not the pump)
    • ble_rfspy 2.0 is the Bluetooth firmware that talks to the phone (if this is not working, you will not even see the device in the list)

HINT: You might need to quit the Loop app. (Don't just close it, actually quit.) Then do the power cycle on the RileyLink compatible device to attempt to have both sets of firmware boot up. When you restart the Loop app, it may show the correct firmware. Don't give up after one failure, try several times.

If several power cycles do not make the correct firmware show up, contact the manufacturer for assistance.

"},{"location":"faqs/rileylink-faqs/#orangelink-firmware","title":"OrangeLink Firmware","text":"

The OrangeLink devices allow the user to update the firmware on the device using an app on the phone itself (available for iPhone 7 and later devices).

  • OrangeLink Firmware Update

A number of OrangeLink Pro devices were shipped with FW2.6 and for people who already had OrangeLink devices, a version of FW2.6 was offered for download. However, this firmware did not work well with Loop (or AndroidAPS).

  • If you are having communication issues, update to the latest firmware FW3.2 using the link above
  • If you are not having communication issues, the update is optional
    • For OrangeLink (not Pro, HW version 1.0), FW2.5 or FW3.2 are OK
    • For OrangeLink Pro (HW version 1.1), FW1.0 or FW3.2 are OK
    • See link above to check if versions newer than FW3.2 have been released, LoopDocs might not have the latest information

Firmware/Hardware Labeling

Earlier versions of the OrangeLink firmware did not put the hardware (HW) version and the firmware version (FW) in the \"correct\" location to hand off to Loop for interpretation. Do not worry if you are running on any FW version 1.x or 2.x and your HW version number doesn't say 1.0 or 1.1. This has been fixed for FW versions 3.x.

"},{"location":"faqs/rileylink-faqs/#emalink-and-orangelink-features","title":"EmaLink and OrangeLink Features","text":"

Some of the features of the OrangeLink were added to the RileyLink Display with Loop 2.2.x. However, as mentioned above, the FW and HW information in some OrangeLink firmware was inconsistent in earlier versions. The consequence is that the OrangeLink Pro screen does not show the Find Device feature that many people want to use with the versions of firmware that provide good communication with Loop. The patch listed below fixes this issue.

The EmaLink features were not added with Loop 2.2.x. The patch listed below adds some EmaLink features.

"},{"location":"faqs/rileylink-faqs/#emalink-and-orangelink-patch","title":"EmaLink and OrangeLink Patch","text":"

A patch was developed to update the RileyLink screen of the Loop app that detects the OrangeLink hardware for all versions of the OrangeLink firmware and adds the battery level reporting and notification to the EmaLink screen. Click on the link below. There are detailed instructions on how to use this patch for Loop 2.2.x.

  • EmaLink and OrangeLink Patch
"},{"location":"faqs/rileylink-faqs/#rileylink-information","title":"RileyLink Information","text":"

Since the RileyLink version of the communication link device has been around the longest, some additional information about that device has been added to LoopDocs throughout the years. The rest of this page is specific just to the RileyLink device.

"},{"location":"faqs/rileylink-faqs/#rileylink-assembly","title":"RileyLink Assembly","text":"

Your RileyLink will come with the Lithium-ion Polymer (LiPo) battery disconnected and the parts not already inside the case. It will be up to you to put the RileyLink in the case and attach the battery.

Make sure the LiPo battery is well-plugged into the connection. Line up the little ridge appropriately, and push fairly firmly to get the connection tight. Poor battery cable connection can make the Loop communications fail. See photos below, for example.

Common new user errors

The most common two errors for new RileyLink owners are (1) not fully pushing in the LiPo battery cable connection and (2) failing to charge the RileyLink. Compare your LiPo battery cable with the photos; it takes a bit of oomph to push that plug fully in like the photos shown below. Remember to charge your RileyLink each night.

Loose battery cable on left. Proper battery cable on right

Finally, the board and the battery fit into the slim case fairly tightly as well. Click on the image below to watch a helpful assembly video.

"},{"location":"faqs/rileylink-faqs/#rileylink-lights","title":"RileyLink Lights","text":"

The RileyLink has several lights that you may notice from time to time. There is no 'power' light. If you suspect that your RileyLink is not being powered, try turning it off and on using the small sliding switch. You should see lights in the middle of the board flash when you do this. If they flash, that means the board has power.

  • Red light: Charging light. The red light will remain on while RileyLink is charging, and it will turn off when charging is complete. You may notice the red light turn on periodically even after charging is complete...it's just \"topping off\".

  • Green light: Bluetooth connection light. The green light will remain on while you have a BT connection with your iPhone. If that green light fails to stay on, you should troubleshoot your BT connections. Try restarting BT on your iPhone and/or turning the RileyLink off/on by its power switch.

  • Blue light: Pump communications. If you have an older firmware on your RileyLink, some of the blue lights will flash periodically as it communicates with the pump. It's just letting you know that it is busy talking and collecting info. You will also see increased blue flashes if you have \"Enabled Diagnostic LEDs\" for Medtronic users that have the RileyLinks with updated firmware (shipping since late August 2018).

A solid blue light that consistently remains lit on the board could mean one of two things:

  • A temporary issue that can be resolved by rebooting the RileyLink physically (turning the switch off/on), or

  • An electrical short or damage to the board. Sweat and moisture are most likely culprits, so try to keep case free from those environments. Don't keep RileyLink in sports bras or waistband next to skin, for example, while exercising.

If your blue light remains on despite trying a restart, it is time to pull out your backup RileyLink.

"},{"location":"faqs/rileylink-faqs/#rileylink-charging","title":"RileyLink Charging","text":"

The battery that comes with RileyLink is not charged completely when it is shipped, so be sure to charge it up before initial use. RileyLink takes about 2 hours to fully charge (the red light will turn off when fully charged, read note above about red light patterns) and should easily last at least a full day of constant Loop use. Typically, it can go into the 30-hour range without any problems. Most people charge their RileyLink each night when they are sleeping. You don't have to worry about leaving the RileyLink plugged in \"too long\" for charging. It will automatically stop charging the battery when it is fully charged.

Since the best practice is to charge your RileyLink overnight while you sleep, and the battery lasts safely over 24 hours, there is no battery level indicator for the RileyLink. The RileyLink's charge level is not viewable on Nightscout, nor within the Loop app. If you forget to charge your RileyLink overnight, you can recharge it with a portable USB battery in a pinch. A short mini-USB cable could be a good addition to a small gear bag.

"},{"location":"faqs/rileylink-faqs/#what-are-the-differences-between-the-rileylink-medtronic-and-omnipod-antennas","title":"What are the differences between the RileyLink Medtronic and Omnipod Antennas?","text":"

There are two types of antennas for RileyLinks; each antenna is optimized for the pump you are using. Otherwise they are identical. See RileyLink Compatible Devices for other devices. The OrangeLink has both antennas included in its design and can talk to either Medtronic or Omnipod. The EmaLink requires selection for type of pump.

The color of the RileyLink circuit board in the photos below is irrelevant.

"},{"location":"faqs/rileylink-faqs/#what-will-happen-if-your-rileylink-has-the-wrong-antenna","title":"What will happen if your RileyLink has the wrong antenna?","text":"

You can technically use that RileyLink with either pump on Loop. But, you will have significant frustrations and probably a lot of red loops. With mismatched antenna/pump, the device needs to be very close (think inches) and in clear line-of-sight to pump/pod. This makes everyday living (and sleeping) a bit hard. If you use the appropriate-antenna-for-your-pump device, the distances the pump/pod and RileyLink can tolerate from each other is much more \"real world\" friendly and stable. The OrangeLink contains both antennas so will work with either pump. This may be a good choice if you like to switch between Medtronic and Omnipod.

In a pinch, if you have a RileyLink that you used with a Medtronic pump and have switched to Omnipod, it might work as a backup, but you won't love it.

"},{"location":"faqs/rileylink-faqs/#how-long-will-my-rileylink-go-between-charging","title":"How long will my RileyLink go between charging?","text":"

RileyLinks can go about 30-36 hours on a single charge. There is no way to see the remaining charge level, so most people just get into the habit of charging overnight while they sleep. The actual time to fully recharge is about 1 or 2 hours; you'll know it is fully charged when the red light turns off. After a full charge, the red light will turn off and then periodically turn on for short times while it \"tops off\" while still on a charger.

"},{"location":"faqs/rileylink-faqs/#how-can-i-tell-how-much-charge-my-rileylink-has","title":"How can I tell how much charge my RileyLink has?","text":"

You can't. There is no charge level indicator. Just charge it nightly, and you won't have a problem. Full battery charge should last about 30-36 hours depending on battery health. Charging takes less than 2 hours.

"},{"location":"faqs/rileylink-faqs/#how-long-will-my-rileylink-battery-last","title":"How long will my RileyLink battery last?","text":"

Eventually, Lithium-ion Polymer (LiPo) batteries will lose charging capacity. You would want to replace if you notice the battery not lasting the full day. Many people report using their battery for more than 2 years without issue.

Be aware that if a battery is failing, it may swell. If you notice that the RileyLink battery is swollen, remove the swollen battery from your home and place in a fire-safe area and recycle it properly. Either order a new battery or pull out your spare.

After a year of use (and a year of being dropped), the antenna may no longer be securely soldered. If you are getting a lot of red loops, it might be a poor antenna connection instead of a failing battery. Check the solder joint at the antenna. The solder should be shiny and the antenna base should be firmly attached to the board.

"},{"location":"faqs/rileylink-faqs/#rileylink-battery","title":"RileyLink Battery","text":"

Keep your RileyLink and its Lithium-ion Polymer (LiPo) battery protected from damage. LiPo batteries are unsafe when damaged or punctured, so the case is an important part of safe Looping. If your battery is damaged in some way, please disconnect it immediately, and dispose of it (it should be recycled). You can order new RileyLink batteries on the GetRileyLink website

"},{"location":"faqs/rileylink-faqs/#rileylink-battery-removal","title":"RileyLink Battery Removal","text":"

To remove the LiPo battery from the RileyLink, please do so slowly and patiently. Work the battery connection side to side slowly to loosen it from the plug. Some people have reported success using small, curved needle-nose pliers such as hemostats. Others have used small flathead screwdrivers as shown in this video.

"},{"location":"faqs/safety-faqs/","title":"Safety Tips","text":""},{"location":"faqs/safety-faqs/#know-your-settings","title":"Know your settings","text":"

Do not enter settings that you are unsure of. For example, if you haven't any idea what your carb ratio is, please don't enter a wild guess. Instead, test your settings and talk to your health care provider about what your appropriate settings should be.

"},{"location":"faqs/safety-faqs/#ios-focus-notifications","title":"iOS Focus Notifications","text":"

iPhones have Focus modes to enable maximum flexibility for notifications. These modes must be configured by each user to allow important notifications from your diabetes apps.

Set up every Focus mode you use to allow glucose alerts or you will not get them.

Critical notifications, for example, urgent low from Dexcom, are enabled regardless of your Focus settings. But regular low and high glucose notifications might be suppressed. Open source apps, like the Loop app, can only be allowed to notify during a Focus mode when configured by the user.

Under iOS Settings, select Focus, then choose the Focus mode you want to adjust.

The graphic below has numbered highlights to follow along for configuring Sleep focus initially:

  1. Enable Time Sensitive Notifications (disabled by default)
  2. Tap on the + sign to add Apps that are allowed to notify in this mode
  3. Use the search feature to find apps of interest
  4. Tap on the radio button to select apps of interest, the check mark means that app will be added
    • If you use additional apps to provide alerts, be sure to add them to Focus as well

The little clock icon indicates that time-sensitive notifications are enabled. The other icons represent the apps you added to have permission to notify you when in this Focus mode.

Be sure to do this for every Focus mode you use.

"},{"location":"faqs/safety-faqs/#understand-the-app-displays","title":"Understand the App Displays","text":"

If you do not understand the components displayed in the graphic below, please spend time reviewing the information at Displays.

"},{"location":"faqs/safety-faqs/#carb-entry-and-insulin-delivery","title":"Carb Entry and Insulin Delivery","text":"

If you configured the app with closed-loop enabled:

  • Once carbohydrates are entered into\u00a0Loop, the algorithm will begin to dose insulin to anticipate those carbs

If you entered carbs and then changed your mind on the amount or the time at which they were eaten, use these instructions to delete or edit them. This will make\u00a0Loop\u00a0better able to predict blood glucose and adjust insulin delivery appropriately.

"},{"location":"faqs/safety-faqs/#how-to-cancel-a-bolus","title":"How to Cancel a Bolus","text":"

Once a bolus starts, the progress of that bolus appears in the HUD Status Row. Note that the phone must be held in portrait mode to see this. Simply tap on the row that shows the delivery to halt the bolus.

"},{"location":"faqs/safety-faqs/#understand-delivery-limits","title":"Understand Delivery Limits","text":"

With each cycle, Loop\u00a0generates a glucose prediction and a recommended dose (positive or negative) to bring you to your correction range.

  • The automated response to a positive recommended dose depends on your Dosing Strategy and is adjusted by your Delivery Limits

For more information, please read How do Delivery Limits Affect Automatic Dosing?.

"},{"location":"faqs/safety-faqs/#health-app-permissions","title":"Health app permissions","text":"

For older versions of\u00a0Loop, or if you customized\u00a0Loop 3\u00a0to read carbohydrates from third-party apps, be aware that you cannot edit those entries inside the\u00a0Loop\u00a0app.

If you let other apps, such as MyFitnessPal, write carbohydrates to the Health app, Loop\u00a0could read those carbohydrates and you could be dosed for those carbohydrates.

  • Loop 3: review Customization: Build Time Features
  • Loop 2: Check your Health permissions and review.
"},{"location":"faqs/safety-faqs/#glucose-prediction-is-scary","title":"Glucose Prediction is Scary","text":"

Users often reach out if the glucose prediction shown on the Loop app screen is very low - negative even.

  • The negative glucose prediction will not happen (that's just the way the model works) but the user must figure out what is going on
"},{"location":"faqs/safety-faqs/#scenario-1-extreme-override","title":"Scenario 1: Extreme Override","text":"

It is pretty common for new users to think a 10% override setting should behave similarly to a 10% temporary basal rate setting on a manual pump. This is not true.

Read this section on the override page for information: Avoid Extreme Insulin Needs Setting

"},{"location":"faqs/safety-faqs/#scenario-2-entry-error-into-apple-health","title":"Scenario 2: Entry Error into Apple Health","text":"

With version 3 of the Loop app, it is no longer necessary to enter glucose or insulin manually into the Apple Health app for the Loop app to read. There are methods within the Loop app for entering a fingerstick value or non-pump insulin.

However, some people are used to entering information into Apple Health directly - and it still works. The Loop app will read entries from Apple Health. But if you do this:

  • Be very careful that you enter glucose into glucose
  • Be very careful that you enter insulin into insulin

A recent user entered a fingerstick value into the insulin record in Apple Health. They use mmol/L glucose units, so it wasn't as obvious as it would have been for someone using mg/dL. At any rate, they could not figure out why their child had such a high IOB and were afraid the pump had delivered 10 U of insulin! Once they deleted the incorrect entry from Apple Health, the Loop app was able to make the appropriate prediction.

"},{"location":"faqs/safety-faqs/#beware-the-medtronic-easy-bolus-button","title":"Beware the Medtronic Easy Bolus button","text":"

Medtronic's easy bolus button has been the cause of several accidental boluses when the pump has been carried in a pocket. Best practice would be to disable the Easy Bolus button since you will be doing boluses from the phone anyways.

"},{"location":"faqs/safety-faqs/#finish-your-medtronic-priming","title":"Finish your Medtronic priming","text":"

After a site change and reservoir rewind, Medtronic's pump will have a menu on the pump screen related to finishing your prime. Make sure you complete that screen and always return to the main menu. Medtronic's pump won't resume basal insulin delivery until that priming screen is completed.

"},{"location":"faqs/time-faqs/","title":"Time FAQs","text":""},{"location":"faqs/time-faqs/#the-loop-phone-must-be-on-automatic-time","title":"The Loop Phone Must be on Automatic Time","text":"

The Loop Phone is a Medical Device

There have been several instances where a Looper disabled automatic time to change the time on their Loop phone.

As of January 2023, this change in time is detected and the Loop app stops all automatic dosing of insulin other than your scheduled basal rates and begins to aggressively warn the user.

One scenario should be enough to convince you not to do this:

  • Glucose is 180 mg/dL (10 mmol/L) when you set time one day ahead (for a game)
  • Later you return time to automatic and think nothing of it
  • As soon as automatic time is restored, the Loop app thinks your eventual glucose will be the future value (in this example 180 mg/dL) and attempts to bring you to your correction range
    • If you are running a very old version of the Loop app, dosing could continue based on that incorrect future glucose value
"},{"location":"faqs/time-faqs/#force-automatic-time","title":"Force Automatic Time","text":"

You can configure the iPhone to only allow automatic time.

  • Under iOS Settings, select Screen Time
  • Scroll down to the Lock Screen Time Settings row
    • Enter a passcode

The ability to use anything other than automatic time is disabled as long as that iOS setting has a passcode. Parents can use this for children. Adults can use this too in case they need a reminder not to change the time - you must first disable the passcode.

This does not affect automatic time zone changes, those are handled by the phone without need for interaction.

"},{"location":"faqs/time-faqs/#remove-future-glucose","title":"Remove Future Glucose","text":"

If you have future glucose from a manual time change or just entering something into Apple Health with the wrong timestamp:

  • You MUST go into Apple Health and remove any glucose values in the future
  • The Loop app detects the future glucose and stops looping
    • It might not be completely obvious why Loop stopped, but you will get a red loop within 15 minutes and Loop is not Looping notifications starting at 20 minutes
    • If you tap on the bolus icon, Loop informs you it detected invalid future glucose
    • If you tap on the glucose icon - it takes you to your CGM which probably has a very different number from that shown on the main Loop screen
  • If you also use Nightscout and have the upload CGM readings enabled in Loop, those future glucose values will appear in Nightscout
    • To fix this problem (after you fix Apple Health), use the Admin Tools in Nightscout to remove future treatments and future entries

The Loop app is very aggressive at warning you if you make this mistake. you will get a notification - even when you are in a different app. The graphic below shows the alert when you next view the Loop app after turning off automatic time and changing the time. Even if you respond right away, you may have at least one glucose reading in the future when you see this alert. Please Remove Future Glucose.

The rest of this page is about changing time zones.

This is safe because the Loop app keeps track of records internally using UTC.

"},{"location":"faqs/time-faqs/#time-zones-daylight-savings-time-summer-time","title":"Time Zones, Daylight Savings Time, Summer Time","text":"

The Loop app operates across time zones and time changes. The phone that is running the Loop app will automatically update the time, but you choose when to modify the time zone for \"pump time\".

What Therapy Settings are set by \"pump time\"?

  • Basal Rate Schedule
  • CR and ISF Schedule
  • Correction Range Schedule

Time Change comments:

  • The Pump Settings screen is used to modify time zones
    • Tap on Pump Status Icon from the HUD
    • or Loop->Settings->Pump
  • Travel
    • There is no urgency to update the pump time to match the wall-clocks when traveling
    • For short trips, many Loopers just leave the pump time alone
  • Time Change (Daylight Savings Time or Summer Time)
    • Most people want to update their pump time immediately after the clocks change
  • A Clock Icon is seen in the HUD Pump Status display when pump time differs from phone Time Zone

Medtronic Users

Do not use the Medtronic pump menus to change your pump's time when Looping.

"},{"location":"faqs/time-faqs/#iphone","title":"iPhone","text":"

The Loop app will warn you if your phone does not have time configured to automatically update. The configuration is under iOS Settings -> General -> Time & Date.

Do not ever adjust the time manually on your Looping phone to \"defeat\" time-based rules for a game. Your phone with the Loop app is now a critical medical device - make sure anyone who uses your phone understands this.

"},{"location":"faqs/time-faqs/#minimed-pump-and-cgm","title":"Minimed Pump and CGM","text":"

The Minimed pump doesn't expose a universal clock, instead it exposes the components of a date (YMDHIS). It has no concept of political time zones, and just continues to increment its components on schedule. Therefore, the Loop app assumes that the pump's date, until changed, remains at a fixed offset from UTC.

That offset is stored by the Loop app the first time the pump ID is changed, and every time the pump's time is changed using the \"Change Time Zone\" command.

"},{"location":"faqs/time-faqs/#dexcom-cgm","title":"Dexcom CGM","text":"

No particular input is needed on your part for the Loop app to work with Dexcom CGM data. All times use UTC. However for Dexcom receiver users, at time changes you may want to manually change your receiver's time setting just so the time visually appears correct when you are viewing the screen.

"},{"location":"faqs/time-faqs/#airports","title":"Airports","text":"

RileyLinks, pumps and CGM have no problem going through any of the airport security systems. You can carry it with you in the airplane cabin and it can go through the x-ray scanner that your carry-on bags go through.

"},{"location":"faqs/time-faqs/#airplane-mode","title":"Airplane Mode","text":"

Nothing wrong with airplane mode, but many people forget about it at the time they travel. So, you can do this simple preparation step now:

Turn airplane mode on. Then make sure your Bluetooth is still slid \u201con\u201d. If Bluetooth isn\u2019t on, then go slide it on again. Now go ahead and turn airplane mode off again.

Why did we just do that? Because in older versions of iOS, airplane mode turned off Bluetooth the first time you ever use it. New iOS don't do that, but worth checking.

But, if you remember to turn Bluetooth back on while in airplane mode, two things happen (1) your CGM and the Loop app will work while in airplane and (2) airplane mode will \u201cremember\u201d the next time that you like Bluetooth left on in airplane mode and will not turn it off the next time you slide airplane mode on. So now you\u2019ve just prevented yourself from forgetting to turn Bluetooth on the next time you fly and are in a hurry to meet your lovely seat mate and stow your luggage. You can safely follow cabin instructions and put phone in airplane mode without losing access to the Loop app or CGM.

"},{"location":"faqs/update-faqs/","title":"Update/Rebuild Loop FAQs","text":""},{"location":"faqs/update-faqs/#overview","title":"Overview","text":"

First, please take a minute to understand what the words mean.

  • Update the Loop App is the process of building a new version of code, updated from that already on your phone

  • Rebuild the Loop App is the process of building the same version of code, identical to that already on your phone

    • Rebuilding the app extends the expiration date and enables your Loop app to keep working

In both cases, you build the code to install over an existing app on your phone or onto a new device.

Check Apple Developer Account

If you have an updated agreement, be sure to accept it before you update or rebuild.

  • Apple Program License Agreement
  • If you use the Browser build method:
    • Follow the steps on Update/Rebuild with Browser
    • Within an hour that new build should be available via TestFlight to install on your phone
  • If you use the build with Mac method:
    • Follow the steps on Update/Rebuild with Mac
      • First make sure your Mac operating system and Xcode version are compatible with your iPhone version, and then
      • Use the Build Select Script to download the latest released version of the code
    • See note below if your internet speed or your Mac is very slow
Slow Internet / Slow Mac? (click to open/close)

If you have a very slow download speed or if you do a lot of customizations, it may be worth your time to decide if you need a new download.

  • Use Finder to check the date of your last download by looking in the Downloads/BuildLoop folder
  • Check the date of the last release at GitHub LoopKit/Loop releases
  • If the date in Finder is after the release date, follow Find my Downloaded Loop Code
    • Double-click on the Loop.xcworkspace file in that folder
    • This opens Xcode and you can just plug in your phone and build with your existing download
"},{"location":"faqs/update-faqs/#what-if-im-changing-phones","title":"What if I'm changing phones?","text":"

There's a whole page devoted to just this topic: New Phone

"},{"location":"faqs/update-faqs/#when-should-i-update","title":"When Should I Update?","text":"
  • Best Practice
    • Build if a serious bug-fix is reported
    • Build, two to four times a year so that it becomes easier and you are ready in case of an emergency
    • Each time you build, the app expiration date is bumped out a full year for build with Mac method and 90-days for Browser build
  • Required
    • When your expiration date forces you
    • Do not wait until the app expires - it will stop working
      • For Mac, you will see Loop is No Longer Available
      • For Browser Build, the message is \"Loop Beta has expired\"
    • Hint - start a few weeks early and take your time
  • Optional
    • A new version of the Loop app is released and you want to install it
    • You want to try a different branch or fork of Loop
"},{"location":"faqs/update-faqs/#steps-to-update","title":"Steps to Update","text":"

Updating the Loop app is the same idea as what happens to your other apps on your iPhone when you update them from the App Store on the phone. A newer version of the same app appears on the phone, simply updating-in-place the same the Loop app you were using with an updated version.

  • Do NOT delete your current app from your phone - even if it says \"Loop is No Longer Available\" or \"Loop Beta has Expired\"
  • There are files stored on your phone that will be read in as soon as the new Loop app is installed
  • If you deleted your app, then you have to enter all your settings again
    • This is a good time to configure your phone to avoid accidental deletion
    • Do an internet search like this: \"iOS 15.4 prevent app deletion\" where you use your current phone iOS version number and follow the instructions
"},{"location":"faqs/update-faqs/#typical-apple-update-schedule","title":"Typical Apple Update Schedule:","text":"
  • Each September, Apple releases a major iOS version which typically works with the current macOS but requires a new Xcode version
  • Each September, Apple releases a major macOS version (but doesn't require you to update your Mac, yet)
  • Each March, you must update to the current macOS (major version) to continue building applications
"},{"location":"faqs/update-faqs/#where-should-i-start-when-i-want-to-update-my-loop","title":"Where should I start when I want to update my Loop?","text":""},{"location":"faqs/update-faqs/#check-your-developer-account","title":"Check your Developer Account","text":"

Regardless of the build method, always check your Apple Developer Account status.

Apple updates its License Agreement for the Developer Program frequently. You need to log in to your developer account to manually check if there is a new agreement to accept. If you see a big red or orange banner across the top of your Developer Account announcing a new license agreement like shown below...please read and accept it before building Loop.

"},{"location":"faqs/update-faqs/#updates-with-the-browser-build-method","title":"Updates with the Browser build method:","text":"

Go to Update/Rebuild with Browser and follow the instructions.

"},{"location":"faqs/update-faqs/#updates-with-the-build-with-mac-method","title":"Updates with the build with Mac method:","text":"

ALWAYS start with the Update/Rebuild with Mac before any new build with Mac. That page is important because it will offer information on the updates you may need for your Mac and Xcode before building.

Do not simply build with your old downloaded folder from months ago. There is a high likelihood that your original code from awhile ago is outdated and might not build with the current phone iOS. Grab new code and you will get the compatible version that has all the latest and greatest features and bug fixes.

"},{"location":"faqs/update-faqs/#will-i-have-to-delete-my-old-loop-app","title":"Will I have to delete my old Loop app?","text":"

No. Do not delete your old Loop app. In fact, that is a bad idea as you will lose your currently paired pod and/or settings if you do that. So, don't delete.

  • Refer to What if I change the branch or fork?
"},{"location":"faqs/update-faqs/#does-update-make-a-separate-second-loop-app","title":"Does update make a separate, second Loop app?","text":"

No. The Loop app is simply updated in-place, written right over the old version.

The only exception to this is if you update/build using a different developer signing team than your current Loop app.

  • The app's identity on your phone is defined by the developer ID.
  • If you change that unique ID, your phone interprets that as a unique app as well...giving you two Loop apps on the phone.
    • Therefore, if changing developer accounts...you will get a new Loop app, and you would need a new Pod.
    • You'll need to transfer your settings manually to the new app and delete your old app.
"},{"location":"faqs/update-faqs/#will-my-settings-be-saved-when-i-update","title":"Will my settings be saved when I update?","text":"

Yes. That's why we don't delete the app. Your settings will be saved so long as you use the same developer ID.

"},{"location":"faqs/update-faqs/#will-my-pod-still-work-when-i-update","title":"Will my pod still work when I update?","text":"

Yes. So long as you use the same developer ID as you originally built the app with before.

"},{"location":"faqs/update-faqs/#how-can-i-confirm-what-version-was-installed","title":"How can I confirm what version was installed?","text":"

The Loop app version is given at the top of the Loop settings page.

There is more detailed information about how the Loop app was built at the top of the Issue Report as shown in the graphic in the next section.

"},{"location":"faqs/update-faqs/#when-will-my-app-expire","title":"When will my app expire?","text":"

The information in the graphic below shows the Build Details included at the very beginning of a Loop Report (Loop, Setting, Support, Issue Report).

Up through version 3.2.3, the Browser Build versions do not report the correct date in the Expiration Alert. The date reported is correct with Mac Build or later versions using the Broswer Build.

  • A Browser Build can be identified when you see runner in the * sourceRoot line in the graphic above
    • If you add 90 days to the * buildDateString, that is approximately when the app expires
    • The best method is to look in the TestFlight app because that tells you exactly how many days until expiration
  • A Mac Build expiration date can be read directly from the * profileExpiration line in the Build Details
    • The * sourceRoot line will be recognizable as where on your computer the download is located
"},{"location":"faqs/update-faqs/#what-if-i-change-the-branch-or-fork","title":"What if I change the branch or fork?","text":"

Does not matter. Changing the branch and even the fork is an update action. Nothing about the information above changes with the following exception.

The exception to the rule is if you build Loop 3 on your phone and want to return to Loop 2.2.x or any FreeAPS fork.

  • In this case, the database storage is different between Loop 3 and Loop 2.2.x
  • Loop 3 can read the data stored by Loop 2.2.x, but the reverse is not true
  • If you are downgrading from Loop 3 to FreeAPS, you need to first record settings, delete the old app and then build the desired app, enter your settings and add your pump (new pod required for Omnipod)
"},{"location":"faqs/update-faqs/#how-long-does-it-take","title":"How long does it take?","text":"

Assuming your macOS and Xcode updates are done, then plan on about 30 minutes for a Mac build. The Browser build steps are very fast, but then you need to wait about an hour for the build to complete and appear in TestFlight.

"},{"location":"gh-actions/automatic/","title":"Automatic Update & Build","text":""},{"location":"gh-actions/automatic/#overview","title":"Overview","text":"

After the next release of the Loop app (version 3.4.0), this page will be required for all versions when building with a browser.

Before that release, this page is only relevant when building the dev branch with a browser and only when the dev branch is the default branch.

"},{"location":"gh-actions/automatic/#modify-automatic-building","title":"Modify Automatic Building","text":"

For someone using development code for their own use, they probably want to decide when to update their fork to the most recent commit. They can still have the advantage of automatic building without automatic updates. There may be other configurations someone would choose. These options are added to Loop 3.3.0 (dev branch) and later.

You can affect the default behavior:

  1. Modify Automatic Schedule
  2. Disable Automatic Actions
"},{"location":"gh-actions/automatic/#modify-automatic-schedule","title":"Modify Automatic Schedule","text":"

You can modify the automation by creating and using some variables.

To configure the automated build more granularly involves creating up to two environment variables: SCHEDULED_BUILD and/or SCHEDULED_SYNC. See How to configure a variable.

Note that the weekly and monthly Build Loop actions will continue, but the actions are modified if one or more of these variables is set to false. A successful Action Log will still appear, even if no automatic activity happens.

  • If you want to manually decide when to update your repository to the latest commit, but you want the monthly builds and keep-alive to continue: set SCHEDULED_SYNC to false and either do not create SCHEDULED_BUILD or set it to true
  • If you want to only build when an update has been found: set SCHEDULED_BUILD to false and either do not create SCHEDULED_SYNC or set it to true
    • Warning: if no updates to your default branch are detected within 90 days, your previous TestFlight build may expire requiring a manual build
SCHEDULED _SYNC SCHEDULED _BUILD Automatic Actions true (or NA) true (or NA) keep-alive, weekly update check (auto update/build), monthly build with auto update true (or NA) false keep-alive, weekly update check with auto update, only builds if update detected false true (or NA) keep-alive, monthly build, no auto update false false no automatic activity, no keep-alive"},{"location":"gh-actions/automatic/#how-to-configure-a-variable","title":"How to configure a variable","text":"
  1. Go to the \"Settings\" tab of your LoopWorkspace repository.
  2. Click on Secrets and Variables.
  3. Click on Actions
  4. You will now see a page titled Actions secrets and variables. Click on the Variables tab
  5. To disable ONLY scheduled building, do the following:
    • Click on the green New repository variable button (upper right)
    • Type SCHEDULED_BUILD in the \"Name\" field
    • Type false in the \"Value\" field
    • Click the green Add variable button to save.
  6. To disable scheduled syncing, add a variable:
    • Click on the green New repository variable button (upper right)
      • Type SCHEDULED_SYNC in the \"Name\" field
    • Type false in the \"Value\" field
    • Click the green Add variable button to save

Your build will run on the following conditions:

  • Default behaviour:
    • Run weekly, every Wednesday at 08:00 UTC to check for changes; if there are changes, it will update your repository and build
    • Run monthly, every first of the month at 06:00 UTC, if there are changes, it will update your repository; regardless of changes, it will build
    • Each time the action runs, it makes a keep-alive commit to the alive branch if necessary
  • If you disable any automation (both variables set to false), no updates, keep-alive or building happens when Build Loop runs
  • If you disabled just scheduled synchronization (SCHEDULED_SYNC set tofalse), it will only run once a month, on the first of the month, no update will happen; keep-alive will run
  • If you disabled just scheduled build (SCHEDULED_BUILD set tofalse), it will run once weekly, every Wednesday, to check for changes; if there are changes, it will update and build; keep-alive will run
"},{"location":"gh-actions/automatic/#disable-automatic-actions","title":"Disable Automatic Actions","text":"

To enable the scheduled build and sync, the GH_PAT must hold the workflow permission scopes. This permission serves as the enabler for automatic and scheduled builds with browser build. To disable this, follow these steps:

  1. Go to your FastLane Access Token
  2. If it says repo, workflow next to the FastLane Access Token link, then automatic building is enabled
  3. To disable automatic update and build, click on the link to open the token detail view
    • Click to uncheck the workflow box
    • Click to check the repo box
  4. Scroll all the way down to and click the green Update token button
  5. Your token now holds only the repo permission

If you choose not to have automatic building enabled, be sure the GH_PAT has repo scope or you won't be able to manually build.

"},{"location":"gh-actions/automatic/#stop-building","title":"Stop Building","text":"

What if I decide I don't want the automatic building feature?

  • If you are using the released version of Loop, please leave automatic building running

    • Please read TestFlight Automatic Updates on how to configure TestFlight so you choose when the updated app gets installed on your phone
    • Otherwise, you may see the dreaded \"Loop Beta has expired\" message, have a Loop that won't open and not have a version ready to go in TestFlight that you can install within a few seconds

  • If you are taking a break from Loop and want to stop monthly Build emails, consider disabling actions for the Build Loop action for your app.

    • GitHub Directions to Disable and Enable a Workflow
    • It is the Build action that kicks off the update and build steps, so simply disabling the one action is sufficient

  • If you are done with Loop, you can delete the whole repository; but you should be sure about this because you'll need to start over with Configure to Use Browser to restore ability to build Loop with GitHub.

"},{"location":"gh-actions/build-dev-browser/","title":"Build Loop dev with Browser","text":""},{"location":"gh-actions/build-dev-browser/#overview","title":"Overview","text":"

This page is only relevant when building the dev branch with a browser.

For Mac, please see: Build Loop dev with Mac

No matter the method used to build Loop-dev, you are testing development code. Please read this link now before continuing.

  • What's going on in the dev branch
"},{"location":"gh-actions/build-dev-browser/#build-development-version","title":"Build Development Version","text":"

For Experienced Builders

Building the development (dev branch) is not typically used for your first attempt at building the Loop app.

The instructions on this page assume you are familiar with building the Loop app using a browser as detailed on Configure to use Browser

  • You should be following along with zulipchat when using the dev branch
  • Summary build updates can be found under the One-Time Changes section

You can build any desired branch (available at LoopKit/LoopWorkspace) using the GitHub Browser build method. This section is suitable if you have already built either dev or main branch using the GitHub First-Time instructions.

The graphics on this page show the dev branch. If you want a different branch, just substitute that branch name for dev.

Overview of what you will do

  1. Your LoopWorkspace fork must have the branch you want
    • You will either add it or make sure it is up to date
    • You cannot just rename your existing branch to dev - you must get the dev branch from LoopKit
  2. When you select the action 4. Build Loop and then click on the Run Workflow dropdown, you must select dev there before clicking the green Run workflow button - see Build Branch
"},{"location":"gh-actions/build-dev-browser/#check-current-branch","title":"Check Current Branch","text":"

Your LoopWorkspace fork is at https://github.com/username/LoopWorkspace where you substitute your actual GitHub username. You need to be logged into GitHub. Review the graphic below as you go through the steps.

  1. Click on the branch icon to display the branches as shown in the lower half of the graphic below:
    • If the branch you want is not listed, then continue with Step 2
    • Otherwise, skip ahead to Update Branch
  2. Click on the New branch button and follow the Add Branch steps

"},{"location":"gh-actions/build-dev-browser/#add-branch","title":"Add Branch","text":"

Each step in the list below matches with the number in the graphic. In the top half of the graphic, the left side shows the initial display and the right side shows the display after making the indicated selections:

  1. Click on the drop down menu labeled 1 in the graphic and choose LoopKit/LoopWorkspace as show in the top right graphic
  2. Click on the drop down menu labeled 2 in the graphic and choose dev
  3. Click on the Branch name box labeled 3 in the graphic and type dev
    • The branch name in your fork should always match the branch name you are adding; check that you type it correctly
  4. Review the dialog items to make sure everything is correct and then tap on Create branch

"},{"location":"gh-actions/build-dev-browser/#update-branch","title":"Update Branch","text":"

Tap the Code button (upper left) and ensure this branch in your fork is up to date.

  • Select the desired branch in the dropdown menu (this graphic shows dev branch)
  • If the message indicates this branch is \"behind\", tap on the sync fork button and then the Update branch button

"},{"location":"gh-actions/build-dev-browser/#one-time-changes","title":"One-Time Changes","text":"

Look in this section for one-time changes for building dev with a browser that require special, one-time actions.

If you have already completed the One-Time Changes, skip ahead to Build Branch.

"},{"location":"gh-actions/build-dev-browser/#transition-to-dev","title":"Transition to dev","text":"

When updating from\u00a0Loop\u00a03.2.x to dev, you will need to take some extra steps.

You have a choice:

  • You can change your default branch to dev, see Change Default Branch and then your\u00a0Loop\u00a0app will be automatically updated and automatically built at least once a month
    • Be sure to review the Modify Automatic Building section
  • You can leave your default branch at main, but no automated updates will happen
    • Running each action below requires you to select the dev branch in the drop-down menu

Here is a summary of the extra steps; each step has an associated link. This assumes you have already updated your fork and are at the correct branch.

  1. Confirm the status of your \u00a0GitHub Personal Access Token
    • It should be configured with permission scope of repo, workflow and to never expire
    • You can check this using directions at GitHub Token
  2. Next, follow along in this section to perform these steps before you build
    • Add and Update New Indentifier
    • Create Certificates
"},{"location":"gh-actions/build-dev-browser/#automatic-creation-of-alive-branch","title":"Automatic Creation of alive branch","text":"

What about the alive branch

  • Sometimes you get an error about the alive branch
  • It should be created for you automatically if you are building with the dev branch and you have workflow permission added to the scope for your GitHub Personal Access Token
  • If necessary, delete the alive branch and run the Create Certificates again
"},{"location":"gh-actions/build-dev-browser/#add-and-update-new-identifier","title":"Add and Update New Identifier","text":"

The bundle ID for the \"widget\" changed from \"SmallStatusWidget\" to the more descriptive \"LoopWidgetExtension\".

  • You need to run Add Identifier - be sure that you run this for the dev branch
  • Wait for it to succeed
  • Add the App Group to this one new Identifier

All other identifiers should be already set up. If they are not, please go through the steps on the Configure to Use Browser page to figure out what you are missing.

NAME IDENTIFIER Loop Widget Extension com.TEAMID.loopkit.Loop.LoopWidgetExtension
  • Open the Certificates, Identifiers & Profiles: Identifiers List page.
  • Click on the \"LoopWidgetExtension\" identifier
  • Edit the App Group to include group.com.TEAMID.loopkit.LoopGroup where you use your TEAMID
"},{"location":"gh-actions/build-dev-browser/#create-certificates-and-build","title":"Create Certificates and Build","text":"

You must create certificates again to cover the new Identifier name and to provide support for the addition of the Libre sensors. (This step is required whether you use Libre or not - Loop needs permission to have that capability). Once the certificate action succeeds, then run the action to build Loop.

  1. Run the Action for Create Certificates - be sure that you run this for the dev branch
  2. Run the Action for Build Loop (see Build Branch)
"},{"location":"gh-actions/build-dev-browser/#build-branch","title":"Build Branch","text":"

If you want a branch to be the one you build all the time, you may choose to Change Default Branch. This is not necessary except for special cases.

If you have one branch as default, for example main, and choose to build a different branch, there is an extra step when you Build Loop. Refer to step 4 in the graphic below. Use the branch dropdown menu to select the branch you want before hitting the green Run workflow button.

!!!

"},{"location":"gh-actions/build-dev-browser/#change-default-branch","title":"Change Default Branch","text":"

There can be several reasons why you would change your default branch.

  • It can be convenient to have the branch you build most be configured as the default branch
  • The branch you want to build has a different workflow than your default branch (not typical)
    • In this case, you must modify the default branch
    • Check the zulipchat conversation about the branch you are testing to see if it is necessary to make it default

These are the steps to modify the default branch.

For this example, we show how to change from a default branch of main to a default branch of dev. Note - only the owner of the repository can take this action and they must be logged in. Otherwise the Settings tab does not appear.

For the numbered steps below, refer to the graphic found under each group of steps.

  1. Click on the Settings Icon near the top right of your LoopWorkspace

    • You may need to scroll down to see the Default Branch as shown in the graphic
    • Do not tap on the Branches tab to the left under Code and Automation, that is not the correct menu

  2. To the right of the default branch name there is a pencil and a left-right arrow icon

    • Tap on the left-right arrow icon to bring up the Switch default branch to another branch dialog
  3. Click on the dropdown next to the current default branch, in this example, main
  4. Select the desired default branch, in this example, dev

  5. Click on the Update button

  6. You will be presented with an are-you-sure question.

    • Click on the red I understand, update the default branch. button

Your default branch has been changed.

"},{"location":"gh-actions/build-dev-browser/#automatic-update-build","title":"Automatic Update & Build","text":"

The automatic update and build features of the development branch are only available if you set the dev branch as your default branch. Be sure to read the Automatic Update & Build if you did this.

"},{"location":"gh-actions/custom-browser/","title":"Customize using Browser","text":""},{"location":"gh-actions/custom-browser/#overview","title":"Overview","text":"

This page is only relevant when building with a browser.

For Mac, please see: Customize with Mac

For new Loopers, please build the code before you make any changes. Start with Open Loop and familiarize yourself with the interface. Later, you can make the customization(s) you desire and build again. The second build will be much easier than your first build.

These customizations require you to modify the code used to build the Loop app and then build the app again with the modified code.

You take responsibility

You are responsible when you decide to use customizations.

Be sure to report what changes you made if you need to ask for assistance with your app.

"},{"location":"gh-actions/custom-browser/#customizations-prepared-for-you","title":"Customizations Prepared for You","text":"

Some customizations are the same for everyone and have been prepared for easy use.

The Loop and Learn team commits to maintaining these prepared customizations and provides an easy method to add your selection from these customizations to your version of Loop.

Please read the documentation for these on the Loop and Learn: Customization Select Page:

  • List of Customizations Available
  • When building using a browser you will be modifying one of the special files that enable the GitHub action to build the Loop app. This file is called the build_loop.yml file and can be located at your fork of your LoopWorkspace repository. There are several sections you need to review on the Loop and Learn page:
    • Overview of how to modify the build_loop.yml file
    • You will copy a template that you paste into that file and then edit it to keep just the customizations you want
    • Template for main
    • Template for dev
"},{"location":"gh-actions/custom-browser/#add-libre-support-to-323","title":"Add Libre Support to 3.2.3","text":"

If you are using main branch to build Loop 3.2.3 and rely on either xDrip4iOS or GlucoseDirect to read your CGM and transfer the readings to the Loop app, you need to review this section of the Loop and Learn customization page.

Alternatively, you can switch to the dev branch, which already supports Libre. Build Loop dev with Browser

"},{"location":"gh-actions/custom-browser/#personal-customizations","title":"Personal Customizations","text":"

Some customizations must be created for yourself. These are of two basic types: Custom Edits and Build-Time Flag.

The information needed to modify the code to make these customizations is found in the Versions tab because the information is independent of build method (think of these as your personal versions). The links are found below.

  • Version: Custom Edits
    • The page linked above indicates how you can modify behavior by editing the code
  • Version: Build-Time Flag
    • By enabling or disabling features controlled by a Build-Time Flag, you are turning on or off features included in the code by the developers that they configured to be off or on by default
    • Please read about these flags on the page linked above

When preparing these personal edits using a browser, there is a page explaining how to get these edits into your personal fork of LoopWorkspace prior to building.

  • Custom Edits with Browser
"},{"location":"gh-actions/custom-browser/#details-at-links","title":"Details at Links","text":"

The code changes required for these customizations are the same regardless of the build method. The pages that provide the documentation on modifying and incorporating these changes are found at the links above.

"},{"location":"gh-actions/edit-browser/","title":"Custom Edits with Browser","text":""},{"location":"gh-actions/edit-browser/#hot-topics","title":"Hot Topics","text":"

Pro Tip

The method on this page allows you to create a set of personalized customizations that you can use in addition to the Loop and Learn: Prepared Customizations. You can use (and re-use) your customizations with either Browser Build or Mac builds so you don't have to repeat the customization with every update.

  • If you are building with Mac method, you can use the same lines prepared for Build with Browser method and simply paste them in your terminal at the\u00a0LoopWorkspace\u00a0folder to customize your code
  • You can often use the same customization for several releases
  • If a customization that you prepared for an older release says \"does not apply\" when you use it, you'll need to prepare a new one

Modules vs Submodule

This page has instructions to set up your own fork for the Modules, otherwise known as submodules, associated with\u00a0LoopWorkspace\u00a0that are needed for a selected customization.

Each Module has its own GitHub repository;and you will be working with your fork of that Module at https://github.com/username/Module, where username is your username.

What is a SHA-1?

SHA-1 means Secure Hash Algorithm 1; which is used to generate an alphanumeric code.

Each time you save a change to your\u00a0GitHub repository, a unique SHA-1 is created. That identifier is used to tell GitHub a specific change that you want applied or identifies a specific version for that repository. These work for any compatible fork from the original\u00a0GitHub repository.

"},{"location":"gh-actions/edit-browser/#do-not-make-a-pull-request-to-loopkit-github-username","title":"Do Not Make a Pull Request to LoopKit GitHub Username","text":"

Ignore\u00a0Compare & pull request\u00a0Prompts

Please do not click on boxes that GitHub might show you that ask if you want to Compare & pull request.

This would be an attempt to merge changes from your fork back to the original version that everyone uses. These changes are for you only. Ignore those prompts.

"},{"location":"gh-actions/edit-browser/#overview","title":"Overview","text":"

Time Estimate

  • About half an hour to an hour per Module
    • Typically 1 or 2 Modules
  • Ten minutes to add patch lines to your build_loop.yml file
  • One minute to start the build
  • An hour before the build shows up on your phone in TestFlight

Summary

  • Prepare Customization (One Time):
    • Once you have prepared a given customization, you can use it again with each update
    • If there is an update (new release) and the customization is no longer valid - you will get a clear error message
      • Just follow the steps on this page again to replace the customization that did not work
    • If there is an update (new release) and the customization applies with no errors, then you do NOT need to create an update
    • It is a good idea to test each customization as soon as you install the new build on your phone
  • LoopDocs: Decide on Modules to modify using the Version: Custom Edits page
    • You only need to create your own customization if what you want is not provided at Loop and Learn: Customization List
    • If there are customization not provided by the Customization List, then you need to make presonalized edits
    • This current page explains how to make the edits using a browser
    • The Version: Custom Edits gives instructions on identifying the Module, finding the file and editing the line(s)
  • GitHub (each Module):
    1. Fork the Module (if needed) - this is your fork where you will make changes
    2. Sync the Module (if needed)
    3. Make the desired modification(s) using the pencil tool
    4. Save your changes
    5. Prepare lines needed for each customization and save
  • GitHub (LoopWorkspace) - using your fork where you will make changes
    1. You will use the pencil tool to edit build_loop.yml
    2. Add customization lines to the file
    3. Save your changes
    4. Action 4: Build Loop
  • Phone: Install with TestFlight

FAQs

  • Do I need a Mac computer? No. This can be done on any browser.
  • Should I build without customizations first? Yes. Make sure the build process works without customizations. You don't need to install the build on your phone, just make sure it builds without errors before you start modifying.
"},{"location":"gh-actions/edit-browser/#how-to-customize-build-with-browser","title":"How to Customize Build with Browser","text":"

You do this using any browser on a computer or laptop. (Phone is not recommended - screen is too small.)

There is some background information at the bottom of this page starting at\u00a0LoopWorkspace\u00a0if you want to know what you are doing. Otherwise, just follow the steps like a cookbook.

"},{"location":"gh-actions/edit-browser/#decide-which-modules-you-want-to-modify","title":"Decide Which Modules You Want to Modify","text":"

Decide which Version: Custom Edits changes you want to make. Each customization lists a Module name.

  • DASH Pods: Use OmniBLE
  • Eros Pods: Use OmniKit
  • Other Modules are Loop and LoopKit
    • Do not get confused later: LoopKit is both a username and a Module name
    • Refer to the Module Table when directed

Look also at the Stable line for the desired customization:

  • Stable: Yes or Changed on date
  • The method for applying that customization differs slightly in the instructions below based on that notation
  • The customizations that are not stable, are summarized in Not Stable List
"},{"location":"gh-actions/edit-browser/#outline-of-what-happens-in-the-module","title":"Outline of What Happens in the Module","text":"

Review Only

Review this section so you know what to expect. The actual steps will come later, starting with Create your Fork for Selected Module or Edit Module in Browser.

In the next sections, the exact process for making changes will be documented. But the steps may feel confusing. There are no links here because you are supposed to review the steps before taking action in the next section.

  1. First time for this module:
    • Make a fork
    • If the customization you want is not \"Stable\" and you are building main
      • Create a new branch for your fork using the SHA-1 table
  2. Change the line(s) of code desired for your customization(s) in your fork
  3. Save the change(s) using descriptive comments
  4. Repeat until done with this Module

Later, you will use information from your fork to create your customizations. (Suggestion - use same file as your Secrets, or at least keep the customization file in the same folder). Details are found at the Prepare the Customizations section.

"},{"location":"gh-actions/edit-browser/#error-committing-your-changes","title":"Error Committing Your Changes","text":"

What should you do if you see the message:

  • There was an error committing your changes: File could not be edited

This is fairly rare, but it can happen. A user got this error when editing a file using GitHub:

The solution was to make sure the email address in their GitHub profile was correct. See GitHub Discussions for more information.

"},{"location":"gh-actions/edit-browser/#create-your-fork-for-selected-module","title":"Create your Fork for Selected Module","text":"

Choose your link:

  • New Fork: if you do not have a fork of this Module
  • Code Updates: if you are returning after a new release and the customization you used before no longer works
  • Existing Fork for Module: if you have a fork but need guidance on whether it is the right fork
"},{"location":"gh-actions/edit-browser/#code-updates","title":"Code Updates","text":"

New Release

If you have previously used this process for a prior release, use the same Modules you already copied.

You can often reuse customizations that you created earlier even with a new release. Attempt to use your existing patches before creating new ones.

If a customization did not work, then

  1. Go to your fork of each Module
  2. Make sure you are on the Default Branch for that Module
  3. Sync that Module to get the most recent version

Skip ahead to Personalized Customization for this Module.

"},{"location":"gh-actions/edit-browser/#new-fork","title":"New Fork","text":"

If you want a modification that uses a particular Module, you must make a fork of that module to your account in GitHub. You will repeat the Fork and Modify steps for each module.

  1. Log into your GitHub account
  2. Click the URL in the Module Table
  3. This opens a new browser tab at the URL of the module you need to fork
  4. Click on\u00a0Fork, your fork will show up in the browser
"},{"location":"gh-actions/edit-browser/#module-table","title":"Module Table","text":"

This table lists all the modules referred to on the Code Customization page linked above:

Module Fork From Loop https://github.com/LoopKit/Loop LoopKit https://github.com/LoopKit/LoopKit OmniBLE (for DASH) https://github.com/LoopKit/OmniBLE OmniKit (for Eros) https://github.com/LoopKit/OmniKit

Remember - you can only have a single fork of a given\u00a0GitHub repository. If you already have a fork, you don't need another one; but it must be a linked to the URL listed the Module Table.

I already have a fork

Go to Existing Fork for Module and follow the directions.

"},{"location":"gh-actions/edit-browser/#default-table","title":"Default Table","text":"

When you\u00a0\"fork a repository\", the default\u00a0branch\u00a0is the one that should be forked.

username/Repository Default LoopKit/Loop dev LoopKit/LoopKit dev LoopKit/OmniBLE dev LoopKit/OmniKit main"},{"location":"gh-actions/edit-browser/#create-branch-if-needed","title":"Create branch if needed","text":"
  • If the customization you wish to prepare indicates Stable: Yes, you can skip ahead to Personalized Customization for this Module
  • If you are preparing a customization for the dev branch, regardless of the Stable notation, there is no need to create a special branch, simply update the default branch to the latest (sync it) and use the current version of the customization when you skip ahead to Personalized Customization for this Module
  • Otherwise, when you a preparing a customization where the file changed sufficiently between main and dev and you want to build the main branch, you need to create a branch for this Module that is consistent with the version you wish to customize.

Open your browser to your https://github.com/username/Module URL. If you already created the branch you need, you do not need to create a new one.

If you are customizing a released version, use the Table of SHA-1 under your version number below. Copy the SHA-1 for your Module so you can paste it into the URL in Step 2 below. Notice the suggested branch name for that table. You will use this in Step 3.3 below.

You should create a branch following the numbered steps and watching the GIF. Each Frame in the GIF corresponds to a numbered step below.

  1. Click on URL line as indicated by the arrow
  2. Add the text /tree/SHA-1 where you change SHA-1 to be the value in the table below and hit return
  3. Create a new branch in three steps
    • 3.1: Click on the dropdown under the branch icon
    • 3.2: Type the suggested new branch name in the blank space
    • 3.3: Click on the create branch button
  4. You should see a screen similar to the example below
    • Do not click on the Create Pull Request button that is marked with a big X

"},{"location":"gh-actions/edit-browser/#table-of-sha-1","title":"Table of SHA-1","text":"

This will be updated with each release. The versions for the dev branch are not reported here because they are frequently updated. If customizing dev, use the default branch for each Module and sync that branch if needed.

"},{"location":"gh-actions/edit-browser/#version-323","title":"Version 3.2.3","text":"

Suggested branch name is v-3.2.3

Repository SHA-1 LoopWorkspace 81a3d9b03305a4b2a844bd6bac14a14f27626fef Loop c6b058b4276681600979aaeba518c635f06ac135 LoopKit 9835a29f1bac9f75023f39c376479a2e6a6c8ccd OmniBLE f21360781c0b8eee26c531d20f1b0aa192a227f2 OmniKit c1e0d395975c93d15b3f84ac21097e40b7d5d93f"},{"location":"gh-actions/edit-browser/#personalized-customization-for-this-module","title":"Personalized Customization for this Module","text":"

Navigate to the file you need to modify (using the instructions to find the lines from the Version: Custom Edit page)

Pro Tip

Look at the files you want to change - if more than one change is desired for a single file - do them at the same time.

This section provides the steps to make a single customization for the Module. If you need more than one, just repeat the process and make additional\u00a0\"\"patch\" branches.

"},{"location":"gh-actions/edit-browser/#example-gif","title":"Example GIF","text":"

The GIF showing the creation of one customization is shown below. Please review the 4 frames of the GIF, read the detailed instructions below and then review the GIF again. In case you are concerned by the\u00a0\"Pull Request\u00a0shown here; this is to your own fork, not back to the original.

"},{"location":"gh-actions/edit-browser/#detailed-instructions","title":"Detailed Instructions","text":"

You will be using the \"pencil\" tool in the browser display for your fork.

Are there detailed instructions?

For more information about editing with GitHub:

  • GitHub Docs: Editing Files

The bullets below go with Frame 1 of the GIF above:

  • Once you make the change to a given file, click on\u00a0\"Commit changes\" (upper right)
  • Click in the\u00a0\"Commit message\"\u00a0box and replace the default\u00a0\"Update filename\"\u00a0with a comment about what the customization does
  • Click on the second option near the bottom\u00a0\"Create a new branch for this commit\"
    • Note: when you do the\u00a0LoopWorkspace\u00a0modifications, you will not choose this option
  • Click on the\u00a0\"Propose changes\"\u00a0button
  • As soon as you do this, a new\u00a0\"branch\"\u00a0is automatically created with a name like username-patch-#, where the number increments each time

The bullets below go with Frame 2 of the GIF above:

  • You will be shown a screen where you create a pull request to your own fork (this does not go back to the original)
  • First review the changes (shown at the bottom) and then click on the\u00a0\"Create pull request\"\u00a0button

Between Frame 2 and 3 of the GIF, your display will look similar to the graphic below:

You see there an opportunity to\u00a0\"Compare & pull request\"

  • Do not click on that
    • This would be an attempt to merge changes from your fork back to the original

The\u00a0branches\u00a0selection is highlighted with a brown rectangle in the graphic above.

  • You can use the drop-down menu or click on the word\u00a0branches.
  • Choose the\u00a0branch\u00a0you just created, i.e., username-patch-#.

Your screen should now look like Frame 3 of the GIF above:

  • Click on the Clock icon to the right

Now your display should look like Frame 4 of the GIF above:

  • The top line is the last thing saved (your customization)
  • You need to record the very long alphanumeric number associated with this
  • There is a copy icon to the right - click on it and save it in your text file along with a comment about the customization and record which module you used for the customization

For example:

# OmniBLE: Increase insulin at insert by 0.35 U\nSHA-1 = 5e9f4f407ff5544663f496d2e3a5ed8aa4f32a68\n

Warning - that is not a valid SHA-1 for this change. Do not try to copy it and use it. You must make your own personalized changes.

Later on, you will create the actual command needed to insert into build_loop.yml so you can add this customization when your build the app.

Repeat this process until you've done all your customizations for this Module and then move on to the next Module.

"},{"location":"gh-actions/edit-browser/#prepare-the-customizations","title":"Prepare the Customizations","text":"

Once you prepare the commands, then you will edit the build_loop.yml file of your fork of\u00a0LoopWorkspace.

Ensure your fork is from\u00a0LoopKit/LoopWorkspace

If your\u00a0LoopWorkspace fork\u00a0did not come from\u00a0LoopKit/LoopWorkspace, then delete your existing fork and make a new one. See Already Have\u00a0LoopWorkspace?.

  • Do not use any other location to create your fork
  • You may have used a different location for Loop 3.2.2
  • This is not supported for Loop 3.2.3 or later

For each customization you want to include, create a pair of lines consisting of the comment (must start with a #) followed by the\u00a0curl\u00a0statement pointing to the SHA-1 that has the customization.

Save the customization lines in your text file for later use in the build_loop.yml file.

Customization Template:
# Module: File: code customization description\ncurl https://github.com/username/Module/commit/SHA-1.patch | git apply -v --directory=Module\n

where:

  • curl\u00a0means copy from URL
  • username is your GitHub username
  • Module is where you made the customization (Module is in multiple places)
  • SHA-1 is the full identifier for the desired change; there is a copy button to make this easy
  • adding\u00a0.patch\u00a0after the SHA-1 informs GitHub to format that code change so it can be applied to your fork
  • the final\u00a0 --directory=Module\u00a0is critical to apply the customization to the correct Module

To view the exact code change associated with that patch, open a browser at the URL of\u00a0https://github.com/username/Module/commit/SHA-1.

"},{"location":"gh-actions/edit-browser/#updateloopworkspace","title":"Update\u00a0LoopWorkspace","text":"

The final step is to update your\u00a0LoopWorkspace fork\u00a0to apply these customizations by adding those customization lines into the build_loop.yml file.

Return to your\u00a0GitHub fork for LoopWorkspace\u00a0and make sure to sync it if needed.

  • Find the folder .github/workflows and click on it
  • Find the file build_loop.yml and click on it
  • Click on the pencil (so you can edit this file)
  • If you are building dev, or if version 3.4 was just released - the directions are different
    • Skip the part where you copy and paste the block of text - it's already included
    • You will Add Personal Customizations to build_loop.yml at or near line 239
  • If you are building main, before version 3.4 was released, keep going
  • Locate line 31, which is just above the words:
    • # Patch Fastlane Match to not print tables
  • Paste the contents of the block below so it comes before that section
Paste into build_loop.yml
      # Customize Loop: Download and apply patches\n      - name: Customize Loop\n        run: |\n\n          # For each patch, edit comment line (keep the #) then update curl (and remove the #)\n\n          # Submodule Loop patches:\n          # Loop: Filename: customization details\n          #curl https://github.com/username/Loop/commit/SHA-1.patch | git apply -v --directory=Loop\n\n          # Submodule LoopKit patches:\n          # LoopKit: Filename: customization details\n          #curl https://github.com/username/LoopKit/commit/SHA-1.patch | git apply -v --directory=LoopKit\n\n          # Submodule xxxxx patches: Follow prototype above\n
"},{"location":"gh-actions/edit-browser/#add-personal-customizations-to-build_loopyml","title":"Add Personal Customizations to build_loop.yml","text":"

Open the text file in which you saved the customization lines.

For a given submodule, paste the comment / curl command as indicated in the template above.

The indenting needs to match, so tab or (shift-tab) to line up the columns.

Once you are done with all the edits for build_loop.yml you will commit the changes to your fork directly.

  • Once you have finished the edits for build_loop.yml
  • Click on\u00a0Commit changes (upper right)
  • Click in the larger box below\u00a0\"Update build_loop.yml\"\u00a0and summarize the customizations you added
  • Click on the option to\u00a0\"Commit directly to your branch\"
    • NOTE: for\u00a0LoopWorkspace fork\u00a0- commit directly to your default branch
  • Click on\u00a0Commit changes
  • You can make as many changes to build_loop.yml in your fork as you want

When you are ready, it's time to build with your customizations.

"},{"location":"gh-actions/edit-browser/#build-with-customizations","title":"Build with Customizations","text":"

At the top of the display, click on\u00a0Actions.

  • Click on\u00a0Action 4: Build Loop
    • Click on Run workflow on the right side
    • Then click on the green Run Workflow button

Wait about 2 minutes before walking away to make sure there are no errors. If you get an error, then look for the first \"did not apply\" error message and fix the customization right before that line.

In about 1 hour, your customized app will be available for installation on your phone via TestFlight.

"},{"location":"gh-actions/edit-browser/#customization-and-sha-1","title":"Customization and SHA-1","text":"

When you commit your customization to your branch of your fork, there is a new SHA-1 associated with that step. The SHA-1 for a given branch, typically main or dev identifies to a mentor exactly which version of code you used for your build.

The SHA-1 for customized code will not be recognized by a developer or mentor. If you are having a problem and need to ask for help you need to identify what the SHA-1 was before you added your customizations.

If you are on main branch and it is up-to-date, this is less of an issue. If you are on dev branch, that can require some investigation.

"},{"location":"gh-actions/edit-browser/#ask-for-help-to-identify-your-base-version","title":"Ask for Help to Identify Your Base Version","text":"

The easy method is to provide a mentor with your GitHub username and they can figure out the base version you are using aside from customization. They can also identify the customizations you added.

"},{"location":"gh-actions/edit-browser/#identify-your-base-version","title":"Identify Your Base Version","text":"

If you want to do this yourself, this section explains the steps.

  • Step 1: In your customized LoopWorkspace fork: tap on Code at upper left

    • If your fork is behind the LoopKit repository, consider updating your fork
      • Typically this can be done without changing your customization
    • Because you added customizations, your fork will be ahead of the LoopKit repository
    • An example is shown for the main branch in the graphic below - it is one commit ahead of LoopKit as indicated by the message highlighted by the red rectangle

  • Step 2: Click on the clock symbol, highlighted by blue rectangle in the previous graphic, to view the commit history - the history is presented in reverse chronological order

  • Step 3: Look at the commit descriptions for your fork; several examples are shown below

    • The last commit made by the developers that is included in your fork is the one a mentor will recognize

    • The first example is for main with one customization

      • The row highlighted in red is the one a mentor will recognize
      • The 7-digit alpha-numeric identifier for the commit is highlighted in the blue rectangle
      • If you click on the copy icon beside it, the full SHA-1 is captured in your paste buffer but the first 7 characters are sufficient to identify your base version (before customization) to a mentor

    • The second example is for dev where the fork was synched both before and after customizations were applied

      • Red rectangle labeled 1 is the commit a mentor will recognize
      • Blue dashed rectangle labeled 2 is what GitHub adds when the user successfully syncs the repository - note that the SHA-1 here is specific to this repo and does not help a mentor identify the base version of your build
      • The row above the red rectangle is a customization made prior to the sync
      • The top row (above the blue rectangle) is a customizaiton made after the sync

"},{"location":"gh-actions/edit-browser/#special-cases","title":"Special Cases","text":""},{"location":"gh-actions/edit-browser/#existing-fork-for-module","title":"Existing Fork for Module","text":"

What if you already have a fork of one of the modules?

Your existing fork is from a username other than LoopKit

  • If you know this is a fork you do not care about, you can delete the repository.
  • If you care about this fork, you are probably experienced enough to know how to solve the issue.

Instructions to delete a repository are found at\u00a0GitHub Docs

Once deleted, go to Create Your Fork for Selected Module.

"},{"location":"gh-actions/edit-browser/#background-information","title":"Background Information","text":""},{"location":"gh-actions/edit-browser/#loopworkspace","title":"LoopWorkspace","text":"

The\u00a0LoopWorkspace repository\u00a0is the umbrella organization holding all the pieces needed to build the Loop app. It provides a list of pointers to a specific version for each of the Modules used in the workspace.

  • commit: a specific change to the code identified by the SHA-1; the most recent one indicates the most recent version of the code
  • workspace: a grouping of several repositories (Modules) into a complete package
  • LoopWorkspace: includes a list of the specific SHA-1 for each Module needed for the app

You are telling GitHub to apply specific customizations when it builds your app for you. It extracts from GitHub all the code needed, applies your specific customizations and then starts the build.

"},{"location":"gh-actions/gh-deploy/","title":"Install on Phone","text":""},{"location":"gh-actions/gh-deploy/#general-installation-information","title":"General Installation Information","text":"

This is only available with\u00a0Loop 3.

The Loop app must be built at least every 90 days when using a browser to build.

After you Build the Loop App with a browser and it has automatically uploaded to the TestFlight app, you are ready to install on as many phones as you and your family members need.

  • If you later need to add an adult family member to your list, refer to Set Up Users and Access (TestFlight).

  • Children (under 13 in US, varies by country) cannot use TestFlight with their ID. When you use TestFlight for a Child, you will need to use your ID on their phone (not the whole phone - just the Media & Purchase portion), so send the TestFlight invitation to the email associated with your ID.

"},{"location":"gh-actions/gh-deploy/#install-testflight","title":"Install TestFlight","text":"

If you already have the TestFlight app installed on your phone, skip ahead to Install App with TestFlight.

To install TestFlight, refer to the GIF below:

  • On the phone, open the App Store and Search for TestFlight
  • Install or Download to that phone TestFlight
    • Hint: On child's phone, do this while logged in as yourself for Media & Purchase
    • Logging in as an adult is explained in TestFlight for a Child

"},{"location":"gh-actions/gh-deploy/#install-app-with-testflight","title":"Install App with TestFlight","text":"

Once you get an email that the TestFlight processing completed, you can install the app on your phone. Note this can be half-hour to an hour after the build displays the green check mark on your browser.

The first time you use TestFlight on any phone associated with a given email, you must Redeem the code sent to that email inviting you to test the app. The GIF below is for someone who has never used TestFlight.

  • Initial screen indicates there are no Apps available to test, tap on Redeem
  • Enter your code and tap redeem to enter it
  • Click on OK to acknowledge
  • Click on Install

If you already have the\u00a0Loop\u00a0app on the phone, you'll see the warning about possible loss of data. Don't worry, all your settings remain. Go ahead with the installation.

  • If you are building\u00a0Loop\u00a03.x over\u00a0Loop\u00a02.x, you will be required to go through Onboarding
"},{"location":"gh-actions/gh-deploy/#subsequent-times-on-phone","title":"Subsequent Times on Phone","text":"
  • Open the TestFlight app and find the name you used for your Loop app in the Create Loop App in App Store Connect step
  • Tap on Install
    • If you already have the Loop app installed on this phone, you will be warned that the app already exists on your phone and that you might lose data
    • Click Install again (your pump connection and all your data will be fine)
  • Choose Open
  • Make sure the Loop app is operating as expected
"},{"location":"gh-actions/gh-deploy/#automatic-update-build-install","title":"Automatic Update, Build, Install","text":"

Automatic features will be available when the next version is released and are available now in 3.3.0 (when\u00a0dev is the default branch). The instructions on the Configure to Use Browser page will, unless you make a change, automatically take the following actions when you update to the next release or use dev:

  • Update the version of your\u00a0fork\u00a0within a week of the change
  • Build the app at least once a month and upload to TestFlight

It is already true that, unless you make a change, the default setting will:

  • Install each new build on phone from TestFlight
"},{"location":"gh-actions/gh-deploy/#recommendation","title":"Recommendation","text":"

Recommended settings:

  • Allow automatic update of your\u00a0fork
  • Allow automatic build and upload to TestFlight
  • Disable automatic installation on phone from TestFlight

If you are running the development code, you may prefer to turn off the automatic update, but keep the automatic build. To read more about modifying automatic update and build options, please read Modify Automatic Building.

"},{"location":"gh-actions/gh-deploy/#disable-automatic-install-from-testflight","title":"Disable Automatic Install from TestFlight","text":"

Once the app is installed one time, you can adjust whether it is automatically installed when updated versions are available. We recommend you disable automatic installation so you can choose when to switch to a newer build, which in some cases, may be a newer version.

Go back to the TestFlight app on your phone and tap on your app name in the list to see an expanded screen similar to the graphic below. The row to enable or disable automatic updates is highlighted in the graphic, which shows the feature disabled. This is recommended for all users.

  • If you leave automatic update enabled (default), then whenever a new build is created and uploaded to TestFlight , it will be installed immediately.
  • WARNING: If you switch between Building with Browser and Mac, you must disable automatic update or Xcode will not be able to install to your phone.

When you are ready to install, just open the TestFlight app and click Install to get the most recent build and then click Open when it completes the installation. All your settings and connections to CGM and Pump are maintained.

If you tap on the bottom row that says Previous Builds, highlighted by the dashed-green rectangle, you can view and choose an older build (as long as it has not expired).

"},{"location":"gh-actions/gh-deploy/#testflight-for-a-child","title":"TestFlight for a Child","text":"

The adult (Apple Developer Account owner) can log into Media & Purchase (see steps below) without affecting the child Apple ID associated with a phone (and thus their health records used by\u00a0Loop). After the adult installs or updates the app using TestFlight, they probably should reverse those steps to remove their credentials from Media & Purchase.

Media & Purchase affects access to the App Store, Books, Music and Podcasts.

On the Child phone:

  • Tap on Settings
  • At the very top of Settings, tap on the Name of the phone, for example, my kids phone
  • Apple ID Screen appears
    • Tap on Media & Purchases
    • Tap on Sign Out, and confirm
    • Sometimes the phone requires a reboot before you can sign in with a different ID
  • Sign in with the adult (Apple Developer Account owner) Apple ID and password
  • Install or Update the app from TestFlight on child phone
  • Repeat the process to sign out the adult and (if needed) sign back in the child
"},{"location":"gh-actions/gh-deploy/#change-the-app-store-connect-name","title":"Change the App Store Connect Name","text":"

Suppose you really don't like the name you picked initially for the\u00a0Loop\u00a0app that shows up in the TestFlight app.

You can change it.

Open this link: App Store Connect Apps and log in as needed.

  • Click on your app name.
  • Click on App Information on the left side (make browser wider if you don't see this).
  • Modify the Name under Localizable Information and click on the Save button (upper left)
  • If you chose a name that is in use, you'll see the warning screen - try again
"},{"location":"gh-actions/gh-errors/","title":"Errors with Browser","text":""},{"location":"gh-actions/gh-errors/#help-with-errors","title":"Help with Errors","text":"

If you get an error when building with a browser, use this page to figure out what to do.

If you are still unsuccessful, then post your request for help along with your GitHub username. Mentors can go to your public\u00a0GitHub repository, check the status and then view your log files directly.

  • Do not copy from the log file and post the words
  • Do not take a screenshot of what you think is an error
  • Just post your username and the name of the app you are trying to build

Username, Not Pictures

If you've been around the DIY community for a while, you know the mantra about screenshots. Well, when using a browser to build, screenshots are close to useless.

All that is needed to assist is your GitHub username.

But first - try to diagnose it yourself using this page.

"},{"location":"gh-actions/gh-errors/#most-common-mistakes","title":"Most Common Mistakes","text":"

These are some of the most common errors to date.

  1. You made a spelling error when adding Secrets
    • Each secret must be spelled exactly the way it is presented in the instructions
    • If you are using an automatic translation, please keep an original page open too and copy from it to make sure there are no spelling errors in the secret name
  2. You did not add the App Group Identifier to all 4 of the required identifiers in this step: Add App Group to Identifiers
  3. You used a smart editor instead of a text-only editor to save your information
    • It only takes one letter to be changed from lower-case to upper-case by your smart editor to ruin your day
    • The alpha-numeric values used for GH_PAT, FASTLANE_ISSUER_ID and FASTLANE_KEY contain both upper and lower-case characters and all the values are case-sensitive
  4. When saving TEAMID, you typed what you thought you saw instead of using copy and paste
  5. You skipped running one of the actions
  6. You need to sign a program license agreement or update a credit card at\u00a0Apple Developer
    • Be sure to read Misleading Error Message

If you are running development code, skip ahead to Preview for Next Version.

"},{"location":"gh-actions/gh-errors/#misleading-error-message","title":"Misleading Error Message","text":"

If there are Apple Developer agreements you have not accepted, you may get errors when you try to Build that indicate your Apple Secrets are incorrect even if they are not.

  • The misleading message tells you that one or more of these: FASTLANE_ISSUER_ID, FASTLANE_KEY_ID or FASTLANE_KEY is not correct
  • Check your Apple Developer account for agreements first, before trying to fix those
  • If you previously built successfully - it is almost certainly the agreement
  • It can take 15 minutes to an hour after the agreement is signed before it can be used

If you need detailed instructions, click on this Apple Program License Agreement Help Page.

You can also get this message if the credit card used to purchase the Developer account is not current, e.g., no longer valid or expiration date has passed.

One user reported: The expiration date on the credit card used for auto-renew of my developer account was updated and the value in the Apple account did not match the new one. After updating my account with the new expiration date - Browser Build succeeded again.

"},{"location":"gh-actions/gh-errors/#find-your-error","title":"Find Your Error","text":"

For Version 3.2.3 and earlier - later versions have an improved method for display errors.

There is a separate section for each step in the process. First, you must follow the Examine the Error instructions to view the record of the failed action. Then go to the section for the Action you were trying to complete to look for possible error strings to copy into the search box.

  1. Action: Validate Secrets
  2. Action: Add Identifiers Errors
  3. Action: Create Certificates Errors
  4. Action: Build Loop Errors before a successful build
  5. Repeat Build Loop Errors after a successful build

If you discover a new error, please reach out to help us update the documentation.

"},{"location":"gh-actions/gh-errors/#examine-the-error","title":"Examine the Error","text":"

It doesn't matter which action you are running; after the action completes, you will either see a green check mark for success or a red x mark for failure. The graphic below shows an example for the Add Identifiers action.

If you click on the action name, it opens a secondary screen as shown below.

Click on the top link to view the record of the failed action as shown in the graphic below. You will be pasting strings into the search box (highlighted with a green rectangle) to look for a documented error. Please read the instructions below the graphic.

  • Paste in a possible error string (copy it exactly); repeat until you find a match
  • If the possible error string is found - follow the directions for that error
  • Still stuck?
    • Post for help including your GitHub username
    • With that, mentors can diagnose your problem - or at least make a good guess at what you need to try
    • Please do NOT post a screenshot

Where to find my GitHub username?

You can find it:

  • either in the URL of your fork of Loopworkspace, after github.com in between the forward slashes (/). https://github.com/username/Loopworkspace

  • or on the GitHub website

As your GitHub username is case-sensitive, use copy and paste.

"},{"location":"gh-actions/gh-errors/#action-validate-secrets-errors","title":"Action: Validate Secrets Errors","text":"

To generate the graphic below, some items were deliberately set to be incorrect in the Secrets list. Representative error messages are shown when running the validate secrets action.

"},{"location":"gh-actions/gh-errors/#action-add-identifiers-errors","title":"Action: Add Identifiers Errors","text":"

Use the Examine the Error instructions to find your error message.

There are two errors that we are familiar with at this point. Look for text matching what is listed below and view what has caused this error to be seen.

"},{"location":"gh-actions/gh-errors/#error-credentials-missing-invalid","title":"Error: credentials missing / invalid","text":"

Copy the words on the line below and paste them into the search function for your action log.

Authentication credentials are missing or invalid\n

The full error looks like this:

Authentication credentials are missing or invalid. - Provide a properly configured and signed bearer token, and make sure that it has not expired. Learn more about Generating Tokens for API Requests https://developer.apple.com/go/?id=api-generating-tokens`

This can be caused by an error in the value (or spelling) of one of these keys:

  • FASTLANE_ISSUER_ID
  • FASTLANE_KEY_ID
  • FASTLANE_KEY
  • GH_PAT

Use a Text-Only Editor

If you used a \"smart\" editor when saving your Secrets in an archive file before pasting them into the repository Secrets, it might have changed a lowercase letter to an uppercase letter.

If even one character is capitalized when it should not be, you will not succeed at the Add Identifiers step.

"},{"location":"gh-actions/gh-errors/#error-invalid-curve-name","title":"Error: Invalid curve name","text":"

If you see:

invalid curve name\n

This was caused by an error in the format of the value entered for the FASTLANE_KEY.

Make sure you copy in a text editor from the first hyphen to the last hyphen.

"},{"location":"gh-actions/gh-errors/#action-create-certificates-errors","title":"Action: Create Certificates Errors","text":"

Use the Examine the Error instructions to find your error message.

"},{"location":"gh-actions/gh-errors/#error-wrong-teamid-in-secrets","title":"Error: Wrong TEAMID in Secrets","text":"

Copy the words on the line below and paste them into the search function for your action log.

error: No profile for team '***' matching 'match AppStore\n

If that phrase is found, then:

  • You probably do not have the correct TEAMID entered in your Secrets
  • The rest of these instructions assume:
    • You have already created a Loop App in the App Store with that incorrect TEAMID
    • This is true if you completed the steps after running Action: Add Identifiers and before Action: Create Certificates

Follow these steps:

Open each link below in a separate tab

It is best to open each link below in a separate tab so you can return to this list and keep using the links in each step.

  1. Delete all the identifiers that you can, following the steps in Configure to Use Browser: Delete Identifiers

    • Delete all the other identifiers first, then try to delete the Loop identifier with the wrong TEAMID
    • It is fine to just ignore identifiers with the wrong TEAMID, but do not use them

  2. Enter your TEAMID correctly in the repository Secrets

    • Make sure you use copy and paste from your Apple Developer Membership page for that TEAMID.
    • Follow the update instructions here (this example is for GH_PAT, you'll do the same but for TEAMID) Update Secrets

  3. Run Action: Configure to Use Browser: Add Identifiers again

  4. Follow all the steps in this section with the correct TEAMID Configure to Use Browser: Configure Identifiers for Loop but when you get to the Configure to Use Browser: Create Loop App in App Store Connect, you need to return to this page and follow the instructions below to remove the app and add a new one.

The first time through, you created an app with a Bundle ID that does NOT include your TEAMID.

You will remove that app and create a new one.

"},{"location":"gh-actions/gh-errors/#remove-app-with-incorrect-teamid","title":"Remove App with Incorrect TEAMID","text":"

Go to App Store Connect / Apps and follow the numbered steps in the graphic below.

  1. Find the Loop app you created earlier and click on it
  2. On the left side, under General, click on App Information
    • Confirm that the value listed under Bundle ID is the incorrect one
    • The Bundle ID says: com.NOT_YOUR_TEAMID.loopkit.Loop
  3. Scroll to the bottom of the page and tap on Remove App
  4. The dialog box, similar to the one in the graphic below, should appear and you tap Remove
    • After the App is removed, you'll see a very similar screen, where you can tap on Restore App
  5. But since you want that App removed, tap on Apps at the very top of the screen and proceed to the next step

That App with the wrong Bundle ID remains in the App store but it is hidden so it won't confuse you.

"},{"location":"gh-actions/gh-errors/#add-app-with-correct-teamid","title":"Add App with Correct TEAMID","text":"

Now click on the Add Apps button or the (plus sign) if you have other apps in the App Store.

Follow the Configure to Use Browser: Create Loop App in App Store Connect directions with these additions:

  • You must come up with a new name for your Loop App
  • Triple-check that the Bundle ID you choose is for Loop and contains your TEAMID, it should look like: com.TEAMID.loopkit.Loop
  • You must come up with a new SKU for your Loop App (try 1234, if you used 123 before)
"},{"location":"gh-actions/gh-errors/#create-certificates","title":"Create Certificates","text":"

You should be able to continue with the Configure to Use Browser Steps to Create Certificates and then proceed from there with Build Loop and keep going.

"},{"location":"gh-actions/gh-errors/#error-missing-repository-access","title":"Error: Missing Repository Access","text":"

Copy the words on the line below and paste them into the search function for your action log.

Error cloning certificates\n

The full error looks like this:

Error cloning certificates repo, please make sure you have read access to the repository you want to use

or

Error cloning certificates git repo, please make sure you have access to the repository - see instructions above

If you see this phrase, the fastlane package that is utilized during the 3. Create Certificates action cannot access your repository to create certificates for your Loop app. This is due to insufficient repository access rights that were not granted during the creation of your GH_PAT token.

To fix this error:

  • Open this link: https://github.com/settings/tokens/
  • Here you will see your personal access token (Fastlane Access Token) that was created during Configure to Use Browser: Setup GitHub: Create GitHub Personal Access Token
  • Note that Tokens (classic) is highlighted in the menu on the left
  • Click on the token name (should be bold, blue Fastlane Access Token ) to open its detail page
  • None of the checkboxes under Select Scopes will be checked\u00a0\u2013 this is what's causing the issue.
  • Add a check beside the workflow permission scope (the graphic does not match the words, you want to use workflow to get both repo and workflow scope)
  • Scroll all the way to the bottom and click Update token (it's a long way, ignore all other settings, do not check anything else)

After you have clicked Update token you should see the token overview again with the message Some of the scopes you\u2019ve selected are included in other scopes. Only the minimum set of necessary scopes has been saved. (You can dismiss the message using the X near the upper right side if it appears).

NOTE: for next release or if using the dev branch - you want GH_PAT to have repo, workflow scope. So click on the workflow scope now and save yourself a step later.

"},{"location":"gh-actions/gh-errors/#create-certificates_1","title":"Create Certificates","text":"

You should be able to continue with the Configure to Use Browser Steps to Create Certificates and then proceed from there with Build Loop and keep going.

"},{"location":"gh-actions/gh-errors/#error-could-not-create","title":"Error: Could not create","text":"

Copy the words on the line below and paste them into the search function for your log file.

Could not create another Distribution certificate\n

The full error message is:

Could not create another Distribution certificate, reached the maximum number of available Distribution certificates

These steps are needed to make room for a Certificate:

  1. Delete an old Distribution Certificate
    • Apple limits you to two Distribution Certificates
    • Use this link to view your Apple Developer Certificates
      • Carefully examine the Type column - do not delete a Development Certificate
      • If you accidentally delete a Development Type certificate associated with an Xcode build for your Loop app - it will stop working and you will be very sad
    • Click on the oldest Distribution Certificate and revoke it
      • You will get an email informing you the certificate was revoked
  2. To create a new Certificate:
    • Return to GitHub and your fork
    • Run the Action: Create Certificates
  3. You are now ready to run the Action: Build Loop

But what about TestFlight builds?

Previous builds using this method that are already in TestFlight are not affected by deleting the Distribution Certificate.

"},{"location":"gh-actions/gh-errors/#error-could-not-decrypt","title":"Error: Could not decrypt","text":"

Copy the words on the line below and paste them into the search function for your log file.

decrypt the repo\n

The full error message is:

Couldn't decrypt the repo, please make sure you enter the right password

If you know you entered the incorrect MATCH_PASSWORD in your repository Secrets, go and fix it now and try again.

Otherwise, you need to follow the steps to Reset Match-Secrets.

"},{"location":"gh-actions/gh-errors/#action-build-loop-errors","title":"Action: Build Loop Errors","text":"

Run Create Certificates First

You must run Action: Create Certificates before attempting to run Action: Build Loop

Use Examine the Error

  • Click on the Action log on GitHub
  • There may be a series of green items followed by a red one
  • Click on the red item to view the error
  • Use the search function in this log to locate your error using one of the strings below

For each section below, copy the phrase into the search function of the log. If you find it, solve that error. If not, move on to the next one.

"},{"location":"gh-actions/gh-errors/#could-not-find-an-app-on-app-store-connect","title":"Could not find an app on App Store Connect","text":"

Copy the words on the line below and paste them into the search function for your action log.

Could not find an app on App Store Connect\n

If that phrase is found, then:

  • Make sure you completed the Create Loop App in App Store Connect Step

    • Once you've resolved that step, run these Actions again:
      • Create Certificates
      • Build Loop

  • This can also be caused if you correctly created the Loop App but entered an incorrect value for the TEAMID.

    • If you have the incorrect TEAMID, check this link: Certificates, Identifiers & Profiles for entries with the incorrect TEAMID embedded
    • For example, if your TEAMID is 0123456789, but you entered 000123, you may see both of these in your identifiers list
      • com.0123456789.loopkit.Loop
      • com.000123.loopkit.Loop
    • Delete the \"bogus\" identifier version, fix your TEAMID and rerun all three steps:
      • Add Identifier
      • Create Certificates
      • Build Loop
"},{"location":"gh-actions/gh-errors/#error-provisioning-profile","title":"Error: Provisioning Profile","text":"

Copy the words on the line below and paste them into the search function for your action log.

error: Provisioning profile \"match AppStore\n

If that phrase is found one, or more times, it means you missed a step when configuring the Loop identifier or missed associating your Loop App Group with one or more identifiers.

For example, if you see:

error: Provisioning profile \"match AppStore com.***.loopkit.Loop\" doesn't include the com.apple.developer.usernotifications.time-sensitive entitlement.

Go back to First-Time: Add or Review Configuration for Loop Identifier and make sure you enabled the Time-Sensitive notification for Loop.

For example, you might see:

  • error: Provisioning profile \"match AppStore com.***.loopkit.Loop.SmallStatusWidget
  • error: Provisioning profile \"match AppStore com.***.loopkit.Loop.statuswidget
  • error: Provisioning profile \"match AppStore com.***.loopkit.Loop.Loop-Intent-Extension

Return to Add App Group to Other Identifiers and fix the missing items.

You must create certificates again before you can build Loop:

  • Action: Create Certificates
  • Action: Build Loop
"},{"location":"gh-actions/gh-errors/#a-new-one-cannot-be-created-because-you-enabled","title":"A new one cannot be created because you enabled","text":"

Copy the words on the line below and paste them into the search function for your action log.

A new one cannot be created because you enabled\n

If that phrase is found with lines similar to the following:

[31mA new one cannot be created because you enabled `readonly`\u001b[0m\n[31mProvisioning profiles in your repo for type `appstore`:\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.statuswidget.mobileprovision'\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.SmallStatusWidget.mobileprovision'\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.mobileprovision'\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.LoopWatch.mobileprovision'\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.Loop-Intent-Extension.mobileprovision'\u001b[0m\n[31m- 'AppStore_com.NOT_YOUR_TEAMID.loopkit.Loop.LoopWatch.watchkitextension.mobileprovision'\u001b[0m\n

This tells you, the Bundle ID you selected in First-Time: Create Loop App in App Store Connect does NOT have your TEAMID embedded in the name.

Once you have created an app in the App Store that is not based on your TEAMID, you cannot delete it, but you can Remove it (i.e. hide it so that it is no longer visible on this page and you don't accidentally click on it).

  1. Open this link: App Store Connect / Apps to view your apps; log in if needed.
  2. Find the App with the wrong Bundle ID and click on it
  3. On the left-hand side, click on App Information (under General)
    • Confirm the Bundle ID listed does not include your TEAMID
    • Scroll all the way to the bottom
    • Tap on Remove App
    • New dialog window appears, select Remove

At this point, get your correct TEAMID, fix your Secrets file to have the correct TEAMID and then return to First-Time: Configure Secrets. This time you will be updating TEAMID in the repository secret list.

"},{"location":"gh-actions/gh-errors/#repeat-build-loop-errors","title":"Repeat Build Loop Errors","text":"

This section is only for people who have successfully built using GitHub Build Actions.

Use the Examine the Error instructions to find your error message.

"},{"location":"gh-actions/gh-errors/#could-not-install-wwdr-certificate","title":"Could not install WWDR certificate","text":"

Assuming you have successfully built using the Browser-Build / GitHub method before:

  • If the details show this message, Could not install WWDR certificate, make sure your Apple developer account is in good standing and that there are no agreements that need to be accepted
  • Sometimes this is a sign that Apple did not respond to a request, this failure happens in the first few minutes
    • Repeat the build and it should be fine the next time

"},{"location":"gh-actions/gh-errors/#reset-match-secrets","title":"Reset Match-Secrets","text":"

This is not the first thing to try, but sometimes it is the best approach.

There might be several reasons to do this:

  • You lost your MATCH_PASSWORD and want to build one of the Other Apps
  • You thought you entered the correct MATCH_PASSWORD but you are getting Error: Could not decrypt
  • You are having trouble renewing your certificates after using Browser Build for a year

These steps are needed to reset your Match-Secrets:

  1. Delete your Match-Secrets Repository
    • Instructions to delete a repository are found at GitHub Docs
  2. Create a new private Match-Secrets Repository
    • main branch: follow the directions First-Time: Create Match-Secrets
    • dev branch: the Action: Validate Secrets automatically creates a new private Match-Secrets repository if you don't have one
  3. In your fork of LoopWorkspace:
    • Run the Action: Create Certificates
    • If this fails, click on this link for the most likely Error: Could not create
    • If that doesn't help, check all your Secrets and try again
  4. You are now ready to run the Action: Build Loop

Other Apps

All DIY iOS apps that have an associated GitHub Browser Build method require the same 6 Secrets.

If you add an app to your GitHub username (by forking the repository and adding Secrets) and then build it, it encrypts your Certificate using MATCH_PASSWORD.

If you already have the other apps configured and then you delete Match-Secrets and add a new one, you will need to run Create Certificates for each app before the next time you build each app - go ahead and do that now so you don't forget.

"},{"location":"gh-actions/gh-errors/#preview-for-next-version","title":"Preview for Next Version","text":"

Error annotations are available for Version 3.3.0 and later. These were contributed by community volunteers along with the improvements to enable automatic updates and automatic builds.

"},{"location":"gh-actions/gh-errors/#examine-annotation","title":"Examine Annotation","text":"

If a\u00a0GitHub Action\u00a0fails, you will see a clear notification.

First consider the following results from the\u00a0GitHub Action: 1. Validate Secrets.

Your screen may look similar to the graphic below. The name in parentheses refers to the branch used to develop these wonderful messages. Yours may be (dev) or (main), once 3.4.0 is released.

But there are so many reasons why this could happen. The first step is to click on the link highlighted by the red rectangle in the graphic above. This opens a new detailed view. The GIF below shows two different error messages. The first frame shows the error in the Annotation box at the bottom (you may need to scroll down to see this), and you may need to click on \"Show More\" to see the full message as seen in the second frame. The third frame of the GIF shows a different message. Each one these messages is designed to make it easier for you to diagnose your own problem.

Notice that\u00a0GitHub Action: 1. Validate Secrets\u00a0is broken into three jobs each of which will either pass and show a green check or fail and show a red check. The secrets are validated with each action, so you will see this a lot.

For example, the graphic below shows a failure of\u00a0GitHub Action: 3. Create Certificates\u00a0.

This is an example of a message that is not terribly descriptive - which is why it is shown here. In this case, you can click on just the one job that failed. There will be less to sort through to find your error. The most likely reason for this error is Error: Could not Create.

If you run across an error that does not have a nice message, be sure to post as discussed in Help with Errors. You may be contributing to future improvements for this process.

"},{"location":"gh-actions/gh-first-time/","title":"Configure to use Browser","text":""},{"location":"gh-actions/gh-first-time/#build-the-loop-app-using-github","title":"Build the Loop App using GitHub","text":"Time Estimate (click to open/close)
  • If you have never built the Loop app (allow up to one week elapsed time)
    • Request and get an Apple Developer Account: 1-2 days
    • Create and configure your GitHub account and repositories: 1-2 hours
    • Add Secrets (requires Apple Developer Account): 1 hour
    • Perform the GitHub Action steps: 30 minutes to 2 hours
  • If you have previously built the Loop app with Xcode you have fewer steps and are probably familiar with some of the concepts
    • Expect 1 to 4 hours
Page Summary with Links (click to open/close)

There is a lot of introductory information on this page.

  • You can skip some sections but please read this one: Save Your Information

A narrated video is available:

  • How to Build the Loop App With a Web Browser

Once you have Apple Developer and GitHub accounts, the steps below are a high-level summary with links to the detailed section of this LoopDocs page.

You can think of the first part as a scavenger hunt where you find or generate and save six Secrets.

  • Apple:
    • Collect the four Apple Secrets
  • GitHub:
    • Collect the GH_PAT Secret
  • Make up a Password

Now it's time to use those Secrets to build the Loop app

  • GitHub:
    • Create a Match-Secrets private repository
    • Fork a repository (copy of LoopWorkspace)
    • Add Secrets to your copy of LoopWorkspace repository
    • Action: 1. Validate Secrets
    • Action: 2. Add Identifiers
  • Apple:
    • Configure Identifiers for Loop
    • Create your version of Loop in App Store (personal use only, not for distribution)
  • GitHub:
    • Action: 3. Create Certificates
    • Action: 4. Build Loop
  • Apple: Set up Internal TestFlight Group
  • Phone: Install the Loop app using the TestFlight app
FAQs (click to open/close)
  • Do I need a Mac computer? No. This can be done on any browser, although it will be easier using a computer or tablet than just using a phone.
  • Can I do this on my phone? Yes, but the graphics shown on this page are from a computer browser.
  • Isn't it hard to build every 90 days? The initial setup and installation take a lot of your focused time. But once you build once, subsequent builds take very little of your time to start the build. The rest is done automatically.
  • Can I use this for my child? You, as the adult, can install using TestFlight on your child's phone. The explicit steps are provided at Install on Phone: TestFlight for a Child.
  • Can I still use my customizations? Yes. Customize using Browser
  • Is there a build video? Yes. How to Build the Loop App With a Web Browser
"},{"location":"gh-actions/gh-first-time/#tips-and-tricks","title":"Tips and Tricks","text":"

This page contains fully detailed steps including graphics, which makes it incredibly long.

Responding to a user request, step number indicators were added to this page.

  • If you do not understand a step, back up a step or substep and review the material again
  • If you learn better watching a video, you may find this video useful as an accompaniment to your building journey
    • How to Build the Loop App With a Web Browser

Some sections have a Section Summary:

  • To view the summary, click on the summary header
  • If the summary is all you need, use the skip forward symbol () to skip to the next instruction
  • Or follow the detailed instructions below the summary

An automatic table of contents (TOC) should appear for each page on the right side of your browser (if the browser is \"wide\" enough). If not, tap on the hamburger menu (upper left) and then this page name to see the TOC.

For sparse instructions, click on the link below:

  • LoopWorkspace Build Instructions
"},{"location":"gh-actions/gh-first-time/#how-to-video-to-build-with-a-browser","title":"How-to Video to Build with a Browser","text":"

In addition to this page, there is a narrated video of each step needed to build using a browser.

  • How to Build the Loop App With a Web Browser

Click in the comments for a full index of topics. If you have issues with a part of this page, use the index to advance to the relevant part of the video. Subtitles are in English. You can choose a different language but the automatic translation feature may provide translations that are not completely accurate.

"},{"location":"gh-actions/gh-first-time/#step-1-of-12","title":"Step 1 of 12","text":"

Step 1 of 12 is Prerequisites, things you must complete before you start.

"},{"location":"gh-actions/gh-first-time/#prerequisites","title":"Prerequisites","text":""},{"location":"gh-actions/gh-first-time/#prerequisites-to-build-the-loop-app","title":"Prerequisites to Build the Loop App","text":"

There are two prerequisites to build the Loop app using GitHub Browser Build.

  1. Paid Apple Developer account ($99/year)
  2. Free GitHub account
"},{"location":"gh-actions/gh-first-time/#prerequisites-to-install-loop","title":"Prerequisites to Install Loop","text":"

To install Loop, you need the free TestFlight app, from the Apple App Store, installed on your Compatible Phone.

"},{"location":"gh-actions/gh-first-time/#prerequisites-to-use-loop","title":"Prerequisites to Use Loop","text":"

To use Loop, you need a Compatible Pump and Compatible CGM. For pumps other than Omnipod DASH, you also need a RileyLink Compatible Device.

"},{"location":"gh-actions/gh-first-time/#new-terms-with-github-browser-build","title":"New Terms with GitHub Browser Build","text":"

You can read details about new terms with GitHub build or skip ahead to Save Your Information.

The GitHub Browser Build may use new and unfamiliar terms.

Some of these terms have ToolTips, so hover your mouse over those - or review them in the Glossary.

  • Some terms in the Glossary are not in alphabetical order. All the Secrets discussed on this page, are listed after Secrets in the Glossary.

If this summary of terms is confusing, finish reviewing the whole page and then come back.

  • Actions: available in your GitHub account to build your app (once you follow the instructions on this page)
    • With Loop 3, the actions: Validate Secrets, Add Identifiers, Create Certificates, and Build Loop enable users to build the Loop app from a browser on any computer
    • If GitHub Browser Build Actions are not operating as you expect, check GitHub Status to see if it is GitHub problem.
  • Secrets: are required to enable GitHub to build the Loop app using GitHub Actions
    • Six Secrets must be added to your fork of LoopWorkspace
    • These Secrets work for any branch in your fork (main or dev, for example)
    • These Secrets can be added to Other Apps configured with the same GitHub Browser Build method
    • For those who feel confident using GitHub, there are optional instructions to configure a free organizational account (for your personal use) that allows you to enter the Secrets only once, see Use a GitHub Organization Account, and have them available for every repository in that organization account
  • API Key:Application Programming Interface Key
    • You obtain and save this key from the Apple Developer website
    • Doing this provides 3 of your Secrets
    • It is required to enable your GitHub account to interface with Apple to create your app
  • Identifiers: are required to build the Loop app with GitHub Browser Build (these are automatically generated for you)
    • Four Identifier Names must be associated with your App Group
      • Loop, Loop Intent Extension, Loop Status Extension and Small Status Widget
      • For the dev branch only: Small Status Widget was renamed Loop Widget Extension
    • Two Identifier Names will exist but do not require that association
      • WatchApp and WatchAppExtension
    • The Identifier screen, has NAME and IDENTIFIER columns
      • If you previously built with Xcode, the items in the NAME column may start with XC
      • The items under the IDENTIFIER column match the table in Add App Group to Identifiers
  • App Store Connect: a website available for Apple Developers to review apps build with your Apple Developer account
    • Once you purchase an Apple Developer annual account, you are an Apple Developer and have access to this site
    • Most Loopers will not have an App until using the GitHub Browser Build
    • The instructions walk you through creating and naming your app: Create Loop App in App Store Connect
"},{"location":"gh-actions/gh-first-time/#save-your-information","title":"Save Your Information","text":"

Everyone needs to read this section!

You need to keep a digital copy of your 6 Secrets.

  • You need to copy and paste those Secrets to build the app with a browser
  • Make sure your editor does not change any characters in your Secrets; use a text-only editor like NotePad (PC) or TextEdit (Mac)
  • Many people add other information to the Secrets file for easy reference

Archive Your Information

To complete the steps on this page, you will need a username, email address, and password for Apple and GitHub. You will find, generate or make up six Secrets as instructed.

  • Record this information in a safe place where you can find them
  • A digital copy is best for copying and pasting in different locations

Be sure to use a Text-Only editor like NotePad (PC) or TextEdit (Mac) to archive your information.

A Note about Capitalization and Spaces

In places, you use a name like \"FastLane API Key\" or \"FastLane Access Token\". Please copy from the docs to use those exact names.

The Secrets that you add use names that are capitalized and use underscore _ instead of spaces. Be precise and careful.

Use a Text-Only Editor

Be sure to use a Text-Only editor like NotePad (PC) or TextEdit (Mac) to archive your information.

If you use a \"smart\" editor, it may change lower-case letters to upper-case letters at the beginning of a line when you paste items into your archive file.

If even one character is capitalized when it should not be, you will get Errors with Browser Build.

If you use a smart editor to store your FASTLANE_KEY, you are likely to get the mysterious invalid curve name error.

"},{"location":"gh-actions/gh-first-time/#step-2-of-12","title":"Step 2 of 12","text":"

Step 2 of 12 is Save Six Secrets.

The creation of accounts at Apple and GitHub, if you don't already have them, are not numbered. Using those accounts, there are 5 Substeps for Step 2.

"},{"location":"gh-actions/gh-first-time/#save-six-secrets","title":"Save Six Secrets","text":"Section Summary (click to open/close)

You require 6 Secrets (alphanumeric items) to use the GitHub Browser Build method and if you use the GitHub Browser Build method to build more than Loop, e.g., Loop Follow or Loop Caregiver, you must use the same 6 Secrets for each app you build with this method.

Each secret is identified with ALL_CAPITAL_LETTER_NAMES.

  • Four Secrets are from your Apple Account
  • One Secret is from your GitHub account
  • One Secret is a password you make up and save
  • Be sure to save the 6 Secrets in a text file using a text editor
    • Do NOT use a smart editor, which might auto-correct and change the case, because these Secrets are case-sensitive
    • Refer back to Save Your Information for more details about smart vs text editors

To skip the detailed instructions, click on Collect the Four Apple Secrets

You need to save your information digitally, so you can copy and paste. The information is created in one place and used in another. Refer to Configure Secrets for how the Secrets are used. In addition to the 6 Secrets, other important information to keep handy (like usernames and passwords) is listed below. Be sure to keep this file secure.

Created at developer.apple.com

  • Email address (this is your username)
  • password
  • Four items used as Secrets
    • TEAMID
    • FASTLANE_ISSUER_ID
    • FASTLANE_KEY_ID
    • FASTLANE_KEY

Created at github.com

  • Email address
  • password
  • username
  • Your GitHub repository address will be: https://github.com/username
  • Your LoopWorkspace repository address will be: https://github.com/username/LoopWorkspace
  • One item used as a Secret
    • GitHub Personal Access Token (GH_PAT)

Created yourself

  • a password - make one up and save it (MATCH_PASSWORD)
"},{"location":"gh-actions/gh-first-time/#collect-the-four-apple-secrets","title":"Collect the Four Apple Secrets","text":"Section Summary (click to open/close)

You will be saving 4 Secrets from your Apple Account in this step.

  1. Sign in to the Apple Developer portal page.
  2. If you need to accept a new agreement (happens about twice a year), be sure to do so now
    • Need help? Look at this section on the update page: Accept Agreements
  3. Copy the Team ID from the upper right of the screen. Record this as your TEAMID.
  4. Go to the App Store Connect interface, click the \"Integrations\" tab, and create a new key with \"Admin\" access. Give it the name: \"FastLane API Key\".
  5. Record three more secrets
    • Record the issuer id; this will be used for FASTLANE_ISSUER_ID.
    • Record the key id; this will be used for FASTLANE_KEY_ID.
    • Download the API Key itself, and open it in a text editor. The contents of this file will be used for FASTLANE_KEY. Copy the full text, including the \"-----BEGIN PRIVATE KEY-----\" and \"-----END PRIVATE KEY-----\" lines.

To skip the detailed instructions, click on Collect the GH_PAT Secret

This section provides detailed instructions for the four Secrets associated with your Apple Developer ID.

Name Description TEAMID This 10-character identifier is associated with your Apple Developer ID and never changes FASTLANE_ISSUER_ID The issuer ID is associated with your Apple Developer ID and never changes FASTLANE_KEY_ID Key ID provided when you create an API Key in App Store Connect; it is associated with the FASTLANE_KEY FASTLANE_KEY Copy the full key from the text file you downloaded when generating the API Key - Filename has FASTLANE_KEY_ID value embedded in it.Include everything in the file from -----BEGIN PRIVATE KEY-----and ending in -----END PRIVATE KEY-----"},{"location":"gh-actions/gh-first-time/#new-apple-developer-account","title":"New Apple Developer Account","text":"

If you have an Apple Developer Account, skip ahead to Find TEAMID.

If not, you need to purchase one ($99 annual fee). It may take a few days for the account to be enabled.

  • LoopDocs has an Apple Developer Program page that explains in detail how to sign up for an account
  • This link takes you straight to Apple Developer account to sign up
"},{"location":"gh-actions/gh-first-time/#substep-21-for-step-2","title":"Substep 2.1 for Step 2","text":"

Next section, Find TEAMID, is Substep 1 out of 5 for Step 2.

"},{"location":"gh-actions/gh-first-time/#find-teamid","title":"Find TEAMID","text":"

Sign in to your Apple Developer account at this link: Apple Developer portal page.

  1. Click Account in the top menu bar
  2. If you need to accept a new agreement (happens about twice a year), be sure to do so now
    • Need help? Look at this section on the update page: Accept Agreements

  3. Click the Membership Details icon

  4. Next to the Team ID field, is a 10-character ID number. This is your Apple Developer TEAMID.

Record this for use as TEAMID in your Secrets file. You will also need it when you Create \u00a0App Group.

  • Stop a moment and double-check

  • If you get this wrong, you will have errors at the very end, which require you to delete some items and repeat some steps on this page

    Do not \"type\" what you think you see

    Copy and paste the Team ID from the webpage.

    • TEAMID must be 10 characters
    • Avoid typing an\u00a08\u00a0when it should be a\u00a0B
"},{"location":"gh-actions/gh-first-time/#substep-22-for-step-2","title":"Substep 2.2 for Step 2","text":"

Next section, Generate API Key, is Substep 2 out of 5 for Step 2.

"},{"location":"gh-actions/gh-first-time/#generate-api-key","title":"Generate API Key","text":"

Paid Apple Developer Account is Required

To generate the API Key, you must have a paid Apple Developer account.

If you are waiting for Apple to enable your account, you can skip ahead to create a New GitHub Account and Create GitHub Personal Access Token. You then pause at Configure Secrets until your Apple account is active.

  1. Click this link to open in a new tab: App Store Connect/Access/Integrations/API

    • The top of the display is shown in the graphic below

    • Click the Integrations tab as indicated in the graphic above

      • If this is your first time here, you will see:

        \"Permission is required to access the App Store Connect API. You can request access on behalf of your organization.\"

        • Click on Request Access and follow directions until access is granted

      • Once access is granted, click on the Generate API Key button

    • If you did not get routed through the permission is required screens click the blue + sign

    • A new Generate API Key dialog box will appear as shown in the graphic below

    • Enter the name of the key as \"FastLane API Key\" and choose Admin in the access drop-down menu
    • Confirm the name and that \"Admin\" is selected and then click on the \"Generate\" button.
"},{"location":"gh-actions/gh-first-time/#substep-23-for-step-2","title":"Substep 2.3 for Step 2","text":"

Next section, Copy API Key Secrets, is Substep 3 out of 5 for Step 2. In this Substep you are dealing with 2 of the Apple Secrets.

"},{"location":"gh-actions/gh-first-time/#copy-api-key-secrets","title":"Copy API Key Secrets","text":"

The Integrations screen appears again with content similar to the graphic below; the key information is blanked out for security.

Review the graphic and then follow the directions below to save more parameters you will need to Configure Secrets

  1. A button labeled Copy is always adjacent to the Issuer ID above the word Active (this is the same for all keys that you generate with this Apple Developer ID)
    • Tap on the Copy button - this copies the Issuer ID into your paste buffer
    • In the file where you are saving information, paste this with the indication that it is for FASTLANE_ISSUER_ID
  2. Hover to the right of the Key ID and the Copy Key ID button shows up
    • Tap on the Copy Key ID button - this copies the Key ID into your paste buffer
    • In the file where you are saving information, paste this with the indication that it is for FASTLANE_KEY_ID

  3. Click on the Download API Key button - you will be warned you can only download this once.

  4. Find your AuthKey download in your downloads folder. The name of the file will be \"AuthKey_KeyID.p8\" where KeyID matches your FASTLANE_KEY_ID

    • Double-click to open it and you will be presented a message asking how you'd like to open it (The message shown is for a Mac - translate these directions to whatever computer you are using)
    • Click on \"Choose Application...\" and then select \"TextEdit\" (on a Mac, NotePad on a PC, or any text-only editor you prefer)

  5. The contents of this file will be used for FASTLANE_KEY

    • Copy the full text, including the \"-----BEGIN PRIVATE KEY-----\" and \"-----END PRIVATE KEY-----\" lines
      • On a Mac, use Cmd+A, then Cmd+C to copy all the contents
      • On a PC, use Ctrl+A , then Ctrl+C to copy all the contents
    • In the file where you are saving information, paste this with the indication that it is for FASTLANE_KEY

"},{"location":"gh-actions/gh-first-time/#do-not-confuse-your-keys","title":"Do Not Confuse Your Keys","text":"

API Key\u00a0 vs\u00a0APN Key

If you use Remote Commands with Nightscout, you may notice the Application Programming Interface (API) key has the same type of format as the Apple Push Notification (APN) key. The keys for both of these purposes are p8 keys, but they should not be confused with each other.

The Secrets for building with GitHub use the\u00a0API Key.

The config vars for Nightscout use the\u00a0APN Key.

  • If you are using remote commands with Nightscout and building with GitHub Browser Build
    • Remote Commands Config Vars: make sure you have a config var of LOOP_PUSH_SERVER_ENVIRONMENT with a value of production or remote commands will not work with Nightscout
  • This is true for using Nightscout directly or using Loop Caregiver
"},{"location":"gh-actions/gh-first-time/#done-with-apple-secrets","title":"Done with Apple Secrets","text":"

In summary, from this section, you have found or generated the following and saved copies for later use

  • TEAMID
  • FASTLANE_ISSUER_ID
  • FASTLANE_KEY_ID
  • FASTLANE_KEY

Time for a Break?

This is a good place to pause if you need to. Just note where you are on the page so you can return later.

"},{"location":"gh-actions/gh-first-time/#collect-the-gh_pat-secret","title":"Collect the GH_PAT Secret","text":"

If you already have a GitHub Account, skip ahead to Create GitHub Personal Access Token.

"},{"location":"gh-actions/gh-first-time/#new-github-account","title":"New GitHub Account","text":"

If you do not already have a GitHub account, you need to create one. Be sure to record the email, password, and username for your GitHub account.

Decide on a couple of usernames that you will be happy with - this will get embedded into your GitHub URL. Your first choice might not be available, so be prepared with several candidates. Your personal URL will be: https://github.com/username.

  • Click on this link to sign up for a free account: GitHub account signup
    • You will need to enter the email you want associated your GitHub account
    • You will be asked to enter a password
    • You will be asked to enter a username
    • You will be asked if you want to receive email, ok to say N for no - you still get important account information with that email
    • Solve the puzzle to prove you're a person
    • Check the associated email to get the code and enter the code into github.com to confirm your account
  • You should get the Welcome to GitHub screen
    • Indicate it is \"Just me\" on your team and Continue
    • Don't check anything on the next screen, just tap Continue
    • Select the Free option by selecting Continue for Free

The free level comes with plenty of storage and compute time to build the Loop app.

"},{"location":"gh-actions/gh-first-time/#substep-24-for-step-2","title":"Substep 2.4 for Step 2","text":"

Next section, Create GitHub Personal Access Token, is Substep 4 out of 5 for Step 2.

"},{"location":"gh-actions/gh-first-time/#create-github-personal-access-token","title":"Create GitHub Personal Access Token","text":"Section Summary (click to open/close)

Log into your GitHub account to create a personal access token, which you will save as GH_PAT.

Click to create a new personal access token:

  • Enter a name for your token, use \"FastLane Access Token\"
  • Change the Expiration selection to No expiration
  • Select the workflow permission scope (repo will be automatically selected)
  • Click \"Generate token\"
  • Copy the token and record it. It will be used below as GH_PAT

To skip the detailed instructions, click on Make up a Password.

You must be logged into your GitHub account before starting this step. If you are continuing, you are already logged in.

  1. You will be creating a new GitHub Personal Access Token and giving it the name \"FastLane Access Token\"

  2. Open this link: https://github.com/settings/tokens/new

    • Referring to the graphic
      • Note that Tokens (classic) is highlighted
      • Most Looper will use the classic Token
        • If you are a developer who needs to use fine-grained tokens, that is fine
      • Edit the note box to be FastLane Access Token
    • The default Expiration time is 30 days - but you should select No expiration (use the drop-down menu to select)
      • GitHub will show a yellow warning when you do this
      • It is ok to ignore the warning
    • Add a check beside the workflow permission scope
    • A check will automatically appear in the repo scope as well - this is normal
    • Scroll all the way to the bottom and click Generate token (it's a long way, ignore all other settings, do not check anything else)

  3. A new screen appears showing your access token

    • Copy the token and record it - once you leave this screen you can't see it again
    • You will use this for GH_PAT when you set up your Secrets
    • You can Regenerate Personal Access Token for GH_PAT if you lose it, but then you have to update that in the Secrets for all repositories using GitHub Build.

"},{"location":"gh-actions/gh-first-time/#substep-25-for-step-2","title":"Substep 2.5 for Step 2","text":"

Next section, Make up a Password, is Substep 5 out of 5 for Step 2.

"},{"location":"gh-actions/gh-first-time/#make-up-a-password","title":"Make up a Password","text":"

If you have not already made up a password, do it now and record it as MATCH_PASSWORD.

"},{"location":"gh-actions/gh-first-time/#step-3-of-12","title":"Step 3 of 12","text":"

Step 3 of 12 is Prepare your Repositories. This step has 2 Substeps.

"},{"location":"gh-actions/gh-first-time/#prepare-your-repositories","title":"Prepare your Repositories","text":""},{"location":"gh-actions/gh-first-time/#substep-31-for-step-3","title":"Substep 3.1 for Step 3","text":"

Next section, Create Match-Secrets, is Substep 1 of 2 for Step 3. This is done only one time for a given GitHub username.

"},{"location":"gh-actions/gh-first-time/#create-match-secrets","title":"Create Match-Secrets","text":"Section Summary (click to open/close)

The creation of the Match-Secrets repository is a common step for all GitHub Browser Builds; do this step only once. You must be logged into your GitHub account.

Click on the link to create a new empty repository titled Match-Secrets. It should be private.

Once created, you will not take any direct actions with this repository; it needs to be there for GitHub to use as you progress through the steps.

To skip the detailed instructions, click on Fork LoopWorkspace

Open your github.com URL (this is https://github.com/username), (username is the name you chose above).

Create a new private repository - you can either click on the link below or follow the instructions with the first graphic:

  • Click on this link: https://github.com/new

or

  • At the top right of the screen, click on the + sign and select New Repository

This shows you a screen similar to the following graphic which has 3 regions highlighted:

  • In Repository name, type Match-Secrets (use a hyphen between Match and Secrets)
  • Be sure to check the box Private (red circle) to make the repository private
  • Please confirm you selected the Match-Secrets repository as private.
  • Scroll to the bottom of the page and tap on \"Create repository\"

A screen will appear with a lot of options - do not do anything on this screen.

  • Click on your username (as indicated by the red rectangle) to return to your main GitHub URL.

You will not directly interact with your Match-Secrets repository.

"},{"location":"gh-actions/gh-first-time/#substep-32-for-step-3","title":"Substep 3.2 for Step 3","text":"

Next section, Fork LoopWorkspace, is Substep 2 out of 2 for Step 3.

If you are creating an app other than the Loop app, you substitute the appropriate URL for the app you are building.

"},{"location":"gh-actions/gh-first-time/#fork-loopworkspace","title":"Fork LoopWorkspace","text":"Section Summary (click to open/close)

Fork https://github.com/LoopKit/LoopWorkspace into your account.

To skip the detailed instructions, click on Configure Secrets

Existing Fork

If you already have a fork of LoopWorkspace, click on Already Have LoopWorkspace to decide what to do. That section provides links to return you to these instructions.

  1. Open this link https://github.com/LoopKit/LoopWorkspace to open the LoopWorkspace repository owned by LoopKit.
  2. Review the highlighted locations of the graphic below (yours won't look quite like this yet, but the Fork button is in the same place)
  3. At the upper right side of the screen, click on the word Fork
    • If you already have a fork, you cannot proceed, see Already Have LoopWorkspace

  4. Now your screen should look like the graphic below

    • Your username will be automatically filled in as the owner (Owner)
    • LoopWorkspace is the repository name (Repository Name)
    • Leave the selection that says \"Copy the main branch only\" checked
    • Click on the green Create fork button

"},{"location":"gh-actions/gh-first-time/#successful-fork","title":"Successful Fork","text":"

After creating the \u00a0fork, your screen should be similar to the next graphic - it will say main for the branch instead of dev because this graphic was prepared before the release of Loop 3. You may or may not see the messages you are told to dismiss in the next two bullets. No worries if you don't see them.

  • Near the top right, click on the close button (x) to dismiss the Successfully fetched message
  • In the middle, click on the Dismiss button to remove the \"Your branch is not protected\" message

Carefully compare your screen to the graphic below paying attention to the highlighted sections.

  • Note that your username is now showing
  • The comment under your username indicates where the \u00a0fork\u00a0 came from (that is a clickable link)
  • The branch that is selected is main
  • The message says \"This branch is up to date with LoopKit/LoopWorkspace:main\"

Time for a Break?

This is a good place to pause if you need to. Just note where you are on the page so you can return later.

"},{"location":"gh-actions/gh-first-time/#step-4-of-12","title":"Step 4 of 12","text":"

Step 4 of 12 is Configure Secrets. This step does not have Substeps, however, you must enter all 6 SECRETS.

Feeling confident? Planning to build more than one app? Click to see more.

If you are already feeling overwhelmed - skip this tip.

If you plan to build more that one app, you will making a fork of each repository associated with each app, and then you must add the 6 Secrets to each repository. It is not hard but it can get tiresome.

There is a way to enter the 6 Secrets only one time for all your repositories, but this requires setting up a free GitHub organization. This is also not hard, but it modifies some of displays you see on GitHub. If you are interested, refer to Use a GitHub Organization Account

"},{"location":"gh-actions/gh-first-time/#configure-secrets","title":"Configure Secrets","text":"Section Summary (click to open/close)

These Secrets are the same for any repository for which you use GitHub Browser Build.

  • They are added once for a repository and work for all branches of that repository
  • They must be added to any other repository, such as Loop Caregiver, for which you also use GitHub Browser Build

For each of the following Secrets, tap on \"New repository secret\", then add the name of the secret, along with the value you recorded for it:

  • TEAMID
  • FASTLANE_ISSUER_ID
  • FASTLANE_KEY_ID
  • FASTLANE_KEY
  • GH_PAT
  • MATCH_PASSWORD

To skip the detailed instructions, click on Validate Secrets.

Branches and Repositories

  • These \u00a0Secrets\u00a0 are added to your fork of LoopWorkspace and work for any branch (main or dev, for example)
  • These \u00a0Secrets\u00a0 must be added, if desired, for Other App repositories
"},{"location":"gh-actions/gh-first-time/#prepare-to-enter-secrets","title":"Prepare to Enter Secrets","text":"

Log into GitHub.

  1. Return to your forked copy of LoopWorkspace

    • Click on your personal icon at the upper right to see the drop-down menu and select \"Your repositories\"

  2. You should see (at least) 2 repositories: Match-Secrets and LoopWorkspace

  3. Click on LoopWorkspace to open that repository

  4. Click on the Settings Icon near the top right of your LoopWorkspace

    • If you don't see \u2699\ufe0f Settings, make your browser wider or scroll to the right
    • If you still don't see \u2699\ufe0f Settings, then you are not on your fork or you need to sign in to your GitHub account

    • After you click on \u2699\ufe0f Settings, your screen should look like the graphic below

  5. On the left side, find the Secrets and variables dropdown and choose Actions

    • After you select Actions, your screen should look like the graphic below

"},{"location":"gh-actions/gh-first-time/#enter-the-secrets","title":"Enter the Secrets","text":"
  1. Tap on the green button at the top right of your screen labeled New repository secret (highlighted above)
    • A new screen appears as shown in the first graphic below
    • Do not do anything until reading the sub-bullets, examining the graphics, and proceeding to the next section where each Secret name is provided for you to copy and paste
      • Under Name *, click on YOUR_SECRET_NAME and paste one of the 6 secret names, as directed in Enter Each Secret
      • Click inside the Secret * box and paste the value for that secret
      • Once you click on Add Secret, the secret will be added
      • The second graphic below shows TEAMID added and ready for save
"},{"location":"gh-actions/gh-first-time/#enter-each-secret","title":"Enter Each Secret","text":"

Enter the name of each Secret found in Save Your Information and your value for that Secret.

  • Once you save a secret value, you will not be able to view what you entered, so check carefully before you hit Add Secret
    • You can replace the value for any secret later - but you can't view the saved value
  • Be especially careful with your TEAMID
    • If TEAMID is incorrect, the initial Actions will succeed but Build Loop will fail and you will have some clean-up to do

You can copy the names of the Secrets by hovering to the right of each word below until you see the copy button (). Click on the button to copy the Secret name and paste it into GitHub where you see YOUR_SECRET_NAME. This avoids spelling errors. 

TEAMID\n
FASTLANE_ISSUER_ID\n
FASTLANE_KEY_ID\n
FASTLANE_KEY\n
GH_PAT\n
MATCH_PASSWORD\n

  • For the FASTLANE_KEY value, copy the entire contents from-----BEGIN PRIVATE KEY----- through-----END PRIVATE KEY-----
  • For MATCH_PASSWORD value - if you did not already make up a password and save it with your other Secrets, do it now
    • The MATCH_PASSWORD must be the same for any repository using this method (Other Apps)

Once all six Secrets have been added to your LoopWorkspace, your screen should look similar to the graphic below.

  • Check that all of your Secrets are spelled correctly
  • If one is misspelled, delete it and add a New repository secret with the correct name

Time for a Break?

This is a good place to pause if you need to. Just note where you are on the page so you can return later.

"},{"location":"gh-actions/gh-first-time/#step-5-of-12","title":"Step 5 of 12","text":"

Step 5 of 12 is Validate Secrets. This step has 2 Substeps.

"},{"location":"gh-actions/gh-first-time/#substep-51-for-step-5","title":"Substep 5.1 for Step 5","text":"

Next section, First Use of Actions Tab, is Substep 1 out of 2 for Step 5. This is done only once for a given repository.

"},{"location":"gh-actions/gh-first-time/#first-use-of-actions-tab","title":"First Use of Actions Tab","text":"

Near the top middle of your LoopWorkspace fork\u00a0 is an Actions tab. This section provides detailed directions to enable Actions.

Click on the Actions tab of your LoopWorkspace repository.

  • Your first time, a message appears saying Workflows aren't being run on this forked repository as shown in the graphic below

  • Tap on the green button that says: I understand my workflows, go ahead and enable them

The workflows are now displayed on the left side as shown in the graphic below. (Dismiss the Actions Enabled message using the X near the upper right side if it appears).

"},{"location":"gh-actions/gh-first-time/#substep-52-for-step-5","title":"Substep 5.2 for Step 5","text":"

Next section, Validate Secrets, is Substep 2 out of 2 for Step 5. This should only be needed one time, unless you modify any of your Secrets.

"},{"location":"gh-actions/gh-first-time/#validate-secrets","title":"Validate Secrets","text":"Section Summary (click to open/close)

This step validates most of your six Secrets and provides error messages if it detects an issue with one or more.

  1. Click on the \"Actions\" tab of your LoopWorkspace repository and enable workflows if needed
  2. On the left side, select 1. Validate Secrets.
  3. On the right side, click \"Run Workflow\", and tap the green Run workflow button.
  4. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.
  5. The workflow will check if the required Secrets are added and that they are correctly formatted. If errors are detected, please check the run log for details.

To skip the detailed instructions, click on Add Identifiers

Near the top middle of your LoopWorkspace fork, click on the Actions tab.

  • If you have never used Actions on this repository before, and need instructions (in addition to what GitHub shows), please back up to First use of Actions Tab.

Refer to the graphic below for the numbered steps:

  1. Click on the Actions tab of your LoopWorkspace repository
  2. On the left side, click on 1. Validate Secrets
  3. On the right side, click Run Workflow to show a drop-down menu
    • You will see your default branch (typically this is main)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says Run workflow.

The Validate Secrets Action\u00a0 should succeed or fail in a few minutes. Do not continue to the next step until this one succeeds.

  • If you see the green check () continue to the next section
  • If you see the red X ():
    • Examine the Error tells how to view the file needed to diagnose your problem.
    • Action: Validate Secrets Errors tells you what to search for in the file
    • Resolve the error and repeat the Action: Validate Secrets
"},{"location":"gh-actions/gh-first-time/#step-6-of-12","title":"Step 6 of 12","text":"

Step 6 of 12 is Add Identifiers. This step has no Substeps.

This should only be needed one time, unless the developers add or modify an identifier.

For example going from version 3.2.x to version 3.3 or higher requires this to be repeated. There will be clear instructions on to update page when you need to do this.

"},{"location":"gh-actions/gh-first-time/#add-identifiers","title":"Add Identifiers","text":"Section Summary (click to open/close)
  1. Click on the \"Actions\" tab of your LoopWorkspace repository.
  2. On the left side, select \"2. Add Identifiers\".
  3. On the right side, click \"Run Workflow\", and tap the green Run workflow button.
  4. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.

To skip the detailed instructions, click on Configure Identifiers for Loop.

Refer to the graphic below for the numbered steps:

  1. Click on the Actions tab of your LoopWorkspace repository
  2. On the left side, click on 2. Add Identifiers
  3. On the right side, click Run Workflow to show a drop-down menu
    • You will see your default branch (typically this is main)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says Run workflow.

The Add Identifiers Action\u00a0 should succeed or fail in a few minutes. Do not continue to the next step until this one succeeds.

  • If you see the green check () continue to the next section
  • If you see the red X ():
    • Examine the Error tells how to view the file needed to diagnose your problem.
    • Action: Add Identifiers Errors tells you what to search for in the file
    • Resolve the error and repeat the Action: Add Identifiers
"},{"location":"gh-actions/gh-first-time/#step-7-of-12","title":"Step 7 of 12","text":"

Step 7 of 12 is Configure Identifiers for Loop. This step has 2 Substeps, some of which may not be required but are numbered so you can check them off.

This should only be needed one time, unless the developers add or modify an identifier.

For example going from version 3.2.x to version 3.3 or higher requires this to be repeated. There will be clear instructions on to update page when you need to do this.

"},{"location":"gh-actions/gh-first-time/#configure-identifiers-for-loop","title":"Configure Identifiers for Loop","text":"

Some steps can be skipped if you previously built the Loop app with a Mac using Xcode.

Please read carefully to avoid confusion.

"},{"location":"gh-actions/gh-first-time/#substep-71-for-step-7","title":"Substep 7.1 for Step 7","text":"

Next section, Create App Group, is Substep 1 out of 2 for Step 7. This is only required one time and can be skipped if you previously built this app with Xcode.

"},{"location":"gh-actions/gh-first-time/#create-app-group","title":"Create App Group","text":"Section Summary (click to open/close)

If you have already built the Loop app via Xcode using this Apple ID, skip ahead to Previous Xcode Builders.

  1. Go to Register an App Group on the Apple Developer site.
  2. For Description, use \"Loop App Group\".
  3. For Identifier, enter \"group.com.TEAMID.loopkit.LoopGroup\", substituting your team id for TEAMID.
  4. Click \"Continue\" and then \"Register\".

To skip the detailed instructions, click on Add App Group to Identifiers

The Loop App Group already exists if you previously built the Loop app using Xcode with this Apple Developer ID. In that case, skip ahead to Previous Xcode Builders.

If you have never built the Loop app with Xcode using your TEAMID, you need to create an App Group associated with your TEAMID.

  1. Open this link: Register an App Group on the Apple Developer site.
  2. For Description, use Loop App Group.
  3. For Identifier, enter group.com.TEAMID.loopkit.LoopGroup, substituting your team id for TEAMID.
  4. Double-check the spelling - your TEAMID must be correct and the Loop App Group must match the format shown in the previous step
    • A mistake here means you will not be able to build the Loop app until you fix it
  5. Click Continue and then Register.
"},{"location":"gh-actions/gh-first-time/#identifiers-for-the-loop-app-32x-and-before","title":"Identifiers for the Loop app (3.2.x and before)","text":"

If you ever built the Loop app using Mac, skip ahead to Previous Xcode Builders.

"},{"location":"gh-actions/gh-first-time/#new-builders","title":"New Builders","text":"

Click this link: Certificates, Identifiers & Profiles: Identifiers List on the Apple Developer site.

If you never built using Xcode, then after the Add Identifiers Action, you will see the six items under NAME in the table below with the associated IDENTIFIER information. Your Developer ID replaces the TEAMID in the identifier.

Skip ahead to Table with Name and Identifier for Loop 3.

"},{"location":"gh-actions/gh-first-time/#previous-xcode-builders","title":"Previous Xcode Builders","text":"

Click this link: Certificates, Identifiers & Profiles: Identifiers List on the Apple Developer site.

Because you built the Loop app using Xcode, then the NAME associated with at least the Loop identifier will appear as XC com.TEAMID.loopkit.Loop under the NAME column. Ignore the NAME column and key off what you see under the IDENTIFIER column of the table. Only the six listed in the table below need to appear when building Loop 3.

"},{"location":"gh-actions/gh-first-time/#table-with-name-and-identifier-for-loop-3","title":"Table with Name and Identifier for Loop 3","text":"NAME IDENTIFIER Loop com.TEAMID.loopkit.Loop Loop Intent Extension com.TEAMID.loopkit.Loop.Loop-Intent-Extension Loop Status Extension com.TEAMID.loopkit.Loop.statuswidget Small Status Widget com.TEAMID.loopkit.Loop.SmallStatusWidget WatchApp com.TEAMID.loopkit.Loop.LoopWatch WatchAppExtension com.TEAMID.loopkit.Loop.LoopWatch.watchkitextension

Loop dev Builders

The name and identifier for \"Small Status Widget\" has been renamed to \"Loop Widget Extension\". This only affects those using the dev branch until the next release. At that time, this table will be updated.

If you are building with the dev branch, follow the directions at One-Time Changes.

"},{"location":"gh-actions/gh-first-time/#substep-72-for-step-7","title":"Substep 7.2 for Step 7","text":"

Next section, Add or Review Configuration for Loop Identifier, is Substep 2 out of 2 for Step 7.

This should only be needed one time, unless the developers add or modify an identifier.

For example going from version 3.2.x to version 3.3 or higher requires this to be repeated. There will be clear instructions on to update page when you need to do this.

"},{"location":"gh-actions/gh-first-time/#add-or-review-configuration-for-loop-identifier","title":"Add or Review Configuration for Loop Identifier","text":"Section Summary (click to open/close)

Note 1 - If you previously built with Xcode, the Names listed below may be different, but the Identifiers will match. A table was provided above that lists both Names and Identifiers. The Add Identifier Action that you completed above generates 6 identifiers, but only 4 need to be modified as indicated in this step.

Note 2 - Depending on your build history, you may find some of the Identifiers are already configured - and you are just verifying the status; but in other cases, you will need to configure the Identifiers.

  1. Go to Certificates, Identifiers & Profiles on the Apple Developer site.
  2. For each of the following identifier names:
    • Loop
    • Loop Intent Extension
    • Loop Status Extension
    • Small Status Widget (released code) / Loop Widget Extension (dev branch)
  3. Click on the identifier's name.
  4. On the \"App Groups\" capabilities, click on the \"Configure\" button.
  5. Select the \"Loop App Group\"
  6. Click \"Continue\".
    • For the Loop Identifier only, you must add a check box next to Time Sensitive Notifications
    • This is only required for released code, it is automatically selected for the dev branch
  7. Click \"Save\".
  8. Click \"Confirm\".
  9. Remember to do this for each of the identifiers above.

To skip the detailed instructions, click on Create Loop App in App Store Connect

Find and click on the row for the Loop identifier on the Certificates, Identifiers & Profiles: Identifiers List page. Look in the IDENTIFIER column to find com.TEAMID.loopkit.Loop. The name in the NAME column may be different than Loop.

NAME IDENTIFIER Loop com.TEAMID.loopkit.Loop

The Edit Your App ID Configuration screen will open. Take two actions for the Loop identifier.

  1. In the App Services column, scroll down to the App Groups row
    • Ensure the check box (under the Capabilities column) for App Groups is checked
    • (XC Loop) - If the word Edit shows up under NOTES, move on to step 2 below
    • If the word Configure shows up, tap on it
      • This opens the App Group Assignment screen
      • Check the box by Loop App Group that uses your TEAMID in group.com.TEAMID.loopkit.LoopGroup and then Continue

  2. Continue scrolling down to the Time Sensitive Notifications row

    • Make sure the box next to Time Sensitive Notifications is checked as shown in the following graphic
    • This is only needed for the Loop identifier

  3. Now scroll slowly back up to the top of the page. As you go, confirm that each of these is configured with a check mark; if any are missing, click to enable.

    • Time Sensitive Notifications
    • Siri (formerly known as SiriKit)
    • Push Notifications
    • HealthKit
    • App Groups (enabled with group.com.TEAMID.loopkit.LoopGroup)

If you modified settings for an identifier, the Save button at the top right will become active. Click on Save before leaving this page - otherwise, the change does not take effect.

  • Tap on Save
  • This opens the Modify App Capabilities confirmation screen
  • Click on Confirm

If you did not need to make changes, the Save button will not be active.

  • Tap on the < All Identifiers button at the top left

The full list of Identifiers should be displayed again.

"},{"location":"gh-actions/gh-first-time/#add-app-group-to-identifiers","title":"Add App Group to Identifiers","text":"

You will now be checking the status for 3 more identifiers to ensure the App Group is configured to use the Loop App Group. You must add or confirm the App Group for these 3 identifiers (for released code):

NAME IDENTIFIER Loop Intent Extension com.TEAMID.loopkit.Loop.Loop-Intent-Extension Loop Status Extension com.TEAMID.loopkit.Loop.statuswidget Small Status Widget com.TEAMID.loopkit.Loop.SmallStatusWidget

Double-check when finished with this step

When you think you have completed this step, double check to make sure all 4 Identifiers listed in the table have the App Group added.

If not, Create Certificates will succeed but Build Loop will fail.

"},{"location":"gh-actions/gh-first-time/#building-dev-branch","title":"Building dev branch?","text":"

If you are building the dev branch, the Small Status Widget was renamed. Look for it and add the App Group to it now.

NAME IDENTIFIER Loop Widget Extension com.TEAMID.loopkit.Loop.LoopWidgetExtension"},{"location":"gh-actions/gh-first-time/#back-to-how-to-instruction-for-main-or-dev","title":"Back to How-to Instruction for main or dev","text":"

Find and click on a given identifier row on the Certificates, Identifiers & Profiles: Identifiers List page.

The Edit Your App ID Configuration screen will open. Take one action for each of these three identifiers.

Looking at the App Services column, scroll down to the App Groups row

  • Ensure the check box (under the Capabilities column) for App Groups is checked
  • If the word Edit shows up under NOTES, return to the identifiers list
  • If the word Configure shows up, tap on it
    • This opens the App Group Assignment screen
    • Check the box by Loop App Group that uses your TEAMID in group.com.TEAMID.loopkit.LoopGroup and then Continue

If you had to modify a given identifier, the Save button at the top right will become active

  • Tap on Save
  • This opens the Modify App Capabilities confirmation screen
  • Click on Confirm

If you did not need to make changes, the Save button will not be active.

  • Tap on the < All Identifiers button at the top left

The full list of Identifiers should be displayed again.

"},{"location":"gh-actions/gh-first-time/#step-8-of-12","title":"Step 8 of 12","text":"

Step 8 of 12 is Create Loop App in App Store Connect. This step has no Substeps. It is only required one time.

If you are building other apps using this page as a guide, you must complete this step one time for each app.

"},{"location":"gh-actions/gh-first-time/#create-loop-app-in-app-store-connect","title":"Create Loop App in App Store Connect","text":"Section Summary (click to open/close)

If you have created a Loop app in App Store Connect before, skip ahead to Create Certificates.

  1. Click on the link apps list to open App Store Connect and click the blue \"plus\" icon to create a New App.
    • Select \"iOS\".
    • Select a name: this will have to be unique, so you may have to try a few different names here, but it will not be the name you see on your phone, so it's not that important.
    • Select your primary language.
    • Choose the bundle ID that matches com.TEAMID.loopkit.Loop, with TEAMID matching your team id.
    • SKU can be anything; e.g. \"123\".
    • Select \"Full Access\".
  2. Click Create

You do not need to fill out the next form. That is for submitting to the app store.

To skip the detailed instructions, click on Create Certificates.

If you have created a Loop app in App Store Connect before, skip ahead to Create Certificates.

If you have previously used some kind of remote build, like diawi or TestFlight, you may have your Loop in the App Store but can't see it. Don't worry - there are instructions for this case.

  1. Open this link: App Store Connect / Apps to view your apps; log in if needed.

    • If you have never added an app to App Store Connect, you will not see the icons inside the red rectangle and should keep going, although some people report the search icon shows up for them
    • If you have an app that is not shown, you will see a search icon and the All Statuses dropdown. If you get to step 3 and cannot find your com.TEAMID.loopkit.Loop in the Bundle ID drop-down, this means you need to follow Find My Loop.

  2. Click the Add Apps button or the blue \"plus\" icon ( ) and select New App as shown in the graphic below

  3. The New App dialog box opens and should appear similar to the graphic below. Before you fill anything out, make sure your Bundle ID is available in the dropdown menu (it shows as Choose in the graphic below). If you do not see com.TEAMID.loopkit.Loop, with TEAMID matching your TEAMID in the dropdown menu; back out of this screen and follow the directions in Find My Loop instead.

    • Select iOS.
    • Enter a name: this will have to be unique
      • You could start with Loop_ABC where ABC are your initials
      • If that is already taken, you can add a number, for example, Loop_ABC_123
      • This name is what you see on the App Store Connect list and in the TestFlight app
      • Once installed on your phone, you will see the Loop app with the standard Loop Logo
      • You can Change the App Store Connect Name later if you want
    • Select your primary language.
    • Choose the Bundle ID that matches com.TEAMID.loopkit.Loop
    • SKU can be anything; for example 123.
    • Select \"Full Access\".

  4. One last check - if the Bundle ID has a number other than your actual 10-digit TEAMID embedded in it, you will be creating an App in the App Store that you cannot use

    • In this case, do NOT select Create
    • Instead, go back and put the correct value into the TEAMID Secret and follow the steps in Delete Identifiers
  5. Click Create but do not fill out the next form. That is for submitting to the app store and you will not be doing that.

You are done with this activity and can close the browser tab. It's time to head back to your GitHub account and Create Certificates

"},{"location":"gh-actions/gh-first-time/#find-my-loop","title":"Find My Loop","text":"

This section is for people who were not able to follow the instructions in the last section because com.TEAMID.loopkit.Loop, with TEAMID matching your TEAMID, was not in the dropdown menu for Bundle ID.

There are two possible reasons:

  1. You did not complete Add App Group to Identifiers or one of the predecessor steps; review those steps
  2. Your app is already in App Store Connect, but you cannot see it

You may have no memory of ever setting up Loop in App Store Connect. If you previously used some kind of remote build, like diawi, your Loop may be there as a Removed App.

  • Open this link: App Store Connect / Apps, look for the All Statuses dropdown indicator, and select Removed Apps

  • Click on the App name:

  • Ensure this is the app you want by selecting App Information, highlighted on the left side in the graphic below.

    • Examine its Bundle ID (not in view in this graphic) - confirm it is correct.
    • The format should be: com.TEAMID.loopkit.Loop with your TEAMID included

  • Then scroll down to the bottom and choose Restore App.

  • Make sure User Access is set to Full Access and click on Restore.

  • You are done with this step and ready to Create Certificates

"},{"location":"gh-actions/gh-first-time/#step-9-of-12","title":"Step 9 of 12","text":"

Step 9 of 12 is Create Certificates. This step has no Substeps.

The next section will be required again in the future for these cases:

  • When your certificates have expired (after one year) and you need to Renew Certificates
  • When the developers have modified the Identifiers; this requires Create Certificates to be run after you successfully run Add Identifiers and update the new Identifiers
"},{"location":"gh-actions/gh-first-time/#create-certificates","title":"Create Certificates","text":"Section Summary (click to open/close)
  1. Go back to the \"Actions\" tab of your LoopWorkspace repository in GitHub.
  2. On the left side, select \"3. Create Certificates\".
  3. On the right side, click \"Run Workflow\", and tap the green Run workflow button.
  4. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.

To skip the detailed instructions, click on Build the Loop App

Refer to the graphic below for the numbered steps:

  1. Click on the \"Actions\" tab of your LoopWorkspace repository
  2. On the left side, click on \"Create Certificates\"
  3. On the right side, click \"Run Workflow\" to show a drop-down menu
    • You will see your default branch (typically main)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says \"Run workflow\".

  5. Wait a minute or two for the action to finish

    • If this action fails, head over to Action: 3. Create Certificates Errors
    • Once you've resolved the error, repeat the Actions Add Identifiers and then Create Certificates. (The Add Identifiers might not be required but it is fast and should be done as a matter of routine.)
"},{"location":"gh-actions/gh-first-time/#step-10-of-12","title":"Step 10 of 12","text":"

Step 10 of 12 is Build the Loop App. This step has no Substeps.

The next section is repeated every time you need to manually build. With the next release, building can be configured to be automatic, but for now, plan to run this once a month so you always have a fresh build in your TestFlight app.

"},{"location":"gh-actions/gh-first-time/#build-the-loop-app","title":"Build the Loop App","text":"Section Summary (click to open/close)
  1. Click on the \"Actions\" tab of your LoopWorkspace repository.
  2. On the left side, select \"4. Build Loop\".
  3. On the right side, click \"Run Workflow\", and tap the green Run workflow button.
  4. You have some time now. Go enjoy a coffee. The build should take about 20-30 minutes.
  5. You should get several emails
    • one says the build succeeded (or failed)
    • one says TestFlight is ready (typically half-hour after the build succeeds)
    • Ignore the one that says you need to fix \"issues\" in your app. You are not selling the app in the app store; so no action is required. The app you built is for personal use for you or a family member.
  6. Your app should eventually appear on App Store Connect.
  7. For each phone/person you would like to support:
    • Add them in Users and Access on App Store Connect.
    • Add them to your TestFlight Internal Testing group.

To skip the detailed instructions, click on Set Up Users and Access (TestFlight).

Refer to the graphic below for the first four steps:

  1. Click on the \"Actions\" tab of your LoopWorkspace repository.
  2. On the left side, click on \"4. Build Loop\".
  3. On the right side, click \"Run Workflow\" to show a drop-down menu
    • You will see your default branch (typically main)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says \"Run workflow\".

  5. Wait a few minutes to make sure there is not an early failure

    • If this action fails, head over to Action: Build Loop Errors
    • Once you've resolved the error, it's a good idea to repeat all three steps in this order:
      • Add Identifiers
      • Create Certificates
      • Build Loop
  6. If the process appears to be happening without an error, go do something else for a while. The build should take about 20-30 minutes.
  7. You should get several emails
    • one says the build succeeded (or failed)
    • one says TestFlight is ready (typically half-hour after the build succeeds)
    • Ignore the one that says you need to fix \"issues\" in your app
  8. Your app should eventually appear on App Store Connect.
"},{"location":"gh-actions/gh-first-time/#apple-email-to-ignore","title":"Apple Email to Ignore","text":"

You can ignore an email from Apple that there are things you must fix in your app:

  • There is no action you need to take - the developers will handle any updates that are required before it affects your ability to build the app
  • Other warnings only address issues if you were selling the app in the app store, but it is for your own personal use
"},{"location":"gh-actions/gh-first-time/#build-failed","title":"Build Failed?","text":"

Did you get a red X? Head over to the Errors with Browser to page find a solution.

"},{"location":"gh-actions/gh-first-time/#successful-build","title":"Successful Build","text":"

Congratulations

If you get the green check mark, your app successfully built. Just a few more steps.

"},{"location":"gh-actions/gh-first-time/#step-11-of-12","title":"Step 11 of 12","text":"

Step 11 of 12 is Set Up Users and Access (TestFlight). This step has no Substeps.

The next section is repeated if you need to add a User to your account. For example, you want to add another adult who can install the app on your child's phone or you want a spouse or friend to have a copy of the app on their phone as backup for a trip.

As a developer, you are already included as a user with the Role of Account Holder, Admin.

"},{"location":"gh-actions/gh-first-time/#set-up-users-and-access-testflight","title":"Set Up Users and Access (TestFlight)","text":"

Once the first build completes, you will be able to configure TestFlight for the app.

Add Each Users One Time

Once you add a user to have access to your TestFlight for this app, you don't need to do it again - it remains available to them across rebuilds and different versions for that app.

You are configuring a private capability for your family using an Internal Testing group. You need the Apple ID email address for each adult installing from your build. When building for a child, you will use your own Apple ID, not theirs. See TestFlight for a Child.

  1. First you need to add the email address(es) to your App Store Connect Access Users list:

    • Open this link: Users and Access
      • You must provide a role for each person - Customer Support is a good choice
      • Once you have added them here, you'll be able to select them in the TestFlight group for your app

  2. Open this link: App Store Connect / Apps to view your apps; log in if needed. Then select your Loop app. Click on the TestFlight tab then click the blue plus button () next to Internal Testing to add a group.

  3. Fill out the name you want for the Internal Testing group

    • Be sure to check the box Enable automatic distribution
    • Click Create when done (this can always be modified later)

  4. As soon as you create the group, you'll be asked who should be included

    • Click in the box beside each person you want to include
    • Each person in this group will get an email each time you update (build again) using the GitHub Browser Build method
    • Click Add when you are done
    • If building for a child, you will send the invitation to yourself because you will install for your child: See TestFlight for a Child

"},{"location":"gh-actions/gh-first-time/#step-12-of-12","title":"Step 12 of 12","text":"

Step 12 of 12 is Install on Phone. This step has no Substeps.

The next section is repeated for every phone that you want to install a given build from TestFlight. Because a TestFlight app only last 90 days, you should probably build and install at least every 60 days.

"},{"location":"gh-actions/gh-first-time/#install-on-phone","title":"Install on Phone","text":"

The Install on Phone page walks you through the steps to use the TestFlight app to install the Loop app on a phone.

But wait - there's more.

  • Caregivers who help manage a loved-ones diabetes often use other open-source apps that can be built the same way
  • When you are done building and installing the Loop app, there are instructions to Build Other Apps with Browser
"},{"location":"gh-actions/gh-first-time/#extra-steps","title":"Extra Steps","text":"

Most people won't need the information on the rest of this page.

"},{"location":"gh-actions/gh-first-time/#already-haveloopworkspace","title":"Already Have\u00a0LoopWorkspace?","text":"

Some people may already have a copy of LoopWorkspace.

If your copy is not from LoopKit, follow the Delete and Start Fresh directions.

If your copy is from LoopKit:

  • Open your LoopWorkspace repository (https://github.com/username/LoopWorkspace) where you use your GitHub username in the URL
  • Review the graphic in the Configure: Successful Fork section
    • Make sure all the items highlighted by red rectangles are correct with the possible exception of your fork being up to date
  • If you see a message that your fork is not up to date - tap on the Sync fork button and follow the instructions
  • Continue with Create GitHub Personal Access Token
"},{"location":"gh-actions/gh-first-time/#delete-and-start-fresh","title":"Delete and Start Fresh","text":"

If your fork is not from LoopKit:

  • Delete your LoopWorkspace repository
    • Instructions to delete a repository are found at GitHub Docs
  • Return to Fork LoopWorkspace and follow all the instructions
"},{"location":"gh-actions/gh-first-time/#delete-identifiers","title":"Delete Identifiers","text":"

When you have already built the Loop app with Xcode, the Identifier names will not match the directions and you might have trouble deciding which ones to configure. Your existing Loop identifier will have a name that starts with XC as shown below, where your 10-digit TEAMID is used.

  • Name: XC com TEAMID loopkit Loop
  • Identifier: com.TEAMID.loopkit.Loop

The Identifier that is associated with the Loop identifier cannot be deleted if it is already in the App Store but all others can. If you attempt to delete the XC Loop identifier, you may be told it cannot be deleted because it is in use in the app store. That's OK. Same for other identifiers (if you build a bunch of Apps). If a Bundle ID has ever been associated with an app in the App Store, you cannot delete the Identifier.

To make it easy when configuring the identifiers, go through and delete as many as you can.

  • Open this link: Certificates, Identifiers & Profiles: Identifiers List on the Apple Developer site.
  • Use the graphic below as a guide to removing identifiers
  • Keep repeating the steps until you've removed all the identifiers you can (or want to) delete
  • It is OK to delete an identifier even if it does have your correct TEAMID
    • If you try to delete the Loop identifier with your TEAMID, it will refuse, don't worry, just keep going
  • Note - this graphic indicates where on this page you can find your TEAMID
    • If you notice an identifier with a value embedded in it that does not have your TEAMID, then delete it if you can and Update Secrets with your correct TEAMID
    • If you try to delete a Loop identifier that does not have your TEAMID, but you already added to the App Store, it will refuse, don't worry, just keep going

If coming here from the Errors with Browser page because you enter the wrong TEAMID in Secrets - return to that page once you've deleted as many identifiers as you can: Errors: Wrong TEAMID in Secrets.

If you were just trying to clean up the identifiers, then follow these steps:

  • Run Action: Add Identifiers to add Identifiers with the documented short names
  • If you did not complete the Add or Review Configuration for Loop Identifier step, do it now
  • Complete the Add App Group to Identifiers
  • If you did not complete the Create Loop App in App Store Connect step, do it now
  • Continue with Create Certificates and then Build the Loop App
"},{"location":"gh-actions/gh-other-apps/","title":"Build Other Apps with Browser","text":""},{"location":"gh-actions/gh-other-apps/#build-other-apps-using-a-browser","title":"Build Other Apps using a Browser","text":"

Once Loop 3 was released with the ability to build using a browser, a lot of other apps in the DIY universe added the same feature.

Only apps that are companions to\u00a0Loop\u00a0are included on this page.

  • Loop Caregiver
  • Loop Follow

If you want to build another DIY app that is not included here, look for the file fastlane/testflight.md in the GitHub repository associated with that app and open it in a browser. The instructions for that app should be located in that file.

The same technique is used and the same six Secrets are applied to each repository. Those secrets are tied to your Apple Developer ID and your GitHub account.

"},{"location":"gh-actions/gh-other-apps/#update-to-build-with-browser-for-the-loop-caregiver-app","title":"Update to Build with Browser for the Loop Caregiver App","text":"

The Loop Caregiver App Requires an App Group

As of 2023 December 8, the updated version of the Loop Caregiver app requires the addition of an App Group to an expanded list of Identifiers.

  • To update the Loop Caregiver App you need to Update the Repository
  • Then (one time only):
    • Run the Action to Add Identifiers
    • Follow the instructions in Add App Group to LoopCaregiver
    • Continue with Create Certificates
    • Finish with Build App
"},{"location":"gh-actions/gh-other-apps/#optional-build-method","title":"Optional Build Method","text":"

Optional - Set up a Organization Account

If you are going to be building a lot of different apps, you can choose to set up a free organization account with GitHub and use that to build.

Pros:

  • The 6 Secrets can be added to the organization one-time and apply to every repository

Cons:

  • The displays for an organization are slightly different than for a personal account but are not hard to navigate if you are computer literate and feel comfortable using a browser

For more information, see Use a GitHub Organization Account.

"},{"location":"gh-actions/gh-other-apps/#multiple-copies-of-loop-follow","title":"Multiple Copies of Loop Follow","text":"

For the convenience of caregivers who use Loop Follow to monitor multiple people, updates were added in v2.1.2 to make this more convenient. This works regardless of the build method. (Build with Browser or Build with Mac).

  • Build up to three instances of Loop Follow
  • Customize the name of the app that appears on your phone
  • Display the custom name in the main Loop Follow screen
"},{"location":"gh-actions/gh-other-apps/#prerequisites","title":"Prerequisites","text":"

  • If you have already built using the Browser Build method, it is easy to build other apps which use the same method. Skip ahead to Fork and Add Secrets

    • If you decide you want to try the GitHub free organization method, review the instructions and then adjust as you work through the step-by-step instructions on this page which show graphics and instructions for using a personal GitHub account

  • If this is the first repository you have built with the Browser Build method, you must first complete the initial steps found on Configure to Use Browser. When you reach the point where

    • You have created your Match-Secrets repository
    • You are told to Configure to Use Browser: Fork LoopWorkspace
      • Review the directions but don't do it
      • Return here and check the table below
      • Use that table to find the link of the repository you will fork

Use the repository for the application you are building

Many graphics on this page show\u00a0LoopWorkspace, just remember to use the repository for the app you want to build, that is either\u00a0Loop Caregiver\u00a0or \u00a0Loop Follow.

"},{"location":"gh-actions/gh-other-apps/#fork-and-add-secrets","title":"Fork and Add Secrets","text":"
  • You will return to this page after reviewing (but not doing) this step Configure to Use Browser: Fork LoopWorkspace
    • Use the same method as that section, but fork the repository for the app you plan to build
    • Loop Caregiver, expect the dev branch
    • Loop Follow, expect the main branch
"},{"location":"gh-actions/gh-other-apps/#table-of-app-repositories","title":"Table of App Repositories","text":"App Fork from this Address Documentation Loop Caregiver https://github.com/LoopKit/LoopCaregiver LoopDocs: Loop Caregiver Loop Follow https://github.com/loopandlearn/LoopFollow Loop Follow

The two repositories below are only if you need to follow a second or third looper. All others should use just the table above. The instructions for the second and third looper are otherwise identical to the first looper. Note that LoopCaregiver can follow multiple Loopers; you select the person inside the app.

Special Case Fork from this Address Loop Follow for a Second Looper https://github.com/loopandlearn/LoopFollow_Second Loop Follow for a Third Looper https://github.com/loopandlearn/LoopFollow_Third"},{"location":"gh-actions/gh-other-apps/#update-the-repository","title":"Update the Repository","text":"

If you just created the fork, you can skip this section.

If you are returning to this page to update an app, please follow these steps. Each step has a link to instructions on the Update LoopWorkspace page. Follow the Update Fork directions for the repository of the app you are updating:

  1. Accept Agreements for the Apple Developer account
  2. Update Fork

Then return to this page.

Normally you skip ahead to Build App after an update.

If you are updating the LoopCaregiver app after the 2023 December 8 update, you need to go to Add Identifiers after updating the fork.

"},{"location":"gh-actions/gh-other-apps/#configure-secrets-for-this-app","title":"Configure Secrets for this App","text":"

If you choose to use the optional GitHub organization method, you can skip this section:

  • All repositories in your GitHub organization use the organization Secrets
  • Make sure you complete Add Secrets to your GitHub Organization instead of this section
  • Skip ahead to Validate Secrets

After successfully creating your fork of the repository for this app:

  • If you have already built Loop using the Browser Build method, skip ahead to Add Existing Secrets

  • If this is the first repository you have built with GitHub

    • You should follow the detailed steps at Configure to Use Browser: Configure Secrets, except you will apply the Secrets to the repository for the app you are planning to build
    • Once your 6 secrets have been added, return to this page and skip ahead to Validate Secrets on this page.
"},{"location":"gh-actions/gh-other-apps/#add-existing-secrets","title":"Add Existing Secrets","text":"

MATCH_PASSWORD

An early version of GitHub First-Time had incorrect information about the need to save MATCH_PASSWORD.

If you did not save your MATCH_PASSWORD in your file with all your Secrets, you will need to delete your Match-Secrets repository, create a new one and then add all your Secrets into all you repositories again and run all the Actions again.

Instructions are found at Reset Match-Secrets.

Open the text file in which you maintain a copy of your 6 Secrets so you can copy each value into the Secrets for this repository.

  1. Click on the repository for your app

  2. Click on the Settings Icon near the top right of your repository

    • On the left side, tap on Secrets and variables dropdown and choose Actions
    • After you select Actions, your screen should look like the graphic below

  3. Tap on New repository secret and add each of the 6 Secrets

    • You will notices the New secret dialog looks a little different
    • As soon as you click on the Name* Box, the 6 Secret Names may show up as a dropdown as shown in the graphic below
    • Select each one in turn and paste the secret value into the Secret* box and hit Add secret
    • If they do not appear in a dropdown, enter them exactly as shown (suggest copy / paste from your text file)

Once all six Secrets are added, proceed to the first Action to validate your secrets.

"},{"location":"gh-actions/gh-other-apps/#validate-secrets","title":"Validate Secrets","text":"

The first action step is to Validate Secrets. Near the top middle of your Repository fork, click on the Actions tab.

  • The first time you click on Actions with this repository you'll be informed that Workflows aren't being run on this forked repository
  • Tap on the green button that says: I understand my workflows, go ahead and enable them

The workflows are now displayed: look at the list on the left side similar to that shown in the graphic below. (You can dismiss the Actions Enabled message using the X near the upper right side if it appears).

  • The graphic below is an example from Loop, your screen will show your app and associated repository

This step validates most of your six Secrets and provides error messages if it detects an issue with one or more.

  1. Click on the \"Actions\" tab of your Loop Follow or Loop Caregiverrepository and enable workflows if needed
  2. On the left side, click on 1. Validate Secrets
  3. On the right side, click Run Workflow to show a drop-down menu
    • You will see your default branch (main for LoopFollow, dev for LoopCaregiver)
    • You can select a different branch, but typically, you run the default
  4. Tap the green button that says Run workflow.

The Validate Secrets Action\u00a0 should succeed or fail in a few minutes. Do not continue to the next step until this one succeeds.

  • If you see the green check () continue to the next section
  • If you see the red X ():
    • Examine the Error tells how to view the file needed to diagnose your problem.
    • Action: Validate Secrets Errors tells you what to search for in the file
    • Resolve the error and repeat the Action: Validate Secrets
"},{"location":"gh-actions/gh-other-apps/#add-identifiers","title":"Add Identifiers","text":"

Near the top middle of your Repository fork, click on the \"Actions\" tab.

  • The graphic below is an example from Loop, your screen will show your app and associated repository

Refer to the graphic below for the numbered steps:

  1. Click on the \"Actions\" tab of your repository
  2. On the left side, click on \"Add Identifiers\"
  3. On the right side, click \"Run Workflow\" to show a drop-down menu
    • You will see your default branch (main for LoopFollow, dev for LoopCaregiver)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says \"Run workflow\"

The Add Identifier Action\u00a0 should succeed or fail in a few minutes.

  • If you see the green check () continue to the next section
  • If you see the red X ():
    • Examine the Error tells how to view the file needed to diagnose your problem
    • Action: Add Identifiers Errors tells you what to search for in the file
    • Resolve the error and repeat the Action: Add Identifiers
"},{"location":"gh-actions/gh-other-apps/#review-app-identifier","title":"Review App Identifier","text":"

Open this link: Certificates, Identifiers & Profiles: Identifiers List on the apple developer site.

After successfully performing the Add Identifiers Action, you will see the identifier for your app with a Name and Bundle ID matching that in the table below. You will see your unique TEAMID embedded in the identifier. (If you previously built this App with Xcode, the name may start with XC but the ending should match.)

App Name Name Bundle ID Loop Caregiver LoopCaregiver com.TEAMID.loopkit.LoopCaregiver Loop Follow LoopFollow com.TEAMID.LoopFollow

If you build from a second or third repository for Loop Follow, the Name will end in Second or Third and Bundle ID will have .Second or .Third at the end.

The Loop Caregiver app requires updates to the Identifiers after they are generated.

The Loop Follow app does not require this extra step. You can skip ahead to Create App in App Store Connect.

"},{"location":"gh-actions/gh-other-apps/#add-app-group-to-loopcaregiver","title":"Add App Group to LoopCaregiver","text":"

As of 2023 December 8, the Loop Caregiver app requires the addition of an App Group to an expanded list of Identifiers. Follow these steps one time to be able to build the Loop Caregiver app after this update.

"},{"location":"gh-actions/gh-other-apps/#check-if-app-group-exists","title":"Check if App Group Exists","text":"

Open this link to view your applicationGroup Identifiers: App Group Identifiers

  • No action is required if there is already an identifier with the NAME of LoopCaregiver App Group and the IDENTIFIER contains your TEAMID in this format: group.com.TEAMID.loopkit.LoopCaregiverGroup
  • In that case, you can skip ahead to Add App Group to Identifiers
"},{"location":"gh-actions/gh-other-apps/#create-app-group-for-the-loop-caregiver-app","title":"Create App Group for the Loop Caregiver App","text":"

Open this link: Register an App Group on the Apple Developer site.

  1. For Description, use LoopCaregiver App Group
  2. For Identifier, enter group.com.TEAMID.loopkit.LoopCaregiverGroup, substituting your team id for TEAMID.
  3. Double-check the spelling - your TEAMID must be correct and the LoopCaregiverGroup App Group must match the format shown above
    • A mistake here means you will not be able to build the LoopCaregiver app until you fix it
  4. Click Continue and then Register.
"},{"location":"gh-actions/gh-other-apps/#add-app-group-to-identifiers","title":"Add App Group to Identifiers","text":"

Click to open this link in a new tab: Certificates, Identifiers & Profiles: Identifiers List on the Apple Developer site.

"},{"location":"gh-actions/gh-other-apps/#table-with-name-and-identifier-for-loopcaregiver","title":"Table with Name and Identifier for LoopCaregiver","text":"

All five of these identifiers should be found after running the Add Identifier action on GitHub.

If you do not see them, please sync your LoopCaregiver repository and then run the Add Identifier action. The NAME might begin with an XC if you previously built with Xcode. However, the IDENTIFIER column value should match.

NAME IDENTIFIER LoopCaregiver com.TEAMID.loopkit.LoopCaregiver LoopCaregiverIntentExtension com.TEAMID.loopkit.LoopCaregiver.IntentExtension LoopCaregiverWatch com.TEAMID.loopkit.LoopCaregiver.watchkitapp LoopCaregiverWatchWidgetExtension com.TEAMID.loopkit.LoopCaregiver.watchkitapp.WidgetExtension LoopCaregiverWidgetExtension com.TEAMID.loopkit.LoopCaregiver.WidgetExtension"},{"location":"gh-actions/gh-other-apps/#add-loopcaregivergroup-to-each-identifier","title":"Add LoopCaregiverGroup to each Identifier","text":"

Find and click on the row for the LoopCaregiver on the Certificates, Identifiers & Profiles: Identifiers List page. Look in the IDENTIFIER column to find com.TEAMID.loopkit.LoopCaregiver. The NAME might begin with an XC if you previously built with Xcode. However, the IDENTIFIER column value should match.

NAME IDENTIFIER LoopCaregiver com.TEAMID.loopkit.LoopCaregiver

The Edit Your App ID Configuration screen will open.

  1. In the App Services column, scroll down to the App Groups row
    • Ensure the check box (under the Capabilities column) for App Groups is checked
    • Tap on the word Edit or Configure, whichever shows up
      • This opens the App Group Assignment screen
      • Check the box by LoopCaregiver App Group that uses your TEAMID in group.com.TEAMID.loopkit.LoopCaregiver
      • If the box by Loop App Group is checked, you should uncheck it
      • If you made any changes, tap Continue, otherwise, tap Cancel

If you modified settings for an identifier, the Save button at the top right will become active. Click on Save before leaving this page - otherwise, the change does not take effect.

  • Tap on Save
  • This opens the Modify App Capabilities confirmation screen
  • Click on Confirm

If you did not need to make changes, the Save button will not be active.

  • Tap on the < All Identifiers button at the top left

The full list of Identifiers should be displayed again.

Continue down the list until every identifier in the table below has the App Group for LoopCaregiver App Group added to it. (DO NOT SELECT the Loop App Group) If you miss any, the GitHub action to 3. Create Certificates will succeed but the GitHub action to 4. Build LoopCaregiver will fail.

NAME IDENTIFIER LoopCaregiver com.TEAMID.loopkit.LoopCaregiver LoopCaregiverIntentExtension com.TEAMID.loopkit.LoopCaregiver.IntentExtension LoopCaregiverWatch com.TEAMID.loopkit.LoopCaregiver.watchkitapp LoopCaregiverWatchWidgetExtension com.TEAMID.loopkit.LoopCaregiver.watchkitapp.WidgetExtension LoopCaregiverWidgetExtension com.TEAMID.loopkit.LoopCaregiver.WidgetExtension"},{"location":"gh-actions/gh-other-apps/#create-app-in-app-store-connect","title":"Create App in App Store Connect","text":"

You will be following the directions below to create an App in App Store Connect if you don't already have one.

This requires you to provide some information. Examine the table below for the bundle ID associated with your app.

App Name Bundle ID Loop Caregiver com.TEAMID.loopkit.LoopCaregiver Loop Follow com.TEAMID.LoopFollow

If you build from a second or third repository for Loop Follow, the Bundle ID will have .Second or .Third at the end.

  1. Open this link: App Store Connect / Apps to view your apps; log in if needed.

  2. If this App already exists, you can continue to Create Certificates

  3. Click the Add Apps button or the blue \"plus\" icon and select New App as shown in the graphic below

  4. The New App dialog box opens and should appear similar to the graphic below. Before you fill anything out, make sure your Bundle ID is available in the dropdown menu. If you do not see the Bundle ID for your app; back out of this screen and follow the directions in Configure to Use Browser: Find My Loop, where you'll be finding App Name instead of Loop.

    • Select \"iOS\". For Loop Follow you can also select \"macOS\" if you own a Mac with macOS 11 or later.
    • Enter a name: this will have to be unique
      • You could start with \"App Name ABC\" where ABC are your initials
      • If that is already taken, you can add a number, for example, \"App Name ABC 123\"
      • This name is what you see on the App Store Connect list and in the TestFlight app
      • Once installed on your phone, you will see the actual app name
      • You can Change the App Store Connect Name later if you want
    • Select your primary language.
    • Choose the bundle ID for your app
    • SKU can be anything; for example \"123\" but must be unique across all your apps, so try 1234 or 12345 depending on how many apps you build with this method
    • Select \"Full Access\".

  5. Click Create but do not fill out the next form. That is for submitting to the app store and you will not be doing that.

You are done with this activity. Before you close this browser window, note the TestFlight tab at the top of the page. You'll be using that tab after you complete the next two actions.

"},{"location":"gh-actions/gh-other-apps/#create-certificates","title":"Create Certificates","text":"
  • The graphic below is an example from Loop. Your screen will show your app and associated repository.

Refer to the graphic below for the numbered steps:

  1. Click on the \"Actions\" tab of your Repository repository
  2. On the left side, click on \"Create Certificates\"
  3. On the right side, click \"Run Workflow\" to show a drop-down menu
    • You will see your default branch (main for LoopFollow, dev for LoopCaregiver)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says \"Run workflow\".

  5. Wait a minute or two for the action to finish

    • If this action fails, head over to Action: Create Certificates Errors
    • Once you've resolved the error, repeat the Actions Add Identifiers and then Create Certificates. (The Add Identifiers might not be required but it is fast and should be done as a matter of routine.)
"},{"location":"gh-actions/gh-other-apps/#build-app","title":"Build App","text":"

The graphic below is an example from Loop, your screen will show your app and associated repository

If you are building the Loop Caregiver app, skip ahead to Build Action.

"},{"location":"gh-actions/gh-other-apps/#display-name-customization-for-loop-follow","title":"Display Name Customization for Loop Follow","text":"

If you build Loop Follow for one, two or three loopers, you may choose to customize your fork or forks to insert a custom display name.

  • Find and click on the file LoopFollowDisplayNameConfig.xcconfig
  • Tap the pencil icon so you can edit the file
  • The last line says display_name = LoopFollow (or LoopFollow_Second or LoopFollow_Third)
  • Insert your custom name so the last line says display_name = LF custom name
  • Click on commit changes and chose to commit directly into the main branch

Continue to build as instructed below. After you install the app on your phone, iPad or Mac via TestFlight, that custom name is what is displayed. The prefix LF is suggested to make it easier to find the custom named Loop Follow app in the list of apps, but is not required.

"},{"location":"gh-actions/gh-other-apps/#build-action","title":"Build Action","text":"

Refer to the graphic below for the first four steps:

  1. Click on the \"Actions\" tab of your Repository repository.
  2. On the left side, click on \"Build App Name\".
  3. On the right side, click \"Run Workflow\" to show a drop-down menu
    • You will see your default branch (main for LoopFollow, dev for LoopCaregiver)
    • You can select a different branch, but typically, you run the default

  4. Tap the green button that says \"Run workflow\".

  5. Wait a few minutes to make sure there is not an early failure

    • If this action fails, head over to Action: Build Loop Errors
    • Once you've resolved the error, it's a good idea to repeat all three steps in this order:
      • Add Identifiers
      • Create Certificates
      • Build Loop
  6. If the process appears to be happening without an error, go do something else for a while. The build should take about 20-30 minutes.
  7. Your app should eventually appear on App Store Connect.
"},{"location":"gh-actions/gh-other-apps/#add-users-to-testflight-for-app","title":"Add Users to TestFlight for App","text":"

Once the first build completes, you will be able to configure TestFlight for the app - follow the template for setting up TestFlight for Loop found in Configure to Use Browser: Set Up Users and Access (TestFlight).

"},{"location":"gh-actions/gh-other-apps/#install-on-phone","title":"Install on Phone","text":"

The Install on Phone walks you through the steps to install the app to a phone. When going through those steps, replace your App Name for\u00a0Loop. Everything else is the same.

"},{"location":"gh-actions/gh-other-apps/#use-a-github-organization-account","title":"Use a GitHub Organization Account","text":"

This section is optional. It is provided to assist:

  • Users who are using GitHub for other reasons and want to segregate their DIY app building from their existing accounts
  • Mentors who want to do a lot of testing of many DIY apps to support people and get tired of entering the 6 Secrets repeatedly
  • Users who are comfortable with the GitHub web interface who want the convenience of entering the 6 Secrets just one time instead of entering them for each repository individually
"},{"location":"gh-actions/gh-other-apps/#set-up-a-free-github-organization","title":"Set up a Free GitHub Organization","text":"

Prerequisite: You need a personal GitHub account.

In the instructions below, use your GitHub username instead of my-name.

  1. Follow the directions below to create a new GitHub organization account with a username of my-name-org (of course naming is up to you)
    • There is documentation at this link, New GitHub Organization, or you can follow the bullets below
    • Log into my-name and click on your icon (at upper right) and choose Settings
    • On the left side-bar, click on Organizations
    • In the new view, click on New Organization and choose Free for the plan by clicking on Create a free organization.
    • In the Set up your organization screen:
      • Enter my-name-org into the Organization name box
      • Enter the same email you use for my-name account
      • Select this organization belongs to My personal account
      • Check the box to accept the terms of service
      • Tap on the next button
  2. You now see a Welcome screen
    • Unless you plan to collaborate with others, just tap Complete setup
    • You can always add others at a later time
  3. Confirm access by entering the same password as you use for my-name
GH_PAT comes from personal my-name account

The GitHub personal access token used as one of the 6 Secrets is associated with your personal account (my-name); so if you already have one, you just keep using it.

"},{"location":"gh-actions/gh-other-apps/#use-the-free-github-organization","title":"Use the Free GitHub Organization","text":"

There are three steps to using this account moving forward:

  1. One-time only: You need to add your 6 Secrets to this organization account (instructions are in next section)

  2. One-time only: Create a Match-Secrets repository in the my-name-org account

    • Start out at the top-level of your organization (github.com/my-name-org)
    • Click on Repositories
    • Click on New repository
    • Choose my-name-org as owner and enter Match-Secrets as the name
    • Make sure to choose Private and tap on the Create button
    • If you want to see graphics for the steps above, refer to the instructions written for a personal (instead of organization) account in Create Match-Secrets

  3. For each repository: you need to fork for each app you wish to build to the new my-name-org account

    • When you do the fork, there will be a drop-down menu under Owner for you to select the account for the fork
    • Choose the organization account
    • Other than that extra step, follow the standard fork directions
      • This link provides instructions to Fork LoopWorkspace
      • Refer to the Table of App Repositories when building apps other than the Loop app

Then, for every build, you will use just the organization account. The original account is maintained to give you access to GitHub and holds your GitHub personal access token.

WARNING - If you have forks of DIY apps in your original my-name account that are configured to build automatically, you want to disable that and have only the my-name-org account be configured for automatic building. Refer to Disable Building for Personal GitHub account.

"},{"location":"gh-actions/gh-other-apps/#add-secrets-to-your-github-organization","title":"Add Secrets to your GitHub Organization","text":"

Adding the Secrets to an organization is similar to adding them to each repository for a personal GitHub account. The difference is you add them at the organization level and then they are available to each repository in that organization.

Follow the directions below to prepare to add secrets to the organization and then skip (when provided the link) to the per-repository directions for more details about adding each secret.

Make sure you are in the organization for GitHub:

  • Click on your icon at upper right of GitHub browser
  • Select Your Organizations
  • In the new screen, select my-name-org
  • Make sure the URL is github.com/my-name-org
  • Click on Settings (it is optional to fill in the information shown under general)
  • In the left pane, scroll down to find Secrets and variables and click on the drop-down symbol and choose Actions
  • Your screen should look like the graphic below

  • At this point, tap on New organization secret
    • Refer the instructions at this link, Enter the Secrets, for adding Secrets
    • Those instructions show the graphics for a personal repository and indicate the button will says New repository secret - your screen will show New organization secret
    • Continue until all six Secrets are entered for your organization account my-name-org
  • Once the organization Secrets are entered, they are used by every repository you fork with this organization as the owner

The GitHub personal access token used as one of the 6 Secrets is associated with your personal account (my-name); so if you already have one, you just keep using it. If not, follow these instructions to get or configure a new one.

"},{"location":"gh-actions/gh-other-apps/#disable-building-for-personal-github-account","title":"Disable Building for Personal GitHub account","text":"

Once you have your apps building as you expected from the my-name-org organization account, you should configure your personal account to stop any automatic building that may be taking place.

"},{"location":"gh-actions/gh-other-apps/#option-1-delete-repository","title":"Option 1: Delete repository","text":"

You can delete the DIY repositories from your personal account

  • Pro: You can't get confused about where you should be building
  • Cons:
    • If you have already generated some customizations there, it is safest to not delete the repository
    • If you have pull requests open from your personal account, DO NOT DELETE that repository - that would automatically close those open PR
  • Here are the instructions if you decide to delete the repositories
    • Click on your icon at upper right of GitHub browser
    • Select Your Repositories
    • Notice the github address now says my-name instead of my-name-org
    • Select the repository you wish to delete and follow these instructions
    • GitHub Docs: Delete a repository
"},{"location":"gh-actions/gh-other-apps/#option-2-disable-build-action","title":"Option 2: Disable Build Action","text":"

You can disable the build actions from the repositories in your personal account

  • Pro: You leave any work you previously did alone in your personal account
  • Con: You might get confused and try to build in your personal account instead of your organization account
  • Here are the instructions to disable the build actions:
    • Click on your icon at upper right of GitHub browser
    • Select Your Repositories
    • Notice the github address now says my-name instead of my-name-org
    • Select the repository you wish to disable build actions for and follow these instructions
    • GitHub Directions to Disable and Enable a Workflow
    • It is the Build action that kicks off the update and build steps, so simply disabling the one action is sufficient
"},{"location":"gh-actions/gh-overview/","title":"Browser Overview","text":""},{"location":"gh-actions/gh-overview/#build-with-a-browser","title":"Build with a Browser","text":"
  • Loop 3\u00a0can be built with a web browser using GitHub Actions
  • The app is then installed remotely on the phone using TestFlight
"},{"location":"gh-actions/gh-overview/#advantages-of-building-with-a-browser","title":"Advantages of Building with a Browser","text":"
  • Mac computer is not required to build or install the app
    • Anything with a browser works to build the Loop app: PC, Tablet, Mac or iPad
    • The TestFlight app is used to install the Loop app on your iPhone
  • Compatible version of Xcode is provided by GitHub
    • The time required for the initial setup to build with a browser may take less time than one macOS and Xcode version update for those using Build with Mac
  • Updates are easy
    • Starting an update takes a few minutes of your time; the rest is automatic
    • Planned for the next release: app will build automatically at least once a month and is checked for updates once a week
"},{"location":"gh-actions/gh-overview/#considerations-for-building-with-a-browser","title":"Considerations for Building with a Browser","text":"
  • After the\u00a0GitHub Build\u00a0starts, your app is ready to install on your iPhone in about an hour
  • The app is delivered to your phone via TestFlight
    • The app is considered \"Beta\" by Apple and expires after 90 days
    • With the next release, which includes automatic builds, this will be even easier than it is now
  • Customization methods are documented at Customize with Browser
"},{"location":"gh-actions/gh-overview/#requirements","title":"Requirements","text":"
  • Loop 3 requires iOS 15.1 or higher on the phone.

To build the\u00a0Loop\u00a0app using a browser, you need:

  1. Free GitHub account (instructions included in Configure to use Browser)
  2. Apple Developer Membership
    • Must be a paid developer account
    • If building for a family member, review this section:
      • Loopers Need Their Own Apple ID
    • If building for a child (age depends on the country), review this section:
      • TestFlight for a Child

Once you have the\u00a0Loop\u00a0app in TestFlight, you need:

  1. Compatible iPhone
  2. Compatible Pump
  3. Compatible CGM
  4. RileyLink Compatible Device (not needed for Omnipod DASH)
"},{"location":"gh-actions/gh-overview/#configuration-to-build-with-a-browser","title":"Configuration to Build with a Browser","text":"

Steps that must be completed to configure for building with a browser are found at:

  • Configure to use Browser

This is a very long page because there are a lot of steps and each step is explained with graphics of what you will see when you work through the steps.

"},{"location":"gh-actions/gh-overview/#how-to-video-to-build-with-a-browser","title":"How-to Video to Build with a Browser","text":"

In addition to the webpage linked above, there is a narrated video of each step needed to build using a browser.

  • How to Build the Loop App With a Web Browser

Click in the comments for a full index of topics. If you have issues with a step, use the index to advance to the relevant part of the video. Subtitles are in English. You can choose a different language but the automatic translation feature may provide translations that are not completely accurate.

"},{"location":"gh-actions/gh-overview/#install-on-phone","title":"Install on Phone","text":"

Instructions to install on your phone are found at:

  • Install on Phone
"},{"location":"gh-actions/gh-overview/#update-the-app","title":"Update the App","text":"

Instructions to make updates are found at:

  • Update with Browser

There is also a helpful video for this process:

  • How to Update and Rebuild DIY Loop with a Web Browser
"},{"location":"gh-actions/gh-overview/#errors-while-building","title":"Errors while Building","text":"

If you get an error, please consult:

  • Errors with Browser
"},{"location":"gh-actions/gh-overview/#building-the-development-version-of-the-app","title":"Building the Development Version of the App","text":"

For experienced and/or advanced users who want to build the development version of the app, there is additional information at the link below. If you have not built using the browser build method before, it is suggested you first build the released version. Once you have a successful build, then follow the steps for the development version. Building the app is independent of installing the app on your phone from TestFlight.

  • Build Development Version
"},{"location":"gh-actions/gh-overview/#what-if-i-get-stuck","title":"What if I get stuck?","text":"

Try to:

  • Scroll back in the directions and see if you missed a paragraph or step
  • Compare your display with the graphics in LoopDocs
    • Is something different or does yours have an error message?
    • Does the error message guide you to the problem and solution?
    • Be aware that GitHub sometimes updates displayed names or locations for menu items - search for GitHub directions if your display looks different than our documentation
  • If you are still stumped - reach out for help: How to Find Help
    • Remember - to get help with Browser Build, all we need is your GitHub username and a brief description of your problem
"},{"location":"gh-actions/gh-update/","title":"Update/Rebuild with Browser","text":""},{"location":"gh-actions/gh-update/#overview","title":"Overview","text":"

This page is only relevant when building with a browser.

For Mac, please see: Update/Rebuild with Mac

Time Estimate (click to open/close)

Build the Loop App

  • 5 min: Check Apple account status
  • Check if you need to renew certificates (once a year only)
  • 5 min: Update version if a new one is available
  • 5 min: Start the Build
  • 1 hour: Wait for the build to complete and appear in the TestFlight app on your phone
    • depends on GitHub, Apple and TestFlight
  • 5 min: Install from TestFlight onto your phone

Once a Year Renew Certificate

  • 5 min: Clear out expired certificates
  • 5 min: Generate new certificates
Page Summary (click to open/close)

The Loop app must be built at least every 90 days when you build with a browser - this is TestFlight requirement.

Most users will start at How to Update or Rebuild.

If your GitHub Personal Access Token has expired, we recommend you update it with No Expiration as explained at GitHub Token.

If you are running Loop-dev, be sure to review these instructions but modify for the branch you are using: refer to Build Loop dev with Browser

FAQs (click to open/close)
  • \"What is an update?\" Anytime you want to change versions or if your TestFlight build is about to expire, follow the instructions on this page.
  • \"Do I delete my old Loop app first?\" Definitely not! If you keep your Loop app on your phone, your Loop settings (and existing pod) will continue to work the same after the update. Seamless.
  • \"Do I need to start a new pod when I update?\" No. Your existing pod session will continue seamlessly if you are using the same Developer Account as the last time you built.
  • \"What if I'm using a new/different developer account?\" If you aren't building with the same developer account used when your existing app was built, then you will be installing a brand new (second) Loop app on your phone. Your existing pod won't work with the new app, so you might want to time this transition when you are due to change pods. Delete the old app once you get the new one all set up.
  • Do I need a computer? No.
  • Can I do this on my phone? Yes, especially after you update your GitHub token to No Expiration.
  • Did the directions change? Yes. We now recommend you select a GitHub Personal Access Token that never expires and supports automatic update and rebuild when that feature is released. It simplifies the build every 90-day process significantly.
  • How do I set my GitHub Personal Access Token to never expire and to support the automatic rebuild feature? See this section Regenerate Token.
  • What happens to my existing builds when I change my GitHub Personal Access Token? Nothing. The GH_PAT only affect future builds. Previous build are available for the full 90 days.
  • Is there anything I have to do once a year? Yes. Once a year you need to get a new Distribution Certificate. These only last one year. See this section Renew Certificate
"},{"location":"gh-actions/gh-update/#when-to-update-or-rebuild","title":"When to Update or Rebuild","text":"

Under ordinary circumstances, you do not have to rebuild or update your Loop app until TestFlight forces you to (90 days). However, there is no harm in building more frequently.

  • You control when the new app is installed on your phone, refer to: Install on Phone: Disable Automatic Install from TestFlight
  • You always want a build available in the TestFlight app
    • You can use TestFlight to quickly install the app if you loose or break your phone and need to replace it
    • You can use TestFlight to quickly install the app if someone accidentally deletes the app from your phone
"},{"location":"gh-actions/gh-update/#how-to-update-or-rebuild","title":"How to Update or Rebuild","text":"

Summary of Update Steps

  1. Accept Agreements
  2. Renew Certificate (once a year)
  3. Update Fork
  4. Build the Loop App
  5. Wait for TestFlight
  6. Install on Phone

Ignore the email that says you need to fix \"issues\" in your app. You are not selling the app in the app store; so no action is required. The app you built is for personal use for you or a family member.

There is also a helpful video for updating (it does not include the Renew Certificates step, which is only done once a year):

  • How to Update and Rebuild DIY Loop with a Web Browser
"},{"location":"gh-actions/gh-update/#accept-agreements","title":"Accept Agreements","text":"

This is Step 1 of 6 - it may not always be necessary, but please check every time.

Sign in to your Apple Developer account. If there are agreements you have not accepted, you will get errors when you try to Build that indicate your Apple Secrets are incorrect - that is very unlikely. You may also need to update your credit card information if it has changed, for example, if there is a new expiration date.

  • For an update, you do not need to modify the FASTLANE_ISSUER_ID, FASTLANE_KEY_ID or FASTLANE_KEY
  • Check your Apple Developer account for agreements, then continue

If you need detailed instructions, click on this Apple Program License Agreement Help Page.

  • Accept the Apple Program License Agreement (only)
    • You do NOT need to accept anything related to the Paid Applications Schedule Agreement
    • That is only required when you sell an app through the App Store

Wait After You Agree

It typically takes 15 minutes before your updated agreement is available so you can complete your build.

If your build with browser fails, wait longer. An hour wait was reported by one person.

"},{"location":"gh-actions/gh-update/#renew-certificate","title":"Renew Certificate","text":"

This is Step 2 of 6 - it is only needed once a year - you should get an email from Apple 30 days before your Distribution Certificate expires. (Don't worry if you did not see the email.)

Apps in TestFlight are not affected when a certificate expires or is revoked.

  • Apps installed on the phone continue to run
  • Apps can be installed from TestFlight onto a phone up through the TestFlight expiration date
  • You just cannot build a new app until a new Certificate is generated
Do you want to know more? (Click to open/close)

This is only a summary - please follow the detailed steps below carefully.

  • Delete all your Distribution Certificates. Apple only allows you to have 2 of these. So get rid of the old ones so you will be able to create a new one that will last a full year. (Step 1 below.)

  • The Certificate in question is embedded in your Match-Secrets repository. In order to proceed, you need to remove the old certificate from Match-Secrets. Later this will be automated and can be done without modifying your Match-Secrets repository, but for now the easiest way to do that is to just delete the certs/distribution folder in your current Match-Secrets repository.

  • Finally, for every app that you build with this method, you need to run Create Certificates for that app. (Step 4 below.)

"},{"location":"gh-actions/gh-update/#manual-steps-to-renew-your-distribution-certificate","title":"Manual Steps to Renew Your Distribution Certificate","text":"

Delete and Create

Do not miss the final step in this section. After you delete certificates, you must run the Action for Create Certificates before you can build an app again.

  1. Use this link to view your Apple Developer Certificates
    • If your screen shows no Certificates and you see a message \"Getting Started with Certificates\", your certificate already expired and was removed by Apple; so skip ahead to Step 2: Navigate to your Match-Secrets Repository
    • Carefully examine the Type column - do not delete a Development Certificate
      • If you do not have any rows that say Distribution Certificate, your certificate already expired and was removed by Apple; so skip ahead to Step 2
      • If your certificate has an expiration date several months in the future - you can wait and renew your certificate later; skip ahead to Update Fork
    • Click each row that has a Distribution Certificate and revoke it
    • You will get an email informing you the certificate was revoked

  2. Navigate to your Match-Secrets Repository

    • You can do this several ways, but one method is demonstrated by the GIF below
    • Open the URL for your GitHub account (address is https://github.com/username where username is replaced by your GitHub username
    • Click on the Repositories Tab
    • Select Match-Secrets

  3. Delete the certs/distribution folder of your Match-Secrets repository using these instructions. The GIF below indicates the places to click with numbered red rectangles:

    • Frame 1: Click 1 on the folder called certs/distribution
    • Frame 2: Click 2 and 3 on the three dots in the upper right and then Delete directory
    • Frame 3: Click 4 and 5 on Commit changes in the upper right and then accept the suggested choice by clicking on Commit changes in the lower right

    Deleting the certs/distribution folder did not work for me

    Some people reported trouble with this step. The other option is to delete and create a new Match-Secrets repository: see Reset Match-Secrets

  4. While still within your Github account, navigate to your fork of LoopWorkspace.

    • You can do this several ways, but one method is demonstrated by the GIF below
    • Click on your username and then Repositories and select LoopWorkspace
    • Once you are on your LoopWorkspace repository, click on the link below and follow the instructions provided to create your certificates.
    • Run the Action: Create Certificates

Other Apps

If you build other apps using the build with browser method, they have just had their certificates revoked.

  • The existing apps you installed from TestFlight continue working until their TestFlight expiration date
  • You cannot build new versions of the app until you run Create Certificates for that app
  • To make sure you don't forget, go ahead and do that for all your other repositories now
"},{"location":"gh-actions/gh-update/#update-fork","title":"Update Fork","text":"

This is Step 3 of 6 - it may not always be necessary, but please check every time.

Open your GitHub account and select your LoopWorkspace repository from your repositories list.

  • If your fork is up to date with LoopKit version, you will see the message This branch is up to date with LoopKit/LoopWorkspace:{branch} - there is no need to build again unless your Loop app in TestFlight is about to expire - in which case, proceed to Build the Loop App
  • If your fork shows a message such as This branch is 3 commits behind LoopKit:main and you want to update and build, then click Sync Fork by tapping where the red rectangle is shown in the graphic above, then in the pop-up window, tap on Update branch
  • If your fork shows a message such as This branch is 3 commits behind LoopKit:main and 4 commits ahead of LoopKit:main; you might need to manually sync and choose to discard changes; you can always customize again after the update

Building a different branch

Do I need to do anything special to build a different branch?

Yes: please follow instructions at Build Development Version

"},{"location":"gh-actions/gh-update/#build-the-loop-app","title":"Build the Loop App","text":"

This is Step 4 of 6 - this is always required.

Refer to graphic below as you follow the steps to build the Loop app.

  • Click on the Actions tab
  • Select the 4. Build Loop workflow on the left
    • If using a mobile browser, be sure to use landscape mode to more closely match how GitHub looks on a computer.
  • Look on the right and click Run workflow to see the dropdown
  • Click on the green Run workflow button in the dropdown
  • Wait ~25 min for the build to complete successfully
  • It is then processed by Apple and sent to TestFlight (be patient)

"},{"location":"gh-actions/gh-update/#what-if-the-build-fails","title":"What if the Build Fails","text":"

If a new release is announced at Current Release, look to see if there are instructions about extra steps required with the release. (The release after 3.2.3 will certainly have extra instructions.)

If you are using the dev branch, head over to Build Development Version for information.

Otherwise, head over to Errors with Browser.

"},{"location":"gh-actions/gh-update/#apple-email-to-ignore","title":"Apple Email to Ignore","text":"

You can ignore an email from Apple that there are things you must fix in your app:

  • There is no action you need to take - the developers will handle any updates that are required before it affects your ability to build the app
  • Other warnings only address issues if you were selling the app in the app store, but it is for your own personal use
"},{"location":"gh-actions/gh-update/#wait-for-testflight","title":"Wait for TestFlight","text":"

You'll receive an App Store Connect email confirming that the build has completed processing, and a TestFlight email confirming the new app is ready to test.

  • If you get an email that the action failed, then return to your repository and look for Build Action error messages
    • Click on the most recent Build job with the red x by it
    • If the details show this message, Could not install WWDR certificate
      • This means Apple did not reply to GitHub as fast as GitHub expected
      • Make sure your developer account is in good standing and that there are no agreements that need to be accepted
      • Repeat the build (previous step)
"},{"location":"gh-actions/gh-update/#install-the-loop-app-on-the-phone","title":"Install the Loop app on the phone","text":"

This is Step 6 of 6 - once you finish this, you are done and your app will last 90 days.

Open the TestFlight app on the Loopers phone and install the most recent version of the Loop app. Most Loopers have automatic update disabled on their phones, so this is a manual process. Don't forget.

The updated Loop app will show up in your TestFlight app on the Looper's phone.

  • Your new app will have \"Expires in 90 days\"
    • There may be older builds that are still in TestFlight
    • It takes time for the update to show up in the TestFlight app
    • Wait for the one that expires in about 90 days
  • You will also see a build number in parentheses, that number increments each build - don't worry about the number

Calendar Reminder

This is a good time to put a calendar reminder in your favorite app.

Set it up for a few days before the TestFlight app will expire.

"},{"location":"gh-actions/gh-update/#automatic-update-disabled","title":"Automatic Update Disabled","text":"

Option 1: If you chose to Disable Automatic Install from TestFlight, you control when to install the app on the phone.

  • This is the recommended option
  • Open TestFlight on your phone and click Install as shown in the GIF below
  • If you are building for a child, follow the TestFlight for a Child instructions again

"},{"location":"gh-actions/gh-update/#automatic-update-enabled","title":"Automatic Update Enabled","text":"

We strongly recommend you toggle off Automatic Updates to allow you to be in full control over when the app is updated. This is even more important if you're using automatic builds from GitHub for version 3.3 or later.

Option 2: If you chose to enable Automatic Updates from TestFlight for the Loop app, the updated build will be installed over your existing app as soon as it uploaded to TestFlight.

  • In this case, when you look at the TestFlight app on your phone, the app should have installed automatically
  • Refer to the GIF above, the message will say Open instead of Install
"},{"location":"gh-actions/gh-update/#choose-previous-build","title":"Choose Previous Build","text":"

If you are a typical user who just builds a single version for yourself or your child, you do not need to read this section.

This section provides detailed instructions if you want to choose a previous build to install on your phone. Typically, the most recent build is selected but there may be special cases:

  • You are supporting multiple family members and may build different versions for each
  • You want to test a different branch or set of customizations; you can install a previous build once you are done with the test

This section covers two topics.

  1. Optional: Add Test Details to the TestFlight build
  2. Select a Previous Build
"},{"location":"gh-actions/gh-update/#add-test-details","title":"Add Test Details","text":"

About half an hour after the build action completes, the new build will appear in the TestFlight screen at this link: App Store Connect / Apps

  • Log in if needed
  • Select your Loop app
  • Click on the TestFlight tab to see a screen similar to the graphic below

Select the build to which you wish to add testing notes. When you tap on that icon, it opens a screen similar to that in the next graphic.

Click inside the box under Test Details. Insert the text you want to see on the phone before you install this version of the app. Tap the Save button at upper right and then < iOS Builds at upper left.

In this example, the branch and commit number are included followed by an indication that this version includes the customizations preferred by this person. Your test details can be as simple as \"Use this for Charlie\".

Commit Number

If your build includes customizations, your commit number will not match what the developer expects to see if you need to ask for help.

Use this section Customization and SHA-1 to determine the SHA-1 before customization.

"},{"location":"gh-actions/gh-update/#select-a-previous-build","title":"Select a Previous Build","text":"

First open the TestFlight app on your phone and select the Loop app.

Near the bottom of the screen is a row labeled previous builds.

  • Tap on the previous builds row
  • The available builds are grouped by app version number, choose your desired version
  • Typically you choose the most recent build for that version and click Install and then Open after installation completes
  • All your settings should remain

The following graphic shows the view seen in the TestFlight app on the phone. By adding test details (as explained in the previous section), the desired build is clear. For most people - they will just use the most recent build. This procedure is useful for those who build often or who support multiple family members.

"},{"location":"gh-actions/gh-update/#the-loop-app-build-details","title":"The Loop App Build Details","text":"

In the Loop app, once installed on your phone, tap on Settings -> Support -> Issue Report. The graphic below shows an example of the Build Details included in the report.

  • The profileExpiration listed here is irrelevant - the app expires when the TestFlight expiration indicates
    • Pro Tip: Add a calender reminder for your next build
  • An app built with a browser displays a sourceRoot that starts with /Users/runner/work/LoopWorkspace
    • The buildDateString is when the app was built and transferred to TestFlight, not when it was installed on your phone
    • You can use 90 days from this date, as well as the Expires in ## Days on the TestFlight app, to know when you need to rebuild

"},{"location":"gh-actions/gh-update/#github-token","title":"GitHub Token","text":"

Your GitHub Personal Access Token should be configured:

  • Never expire
  • repo, workflow permission scope

If you are not logged in to GitHub and have not logged in recently, then you may see the authentication screen when doing the steps below.

Authenticate if requested by clicking on the green Send SMS button or entering your password.

Once you are authenticated, you will have access to view your personal access token.

"},{"location":"gh-actions/gh-update/#modify-personal-access-token","title":"Modify Personal Access Token","text":"

If your Personal Access Token has not expired but does not have the correct permission, you should modify it. Do not regenerate it.

Click on the link to view your token and compare it to the graphic below.

  • Link to access your GitHub Personal Access Token

The graphic above has a blue rectangle added to indicate where you should see your token. If yours does not look like this, click on the link (FastLane Access Token) to open a new display. Watch the GIF below - there are 4 frames, the last one has the Update token button.

  1. Click on the link (FastLane Access Token) to open a new display
  2. This example has no workflow or repo checks in it
  3. Add a check to the workflow box
  4. Scroll all the way to the bottom of the screen and click on the green Update token button

After you click on the Update token button, your FastLane Access Token should now show repo, workflow and look like the earlier graphic above.

The only reason to regenerate a token is if it is set to expire. Do not do the next section unless you have to.

"},{"location":"gh-actions/gh-update/#regenerate-token","title":"Regenerate Token","text":"

If your Personal Access Token has expired or has an expiration date, you can regenerate the new one at any time.

Update new GH_PAT to Secrets

After you get your new token, immediately add it to your Secrets for any app you build with this method. You don't have to rebuild the app, but it's a good idea to at least run Action 1. Validate Secrets for each repository to make sure you did not make a mistake.

You can regenerate your GitHub Personal Access Token at any time by clicking on the link below. (it will open in a new browser tab.)

  • Link to access your GitHub Personal Access Token

The FastLane Access Token is a clickable link.

After you click on FastLane Access Token your screen should be similar to the graphic below.

Your existing TestFlight builds are fine

The yellow GitHub warning by the Regenerate Token button is for new builds you make in the future.

Previous builds are still available in TestFlight and are not affected by this action.

Note - selecting the workflow check box below is new. If yours does not show that selection, add it before you click on Regenerate token (red highlight in graphic below).

Click on Regenerate token (red highlight in previous graphic) to see screen similar to next graphic.

  • Most Loopers will have classic personal access tokens
    • If you are a developer who needs to use the fine-grained (by repository) option, that's fine

Be sure to change the Expiration from 30 days to No Expiration. When you select No Expiration a GitHub warning appears. Click on the green Regenerate Token button (red highlight in following graphic).

The next screen shows your new token. Copy the token using the copy icon and save it along with your other secret settings.

The next step is to update GH_PAT in your Secrets. (If you build other apps with this method - update the GH_PAT for all of them right now - do not forget.)

"},{"location":"gh-actions/gh-update/#update-secrets","title":"Update Secrets","text":"

This example is for updating GH_PAT in the Secrets for your repository, but the same method can be applied when changing any of the Secrets.

Open the repository for which you will update Secrets. On the far right is a Settings selection. If you don't see Settings (if last item on row is Insights), then you are not on your fork or you need to sign in to your GitHub account. You should see username/LoopWorkspace with forked from LoopKit/LoopWorkspace underneath.

Refer to the GIF for help. There are 3 frames.

  1. Tap on Settings, then scroll down until you see Secrets and variables on the left side and click on the drop down indicator to display Actions.
  2. Keep scrolling on the same screen, past the Action secrets / New repository secret row, until you see the list of your current Secrets.
  3. Click on the GH_PAT, tap on the pencil and enter the new token in the form. Click on Update Secret to complete the action.

Scroll all the way to the top of the screen and tap on your LoopWorkspace link. Then follow the How to Update or Rebuild instructions to start a new build.

"},{"location":"gh-actions/gh-update/#build-development-version","title":"Build Development Version","text":"

The information to build a development (dev or any other branch) has been moved to a new page: Build dev with Browser

"},{"location":"intro/loopdocs-how-to/","title":"LoopDocs How-to","text":""},{"location":"intro/loopdocs-how-to/#how-to-find-help","title":"How to Find Help","text":"

Volunteers generously provide support for Loop via online platforms. You have several options for joining conversations on Loop and asking for help. Links to the main platforms are listed below. Non-US Loop users in Italy, Australia, and several other countries have also formed Facebook (FB) groups.

  • The Looped Group on Facebook. Looped Group is the original FB group for DIY looping systems. There are a lot of active members there with an excellent history of helping people.
  • Loop and Learn is a community that provides Loop-centric information, a T1D Speaker Series covering many topics of general diabetes interest as well as Loop-specific chats, alerts whenever there is an update to iOS and Xcode, Quick Tips and articles written by mentors providing their Loop experience.
    • LoopandLearn Facebook Group
    • LoopandLearn Website
    • LoopandLearn YouTube Channel
  • The LoopTips website provides non-build information that is helpful once you are looping, e.g., how to print endo reports, find Loop data, deal with therapy settings changes, etc.
  • Many Loopers use a companion app called Nightscout. Nightscout help can be found in the CGM in the Cloud Facebook group.
  • For those interested in what is coming next for Loop and those who prefer not to use Facebook, join Loop Zulipchat and be sure to subscribe to all the streams or you'll miss some interesting conversations.
  • Loop has an Instagram account @diy.loop where some updates are shared.
"},{"location":"intro/loopdocs-how-to/#how-to-ask-for-help","title":"How to Ask for Help","text":"

If you are having trouble building or using your Loop app, there are some important steps to get responses to your question, while also being considerate of our volunteers' time.

  1. Always search in both LoopDocs and your favorite support group.
    • Confused about how to search in a Facebook group? Here is a video to help.
  2. If you use Facebook, click on the Featured posts (at the top of the page); many posts asking for help are already answered there.
  3. Don't post a duplicate question in multiple groups (mentors monitor many groups). Only post to a different group if you have had no responses for several hours.
  4. If a LoopDocs search, FB or Zulipchat search, and a check of Looped Group featured posts pinned to the top of the page haven't answered your question, then post for help. Review the tips for how to post for help so that our volunteers get all the information they'll need to help you, without needing to ask 40 questions first.
  5. Leave your question posted even after you've gotten an answer, but edit the original post to add the word RESOLVED at the beginning of the original post.
    • This helps other Loopers who have the same question
    • This helps mentors know they don't need to respond to help you
"},{"location":"intro/loopdocs-how-to/#how-to-use-loopdocs","title":"How to use LoopDocs","text":""},{"location":"intro/loopdocs-how-to/#website-short-cuts","title":"Website Short Cuts","text":"

One of our awesome Loop volunteers captured the domain names loopdocs.org and looptips.org. So you can find these valuable websites by simply typing loopdocs or looptips followed by .org in your browser. In other words, you don't need to remember or type https://loopkit.github.io/loopdocs/.

"},{"location":"intro/loopdocs-how-to/#website-navigation","title":"Website Navigation","text":"

There are a lot of links you can click on this website.

  • Some links take you to a different section of the same page
  • Some links take you to a different page in LoopDocs
  • Some links take you to a different website

If you click on the link, you are moved to the new location and must hit the back button on your browser to return.

You can choose to open that link in a new window or new tab.

  • If your mouse has a right button, then right click the link
  • On a Mac with no right button, hold down the Control key and click
  • On a mobile device, click and hold the link and choose where to open the link

Keyboard Navigation

When viewing the site at a computer, you can use keys as shortcuts:

  • n for next page
  • p for previous page
  • s for search

The website navigation depends on whether you are on a mobile device or a computer (with browser width > 1220 pixels).

  • For the wide-view:
    • The tabs for the different sections of LoopDocs are visible across the top of the browser
    • Once a tab is selected:
      • That tab is highlighted
      • The list of pages in that tab is displayed on the left side
      • The Table of Contents for the current page is displayed on the right side
  • For the mobile (or narrow) display:
    • From the Home page, tap the Hamburger Menu to display the tabs for the different sections of LoopDocs
    • Once a tab is selected:
      • The list of pages in that tab is displayed in the Hamburger Menu
      • To return to the main tab list, tap the back arrow
      • To see the Table of Contents, use the Hamburger Menu and scroll to the highlighted page (current page) and tap again
"},{"location":"intro/loopdocs-how-to/#website-search","title":"Website Search","text":"

It is not uncommon to have a question about Loop. But, it is exceptionally rare to have the question not already answered in LoopDocs, so please search for answers by selecting the Search tool (upper right) or typing s then a search term at a computer. As you begin to type, suggested completions and links to pages are displayed. Click on the item you think answers your question.

"},{"location":"intro/loopdocs-how-to/#how-to-improve-loopdocs","title":"How to Improve LoopDocs","text":"

Please submit suggestions for updates and improvements to this documentation. There are many pages of content and we welcome reviewers to help find typos and outdated info/links. If you notice a typo, poor word choice or some explanation that could be improved or clarified, there are a few options. The first two options use github, a website where open-source code and documentation is often shared. You can only use github if you have an account (it's free).

  1. You can issue a Pull Request (best option if it is a simple typo or wording update)
  2. You can open an Issue (best option if a major rewrite is needed or you think a conversation would help), or
  3. You can post on Facebook or Zulipchat
"},{"location":"intro/loopdocs-how-to/#pull-requests-and-issues","title":"Pull Requests and Issues","text":"

If you decide to do a GitHub Pull Request (PR) or create an Issue, first look to see if someone has already opened a PR or Issue on the topic so you don't create a duplicate.

  • If a PR or Issue on the topic is open, feel free to add your comments (don't be shy), but please don't create a duplicate
  • If a PR doesn't exist, watch this LoopDocs Pull Request video on how to create one (it's easy, video is less than 5 minutes)
  • If your Issue is new, please add it by clicking on the New Issue button
    • Give the Issue a descriptive title
    • Indicate which page or pages need updating , along with a brief description of the problem(s)
"},{"location":"intro/loopdocs-how-to/#facebook-or-zulipchat","title":"Facebook or Zulipchat","text":"

Helpful tips for providing LoopDocs feedback through Facebook and/or Zulipchat:

  • In Looped Group - make sure your post is clear that you have a comment about LoopDocs in particular.
  • In Loop Zulipchat, please use the documentation stream, Loopdocs Issue channel.
"},{"location":"intro/overview-intro/","title":"LoopDocs Overview","text":"

Take a deep breath

It is totally understandable if the thought of building and operating your own\u00a0Loop\u00a0app feels intimidating.

As you learn the information explained in\u00a0LoopDocs, this will start feeling more comfortable.

"},{"location":"intro/overview-intro/#loopdocscontents","title":"LoopDocs\u00a0Contents","text":"

The\u00a0LoopDocs\u00a0website is organized as follows

  • Home: What is\u00a0Loop?
  • Intro: Introduction to\u00a0LoopDocs
    • Requirements: What is needed regardless of build method
  • There are two ways to build - you get the same app either way
    • Build with Browser: Build\u00a0Loop\u00a0app using a browser on any computer or tablet
    • Build with Mac: Build\u00a0Loop\u00a0app with a Mac the first time, or Update next time
  • Set Up: How to set up the\u00a0Loop\u00a0app
  • Operate: How to use the\u00a0Loop\u00a0app
  • Troubleshoot: What to do if you're having trouble with the\u00a0Loop\u00a0app
  • Version: Information about\u00a0Loop\u00a0versions, code customization and development
  • Nightscout: Loop-specific\u00a0Nightscout\u00a0details; Nightscout is an open-source cloud application used by people with diabetes and their caregivers
    • Remote Overview: Overview on issuing commands remotely to a\u00a0Loop\u00a0app using\u00a0Nightscout\u00a0and Apple Push Notifications
    • Loop Caregiver: Companion app useful for remote commands
  • FAQs: Pages with safety tips, frequently asked questions and the Glossary
  • Translation: Links to Google Translate provided as a convenience, no guarantees about the quality of the translation
"},{"location":"intro/overview-intro/#using-links","title":"Using Links","text":"

You will notice many links in the LoopDocs pages pointing to detailed information.

  • If you notice an arrow pointing up and to the right beside the link:

    • This means a new tab or window (depending on your browser configuration) is opened when you click on the link
    • For example, the What is Loop? video is found on YouTube

  • This link format is used anytime the link will take you to a different website

  • In some cases, it is also used when referring to a different LoopDocs page
"},{"location":"intro/overview-intro/#using-tooltips","title":"Using Tooltips","text":"

The LoopDocs pages contain words that may be unfamiliar. For a definition of any word with a dashed underline, simply hover your mouse over the word, or tap on the word on a mobile device, to view the definition. For example, Omnipod has a tooltip.

Every tooltip definition is also found in the Glossary - so head over there if you have trouble reading a tooltip.

"},{"location":"intro/overview-intro/#buildingloop","title":"Building\u00a0Loop","text":"

The process for building the\u00a0Loop\u00a0app is divided into short segments (sections or pages) in the Build tabs of\u00a0LoopDocs.

Best Practice: Learn to Build

You are strongly encouraged to build\u00a0Loop\u00a0for yourself.

  • No links to providers who build\u00a0Loop\u00a0as a service are found in\u00a0LoopDocs
  • If you choose to use such a service, before you begin, you should:
    • Read\u00a0LoopDocs
    • Know how to Set up and Operate\u00a0Loop
    • Ask what features, if any, available with DIY loop are not available with their service
    • These steps are important for your safety
"},{"location":"intro/overview-intro/#use-a-simulator","title":"Use a Simulator","text":"

You can build\u00a0Loop\u00a0and practice with a simulated phone, CGM and/or pump. You can \"dose\" the simulated pump and your real pump at the same time and watch the glucose predictions.

Starting with a simulator can help you decide if you want to move forward with purchasing additional items required to use the app. You can:

  • Learn the interface
  • Explore glucose predictions and dosing recommendations

Locked Phone or App in Background

Do not expect the simulator to work when the phone is locked or the app is in the background. The app relies on a real insulin pump or a real CGM to wake up the app when the phone is locked or the app is in the background. The simulator cannot do this.

Please review Simulator Build for more information.

"},{"location":"intro/overview-intro/#operatingloop","title":"Operating\u00a0Loop","text":"

A significant amount of content is provided on this website and via link to other sources.

Please review these pages when initially setting up and learning to use\u00a0Loop.

Some techniques are specific to\u00a0Loop, but the general concepts of how man-made insulin works and strategies to test basal, carb ratios and insulin sensitivity apply to all the hybrid closed-loop systems, commercial and open source.

"},{"location":"intro/overview-intro/#development-history","title":"Development History","text":"

Loop\u00a0is an open-source, shared project. The entire project has been, and continues to be, done by volunteers. From the code to the website, you're getting all this because dozens of volunteers have given their time, so please add your time by reading this website thoroughly before embarking on your\u00a0Loop\u00a0journey.

Here are development history links to other resources for you to explore.

  • The early history of\u00a0Loop\u00a0development:

    • History of\u00a0Loop\u00a0and\u00a0LoopKit, written by\u00a0Loop\u00a0developer Nate Racklyeft

  • The early days and the many advances brought about by the #We Are Not Waiting diabetes community:

    • The Artificial Pancreas Book written by Dana Lewis and check out her website DIYPS.

  • How the Omnipod Eros pods were cracked to work with\u00a0Loop:

    • Insulin Pumps, Decapped Chips and Software Defined Radios written by\u00a0Loop\u00a0developer Pete Schwamb
    • Deep Dip Teardown of Tubeless Insulin Pump by Sergei Skorobogatov
"},{"location":"intro/requirements/","title":"Requirements Overview","text":""},{"location":"intro/requirements/#two-ways-to-build-the-app","title":"Two Ways to Build the App","text":"

With the release of\u00a0Loop 3\u00a0, there are two ways to build the app.

  • If you have never built\u00a0Loop\u00a0before:
    • If you already own a Mac then you may prefer the Build with Mac method
    • For all others, you will probably prefer the Build with Browser method

The Build Steps have been split into two tabs:

  • Build with Browser
    • Build with a browser on any computer or tablet
    • App is installed on the iPhone using TestFlight
  • Build with Mac
    • App is built on a Mac with Xcode connected to the iPhone
    • The operating system on the Mac and the version of Xcode must be kept up-to-date

There are some requirements common to both methods. Some requirements are specific to only one method.

"},{"location":"intro/requirements/#common-requirements","title":"Common Requirements","text":"

These requirements are independent of how you build the Loop app:

  1. Compatible iPhone
  2. Compatible Pump
  3. Compatible CGM
  4. RileyLink Compatible Device
    • Not needed with Omnipod DASH
    • Required for Medtronic and Omnipod Eros
  5. Apple Developer Membership
    • If building for a child, be sure to read Loopers Need Their Own Apple ID
    • Build with Browser - requires a paid developer account
    • Build with Mac - can build a free version with some limitations and must rebuild weekly
"},{"location":"intro/requirements/#added-requirements-to-build-with-browser","title":"Added Requirements to Build with Browser","text":"

If you plan to build using the Build with Browser instructions, you also need:

  1. A free GitHub account

Detailed instructions are included in the link above.

"},{"location":"intro/requirements/#added-requirements-to-build-with-mac","title":"Added Requirements to Build with Mac","text":"

If you plan to build using the Build with Mac instructions, you also need:

  1. Compatible Computer
  2. Xcode (a free Apple application)
"},{"location":"intro/requirements/#getting-ready-to-build","title":"Getting Ready to Build","text":"

Go through the Common Requirements to see what you need to actually Loop.

Simulator Option

If you want to test the Loop app without attaching CGM or pump hardware, you can run a simulated CGM or simulated pump. You can use actual CGM data using Dexcom Share or Nightscout as a Remote CGM.

These simulators are part of the Loop app and are available with either build method you choose.

Check out the Simulator page.

Once you have chosen your Build Method, go through the pages for that build method several times before beginning, especially if this is new to you.

When you are ready to proceed, work through the tasks on each page. Take your time. You can do one a day, take a week per page or blaze through them quickly. Just be sure to read carefully and if you are confused - reach out for help: How to Find Help.

After you build Loop on your phone, keep following along in the docs as you Set up and Operate your Loop app.

"},{"location":"intro/requirements/#next-steps","title":"Next Steps:","text":""},{"location":"intro/requirements/#review-the-common-requirements","title":"Review the Common Requirements","text":"

Before you start either build method, review the Common Requirements. First one is Compatible iPhone. On each page, keep clicking Next (or n) until you've finished with the Intro pages and are ready to Build.

"},{"location":"intro/requirements/#build-with-browser","title":"Build with Browser","text":"

Click on the link if you are done reviewing the common requirements and you want to skip ahead to Build with Browser.

"},{"location":"intro/requirements/#build-with-mac","title":"Build with Mac","text":"

Click on the link if you are done reviewing the common requirements and you want to skip ahead to Build with Mac.

"},{"location":"loop-3/add-cgm/","title":"Add CGM","text":""},{"location":"loop-3/add-cgm/#cgm-choices","title":"CGM Choices","text":"

A CGM can be added from the Heads-Up-Display (HUD) or from the Loop Settings screen \u2699\ufe0f.

The HUD will look like the graphic below if no CGM or Pump is connected with Loop:

Loop can be connected to the following CGMs:

  • CGMs that reside on the same phone (internet not required)
    • Dexcom G5
    • Dexcom G6 (use this for Dexcom ONE)
    • Dexcom G7 (Loop 3 only)
    • Minimed Enlite CGM
      • Medtronic Pump only
      • You must add pump first
        • If Enlite is connected to Medtronic pump and that pump is connected to Loop, then an option for Enlite shows up when choosing a CGM, not visible in graphic below
    • Libre: LibreTransmitter was added to the dev branch (and thus will be supported in the next release of Loop)
      • Only some Libre sensors are supported; some have encryption that limits DIY use
      • No details for using Libre will show up on this page until the next release - please read Build Loop-dev and follow the links to understand what you are doing if you choose a development branch
  • CGMs that require active internet (WiFi or Cell)
    • Dexcom Share
    • Nightscout Remote CGM
  • CGM Simulator - useful to learn the app interface
"},{"location":"loop-3/add-cgm/#add-cgm","title":"Add CGM","text":"

To add a CGM, go to the Settings screen \u2699\ufe0f, tap on Add CGM, and tap on your CGM.

If you later decide to use a different CGM type, you must first delete the CGM and then add CGM to choose the new one.

  • For Dexcom G5, G6 or ONE, you must delete the CGM when you change transmitters (about once every 90 days)

Set up Focus Mode

Don't forgot to check your iOS Focus Notifications when you add or change your CGM.

  • Dexcom CGM must have the app for G6 or G7 added separately
  • Libre CGM (dev branch only) must have Loop notifications turned on to get CGM alerts
  • Nightscout or other alerts: if you use another app to provide alerts, be sure to add them to Focus as well
"},{"location":"loop-3/add-cgm/#remote-upload-from-loop","title":"Remote Upload from Loop","text":"

Loop provides an option to upload CGM values to a remote service like Nightscout or Tidepool. In many cases this can be a preferred solution.

With Loop 3, the data-store on the Loop phone keeps a full week of data. If there is an interruption in the upload, when it is restored, Loop will fill in up to 1-week of CGM data that was not previously uploaded.

Some people use Dexcom Share to feed their remote services. There have been outages with Share. When those occur, the data is not back-filled like it is with Loop.

This is the reason why there's a comment under each CGM below to select Upload Readings.

"},{"location":"loop-3/add-cgm/#dexcom-g5-g6-one","title":"Dexcom G5, G6, ONE","text":"

To use the Dexcom G5, G6 or ONE:

  • Select Dexcom model, use Dexcom G6 for either G6 or ONE
  • Dexcom app must be running on the Loop iPhone and paired to an active transmitter
  • User must enter that active transmitter ID in the location indicated by the red rectangle in the graphic below
  • Do not enter your Share Credentials
    • The graphic below shows Tap to set
    • Do not tap, leave it alone
  • Only add the transmitter ID to Loop after it is paired with the Dexcom app on your phone

"},{"location":"loop-3/add-cgm/#where-to-get-the-transmitter-id-for-dexcom-g6","title":"Where to get the Transmitter ID for Dexcom G6?","text":"

You can find the transmitter ID in your Dexcom G6 app or on the back of the transmitter box (please refer to the below screenshots).

  • In your Dexcom G6 app
  • Tap \"\u2699\ufe0f Settings\"
  • The transmitter ID is located under section \"CGM\" where it says \"Transmitter\" with a the 6-digit string.
  • Alternatively, while in Settings, tap on the > in the \"Transmitter\" row: your transmitter ID is the 6-digit identifier next to \"SN\" (short for serial number).

  • On the back of your transmitter box
  • Your transmitter ID is the 6-digit number next to \"SN\" and the QR code on the back of the carton.

It is suggested that you enable Remote Upload from Loop.

"},{"location":"loop-3/add-cgm/#change-dexcom-sensor","title":"Change Dexcom Sensor","text":"

When you change a Dexcom G5, G6 or ONE sensor, you do this in the Dexcom app. When the sensor completes warmup and CGM values are once again reported in the Dexcom app, Loop picks these values up because you are using the same Dexcom Transmitter.

"},{"location":"loop-3/add-cgm/#change-dexcom-transmitter","title":"Change Dexcom Transmitter","text":"

When you change the Dexcom G5, G6 or ONE Transmitter, you need to delete your CGM selection from Loop and then add it back after you complete the pairing with the transmitter in your Dexcom app.

FYI: When You Change Dexcom Transmitters (click to open)

Before you change Dexcom transmitters, select the Delete CGM button at the very bottom of the CGM info page in Loop. If you leave the transmitter connected in Loop, you may have trouble pairing your new transmitter. If pairing does work, then Loop will not get CGM data from the Dexcom app on your phone.

Follow the instructions here: What do I do when I switch Dexcom transmitters?.

The Dexcom G7 is handled differently - Loop automatically detects when a new sensor/transmitter pair is added to the Dexcom G7 app.

Your selection to enable Remote Upload from Loop must be repeated with each new Transmitter. The default setting is disabled.

"},{"location":"loop-3/add-cgm/#about-dexcom-share-credentials","title":"About Dexcom Share credentials","text":"

You do NOT need your Share account info listed in Loop settings if you are using a G5 or G6 system. The transmitter ID is sufficient. In fact, you should leave your Share credentials blank so that you don't accidentally become internet-dependent for CGM data if you forget to update your transmitter ID when you start a new transmitter.

"},{"location":"loop-3/add-cgm/#dexcom-g7","title":"Dexcom G7","text":"

This is only available on Loop 3.

You must have the G7 app on the same phone as Loop. When the G7 app switches to the next sensor/transmitter assembly, Loop automatically switches too.

It is suggested that you enable Remote Upload from Loop.

Don't forget Health Permissions

For those switching from Dexcom G6 to Dexcom G7, you might forget to add permission for the G7 app to write to Apple Health. If you want long-term history of those CGM readings to persist in Apple Health, turn on the permission for the Dexcom app to write glucose to Health.

If either the G6 or the G7 has permission to write to Apple Health, then Loop will delete the Loop glucose data in Apple Health that are older than 3 hours and newer than 1 week. The Dexcom app will write its glucose values to Health when each value is 3 hours old.

"},{"location":"loop-3/add-cgm/#medtronic-enlite-cgm","title":"Medtronic Enlite CGM","text":"

The Medtronic Enlite CGM is only available if you have connected it to your compatible Medtronic Pump.

  • Make sure your pump reports the Enlite CGM results
  • Go through the Add Pump to Loop steps with that Medtronic pump
  • Then do the Add CGM steps and the sensor should be presented as an option
"},{"location":"loop-3/add-cgm/#dexcom-share-as-a-cgm","title":"Dexcom Share as a CGM","text":"

If you need to use Dexcom Share

If the dexcom is on another phone, you can use Share if internet / cell coverage is good.

Dexcom Share is not available for Dexcom ONE CGM.

The Dexcom Share credentials (in other words, account login) is the same as what you used to log in to the active Dexcom app on your iPhone. Dexcom Share account is not always the same login info as your Dexcom Clarity account. The information is entered when you first log in to the app and then is never displayed again, nor visible under any information screens. If you have forgotten your G5/G6 account info, you can delete the Dexcom app and redownload it to try logging in again. This will not cause a restart of any sensor sessions in progress.

If you do not enter your Share credentials correctly into Loop, you will get an error when Loop tries to access your Share account to backfill CGM data. An example of the error message is shown in the graphic below. If you see that message, delete your Share account from Loop settings and try again.

"},{"location":"loop-3/add-cgm/#nightscout-remote-cgm","title":"Nightscout Remote CGM","text":"

If the user is already uploading CGM data to their Nightscout URL, they can select that as a source for CGM data for Loop. The user must acknowledge they understand the risks of using a remote source that requires internet, as shown in the graphic below.

In addition to the risks of missing data if the internet is not reliable, you must also make sure the CGM data sent to Nightscout is reliable.

DANGER - Make sure Nightscout CGM Data is Reliable

Just because you can use Nightscout as a CGM source does not mean you should.

If you decide to use Nightscout as a CGM source, make sure the data stored in Nightscout is reliable. If the app you choose uploads bad results to Nightscout, you don't want Loop to use that bad data.

Sensors that can be added to Nightscout via other apps include Dexcom, some Libre and some Medtronic sensors. Please refer to Nightscout Docs: Configure your Uploader.

There are third party apps that bring Libre data to your Loop phone and there are customization instructions starting at Libre Support for Loop 3.2.x Code that explain how to modify Loop 3 to use one of those apps. Please use these steps to get a version of Loop that does not rely on internet access to work.

It is suggested that you use Open Loop during warmup until the new sensor begins to provide reasonable data. This is especially important with European Libre 2 using direct bluetooth connection.

The xDrip4iOS app (which can also be found in the app store under the name Shuggah) may have a problem during warmup of a new sensor (European Libre 2 using direct bluetooth connection). There were two instances of crazy high values being reported and picked up by Loop 3. One Shuggah user and one xDrip4iOS user who connected via Nighscout as a CGM with Loop 3 had serious overdose of insulin because of bad readings with a new sensor. The developers of xDrip4iOS fixed their application - so make sure you have the latest version. Those developers have no control over what is provided by Shuggah.

The user must enter both the URL and API_SECRET for their site to ensure the security of the data. The URL must start with https:// and cannot have any extra spaces in the line.

When using Nightscout Remote CGM, if the user needs to change credentials or switch to a different CGM, the user must go through the Loop->Settings \u2699\ufe0f->CGM menu.

"},{"location":"loop-3/add-cgm/#change-cgm","title":"Change CGM","text":"

To change CGMs, delete your existing CGM and then add a new CGM.

"},{"location":"loop-3/add-cgm/#change-a-nightscout-remote-cgm","title":"Change a Nightscout Remote CGM","text":"

For Nightscout Remote CGM, the Nightscout URL is opened when tapping on the CGM icon in the Heads-Up Display, while the credential sections with the Delete CGM row are shown when tapping on Loop Settings \u2699\ufe0f, and selecting CGM.

After deleting a CGM, the Head-Up-Display at the top of the Loop main screen will show the Add CGM icon.

"},{"location":"loop-3/add-cgm/#change-other-cgm","title":"Change Other CGM","text":"

Other CGM, you can tap on the CGM from either the Heads-Up Display or tap on Settings \u2699\ufe0f, and select your CGM.

Scroll to the bottom of the screen and select Delete CGM.

For some CGM that can be added to Loop 3 with a patch, the words may be different, but the steps are the same.

"},{"location":"loop-3/add-cgm/#dexcom-g5-g6-and-one-not-g7","title":"Dexcom G5, G6 and One (not G7)","text":"

For older Dexcom sensors, the transmitter is replaced separately about once every three months. In order to enter a new transmitter number, you must first delete the CGM and then add the CGM.

Detailed instructions are found at CGM FAQs: What do I do when I switch Dexcom transmitters?.

Once the Dexcom G7 has been added to Loop, the user only needs to let the Dexcom G7 app know when to use the new sensor. The Loop app automatically switches to the new sensor with no additional steps required by the Looper.

"},{"location":"loop-3/add-pump/","title":"Add Pump","text":""},{"location":"loop-3/add-pump/#pump-choices","title":"Pump Choices","text":"

You can choose a pump from the Heads-Up-Display (HUD) or from the Loop Settings screen.

The HUD looks like the graphic below if no CGM or Pump is chosen:

Switching Pumps?

To change the pump connected to Loop go to Change Pump Type.

Loopers can choose from 3 pumps and a simulator:

  • Minimed 500/700 Series
    • Note: this label does not mean any 5 or 7 series pump works with the app
    • Please refer to Compatible Pump for additional details
  • Omnipod
  • Omnipod DASH
  • Insulin Pump Simulator

Omnipod Terms

The Loop app and LoopDocs use these terms:

  • Omnipod is the older (Eros) pods (requires RileyLink compatible device to Loop)
  • Omnipod DASH is the newer BLE pods (phone talks directly to pod - no extra device needed to Loop)
  • Omnipod Common means information common to Omnipod and Omnipod DASH
"},{"location":"loop-3/add-pump/#summary-of-steps-to-add-a-pump","title":"Summary of Steps to Add a Pump","text":"

Here is an overview of the different steps for adding each pump. Before changing pumps, you need to delete the old pump first. See Change Pump Type section below.

"},{"location":"loop-3/add-pump/#steps-for-omnipod","title":"Steps for Omnipod","text":"
  1. Omnipod Common 1 (choose default notifications)
  2. Insulin Type
  3. Select RileyLink
  4. Omnipod Common 2 (Pair Pod)
"},{"location":"loop-3/add-pump/#steps-for-omnipod-dash","title":"Steps for Omnipod DASH","text":"
  1. Omnipod Common 1 (choose default notifications)
  2. Insulin Type
  3. Omnipod Common 2 (Pair Pod)
"},{"location":"loop-3/add-pump/#steps-for-medtronic","title":"Steps for Medtronic","text":"
  1. Insulin Type
  2. Select RileyLink
  3. Medtronic
"},{"location":"loop-3/add-pump/#add-pump","title":"Add Pump","text":"

Tap on Add Pump in the Settings screen to see pump options (shown in the graphic below).

Tap on your Pump.

Medtronic pump users - skip ahead to Insulin Type.

"},{"location":"loop-3/add-pump/#omnipod-common-1","title":"Omnipod Common 1","text":""},{"location":"loop-3/add-pump/#pod-nofication-defaults","title":"Pod Nofication Defaults","text":"

Here are the common screens for adding Omnipod or Omnipod DASH showing the default settings. You can change the default settings later.

After you complete these screens, you select the insulin type.

"},{"location":"loop-3/add-pump/#insulin-type","title":"Insulin Type","text":"

For all pumps, you can choose from the insulin types below.

  • Insulin Type
    • Rapid Acting (Novolog, Humalog, Apidra) or Ultra Rapid (Fiasp, Lyumjev)
    • Inhaled insulin (Afrezza) is not offered because it is not used in pumps. Non-Pump Insulin

To add a Omnipod DASH pump, skip ahead to Omnipod Commom 2.

Omnipod and Medtronic users should continue to select a RileyLink compatible device.

"},{"location":"loop-3/add-pump/#omnipod-or-medtronic","title":"Omnipod or Medtronic","text":""},{"location":"loop-3/add-pump/#select-rileylink","title":"Select RileyLink","text":"

For Omnipod and Medtronic pumps, you need a RileyLink compatible device to Loop. The Device and your phone must be kept close to your pump for Loop to work.

A new RileyLink compatible device is not listed next to its slider until after you connect the device to Loop. Find the little toggle in the device list, switch on that toggle, and the RileyLink will appear after the toggle is green.

You can personalize the name once it is connected to Loop.

All RileyLink compatible devices in the nearby area, not already connected to a Loop app, will display in the RileyLink Setup screen. Select your RileyLink by sliding the toggle to display green and then press the blue Continue button at the bottom of the screen.

If your device does not appear:

  • Make sure it is charged and turned on
  • Make sure it is not connected to a different phone or app

If you are adding a Medtronic pump, skip ahead to Medtronic.

"},{"location":"loop-3/add-pump/#omnipod-common-2","title":"Omnipod Common 2","text":"

After selecting a RileyLink for Omnipod, all other actions for Omnipod and Omnipod DASH are the same. Once a pod is paired, the Pump display is the same, except the Omnipod screen has a RileyLink Devices section.

For Omnipod (left) and Omnipod DASH (right), you should see the Pair Pod screen.

At this point - you should hit Cancel (upper right of screen) and review the Omnipod Common page before pairing a pod.

New Looper / New Podder

Carefully review the Pair Pod instructions and the rest of the Omnipod Common page before continuing. Then, when you are ready, pair a pod.

If you are not ready to fill and attach a pod with insulin, try filling a pod with water and let it drip into a ziplock bag to test running Loop on the pod. (Be sure the pod is not near anything when you hit \"Insert Cannula\".)

You may enjoy reading Rufus the Bear.

"},{"location":"loop-3/add-pump/#medtronic","title":"Medtronic","text":"

If you followed this page to add your Medtronic pump, you have completed the first three steps. If not, you can prepare your pump now, then do those first three steps using Loop (follow the links). All other steps be completed before you Connect the Pump.

  1. Select Minimed 500/700 Series as your pump
  2. Select Insulin Type
  3. Select RileyLink
  4. Prepare Medtronic Pump
  5. Connect Pump to Loop
"},{"location":"loop-3/add-pump/#prepare-medtronic-pump","title":"Prepare Medtronic Pump","text":"

Loop requires these settings on your Medtronic pump.

Check with your users guide (can be found online if you don't have one) for more detailed instructions on your model of pump if you're not sure how to accomplish these steps.

If you have basal rates, insulin to sensitivity factor and carb ratios in your pump - these will be overwritten (using the Therapy Setting values) when you connect your pump to Loop. If those rates are important to you, record them prior to continuing.

  • Turn off Patterns under the basal menu settings.
  • Set the Max Basal and Max Bolus values in the Medtronic pump to be greater than or equal to the values you enter in the Loop Therapy Settings. Otherwise, Loop will not connect to your pump with the error message: Pump Error. Max setting exceeded.
  • Set your pump's Temp Basal Type to Insulin Rate (U/hr).
  • Set Remote Devices to ON and enter any random ID (010101 will work - avoid using all zeros). This setting is found in the pump's Utilities menu (for x23 continue to Connect Devices, Remotes) and turn ON the Remote Options.
  • Cancel any currently running extended or dual wave boluses. Loop cannot loop with those running.
  • If you are using an Enlite CGM through your Medtronic pump, make sure that is configured properly before adding your pump to Loop
"},{"location":"loop-3/add-pump/#connect-pump-to-loop","title":"Connect Pump to Loop","text":"

The final step is to connect your Medtronic pump to Loop.

  • Make sure your RileyLink is turned on and nearby
  • Add your pump's region, color as shown in the graphic below
    • Note that some Canadian pumps use CM instead of CA for the region code. Select CA/CM in the dropdown menu.

  • Add your pump's 6-digit serial number as shown in the graphic below
  • Click the Connect button to connect the pump to Loop.
  • The spinning icon continues until you see the blue check mark and Continue button
    • If Loop is not successful at connecting, you will get an error message and stay on this screen
    • If the Delivery Limits (max basal and max bolus) in the pump are lower than values you entered in Loop you will see an error message: Pump Error. Max setting exceeded. (See note below for other reasons you might see this message.)
      • In this case, edit the values in the pump and then click Connect to retry.

Max setting exceeded

It turns out the \"Max setting exceeded\" error might be displayed even when Max Bolus and Max Basal Rate are already set appropriately on the pump.

  • If you had previously used a pump that allows multiples of 0.025 U/hr basal rate and you have one of those rates in the basal rate schedule in Loop, you will not be able to connect to a different Medtronic pump that does not support those rates.
  • If this happens to you, cancel out of connecting to that pump
    • Refer to Prep for Medtronic on the Settings page
      • Add a simulator so you can Change the scheduled basal rates
      • Delete the simulator
    • Try again
"},{"location":"loop-3/add-pump/#bolus-in-progress","title":"Bolus in Progress","text":"

If you get an error Bolus in progress on the pump when trying to connect, you probably need to rewind and load insulin into the reservoir.

If the pump has alerted that it is out of insulin, you cannot pair to Loop as a new pump.

"},{"location":"loop-3/add-pump/#final-steps","title":"Final steps","text":"

Once you have successfully connected to the Medtronic pump, click on Continue:

  • You will then be presented with two more screens, click Continue for each
    • Pump Clock message
    • Pump is ready for use screen
  • If you have an x23 or x54 pump, there is one more step - highlighted below

For x23 and x54 Medtronic pump users only

For x23 and x54 Medtronic pump users, there is a packet of information special to those pumps called MySentry messages. If you have never setup this part of the pump previously, you may see a screen, called \"Pump Broadcasts\", at this point in the setup process.Follow the directions on the screen. They will require you to take some manual steps on your pump to \"pair\" it with your Loop app.Basically, you will need to go to your pump's main menu, scroll down to Utilities, then Connect Devices, then Other Devices, turn that setting On, and then select Find Device. Once you do that, click on the Continue button in Loop app and the pairing will take place. This will allow those MySentry packets of information to flow to Loop app.This step does not apply for x22 or x15 pump users, since those pumps do not have MySentry capabilities.

Now that your pump is paired with Loop, you should select the type of battery you are using and decide whether to use My Sentry:

  1. Select your pump's battery type (lithium or alakine)
    • There is a whole page about Medtronic pump batteries
  2. Leave the Preferred Data Source on Event History
  3. If you have a x23 or x54 pump, choose whether to use My Sentry (saves phone battery) or not (saves OrangeLink battery)
    • For other Medtronic pumps, adjusting this setting does not do anything

The Medtronic status and commands available are shown in the Pump Setting page.

"},{"location":"loop-3/add-pump/#change-pump-type","title":"Change Pump Type","text":"

Before changing from one pump type to another pump type, you must delete the old pump type.

  • If you are using Medtronic, scroll to the bottom of the pump screen and select Delete Pump

  • Before switching between Omnipod and Omnipod DASH or any kind of Omnipod to Medtronic, you must deactivate your current pod

    • This does not include changing a pod, so long as the pods are of the same type
    • The Switch to other insulin delivery device button will not be available with an active pod

    • Follow along in the GIF below - it cycles though these steps.

      • Go to the Omnipod screen and tap on Replace Pod
      • Deactivate the pod
      • When deactivation completes, tap on Cancel in upper right
        • If you hit continue instead, tap cancel when Pair Pod screen appears
      • On the main Loop screen, tap on the ! No Pod icon
      • Scroll to the bottom of the screen
      • Tap on Switch to other insulin delivery device and follow the directions to complete the task

    • Now the new pump type can be selected from settings or tapping on the add pump icon on the HUD

The Head-Up-Display at the top of the Loop main screen will now show the add pump icon.

"},{"location":"loop-3/displays-v3/","title":"Displays","text":"

This page has detailed information about Loop 3 Displays.

If you are running Loop v2.2.x, follow this link: Loop v2.2.x Displays.

"},{"location":"loop-3/displays-v3/#main-loop-screen","title":"Main Loop Screen","text":"

The main Loop screen contains a Heads-Up Display (HUD) at the top (when in portrait mode) with various charts in the middle and a toolbar at the bottom. As part of the HUD, important messages will appear in the Status Row location.

"},{"location":"loop-3/displays-v3/#landscape","title":"Landscape","text":"

When the device is in landscape mode, the HUD is no longer visible, but the chart history is increased. In landscape, the exact number of hours varies by phone, but on my test phone, each chart displays the last 8 hours of history along with the next 6 hours of glucose prediction. The toolbar is always visible while the chart display can be scrolled up and down to view charts of interest.

"},{"location":"loop-3/displays-v3/#heads-up-display","title":"Heads-Up Display","text":"

The Heads-Up Display (HUD) shows 3 icons:

  • Left: Glucose status
  • Middle: Loop status
  • Right: Pump status

There is a Status Row underneath those three icons that is used to display bolus progress, some alerts and important messages. The Status Row is also a button that performs an action depending on the message. These are described in the table in the HUD Status Row section. The Status Row is only visible in portrait mode, so make sure to orient your device to look for these messages.

"},{"location":"loop-3/displays-v3/#charts","title":"Charts","text":"

There are several charts on the main screen to help you navigate and understand Loop. Tapping on a chart on your phone opens up additional information.

"},{"location":"loop-3/displays-v3/#glucose-chart","title":"Glucose Chart","text":"

The Glucose Chart displays glucose values in your preferred units.

mg/dL or mmol/L

If your preferred glucose unit is not selected, follow these instructions to change Glucose Units.

The vertical scale is automatically adjusted by Loop to be as useful as possible while including the highest and lowest readings in the chart.

The horizontal axis is set to go forward from the current time through your DIA (insulin duration), so you can see what Loop thinks glucose will be eventually. It then goes back in time as far as there is room, based upon the width in pixels of your screen. Note, if you turn your device to landscape mode you will have more screen real estate and thus will be able to see further back in time.

The glucose Correction Range is shown as a blue bar on the glucose chart. Single-value ranges (such as 100-100 mg/dL), will have a narrower blue bar. When a temporary override range is enabled, a darker blue bar indicates the correction range during that override.

Negative Glucose Prediction

If you have a crazy negative glucose prediction - it is likely that you set an Override with a tiny Overall Insulin Needs percentage.

  • Do not panic - this is a prediction only; not reality.

Best approach:

  • Open the loop until the prediction settles down.
  • In future, do not choose a tiny Overall Insulin Needs percentage to force less insulin
    • Increase the correction range in your override
    • Loop will reduce your basal rate at the next cycle (within 5 minutes)
    • Most users should limit Overall Insulin Needs settings in the range of 50% to 200% (a factor of 2 in each direction)
    • Be cautious adding carbs during an override with a change in Overall Insulin Needs - make sure you understand the effects first

If you tap on the Glucose Chart itself, it will open the Predicted Glucose chart described below.

"},{"location":"loop-3/displays-v3/#predicted-glucose-chart","title":"Predicted Glucose Chart","text":"

The predicted glucose view is a great way to gain insight into the various components\u2019 importance in Loop\u2019s prediction of eventual glucose.

The graph at the top of this view will match your Glucose Chart. Below this chart you will see an explanation of the variables Loop takes into account in predicting your future glucose value: Carbohydrates, Insulin, Glucose Momentum and Retrospective Correction. You can tap on any of the entries to see the effects of that component by looking at the dashed lines.

Display Only

These elements are not turned on and off in the Loop predictions. They just modify the graph so you can view the relative effects.

"},{"location":"loop-3/displays-v3/#active-insulin-chart","title":"Active Insulin Chart","text":"

The Active Insulin chart displays the total insulin contribution from both temp basals and boluses. Active IOB can be either positive or negative. Negative IOB results from the suspension of normally scheduled basals.

The active insulin displayed in the upper right corner of the chart updates as soon as Loop issues a command to your pump.

It may later be modified and the Event History updated if:

  • The command does not go through and Loop is sure it did not go through
  • The user cancels a bolus
  • The user cancels a temp basal

There are some times when communication is interrupted at a critical moment in the communication cycle. When that happens the Loop Alert - Unable to Reach Pump modal screen appears on your device. Typically, this resolves by itself. Click the link above for more information.

Medtronic Only: So long as you have Event History as the Preferred Data Source in Loop settings, primed insulin deliveries (e.g., cannula fills or manual primes) will not be counted towards IOB.

"},{"location":"loop-3/displays-v3/#insulin-delivery-chart","title":"Insulin Delivery Chart","text":"

The Insulin Delivery chart displays a history of the temp basals enacted by Loop. The display is relative to the scheduled basal rates entered in the Loop settings. So, a rate displayed in this chart as +0 units would indicate no temp basal was set, and Loop defaulted to the scheduled basal rate. Individual boluses are indicated by an orange triangle on the chart (shown in the graphic above, near the left-most time). The total insulin delivered since midnight, including all basals and boluses AND (Medtronic Only) priming insulin, is given in the upper right corner of the graph.

Please note that for safety reasons, Loop will assume a bolus was successful, even if it is not sure that the pump responded as expected. Once the communications with the pump settle down, Loop will (almost always) be able to reconcile whether a dose went through as expected. Occasionally, the bolus may be temporarily rendered (drawn) as a very high temp basal rate vs. a (triangle) discrete bolus event. This does NOT mean that the Loop actually enacted a high temp basal rate...only that the bolus is being drawn on the chart as the equivalent of a high temp basal rate.

"},{"location":"loop-3/displays-v3/#event-history-reservoir-and-non-pump-insulin","title":"Event History, Reservoir and Non-Pump Insulin","text":"

Clicking on either the Active Insulin or Insulin Delivery charts will open your Insulin Delivery history. The top of the screen will display the current IOB and the total insulin delivered for the day since midnight (or since the time the loop became active if you started Loop after midnight). There are three tabs that can be viewed, with Event History shown by default:

  • Event History: Event history is a detailed accounting of all pump/pod actions. Both Medtronic and Omnipod users will have a detailed record of event history. If you tap on an event, you get more detail. Turn your phone to landscape to improve readability.

  • Reservoir:

    • Omnipod users should not worry if the reservoir display is blank. Pods do not report or track insulin remaining until their reservoirs get below 50 units remaining. When a pod is deactivated, the reservoir history for that pod is no longer displayed.
    • Medtronic users will have reservoir history displayed in 5-minute increments, unless Loop has been having communication issues.

  • Non-Pump Insulin: The user can enter insulin taken by another method such as inhaled or by injection. The user can choose a different insulin type than used by the pump. This is explained further at this link.

Previous Pod Insulin History

For those who want to delete some recorded insulin near the end of a pod because the site was not absorbing properly, this can be done in Apple Health.

Before attempting that modification, please read this entire section on How does Loop use Apple HealthKit in detail.

Pay special attention to Insulin and Apple HealthKit section.

"},{"location":"loop-3/displays-v3/#active-carbohydrates-chart","title":"Active Carbohydrates Chart","text":"

The Carbohydrate chart displays the carbs used by Loop to predict glucose changes. The active COB is displayed in the upper right corner of the chart. Clicking on the chart will open the Carb Entries history and you can edit/delete any previous entries through that screen. Please read the Meal Entry page for more information about entering and editing carb entries.

"},{"location":"loop-3/displays-v3/#ice-chart","title":"ICE Chart","text":"

Click this link for even more details about Insulin Counteraction Effects. It's a good idea to read both the Meal Entry and ICE pages - this is an important concept.

"},{"location":"loop-3/displays-v3/#toolbar","title":"Toolbar","text":"

The toolbar is always found at the bottom of the main Loop screen in both portrait and landscape orientation. By tapping on one of these icons, you can begin a Meal Entry, start a Pre-Meal Range, initiate a Manual Bolus, select an Override or go to the Loop Settings screen.

From left to right, the icons are:

  • Meal Entry- click on this icon to enter meals. Detailed info regarding how to enter, save, and edit meal entries can be found in the Meal Entry page.

    • For those used to entering carbs on a Medtronic pump or coming from non-Loop DIY systems, Loop will not read carb entries from a Medtronic pump or Nightscout, so you must use the meal entry tool.

  • Pre-Meal Range - click on this icon to start the Pre-Meal Range for one hour or until carbs are entered. (plate symbol turns dark green when active)

  • Bolus - click on this icon to open the Bolus tool.

  • Overrides - click on this icon to select a saved or custom Override or to cancel an override if one is active (heart symbol turns dark blue when active)

  • Loop Settings - click on this icon to make changes to any of your Loop settings.

"},{"location":"loop-3/displays-v3/#hud-details","title":"HUD Details","text":"

Very Detailed Section

This section is packed with an incredible amount of detail. Remember it exists and come back when you need a reference to Loop 3 icons and messages.

If you are a new looper your eyes may glaze over the first time through. Don't worry. But do come back and read this section again after you've used the system in Open Loop mode (before you enable Closed Loop mode). And then come back again after a day or so of closed loop testing.

Experienced loopers need to read the detail on this page. There are important changes from Loop 2.2.x.

The Heads-Up-Display, visible in portrait mode, shows the Glucose Status on the left, the Loop Status in the middle and the Pump Status on the right. Once a CGM and pump have been added to Loop, the Loop Status icon will update and ideally be similar to the graphic below.

  • The Glucose is displayed in the same units as the selected CGM
    • If units are incorrect, quit Loop, allow your CGM app to update and then restart Loop
    • You can override the display units, later, by selecting the units in Apple Health
  • The green Loop icon indicates that within the last 5 minutes Loop completed a cycle
  • The Pump Status indicates the scheduled basal rate is running
    • The +0.0 U display means the basal currently running is 0 U/hr different from the scheduled basal
"},{"location":"loop-3/displays-v3/#loop-status-icon","title":"Loop Status Icon","text":"

The Loop Status Icon is the colored circle in the center of the main Loop display. The three colors displayed are Green, Yellow or Red. In all cases, more information is displayed by tapping on the Loop Status Icon, which brings up a modal message indicating the last time a loop cycle completed and other descriptive text.

"},{"location":"loop-3/displays-v3/#loop-cycle","title":"Loop Cycle","text":"

A complete Loop cycle, at high level, includes these steps:

  • Current Glucose is updated
  • Glucose prediction is calculated along with any recommended change to insulin delivery to maintain future glucose above safety threshold and within correction range
  • Messages are sent to the pump to modify insulin delivery if required and request current pump status
  • Pump acknowledges the loop messages

This table shows examples of Loop Status Icons and what each icon means.

Icon Meaning A green circle indicates the app is in Closed Loop mode and it completed a cycle within the last 5 minutes. A yellow circle indicates the app is in Closed Loop mode and it has completed a cycle in the last 5-15 minutes.It is not unusual to have a few instances of yellow loops per day. They can be caused by being out of range (physically), Bluetooth or RileyLink \u201cnoise\u201d interference, or even that the pump was giving a bolus.Most yellow loops will self-resolve without needing any special troubleshooting. A red circle indicates the Loop has not completed in over 15 minutes.This is not a typical state, and you should troubleshoot the problem.In this case, either the Glucose Icon or the Pump Icon or both will display an alert graphic. When the circle is open at the top, Loop is operating in \u201copen-loop\u201d mode. The color code is the same as for closed loop except the cycle involves updating predictions from available blood glucose values and obtaining pump status; but the app will not make any automated changes in insulin delivery.While Manual Temp Basal (MTB) is active, the Open Loop icon will be displayed until MTB expires or is cancelled. Note that MTB is only implemented in Loop 3 for Omnipod and Omnipod DASH, at the current time.

Fun Fact

The loop status icon will pulse slightly when Loop is communicating with the pump. The pulsing will stop when the communication has completed (green loop) or given up (yellow or red loop).

"},{"location":"loop-3/displays-v3/#example-loop-status-modal-messages","title":"Example Loop Status Modal Messages","text":"

When you tap on the Loop Icon on the main screen, you will see a message similar to one of those shown below. The message content depends on:

  • Closed Loop enabled or disabled
  • How long since the last successful Loop Cycle; <20 minutes, <4 hours, more than 4 hours

On your phone, you should see the green, yellow or red icon in the background - the color is not captured when taking screenshots of the modal message.

"},{"location":"loop-3/displays-v3/#glucose-status-icon","title":"Glucose Status Icon","text":"

The table below shows examples of the Glucose Status Icon and what each icon means. The Glucose Color Code is provided below the table.

Icon Meaning The current glucose reading is displayed. It can be from the CGM or from a finger stick. The value must have been updated within the last 15 minutes to be displayed.For the example shown, a valid trend arrow is available and is blue. Color codes are explained at this link. The last glucose reading from the CGM or from a finger stick is stale, i.e., it was acquired more than 15 minutes ago. In this case, the glucose prediction will stop updating.The HUD Status Row message enables user to enter fingerstick glucose value if desired.If in closed-loop mode, no changes will be made to insulin delivery. If a temporary basal is running, it continues running for the scheduled duration. Once the temporary basal expires, the pump resumes the scheduled basal rate.When the app issues a temporary basal, the duration is always 30 minutes.The user can enter a manual temporary basal duration up to the limits of their pump. If no CGM is currently selected, the Add CGM icon is displayed. The user can add a CGM following these instructions. If no CGM is currently selected, but a glucose value was acquired within the last 15 minutes (from fingerstick or a different CGM), that value is displayed along with a plus sign. By tapping on the icon, the user can add a CGM following these instructions."},{"location":"loop-3/displays-v3/#glucose-color-code","title":"Glucose Color Code","text":"Glucose Range Glucose Value Color Trend Arrow Color 55 mg/dL (3.0 mmol/L) or below red regardless of background color red 56 to 79 mg/dL (3.1 and 4.4 mmol/L) black (light mode) / white (dark mode) yellow 80 to 199 mg/dL (4.4 to 11.0 mmol/L) black (light mode) / white (dark mode) blue 200 mg/dL (11.1 mmol/L) or above black (light mode) / white (dark mode) yellow"},{"location":"loop-3/displays-v3/#cgm-display","title":"CGM Display","text":"

Tapping on the CGM icon in the HUD shows more information about the last CGM reading.

For Dexcom G5/G6 and Share, the same screen is obtained by tapping on Loop Settings->CGM.

For Nightscout Remote CGM, the Nightscout URL is opened when tapping on the CGM icon in the HUD, while the credential sections is shown when tapping on Loop Settings->CGM.

The graphic below shows the result of tapping on the CGM icon when using a Dexcom G6. It includes the time of the last reading to the nearest second, along with other information about that sensor and transmitter. It also has an option to go to the Dexcom app on the same device.

"},{"location":"loop-3/displays-v3/#pump-status-icon","title":"Pump Status Icon","text":"

The nominal pump icon displays high-level status information for the pump with two main components: left side is the basal delivery status and right side is the reservoir status. For Pods, a lifecycle line is displayed underneath the pump icon during the last 24 hours of nominal pod life.

  • The basal delivery status displays the enacted temp basal change relative to the scheduled basal. For example, for a scheduled basal of 0.45 U/hr
    • If Loop sets a temp basal rate of 0.2 U/hr, the icon displays -0.25 U
    • If Loop sets a temp basal rate of 1.5 U/hr, the icon displays +1.05 U
    • When scheduled basal is running, the icon displays +0.0 U
  • But what about Overrides?
    • Using scheduled basal of 0.45 U/hr with override set to 70%, the \"override basal rate\" is 0.315 U/hr
      • That is a value that cannot be set in the pump, but Loop uses it for IOB calculations
        • If Loop sets a temp basal rate of 0.2 U/hr, the icon displays -0.115 U
        • If Loop sets a temp basal rate of 1.5 U/hr, the icon displays +1.185 U
  • The reservoir status indicates insulin remaining graphically and displays a value when less than 50 U remain.
    • For Medtronic Pumps, the reservoir display indicates the level graphically.
    • For Pods, the reservoir graphic is constant until the pod begins to report reservoir level when less than 50 U remain.

The table below shows examples for a few nominal Pump Status Icons and Alert messages that might be shown. In all cases, tapping on the Pump Status Icon opens the Pump Settings screen with more information.

Icon Meaning This nominal pump status graphic is for a Pod with temp basal less than scheduled basal rate and no reported reservoir level. This nominal pump status graphic is for a Medtronic pump running scheduled basal rate and with a half-full reservoir.For a Pod, the reservoir shows full until pod estimates reservoir is below 50 U remaining. This nominal pump status graphic is for a pump running a high temp basal rate with the reservoir level reported. When the reservoir level is above the notification level, the reservoir graphic is orange. This pump status graphic indicates 2 alerts: (1) the 15 U reservoir level is less than the notification level of 20 U selected by this user and (2) a small clock icon is added to the display to indicate the phone time zone and pump time zone do not match. When the reservoir level is below the notification level, the reservoir graphic is yellow.Follow the link for time zone information. This alert message indicates the reservoir reports 0 U. Although pumps will continue to deliver some insulin after this point (max of 4 U for pods, or until all insulin is gone for both pods and Medtronic), the user should be aware that insulin delivery could stop at any moment.Note that if you see a display of 0 U in yellow, that means there is 0.5 U or less reported by the pump. This alert message indicates no pod is currently paired so no insulin is being delivered.Tap on the icon to reach the pod setting screen and pair a new pod, or switch to a different source for providing insulin. This alert message indicates all insulin delivery has been suspended. A Status Row message appears to enable the user to resume delivery with one tap. Alternatively, insulin can be resumed by tapping on the Pump Icon to enter the Pump Setting display and resume from that screen. This alert message indicates the user has initiated a manual temp basal (MTB). While the MTB is active, the Loop Icon Status will also display an Open Loop symbol to indicate no automatic adjustments are made until MTB expires or is canceled. The lifecycle indicator across the bottom of the pod status indicates a pod within the final 24 hours of nominal life.Tapping on the icon takes the user to the pump settings display where the rate and duration of the MTB are displayed. This alert message indicates it has been more than 15 minutes since the app was able to communicate with the pump.Follow these troubleshooting steps. This alert message indicates no pump has been added. Follow the instruction for adding a pump."},{"location":"loop-3/displays-v3/#time-zone","title":"Time Zone","text":"

Loop allows your pump to have a different time zone from your phone.

  • For Medtronic - the pump time shows on the pump display
    • Always use Loop to set your pump time
  • For Omnipod Common - there isn't a clock on pods, but Loop has a concept of \"pump\" time for that pod

Your daily schedule for basal rates, correction ranges, insulin sensitivity factors and carb ratios is displayed with respect to midnight on \"pump time\". When you first Add Pump to Loop, the pump and phone are in the same time zone, but it's important to understand what happens when the time zone changes on the phone.

  • The scheduled rates for basal, correction range, ISF and CR follow the pump time

    • This is true even when your phone updates because of a new time zone (travel) or because of daylight savings (summer) time
    • This is true across pod changes

  • To change the pump time zone to match your phone, select the Pump Settings display

    • An active row is available when phone and pump time zones are different
    • Touch the active row to update the pump time zone to phone time zone
      • Medtronic: Loop sets the pump time to the current phone time
      • Omnipod Common: Loop sends your scheduled basal rates to your pod based on phone time
      • Make sure your gear is close together (phone, pump and, if needed, RileyLink)

The display to modify time zone is slightly different for Loop 2.2.x and Loop 3 (links below):

  • Loop 3 Omnipod
  • Loop 3 Medtronic
  • Loop 2.2.x

You can choose to leave the pump and phone time zones different; the pump icon on the HUD (Loop 3 only) will show the clock icon to remind you. Many people do this for short trips.

"},{"location":"loop-3/displays-v3/#other-time-changes","title":"Other Time Changes","text":"

What about other time changes? Suppose the iOS -> General -> Time & Date is modified to manually change the time, but the time zone is not adjusted. (Sometimes this is done to defeat limits on games. Do Not do this on a Looping phone. If you have an \"old\" glucose reading in the \"future\" - Loop will not predict correctly which may have dangerous consequences.) There will not be an obvious display in the HUD or Omnipod screen (which keys off time zone) but you will get regular warnings that phone does not have automatic time set.

Loop 3 will display this warning modal screen if it detects a problem with the Phone time. It leaves it up the user to decide what action should be taken. To make this warning stop, go to iOS -> General -> Time & Date and enable Set Automatically.

"},{"location":"loop-3/displays-v3/#hud-status-row","title":"HUD Status Row","text":"

The Status Row is located immediately below the CGM, Loop and Pump Icons and is used to provide status, action buttons and information. The messages in the table are in order of priority. For example, a No Recent Glucose message is displayed even when an Override is active.

Bolus In Progress

The bolus messages are displayed with the highest priority:

  • If another message is shown when a bolus starts, the bolus message is displayed instead
  • To return to the other message, such as Override or No Recent Glucose, you must either wait for the bolus to complete or cancel the bolus by tapping on the Status Row
  • To ensure you do not accidentally cancel a bolus, keep the phone locked when not in use
Status Row / Meaning When the user issues a manual bolus through the app, a Starting Bolus information message is displayed. Tapping on this message has no action.As soon as the app issues a command to the pump (or sends it to the RileyLink to be delivered to the pump), the bolus in progress message appears. As soon as a bolus is started, from either a manual command or an automatic bolus, the bolus in progress message is displayed. Tapping on the Status Row causes the app to attempt to cancel the bolus. The app can only cancel a bolus if communication is active between the app and the pump.The message says BolusedvalueoftotalU. The value is based on a timer, so it is possible for an occlusion or other fault to occur while the app indicates bolus is in progress.In case of a fault, the user can tap on the pump icon to force a new pump status reading. For the case of pods, this allows you to silence a screaming pod quickly. Once the app communicates with the pump, the actual delivery status will be updated. If the user taps on the bolus in progress message in the Status Row, the message changes to Canceling Bolus. Tapping on this message has no action. As soon the app determines that the pump is suspended, the Insulin Suspended, Tap to Resume message is displayed. Tapping on the Status Row resumes scheduled basal delivery if communication is active between the app and the pump.Medtronic pump users who suspend directly on the pump will notice a delay before this message is displayed. It is best to use the app Pump Settings screen to suspend the pump. If a higher priority message is not displayed in the Status Row and the glucose value is stale (more than 15 minutes old), the No Recent Glucose, Tap to Add message is displayed. Tapping on the Status Row opens the Manual Bolus screen for entry of a Fingerstick Glucose. Note that if you choose not to accept a recommended bolus on this screen but you want to save the Fingerstick value, you need to tap the Bolus line to force it to 0 U and then tap Save Without Bolusing. However, be aware that, in Closed Loop mode, the app will use that glucose value for the next 15 minutes and may adjust insulin delivery accordingly. If a higher priority message is not displayed in the Status Row and an override is active, the override symbol and name, along with the time at which the override expires, is displayed. Tapping on the Status Row opens the screen for that particular override to enable the user to edit the override. Note that any changes made to that override are applied just to the current session. If you want the override permanently modified, refer to the Overrides instructions. If a higher priority message is not displayed in the Status Row and the Pre-Meal Range is active in the toolbar, the Pre-meal Preset, until time stamp is displayed. Tapping on the status row has no effect for this message.New with Loop 3: The Pre-Meal Preset can be engaged with an Override. When both are active, the Pre-Meal Range supersedes the range of the active Override, but the other settings for that Override still apply. When both are active, the Status Row message reflects the Override with both the Pre-Meal and Override icons in the toolbar highlighted."},{"location":"loop-3/features/","title":"Features","text":""},{"location":"loop-3/features/#work-in-progress","title":"Work in Progress","text":"

work in progress

This page will be deleted after all the relevant information is incorporated into the appropriate locations as part of the development process for Loop 3.

Now that Loop 3 has been released, this page may be updated, but leaving it alone for now.

This page discusses updated versions of Loop features as well as new capabilities provided with Loop 3.

Loop 3 Displays

One thing you may notice on some screens is the primary button, with associated information message, is always visible at the bottom of even small screens. You may need to scroll to see intermediate rows.

For example, if the default action on a bolus screen is to deliver the recommended bolus, that button is visible and active. The button remains fixed as other portions of the screen are scrolled up and down. When you make changes to selections, then the information displayed and the button label updates to reflect the action taken if you tap on the button.

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

"},{"location":"loop-3/features/#non-pump-insulin","title":"Non-Pump Insulin","text":"

If insulin is taken from a different source and the user wants to let Loop know, there is a new method in Loop 3.

With Loop 2.2.x, the user manually entered the Insulin dose into the Apple Health app. Loop then imported that value.

With Loop 3, the \"old\" method still works, but there is a new method for entering this information. This method enables the user to indicate the type of insulin so that the appropriate model is used by Loop. An updated Glucose prediction chart is displayed prior to saving the dose.

"},{"location":"loop-3/features/#enter-non-pump-insulin-before-carbs","title":"Enter non-pump insulin before carbs","text":"

WARNING

If you are planning to enter non-pump insulin to cover carbs and you do NOT want Loop to automatically start increasing insulin based on the carb entry, enter the non-pump insulin first and then add the carbs.

To find out what Loop recommends, without actually dosing with Loop:

  • Wait for a CGM entry (or fingerstick) to appear in the HUD
    • Enter the carbs and continue to the bolus screen, i.e., do not save carbs
    • Note the recommended bolus, but do not actually bolus
    • Back up to the carb entry screen and Cancel
  • Go to the non-pump insulin screen and enter the bolus amount you've decided to take, and select the model if it's different from your pump
    • Don't forget to actually take the insulin
    • Add the carb entry and save the carbs without bolusing

  1. Tap on either of the insulin charts (Active Insulin or Insulin Delivery) on the home screen to display the Insulin Delivery Screen. This screen has 3 tabs.

    • Event History (default) is similar to Loop 2.2.x; however, the event history from a prior pod is not displayed once it is deactivated
    • Reservoir is similar to Loop 2.2.x; however, the reservoir value from a prior pod is not displayed once it is deactivated
    • Non-Pump Insulin is a new feature with Loop 3

  2. Select the Non-Pump Insulin tab to bring up the graphic shown below

    • Tap on the + sign (green solid lines)
    • Log Dose screen is displayed showing the current Glucose prediction
    • The default insulin type is that used by the pump
    • To modify Insulin Type, tap on that row (red dashed lines)
      • Picker wheel allows other insulin types to be selected
      • Note that some insulin types, such as Afrezza are only available for non-pump insulin selection
    • Tap on the Bolus row (blue dash-dot lines) to bring up a keyboard
      • The Glucose prediction chart updates automatically based on the value entered in the Bolus row
      • Tip, add 0.001 to the actual dose to make it easier to see if reviewing in Apple Health
      • Once the user selects Done on the keyboard display, the entered value is displayed on the Bolus row and the Log Dose button changes from gray to blue
      • Tap on Log Dose to record or Cancel to quit

"},{"location":"loop-3/features/#bolus-entry","title":"Bolus Entry","text":"

The bolus following carbs (Meal Bolus) and manual bolus (Bolus) screens are updated from Loop 2.2.x version. There is still a predicted Glucose chart that actively updates as the bolus value is updated and various buttons.

  • With Loop 2.2.x
    • The Recommended Bolus is provided but the default for the Bolus value is 0
    • If the user taps on the Recommended Bolus row, the recommended amount is transferred to the Bolus row
  • With Loop 3
    • The Recommended Bolus is provided AND the default for the Bolus is the recommended value
    • If the user taps on the Bolus row, the amount is modified to 0 and the keyboard is opened for entry

Blue Means Active

  • The blue color indicates an active button, whereas a grey button is inactive.
  • The value displayed on the Bolus row is blue to indicate if you tap on that, you can edit the value
"},{"location":"loop-3/features/#meal-bolus","title":"Meal Bolus","text":"

When the Meal Bolus screen is entered following a carb entry or edit action, the active button might be Save and Bolus or, if no bolus was recommended, Save without Bolusing. The Save refers to saving the Carb entry or Carb edit that led to this screen in addition to saving the amount that might be bolused. It can also refer to saving a fingerstick value entered in the Meal Bolus screen.

"},{"location":"loop-3/features/#accept-recommendation","title":"Accept Recommendation","text":"

In the graphic below, the user enters carbs and taps continue to display the Meal Bolus screen.

  • The left graphic shows a case where a bolus is recommended - tapping on the Save and Deliver button saves the carbs and delivers the bolus
  • The right graphic shows a case where no bolus is recommended - tapping on the Save without Bolusing saves the carbs
  • Note that these graphics are taken from a small phone - the left graphic shows all the information at once whereas the right graphic has an extra information message that requires the user to scroll to see the Recommended Bolus and Bolus rows
  • For both graphics
    • Active Carbs and Active Insulin are displayed above the Glucose prediction graph - these are accurate at the time this screen is entered (before carbs or bolus are saved)
    • The Bolus Summary is presented below the Glucose prediction graph with three rows:
      • Carb Entry, the proposed carbs with the time to add the carbs and the absorption time displayed - to modify that information, tap on the < Carb Entry button at upper left
      • Recommended Bolus displays what Loop recommends for that proposed Carb Entry
      • Bolus default display is what Loop recommends, but user can edit that value

If a CGM entry arrives while in this screen, a Bolus Recommendation Updated modal message will be displayed and must be acknowledged.

"},{"location":"loop-3/features/#modify-bolus","title":"Modify Bolus","text":"

This section is a continuation of the information presented in the Accept Recommendation portion of the Meal Bolus section. In the graphic below, the user overrides the recommended bolus.

  • The left side shows a modified bolus less than the recommended bolus
  • The right side shows a modified bolus greater than the recommended bolus
  • Note that the Glucose prediction graph updates based off the Bolus value, giving the user the opportunity to accept or change their proposed value before tapping Save and Deliver
  • At the next Loop cycle, the app modifies insulin delivery based on the saved information
    • For the example with bolus less than the recommended amount:
      • Loop will NOT begin to automatically increase insulin delivery until the current glucose is above the bottom of the Correction range
      • The recommendation to add insulin when the current glucose is below the Correction Range is only offered as a manual feature and is limited to an amount predicted to maintain glucose above the Safety Threshold
    • For the example with bolus greater than the recommended amount:
      • Loop will probably issue an automatic temporary basal of 0 U/hr
      • This is a common \"super-bolus\" scenario; in other words, \"borrow\" basal for the meal bolus to limit post-meal spikes
  • Remember - the Glucose prediction is what happens if you Save and Deliver and then no further adjustments are made to insulin delivery by Loop

"},{"location":"loop-3/features/#manual-bolus","title":"Manual Bolus","text":"

When the Bolus screen is entered directly from the toolbar, the button choices are Enter Bolus if none is recommended, Deliver if a value is on the Bolus row, or Cancel using the button on the upper left. The user can also tap on the value on the Bolus row to bring up a keyboard to modify that amount. When doing that, the value is automatically set to zero.

Other alert messages might be displayed if the pump or CGM is not active. Those are found on the Loop 3 Displays page.

The two graphics below are examples of manual bolus screens.

  • In the first graphic, no bolus was recommended
    • If you tap on the Enter Bolus button at the bottom, it brings up a screen to enable you to type in an amount and then Deliver it.
    • Alternatively, you can tap the 0 amount in the Bolus row and perform the same action as the Enter Bolus button
    • If you do not want to override the recommendation, hit the Cancel button at the upper left.

  • In the second graphic, a recommended amount is shown
    • If you tap on Deliver that recommended dose is delivered
    • If you tap on the value on the Bolus row, you can override the amount
    • The amount displayed on the Bolus row is modified to 0 U with the first tap - at that point, you may enter a new value or tap Cancel using the button at the upper left of the screen

"},{"location":"loop-3/features/#remote-carb-bolus","title":"Remote Carb / Bolus","text":"

Loop 3 includes a feature for remote input of Carbohydrates and Bolus, enabling caregivers who are not physically present to better assist the individual who requires support in managing Loop.

Please read the documentation about this feature carefully to ensure proper configuration and use: * Remote Command Overview

WARNING

You will be using this feature at your own risk, like any other Loop code you build. It is very important you completely read and re-read the Remote Command Overview before getting started.

There are validation and troubleshooting steps for each section of the guide.

Please make sure not to skip sections as this makes it difficult to troubleshoot.

Be aware:

  • Apple limits how many push notifications (used by this feature) can be received on an iOS device
  • If the system feels too many are being sent, it may begin to throttle notifications
  • There is no published limit, but consider limiting it to 1 per hour
  • When on cellular data, there may be further limitations to protect your data usage
"},{"location":"loop-3/features/#new-with-loop-3","title":"New with Loop 3","text":"

The Loop 3 app, building off work by Tidepool and DIY contributors, provides a major upgrade in user safety, user experience, and user interface with the same great Loop algorithm.

Here are some highlights:

  • Onboarding protocol with guardrails to help configure settings
  • Streamlined main screen display and user experience
  • Better alerts and notifications
  • Omnipod Dash compatibility
  • Fingerstick blood glucose prompts when data is stale
  • Non-pump insulin entry within the app
  • Remote capability for Carbohydrate/Bolus input
"},{"location":"loop-3/loop-3-overview/","title":"Overview","text":""},{"location":"loop-3/loop-3-overview/#loop-3-set-up-overview","title":"Loop 3 Set Up Overview","text":"

Congratulations on Building Loop!

The first time you build Loop 3, the app takes you through the Onboarding process. Review this page before using your app.

Suggestion

  • Read this page all the way through without clicking on any links
  • Scroll back to the top of the page and click the links for more detail on particular topics as needed
    • Use the back button on your browser to return from a link
"},{"location":"loop-3/loop-3-overview/#brand-new-loopers","title":"Brand New Loopers","text":"
  • Review these 3 pages in detail before you touch any buttons on your app
    • Onboarding
    • Add CGM
    • Add Pump

  • Review these pages from the Intro tab of LoopDocs

    • Test Settings
    • Loop Data
    • Meet the Community

  • Read the rest of the pages listed under All Loopers, below.

    • The information on the pages will become clearer as you learn to use the app. You can find a page later using the search function
    • Complete the Onboarding steps to set up Loop
    • Learn to use Loop starting with the Open Loop page
    • Once you are comfortable with manually controlling Loop and have settings that work with the algorithm, move on to the Closed Loop page
    • Make suggestions if you think parts of LoopDocs could be clarified, especially from the viewpoint of a brand-new Looper
"},{"location":"loop-3/loop-3-overview/#experienced-loopers","title":"Experienced Loopers","text":"
  • Skim these 3 pages before you touch any buttons on your app
    • Onboarding
      • Read in detail Onboarding: Experienced Loopers
    • Add CGM
    • Add Pump
      • If switching to DASH, read Change Pump Type
  • Read the rest of the pages listed under All Loopers, below
    • Some of the screens and user interface changed with Loop 3
    • Many of the new Loop 3 features are described
    • Reach out if information is missing or needs to be clarified, suggestions are always welcome
  • LoopDocs design
    • Sections specific to experienced Loopers are after the sections for new Loopers
    • The goal is to make LoopDocs easier for new Loopers to navigate
    • Experienced Loopers can scroll ahead, check the page table of contents or use the search feature
"},{"location":"loop-3/loop-3-overview/#all-loopers","title":"All Loopers","text":"

These pages have a lot of detailed Loop information.

  • Settings
  • Therapy Settings
  • Optional Services
  • Displays

And a lot of detailed information about Status and Commands for:

  • RileyLink
  • Omnipod Common
  • Medtronic

Medtronic Users

You must select Insulin Type on your pump settings screen after updating from Loop 2 to Loop 3 and completing the onboarding. Without an insulin type, closed loop will not work.

"},{"location":"loop-3/loop-3-overview/#safety","title":"Safety","text":"

Please be informed so you can Loop safely.

Consult with your health care professional regarding your diabetes management.

Open Source

  • The Loop app is an open source project used by many, but it is not approved for therapy by any government organization.
  • You take full responsibility for building and running this system and do so at your own risk.
"},{"location":"loop-3/medtronic/","title":"Medtronic Pump","text":""},{"location":"loop-3/medtronic/#pump-settings","title":"Pump Settings","text":"

To bring up the Pump Settings display, tap on the pump icon in the Heads Up Display (HUD) or your connected pump in the Loop Settings screen.

"},{"location":"loop-3/medtronic/#medtronic-status-and-commands","title":"Medtronic Status and Commands","text":"

Medtronic status and commands are found in the Pump Settings screen shown in the graphic below. The bottom section with Pump ID, Firware Version and Region is configured at the time the pump is connected to Loop. You cannot edit those lines.

"},{"location":"loop-3/medtronic/#suspend-delivery","title":"Suspend Delivery","text":"

Tapping on the Suspend Delivery row will suspend all insulin delivery: basals, temp basals, and boluses in progress. When you press Suspend Delivery, the label changes to Suspending while Loop is communicating with the pump. When the label changes to Resume Delivery, all insulin delivery is stopped until the user resumes using the HUD Status Row, the Pump Settings screen or on the pump itself.

As long as the spinning icon is spinning, Loop is trying to execute the Suspend or Resume command. If it fails to complete, a modal alert will appear that says \"Error Suspending\" or \"Failed to Resume Insulin Delivery\" which you must acknowledge. You must then repeat the command to try again. Make sure your RileyLink device is powered on and close to the phone and pump.

When the phone is in portrait mode, so the HUD is visible:

  • The user is alerted that pump is suspended by the HUD Pump Status Icon.

  • The HUD Status Row message can be tapped to resume delivery.

You can still suspend and resume insulin on the pump itself. It may take until the next Loop cycle (typically less than 5 minutes), but Loop will detect that the pump is suspended or basal is resumed and the HUD Status Row will update.

If you request a manual bolus with Loop while the pump is suspended, Loop resumes basal delivery as well. No automated boluses are initiated while suspended, only manual ones.

"},{"location":"loop-3/medtronic/#insulin-type","title":"Insulin Type","text":"

You select insulin type when connecting to a new Medtronic pump.

If you install Loop 3 over Loop 2 with the pump already configured, be sure to set the Insulin Type on the pump settings screen. If no insulin type is set, you will get red loops.

Use this row if you switch to a different type of insulin.

  • The model used by Loop for all the rapid insulin brands are the same, but it's a good idea to record if you change brands - some people notice differences
  • If you switch between rapid and ultra-rapid insulin, you need to let Loop know so it will use the appropriate model
"},{"location":"loop-3/medtronic/#pump-battery-type","title":"Pump Battery Type","text":"

The type of battery used in the Medtronic pump affects how Loop interprets the battery level for the pump.

"},{"location":"loop-3/medtronic/#preferred-data-source","title":"Preferred Data Source","text":"

Leave the Preferred Data Source set to on Event History.

"},{"location":"loop-3/medtronic/#use-mysentry","title":"Use MySentry","text":"

The Use My Sentry row only shows up on pumps that support it.

Using the MySentry feature on some Medtronic pumps when using an OrangeLink causes the batteries to die quickly. This option allows you to turn off MySentry within the Loop app.

"},{"location":"loop-3/medtronic/#devices","title":"Devices","text":"

This allows access to the RileyLink screen for each connected RileyLink compatible device.

"},{"location":"loop-3/medtronic/#pump-battery-remaining","title":"Pump Battery Remaining","text":"

Loop uses the Pump Battery Type to estimate Pump Battery Remaining. For information about the method, review MDT Pump Battery.

"},{"location":"loop-3/medtronic/#pump-time","title":"Pump Time","text":"

Loop keeps the pump time up to date with the phone time automatically. As shown in the graphic in the next section, Loop allows differences in time zone. The user can decide when and if to modify the pump time zone, if different from the phone time zone. If the Pump Time shows as yellow, then the time zones do not match.

"},{"location":"loop-3/medtronic/#change-time-zone","title":"Change Time Zone","text":"

During normal operation, Loop automatically keeps phone time and pump time aligned. In the case of time zone or daylight savings time changes, Loop allows the differences to persist until the user chooses to Change Time Zone. Please review Time Zone for more details.

When the time zone for the pump and phone are not the same, you will notice a small clock symbol in the upper right of the pump status icon.

Navigate to the Pump Settings screen. Right below the Pump Battery Remaining and Pump Time rows, there is a new row Sync to Current Time. When you tap that row, the time for the Medtronic pump is updated to the current Loop phone time.

"},{"location":"loop-3/medtronic/#delete-pump","title":"Delete Pump","text":"

If you want to switch to a different pump you must first delete this one:

  • Deselect your RileyLink compatible device
    • Move the slider(s) so it is no longer green
  • Tap on Delete Pump
  • Acknowledge you really mean it when asked by tapping Delete Pump again
  • Add a new pump

For more information, follow this link: Modify Pump.

"},{"location":"loop-3/omnipod/","title":"Omnipod Pump","text":""},{"location":"loop-3/omnipod/#omnipod-and-omnipod-dash-pump","title":"Omnipod and Omnipod DASH Pump","text":"

The information and user interface for Omnipod (Eros) and DASH pods is the same, except Omnipod DASH pods do not require a RileyLink compatible device. They communicate directly with the phone through Bluetooth.

"},{"location":"loop-3/omnipod/#pair-pod","title":"Pair Pod","text":"

Max Fill is 200 Units

When you fill the Pod do not exceed 200 units.

If you overfill the pods, you may get a pod fault right after priming.

Pod Filling and Insertion

The Pod filling and insertion instructions are the same with the Loop app as they are for the PDM. These videos: Filling a Pod with Insulin and Inserting the Cannula, may be useful.

For DASH Pods:

  • You will use your phone instead of the PDM. Be sure to keep the phone close to the pod during pairing and insertion because the Pod uses a low-power mode during these activities.

For Eros Pods:

  • You will use your phone and RileyLink compatible device instead of the PDM. Be sure to keep the phone and RileyLink close during pairing and insertion because the Pod uses a low-power mode during these activities.

You'll be pairing a pod every 2 or 3 days (max pod life is 80 hours).

You'll see this screen every time you ask Loop to Pair New Pod.

The Omnipod Common pairing protocol is the same for all pods. The difference is that Omnipod requires a RileyLink compatible device and Omnipod DASH does not. There are also slight differences in some of the text and graphics, e.g., Omnipod DASH uses a blue needle cap and Omnipod has a clear needle cap.

Graphic below shows the Pair Pod screen for Omnipod (left) and Omnipod DASH (right).

Loop walks you through each step of the filling, pairing, priming, attaching and insertion process.

It makes sure you are really ready to do the insertion.

Please watch the video of the Loop app screen when pairing a DASH pod to see the full process before pairing your first pod. In this video, once the pod starts priming, you may want to skip forward (it takes about a minute to prime).

Keep Gear Close

  • Make sure the phone (and RileyLink if using one) are close to the pod before you tap Pair Pod
    • Do NOT move devices away from the pod until you see the blue check mark and the Continue button on the phone screen
    • You can then move away to attach the pod to your body
  • Make sure the phone (and RileyLink if using one) are close to the pod before you tap Insert Cannula
    • Do NOT move devices away from the pod until you see the blue check mark and the Continue button on the phone screen
"},{"location":"loop-3/omnipod/#insert-cannula-slider","title":"Insert Cannula Slider","text":"

New Insert Cannula Control

For version 3.3.0 and later, (which means the dev branch right now), there is a new slider to control insertion of the cannula instead of a button to tap. It looks like the graphic below. You place your finger on the darker blue icon and, while keeping your finger in contact with the screen, drag all the way to the right. After the drag operation, as soon as you lift your finger off the phone, the cannula insertion command is sent to the pod.

The Screen that says Setup Complete allows you to change the Scheduled Reminder for this pod if you want a different reminder time (including none) from your usual setting.

  • This only changes the reminder for this one pod
  • If you want to change all future reminders, tap on Notifications to modify the Reminder Default
  • In that same location, you can also change notification for the current pod
"},{"location":"loop-3/omnipod/#pod-status","title":"Pod Status","text":"

The Pod Status screen is shown in the graphic below. The dashed green outline indicates the Device portion that is found only for the Omnipod. All other features of the screen are common for Omnipod and Omnipod DASH.

"},{"location":"loop-3/omnipod/#play-beeps","title":"Play Beeps","text":"

If you want to make sure Loop can talk to your pod, click on the sound icon (highlighted by the red box) in the graphic above. If the icon is greyed out - that means Loop is having a communication issue reaching your pod. Follow the usual Troubleshoot: Pump is Not Responding steps to resolve this problem.

Other Uses

  • Find (or startle) your child
  • Find the pod that fell off overnight and is mixed with the laundry
"},{"location":"loop-3/omnipod/#pod-expires","title":"Pod Expires","text":"
  • This line provides a count-down until expiration along with a graphical representation of pod life
    • Once you are on the final day, the time remaining until expiration starts to report in Hours and Minutes
    • The solid bar is proportional to pod hours since activation
      • It is blue for the first 48 hours
      • It is orange for the last 24 hours and also appears in the HUD Pump Status icon
      • After expiration, a full-width red bar is shown here and in the HUD Pump Status icon
  • Once the pod officially expires, at 72 hours, there is an 8 hour grace period
    • Insulet does not guarantee the pod will keep working that long, but it often does
    • A note will appear on the Pod Status screen with count-down text:
      • Change pod now. Insulin delivery will stop in HH hours, MM minutes or when no more insulin remains
"},{"location":"loop-3/omnipod/#basal-report","title":"Basal Report","text":"

The next row changes the label depending on the situation. In all cases, the current basal rate is reported.

Label Description Scheduled Basal Pod is running the scheduled basal rate Insulin Delivery Pod is running an automated or manual temporary basal rate"},{"location":"loop-3/omnipod/#insulin-remaining","title":"Insulin Remaining","text":"

Pods start reporting reservoir values when 50 U are left.

Value Meaning 50+ U Pod reservoir is greater than 50 U Value U Pod reservoir is estimated to be at least as great as the indicated value. 0 U Pod will attempt to deliver up to 4 U after it reports 0 U. This is not guaranteed. The pod senses when it is not successful delivering pulses and that can happen before 4 U have been delivered."},{"location":"loop-3/omnipod/#activity","title":"Activity","text":""},{"location":"loop-3/omnipod/#suspend-delivery","title":"Suspend Delivery","text":"

You may want to consider using a Manual Temp Basal of 0 U/hr instead of suspend.

Tapping on Suspend Delivery brings up a timed reminder screen. You can choose to be reminded (via a beep on the pod itself) with 4 choices (or you can cancel the request):

  • 30 minutes
  • 1 hour
  • 1 hour 30 minutes
  • 2 hours

After you select the reminder time, Loop issues a command to the pod to halt all insulin delivery: basals, temp basals, and boluses in progress. The label on the Suspend Delivery row changes to Suspending while Loop is communicating with the pump. When the label changes to Resume Delivery, all insulin delivery is stopped until the user resumes using the HUD Status Row or the Pod Status screen.

As long as the spinning icon is spinning, Loop is trying to execute the Suspend or Resume command. If it fails to complete, a modal alert will appear that says \"Error Suspending\" or \"Failed to Resume Insulin Delivery\" which you must acknowledge. You must then repeat the command to try again. For Omnipod, make sure your RileyLink device is powered on and close to the phone and pod.

When the phone is in portrait mode, so the HUD is visible:

  • The user is alerted that pump is suspended by the HUD Pump Status Icon.

  • The HUD Status Row message can be tapped to resume delivery.

"},{"location":"loop-3/omnipod/#no-manual-bolus-while-pod-is-suspended","title":"No Manual Bolus While Pod is Suspended","text":"

If you request a manual bolus with Loop while a pod is suspended, Loop will send a notification that Bolus Failed with instructions that Pump is Suspended, Resume Delivery. In other words, you must resume delivery before you will be allowed to bolus with pods.

"},{"location":"loop-3/omnipod/#suspend-timer-reminder","title":"Suspend Timer Reminder","text":"

At the end of the reminder time, an alert beep is issued by the pod and a modal alert will be provided on the Loop app. You must acknowledge the modal alert on the phone to silence future pod alerts.

  • If you do not acknowledge the modal alert, the pod will keep beeping
  • If you need a silent pod, consider using Manual Temp Basal of 0 U/hr instead of Suspend

Manually Resume Insulin Delivery

The halt of all insulin delivery continues until you manually resume. There is no automatic resumption of basal insulin from a suspend command.

If you select a Manual Temp Basal command of 0 U/hr instead of Suspend:

  • Basal Delivery automatically resumes at the end of the selected duration without need for Loop to command it
  • At the end of the duration, Loop will restore Closed Loop, if you were in closed loop when you issued the Manual Temp Basal command
  • There are no beeps on the pod to remind you to resume insulin delivery
"},{"location":"loop-3/omnipod/#manual-temp-basal","title":"Manual Temp Basal","text":"

Tap on the Set Temporary Basal Rate to select a Manual Temp Basal.

This brings up the Temporary Basal screen shown on the left of the graphic below.

  • You can select any basal rate from 0 U/hr to your maximum basal rate set in Delivery Limits
  • You can choose any duration up to 12 hours in half-hour increments
  • Once you select rate and duration and tap Set Temporary Basal, Loop goes into Open Loop mode and the pod is commanded to that rate and duration.

In other words, you can leave your phone behind and the selected basal rate continues for the selected basal duration. There will be no automated adjustments of delivery for the temp basal duration.

"},{"location":"loop-3/omnipod/#during-manual-temp-basal","title":"During Manual Temp Basal","text":"

This Pod Only

The manual temp basal command from Loop tells the pod to initiate a temp basal for the designated rate and duration.

  • The pod itself takes care of the temp basal with no further interaction with Loop
  • Loop will no longer issue commands to the pod without manual intervention from the user until the expected duration ends or user selects Cancel Manual Basal
  • Loop continues to request and receive status reports from the pod while the pod is within communication range

Deactivating this pod and pairing a new one interrupts the temp basal.

If you still need that basal rate, you must initiate it on the new pod.

Once the manual temp basal command is sent to the pod, Loop changes to Open Loop mode and updates displays as shown in the graphic above

  • Pod Status screen:
    • The Basal Report updates with the new rate and label indicates Insulin Delivery
    • The row label changes to Cancel Manual Basal and reports the time remaining until the temp basal expires
  • Main screen (refer to red rectangle highlights):
    • The HUD Loop Status Icon changes to an Open Loop icon and the HUD Pump Status Icon indicates Manual Basal
    • The Insulin Delivery plot indicates the planned duration of the manual temp basal
    • The Glucose Prediction updates using that assumed change in insulin delivery

So long as you were in Closed Loop before requesting the Temp Basal, Loop returns to Closed Loop automatically when the duration ends or you cancel the temporary basal.

Automatic Resumption of Scheduled Basal

The phone does not need to be in contact with the pod for insulin delivery to return to scheduled basal at the end of the selected duration. That duration is commanded along with the temporary rate. Once the pod accepts that command, and you'll get an error message if it does not, the pod will resume scheduled basal rate without further commanding if there is insulin in the reservoir and a pod fault does not occur.

For situations where you need a modification of your insulin needs that is not dependent on a particular pod, review the information on the Overrides page.

"},{"location":"loop-3/omnipod/#devices","title":"Devices","text":"

For Omnipod, there is a Devices section used to access the RileyLink status and commands screen.

"},{"location":"loop-3/omnipod/#pod-details","title":"Pod Details","text":"

The Pod Details table, shown in the graphic below, reports:

  • Time at which pod was Activated
  • Time at which pod will Expire
  • Access to Device Details

Time Drift

The pod will expire when it thinks it has been 80 hours. The pod clock may drift a few seconds with respect to phone time during the pod life. The Expiration time gets updated when the pod reports how long it thinks it has been since it was activated.

"},{"location":"loop-3/omnipod/#device-details","title":"Device Details","text":"

Some additional details from the most recent pod status response message are displayed if you tap the Device Details row, as shown in the graphic below. Most people will not need to view this.

The graphic shows an example for Omnipod on the left, Omnipod DASH (TWI BOARD) in the middle and Omnipod DASH (NXP BLE) on the right. Do not worry about the different board styles (Device Name) for DASH. The developers did that for you. If you are asking for help from a mentor - they may request this information.

"},{"location":"loop-3/omnipod/#replace-pod","title":"Replace Pod","text":"

When you tap on the Replace Pod row, the Deactivate Pod screen, shown below, is displayed.

  • If you tap Deactivate Pod on this screen, insulin delivery stops for this pod and cannot be resumed
  • If you have changed your mind, tap Back or Cancel to continue using the pod

"},{"location":"loop-3/omnipod/#configuration","title":"Configuration","text":""},{"location":"loop-3/omnipod/#notification-settings","title":"Notification Settings","text":"

When you tap on the Notifcation Settings row, the graphic below is displayed. The notifications are a combination of beeps on the pod with associated modal alerts on the phone app that must be acknowledged to prevent future beeps.

  • Expiration Reminder Default: changes the reminder time for any future pod (not the current one)
  • Scheduled Reminder: affects the reminder for the current pod (not future pods)
    • If no pod is connected, you will not see the Scheduled Reminder section
  • Low Reservoir Reminder: changes the reminder level for the current pod and all future pods
    • If no pod is connected, the app will not allow you to modify this setting
    • Change it after the next pod is paired
  • Critical Alerts: Information row about which alerts can be silenced by phone settings

"},{"location":"loop-3/omnipod/#confidence-reminders","title":"Confidence Reminders","text":"

When you tap on the Confidence Reminder row, the graphic below is displayed. You can choose from three levels of audible responses that Loop requests from the pod:

  • Disabled: no audible pod alerts to acknowledge commands
  • Enabled: each manual command provides an audible sound to acknowledge it:
    • For manual dosage change, the pod beeps at both the beginning and end of the manual command.
    • For automated dosage change, the pod does not beep.
  • Extended: Automated dosage change beeps, similar to the manual commands when set to Enabled

"},{"location":"loop-3/omnipod/#insulin-type","title":"Insulin Type","text":"

You selected insulin type when connecting to this pump.

Tap on this row if you switch to a different type of insulin.

  • The model used by Loop for all the rapid insulin brands are the same, but it's a good idea to record if you change brands - some people notice differences
  • If you switch between rapid and ultra-rapid insulin, you need to let Loop know so it will use the appropriate model
"},{"location":"loop-3/omnipod/#pump-time","title":"Pump Time","text":"

Click on Time Zone to understand how Loop treats \"pump\" time for pods.

When the Pump time zone matches the phone time zone, the Pump Time is displayed with black font.

When the phone time zone and pump time zone do not match, there is a clock icon on the main screen in the Pump Status Icon of the HUD.

  • Tap on the Pump Status Icon in the HUD (top red rectangle in graphic below)
  • Information about Time Change is provided on the Omnipod screen
  • The Pump Time displays the clock icon and yellow font
    • The Sync to Current Time row appears
    • Tap on the Sync to Current Time row to choose whether to make Pump Time match Phone Time or not (bottom red rectangle in graphic below)

"},{"location":"loop-3/omnipod/#other-time-changes","title":"Other Time Changes","text":"

What about other time changes? Suppose the iOS -> General -> Time & Date is modified to manually change the time, but the time zone is not adjusted. (Sometimes this is done to defeat limits on games. Do Not do this on a Looping phone. If you have an \"old\" glucose reading in the \"future\" - Loop will not predict correctly which may have dangerous consequences.) There will not be an obvious display in the HUD or Omnipod screen (which keys off time zone) but you will get regular warnings that phone does not have automatic time set.

Loop 3 will display this warning modal screen if it detects a problem with the Phone time. It leaves it up the user to decide what action should be taken. To make this warning stop, go to iOS -> General -> Time & Date and enable Set Automatically.

"},{"location":"loop-3/omnipod/#previous-pod-information","title":"Previous Pod Information","text":"

When you tap on the Previous Pod Information row, a graphic similar to those shown below is displayed. This provides summary information about the pod before the one currently in use.

If the previous pod had a fault and you choose to report it to Insulet, this screen reports the PDM reference code that Insulet uses in their tracking system.

Do Not Call Insulet about -049 (0x31) Faults

If you should happen to get a fault where the last 3 digits of the PDM ref code are \"-049\" (the Hex Designation is fault code 0x31), do not report this to Insulet and do not ask for a replacement. This means Loop did not ensure the pod was in the correct state to accept a command. In other words, it was a bug in the Loop code.

We believe the code has been updated to prevent these faults. There was a brief period during development in which at least one of these happened - this was fixed July 3, 2022. If this happens to you, report it on zulipchat for the developers, save a Loop Report and rebuild if you have an older version of the development code.

With Loop 3, do not leave the screen open and unlocked for long periods of time without first reading Is there an increase in pod failures on Loop?

"},{"location":"loop-3/omnipod/#pod-error-messages","title":"Pod Error Messages","text":"

This section presents some of the error message screens you may see specific to pods.

"},{"location":"loop-3/omnipod/#pod-faults","title":"Pod Faults","text":"

You are likely to hear a pod fault before Loop notices. If your phone is locked, Loop only checks status every 5 minutes for Omnipod or 3 minutes for Omnipod DASH.

Unlock your phone, open Loop, navigate to the Pod Status screen and tap on Deactivate Pod to stop the noise. The pod fault - even if it does not show up in the HUD or the Pod Status screen, will be picked up by the process of hitting Deactivate Pod. You can then view the Fault information in the Previous Pod Information screen.

"},{"location":"loop-3/onboarding/","title":"Onboarding","text":""},{"location":"loop-3/onboarding/#onboarding","title":"Onboarding","text":"

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.

"},{"location":"loop-3/onboarding/#entering-and-editing-values","title":"Entering and Editing Values","text":"

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
"},{"location":"loop-3/onboarding/#glucose-units","title":"Glucose Units","text":"

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:
    • Quit onboarding
    • Click on the link FAQs: How Do I Change Glucose Units?
    • Start the Loop app again and Onboarding will restart
"},{"location":"loop-3/onboarding/#onboarding-steps","title":"Onboarding Steps","text":"

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.

"},{"location":"loop-3/onboarding/#welcome-to-loop","title":"Welcome to Loop","text":"

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

"},{"location":"loop-3/onboarding/#apple-health-permissions","title":"Apple Health Permissions","text":"

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.

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

"},{"location":"loop-3/onboarding/#usage-data-sharing","title":"Usage Data Sharing","text":"

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:

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

  • Do not share any usage data
  • Share the Loop version number, phone type and iOS version number
  • Additionally share usage data in terms of events only - health data such as values for glucose, insulin and carbs is not collected
"},{"location":"loop-3/onboarding/#share-usage-data","title":"Share Usage Data","text":"

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

  • Statistics on loop failures can show which devices are causing more issues and which issues are more widespread
  • Pod failures show whether particular versions of Loop affect the rate of failure, which helps determine fixes
  • Learning how often particular features, like overrides, are used helps with future user interface design and improvements
  • Language and location information helps understand the user base so localization (language translations) can be prioritized
  • Version information helps quantify risk when a bug is found in a particular version of Loop, giving an indication of how many people may be affected

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

"},{"location":"loop-3/onboarding/#connect-loop-to-nightscout","title":"Connect Loop to Nightscout","text":"

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

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

  • If you were using a Nightscout site with a prior version of Loop, you need to type it in again.

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.
"},{"location":"loop-3/onboarding/#therapy-settings-onboarding","title":"Therapy Settings (Onboarding)","text":"

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.

  • 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 setting section on this page has a link to a more detailed description of that setting on the Therapy Settings page.
      • 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
      • Carb Ratios
      • Basal Rates
      • Delivery Limits
        • Maximum Basal Rate
        • Maximum Bolus
      • Insulin Sensitivites
"},{"location":"loop-3/onboarding/#guardrails-while-onboarding","title":"Guardrails While Onboarding","text":"

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.

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

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.

mmol/L

People using mmol/L should avoid the red (the min or max end points) glucose values for their settings. They sometimes cause a crash.

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

"},{"location":"loop-3/onboarding/#glucose-safety-limit","title":"Glucose Safety Limit","text":"

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.

"},{"location":"loop-3/onboarding/#correction-range","title":"Correction Range","text":"

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

"},{"location":"loop-3/onboarding/#manual-vs-automated-dosing","title":"Manual vs Automated Dosing","text":"

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.

  • 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.
"},{"location":"loop-3/onboarding/#pre-meal-range","title":"Pre-Meal Range","text":"

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.

"},{"location":"loop-3/onboarding/#carb-ratios","title":"Carb Ratios","text":"

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
"},{"location":"loop-3/onboarding/#basal-rates","title":"Basal Rates","text":"

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.

"},{"location":"loop-3/onboarding/#medtronic-pump-users","title":"Medtronic Pump Users","text":"

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
"},{"location":"loop-3/onboarding/#delivery-limits","title":"Delivery Limits","text":"

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

"},{"location":"loop-3/onboarding/#medtronic-pump-users_1","title":"Medtronic Pump Users","text":"

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.
"},{"location":"loop-3/onboarding/#maximum-basal-rate","title":"Maximum Basal Rate","text":"

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.

"},{"location":"loop-3/onboarding/#maximum-bolus","title":"Maximum Bolus","text":"

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.

"},{"location":"loop-3/onboarding/#insulin-sensitivities","title":"Insulin Sensitivities","text":"

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.

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

"},{"location":"loop-3/onboarding/#therapy-settings-review","title":"Therapy Settings Review","text":"

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.

"},{"location":"loop-3/onboarding/#notifications-and-bluetooth","title":"Notifications and Bluetooth","text":"

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.

"},{"location":"loop-3/onboarding/#cgm-and-pump","title":"CGM and Pump","text":"

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

  • Add a CGM
  • Add a Pump

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.

"},{"location":"loop-3/onboarding/#experienced-loopers","title":"Experienced Loopers","text":"

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.

  • 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
"},{"location":"loop-3/onboarding/#check-imported-settings","title":"Check Imported Settings","text":"

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:

  • Insulin Type: ensure the correct insulin type is selected
"},{"location":"loop-3/onboarding/#carb-absorption-time-update","title":"Carb Absorption Time Update","text":"

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.

"},{"location":"loop-3/onboarding/#carb-data-source","title":"Carb Data Source","text":"

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.

"},{"location":"loop-3/services/","title":"Optional: Services","text":"

## Loop Services

Near the bottom of your Loop settings screen is a section called \"Services\".

Sevices are Optional

  • Loop will work whether you use these or not.
  • Nightscout is highly recommended by experienced Loopers but can be added later - you don't need it to get started.
  • If you are running Loop 2.2.x, see Loop 2 Services

The services are added by tapping on the + sign and choosing the service from the list. Services are shown alphabetically. The most common services are Nightscout and Tidepool.

"},{"location":"loop-3/services/#nightscout","title":"Nightscout","text":"

There is a whole section in LoopDocs about Nightscout. Please follow this link to the Using Nightscout with Loop section of LoopDocs. That also has the links you might need to the official Nightscout Documentation (different website).

If you have an existing Nightscout site, it's still a good idea to review that section, but here's the quick summary of how to add your Site URL and API_SECRET to have your Loop data transmitted to your Nightscout site. If you can\u2019t remember your API_SECRET, it can be found under Settings, Reveal Config Vars for Heroku sites (or Application Settings, Connection Strings for Azure sites).

The two most common errors in filling out this section are:

  1. Failure to use https:// in the site URL. If you use http:// (see how that doesn't have the \"s\" at the end?), you will get an error message about an App Transport Security policy.
  2. Having a trailing slash on the end of the URL (or an embedded space). If you copy and paste from a web browser, make sure to delete the trailing slash on the URL entry.

More Tips about Nightscout

  • One family had an app configured to block some websites for their child's phone and accidentally blocked their Nightscout URL - took them a while to figure out that mistake.
"},{"location":"loop-3/services/#tidepool","title":"Tidepool","text":"

With Loop 3.2.x and newer versions, data can be directly uploaded from Loop to Tidepool.

User Beware

Don't use the Loop Tidepool uploader yet unless you want to help the developers work through some known issues. The Tidepool Mobile app still works to upload some of your Loop data from Health.

  • There is a new authentication framework in Tidepool
    • Loop developers are working on handling this new authentication protocol
  • One other problem is that data uploaded with the Tidepool Mobile uploader from Apple Health shows up as duplicate data
    • Even if you turn off access of the Tidepool Mobile uploader to Apple Health, there will still be 7-days of overlap with Loop that will display as duplicated data (think 2x carbs, insulin etc in your Tidepool Web display) when you enable Loop Tidepool service as the uploader

Please refer to the LoopTips: Data: Tidepool page for more information about Tidepool. The Tidepool display browser is undergoing some updates; the information on these pages will be updated after changes happen.

The Tidepool Mobile app serves 2 purposes:

  1. Allow notes to be recorded with associated glucose, carbs, and insulin record for a snap shot in time
  2. Upload Loop data stored in Health to the Tidepool database for display in their browser tool; when the Connect to Health feature is enabled

With the new Loop Service to upload to Tidepool, additional information that is not stored in Health can be made available to Tidepool. However, this is a work in progress.

At the current time:

  • If you have Tidepool Mobile installed on your phone, with the Connect to Health feature enabled, while also using the Tidepool Service in Loop, all of your carb and insulin records will be doubled on the Tidepool Web browser display
    • In other words, your data is uploaded by the Tidepool Mobile app and by the Loop app and duplicates are not filtered (at the current time)
  • Short Term: There is a filter button at the bottom right of the browser display where you turn off the Loop portion for days when you have both Tidepool Mobile uploader and Loop uploader turned on

When you add the Tidepool Service to Loop, be sure to disable Tidepool Mobile ability to read from Apple Health.

  • Warning: Even when you turn off the access to Health on the Tidepool Mobile app on the day that you turn on Loop Tidepool service, you will still get 7 days of overlap because Loop stores 7 days of data.

You can still use the note taking feature with Tidepool Mobile when Health is not connected, although you must have internet connectivity for this to work.

Tidepool Support is available to help troubleshoot issues or answer questions about using Tidepool. Contact them via email at support@tidepool.org.

"},{"location":"loop-3/services/#loggly","title":"Loggly","text":"

Loggly is a free logging service. If you sign up for an account, you'll need to go under Source Setup and then Customer Tokens. Copy and paste your customer token into your Loop App settings for Loggly.

"},{"location":"loop-3/services/#amplitude","title":"Amplitude","text":"

Amplitude is a remote event monitoring service and can be used to quickly identify errors and events with Loop. Amplitude stores the events and allows you to view those events as points in time. To retrieve the details of the events you will need to look at corresponding mLab data entries to get a complete picture of the issues. If you sign up for a free account with Amplitude, you will be given an API Key that you can enter here to have Loop integration setup.

"},{"location":"loop-3/services/#next-step-loop-displays","title":"Next Step: Loop Displays","text":"

Great job, almost finished! Now that you have completed your services, let's move onto understanding your Loop Displays.

Loop displays is a valuable tool for understanding your Loop and a great page to review when troubleshooting.

"},{"location":"loop-3/settings/","title":"Settings","text":""},{"location":"loop-3/settings/#loop-settings-screen","title":"Loop Settings Screen","text":"

The Settings screen, shown in the graphic below, is reached by tapping the gear icon in the Toolbar on the Main Loop Screen.

Each section and row on the Settings screen is described below.

"},{"location":"loop-3/settings/#closed-loop","title":"Closed Loop","text":"

The user can select closed loop or open loop using this slider. When you first start Loop, we encourage you to leave this slider disabled and become familiar with the app using Open Loop mode.

As soon as Closed Loop is enabled, Loop will begin automatic adjustment of insulin dosing. Please ensure the settings you entered are appropriate for the Loop algorithm.

No automatic (closed loop) adjustment of insulin will occur and the slider will be disabled under the following conditions.

  • No Pump added
  • No CGM added
  • User set a Manual Temp Basal
"},{"location":"loop-3/settings/#recommended-insulin","title":"Recommended Insulin","text":"

With every loop cycle - typically every 5 minutes - Loop updates the glucose prediction using

  • CGM or Fingerstick glucose value (no older than 15 minutes)
  • COB from meal entries
  • IOB from previous insulin delivery
  • Your Therapy Settings

Based on this prediction, Loop calculates a modification to insulin dosing to bring the user into the desired correction range. This can be a reduction in basal to raise the glucose prediction or a recommended bolus, subject to Delivery Limits, to lower the prediction. The glucose prediction is shown in the Glucose Chart along with the measured glucose values.

  • When in Open Loop, no automated action is taken.
  • When in Closed Loop, automated action is taken based on the selected Dosing Strategy.

If you find this confusing, read how to Think Like a Loop on the LoopTips website.

"},{"location":"loop-3/settings/#dosing-strategy","title":"Dosing Strategy","text":"

This row gives you the ability to select Dosing Strategy. The Dosing Strategy only affects the method by which the recommended bolus - if any - is delivered. The current selection is noted underneath the Dosing Strategy label. The default (initial) value for this setting is Temp Basal Only. Tap on the arrow to the right to modify your selection.

Words in Graphic

Temp Basal Only: Loop will set temporary basal rates to increase and decrease insulin delivery.

Automatic Bolus: Loop will automatically bolus when insulin needs are above scheduled basal, and will use temporary basal rates when needed to reduce insulin delivery below scheduled basal.

Regardless of the Dosing Strategy selected, when glucose is below target or predicted to go below target, Loop decreases basal insulin using Temporary Basal.

Temp Basal Only: Subject to your Delivery Limits, Loop will deliver the Recommended Bolus over 30 minutes using positive temp basals (i.e., increase over your scheduled basal rate) to increase your IOB.

Automatic Bolus: Subject to your Delivery Limits, you receive 40% of the Recommended Bolus at every loop cycle.

"},{"location":"loop-3/settings/#automatic-bolus","title":"Automatic Bolus","text":"

When you first start Loop, we encourage you to leave Dosing Strategy set to Temp Basal Only until you are sure your settings are dialed in.

The Automatic Bolus selection causes Loop to provide 40% of the recommended dose as a bolus at the beginning of each Loop cycle (when a CGM reading comes in). This is a faster method of getting the recommended insulin delivered. When Loop delivers extra insulin, the scheduled basal rate continues unchanged.

As with all Loop versions, you can manually bolus at any time by pressing the Bolus icon in the center of Loop's Main Screen. Any bolus recommendation that you see when you press the Bolus icon will be 100% of the Recommended Bolus.

"},{"location":"loop-3/settings/#configuration","title":"Configuration","text":"

The Configuration section allows entry to the following screens:

"},{"location":"loop-3/settings/#therapy-settings","title":"Therapy Settings","text":"

There's a LoopDocs page devoted to therapy settings. Click on the link to get to that page: Therapy Settings.

"},{"location":"loop-3/settings/#add-pump-for-therapy-settings","title":"Add Pump for Therapy Settings","text":"

But I don't see Therapy Settings!

Therapy Settings is only accessible in the Settings screen when you have a pump connected to Loop.

  • Loop needs to know the parameters for the pump
  • There are several options presented below
"},{"location":"loop-3/settings/#option-1-prep-for-pods","title":"Option 1: Prep for Pods","text":"

If you add an Omnipod (requires RileyLink) or Omnipod DASH up to the Pair Pod screen and then cancel, Loop will use the common Omnipod details to allow you to modify your Therapy Settings.

"},{"location":"loop-3/settings/#option-2-prep-for-medtronic","title":"Option 2: Prep for Medtronic","text":"

If you need to modify Therapy Settings before connecting to a Medtronic pump:

  • Add the Insulin Pump Simulator
    • Tap on the Pump in settings or the HUD to bring up the control screen
    • Select the type of Medtronic
    • Adjust the Therapy Settings as required
  • Delete the Insulin Pump Simulator
"},{"location":"loop-3/settings/#option-3-simulate-loop","title":"Option 3: Simulate Loop","text":"

If you want to use Loop in parallel with your current method of dosing insulin.

  • Add the Insulin Pump Simulator
  • Tap on the Pump in settings or the HUD to bring up the control screen
  • Choose the type of pump you wish to simulate (notice each pump has specific basal rates and ranges available)
  • For best fidelity, use a real CGM (if available on the same phone) or set up the CGM to be from Dexcom Share or Nightscout
  • For every meal or correction, you can echo that meal or correction with Loop using the simulated pump - watch and learn from recommendations and predictions
"},{"location":"loop-3/settings/#usage-data-sharing","title":"Usage Data Sharing","text":"

iOS 15

If you are running an iOS 15 device, this screen is shown in German regardless of the language you choose for Loop. That is an accident that will be fixed by the next release. The English version is shown below.

You can review and modify your preference for Usage Data Sharing as shown in the graphic below:

If you change the check mark, it is immediately modified. Tap on Settings in upper left to return to the main Settings screen.

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

  • Do not share any usage data
  • Share the Loop version number, phone type and iOS version number
  • Additionally share usage data in terms of events only - health data such as values for glucose, insulin and carbs is not collected
"},{"location":"loop-3/settings/#pump","title":"Pump","text":"

The information about the pump section is detailed on several different pages. Follow the links below:

  • Add or Modify Pump
  • Omnipod or Omnipod DASH Status and Commands
  • Medtronic Status and Commands
"},{"location":"loop-3/settings/#cgm-settings","title":"CGM Settings","text":"

The information about the CGM is found on the Add or Modify CGM page.

"},{"location":"loop-3/settings/#services","title":"Services","text":"

The Services section allows additions of other services such Nightscout, Tidepool, Loggly and Amplitude.

Please refer to the Optional: Service page.

"},{"location":"loop-3/settings/#support","title":"Support","text":"

The Support section enables the user to provide output data (Loop Report and/or Critical Logs) about the app. This information can be very helpful to folks trying to assist with problem reports.

The graphic below shows the screen provided when you tap on the Support row at the bottom of the Settings screen.

"},{"location":"loop-3/settings/#issue-report","title":"Issue Report","text":"

Tap on the Issue Report row, on the graphic above, to create a Loop Report text file with a lot of useful information for the mentors or developers if they need to assist you in solving a problem. This covers 84-hours (to enable a full pod history for users of Omnipod or Omnipod DASH). When you tap that row, you'll see a message that the file is loading. That message never goes away but the rest of the page fills in fairly quickly. After that happens, use the up arrow to see various options to save the report.

Issue vs Issue Report

Be aware:

  • Issue (on github) is used to report code problems
  • Issue Report is an action in Loop app to provide information you may need when you ask for help: refer to How to Find Help

It's a good idea to use the Issue Report button and save it along with a screenshot if you think you will ask for help. You can always discard these if you resolve the problem on your own.

Pro Tip

The Loop Reports can be saved in the Files section on your iPhone. I have a folder on my phone Files named Loop Reports.

You can upload them to zulipchat from your phone (new feature) using the paperclip in the zulipchat app. (Don't see a paperclip - update your app.)

"},{"location":"loop-3/settings/#submit-bug-report","title":"Submit Bug Report","text":"

Tap on the Submit Bug Report row to bring up one of the two views shown in the graphic below. The left view is if you do not have a github account (or the phone is not signed in to your account). The right view is if your github credentials are available.

In either case, the first action should be to add a term or phrase to the search box (red rectangle) to see if your issue has already been reported and to read the status if it has been reported. Please refer to the GitHub Issues section for more information.

Not for Build or Settings Help

Submit Bug Report should be used when you believe there is an error in the code.

  • Use How to Find Help instead for these cases:
    • Trouble building
    • Trouble pairing a pod
    • Trouble with red loops
    • RileyLink is not working
    • Trouble adjusting your settings
"},{"location":"loop-3/settings/#export-critical-event-logs","title":"Export Critical Event Logs","text":"

The last row under Support creates a zip (compressed file) with detailed app information over a 7-day period. It is stored in a different format from the Loop Report and provides critical information to the developers when troubleshooting. Once the compressed file is created, you can save it and later share it with the developers if they request it. You can always discard these if you resolve the problem on your own.

Pro Tip

The Critical Logs zip file can be saved in the Files section on your iPhone. I have a folder on my phone Files named Critical Logs.

You can upload them to zulipchat from your phone (new feature) using the paperclip in the zulipchat app. (Don't see a paperclip - update your app.)

"},{"location":"loop-3/settings/#critical-log-format","title":"Critical Log Format","text":"

The critical logs use a JSON (JavaScript Object Notation) format.

Each day (in user's local time) has the following files:

  • Alerts.json
  • Carbs.json
  • DeviceLog.json
  • Doses.json
  • DosingDecisions.json
  • Glucoses.json
  • Settings.json

The JSON file for each day are zipped into one file for that day and then the zip files are again zipped into a single file that you can save. The current day (up to the current time) is combined with the previous day's data.

The time stamps within the JSON files use UTC.

"},{"location":"loop-3/settings/#app-profile","title":"App Profile","text":"

The Profile Expiration is reported at the bottom of the Settings display along with the number of days remaining before Loop stops working.

The link for How to update (LoopDocs) is provided for build with Mac.

In fine print, the exact date and time of the expiration is reported in your local time zone.

The Profile Expiration is different for GitHub Browser Build method. A feature request is in place (but not yet added to the code) to report the TestFlight expiration for that build method.

"},{"location":"loop-3/therapy-settings/","title":"Therapy Settings","text":""},{"location":"loop-3/therapy-settings/#loop-therapy-settings","title":"Loop Therapy Settings","text":"

During Onboarding, all of your therapy settings were entered.

After onboarding, the Therapy Settings screen is reached by going through the Loop Settings screen after a pump has been added.

When building Loop 3 over Loop 2.2.x, the existing values from Loop 2.2.x are kept where possible and presented to the user as the \"default\" value when moving through each screen.

This page provides more details about each of your Therapy Settings.

"},{"location":"loop-3/therapy-settings/#authorization-required","title":"Authorization Required","text":"

All the settings configured under Therapy Settings are protected by the same authorization method (FaceID, Fingerprint or Passcode) used to enable the app to issue a manual bolus.

"},{"location":"loop-3/therapy-settings/#details-for-therapy-settings","title":"Details for Therapy Settings","text":"

Loop 3 has Guardrails for some Therapy Settings. These are grouped in the Guardrails for Settings section of this page.

New Loopers

New Loopers may prefer settings that show up outside the \"typical\" range.

  • These show yellow font on the picker dial and you must acknowledge a warning message that the selected value is lower, higher or outside \"typical\"
  • It is always fine to pick a yellow or even red value when being cautious

For example, choosing a Correction Range that is higher than \"typical\" when starting to learn Loop is fine. Once you are comfortable with how the system works, the range can be adjusted if desired - entirely up to you in consulatation with your health care professional.

Therapy Settings are used for automated insulin delivery when Loop is in Closed-Loop mode.

  • If your Therapy Settings are not \"dialed-in\" before you enable closed loop, you may experience too much or too little automated insulin delivery
  • Please spend the time to thoroughly understand the effect of each therapy setting
"},{"location":"loop-3/therapy-settings/#screens-displayed","title":"Screens Displayed","text":"

Some screens displayed on this page were acquired during Onboarding.

  • When saving a Therapy Setting
    • During Onboarding, the button is labeled \"Confirm Setting\"
    • Otherwise, the button is labeled \"Save\"
"},{"location":"loop-3/therapy-settings/#glucose-safety-limit","title":"Glucose Safety Limit","text":"

Loop will deliver basal and recommend bolus insulin only if your glucose is predicted to be above the Glucose Safety Limit for the next three hours.

The graphic below shows the information screen presented during onboarding or when user taps the information icon, \u24d8.

The GIF below shows two screens for Glucose Safety Limit.

  • Frame 1: During onboarding, user can accept the default limit by tapping \"Confirm Setting\" or tap the row to configure the range (see Frame 2)
  • Frame 2: The user adjusts the picker wheel to select desired value and then taps on the \"Confirm Setting\" or \"Save\" button

If you feel more comfortable with a higher limit, do not let the yellow font influence you. Once you've used Loop for a while, you can revisit this setting.

Note

The value you select for Glucose Safety Limit will dictate the lowest value on the glucose picker that is available for Correction Range and Pre-Meal Range. Those cannot be lower than the Glucose Safety Limit.

Guardrails for Glucose Safety Limit

"},{"location":"loop-3/therapy-settings/#correction-range","title":"Correction Range","text":"

Your Correction Range is the glucose value (or range of values) that you want Loop to aim for in adjusting your basal insulin and helping you calculate your boluses.

The graphic below shows the information screen presented during onboarding or when user taps the information icon, \u24d8.

The GIF below shows four screens when first adding and selecting a correction range. The red box indicates where the user taps.

  • Frame 1: Tap the + sign
  • Frame 2: Use the picker wheels to select desired values
    • This is the first entry so must start at midnight - additional rows can be added for other times
    • When happy with the picker values, user must tap add
  • Frame 3: This screen is shown only if a value is outside \"typical\"
  • Frame 4: Tap on the \"Confirm Setting\" or \"Save\" button to accept the values

Do not let the yellow font discourage you if you want to have a \"higher than typical\" range to start with. Once you've used Loop for a while, you can revisit this setting.

Guardrails for Correction Range

"},{"location":"loop-3/therapy-settings/#manual-vs-automated-dosing","title":"Manual vs Automated Dosing","text":"

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.

  • 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.
"},{"location":"loop-3/therapy-settings/#pre-meal-range","title":"Pre-Meal Range","text":"

Your Pre-Meal Range is used to temporarily lower your glucose target before a meal to impact post-meal glucose spikes.

The graphic below shows the information screen presented during onboarding or when user taps the information icon, \u24d8.

The GIF below shows three screens from various scenarios. The red box indicates where the user taps. If the user chooses to leave Pre-Meal not set, the Pre-Meal icon in the tool bar is disabled. Some users prefer this.

  • Frame 1: During onboarding, user can choose not to add a pre-meal range by tapping \"Confirm Setting\" or tap the Pre-Meal row to configure the range (see Frame 2)
  • Frame 2: User adjusts the Pre-Meal range using the picker and then \"Save\"
  • Frame 3: If a pre-meal range was added, user can remove it by tapping \"Delete\" and then \"Save\"

Note

  • If you do not add an entry, the pre-meal icon on the toolbar is disabled
  • If you add an entry, the pre-meal icon is activated for 1 hour or until carbs are entered or until the user cancels it

Guardrails for Pre-Meal Range

"},{"location":"loop-3/therapy-settings/#carb-ratios","title":"Carb Ratios","text":"

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

  • At least one carb ratio must be entered
    • Use the + sign, picker wheels and then tap \"Add\"
    • The method was described in the Correction Range section
  • Loop supports 1 to 48 carb ratios per day

Guardrails for Carb Ratios

"},{"location":"loop-3/therapy-settings/#basal-rates","title":"Basal Rates","text":"

Your Basal Rate of insulin is the number of units per hour that you want to use to cover your background insulin needs.

  • Loop supports 1 to 48 rates per day
  • The schedule starts at midnight and cannot contain a rate of 0 U/hr (as the only entry)

Guardrails for Basal Rates

"},{"location":"loop-3/therapy-settings/#delivery-limits","title":"Delivery Limits","text":"

Delivery Limits are safety guardrails for your insulin delivery.

  • Click on one of the limits on this screen, Maximum Basal Rate or Maximum Bolus, to display the picker wheel for that limit
  • You must first move the picker off the current value before saving
    • When onboarding, you can restore the picker to the original level once it has been moved
    • When adjusting settings later, one of the two limits must be changed to make the Save button active
  • You may need to put your finger on part of the screen away from the picker wheel and scroll up and down to see the other setting
  • Make sure both Maximum Basal Rate and Maximum Bolus have the desired value before hitting Save
"},{"location":"loop-3/therapy-settings/#maximum-basal-rate","title":"Maximum Basal Rate","text":"

Maximum Basal Rate is the maximum automatically adjusted basal rate that Loop is allowed to enact to help reach your correction range. Some users choose a value 2, 3, or 4 times their highest scheduled basal rate. Work with your healthcare provider to choose a value that is higher than your highest scheduled basal rate, but as conservative or aggressive as is comfortable.

If the Dosing Strategy is configured to Temp Basal Only, then the maximum basal rate can be used to limit how much extra insulin can be supplied automatically.

Guardrails for Maximum Basal Rate

"},{"location":"loop-3/therapy-settings/#maximum-bolus","title":"Maximum Bolus","text":"

Maximum Bolus is the highest bolus amount that you will allow Loop to recommend at one time to cover carbs or bring down high glucose. The value the user selects for Maximum Bolus is also used to set a maximum level of IOB for automated dosing.

  1. Maximum Bolus is the largest single bolus that Loop will recommend or allow the user to bolus in a single action
  2. Maximum Automatic IOB is two times the value of Maximum Bolus
    • The Loop algorithm will not automatically dose any value that would cause the user's IOB to exceed Maximum Automatic IOB
    • The user can exceed Maximum Automatic IOB with a manual bolus
    • The recommended manual bolus amount is limited by Maximum Bolus

If you manually enter a value in the Bolus screen that is greater than the Maximum Bolus setting and press Deliver, Loop will show a warning message and refuse to bolus that amount.

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.

If the Dosing Strategy is configured to Automatic Bolus, then the maximum bolus that is automatically supplied is 40% of the maximum bolus, but this can be applied at 5-minute intervals. Automatic dosing is limited to keep the user's IOB less than two times the Maximum Bolus setting.

Guardrails for Maximum Bolus

"},{"location":"loop-3/therapy-settings/#insulin-sensitivities","title":"Insulin Sensitivities","text":"

Your Insulin Sensitivities refer to the drop in glucose expected from one unit of insulin over the full duration of the insulin action time. You may have also seen the term Correction Factor or Insulin Sensitivity Factor (ISF). These are all referring to the same setting.

  • At least one insulin sensitivity must be entered
    • Use the + sign, picker wheels and then tap \"Add\"
    • The method was described in the Correction Range section
  • Loop supports 1 to 48 insulin sensitivities per day

Guardrails for Insulin Sensitivities

"},{"location":"loop-3/therapy-settings/#guardrails-for-settings","title":"Guardrails for Settings","text":"

Loop has guardrails for Therapy Settings.

  • The limits in the code are provided for reference below
    • The tables list from left to right: the lower limit, min recommended, max recommended and upper limit values for that guardrail
  • The limits for some settings can be altered by other therapy settings you have selected

Experienced Loopers

The guardrails for each therapy setting used by Loop can be modified with Code Customization.

mmol/L

People using mmol/L should avoid the red (the min or max end points) glucose values for their settings. They sometimes cause a crash.

The font color in the value picker has the following meaning:

  • black: value is within the range \"recommended by Loop\"
  • yellow: value is outside the range \"typical\" for Loopers
    • It is fine to choose yellow values - sometimes that's a good choice for a new Looper
  • red: value is minimum or maximum limit of the range \"allowed by Loop\"

Mobile Device

  • On a mobile device, you may need to scroll the table left to right to see all four values
  • Try landscape mode to see the entire table width without scrolling
"},{"location":"loop-3/therapy-settings/#guardrails-for-glucose-safety-limit","title":"Guardrails for Glucose Safety Limit","text":"Units limit min max limit mg/dL 67 74 80 110 mmol/L 3.7 4.2 4.4 6.0

Glucose Safety Limit Info

Top value available on the picker limited by lowest of:

  • code constraint
  • your Correction Range
  • your Pre-Meal Range
"},{"location":"loop-3/therapy-settings/#guardrails-for-correction-range","title":"Guardrails for Correction Range","text":"Units limit min max limit mg/dL 87 100 115 180 mmol/L 4.8 5.6 6.3 10.0

Correction Range Info

Bottom value available on the picker limited by highest of:

  • code constraint
  • your Glucose Safety Limit
"},{"location":"loop-3/therapy-settings/#guardrails-for-pre-meal-range","title":"Guardrails for Pre-Meal Range","text":"Units limit min max limit mg/dL n/a safety 106 130 mmol/L n/a safety 5.9 7.2

Pre-Meal Range Info

Bottom value available on the picker limited by highest of:

  • code constraint
  • your Glucose Safety Limit
"},{"location":"loop-3/therapy-settings/#guardrails-for-basal-rates","title":"Guardrails for Basal Rates","text":"
  • Limited by your selected pump (or if no pump selected, then generic pump limits apply)
    • Generic Pump rates from 0.05 U/hr to 30 U/hr in steps of 0.05
  • Top value available on the picker is your Maximum Basal Rate (once that is set)
"},{"location":"loop-3/therapy-settings/#guardrails-for-maximum-basal-rate","title":"Guardrails for Maximum Basal Rate","text":"
  • Recommended maximum value available on the picker is 6.4 times the highest basal rate in your scheduled basal rates
    • Values higher than this, if available, are shown in yellow
  • Absolute maximum value is 70 divided by the smallest carb ratio (CR) in your schedule or the maximum rate allowed by your pump, whichever is higher
    • Depending on your basal rate and CR schedules, the maximum value available on the picker might be more that 6.4 times the highest basal rate
"},{"location":"loop-3/therapy-settings/#guardrails-for-maximum-bolus","title":"Guardrails for Maximum Bolus","text":"

The maximum bolus is limited by your pump, but it is a good idea to limit it to the maximum you use for a common \"big\" meal. This limits the bolus for a single manual dose.

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.

"},{"location":"loop-3/therapy-settings/#guardrails-for-carb-ratios","title":"Guardrails for Carb Ratios","text":"

Remember, CR goes in the denominator when calculating insulin dose for carbs. So the min - max values in the table below correspond to stronger - weaker values for CR.

Units limit min max limit g/U 2.0 4.0 28.0 150.0"},{"location":"loop-3/therapy-settings/#guardrails-for-insulin-sensitivities","title":"Guardrails for Insulin Sensitivities","text":"

Remember, ISF goes in the denominator when calculating insulin dose for a correction. So the min - max values in the table below correspond to stronger - weaker values for ISF.

Units limit min max limit mg/dL/U 10 16 399 500 mmol/L/U 0.6 0.9 22.1 27.8"},{"location":"nightscout/loop-caregiver/","title":"Loop Caregiver","text":""},{"location":"nightscout/loop-caregiver/#the-loop-caregiver-app","title":"The Loop Caregiver App","text":"

The Loop Caregiver app is under development to make remote commands easier to implement and monitor.

"},{"location":"nightscout/loop-caregiver/#minimum-requirements","title":"Minimum Requirements:","text":"
  • Loop\u00a0version 3.2.0 or newer
    • version 3.0 works but is not recommended for other reasons
    • version 3.3 and higher offers improved feedback to the Loop Caregiver user
  • iOS 16 or newer for Loop Caregiver phone
  • Nightscout version 14.2.6
"},{"location":"nightscout/loop-caregiver/#prerequisites","title":"Prerequisites:","text":"
  • Complete all 4 steps on the Remote Configuration page:
    • Step 1: Update the Looper's iPhone settings
    • Step 2: Apple Push Notifications
    • Step 3: Add APN to Nightscout
    • Step 4: Test Remote Overrides
  • Read the Remote Commands page and pay special attention to these 2 sections
    • FAQs on Remote Overrides
    • Warnings on Remote Commands

Older Nightscout Versions

If you ignore this minimum version requirement - what happens:

  • If you attempt to use the carb entry in the past or future, the caregiver app accepts it but the remote commands accepted by the Loopers phone show up at the current time - not when the caregiver intended to insert carbs
  • Please take the time to update your Nightscout site to master
  • Nightscout 14.2.6 was released 30-Sep-2022 as Classic Liquorice

If you use Loop Caregiver, please join Loop Caregiver App Zulipchat stream.

As with all development code, monitor Zulipchat for announcements, report any problems you experience, be prepared to build frequently, and pay attention.

"},{"location":"nightscout/loop-caregiver/#build-the-loop-caregiver-app","title":"Build the Loop Caregiver App","text":"

You can build the Loop Caregiver app using the Build with Browser method or the Build with Mac method.

"},{"location":"nightscout/loop-caregiver/#build-with-browser","title":"Build with Browser","text":"

The Build with Browser method is documented on the Build Other Apps with Browser page.

"},{"location":"nightscout/loop-caregiver/#build-with-mac","title":"Build with Mac","text":"

A build script is available to assist in building Loop Caregiver. This should be straightforward for anyone who has previously built \u00a0Loop 3\u00a0 using the script.

  • Open a terminal window.
  • Spot the line below that starts with /bin/bash
  • Click the gray copy button () located near the bottom right side of that line (should say Copy to Clipboard when you hover the mouse over it). Once clicked, a confirmation message that says Copied to Clipboard will appear on your screen. Copy and Paste to start the BuildLoopCaregiver script
    /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildLoopCaregiver.sh)\"\n
  • Important: Click anywhere in the terminal before trying to paste
  • Paste the line into the Terminal window.
    • on Mac, you can do this in one of the following ways:
      • Press Cmd+V
      • or Press Ctrl+click and select Paste from the menu
      • or select Edit => Paste (i.e. click the Edit menu at the top of the Mac screen then click Paste).
    • on PC (Virtual Mac):
      • Press Ctrl+V
  • Once the line is pasted, hit Return (Enter) to execute the script.
  • The script displays the directions for downloading and building. Please read them carefully.

Read Carefully

The output you see in the Terminal may look very similar to when you build the Loop app from a script.

It is pulling down a clone from a different location (LoopKit/LoopCaregiver). It uses some modules from Loop. The target and scheme are automatically selected for Loop Caregiver and if you follow directions for a paid Developer account, the signing is automatic.

"},{"location":"nightscout/loop-caregiver/#use-the-loop-caregiver-app","title":"Use the Loop Caregiver App","text":"

Some limited directions for using the Loop Caregiver app are provided - please also read the Zulipchat stream to stay up-to-date with improvements - especially if you are using a development branch of \u00a0Loop.

"},{"location":"nightscout/loop-caregiver/#add-looper-to-the-loop-caregiver-app","title":"Add Looper to the Loop Caregiver App","text":"

You must add a Looper to continue with the Loop Caregiver app as shown in the graphic below.

  • On the\u00a0Loop\u00a0phone:

    • Tap on Loop -> Settings -> Services -> Nightscout
    • Tap on the One-Time-Password row to see the QR code

    Pro-tip

    Take a screenshot of the QR code and store it on your computer.

    You can then add the QR code to Loop Caregiver without bothering your Looper.

    • Keep the screenshot secure
    • Do not share the QR screenshot when asking for help

  • On the Loop Caregiver phone:

    • Tap on Loop Caregiver -> Settings
    • Enter the name of the Looper, the Nightscout URL (use \u00a0 https://\u00a0) and API_SECRET
    • Touch the QR code row - this opens the camera - point the camera at the QR code from Looper's phone

You can add additional more people under settings. (*Loop Caregiver * can monitor more than one Looper).

"},{"location":"nightscout/loop-caregiver/#main-screen-of-the-loop-caregiver-app","title":"Main Screen of the Loop Caregiver App","text":"
  • Loop Caregiver uses a lot of features from\u00a0Loop\u00a0with some Nightscout-like features in the Timeline.

The Timeline:

  • Autoscales the vertical display for glucose reported over the last 24 hours (plus the forecast if that is turned on)
    • Show Prediction for Timeline is turned off in the graphic below.
  • Horizontal display can be adjusted using the dropdown hours selector and scrolling left/right.
  • A double tap on the Timeline alternates between 1 and 6 hour display

You can also use the Loop Caregiver -> Settings screen to modify:

  • Units used for glucose display: mg/dL or mmol/L
  • Include the\u00a0Loop\u00a0forecast display on the Timeline chart as well as the Glucose chart of the main display (Show Prediction is turned off in the graphic above)
"},{"location":"nightscout/loop-caregiver/#issue-remote-commands-with-the-loop-caregiver-app","title":"Issue Remote Commands with the Loop Caregiver App","text":"

You issue override, carb, and bolus commands using a toolbar similar to the one seen on\u00a0Loop. In the example graphic above, the carb and bolus entries visible were issued remotely.

Carb and bolus commands each require authorization before they are accepted. The authorization (FaceID, Fingerprint, or passcode) matches that required to unlock the Loop Caregiver 's phone.

The use of Loop Caregiver makes remote commands much easier and more reliable.

Go back and review the details about Remote Commands before using the app.

"},{"location":"nightscout/loop-caregiver/#troubleshooting","title":"Troubleshooting","text":"

Troubleshooting steps are found on the Remote Errors page.

"},{"location":"nightscout/new-user/","title":"New Nightscout","text":""},{"location":"nightscout/new-user/#why-nightscout","title":"Why Nightscout?","text":"

Nightscout is not required, but is recommended for Loop

  • A Nightscout site provides a dashboard for remote viewing of Loop actions including the temporary basal rates Loop is setting, the current insulin on board, or a recent bolus and carb entry
  • A Nightscout site provides reports for retrospective review of your settings
  • You will want a Nightscout site:
    • If you are a parent of a little Loop user
    • If you want to see Loop's actions anywhere other than the Looper's iPhone
    • If you want to ask a mentor for help adjusting your settings
    • If you want to prepare reports to evaluate your own settings
    • If you want to prepare reports to hand to your doctor
"},{"location":"nightscout/new-user/#setup-nightscout","title":"Setup Nightscout","text":"

Please visit Nightscout: Documentation to read about Nightscout. There are several options, mentioned in that documentation, for setting up your Nightscout site.

  • You can choose one of many free (except for your time) DIY methods
  • You can choose one of many DIY methods where you pay a monthly fee for data storage
  • You can choose a managed site (for a monthly fee) that creates your site, keeps the software up to date and provides data storage
  • Social Media sites for announcements, help and discussion:
    • CGM in the Cloud Facebook group
    • Nightscout Discord Channel

Once your Nightscout site is operational and you've read the information about using your site, return to LoopDocs to follow the directions on the LoopDocs: Nightscout with Loop page.

Comments

Most of the free DIY methods provide sufficient storage for a single Loop user, but will require you to delete older data after a year or two of use. The one exception is the Google Cloud method which includes multiple GB of storage.

If there are multiple Loopers in your family and you want to stay in the \"free\" tier, each will need their own site to stay under the monthly usage limitations. That means an account for each user under different email addresses for each user.

\"Free\" sites might potentially stop being \"free\" in the future.

One of the Nightscout as a Service providers will not allow you to put in your own Apple Push Notification variables, you must use theirs. If you have no plans to use remote commands via Nightscout, this will not affect you. If you decide to use remote commands, you may need to switch to a different service or get Loop through that same provider for an extra monthly fee.

"},{"location":"nightscout/new-user/#configure-nightscout-to-use-with-loop","title":"Configure Nightscout to use with Loop","text":"

There are a few Loop-specific variables you should configure to get the most out of your Nightscout site. Follow the instructions on the LoopDocs: Nightscout with Loop page.

"},{"location":"nightscout/new-user/#add-nightscout-to-loop","title":"Add Nightscout to Loop","text":"

Once you finish setting up your new Nightscout site, don't forget to enter your website URL and API_SECRET into your Loop settings, LoopDocs: Services - Nightscout. This way Loop will have access to your Nightscout site to upload all the wonderful data.

"},{"location":"nightscout/new-user/#nightscout-troubleshooting","title":"Nightscout Troubleshooting","text":"

If your Nightscout site is not showing CGM (and Loop, if you are Looping) data within about 10 minutes of finishing your setup, then please follow the steps on the Nightscout: Troubleshooting page.

"},{"location":"nightscout/ns-crossref/","title":"Nightscout Cross Ref","text":""},{"location":"nightscout/ns-crossref/#nightscout-documentation","title":"Nightscout Documentation","text":"

A number of pages that used to be in LoopDocs have been moved to the Nightscout documentation. To prevent duplication and inconsistency, those pages have been removed from LoopDocs. A cross-reference to the Nightscout pages is provided below.

  • You can always use the search function of Nightscout: Documentation to find any topic
"},{"location":"nightscout/ns-crossref/#remote-notifications","title":"Remote Notifications","text":"

While the Loop app sends notifications locally on the Loop user's iPhone, parents and caregivers may want those messages on their phones, too. We can achieve this functionality through a combination of Nightscout, IFTTT, Google, and Pushover.

  • Please see
    • Nightscout: Configurations: Pushover
    • Nightscout: Remote Notifications
"},{"location":"nightscout/ns-crossref/#loop-follow","title":"Loop Follow","text":"

Loop Follow was created by Jon Fawcett who took ideas from multiple other apps to create a single app to assist in his caregiving role. It is popular with Loopers who like the display and notifications as well as Loop caregivers. It can work with just the Dexcom Share credentials and/or the Nightscout URL and allows for easy customization of alerts and alarms. Jon handed over maintenance of this app to the Loop and Learn team.

  • Please see
    • Loop and Learn: Loop Follow page
    • Loop and Learn Facebook group
"},{"location":"nightscout/ns-crossref/#pebble-watch","title":"Pebble Watch","text":"

LoopDocs had a page specifically about the Pebble Watchface called SkyLoop Predict, which is no longer being supported. The Nightscout Documentation provides information about many methods for displaying your Nightscout data on a variety of wearable devices.

  • Please see
    • Nightscout: On Your Watch
"},{"location":"nightscout/ns-crossref/#reports","title":"Reports","text":"

Nightscout offers some fantastic data-crunching report tools.

  • Please see
    • Nightscout: Reports
"},{"location":"nightscout/overview/","title":"Nightscout Overview","text":""},{"location":"nightscout/overview/#overview","title":"Overview","text":"

Nightscout is an excellent tool for remotely viewing Loop actions. Nightscout can act as a stand-alone tool or be integrated with Loop. (Nightscout also integrates with other open-source hybrid closed loop systems such as OpenAPS, AndroidAPS and iAPS. LoopDocs focuses on Loop.)

When integrated with Loop, Nightscout provides monitoring of Loop activities such as viewing history of glucose, carbs, boluses, temp basals and overrides; troubleshooting Loop errors; and provides extensive reports for analyzing data trends and patterns. These reports assist when Loop Therapy Settings need to be adjusted.

For caregivers, Nightscout enables remote monitoring and even the ability to issue remote commands through Nightscout when both Loop and Nightscout are properly configured. There are several pages starting at LoopDocs: Remote Overview that provide documentation on this feature. If you are a caregiver, this summary of remote capabilities may encourage you to look into Nightscout.

Remote Commands

  • Loop 2.2.x
    • Overrides can be enabled and disabled
  • Loop 3
    • Overrides can be enabled and disabled
    • Carbs can be entered
    • Boluses can be commanded
    • Loop Caregiver app (under development, iOS only) enables the following from the caregiver's phone
      • monitor Loop
      • issue remote commands for carbs, bolus, and overrides

If you plan to use remote commanding with Nightscout, please read these links with additional information:

  • Set Up Remote for Nightscout
    • Paid Providers and Remote Configuration

Nightscout is useful for many who use Loop. Adults who take care of themselves find the reports and analysis methods from Nightscout provide effective tools to monitor their settings and provide reports for their health care provider. It also stores Loop configurations so they can be reviewed. With Loop 3, the saved Nightscout profiles can be downloaded to a new Loop installation or a new phone for quick onboarding, should you ever need to start fresh.

Setting up a Nightscout site is described in a separate web site: Nightscout: Documentation.

There are Nightscout apps in your iPhone App Store that allow you to view the Nightscout site after you've configured it, or you can use a web browser to view the data. The app alone is not enough - you need to follow the steps to configure your own Nightscout site and obtain your specific Nightscout URL.

  • Nightscout is highly recommended for Loop users, especially for caregivers helping someone use Loop
  • Nightscout displays are often the easiest way to troubleshoot Loop settings if you are having problems and seeking input from others
  • Nightscout provides reporting features for longer-term review and preparing information for your physician
"},{"location":"nightscout/overview/#nightscout-documentation","title":"Nightscout Documentation","text":"

There used to be a lot of Nightscout information found only in LoopDocs, but that was transferred and subsequently updated in Nightscout: Documentation. The information that remains in LoopDocs about Nightscout is Loop specific. So you may be jumping back and forth between the two sets of documents.

  • If you see the Nightscout Owl logo in upper left you are in the Nightscout website
  • If you see the LoopDocs green-loop logo in upper left you are in the LoopDocs website
  • While in the Nightscout tab of LoopDocs, most links have a Nightscout or LoopDocs in the link name
  • Suggestion: open the Nightscout: Documentation in a separate tab or window of your browser for easy access to both websites
"},{"location":"nightscout/overview/#nightscout-with-loop","title":"Nightscout with Loop","text":"

This page provides a general discussion about the Nightscout display, as well as some Loop-specific display information. Over time, interactions between Loop and Nightscout were improved. The information on this page has been updated for Loop 3 and Nightscout version 14.2.6 (or later). Older versions may exhibit some differences in the display of Loop information on the Nightscout site.

"},{"location":"nightscout/overview/#loop-uploads-to-nightscout","title":"Loop Uploads to Nightscout","text":"

The Nightscout display updates when the Loop phone is connected to the internet via WiFi or cellular service. When the uploads stop, the Loop pill becomes \"stale\" (cannot open it) after 15 minutes.

Pills are the little information boxes. They are Nightscout: Plugins that must be enabled with configuration variables and then the display for each pill can be turned on or off within your Nightscout site.

If upload to Nightscout is interrupted, Loop 3 stores up to 7 days of Nightscout information in a local buffer on the phone, and will attempt to upload later when access is restored. Once access is restored, a stale Loop Pill may require 15 minutes before it will open to display additional Loop information.

The Carb pill on the Nightscout site is populated by Loop when Loop is actively uploading to Nightscout - but it may lag the value displayed in the Loop pill by one loop cycle and it will display 0 COB within 5 to 10 minutes if the upload is interrupted. In other words, if the COB pill shows 0 unexpectedly and Loop pill is active, you can believe the value shown in the Loop pill.

"},{"location":"nightscout/overview/#loop-2-red-loop-warning","title":"Loop 2 Red Loop Warning","text":"

With Loop 2.2.9 and earlier versions, when a Nightscout site is selected in Loop Services and is unable to upload messages to that site, Loop keeps trying to upload the buffer of stored messages. This could lead to sluggish behavior in Loop or even cause a \u00a0Red Loop. This can happen if the Nightscout site is not accessible (no WiFi or cellular coverage) or if the database is full and not accepting messages.

Step 1: Remove Nightscout URL from Loop Services

Step 2: Figure out why the Nightscout site is not accepting uploads from Loop and fix that problem.

  • Nightscout: Troubleshooting
  • Nightscout: Database Management

Step 3: Add Nightscout URL to Loop Services

Note - the method used by Loop 3 is not subject to this same problem.

Do you want to know more? (Click to open)

For those who want to know more:

There is a big architectural change between Loop 2 and Loop 3 for remote data services like Nightscout.

It used to be that Loop would keep trying to upload data to Nightscout. If a site could not be reached or would not accept data, that could cause large backlogs. Loop 2 could slow down by trying to keep uploading the backlog. The new system does not allow for this. Uploaders individually keep track of where they are in the upload stream via a lightweight \u201cquery handle\u201d, and if the data in Loop data store expires before upload, that data will be missing in Nightscout.

Loop 3 saves 7 days of information in the data store.

"},{"location":"nightscout/overview/#nightscout-dashboard","title":"Nightscout Dashboard","text":""},{"location":"nightscout/overview/#blood-glucose","title":"Blood Glucose","text":"

Glucose readings from the CGM are shown in green, yellow, or red in the main Dashboard of Nightscout. (The graphic above was generated with Colors enabled in Nightscout; there are other display options.) You can adjust your high and low glucose alarm thresholds in Nightscout by modifying configuration variables. This is optional - defaults are provided if you do not set them. The alarm thresholds affect the color of the displayed CGM data points and, if enabled, determine when an audible and visible alarm sounds. The Nightscout alarm thresholds will not affect Loop performance. Loop only uses the glucose correction ranges in the Loop app settings.

The main dashboard (upper section) for Nightscout displays the time duration you have selected (in the example above, 12 hours). The bottom of the screen shows the last 48-hours of glucose trends. You can scan backward by dragging the bottom timeline to the left, if you want to review specific Loop actions or data in the last two days.

"},{"location":"nightscout/overview/#sage-cage-bage","title":"SAGE, CAGE, BAGE","text":"

The SAGE, CAGE, and BAGE pills are for Sensor Age, Cannula Age, and (pump) Battery Age. These optional pills track the time since your CGM sensor, Pump site, and Pump battery were last changed. You can set up custom alerts to remind you when it is time to change the devices, or simply use the visuals to keep track of your particular timing for site/sensor changes. When these items do not auto-upload, you can use the Nightscout Careportal to input the changes.

  • Loop 3.3.0 or newer: The SAGE and CAGE fields are automatically uploaded
  • Loop 3.2.x or older: None of the fields are automatically uploaded
"},{"location":"nightscout/overview/#carbs","title":"Carbs","text":"

Carbs are automatically uploaded to Nightscout by the Loop app. The amount of carbs on board (active carbs or COB) can be seen by clicking the Loop pill. The size of a white carb dot on the graph is proportional to the amount of carbs entered...bigger meals get bigger dots. Loop does not read carbs from Nightscout for use in looping calculations, it only uploads carbs to Nightscout that have been entered in the Loop app.

"},{"location":"nightscout/overview/#boluses","title":"Boluses","text":"

Insulin boluses are automatically uploaded to Nightscout by the Loop app. The bolus is shown as a filled-in blue lower-half of the dot, and the specific amount of the bolus is also shown. There may be a separation between the bolus and the carb entry, especially if the user preboluses a meal.

The bolus is uploaded to Nightscout as soon as it starts and Insulin on board (active insulin or IOB) is updated in the Loop pill. Should the bolus be interrupted, the Nightscout information is updated when the Loop information updates (assuming internet access is active).

"},{"location":"nightscout/overview/#temp-basals","title":"Temp Basals","text":"

Your current basal profile is automatically updated to Nightscout whenever it is changed by Loop. The dashed blue line represents the scheduled basal profile. The solid blue lines indicate the actual basal amounts set for a given time...so as Loop sets temp basals higher or lower than your scheduled basal rate. If the graph and Loop pill do not agree, you should believe the Loop pill.

"},{"location":"nightscout/overview/#predicted-glucose","title":"Predicted Glucose","text":"

The purple line to the right of the glucose is Loop predicted glucose. Watching the behavior of that purple line can help you understand why Loop is making decisions regarding high or low temps. You can read more on that topic in the LoopDocs: Algorithm section of these docs. If you don't see the prediction (and all other Nightscout and Loop settings are configured), tap on the 3 dots to the right of the 24 to reveal the choice to display AR2 prediction or Loop prediction. Adjust the check boxes to show just the Loop prediction.

"},{"location":"nightscout/overview/#loop-pill","title":"Loop Pill","text":"

The Loop pill is the little display box which, when hovered over or clicked, will provide additional information about recent Loop activities and status. Information included is the last time Loop ran, the temp basal set, IOB, and COB. Looking at the Loop pill is a quick method for assessing if your loop is currently active, as well.

Loop Pill status indicator symbols

X Error in Loop

\u03d5 Recommending basal or bolus, but not enacting (open loop or pump suspended)

\u2301 Enacted a new temp basal

\u21bb Loop is continuing with last temp basal, no change

\u26a0 Warning indicating Loop is either red or has failed to upload to Nightscout for a longer period of time.

Mouse over or touch the Loop pill to view a tooltip containing one or more of the latest status messages. The most up-to-date Nightscout also includes information in the Loop pill for the minimum and maximum predicted glucose, eventual and predicted glucose.

"},{"location":"nightscout/remote-commands/","title":"Remote Commands","text":""},{"location":"nightscout/remote-commands/#requirements","title":"Requirements","text":"

All remote commands require the configuration steps from Remote Configuration.

  • A new One-Time Password (OTP) is required for each remote command that issues a bolus or adds a carb entry
    • The OTP updates every 30 seconds
    • Both the sending device and the Loop phone must have automatic time enabled
  • Remote Overrides do not require a One-Time Password (OTP)
    • There are some versions of Nightscout that provide a row for entry of an OTP for Temporary Override in the Nightscout Careportal
    • Leave that row blank

Do I have to use Loop Caregiver ?

There are a number of methods for using remote commands.

Things everyone needs to know are covered on this page, so you should read it regardless of how you plan to issue remote commands.

If you decide on Loop Caregiver , review both this page and \u00a0Loop Caregiver page.

"},{"location":"nightscout/remote-commands/#qr-code","title":"QR Code","text":"

On the\u00a0Loop\u00a0phone, Nightscout must be included under the Loop -> Settings -> Services section. Navigate to Services and select Nightscout. Tap on the One-Time Password row to view the QR code.

When you need to configure your authentication method, you can either use a saved QR screenshot or scan the QR on the\u00a0Loop\u00a0phone.

Options:

  • Have your Looper (or at least their phone) available
  • Save a screenshot of their QR code
    • Keep this secure
    • Do not share the QR screenshot when asking for help

While you are on the Settings -> Services -> NightScout screen, notice that the 6-digit number on the One-Time Password row updates every 30 seconds.

"},{"location":"nightscout/remote-commands/#set-up-an-authentication-app","title":"Set up an Authentication App","text":"

You need to set up an authentication app to generate one-time-passwords for remote bolus and carbs.

One of the nice features of Loop Caregiver is that it handles the one-time password (OTP) requirements for you.

But even if you choose to use Loop Caregiver , you should configure an authentication app for cases where you don't have access to your Loop Caregiver phone.

There are several authentication apps that support one-time passwords.

"},{"location":"nightscout/remote-commands/#apple-keychain","title":"Apple Keychain","text":"

If you are using an iPhone or a Mac to issue remote commands through a browser or Nightscout app, you can use the \u00a0Apple Keychain\u00a0 which has native support to store passwords and generate one-time passwords.

To set up your Nightscout credentials in \u00a0Apple Keychain:

On the Caregivers device (iPhone or Mac):

  • Go to Apple Settings -> Passwords

  • Tap the + Button up top to add a new Password

  • You will enter your Nightscout credentials

    • Website: Enter a portion of the Nightscout URL, without the leading \u201chttps://\u201d
    • Username: Enter the full Nightscout URL including the leading \u201chttps://\u201d part
    • Password: Enter the API_SECRET for the Looper's Nightscout site
    • Tap Done
  • Next, you are offered a screen that allows you to set up a Verification Code
    • If you need to come back later, you can find that screen again
    • Go to Apple Settings -> Passwords -> Tap the row with your Nightscout URL
  • Tap \u201cSetup Verification Code\u201d
    • This is where you can scan your QR code from the\u00a0Loop\u00a0phone or the saved QR screenshot
    • As soon as the camera reads the QR code, an OTP will begin to appear
    • If the\u00a0Loop\u00a0phone is handy, wait a cycle or two and ensure the 6-digit OTP on the password screen matches that on the\u00a0Loop\u00a0phone and they update at the same time
    • Click Passwords on the upper left to return to the previous screen
  • Select Passwords Options
    • Enable the Autofill Passwords and check Keychain
"},{"location":"nightscout/remote-commands/#using-safari","title":"Using Safari","text":"
  • When you use Safari to view your Looper's Nightscout site and choose the Careportal ()
    • Choose a remote command from the Event Type drop-down menu (remote commands are at the bottom of the list)
    • The OTP will be offered to you for every row - ignore it when entering Carb amount or Absorption Time, or Bolus Amount
    • Select it for the OTP row
    • Note that OTP is not required for Remote Overrides - leave that row blank
"},{"location":"nightscout/remote-commands/#other-authentication-apps","title":"Other Authentication Apps","text":"

There are other Authentication apps available. Here are a few options that you can download from your phone\u2019s app store:

  • 1Password
  • Authenticator
  • Authy
"},{"location":"nightscout/remote-commands/#faqs-for-all-remote-commands","title":"FAQs for all Remote Commands","text":"

  1. If I have multiple Nightscout sites because I support multiple people with T1D looping, do I need multiple APNs Keys? Answer: No. If you support multiple people, you can use the one APNs key in each of their Nightscout sites.

  2. How can I tell if it worked? Answer: You should see your override pill in Nightscout, with the NEXT Loop\u00a0cycle, reflecting that the desired remote action took place. If you are near the\u00a0Loop\u00a0phone, you should see the new override within less than 30 seconds or so.

"},{"location":"nightscout/remote-commands/#faqs-on-remote-overrides","title":"FAQs on Remote Overrides","text":"

Don't forget to read Loopdocs: Overrides.

For remote overrides in particular:

  1. Can I set a different override in Nighscout than I have programmed into\u00a0Loop\u00a0app? Answer: No. You will only be able to enact override presets already programmed into the Loop app.

  2. If I didn't start the override in Nightscout (it was started in\u00a0Loop\u00a0itself), can I still use Nightscout to cancel it? Answer: Yes. You can cancel an override set in\u00a0Loop\u00a0with a Nightscout-set cancel \"temporary override\" command in the careportal.

  3. Can I replace an override set in\u00a0Loop\u00a0with an override set in Nightscout? Answer: Yes.

  4. Can I see on Nightscout when a temporary override has been set using the looper\u2019s phone? Answer: Yes. There will be a grey bar with the name of the override noted and the Loop pill will display the targets and duration. Remember, there is a KNOWN issue with the grey bars, so use the pill as your best guide.

  5. Can a looper cancel a remote override? Answer: Yes. They can tap the heart icon in\u00a0Loop\u00a0so that it is no longer highlighted. This turns off the override, regardless of where it was initiated.

  6. I set a remote override in Nightscout but the Looper tapped the heart symbol in the Loop app, so the override turned off. Will the override get reinstated the next time\u00a0Loop\u00a0completes with internet access? Answer: No. The APN is only sent once. You can set the remote override again if need be.

  7. Can I schedule a remote override ahead of time using Nightscout? Answer: No. When you set a remote override in Nightscout, it starts immediately and lasts for the duration programmed for that override in the Loop app. You can only set an override in advance using the Loop app.

"},{"location":"nightscout/remote-commands/#remote-commands","title":"Remote Commands","text":"

Remote Commands to deliver a bolus or add a carb entry require a \u00a0One Time Passcode\u00a0 (OTP).

Minimum Versions: Loop 3\u00a0 and \u00a0Nightscout 14.2.6

If your Nightscout version does not meet that minimum requirement, remote commands might be accepted but if they are, the time for the commands is always the current time. In other words, Carbs in the Past or Future might be accepted, but would be entered at the current time on the\u00a0loop\u00a0phone.

"},{"location":"nightscout/remote-commands/#warnings-on-remote-commands","title":"Warnings on Remote Commands","text":"

Duplicate Delivery Risk

We want to highlight a very important risk before you get started.

For safety, always assume a previous remote carbs/bolus was delivered. For motivation think of the following example:

  • You send a 5-unit remote bolus.
  • The bolus is delivered to the Looper.
  • Nightscout is having a temporary technical issue and doesn't show the bolus was received.
  • You are watching Nightscout and you don\u2019t see a delivery so you assume it failed.
  • You send another remote 5-unit bolus.
  • The second 5-unit bolus is delivered to the Looper (10 Units total).

You can see the danger of sending duplicate bolus/carbs so be careful. If a remote bolus/carb entry doesn\u2019t show in Nightscout, use your own judgment on whether enough time has passed to try again.

"},{"location":"nightscout/remote-commands/#remote-bolus-then-remote-carb","title":"Remote Bolus, Then Remote Carb","text":"

If sending both, choose Bolus then Carbs

If you plan to send a carb command remotely and later decide to issue a bolus command - STOP and consider.

There are 2 scenarios of concern that could lead to too much insulin:

  • Dosing Strategy is Temp Basal Only (temporary basal)
    • Loop\u00a0will initiate a max Temp Basal when it receives the carbs remote command
    • Your bolus is accepted next and takes place in addition to the high temporary basal
  • Dosing Strategy is Automatic Bolus
    • Loop\u00a0will initiate a percentage of the recommended dose when it receives the carbs remote command
    • Your bolus will be accepted and take place in addition to an automatic boluses or be rejected because a bolus is already in progress

Typically, sending a remote carb entry alone is sufficient for\u00a0Loop\u00a0to know about the carbs and begin to dose for them.

If you really want to both bolus for carbs and enter carbs, then do it in that order.

  1. The bolus, when accepted, may start a zero Temp Basal (temporary basal) (which is \"safer\")
  2. The carbs, when accepted, will cause the app to respond to the carbs
  3. In this case, the prediction includes both carbs and bolus

\u2757\ufe0f Remember - you should pause at least 60 seconds between remote commands or the One-Time-Password (OTP) will be rejected as having already been used.

"},{"location":"nightscout/remote-commands/#use-unique-times-for-remote-carbohydrate-entries","title":"Use Unique Times for Remote Carbohydrate Entries","text":"

Use unique times for remote carbohydrate entries

Instead of adding a second remote carbohydrate entry at an identical time, add one minute to the second entry.

This ensures that Nightscout keeps both entries.

Any Caregiver entering remote carbohydrates needs to be aware of how Nightscout decides what carbohydrates treatments are unique. If two entries have the same hour:minute:second time, Nightscout keeps only one of the entries.

  • It does not affect how the Loop app handles the remote carbohydrate entries it receives
    • The Loop app assigns a unique identifier to each entry; it doesn't depend just on the timestamp
  • It will affect Nightscout and thus LoopCaregiver displays
    • This might lead to the Caregiver thinking they need to send the remote carbohydrate again
    • But Loop has both entries

One example scenario:

  • A caregiver enters 10 g for lunch with a timestamp of 11:30, then waits for child to eat and glucose to start rising
  • They then want to \"edit\" that entry to 15 g, but that is not possible with remote carbohydrates
    • Instead they can add a new 5 g entry
    • They should enter the second entry at 11:31

Second example scenario:

  • A caregiver wants to enter two different absorption times using remote carbohydrates
    • The first entry eating time is at 11:30 for 10 g with 2 hour absorption
    • The second entry eating time is at 11:31 for 15 g wtih 4 hour absorption

The LoopCaregiver app was recently modified to use the seconds from when the new entry was created, instead of using hour:minute:00. This change makes it less likely that two entries with the same timestamp will collide. (One chance in 60.)

Any remote carbohydrate entry from the Nightscout careportal using the same hour:minute time, however, will be entered with 0 seconds.

  • If a second entry is made from the Nightscout careportal with the same hour:minute selection:
    • The Loop app accepts the second entry and treats it as a unique event
    • When the entry is reported to Nightscout from the Loop app as a carbohydrate event, the new event replaces the previous event in the Nightscout record

For more information, see:

  • Carb treatments disappearing in Nightscout
"},{"location":"nightscout/remote-commands/#using-remote-commands","title":"Using Remote Commands","text":"

There are four ways you can trigger your commands remotely; \u00a0Loop Caregiver (link takes you to a new page), Nightscout Careportal, Shortcuts, and IFTTT.

"},{"location":"nightscout/remote-commands/#loop-caregiver","title":"Loop Caregiver","text":"

Click the link above to read more about Loop Caregiver .

"},{"location":"nightscout/remote-commands/#nightscout-careportal","title":"Nightscout Careportal","text":"

To use remote commands in the \u00a0Careportal, you must configure Nightscout site according to the directions here in \u00a0Loopdocs\u00a0 in addition to setting up the Remote Configuration.

Pay particular attention to these entries in the ENABLE line: override careportal Loop. The order of the words in the ENABLE line is not important.

You'll also need to have your site authenticated so that your \u00a0Careportal\u00a0 is active to send remote overrides .

Once authenticated by entering your API_SECRET, there is a plus sign () in the upper right corner of your site. That is your Careportal. Tap the Careportal plus sign () and then scroll down in the event type menu to find Temporary Override. Within there, you will find all your\u00a0Loop\u00a0override presets already loaded for you.

"},{"location":"nightscout/remote-commands/#start-and-end-remote-override","title":"Start and End Remote Override","text":"

The Looper will see a banner notification that a remote command has been sent with details about that command and whether it succeeded (or not).

Canceling an override through Nightscout careportal is as simple as selecting the event type Temporary Override Cancel and submitting.

"},{"location":"nightscout/remote-commands/#command-remote-bolus-or-carb-entry","title":"Command Remote Bolus or Carb Entry","text":"

Open your Nightscout site in a browser or app.

  • Tap the Careportal plus sign () and then scroll down in the event type dropdown menu to find Remote Carb Entry or Remote Bolus Entry
  • Fill out the treatment log until you get to the OTP row
    • When using Safari, the OTP code is automatically offered - might need to tap twice
    • For other authentication apps (Authenticator, 1Password, etc)
      • Tap on the code in the authentication app and copy it to your clipboard
      • In Nightscout, paste that code into the OTP box
    • Click \u201cSubmit Form\u201d

Note that Loop will honor both the current OTP code and the one that just expired.

If the Looper is with you, you can see the notification on their phone. You can see the entry on the\u00a0Loop\u00a0carbohydrate or the insulin displays to see if it went through.

If the Looper is not with you, you should see the result in the Nightscout dashboard within 5 minutes.

"},{"location":"nightscout/remote-commands/#shortcuts","title":"Shortcuts","text":"

If you want to make your life SUPER AMAZING, check out using the iPhone's Shortcuts app. The Shortcuts app is for making little automations (like mini apps) that can integrate parts of your life. In this case, we've written a couple of shortcuts for you that integrate\u00a0Loop\u00a0overrides with Nightscout.

Important Note

Before you click on the download file below...save yourself some trouble.

  1. Download the Shortcuts app if you don't have it yet
  2. Choose to run any shortcut from the Gallery. It can be the laundry timer...I don't care, just pick one shortcut and run it.
  3. THEN, go to download the shortcut of your choice below. \u2139\ufe0f The shortcuts that aren't run through the Gallery option are called \"untrusted\". And you need a slider in your iPhone to trust the \"untrusted\" shortcuts you would be downloading here. But...in a lovely iOS glitch...that slider doesn't appear unless you've run a trusted shortcut first. So, run one now.
  4. Then, this slider will now be visible in the iPhone Settings app under the Shortcuts app menu.
  5. When you will see the message \"This shortcut cannot be opened because your Shortcuts security system settings don't allow untrusted shortcuts\"
  6. Open iPhone Settings and scroll down the list and tap the Shortcuts menu to turn on \"Allow Untrusted Shortcuts\".

Click these links on your iPhone and you'll be prompted to download the premade shortcuts (assuming you open the links in Safari browser on iPhone):

Comprehensive\u00a0Loop\u00a0Shortcut includes Set Remote Override, Cancel Override, Loop Troubleshooting Tips, Quick Text options, Manual BG entry, Bookmarks to websites, etc.

And if you want to save one click to get to these one functions more directly: these shortcuts are simplified to offer only one function:

Set Remote Override only shortcut

Cancel Override\u00a0 only shortcut

A couple notes about these shortcuts:

You need to open those links in the Safari browser on your iPhone. A confirmation will show to initiate the download.

After the download finishes, tap the button marked AA near your Safari address bar and tap Downloads (downloads) to find and open the downloaded Shortcut.

Wait a bit, and the shortcut's inner guts will be there...scroll ALL the way down to the bottom to click the button to save the untrusted shortcut

  1. When you enter your Nightscout URL in \u00a0the URL field\u00a0 of the\u00a0Loop\u00a0shortcut setup, make sure you don't include a \u00a0trailing /, or the API calls to Heroku will error out.
  2. When a remote override is set properly, you'll see an ok message displayed. If there is an error, you'll see an error message. Most errors will be that you have an API_SECRET wrong (make sure there isn't a space at the end of your API_SECRET that you don't see) or you failed to do the steps to setup Nightscout and update your\u00a0Loop\u00a0app as described in steps 1-3 above.
  3. You can absolutely customize these bits and pieces within the shortcut. Change the text messages, and change the links... It is totally up to you.
"},{"location":"nightscout/remote-commands/#ifttt","title":"IFTTT","text":"

If you want to walk uphill both ways in the snow carrying bags of uneven groceries, you can also set overrides remotely by using If This, Then That (IFTTT) integration. By using IFTTT, you can have single button presses on your phone that will set an override, log a cannula change, log a sensor change and much more.

  • Please see
    • Nightscout: Configurations: IFTTT Maker
    • Nightscout: IFTTT
"},{"location":"nightscout/remote-config/","title":"Remote Configuration","text":"

Page Summary

  1. Update the Looper's iPhone Settings
  2. Create a Key for an Apple Push Notifications service (APNs)
  3. Update Nightscout site and add some \"config vars\" lines in Nightscout site settings
  4. Test Remote Overrides
"},{"location":"nightscout/remote-config/#set-up-remote-for-nightscout","title":"Set Up Remote for Nightscout","text":"

You can use the Nightscout site to remotely set and cancel override presets remotely in the Loop app.

With \u00a0Loop 3, you can also send remote commands to add carbs and command a bolus. Remote bolus/carb commands have a minimum requirement of \u00a0Nightscout 14.2.6. If your Looper's Nightscout version does not meet that minimum requirement, remote commands might be accepted, but the time for the commands is always the current time. In other words, Carbs in the Past or Future might be accepted, but would be entered at the current time on the\u00a0Loop\u00a0phone.

After you complete the configuration, read the entire Remote Commands page - pay attention to the warnings and caveats. Test this while your Looper is sitting next to you so you can watch their phone.

Remote Nightscout Interface Caveats

  • Must use a paid \u00a0Apple Developer\u00a0 account to build\u00a0Loop
    • Apple Push Notifications\u00a0 (APN) service is not available with a Free account
  • When you build \u00a0Loop, the required APN information is tied to your Apple Developer account
    • You add your APN information to your Looper's Nightscout site
    • If you support multiple Looper's, you add the same APN variables to each of their Nightscout sites
  • There are many choices for building your own or paying someone to build a Nightscout site
    • The directions for only one of the options is documented on this page
    • Use that as a guide for your site
  • Nightscout Docs: Comparison Table
    • Warning: examine the Loop remote carbs/bolus row: subscription refers to a monthly fee
    • If a green check is missing, it might just be too new for evaluation
"},{"location":"nightscout/remote-config/#paid-providers-and-remote-configuration","title":"Paid Providers and Remote Configuration","text":"

There are several options to pay for a turn-key Nightscout service.

  • In order to enable remote commanding, your Nightscout site must be configured with information associated with the Apple Developer ID used to build the Loop app
    • Most Nightscout options allow you full access to your Nightscout configuration variables so you can add the required information
  • Please check out Nightscout: New User for up-to-date information about your Nightscout options
    • If you use the wizard, you can see more options when you select No to the question about contributing to research and development
    • If you choose T1Pal and want to use remote commands, you must also purchase your Loop app from them for an additional monthly fee - contact T1Pal for details

The rest of this page assumes that you built your Loop app and you have full access to the configuration variables for your Nightscout site.

"},{"location":"nightscout/remote-config/#step-1-update-the-loopers-iphone-settings","title":"Step 1: Update the Looper's iPhone settings","text":"

For remote commands to successfully deploy to a Looper's iPhone when the phone is locked, they must have Background App Refresh enabled.

  • The slider in iPhone -> Settings -> General -> Background App Refresh -> Loop must be enabled

Consequence if Looper's phone is not configured correctly:

  • If Background app refresh is not enabled, the remote overrides might only enact if the Loop app is open and the phone is unlocked

Keep Notifications Turned on for Looper's Phone

Typically, the Looper's phone has Notifications enabled for \u00a0Loop. In fact, if they don't, a red warning bar is prominently displayed.

There may be times when you really need\u00a0Loop\u00a0to be quiet, so you can turn off Notifications. The remote commands still go through but the Looper does not see a notification that this happened.

Best practice is to keep\u00a0Loop\u00a0Notifications enabled.

"},{"location":"nightscout/remote-config/#step-2-apple-push-notifications","title":"Step 2: Apple Push Notifications","text":"

The step is required for the Loop app to give permissions to your Nightscout site to remotely interact with it. To enable this, you need to create a key and grant it access to the \u00a0Apple Push Notification Service (APNS).

Reminder

This only works with the paid Apple Developer ID.

  1. To get started, go to the Keys section under Apple Developer's Certificates, Identifiers & Profiles and login with the Apple ID associated with your developer team that you used to build the Loop app.
  2. If not already open in your browser (compare with the below screenshot),
    • Click on Keys (located in the left-hand column).
    • Either click on the blue Create a new key button OR the plus button () to add a new key.

  3. In the form that appears, do the following:
    • Click the checkbox for enabling Apple Push Notifications service (APNs)
    • Enter a name for the key such as Nightscout (you can name it however you want, just make sure you know what the key is for by the name you choose).
    • Then click the Continue button in the upper right of the screen.

  4. In the screen that follows, click the blue Register button.

  5. In the screen that follows, click the blue Download button. This step will download a file with a name that starts with AuthKey and ends with .p8.

  6. Find your AuthKey downloaded file in your downloads folder. Double-click to open it and you will be presented a message asking how you'd like to open it. The graphic and instructions below are for a Mac. Make sure your editor does not change any characters in your APN key; use a text-only editor like NotePad (PC) or TextEdit (Mac). Click on Choose Application... and then select TextEdit as your application to open it with.

  7. When the file opens, it will look similar to the screenshot below. In a few minutes, after we do a few other steps first, we will need to highlight ALL OF THE CONTENTS of that file and copy it because we will be pasting it in Heroku or whichever Nightscout provider you are using. Yes, allllll of the contents. So, the easiest way is to:

    • Click inside that file
    • Highlight all the text, and then
    • Copy all the text to the clipboard (Cf. screenshot below).
      • On a Mac, press Cmd+A to select all, then press Cmd+C to copy the selection.
      • On a PC, press Ctrl+A to select all, then press Ctrl+C to copy the selection.

    You don't have to do it right now...just keep that window open in the background for now until we need it a little further down. Then we will copy all that text.

"},{"location":"nightscout/remote-config/#step-3-add-apn-to-nightscout","title":"Step 3: Add APN to Nightscout","text":""},{"location":"nightscout/remote-config/#update-nightscout-site","title":"Update Nightscout Site","text":"

You'll need to make sure your Nightscout site version is version 13.0.1 or newer for remote overrides and version 14.2.6 or newer for access to all the remote command features.

What is my Nightscout Version Number?

To find your Nightscout version number:

  • Tap on (\u2630) the hamburger button (3 horizontal lines stacked on each other) at the upper right, near the authentication button.
  • A context menu slides in from below the hamburger.
  • Scroll to the very bottom of this menu.
  • The version is located in the About section after the Settings section, (below the Save button).

This link should be used if you want to Nightscout: Update your Nightscout site.

Note for Google Cloud Users

The Nightscout with Google Cloud instructions include information about updating your site. Scroll down to the line (on that page) that says Update Nightscout.

"},{"location":"nightscout/remote-config/#add-apn-variables-to-nightscout","title":"Add APN Variables to Nightscout","text":"

In order to use remote overrides, you must add a couple of new variables. If you don't know how to update your Nightscout configuration, review Nightscout: Setup Variables and then come back.

The instructions in this section show Heroku images. If you are using a different method, you should be able to \"translate\" the steps.

Go to the Settings tab near the top of the screen on your Heroku app and then click on Reveal Config Vars.

Scroll down the bottom of the Config Vars lines until you find the last blank one. You are going to add three new rows of config vars for remote overrides as shown below:

KEY VALUE LOOP_APNS_KEY Enter the ENTIRE contents of the downloaded .p8 file including the BEGIN and END lines. Here's where you can use the Cmd+A and Cmd+C to highlight and copy all the text in that file so you can paste it into Heroku here for this new variable you are creating. LOOP_APNS_KEY_ID String of characters on the .p8 download file immediately following the underscore (_) and not including the file extension (.p8), or you can get it from your saved key in your developer account as shown next step, too. This is a part of the downloaded filename located after the underscore (_) and before the file extension (.p8). LOOP_DEVELOPER_TEAM_ID Get this value from the Loop app signing or in your \u00a0Apple Developer\u00a0 account's top right corner under your name LOOP_PUSH_SERVER_ENVIRONMENT (optional) Set this to production if you installed\u00a0Loop\u00a0remotely such as with TestFlight, Diawi, AppCenter, or an IPA. If you built directly to your phone in XCode with your phone plugged into to your computer, do not include this variable."},{"location":"nightscout/remote-config/#remote-build-config-var-requirement","title":"Remote Build Config Var Requirement","text":"

That last row of the table above is needed if you are using a remote build option such as LoopDocs: GitHub Build Actions or downloaded an archived file via Loop and Learn: Remote Build with Diawi. If you later return to a direct Xcode build to your phone, you must remove that config var or remote commands will not work.

When executed properly, you should have something that looks like this for the three (or four) new variables that you added:

"},{"location":"nightscout/remote-config/#baddevicetoken","title":"BadDeviceToken","text":"

When the Nightscout config var LOOP_PUSH_SERVER_ENVIRONMENT does not match the Loop app build method; the error message contains the phrase APNs delivery failed: BadDeviceToken.

  • If\u00a0Loop\u00a0was installed remotely (typically from TestFlight following GitHub Browser Build), you must have Nightscout config var LOOP_PUSH_SERVER_ENVIRONMENT set to production
  • If\u00a0Loop\u00a0was built using Mac, you cannot have LOOP_PUSH_SERVER_ENVIRONMENT as one of your Nightscout config vars
"},{"location":"nightscout/remote-config/#do-not-confuse-your-keys","title":"Do Not Confuse Your Keys","text":"

API Key vs APN Key

If you build with the Build with Browser, you may notice \u00a0the \u00a0Application Programming Interface (API)\u00a0 key\u00a0 has the same type of format as \u00a0the \u00a0Apple Push Notification (APN)\u00a0 key. The keys for both purposes are of type p8, but should not be confused.

The Secrets for building with GitHub use the API Key.

The config vars for Nightscout use the APN Key.

  • If you are using remote commands with Nightscout and building with the GitHub Browser build method, you must also add the config var of LOOP_PUSH_SERVER_ENVIRONMENT with a value of production to your Nightscout site or the remote commands will not work.
  • If you are using the Mac build method, you should not have a config var of LOOP_PUSH_SERVER_ENVIRONMENT entered - remove it if it is present.
"},{"location":"nightscout/remote-config/#step-4-test-remote-overrides","title":"Step 4: Test Remote Overrides","text":"

If remote overrides do not function, remote commands for delivering a bolus or adding a carb entry will not work either.

After you finish setting up your Nightscout site:

  1. Use the Looper's phone to set an override
  2. Make sure that override shows up on the Nightscout site
  3. Then using the \u00a0Nightscout Careportal, test that you can turn off that override
"},{"location":"nightscout/remote-config/#things-to-check","title":"Things to Check:","text":"
  • Remote overrides will not start working until after you activate an override in the app at least once
    • Activating an override from the\u00a0Loop\u00a0interface will upload the necessary push notification token to Nightscout which will enable remote commands to work
    • If your Looper gets a new phone - be sure to activate an override from the new phone before trying to use remote commands
  • Notifications must be allowed in\u00a0Loop
  • Give loop access to all health data
  • Enable Background App Refresh
  • Double check your Nightscout credentials
  • Low Power Mode may prevent background notifications from working
  • Some have found that activating the \u201cFocus\u201d and Do-Not-Disturb features on iOS can prevent push notifications from being delivered
    • Turn these off when troubleshooting to eliminate this as a source of problems
  • iOS 15.3.x: Note there are reports of Remote notifications not being received to the Loopers device for iOS version 15.3 and 15.3.1; this is fixed in iOS version 15.4
  • If you distribute the app remotely (i.e. TestFlight, Diawi, AppCenter), you must set a special Nightscout variable, LOOP_PUSH_SERVER_ENVIRONMENT to \u201cproduction\u201d, to enable push notifications
    • See Remote Build Config Var Requirement
"},{"location":"nightscout/remote-errors/","title":"Remote Errors","text":""},{"location":"nightscout/remote-errors/#loop-data-is-not-showing-in-nightscout","title":"Loop data is not showing in Nightscout","text":"
  • This is a\u00a0Loop\u00a0and/or Nightscout issue, not related to remote configuration
    • Review the LoopDocs: Nightscout with\u00a0Loop page
    • Check out links on the LoopDocs: Nightscout Troubleshooting page
  • Make sure Looper's phone is connected to the internet so it can upload to Nightscout
"},{"location":"nightscout/remote-errors/#remote-commands-stopped-working","title":"Remote Commands Stopped Working","text":"

This section is for people who were using remote commands and they suddenly stopped working.

If you are using LoopCaregiver, try the remote command directly from Nightscout to see if they work there. If they are not working there as well, check out your account status first before attempting the fixes on the rest of this page.

  • Your Apple Developer account must be in good standing for the push notifications to work
  • Log in to your Apple Developer account and see if there are agreements you need to accept
"},{"location":"nightscout/remote-errors/#improper-configuration","title":"Improper Configuration","text":""},{"location":"nightscout/remote-errors/#nightscout-config-and-loop-build-method","title":"Nightscout Config and Loop Build Method","text":"

Ensure your Nightscout version is at least version 14.2.6.

Verify that you performed all the Remote Configuration steps for the Nightscout site including sending an override from the\u00a0Loop\u00a0phone to Nightscout.

"},{"location":"nightscout/remote-errors/#baddevicetoken","title":"BadDeviceToken","text":"

When the Nightscout config var LOOP_PUSH_SERVER_ENVIRONMENT does not match the\u00a0Loop\u00a0app build method; the error message contains the phrase APNs delivery failed: BadDeviceToken.

  • If\u00a0Loop\u00a0was installed remotely (typically from TestFlight following GitHub Browser Build), you must have Nightscout config var LOOP_PUSH_SERVER_ENVIRONMENT set to production
  • If\u00a0Loop\u00a0was built using Mac, you cannot have LOOP_PUSH_SERVER_ENVIRONMENT as one of your Nightscout config vars

If you attempt to issue a command from Nightscout Careportal; after you hit submit and then OK, you will see the error message:

Error: APNs delivery failed: BadDeviceToken\n

If you attempt to issue a command using Loop Caregiver ; after you authenticate the command, you will see the error message listed below and shown in the screenshot.

HTTP Error\nStatus Code: 500\nbody: APNs delivery failed: BadDeviceToken\n

"},{"location":"nightscout/remote-errors/#loop-remote_overrides_disabled","title":"Loop REMOTE_OVERRIDES_DISABLED","text":"

You can build Loop with Build-Time Features as part of code customization.

If you added this Build-Time Flag: REMOTE_OVERRIDES_DISABLED

You will not see any errors, but nothing will happen when you issue any kind of remote command.

Solution: Remove REMOTE_OVERRIDES_DISABLED from LoopConfigOverride.xcconfig file and rebuild the\u00a0Loop\u00a0app.

"},{"location":"nightscout/remote-errors/#incorrect-password-otp-error","title":"Incorrect Password (OTP) Error","text":"

The references to Caregiver below is the person sending the commands. There are specific Loop Caregiver app insructions that you modify for your authenticator. You must have the\u00a0Loop\u00a0phone with you to troubleshoot this problem.

  • The Apple clock should be set to automatic on both the Looper's phone and Caregiver\u2019s device.
    • If the clock is incorrect, even slightly, remote commands will fail.
  • Check if One-Time Passwords (OTP) align between Caregiver and\u00a0Loop.
    • In\u00a0Loop: Settings -> Services -> Nightscout
    • In Loop Caregiver : Settings -> Tap on Loopers Name
    • Observe the 6-digit OTP as they change
  • If the OTP don't match, you can reset it:
    • Warning: If there are multiple devices (or people) sending remote commands, this procedure resets the OTP for all
    • Loop: Settings -> Services -> Nightscout -> One-Time Password -> Tap Reload button
      • The QR code is different as soon as you hit Reload
    • Loop Caregiver: Delete the Looper's profile from Loop Caregiver and add the Looper again by scanning their new QR code
    • Authenticators for every device used to send remote commands must be updated
      • Delete the OTP configuration
      • Add the new QR code
"},{"location":"nightscout/remote-errors/#undelivered-or-expired-commands","title":"Undelivered or Expired Commands","text":"

Apple Push Notifications will often not make it to an app, either due to your settings or intentional limitations by Apple. This error can appear in various forms:

  • Push notification banner never shows on Looper\u2019s device.
  • Push notification banner shows but nothing happens in\u00a0Loop (no error or success message afterwards)
  • Error message shows that Password (OTP) is expired

While\u00a0Loop\u00a0does not have control over Push Notification timely delivery, there are things that can be done to mitigate these issues. Note that rebuilding\u00a0Loop, Loop Caregiver or Nightscout is generally not going to help.

Check these settings on the Looper\u2019s device, not the Caregivers. Several of these are related to Apple suppressing notifications.

  • Notifications
    • Settings -> Notifications ->\u00a0Loop
    • Turn on \u201cAllow Notifications\u201d
    • Turn on \u201cTime Sensitive Notifications\u201d
  • Focus Modes
    • For all focus modes (ex: Do Not Disturb, Sleep), make sure\u00a0Loop\u00a0is listed as an app allowing Notifications.
    • To Adjust
      • Settings -> Focus
      • Select the focus mode (ex: Do Not Disturb, Sleep)
      • Under \u201cAllow Notifications, tap \u201cApps\u201d
      • Add \u201c\u00a0Loop\u00a0\u201d to the list.
      • Turn on \u201cTime Sensitive Notifications\u201d.
  • Background App Refresh
    • Settings -> General -> Background App Refresh
    • Select \u201cOn\u201d up top
    • Activate\u00a0Loop\u00a0toggle in list
  • Lower Power Mode
    • Turn off if able

Some other things to try on the Looper\u2019s phone:

  • Reboot phone
    • This sometimes resets Apple\u2019s push notification limit.
  • Try wifi instead of cellular, if able
    • Apple may not deliver notifications on cellular as often as wifi.
  • Charge the phone
    • If the battery is low, iOS may not deliver notifications to save battery life.
  • Limit the number of\u00a0Loop\u00a0commands you send in a short period. Apple may throttle notifications if too many are received. (i.e. no more than 1 or 2 per hour may help).
  • Consider disabling \u201cspammy\u201d notifications from other apps. This is only a theory, but it is possible that other apps can cause the system to throttle all notifications, including\u00a0Loop.
  • Wait 24 hours or so as it often just takes time for the push notification limits to \u201creset\u201d.
  • iOS 15.3.x: Note there are reports of Remote notifications not being received to the Loopers device for iOS version 15.3 and 15.3.1. This is fixed in iOS version 15.4.
"},{"location":"nightscout/remote-errors/#how-to-ask-for-help","title":"How to Ask for Help","text":"

This is helpful information to share when requested by helpers. If you are not using Loop Caregiver, review the response seen on the Nightscout site.

  1. Activate an override from within\u00a0Loop . Does Nightscout show the active override?
  2. Activate an override from Nightscout . Does it change the active override in\u00a0Loop?
  3. Do errors show in Loop Caregiver or Nightscout Careportal when you send a remote command?
    • Share screenshots of error if any
  4. Do errors show in iOS Notifications on the Looper\u2019s device?
    • Check their Notification history in iOS by swiping down
    • Share screenshots of errors if any
  5. What\u00a0Loop\u00a0version are you using? Released (main) or development (dev)? Approximately when did you update last?
    • The minimum version that support remote bolus and carbs is\u00a0Loop\u00a03
  6. What iOS version is being used on the Looper\u2019s device?
    • Note that iOS 15.3.x had notification issues
    • Update to a newer version
  7. How did you build\u00a0Loop?
    • Build with Xcode to device (typical)?
    • Using AppCenter or Diawai? A special environment variable must be set LOOP_PUSH_SERVER_ENVIRONMENT=production

Mention which troubleshooting steps you have completed so we know whether to ask about these again.

"},{"location":"nightscout/remote-errors/#other-errors","title":"Other Errors","text":"

Once you've set up remote commands, you may encounter errors when trying to run them via Nightscout or iOS Shortcuts. Below are the most common and typical solutions.

  1. Error: Loop notification failed: Could not find deviceToken in loopSettings You might see this in either Nightscout or Shortcuts. The error is most commonly caused by\u00a0Loop\u00a0not pointing to the right Nightscout instance or you haven't yet run an override locally (with the\u00a0Loop app) before trying to run one remotely. Solution: Confirm the Loop app is pointing to the right Nightscout site (and there are no extra spaces or a slash (/) at the end, and always run an override for a few seconds in the Loop app before you try to run one remotely.
  2. Error: cannot POST/api/v2/notifications/loop You might see this in iOS Shortcuts. This means Nightscout is not updated correctly and you are running a version of Nightscout that doesn't yet support remote overrides. Solution: Follow the Remote Configuration documentation.
  3. Error: {\u201cstatus\u201d:401,\u201dmessage\u201d:\u201dUnauthorized\u201d,\u201ddescription\u201d:Invalid\\\\/Missing\u201d} You might see this in iOS Shortcuts. This is caused by having an incorrect API_SECRET in the shortcut. Solution: Double check the API_SECRET is correct and that there are no spaces at the end.
  4. Error: APNs delivery failed: InvalidProviderToken You might see this in either Nightscout or Shortcuts. This is caused because your LOOP_APNS_KEY_ID and LOOP_DEVELOPER_TEAM_ID are swapped in Heroku. Solution: Double check what's listed in your Apple Developer Account and compare it to the config variables in Heroku. Your Team_ID is next to your name in the top right corner. The other code is your Key_ID. Get the IDs in the correct location in Heroku to resolve the error.
"},{"location":"nightscout/remote-overview/","title":"Remote Overview","text":""},{"location":"nightscout/remote-overview/#remote-caregivers","title":"Remote Caregivers","text":"

With\u00a0Loop\u00a03, a caregiver can provide remote commands to assist in diabetes care, including modifying overrides, issuing remote bolus commands and adding remote carb entries. With\u00a0Loop\u00a02, only overrides can be turned on or off remotely.

Remote commands to the\u00a0Loop\u00a0phone go through their Nightscout site. For security, any command to deliver a bolus or add a carb entry requires a one-time-password (OTP) to be used with each remote command. These codes are unique to your combined\u00a0Loop\u00a0and Nightscout configuration. An authentication app needs to be installed on the device sending the remote boluses/carbs. The Loop Caregiver app can be used. It handles authentication requirements and offers a\u00a0Loop\u00a0-like user interface.

"},{"location":"nightscout/remote-overview/#remote-commanding-requirements","title":"Remote Commanding Requirements:","text":"
  • Loop\u00a0version 3.2.0 or newer
    • version 3.0 works but is not recommended for other reasons
  • Apple Push Notifications\u00a0 ( APN\u00a0) created with the \u00a0Apple Developer ID\u00a0 that built the\u00a0Loop\u00a0app
  • Nightscout version 14.2.6 or newer
    • Several configuration variables must be added
  • Ability to generate a One-Time-Password (OTP)

What about Older Versions?

Caregivers for those using older versions of Loop can modify Overrides remotely but cannot send remote bolus or carb commands.

If your Nightscout site is an older version, you should limit your remote commands to Overrides, even with \u00a0Loop 3.

Loop Caregiver

There is a new companion app, \u00a0Loop Caregiver that makes remote commands and reviewing the status of your looper much easier.

"},{"location":"nightscout/remote-overview/#how-does-this-work","title":"How does this work?","text":"

Loop\u00a0and Nightscout work using \u00a0Apple Push Notifications\u00a0 (APN).

  • The \u00a0Apple Developer ID\u00a0 used to build the\u00a0Loop\u00a0app must be configured to enable \u00a0Apple Push Notifications
    • If you built Nightscout and\u00a0Loop\u00a0yourself, follow the directions to set up Remote Configuration
  • Most providers who supply Nightscout as a service or Hosted Nightscout will assist you, if needed, in getting your APN information added to your Nightscout variables
    • Nightscout Docs: New User
    • Nightscout Docs: Comparison Table
      • Warning: examine the Loop remote carbs/bolus row: subscription refers to a monthly fee
"},{"location":"nightscout/remote-overview/#warning-nightscout-remote-carbohydrate-entries","title":"Warning: Nightscout Remote Carbohydrate Entries","text":"

Use unique times for remote carbohydrate entries

Instead of adding a second remote carbohydrate entry at an identical time, add one minute to the second entry.

This ensures that Nightscout keeps both entries.

For more information, see:

  • Use Unique Times for Remote Carbohydrate Entries
"},{"location":"nightscout/remote-overview/#next-steps","title":"Next Steps","text":"

There are several steps to follow to set this up. Each page is linked below:

"},{"location":"nightscout/remote-overview/#set-up-remote-for-nightscout","title":"Set Up Remote for Nightscout","text":""},{"location":"nightscout/remote-overview/#using-remote-commands","title":"Using Remote Commands","text":""},{"location":"nightscout/remote-overview/#remote-errors","title":"Remote Errors","text":""},{"location":"nightscout/remote-overview/#loop-caregiver-app","title":"Loop Caregiver App","text":""},{"location":"nightscout/troubleshoot/","title":"Nightscout Troubleshooting","text":""},{"location":"nightscout/troubleshoot/#setup-troubleshooting","title":"Setup Troubleshooting","text":"

If you have just tried to set up your Nightscout site and have problems with seeing all your data, please check out the Nightscout: Troubleshooting page.

"},{"location":"nightscout/troubleshoot/#dexcom-data-not-showing","title":"Dexcom data not showing","text":"

If you use a Dexcom and get your CGM data into Nightscout using Dexcom Share (bridge in Nightscout) and everything is working but the Dexcom data stops showing, please review Nightscout: Dexcom bridge Troubleshooting.

As part of that troubleshooting, you may need to remove the Nightscout service credentials from Loop. You may need to remove Dexcom credentials from all third-party apps that get data from Dexcom Share. Be sure to add them back after the CGM data to Nightscout is restored.

You do not need to use Share or bridge with Nightscout. You can choose to have Loop update your CGM readings to Nightscout directly. There's a check box in the Loop CGM setting screen to select this. You must select that check box every time you update your transmitter for Dexcom G5 or G6.

"},{"location":"nightscout/troubleshoot/#loop-data-not-showing","title":"Loop data not showing","text":"

If your BG data is showing, but Loop data is not (like Loop pill is empty and carbs and boluses are not showing), please delete your Nightscout account in Loop settings area. Enter the information in Loop again. Make sure to use https:// to start the site URL. Make sure there is no trailing slash at the end of the URL. Enter your API_SECRET correctly. Make sure you have loop on the ENABLE line in Heroku settings.

"},{"location":"nightscout/update-user/","title":"Nightscout with Loop","text":""},{"location":"nightscout/update-user/#adding-loop-to-existing-nightscout-site","title":"Adding Loop to Existing Nightscout Site","text":"

Many people may already have an existing Nightscout site setup from before adding Loop to their management strategies. In order to make the most of your Looping setup, you will need to modify your existing Nightscout site a bit specifically for Loop. The process is pretty easy and should not take long.

The graphics on this page are from a Heroku implementation for DIY Nightscout. When you read the Nightscout documents, you'll notice there are a lot more options than just Heroku. When Heroku announced that the \"free\" tier for Heroku would be disabled in November 2022, the #WeAreNotWaiting community developed a lot of options - both free DIY, nominal cost DIY and there were already several companies that provide Nightscout as a service. If your site is not with Heroku, you need to translate how to adjust the configuration variables.

"},{"location":"nightscout/update-user/#variables-for-loopers","title":"Variables for Loopers","text":"

Once you have created a Nightscout site, there are some Nightscout Config Vars specific to Loop.

  • First the Config Vars need to be added to the Nightscout site.

  • For each instance of viewing the Nightscout site (i.e., on broswer or phone app), you can individually select which of those configured items are displayed. This is on a per-view basis. However, Config Vars like the SHOW_PLUGINS line allow you to preconfigure what will be shown by default.

"},{"location":"nightscout/update-user/#editadd-config-vars","title":"Edit/Add Config Vars","text":"

These instructions are for people using Heroku, because that is the most common choice. If your Nightscout site is not on Heroku, this page provides a guide for the Config Vars used by Loop.

Login to your Heroku account, select the Settings tab near the top of the screen on your Heroku app.

Click on Reveal Config Vars. Scroll down the bottom of the Config Vars lines until you find the last blank one. You are going to add several additional lines of config vars for Loop use; the DEVICESTATUS_ADVANCED and ENABLE lines are required, the others just make Nightscout more useful when Looping.

Omnipod Users can skip the Config Vars that begin with PUMP_. Those are useful for Medtronic users.

ENABLE bridge loop pump iob cob basal careportal sage cage bage override dbsize (Note: If you are an existing NS user, you likely already have an ENABLE line in this section of Heroku. Don't add a new one. Simply find the existing ENABLE line, click on the little pencil icon to the right of it, and add the words shown on the ENABLE line above to the existing words already on the enable line. Avoid duplicates. The remainder of the lines are likely going to be brand new additions to your Heroku settings.) DEVICESTATUS_ADVANCED true PUMP_FIELDS battery reservoir clock status PUMP_RETRO_FIELDS battery reservoir clock status SHOW_FORECAST loop SHOW_PLUGINS loop pump cob iob sage cage careportal basal override dbsize PUMP_ENABLE_ALERTS true PUMP_URGENT_BATT_U 30(This is the pump battery percentage that will trigger a red, urgent alert in NS.) PUMP_URGENT_BATT_V 1.25(This is the pump battery voltage that will trigger a red, urgent alert in NS.) PUMP_URGENT_RES 10(This is the reservoir volume that will trigger a red, urgent alert in NS.) PUMP_URGENT_CLOCK 30 LOOP_ENABLE_ALERTS true LOOP_WARN 20(This is the minutes since Loop last successfully looped, the t1d will have a similar notification at this time through the Loop app. This will be a yellow alert in NS.) LOOP_URGENT 60(Same as the alert above, but will be red in color and have a shorter snooze option.) BASAL_RENDER default

Click on Open App in the top right corner of your Heroku site.

"},{"location":"nightscout/update-user/#plugins-selection","title":"Plugins Selection","text":"

Once you are viewing an instance of your Nightscout site (browser or app), you can adjust what this instance of the display will show.

Click on the \"hamburger\" menu - those three horizontal lines in the upper right corner of the main NS display.

Different sets of documentation call the three horizontal lines in the upper right of the Nightscout display different things such as:

  • Settings
  • Hamburger Menu
  • Drawer Menu

The graphic below shows some of the check boxes you can select. Make sure your basal render is selected to either default or icicle (personal preference for how the temp basals show as blue lines in NS site), adjust alarms (on or off), check the boxes that you\u2019d like display as pills in the SHOW PLUGINS section (usually all of them), and then click save. (You are saving your display preferences, not modifying anything in the NS database.)

Note - Nightscout has been updated since this figure was generated.

"},{"location":"nightscout/update-user/#authenticate-site","title":"Authenticate Site","text":"

If the current display of your NS site has been not authenticated, you will not be able to access certain portions of Nightscout such as the careportal, administration tools and remote overrides. There are two ways to authenticate.

  • Use API_SECRET to access all features of Nightscout

  • Use Tokens to generate a URL that opens with predefined role(s)

The use of tokens is documented at this link to the security page in the Nightscout documentation.

  • Please see Nightscout: Tokens

You can authenticate with your API_SECRET using either of these methods:

  • Click on the hamburger menu and scroll all the way to the bottom, click on authenticate and add your API_SECRET

  • Click on the Lock symbol on upper right on main display (requires careportal plugin to be enabled) and add your API_SECRET

An authenticated site, with careportal plugin enabled, will show a + at upper right of the main display instead of a lock symbol. Tapping on the + gives you access to the careportal.

"},{"location":"nightscout/update-user/#nightscout-version-update","title":"Nightscout Version Update","text":"

If you are new to Loop and haven\u2019t updated your Nightscout site for a while, check to see if there's an available update. Visit Nightscout: Update Instructions for directions on updating.

"},{"location":"nightscout/update-user/#more-variables-for-loopers","title":"More Variables for Loopers","text":"

The list of Variables for Loopers above can be expanded if you want your site to automatically open with specific values and alarm settings.

This Loop and Learn: Nightscout Variables page, created for folks using the Google Cloud method to create a Nightscout site, has a convenient, expanded list.

"},{"location":"operation/overview/","title":"Loop 2 Set Up Overview","text":"

This section of LoopDocs will be maintained during the transition to Loop 3. These pages are specific to Loop 2.2.x and some forks based off that older version.

Be aware that older versions and forks will probably not be updated as the Apple environment changes.

With Loop 2.2.x, you must manually step through every Loop setting and fill out the appropriate values. If you miss some, you may get errors in the app. If this happens to you, review every setting carefully.

You need to work through the steps listed in the headings under this page one by one. Please follow along with each page's information to make sure that you don't miss any valuable information about your Loop's settings and function.

You can work through each page completely and click on the link at the bottom of the page to proceed to the next page. Or you can use the back button on your browser to return to this page and click on the link for the page of interest.

"},{"location":"operation/overview/#permissions","title":"Permissions","text":"

Make sure that Loop has permission to send you notifications. For example, you will want to know if Loop has stopped working for more than 20 minutes.

Make sure Loop has permission to access Bluetooth devices. You'll need that for your CGM and to connect a pump to Loop.

"},{"location":"operation/overview/#loop-2-health-permissions","title":"Loop 2 Health Permissions","text":"

Follow the instructions on the Loop 2 Health Permission page. Note that the Carbohydrate read permission should be turned off after enabling all.

"},{"location":"operation/overview/#loop-2-add-pump","title":"Loop 2 Add Pump","text":"

Select and configure your insulin pump. There are separate pages for setting up a Medtronic (MDT) pump or an Omnipod Eros pump (aka \"pods\"). Click on one of the pages to go straight to that page's guide.

Loop 2 Add Medtronic Pump

Loop 2 Add Omnipod Pump

"},{"location":"operation/overview/#loop-2-add-cgm","title":"Loop 2 Add CGM","text":"

Follow direction on the Loop 2 Add CGM page. If you are wondering which CGMs are supported natively by Loop, check Compatible CGM.

"},{"location":"operation/overview/#loop-2-configurations","title":"Loop 2 Configurations","text":"

Configure Loop's settings. Within this section, you will be entering many settings that you are already familiar with such as basal rates, carb ratios, and insulin sensitivity factor (aka correction factor). There are also several new terms that you may be unfamiliar with like insulin model selection, suspend threshold, and override ranges. Make sure to refer to the Loop 2 Configurations while entering values - DO NOT GUESS.

"},{"location":"operation/overview/#loop-2-services-optional","title":"Loop 2 Services (Optional)","text":"

You are not required to use services although many Loopers use Nightscout. If you do not yet have Nightscout configured and want to add it later, just return to the Services page when you are ready. Note that Loop 3 and Loop 2 use the same documentation page for Services. Services can be added at any time.

"},{"location":"operation/overview/#loop-2-displays","title":"Loop 2 Displays","text":"

After you are done entering your settings, you should familiarize yourself with the information displays. The Loop 2 Displays page will help you recognize and begin to understand what all the icons, graphs, and data mean.

It is a good idea to remain in Open Loop while becoming familiar with the app.

"},{"location":"operation/overview/#loop-2-pump-settings-screen","title":"Loop 2 Pump Settings Screen","text":"

The pump settings screens for Loop 3 were updated. The older interface used by Loop 2 is documented at Loop 2 Pump Settings

"},{"location":"operation/overview/#rileylink-screen","title":"RileyLink Screen","text":"

The documentation for Loop 3 and Loop 2 is the same for the RileyLink screen. This screen is only available after configuring a pump that uses a RileyLink Compatible Device.

After a pump that uses a RileyLink is connected to the app, tap on a RileyLink name in the pump settings screen to bring up the displays and commands found on the RileyLink Menu screen.

"},{"location":"operation/algorithm/bolus/","title":"Bolus Recommendations","text":""},{"location":"operation/algorithm/bolus/#loop-manual-bolus","title":"Loop Manual Bolus","text":"

Loop will recommend bolus insulin corrections when the eventual blood glucose is greater than the correction target and the active insulin plus any active 30-minute temporary basal will not be sufficient to cover the predicted excursion above correction target.

These recommendations are not proactively sent to the Loop user through any notification or banner alert; the recommendation is only viewable when the user clicks on the bolus tool. Note that Loop never issues a bolus command automatically while using the default Temp Basal Dosing Strategy; all boluses are initiated by the user unless the Automatic Bolus dosing strategy is enabled. With automatic bolus enabled, each automatic bolus is limited to 40% of the recommended amount or the maximum bolus setting, whichever is smaller.

The bolus dose calculation is identical to the dose equation given in the basal recommendations section, with the exception that:

  • the insulin contribution from the currently running temporary basal set by Loop is removed or subtracted from the recommended bolus amount, and
  • the delta is calculated for the top of the correction range, rather than the average of the correction range.

For recently saved carbohydrates where the projected carbohydrate absorption will outlast the insulin activity duration (e.g., very slow-digesting meals like pizza or pasta), Loop\u2019s algorithm will inherently decrease the initial meal bolus \u2014 to prevent hypoglycemia events that often occur after these meals \u2014 by only recommending enough bolus to prevent minimum predicted glucose from going below the suspend threshold. As described above, the Loop algorithm computes the recommended bolus such that predicted glucose will not dip below the suspend threshold. This may result in future blood glucose levels predicted above correction range, but will prevent a hypoglycemia event shortly after the meal (as it sometimes occurs for people giving a \"pizza bolus\" in traditional pump therapy). Loop will then later make corrections by issuing a command to temporarily Increase Basal Rate or provide an automatic bolus. In effect, this algorithm behavior mimics traditional pump therapy of \u201cextended\u201d or \u201cdual wave\u201d bolusing, but with the benefit of added information about actual carbohydrate absorption effects as time goes by.

Finally, Loop checks that the result of the calculations is below the maximum single bolus the Loop user specified in their settings. If the calculated bolus is less than the maximum single bolus setting, then the recommended bolus will be displayed in Loop\u2019s bolus tool.

Bolusing safety feature

If the current blood glucose, or any predicted blood glucose, falls below the suspend threshold, Loop will not return a recommended bolus. When the minimum blood glucose rises above the suspend threshold, the bolus tool will provide a recommended bolus.

"},{"location":"operation/algorithm/bolus/#algorithm-section-menu","title":"Algorithm Section Menu","text":"
  • Algorithm Overview
    • Bolus Recommendations
    • Blood Glucose Prediction
    • Temp Basal Adjustments
"},{"location":"operation/algorithm/overview/","title":"Algorithm Overview","text":""},{"location":"operation/algorithm/overview/#loop-algorithm","title":"Loop Algorithm","text":"

Loop\u2019s algorithm for adjusting insulin delivery is oriented around making a blood glucose prediction. Every five minutes, triggered by new blood glucose data, it generates a new prediction. Both bolus recommendations and temporary basal rate adjustments are set based on this prediction.

"},{"location":"operation/algorithm/overview/#algorithm-terminology","title":"Algorithm Terminology","text":"

This graph and legend illustrates terms commonly used in discussing Loop's algorithm, and shows them in the context of historical and forecasted blood glucose in style similar to the status screen of Loop.

Insulin activity duration The insulin activity duration is the duration of the insulin activity curve, and describes the point at which the delivered insulin dose no longer affects blood glucose. The insulin activity duration is 6 hours for Loop's rapid-acting and ultra-rapid insulin models. Correction range The correction range is the blood glucose range Loop uses to determine corrective actions (e.g., between 90 and 120 mg/dL in the figure). NOTE: Loop\u2019s correction range is a user setting and should not be confused with the target range, typically 70-180 mg/dL, used for the purpose of calculating the percent time in range. Correction minimum The lower or minimum value of the user\u2019s correction range, which is 90 mg/dL in the figure. Correction maximum The upper or maximum value of the user\u2019s correction range, which is 120 mg/dL in the figure. Correction target The correction target is the average value of the correction range. In the overview figure, this is 105 mg/dL given that the correction minimum is 90 mg/dL and the correction maximum is 120 mg/dL. Predicted blood glucose Loop makes a prediction of blood glucose values out for a length of time equal to your insulin action duration. The predicted blood glucose is the basis for how Loop makes its insulin delivery recommendations and actions. Eventual blood glucose The last value of the predicted glucose curve, in other words the very last blood glucose predicted at the end of your insulin action duration. In the figure above, this is 85 mg/dL. Minimum predicted blood glucose The lowest blood glucose value at any point in time within the prediction. In the figure above, this is 77 mg/dL. Delta The delta is the difference between the eventual blood glucose and the correction target. In the overview figure, the eventual blood glucose is 85 mg/dL and the correction target is 105 mg/dL, which means that the delta is -20 mg/dL. Suspend Threshold The suspend threshold is a safety feature of the Loop algorithm. If any predicted blood glucose is below this threshold, the Loop algorithm will issue a temporary basal rate of 0 CGM data Blood glucose readings made by a continuous glucose monitor. Insulin sensitivity factor A configuration value that provides an estimate of how much blood glucose will drop given a unit of insulin. Active insulin Active insulin, often referred to as Insulin-on-Board (IOB), is the remaining amount of insulin activity from boluses and temporary basal rates relative to a user\u2019s scheduled basal rates. More specifically, it is the total amount of insulin activity due to all bolus and basal insulin delivered within the last N hours, where N is determined by the insulin activity duration. The amount of \u201cactive\u201d insulin depends upon the insulin activity curve, and also accounts for the insulin withheld via basal suspensions. As such, it is possible that the active insulin can be negative. Negative active insulin will result in an increase in predicted blood glucose. The active insulin displayed in Loop's main display does not reflect the currently enacted temporary basal rate, as that basal rate may be canceled or modified before completion over the next 30 minutes. In others words, Loop doesn't count chickens before the eggs hatch...insulin delivery must be confirmed before being added to the active insulin reporting."},{"location":"operation/algorithm/overview/#algorithm-section-menu","title":"Algorithm Section Menu","text":"
  • Algorithm Overview
    • Bolus Recommendations
    • Blood Glucose Prediction
    • Temp Basal Adjustments
"},{"location":"operation/algorithm/prediction/","title":"Glucose Prediction","text":""},{"location":"operation/algorithm/prediction/#blood-glucose-prediction","title":"Blood Glucose Prediction","text":"

Loop uses an algorithm to maintain blood glucose in a correction range by predicting the contributions from four individual effects (insulin, carbohydrates, retrospective correction, and blood glucose momentum) at any time t to recommend temporary basal rate corrections and boluses.

\\[ BG[t] = Insulin[t] + Carb[t] + RetrospectiveCorrection[t] + Momentum[t] \\]

Note that the Momemtum term does not just add to the other effects as implied in the simple formular above; it is blended with the other terms as described in more detail in the Momemtum section below).

You can see the individual contributions of these effects by tapping on the predicted blood glucose chart on Loop's status screen. Loop updates this blood glucose prediction every five minutes when a new CGM value has been received and the pump's status has been updated.

Just a note, this whole section is fairly technical. While perhaps not the most interesting topic for many readers, if you are seeking the detailed view of the Loop algorithm this discussion is quite useful. If you want a more surface understanding, the overview and temporary basal recommendations sections alone are probably sufficient.

"},{"location":"operation/algorithm/prediction/#overview","title":"Overview","text":"

Before we delve into each of the four individual effects, a general overview figure may be a helpful start. There are four effects summed together to produce Loop's final predicted blood glucose curve. Each individual effect, along with their combined effect, is illustrated in the figure below. Insulin, from boluses and temporary basals, will have a decreasing effect on the prediction. Carbohydrates will have an increasing effect on the prediction. Blood glucose momentum effect can have a positive or negative effect, depending on how blood glucose is trending in the most recent CGM values. As shown in the example below, blood glucose is trending slightly upwards at the time of the prediction. Therefore, the blood glucose momentum effect\u2019s contribution is pulling up the overall prediction from the other three effects for a short time. Retrospective correction is lowering the prediction, indicating that the recent rise in blood glucose was not as large as had been predicted by Loop in the recent past.

The sections below provide detailed information on each of the four contributions.

"},{"location":"operation/algorithm/prediction/#insulin-effect","title":"Insulin Effect","text":"

Most traditional pump users and caregivers are already familiar with the concept of an insulin activity curve, where the insulin\u2019s effect is time-dependent. Insulin takes a little while to affect blood glucose. The insulin effect typically peaks around one hour after giving insulin and then gradually decays.

Loop 2.x provides users with two different classes of insulin models (i.e., an exponential model and the Walsh model). All of the exponential models have an insulin activity duration of 6 hours, whereas the insulin activity duration is customizable for the Walsh model. The rapid-acting and Fiasp insulin activity curves are modeled as exponential curves that match the shape of the insulin activity curves from insulin labeling, and as observed in both adults and children.

Loop 3 drops the Walsh model and, by default, does not include the concept of child versus adult for \"rapid\" acting insulin, i.e., Humalog, Novalog and Apidra. Loop 3 adds the concept of non-pump insulin to account for injections or inhaled insulin. The Afrezza model is added as a non-pump insulin. The Insulin Type is selected in the Pump Settings screen. All insulin types are modeled by selecting parameters in the exponential model. See also Exponential Insulin Curve on the Code Customization page.

"},{"location":"operation/algorithm/prediction/#insulin-effect-remaining","title":"Insulin Effect Remaining","text":"

The amount of insulin effect remaining, or percent of remaining active insulin after an insulin bolus is delivered, is modeled mathematically in Loop with an exponential decay curve.

If a user\u2019s insulin sensitivity factor (ISF) is 50 mg/dL per 1 unit of insulin and the user gives 2 units of insulin, then the user\u2019s blood glucose would be expected to drop 100 mg/dL within the 6 hours following the insulin delivery. This insulin effect can be visualized in several different ways: the expected active insulin, expected drop in blood glucose every 5 minutes after delivery, and the expected cumulative drop in blood glucose. The figures below use the Rapid Acting - Adult insulin model in Loop.

"},{"location":"operation/algorithm/prediction/#active-insulin","title":"Active Insulin","text":"

This figure shows that 2 units of insulin are given initially, and the corresponding active insulin (i.e., insulin on board IOB) decays according to the curve below.

The active insulin at any time is the product of original insulin delivered and the percent of insulin activity remaining. Knowing the expected active insulin over the next 6 hours, and the insulin sensitivity factor (50 mg/dL, in this case), Loop can calculate the expected drop in blood glucose from that dose of insulin as shown in the figure below.

NOTE: ISF is also a function of time, which means if the user\u2019s scheduled ISF changes during the insulin activity time, it will change the expected drop in blood glucose due to the insulin effect.

"},{"location":"operation/algorithm/prediction/#expected-change-in-blood-glucose","title":"Expected Change in Blood Glucose","text":"

Lastly, taking the first derivative (i.e., the rate of change) of the cumulative drop in the blood glucose curve yields the expected change in blood glucose over the insulin activity duration. For each dose of insulin given, Loop calculates the expected discrete drop in blood glucose at each 5-minute period for the insulin activity duration, as shown below.

"},{"location":"operation/algorithm/prediction/#insulin-effect-on-blood-glucose","title":"Insulin Effect on Blood Glucose","text":"

For this example, assuming a user\u2019s blood glucose was 205 mg/dL at the time of insulin delivery, Loop would predict a drop in blood glucose due to the two units delivered at 12 pm as shown in the figure below.

"},{"location":"operation/algorithm/prediction/#scheduled-basal-rates","title":"Scheduled Basal Rates","text":"

In traditional basal/bolus pump therapy, basal rates are set to accommodate the user's endogenous glucose production (EGP) that causes blood glucose to rise. If a user's basal settings were exactly right in traditional pump therapy, the user would have perfectly flat blood glucose all day, all other factors being equal.

In reality, people with type 1 diabetes, and their caregivers, know that basal settings are never exactly right. Every day is a little different, and a myriad of factors that affect blood glucose (e.g., including stress, hormones, sleep, etc.) may affect insulin needs. Some people have different basal profiles to accommodate these variations. Some people regularly tune and adjust their basal rates, and/or do so at their endocrinology clinic visits.

Since the Loop algorithm assumes that the user-set basal rates are correct, it calculates the effect of insulin relative to scheduled basal rates. If basal rates are not entirely correct, Loop can compensate a bit through the retrospective correction and blood glucose momentum effects, discussed later in this page.

The insulin delivery chart below displays a bar-graph history of the temporary basal rates enacted by Loop. The display is relative to the scheduled basal rates entered in the Loop settings. A rate displayed in this chart as +0 would indicate that no temporary basal rate was set and that the basal rate being delivered was the scheduled basal rate. Positive values indicate a temporary basal rate was set above the scheduled basal rate (i.e., more insulin delivered), and negative values indicate that a temporary basal rate was set below the scheduled basal rate (i.e., less insulin delivered).

For example, if the user\u2019s scheduled basal rate is 1 U/hr, and Loop gives a temporary basal rate of 3 U/hr, then it will calculate the expected drop in blood glucose due to +2 U/hr of insulin.

Similarly if Loop sets a temporary basal rate of 0 U/hr for 1 hour, then the insulin effect will also be relative to the current scheduled basal rate of 1 U/hr, and Loop would predict the user\u2019s blood glucose to increase by the amount of change from -1 U/hr of insulin. If the user\u2019s ISF is 50 mg/dL, then Loop would predict blood glucose to rise 50 mg/dL over the insulin activity duration (6 hours).

Here is a real-world example where Loop is setting many temporary basal rates over the course of the day. The light orange bars are the temporary basal rates delivered and the solid orange line is the active insulin at any given time during the day.

"},{"location":"operation/algorithm/prediction/#total-insulin-effect-combining-boluses-and-temporary-basal-rates","title":"Total Insulin Effect (combining boluses and temporary basal rates)","text":"

Loop will combine or stack the active insulin of all the discrete (individual) boluses and temporary basal rates over the past insulin activity duration (6 hours), to predict the active insulin for the next 6 hours. As demonstrated above, using the predicted active insulin Loop can predict the blood glucose drop over the next 6 hours.

Lastly, the combined effect of bolus and basal insulin are visually represented for the user by Loop\u2019s insulin charts:

The insulin effect can be expressed mathematically:

\\[ \\Delta BG_{I}[t] = ISF[t] \\times IA[t] \\]

where BG is the expected change in blood glucose with the units (mg/dL/5min), ISF is the insulin sensitivity factor (mg/dL/U) at time t, and IA is the insulin activity (U/5min) at time t. Insulin activity can also be thought of as a velocity or rate of change in blood glucose due to insulin. The insulin activity accounts for the EGP and any active insulin from basals and boluses.

"},{"location":"operation/algorithm/prediction/#carbohydrate-effect","title":"Carbohydrate Effect","text":"

Carbohydrates will raise blood glucose, but the speed and degree to which they impact blood glucose are dependent on the type of carbohydrates. High glycemic index (GI) carbohydrates will raise blood glucose quickly over a shorter time, whereas low GI foods will raise blood glucose more slowly over a longer period. Foods like candy, juice, and fruits tend to be high GI foods, while pizza, burritos, and quesadillas are usually lower GI foods. Digestion issues like gastroparesis may also contribute to variations in carbohydrate absorption.

Because carbohydrate absorption can be quite variable, Loop has a model that dynamically adjusts the expected remaining time of carbohydrate absorption. To start with, Loop allows the user to input a rough guess of how long they think the food or drink will take to absorb. The user\u2019s guess is used as a middle of the road estimate, and Loop\u2019s algorithm will shorten or lengthen it based on observed blood glucose change.

For all carbohydrate entries, Loop assumes carbohydrates will not start absorbing for 10 minutes, so there is a 10-minute period of no absorption that is modeled prior to the absorption modeled in the next sections.

"},{"location":"operation/algorithm/prediction/#linear-carbohydrate-absorption","title":"Linear Carbohydrate Absorption","text":"

Loop takes a conservative view of how fast the remaining carbohydrates will absorb. Because it is safer to under-deliver insulin for long-duration meals, Loop starts out at a minimum rate of absorption based on extending the entered carbohydrate duration by 50%. Said another way, the minimum carbohydrate absorption rate is the total number of grams of carbohydrates over 150% of the entered duration.

Using this initial minimum absorption rate, the remaining carbohydrates are modeled to absorb linearly. For example, if the user enters a 72g carbohydrate meal, and selects an estimated absorption time of 4 hours, then Loop will forecast a 12g/hr absorption rate for the next 6 hours. This rate can be termed the minimum absorption rate, which can be represented mathematically as:

\\[ MAR[t] = \\frac{CA[t]}{1.5 \\times d} \\]

where MAR is the minimum absorption rate (g/hr), CA is the number of carbohydrates (g) and d is the expected duration (hr) it will take the carbohydrates to absorb.

"},{"location":"operation/algorithm/prediction/#dynamic-carbohydrate-absorption","title":"Dynamic Carbohydrate Absorption","text":"

The linear model above is modulated by an additional calculation that uses recently observed blood glucose data to estimate how fast carbohydrates have been absorbing. The expected change in blood glucose due to insulin effects alone is compared to the actual observed changes in blood glucose. This difference is termed the insulin counteraction effect (ICE):

\\[ ICE[t] = OA[t] + IA[t] \\]

where, ICE (mg/dL/5 min) is the insulin counteraction effect, OA is the observed activity (mg/dL/5min) or observed change in blood glucose at time t, and IA is the insulin activity (mg/dL/5min).

Insulin counteraction effects are caused by more than just carbohydrates, and can include exercise, sensitivity changes, or incorrectly configured insulin delivery settings (e.g., basal rate, ISF, etc.). However, since the effect of carbohydrates is often dominant (after insulin), Loop can still make useful ongoing adjustments to its carbohydrate model by assuming that the increase in blood glucose is mainly carbohydrate absorption in the period following recorded meal entries.

The insulin counteraction effect is converted into an estimated carbohydrate absorption amount by using the current carbohydrate-to-insulin ratio and the insulin sensitivity factor at the time of the recorded meal entry.

\\[ AC[t] = ICE[t] \\times \\frac{CIR[t]}{ISF[t]} \\]

where AC is the number of carbohydrates absorbed (g/5min), ICE is the insulin counteraction effect, CIR is the carbohydrate-to-insulin ratio (g/U), and ISF is the insulin sensitivity factor (mg/dL/U) at time t.

If multiple meal entries are active (i.e., still absorbing), the estimated absorption is split between each carbohydrate entry in proportion to each carbohydrate entry\u2019s minimum absorption rate. For example, if 72g carbohydrates with an expected absorption time of 4 hours was consumed at 12 pm, and another 72g of carbohydrates with an expected absorption time of 2 hours was consumed at 3 pm, then the minimum absorption rate (see MAR equation above) would be 12 g/hr and 6 g/hr respectively, or 1 g/5min and 0.5 g/5min.

\\[ MAR[t = 12pm] = \\frac{ 72g }{ 1.5 \\times 4hr } = 12 \\frac{ g }{ hr } = 1 \\frac{ g }{ 5min } \\] \\[ MAR[t = 3pm] = \\frac{ 72g }{ 1.5 \\times 2hr } = 24 \\frac{ g }{ hr } = 2 \\frac{ g }{ 5min } \\]

Examining just the simple linear carbohydrate effect of these two meals:

If we further expand this example, by assuming the following at 4pm:

  • that there are still carbohydrates left to be absorbed from both meals,
  • that the estimated insulin counteraction effect (ICE) is \\(+15 \\frac{mg/dL}{5min}\\), and
  • the user\u2019s CIR is \\(10 \\frac{g}{U}\\) and the ISF is \\(50 \\frac{mg/dL}{U}\\),

then the estimated amount of carbohydrates absorbed at 4pm would be 3g:

\\[ AC[t = 4pm] = 15 \\frac{mg/dL}{5min} \\times \\frac{10 \\frac{g}{U}}{50 \\frac{mg/dL}{U}} = 3 \\frac{g}{5min} \\]

Those 3g of carbohydrates would then be split amongst the meals proportional to their minimum absorption rates:

\\[ \\text{Proportion to Meal1} = \\frac{MAR_{meal1}}{MAR_{meal1} + MAR_{meal2}} = \\frac{12}{12+24}=\\frac{1}{3} = 33.3\\% \\] \\[ \\text{Proportion to Meal2} = \\frac{MAR_{meal2}}{MAR_{meal1} + MAR_{meal2}} = \\frac{24}{12+24}=\\frac{2}{3} = 66.6\\% \\]

resulting in 1g of absorption being attributed to Meal 1 and 2g attributed to Meal 2.

"},{"location":"operation/algorithm/prediction/#minimum-carbohydrate-absorption-rate","title":"Minimum Carbohydrate Absorption Rate","text":"

If the estimated carbohydrate absorption of a meal entry is less than what would have been absorbed using the minimum absorption rate, then the minimum absorption rate is used instead. This is to ensure that meal entries expire in a reasonable amount of time.

"},{"location":"operation/algorithm/prediction/#modeling-remaining-active-carbohydrates","title":"Modeling Remaining Active Carbohydrates","text":"

After the estimated absorbed carbohydrates have been subtracted from each meal entry, the remaining carbohydrates (for each entry) are then forecasted to decay or absorb using the minimum absorption rate. Loop uses this forecast to estimate the effect (active carbohydrates, or carbohydrate activity) of the remaining carbohydrates. The carbohydrate effect can be expressed mathematically using the terms described above:

\\[ \\Delta BG_{C}[t] = MAR[t] \\times \\frac{ISF[t]}{CIR[t]} \\]"},{"location":"operation/algorithm/prediction/#retrospective-correction-effect","title":"Retrospective Correction Effect","text":"

The retrospective correction effect allows the Loop algorithm to account for effects that are not modeled with the insulin and carbohydrate effects, by comparing historical predictions to the actual blood glucose.

In addition to the modeled effects of insulin and carbohydrates, there are many other factors that affect blood glucose (e.g., exercise, stress, hormones, etc.). Many of these effects are active for a period of time. By observing its own forecast error, Loop can estimate the magnitude of these effects and, by assuming that they will continue for some short period of time, incorporate them into the forecast to improve forecast accuracy.

To do this, Loop calculates a retrospective forecast with a start time of 30 minutes in the past, ending at the current time. Loop compares the retrospective forecast to the actual observed change in blood glucose, and the difference is used to determine a blood glucose velocity or rate of difference:

\\[ BG_{vel}=\\frac{1}{6} \\times \\left(BG[0] - RF[0]\\right) \\]

where BGvel is a velocity term (mg/dL per 5min) that represents the average blood glucose difference between the retrospective forecast (RF) and the actual blood glucose (BG) over the last 30 minutes. This term is applied to the current forecast from the insulin and carb effects with a linear decay over the next hour. For example, the first forecast point (t=5) is 100% of this velocity, the forecast point one-half hour from now is adjusted by approximately 50% of the velocity, and points from one hour or more in the future are not affected by this term.

The retrospective correction effect can be expressed mathematically:

\\[ \\Delta BG_{RC}[t] = BG_{vel} \\times \\left(1-\\frac{t-5}{55}\\right) \\]

where BG is the predicted change in blood glucose with the units (mg/dL/5min) at time t over the time range of 5 to 60 minutes, and the other term gives the percentage of BGvel that is applied to this effect.

The retrospective correction effect can be illustrated with an example: if the BGvel over the past 30 minutes was -10 mg/dL per 5min, then the retrospective correction effect over the next 60 minutes would be as follows:

Minutes relative to now (t=0) Percent of \\(BG_{vel}\\) Applied to RC Effect \\(\\Delta BG_{RC}[t]\\) 5 100% -10 10 91% -9.1 15 82% -8.2 20 73% -7.3 25 64% -6.4 30 55% -5.5 35 45% -4.5 40 36% -3.6 45 27% -2.7 50 18% -1.8 55 9% -0.9 60 0% 0

The example below that shows the retrospective correction effect when the BGvel over the past 30 minutes was -3 mg/dL/5min.

"},{"location":"operation/algorithm/prediction/#blood-glucose-momentum-effect","title":"Blood Glucose Momentum Effect","text":"

The blood glucose momentum effect incorporates a prediction component based on the assumption that recent blood glucose trends tend to persist for a short period of time. In other words, the best predictor of the future is the recent past.

The blood glucose momentum portion of the algorithm gives weight or importance to recent blood glucose to improve the near-future forecast. Loop calculates the slope of the last 3 continuous CGM readings (i.e., the last 15 minutes) using linear regression. Using multiple points helps filter out noise in the CGM data while still responding fast to changing situations. That momentum slope (Mslope) is the approximate or average rate of change over the last 15 minutes, though it is normalized to 5 minutes so that the units are (mg/dL/5min).

The momentum slope is then blended into the next 20 minutes of predicted blood glucose from the other effects (i.e., insulin, carbohydrates, and retrospective correction effects). This, in essence, makes the next 20 minutes of blood glucose prediction more sensitive to recent blood glucose trends. The blending of the recent trend slope into the next 20 minutes is weighted so that the first prediction point (5 minutes into the future) is highly influenced by the slope, and the influence of the slope gradually decays over the 20 minute time period. The momentum effect can be expressed mathematically as:

\\[ \\Delta BG_{M}[t] = M_{slope} \\times \\left( 1 - \\frac{t-5}{15} \\right) \\]

NOTE: The term \\(\\left(\\frac{t-5}{15}\\right)\\) is also applied to the combined insulin, carbohydrates, and retrospective correction effects to get the delta blood glucose prediction.

The momentum effect can be illustrated with an example: if the last 3 blood glucose readings were 100, 103, and 106 mg/dL, then the slope would be 3 mg/dL per 5 minutes (0.6 mg/dL per minute). The amount of that recent trend or slope applied to the next 20 minutes of predictions (i.e., the next 4 predictions from the other effects) is roughly 100% (3 mg/dL per 5 min) at 5 minutes, 66% (2 mg/dL per 5 min) at 10 minutes, 33% (1 mg/dL per 5 min) at 15 minutes, and 0% (0 mg/dL per 5 min) at 20 minutes.

Also, if the combined effect from the insulin, carbohydrates, and retrospective correction is assumed to be a constant 6 mg/dL/5min over the next 20 minutes, then the expected overall effect and the predicted blood glucose can be calculated as follows.

Minutes relative to now (t=0) Percent of Slope Applied to Momentum Effect Momentum Effect (3mg/dL/5min) Percent of Other Effects Applied Overall Effect Other Effects (Insulin, Carbohydrate, and Retrospective Correction) Overall Effect (mg/dL/5min) Predicted BG (mg/dL) 5 100% 3 0 6 3 109 10 66.6% 2 33.3%< 6 4 113 15 33.3% 1 66.6% 6 5 118 20 0% 0 100% 6 6 124

This example is illustrated in the figure below.

It is also worth noting that Loop will not calculate blood glucose momentum in instances where CGM data is not continuous (i.e., must have at least three continuous CGM readings to draw the best-fit straight line trend). It also will not calculate blood glucose momentum when the last three CGM readings contain any calibration points, as those may not be representative of true blood glucose momentum trends.

"},{"location":"operation/algorithm/prediction/#predicting-glucose","title":"Predicting Glucose","text":"

As described in the momentum effect section, the momentum effect is blended with the insulin, carbohydrate, and retrospective correction effects to predict the change in blood glucose:

\\[ \\Delta BG[t] = \\Delta BG_{M}[t] + \\left(\\Delta BG_{I}[t] + \\Delta BG_{C}[t]+ \\Delta BG_{RC}[t] \\right) \\times min\\left(\\frac{t-5}{15}, 1\\right) \\]

Lastly, the forecast or predicted blood glucose BG at time t is the current blood glucose BG plus the sum of all blood glucose effects BG over the time interval [t5, t]:

\\[ \\widehat{BG}[t] = BG[t_{o}] + \\sum_{i=5}^{t} \\Delta BG[t_{o+i}] \\]

Each individual effect along with the combined effects are illustrated in the figure below. As shown, blood glucose is trending slightly upwards at the time of the prediction. Therefore, the blood glucose momentum effect\u2019s contribution is pulling up the overall prediction from the other three effects for a short time. Retrospective correction is lowering the current prediction, indicating that the recent rise in blood glucose was not as great as had been predicted in the recent past.

"},{"location":"operation/algorithm/prediction/#algorithm-section-menu","title":"Algorithm Section Menu","text":"
  • Algorithm Overview
    • Bolus Recommendations
    • Blood Glucose Prediction
    • Temp Basal Adjustments
"},{"location":"operation/algorithm/temp-basal/","title":"Automated Adjustments","text":""},{"location":"operation/algorithm/temp-basal/#calculated-dose","title":"Calculated Dose","text":"

The Loop algorithm takes one of four actions depending upon the eventual blood glucose, predicted glucose, target range and glucose safety threshold when Closed Loop operation is enabled.

The recommended insulin dose (positive or negative) is calculated first, then the Temp Basal or Automatic Bolus to be enacted is modified based on the recommended dose, dosing strategy, maximum Temp Basal and maximum Bolus settings. The automated dosing (increase or decrease) is updated with every CGM value - typically every 5 minutes.

Dosing Strategy: Temp Basal Only

All temporary basal rate commands are issued for 30 minutes, however they may be updated (re-issued) every 5 minutes. Said another way, Loop may enact a new temporary basal rate every 5 minutes. But, if communication with the pump is lost, the last issued temporary basal rate will last for at most 30 minutes before the pump reverts to the user\u2019s scheduled basal rates.

Dosing Strategy: Automatic Bolus

If the Looper has selected Automatic Bolus Dosing Strategy and an increase in insulin dose is recommended, then the Four Actions discussion below applies to the automatic bolus decision.

"},{"location":"operation/algorithm/temp-basal/#no-automatic-dosing","title":"No Automatic Dosing","text":"

If glucose is entirely below the correction range but above glucose safety level, no automatic increase in insulin delivery will be enacted. The Looper can tap on the manual bolus tool and get a recommendation, but no automatic bolus or high temp basal will be issued automatically until the glucose level is higher than the minimum value of the correction range.

The Pre-Meal button or a named override can be configured with a correction range lower than the scheduled correction to assist in getting insulin delivered automatically after meals.

"},{"location":"operation/algorithm/temp-basal/#four-possible-actions","title":"Four Possible Actions","text":"

Loop implements one of four possible temporary basal actions: decrease, increase, suspend, or resume a scheduled basal rate.

Automatic Bolus

If you are using an Automatic-Bolus Dosing Strategy in closed Loop mode and Loop predicts you need an increase in insulin; this increase is provided as a percentage of the recommended bolus instead of an increased temporary basal. The default percentage is 40%.

"},{"location":"operation/algorithm/temp-basal/#decrease-basal-rate","title":"Decrease Basal Rate","text":"

If the eventual blood glucose is less than the correction range and all of the predicted glucose values are above the suspend threshold, then Loop will issue a temporary basal rate that is lower than the current scheduled basal rate to bring the eventual blood glucose up to the correction target.

"},{"location":"operation/algorithm/temp-basal/#increase-basal-rate","title":"Increase Basal Rate","text":"

If the eventual blood glucose is greater than the correction range and all of the predicted glucose values are both above the suspend threshold and equal to or above the correction range, then Loop will issue a temporary basal rate that is higher than the current basal rate to bring the eventual blood glucose down to the correction target.

"},{"location":"operation/algorithm/temp-basal/#suspend-basal-rate","title":"Suspend Basal Rate","text":"

If the minimum predicted blood glucose goes below the suspend threshold, then Loop will issue a temporary basal rate of zero units per hour, regardless of the eventual blood glucose.

"},{"location":"operation/algorithm/temp-basal/#resume-basal-rate","title":"Resume Basal Rate","text":"

There are three situations where the Loop algorithm will resume the current scheduled basal rate.

If the eventual blood glucose is within the correction range, and all of the predicted glucose values are above the suspend threshold, then Loop will resume the current scheduled basal rate.

If the eventual blood glucose is above the correction range, and the predicted glucose values have a temporary excursion below the correction range but still above the suspend threshold, then Loop will resume the current scheduled basal rate.

If the Loop algorithm does not have ALL of the data it needs to make a prediction, it will let the remaining temporary basal rate run its duration (maximum of 30 minutes), and then the basal rate will default back to the current scheduled basal rate, thus returning to the same therapy pattern that they would receive using a traditional insulin pump.

"},{"location":"operation/algorithm/temp-basal/#determining-the-temporary-basal-rate","title":"Determining the Temporary Basal Rate","text":"

To determine the corrective temporary basal rate to implement, Loop calculates a \u201cdose\u201d in the same way doses are calculated in both open-loop and traditional insulin pump therapy. It's also the same math many people on multiple-daily injection therapy use. The benefit of Loop (and all other close-loop algorithms) is that it does this math every 5 minutes, and is far less prone to error than humans doing the math. Loop also does its math based on predicting into the future, which traditional pumps and humans, do not always have the time or inclination to do.

The amount of insulin needed, or dose, is calculated using the desired reduction in blood glucose and the user\u2019s ISF. For the Loop algorithm, the desired reduction in blood glucose is the delta between the eventual blood glucose and the correction target:

\\[ \\mathit{dose} = \\frac{\\mathit{BG_{eventual}} - \\mathit{BG_{target}}}{\\mathit{ISF}} \\]

Loop Dose Calculation

A major difference between traditional pump therapy and how the Loop calculates dose is that in pump therapy the current blood glucose is used to estimate the dose, whereas in the Loop algorithm the eventual and minimum blood glucose predictions are also used in determining dosing decisions.

Loop then converts the dose into a basal rate using the Loop\u2019s temporary basal rate duration of 30 minutes:

\\[ \\mathit{BR_correction} = \\frac{\\mathit{dose}}{30 \\mathrm{min}} = \\frac{\\mathit{dose}}{\\frac{1}{2} \\mathrm{hr}} = \\frac{2 \\times \\mathit{dose}}{\\mathrm{hr}} \\]

where \\(\\mathit{BR_correction}\\) is the basal rate ( \\(\\mathrm{\\frac{U}{hr}}\\) ), which is the amount of insulin needed over the next 30 minutes to bring the eventual blood glucose to the correction target. The basal rate, however, is the amount of basal rate needed beyond the user\u2019s scheduled basal rate. As such, the required basal rate can be determined by:

\\[ \\mathit{BR_required} = \\mathit{BR_scheduled} + \\mathit{BR_correction} \\]

Finally, Loop compares the \\(BR_{required}\\) with the user-specified maximum temporary basal rate \\(BR_{max}\\) setting to determine the temporary basal to issue:

\\[ \\mathit{BR_temp} = \\max(\\min( \\mathit{BR_required}, \\mathit{BR_max} ), 0) \\]

After running the temporary basal calculation described above, Loop checks whether there is already an appropriate basal running with at least 10 minutes remaining. If so, Loop will not reissue the temporary basal. However, if the recommended temporary basal differs from the currently running temporary basal \u2014 or the current scheduled basal if no temporary is running \u2014 then Loop will replace the current basal rate with the recommended temporary basal rate.

As mentioned at the beginning of this section, the process of determining whether a temporary basal should be issued is repeated every 5 minutes.

"},{"location":"operation/algorithm/temp-basal/#temporary-basal-rate-calculation-example","title":"Temporary Basal Rate Calculation Example","text":"

To illustrate how the Loop calculates the temporary basal rate to issue, consider the calculation for the following scenario:

  • \\(\\mathit{BG_eventual} = 200 \\mathrm{\\frac{mg}{dL}}\\)
  • \\(\\mathit{BG_target} = 100 \\mathrm{\\frac{mg}{dL}}\\)
  • \\(\\mathit{ISF} = 50 \\mathrm{\\frac{\\frac{mg}{dL}}{U}}\\)
  • \\(\\mathit{BR_scheduled} = 1 \\mathrm{\\frac{U}{hr}}\\)
  • \\(\\mathit{BR_max} = 6 \\mathrm{\\frac{U}{hr}}\\) (set by user in Loop)

First, calculate the dose:

\\[ dose = \\frac{\\mathit{BG_eventual} - \\mathit{BG_target}}{\\mathit{ISF}} = \\frac{200 \\mathrm{\\frac{mg}{dL}} - 100 \\mathrm{\\frac{mg}{dL}}}{50 \\mathrm{\\frac{\\frac{mg}{dL}}{U}}} = 2 \\mathrm{U} \\]

Then, convert the dose into a basal rate to be issued for the next 30 minutes:

\\[ \\mathit{BR_correction} = \\frac{2 \\times \\mathit{dose}}{\\mathrm{hr}} = \\frac{2 \\times 2 \\mathrm{U}}{\\mathrm{hr}} = 4 \\mathrm{\\frac{U}{hr}} \\]

Next, calculate the required basal rate:

\\[ \\mathit{BR_required} = \\mathit{BR_scheduled} + \\mathit{BR_correction} = 1 \\mathrm{\\frac{U}{hr}} + 4 \\mathrm{\\frac{U}{hr}} = 5 \\mathrm{\\frac{U}{hr}} \\]

Lastly, compare the required basal rate to the maximum temporary basal rate, and find that Loop will enact a temporary basal rate of \\(5 \\mathrm{\\frac{U}{hr}}\\) for 30 minutes since this temporary basal rate is below the maximum temporary basal rate of \\(6 \\mathrm{\\frac{U}{hr}}\\), which was set by the user in Loop app settings.

\\[ \\mathit{BR_{temp}} = \\max(\\min( \\mathit{BR_{required}}, \\mathit{BR_max}), 0) = \\max(\\min( 5 \\mathrm{\\frac{U}{hr}}, 6 \\mathrm{\\frac{U}{hr}} ), 0) = 5 \\mathrm{\\frac{U}{hr}}\\]"},{"location":"operation/algorithm/temp-basal/#more-examples","title":"More Examples","text":"

Consider the following values as fixed values for our calculation:

  • \\(\\mathit{BG_target} = 100 \\mathrm{\\frac{mg}{dL}}\\)
  • \\(\\mathit{ISF} = 50 \\mathrm{\\frac{\\frac{mg}{dL}}{U}}\\)
  • \\(\\mathit{BR_scheduled} = 1 \\mathrm{\\frac{U}{hr}}\\)
  • \\(\\mathit{BR_max} = 6 \\mathrm{\\frac{U}{hr}}\\)

The table below shows the \\(\\mathit{BR_temp}\\) for different \\(\\mathit{BG_eventual}\\). \\(\\mathit{BR_temp}\\) should never turn negative and should never be greater than \\(\\mathit{BR_max}\\).

\\(\\mathit{BG_eventual}\\) \\(\\mathrm{(\\frac{mg}{dL}})\\) \\(\\mathit{dose}\\) \\(\\mathrm{(U)}\\) \\(\\mathit{BR_correction}\\) \\(\\mathrm{(\\frac{U}{hr}})\\) \\(\\mathit{BR_required}\\) \\(\\mathrm{(\\frac{U}{hr}})\\) \\(\\mathit{BR_temp}\\) \\(\\mathrm{(\\frac{U}{hr})}\\) 300 4.0 8.0 9.0 6.0 200 2.0 4.0 5.0 5.0 100 0.0 0.0 1.0 1.0 90 -0.2 -0.4 0.6 0.6 75 -0.5 -1.0 0.0 0.0 50 -1.0 -2.0 -1.0 0.0"},{"location":"operation/algorithm/temp-basal/#algorithm-section-menu","title":"Algorithm Section Menu","text":"
  • Algorithm Overview
    • Bolus Recommendations
    • Blood Glucose Prediction
    • Temp Basal Adjustments
"},{"location":"operation/features/battery/","title":"MDT Pump Battery","text":""},{"location":"operation/features/battery/#medtronic-pump-battery","title":"Medtronic Pump Battery","text":"

One common confusion point for new Loop users is how to interpret their pump's battery levels and whether they need to change their pump batteries based on which pieces of information.

"},{"location":"operation/features/battery/#discharge-curves","title":"Discharge Curves","text":"

There are generally two different types of AAA batteries that we use in these Medtronic pumps; alkaline or lithium.

To understand pump battery levels, you first need to know a little about battery discharge curves. It's not a hard concept...basically how a battery dies over time as it is used or sits in a drawer. More technically said, a battery discharge curve is the measure of volts that a battery puts out over time. Batteries start at a higher voltage output and slowly that voltage output degrades over time (or use) until the battery no longer provides enough \"ummph\" to keep the electronic gadget going. BUT, alkaline batteries and lithium batteries have different discharge curves due to the chemistry inside them, and the curves can be slightly different depending on the environment (temperature) and battery manufacturer.

Alkaline batteries have a relatively steady voltage drop over time, as shown below. Notice the shape of the curve has a significant amount of time in the 1.3 to 1.2 volts range, and a relatively smooth decline to about 1.2 volts.

Lithium batteries have a much steadier voltage output over time, as shown below. Notice how the shape of the curve is relatively flat for a large portion of the battery life before suddenly off around 1.3 volts.

What does the above information mean in terms of Looping? A lithium battery at 1.3v is going to have a much quicker time to death than an alkaline battery sitting at 1.3v. You might only get a couple of hours of looping left when a lithium battery is at 1.3v, but an alkaline battery at 1.3v might go for several more days. So when we talk about setting alarm levels in either system, your battery type is an important consideration.

"},{"location":"operation/features/battery/#medtronic-pump-battery-level-indicator","title":"Medtronic Pump Battery Level Indicator","text":"

If you read Medtronic's literature, it will tell you to use Energizer alkaline batteries in their pumps. Why would that be? Hint: the answer doesn't mean that Duracell batteries are inherently worse than Energizer or that lithium batteries won't work in Medtronic pumps.

The answer is all about the accuracy of their little pump battery level indicator on their pump's screen. Medtronic calibrated their pump battery level indicator to:

  • Energizer alkaline batteries
  • Normal (non-Loop) uses
  • Temperatures between 37\u00b0F (3\u00b0C) to 104\u00b0F (40\u00b0C).

In other words, Medtronic ran experiments to see exactly how long an Energizer alkaline battery will last in normal pump use and made their own discharge curve. They programmed their pump battery level indicator to change from 4 bars to 3 bars to 2 bars to 1 bar based on that particular discharge curve.

However, Loop users are slightly more demanding on the pump's battery/voltage than simply delivering insulin. We are also asking for the pump to perform radio communications, in addition to delivering insulin. Those radio communications need a slightly higher voltage than the typical \"normal\" pump use. So while a non-Looper might be ok running their pump until a voltage of about 1.12 for insulin delivery, radio communications might stop at a voltage output of about 1.17. If you experiment with your Looping pump, you'll find Loop will turn red from failed pump comms before the pump actually fails at insulin delivery. This difference between \"failure\" voltages needs to be considered when determining how much useful battery life is left for a pump battery.

In summary, that little pump battery indicator on the Medtronic pump screen is ONLY useful if you are:

  • not using the pump for Looping,
  • using Energizer alkaline batteries, and
  • in the temperature environment similar to their testing.

Loop users should not rely on their Medtronic pump screen's pump battery indicator, and instead use the Loop's pump battery level indicator.

"},{"location":"operation/features/battery/#loops-pump-battery-level-indicator","title":"Loop's Pump Battery Level Indicator","text":"

Keeping the information about battery discharge curves in mind, Loop developers tested various battery brands and types to develop discharge curves for Loop users. These discharge curves form the basis of the pump battery level indicator found in the top right of the Loop's main display screen and the pump battery notifications provided by the Loop app. The pump battery level indicator will also report in %.

  • For x23 and x54 model users, the Loop's pump battery level will move in 25% increments.
  • For x15 and x22 model users, the Loop's pump battery level will move in discrete % increments.

Based on the battery type selected and the pump model being used, the Loop's pump battery level notifications are designed to give the user about 8 hours of notice before pump communications are likely to fail. The Loop user should have some additional time after pump comms fail before actual insulin delivery would stop.

"},{"location":"operation/features/battery/#nightscout-pump-battery-display","title":"Nightscout Pump Battery Display","text":"

The Nightscout information regarding pump battery levels will depend on pump model being used.

  • If you use an x23 or x54 pump and MySentry, the pump levels are reported as a percent to NS, because that's how MySentry reports the data to Loop. The packets use 100%, 75%, 50%, and 25% increments, and the Loop's main display matches the NS pump display.
  • If you use an x22 or x15 pump, the pump levels are reported as voltage readings to NS because Loop has to specifically request the voltage reading from the pump. The Loop's main display will show pump battery level as discrete %, not the individual voltage measurement.
  • No matter what pump you are using, you can always get the current pump battery's voltage by using the RileyLink's Read Pump Status command.
  • The extra communications effort for non-MySentry model pumps will mean slightly shorter battery life vs. MySentry model pumps.
"},{"location":"operation/features/battery/#nightscout-pump-battery-alarms","title":"Nightscout Pump Battery Alarms","text":"

The Nightscout alarms are based on the Heroku settings that you have input specifically. If you don't specifically set them, Nightscout will use the default settings for pump battery alerts as shown below:

Nightscout pump battery levels, if you leave things at default installation, will not trigger alarms. If however you add a setting of PUMP_ENABLE_ALERTS to true, you will receive pump battery notifications according to the levels shown in the parenthesis above. For example, your x23 pump is reporting its levels in percent, therefore you'd receive a yellow warning alarm at 30% and an urgent red alarm at 20%. Your x22 pump however is reporting its levels at voltage readings, therefore you'd receive a warning yellow alarm at 1.35v and an urgent red alarm at 1.30v.

Are the default NS alarm levels going to work for you? The answer depends on what type of battery level you are using, what model pump you are using, and how much advance notification you want to receive before needing to change a pump battery. There is a bit of personal preference and experimentation to finding what works for you.

For x22 or x15 pump users, the NS alert settings that may need to be adjusted are the ones based on voltage.

Generally speaking, for a x22 or x15 pump using alkaline batteries, the default NS alarm levels will be too early to be useful and lead you to change out your battery too frequently. Alkaline batteries can go to low 1.2s or high 1.1s before Looping starts to have communication problems. How much lower than the default voltage 1.35/1.30 alarm levels you want to go will depend on how far in advance you want to be warned about an upcoming battery change.

If however, you are using a x22 or x15 pump with lithium batteries, the default 1.35v/1.30v alarm levels may be completely appropriate. Remember how the lithium battery curves at the start of this discussion died off quickly around 1.3v? You won't get hardly any heads-up notice for a lithium battery if you set the alarm below 1.3v.

For x23 or x54 pump users, the NS alert settings that may need to be adjusted are the ones based on percentage settings.

Alkaline and lithium batteries should have automatically had their percentage-remaining based on the correct battery type in your Loop settings. So, generally speaking the default NS alert levels don't generally need adjusting. However, if you are using lithium batteries, the drop off between 75% to 25% can be quite dramatic and not be easy to anticipate (especially if the drop happens overnight).

As an alternative method of tracking pump battery changes, you could use the insulin age (IAGE) plug-in to anticipate your pump battery changes as well. For example, after tracking pump battery life on my 723 using energizer batteries lithium batteries for the last several months, I know that we get about 15 days plus a handful of hours. The amount of hours more beyond 15 days varies depending on how much we've interacted with the pump buttons directly, whether we've looped the full 15-days solid, and if the pump has been in extreme weather (cold weather can sap pump battery life). By tracking the pump battery changes with NS's careportal \"insulin cartridge change\", I can see in advance if we are nearing an overnight on a 15 day battery and decide to change batteries before overnight to prevent any middle-of-night battery issues.

  • Lithium batteries will get a significantly longer life than an alkaline battery.
  • Experiment and track your particular pump model and battery type to understand what NS settings will work best for you.
  • Do not rely on the pump's on-screen pump battery indicator, especially when using lithium batteries.
"},{"location":"operation/features/bolus/","title":"Bolus","text":""},{"location":"operation/features/bolus/#bolus","title":"Bolus","text":"

This page was updated with information for Loop 3.

"},{"location":"operation/features/bolus/#loop-2-and-3-differences","title":"Loop 2 and 3 Differences","text":"

Most of the information is the same for Loop 2.2.x and Loop 3.

Loop 2 and 3 differences:

  • Loop 3 uses the setting name of Glucose Safety Limit, which has the same meaning as Suspend Threshold in Loop 2
  • With Loop 3.2 and later
    • Loop automatic delivery of insulin is limited when users IOB is two times the Maximum Bolus amount
  • Bolus Row:
    • With Loop 3.0 and later
      • The Recommended Bolus is provided AND the default for the Bolus is the recommended value
      • If the user taps on the Bolus row, the amount is modified to 0 and the keyboard is opened for entry
    • With Loop 2.2.x
      • The Recommended Bolus is provided but the default for the Bolus value is 0
      • If the user taps on the Recommended Bolus row, the recommended amount is transferred to the Bolus row
"},{"location":"operation/features/bolus/#meal-bolus","title":"Meal Bolus","text":"

The Meal Bolus screen is entered following a carb entry or edit action, the active button might be Save and Bolus or, if no bolus was recommended, Save without Bolusing.

The Save refers to saving the Carb entry or Carb edit that led to this screen in addition to saving the amount that might be bolused. It can also refer to saving a fingerstick value entered in the Meal Bolus screen (Loop 3 only).

You can review the carb information at the Meal Entry link.

Carbs are Saved in Meal Bolus Screen

Carbs are saved when the Save and Bolus or Save without Bolusing button is tapped in Meal Bolus Screen. When the button is tapped, carbs are saved even if the bolus does not go through to the pump.

If you see a Bolus Issue notification (Bolus in progress, etc) after saving a carb entry, check the state of Loop carb entries.

Do not just add the carbs again.

"},{"location":"operation/features/bolus/#accept-recommendation","title":"Accept Recommendation","text":"

The graphic below shows the Meal Bolus screen after the user entered carbs and tapped continue:

  • The left graphic shows a case where a bolus is recommended - tapping on the Save and Deliver button saves the carbs and delivers the bolus
  • The right graphic shows a case where no bolus is recommended - tapping on the Save without Bolusing saves the carbs
  • These graphics are taken from a small phone - the left graphic shows all the information at once whereas the right graphic has an extra information message that requires the user to scroll to see the Recommended Bolus and Bolus rows
  • For both graphics
    • Active Carbs and Active Insulin are displayed above the Glucose prediction graph - these are accurate at the time this screen is entered (before carbs or bolus are saved)
    • The Bolus Summary is presented below the Glucose prediction graph with three rows:
      • Carb Entry, the proposed carbs with the time to add the carbs and the absorption time displayed - to modify that information, tap on the < Carb Entry button at upper left
      • Recommended Bolus displays what Loop recommends for that proposed Carb Entry
      • Bolus default display is what Loop recommends, but user can edit that value

If a CGM entry arrives while in this screen, a Bolus Recommendation Updated modal message will be displayed and must be acknowledged.

"},{"location":"operation/features/bolus/#modify-bolus","title":"Modify Bolus","text":"

This section is a continuation of the information presented in the Accept Recommendation section above. In the graphic below, the user overrides the recommended bolus.

  • The left side shows a modified bolus less than the recommended bolus
  • The right side shows a modified bolus greater than the recommended bolus
  • The Glucose prediction graph updates with changes to the Bolus value, giving the user the opportunity to accept or change their proposed value before tapping Save and Deliver
  • At the next Loop cycle, the app modifies insulin delivery based on the saved information
    • For the example with bolus less than recommended amount:
      • Loop will NOT begin to automatically increase insulin delivery until the current glucose is above the bottom of the Correction range
      • The recommendation to add insulin when the current glucose is below the Correction Range is only offered as a manual feature and is limited to an amount predicted to maintain glucose above the Safety Threshold
    • For the example with bolus greater than recommended amount:
      • Loop will probably issue an automatic temp basal of 0 U/hr
      • This is a common \"super-bolus\" scenario; in other words, \"borrow\" basal for the meal bolus to limit post meal spikes
  • Remember - the Glucose prediction is what happens if you Save and Deliver and then no further adjustments are made to insulin delivery by Loop

"},{"location":"operation/features/bolus/#manual-or-correction-bolus","title":"Manual (or Correction) Bolus","text":"

To start a bolus entry, tap on the double orange triangles (circled below) in the toolbar at the bottom of the Loop status screen.

The Loop app will open to the Bolus screen. This looks similar to the Meal Bolus screen without the Carb Entry row. Loop considers the Glucose Safety Limit and Predicted Glucose when determining the recommended bolus.

In the graphic below, the current glucose is under the Correction Range. Loop allows you to dip below the correction range but its recommended bolus will be limited by the glucose prediction and the Glucose Safety Limit. Check back once your glucose starts to rise and there will probably be a bigger recommendation.

This screen behaves differently for Loop 2.2.x and Loop 3. The graphics and instructions on this page are for Loop 3 version. Click on the Loop 2.2.x link above to view the Loop 2 version.

When the Bolus screen is entered directly from the toolbar, the button choices are Enter Bolus if none is recommended, Deliver if a value is on the Bolus row or Cancel using the button on the upper left. The user can also tap on the value on the Bolus row to bring up a keyboard to modify that amount. When doing that, the value is automatically set to zero.

The two graphics below are examples of manual bolus screens.

  • In the first graphic, no bolus was recommended
    • If you tap on the Enter Bolus button at the bottom, it brings up a screen to enable you to type in an amount and then Deliver it.
    • Alternatively, you can tap the 0 amount in the Bolus row and perform the same action as the Enter Bolus button
    • If you do not want to override the recommendation, hit the Cancel button at upper left.

  • In the second graphic, a recommended amount is shown
    • If you tap on Deliver that recommended dose is delivered
    • If you tap on the value on the Bolus row, you can override the amount
    • The amount displayed on the Bolus row is modified to 0 U with the first tap - at that point, you may enter a new value or tap Cancel using the button at upper left of the screen

"},{"location":"operation/features/bolus/#recommended-bolus","title":"Recommended Bolus","text":"

Loop updates the glucose prediction every time a new glucose reading is detected, typically every 5 minutes. If Loop predicts your glucose will be above the high end of your Correction Range at the end of the Duration of Insulin Activity (DIA) and the predicted glucose is above the Glucose Safety Threshold, it will provide a Recommended Bolus. Loop will not give an alert when a bolus is being recommended, the bolus entry tool must be clicked to check for one. The Loop pill in Nightscout will display when Loop is recommending a bolus.

  • If your Dosing Strategy is set to Temp Basal (default)

    • Loop will provide increased temporary basal rates until it has delivered enough insulin to bring predicted glucose into range
    • The increased temporary basal rates are subject to your Delivery Limits.

  • If your Dosing Strategy is set to Automatic Bolus

    • Loop will recalculate the correction bolus at each successive loop interval, i.e., every 5 minutes
    • Loop will then automatically deliver 40% of that new correction value
    • Each automatic bolus is subject to your Delivery Limits
"},{"location":"operation/features/bolus/#bolus-status-line","title":"Bolus Status Line","text":"

Lock Phone During Bolus

Once the bolus has started, you should lock your phone to avoid inadvertently cancelling a bolus.

When the phone is in portrait mode, a bolus status line will appear below the Heads Up Display when Loop has a bolus in progress. The \"starting bolus\" indicator is shown in the left screenshot above - this is when Loop is communicating with the RileyLink. Once the message has been sent to the RilyLink, even if a response from the pump did not make it back to Loop, the bolused xx of yy with the circle display begins, as shown in the right screenshot above. If you change your mind, just click on the bolus status line while the bolus is in progress to cancel your bolus, as shown in the screenshot below. (Newer versions of Loop explicitly state: Tap to Stop on this line.) The amount bolused shown in this display is based on time. Loop reconciles the bolus amount with messages received from the pump once the bolus completes.

If you see a 'pump is suspended notice' in the bolus status line after cancelling your bolus, just tap on it to resume pump operations.

"},{"location":"operation/features/bolus/#bolus-failure-notifications","title":"Bolus Failure Notifications","text":"

On occasion, you will receive a notification that a bolus may have failed. If your Dosing Strategy is set to Automatic Bolus, this can happen when an automatic bolus is in progress. In some of these cases, the bolus was delivered. On a Medtronic pump, you should check the pump screen to verify the bolus status before attempting to redeliver a failed bolus. Omnipod users can hear the clicks if the room is quiet enough.

If you get an uncertain delivery message, you may still see the \"bolused xx of yy\" display continue for as long as it would have taken to actually deliver the bolus. This display is driven by a timer and logic on the phone. (Loop is not asking the pump repeatedly - \"are you done yet?\"). You may want to interrupt an uncertain bolus if it is large, evaluate status and then resume with a fresh bolus. Loop should update the status the next time it contacts the pump. It can determine whether that bolus actually went through or not and will update the screen. Look at the Event History screen (accessed by tapping the Active Insulin or Insulin Delivery plots). Turn your phone to landscape orientation and you should see either \"Certain\" or \"Uncertain\" at the end of each Bolus record. (If you tap on the specific record, even more detail is displayed.)

If an \"uncertain\" delivery is not resolved:

  • Make sure the RileyLink compatible device is communicating properly
  • You can try to turn off Bluetooth and then turn it back on again
  • Quit the Loop app and restart it. (Note - this is different from a power cycle of the phone which remembers settings within an app that was running before the power cycle.)

If that does not resolve the issue, please tap on Loop Settings, Issue Report and email it to yourself. Then post on Facebook or Zulipchat, explain what happened and say you have an Issue Report. Someone should reach out to you.

There are other alert messages that might be displayed if the pump or CGM is not active. Those are found on the Loop 3 Displays page.

"},{"location":"operation/features/bolus/#loop-2-bolus-screen","title":"Loop 2 Bolus Screen","text":"

  • Loop 2.2.x shows the recommended bolus but the bolus row is initially set to 0

    • You can tap on the Recommended line and that value will be transferred to the Bolus line
    • OR
    • You can tap on 0.0u on the Bolus row and type in your desired bolus amount
    • As soon as a value is entered on the Bolus row, the Deliver button turns blue and can be tapped to deliver that amount via your pump.

"},{"location":"operation/features/carbs/","title":"Meal Entries","text":""},{"location":"operation/features/carbs/#meal-entry","title":"Meal Entry","text":"

This page was updated with information for Loop 3.

"},{"location":"operation/features/carbs/#loop-3-updates","title":"Loop 3 Updates:","text":"
  • Time: Loop 3 adds the +/- 15 minute buttons to adjust time for entry
  • Food Type: emoji keyboard
    • Loop 3 initially displays Medium emojis and the association of some emojis with absorption time has been improved
    • Loop 2.2.x initially displays Fast emojis
  • Absorption Time: values for fast, medium and slow
    • Loop 3 uses 30 minutes, 3 hr, 5 hr
    • Loop 2.2.x uses 2 hr, 3 hr, 4 hr
  • Meal Bolus: Loop 3 fills in the Bolus row with Recommended Bolus
  • Large Meal Warning
    • The warning limit of 99 g was chosen to assist in catching mistakes such as entering 115 grams instead of 15 grams
  • Override Active Warning
    • A warning is presented when entering carbs while an override with sensitivity other than 100% is active
"},{"location":"operation/features/carbs/#meal-entry-fast-version","title":"Meal Entry - Fast Version","text":"

To start a new meal entry, tap on the green plate icon (circled below) in the toolbar at the bottom of the Loop status screen. Your Loop app will open to the Add Carb Entry screen.

Loop assumes carbs saved will be absorbed and Loop will adjust recommended insulin, and, when Closed Loop is enabled, Loop will adjust automated dosing based on those carbs.

  • Loop updates the carb estimate dynamically based on your glucose while meal is active
  • Approximate entry is \"good enough\"; better to underestimate carbs than to overestimate
  • The Loop recommended bolus can be modified by editing the Bolus amount after tapping the Continue button on the Add or Edit Carb Entry screen.

Beginner's Tip

  • Add some amount of carbs when you normally would dose before or at a meal
    • Make sure the amount of insulin recommended is not more than you expect
    • If the amount seems too large, you might need to reduce Amount Consumed entry or adjust settings
  • Accept the defaults as directed below
"},{"location":"operation/features/carbs/#meal-entry_1","title":"Meal Entry","text":"

The steps and graphics in this section are for users of Loop 3. To view the version used by Loop 2.2.x, click on this link.

Tap the meal entry icon on the toolbar to open the Add Carb Entry screen:

  1. Enter number of grams of carbs in the Amount Consumed row (keyboard appears automatically)
  2. Tap continue to advance to the Meal Bolus screen (as shown in the graphic below)
  3. Tap Save and Deliver to Save the carbs and Deliver the recommended bolus

The carbs are not saved until the Meal Bolus screen is completed.

  • If no bolus is recommended in the Meal Bolus screen:
    • A No Bolus Recommended warning appears with the reason why
    • The blue button on the Meal Bolus screen says Save without Bolusing
    • In this case, carbs are saved when the Save without Bolusing button is tapped

Carbs are Saved in Meal Bolus Screen

Carbs are saved when the Save and Bolus or Save without Bolusing button is tapped in Meal Bolus Screen. When the button is tapped, carbs are saved even if the bolus does not go through to the pump.

If you see a Bolus Issue notification (Bolus in progress, etc) after saving a carb entry, check the state of Loop carb entries.

Do not just add the carbs again.

By tapping on the Active Carbohydrates chart on the main Loop display, previously entered carbs can be edited, refer to Edit Meals.

"},{"location":"operation/features/carbs/#meal-entry-row-by-row","title":"Meal Entry Row by Row","text":"

Do you want to know more? This section discusses each row in turn.

"},{"location":"operation/features/carbs/#amount-consumed","title":"Amount Consumed","text":"

When entering the Add Carb Entry screen, the number keypad is deployed and when you start typing, that value is entered into the Amount Consumed row.

Tapping on any other row dismisses the number keypad. It can be restored by tapping on the Amount Consumed row.

Some value must be entered into the Amount Consumed row to continue.

Many Loopers increase the carbohydrate amount to cover the expected effect of protein and fat in their meal entry. For simplicity, the rest of this page only refers to carbs because all the figures show carbs or carbohydrates in the menus. You should consider the whole meal, including fat and protein, especially if you eat lower carb.

Loopers who consume mostly carbs in a given meal, might do better entering just the carbs.

"},{"location":"operation/features/carbs/#time","title":"Time","text":"

Modifying the Time for a new meal entry from the default value of \"now\" is optional.

  • Each tap on the \u2212 icon changes the time earlier in 15 minute increments
  • Each tap on the + icon changes the time later in 15 minute increments
  • Tap on the time to bring up a picker wheel for desired time

The 15 minute increments, which are also available on the watch interface, can be handy if the Looper chooses to prebolus.

Reasons to modify the time when entering a meal:

  • Meal is planned for the future, e.g., prebolus now (optional)
    • If meal is planned more than 15 minutes from \"now\", it's a good idea to modify the time to the planned start time
    • In Closed Loop, insulin dosing adjusts for planned carbs while maintaining the Glucose Safety Limit
  • Meal was eaten in the past but carbs were not entered
    • Loop does a better job with predictions if you enter the meal at the time it was eaten
    • Entering a previous meal (now) makes Loop think the carbs will all be in the future (not some of them in the past) and can cause too much insulin to be recommended / delivered
  • Some foods, like pizza, may need entries to start later with a longer absorption time

Limits for time entry of when meal was consumed:

  • The carbs can be entered up to 12 hours earlier or 1 hour later
    • When editing, this limit applies to the time when the carb entry was previously saved
"},{"location":"operation/features/carbs/#food-type","title":"Food Type","text":"

Food Type entries are optional.

The information about the next row: Absorption Time is also important when discussing Food Type entries.

  • The first touch of any icon sets the absorption time to the value associated with that icon
    • This includes the 3 icons (Lollipop, Taco, Pizza) on the Food Type row
    • If you touch the plate icon (or the words Food Type), a new set of icons (food emoji) appear as shown in the graphic below
      • Each emoji is associated with Fast, Medium or Slow absorption time
      • The first emojis presented are medium - scroll in either direction to view the fast and slow emojis or tap on the short-cut tabs at the bottom of the screen
      • The emojis under Other have no effect on absorption time and they do not \"count\" as a first tap; e.g., wine followed by bacon updates absorption time to Slow.
  • Any additional icon touches have no effect on selected absorption time
  • At any time, the Absorption Time picker can be used to adjust the absorption time

Pro Tip

  • If you want to enter food emojis
    • Verify food absorption time when you are done
    • If you know you want to keep the 3 hour absorption time, tap the taco icon on the main screen before entering food emojis

Loop 3 Absorption Times

If you switched to Loop 3 from Loop 2.2.x, please be aware that absorption times for the Lollipop, Taco, Pizza icons have been updated.

  • Loop 3 uses 30 minute, 3 hours and 5 hours
  • Loop 2.2.x used 2 hours, 3 hours and 4 hours

Beware using Lollipop for Complex meals

If you select the Lollipop icon for a large complex meal with Loop 3, you tell Loop to expect glucose to rise rapidly (30 min absorption). When that rapid rise does not materialize, Loop may predict an unexpectedly low glucose because the algorithm assumes something must be affecting 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.

\ud83c\udf6d (Fast) is for simple foods often used for low treatments. Some Loopers use it for coffee.

"},{"location":"operation/features/carbs/#absorption-time","title":"Absorption Time","text":"

Modifying the Absorption Time from the default value of 3 hours is optional.

  • If you touch any icon on the main entry or Food Type row, the absorption time associated with that icon becomes the new absorption time
    • Any additional icon touches have no effect on selected absorption time
  • At any time, the Absorption Time picker can be used to adjust the absorption time

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

Loop assumes a specific model for how those carbs will be absorbed that is spread out over an interval that is 150% of the selected time. This allows for variations in actual absorption. More information about this model is found in the prediction link above.

Many meals can be entered with the medium (3 hour) default absorption time. Learn by experimenting and modify going forward. Evaluate the CR setting, as well as the entries for Amount Consumed and Absorption Time for adjusting meal entries. The amount of up-front insulin recommended is typically similar up through 3 hours absorption and then begins to decrease as absorption time is increased.

Experiment for yourself - how much does Loop recommend compared to a straight Carbs/CR value? Try this at different times; especially when glucose is nominal and flat compared to low and dropping or high and rising.

  • Enter an absorption time and hit continue
  • Examine recommended bolus
  • Tap the < Carb Entry button at upper left
  • Modify the absorption time and hit continue
  • Repeat to get a feel for the up front bolus under different scenarios
"},{"location":"operation/features/carbs/#continue","title":"Continue","text":"

Carbs are not saved in the Add Carb Entry screen until the Continue button is pressed and the user saves those carbs in the Meal Bolus screen, follow the link for details.

"},{"location":"operation/features/carbs/#large-meal-warning","title":"Large Meal Warning","text":"

If the Amount Consumed row exceeds 99 grams when the Continue button is tapped, the user is provided with a modal alert from which they can proceed to the Meal Bolus screen, or return to edit Amount Consumed if that was not the intended amount.

"},{"location":"operation/features/carbs/#override-active-warning","title":"Override Active Warning","text":"

If you have an override active with insulin sensitivity value set to anything other than 100%, a warning message appears at the top of the Add Carb Entry screen.

"},{"location":"operation/features/carbs/#automatic-bolus","title":"Automatic Bolus","text":"

Loopers who are using the Automatic Bolus Dosing Strategy should still prebolus and/or bolus for meals. The amount of Recommended insulin that will appear in the Meal Bolus screen will be the full amount of the bolus Loop recommends (not the 40% partial bolus delivered automatically). As discussed above, you can accept this recommendation or enter a different amount, however, and this is very important, if your Dosing Strategy is set to Automatic Bolus, by entering less than the recommended amount and tapping Deliver or tapping Save Without Bolusing, you are telling Loop to deliver the remaining recommended insulin in the future using 40% of the recommended bolus at each successive Loop interval.

Carb Entry Leads to Insulin Delivery

Note that this same automatic delivery of insulin in response to entered carbs occurs when Dosing Strategy is set to Temp Basal, but the delivery via temporary basal rates is slower, providing more time for an error to be noticed. By the same token, the Automatic Bolus Dosing Strategy responds more quickly to increases in blood glucose, helping to minimize food spikes.

"},{"location":"operation/features/carbs/#edit-meals","title":"Edit Meals","text":"

Adjusting a meal entry can be a particularly useful tool when:

  • You did not finish an entire meal that you bolused for,
  • You did not get to eat the meal at the time you originally expected,
  • You ate more servings than originally entered, or
  • You suspect your carb count was in error because BGs are rising more/less than expected.

From the main Loop screen, tap on the Active Carbohydrates chart to view the Carbohydrates screen (see graphic below).

To adjust an entry, simply tap on it (do not tap the Edit button at the top of the screen). You can change the time, modify carb amounts, or adjust absorption times (even mid-meal). To delete an entry, you first tap Edit and tap on the red circle to the left of the entry that you would like to delete. It is a little counterintuitive, but the Edit button lets you delete, but not edit an entry.

For more information on some of the details reported on this screen, review Dynamic Carb Absorption

"},{"location":"operation/features/carbs/#review-carb-absorption","title":"Review Carb Absorption","text":"

New Loopers, and even experienced Loopers with an unfamiliar meal or activity, should review how Loop reports absorption for the carbs you entered for a meal. If you have perfect dosing for your meal (the mythical flat line), then the carb absorption will match the model perfectly. But sometimes, there might be COB on the Active Carbohydrates Chart Loop 3 / Loop 2 that doesn't reflect your current situation, and you might need to make an adjustment. Note that while Loop is pretty forgiving on exact values and absorption time, you need to learn what works for you. Some common things to consider are listed below.

  • Need to adjust value for carbs or account for fat/protein
  • Need to adjust aborption time
  • Need to review settings
  • Settings, carbs and absorption time are good for this meal but there was more or less activity than normal
  • Stress / Hormones / Exercise
  • Other effects

You can Edit previously saved carbs so Loop has a better idea of how to adjust predicted glucose moving forward. This can head off a low or a high.

"},{"location":"operation/features/carbs/#check-cob-before-adding-more","title":"Check COB Before Adding More","text":"

Loop works better when informed that carbs are coming, but if you have a lot of left-over carbs from an earlier entry - wait before adding more carbs for that next snack. If Loop thinks more carbs are expected, it will dose extra insulin to accommodate. Maybe set a timer and check back in half-an-hour or an hour to see if you really need to add more carbs.

Dosing at a Party

Example - at a party where Looper is eating small amounts at a time, get some carbs entered to get some insulin up front, but pay attention when clicking add carbs (especially when using the watch and accepting recommended dosing).

"},{"location":"operation/features/carbs/#avoid-double-meal-entries","title":"Avoid Double Meal Entries","text":"

Be Aware

If you have accidentally made duplicate entries for the same meal, click on the Active Carbohydrates chart in the main Loop screen and tap Edit to delete the redundant entries. Deleting the meal entry will not impact the insulin that has already been delivered, but it will alert Loop to adjust your BG projection for purposes of calculating future insulin delivery.

"},{"location":"operation/features/carbs/#dynamic-carb-absorption","title":"Dynamic Carb Absorption","text":"

Loop observes the blood glucose impact of the meal within the 150% absorption time window. Loop calculates how many carbs have been absorbed (regardless of how many you entered) based on your BG pattern and your settings.

You can watch the progression of Loop's observations of your meal by tapping on the Active Carbohydrates chart at the bottom of Loop's main screen and watching the insulin counteraction effects (ICE) on the Carbohydrates screen. An example of the screen is on the left side of the figure below. An explanation of the dual lines for each entry and the color coding scheme is explained below the figure. Click on the ICE link for more details and an in-real-life example.

  • Top line of each entry for the graphic on the left (above)
    • Amount you entered, time of entry, absorption time entered
  • Bottom line of each entry (changes with each CGM reading)
    • Amount absorbed, estimated time when amount you entered will be absorbed
    • Color codes while within the 150% absorption time window
      • Green: amount absorbed is less than 10% above the entered amount
      • Yellow: amount absorbed exceeds 10% above the entered amount
    • Color codes after 150% absorption time window expires
      • Grey: amount absorbed is within 10% of the entered amount
      • Yellow: amount absorbed is exceeds 10% above or below the entered amount

The information available on the Carbohydrates screen disappears for any meals older than 12 hours, so if you're looking for details as to how a particular meal absorbed, you may need to screenshot or otherwise capture this information within that window. Previous entries can be modified or deleted through this screen.

"},{"location":"operation/features/carbs/#medtronic-warning","title":"Medtronic Warning","text":"
  • Do not enter carbs into your Medtronic pump
    • If you use your Medtronic pump bolus wizard or carb entry screen, the pump will give you insulin but Loop will not know about the carbs
    • The Loop predictions will be off and next time Loop reads the reservoir history on the pump, it will probably command a temporary basal rate of 0.0 U/hr
"},{"location":"operation/features/carbs/#nightscout-entries","title":"Nightscout Entries","text":"

With Loop 3, a caregiver can add remote carbs and perform remote bolus through Nightscout, but that requires set-up between the caregiver and Loopers phone and use of the Remote Carb and Remote Bolus entries in the Careportal.

If you enter carbs (not remote carbs) into the Careportal, they are not read by Loop and will not be reflected in COB.

  • There may be times you want to do this, e.g., you want to indicate a low treatment you don't want Loop to know about
"},{"location":"operation/features/carbs/#third-party-apps","title":"Third Party Apps","text":"

This is relevant for Loop 2.2.x versions. Loop 3 does not read carbs from Apple Health unless you modified the code.

Please see Loop 2 Permissions.

"},{"location":"operation/features/carbs/#carb-absorption-model","title":"Carb Absorption Model","text":"

For more information about the way Loop models the effects of carbs, insulin, etc., see the algorithm page.

"},{"location":"operation/features/carbs/#loop-2-fast-meal-entry","title":"Loop 2 - Fast Meal Entry","text":"

This section is for users of Loop 2.2.x.

Tap meal entry icon on toolbar

  1. Enter number of grams of carbs in the Amount Consumed row
  2. Tap continue to advance to the Meal Bolus screen
  3. Tap Recommended line to transfer the value to the Bolus line (Loop 2.2.x)
  4. Tap Deliver

The carbs are not saved until the Meal Bolus screen is completed.

By tapping on the Active Carbohydrates chart on the main Loop display, previously entered carbs can be edited, refer to Edit Meals.

"},{"location":"operation/features/ice/","title":"Meal Review","text":"

When on Loop main screen, tapping on the \"Active Carbohydrates\" graph will open up the \"Carbohydrates\" details page that tracks your carb entries for the last 12 hours and how they are absorbed. It can be helpful to review your meals when monitoring settings, troubleshooting past meal entries, and planning future meal entries.

"},{"location":"operation/features/ice/#insulin-counteraction-effects","title":"Insulin Counteraction Effects","text":"

What are Insulin Counteraction Effects (ICE for short)?

Consider the possible effects that counteract insulin (in other words, make glucose levels go up):

  • food
  • stress
  • illness
  • site failure
  • basal too low
  • someone sat too close to you

As we all know, this list can be long; but on \"normal\" days, food is the primary reason glucose levels go up. By \"normal\", we mean basal rates and settings are close to correct, illness is not an issue, and the site is good. We depend on the Loop dynamic carb absorption and other prediction effects to keep glucose in our desired range.

When you have carbs on board, Loop always\u00a0assigns ICE to carbs, not just on a normal day. This is how Loop looks at it. Keep in mind that in situations where you have other positive ICE, like insulin resistance, and carbs on board, Loop will attribute all the positive ICE to carbs until all the entered carbs are considered absorbed. At that point, ICE will start driving RC upward.

Insulin Counteraction Effect (ICE) as explained in Dynamic Carbohydrate Aborption is one very important part of carb absorption as well as a foundational part of Loop Predictions.

"},{"location":"operation/features/ice/#glucose-change-display","title":"Glucose Change Display","text":"

The graph at the top of your \"Carbohydrates\" details page shows the effect Loop expects carbs to have on your glucose (gray bars) compared to the actual effect, or ICE. The units on the graph are mg/dL/5-min or mmol/L/5-min

  • \u2b1c\ufe0f: The gray bars represent the effects of carbohydrates on your blood glucose that Loop is currently modeling.

  • \ud83d\udfe9: As a meal is tracked by Loop, you'll see green bars of observed carb absorption (including ICE).

    How Loop thinks about carbs

    ICE is just one important component of how Loop thinks about carbs. The other parts are the user-entered data (amount of carbs, and absorption speed).

    Sometimes Loop falls back to a default absorption model when ICE is less than the minimum absorption rate.

    In the graphic below, early in the meal timeline, the green bars are below the grey bars. Loop uses the minimum absorption instead of estimating absorption from glucose change. For example, if a pre-bolus was \"perfect\" leading to a constant glucose after a meal, the ideal grey bars will be used by Loop throughout.

When not to Use Glucose Change Display to Understand Meal Absorption?

If you know that other non-carb effects are affecting your insulin sensitivity significantly (sickness, exercise, etc), all the info about carb absorption should be considered skewed, and not be used for trying to understand meal absorption.

"},{"location":"operation/features/ice/#practical-use","title":"Practical use","text":"

Some practical use of the ICE screen is provided in the Meal Entries: Review Carb Absorption section.

Many ways to successfully use Loop

You should choose what works for you.

  • Some people plan ahead and try to get their carbs entries \"good enough\" to not worry about Loop or glucose after they make the initial entry
  • Some people enter typical values for themselves for a given meal and let Loop handle the rest
  • Some people guess and then carb surf if their glucose goes higher than they like

The rest of this page was written by Katie DiSimone before the non-linear carb model was added to Loop in 2019. You may also want to review her blog post from 2017: Loop: Dynamic Carb Absorption.

A lot of the information is still relevant although some of the Loop carb modeling and prediction details have been updated over the years.

Let's take a look at an example day using the screenshot below.

When you make a food entry originally, Loop will save your entry as you've made it. On the line below your original entry, Loop will also start tracking your food entry assuming a 1.5 times longer carb absorption time. This helps Loop track carbs that may actually be absorbing longer than you expected (part of that whole dynamic carb absorption modeling). Loop will be updating that value of \"observed\" carb absorption time as well as absorbed carbs as your meal goes on.

So how can we use this information to make our Looping experience better? The answer is probably best illustrated using a real-world example. Chinese food...in fact, this Chinese dish. General Tso's chicken. As you can see in the recipe, loads of fast carbs with ingredients like hoisin sauce, brown sugar, and cornstarch. But also slower carbs like chicken. Rice can be a difficult one because, for us, it acts fast but also seems to have a long tail.

It was a busy day and I really didn't want to count carbs. Ok, even on the slow days I don't want to count carbs. I just eyeballed the bowl of food and guessed. As I entered the food in originally, I was still trying to come up with a good guess on the ratio of fast:slow carbs but kid was in a hurry to eat. My initial guess around 3:30 pm was 70g of carbs at 5 hours absorption (note: it gets edited to 80g in a little bit), we bolused for that and she started to eat. About 10 minutes later, I decided to add 10g of fast-acting carbs at 1-hour absorption to help with the sauce's speedy carbs.

Watching what was going on a little later...glucose levels were rising at a decent clip and I had a feeling I really didn't cover things super well...so I edited the original 70g entry, adding 10g and making it 80g instead. (That's why there is a 2U bolus around 4:20 pm.) And of course, around 5:40 pm there was a little bit of nibbling on the leftovers as we put them into the fridge. We gave 10g for that. Glucose levels climbed a bit more, not surprising given how we were underestimating fast carbs at this point...but still not so bad at 180 peak glucose. (Anna gave 2 units of correction at the peak because there was dessert coming later that night and she wanted to be ready for it without too much pre-bolus.)

So, how can I use the \"Glucose Change\" graph to make this meal better? I can look at the observed carb information and the observed carb entry Loop has recorded to adjust my insulin bolusing the next time we eat this meal.

For example, the biggest weakness I had in this (and suspected it even as I did the initial bolus) was that I underestimated the sauce's fast carbs. I can see this in the observed carb absorption graph having the early green peaks after the meal, and in the way that the observed carb distribution was more like 7:2 vs my original guess of 8:1 (slow:fast carbs). Overall, it appears that I guess on overall carb content pretty closely (90g vs. 89g observed). Next time we have General Tso's chicken, I will likely bolus it as 70g at 5 hours and 20g at 2 hours.

Check Carbohydrates Page

Remember to check your Carbohydrates page at the end of a meal's absorption. By checking in on the meal's observed behaviors, you'll have a good starting point to fine-tuning any new or unknown carb breakdown.

Note

Remember this conversation is assuming you have basals fairly well set and are not sick. If other factors could be significantly causing your glucose levels to swing that Loop doesn't know about (bad sites, illness, or basal rates that need to be adjusted), they may be attributed in part to ICE when they really aren't food-related. In those cases, address the underlying cause and then use the Carbohydrates page when you've come back to \"normal\".

"},{"location":"operation/features/notifications/","title":"Loop Notifications","text":""},{"location":"operation/features/notifications/#loop-notifications","title":"Loop Notifications","text":"

Loop provides discrete notifications on the iPhone and Watch which will appear on the (locked) screen and vibrate, depending on your notification settings of Loop.

"},{"location":"operation/features/notifications/#loop-alert-unable-to-reach-pump","title":"Loop Alert - Unable to Reach Pump","text":"

With Loop 3, there is a new modal alert that halts all Loop activity until pump communication can be restored.

When you tap on the Learn More button, another screen appears. The only option allowed on the second screen is to give up and discard the pump (or pod) or continue to wait - tap the Back button. The second screen is there if you need to tell Loop you will not be able to restore communication and it should treat the last attempt to send a command as uncertain. Loop will then allow you to add a new pod or new Medtronic pump or switch to a different insulin delivery device.

Only do this if bringing your phone and pump into close proximity, waiting a few minutes and then trying the Reset Loop-to-Pump Communications suggestions are not successful.

Why Stop all Activity?

When communication is interrupted at a critical moment in the communication cycle, Loop cannot provide a reliable calculation for IOB. When that happens a warning screen similar to the graphic above appears on your device. You cannot do anything but wait for Loop to restore communications or give up on that device.

"},{"location":"operation/features/notifications/#loop-app-expiration-notification","title":"Loop App Expiration Notification","text":"

Profile expiration notification was added with Loop 2.2.5.

  • When fewer than 20 days remain until profile expiration, you'll get a notification when you open the app but no more frequently than every 2 days
  • When fewer than 24 hours remain, you'll get a notification when you open the app, once every hour at most
  • Simply tap on the More Info button of the notification to go directly to the LoopDocs Updating page.
"},{"location":"operation/features/notifications/#free-7-day-loop-app-expiration-notification","title":"Free (7-day) Loop App Expiration Notification","text":"

The expiration notification pattern is the same as for the Paid Loop App. You may want to add an Expiration Notification Customization to modify the first appearance and frequency of the notification.

"},{"location":"operation/features/notifications/#loop-app-expiration-date","title":"Loop App Expiration Date","text":""},{"location":"operation/features/notifications/#for-loop-32x-and-newer-versions","title":"For Loop 3.2.x and newer versions","text":"

The expiration date is found in the App Profile section at the bottom of the Loop Settings screen.

"},{"location":"operation/features/notifications/#for-loop-225-through-loop-30","title":"For Loop 2.2.5 through Loop 3.0","text":"

If you want to see the expiration date at any time:

  • Loop 2.2.5 through 2.2.9: tap on Settings, then tap on Issue Report
  • Loop 3.x.x: tap on Settings, scroll down and tap on Support, then tap on Issue Report

The expiration date is near the top of the report (to the right of profileExpiration). If you don't see that, time to rebuild to get that feature. Once you've viewed the expiration date, tap Settings to back out of the Issue Report display. The time uses UTC, so adjust to your time zone if you procrastinated until the last minute.

"},{"location":"operation/features/notifications/#omnipod-beeps","title":"Omnipod Beeps","text":"

Most pod beep alarms are disabled for a more discrete use of pods than is available with the PDM. Only the following audible acknowledgments or alarms are used. Some can be configured in Omnipod: Notification Settings:

  • Pod activated acknowledgment when filling the pod with enough insulin when pairing a new Pod.
  • Pod expiration advisory alarm, which you can configure between 48 and 72 hours (3 days)
  • Pod low reservoir alert
    • Note that the pod may continue delivering after the reservoir reports 0 U
    • The pod will continue until the pod runs out of insulin or 4 U is delivered, which ever comes first
    • Loop will update the actual delivery amounts based on pod reported information
  • Pod deactivation acknowledgment
  • Pod fault alarm (also called a screamer) when reaching the max life of the Pod: 80 hours (3 days + 8 hours), running out of insulin or a fault/occlusion happens
    • Screamers are silenced using the Replace Pod row on the pod settings page
    • The one exception is if communications with the pod is lost and cannot be restored - in that case, you will be offered the chance to discard the pod from Loop but will still want to Silence the Pod
"},{"location":"operation/features/notifications/#notification-settings-for-loop","title":"Notification settings for Loop","text":"

You can customize the way notifications of Loop are behaving in the Settings App of the iPhone:

Loop 3 Notifications Settings:

Mark Loop 3 notifications as time-sensitive and ask for immediate delivery:

  • tick the Immediate Delivery so that notifications are delivered right away
  • enable the TimeSensistive Notifications checkbox

Notification Delivery

You will see the Notification Delivery section only if you previously toggled on Settings / Notifications / Scheduled Summary in order to receive a summary of notifications at a certain time of the day. If this is not what you want, simply ignore it.

Announce Notifications

The Announce Notifications section is displayed only if you previously turned on the toggle Settings / Notifications / Announce Notifications. Use it if you want Siri to read Loop's notifications out loud on CarPlay, and AirPods...

Make sure Loop notifications are allowed in your Focus mode. Edit the focus mode to:

  • add Loop to the list of apps with allowed notifications
  • enable the Time Sensitive Notifications toggle button
"},{"location":"operation/features/notifications/#taking-a-loop-break","title":"Taking a Loop Break","text":"

If you want to take a break from using Loop but want to keep the app on your phone, you'll want to disable Loop Notifications while you are not using Loop. Otherwise, the Loop Failure messages will drive you crazy.

When you are ready to resume using Loop, the main screen will remind you to turn those notifications back on.

Another time you might want to disable notifications is if you are testing with a simulated pump. When the app is closed or phone is locked, the simulated pump is inactive and you would get the Loop Failure notifications.

"},{"location":"operation/features/notifications/#loop-failure","title":"Loop Failure","text":"

At 20, 40, 60, and 120 minutes, there is a Loop Failure notification. This mostly happens when the connection is lost for a longer period of time between the CGM or the Rileylink and Loop.

"},{"location":"operation/features/notifications/#bolus-failure","title":"Bolus Failure","text":"

If Loop detects that a bolus was not able to be delivered, it will provide a notification. Bolus failures are usually due to stale pump data. Try fetching recent history from the RileyLink menu to update pump data. Loop will also notify of partial bolus deliveries.

"},{"location":"operation/features/notifications/#low-reservoir","title":"Low Reservoir","text":"

Medtronic At 20% and 10% remaining reservoir volume, there is a Low Reservoir notification.

Omnipod Select your desired notification level for low reservoir Omnipod: Notification Settings

"},{"location":"operation/features/notifications/#empty-reservoir","title":"Empty Reservoir","text":"
  • Loop 2 will notify when the reservoir is empty.
  • Loop 3 reports No Insulin on the Heads-Up-Display.

Omnipod After the reservoir reports 0 U, the pod attempts to deliver insulin when requested.

  • After 4 U are delivered, the pod alarms and must be changed
  • If during the attempt to deliver the 4 U (below zero), the pod runs out of insulin, the pod alarms and must be changed
  • In both cases, the pod reports it is out-of-insulin
"},{"location":"operation/features/notifications/#low-battery-medtronic","title":"Low Battery (Medtronic)","text":"

Loop will notify when battery levels have approximately 8-10 hours of battery life remaining.

"},{"location":"operation/features/notifications/#remote-notifications","title":"Remote Notifications","text":"

Loop does not have a remote notification to other devices. If you are a remotely monitoring parent, you will want to read here about setting up pushover alerts using your Nightscout site if you want proactive notifications of looping related information.

"},{"location":"operation/features/notifications/#loop-follow","title":"Loop Follow","text":"

Many people use additional apps to assist in following a loved one or to support a loved one who needs help waking up to alarms. One of the more popular options is Loop Follow, written by a parent of a Looper. There are several features to assist in remote monitoring with a variety of options for the source of data.

For more information, please read the Loop Follow documentation. You can build Loop Follow using the same Build Select Script you used to build the Loop app or using the GitHub Browser Build Method.

"},{"location":"operation/features/overrides/","title":"Overrides","text":""},{"location":"operation/features/overrides/#new-loopers-please-read","title":"New Loopers - Please Read","text":"

Please do not use this feature until you understand it.

Many new Loopers interpret Loop Overrides as a one-for-one replacement for manual pump options where a temporary basal was applied for a particular activity. Although Loop Overrides can help in a situation where you previously used a temporary basal rate, overrides are more powerful.

Changing Overall Insulin Needs is NOT like Manual Pump Temp Basal Change

Loop Overrides are not the same as adjusting temporary basal on a manual pump. The easiest way to restrict basal rates with an automated system is to raise your correction target temporarily. In some cases, you may need to also adjust insulin needs, but begin just by changing that target.

When you modify insulin needs, you are affecting basal rates, carb ratios, and insulin sensitivity factors (ISF) for the duration of the override.

A common mistake is to think selecting an override with 10% Overall Insulin Needs is like selecting 10% basal rate with a manual pump. With Loop, that selection modifies all your normal settings by a factor of 10!

"},{"location":"operation/features/overrides/#manual-temp-basal","title":"Manual Temp Basal","text":"

Sometimes you need to set a manual temp basal and you need it to keep working whether you are near your gear. There's a function for that with Loop 3.

  • Pods: use the Manual Temp Basal setting
  • Medtronic: select Open Loop and use your Medtronic pump temp basal feature
"},{"location":"operation/features/overrides/#how-overrides-work","title":"How Overrides Work","text":"

Overrides let Loop know selected settings are modified for the duration of the override. The override can change either the correction range or the overall insulin needs or both. When you set an override on insulin needs, the override adjusts basal schedule, ISF, and CR together. Examples where this can be helpful include hormone cycles, steroid medications, and/or exercise.

Override presets are (1) optional and (2) can be configured within Loop's workout icon (the little blue heart icon in the Loop toolbar). Once override presets are created, they can be turned on/off by using the workout icon as well.

"},{"location":"operation/features/overrides/#features-of-an-override","title":"Features of an Override","text":"

Overrides allow you to specify:

  • an overall insulin needs adjustment
  • a correction target range
  • a duration in 15-minute increments (or indefinite)
  • a start time

The override only works when your Loop gear is with you. For example, if Loop sets a zero temporary basal rate based on an override and then you leave your gear behind; at the end of half an hour, your pump will resume scheduled insulin delivery.

The target range replaces the correction range target for the duration of the override.

  • If the target range is left blank, your scheduled correction range continues to be in effect
  • If the target range is specified, that range is used instead of your scheduled correction range

The overall insulin needs is applied to your basal rates, insulin sensitivities and carb ratios for the duration of the override.

  • If the insulin needs is left at 100%, no change is made to basal rates, ISF or CR
  • If you set an overall insulin needs adjustment below 100%, you are telling Loop you are more insulin sensitive and need a lighter touch.
    • Loop uses basal rates decreased from scheduled rates
    • Loop uses ISF and CR numbers increased from settings
  • If you set an overall insulin needs adjustment above 100%, you are telling Loop you are less insulin sensitive and need a heavier touch.
    • Loop uses basal rates increased from scheduled rates
    • Loop uses ISF and CR numbers decreased from settings
  • While the override is active, the modified basal rates, ISF and CR are applied for every automated or manual insulin delivery and affect the calculation for future IOB while the override is active
    • Those ISF and CR numbers are associated with the carbs and/or insulin delivered during the override
    • As the carbs and/or insulin \"ages\" during their absorption-time/duration-of-action, Loop maintains the sensitivity values associated with those during-the-override entries

For an override to be accepted:

  • You must change either insulin needs or target range
  • A named override can be saved and used again
    • To save the override, you must supply a name and an icon
    • Named overrides can be set to occur at a scheduled time
  • A Custom override is used only once
  • Any override can be edited while it is active
"},{"location":"operation/features/overrides/#future-override","title":"Future Override","text":"

When an override is scheduled to start in the future, it can have an effect earlier than you might think. The closed loop automated insulin increase or restriction at each cycle is calculated to map your predicted glucose to the desired target range over the duration of insulin action (6 hours). If the future override has a higher target, that higher target is factored into the Loop calculations.

Example:

  • At 10 pm, you set an override with a higher correction range target to start the following morning at 6 am
  • At approximately midnight, Loop will begin taking that future target into account in the dosing for each Loop cycle
  • By the time you awaken at 6 am, Loop should have your glucose in that higher target range
  • The insulin needs modification, if any, associated with that override do not affect the Loop prediction until the scheduled start time for the override
"},{"location":"operation/features/overrides/#how-overrides-do-not-work","title":"How Overrides Do NOT Work","text":"

Overrides will work while you are Looping. Sounds obvious, right? But, the thing to remember is that the adjustments (multipliers) that overrides make are not saved back to your Medtronic pump or Omnipod. They only exist in the Loop app.

If you walk away from iPhone and/or RileyLink...

If you stop Looping (i.e., walk away from your gear or your glucose reading is stale), your existing temp basal will complete the remainder of whatever is left of its original 30 minutes and you will return to scheduled basal rates in your Therapy Settings. Your adjusted needs as set-up in any override will not continue if your Loop is not running properly. So you cannot set a 50% override and then hop in the ocean for a 2-mile swim without your iPhone and RileyLink and expect decreased basals of 50%. Just be aware that in situations where you need prolonged lower basals while away from Looping gear, you will need to edit your scheduled basals or use a Manual Temp Basal setting.

"},{"location":"operation/features/overrides/#avoid-extreme-insulin-needs-setting","title":"Avoid Extreme Insulin Needs Setting","text":"

There have been users who select a 10% overall insulin need. This is NOT the same as choosing a 10% temporary basal with the PDM. This changes your basal rates, ISF and CR by a factor of 10!

Scenario for 10% Insulin Need

  • User really wants insulin reduced and chooses 10% insulin need
  • User doesn't think about the 10% and enters carbs while the override is active
    • Loop suggests a tiny bolus and the user accepts
      • User goes high because CR was 10 times higher than Therapy Setting Value
      • User stays high because ISF is also 10 times higher than Therapy Setting Value
        • Automated corrections are 10% of typical corrections
        • Basal supplied is 10% of the Therapy Setting value
    • OR
    • Loop suggests a tiny bolus and the user manually boluses the amount they know the food needs
      • User glucose may be normal BUT
        • Loop predicts a negative eventual glucose (prediction only - this will never happen)
        • Loop immediately withholds all basal until prediction normalizes

Instead of selecting 10%, raise your correction range with a moderate needs adjustment. Loop tends to suspend insulin delivery via temp basals with the next CGM reading.

With Loop 3, there is now a warning message in the meal entry screen when an override is active with an overall insulin needs value other than 100%. The user can decide whether to proceed with the meal entry with the override active.

If you feel the need to immediately halt insulin delivery, consider a Manual Temp Basal or suspend command to the pump. If you choose to suspend, be sure to pay attention to the reminder to resume insulin delivery later.

Extreme Athletes

There are athletes who do need those extreme overall insulin need changes and know how to use them appropriately. This typically involves extreme or prolonged exercise.

"},{"location":"operation/features/overrides/#create-an-override-preset","title":"Create an Override Preset","text":"

To create an override preset, tap on the workout icon. Then click the + sign in the upper right corner to start a new preset entry.

You must select an emoji, name the preset and modify either the overall insulin needs or target range or both to save your new preset

  • Pick an emoji
  • Enter a name for the preset
  • Optional: change insulin needs
    • Default is 100% - no change to your settings
    • You may use the picker wheel or Select 1% Insulin Needs increments
  • Optional: enter a target range
    • If you do not enter a target range, Loop will use your existing scheduled target range
  • Select whether you want the override to run indefinitely or for a finite time

When you've made your selections, save the preset using the \"Save\" button in the upper right corner.

"},{"location":"operation/features/overrides/#select-1-insulin-needs","title":"Select 1% Insulin Needs","text":"

Available with Loop 3.

The selectable Overall Insulin Needs values are not limited by the default picker values of 10%.

  • When adjusting Needs, press and hold the \"orange\" bar, highlighted by the red rectangle in the graphic below
  • Move your finger left and right to adjust by 1%
  • Release to select the desired level

"},{"location":"operation/features/overrides/#activate-an-override","title":"Activate an Override","text":"

To enact your override preset, tap on the workout icon toolbar and select an override from your list of saved presets, create a new one or use the custom override for one-time use.

The heart will be highlighted in a blue square while active and the HUD Status Row will indicate the active override name. The Glucose Chart will show a darker blue bar indicating the active target range and duration.

"},{"location":"operation/features/overrides/#schedule-an-override","title":"Schedule an Override","text":"

You can set up a future start time when selecting a saved override by tapping on the calendar icon to the right of the override. Adjust the \"Start time\" row. Tap the \"Enable\" button in the top right corner.

A Future Override can be very helpful, for example, to set an exercise override the night before your workout. You'll wake up with less insulin on board and at your desired exercise targets.

"},{"location":"operation/features/overrides/#deactivating-an-override","title":"Deactivating an Override","text":"

Tap the heart icon to turn off your override at any time. This happens without confirmation, so be sure to lock your phone when you have an override running to avoid accidentally turning it off.

Override presets with a finite duration will automatically deactivate when the duration is over.

"},{"location":"operation/features/overrides/#apple-watch","title":"Apple Watch","text":"

Saved overrides can be turned on and off by tapping on the blue heart icon on your watch.

"},{"location":"operation/features/overrides/#editing-an-active-override","title":"Editing an Active Override","text":"

Tap on the active override in the HUD Status Row with the phone in portrait orientation. This brings up a screen to edit the override currently running.

This only affects this override during the current period. It is not saved to that named override. For example, you can extend the duration or modify the needs value or target value based on a temporary situation.

Higher Priority Messages

If the HUD Status Row is displaying a higher priority message, you must wait for that message to complete before you'll be able to edit an active override. If you want to edit an active override, you can choose to cancel an active bolus and edit the override immediately. The edited override will then be in effect for the next Loop cycle or manual recommendation.

HUD Status Row messages with higher priority:

  • Bolus starting, in-progress or canceling
  • Pump suspended
  • No recent glucose
"},{"location":"operation/features/overrides/#remote-overrides","title":"Remote Overrides","text":"

You can also use your Nightscout site to activate/deactivate your Loop's override presets. To accomplish this, you will need to do some legwork as outlined on this page for how to set up Remote Overrides in Nightscout and you will need to be using a paid Apple developer account. Remote overrides require Apple Push Notifications service, and that is only available on paid accounts.

"},{"location":"operation/features/premeal/","title":"Pre-Meal Target","text":""},{"location":"operation/features/premeal/#pre-meal-range","title":"Pre-Meal Range","text":"

The Loop toolbar's second icon from the left is a small clock with a knife and fork on the sides. This is the pre-meal tool. The tool will be colored grey until you define a glucose range in Loop settings. Once a pre-meal range is available in Loop Settings, the icon will be colored green and available for use. The background coloring of the Pre-Meal Range icon will turn green when active and there will be a dark blue line on the glucose chart indicating the pre-meal range.

The pre-meal range can be used as an easy way to get a small amount of insulin delivered before a meal in order to help control post-meal blood glucose spikes. It's not designed to replace a traditional pre-bolus, but rather as a more gentle way to build up some pre-meal insulin activity.

If your normal target is 100-110 mg/dL and pre-meal range is 80-80 mg/dL, for example, Loop will give you an extra push to get you to the lower target 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 icon, will stay active for one hour, until carbs are entered, or until it is manually canceled... whichever comes first. Setting an override will also cancel pre-meal range.

Loop will adjust any insulin bolus as needed based on the extra insulin provided during this pre-meal time.

Other Uses

Some people prefer to use this as an easy way to raise the correction range for an hour.

"},{"location":"operation/features/premeal/#how-to-adjust-pre-meal-range","title":"How to Adjust Pre-Meal Range","text":"

Loop 3:

  • In Loop Settings, select Therapy Settings and then tap on Pre-Meal Range to adjust
  • If you prefer not to have that icon active on the Toolbar, you can tap Delete in the upper right corner of the adjustment screen

Loop 2.2.x:

  • In Loop settings, find the Correction Range section. The Correction Range sections stores all targets for Loop over the hours of the day, including Pre-Meal.
"},{"location":"operation/features/premeal/#assessing-the-impact-of-pre-meal","title":"Assessing the impact of pre-meal","text":"

The intent of the pre-meal icon on the toolbar is to provide an eating-soon mode in Loop. Do not set pre-meal limits to any hypoglycemic ranges that may require treatment.

To mitigate the impact of unintentional pre-meal activation:

  • If you are running Loop 3, you can delete the setting to deactivate the icon
  • If you are running Loop 2.2.x, you can set the pre-meal range to the same value as your usual correction range

Custom Pre-Meal Overrides

Some loopers set up a custom override to use instead of the pre-meal icon. This allows enabling the override remotely with Nightscout, permits specifying a custom duration, and will keep the override enabled after carbs are announced.

"},{"location":"operation/features/watch/","title":"Apple Watch","text":""},{"location":"operation/features/watch/#loop-with-apple-watch","title":"Loop with Apple Watch","text":"

The Loop user can directly enter carbs and boluses and turn on or off premeal or override settings from the watch, without needing to pull their iPhone out. There are some caveats when iPhone is not within Bluetooth range - the action requested by the watch will not be enacted until iPhone reconnects.

There are two screens in the Loop watch app, shown in the bottom half of the graphic above. By swiping left or right, the other screen is displayed. The eventual (predicted) glucose feature, shown on both screens in the graphic can be turned off as a feature in Loop 3, but requires the user to rebuild. It is on by default.

The screen on the left side of the graphic shows Loop status, current glucose, trend arrow and eventual glucose with icons to enable carb entry, bolus entry, pre-meal and override selection. If necessary, use the crown (or swipe up and down) to see the full display.

"},{"location":"operation/features/watch/#watch-carb-bolus-overview","title":"Watch Carb / Bolus Overview","text":"

After tapping on the carb or bolus icons, you can adjust the entries using the crown to dial in more/less. See Meal Entry on Watch for more details.

  • The watch carb entry screen allows you to choose the amount and absorption time, using the standard icons, and adjust the time the carbs were or are planned to be consumed. After tapping continue on the carb screen, the meal bolus screen is displayed - carbs are only saved after selecting Save or Save & Bolus on the meal bolus screen.
  • The watch bolus screen displays the recommended bolus. If you want to decrease/increase from the recommended amount, use the digital crown or tap on +/- icons to modify.
  • Once the bolus button is tapped, the bolus command is only delivered after using the digital crown to Spin for Watch Bolus to align the two triangles.
  • If you tap Save & Bolus on the bolus screen when entered from the carb screen AND then fail to turn the digital crown to confirm the bolus or hit Cancel, that means the bolus was not delivered and the carbs might not saved - but check to be sure.
"},{"location":"operation/features/watch/#watch-graph-and-status","title":"Watch Graph and Status","text":"

If you swipe the Apple Watch Loop screen from right-to-left, a second screen, as displayed on the right side of the graphic above, is available. This second screen displays a graph of recent glucose and predicted glucose data. The display can be scrolled with a finger swipe or turn of the crown to display Active Insulin, Active Carbs, Net Basal Rate (with respect to scheduled rate) and in some cases Reservoir Units. (A recently changed pod may show the reservoir level from the prior pod - just ignore that. It goes away within 24 hours.)

  • Check the Recent Carbs List on Watch by tapping the Active Carbs row:
    • If a desired carb entry added by the watch is not present on the watch display, you are safe to try again
    • If the carb entry is present on the watch display, do not enter it again
    • If your phone is not in range of your watch, carbs entered on the watch will be added to the phone carb storage when you reconnect
"},{"location":"operation/features/watch/#watch-graph-windows","title":"Watch Graph Windows","text":"

The windows for history and prediction available on the watch can be modified to suit your preference. The windows can be modified from 2 hours to 12 hours.

  • Double tap on the graph to increase the windows
  • Single tap on the graph to decrease the windows

The selection for the window remains as selected until you change it.

"},{"location":"operation/features/watch/#loop-complication","title":"Loop Complication","text":"

A loop complication exists to show glucose on the watch face but the update rate is limited by Apple. If you have a Loop complication installed in the watch face, you can simply tap the complication to open the Loop watch app.

In some positions and with some watch faces, the complication includes a graph.

  • The windows for the Loop Complication history and prediction are fixed (not modified when you change the Watch Graph Windows)
"},{"location":"operation/features/watch/#loop-watch-features","title":"Loop Watch Features","text":""},{"location":"operation/features/watch/#spin-for-watch-bolus","title":"Spin for Watch Bolus","text":"

To prevent an accidental bolus from your Watch app, don't let your kids hold your watch. Just kidding, we've added an even better solution. After requesting a bolus or accepting a meal entry recommended bolus, the watch face displays a graphic like the one below. As you spin the digital crown, the two triangles will begin to merge. Once they merge, the bolus is confirmed through a little haptic and a white checkmark will appear on the watch screen.

"},{"location":"operation/features/watch/#bolus-cancel-or-spin-fail","title":"Bolus Cancel or Spin Fail","text":"

At this point if you hit cancel, or fail to merge the two triangles, the bolus will not be delivered. You will feel a haptic and may hear a notification when Loop stops waiting. The watch display restores to the nominal screen.

"},{"location":"operation/features/watch/#meal-entry-on-watch","title":"Meal Entry on Watch","text":"

Tap on the Meal entry icon on the watch to view the watch carb entry screen as show in the graphic below.

The watch carb entry screen allows you to choose the amount and absorption time, using the standard icons, and adjust the time the carbs were or are planned to be consumed.

  • While the Amount is highlighted, the + and - buttons add or subtract 5 g of carbs from the amount, or you can use the digital crown to adjust the amount
  • Tap on the time and the + and - buttons add or subtract 15 minutes from the time when the meal was or will be consumed, or you can use the digital crown to adjust the time
  • The default absorption time is 3 hours (taco), but the fast (30 minute, lollipop) or slow (5 hour, pizza) can be selected

After tapping the Continue button on the carb screen, the meal bolus screen is displayed - carbs are only saved after selecting Save or Save & Bolus on the meal bolus screen.

"},{"location":"operation/features/watch/#carb-entry-no-bolus","title":"Carb Entry, No Bolus","text":"

If you enter carbs from the watch and no bolus is recommended or selected, you will see a screen like the graphic below where the Save button is offered. You can choose to Save the carbs, or cancel the entry.

If you choose to modify the zero bolus recommendation, the display changes to the option shown in the graphic in the following section.

If your phone is in communication with your watch, then when you hit the Save button, the carbs will be immediately saved to your phone record as well as your watch.

If your phone is not in range of your watch, then when they are brought into communication later, the carbs will appear on the phone.

"},{"location":"operation/features/watch/#carb-entry-with-bolus","title":"Carb Entry, With Bolus","text":"

If you enter carbs from the watch and a bolus is recommended or selected, you will see a screen like the graphic below where the Save & Bolus button is offered.

You may choose to leave that bolus at the recommended level, tap on the + or - buttons to add or subtract 0.5 U per tap or use the digital crown to adjust the value. Should the value go to zero, then the Save button appears as shown in the graphic in the previous section; but remember, Loop will begin adjusting automatic insulin delivery based on those newly entered carbs, even if you choose not to bolus.

  • If your phone is in communication with your watch

    • When you hit the Save & Bolus button, the carbs will be immediately saved to your phone record as well as your watch
    • Your pump will be commanded to deliver the indicated dose (from your phone)
      • If the pump communication succeeds, the delivery begins
      • If the pump communication fails, the bolus not delivered message will apear on the phone
      • You might want to have confirmation beeps enabled so you can hear if the pump bolus starts

  • If your phone is not in range of your watch

    • The carbs are saved in the watch carb storage
    • When the watch reconnects with the phone, the carbs are added to the phone carb storage
    • The bolus not delivered message will appear on the phone
"},{"location":"operation/features/watch/#recent-carbs-list-on-watch","title":"Recent Carbs List on Watch","text":"

You can review the recent carb entries on the Apple Watch. Simply swipe left to see the blood glucose graph screen on the watch. Scroll down with your finger or the digital crown to the Active Carbs row beneath the graph, and tap that row. You can see the list of recent carb entries.

If you enter carbs on your watch while not connected to the phone, they will appear on this display and, when the phone reconnects, will be transferred to the phone.

Be Cautious - Avoid Double Entry

If the phone and watch are not connected, someone could add entries to the phone manually or via remote commanding and the watch will not know about them. So be careful and check the phone carb record when the phone and watch reconnect. This is especially important if more than one caregiver is involved.

"},{"location":"operation/features/watch/#eventual-glucose-on-watch","title":"Eventual Glucose on Watch","text":"

One feature on the Watch app that can be turned on and off with Loop 3 is the eventual glucose display on the watch. That display is shown on the graphic above with current glucose on left, trend arrow beside it and eventual (from prediction) glucose on the right.

If this is a feature you want turned off, please follow the directions on the Code Customization page (found under the Version tab): Build Time Features.

"},{"location":"operation/features/watch/#adding-a-watch-to-existing-loop","title":"Adding a Watch to Existing Loop","text":"

If you add an Apple Watch after building Loop using Xcode on a computer, you will need to pair your watch to your iPhone and then rebuild Loop to enable the Loop watch app to show up as an available watch app.

If you use the new, Loop 3 only, Build Loop using GitHub Actions process that enables building without needing a Mac, the watch app should work so long as you have the watch paired to your phone when you install from TestFlight.

"},{"location":"operation/features/watch/#watch-hardware-and-os-requirements","title":"Watch Hardware and OS Requirements","text":"

Loop 2.2.9 and FreeAPS is currently supported with all released versions of the Apple Watch and Apple watchOS 4.1 and newer.

Loop 3 requires newer versions of the watch and requires watchOS 8 as a minimum.

The compatibility list below is copied from Apple. Note that some version of iOS require specific versions of watchOS. That level of detail is not captured here. Please review LoopDocs: Wikipedia Chart for Apple Versions.

"},{"location":"operation/features/watch/#watchos-8-compatibility","title":"watchOS 8 Compatibility:","text":"

watchOS 8 requires iPhone 6s or later with iOS 15 or later and one of the following Apple Watch models:

  • Apple Watch Series 3.
  • Apple Watch Series 4.
  • Apple Watch Series 5.
  • Apple Watch SE.
  • Apple Watch Series 6.
  • Apple Watch Series 7.
  • Not all features are available on all devices.
"},{"location":"operation/features/watch/#watchos-9-compatibility","title":"watchOS 9 Compatibility:","text":"

watchOS 9 requires iPhone 8 or later with iOS 16 or later and one of the following Apple Watch models:

  • Apple Watch Series 5.
  • Apple Watch SE.
  • Apple Watch Series 6.
  • Apple Watch Series 7.
  • Apple Watch Series 8.
  • Apple Watch Ultra.
"},{"location":"operation/features/widget/","title":"iPhone Widget","text":""},{"location":"operation/features/widget/#loop-3","title":"Loop 3","text":"

Loop 3 uses the new-style widget is in process. There are a lot of updates with widgets. With the advent of iOS 16, you can add widgets that show up on the lock screen without need to swipe to view. There is work in progress on this - please be patient.

"},{"location":"operation/features/widget/#old-style-loop-widget","title":"Old-Style Loop Widget","text":"

Loop 2.2.x and FreeAPS both include an old-style widget.

With older versions of iOS, the widget is available in the Today view of your iPhone. Swipe right on your iPhone home screen and your widgets will be available. The Loop widget may be at the bottom of your widget list. Scroll down to the bottom of the screen and press the edit button. That opens an \"Add Widgets\" screen. If you hold and drag the three horizontal lines on the Loop widget row, you can drag it up to the order you'd like it to appear on your widget list.

With newer version of iOS, the old-style widgets cannot be moved to the top of the screen. The example graphic below shows the new-style Dexcom G6 widget above the old-style Loop 3 widget.

New to Loop or never added a widget before

  • There is a difference in behavior between \"new-style\" Widgets and \"old-style\" Widgets
    • New-Style Widgets: always appear at the top of your Today View, can be changed by long-pressing on one and then dragging around, or can be added with the + button in edit mode
    • Old-Style Widgets, like that available with Loop: use a different method to install
  • Make sure your phone is unlocked, then swipe from the Home Screen to get to Today View
    • You can't edit the screen if you start from a locked phone
  • Start the Edit mode (where all of the icons are shaking), either by long-pressing on one of the new-style widgets, or by scrolling all the way to the bottom of Today View and pressing Edit.
  • Scroll all the way to the bottom again to find and select the button labeled \"Customize\"
  • Now you can configure (add, remove, rearrange) the \"old-style\" widgets for your screen.
  • The Loop widget should appear in the list available there.

Experienced Looper who already had a widget should not need to modify anything to see it.

"},{"location":"operation/loop/close-loop/","title":"Closed Loop","text":""},{"location":"operation/loop/close-loop/#closed-loop","title":"Closed-Loop","text":"

After you learn what you need from open-loop, this page provides suggestions to smooth the transition to closed loop.

"},{"location":"operation/loop/close-loop/#timing","title":"Timing","text":"

Consider transitioning in steps. Some loopers start closed-loop when there are fewer distractions, possibly on weekends. It can be easier to transition at a time that does not involve food, possibly overnight.

"},{"location":"operation/loop/close-loop/#maximum-basal-rate","title":"Maximum Basal Rate","text":"

When starting closed-loop, it is important to be conservative. Start with the \"Temp Basal Only\" dosing strategy and limit the maximum basal rate. If your Meal Entries or Therapy Settings (basal rates, CR, ISF) are incorrect, this approach limits the risk of getting too much insulin. Typically, experienced loopers set their max closed-loop basal rate at no more than 3-4 times their average basal rate. Wait until you are comfortable with the slower corrections in \"Temp Basal Only\" before transitioning to \"Automatic Bolus\".

Temp Basal Only vs Automatic Bolus

Both Dosing Strategy methods update the prediction with each CGM or glucose reading, typically every 5 minutes, and use the updated prediction to generate a recommended bolus or recommended dosing restriction.

  • \"Temp Basal Only\" provides no more than 17% (per 5 minute interval) of that recommended bolus using temporary basal
  • \"Automatic Bolus\" mode provides 40% of that recommended bolus as an immediate bolus
  • When Loop recommends restricting insulin, both methods use temporary basals that are less than the scheduled basal, often commanding a temp basal of 0 U/hr
"},{"location":"operation/loop/close-loop/#glucose-correction-range","title":"Glucose Correction Range","text":"

If your basal, ISF, or carb ratios are not correct, Loop may give you more insulin than you need to reach the correction you selected. Setting the correction range slightly higher at first helps prevent unexpected low glucose as you adjust your settings.

"},{"location":"operation/loop/close-loop/#watch-the-iob","title":"Watch the IOB","text":"

Watch whether Loop accumulates positive or negative IOB while holding your glucose steady when no food is present. If you consistently have positive or negative IOB, review whether to adjust your basal rate or ISF.

Expert Tip

In the absence of food, glucose trends should flatten out when positive or negative IOB trends to zero.

  • If glucose drops below the correction range and continues to drop while IOB goes negative, basal rates may be too high
  • If glucose remains above the correction range while IOB remains positive, basal rates may be too low

The ISF is also important, but basal should be evaluated first.

"},{"location":"operation/loop/close-loop/#meals","title":"Meals","text":"

Start with meals that you know well. If Loop suggests less or more insulin than expected as a bolus before the meal - consider why this may be true.

  • If glucose is trending down, Loop may be trying to prevent a low glucose event
  • If glucose is trending up, Loop may be trying to add a correction to the meal dose
  • In any case:
    • You can adjust the absorption time and carb amount to see if that modifies the suggested bolus
    • You can override the Loop suggestion
    • Do not be surprised if Loop immediately suspends basal
    • Loop needs to see glucose start to rise before deciding you need more insulin after the initial meal bolus recommendation
    • Loop will not automatically provide more insulin until your glucose is above the lower range of the correction range (but will recommend a manual bolus)

This is definitely an area where YDMV (your diabetes may vary), so don't expect or accept that what works for others will work for you. Test, observe, and adjust as needed.

"},{"location":"operation/loop/close-loop/#automated-dosing","title":"Automated Dosing","text":"

Loop calculates a predicted glucose curve based on your programmed settings for carb ratio (CR) and insulin sensitivity factor (ISF), using your glucose, insulin and carb history.

Two scenarios are given below to help illustrate the closed-loop automatic actions of Loop. A more typical scenario is to enter carbs and then use Loop's recommendation for an appropriate bolus.

  1. Enter a bolus with no carb entry
  2. Enter a carb entry without a bolus
"},{"location":"operation/loop/close-loop/#bolus-with-no-carbs","title":"Bolus with No Carbs","text":"

If you enter a bolus without entering carbs, the prediction will be for your glucose to go low. (The Loop model calculates a negative number for recommended bolus.) For this case, Loop issues a Temp Basal to prevent the low, typically 0.0 U/hr but always less than your scheduled basal rate.

COB and IOB

  • COB is the carbohydrates (g) that Loop expects to be absorbed
  • IOB is the current active insulin (above or below the scheduled basal rate)
"},{"location":"operation/loop/close-loop/#carbs-with-no-bolus","title":"Carbs with No Bolus","text":"

If you enter carbs and select Save without bolusing, you have COB without associated IOB. In that case, Loop predicts your glucose will start rising and updates the recommended bolus, which includes consideration of your Glucose Safety Limit, Correction Range and Maximum Bolus . If that recommended bolus is positive, Loop might deliver some part of that bolus automatically - the exact percentage and timing of that delivery depends on your Dosing Strategy. At each loop cycle (new glucose reading), Loop updates the prediction and calculates a new recommended bolus. When you enter carbs without bolusing, Loop may start delivering some insulin, but if your glucose doesn't start rising as Loop expects, it revises the recommended bolus with each new glucose value.

"},{"location":"operation/loop/close-loop/#when-does-automatic-dosing-happen","title":"When does Automatic Dosing Happen","text":"

Automatic dosing only happens when Closed Loop is enabled in the settings screen.

The Loop app generates a glucose prediction over the next 6 hours (the duration of insulin action), which is why the predicted glucose plot is included on the bolus screen. The Loop app considers glucose prediction with respect to your scheduled Correction Range over the full DIA, weighting closer predictions more than later predictions, when calculating Recommended Bolus.

It is actually easier to answer when Loop will not automatically increase insulin delivery.

In the situations listed below, the prediction at the end of the DIA can be significantly higher than your Correction Range but no automatic increase in insulin delivery will occur:

  • If at any time in the next 3 hours, the Loop app predicts glucose below Glucose Safety Limit, Temp Basal is immediately set to 0.0 U/hr and recommended bolus is set 0 U
  • If the prediction dips below the low-end of your Correction Range, there is no automatic increase over scheduled basal
  • If the current glucose is less than the low-end of your Correction Range, there is no automatic increase over scheduled basal
  • If the current IOB is greater than or equal to two times the Maximum Bolus setting, there is no automatic increase over scheduled basal

Even in cases where Loop does not automatically increase insulin delivery, the recommended bolus might be positive, which you see if you tap on the bolus icon manually.

"},{"location":"operation/loop/looptips/","title":"Loop Tips","text":""},{"location":"operation/loop/looptips/#loop-tips","title":"Loop Tips","text":"

These docs are a great resource for the technical aspects of building your Loop app. However, they don't really cover in detail a lot of the frequently asked questions about USING Loop.

Things such as:

  • How to enter low treatments while using Loop?
  • What to discuss with your Endo?
  • What data reports might be useful?
  • How to deal with failed sites?
  • What about pizza boluses?
  • What do I do when I shower or swim?

All of those usability questions and more are addressed over in the companion site called LoopTips.

Please head over to Looptips in order to read some really helpful tips to make your Looping easier.

"},{"location":"operation/loop/open-loop/","title":"Open Loop","text":""},{"location":"operation/loop/open-loop/#open-loop-introduction","title":"Open Loop Introduction","text":"

Open Loop is the best place to start with Loop.

  • Become familiar with the Loop app by watching it operate with Closed Loop disabled.
  • Take it slow and safe to become a successful Looper.
Menus do not include all Manual Pump Features (Click to learn more)

The Loop app is built around the concept of Closed Loop performance.

If you use a Medtronic pump and want to use a feature not found in the Loop app, simply disable Closed Loop and control delivery with your Medtronic Controller.

If you use an Omnipod pump, keep reading:

There may be a feature, like extended bolus, that you used with an Omnipod Personal Device Manager (PDM) that is not in the Loop app.

Please refer to Extended Bolus.

Practice with Simulators (Click to learn more)

You can build the Loop app without connecting it to any hardware.

  • You can use your phone, a partner's phone or a simulated phone on the computer
  • You can practice with a simulated CGM and / or a simulated pump.
  • You can use Dexcom Share or Nightscout as a CGM to follow your own glucose.
  • You can \"dose\" the simulated pump and your real pump at the same time and watch the glucose predictions.
"},{"location":"operation/loop/open-loop/#glucose-prediction","title":"Glucose Prediction","text":"

Pay attention to the prediction in the Glucose Chart. Practice with the user interface while you manually control your insulin delivery. Compare the recommended insulin after entering carbs for a familiar meal. Be sure you understand the predictions and recommendations before you enable Closed Loop. You may need to adjust settings or learn more about how the app works. The Loop app tries to keep predicted glucose in the Correction Range and, more importantly, above your Glucose Safety Limit.

There's a lot to learn and understand. New loopers may need to adjust the following Therapy Settings, typically in this order:

  1. Basal Rates
  2. Insulin Sensitivity Factor (ISF)
  3. Carb Ratios (CR)

Using an algorithm that updates glucose predictions and adjusts insulin delivery every 5 minutes requires accurate settings. Entering carbs and absorption time is a new skill that takes time to master.

"},{"location":"operation/loop/open-loop/#eventual-glucose","title":"Eventual Glucose","text":"

Watch the eventual glucose, current glucose and prediction curve in the Glucose Chart to understand recommendations for insulin delivery adjustment. The Loop app is looking at current glucose, glucose momentum, carbs on board, insulin on board, and retrospective trends to predict an eventual glucose. Its current decisions are based on actual, predicted and eventual glucose. Predictions for the first three hours of insulin duration of activity are given more emphasis than later predictions when deciding how much insulin should be recommended or withheld from basal.

If there is a dip in the predicted glucose below the Glucose Safety Limit, the Loop app will not recommend insulin even if the eventual glucose is above your Correction Range.

  • In Closed Loop mode, the Loop app automatically decreases insulin delivery using a temp basal of 0 U/hr until the predicted glucose exceeds the Glucose Safety Limit
  • When you tap on the Bolus icon in the Toolbar, the Loop app recommends insulin delivery only after predicted glucose is above Glucose Safety Limit
  • In Closed Loop mode, the Loop app automatically increases insulin delivery only after predicted glucose is above the bottom of the Correction Range

If the Loop predictions don't match your experience, your settings may need to be adjusted.

If you want to issue a manual temp basal, this is done on the pump for Medtronic or using the Manual Temp Basal feature for Omnipod.

"},{"location":"operation/loop/open-loop/#testing","title":"Testing","text":"

Open Loop mode shows you glucose trends without the influence of temporary basal or automatic bolus. This is particularly helpful if you haven't used Medtronic sites/pumps or Omnipod before. You may find that your basal rates and carb ratios can change significantly coming from other brands of pumps or from multiple daily injections (MDI).

The suggestions below work for most people. You need to adjust for your own situation.

Take the time to establish a good basal profile while in Open Loop mode using the pump you plan to use for the Loop app. When using an algorithm, your basal rates needs to be neutral; in other words your glucose, in the absence of food and exercise, should be stable. (When you do basal testing, you should aim to stay at a glucose that is steady within 35 mg/dL (2 mmol/L).)

If you previously ran a high basal rate during the day to cover meals, you may need to adjust your CR (to a smaller value) after your basal rate is adjusted to be neutral.

Test your insulin sensitivity factor (ISF) during Open Loop after your basal rates are established. The Loop app uses your ISF every 5 minutes to update predictions, so it's worth testing before turning on automated insulin dosing with Closed Loop mode. You may need a different, probably higher value, than what you used as a correction factor with manual pumping or MDI.

The algorithm uses the ratio of ISF/CR as part of the prediction while meals are being absorbed. That ratio is approximately how much a single gram of carbohydrate raises your glucose. Experiment by taking a small fast-acting \"low treatment\" when stable with no other food or exercise.

Assume ISF is 75 mg/dL and CR is 15 g/U. When a 4 g glucose tablet is consumed, you expect to see a sharp rise in glucose by about 20 mg/dL over the next half hour to an hour. (Your ISF/CR ratio times the grams eaten should be within a factor of two of how much rise you see in glucose.)

"},{"location":"operation/loop/open-loop/#meal-entry","title":"Meal Entry","text":"

Loop recommends increased insulin dosing as soon as you save carbs.

Meal Entry is an important concept - there's a whole page devoted to it later in the docs - but here's a quick summary. You tap on the plate icon in the Toolbar before you meal to show the Add Carb Entry screen.

  • In the Add Carb Entry screen, you must enter Amount Consumed, defaults are ok for other rows
  • The meal entry is not saved when you tap continue - the Loop app takes you to the Meal Bolus screen
  • In the Meal Bolus screen, you can save the carbs and accept or override the recommended bolus
  • Review the recommended bolus for the meal entry
    • Does the recommendation make sense based on your prior experience
    • Pay attention to the glucose prediction chart embedded in the Meal Bolus tool
    • Practice modifying when the carbs are expected and how long they are expected to last
    • Practice modifying the bolus recommendation - note how the prediction changes
    • When you are confident, you can save the carbs and deliver the bolus
"},{"location":"operation/loop/open-loop/#carb-absorption","title":"Carb Absorption","text":"

Loop uses carb absorption as a component to every meal entry. Most people are successful with the default absorption time of 3 hours. Remember the Loop app updates the prediction every 5 minutes and will adjust if you get the amount or absorption time wrong, as long as you are close.

  • For low-glucose treatment, you can enter using the 30-minute (lollipop) icon
  • For high-fat meals, you can try the 5-hour (pizza) icon

The Active Carbohydrate chart displays how the app thinks your meal is being aborbed. This is affected by your basal rates, ISF and CR. If it looks wrong, examine your settings.

Depending on the type of food you eat, you may increase the carb entry to include some protein or fat.

"},{"location":"operation/loop/open-loop/#manual-or-correction-bolus","title":"Manual (or Correction) Bolus","text":"

At any time, you can enter a bolus using the Bolus (double orange triangles) icon in the Toolbar. The Loop app offers a recommendation if the glucose prediction supports one. Review the Eventual Glucose section above to understand when the app will recommend a bolus. The Loop recommendation can be modified by editing the Bolus amount.

If you tap on the Bolus button (on the Toolbar), does the app recommend more insulin?

  • If so, you can choose to accept if it looks reasonable to you
  • If not, look at the prediction plot to understand the decision

Ask if this is the same decision you would make. This effort will help smooth the transition to Closed Loop.

"},{"location":"operation/loop/open-loop/#troubleshooting","title":"Troubleshooting","text":"

If you use a RileyLink, determine how far the link can be from your phone and pump, and plan where to carry the link. DASH Omnipod users do not need the RileyLink but should determine how far their phone can be from the pod without communication problems.

Learn to troubleshoot Red Loops and the cause of potential loop issues. You'll be less frustrated starting on closed loop if you know how to address these issues.

Familiarize yourself with the Bolus Failure Notifications.

"},{"location":"operation/loop/open-loop/#caregiver-training","title":"Caregiver training","text":"

Caregivers for Loopers should learn how to use the Loop app. School staff or your child need to know how to handle a site change or CGM failure at school. Consider preparing an individualized quick info sheet for your child.

Learn to observe the Nightscout site while your child is with you and you can look at their phone. This will help you help your child if they have problems when they are not with you.

For more reading, there's a whole set of pages on using Nightscout with the Loop app and setting up a secure method for you to provide bolus or carb entries via remote commands.

"},{"location":"operation/loop/open-loop/#apple-health-in-open-loop","title":"Apple Health in Open Loop","text":"

If you are using the Apple Health app to examine insulin given while in Open Loop, basal delivery is not recorded in the Health app promptly. You can force an update from the Loop app to Health by suspending and then resuming the pump. If you do this, keep watching the app to make sure delivery did resume.

"},{"location":"operation/loop/open-loop/#extended-bolus","title":"Extended Bolus","text":"

A menu item to set an extended bolus is not a feature provided by the Loop app at this time. You can make your own extended bolus using the Manual Temp Basal feature with Omnipod.

During the time the Manual Temp Basal command is running, the Loop app will make no automated changes to dosing even if the Closed Loop slider is selected as enabled.

"},{"location":"operation/loop/open-loop/#extended-bolus-equations","title":"Extended Bolus Equations","text":"

This section was added at user request. Once you switch to Closed Loop mode, you should not need this. But before you are ready for that step, you may want to use a tested method for a known meal.

Consider a desired total bolus \\((BolusTotal)\\) given over an extended time with a prompt amount \\((PromptAmount)\\) now and the balance \\((Balance)\\) delivered over the next \\((H)\\) hours with a current scheduled basal rate \\((BR)\\).

First the equations to calculate the desired rate \\((MTB)\\) to enter into the Manual Temp Basal menu and then an example.

\\[ Balance = BolusTotal - PromptAmount \\] \\[ MTB = Balance / H + BR \\]
  1. Turn on a Manual Temp Basal to value of \\(MTB\\) units/hour for \\(H\\) hours
  2. Tap the bolus icon on the main toolbar and enter a bolus for \\(PromptAmount\\) units

The order is important. Sending the Manual Temp Basal request to the pod is a single command and then the Loop app is available for the next command to be entered. The Loop app (and pod) will not respond to any pod commands until the bolus finishes delivering; this takes about 40 seconds per unit requested.

"},{"location":"operation/loop/open-loop/#specific-example","title":"Specific Example","text":"

For this example:

  • \\(BolusTotal\\) is 3 U
  • \\(PromptAmount\\) is 1 U
  • Time in hours, \\(H\\), is 1.5
  • Scheduled basal rate, \\(BR\\), is 0.5 U/hr
\\[ Balance = 3 U - 1 U = 2 U \\] \\[ MTB = (2 / 1.5) U/hr + 0.5 U/hr = 1.55 U/hr \\]

You have your choice of rounding \\(MTB\\) up or down to the nearest \\(0.05 U/hr\\). For this example, the quantity of \\((2/1.5)=1.333\\) was rounded up to \\(1.35 U/hr\\).

Why isn't there a menu item? (Click to see more)

Each item provided by the Loop app needs a volunteer to decide it is important and develop a method to provide that item. If a volunteer steps up to do this work, there is a long process of discussion and code review before such a modification is considered for the development branch.

Most Loopers go to Closed Loop quickly and this feature is not an option at this time.

"},{"location":"operation/loop-settings/cgm/","title":"Loop 2 Add CGM","text":""},{"location":"operation/loop-settings/cgm/#add-cgm","title":"Add CGM","text":"

Now we need to add a CGM source so that Loop has glucose data. From the Loop settings screen, select Add CGM.

The standard selections are:

  • Dexcom G6 (use this for Dexcom ONE)
  • Dexcom G5
  • Dexcom G4
  • Dexcom Share

If you added a compatible Medtronic pump earlier in the setup process, then you will also see an option for the compatible Medtronic sensor that works with that same pump. If you are using a compatible MDT sensor, select that option and the CGM data will be uploaded to Loop when pump status is updated.

"},{"location":"operation/loop-settings/cgm/#about-dexcom-share-credentials","title":"About Dexcom Share credentials","text":"

You do NOT need your Share account info listed in Loop settings if you are using a G4, G5, or G6 system. The transmitter ID is sufficient. In fact, the recommendation is that you leave your Share account empty so that you don't accidentally become internet-dependent for CGM data when you forget to update your transmitter ID when you start a new transmitter. Just leave the Share credentials blank.

If you need to use Dexcom Share

If the dexcom is on another phone and you choose to use Share (not advised), here is some information.

For all selections, the Dexcom Share credentials (in other words, account login) is the same as what you used to log in to the active Dexcom app on your iPhone. Dexcom Share account is not always the same login info as your Dexcom Clarity account. For G4 users, the Share account is found in the account tab on the app. For G5/G6 users, unfortunately, there is no information in the app displaying what your account name is. The information is entered when you first log in to the app and then is never displayed again, nor visible under any information screens. If you have forgotten your G5/G6 account info, you can delete the Dexcom app and redownload it to try logging in again. This will not cause a restart of any sensor sessions in progress.

If you do not enter your Share credentials correctly, you will get an error when Loop tries to access your Share account to backfill CGM data. That error message will look like below. If you see that message, delete your Share account from Loop settings and try again...or just leave it out and depend on your transmitter ID.

"},{"location":"operation/loop-settings/cgm/#dexcom-g5-g6-one","title":"Dexcom G5, G6, ONE","text":"

The Dexcom G5 and G6 options only require the addition of the active transmitter ID, and the matching Dexcom app to be running on the Loop iPhone. Use the G6 options if you are using a Dexcom ONE CGM.

When you change transmitters, you will need to select the Delete CGM button at the very bottom of the CGM info page in Loop. Then you will select your Dexcom system again and add the new transmitter ID. You cannot just tap on your old transmitter ID to update it.

If you don't update your transmitter ID when you change active transmitters, your Loop will not get CGM data from the Dexcom app.

If you did add Share credential, Loop will get data from your Dexcom Share server and will not work without cell or wifi connection. When Loop is using data from Dexcom Share servers, a small cloud will appear above the glucose reading in Loop and should tip you off that maybe you forgot to update your transmitter ID.

"},{"location":"operation/loop-settings/cgm/#dexcom-g4","title":"Dexcom G4","text":"

Dexcom G4 users will need the Dexcom G4 Share2 app active on their iPhone and paired to their Dexcom G4 Share receiver.

"},{"location":"operation/loop-settings/cgm/#dexcom-share","title":"Dexcom Share","text":"

The Dexcom Share selection is primarily for people who wish to test Loop function without a local CGM source and who are not running the Dexcom app on their Loop iPhone. This selection will require login access to a Dexcom Share account with live data and active internet connection in order to work.

Dexcom Share is not available for Dexcom ONE CGM.

"},{"location":"operation/loop-settings/cgm/#libre-and-other-cgm","title":"Libre and Other CGM","text":"

Loop 2 does not natively support Libre CGM.

If you switch to Loop 3, there are additional CGM options:

  • If you choose to build Loop-dev, Libre support has been added.

  • If you can upload your CGM to Nightscout, Loop 3 offers the option to use Nightscout as a CGM source.

  • You can choose to download the Loop with patches option when building with the script.

    • As a prerequisite, you must interface your iPhone to the Libre
    • Please read Libre Support for Loop 3.2.x Code
"},{"location":"operation/loop-settings/cgm/#next-step-loop-2-configuration","title":"Next Step: Loop 2 Configuration","text":"

Now that you have added your CGM source, we need to complete the configuration and settings in your Loop. Please head over to the Loop 2 Configuration page for guidance with this important part of Loop's setup.

"},{"location":"operation/loop-settings/configurations/","title":"Loop 2 Configuration","text":""},{"location":"operation/loop-settings/configurations/#configuration","title":"Configuration","text":"

This page will cover two general parts of the Loop app settings for Loop 2.2.x versions. The sections documented are circled in red in the screenshot below. The headings will match the flow of the screen, top to bottom.

  • The first circled section covers closed/open loop status and how to issue a Loop Report.

  • The second circled section is the configuration section. This section contains a lot of really important settings that control how your Loop will calculate your predicted glucose curve. Given the importance of your predicted glucose curve to Loop's actions, please make sure you read over this page carefully to know how to navigate the selections and entries.

"},{"location":"operation/loop-settings/configurations/#closedopen-loop","title":"Closed/Open Loop","text":"

The user can select closed loop or open loop using this slider. When you first start Loop, we encourage you to leave this slider disabled and become familiar with the app using Open Loop mode.

As soon as Closed Loop is enabled, Loop will begin automatic adjustment of insulin dosing. Please ensure the settings you entered are appropriate for the Loop algorithm.

"},{"location":"operation/loop-settings/configurations/#open-loop-mode","title":"Open Loop Mode","text":"

When the Closed Loop switch is in the (Off) position, Loop WILL NOT modify insulin dosing automatically.

"},{"location":"operation/loop-settings/configurations/#closed-loop-mode","title":"Closed Loop Mode","text":"

When the Closed Loop switch is in the (On) position, Loop WILL automatically modify insulin dosing on the configured insulin pump. This is known as closed loop. Typically, Loop will show the recommended temp basal or automatic bolus just above the blood glucose graph prior to automatically enacting it. It may take a few seconds for Loop to connect to the pump to enact the modified dose.

"},{"location":"operation/loop-settings/configurations/#issue-report","title":"Issue Report","text":"

If you run into problems or errors with your Loop, a Loop Report, generated by tapping on the Issue Report row can be used to help identify where the problem is occurring. The Loop Report can be sent to yourself via text or email. You can then post it on Zulipchat to ask for help.

Frequently, if you seek help with a technical problem, a Loop Report will provide insight for the developers and troubleshooters. Please email yourself a Loop Report anytime you are questioning Loop actions or displays. Acquiring a screenshot of the phone is also useful. You can use the report and graphics later to ask for help or discard them if you figure it out on your own.

"},{"location":"operation/loop-settings/configurations/#select-glucose-units","title":"Select Glucose Units","text":"

Before you continue further, a word about glucose units

Entries into the configuration section will be available in mg/dL or mmol/L automatically, based upon how your blood glucose values are received. By default they are set to mg/dL, however once CGM values arrive in mmol/L these Loop settings can be entered in mmol/L. If you are planning to use mmol/L, be sure to wait to set your entries until after you have started to receive CGM values in Loop. If you do these in the wrong order, then your charts and entries may have incorrect units.

"},{"location":"operation/loop-settings/configurations/#correction-range","title":"Correction Range","text":"

The correction range is your blood glucose range that you would like Loop to correct to. Correction range is not necessarily the same target blood glucose range that you have discussed with your endocrinologist; generally the doctor's range may be much wider. For example, you may keep a correction target of 100-110 for Loop to aim to, but use a desired glucose target range of 80-180 when discussing things with your endo about \"time in range\".

Click the + in the upper right corner to add correction glucose range(s). You can have multiple ranges based on time of day, but the first setting of the day needs to begin at midnight.

Correction ranges can be a single number, such as 100-100 mg/dL, or a range such as 100-120 mg/dL. Generally speaking, if you choose to use a range, keeping the range between about 10-30 mg/dL between the lowest and highest value is a good starting place.

"},{"location":"operation/loop-settings/configurations/#pre-meal-range","title":"Pre-Meal Range","text":"

Below the Correction Range entry is a section called \"Overrides\" with a Pre-Meal setting. While active, the pre-meal targets will replace the usual correction range for Loop's temp basal recommendations. If a pre-meal range is not entered in this section, the icon will remain grey and unusable on the main screen's toolbar.

The pre-meal override target can be used as an easy way to get a small amount of insulin delivered before a meal in order to help control post-meal blood glucose spikes.

If your normal target is 100-110 mg/dL and pre-meal target is 80-80 mg/dL, for example, Loop will give you an extra push to get you to the lower target number before the meal. This early insulin brings you into the meal with a mini-prebolus. The pre-meal target, when activated by pressing on the icon, will stay active for one hour, until carbs are entered, or until it is manually cancelled...whichever comes first.

Loop will adjust any insulin bolus as needed based on the extra insulin provided during this pre-meal time.

"},{"location":"operation/loop-settings/configurations/#suspend-threshold","title":"Suspend Threshold","text":"

The suspend threshold must be set up for successful configuration of Loop. Your Loop will not turn green without setting this value. This value affects both bolus and basal recommendations by Loop.

"},{"location":"operation/loop-settings/configurations/#bolus","title":"Bolus","text":"
  • If you are trying to bolus a meal while any part of the predicted glucose curve is below this suspend threshold value, Loop will not recommend a bolus. Instead, you will need to wait until your prediction curve is above the suspend threshold value in order to bolus.
"},{"location":"operation/loop-settings/configurations/#basal","title":"Basal","text":"
  • If your current or any point on your predicted glucose curve is below the suspend threshold, Loop will always recommend a temporary basal rate of 0 U/hr.

Reasonable settings for suspend threshold will depend on user preference, but recommended not set lower than 65 mg/dL.

"},{"location":"operation/loop-settings/configurations/#basal-rates","title":"Basal Rates","text":"

Note: You cannot enter basal rates until you first add a pump in Loop settings. Your basal rates will be initially populated when you walk through the Add Pump part of the setup at the beginning of this setup guide.

Only one basal schedule may be set in each Loop app. The basal increments are available according to the increments of the particular pump/pod you are using. Not all pumps provide the same increments for basal deliveries. Basal schedule must start at midnight and cannot contain rates of 0 U/hr.

To edit a line in your basal schedule, tap the line and adjust the time and/or amount. To remove a line, select Edit in the top right and delete it. If tapping the line doesn't work, try closing and re-opening the app. When finished editing, click on the Save to Pump... or Sync With Pod button, depending on which pump you are using.

If you make any basal edits and use the Cancel button to go back to the menu without successfully saving/syncing to pump/pod, the changes you made will not be saved. Loop makes saving/syncing to pump a mandatory step to successfully editing basal rates. If you get an error message while trying to save/sync the edited basal rates, please retry until successful.

"},{"location":"operation/loop-settings/configurations/#delivery-limits","title":"Delivery Limits","text":"

The maximum basal rate and maximum bolus settings are collectively referred to as Delivery Limits. This section will have been initially populated when you finished the Add Pump part of the setup previously. For safety, similar to basal schedule, you must keep these values the same on both the Loop app and within the pump/pod settings. If you edit these settings in Loop app, always use the Save to Pump... or Sync With Pod button, depending on which pump you are using.

"},{"location":"operation/loop-settings/configurations/#maximum-basal-rate","title":"Maximum Basal Rate","text":"

Maximum basal rate will cap the maximum temporary basal rate that the Loop is allowed to enact to meet your correction range. Typically, Loop users set their maximum basal rate around 3-4 times their highest scheduled basal rate. When you are first beginning to use Loop, it is wise to start conservative (low) in setting your maximum basal rate. If your settings are incorrect in other areas (basal rates, insulin sensitivity, carb ratio, etc), you may need time to identify where settings need to be adjusted. This process is easier if Loop is given less latitude to set high basal rates. Gradually increase your maximum basal rate as your comfort and confidence in Loop increases. If you need help with your settings adjustment, head over to LoopTips for some initial settings help

"},{"location":"operation/loop-settings/configurations/#maximum-bolus","title":"Maximum Bolus","text":"

Enter your desired single bolus maximum here. For safety, don't set a maximum bolus limit any higher than your typical large meal bolus.

"},{"location":"operation/loop-settings/configurations/#insulin-model","title":"Insulin Model","text":"

There are four insulin models to choose from with Loop 2.x; Walsh, Rapid-Acting Adults, Rapid-Acting Children, and Fiasp. If you want to read the nitty-gritty discussion that went into the development of the Rapid-Acting and Fiasp curves (collectively called \"exponential insulin models\"), you can see that in GitHub here.

Loop 3 Insulin Type

Loop 3 drops the Walsh model and, by default, does not include the concept of child versus adult for \"rapid\" acting insulin, i.e., Humalog, Novalog and Apidra.

  • Insulin Type is selected when the user adds a pump
  • The user can choose to customize Loop 3 to Enable Child Model

We highly recommend selecting one of the exponential insulin models for Loop 2.2.x (in other words, not the Walsh model).

A common new Loop user error is to select Walsh model in order to easily shorten their insulin duration (DIA) to one like they used prior to Looping. This almost invariably leads to insulin stacking. If you would like to read more about why the duration of insulin action is important in Loop vs how you've traditionally used it, please click here to read a blog post about the subject. In summary, choosing Walsh curve just to shorten your DIA will lead to insulin stacking and less than desired bolusing recommendations.

You can click on each model and see what each model's insulin activity curve looks like, active one selected in blue.

The differences between the three exponential models (two Rapid-Acting and Fiasp) models has to do with the timing of the peak insulin activity timing. Not surprising, since Fiasp is marketed as the \"faster acting\" insulin. Currently all the exponential models are defaulted to an insulin duration of 6 hours, but the peak activity of the curves differs:

  • Rapid-acting adult curve peaks at 75 minutes
  • Rapid-acting child curve peaks at 65 minutes
  • Fiasp peaks curve peaks at 55 minutes
"},{"location":"operation/loop-settings/configurations/#dosing-strategy","title":"Dosing Strategy","text":"

This configuration setting gives you the ability to select the Dosing Strategy. (If you do not see this setting, then you are running Loop v2.2.4 or older.) If you tap on that Dosing Strategy, it reveals a selection screen, shown in the graphic below, with some explanation. Note that this Dosing Strategy feature was available for more than a year in the automatic-bolus branch. Users who have been using the automatic-bolus feature should update as soon as possible to get the other improvements recently added, Loop Releases.

The Automatic Bolus selection causes Loop to provide 40% of the recommended dose as a bolus at the beginning of each Loop cycle (when a CGM reading comes in). This is a faster method of getting the recommended insulin delivered. When Loop delivers extra insulin, the scheduled basal rate continues unchanged.

Both Temp Basal Only and Automatic Bolus strategies restrict basal rates to reduce the amount of insulin delivered when appropriate.

"},{"location":"operation/loop-settings/configurations/#temp-basal-only","title":"Temp Basal Only","text":"
  1. When your glucose is at or above target, Loop determines the amount of Recommended Bolus based upon your settings. Subject to your Delivery Limits, Loop will deliver the Recommended Bolus over 30 minutes using positive temp basals (i.e., increase over your scheduled basal rate) to increase your IOB. This decision is re-evaluated during every Loop interval.
  2. When your glucose is below target, negative temp basals (i.e., reduction of your scheduled basal rate) are used to reduce your IOB. This decision is also re-evaluated during every Loop interval.

You can manually bolus at any time by pressing the Bolus icon in the center of Loop\u2019s Main Screen.

"},{"location":"operation/loop-settings/configurations/#automatic-bolus","title":"Automatic Bolus","text":"

When you are first starting Loop, we encourage you to leave automatic boluses disabled until you are sure your settings are dialed in. To enable automatic boluses, click on Settings \u2013 Dosing Strategy \u2013 Automatic Bolus. This Automatic Bolus checkbox turns-off positive temporary basal so that:

  1. When your glucose is at or above target, you receive 40% of the Recommended Bolus at every Loop interval.
  2. When your glucose is below target, negative temp basals (i.e., reduction of your scheduled basal rate) are used to reduce your IOB. This decision is re-evaluated during every Loop interval (same as with the Temp Basal Only dosing strategy).

As with all Loop versions, you can manually bolus at any time by pressing the Bolus icon in the center of Loop's Main Screen. Any bolus recommendation that you see when you press the Bolus icon will be 100% of the Recommended Bolus.

"},{"location":"operation/loop-settings/configurations/#carb-ratios","title":"Carb Ratios","text":"

Click the + in the upper right to add carb ratios for various times of day. Loop works best if you have tested and optimized your carb ratio settings for accuracy.

Beware of other apps writing carbs to Health app

If you are using a third-party app (such as Spike or MyFitness) that can write carbohydrates to the phone's Health app, you will need to double-check permissions to make sure Loop doesn't read those carb entries. Confirm Loop permissions in Health to only write and not read carbs. See see Loop Permissions.

"},{"location":"operation/loop-settings/configurations/#insulin-sensitivities","title":"Insulin Sensitivities","text":"

Insulin Sensitivity Factor (ISF) is the same term as Correction Factor used in some clinics and endocrinology offices. ISF represents the drop in blood glucose levels expected from one unit of insulin. Click the + in the upper right to add insulin sensitivities for various times of day. 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 glucose for new Loop users. You will 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.

"},{"location":"operation/loop-settings/configurations/#loop-2-services-optional","title":"Loop 2 Services (Optional)","text":"

You are not required to use services, although many Loopers use Nightscout. If you do not yet have Nightscout configured and want to add it later, just return to this page when you are ready. This can be added at any time. The same is true for the other services. For more details, click on Loop 2 Services.

"},{"location":"operation/loop-settings/configurations/#next-step-loop-2-displays","title":"Next Step: Loop 2 Displays","text":"

Proceed to the Loop 2 Displays page. Understanding the Loop displays can be a valuable tool to understanding your Loop's actions, and also for troubleshooting, if you are having issues.

"},{"location":"operation/loop-settings/displays/","title":"Loop 2 Displays","text":""},{"location":"operation/loop-settings/displays/#loop-displays","title":"Loop Displays","text":"

This section of the docs describes the Loop displays available and what information they offer. Information about Loop's actions (or inactions) can often be found simply by looking at the visuals presented in the app. (Page last updated for Loop v2.2.4.) For Loop 3, refer to Loop 3 Displays.

"},{"location":"operation/loop-settings/displays/#status-screen","title":"Status Screen","text":"

The Status Screen is the main root navigation screen in Loop. It is broken up into 3 main display areas; Heads Up Display (HUD), Charts, and Toolbar. The HUD is the top area of the screen. This shows the status of the last time loop ran, current BG Reading, current temp basal, and current pump information. The next area is the charting area. This includes, glucose trend and prediction, Active Insulin, Insulin Delivery, and Carbohydrates. The final display area is the toolbar which has buttons for Carbs, Pre-Meal, Bolus, Overrides, and Settings.

"},{"location":"operation/loop-settings/displays/#heads-up-display","title":"Heads Up Display","text":"

The Heads Up Display (HUD) is a very useful quick reference guide to your Loop's status. Every 5 minutes, Loop updates CGM and pump/pod data. Loop timestamps the HUD data with the last data point that came in. If a timestamp goes older than 5 minutes old, that is a valuable indicator to where your Loop is failing to get the needed information. The HUD's first three icons, from left to right, are the same no matter whether you are using a Medtronic pump or Omnipod; status of the last time loop ran, current BG Reading, and current relative temp basal. The last two icons will change depending on what type of pump you are using.

Medtronic users: The last two icons are the most recent (1) pump/reservoir status and (2) pump percentage battery remaining. Details below

Omnipod users: The last two icons are the most recent (1) pod status and (2) hours of pod use. Details below

"},{"location":"operation/loop-settings/displays/#loop-status","title":"Loop Status","text":"

The Loop Status is the colored circle in the upper left corner of the main Loop display. There are four colors that are typically displayed.

A grey circle indicates the Loop is warming up and hasn\u2019t yet completed its initial loop. When the Loop is first activated, it may take about 15-20 minutes to complete the first Loop, and the grey circle will be displayed. It needs CGM data to be gathered, so be patient. When it finally completes its first loop, the circle will turn green. If you can't get your grey loop to turn green, please see the Yellow and Red Loop troubleshooting page for tips. A green circle indicates the Loop has been successfully completed within the last 5 minutes. The time since the loop last completed will be displayed under the circle. A yellow circle indicates the Loop has not completed in the last 5-15 minutes. It is not unusual to have a few instances of yellow circles throughout a day of looping. They can be caused by temporarily getting too far away from RileyLink or iPhone (more than about 3-10 feet depending on conditions), CGM failing to read or being in ???, radio frequency \u201cnoise\u201d interference, and such. Generally, most yellow circles will self-resolve without needing any special troubleshooting. A red circle indicates the Loop has not completed in over 15 minutes. This is not a typical state, and you should troubleshoot why Loop is not completing. Please review the Yellow and Red Loop troubleshooting page for tips on how to get your green Loop back. Clicking on the red circle will also pop-up the last error message to help guide your troubleshooting. When the circle is notched and not complete, that means the Loop is operating in \u201copen-loop\u201d mode. When the \u201cclosed-loop\u201d setting is turned on, the loop status will show a completed circle.

Fun Fact

The loop status icon will pulse slightly when Loop is communicating with the pump. The pulsing will stop when the communication has completed (green loop) or given up (yellow or red loop).

"},{"location":"operation/loop-settings/displays/#glucose","title":"Glucose","text":"The current BG reading from the CGM will display, including trending arrow and time the reading was taken. If the BG is being read straight from the G5/G6 transmitter or G4 receiver, no special symbols will appear. If the BG is being read from the Dexcom Share Servers, a small cloud icon will be in the corner of the BG reading. Internet access is required to run in this mode. When you first start Loop, there may be a small yellow alert next to the BG. This should go away within a short period of time (around 5 minutes or less). If the yellow alert remains, something may be wrong with fetching BG data. You can try restarting the Loop app (double tap home button, up-swipe on the app to close it) to see if BG data will resume. Special note for Dexcom G5/G6 users>, a yellow alert will appear when calibration is needed. The alert will clear once the calibration is given, but typically Loop will work IF the yellow alert is only for a needed G5/G6 calibration."},{"location":"operation/loop-settings/displays/#temp-basal","title":"Temp Basal","text":"The temp basal will display the enacted temp basal change relative to the scheduled basal. So if the scheduled basal was 1.0 units per hour and Loop has set a temp basal of 0.2 units per hour, the temp basal icon will display -0.8 U, as shown in the graphic to the left."},{"location":"operation/loop-settings/displays/#reservoir-medtronic-users","title":"Reservoir (Medtronic Users)","text":"The reservoir icon will remain grey and plain until insulin volume decreases. At 25% reservoir volume remaining, the reservoir icon will turn yellow. At 10% reservoir volume remaining, the reservoir icon will turn red. The remaining units will be displayed when it gets to these lower thresholds."},{"location":"operation/loop-settings/displays/#battery-medtronic-users","title":"Battery (Medtronic Users)","text":"For x54 pumps, the battery icon will show 100/75/50/25% increments just as the pump does. As the battery level decreases, the icon will turn from grey to yellow to red. For x22, x23 pumps, the battery icon will read discrete % values. The warning colors/levels on Loop's battery indicator work in conjunction with the type of battery selected. If you change battery types, please make sure to update your battery selection in the Loop app settings. The pump's on-screen battery indicator is not a good indicator of remaining battery life for the purposes of looping. Loop's pump communications will fail from low battery levels sooner than the insulin delivery will fail. The Loop's battery level warnings are designed to give you approximately 8 hours of notice before the pump battery will need changing."},{"location":"operation/loop-settings/displays/#reservoir-omnipod-users","title":"Reservoir (Omnipod Users)","text":"The pod icon will remain grey and plain until insulin volume decreases. At 50 units or less insulin remaining, the reservoir icon will turn yellow. At 20 units or less remaining, the reservoir icon will turn red. The remaining units will be displayed when it gets to these lower thresholds. When the reading is 0 units, there may be up to 4 units of insulin available but don't count on it. If the pod senses insulin can no longer be delivered, the pod will have a sustained audible alarm (the scream). Tapping Replace Pod in Loop->Pod->Settings should silence the alarm."},{"location":"operation/loop-settings/displays/#pod-age-omnipod-users","title":"Pod Age (Omnipod Users)","text":"The pod's age, typically a 3-day lifespan, is represented by three equal segments of the pod age icon. As the pod ages, the segments are converted to a darker grey color. At 54 hours old, the pod age icon will turn yellow. At 72 hours old, the pod age icon will turn red, the pod will begin the periodic warning beep, and the pod age icon will show a \"replace pod\" message in the HUD. When you reach 80 hours of pod use, the pod will have a sustained audible alarm (the scream) and stops all insulin delivery. Tapping Replace Pod in Loop->Pod->Settings should silence the alarm."},{"location":"operation/loop-settings/displays/#charts","title":"Charts","text":"

There are several charts that help you navigate your Loop actions. Clicking on each of the charts will also open up additional information.

"},{"location":"operation/loop-settings/displays/#glucose-chart","title":"Glucose Chart","text":"

The glucose chart displays BG values in your preferred units. (If not, quit and restart Loop app on your phone.) The vertical scale of the chart is calculated on the fly by Loop to be as useful as possible while including the highest and lowest readings in the chart.

The horizontal axis is set to go forward from the current time until your DIA (insulin duration) forward (so you can see what Loop thinks BG will be eventually). It then goes back in time as far as it can, based upon the width in pixels of your screen. Note, if you turn your device to landscape mode you will have more screen real estate and thus will be able to see further back in time.

The BG correction range is shown as a blue bar on the glucose chart. Single-value range BG range (such as 100-100 mg/dL), will have a narrower blue range. When a temporary override range is enabled, a darker blue bar where the overrides are set will be displayed, as well as the normal correction range in lighter blue.

If you have a crazy negative prediction - it is likely that you set an override with a tiny Overall Insulin Needs setting. Don't do that again. Best approach: Do not panic - this is a prediction only; not reality. Open the loop until the prediction settles down. In future, do not choose a tiny Overall Insulin Needs setting to force less insulin, simply increase the correction range in your override - Loop will reduce your basal rate at the next cycle (within 5 minutes).

The eventual BG displayed on the right side of the chart does NOT take into account a recently enacted temp basal. In other words, if you are above BG range and Loop just enacted a high temp basal to help, the eventual BG does not reflect the expected lowering of BGs that would result from that recently enacted temp basal. Loop waits until the insulin has actually been delivered before it \"uses\" the insulin in its calculations for BG impacts. If you suspended your pump or had a \"no delivery\" alarm shortly after the temp basal was started, you would want that accurately reflected in the insulin on board and associated eventual BG.

If you tap on the Glucose Chart itself, it will open the Predicted Glucose chart described below.

"},{"location":"operation/loop-settings/displays/#predicted-glucose-chart","title":"Predicted Glucose Chart","text":"

The predicted glucose view is a great way to gain insight into the various components\u2019 importance in Loop\u2019s prediction of eventual BG.

The graph at the top of this view will match your Glucose Chart. Below this chart you will see a very detailed explanation of all of the variables that Loop takes into account in predicting your future BG value. Each of those effects (including Carbohydrates, Insulin, Glucose Momentum and Retrospective Correction) includes details of the calculation used. You can tap on any of the entries to turn them off and on for visualization. The resulting changes can be viewed by the changes in the dashed lines.

Note - these elements are not turned on and off in the Loop predictions. They just modify the graph so you can view the relative effects.

"},{"location":"operation/loop-settings/displays/#active-insulin-chart","title":"Active Insulin Chart","text":"

The Active Insulin chart displays the total insulin contribution from both temp basals and boluses. Active IOB can be either positive and negative IOB. Negative IOB results from the suspension of normally scheduled basals. The active insulin displayed in the upper right corner of the chart does NOT include insulin contributions from a recently enacted temp basal or bolus until the (for Medtronic) pump\u2019s reservoir volume is read and confirms a drop in reservoir volume (confirming the insulin has actually been delivered). The opposite is true for Omnipods. If a message is sent from Loop, it assumes the pod got the message and enacted it - even if the acknowledgement is not received. Later, when communication is restored, if a command was not enacted by the pod, the Event History is updated.

Medtronic Only: So long as you have Event History as the Preferred Data Source in Loop settings, primed insulin deliveries (e.g., cannula fills or manual primes) will not be counted towards IOB.

"},{"location":"operation/loop-settings/displays/#insulin-delivery-chart","title":"Insulin Delivery Chart","text":"

The Insulin Delivery chart displays a history of the temp basals enacted by Loop. The display is relative to the scheduled basal rates entered in the Loop settings. So, a rate displayed in this chart as +0 units would indicate no temp basal was set, and Loop defaulted to the scheduled basal rate. Individual boluses are indicated by an orange triangle on the chart (shown in the graphic above, near the left-most time). The total insulin delivered since midnight, including all basals and boluses AND (Medtronic Only) priming insulin, is given in the upper right corner of the graph.

Please be patient for a bolus delivery to appear. There is a lag time from when you press the \u201cdeliver\u201d bolus button to when the orange triangle is drawn sometimes. The insulin has to be delivered and then the (Medtronic Only) pump reservoir needs to be read to confirm delivery, before the triangle will appear and IOB will be added. Occasionally, the bolus may be temporarily rendered (drawn) as a very high temp basal rate vs. a (triangle) discrete bolus event. This does NOT mean that the Loop actually enacted a high temp basal rate...only that the bolus is being drawn on the chart in the equivalent of a high temp basal rate.

"},{"location":"operation/loop-settings/displays/#reservoir-and-event-history","title":"Reservoir and Event History","text":"

Clicking on either the Active Insulin or Insulin Delivery charts will open your Insulin Delivery history. The top of the screen will display the current IOB and the total insulin delivered for the day since midnight (or since the time the loop became active if you started Loop after midnight). There are two viewing options; Reservoir or Event History.

  • Reservoir: Omnipod users should not worry about the reservoir display. Pods do not report or track insulin remaining until their reservoirs get below 50 units remaining. If your pod has more insulin than that - you'll see the reservoir history from the previous pod - ignore that. Medtronic users will have reservoir history displayed in 5-minute increments, unless Loop has been having communication issues.

  • Event History: Event history is a detailed accounting of all pump/pod actions. Both Medtronic and Omnipod users will have a detailed record of event history. If you tap on an event, you get more detail. Turn your phone to landscape to improve readability.

"},{"location":"operation/loop-settings/displays/#active-carbohydrates-chart","title":"Active Carbohydrates Chart","text":"

The Carbohydrate chart displays the carbs used by Loop to predict BG changes. The active COB is displayed in the upper right corner of the chart. Clicking on the chart will open the Carb Entries history and you can edit/delete any previous entries through that screen. Please read the Carb Entry page for more information about editing carb entries.

For more information about the Insulin Counteraction Effects information found in the Carb History, please see here.

"},{"location":"operation/loop-settings/displays/#tool-bar","title":"Tool Bar","text":"

The toolbar is where your inputs to the Loop behavior take place. The individual components of the toolbar are, left to right:

  • Carb entry tool- click on this tool to enter carbs into the Loop app. Loop will not read carb entries from a Medtronic pump or Nightscout, so you must use the carb entry tool in Loop app in order to have carbs accounted for by the Loop. Detailed info regarding how to enter, save, and edit carb entries can be found in the Carb Entry page.

  • Pre-meal range - click this tool to set the Pre-Meal temporary override range. (If you have not configured a pre-meal range under Loop Settings, this icon will be inactive - some people prefer this to avoid accidently tapping it.) This range will remain in effect (1) for 60 minutes, (2) until a carb entry is saved, or (3) until the range is toggled off manually or by tapping on the override icon, whichever comes first. The background coloring of the Pre-Meal range will turn green when active and there will be a dark blue line on the BG chart indicating where the override range is enabled.

  • Bolus tool - click on this tool to bring up the bolus tool. Normally, this screen will automatically open on its own and function as a bolus wizard when a meal is saved on the carb entry tool screen. But you can click on this icon anytime to manually bolus. During rapidly rising BGs, where Loop doesn't have an adequate temp basal rate to cover the pace at which BGs are rising, you may try clicking on the bolus tool to see if Loop is recommending a correction bolus to help control the BG spike. Or if you want to trade bolus now for basal later (super bolus), you can enter a bolus greater than Loop recommends - Loop will set zero Temp Basal next cycle. For more information about the Bolus tool features and use, see the Bolus page.

  • Overrides - click this tool to set an Override.

  • Loop Settings - click on this tool to make changes to any of your Loop settings.

"},{"location":"operation/loop-settings/displays/#next-step-pump-settings","title":"Next Step: Pump Settings","text":"

The pump attached to Loop has a screen to display status and command options. For Loop 2, these are documented in Loop 2 Pump Settings.

"},{"location":"operation/loop-settings/mdt-pump/","title":"Loop 2 Add Medtronic","text":""},{"location":"operation/loop-settings/mdt-pump/#medtronic-pump-users","title":"Medtronic Pump Users","text":"

Your Loop app will have a lot of blank spots until you input some basic settings. The beginning step is to add a pump to your Loop app. If you are using an Medtronic pump, you can follow along for the rest of this page. If you are using an Omnipod pump, please head over to Loop 2 Add Omnipod instead.

"},{"location":"operation/loop-settings/mdt-pump/#prepare-medtronic-pump","title":"Prepare Medtronic Pump","text":"

Before you begin the rest of the setup process, there are several steps on your Medtronic pump that you will need to complete prior to moving on with Loop setup. DO NOT SKIP THESE STEPS OR YOUR LOOP WILL NOT WORK.

  1. Turn off Patterns under the basal menu settings. This will force Loop to use your \"Standard\" basal rate schedule.
  2. Make sure your standard basal rate schedule is up-to-date and accurate. Loop will automatically import your pump's existing standard basal rate schedule when you add your pump in the subsequent parts of this page. If you change basal rates later...make sure to make those changes in the Loop app and use Loop to save the changes back to the pump. If you make changes directly in the pump, Loop will not automatically know about those changes and you will cause a mismatch.
  3. Set your pump's Temp Basal Type to Insulin Rate (U/hr). Do NOT use percentage. Your Loop will not run unless your temp basal type is set to units/hour.
  4. Make sure your maximum basal rate and maximum bolus (those are particular settings in the pump) are reasonably set for your particular needs. For new Loop users, a maximum basal rate equal to approximately 2-4 times your highest scheduled basal rate is a good starting point as you learn Loop and dial in your other settings. You can adjust as your comfort and use of Loop develop.
  5. Set Remote Devices to ON and enter any random ID (010101 will work - avoid using all zeros). This setting is found in the pump's Utilities menu (for x23 continue to Connect Devices, Remotes) and turn ON the Remote Options.
  6. Cancel any currently running extended or dual wave boluses. Loop cannot loop with those running.
  7. Make sure the other settings in your pump, such as bolus wizard settings, are up-to-date so that if you stop using Loop, those settings will be accurate for non-Loop traditional pump use.
"},{"location":"operation/loop-settings/mdt-pump/#select-pump-type","title":"Select Pump Type","text":"

Let\u2019s start by clicking on the Loop Settings button in the tool bar at the bottom of your Loop app. It looks like a little sprocket. On the settings screen that opens, click on Add Pump and select the Medtronic pump option that appears.

"},{"location":"operation/loop-settings/mdt-pump/#connect-pump-to-loop","title":"Connect Pump to Loop","text":"

New RileyLink compatible devices won't have a name listed next to their slider at first. The name will only be displayed after connecting the device to Loop for the first time. So, if all you see in the device list is a little toggle and no \"RileyLink\" name...go ahead and switch that toggle. The default device name will appear after that toggle is green.

You can later personalize the default device name once it is connected to Loop.

Continue with these steps to connect your Medtronic pump to Loop.

  1. Make sure your RileyLink is turned on and nearby, then you will see a RileyLink listed in this area of the settings. Actually, you will see a list of any RileyLinks that are in the nearby area. Slide on the toggle for just one RileyLink.
  2. Add your pump's region, color, and serial number.
    • Note that some Canadian pumps use CM instead of CA for the region code. Just select CA in the dropdown menu.
  3. Click the Continue button to finish the addition of your pump.

For x23 and x54 Medtronic pump users only

For x23 and x54 Medtronic pump users, there is a packet of information special to those pumps called MySentry messages. If you have never setup this part of the pump previously, you may see a screen, called \"Pump Broadcasts\", at this point in the setup process.Follow the directions on the screen. They will require you to take some manual steps on your pump to \"pair\" it with your Loop app.Basically, you will need to go to your pump's main menu, scroll down to Utilities, then Connect Devices, then Other Devices, turn that setting On, and then select Find Device. Once you do that, click on the Continue button in Loop app and the pairing will take place. This will allow those MySentry packets of information to flow to Loop app.This step does not apply for x22 or x15 pump users, since those pumps do not have MySentry capabilities.

Now that your pump is paired with Loop, you will be finishing these steps:

  1. Change your pump time using the Loop app (and read all the info on that screen)
  2. Import your pump's basal rate schedule, maximum basal rate, and maximum bolus (maximums are collectively called \"delivery limits\" in Loop)
  3. Select your pump's battery type (lithium or alkaline)
  4. Leave the Preferred Data Source on Event History

Event History must be selected for Nightscout to display temp basals, carbs, and boluses from Loop. Event History must also be selected in order for prime events to be detected and NOT contribute to IOB during site changes. Please just leave the Preferred Data Source on Event History.

"},{"location":"operation/loop-settings/mdt-pump/#change-time-zone","title":"Change Time Zone","text":"

Loop automatically prompts you to set your pump time using the Loop app as part of initial Loop setup. There will be other times you need to change the time - traveling or daylight savings time start and end. It is important that you use Loop to change time on your pump; do not adjust time on your pump directly once it is attached to Loop.

If you are traveling through time zones, Loop continues to work - just be aware that your basal rate and other configuration settings will be in the original time zone. To change time zones, please follow the Change Time Zone instructions.

Always use the Loop -> Pump -> Change Time command to change pump time. Do not use the Medtronic pump menus to change your pump's time when Looping.

"},{"location":"operation/loop-settings/mdt-pump/#next-step-add-cgm","title":"Next Step: Add CGM","text":"

Congrats! You've added your Medtronic pump to your Loop app. Now, click on the settings button in the upper left corner to take you back to Loop's settings menu. Your next step is to Loop 2 Add CGM to your Loop app. After all, without CGM data, your Loop won't loop.

"},{"location":"operation/loop-settings/omnipod-pump/","title":"Loop 2 Add Omnipod","text":""},{"location":"operation/loop-settings/omnipod-pump/#omnipod-users","title":"Omnipod Users","text":"

Your Loop app will have a lot of blank spots until you input some basic settings. The beginning step is to add a pump to your Loop app. If you are using an Omnipod pump, you can follow along for the rest of this page. If you are using a Medtronic pump, please head over to Loop 2 Add Medtronic Pump page instead.

"},{"location":"operation/loop-settings/omnipod-pump/#select-pump-type","title":"Select Pump Type","text":"

Let\u2019s start by clicking on the Loop Settings button in the toolbar at the bottom of your Loop app. It looks like a little gear. On the settings screen that opens, click on Add Pump and select the Omnipod option.

"},{"location":"operation/loop-settings/omnipod-pump/#select-rileylink","title":"Select RileyLink","text":"

New RileyLink compatible devices won't have a name listed next to their slider at first. The name will only be displayed after connecting the device to Loop for the first time. So, if all you see in the device list is a little toggle and no \"RileyLink\" name...go ahead and switch that toggle. The default device name will appear after that toggle is green.

You can later personalize the default device name once it is connected to Loop.

A list of all RileyLink compatible devices in the nearby area will display in the RileyLink Setup screen. Select your RileyLink by sliding the toggle to display green and then press the blue Continue button at the bottom of the screen. If your RileyLink does not appear, make sure it is charged and turned on: slide the recessed switch toward the case's keyring.

"},{"location":"operation/loop-settings/omnipod-pump/#delivery-limits-and-basals","title":"Delivery Limits and Basals","text":"

The next screen will offer two areas where you will need to enter information:

  • Delivery Limits: Tapping on Delivery Limits presents a screen where you enter your Maximum Basal Rate and your Maximum Bolus.

    • Your Maximum Basal Rate limits how aggressive your Loop app can be in setting temporary basal rates to treat high blood glucose.
    • The recommended value for new users is about 3 times their highest scheduled basal rate.
    • Your Maximum Bolus entry limits the size of a single bolus.
    • The recommended value for new users is the largest bolus typically used for meals.

  • Basal Rates: Enter your scheduled basal rates, beginning at midnight. Consistent with Omnipod use, the scheduled basal rates have a maximum of 24 entries, no 0 u/hr entries are allowed, and the rate increments are 0.05 u/hr.

    • Start by tapping the + at the top right of the Basal Rates screen to enter the first value.
    • Tap + to add rows as needed.
    • When you are done, hit the Back button at the upper left.
    • Note - once a pod is paired to the Loop app, you will press Sync to Pod instead of Back to save your basal rates - you only see Back when no pod is paired.
    • To delete a basal rate or rearrange the order, first tap Edit on upper right and then use standard Apple gestures (for your phone iOS) to delete or move rows.
    • You will not be able to move or delete the row for midnight.
    • You will not be able to add another row if the last row is for 11:30 pm

When you finish entering these values, press the blue Continue button on the bottom of the Pod Settings screen to continue with the next steps of Pod setup.

"},{"location":"operation/loop-settings/omnipod-pump/#pair-pod","title":"Pair Pod","text":"

Max Fill is 200 Units

When you fill the Pod do not exceed 200 units.

If you overfill the pods, you may get a pod fault right after priming.

Pod Filling and Insertion

The Pod filling and insertion instructions are the same with the Loop app as they are for the PDM. These videos: Filling a Pod with Insulin and Inserting the Cannula, may be useful. You will use your phone and RileyLink compatible device instead of the PDM. Be sure to keep the phone and RileyLink close during pairing and insertion because the Pod uses a low-power mode during these activities.

  1. Fill the Pod with insulin until it beeps (minimum fill is 80 units)
  2. Place the Pod about 6 inches from the RileyLink compatible device with the phone within a few feet
  3. Click the Pair button
  4. Loop checks on the radio signal strength (RSSI) reported by the pod when it starts to pair and if it is not within the optimum range, it will ask you to move the RileyLink closer or further away and try again.
  5. Wait while the progress bar for priming completes
  6. Press the Continue button when the blue checkmark confirms priming is complete

"},{"location":"operation/loop-settings/omnipod-pump/#insert-cannula","title":"Insert Cannula","text":"
  1. Prepare your insertion site
  2. Remove the Pod's needle cap and adhesive backing
  3. If the cannula is safely tucked away, apply the Pod to your desired infusion site. If cannula is sticking out, press cancel in the upper right corner of the screen and try a new Pod. (Report this issue to Insulet; it is a Pod problem.)
  4. Press the Insert Cannula button.
  5. Listen to the clicks filling the cannula, wait for insertion and the progress bar to complete. The number of clicks to insertion is not consistent. The cannula will deploy before the progress bar is completed.
  6. Confirm cannula has deployed: you should feel it and there is a pink slide that can be seen on the outside of the pod as shown in this video: Inserting the Cannula.
  7. Proceed to the Expiration Reminder screen to accept or modify the default reminder.
"},{"location":"operation/loop-settings/omnipod-pump/#expiration-reminder","title":"Expiration Reminder","text":"

Finish the setup using the default expiration reminder time (2 hours before a full 3-days of usage). You can modify that expiration reminder at any time, see Expiration Reminder. The notification will come from Loop; your Pod will not beep at this time. Setup is complete and your Pod is ready for use when you press the Continue button.

Range

Now that the priming and insertion steps are complete, the Pod is in normal power mode, so the range between the Pod and RileyLink compatible device is increased.

"},{"location":"operation/loop-settings/omnipod-pump/#pod-settings","title":"Pod Settings","text":"

After the Pod setup is complete, you will be on the Pod Settings screen. The information on this screen is described in Omnipod Pump Commands.

"},{"location":"operation/loop-settings/omnipod-pump/#next-step-add-cgm","title":"Next Step: Add CGM","text":"

Congrats! You've added your Pod to your Loop app. Now, click on the Done button in the upper right corner of your Pump Settings screen to take you back to Loop Settings. Your next step is to Loop 2 Add CGM to your Loop app. After all, without CGM data, your Loop app won't loop.

"},{"location":"operation/loop-settings/pump-commands/","title":"Loop 2 Pump Settings","text":""},{"location":"operation/loop-settings/pump-commands/#pump-settings","title":"Pump Settings","text":"

To bring up the Pod/Pump Settings display, tap on the reservoir icon in the Heads Up Display or the image of the pump in the Loop settings screen.

Omnipod Eros vs DASH

With the addition of DASH pods with Loop 3, you will notice all reference to Eros pods continue to say Omnipod in both the documentation and the code.

Documentation and screens in the app indicate DASH explicitly.

"},{"location":"operation/loop-settings/pump-commands/#change-time-zone","title":"Change Time Zone","text":"

The schedules for the basal rates, correction ranges, insulin sensitivity factors and carb ratios stay at the pump time even if the user and their phone change time zones or when daylight savings time occurs. To bring the pump into the same time zone as the phone, use this command in Loop. (Medtronic users - do NOT adjust time on your pump - always go through Loop.)

Select the Pod/Pump Settings display, scroll down to the Change Time Zone line, example shown in the graphic below. You can leave the time zone offset unchanged or touch it to change to the current time zone. Note that the 24 hour configuration pattern for basal rates, insulin sensitivity factor, carb ratio and correction range are aligned with the time zone shown on this line.

Once the Change Time Zone command is tapped, Loop no longer shifts the 24 hour configuration pattern to the old time zone. Some behavior depends on whether the pump is an Omnipod or Medtronic.

"},{"location":"operation/loop-settings/pump-commands/#omnipod-commands","title":"Omnipod Commands","text":"

To bring up the Pod Settings display, tap on the Pod Age icon on the Heads Up Display or the image of the Omnipod in the Loop settings display to reach the Pod Settings display.

This screen provides important information about your Pod and allows you to issue some commands to the Pod through Loop. There were some recent modifications made to the layout and underlying information for some of the rows.

  • Enable/Disable Confirmation Beeps: moved up to the Configuration section; beeps for all manual pod operations; uses a more efficient implementation

  • Suspend/Resume: Pod will beep every 5 minutes when suspended; the beeps can be silenced by tapping on the Alarms line

"},{"location":"operation/loop-settings/pump-commands/#pod-information","title":"Pod Information","text":"

The first section has the (72 hour) Pod expiration date/time and how long the Pod has been active. These are determined when the Pod is activated by injecting insulin into the reservoir and uses pod active time.

"},{"location":"operation/loop-settings/pump-commands/#bolus-delivery","title":"Bolus Delivery","text":"

This line reports the % progress of any ongoing bolus. This line reports None unless a bolus is actively being delivered when you enter Pod Settings. This line may not update until you tap on the refresh symbol to the right of the Pod image, or exit and re-enter the Pod Settings screen.

"},{"location":"operation/loop-settings/pump-commands/#basal-delivery","title":"Basal Delivery","text":"

This line reports

  • schedule for scheduled basals
  • U/hour for a 30 minute Temporary Basal
  • suspended if the Pod is suspended

"},{"location":"operation/loop-settings/pump-commands/#alarms","title":"Alarms","text":"

This line displays Alerts or Alarms; tapping on it, or on the accompanying banner displayed in the HUD, acknowledges the alert

  • If your Pod is beeping an alert, this line will display information about the alert. Tapping on the alert clears or \"snoozes\" the alert status.
  • If your Pod is screaming, it's time to change it. Tapping on this line stimulates an immediate reading of the actual error (normally this happens at the next CGM reading).
  • There was overwhelming preference during initial testing to minimize the \"beeping\" of Pods. You can turn on additional beeps by enabling Confirmation Beeps. These are the Loop Notifications and Pod beeps you should expect with the default (confirmation beeps disabled) setting:
    • Expiration Reminder - Loop notification only, no Pod beeps
    • 72 Hours Expiration - Loop notification and Pod beeps (Pod beeps continue once per hour until alert is acknowledged)
    • 79 Hour Alert - Loop notification and Pod beeps (Pod beeps continue every 15 minutes until alert is acknowledged)
    • Pod Suspended (v2.2.5 or later): Pod beeps once per 5 minute unless this alarm is cleared

"},{"location":"operation/loop-settings/pump-commands/#reservoir","title":"Reservoir","text":"

Pods do not report the volume of insulin remaining in the reservoir until there are less than 50 units remaining. So, typically you will see \"50+ U\" in this line for quite a while with a new Pod.

"},{"location":"operation/loop-settings/pump-commands/#insulin-delivered","title":"Insulin Delivered","text":"

This line is the basal and bolus insulin delivered by the Pod since the cannula was inserted. It is obtained by taking the reported Pod insulin delivery and subtracting the amount used to prime the Pod and fill the cannula upon insertion (about 3\u00a0U).

"},{"location":"operation/loop-settings/pump-commands/#pod-commands","title":"Pod Commands","text":"

This section contains commands the typical user will use.

"},{"location":"operation/loop-settings/pump-commands/#suspend-delivery","title":"Suspend Delivery","text":"

This command will suspend all insulin delivery; basals, temp basals, and boluses in progress. When you press suspend delivery, all insulin delivery stops indefinitely and the display changes to say Resume Delivery. (If the display does not update, tap the refresh screen icon at the top of the screen to the right of the Pod image.)

A banner notice will appear on the Loop's main screen when phone is in portrait mode when insulin delivery is suspended. Unless you are running v2.2.4 or earlier, a pod beep is initiated with a frequency of every 5 minutes. This can be silenced by acknowledging the alarm.

You will need to press Tap to Resume in the banner or the Resume Delivery button in the Pod Settings to resume your scheduled basal rate and let Loop get back to action. If a bolus delivery was interrupted by the Suspend Pod command, it will not be resumed.

When you resume delivery, the 24 hour Pod basal rate schedule is sent to the Pod. Be sure the Phone, RileyLink and Pod stay close until the message exchange is complete.

"},{"location":"operation/loop-settings/pump-commands/#enable-confirmation-beeps","title":"Enable Confirmation Beeps","text":"

This turns confirmation beeps on for the Pod. The Pod beeps when you enable this, but is silent when you disable it.

  • Bolus Acknowledgement - the Pod beeps when it has received and accepted the bolus command from Loop (manual or automatic) and then beeps again when the bolus is completed.
  • Other - all the manual commands you can issue to the Pod will have an associated confirmation beep when the message is received by the pod, such as updating the basal rate, requesting Pod status, canceling a bolus, suspending or resuming delivery.
"},{"location":"operation/loop-settings/pump-commands/#expiration-reminder","title":"Expiration Reminder","text":"

With the Expiration Reminder you can set a convenient time to get a notification to replace your Pod. Loop sets the default to 70 hours, i.e., two hours before the full 3 days that Insulet guarantees. The allowed range of values is between 1 hour and 24 hours prior to the Pod expiration at 72 hours of Pod life. If you select a date/time outside this range, Loop will modify your selection to the closest allowed value.

As with the PDM, Loop allows the Pod to continue operating after expiration until it reaches the maximum allowed 80 hours of life, at which time, the Pod shuts down and alarms. Loop detects this message the next time it tries to communicate with the Pod. In the event your Pod runs out of insulin before that time, then you will get a \"Pod empty\" notification.

The glitch in setting the Expiration Reminder in v2.2.4 is now fixed.

Loop v2.2.4 has a \"glitch\" in setting the Expiration Reminder. Tap on the line (can't change time), scroll the entire display up or down until the line no longer is visible and then scroll it back. The Expiration Reminder display should now look like the graphic below. The expiration reminder time can now be selected.

"},{"location":"operation/loop-settings/pump-commands/#change-time-zone_1","title":"Change Time Zone","text":"

Use the Change Time Zone command to align your configuration settings with the current time zone. Note that this updates your basal schedule on your Pod. If you start a new Pod session without modifying the time zone here, the original time zone will be used for the new Pod. Please wait until you see Succeeded appear on the page to ensure the command has successfully been received by the Pod.

Make sure the phone, RileyLink compatible device and Pod are kept in close proximity until this command has completed. The time zone is updated by Loop issuing the 24-hour basal rate schedule to the Pod based on the current time.

"},{"location":"operation/loop-settings/pump-commands/#replace-pod","title":"Replace Pod","text":"

This command deactivates a Pod prior to replacing it. Once you tap Replace Pod, another screen appears for you to confirm that you mean it.

"},{"location":"operation/loop-settings/pump-commands/#devices","title":"Devices","text":"

This allows access to the RileyLink screen for each connected RileyLink compatible device.

"},{"location":"operation/loop-settings/pump-commands/#pod-diagnostics","title":"Pod Diagnostics","text":"

This section is labeled Diagnostics, but many Pod users make use of this section.

"},{"location":"operation/loop-settings/pump-commands/#read-pod-status","title":"Read Pod Status","text":"

This command requests the status of the Pod and reports some of the returned information.

  • The line labeled Pulses reports the total number of pulses of insulin delivered by that Pod since activation (adding insulin to the reservoir). To convert this to units of insulin, multiply by 0.05 units/pulse. If you compare this report (for your Pod) to the Insulin Delivered line in Pod settings, for your Pod at the same time, the difference is the insulin used to prime the Pod and fill the cannula at insertion.

  • The line label RSSI reports the Received Signal Strength Indicator (RSSI) between the RileyLink compatible device and the Pod. The RSSI is a positive number with a larger number indicating a stronger signal strength detected by the Pod.

"},{"location":"operation/loop-settings/pump-commands/#play-test-beeps","title":"Play Test Beeps","text":"

This command requests the Pod emit a beep pattern. If you hear it, you know the commands are getting to the Pod. A message appears on your screen to indicate Loop got or did not get an acknowledgment from the Pod.

"},{"location":"operation/loop-settings/pump-commands/#read-pulse-log","title":"Read Pulse Log","text":"

This command reads the pulse log (diagnostic), displays it on the screen and saves the result in the log file. It takes some time, so keep your gear close until command completes. This can be extracted by sending the pulse log to yourself using the send-to icon at the top right of the screen. It is also included in the Issue Report. If you are having communication issues, you can provide this report to an expert who may be able to provide assistance. Post for help in either zulipchat or a Facebook group to request assistance and you'll get information about how to get that log file submitted.

"},{"location":"operation/loop-settings/pump-commands/#test-command","title":"Test Command","text":"

This verifies communication with the Pod. Loop reports success or failure. Use Get Pod Status if you want to see the some of the information returned from the Pod.

"},{"location":"operation/loop-settings/pump-commands/#pod-details","title":"Pod Details","text":"

This section provides some Pod identifying information. The Lot number and TID number are the tiny number stamped on the Pod that Insulet might ask you to report if you happen to call in this Pod for an appropriate failure.

"},{"location":"operation/loop-settings/pump-commands/#medtronic-commands","title":"Medtronic Commands","text":"

Medtronic commands are found in the Pump Settings screen shown in the graphic below. The top section is configured at the time the pump is connected to Loop and can only be modified by deleting the pump and adding a pump. This screen is the same as for earlier versions with the addition of the Use MySentry row.

"},{"location":"operation/loop-settings/pump-commands/#suspend-delivery_1","title":"Suspend Delivery","text":"

This command will suspend all insulin delivery; basals, temp basals, and boluses in progress. When you press suspend delivery, all insulin delivery stops indefinitely and the display changes to say Resume Delivery.

A banner notice will appear on the Loop's main screen when phone is in portrait mode when insulin delivery is suspended.

You will need to press Tap to Resume in the banner or the Resume Delivery button in Pump Settings to resume your scheduled basal rate and let Loop get back to action. If a bolus delivery was interrupted by the Suspend Pod command, it will not be resumed.

"},{"location":"operation/loop-settings/pump-commands/#change-time-zone_2","title":"Change Time Zone","text":"

During normal operation, Loop automatically keeps phone time and pump time aligned. In the case of time-zone or daylight savings time changes, Loop allows the differences to persist until the user chooses to Change Time Zone and accounts for time zones when performing insulin delivery accounting.

"},{"location":"operation/loop-settings/pump-commands/#pump-battery-type","title":"Pump Battery Type","text":"

The type of battery used in the Medtronic pump affects how Loop interprets the battery level for the pump.

"},{"location":"operation/loop-settings/pump-commands/#preferred-data-source","title":"Preferred Data Source","text":"

Leave the Preferred Data Source set to on Event History for proper functioning of Loop.

Event History must be selected for Nightscout to display temp basals, carbs, and boluses from Loop. Event History must also be selected in order for prime events to be detected and NOT contribute to IOB during site changes. Please just leave the Preferred Data Source on Event History.

"},{"location":"operation/loop-settings/pump-commands/#use-mysentry","title":"Use MySentry","text":"

This is a new option. If you don't see this row, consider updating your Loop app. Using the MySentry feature on some Medtronic pumps when using an OrangeLink causes the batteries to die quickly. This option allows you to turn off MySentry within the Loop app.

"},{"location":"operation/loop-settings/pump-commands/#devices_1","title":"Devices","text":"

This allows access to the RileyLink screen for each connected RileyLink compatible device.

"},{"location":"operation/loop-settings/rileylink/","title":"RileyLink Display","text":""},{"location":"operation/loop-settings/rileylink/#rileylink","title":"RileyLink","text":"

The RileyLink (or compatible device) screen is accessed by clicking on the image of your connected pump in Loop settings or the pump icon in the Heads Up Display to bring up the associated pump screen. From that screen, scroll down to the section labeled DEVICES to view the list of connected RileyLink compatible device(s) and tap on the name with a green slider that you want to display. An example is shown in the graphic below.

"},{"location":"operation/loop-settings/rileylink/#signal-loss","title":"Signal Loss","text":"

If there is a problem communicating with that RileyLink compatible device, tapping on the line will show out-of-date or missing information. Go to Troubleshoot: Red Loop: Reset Loop-to-Pump Communications for suggestions.

With Loop 3

  • The Pump Devices display will show the signal loss icon instead of reporting dB as shown in the graphic below.
  • If the problem persists, you'll start to see some Error Messages as well.

"},{"location":"operation/loop-settings/rileylink/#rileylink-status-and-commands","title":"RileyLink Status and Commands","text":"

Tapping on a name with a green slider takes you to the RileyLink Status and Commands screen for that device.

The name at the top center is whatever you named your RileyLink compatible device. The RileyLink screen is the same regardless of the pump you are using.

  • The three graphics below match the display for Loop 3.
  • For Loop 2.2.x - the displays are almost identical when the patch mentioned below the graphic is applied.
  • The firmware displayed is specific to each device.

Patch Required for Loop 2.2.x

Some devices have features not available with other devices. With Loop 2.2.6 some features were added to the OrangeLink, but there is a mismatch of reported hardware for some versions of OrangeLink firmware which prevents the Find Device row from showing up for OL Pro. The EmaLink extra features did not make it into the Loop v2.2.6 release.

  • With Loop 2.2.x, to see the displays shown in the graphics below, please follow instructions in the EmaLink and OrangeLink Feature and Patch sections.
"},{"location":"operation/loop-settings/rileylink/#device","title":"Device","text":"

The lines under the Device section provide information on the device. The two most important lines are the Connection Status and Signal Strength.

  • The Connections Status should say connected if the device is connected to the iPhone's Bluetooth. If the status says connecting or disconnected then you should toggle the iPhone's BT and/or power cycle the device to help reconnect.

  • The Signal Strength is the strength of the Bluetooth signal between the iPhone and the device. It is not the signal strength of the radio communications with the pump/pod.

  • The phone to device Signal Strenth is reported as a negative number so a -50\u00a0dB signal is stronger than -80\u00a0dB. As you move the device and iPhone closer/farther apart, you will be able to see the signal strength change. In a pinch, this can be used to help locate a lost device in the house or at the park after dark.

"},{"location":"operation/loop-settings/rileylink/#personalize-device","title":"Personalize Device","text":"

As soon as you connect the RileyLink compatible device initially - it is strongly encouraged that you rename it from the default name for that device, e.g., RileyLink or OrangeLink or EmaLink.

Once you display the RileyLink Status and Commands screen:

  • Tap on the Name line
  • Enter your desired name
  • Wait a few seconds before doing anything
    • The new name needs to be transferred and saved in the device
    • If you return to the Pump screen too soon, it might not happen - just repeat the process
    • The device must be connected and on to change its name
"},{"location":"operation/loop-settings/services-v2/","title":"Loop 2 Services","text":""},{"location":"operation/loop-settings/services-v2/#loop-services","title":"Loop Services","text":"

Near the bottom of your Loop settings screen is a section called \"Services\".

Sevices are Optional

  • Loop will work whether you use these or not.
  • Nightscout is highly recommended by experienced Loopers but can be added later - you don't need it to get started.

  • For Loop 2.2.x, the services listed in the graphic below can be added by clicking on the Tap to set arrow.

  • Click for Loop 3 Services

"},{"location":"operation/loop-settings/services-v2/#nightscout","title":"Nightscout","text":"

There is a whole section in LoopDocs about Nightscout. Please follow this link to the Using Nightscout with Loop section of LoopDocs. That also has the links you might need to the official Nightscout Documentation (different website).

If you have an existing Nightscout site, it's still a good idea to review that section, but here's a quick summary of how to add your Site URL and API_SECRET to have your Loop data transmitted to your Nightscout site. If you can\u2019t remember your API_SECRET, it can be found under Settings, Reveal Config Vars for Heroku sites (or Application Settings, Connection Strings for Azure sites).

The two most common errors in filling out this section are:

  1. Failure to use https:// in the site URL. If you use http:// (see how that doesn't have the \"s\" at the end?), you will get an error message about an App Transport Security policy.
  2. Having a trailing slash on the end of the URL (or an embedded space). If you copy and paste from a web browser, make sure to delete the trailing slash on the URL entry.

More Tips about Nightscout

  • One family had an app configured to block some websites for their child's phone and accidentally blocked their Nightscout URL - took them a while to figure out that mistake.
"},{"location":"operation/loop-settings/services-v2/#loggly","title":"Loggly","text":"

Loggly is a free logging service. If you sign up for an account, you'll need to go under Source Setup and then Customer Tokens. Copy and paste your customer token into your Loop App settings for Loggly.

"},{"location":"operation/loop-settings/services-v2/#amplitude","title":"Amplitude","text":"

Amplitude is a remote event monitoring service and can be used to quickly identify errors and events with Loop. Amplitude stores the events and allows you to view those events as points in time. To retrieve the details of the events you will need to look at corresponding mLab data entries to get a complete picture of the issues. If you sign up for a free account with Amplitude, you will be given an API Key that you can enter here to have Loop integration setup.

"},{"location":"operation/loop-settings/services-v2/#next-step-loop-displays","title":"Next Step: Loop Displays","text":"

Great job, almost finished! Now that you have completed your services, let's move onto understanding your Loop Displays.

  • Loop 2.2.x - click on this link for Displays

  • Loop 3 - click on this link for Displays.

Loop displays is a valuable tool for understanding your Loop and a great page to review when troubleshooting.

"},{"location":"troubleshooting/loop-crashing/","title":"Loop App Crashes","text":""},{"location":"troubleshooting/loop-crashing/#loop-crashes-upon-opening","title":"Loop Crashes Upon Opening","text":"

If your Loop app crashes immediately upon opening, you have a problem that needs to be fixed. What do I mean by \"crashes\"? Your Loop app immediately turns to a white (light mode) or black (dark mode) screen and then shuts itself down, landing you back at your iPhone's main screen. No amount of tapping will let you keep your Loop app open.

The most likely reason is Your Loop App Expired. But there can be other reasons.

  • If you just updated your phone from iOS 16 to iOS 17 (or a similar major phone update), Apple spends a lot of time indexing your Apple Health data
    • Many people report 5 to 30 minutes during which they cannot open the Loop app but they also cannot open Apple Health
      • Wait until you can open Apple Health and then try to open the Loop app again
  • If you still can't stop the crashes, see Other Reasons and be sure to save the crash log
"},{"location":"troubleshooting/loop-crashing/#your-loop-app-expired","title":"Your Loop App Expired","text":"

Your Loop app has an expiration date. The expiration date will depend on the build method and may also depend on the type of developer account that signed the app.

  • If you build with Browser Build, your app will expire after 3 months
  • If you build with a Mac using a paid account, your app will expire after 12 months
  • If you build with a Mac using a free account, your app will expire after 7 days
"},{"location":"troubleshooting/loop-crashing/#browser-build","title":"Browser Build","text":"

With the current version, 3.2.3, you unfortunately do not get prior warning that the app is about to expire, although you can look in the TestFlight app and it will tell you. An in-app warning will be added to the next release.

Please follow these steps to ensure you can build the app again. How to Update or Rebuild

"},{"location":"troubleshooting/loop-crashing/#mac-using-a-paid-account-1-year","title":"Mac using a Paid account (1 year)","text":"

When your app expires after a year, you need to follow the steps on the Build Updating page. Your phone will probably have a new iOS that may require an updated version of Xcode that may require an updated Mac operating system. All this is explained in the link above. Give yourself time before expiration to prepare yourself.

To make it easy to build when you have to, practice building every 3 to 6 months. This makes the process much lower stress. Also, each time you build, when you follow the link above, you give yourself another full year before rebuilding is required. Please review the Updating FAQS.

"},{"location":"troubleshooting/loop-crashing/#mac-using-personal-team-7-day","title":"Mac using Personal Team (7 day)","text":"

When your app expires, you simply need to open Xcode, reopen the project: File->Open Recent, plug your phone back into the computer and select it in Xcode and press the play button on your project again. This will rebuild. If you want to change to a paid signing team before rebuilding, please make sure to double-check which signing team is selected before building again.

"},{"location":"troubleshooting/loop-crashing/#switching-from-free-to-paid","title":"Switching From Free to Paid","text":"

If you started with a free account and switched to a paid account:

Many people accidentally build with their old free account

  • How can you tell which you're signing with?
  • The free signing team has the (Personal Team) listed after your name in the signing team

Remember that switching from free to paid changes the developer name incorporated into your Loop App

  • A separate Loop app is created - see Switching from Free to Paid Membership for more details
  • Did you select the new app and enter all your settings into it and then delete the 7-day app?
  • The new app issue only happens if you change developer name
  • As long as you stick with the same developer ID, updated Loop apps are built over existing apps and all your settings should be maintained
"},{"location":"troubleshooting/loop-crashing/#other-reasons","title":"Other reasons","text":"

If you experience a crash for any other reason, please gather all the information you can about what was happening before the crash and report it to your favorite Loop Social Media help site - you will need to get some personalized help. Please - choose one site for your post and wait for someone to get back to you. While you are waiting, search on any of the sites and, if on Facebook, read all the announcements.

"},{"location":"troubleshooting/loop-crashing/#save-and-submit-your-crash-logs","title":"Save and Submit your Crash Logs","text":"

If you have continuous crashes, please save the crash logs so the developers can look at it. If you can, log into Zulipchat and post it directly.

  • The crash logs can be found under Settings --> Privacy & Security --> Analytics & Improvements --> Analytics Data
  • Scroll to find the file Loop_DateTime.ips for crash reports
"},{"location":"troubleshooting/omnipod-faults/","title":"Omnipod Faults","text":""},{"location":"troubleshooting/omnipod-faults/#screamers","title":"Screamers","text":"

Pod faults are typically noticed by hearing a high-pitched continuous tone coming from the pod.

Loop will pick up the fault the next time it exchanges messages with the pod:

  • every 3 minutes for DASH
  • every 5 minutes for Eros

Once Loop detects the fault, you will get a Critical Pod Error modal message on the screen that you must acknowlege along with a Pod Error indicator shown in the HUD:

Normal High-Pitched Tone

There are 2 cases in which you hear the high-pitched continuous tone that are not Faults.

  1. Modal Alert says Empty Reservoir, Pod icon displays No Insulin
  2. Modal Alert says Pod Expired, Pod icon displays Pod Expired
"},{"location":"troubleshooting/omnipod-faults/#stop-that-noise","title":"Stop that Noise","text":"

The first action people want to take is to make that noise stop.

  • Tap on the Pod icon and then the Replace Pod row and deactivate the pod
    • The Replace Pod row is highlighted in red in the graphic below
    • Once the pod has been dealt with and you have a new one in place, it's time to get the details for the Pod Fault
"},{"location":"troubleshooting/omnipod-faults/#capture-the-fault","title":"Capture the Fault","text":"
  • Tap on the Pod icon and scroll all the way down and tap on the Previous Pod Information row, highlighted in dashed-blue in the graphic below
    • If there was a Fault, the information is found at the bottom of the screen
    • For any pod, the information about that pod is always available
"},{"location":"troubleshooting/omnipod-faults/#report-the-fault","title":"Report the Fault","text":"

Faults should be reported to Insulet. They may not give you a replacement, but it is important they be informed so they can determine if certain lots are having more failures than others. This helps them improve the quality of the pods.

  • Take a screen shot of the Fault Information
  • Insulet needs the following:
    • The Lot number (Eros found on the screen, DASH is different)
      • The DASH lot number needed by Insulet is the one found on both the box the pod came from and the paper cover from the pod tray
      • The electronic lot number reported by DASH pods to Loop is not helpful to Insulet
    • The Sequence number (also on the pod in tiny print)
    • The Active time (how long you wore the pod)
    • The Ref code - for the example above, the Ref code is: 19-00805-00551-064
    • They will also ask where on your body the pod was placed

Extra Information

The extra information, e.g., Fault Event Code 0x40: Encoder count too high, is only useful for the curious or the developers. Do not report that to Insulet.

The 0x40 is the hex version of the -064 decimal value found at the end of the Ref code.

"},{"location":"troubleshooting/omnipod-faults/#report-049-0x31-to-developers-not-insulet","title":"Report 049 (0x31) to Developers, Not Insulet","text":"

The sole exception to reporting to Insulet is if you get a fault ending in 049 in the Ref code or with the notation Fault Event Code 0x31: Incorrect pod state for command. That particular fault is only seen if there is a mistake in Loop. This happened rarely in earlier versions but should be fixed by the time version 3.4.0 is released. If you do get an 0x31 (049) fault - report that to the Loop developers and include a Loop Report (Loop, Settings, Support, Issue Report).

"},{"location":"troubleshooting/omnipod-faults/#known-pod-fault-codes","title":"Known Pod Fault Codes","text":"

The currently known pod faults are listed here on the openomni wiki page: Pod Fault codes

"},{"location":"troubleshooting/omnipod-faults/#ways-to-reduce-likelihood-of-a-fault","title":"Ways to Reduce Likelihood of a Fault","text":"

The Loop app will put a higher battery load on a pod than the PDM due to its regular and repeated communications. A pod with lower battery level appears to be more likely to fault for conditions like static electricity and occlusions/pump issues the Loop app is not directly causing, like decimal fault codes 052, 061, 064 and 066. Pods always perform safety checks and if a potential problem is found, the pod will end itself by screaming and halt all insulin delivery.

DASH pods have additional Fault Codes associated with the pod Bluetooth communications. The 0xCB, -203 decimal, seems to be pretty common. These should be reported to Insulet for their records.

None of the ways listed here are guaranteed to prevent a screaming pod, but they could be worth considering.

  • Keep the Loop app up to date; newer versions might include improvements to reduce pod battery load
  • Maintain a wider correction range (10 to 20 mg/dL; 0.5 to 1.1 mmol/L) instead of a single number
  • Loop Version 3, for Eros pods when used with a RileyLink Device that has a lot of communication errors, will send many repeated messages trying to resolve uncertain communications
    • Make sure your RileyLink Device is working well
    • Use a 433 Mhz RileyLink for Eros Pods and ensure the antenna is not loose or pinched
"},{"location":"troubleshooting/omnipod-faults/#replacement-pod-situations","title":"Replacement Pod Situations","text":"

Help Insulet Improve their Quality Control

Insulet is aware that pods are used by the DIY community. You can be honest about your use and might receive replacement pods. If your pod fails early, it is worth informing Insulet for their troubleshooting records even if you do not get a replacement.

You can always call Insulet tech support if a pod has a clear failure on the pod, such as:

  • A cannula was sticking out when the end cap was removed.
  • Visual inspection of the pod's cannula window indicating the cannula insertion was not successful.
  • Leaking or kinked cannula was causing insulin delivery issues.
  • The adhesive was not working properly when trying to place it on your body.
  • The pod begins to scream during filling, pairing, priming or insertion

If the pod fails during use with Loop, a replacement might still be possible. The software which communicates with the pod isn't developed or supported by Insulet. Generally speaking, asking for replacement for failed pods on the third day of pod life is a bit of a reach for the DIY community. We acknowledge that Looping may be a contributor in certain faults, especially by the third day.

"},{"location":"troubleshooting/overview/","title":"Troubleshooting Overview","text":"

After you have been using Loop for a while, there's a potential that you will run across a behavior or issue that you wonder if it is normal or intended. When that happens, there are a few things that we'd recommend doing to resolve the issue.

"},{"location":"troubleshooting/overview/#use-automatic-time-on-loop-phone","title":"Use Automatic Time on Loop Phone","text":"

If you have modified the Loop time (not changed time zone, but turned off automatic time and manually changed the time), please read: Loop Phone Must be on Automatic Time.

"},{"location":"troubleshooting/overview/#gather-information","title":"Gather information","text":""},{"location":"troubleshooting/overview/#screenshots","title":"Screenshots","text":"

Take a screenshot of your Loop main display screen, or other screens such as the display when you touch a red loop icon that may help you or troubleshooters better understand your issue. A lot of times a picture is worth a thousand words. Being able to see recent Loop basal adjustments, predicted BG curve and carb entries really help fill in the full story of the current Loop status. If you didn't manage to get a screenshot when the issue was happening, you can also go to Nightscout and scroll back over the previous 48 hours to obtain much of the same information. Try to capture a Nightscout screen from the time period in question.

"},{"location":"troubleshooting/overview/#check-the-docs","title":"Check the Docs","text":"

Loop docs are updated regularly. If you built your Loop app awhile ago, chances are good that more information has been updated and changed since you last read them. Please use the search tool - if there's an error message - search for it. Scan the topics in the Troubleshoot tab of LoopDocs and look for a page that may be applicable. The FAQs pages are definitely worth reviewing too.

"},{"location":"troubleshooting/overview/#issue-report","title":"Issue Report","text":"

Use the Issue Report Loop 3 / Loop 2 command under Loop Settings to generate a Loop Report. This has a lot of detailed information that may help you or a mentor understand your problem.

The Loop Report (a text file) contains important information about actions and status that can be very useful for troubleshooters...particularly with unexplained behaviors. The upper right corner of the Loop Report includes a button so that you can email the Loop Report to yourself (or others).

"},{"location":"troubleshooting/overview/#check-resources","title":"Check Resources","text":""},{"location":"troubleshooting/overview/#github-issues","title":"GitHub Issues","text":"

Check the current list of GitHub Loop Issues for known issues. Many times other users have noticed the same issue previously and opened an Issue so that more information can be added to help develop a solution. If you see the same issue has already been reported, please add it to the open issue instead of creating a new one.

There is a nice search feature on GitHub issues - type a keyword into the box next to Filters: where it says \"is:issue is:open\" in the graphic and the display will show just those open issues that contain the keyword in the title.

"},{"location":"troubleshooting/overview/#zulipchat-and-facebook","title":"Zulipchat and Facebook","text":"

Search in Zulipchat, Looped Facebook Group or LoopandLearn Facebook Group. Quite possibly someone else has already posted about the same issue and perhaps a resolution has already been provided.

"},{"location":"troubleshooting/overview/#ask-for-help","title":"Ask for Help","text":"

If you can't find any information in LoopDocs, GitHub Issues, Zulipchat, or Facebook...PLEASE post and ask for help. GitHub Issues list is an EXCELLENT place to post issues of unexpected Loop behavior (that you believe are errant or need improvement). However, if you are just seeking clarifications on Loop, but don't necessarily expect that there's a problem with the underlying code, then Facebook and Zulipchat are a better place. For example, Zulipchat and Facebook are great for asking about bolus strategies or exercise target use...those aren't really code issues.

When you post, provide a description along with any screenshots of the issue you are having and include the version of Loop you are running and the iOS on your device. (Tap on Loop-Settings and look at the top of the screen to get the Loop version number). You don't necessarily have to tag any particular person, the community is fairly active in replying to messages.

Post in only one place - the same volunteers monitor various sites.

"},{"location":"troubleshooting/pod-pairing/","title":"Pod Pairing Failures","text":""},{"location":"troubleshooting/pod-pairing/#pod-not-found","title":"Pod Not Found","text":"

Have you seen an error message during the pairing process for a new pod? The most common message is No pods found, as shown below. Make sure no other active pods are anywhere near the phone. Reposition the pod and the phone and if using one, the RileyLink, and then try again.

The instructions in the graphic say fill with U-100 insulin. That is the strength of your insulin, 100 U per mL of solution. The Insulet directions say to inject between 85 and 200 U of insulin. In other words, between 0.85 and 2.0 mL of fluid.

There have been a large number of fixes and improvements to reduce various pairing problems and to automatically recover from them when they do occur.

Update regularly to take advantage of improvements

Make sure you stay on top of Loop updates to take advantage of these code improvements. It is strongly recommended to update to a modern stable version (i.e., the current Loop release).

"},{"location":"troubleshooting/pod-pairing/#the-app-crashed-after-pairing-started-and-before-cannula-insertion","title":"The app crashed after pairing started and before cannula insertion","text":"

Sometimes the app will crash while the pod is priming. This is rare but can happen.

  1. Wait for the clicking to stop
    • It takes a full minute for the pod to finish priming once it starts
    • If the crash occurs while the pod is still priming - it is best to wait 30 seconds after clicks stop before reopening the app
  2. As soon as you resume the app, it will inform you that you did not complete the process
    • If you did not wait, you might be given the Insert Cannula screen before the pod is ready
    • Wait 30 seconds after clicking (priming) stops before attempting to insert the cannula
  3. In most cases, the cannula will insert as expected and you can use the pod
"},{"location":"troubleshooting/pod-pairing/#why-do-pod-pairings-fail","title":"Why do pod pairings fail?","text":"

When the pod is paired to a new device, the pod is using low-power mode. That's one reason why placement is important. And you can only have one pod that is not yet paired in the room. Try to get your new pod working before giving up and trying a new one.

Sometimes it is the pod, so if you do need to try a new one, move the one that did not pair far away from your phone.

Move Logically

Let's walk through the pod pairing/replacement process from the very beginning to make sure that we have all the important steps clearly identified even before you attempt to press that Pair button.

"},{"location":"troubleshooting/pod-pairing/#step-0-check-your-loop-version","title":"Step 0: Check your Loop version","text":"

You can check which version of Loop you are running by pressing the gear icon (\u2699\ufe0f) in the bottom right-hand corner of the Loop home screen and then looking at the line under the header.

Upgrade Loop if version prior to v3.2.x

If you are running a version of Loop prior to v3.2.x, it is recommended to update to the current Loop release.

"},{"location":"troubleshooting/pod-pairing/#step-1-verify-the-rileylink-eros-pods-only","title":"Step 1: Verify the RileyLink (Eros Pods Only)","text":"

For DASH pods, skip ahead to Deactivate old Pod.

For Eros pods, let's make sure everything is ok as far as the RileyLink goes:

  1. RileyLink is charged and nearby, and
  2. RileyLink has a green LED light lit (indicating a Bluetooth connection with your iPhone), and
  3. Try toggling the RileyLink off/on at its physical switch if the green light is not on.
"},{"location":"troubleshooting/pod-pairing/#step-2-deactivate-old-pod","title":"Step 2: Deactivate old Pod","text":"

Make sure old pod was deactivated. If you cannot communicate with the old pod in order to deactivate it, try the steps in Reset Loop to Pump Communications.

If you were not able to deactivate the old pod, you need to Discard the old pod. After several failures to deactivate, Loop offers to Discard the pod. This just tells Loop that the pod is no longer connected to the app.

You must still get that pod (that would not deactivate) away from your vicinity. Put it in a microwave or throw it over the fence into the neighbor's backyard (kidding, obviously...but outside trashcan is a good idea).

Eros Pods Only: If you had issues deactivating your pod, review Step 1.

"},{"location":"troubleshooting/pod-pairing/#step-3-start-new-pairing-process","title":"Step 3: Start new pairing process","text":"

You've deactivated your old pod successfully...great! As the first part of pairing a new pod, Loop will prompt you to fill the new pod with insulin. Once a new pod is powered-up by the insertion of at least 85 units of insulin, the pod will emit reminder beeps every 5 or 10 minutes until the entire pod pairing process has completed. This pairing process must be completed within 60 minutes of beeps starting, or the pod will give up and never pair. These activation reminder beeps do not actually indicate that any pod communication is being attempted, just that the activation has not yet been completed and your 60 minute timer is counting down.

Max Pod fill is 200 U

If you put more than 200 U in a pod, you will probably get a pod fault during priming.

Hopefully, your pod pairing continues uneventfully at this point. You'll press the Pair button and the pod pairs, primes, and the cannula insertion is successful. BUT, if not...you'll want to keep reading Steps 4-5 to find out how to recover.

One beeping pod at a time, please

It is very important to not have two pods giving reminder beeps at the same time as this can cause even more confusion for you and for Loop. Continue to work with a single pod at a time, retrying the Pair attempts multiple times if needed as described in Step 4.

If you cannot get the pairing to complete with the single beeping pod (after trying the procedures described below a few times with multiple Pair attempts during each try), then you should completely abandon that pod before attempting to use another pod. \"Completely abandon\" means move that failed-to-pair-no-matter-what-you-tried pod far, far away from you or put it in a not-turned-on-but-door-is-closed microwave. You do not want that beeping-but-not-pairing pod to be able to plague your next pod's communications with Loop during the fresh pairing process.

"},{"location":"troubleshooting/pod-pairing/#step-4-check-the-pod-placement","title":"Step 4: Check the Pod Placement","text":"

Pod pairing failed?

Ok, so you've pressed that Pair button and received an error message like shown at the top of the web page? It's time to start the stepwise process of seeing if we can get it to recover successfully.

"},{"location":"troubleshooting/pod-pairing/#dash","title":"DASH","text":"

The DASH pod can be left in the tray and placed right next to the phone. If the first attempt to pair shows the \"No pods found\" message, place the tray on top of the phone or move the pod a little further away from the phone, then try again.

If you see the Pairing exception message as shown in the graphic below, you need to toggle Bluetooth on the phone:

  • In your phone settings, turn off Bluetooth
  • Turn on Bluetooth
  • Try again

Still not working, reboot the phone and try again.

If none of those steps work, it may be the pod. But try everything one more time before giving up.

"},{"location":"troubleshooting/pod-pairing/#eros-with-rileylink","title":"Eros with RileyLink","text":"

The placement of the pod and the RileyLink relative to each other is a critical variable because the pod operates in a low-power radio mode during pairing which can lead to a number of potential faulty and half-paired pod situations, particularly with earlier versions of Loop.

How close should they be? Most people assume \"the closer the better\", but it has been measured that if the RileyLink and pod are too close together, the RileyLink may not be able to pick up the pairing response. The current recommendation is for the RileyLink to be placed a few inches to the side of the pod being paired.

If Pair fails, move a bit and RETRY

  • If the Pair operation is not succeeding, try repositioning the relative placement of the RileyLink and the pod multiple times. A little closer together if you had them far apart? A bit farther apart if they were really close? RileyLink on its side? Try standing it up with the antenna pointed to the ceiling.
  • If the pairing is still unsuccessful with multiple repositioning attempts, move yourself, the RileyLink, and the pod to another area/room (preferably away from other radio frequency signals that might be interfering), and try Pair again. Again don't be shy to try repositioning the RileyLink and pod's relative position, if needed, in this new area/room too.
  • If you have another available RileyLink, you can also try pairing using that RileyLink instead.
"},{"location":"troubleshooting/pod-pairing/#step-5-eros-pod-pairing-recovery","title":"Step 5: Eros Pod Pairing Recovery","text":"

When you have a pod that continues to appear non-responsive after several retried Pair attempts, it may be possible to recover by forcing Loop to start the pairing process from the beginning.

This section is for Eros pods

  • This section was last updated for Loop version 2.2.x
  • The error messages may be different and some steps might not be effective
  • This section remains for reference, with no guarantees.

To start we will have to press the Cancel button in the upper right corner of the pairing screen. Depending on which state the pod is stuck at in the pairing process...you'll see one of two screens after you select the Cancel button. Follow the directions (Step 5A vs Step 5B) for whichever screen corresponds to what you see after pressing Cancel.

  • Step 5A \"Switch from Omnipod Pumps\": You press Cancel and Loop will send you back to the Pod Settings screen to do the \"Switch from Omnipod Pumps\" method
  • Step 5B \"Deactivate\": You press Cancel and Loop will display a screen giving the option to \"Deactivate\"
"},{"location":"troubleshooting/pod-pairing/#step-5a-switch-from-omnipod-pumps","title":"Step 5A \"Switch from Omnipod Pumps\"","text":"

If you press the Cancel button and see a screen like below, you're going to select Switch from Omnipod Pumps in red. While this appears to confirm that you want to stop using the Omnipod, we will be adding pods back soon. Don't worry.

Don't fret. None of your Loop settings including the basal schedule and delivery limits, will be lost deleting the Omnipod pump. Select Delete Omnipod to proceed which will take you back to the Loop home screen. From here, select the gear icon at the bottom right to go to the Loop \u2699\ufe0f Settings page. Then select Add Pump in blue and then select Omnipod from the Add Pump list displayed.

Verify that the green LED on the RileyLink goes on and off as you touch the switch for RileyLink you are using indicating a successful Bluetooth connection between the RileyLink and your iPhone. Leave the RileyLink enabled with its green LED and slider turned on, and then touch the Continue button on the bottom. The Pod Settings screen should have the previous Basal Rates and Delivery Limits in effect from your previous run which can be verified at this time. Once ready, select Continue at the bottom of the screen.

Finally, you will be back to the Pod Pairing screen.

Instead of filling a new pod with insulin, attempt to pair again using the original pod which was previously filled but unable to complete the pairing process successfully. That pod should still be occasionally giving reminder beeps. Place the RileyLink a few inches to the side of the pod and press the Pair button at the bottom of the screen and hopefully, Loop will be able to successfully pair this time after starting from a fresh slate. If this pairing attempt is still unsuccessful, remember to still exhaust repositioning and Step 4 options before giving up on that pod. If it really won't pair after all that...then mark that loser pod with a Sharpie-drawn sad face and follow the directions in Step 3's colored box so that you don't end up with multiple beeping pods around accidentally.

"},{"location":"troubleshooting/pod-pairing/#step-5b-deactivate-pod","title":"Step 5B \"Deactivate pod\"","text":"

If you press the Cancel button and see an option for \"Deactivate pod\", we're going to do a little differently than Step 5A.

You might lose your pod by attempting this procedure

This is a point of no return for certain pod pairing situations and it is possible that the pod will be lost by attempting this procedure depending on the pod state. Some will recover fine, others may not. Since you can't know in advance if you might lose the pod, it is important to have already exhausted other possibilities described above in Steps 1-4 to try pairing. Specifically, (1) attempting to pair several times using varied relative positions of the RileyLink and pod (2) trying the pairing again but in a different room/location that might have less wireless interference, and (3) verifying your RileyLink is connected and functioning correctly.

For this next part, we want to make sure that the pod doesn't accidentally receive the deactivation command we are about to use. We want Loop to do the command...we just really don't want the pod to hear it. There are two ways we can keep the pod from hearing it, either (1) prevent the RileyLink from hearing Loop's command (and thus the command cannot reach the pod) or (2) prevent the pod from hearing the command from RileyLink. To accomplish our keep-the-pod-ignorant goal, you can try either option like so:

  1. Prevent RileyLink from hearing: Turn your RileyLink off temporarily at its physical switch. Some people worry about accidentally breaking their RileyLink switch, and if that's you...you can instead put the RileyLink far away from your iPhone or put the RileyLink in the microwave. That will keep the RileyLink from hearing the Loop's deactivate pod command. If RileyLink can't hear it, then your pod won't receive it.
  2. Prevent the pod from hearing: Move the beeping pod to a place where the pod is incapable of hearing the command. There are several options depending on what works for you:
    • Put the beeping pod far away...\"shouldn't be able to hear those beeps anymore\" kind of distance.
    • Put the pod in a not-turned-on-but-door-is-closed microwave.
    • Put the pod in a Faraday bag, if you own one.

Ok. Have the pod nice and ignorant? Good. Now press the \"Deactivate Pod\" button. It will take a few attempts, and you will see some failure messages about how the deactivation failed (of course it did...we hid the pod!) Eventually, you'll be given a \"Continue\" button that you'll want to use.

Press the \"Continue\" button. The instructions start with \"fill a new pod with insulin\"...BUT DO NOT! Instead, bring that beeping pod back to the hearing range. Turn that RileyLink back on if you turned it off. Once you get the RileyLink on and the pod back in range, you'll just press the Pair button and hopefully you'll find success with the process. If this pairing attempt is still unsuccessful, remember to still exhaust repositioning and Step 4 options before giving up on that pod. If it really won't pair after all that...then mark that loser pod with a Sharpie-drawn sad face and follow the directions in Step 3's colored box so that you don't end up with multiple beeping pods around accidentally.

"},{"location":"troubleshooting/pod-pairing/#step-6-help-improve-pod-pairing-process","title":"Step 6: Help improve pod pairing process","text":"

To help fix pairing bugs, some improvements have also been made in our ability to save the communications between the pods and Loop app during the pairing process. So, please help us leverage these new improvements and better squash bugs.

If you run into any pairing problems, which required Step 5A or Step 5B to be able to pair, or you had a pod that had to be abandoned, it would be helpful to generate an \"Issue Report\" after you finally get a pod paired (whether it was the original pod or if a different pod) and then post the resulting \"Loop Report\" on Zulipchat here with a short explanation of what happened.

"},{"location":"troubleshooting/pod-pairing/#what-about-other-pod-start-up-failures","title":"What about other pod start-up failures?","text":"

If you have a pod that has already started the priming operation and then has problems either finishing the priming operation or the cannula insertion, review the app crashed after pairing started and before cannula insertion to see if you can save the pod.

If a pod begins to alarm (has a fault) during priming or cannula insertion, the pod is no good and it should be deactivated and disposed of properly.

"},{"location":"troubleshooting/pod-pairing/#what-about-that-insulin","title":"What about that insulin?","text":"

If you have the misfortune of losing a pod during pairing, you can opt to not waste the insulin in that pod. Simply use the same syringe and same fill port on the pod to suck the insulin OUT of the loser pod.

If you do that, good practice is to make sure that you get that loser pod far away from the process as you go forward. Mark a big \"X\" on the failed pod and put it in a microwave, or very far away from you, so that it can't interfere with subsequent pod pairing attempts.

"},{"location":"troubleshooting/pump-errors/","title":"MDT Pump Errors","text":""},{"location":"troubleshooting/pump-errors/#medtronic-pump-errors","title":"Medtronic Pump Errors","text":"

The Medtronic pumps are used and typically not under warranty. Use this section at your own risk. However, that said, some of the most common pump errors are repairable, or not actually a real problem.

"},{"location":"troubleshooting/pump-errors/#a21-error","title":"A21 error","text":"

This error message is common when a pump has been stored for some time without a battery. Most pumps will show an A21 error when you first purchase them on the used market. Not a big deal. Press the down arrow (it also has the symbol of a light bulb on it) and the pump screen message will scroll down to let you know how to clear that error message (press ESC then ACT). If the message is coming up on a pump that hasn't been in storage, pull the battery out and replace it with a fresh, new battery. Chances are your battery or battery cap is old. Look for signs of dirt or rust in the battery cap, give it a little cleaning.

Display Tip

When the pump screen has a little black/white bar on the right side, that is a scroll bar. Use the arrow keys on the right of the pump screen to scroll and see the additional information.

"},{"location":"troubleshooting/pump-errors/#batt-out-limit","title":"Batt Out Limit","text":"

This error message \"battery out of limits\" has to do with the internal pump battery, not the AAA battery you replace. The internal battery cannot be replaced, and unfortunately also has a finite lifespan. The error message is more of an annoyance than a true problem. You can try to change the AAA battery faster. But, the worst-case scenario is that you'll have to re-enter the time and date when you get this message more often. (Don't forget to use RileyLink to set the time after you get this message.)

"},{"location":"troubleshooting/pump-errors/#button-error","title":"Button Error","text":"

The Button Error message usually happens from water, moisture, or dust getting under the pump's button pad and causing button(s) to fail. The fix luckily is quite straight-forward and takes less than 30 minutes. Check out the fix here for a YouTube video or here for photo gallery. There is also a detailed page in the OpenAPS docs.

The solution involves simply prying up the button pad's sticker face to expose the layers beneath.

You can see some evidence of crud/rust on the underside of this button pad which caused the button error.

After you finish your fix, another excellent idea is to make sure you add a length of clear packing tape across the front face of the pump to prevent errant water or dirt from having easy access to the button pad seams.

"},{"location":"troubleshooting/pump-errors/#crackmissing-piece-repairs","title":"Crack/Missing Piece Repairs","text":"

Another common issue on these Medtronic pumps are cracks and/or missing bits of plastic near the battery cap or reservoir sleeve. You can repair these fairly easily. For filling small cracks, Testor's plastic cement or Gorilla epoxy are good choices.

For more extensive repairs to replace missing chunks of plastic, Gorilla epoxy or Sugru are excellent choices.

You can use teflon thread tape on the battery cap to make sure the epoxy or Sugru don't stick to the battery cap, but still recreate the threads. The first photos are of a Sugru repair and second set of photos are Gorilla epoxy repair.

"},{"location":"troubleshooting/pump-errors/#motor-error","title":"Motor error","text":"

Often a motor error is the result of a poorly seated reservoir or tubing cap. If you get a motor error, the first thing you should do is detach from your infusion site. Remove and reseat the reservoir, prime again, and see if the motor error resolves. If it does not, try replacing the tubing cap on the reservoir (new tubing). If that does not resolve the motor error, also replace the entire reservoir.

"},{"location":"troubleshooting/pump-errors/#a33-error","title":"A33 error","text":"

Safety warning

If you get this error, DO NOT push on the bulged-out end cap. Always detach your tubing from your infusion set before addressing this error message. If you push on the end cap in an attempt to get it back flush, you may deliver a dangerous amount of insulin mistakenly.

This error is a bit more involved to repair. The problem is that there is a loose drive support cap. Most of the time this error message will appear during a priming event as the end cap of the drive will slip, releasing the ability of the reservoir plunger to get pressure to deliver insulin. The pump senses the lack of pressure and delivers the A33 error.

The solution is to UNHOOK from your site. See the warning above. Remove the reservoir and put your finger inside the reservoir sleeve. Push on the drive so that the end cap is pushed out the most possible. This will give you the most surface area possible to place the super glue GEL that you will use. (don't use regular super glue...it must be gel.) Remove the sticker that covers the end cap, and save it for later because you can reattach it when the repair is completed.

With the end cap pushed out, take some glue gel with the toothpick and apply it on the outside of the popped-out cap. Be generous cause you can do this only once. Once you are done take a napkin and press hard the cap toward the pump so it can go back inside and keep it pressed for a few seconds. Then remove all the small parts of the napkin that has glued to the pump. Leave the pump to dry for about 10-15 minutes.

Now to test whether the pump was glued well. You have already waited about 10-15 minutes so put your finger back in and press hard the plunger. If you glued it well, the end cap will not move. If the cap goes out again, you have to glue it one more time. If all looks well, put some glue back on top of the pump cap and reattach the sticker that was removed to start.

"},{"location":"troubleshooting/pump-errors/#a32-and-e22-error-loop","title":"A32 and E22 error loop","text":"

From what we know, this set of error codes seems like a pump killer. A call to Medtronic support gave this less-than-hopeful information:

A32 - failure of flash memory E22 - software re-installation is necessary

We don't have any reports of a good fix for these error codes. When seen, usually the E22 error comes up and as soon as it is cleared, the A32 error comes up. And the loop continues with a pump restart.

"},{"location":"troubleshooting/red-loop/","title":"Red Loop","text":""},{"location":"troubleshooting/red-loop/#red-loop-overview","title":"Red Loop Overview","text":"

This page provides help if your Loop icon is red and Loop is not working or only working sometimes.

With Loop 3 - clicking on the Loop icon on the main screen tells you the last time Loop completed, but you need to look at the Pump Status Icon and the Glucose Status Icon for more information. For example, when Glucose is stale (more than 15 minutes old), the Glucose icon shows \"- - -\". For example, when the Pump is having a communication issue, you will see a No Signal icon.

With Loop 2.2.x - clicking on the Loop icon on the main screen provides an error message. If you understand it, great...that should help you fix the problem. If not, grab a screenshot so you can ask for help from a mentor.

Omnipod Users

Do not pull a pod when there is a red loop.

  • Usually the problem is with Loop, not the pod
  • A new pod won't fix a Loop (Bluetooth or RileyLink communication problem)

There are a few times when it is the pod - but try all the steps on this page first.

Medtronic Users

You must select Insulin Type on your pump settings screen after updating from Loop 2 to Loop 3 and completing the onboarding. Without an insulin type, closed loop will not work.

A Red Loop icon means that Loop has not completed a cycle for 15-minutes or more and this is normally because of a communication break-down with one of the systems listed below.

"},{"location":"troubleshooting/red-loop/#typical-causes-for-red-loop","title":"Typical Causes for Red Loop","text":"

Some of the reasons listed below cause Loop to go Red and stay Red until you fix it. Others will cause intermittent Red Loops that come and go.

  1. Reset Loop-to-Pump Communications
  2. Continuous Glucose Monitor (CGM)
  3. Apple Health
  4. Background App Refresh is not enabled for Phone, Loop and/or CGM
  5. Nightscout (optional service)
  6. Phone Storage is Full
  7. Lost Pod Information If running Loop 2.2.x or FreeAPS, read this section first
"},{"location":"troubleshooting/red-loop/#lost-pod-information","title":"Lost Pod Information","text":"

We think this was fixed with Loop 3. If you are running Loop 2.2.x or FreeAPS:

  • Before attempting to resolve a red-loop with a phone reboot; please review this section. It can affect the stored CGM information as well as the stored pump information.

Be Careful with Phone Reboots with Loop 2 or FreeAPS

If you are using an Omnipod, then before rebooting the phone, make sure it is absolutely necessary - try all other methods first. Be prepared to check that the pod is still communicating with Loop following the reboot. If this rare event happens to you, please report it, save and post a Loop Report and be prepared to put on a new pod and possibly re-enter your CGM information.

This could happen to someone using a Medtronic pump, but the consequence is less of a concern because the pump information is not modified as frequently as for Omnipod users.

"},{"location":"troubleshooting/red-loop/#reset-loop-to-pump-communications","title":"Reset Loop-to-Pump Communications","text":"

If the indication is one of these (or something similar), it can probably be fixed by resetting the Loop-to-Pump communication. For DASH, this is Bluetooth only. For Eros or Medtronic, it is a combination of Bluetooth and the RileyLink compatible device.

  • pump history is too old
  • no rileylink could be found
  • pod cannot be reached
  • the Unable to Reach Pump modal screen is visible

Do these steps until one of them fixes the issue:

  • Turn off Bluetooth on your phone and then turn it right back on again.
  • Close your Loop app (upswiping it in the iPhone's app selector) and reopen it.

  • Eros or Medtronic: Turn your RileyLink off/on at its physical power switch located on the side of the RileyLink.

    • If you have a different device, make sure you know how to power-cycle the device.
    • For RileyLink (without wireless charging) use a small pointy object to carefully move the slider away from the charging port and then back up towards the charging port. A paperclip on the keyring can provide the help you need to reach the switch in the recessed case, and double as a screaming pod silencer tool.

This should restore a green Loop within 5 minutes. If you're impatient and are using pods, you can tap on Play Beeps. With Medtronic, you can attempt to suspend/resume the pump. If this is successful, you've established communication again.

Last thing to try is:

"},{"location":"troubleshooting/red-loop/#power-cycle-your-phone","title":"Power cycle your phone.","text":"
  • This suggestion is last because of a rare, intermittent issue (with iOS 15 and Loop 2.2.x) in which power cycling the phone does not load the latest version of Loop information
  • This was fixed with Loop 3
  • Click on the Lost Pod Information link for more information

If this was not successful, check out the Pump is Not Responding section.

"},{"location":"troubleshooting/red-loop/#cgm-values-are-not-being-collected-by-loop","title":"CGM Values Are Not Being Collected by Loop","text":""},{"location":"troubleshooting/red-loop/#new-transmitter","title":"New Transmitter","text":"

If you recently changed a transmitter, you need to also update your Loop settings to reflect the new transmitter ID. Go to the CGM section of Loop settings and Delete CGM (it's a button on the bottom of that page). Then use the Add CGM in Loop settings to include the new transmitter ID.

If you fail to update your Transmitter ID in Loop and you also left Share Credentials in Loop (not recommended), you will see messages such as: Failed to decode SGV when the Share server cannot be reached. That's your notice to update the Transmitter ID (or if you think you already did - check for typos in data entry).

"},{"location":"troubleshooting/red-loop/#delete-share-account","title":"Delete Share Account","text":"

Finally, we see a lot of errors reported because people have problems with their Share server information in Loop app. Please delete your Share account information from within Loop settings. In other words, the credentials portion of the Share account info, as shown in the screenshot below, should say Tap to Set and not have your account info. It is unnecessary to have this portion filled out as local, non-internet spying of a transmitter is the preferred CGM source anyways. In fact, by leaving this information out, it will help you remember to change your transmitter ID when you change transmitters because CGM data won't appear in Loop. By not including Share account in Loop, you will prevent yourself from accidentally becoming internet dependent.

"},{"location":"troubleshooting/red-loop/#firefly-style-transmitter","title":"Firefly-style Transmitter","text":"

Leaving this in for historical interest only. It illustrates the need to keep Loop up-to-date. Who knows what the next hardware change will be. Enough time has passed that everyone's Loop code should be newer.

In July 2019, we started to see a new style of Dexcom G6 transmitters on the market. These new transmitters required a rework of some of the Loop's code to continue to \"spy\" on the transmitter. Without that update, your Loop can not get CGM data unless it is pulling from Share servers (which is not a recommended mode of operation). So, download fresh code for your Loop app if you have a new transmitter type and haven't downloaded since July 2019.

"},{"location":"troubleshooting/red-loop/#apple-health","title":"Apple Health","text":"

Make sure both the Loop app and the Dexcom app have permission to write to Apple Health by checking the Apple Health Permissions

In the early days of iOS 14, there were problems with the Apple HealthKit. The consequence is that some people's database was corrupted. If you tap on the Heart Icon on your phone to go to Apple Health and display data and it is very slow to respond - or never responds, you probably need to get rid of a corrupted database and start fresh. Be sure to go Open Loop if this is needed. Please get help from your favorite Loop Social Media group or from Apple support in this case.

"},{"location":"troubleshooting/red-loop/#background-app-refresh","title":"Background App Refresh","text":"

If you have not enabled background app refresh on your phone, then Loop is likely to stop communicating as soon as the phone is locked.

  1. Phone Settings -> General -> Background App Refresh -> enable
  2. Then scroll down until you find Loop and make sure the green slider is enabled
  3. While you are there - check your CGM app as well

For iOS 15, there is a new feature described by Dexcom

  1. Phone Settings -> Screen Time -> choose Always Allowed -> select an app, tap the plus icon to add to Always Allowed list
    • add Dexcom
    • add Loop
"},{"location":"troubleshooting/red-loop/#nightscout","title":"Nightscout","text":"

If you added your Nightscout URL to Loop and are uploading information to Nightscout, make sure the communication is working properly. For short-term interruptions, Loop will store information to upload to Nightscout later. But if too much information builds up, Loop can slow down and in some cases have a Red Loop.

  1. Check to see that internet service (WiFi or Cell) is operating
  2. Check that Nightscout database size isn't full (more details below)
  3. If Red Loops are resolved by removing the Nightscout URL from Loop; you need to figure out if it's the connection or the database or some other issue

If you opted for the free DIY Nightscout, you will need to clean your database once or twice a year. Follow the Nightscout Database cleanup steps. Make sure you are periodically checking your database size (and that the dbsize keyword is in your ENABLE list and cleaning it.

"},{"location":"troubleshooting/red-loop/#phone-storage-is-full","title":"Phone Storage is Full","text":"

This was reported by a user in November 2021. His phone storage was almost full and the reported error messages for Loop was:

  • Sqlite Error: A Sqlite Error Occurred: (13) Database or Disk is Full

The error message from Dexcom was not as helpful. If you see this, check your phone storage:

  • The Dexcom G6 app has stopped working. Please delete the app from your device and redownload it from the App Store

Solution: clear up space on your phone.

"},{"location":"troubleshooting/red-loop/#other-reasons-for-red-loop","title":"Other Reasons for Red Loop","text":""},{"location":"troubleshooting/red-loop/#pump-is-not-responding","title":"Pump is Not Responding","text":"

The first step is to make sure the phone and if needed, the RileyLink compatible device, is not so far away from the pump or pod that they cannot communicate. Assuming you've addressed this, then you can move on to other steps.

Omnipod Loopers:

If the pod is screaming, it should still be able to communicate with Loop, but sometimes you need to restore communication so you can deactivate the pod and quiet it. Follow the steps below, just do it with the added \"noise\".

The Reset Loop-to-Pump Communications steps almost always fix the issue. It is possible that the pod really had stopped communicating, but try everything else before burning another pod.

Medtronic Loopers: If the pump is not responding with \"decoding\" errors or various other messages about pump responses. Try the following:

  1. Change pump battery. Low pump battery will cause radio communications to fail.
  2. Use the Change Time command in the pump menu to update the pump's clock. If you've accidentally changed the pump's time in the pump itself or if the pump time has drifted, this will get the Loop app and pump time back in sync.
  3. If using a x23 or x54 pump, try deleting all the IDs under the \"Other Devices\" submenu in the pump's \"Connect Devices\" menu. Then go to the RileyLink menu and use the MySentry pairing command to get a fresh ID issued. Follow the directions listed in the MySentry pairing command's screen to scan for devices. A fresh ID can help prevent recurring red loops for x23 and x54 users, particularly if they started to occur after a recent Loop update.
  4. Make sure the following are checked in the pump:
    • Your pump cannot be suspended. Resume insulin deliveries.
    • Temp basal type must be set to unit/hour, not percent, in pump's Basal menu.
"},{"location":"troubleshooting/red-loop/#resolving-frequent-red-loops","title":"Resolving Frequent Red Loops","text":"

Here's some things to check if you have frequent red loops:

  • Try deleting your Nightscout account from Loop settings and see if your Loop stops having red loops. If it does, then you'll need to assess what's going wrong in your Nightscout site and fix it. Most of the time, your database is getting too big and cleanup is required.

  • Is your RileyLink battery plugged in all the way on the board? One Looper recently posted that her RileyLink battery connection needed to be reseated after several years of service.

  • Has your RL been fully charged? Try charging your RL for an hour or two, make sure the red light comes on while charging. Try a new charger or cable.

  • Oddly, some people have found that turning off Siri integrations for Loop and Dexcom apps in your iPhone settings has helped. This may be coincidental, but if you're still having trouble, you might want to try it.

  • Check for sources of wireless interference. If you have a certain environment that seems to have more drops than others, it is likely that there is a source of wireless communication interfering with your Loop. Lots of Medtronic Loopers in a room together will often interfere with each other and get \"cross-talk\" red loop error messages. If it is a bedroom at night causing problems, try moving other wireless devices such as routers or baby monitors farther away from where you and your RileyLink compatible device.

  • In some cases, you may need to clean out Apple Health, or even reset your phone to factory defaults and reload all your personal information and then rebuild the Loop app. Before you do this, you may want to Post for Help (next section).

"},{"location":"troubleshooting/red-loop/#posting-for-help","title":"Posting for Help","text":"

Before you post on Looped group for help with a red loop, please make sure you've reset the RileyLink / Phone.

Before you post for help, please also check your Nightscout status including database size. This step is often overlooked and yet solves a lot of problems.

When posting for help, include two screenshots of Loop's main screen; one with the red loop's error message and the other just the plain Loop main screen. Include a detailed description of what you have tried doing from the troubleshooting list above. For example, state if you've double checked the transmitter ID, deleted the Share account info from Loop settings so that we can rule out some of the causes of CGM issues.

"},{"location":"troubleshooting/red-loop/#what-else","title":"What Else?","text":"

There are a few other things to consider:

  • RileyLink is broken
  • Battery has failed
  • OrangeLink has firmware 2.6
"},{"location":"troubleshooting/red-loop/#rileylink-is-broken","title":"RileyLink is Broken","text":"

How can you tell if your RileyLink has a problem? The answer is mostly within the LED lights that display on the board. Some information is listed below, but also review the FAQs at getrileylink.org.

If you have a different RileyLink compatible device, please check the appropriate site for troubleshooting help.

Red light: comes on during charging and will turn off/on periodically, while still plugged in, after charge is complete.

Green light: Indicates an active BT connection with the phone. You want the green light to stay on all the time on the RileyLink. If the green light is not on, then make sure your iPhone's bluetooth is still switched on.

Blue light: The blue light will flash off/on periodically when the RileyLink and pump are actively communicating...it should NOT be always on. If your blue light is stuck on, that is an indication of a problem on the board. Try looking for signs of damage or debris that may be causing a short on the board. Clean the board with rubbing alcohol (unplug the battery first). If you still can't get the blue light off, then contact GetRileyLink for help or check out RileyLink Compatible Devices for replacement options.

"},{"location":"troubleshooting/red-loop/#battery-has-failed","title":"Battery has Failed","text":"

Both RileyLink and EmaLink use LiPo batteries. If they stop holding charge for as long as they used to, or if they swell (often first noticed as bowing of the case), stop using the battery and replace it as soon as possible.

OrangeLink uses regular batteries, so just change them out.

"},{"location":"troubleshooting/red-loop/#orangelink-firmware","title":"OrangeLink Firmware","text":"

One version of the OrangeLine firmware did not communicate well with Loop (or Android APS).

If you have FW 2.6 on your OrangeLink or OrangeLink Pro, please upgrade to FW 3.2 as soon as possible.

"},{"location":"version/build-dev/","title":"Build Dev","text":""},{"location":"version/build-dev/#building-development-code","title":"Building Development Code","text":"

No matter the method used to build Loop-dev: GitHub actions or git commands, you are testing development code. Please read this link now before continuing.

  • What's going on in the dev branch

There are several methods to build Loop-dev. First review the general information on this page then choose the link for the method of your choice:

"},{"location":"version/build-dev/#update-frequently","title":"Update Frequently","text":"

While Loop-dev is under active development, you should monitor zulipchat and update frequently. Sometimes the dev branch is quiet for a month or more and other times it gets updated daily. Please pay attention.

Checking for updates every week is a good idea. Also - subscribe to all the streams on Loop Zulipchat to make sure you don't miss critical information.

"},{"location":"version/build-dev/#loop-dev-version","title":"Loop-dev Version","text":"

The version of code that shows up under the Loop Settings screen does not change when the dev branch is modified.

If you need help with your app, the mentors need more information. Please issue a Loop Report when asking for help. Refer to Support for how to issue a Loop Report. If you want to keep track yourself, refer to Identify Loop-dev Version

  • Loop Version Numbering
"},{"location":"version/build-dev/#identify-loop-dev-version","title":"Identify Loop-dev Version","text":"

The version of code that shows up under the Loop Settings screen will remain fixed until Loop-dev is released. In order to identify which version of dev you have on your phone, you need the commit.

The commit is identified by a 7-digit alphanumeric code. That code was also appended to the folder name of the downloaded code under Downloads/BuildLoop as shown in the graphic above. You can use finder to view the folder name after the script completes. It also appears in the Loop Report, refer to Support for instructions on issuing a Loop Report. After you issue the Loop Report, look at the workspaceGitRevision number near the beginning of the report.

"},{"location":"version/build-dev/#build-loop-dev","title":"Build Loop dev","text":"
  1. For the Build with Browser method
    • Build dev with Browser
  2. For the Build with Mac method:
    • Build dev with Mac
"},{"location":"version/build-time-flag/","title":"Build-Time Flag","text":""},{"location":"version/build-time-flag/#overview","title":"Overview","text":"

Build-time features are not available with Loop 2.2.x.

With Loop 3, some features are enabled or disabled by default but can be modified by adding a \"flag\" in the LoopConfigOverride.xcconfig file.

If you use Build with Browser, these build-time features can be added to your copy of the LoopConfigOverride.xcconfig file. Use the pencil icon in that file on your copy of LoopWorkspace and then commit the change.

If you use the Build with Mac Method, this is the same file used to automatically sign all your targets. You can edit the version in your LoopWorkspace folder (it shows up as the top item in the Xcode folder view) - or - if you use the build script, you can edit the copy found in ~/Downloads/BuildLoop after the first time you use the script. For that second case, the \"flags\" you add in ~/Downloads/BuildLoop/LoopConfigOverride.xcconfig are applied to all downloads created with the script.

These flags are always upper case with underscore separating words for clarity, for example MY_EXAMPLE_FLAG. If you have more than one flag, they are separated by a space. Do not enter a line break between selections; in other words, do not hit return or enter. Xcode will automatically word-wrap the line for clarity. All values need to be on a single line.

New Instructions

The instructions are more robust than earlier instructions that had you editing a line instead of adding new ones.

Copy the text below, add it to the end of your LoopConfigOverride.xcconfig file and then insert the desired flags in place of MY_EXAMPLE_FLAG. If you want more than one flag, separate them by a space.

Lines to add to end of file
// Add Build-Time features to compilation conditions\nSWIFT_ACTIVE_COMPILATION_CONDITIONS = $(SWIFT_ACTIVE_COMPILATION_CONDITIONS) MY_EXAMPLE_FLAG\n

Code Before Modification

// Put your team id here for signing\n//LOOP_DEVELOPMENT_TEAM = UY678SP37Q\n

The example below is for someone who is using a Free Developer ID - which does not support Siri.

Code After Modification

// Put your team id here for signing\n//LOOP_DEVELOPMENT_TEAM = UY678SP37Q\n\n// Add Build-Time features to compilation conditions\nSWIFT_ACTIVE_COMPILATION_CONDITIONS = $(SWIFT_ACTIVE_COMPILATION_CONDITIONS) SIRI_DISABLED\n

List of some flags and what they do:

FLAG PURPOSE SIRI_DISABLED Required to build Loop from Xcode with a free developer account ADULT_CHILD_INSULIN_MODEL_SELECTION_ENABLED The choice for Child Model is enabled in Therapy Settings. Please read Enable Child Model. REMOTE_OVERRIDES_DISABLED Remote commands: override, carbs or boluses will not be accepted even if all the Remote Command requirements are configuredIf you do configure this and later try to set up remote commands, they will not work and there is no error message. Remote Errors: Loop REMOTE_OVERRIDES_DISABLED OBSERVE_HEALTH_KIT_CARB_SAMPLES_FROM_OTHER_APPS_ENABLED Turns on ability for Loop to read third party carb entries. You must also make sure Health permissions allow Loop to read carbs from Health. Be vigilant if you select this; added carbs lead to added insulin dosing when closed loop is enabled SHOW_EVENTUAL_BLOOD_GLUCOSE_ON_WATCH_DISABLED The Apple Watch screens show current glucose, trend arrow and eventual glucose by default. This flag disables the display of eventual glucose on the watch if you find the display distracting. PREDICTED_GLUCOSE_CHART_CLAMP_ENABLED Chart Clamp ALLOW_ALGORITHM_EXPERIMENTS dev branch onlyThis is enabled by default to show Algorithm Experiments below the Therapy Settings row. This enables the user to separately enable or disable Glucose Based Partial Application and Integral Retrospective Correction"},{"location":"version/build-time-flag/#chart-clamp","title":"Chart Clamp","text":"

What the heck is a chart clamp? It means the range displayed will not be smaller than the clamp but it can be bigger.

Loop automatically scales the glucose charts based on the history shown. Some people don't like to see the vertical axis changing, so they turn on the \"clamp\".

When the PREDICTED_GLUCOSE_CHART_CLAMP_ENABLED build time flag is added:

  • the range shown is never smaller than glucoseChartDefaultDisplayBoundClamped
  • 80 to 240 mg/dL (4.4 to 13.3 mmol/L)

When you do not add that build time flag:

  • the range shown is never smaller than glucoseChartDefaultDisplayBound
  • 100 to 175 mg/dL (5.6 to 9.7 mmol/L)

If glucose within the display history is outside of the bound, the graph range expands to include that glucose level. This prevents glucose readings from being \"hidden\".

You can customize chart display settings if you want. The original lines of code are shown below. You will need to read the rest of this page to figure out how to modify these to meet what you prefer. If you can't figure this out - reach out for help.

  • Module: Loop
  • Loop 3
    • Folder: Loop/Models
    • File: LoopConstants.swift
    • Lines: 32 to 45
    // MARK - Display settings\n\n    static let minimumChartWidthPerHour: CGFloat = 50\n\n    static let statusChartMinimumHistoryDisplay: TimeInterval = .hours(1)\n\n    static let glucoseChartDefaultDisplayBound =\n        HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 100)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 175)\n\n    static let glucoseChartDefaultDisplayRangeWide =\n        HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 60)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 200)\n\n    static let glucoseChartDefaultDisplayBoundClamped =\n        HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 80)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 240)\n
"},{"location":"version/build-time-flag/#enable-child-model","title":"Enable Child Model","text":"

Loop 3, by default, does not include the concept of child versus adult for rapid-acting insulin, i.e., Humalog, Novalog and Apidra.

  • The child model can be enabled following the directions above, adding ADULT_CHILD_INSULIN_MODEL_SELECTION_ENABLED to the LoopConfigOverride.xcconfig file and rebuilding
  • Insulin Model is then found in the Therapy Setting section of Loop 3 with Adult selected by default
  • Insulin Type continues to be associated with the pump and can be modified in the Pump Settings screen
"},{"location":"version/code-custom-edits/","title":"Custom Edits","text":""},{"location":"version/code-custom-edits/#build-then-customize","title":"Build then Customize","text":"

For new Loopers, please build the code before you make any changes. Start with Open Loop and familiarize yourself with the interface. Later, you can make the customization(s) you desire and build again. The second build will be much easier than your first build.

These customizations require you modify the Loop app code and then build the app after making these customizations. This page supports version 3 and greater for the Loop app.

"},{"location":"version/code-custom-edits/#customization-options","title":"Customization Options","text":"

Read about the customizations on this page before applying them.

You take responsibility

You are responsible when you decide to use customizations.

Be sure to report what changes you made if you need to ask for assistance with your app.

Some customizations are the same for everyone and have been prepared for easy use. Refer to the build method that you use for information about applying these prepared changes - the same set is available for both build methods.

  • Customize with Browser
  • Customize with Mac

Other customizations require that you create your own personalized version.

  • On this page are instructions for what modifications are required to your code to achieve a personalized customization (regardless of build method)
  • On Version: Build-Time Flag are details about how to change the default settings for the build-time flags by editing the LoopConfigOverride.xcconfig file.
"},{"location":"version/code-custom-edits/#instructions-for-finding-the-lines","title":"Instructions for Finding the Lines","text":"

The instructions on this page identify the module, Key_Phrase or file and line numbers required to locate the code you need to modify.

Why do I have to jump between pages?

  • The code changes are defined on this page
  • The method to make code changes depends on build method and are found at:
    • Custom Edits with Browser
    • Custom Edits with Mac

Line numbers may change

Every effort will be made to update the line numbers as the code is updated, but there may be times where the screenshots and line numbers differ from the current version of Loop code.

  • You may notice some customizations list line numbers for different branches

  • If you cannot identify a line that looks exactly like the example - do not guess - go to your favorite social media group and ask for help

  • Sometimes there is a bigger change than just line numbers. The git software is really good about finding the \"right\" code that is just at a different line number. When you see the notation Stable: Changed on date, that means you must select the correct version when making your personal customization depending on which version you are modifying.

This page is broken into two halves:

  • Custom Edits Required:

    • The first half of this page is for customizations that require you to edit your own code

  • Custom Edits Optional:

    • The second half of this page provides instructions for some of the prepared customizations included in the Loop and Learn: Customization Select Script
    • Some people prefer to make all their own edits

For each customization, you will be given landmarks to find the correct location in the code. You can choose to search using the Key_Phrase or navigate to the file in the folder structure and look for the line number.

"},{"location":"version/code-custom-edits/#key_phrase","title":"Key_Phrase","text":"Example of a Key_Phrase
use the copy button at right, paste into search\nThe copy button for this exampe is just for practice\nDo not paste the result anywhere\n

To search using the Key_Phrase (see graphic above for an example):

  • A copy button is available when you hover your mouse in the right-hand side of the block below the title Key_Phrase; click on it to copy the phrase into your paste buffer
  • You can paste this into the search function of the tool you are using if desired (warning, you may have to hit back-space to remove a return character from the pasted text)
  • Alternatively, navigate to the required file using Module, Folder, File and line number
"},{"location":"version/code-custom-edits/#module-folder-file","title":"Module, Folder, File","text":"

Stability Information Added

If a customization needs to be modified to work with the dev branch, that will be noted. This means a change that is more than a line number. Instead it is a change that requires a new customization.

For those using the Browser Build method for main branch, this means you will need to use Create branch if needed to create a special branch to prepare a new version of this customization. If you already created a personal customization earlier (before the date noted), you can keep using that customization with main.

For your convenience, see Not Stable List.

Each customization provides the Module, Folder and File bullet below the key phrase.

  • Module: Loop
  • Folder: Loop/subfolder1/subfolder2/etc.
  • File: filename.swift, line number(s)
  • Stable: \"Yes\" or \"Changed on date\"

The customizations below show the original line of code that you will be changing.

There may be a figure illustrating the change.

Below the figure, the original, and in some cases, the modified code will be displayed as text.

  • Sometimes that line is long and you may need to use the scroll bar to see the entire line in LoopDocs
  • In most cases, an example customization is shown to assist you in deciding how to edit the line to meet your needs
"},{"location":"version/code-custom-edits/#not-stable-list","title":"Not Stable List","text":"

This list indicates personalized customization that differ between main and dev

  • 2024 Feb 19: Glucose Guardrails
  • 2023 May 29: Adjust Future Carbs Time Interval
"},{"location":"version/code-custom-edits/#custom-edits-required","title":"Custom Edits Required","text":""},{"location":"version/code-custom-edits/#default-carb-absorption-times","title":"Default Carb Absorption Times","text":"

Loop\u2019s default carb absorption times are based on the high, medium, and low glycemic index absorption curves presented in Think Like A Pancreas by Gary Scheiner. In prior versions of the Loop app, for example version 2.2.x, the lollipop (fast) icon was set for 2 hours, taco (medium) icon for 3 hours, and pizza (slow) icon for 4 hours. This is modified for Loop 3 to 30 minutes, 3 hours and 5 hours respectively. Some people prefer different values.

Do you want to know more? (Click to open/close)

The developers did this because they expect fast to only be used for rapid-acting low treatments. The medium and fast values are for moderate and higher-fat or large meals.

Key_Phrase
defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes\n
  • Module: Loop
  • Folder: Loop/LoopCore
  • File: LoopCoreConstants.swift
  • Line: 19
  • Stable: Yes

For example, if you wanted to change fast to be slightly longer, the edit would be as follows:

_Code Before Modification

public static let defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes = (fast: .minutes(30), medium: .hours(3), slow: .hours(5))\n

_Code After Modification

public static let defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes = (fast: .hours(1.5), medium: .hours(3), slow: .hours(5))\n

Note that if you change fast from 30 minutes to 1.5 hours, you must also change the indication before the parentheses.

"},{"location":"version/code-custom-edits/#adjust-maximum-iob-for-automatic-dosing","title":"Adjust Maximum IOB for Automatic Dosing","text":"

With version 3.2.0, a new safety feature was added. This limits automatic dosing so IOB is no more than two times the \\(\\mathit{maximumBolus}\\) set in your Delivery Limits. (The term automatic dosing refers to insulin the app automatically delivers above your scheduled basal rate.) Manual Bolus, where you initiate the bolus yourself, is not subject to this limit. Please read How do Delivery Limits Affect Automatic Dosing? for detailed information on how this safety feature works.

The default value (\\(\\mathit{2*maximumBolus}\\)) used for this feature is good for the majority of people who use the app. However, there are some individuals who might need to limit the size of any single bolus independent from the maximum IOB they want to set for their app. This is particularly true for those who find large boluses give rise to tunneling and the insulin leaks out along the cannula.

Key_Phrase
automaticDosingIOBLimit = maxBolus\n
  • Module: Loop
  • Folder: Loop/Managers
  • File: LoopDataManager.swift, line: 1690 (main), 1796 (dev)
  • Stable: Yes

The following example is for someone who limits a single bolus to 5 U but frequently needs to achieve an IOB of 15 U for meals. They want that level of IOB to be reached with automatic bolusing. In that case, they may want to modify the factor used to calculate \\(\\mathit{automaticDosingIOBLimit}\\).

Original Code: 

let automaticDosingIOBLimit = maxBolus! * 2.0\n

Modified Code Example: 

let automaticDosingIOBLimit = maxBolus! * 3.0\n

Because the automatic bolus amount is also limited by the partial application factor, it still takes a few cycles to reach the higher IOB of \\(\\mathit{3*maximumBolus}\\); but they can get there without manual intervention.

"},{"location":"version/code-custom-edits/#adjust-percent-bolus-for-automatic-bolus","title":"Adjust Percent Bolus for Automatic Bolus","text":"

If you are mostly happy with the Dosing Strategy of Automatic Bolus but wish it delivered more or less insulin during every Loop interval, then this customization is for you.

This customization changes the percent of the recommended bolus used for automatic delivery. The method for calculating that recommendation is not changed by this modification. The default value is 40% (0.4). It is recommended you take small changes of 0.1 at a time. Once you modify it once and try it out for a while, it\u2019s easy to go back and change it again.

Change just the number and double check that the value is less than 1.

Key_Phrase
let bolusPartialApplicationFactor\n
  • Module: Loop
  • Folder: Loop/Loop/Models
  • File: LoopConstants.swift
  • Line: 53
  • Stable: Yes

Code Before Modification

static let bolusPartialApplicationFactor = 0.4\n

Code After Modification to 50% of recommended insulin

static let bolusPartialApplicationFactor = 0.5\n

Do not exceed 1.0

This number should never be bigger than 1 (you\u2019d be getting more than Loop recommends). If you think you need more than 1, consider your settings and meal entries.

"},{"location":"version/code-custom-edits/#pods-add-extra-insulin-on-insertion","title":"Pods: Add Extra Insulin on Insertion","text":"

The default value is 0.0 U of extra insulin. If you use this customization, start with a small number and work your way up. If you are coming from manual podding and routinely gave yourself an extra bolus with your PDM at pod change time, you may not need nearly as much with Loop - be conservative.

Note that Loop does not include the amount of insulin in the prime or insertion steps in your IOB. The pod reports every pulse that it delivers to Loop. If you look in the Pod Settings insulin delivered row, that is the total delivered by the pod minus the (prime plus insertion) amounts. The only way to know that you successfully made this change is to count the clicks. Normal insertion is 0.5 U (0.5 U / 0.05 U per click = 10 clicks). So if you add 0.35 U to the \"extra\" value, you should get 0.35 / 0.05 = 7 extra clicks. In other words, 17 total clicks after you press insert.

This code change is found in one location for Eros Pods (called Omnipod throughout the app) and DASH Pods (called Omnipod Dash throughout the app). I tend to change both files, but if you're only using one kind of pod, that is really not necessary.

Key_Phrase
let cannulaInsertionUnitsExtra\n
  • Module: OmniBLE (DASH) or OmniKit (Eros)
  • DASH or Eros Pod (Loop 3 only)
    • Folder: OmniBLE/OmniBLE/OmnipodCommon (DASH)
    • Folder: OmniKit/OmniKit/OmnipodCommon (Eros)
    • File: Pod.swift, Line 82 (DASH); Line 87 (Eros);
  • Stable: Yes

Code Before Modification

public static let cannulaInsertionUnitsExtra = 0.0 // edit to add a fixed additional amount of insulin during cannula insertion\n

Code After Modification to add 0.35 U

public static let cannulaInsertionUnitsExtra = 0.35 // edit to add a fixed additional amount of insulin during cannula insertion\n
"},{"location":"version/code-custom-edits/#modify-the-guardrails","title":"Modify the Guardrails","text":"

The Therapy Setting Guardrails are for Loop 3 only.

"},{"location":"version/code-custom-edits/#glucose-guardrails","title":"Glucose Guardrails","text":"

If you build Loop 3 over a version of Loop 2.2.x or FreeAPS where the Correction Range is lower than the default value of 87 mg/dL (4.8 mmol/L), your app requires you to satisfy the new guardrail before you can save that Therapy Setting when you onboard.

Key_Phrase
Guardrail(absoluteBounds:\n
  • Module: LoopKit
  • Folder: LoopKit/Extensions
  • File: Guardrail+Settings.swift
  • Line: 12 for suspendThreshold
  • Line: 26 for correctionRange
  • Stable: Changed on 2024 Feb 19 Version after Update
"},{"location":"version/code-custom-edits/#version-before-update","title":"Version before Update","text":"

Code Before Modification

static let suspendThreshold = Guardrail(absoluteBounds: 67...110, recommendedBounds: 74...80, unit: .milligramsPerDeciliter, startingSuggestion: 80)\n

and

static let correctionRange = Guardrail(absoluteBounds: 87...180, recommendedBounds: 100...115, unit: .milligramsPerDeciliter, startingSuggestion: 100)\n

Modify the absoluteBounds to change the allowed ranges or the recommendedBounds to change the color of the numbers on the picker wheel.

Loop automatically converts from mg/dL to mmol/L. So you must enter values reasonable for mg/dL (18 times higher than for mmol/L).

"},{"location":"version/code-custom-edits/#version-after-update","title":"Version after Update","text":"

This update, merged into dev on 2024 Feb 19 was part of a larger fix to a problem when glucose units were mmol/L. The user could not select two values (min and max) that were the same and equal to the reported absolute range. This was a rounding problem going between mmol/L and mg/dL that has now been resolved. Part of the resolution was to modify the mg/dL absolute ranges to preserve the previously reported mmol/L absolute ranges.

Code Before Modification

static let suspendThreshold = Guardrail(absoluteBounds: (66.1)...(110.9), recommendedBounds: (73.1)...(80.9), unit: .milligramsPerDeciliter, startingSuggestion: 80)\n

and

static let correctionRange = Guardrail(absoluteBounds: (86.1)...(180.5), recommendedBounds: (99.1)...(115.9), unit: .milligramsPerDeciliter, startingSuggestion: 100)\n

Modify the absoluteBounds to change the allowed ranges or the recommendedBounds to change the color of the numbers on the picker wheel.

Loop automatically converts from mg/dL to mmol/L. So you must enter values reasonable for mg/dL (18 times higher than for mmol/L).

"},{"location":"version/code-custom-edits/#modify-guardrails-for-insulin-sensitivity-factor-isf","title":"Modify Guardrails for Insulin Sensitivity Factor (ISF)","text":"

Similar to the instructions for glucose guardrails above, but use this Key_Phrase and modify the absoluteBounds row, next line.

Key_Phrase
static let insulinSensitivity = Guardrail(\n
  • Module: LoopKit
  • Folder: LoopKit/Extensions
  • File: Guardrail+Settings.swift, line: 81
  • Stable: Yes
"},{"location":"version/code-custom-edits/#modify-guardrails-for-carb-ratio-cr","title":"Modify Guardrails for Carb Ratio (CR)","text":"

Similar to the instructions for glucose guardrails above, but use this Key_Phrase and modify the absoluteBounds row, next line.

Key_Phrase
static let carbRatio = Guardrail(\n
  • Module: LoopKit
  • Folder: LoopKit/Extensions
  • File: Guardrail+Settings.swift, line: 88
  • Stable: Yes
"},{"location":"version/code-custom-edits/#adjust-future-carbs-time-interval","title":"Adjust Future Carbs Time Interval","text":"

Loop 3 limits to 1 hours the amount of time in the future that carbs can be entered.

  • The Loop and Learn: Customization Select Script has a customization that changes this to 4 hours in the future
  • If you want something other than 1 hour or 4 hours, you must create a personal customization

The customization varies depending on whether you are building dev or main.

  • Module: Loop
  • Stable: Changed on 2023 May 29

The main branch:

  • Folder: Loop/Loop/View Controllers
  • File: CarbEntryViewController.swift, Line 438

The dev branch:

  • Folder: Loop/Loop/Models
  • File: LoopConstants.swift, Line 28

The changes required for this customization have changed several time for dev. The code provided in Version after Update is for the latest dev code, as of 2023 Aug 20.

"},{"location":"version/code-custom-edits/#version-before-update_1","title":"Version before Update","text":"Key_Phrase
cell.datePicker.maximumDate = date.addingTimeInterval\n

Default shown below (for maximum and minimum):

Code Before Modification

cell.datePicker.maximumDate = date.addingTimeInterval(.hours(1))\ncell.datePicker.minimumDate = date.addingTimeInterval(.hours(-12))\n

Change the maximumDate to the number of hours in the future you desire. Remember that Loop may increase insulin dosing for future carbs - make sure that they actually arrive.

The minimumDate is how far back in the past you can modify time. The default is 12 hours in the past.

"},{"location":"version/code-custom-edits/#version-after-update_1","title":"Version after Update","text":"Key_Phrase
static let maxCarbEntryFutureTime\n

Default shown below:

Code Before Modification

static let maxCarbEntryFutureTime = TimeInterval(hours: 1)\n

Change the maxCarbEntryFutureTime to the number of hours in the future you desire. Remember that Loop may increase insulin dosing for future carbs - make sure that they actually arrive.

"},{"location":"version/code-custom-edits/#adjust-the-watch-crown-sensitivity","title":"Adjust the Watch Crown Sensitivity","text":"

The rate of change of the carb and bolus entry pickers when using the digital crown can be altered as can the rotation required to confirm a bolus on the watch. If you are running an older series watch - you may want to make these customizations. When I switched from Series 3 to Series 7 watch - it was amazing. I got a graph on the main watch screen I didn't even know existed and the bolus acceptance was a breeze!

  • The Loop 3 customization is provided from code inspection and one test - use with care.
"},{"location":"version/code-custom-edits/#loop-3-digital-crown-adjustments","title":"Loop 3 Digital Crown Adjustments","text":"

These are new instructions and the user should take care - and please report back if you have problems.

First - try it with no customization. Then make small changes.

This key phrase will indicate three different files in the same folder as shown in the graphic below - you can adjust each in turn as you desire. When you click on the line, the quantity you change is a few lines below where you find the Key_Phrase, except for the CarbAndDateInput file.

Key_Phrase
.digitalCrownRotation\n
  • Module: Loop
  • Folder: Loop/WatchApp Extension/Views/Carb Entry & Bolus
  • Stable: Yes

"},{"location":"version/code-custom-edits/#modify-bolus-confirmation-motion","title":"Modify Bolus Confirmation Motion","text":"
  • File: BolusConfirmationView.swift, line 59
  • Initial Value for scalingRotationBy is 4
  • Decrease to require less motion to confirm bolus (use whole numbers only), start with 3
"},{"location":"version/code-custom-edits/#modify-bolus-picker-sensitivity","title":"Modify Bolus Picker Sensitivity","text":"
  • File: BolusInput.swift, line 53
  • Initial Value for rotationsPerIncrement is 1/24
  • A change to 1/12 increases the change in picker value for a given motion
"},{"location":"version/code-custom-edits/#modify-carb-and-time-picker-sensitivity","title":"Modify Carb and Time Picker Sensitivity","text":"
  • File: CarbAndDateInput.swift, line 68
  • Initial Value for rotationsPerIncrement is 1/24
  • A change to 1/12 increases the change in picker value for a given motion
"},{"location":"version/code-custom-edits/#expiration-notification-customization","title":"Expiration Notification Customization","text":"

An expiration notification feature has been added to Loop. You get a notification when you open the Loop app to alert you that the expiration is approaching.

  • Read Loop App Expiration Notification to see the expiration reminder
  • Read Loop App Expiration Date if you have an older version of Loop

If you prefer a different notification time and frequency, there are two lines you can modify:

  • Module: Loop
  • Folder: Loop/Managers
  • File: ProfileExpirationAlerter.swift
    • Line 16: modify how long before expiration you get the FIRST notification
    • Line 28: modify how frequently you will be notified
  • Stable: Yes
Key_Phrase
expirationAlertWindow: TimeInterval\n
Key_Phrase
 minimumTimeBetweenAlerts: TimeInterval\n

Default code for line 16: 

    static let expirationAlertWindow: TimeInterval = .days(20)\n

Example modifications to First Notification:

  • 30 days: change .days(20) to .days(30)
  • 12 hours: change .days(20) to .hours(12)

Default code for line 28:

    let minimumTimeBetweenAlerts: TimeInterval = timeUntilExpiration > .hours(24) ? .days(2) : .hours(1)\n

Modify Frequency of Repeated Notifications (Three Values):

  • This phrase: > .hours(24) ? .days(2) : .hours(1)
  • Rewritten as: > Time_A ? Frequency_A : Frequency_B, means:
    • Use Frequency_A if there is more time between now and the expiration date than Time_A
    • Use Frequency_B if there is less time between now and the expiration date than Time_A

You can enter Time or Frequency as .days(value), .hours(value) or .minutes(value).

Free App Users:

An example change that a Free Loop App user (who has to build once a week) might choose is:

     > .hours(4) ? .days(10) : .hours(2)\n
Combined with an .hours(12) on line 16, they would get notified at 12 hours, 4 hours and 2 hours before expiration on the day of expiration and only when the app is opened. Since you'll be building once a week, you can play around with these values until you are happy.

"},{"location":"version/code-custom-edits/#enable-child-model","title":"Enable Child Model","text":"

Please see the Build-Time Flag page for this customization.

"},{"location":"version/code-custom-edits/#insulin-model-customization","title":"Insulin Model Customization","text":"

Each exponential model has 3 parameters that can be adjusted:

  • actionDuration: Duration of insulin activity (minutes)
  • peakActivity: Peak of insulin activity (minutes)
  • delay: Delay before insulin begins to acts after delivery starts (minutes)

Please read the nitty-gritty discussion that went into the development of the \"exponential insulin models\" in this Comment.

If you wish to customize these values, please make sure you know what you are doing. This is not a modification recommended for Loop novices.

Key_Phrase
MARK: - Model generation\n
  • Module: LoopKit
  • Folder: LoopKit/LoopKit/Insulin/ << NOTE new location
  • File: ExponentialInsulinModelPreset.swift
  • Lines:
    • actionDuration (19 to 32)
    • peakActivity (34 to 47)
      • delay (49 to 62)
  • Stable: Yes

This Loop 3 table of default values is provided for convenience. The times are all in minutes.

Model DIA Peak Delay rapidActingAdult 360 75 10 rapidActingChild 360 65 10 fiasp 360 55 10 lyumjev 360 55 10 afrezza 300 29 10"},{"location":"version/code-custom-edits/#loop-logo","title":"Loop Logo","text":"

Mac Instructions

This can be done with Build with Browser but the instructions might need to be adjusted for that case.

If you want an app logo other than the default green circle for your Loop app, you can easily customize this. To make it easy to generate the correct sizes of icons, you can use a site like appicon.build or appicon.co and just drag and drop your source image. The source image needs to be 1024 pixels x 1024 pixels. The site will email you a zip file or automatically download a set of files. Highlight and copy the contents of the Appicon.appiconset that you are sent, including the Contents.json file

  1. Navigate to the LoopWorkspace folder
  2. Open the OverrideAssetsLoop.xcassets folder
  3. Open the AppIcon.appiconset folder
  4. Delete the contents of the Appicon.appiconset and copy/paste your new images and Contents.json file.
  5. Rebuild your app

You may see a yellow warning that there are \u201cunassigned children\u201d depending on the images the app icon generator tool produced. The unassigned children alert will not prevent your app from building, it\u2019s simply because there are more sizes of images than Loop app uses. You can just leave the unassigned children alone (wow...how often do you get to say that phrase?).

And now you'll be the proud new owner of a custom Loop icon.

"},{"location":"version/code-custom-edits/#custom-edits-optional","title":"Custom Edits Optional","text":""},{"location":"version/code-custom-edits/#disable-authentication-for-bolusing","title":"Disable Authentication for Bolusing","text":"

Depending on your iPhone Settings and model, you may have Face ID or Touch ID enabled. Those security features will also be used to authenticate bolus delivery in Loop. You can choose to disable authentication (i.e., not require Face ID, Touch ID, or passcode for bolusing) through the following code customization.

Safety Measure

If you disable this, you are removing an important safety feature.

In addition to authenticating every manual bolus, this helps to protect against sleep bolusing and pocket bolusing.

For Loop 3, this controls the authorization requirement to modify Therapy Settings as well as to confirm bolus delivery.

Key_Phrase
canEvaluatePolicy(.deviceOwnerAuthentication\n
  • Module: LoopKit
  • Folder: LoopKit/LoopKitUI/Extensions/
  • File: Environment+Authenticate.swift, Line 20
  • Stable: Yes

Code Before Modification

if context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) {\n

Code After Modification

if false && context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) {\n
"},{"location":"version/code-custom-edits/#modify-override-insulin-needs-picker","title":"Modify Override Insulin Needs Picker","text":"

Some people want finer settings on the override insulin needs picker (5% instead of 10%) and may want to limit the overall range for overrides \u2013 especially for children.

1% Settings Available without Customization

With the advent of Loop 3, the Override Insulin Needs values are not limited by the default picker values of 10%.

  • Select 1% Insulin Needs

Any override more than a factor of 2 from 100% can cause Loop predictions to be wrong \u2013 especially if a carb count is entered. (An override is NOT the same as a manual temp basal - it changes insulin sensitivity factor and carb ratio in addition to the basal rate needed for zero change in IOB for the duration of the override.)

A Sensitivity of 0% is NOT Valid

Do not set the lower level of the sensitivity range to be 0%.

If you configure to allow that and someone chooses it, they will be telling Loop to divide by zero in some of the calculations. They will see NaN (not a number) in Loop predictions until that override is removed and will continue to see that for the full duration of insulin action (6 hours).

This example customization changes the lower bound for sensitivity to 50% (factor of 2 smaller than 100%) and provides 5% steps. This is the same as the prepared customization offered by the Loop and Learn team.

Key_Phrase
let allScaleFactorPercentages\n
  • Module: LoopKit
  • Folder: LoopKit/LoopKitUI/Views
  • File: InsulinSensitivityScalingTableViewCell.swift, Line 19
  • Stable: Yes

Code Before Modification

private let allScaleFactorPercentages = Array(stride(from: 10, through: 200, by: 10))\n

Code After Modification to 50% to 200% by steps of 5%

private let allScaleFactorPercentages = Array(stride(from: 50, through: 200, by: 5))\n
"},{"location":"version/code-custom-edits/#modify-maximum-and-warning-carb-entry","title":"Modify Maximum and Warning Carb Entry","text":"

Version 3.x of the Loop app has both a maxCarbEntryQuantity and a warningCarbEntryQuantity, found adjacent to each other in the code. The warning value is the level at which you are asked if you really meant to enter that amount:

Key_Phrase
let maxCarbEntryQuantity =\n
  • Module: Loop
  • Folder: Loop/Loop/Models
  • File: LoopConstants.swift, line 18
  • Stable: Yes

Code Before Modification

static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 250) // cannot exceed this value\n\nstatic let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 99) // user is warned above this value\n
"},{"location":"version/code-custom-edits/#low_carb_limit","title":"\"low_carb_limit\"","text":"

This first example might be used by a parent for a child with very small carb entries. It is provided as one of the prepared customizations supplied by the Loop and Learn Customization as \"low_carb_limit\".

Code After Modification to enable the warning at lower levels and limit maximum

static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 99) // cannot exceed this value\n\nstatic let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 49) // user is warned above this value\n
"},{"location":"version/code-custom-edits/#high_carb_limit","title":"\"high_carb_limit\"","text":"

This second example might be used by a person who routinely enters large meals and does not want to be warned with every meal. It is provided as one of the prepared customizations supplied by the Loop and Learn Customization as \"high_carb_limit\".

Code After Modification to warn if entry is between 201 and 300g

static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 300) // cannot exceed this value\n\nstatic let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 200) // user is warned above this value\n
"},{"location":"version/development/","title":"Loop Development","text":""},{"location":"version/development/#overview","title":"Overview","text":"

The early history of the Loop app was touched on in the introductory LoopDocs Overview: Development History section.

The Loop Releases page lists releases since version 2.0 in reverse chronological order.

The next version of the Loop app is developed using branch(es), independent of the released Loop version, which is found in the main branch. The dev branch is used by the developers to push out changes for users to test. You should only test a development branch if you are willing to be both an active participant with the developers to monitor announcements and provide feedback and to build frequently to obtain the latest feature or bug-fix that is being tested. If you are willing to help out - this is the way the next release of Loop is improved.

If you choose to use dev, you accept that this code is not released.

Please read this entire page before using any version of Loop other than the released code.

"},{"location":"version/development/#updates-in-dev","title":"Updates in dev","text":"

This section is an early look at what has been added to dev since Loop 3.2.x\u00a0and will probably be in the next release. After the release, some of the content and graphics in this section will move to the Releases page or the appropriate documentation section.

  • Support for Libre Sensors
  • Modified Simulator Interface
  • Algorithm Experiments
    • Glucose Based Partial Application\u00a0 Factor
    • Integral Retrospective Correction
  • Favorite Foods
  • Updates to Omnipod User Experience
    • Insert Cannula Slider
  • TestFlight Expiration Warning
  • GitHub Browser Build\u00a0 Updates
  • Miscellaneous Code Fixes
"},{"location":"version/development/#support-for-libre-sensors","title":"Support for Libre Sensors","text":"

LibreTransmitter support was merged into the dev branch in July 2023.

If you are using the GitHub / Browser Build method, please review:

  • Browser Build: One-Time Changes: New steps and dates at which the new steps were added
"},{"location":"version/development/#modified-simulator-interface","title":"Modified Simulator Interface","text":"

The simulators for the Pump and CGM, for the dev branch show a new format when first selected. The initial view is a demonstration screen showing a typical CGM or Pump display. In order to view behind the scenes, modify settings, and delete the simulator, you must press and hold (long-press) on the top of the display. Anywhere in the top third works for the long-press, but I like to touch the card as shown in the pump example below. If you've counted to 10 and the display has not updated yet, then return to the main screen, go back to the simulator screen, and try again.

"},{"location":"version/development/#algorithm-experiments","title":"Algorithm Experiments","text":"

Two algorithm experiments have been added to dev. These are \u00a0Glucose Based Partial Application\u00a0 and \u00a0Integral Retrospective Correction. They can be viewed on the Loop Settings screen just below Therapy Settings and Usage Data Sharing as shown in the graphic below:

"},{"location":"version/development/#glucose-based-partial-application-gbpa","title":"Glucose Based Partial Application\u00a0 (GBPA):","text":"
  • Originally proposed in Pull-Request 1988 for Loop.
  • It is only used when Automatic Bolus (AB) is selected for Dosing Strategy
  • This modification does not affect the recommended dose, only how quickly the recommended dose is automatically delivered

When AB is selected and GBPA is enabled, the percentage of the recommended dose delivered per cycle of \u00a0Loop\u00a0 ranges from 20% to 80% based on glucose level and user-selected correction range. (Without GBPA enabled, AB uses a fixed 40% percentage regardless of glucose level.)

  • Partial Application = 20% when glucose is at or below the users correction range lower value (including overrides) plus 10 mg/dL (0.6 mmol/L)
  • Partial Application increases linearly from 20% to 80% up to a glucose level of 200 mg/dL (11.1 mmol/L)
  • Partial Application is 80% when the glucose level is above 200 mg/dL (11.1 mmol/L)
"},{"location":"version/development/#insulin-delivery-using-gbpa","title":"Insulin Delivery Using GBPA","text":"

Loop makes a prediction and recommends an insulin dose based on your settings and your glucose, insulin and carb history. The selected Dosing Strategy (Automatic Bolus with or without GBPA or Temp Basal Only) only changes how quickly that recommended dose is delivered.

This example assumes Loop recommends 1 U (at time 0) and future glucose values match Loop's prediction for each successive 5-minute update. In other words, over half an hour, Loop provides about 1 U of insulin above that delivered by the scheduled basal rate.

The tables below show Automatic Bolus patterns, using a pump minimum bolus increment of 0.05 U, for several application factors. When using GBPA, the application factor can vary with glucose, but that is ignored for this simplified example.

The first table shows the bolus delivered each Loop cycle for several application factors. Higher application factors start with higher boluses, but go to zero (indicated by a dash) more quickly.

Incremental Dose for several application factors when initial recommendation is 1 U

Minutes 20% 40% 60% 80% 0 0.20 0.40 0.60 0.80 5 0.15 0.25 0.25 0.15 10 0.15 0.15 0.10 0.05 15 0.10 0.10 0.05 - 20 0.10 0.05 - - 25 0.05 - - - 30 0.05 - - -

The second table shows the cumulative delivery. A dash shows recommended dose was delivered. Remember, this is a simplified example.

Cumulative Dose for several application factors when initial recommendation is 1 U

Minutes 20% 40% 60% 80% 0 0.20 0.40 0.60 0.80 5 0.35 0.65 0.85 0.95 10 0.50 0.80 0.95 1.00 15 0.60 0.90 1.00 - 20 0.70 0.95 - - 25 0.75 0.95 - - 30 0.80 0.95 - -

The 20% and 40% application factor columns did not reach 1 U in 30 minutes because the requested dose is smaller than this pump will deliver. The 60% application factor only reached 1 U because tiny doses down to 0.03 U were rounded up to 0.05 U.

The Temp Basal Only Dosing Strategy provides about 17% of the recommended bolus each 5-minute interval. The minimum GBPA application factor of 20% was selected to be similar to that rate for lower glucose values. Initially, an application factor of 20% delivers insulin more quickly than Temp Basal Only, but by the end of 30 minutes, the basal program inside the pump keeps track of how much is delivered to reach the rate requested, achieving the full 1 U (for this example).

"},{"location":"version/development/#integral-retrospective-correction-irc","title":"Integral Retrospective Correction\u00a0 (IRC):","text":"
  • Originally proposed in Loop Issue 695
    • This was tested in a few forks but not included into dev until recently
    • Initial merge into dev: Loop PR 2008
  • Updated with a modification to limit stacking of IRC with Glucose Momentum: Loop PR 2028
  • Integral Retrospective Correction, when enabled:
    • changes the Loop app prediction model and thus can affect the recommended dose
    • applies to both Dosing Strategies: Temp Basal or Automatic Bolus

Referring to the Algorithm: Prediction page:

  • When IRC is disabled (default), the equation used to predict glucose continues to be:
\\[ BG[t] = Insulin[t] + Carb[t] + RetrospectiveCorrection[t] + Momentum[t] \\]
  • When IRC is enabled that equation changes to:
\\[ BG[t] = Insulin[t] + Carb[t] + IntegralRetrospectiveCorrection[t] + Momentum[t] \\]

Note that the Momentum\u200b term does not just add to the other effects; it is actually more complicated (and also more challenging to describe in simple math terms).

The Retrospective Correction section of the Predicted Glucose Chart is updated when IRC is enabled, as shown in the graphic below. The Integral effect, inside the lower blue rectangle, is the difference between the IRC and RC calculations.

The IRC term is described in this (updated) comment including plots and equations. Some of the information in that comment is repeated below: Important points about IRC.

If you want to look at the code, the version (as of 14-Aug-2023) is found in LoopKit/LoopKit:

  • RetrospectiveCorrection code: StandardRetrospectiveCorrection.swift
  • IntegralRetrospectiveCorrection code: IntegralRetrospectiveCorrection.swift
"},{"location":"version/development/#important-points-about-irc","title":"Important points about IRC","text":"

  1. Known risk factors compared to standard Loop:

    • With IRC turned on, Loop will likely increase insulin corrections in response to persistent discrepancies between observed and predicted glucose motion, which may increase the risks of hypoglycemia
    • IRC may also lead to increased oscillations (\"roller-coaster\") in glucose responses
    • Both of these risk factors are higher if the user's setting value for Insulin Sensitivity (ISF) is too low
    • Increasing ISF setting value tends to mitigate these risks but it is impossible to offer any guarantees for anything around T1D

  2. Compared to standard RC, IRC is more likely to improve glucose control in the following scenarios:

    • Glucose remaining high or decreasing slower than expected due to temporarily reduced insulin sensitivity or poor site absorption
    • Glucose trending low faster than expected due to temporarily higher insulin sensitivity
    • Glucose spikes due to unannounced meals
    • Glucose remaining high (or trending low) on tail ends of meals where carbs entered were underestimated (or overestimated)
    • Glucose remaining elevated due to unannounced protein+fat effects
    • Glucose staying above (or below) the correction range due to too low (or too high) basal rate settings

  3. In some scenarios IRC does not differ from standard Loop RC

    • Regardless of the current glucose level, neither RC nor IRC is adding to the glucose forecast during the times when the absorption rate of announced carbs is greater than the minimum absorption rate.
    • Neither RC nor IRC effects depend on glucose level; both depend on discrepancies between predicted and actual glucose responses.

  4. Please do not expect immediate or very substantial improvements in blood glucose control. A one-time success after turning IRC on does not really mean that IRC \"works\" - this could just as well be a temporal coincidence. Some ways to decide if IRC could be safe and effective for you include:

    • Responses to unannounced meals - spikes should in general be somewhat lower than those with standard Loop, but there should also be no follow-up lows
    • Nighttime responses over a few weeks - highs or lows should be less frequent compared to the standard Loop; at the wake-up time blood glucose should, in general, be closer to the correction range.
"},{"location":"version/development/#favorite-foods","title":"Favorite Foods","text":"

This feature allows you to save Favorite Foods.

A new row on the\u00a0Loop\u00a0app Settings screen, see graphic below, provides access to create and edit your \u00a0Favorite Foods.

In the example meal entry shown below:

  1. The Favorite Food row (at the bottom) is tapped
  2. The desired Favorite Food is selected

At this point the meal can be saved by tapping the Continue button, or the user can modify the time (typical) or any other of the carb entry rows before tapping Continue.

"},{"location":"version/development/#testflight-expiration-warning","title":"TestFlight Expiration Warning","text":"

The\u00a0Loop\u00a0app has been updated to detect whether the build was uploaded through TestFlight, which implies a 90-day limit until the app expires.

The usual\u00a0Loop\u00a0expiration notification system alerts the user when within 20 days of expiration. In addition to that modal alert, the user can examine the bottom of the Settings screen at any time to see the expected expiration date and time.

"},{"location":"version/development/#github-browser-build-updates","title":"GitHub Browser Build\u00a0 Updates","text":"

The dev branch has several updates merged that make it easier to find errors in configuration and that make the \u00a0GitHub Browser Build\u00a0 automatic.

Note that the automatic build feature is opt-out. In other words, unless you take specific steps, the \u00a0GitHub Browser Build\u00a0 for\u00a0Loop\u00a0will:

  • Automatically build a new version once a month, with automatic update included
  • Automatically update your fork of LoopWorkspace once a week if updates are available

It is suggested that all users of the released code (main branch), maintain this automatic schedule so they are never without a valid and up-to-date\u00a0Loop\u00a0in their TestFlight app.

For users of the dev branch, it is not uncommon to disable the automatic update portion so they can choose when to update their development version, but should probably keep the monthly build portion of the process.

  • Configure GH_PAT
  • Modify Scheduled Building and Synchronization

In addition to the easier to read error messages found with these updates, these additional simplifications include:

  • Actions are broken into logical components, each of which provides an easy to understand error message if it fails which includes a suggested fix
  • A new builder no longer needs to create the \u00a0Match-Secrets repository
    • If it does not exist, one is created for you
    • Only the App Group ID must be added to the Identifiers; all other App services are automatically added
  • For new builders and current 3.2.2 users updating to the next release
    • The \u00a0alive branch needed to enable automatic building is created automatically
    • If their GH_PAT does not have repo, workflow permission, a prominent message is displayed with each Action completed

These sections are still useful for version 3.3.0 dev users:

  • Browser Build for dev: How to use \u00a0GitHub Browser Build\u00a0 for dev branch
  • Browser Build: One-Time Changes: New steps and dates at which the new steps were added
"},{"location":"version/development/#miscellaneous-code-fixes","title":"Miscellaneous Code Fixes","text":""},{"location":"version/development/#g7-sensors-duplicate-cgm-values","title":"G7 Sensors: Duplicate CGM Values","text":"

Fixed with PR 16: Fix parsing of age field of message

  • Most sensors report the time with very little offset between time of arrival and time of sensing
  • If the time discrepancy is large, the error (using one byte instead of two for age of the reading) could cause CGM values to appear as duplicate readings in Loop
"},{"location":"version/development/#remote-services-update","title":"Remote Services Update","text":"

The code that feeds Loop data to remote services like Tidepool and Nightscout have been improved to be more robust.

"},{"location":"version/development/#what-are-git-branches","title":"What are Git Branches?","text":"

There is a lot of discussion about branches with Loop but the concept is simple. Basically, they are all slightly different versions of Loop...kind of like different edits of the same book.

To really understand what branches are, we should probably explain a little more about the software and how development works. You can watch a 30-minute long, classic Katie DiSimone video explanation about branches created when Loop Version 2.0 was newly released. Keep in mind while watching the video that master was the old name for the main branch. The information in this video is still generally useful with the last half focused on automatic-bolus - the automatic-bolus dosing strategy has now been incorporated into Loop main branch. Loop has moved on to using only one stable branch (main), with dev suggested for developers/testers.

"},{"location":"version/development/#loop-github-information","title":"Loop GitHub Information","text":"

Loop developers own an account in GitHub called LoopKit. Within that account, the developers have several repositories that support Loop in particular. A repository\u200b is like a book...let's think of it like a cookbook for now. Within the LoopKit account, there are repositories for Loop\u200b itself, LoopDocs, and various other supporting \"frameworks\" that are helper \u200brepositories\u200b for Loop to build correctly. For example, Loop's \u200brepository\u200b has a lot of info about the app itself; the outward-facing things that you interact with. How information is put to you and taken in from you...that's in Loop repository code. But, there's more than just a user interface for Loop. Loop has to do a lot of complex work like Bluetooth communications, algorithm math, pump communications, etc. The Loop app has help from frameworks to do those other parts. CGMBLEkit\u00a0 for some of the transmitter parts of Loop, RileyLink_ios for the pump managers (talking to the pumps and decoding their information), LoopKit for the algorithm about carbs and insulin curves, etc.

When you build Loop, in the background, Loop pulls those other frameworks (7 in total) into the build process using Carthage. Carthage\u00a0 is like a personal shopper. You give it a shopping list (the cart file in Loop code is that shopping list) and it goes and fetches that for you during the build process. Sometimes your computer has an old shopping list...and that can cause build errors. Hence the carthage update fix in the Build Errors page...that command updates the shopping list to get the right versions of those frameworks.

Anyways...so now you know about the general structure of Loop and LoopKit in GitHub. Now we can discuss Loop itself a little deeper.

So let's imagine Loop as a cookbook. The developers are the authors/chefs of the recipes (code) in the cookbook. The authors spend countless hours testing new recipes, taste testing, and documenting improvements. They send the drafts to the editor, who makes suggestions and eventually, the cookbook is finalized. There are no grammar issues, and no typos, the photos are beautiful and the recipes are yummy. They publish the book and you see a gorgeous final product on the shelves. That is called a release\u200b, and it is the main branch. This book has been well-tested and is super stable. Every time you cook with those recipes, you know exactly what you're getting and lots of people have had a chance before you to make sure that it all tastes good. The main branch is stable and tested.

But then...the chefs/developers go on a trip. They are inspired by new cuisine and want to add new recipes to the old cookbook. (Things like Omnipod\u200b support and the overrides are new \"recipes\" that were developed since the last main release, for example.) But, the process of developing a recipe is arduous. There was a lot of trial and error involved. Lots of tweaking ingredients (code). The editors try out the new recipes and offer feedback (similar to the Issues List on GitHub). While the recipes are being developed, they have a version of the old cookbook that gets marked up...edited in pencil a lot. Scribbles and notes in the side. Revisions happen frequently because that's what testing new recipes is all about. These marked-up versions of the cookbook are called the dev branch. Short for \"development\" branch. Like the name sounds...this is where new developments are happening, new recipes, and tweaks.

After much testing and tweaking, eventually, the recipes get the flavors right (bugs in code are squashed) and enough people have provided feedback and careful observations of results...that the book goes to the publishing house for the next printing. The cookbook is republished with an updated edition number and new recipes are highlighted. When this happens in Loop, Loop's main branch is updated with the new features coming from dev (aka, the dev branch is merged into the main branch). When that happens, the main branch gets another release version. At this point, dev and main are identical. They remain so until the development team for Loop\u00a0 starts working on the next batch of improvements, which could be in the next hour or even days later, but then the cycle starts again. The developers will start editing the code again and dropping those edits in the dev branch for further development.

"},{"location":"version/development/#whats-going-on-in-the-dev-branch","title":"What's going on in the dev branch?","text":"

The dev branch, currently v3.3.0, is where the next version of Loop is being developed and tested.

If you choose to build Loop using a dev branch, you need to be aware that the dev branch may update code frequently and unannounced in the traditional sense that most users in the Looped group or Instagram would see. Developers are not helped by people being in a dev branch if those users mistakenly think of it as a stable main branch with lots of detailed docs to go with it. People should only use a dev branch build if they EDUCATE themselves on the expectations and how to properly manage dev information and updates. People using the dev branch should also have regular access to a computer to be able to rebuild quickly if a new bug/fix is identified.

If you choose to use a dev build, you can stay abreast of developments in a number of ways...but they will all require you to do some legwork and keep yourself informed. This is not a situation where you should expect a fancy Loopdocs page updated regularly with current \"dev updates\"...that's just not the way the dev branch works (at least normally).

"},{"location":"version/development/#subscribe-to-the-zulipchat-channels","title":"Subscribe to the Zulipchat channels","text":"

Use Zulipchat forums for Loop. This forum has several streams of conversations (streams) depending on interest. I highly recommend following all the streams so you do not miss conversations. You can select by stream and by topic within a stream to focus on a given conversation.

Zulip Chat Streams

  • If you are using the dev branch, you must be in the #development stream.
  • If you want to know when LoopDocs gets updated, follow the #documentation stream.
  • Code changes are called commits in GitHub. The #github stream will have an automated post whenever a new commit is made and it will give a brief line description of the commit.

You can also go directly to the git commit history for each of the branches if you'd like.

  • Loop main branch: git commit history
  • Loop dev branch: git commit history

If you click on the commit, you can see exactly what changes to the code were made. It's an interesting learning experience. In red is the old code, and in green is the updated code. The line numbers and file names of the edited code are also there to help.

I don't expect many of you would understand exactly what the edits mean, or how the new code might function. However, I bring up the topic of git commit history so that you can use that to realize just how often the dev branch is updated. Go ahead and look at the number and frequency of commits in that branch. That's why no one would want to maintain a documentation list of the changes in the dev branch. It's just too much of a moving target.

"},{"location":"version/development/#watch-the-loop-repository-and-issues-list","title":"Watch the Loop Repository and Issues List","text":"

Open the Loop repository and subscribe to the Issues.

You can choose to watch the repository so that you get emails when new Issues are reported. This is a good way to find out if other people are reporting odd behavior that you are wondering about. If you use dev and wonder about something you are seeing in Loop, you can check Issues list to see if others are noticing the same. If so, you can help by capturing information and reporting it. Not super helpful to just say \"Yeah, me too...\" but better if you can attach screenshots, Issue Reports from Loop settings, and a thorough description of the problem you are seeing. Be a part of the solution by thoughtfully providing information to help debug.

"},{"location":"version/development/#keep-checking-looped-group","title":"Keep checking Looped group","text":"

Keep watching The Looped Group on Facebook. Major concerns/issues are brought up there...so it doesn't hurt to scroll through and see what's going on there.

"},{"location":"version/development/#become-familiar-with-your-data-sources","title":"Become familiar with your data sources","text":"

Another useful thing if you'll be on dev branches undergoing a lot of active change...know how Loop works and where to look for additional information about what you are seeing. For example, if you see an IOB value that looks odd, you should know to look at the insulin deliveries stored in the Health app.

"},{"location":"version/development/#generate-an-issue-report","title":"Generate an Issue Report","text":"

Know how to generate an Issue Report when you see a problem so you can provide that if asked. An Issue Report is a log file generated by the Loop app that has a lot of information the developers can parse to figure out what Loop was doing when you were having a problem.

  • Loop v2.2.9\u00a0 and earlier:Loop Settings -> Issue Report
  • Loop 3\u00a0 and later: Loop Settings -> Support -> Issue Report

Do not confuse this with reporting an issue with Loop. That is done by logging into GitHub and going to the Issue page to report a new issue. You can read about existing issues without logging in, but to report a new one, you must log in to GitHub.

"},{"location":"version/development/#create-a-debug-report","title":"Create a Debug Report","text":"

This 6-minute long, classic Katie DiSimone video shows how to capture debugging logs. If you are testing a new branch, this is a valuable skill to assist developers in identifying problems. In addition to showing you how to generate and save the debug text information, the video explains how to create a gist with the debug information using your GitHub account and file an official Issue on the Loop GitHub repository. This may be required in some cases. But start by chatting directly on Zulipchat with the developer. What you are experiencing may already be known. If the developers need you to open a new Issue, they will say so on Zulipchat.

"},{"location":"version/development/#repositories-and-code","title":"Repositories and Code","text":"

If you're a developer looking for direct links to the code and documentation in GitHub:

  • Loop
  • LoopDocs

For more information on how to contribute code to the Loop project, please review:

  • How to Contribute to Open Source
  • the LICENSE
  • the CODE_OF_CONDUCT

If you want to contribute code improvements, please join Loop Zulipchat and be sure to subscribe to all the channels. Meet the developers and testers who make this app, and learn about what is coming next.

"},{"location":"version/loopworkspace/","title":"LoopWorkspace","text":""},{"location":"version/loopworkspace/#loop-workspace","title":"Loop Workspace","text":"

This page is for the advanced user. It is a short introduction for folks interested in testing code before it is released, or contributing to that code.

If you wandered over here meaning to build the latest Loop release, the rest of this page might be interesting but you should not follow any of the steps. Head back over to Build Loop App when you are ready to build the app.

LoopWorkspace is now used for all Loop Builds

  • With the release of Xcode 13, Loop builds require LoopWorkspace
  • Loop old-timers may remember the zip-download method - it is no longer available
  • For all Loopers who want the latest
    • Loop Release
    • Follow the step-by-step instructions found at Build Loop App

The typical user who wants to build Loop does not need to know the level of detail on the rest of this page.

"},{"location":"version/loopworkspace/#new-way-to-sign","title":"New Way to Sign","text":"

One of the recent changes to LoopWorkspace is the addition of the file: LoopConfigOverride.xcconfig to the LoopWorkspace folder. The contents of this file are shown in the graphic below.

There are several ways to use this to sign the targets automatically.

  1. Edit the line highlighted by the red rectangle to remove the comment marks (//) from the beginning of the line and replace the indicated TeamID (UY678SP37Q) with your own Team ID
  2. For developers who may have more than one clone for various testing, note the first line of that file, highlighted by the blue-dashed rectangle
    • If a LoopConfigOverride.xcconfig exists up two levels from the current LoopWorkspace folder, it will be included
    • Use a directory structure for clones similar to the example shown in the graphic below where clones were created under ~/Downloads/ManualClones.
    • Make a copy of the LoopConfigOverride.xcconfig in the ~/Downloads/ManualClones folder (from any LoopWorkspace folder) and edit that version with your TeamID
    • All future clones created in this directory grouping are then automatically signed
  3. For users of the Build Select Script, the script automatically generates the copy of LoopConfigOverride.xcconfig in the ~/Downloads/BuildLoop folder the first time the script is run, guides the user into adding their TeamID and then, in subsequent downloads, uses that previously created file

"},{"location":"version/loopworkspace/#team-id","title":"Team ID","text":"

Your Apple Developer ID is the 10-character Team ID found on the Membership page after logging into your account at: https://developer.apple.com/account/#!/membership.

"},{"location":"version/loopworkspace/#what-is-git","title":"What is git?","text":"

Git is a system of \"distributed version control\" that allows remotely (as in not located in the same place) collaborating people to work on one project and still track their changes to the same place. For example, if I sent 5 people one document to proof-read at the same time...it is quite possible that the edits I will get back from those 5 people would conflict with each other. Bob may have entirely deleted a sentence while Mary would have added words to that sentence. Git lets these remotely collaborating people deal with \"resolving conflict\" between versions more easily and merging suggestions (pull requests) into a coordinated space.

So, in using git, we can do things with \"git commands\". Like \"Hey git...make me an exact copy of that guy's work over there.\" or \"Hey git, I'd like to compare my version of this page with Joe's version of the same page.\" Or using my old cookbook analogy...\"Hey git, I'd like to start a new cookbook called Italian Desserts.\"

But yes, git commands take awhile to properly use. And they are not plain English-friendly.

"},{"location":"version/loopworkspace/#what-is-loopworkspace","title":"What is LoopWorkspace?","text":"

There is more information in Loop Development that is not repeated here.

The important fact for this discussion on LoopWorkspace is that Loop developers own an account in GitHub called LoopKit. Within that account, the developers have several repositories that support Loop in particular. A repository is like a book...let's think of it like a cookbook for now. Within the LoopKit account, there are repositories for Loop itself, LoopDocs, and various other supporting \"frameworks\" that are helper repositories for Loop to build correctly. For example, Loop's repo has a lot of info about the app itself; and the outward-facing things that you interact with. How information is put to you and taken in from you...that's in Loop repository code. But, there's more than just a user interface for Loop. Loop has to do a lot of complex work like Bluetooth communications, algorithm math, pump communications, etc. The Loop app has help from frameworks to do those other parts. CGMBLEkit for some of the transmitter parts of Loop, RileyLink_ios for the pump managers (talking to the pumps and decoding their information), LoopKit for the algorithm about carbs and insulin curves, etc.

When you build Loop from LoopWorkspace, each of those repositories is downloaded to your computer. This is slower than the old zip-download as far as downloading Loop - but it is much faster when you build Loop because all the files are already on your computer.

LoopWorkspace uses submodules to define how the frameworks are coordinated for building. The graphic below shows the dev branch at a particular point in time. The precise version, or commit, of each submodule is defined by 7-character hexadecimal codes (look up SHA-1) with the repository for each submodule defined in a text file called .gitmodules.

  • Several key git and other operating system commands will be provided later to assist you
  • These commands will not be explained in detail
  • If you want to know more, search the internet for documentation
  • Often a series of commands is shown on one line, separated by semicolons

The commit identifier for each submodule is important because that repository can be modified after things are set up and working with Loop. When you download the code from that repository you want the exact version that was tested.

  • Later on there will be information about determining your git branch for a given submodule
  • You'll see language: (HEAD detached at #)
  • That # is the commit identifier for the submodule

The commit for the LoopKit submodule is highlighted by the red rectangle in the graphic below. Advanced users testing the dev branch (or other branches or forks) need to know how to tell if their current download is up-to-date.

"},{"location":"version/loopworkspace/#clone-loopworkspace","title":"Clone LoopWorkspace","text":"

To get that LoopWorkspace code to your computer, first open a terminal. Make sure your current path name does not have any embedded spaces. If it does, you will get errors on your build.

If you don't know how to open a terminal and navigate to a directory, reconsider whether you are ready for this page.

You need to use a git clone command LIKE THIS (but not exactly the same...you're going to edit the branch-name part in there):

git clone --branch=branch-name --recurse-submodules https://github.com/LoopKit/LoopWorkspace

Now...look carefully and notice two things...that command (1) is getting the version of LoopWorkspace found in the LoopKit repository and (2) selects the branch you want to start working with when the clone is done.

So, you will need to edit that branch-name before using the command so that you are getting started with the branch you want. If you want to clone from a different fork, the LoopKit will be replaced with the name of the GitHub site for the fork. For example, to test the dev branch (which is under development and has some cool new architecture and features), you would copy/paste:

git clone --branch=dev --recurse-submodules https://github.com/LoopKit/LoopWorkspace\n
"},{"location":"version/loopworkspace/#start-xcode-using-command-line","title":"Start Xcode using command line","text":"

If you want to start the build from the command line, enter the following 2 lines into the terminal.

cd LoopWorkspace\nxed .\n

Remember the warning - if you build the dev branch on your phone from Loop main, it should work fine. Going backward, please delete the app from your phone and enter all your settings again to return to main.

"},{"location":"version/loopworkspace/#start-xcode-using-finder","title":"Start Xcode using Finder","text":"

The cloned version of the LoopWorkspace will go into the current directory in the Terminal app when you execute the command. Terminal app opens in your User account home directory by default when you first open it. Unless you changed to a different directory, check your home directory for the LoopWorkspace folder.

How can you find your home directory?

  1. In Terminal, if you use cd that will take you there automatically.
  2. In Finder, Shift+Cmd+H will open your home folder.

There are a lot of cloned things in this home directory that involve Loop. You may have fewer...but be aware, you can always delete and reclone if you are in doubt or confused. You can also set up a special directory to hold the cloned code - just make sure there are no embedded spaces in the full path name.

For this graphic, the cloned LoopWorkspace is in the home directory.

Loop to LoopWorkspace in dev

Note that the directory Loop.xcworkspace has been renamed to LoopWorkspace.xcworkspace in the dev branch. This change makes LoopWorkspace the default target to simplify the build process.

The words will be updated with the next release. It may take more time for the figures to be updated.

  1. Open Finder and navigate to the location that has LoopWorkspace
  2. Open the LoopWorkspace folder
  3. Search for and double-click on the LoopWorkspace.xcworkspace folder - this automatically opens the Workspace in Xcode

  • Enter your Apple Developers ID in the LoopConfigOverride.xcconfig file that now appears in the top of the folder list (not shown in this graphic)
  • This automatically signs the 5 targets required for the dev branch
  • Choose your device
  • Tap on the build (play) button to build to your selected device
"},{"location":"version/loopworkspace/#updating-loop-using-loopworkspace","title":"Updating Loop using LoopWorkspace","text":"

When it's time to update the copy of LoopWorkspace on your computer - you have choices. You can use the method below or redo the whole cloning process.

Be sure your terminal is in the correct location using Open a Terminal in LoopWorkspace Folder

  1. Make sure you are in the correct branch using this git command: 
    git branch\n
  2. If you are not in the correct branch, for example, dev, then issue this git command (suitably modified for the desired branch) 
    git checkout dev\n
  3. Use the following git commands in the LoopWorkspace folder of your terminal: 
    git fetch\ngit pull --recurse\n

If you are testing the LoopKit dev branch, you need to be on zulipchat and subscribe to at least the #development and #github streams. (It's a good idea to subscribe to all the streams.) When you see repository updates similar to the graphic below, there may also be an announcement in the #development channel that LoopWorkspace is updated and ready to test. If not you can check the commits in LoopWorkspace and see if they've been updated. It's a good idea to wait 24 hours. My procedure is to build dev to my backup phone and then put it on my \"real\" phone. Otherwise, wait for someone else to do it and give the all-clear in zulipchat.

"},{"location":"version/loopworkspace/#updating-loop-to-a-specific-loopworkspace-commit","title":"Updating Loop to a Specific LoopWorkspace commit","text":"

Sometimes, you know a feature you want was added at a specific commit number; however, you know there are other changes later than that commit which you do not want to test. There is a solution.

Be sure your terminal is in the correct location using Open a Terminal in LoopWorkspace Folder. First you have to bring down all the latest dev commits. Then you will back up to the one you want.

  1. Make sure you are in the correct branch using this git command: 
    git branch\n
  2. If you are not in the correct branch, normally the desired branch is dev, then issue this git command (suitably modified for the desired branch) 
    git checkout dev\n
  3. Use the following git commands to bring down all the newer commits to your copy: 
    git fetch\ngit pull --recurse\n

  4. Now you want to \"backup\" to the desired commit:

    • You will need to figure out what that commit should be - there is no copy button here - you need to create this line yourself with the correct commit:
    git checkout <desired commit here>\n
    • Once you have checked out the correct commit, assuming there were no errors, you need to update all the submodules to that commit with this command (which you can copy and paste)
    git submodule update\n

  5. Assuming there were no errors, see Local Modifications Conflict, in the process above, you can now build that commit.

"},{"location":"version/loopworkspace/#build-following-update","title":"Build Following Update","text":"

Sometimes there is a change to the Workspace scheme in Xcode that interferes with building following an update to your local clone. In those cases, these steps typically work. Try the first one, and if that doesn't work, try the first two, etc. Only after trying all three should you post asking for help on zulipchat.

  1. In Xcode Menu, select Product->Clean Build Folder
  2. In Xcode Menu, select File->Close Workspace and then File->Open Recent and select top line (one you just closed)
  3. Quit Xcode and delete derived data, then reopen Xcode (you may need to resolve package versions again)
"},{"location":"version/loopworkspace/#delete-derived-data","title":"Delete Derived Data","text":"

This command deletes derived data stored across all workspaces and projects by Xcode on your computer. If you have multiple clones locally, it deletes derived data from all of them. The derived data will be regenerated next time you build with Xcode using that clone.

Copy and paste this command into a terminal window.

Copy and Paste to Delete Derived Data
rm -rf ~/Library/Developer/Xcode/DerivedData\n
"},{"location":"version/loopworkspace/#compare-your-local-clone-to-loopworkspace","title":"Compare your local clone to LoopWorkspace","text":"

In an ideal world, LoopWorkspace has the most recent compatible submodule identifiers revised at the same time the submodules are updated. You will notice the commit identifiers for the updated submodules are different from the ones you have locally.

You can check your current submodules with the git submodule status command in the LoopWorkspace folder of your terminal:

What are those super-long numbers? Those are the actual SHA-1 (remember - look it up) for the commits. But the first 7 characters are sufficient to uniquely identify the commit you need for the repository and branch identified in .gitmodules. So compare the first 7 characters to the LoopKit / LoopWorkspace number and you know whether you need to update or not.

To determine the commit for a single submodule on your computer, use the following commands in the LoopWorkspace folder:

  cd <submodule-name>; git branch; cd ..\n

The response will be similar to this exchange:

  cd rileylink_ios; git branch; cd ..\n
  * (HEAD detached at 2541c1c)\n    dev\n

The asterick indicates the branch that is currently checked out (active).

The phrase * (HEAD detached at #) allows you to compare your local version with the commit identifier on github.

"},{"location":"version/loopworkspace/#loopworkspace-unchanged","title":"LoopWorkspace Unchanged","text":"

What happens if you update (git pull --recurse) and there are no changes at the LoopWorkspace repository? There will be no change to your current clone on your computer.

  • You'll see a series of responses saying:
    • Fetching submodule submodule-name for each submodule-name
    • followed by Already up to date.
"},{"location":"version/loopworkspace/#loopworkspace-updated","title":"LoopWorkspace Updated","text":"

What happens if you update (git pull --recurse) and there are changes at the LoopWorkspace repository? The changes will be brought down to your clone on your computer.

You'll need to build Loop again to get these changes incorporated in the app on your phone.

  • You'll see a series of responses saying:
    • Fetching submodule submodule-name for each submodule-name
    • One or more will show changes and specify which submodules were changed
      • followed by Submodule path submodule-name: checked out new SHA-1
"},{"location":"version/loopworkspace/#update-locally","title":"Update Locally","text":"

It has happened that you notice changes in one or more repository (in the #github stream) followed by an announcement in the #development stream that changes have been committed and please test. But you get the response shown in the LoopWorkspace Unchanged scenario. You can make a comment in zulipchat, saying please update LoopWorkspace and then wait, or you can download the appropriate commit. If you are a new tester - you probably want to wait.

If you want to go on and test, you can update to the correct commit without waiting for LoopWorkspace to get updated.

First, in zulipchat, in the #github stream of the commit, click on the word pushed and that will take you to the commit. For example, clicking on pushed in zulipchat from the graphic shown above, goes to this website:

https://github.com/ps2/rileylink_ios/compare/8ff4bca2bc5f...2541c1c899a9

This indicates the final commit of that push for rileylink_ios is identified as 2541c1c.

At this point, the commands to get that commit locally on your computer are as follows, starting from the LoopWorkspace folder:

cd rileylink_ios; git fetch; git checkout 2541c1c; cd ..

If you got an error message the # you requested did not match any file(s) known to git, you either typed it incorrectly or you forgot the git fetch command. The fetch command brings down information from github to your computer but doesn't make changes to what you have checked out.

"},{"location":"version/loopworkspace/#local-modifications-conflict","title":"Local Modifications Conflict","text":"

If you have modified anything in a submodule folder on your computer, it might be in conflict with the latest commit.

If you get a message such as this:

  error: Your local changes to the following files would be overwritten by checkout:\n    Loop/Models/LoopConstants.swift\n  Please commit your changes or stash them before you switch branches.\n  Aborting\n

The easiest fix is to type commands similar to the following, where you modify Loop to be whichever folder(s) had the conflict. If more than one folder had a conflict, then issue the stash for each folder. The submodule update command will continue to show errors until you stash all local changes that interfere with the new code:

  cd Loop; git stash; cd ..\n  git submodule update\n

After stashing and updating with no errors, you can try to restore your changes: 

  cd Loop; git stash pop; cd ..\n

If you see errors indicating you cannot use pop, that means you need to manually add your customizations back.

You will need to repeat this for each submodule that has a conflict. Use the lines above (for Loop submodule) as a template to resolve conflict(s) other submodule(s).

"},{"location":"version/loopworkspace/#checking-out-different-branches-within-a-loopworkspace","title":"Checking out different branches within a LoopWorkspace","text":"

More advanced users...I'm not going to explain this in quite so much detail, but yes, you can individually change the branches in a LoopWorkspace.

There are 2 main ways to do this.

  1. If you're already familiar with git, the easiest way is to cd into the appropriate repository (like cd rileylink_ios) and checkout the desired branch.

  2. If you're not as familiar with git, if you edit your .gitmodules directory in LoopWorkspace, you can specify other repos to use (and add a line to specify branches, too). Then if you do a git submodule sync the workspace will sync to new submodules. Then git submodule update --init --recursive --remote will update all the submodules to the right branches and get HEADs detached correctly, etc. Note that the HEADs will be detached at the top of the branch (most recent commit) based off of .gitmodules.

"},{"location":"version/loopworkspace/#branch-tutorial","title":"Branch Tutorial","text":"

This tutorial is pretty nice.

Git Tutorial

When I first started using git, my adult son answered all my questions very politely and then started sending me links to this tutorial instead.

  • Learn Git Branching

There's a section called Main that goes over commands in your local copy (clone) of the code. There's a section called Remote that goes over fetching, pulling, and pushing to remote copies.

For Open Source Software, you might fetch and pull from the LoopKit repositories, but you will only push to your fork.

  • You may need to add git remote add <name> <your-fork-repo> and git push --set-upstream <name> <branch> to your vocabulary.
"},{"location":"version/loopworkspace/#non-loopkit-clones","title":"Non-LoopKit clones","text":"

Average Loopers can skip this whole section...it's for Developers mostly

This whole section about non-LoopKit workspace clones is something almost every Looper can totally skip over. I'm only writing up this section for people who are interested in dabbling in code collaborations/customizations that they would want to maintain separately from LoopKit proper.

Scenario: You have a friend named DeveloperBob who has his own version of LoopWorkspace that he's customized. DeveloperBob wants you to look at his code customizations and collaborate with him. You need to change the \"git clone\" command to get DeveloperBob's version, not LoopKit's version. And, you'd want to make sure you specify the branch that the new feature is on, too. DeveloperBob should usually include the branch name when he posts/shares. So, the command line might be edited to something like:

git clone --branch=new-features --recurse-submodules https://github.com/DeveloperBob/LoopWorkspace

So...if you are trying to grab someone's LoopWorkspace to use it, you'll need to make sure you get the command correct if they don't specify it for you. You can't clone multiple \"LoopWorkspaces\" into the exact same home directory (because they will have the same name), so you may want to create a subdirectory to put them in. Like you could make a folder called \"DeveloperBob\" and then move into that directory in Terminal before you clone DeveloperBob's LoopWorkspace.

How would you do that? Simple cd && mkdir DeveloperBob would make the new folder in your home directory. And then cd DeveloperBob would move your Terminal app to be working inside the new DeveloperBob folder. So if you wanted to clone DeveloperBob's LoopWorkspace, that would be a good way to keep track of where the code came from.

If you ever get in doubt and can't remember where your code was cloned from, you can cd LoopWorkspace to get into the directory and then use git remote -v to tell you where it came from.

"},{"location":"version/loopworkspace/#pushing-commits-from-loopworkspace","title":"Pushing commits from LoopWorkspace","text":"

So you've got a great idea for a new feature, made those changes to your LoopWorkspace, and want to get them into GitHub. Awesome!

To understand how to do this, we'll need to understand a bit more about how git keeps track of changes. In git, developers can have different \"branches\" (see What are Git Branches? on the Loop Development page for more details about what a branch is). There are two different types of branches: remote and local. If you were to fork Loop on GitHub, then the branches that you can see on GitHub are \"remote\" branches - they're hosted on the GitHub server. On the other hand, you can also create \"local\" branches that are stored directly on your computer by \"checking out\" the remote branch. You'll need to \"commit\" your changes to the local branch, and then \"push\" those changes to the remote branch in order to be able to see them in GitHub. There are specific commands that you can type into the command line to do all of these actions, but I'm not going to go into detail because there are different ways and everyone has their own preference.

It's a little easier to think about this with an analogy. Let's say you're working at a company that's creating a cookbook. There's a centralized, production-ready version of the cookbook on their website that all the employees can view. Think of the website version of this cookbook as being like the remote branch. You're assigned to change the pancake recipe in the cookbook. Since the company doesn't want employees to make changes directly to the version of the cookbook that the customers see, you need to make a copy of it on your computer so you can make your changes to the pancake recipe. When you make the personal copy on your computer, it's like \"checking out\" the remote branch. Your copy is like the local branch - you can make whatever changes you want without having to worry about customers accidentally seeing them. When you make an important change to the recipe (like adding a photo or changing the ingredients), you might want to make a note in the edit history so that you can go back to that version of the recipe in case you accidentally make unintended changes - those notes you make would be \"commits\". Once you're happy with the recipe, you'll add it back into the production version of the cookbook on the website, which is similar to what you're doing when you \"push\" your changes.

Where do the submodules fit in? Each submodule is actually a branch, so when you make changes to multiple submodules, you'll need to commit those changes to their respective branches. Let's say you've made changes to Loop and LoopKit. You'll need to go into Loop and commit and push the changes, then go into LoopKit and commit and push the changes.

There are a few different ways to keep track of all these different branches. Some people like using the command line (which is what you're using when you do commands like git clone) because it's very customizable and has the largest variety of commands. Others like to use graphical Git editors, which make it easier to see changes and be able to do a variety of common actions (like cloning, committing, and pushing) with the push of a button. Everyone has their own preferences, but some methods that Loop contributors have used in the past include the command line, Gitkraken, and SourceTree.

"},{"location":"version/overview-version/","title":"Version Overview","text":""},{"location":"version/overview-version/#version-overview","title":"Version Overview","text":"

The Version tab of LoopDocs contains information about releases (versions), code customization and development.

Map to this section:

  • Releases
    • Description of the current released version of the Loop app including when it was released
    • Reverse chronology of earlier releases
  • Information needed to Personalize (Customize) your app (regardless of build method)
    • Custom Edits
    • Build-Time Flag
  • Simulator Build
    • Considerations when using a simulator
  • Loop Development
    • Description of the development process for Loop
    • Information you need if you want to participate
  • Build Dev
    • Considerations when using the dev branch
    • Links to the two build methods
  • LoopWorkspace
    • If you are interested in development, this page goes into more detail
    • The primary focus is on techniques for using git
"},{"location":"version/releases/","title":"Releases","text":""},{"location":"version/releases/#loop-releases","title":"Loop Releases","text":"

The new features added with each Loop release (starting with Loop version 2.0) are provided for reference.

"},{"location":"version/releases/#loop-3-compatibility","title":"Loop 3 Compatibility","text":"

Be aware that Loop 3 is forward compatible:

  • You can build Loop 3 over older versions of Loop and maintain therapy settings as well as your configuration for CGM and pump (including a pod)
  • You can build Loop 3 using a browser on any computer (no Mac required) with Build with Browser
  • Your phone must be running at least iOS 15.1 (although some people report they needed newer iOS than that when building with GitHub Browser Build)

Loop 3 is NOT backwards compatible.\u00a0Once you build Loop 3 or later on your phone, you cannot return to Loop 2.2.x or FreeAPS without some additional work.

  • Be prepared to enter all your settings again and start a new pod
  • If you use Loop Follow, you do not need to delete Loop Follow
  • When downgrading to an older version of Loop from Loop 3, you have to delete all apps with a shared app group ID
    • For more information, click on Remove Apps with Shared App Group
"},{"location":"version/releases/#current-release","title":"Current Release","text":"

The current released version for the Loop app is 3.2.3. The dates and contents for releases are summarized below in reverse chronological order (so newest release information comes first).

"},{"location":"version/releases/#what-version-do-i-have","title":"What Version Do I Have?","text":"

Tap on the Settings icon at the toolbar of the Loop app and look at the version information at upper left. This graphic was generated with an older version.

"},{"location":"version/releases/#is-the-released-version-newer","title":"Is the Released Version Newer?","text":"

Release information is always found on the GitHub LoopKit/Loop\u00a0release page.

Additional information including links is found here, but be aware that updates to\u00a0LoopDocs\u00a0may take some time after a new release comes out.

"},{"location":"version/releases/#loop-version-numbering","title":"Loop Version Numbering","text":"

With the release of Loop 3, there is a new pattern for identifying the releases as distinct from the development work.

Each release uses 3 numbers: Major.Minor.Patch

  • Major is reserved for a significant change in the code, such as occurred going from Loop 2.2.9 to Loop 3.0.0
  • Minor is used when the development branch is released for general use
  • Patch typically indicates a modification to support external events like an Xcode or iOS version update with no feature changes in Loop

To prevent confusion between versions used for development and versions used for release (main branch), the Minor values are even for released code. The Minor value for the development branch (dev) is incremented as part of the release process and is always odd.

For example:

  • Loop 3.0.0 was the first released version of Loop 3
    • Loop 3.1.0 was the development version before Loop 3.2.0 was released
  • Loop 3.2.0 was the next released version
    • Loop 3.2.1, 3.2.2 and 3.2.3 are patches to Loop 3.2.0 without changes to the features of Loop 3.2.x
    • Loop 3.3.0 is the current development version
"},{"location":"version/releases/#loop-3-version-history","title":"Loop 3 Version History","text":""},{"location":"version/releases/#loop-v323","title":"Loop v3.2.3","text":"

Loop v3.2.3 was released on September 19, 2023.

This patch release was required for those who build using the Mac method.

  • There are no changes to app functionality
  • Version 3.2.2 and earlier cannot be built using Xcode 15, see Cycle Inside Loop
"},{"location":"version/releases/#loop-v322","title":"Loop v3.2.2","text":"

Loop v3.2.2 was released on April 24, 2023.

This is a patch release to fix archiving with Xcode 14.3.

"},{"location":"version/releases/#loop-v321","title":"Loop v3.2.1","text":"

Loop v3.2.1 was released on March 20, 2023.

This is a patch release primarily dealing with localization updates.

  • G7 Plugin localization fixed: was defaulting to Spanish in some cases.
  • Updated translations from translators on Lokalise.
  • Many behind-the-scenes fixes for how strings are tracked in the various frameworks that Loop uses, fixing a large number of broken/missing translations.
"},{"location":"version/releases/#loop-v320","title":"Loop v3.2.0","text":"

Loop v3.2.0 was released on March 17, 2023.

There are some important bug fixes and new features, so please rebuild to this version as soon as possible.

Pete's announcment:

Loop 3.2 Is released! This contains some very important bug fixes for everyone. If you are running latest dev, you do not need to update, but everyone else running older 3.x versions of Loop should consider upgrading as soon as you can.

https://github.com/LoopKit/Loop/releases/tag/v3.2.0

Bug Fixes (Please update ASAP):

  • Omnipod bolus tracking issue fixed: link
  • Medtronic temp basal tracking issue fixed: link
  • Crashes caused by large updates from Apple Health fixed
  • Automatic refresh timers for Omnipod (both Dash and Eros) have been removed, to reduce load on pods and reduce frequency of failed pods.

Updates and new Features:

  • Missed Meal Notifications. If you want, Loop will detect situations where it looks like you may have consumed carbs but did not enter them into Loop, and will notify you with an easy option to enter the amount, and the time of eating already estimated for you. Find this option in the Alert Management section of Loop settings.
  • Tidepool Service added. This lets you upload your diabetes data from Loop to Tidepool! It is in early stages, so there may be issues. Please report any issues you have with this integration on DIY Loop forums, like Zulip, GitHub, or the Looped group.
  • Translations! Loop now has very good coverage for several languages, including German, Spanish, Italian, French, Danish, Polish, Dutch, Norwegian, Russian, Turkish, and Romanian!
    • Warning - a few items got overwritten by Spanish - if you can't figure it out, try Google translate
  • A new safeguard restricts automatic dosing to keep your IOB below a limit of 2 times your max bolus. Manual dosing can still be delivered to put your IOB above this amount. link
  • Add missing X-Large watch complications. link
  • \u201cDeactivate Pod\u201d button on some screens changed to not be so alarming, as it doesn\u2019t actually deactivate the pod, but takes you to a screen where you can, and has an option to cancel: link
"},{"location":"version/releases/#loop-v300","title":"Loop v3.0.0","text":"

After several years of development and a lot of testing, Loop 3 is here!

Loop v3.0.0 was released on January 14, 2023.

Link to release notes for Loop 3.0

Use Script not Zip

If you follow that link above, there is an Assets section with a zip link

  • Do not try to build from the zip link
  • For Browser Build, refer to: GitHub Overview
  • For Build with Mac refer to:
    • Updating
    • Build the Loop App

Branch Name Change

The branch name associated with the latest Loop release is main.

  • All new Git repositories on GitHub will be named main instead of master starting October 1, 2020
  • GitHub provides tools to assist in modifying existing repositories to use main
"},{"location":"version/releases/#remove-apps-with-shared-app-group","title":"Remove Apps with Shared App Group","text":"

The storage of data with Loop 3 is not backward compatible. In other words, if you attempt to build Loop 2.2.x (or FreeAPS) on a phone which has been upgraded to Loop 3, you will not be able to run that app. You can successfully build the app, which will overwrite Loop 3 on the phone, but the app will crash and you will not be able to Loop.

At this point, you can restore your Loop 3 build on your phone and continue using Loop 3 or you delete all apps on your phone with a shared app group. This list includes Loop, FreeAPS, FreeAPS X, xDrip4iOS, Glucose-Direct, and the g5 Transmitter Reset app.

If you tried to delete \"all\" the apps and still have something causing an issue; you can follow the directions to Review Provisioning Profiles and then delete the profiles for all the apps by using the - sign.

You do not need to delete Loop Follow, so if you use Loop Follow - do not delete that provisioning profile.

"},{"location":"version/releases/#loop-2-version-history","title":"Loop 2 Version History","text":""},{"location":"version/releases/#loop-v229","title":"Loop v2.2.9","text":"

This release updates Loop to handle Dexcom Share server changes for how glucose trend is parsed. Dexcom used to provide integers that mapped to the meaning for the arrows. They changed that to strings, like \"Flat\" or \"FortyFiveUp\".

Loop v2.2.9 was released on April 4, 2022.

"},{"location":"version/releases/#loop-v228","title":"Loop v2.2.8","text":"

This is a hotfix (no features were modified in the Loop app) to enable the app to be built with Xcode 13.3.

Loop v2.2.8 was released on March 16, 2022.

"},{"location":"version/releases/#loop-v227","title":"Loop v2.2.7","text":"

This is a fix (no features were modified in the Loop app) to enable the app to be distributed via TestFlight.

Loop v2.2.7 was released on Jan 11, 2022.

"},{"location":"version/releases/#loop-v226","title":"Loop v2.2.6","text":"

Several users reported issues with IOB accounting in Loop v2.2.5, where IOB was being under-reported, which could cause Loop to continue recommending increases in insulin delivery. A fix was made and provided as Loop v2.2.6.

This is a serious issue, so updating to this release is strongly recommended for anyone currently running v2.2.5. If you tap on Loop Settings and look at the top, and see LOOP V2.2.5, then rebuild ASAP. The time window when you would have built v2.2.5 is from Aug 22 through Sep 6, 2021.

The issue appears to be the result of a failure to write to Apple HealthKit, which may occur if the Health app on your phone is having problems, or if you have turned off Loop's ability to write Insulin data to HealthKit. The fix involves reverting a change made in v2.2.5. This change was an attempt to reduce overlaps of Reservoir and Pump Event reconciliation which intermittently over estimate insulin delivery. Instead, that issue will be fixed in the next major release of Loop.

Thanks to all who helped with reporting, digging, and testing this quickly. It's great to have such a strong community of people eager to help.

Loop v2.2.6 was released on September 6, 2021.

"},{"location":"version/releases/#loop-v225","title":"Loop v2.2.5","text":"

This is an interim release as we prepare for the major changes currently in development. If you are running an older version of Loop, such as v2.2.4 (master or automatic-bolus branch) or an older version, it is recommended that you update to v2.2.6 to get all these new features. A summary of modifications with respect to Loop v2.2.4 is listed below.

Loop v2.2.5 was released on August 22, 2021.

"},{"location":"version/releases/#new-features","title":"New Features:","text":"

Automatic Bolus (Experimental) Dosing Strategy

  • Users may select Dosing Strategy
  • Default Dosing Strategy continues to be Temp Basal Only
  • Automatic Bolus Dosing Strategy is marked experimental
    • If you used Loop v2.2.4 automatic-bolus branch, this release will behave the same
    • If you used Loop v2.2.4 master branch, approach this feature with caution; it may require changes to settings
    • Tracking automatic vs manual boluses is not yet implemented in the code and databases

Provisioning Profile Expiration Notifications:

  • User gets notified when Loop app expiration date nears
  • Expiration date is included in the issue report

RileyLink Compatible Devices:

  • The RileyLink compatible device displays are pump independent
  • OrangeLink Support added for connection monitoring, battery level alerting, find device, and light/vibration controls
  • Medtronic Pump Settings screen updated with option to disable MySentry use; user can trade Medtronic pump battery for longer RileyLink compatible device battery life

Omnipod Features:

  • Pod Settings layout: improved layout and functionality
  • Fault Codes: PDM style Ref code displayed for pod faults
  • Confirmation beeps: improved and more uniform implementation
  • Pod Suspended: pod beeps once every 5 minutes until delivery is resumed or alarm cleared
"},{"location":"version/releases/#code-fixes","title":"Code Fixes:","text":"

Omnipod Code Fixes:

  • Make insertion more robust (LoopKit issue #1369)
  • Fix \u201cPod already primed\u201d errors when priming cancelled (rileylink_ios issue #661)
  • Prevent 049 pod faults during setup (rileylink_ios issue #627)
  • See RileyLink Pull Request 676 for additional details.

(REMOVED) Insulin Accounting:

  • Reduced occurrences of overlaps in accounting for insulin via reservoir and dose history, which causes temporary overestimation of IOB
  • See Loop Pull Request 344 for details
  • This modification (in v2.2.5) was removed for v2.2.6
    • It worked as advertised during testing, but . . .
    • If the user's phone had trouble communicating with the Apple HealthKit app, this could cause IOB to be under-reported and cause Loop to provide more insulin than needed

Dexcom Non-US Share:

  • Dexcom Share URL for non-US users has been fixed.

For community support, please use one of the Loop Social Media help sites.

"},{"location":"version/releases/#loop-v224","title":"Loop v2.2.4","text":"

Released October 3, 2020 with \"fixes\" introduced without renumbering the version number. Last change was on January 19, 2021.

  • Revert to previous date pickers (Thanks @novalegra!)
  • Pod fault handling improvements (Thanks @itsmojo!)
  • Fix issue with pod status screen not allowing new pod pairing or continuing of interrupted pairing.
  • October 22, 2020, update travis to make it work with Xcode 12
  • January 19, 2021, pin the carthage to 0.36.0. Users no longer required to install homebrew or carthage
"},{"location":"version/releases/#loop-v223","title":"Loop v2.2.3","text":"

Released September 25, 2020

Warning - Rebuild ASAP for Pods

  • A bug was introduced in this version, quickly fixed in v2.2.4.
  • If you use pods, please rebuild using v2.2.6.
  • Fetch pump and cgm data on manual loop retry (when Loop icon is red or yellow)
  • Re-arranged pod status screen to prioritize needed information and actions.
  • Pod pairing fixes for more edge cases.
  • Translation updates.
  • Fix share server integration, pointing to share2.
  • Report RSSI and low gain in Read Pod Status command.
  • Report failure properly when Play Test Beeps command fails.
  • Carthage build fix for Xcode 12.0.1
"},{"location":"version/releases/#loop-v221","title":"Loop v2.2.1","text":"

Released August 9, 2020

  • Include pending insulin in:
    • forecast uploaded to Nightscout
    • status extension forecast
  • Updated translations, fixes for temp override translations, new Arabic translations.
  • Omnipod integration fixes:
    • Avoid suspending during deactivation if pod has a fault, is in setup, or already suspended.
    • Show the correct expected address in invalid address error
    • Reuse same address during attempts to pair with same pod
    • Fix for Medtronic only: when a bolus issued via the Loop interface was canceled by issuing a suspend on the pump itself, Loop will incorrectly track the bolus as if the full amount were delivered
    • Updates for omnipod packet parser
    • Suggest moving RileyLink to new area on multiple pairing failures
  • Minimed updates:
    • Detect temp basal cancellation performed on pump
"},{"location":"version/releases/#loop-v22","title":"Loop v2.2","text":"

Released April 17, 2020

  • Updated carb/bolus screens. Thanks @mpangburn!
    • Carbs and boluses are now entered together, which is a more familiar model to many caregivers.
    • Forecast preview while entering bolus allows you to see potential impact of your bolus before delivering.
  • Improvements in Watch updates; sleep data being used to update complications when you are awake. Thanks @novalegra!
  • Omnipod pairing improvements. Bug fixes, and better error messaging. Thanks @itsmojo!
  • Many performance improvements, especially effecting long time Loop users. Delays in rendering graphs during app launch should be fixed.
  • New device communication logging facility- Additional logging across pod swaps, and logging of CGM communication.
  • Rendering fixes to prevent insulin graph from drawing outside of bounds.
  • Bug fix to align use of 10m insulin delay in dose computation and forecast.
  • Include current bg in suspend threshold evaluation.
"},{"location":"version/releases/#loop-v20","title":"Loop v2.0","text":"

Released December 31, 2019.

For Reference Only

Enough time has passed that this version should no longer be on anyone's phones (the one-year expiration time should take care of that).

There is a lot more detail provided in the Loop v2.0 section because it constituted a significant change to parts of Loop from prior releases. This section and the Omnipod-Testing branch sections are left here for historical interest.

"},{"location":"version/releases/#what-was-new-in-loop-v20","title":"What was new in Loop v2.0?","text":"

This is a highlights reel comparing Loop v2.0 to v1.9.6.

"},{"location":"version/releases/#uploading-of-bgs-to-nightscout","title":"Uploading of BGs to Nightscout","text":"

Loop v2.0 has an option to upload your BG data to Nightscout directly. It is a new slider under the CGM configuration section for Dexcom users. After you add your CGM transmitter ID, go back into the CGM info and you'll see a new slider called \"Upload Readings.\" Technically, Loop's dev branch had that feature for a hot minute before Loop v2.0 was released...but for almost everyone this will be a brand new feature they haven't had before. This feature can help if/when Dexcom's Share servers ever go through another large outage like we had before. If that happens, you can turn on the \"Upload Readings\" switch and your CGM data will now be in Nightscout even without Share servers working properly. Good practice would be to temporarily disable your Share bridge in Nightscout while Loop is responsible for CGM uploading so that you don't get duplicate data. You can disable Share bridge by logging into your Heroku account, going to the Settings tab, clicking on \"reveal config vars\" and then deleting the word \"bridge\" from the ENABLE line.

"},{"location":"version/releases/#a-fix-for-settings-loss","title":"A fix for settings loss","text":"

iOS 13 brought about a quirky little bug where you could suddenly lose settings in Loop. But, it wasn't just limited to Loop, sometimes people lost Dexcom app settings too. The issue is most common when the phone goes through a power cycle, but it has happened at other times, too. There's a fix for that new bug in Loop now...so that's a good reason to update. (If you encounter that bug before you have a chance to update your Loop app, simply restart the Loop app and your settings should reappear.)

"},{"location":"version/releases/#confirmation-beeps-expanded","title":"Confirmation beeps expanded","text":"

Confirmation beeps have been expanded based on user feedback...we heard parents and school nurses really appreciate hearing a beep for not just boluses, but also for suspend/resume commands and editing basal schedule (so you are sure it saved properly). So, confirmation beeps are now for boluses, suspend/resume, and basal schedule edit saves.

"},{"location":"version/releases/#read-pod-status-added","title":"Read Pod Status added","text":"

There's a new command in the RileyLink menu for \"Read Pod Status\" that is analogous to the existing command for Medtronic users. You can query your Pod for its current status info using that command.

"},{"location":"version/releases/#nightscout-profile-uploading-introduced","title":"Nightscout profile uploading introduced","text":"

Loop will upload your basal schedule, ISFs, carb ratios, and override presets from Loop settings to your Nightscout profile. If you ever lose your phone and need to setup Loop brand new...your settings will be easy to find in Nightscout now.

"},{"location":"version/releases/#non-linear-carb-model-introduced-as-default","title":"Non-linear carb model introduced as default","text":"

All branches (master and dev) now use a \"non-linear\" carb model, so let's give some info about the change.

Previously, the carb model Loop used had a linear absorption predicted with dynamic carbs adjustments. What this means is that food absorption was modeled as a flat, even effect (like the straight grey graph that you'll see in the Insulin Counteraction Effects chart after you added a carb entry. But looking at large groups of meals' datasets (and supported by personal, anecdotal experiences), food really has a bit more of a non-linear absorption. Meaning, we usually see more of a food impact up-front than the old carb model in Loop predicted.

What did that mismatch mean for us if the model predicts a linear absorption, but the meal actually behaves differently?

  1. Bolusing: You've probably seen smaller upfront boluses for meals than you would have preferred. This is because the insulin was predicted to over-power the linear (slower) carb model soon after a bolus is given.
  2. Early low temp basals: You've also probably seen a tendency to have early zero basal or low basals set by Loop for the first 30-60 minutes after a meal bolus if you don't have a significant blood glucose spike immediately after the carb entry. This might have been even more obvious for those of you who are regularly waiting to eat after a bolus, too.

With a non-linear absorption model, the carb absorption will more closely match observed blood glucose impacts we've seen after meals. And when the model is more closely matching actual experience, that means the predicted blood glucose curves will do a better job at providing more upfront bolus and not having the tendency to have overly conservative temp basals soon after a meal.

"},{"location":"version/releases/#overrides-introduced","title":"Overrides Introduced","text":"

Loop v2.0 marks the first time Loop master branch has overrides included. Additionally, this release moves overrides setup from the configurations area of Loop settings to the workout icon in the Loop toolbar. There has also been bug squashing in dev branch for overrides over the recent past, so updating is a good idea even if you already have overrides on your current build. Want to learn more about overrides? Read about them here.

"},{"location":"version/releases/#retrospective-correction-always-on","title":"Retrospective Correction always on","text":"

Retrospective correction used to be an optional toggle in the algorithm. It is now on by default all the time. It is an important part of the algorithm (helps Loop look at how good/bad its recent prediction curve has been vs reality), and leaving it on made sense anyways.

"},{"location":"version/releases/#omnipod-support-in-released-code","title":"Omnipod support in Released Code","text":"

Yes, most of you are already using Omnipod with your Loop...but this is the first time that Loop master branch supports Omnipod users. Please update if you have been using Omnipod-testing branch especially...it's time to get all the bug fixes that we've done in Loop.

"},{"location":"version/simulator/","title":"Simulator Build","text":""},{"location":"version/simulator/#simulator-build","title":"Simulator Build","text":"

There are 2 main types of simulators users may want to build. Each of these require less up-front acquisition of hardware and may be desirable as a first step towards becoming a Looper.

Please, review all the Intro and Build pages, even if you will not complete them yet.

"},{"location":"version/simulator/#simulator-using-browser-build","title":"Simulator using Browser Build:","text":"
  • No Mac computer required
  • Must have a paid Apple Developer ID ($99/year)
  • Must have a compatible phone

Follow the normal instructions to build with browser, install the app on a compatible phone and explore the app using the Pump Simulator, CGM Simulator or both.

"},{"location":"version/simulator/#simulator-using-build-with-mac","title":"Simulator using Build with Mac:","text":"
  • Must have a Mac computer (or virtual machine, Intel chips only)
  • Can build the simulator with a free Apple Developer ID
    • Build to Mac (no phone required) or
    • Build to a Compatible Phone using Mac Build
"},{"location":"version/simulator/#build-to-a-simulated-phone-on-mac-computer","title":"Build to a Simulated Phone on Mac Computer","text":"

This simulator requires access to a Mac or virtual computer, see Compatible Computer

  • Build pages to review, but complete later
    • Apple Developer Program (can use a free account)
  • Follow Xcode Version
  • Follow Xcode Settings but can skip the Add Apple ID section
  • Follow Build the Loop App but with the following variation:
    • Skip the section on Developer Mode (that is only when building to a phone)
    • Download the code as directed
    • Choose to Sign Manually in the Signing Targets section
    • Continue with the Build Free Loop page
      • Select a simulator (not your phone) when told to do so
      • Complete the Build to a Simulator section
  • Use the simulated iPhone that will appear on you Mac and set up the app as desired
  • This gives you a feel for the interface, but the simulator on the Mac has limitations
"},{"location":"version/simulator/#build-to-a-compatible-phone","title":"Build to a Compatible Phone","text":""},{"location":"version/simulator/#build-to-a-compatible-phone-using-browser-build","title":"Build to a Compatible Phone using Browser Build","text":"

You don't need to do anything special when you build the app using the Build with Browser instructions. Install the app on your phone from TestFlight. Then select the CGM and/or Pump simulator desired. You must have a paid developer account.

"},{"location":"version/simulator/#build-to-a-compatible-phone-using-mac-build","title":"Build to a Compatible Phone using Mac Build","text":"

When building to a real phone using a Mac, you must have access to a Compatible Computer and a Compatible Phone.

  • You can use a Free Apple Developer account
  • Follow Xcode Version
  • Follow Xcode Settings
    • If you have a developer ID, use it in the Add Apple ID step and follow the normal build directions
    • If you do not have a developer ID, use the Free Developer Account instructions in the Add Apple ID section
  • Follow Build the Loop App using the Free Account instructions
    • If your phone is running iOS 16 or newer, you must enable Developer Mode
    • Download the code as directed
    • Choose to Sign Manually in the Signing Targets section
    • Continue with the Build Free Loop page
  • Once the App is on your phone
    • Follow the set up the app instructions on your phone but choose a simulated pump
    • If you have a compatible CGM on this phone, you can select that or you can use the simulated CGM or enter glucose values on the main Loop screen
"},{"location":"version/simulator/#what-to-expect","title":"What to Expect","text":"

Locked Phone or App in Background

Loop will not work in the background without either a real CGM or a real pump to \"wake\" it up.

The app will only work in the background in these special cases:

  • Loop is on on the same phone as a CGM and you've added that CGM information to Loop
  • Loop is attached to a pump (Pod or Medtronic)
    • You can configure the pump to drip water (instead of being attached to your body)

In all other cases, the phone must be open and unlocked for you to test the app.

These CGM and pump options work to provide glucose readings or accept pump commands while the app is open, but will not \"wake\" the app when in the background or phone is locked:

  • Dexcom Share
  • Nightscout Remote CGM
  • CGM Simulator
  • Pump Simulator

Disable Notifications

When you have the Loop app on your phone to test as a simulator, you may want to disable notifications when you are not actively using it. Even if you quit the app, you will get Loop not Looping notifications while the app is on your phone.

To Disable Notifications:

  1. Tap on iOS Settings -> Notifications -> Loop
  2. Disable Allow Notifications

The Loop app, when open, will be quite aggressive at warning you that you have disabled Notifications, so you can reverse those directions to enable notifications when actually using the app.

"}]} \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index 390d63c4f9ee74b558631d678a9b16013a1d50bd..86d6588eaebe099f3e1cf0613a7a54073a1f481b 100644 GIT binary patch delta 12 Tcmb=gXOr*d;E+Btk*yK{7gqzW delta 12 Tcmb=gXOr*d;Mkfnk*yK{7}*2p