diff --git a/browser/bb-update/index.html b/browser/bb-update/index.html index f1378be4ca2..f7d9cce3165 100644 --- a/browser/bb-update/index.html +++ b/browser/bb-update/index.html @@ -4150,7 +4150,7 @@

Build the App

graphic indicating how to build again

What if the Build Fails

-

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 a new release is announced at Current Release, look to see if there are instructions about extra steps required with the release. (Updating from 3.2.3 to 3.4.1 requires extra steps described above.)

If you are using the dev branch, the update steps are the same, but review information on this page: Build Loop dev with Browser.

Otherwise, head over to Errors with Browser.

Apple Email to Ignore

diff --git a/search/search_index.json b/search/search_index.json index fc7c046b4f1..218d697b693 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-is-loop-video","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":"browser/automatic/","title":"Automatic Update & Build","text":""},{"location":"browser/automatic/#overview","title":"Overview","text":"

The instructions provided for building with a browser include settings to automatically update and build for you.

This keeps the most recent version of the Loop app available in TestFlight for you to install when you are ready.

These events are automatically scheduled:

If you do not want this automatic schedule, you can modify it.

Regardless of your choice, please Disable Automatic Installation from TestFlight. You should be alert any time your Loop app is updated. Check that all settings are maintained and pay attention to make sure the app behavior is nominal.

You still need to take these actions to ensure a recent build of the Loop app is available in TestFlight for you to install on your phone when you choose:

"},{"location":"browser/automatic/#successful-weekly-action","title":"Successful Weekly Action","text":"

Normally, you will see a successful build action once a week. This happens at 08:00 UTC every Wednesday.

If there are no updates to the main branch, your actions show a very short, successful build action as shown in the graphic below. It only takes about a minute because the logic says - no update then skip the build.

If there is an update, the build action updates your fork and creates a new build.

In that case, you should check your favorite information site to find out what the update was and then, when you are ready, install the update using the TestFlight app on your phone.

"},{"location":"browser/automatic/#successful-monthly-action","title":"Successful Monthly Action","text":"

On the first day of every month at 06:00 UTC, you will see a successful build action. The purpose of this build is to provide a recent version of the app in TestFlight so you are never in a situation where you have no app on your phone.

You start getting Notifications when there are fewer than 20 days until expiration. When you see the warning, install the newest build from your TestFlight app. You do not want to get the dreaded \"Loop Beta is not available\" message on your phone. (The warnings get very agressive when close to expiration.)

"},{"location":"browser/automatic/#what-are-the-alive-branches","title":"What are the alive branches?","text":"

The automatic update and build feature is embedded in the build_loop.yml code and uses the GitHub scheduling feature to trigger actions to run automatically.

Some may have noticed one or more branches added to your repository that start with the name alive. Don't worry about these. They are automatically created to ensure GitHub will keep building your app automatically.

You may see branches called alive, alive-dev or alive-main in your repository.

The alive branches are created and used to make sure at least one commit per month is added to an alive branch in your repository. That keeps your repository active to allow the automatic update and build process to work.

The alive branches are only used for the keep-alive functions. Do not build using an alive branch. Most people will build using the default branch of main.

"},{"location":"browser/automatic/#automatic-creation-of-alive-branch","title":"Automatic Creation of alive branch","text":"

The alive branch you need is created automatically when you run the Build Loop action.

I got an error regarding a branch with alive in the name

"},{"location":"browser/automatic/#modify-automatic-building","title":"Modify Automatic Building","text":"

For someone using development code for their own use, they could decide to choose when to update their fork to the most recent commit. They can still have the advantage of automatic building without automatic updates; in other words, they want a new build added to TestFlight every month. There may be other configurations someone would choose. These options are available starting with Loop 3.3.0 (dev branch) and later.

You can affect the default behavior:

  1. Modify Automatic Schedule
  2. Disable Automatic Actions
"},{"location":"browser/automatic/#modify-automatic-schedule","title":"Modify Automatic Schedule","text":"

This is an optional step. If you are happy with the automatic sync and update, you are done with this page.

Instructions to Modify the Automatic Actions (Click to Open/Close)

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 N/A) true (or N/A) This is the default:keep-alive, weekly update check (auto update/build), monthly build with auto update false true (or N/A) keep-alive, monthly build, no auto update true (or N/A) false keep-alive, weekly update check with auto update, only builds if update detected false false no automatic activity, no keep-alive"},{"location":"browser/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:
  6. To disable scheduled syncing, add a variable:

Your build will run on the following conditions:

"},{"location":"browser/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
  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":"browser/automatic/#stop-building","title":"Stop Building","text":"

What if I decide I don't want the automatic building feature?

"},{"location":"browser/bb-errors/","title":"Errors with Browser","text":""},{"location":"browser/bb-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 the link to your repository. For example - this link is used to test the build instructions and generate figures for LoopDocs. You replace your GitHub username where you see loopdocs-tester:

Mentors can go to your public\u00a0GitHub repository, make sure your code is up to date, examine your customizations (if any), then click on the Action tab and 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 link or as a bare minimum your GitHub username.

But first - try to diagnose it yourself using this page.

"},{"location":"browser/bb-errors/#most-common-mistakes","title":"Most Common Mistakes","text":"

Just updated?

If you just updated to version 3.4 from version 3.2.x, you must add a new Identifier.

If you missed this step - go do it now. Update from 3.2.x to 3.4

Certificate is missing

If you get this build error message: No code signing identity found and can not create a new one because you enabled, you do not have certificates needed to run the build.

These are some of the most common errors to date.

  1. You made a spelling error when adding Secrets
  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
  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
  7. You got an error regarding a branch with alive in the name
"},{"location":"browser/bb-errors/#error-annotations","title":"Error Annotations","text":"

Error annotations are available for the Loop app released version 3.4 and later. These were contributed by community volunteers along with the improvements to enable automatic updates and automatic builds.

Not all error messages have an annotation yet. In those cases, you will be required to search for the error string as explained in Find the Error.

"},{"location":"browser/bb-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.

"},{"location":"browser/bb-errors/#annotation-with-clear-message","title":"Annotation with Clear Message","text":"

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

"},{"location":"browser/bb-errors/#annotation-without-clear-message-certificates","title":"Annotation without Clear Message (Certificates)","text":"

Not all error messages have a clear annotation (yet).

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.

"},{"location":"browser/bb-errors/#missing-certificates","title":"Missing Certificates","text":"

If your certificates have expired, you will see this error when you try to build. It does not have a clear annotation. The error string starts with: No code signing identity found and can not create a new one because you enabled.

"},{"location":"browser/bb-errors/#annotation-without-clear-message-build","title":"Annotation without Clear Message (Build)","text":"

The GIF below shows a failure of\u00a0GitHub Action: 4. Build Loop\u00a0. The nice messages have not been added to this yet - you will have to follow the Find the Error instructions, but now, you are automatically taken to the correct section so there is less of the log to deal with.

"},{"location":"browser/bb-errors/#find-the-error","title":"Find the Error","text":"

This section is required when you need to search for a string to diagnose and error that does not have a clear annotation.

"},{"location":"browser/bb-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":"browser/bb-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 Annotation 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. For each section there are possible strings to paste to search the log.

Error annotations are available for the Loop app version 3.4 and later for some of the actions. We believe the first two actions have a complete set of error annotations.

  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":"browser/bb-errors/#still-stuck","title":"Still Stuck?","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":"browser/bb-errors/#action-validate-secrets-errors","title":"Action: Validate Secrets Errors","text":"

For Version 3.4 and later - use Examine Annotation and read the annotation.

"},{"location":"browser/bb-errors/#action-add-identifiers-errors","title":"Action: Add Identifiers Errors","text":"

For Version 3.4 and later - use Examine Annotation and read the annotation.

"},{"location":"browser/bb-errors/#action-create-certificates-errors","title":"Action: Create Certificates Errors","text":"

Review Examine Annotatios for instructions on how to use the error strings.

"},{"location":"browser/bb-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:

Click on this link to Delete Identifiers.

"},{"location":"browser/bb-errors/#rerun-steps-with-correct-teamid","title":"Rerun Steps with correct TEAMID","text":"

  1. Enter your TEAMID correctly in the repository Secrets

  2. Run Action: Configure to Use Browser: Add Identifiers again

  3. 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":"browser/bb-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
  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
  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":"browser/bb-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":"browser/bb-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":"browser/bb-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":"browser/bb-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":"browser/bb-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
  2. To create a new Certificate:
  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":"browser/bb-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":"browser/bb-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

If you had to step backward and fix an Identifier, you must run Create Certificates again.

Refer to Annotation without Clear Message (Build) for a detailed example of these steps:

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":"browser/bb-errors/#error-could-not-find-an-app-on-app-store-connect","title":"Error: 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":"browser/bb-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, you might see:

Return to First-Time: Identifiers for the Loop app and make sure you followed all the steps.

You must create certificates again before you can build Loop:

"},{"location":"browser/bb-errors/#error-a-new-one-cannot-be-created-because-you-enabled","title":"Error: 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)

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":"browser/bb-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 Annotation instructions to find your error message.

"},{"location":"browser/bb-errors/#error-asset-validation-failed","title":"ERROR: Asset validation failed","text":"

This error indicates your fork needs to be updated. As of 29 April 2024, you are required to use Xcode 15 to build the app.

There are serveral phrases you can check for. All of them have the same solution.

Copy the words on the line below and paste them into the search function for your action log.

ERROR: Asset validation failed\n
Could not download/upload from App Store Connect\n

Solution: Update your fork. See instructions on the Update page: Update Fork

"},{"location":"browser/bb-errors/#intermittent-testflight-upload-number-error","title":"Intermittent TestFlight Upload Number Error","text":"

This is an intermittent error

Looking into history, we see that this error has been reported intermittently over the last few years.

Copy the words on the line below and paste them into the search function for your action log.

Error: The provided entity includes an attribute\n

The full error looks like this: Error: The provided entity includes an attribute with a value that has already been used The bundle version must be higher than the previously uploaded version: #

Examine the number that is there. If it is 3, you need to use 4 in the Solution step. If it is 53, you use 54.

Solution: You must force Apple to update to a build number higher than the one it has on record.

Summary of what you will do (don't do it yet); there are detailed steps and graphics below:

  1. You will edit the Fastfile in your fork and save the changes to a new patch branch
  2. Perform the Action to Build Loop and select the patch branch when you build

There is no reason to expect subsequent builds to fail with this same error, but if it does, repeat this section.

"},{"location":"browser/bb-errors/#prepare-your-fork","title":"Prepare your fork","text":"

The graphic below shows the steps to make sure your fork is up to date and to locate the fastfile folder:

  1. Select the branch that you plan to build
  2. Check the fork for that branch is up to date

  3. Scroll down to locate the folder fastlane and click on it (next graphic)

"},{"location":"browser/bb-errors/#prepare-to-edit-your-fastfile","title":"Prepare to Edit your Fastfile","text":"
  1. After clicking on the fastlane folder, 3 files are visible; click on Fastfile
  2. When the Fastfile file opens click on the pencil icon so you can edit the file
"},{"location":"browser/bb-errors/#edit-your-fastfile","title":"Edit your Fastfile","text":"

  1. Type either Cmd+F (Mac) or Ctrl+F (PC) to reveal the find and replace dialog shown in the graphic below

    previous_build_number + 1\n

  2. Tap on the Find button and the Replace button to make 2 changes to the file

  3. After modifying the two lines, click on the Commit changes button at upper right

"},{"location":"browser/bb-errors/#save-to-a-patch-branch","title":"Save to a Patch Branch","text":"

Refer to the graphic below. The number 3 by the Commit changes button indicates the selection made in the previous step; it is shown for reference.

  1. Tap on indicator that you will save to a new branch - GitHub will automatically name it for you
  2. Tap on Propose changes button and then STOP; do not click on Open pull request - you are done with this step

"},{"location":"browser/bb-errors/#build-using-patch-branch","title":"Build using Patch Branch","text":"

Select Action: Build Loop

Refer to the first graphic below:

There is not a lot of indication that the build started - be patient - or refresh the screen - do NOT start another build. Your build status should be similar to the next graphic.

Once you get a successful build, you return to using your normal branch for future builds.

There is no reason to expect subsequent builds to fail with this same error, but if it does, repeat this section.

"},{"location":"browser/bb-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":"browser/bb-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
  2. In your fork of LoopWorkspace:
  3. 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":"browser/bb-errors/#misleading-error-message_1","title":"Misleading Error Message","text":"

If there are Apple Developer agreements you have not accepted, you will get errors when you try to build the app that indicate your Apple Secrets are incorrect.

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.

If you need detailed instructions, click on this Apple Program License Agreement Help Page.

"},{"location":"browser/bb-errors/#extra-sections","title":"Extra Sections","text":"

It is unlikely you will need these sections. They are being saved for the transition to version 3.4.x. The Match-Secrets repository is automatically created for you if you don't have one. The instructions below were used when you had to create yours manually.

"},{"location":"browser/bb-errors/#create-match-secrets","title":"Create Match-Secrets","text":"

Open your github.com URL (this is https://github.com/username), (username is your GitHub account name).

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":"browser/bb-errors/#delete-identifiers","title":"Delete Identifiers","text":"

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. If a Bundle ID has ever been associated with an app in the App Store, you cannot delete the Identifier.

If coming here because you enter the wrong TEAMID in Secrets - return to Rerun Steps with Correct TEAMID when you've deleted as many identifiers as you can.

After you delete identifiers, you must add them back, configure them and create certificate before you can build again.

"},{"location":"browser/bb-overview/","title":"Browser Overview","text":""},{"location":"browser/bb-overview/#build-with-a-browser","title":"Build with a Browser","text":""},{"location":"browser/bb-overview/#requirements","title":"Requirements","text":""},{"location":"browser/bb-overview/#phone-cgm-and-pump","title":"Phone, CGM and Pump","text":"

To use the Loop app, you need:

"},{"location":"browser/bb-overview/#accounts","title":"Accounts","text":"

To build the\u00a0Loop\u00a0app using a browser, you need:

  1. Free GitHub account: (instructions found at New GitHub Account)
  2. Paid Apple Developer account: ($99/year; instructions found at Apple Developer Account)
"},{"location":"browser/bb-overview/#instructions-to-build-with-a-browser","title":"Instructions to Build with a Browser","text":""},{"location":"browser/bb-overview/#how-to-video-to-build-with-a-browser","title":"How-to Video to Build with a Browser","text":"

In addition to the pages linked in Configure to use Browser, there is a narrated video of each step needed to build using a browser. (This video shows build steps for version 3.2.3 or older. Some items are simplified for version 3.4.1 and newer.)

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":"browser/bb-overview/#configure-to-use-browser","title":"Configure to use Browser","text":"

There is a lot of information in the introduction and summary page. Please don't skip that. it should be read before you begin. The steps on these pages must be completed for you to build an app using a browser:

  1. Introduction and Summary
  2. Collect Secrets
  3. Prepare Fork
  4. Identifiers
  5. Prepare App
  6. Create Certificates
  7. Build the Loop App
  8. TestFlight Users
"},{"location":"browser/bb-overview/#install-on-phone","title":"Install on Phone","text":"

Instructions to install on a phone are found at:

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

Try to:

"},{"location":"browser/bb-overview/#errors-while-configuring-and-building","title":"Errors while Configuring and Building","text":"

If you get an error that you cannot figure out, reach out for help before you get frustrated or begin to delete things - let a mentor help you:

"},{"location":"browser/bb-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. Once again, this was prepared for an earlier version 3.2.3 or older. With version 3.4.1 and newer, the update and build is automatic:

"},{"location":"browser/bb-overview/#other-topics","title":"Other Topics","text":""},{"location":"browser/bb-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":"browser/bb-overview/#mac-vs-browser","title":"Mac vs Browser","text":"

These considerations were prepared when most people were using a Mac computer to build the Loop app.

"},{"location":"browser/bb-update/","title":"Update/Rebuild with Browser","text":""},{"location":"browser/bb-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

One Time: Complete the information for the Digital Service Act Compliance

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 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":"browser/bb-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":"browser/bb-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":"browser/bb-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.

Digital Service Act Compliance

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":"browser/bb-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":"browser/bb-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

  2. Navigate to your Match-Secrets Repository

  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:

    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.

Other Apps

If you build other apps using the build with browser method, they have just had their certificates revoked.

"},{"location":"browser/bb-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.

"},{"location":"browser/bb-update/#up-to-date-or-behind","title":"Up to Date or Behind","text":"

"},{"location":"browser/bb-update/#ahead-and-behind","title":"Ahead and Behind","text":"

Building a different branch

Do I need to do anything special to build a different branch?

Yes: the update steps are the same, but review information on this page: Build Loop dev with Browser

"},{"location":"browser/bb-update/#build-the-loop-app","title":"Build the Loop App","text":"

This is Step 4 of 6 - this is always required.

"},{"location":"browser/bb-update/#update-from-32x-to-34","title":"Update from 3.2.x to 3.4","text":"

For the update from 3.2.x to 3.4, you must do more than \"just\" build. If you skip this step - the build will fail.

If you built version 3.3.0 (the dev branch before release of version 3.4) or newer, you can skip ahead to Build the App.

You will (1) run Add Identifiers, (2) add the App Group to the new identifier, (3) run Create Certificates and then (4) run Build Loop.

"},{"location":"browser/bb-update/#add-identifiers","title":"Add Identifiers","text":"

In your fork of LoopWorkspace:

Detailed instructions for Add Identifier (Click to open/close)

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 dropdown menu

  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":"browser/bb-update/#add-app-group-to-new-identifier","title":"Add App Group to New Identifier","text":"

Open the Certificates, Identifiers & Profiles: Identifiers List page.

Click on the \"LoopWidgetExtension\" identifier to open the Edit Your App ID Configuration screen.

NAME IDENTIFIER Loop Widget Extension com.TEAMID.loopkit.Loop.LoopWidgetExtension

The graphic below has numbered steps that match these directions:

  1. Looking at the App Services column, scroll down to the App Groups row and ensure the check box (under the Capabilities column) for App Groups is checked
  2. If the word Configure shows up, tap on it
  3. Check the box by Loop App Group that uses your TEAMID in group.com.TEAMID.loopkit.LoopGroup
  4. Tap Continue
  5. Tap Save

If you did not need to make changes, the Save button will not be active.

The full list of Identifiers should be displayed again.

Other Identifiers

All other identifiers should be already set up.

"},{"location":"browser/bb-update/#create-certificates","title":"Create Certificates","text":"

You must run the action Create Certificates again because the Identifiers were updated. Wait for this to succeed before trying to build.

Detailed instructions (Click to open/close)

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 dropdown menu

  4. Tap the green button that says \"Run workflow\".

  5. Wait a minute or two for the action to finish

"},{"location":"browser/bb-update/#build-the-app","title":"Build the App","text":"

Refer to graphic below as you follow the steps to build the Loop app.

"},{"location":"browser/bb-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, the update steps are the same, but review information on this page: Build Loop dev with Browser.

Otherwise, head over to Errors with Browser.

"},{"location":"browser/bb-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":"browser/bb-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":"browser/bb-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 app will show up in your TestFlight app.

"},{"location":"browser/bb-update/#testflight-automatic-update-disabled","title":"TestFlight 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":"browser/bb-update/#testflight-automatic-update-enabled","title":"TestFlight 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":"browser/bb-update/#other-information","title":"Other Information","text":""},{"location":"browser/bb-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:

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. If you choose to Add Test Details to TestFlight, you can have notes show up to help you decide which version to load.

"},{"location":"browser/bb-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":"browser/bb-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.

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":"browser/bb-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":"browser/bb-update/#add-test-details-to-testflight","title":"Add Test Details to TestFlight","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":"browser/build-dev-browser/","title":"Build Loop dev with Browser","text":""},{"location":"browser/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":"browser/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
  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":"browser/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:
  2. Click on the New branch button and follow the Add Branch steps

"},{"location":"browser/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
  4. Review the dialog items to make sure everything is correct and then tap on Create branch

"},{"location":"browser/build-dev-browser/#update-branch","title":"Update Branch","text":"

If you normally build released code, but decided to build the dev branch because you want the features and bug fixes found there, please do not update the fork for the dev branch without first finding out what has changed since your last build.

Tap the Code button (upper left) and ensure this branch in your fork is up to date.

"},{"location":"browser/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.

With the release of version 3.4, no one-time changes are required. This assumes you built main after the release of 3.4.

"},{"location":"browser/build-dev-browser/#build-branch","title":"Build Branch","text":"

We recommend most users leave their default branch as main.

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. In addition to the normal steps 1, 2 and 3 in the graphic below, you must also do the (optional) step. Select the dev branch in the branch dropdown menu before continuing to step 4 and tapping on the green Run workflow button.

"},{"location":"browser/build-dev-browser/#refresh-do-not-repeat","title":"Refresh, Do Not Repeat","text":"

Hit Refresh

After you tap the green Run workflow button, GitHub can be slow to update.

"},{"location":"browser/build-dev-browser/#automatic-update-build","title":"Automatic Update & Build","text":"

The Automatic Update & Build features are applied to the default branch of your repository. Normally this is the main branch. If you are a developer or tester who wants the dev branch to be built automatically, you must configure it as your default branch. Be aware that for this situation, you will not get automatic updates of released code.

Most people should keep main as default and make a considered decision when to launch a manual build of the dev branch. At that time, it will automatically update to the latest dev commit unless you have modified your environment settings: Modify Automatic Building.

"},{"location":"browser/build-dev-browser/#change-default-branch","title":"Change Default Branch","text":"

We recommend most users leave their default branch as main.

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

  2. To the right of the default branch name there is a pencil and a left-right arrow icon

  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.

Your default branch has been changed.

"},{"location":"browser/build-dev-browser/#automatic-update-build_1","title":"Automatic Update & Build","text":"

The automatic update and build features are available for both the released (main) and development (dev) branch, but only for your default branch. For any other branch name set as your default branch, there is no automatic update available but the automatic build will run monthly.

Be sure to read this page: Automatic Update & Build.

"},{"location":"browser/build-yml/","title":"Build the App","text":""},{"location":"browser/build-yml/#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
  6. Your app should eventually appear on App Store Connect.
  7. For each phone/person you would like to support:

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 dropdown menu

  4. Tap the green button that says \"Run workflow\".

  5. Wait a few minutes to make sure there is not an early failure

Be Patient

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.

You should get several emails

Your app should eventually appear on App Store Connect.

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

Congratulations

If you get the green check mark, your app successfully built. Just a few more steps.

"},{"location":"browser/build-yml/#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":"browser/build-yml/#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":"browser/build-yml/#next-steps","title":"Next Steps","text":"

If this is your first build, you need to configure your TestFlight Users

If this is a repeat build, wait up to an hour for your new build to appear in TestFlight. Then from the phone where you want to install the Loop app, use TestFlight on that phone to install the app.

"},{"location":"browser/build-yml/#caregivers","title":"Caregivers","text":"

If you are a Caregiver who helps manage a loved-ones diabetes, you may use other open-source apps that can be built the same way:

"},{"location":"browser/certs/","title":"Create Certificates","text":""},{"location":"browser/certs/#overview","title":"Overview","text":"

The instructions on this page are required to build your app intially. This action ties information in your Match-Secrets private repository to your Apple information so that the build action works. Once successful that, it only needs to be run again in a few cases.

"},{"location":"browser/certs/#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 dropdown menu

  4. Tap the green button that says \"Run workflow\".

  5. Wait a minute or two for the action to finish

Be Patient

"},{"location":"browser/certs/#success","title":"Success","text":"

Once you see the green check mark by Create Certificates, the next step is to Build your Loop App.

"},{"location":"browser/certs/#failure","title":"Failure","text":"

If this action fails, head over to the errors page. Review these links, identify and fix your error or ask for help.

"},{"location":"browser/custom-browser/","title":"Customize using Browser","text":""},{"location":"browser/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":"browser/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":"browser/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":"browser/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":"browser/edit-browser/","title":"Custom Edits with Browser","text":""},{"location":"browser/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":"browser/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":"browser/edit-browser/#overview","title":"Overview","text":"

Time Estimate

Summary

FAQs

"},{"location":"browser/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":"browser/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":"browser/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 Personalized Customization for this Module.

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:
  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":"browser/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":"browser/edit-browser/#create-your-fork-for-selected-module","title":"Create your Fork for Selected Module","text":"

Choose your link:

"},{"location":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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
  4. You should see a screen similar to the example below

"},{"location":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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.

"},{"location":"browser/edit-browser/#prepare-customization-lines","title":"Prepare customization lines","text":"

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":"browser/edit-browser/#update-loopworkspace","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":"browser/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 lines that you prepared in Prepare customization lines similar to the examples, near line 239, that are commented out and provided as an example. The best place to paste these is at the end of the # Customize Loop: Download and apply patches section and before the # Patch Fastlane Match to not print tables line.

The indenting needs to match, so tab or (shift-tab) to line up the columns.

It is best to leave a blank line between customizations.

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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/edit-browser/#special-cases","title":"Special Cases","text":""},{"location":"browser/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":"browser/edit-browser/#background-information","title":"Background Information","text":""},{"location":"browser/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":"browser/identifiers/","title":"Identifiers","text":""},{"location":"browser/identifiers/#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":"browser/identifiers/#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 dropdown menu

  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.

Hit Refresh

After you tap the green Run workflow button, GitHub can be slow to update.

"},{"location":"browser/identifiers/#add-identifiers","title":"Add Identifiers","text":"

Update to Version 3.4

The name and identifier for \"Small Status Widget\" was renamed to \"Loop Widget Extension\". If you previously built, you will need to run the Add Identifiers as directed on the update page to add the renamed Identifier and Create Certificates for it.

If you previously built the dev branch, you already have this identifier.

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 dropdown menu

  4. Tap the green button that says Run workflow.

Be Patient

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":"browser/identifiers/#next-step","title":"Next Step","text":"

The next step is to Prepare the App.

"},{"location":"browser/intro-summary/","title":"Introduction and Summary","text":""},{"location":"browser/intro-summary/#summary-of-steps","title":"Summary of Steps","text":"Time Estimate (click to open/close) Summary for Browser Build with Links (click to open/close)

You may be overwhelmed at first with all the new terms and the many steps. Take a deep breath and work through the steps one at a time.

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 LoopDocs section.

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":"browser/intro-summary/#automatic-build-of-loop","title":"Automatic Build of Loop","text":"

When you follow the directions to configure building with a browser, for Loop 3.4 and later, you configure your app to automatically build at least once a month. You also configure your app to be updated within one week of a new release, in other words, when the LoopKit/LoopWorkspace main branch is updated. For details, see Automatic Update & Build.

"},{"location":"browser/intro-summary/#tips-and-tricks","title":"Tips and Tricks","text":"

The steps to configure for building with a browser requires a lot of focused attention. Take it in steps and take breaks as needed. Some people prefer a video. Some people prefer more detailed steps on a webpage and others only high-level steps.

"},{"location":"browser/intro-summary/#how-to-video-to-build-with-a-browser","title":"How-to Video to Build with a Browser","text":"

There is a narrated video of each step needed to build using a browser. This video was created for version 3.2.x and some steps have been simplified with version 3.4.x.

Click in the comments for a full index of topics. If you have issues with a particular section, 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":"browser/intro-summary/#section-summaries","title":"Section Summaries","text":"

Some sections have a Section Summary for those who just want high-level steps without a lot of graphics. It also provides a high-level view of what you are going to do before you do it.

"},{"location":"browser/intro-summary/#sparse-instructions","title":"Sparse Instructions","text":"

For sparse instructions, with no graphics or hand-holding, click on the link below:

"},{"location":"browser/intro-summary/#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.

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 or hyphens. 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.

"},{"location":"browser/intro-summary/#make-a-secrets-reference-file","title":"Make a Secrets Reference File","text":"

Please save yourself a lot of agony. Make a Secrets Reference folder and then create a Secrets Reference file in it.

You don't need to know anything about the Secrets to do this. Come up with your own names, but make sure you know where you put this file.

  1. Decide where you want your Secrets saved and create a special folder
  2. Open a text-only editor (do not use a Smart Editor, those might change capitalization or formating and ruin your Secrets)
  3. As you move through the steps of Collect Secrets, fill in the file
  4. In addition to the Secrets, this template has places for other pieces of information you may find handy to save in the same file
  5. At the very beginning is a place to indicate the last day you updated the file
Template to use for Secrets
MySecretsReferenceFile.txt\n\n## This file updated on: DD MMM YYYY\n\nInformation needed to use Browser Build.\nThe same secrets are used for every app you build.\n\nFirst some handy username and password information:\n\n## Apple ID username for your Developer account is the associated email:\n<your information here>\nsuggest you use your desired password tool to save the password for this account\n\n## GitHub username\n<your information here>\nsuggest you use your desired password tool to save the password for this account\n\nThese are the Six Secrets in alphabetical order - each one shows the expected format.\nDelete each prototype as you gather your own secrets.\nThe letter A indicates an alphanumeric character.\nSome may be lower case, some upper case and some numerals.\nThe FASTLANE_KEY may have additional characters included.\nFor that one copy the entire key\nincluding -----BEGIN PRIVATE KEY-----\nthrough\n-----END PRIVATE KEY-----\n\n## SECRETS BELOW:\n\nFASTLANE_ISSUER_ID\n<looks like this>\nAAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA\n\nFASTLANE_KEY_ID\n<looks like this>\nAAAAAAAAAA\n\n\nFASTLANE_KEY\n<looks like this>\n-----BEGIN PRIVATE KEY-----\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nAAAAAAAA\n-----END PRIVATE KEY-----\n\nGH_PAT\n<looks like this>\nghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n\nMATCH_PASSWORD\n<looks like this>\nAnyThingYouWant-sameForEveryRepository\n\nTEAMID\n<looks like this>\nAAAAAAAAAA\n\n## Repository Names for my Fork:\n\nhttps://github.com/my-github-username/LoopWorkspace\n\nAdd additional apps here if you decide to build any\n
"},{"location":"browser/intro-summary/#new-terms-with-github-browser-build","title":"New Terms with GitHub Browser Build","text":"

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.

"},{"location":"browser/intro-summary/#next-step","title":"Next Step","text":"

The next step is to Collect and Save Secrets.

"},{"location":"browser/other-apps/","title":"Build Other Apps with Browser","text":""},{"location":"browser/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":"browser/other-apps/#updating-rebuilding-other-apps","title":"Updating / Rebuilding Other Apps","text":"

If you are coming to this page to update one of the other apps, follow the How to Update or Rebuild instructions provided for the Loop app, but substitute the repository name from the Table of App Repositories for the app you want to rebuild for all references to\u00a0LoopWorkspace.

"},{"location":"browser/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":"browser/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":"browser/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":"browser/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":"browser/other-apps/#fork-and-add-secrets","title":"Fork and Add Secrets","text":""},{"location":"browser/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":"browser/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":"browser/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":"browser/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

  3. Tap on New repository secret and add each of the 6 Secrets

Once all six Secrets are added, proceed to the first Action to validate your secrets.

"},{"location":"browser/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 dropdown menu
  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":"browser/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 dropdown menu

  4. Tap the green button that says \"Run workflow\"

The Add Identifier Action\u00a0 should succeed or fail in a few minutes.

"},{"location":"browser/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":"browser/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":"browser/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":"browser/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
  4. Click Continue and then Register.
"},{"location":"browser/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":"browser/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":"browser/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

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

  3. If you did not need to make changes, the Save button will not be active.

  4. The full list of Identifiers should be displayed again.

  5. 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":"browser/other-apps/#create-app-in-app-store-connect","title":"Create App in App Store Connect","text":"

Same procedure as for the Loop app

You will follow the same procedure as you did with the Loop app.

You will also want to edit your new app once you create it to Remove Apple Vision Pro.

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.

  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.

  6. Edit your new app to Remove Apple Vision Pro

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":"browser/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 dropdown menu

  4. Tap the green button that says \"Run workflow\".

  5. Wait a minute or two for the action to finish

"},{"location":"browser/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":"browser/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":"browser/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 dropdown menu

  4. Tap the green button that says \"Run workflow\".

  5. Wait a few minutes to make sure there is not an early failure

  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":"browser/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":"browser/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":"browser/other-apps/#use-a-github-organization-account","title":"Use a GitHub Organization Account","text":"

This section is optional. It is provided to assist:

"},{"location":"browser/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)
  2. You now see a Welcome screen
  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":"browser/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

  3. For each repository: you need to fork for each app you wish to build to the new my-name-org account

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":"browser/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":"browser/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":"browser/other-apps/#option-1-delete-repository","title":"Option 1: Delete repository","text":"

You can delete the DIY repositories from your personal account

"},{"location":"browser/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":"browser/phone-install/","title":"Install on Phone","text":""},{"location":"browser/phone-install/#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. With version 3.4.0 and later, the build is automatic. It is recommended you manually install the new build using TestFlight at your convenience.

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":"browser/phone-install/#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":"browser/phone-install/#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":"browser/phone-install/#subsequent-times-on-phone","title":"Subsequent Times on Phone","text":""},{"location":"browser/phone-install/#automatic-update-build-install","title":"Automatic Update, Build, Install","text":"

The instructions on the Configure to Use Browser page will, unless you make a change, automatically take the following actions for released versions 3.4.0 and later:

It is already true that, unless you make a change, the default setting will:

"},{"location":"browser/phone-install/#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 Automatic Update & Build.

"},{"location":"browser/phone-install/#disable-automatic-install-from-testflight","title":"Disable Automatic Install from TestFlight","text":"

Once the app is available in TestFlight, 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":"browser/phone-install/#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 the Loop app). 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":"browser/phone-install/#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":"browser/prepare-app/","title":"Prepare App","text":""},{"location":"browser/prepare-app/#prepare-the-app","title":"Prepare the App","text":"

After creating the identifiers, you will need to modify to make sure the correct App Group is associated with each identifier (there will be instructions) and you need to prepare the App - one of those identifiers just created is used as the Bundle ID for building your app. This can be a little confusing and a lot of pages over at Apple look the same. Make sure you follow the links given for each section.

"},{"location":"browser/prepare-app/#configure-identifiers-for-loop","title":"Configure Identifiers for Loop","text":"

This should only be needed one time, unless the developers add or modify an identifier. This happened between version 3.2 and version 3.4.

Some steps can be skipped if you previously built the Loop app with a Mac using Xcode.

Please read carefully to avoid confusion.

"},{"location":"browser/prepare-app/#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 Optional: App Group Description Modification.

  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

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 Optional: App Group Description Modification to update the description.

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
  5. Click Continue and then Register.

If this is successful, then skip ahead to Add App Group

If you get an error saying An Application Group with Identifier 'group.com.TEAMID.loopkit.LoopGroup' is not available. Please enter a different string, that means you already have the Loop App Group assigned to your account. Continue with the next section.

"},{"location":"browser/prepare-app/#optional-app-group-description-modification","title":"Optional: App Group Description Modification","text":"

This step is not required, but if you previously built using a Mac with Xcode, it is a good idea to update the Name associated with the Identifier for the Loop App Group. Then what you see on your display will match the directions as you continue.

Optional Rename Step (click to open/close)

Click to display the App Group List

Tap on the Identifier that shows group.com.TEAMID.loopkit.LoopGroup where TEAMID is your Developer ID.

Notice in the table below that the XCode version of the NAME for the App Group is the same as the IDENTIFIER but with the . replaced with a space.

NAME XCode version IDENTIFIER Loop App Group group com TEAMID loopkit LoopGroup group.com.TEAMID.loopkit.LoopGroup"},{"location":"browser/prepare-app/#add-app-group","title":"Add App Group","text":"

First, review the Identifiers and then Add App Group to Identifiers.

"},{"location":"browser/prepare-app/#identifiers-for-the-loop-app","title":"Identifiers for the Loop app","text":"

Identifier change after version 3.2.x

One of the identifier names changed when transitioning from version 3.2.3.

This is indicated in the Table of identifiers with v3.2 or v3.4.

If you ever built the Loop app using Mac, skip ahead to Previous Xcode Builders.

"},{"location":"browser/prepare-app/#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.

"},{"location":"browser/prepare-app/#previous-xcode-builders","title":"Previous Xcode Builders","text":"

If you built previously using a Mac with Xcode, you may see the XCode version in your NAME column of the table below.

If you want your NAME column to match the documentation, follow this optional step.

Optional Rename Step (click to open/close)

Referring to the table below, tap on each IDENTIFIER that has a different NAME

Only the Identifer Bundle ID matters and that is not something you can edit.

The Description or Name can be whatever you want.

"},{"location":"browser/prepare-app/#table-with-name-and-identifier","title":"Table with Name and Identifier","text":"

One Identifier was changed after v3.2.3. (Small Status Widget is now Loop Widget Extension).

NAME XCode version IDENTIFIER Loop XC com TEAMID loopkit Loop com.TEAMID.loopkit.Loop Loop Intent Extension XC Identifier com.TEAMID.loopkit.Loop.Loop-Intent-Extension Loop Status Extension XC Identifier com.TEAMID.loopkit.Loop.statuswidget Loop Widget Extension XC Identifier com.TEAMID.loopkit.Loop.LoopWidgetExtension WatchApp XC Identifier com.TEAMID.loopkit.Loop.LoopWatch WatchAppExtension XC Identifier com.TEAMID.loopkit.Loop.LoopWatch.watchkitextension v3.2 Small Status Widget XC Identifier com.TEAMID.loopkit.Loop.SmallStatusWidgetNo longer used, harmless to leave or to delete"},{"location":"browser/prepare-app/#add-app-group-to-identifiers","title":"Add App Group to Identifiers","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. The Add Identifier Action that you completed above generates 6 identifiers, but only 4 need to be modified as indicated in this step. A table, provided above, lists both Names and Identifiers for all 6 if you are interested.

Note 2 - Depending on your build history, you may find some of the Identifiers already have your \"App Group\" and you are just verifying the status.

  1. Go to Certificates, Identifiers & Profiles on the Apple Developer site.
  2. For each of the following identifier names (be sure to look in Identifier column if names do not match):
  3. Click on the identifier's name.
  4. In the App Services column, scroll down to the App Groups row
  5. Remember to do this for each of the identifiers above.

To skip the detailed instructions, click on Create Loop App in App Store Connect

Click to open the Certificates, Identifiers & Profiles: Identifiers List page.

Look in the IDENTIFIER column to locate each Identifer. The name in the NAME column may be different if you previously built with a Mac using Xcode.

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 Loop Widget Extension com.TEAMID.loopkit.Loop.LoopWidgetExtension

Click on each IDENTIFIER in turn and the Edit Your App ID Configuration screen will open.

The example graphic below has numbered steps that match these directions:

  1. Looking at the App Services column, scroll down to the App Groups row and ensure the check box (under the Capabilities column) for App Groups is checked
  2. If the word Configure shows up, tap on it
  3. Check the box by Loop App Group that uses your TEAMID in group.com.TEAMID.loopkit.LoopGroup
  4. Tap Continue
  5. Tap Save

If you did not need to make changes, the Save button will not be active.

The full list of Identifiers should be displayed again.

Repeat until the 4 Identifiers have the Loop App Group configured.

"},{"location":"browser/prepare-app/#digital-service-act-compliance","title":"Digital Service Act Compliance","text":"

In order to create an app you need to indicate whether you are a trader or a non-trader. You are a non-trader unless you use the same Developer ID to submit apps for sale.

Even if the graphic below does not match what you see exactly, it should assist in guiding you through the steps.

Open this link: App Store Connect / Apps; log in if needed.

If you do not see the banner, shown in the top of the graphic below, asking you to Complete Compliance Requirements, you can skip ahead to Create Loop App in App Store Connect.

If you do see the banner, follow the numbered steps in the graphic below:

  1. Click on the link that says \"Complete Compliance Requirements\" to open a new screen shown in the middle of the graphic below

  2. Tap on the \"Complete Compliance Requirements for Your Name\" link to bring up a pop-up shown in the bottom of the graphic below

  3. Select the \"This is a non-trader provider account\" radio button

  4. Click Save

You do not need to add a bank account or fill out tax forms if you are only using the App Store to get your own app into TestFlight. You only need to have a paid account with a valid license agreement and have completed this compliance form. Ignore other requests from Apple.

"},{"location":"browser/prepare-app/#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, make sure you Remove Apple Vision Pro and then 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.
  2. Click Create

You do not need to fill out the next form. That is for submitting to the app store.

Remove Apple Vision Pro from the app you just created.

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.

  2. There might be a blue banner present at this time. If not, it will show up after you have at least one app.

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

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

  6. 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.
"},{"location":"browser/prepare-app/#remove-apple-vision-pro","title":"Remove Apple Vision Pro","text":"

It is now time to edit the availability of your app on Apple Vision Pro. If you skip this step, you will get an annoying email telling you Apple Vision Pro is not supported by your app.

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":"browser/prepare-app/#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":"browser/prepare-app/#next-step","title":"Next Step","text":"

The next step is to Create Certificates.

"},{"location":"browser/prepare-fork/","title":"Prepare Fork","text":""},{"location":"browser/prepare-fork/#fork-loopworkspace","title":"Fork LoopWorkspace","text":"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

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

  4. Now your screen should look like the graphic below

"},{"location":"browser/prepare-fork/#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.

"},{"location":"browser/prepare-fork/#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.

"},{"location":"browser/prepare-fork/#prepare-to-enter-secrets","title":"Prepare to Enter Secrets","text":"

Log into GitHub.

  1. Return to your forked copy of LoopWorkspace

  2. Click on LoopWorkspace to open that repository

  3. Click on the Settings Icon near the top right of your LoopWorkspace

  4. On the left side, find the Secrets and variables dropdown and choose Actions

"},{"location":"browser/prepare-fork/#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)
"},{"location":"browser/prepare-fork/#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.

"},{"location":"browser/prepare-fork/#next-step","title":"Next Step","text":"

The next step is to Validate Secrets and Add Identifiers.

"},{"location":"browser/prepare-fork/#already-have-loopworkspace","title":"Already Have\u00a0LoopWorkspace?","text":"

Some people may already have a copy (fork) of LoopWorkspace.

If your copy (fork) is not from LoopKit, follow the Delete and Start Fresh directions.

If your copy (fork) is from LoopKit:

"},{"location":"browser/prepare-fork/#delete-and-start-fresh","title":"Delete and Start Fresh","text":"

If your fork is not from LoopKit:

"},{"location":"browser/secrets/","title":"Collect Secrets","text":""},{"location":"browser/secrets/#collect-and-save-secrets","title":"Collect and Save 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":"browser/secrets/#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
  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

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":"browser/secrets/#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":"browser/secrets/#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

  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":"browser/secrets/#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

"},{"location":"browser/secrets/#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)
  2. Hover to the right of the Key ID and the Copy Key ID button shows up

  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

  5. The contents of this file will be used for FASTLANE_KEY

"},{"location":"browser/secrets/#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":"browser/secrets/#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":"browser/secrets/#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":"browser/secrets/#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":"browser/secrets/#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.

Default Settings

These instructions are a prerequisite for automatic update and automatic build.

Refer to Modify Automatic Building if you don't want to accept the default recommendation to automatically update and build.

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

    What does repo and workflow do?

  3. A new screen appears showing your access token

"},{"location":"browser/secrets/#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":"browser/secrets/#next-step","title":"Next Step","text":"

The next step is to Prepare your Fork (Copy of LoopWorkspace).

"},{"location":"browser/tf-users/","title":"TestFlight Users","text":""},{"location":"browser/tf-users/#set-up-users-and-access-testflight","title":"Set Up Users and Access (TestFlight)","text":"

You repeat this step 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. But you will need to add yourself to the TestFlight group for your App.

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:

  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

  4. As soon as you create the group, you'll be asked who should be included

"},{"location":"browser/tf-users/#next-step","title":"Next Step","text":"

It is now time to install your Loop app using the TestFlight app on the phone: Install on Phone.

"},{"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
  4. If you use the Build with Mac method
"},{"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
  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
  6. Otherwise manually add the UDID to your Developer Account
  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
  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.

  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

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/#the-file-could-not-be-unlocked","title":"The File Could not be Unlocked","text":"

Error Message: This error occurs inside Xcode with a modal alert that says:

The file \"contents.xcworkspacedata\" could not be unlocked

The solution is the same as in the previous section, Unable to read included file.

"},{"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
  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:
  2. Add the keyword SIRI_DISABLED to the LoopConfigOverride.xcconfig file

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 (on the same phone) 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.

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-and-one-cgm","title":"Dexcom G7 and ONE+ CGM","text":"

The Dexcom G7 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 G7 as far as the Loop app is concerned.

"},{"location":"build/cgm/#libre-cgm","title":"Libre CGM","text":"

With Loop 3.4 and newer versions, some Libre CGM are supported.

"},{"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":"

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/#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/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-the-loop-app","title":"Pumps Compatible with the Loop app","text":"

These types of pumps are compatible with the Loop app.

"},{"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 back of your pump to locate the sticker similar to that shown in the graphic below. 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 temporary basal rates 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 the pump firmware is compatible.

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 pump moves to 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 choose from different pump models, there are some slight differences between the Loop-compatible Medtronic pumps that may influence your decision.

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 noteworthy differences 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 people with diabetes, your 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 in some countries. Insulet stopped providing Eros pods in the US end of 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/#sooil-dana-pumps","title":"Sooil Dana pumps","text":"

Future Feature Only

Sorry but the Dana pump has not landed in released code or even dev code at this time. There is a testing fork, so check out Zulipchat Dana Pump discusion.

The information below is for the convenience of people reading along in zulipchat.

Every Dana pump has built-in BLE communications. Therefore, no RileyLink-compatible device is needed to use Dana-i / DanaRS-v3 with the Loop app.

"},{"location":"build/pump/#dana-i","title":"Dana-i","text":"

The Dana-i is the latest and greatest from the Korean pump manufacturer Sooil, released in 2020.

The special fork (see link for details) works with the Dana-i. If your version of the Loop app not from that fork, you cannot use the Dana-i.

"},{"location":"build/pump/#danars","title":"DanaRS","text":"

The DanaRS was first released in 2002, with firmware version v1 which is not supported at this time. Only firmware version v3 and onwards are supported with the Loop app. Check here to see how to check your firmware version.

The special fork (see link for details) works with the DanaRS-v3. If your version of the Loop app not from that fork, you cannot use the DanaRS-v3.

"},{"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
  2. Your version of Xcode is way out-of-date

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
  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
  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/#apple-health-storage","title":"Apple Health Storage","text":"

Is Apple Health access Required?

There is internal Loop storage of all data required for the app to operate with a 7-day history. (This is new with version 3.) So using Apple Health for data storage is not 100% required for the app to operate, but it is very useful and recommended.

If you do not give Loop permission to use Apple Health, you will see no records in the Health app from Loop for carbohydrates, insulin or glucose. LoopDocs assumes permission was enabled to Apple Health.

"},{"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":"

Choose One Method for Upload

Previously, the only method to get Loop data into Tidepool was to use their mobile app on your phone and enable that app to read from Apple Health to upload data to Tidepool.

You can now upload directly from Loop to Tidepool - this is the preferred method.

With the direct upload, be sure to disable your Tidepool mobile app from reading Apple Health on your phone. If you do not do this, you will have double uploads of all your data. You can still make notes on the mobile app; it will get your data via the internet from Tidepool.

If you are currently using the Tidepool mobile app to upload and switch to direct upload, you will get one week of double uploads. You can filter the upload source for that week on 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 following CGM are supported by some or all versions of Loop:

See also: Compatible CGM page.

"},{"location":"faqs/cgm-faqs/#dexcom-faq","title":"Dexcom FAQ","text":""},{"location":"faqs/cgm-faqs/#do-i-need-wait-for-a-new-dexcom-sensor-session-to-start-loop","title":"Do I need wait for a new Dexcom 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-dexcom-sensor-is-in-warm-up","title":"What do I do when Dexcom 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/#libre-cgm","title":"Libre CGM","text":""},{"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":"

Loop 3.4.0 and later allows any Libre sensor supported by LibreTransmitter.

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":"

It is recommended that Libre users take advantage of the LibreTransmitter that is incorporated into the Loop app itself for version 3.4 and later.

You can add xDrip4iOS and GlucoseDirect as a CGM option to the Loop app by applying a code customization. However, this uses the shared AppGroup feature to transfer data from the CGM app to Loop. This is not the preferred approach.

Please read the docs for xDrip4iOS and Glucose Direct. You must build these apps yourself so they have the same developer ID as your Loop app; 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

dynamic carb absorption\u00a0 (dynamic carb absorption): Loop models the expected glucose change based on carbs entered, absorption time and your settings; and adjusts based on measured glucose

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 - Refers to the difference between observed change in blood glucose and the change in blood glucose that Loop models based on the effects of insulin.

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
  2. Use iCloud backup from old phone to transfer information to the new phone

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)
  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
  2. Install\u00a0Loop\u00a0on the new phone (all your settings should be there)
  3. As soon as you install the Loop app on the new phone, go ahead and disable Closed Loop.
"},{"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
  2. Phone Settings, Bluetooth
  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/#libre-cgm","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

  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/#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 Change Pump Type 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.

Loop 3 is compatible with the OrangeLink.

"},{"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

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":"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.
  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.
"},{"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/#loopdocs-contents","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/#building-loop","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/#operating-loop","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
  5. Apple Developer Membership
"},{"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-or-one","title":"Dexcom G7 or ONE+","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/#libre","title":"Libre","text":"

The Libre plugin for Loop, LibreTransmitter, connects directly via Near Field Communication (NFC) during pairing (for some sensors) and via Bluetooth (direct to sensor or direct to a transmitter attached to the sensor) for regular readings. No other app is needed.

Connecting to Libre

First reading for a new sensor will often take 2-4 minutes. This is due to some technicalities on how the Libre sensor announces its presence via bluetooth.

There are solutions for some Libre 3 but they cannot reside on an iPhone. The Android solution can be uploaded to Nightscout, with Loop using Nightscout as a Remote CGM; but this requires internet access to continue closed-loop performance.

Part of the problem with Libre sensors is that there are differences in region, type and \"security generations\" which makes it hard to account for all variants. For example, the Libre 2 US has a different \"security generation\" than European Libre 2 sensors (different encryption in the data transmitted over bluetooth).

Libre 3 sensors have started appearing as well, but are unsupported. Other Libre sensors that are unsupported: Libre Pro, Libre H, Libre Sense Glucose Sport Biosensors.

"},{"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. Cuustomization instructions are provided at the Loop and Learn website: Libre Support for Loop 3.2.x that explain how to modify Loop 3 to use one of those apps for Browser Build. The Mac instructions are found on the same page. 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 a direct Bluetooth connection.

The xDrip4iOS app (which can also be found in the app store under the name Shuggah) may have a problem during the warmup of a new sensor (European Libre 2 using a 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 a 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 CGM Types, you first delete your existing CGM selection 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.

"},{"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?.

With the Dexcom G7, 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 4 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/#steps-for-dana-i-danars-v3-coming-soon","title":"Steps for Dana-i / DanaRS-v3 (Coming soon)","text":""},{"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 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":"

No Need to Set the Time

If you just added a battery to a Medtronic pump you have not used for a while, the pump initiation screens require you to set the date and time for the pump. You can just accept the default values; when you connect the pump to the Loop app, the time and date are automatically set.

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)
  2. Leave the Preferred Data Source on Event History
  3. If you have an x23 or x54 pump, choose whether to use My Sentry (saves phone battery) or not (saves OrangeLink battery)

The Medtronic status and commands available are shown in the Pump Settings page.

"},{"location":"loop-3/add-pump/#dana-i-danars-v3","title":"Dana-i / DanaRS-v3","text":"

Coming Soon

The Dana pump is not part of the released code yet. But the plug-in feature of Loop makes adding it extremely easy.

If you want to test the Dana before it added to Loop, please join the discussion of this pump in zulipchat: Dana Discussion

Support for Dana-i

All versions of the Dana-i are supported at the moment!

Check your DanaRS version before starting

Only the DanaRS firmware v3.0 or higher is supported, every other version is not supported or is untested (The korean versions are untested for example). To check your DanaRS version, please go to \"Analyze\" -> \"Model information\". The version should be at least xxx-3.0.0.

When you select the \"Dana-i/RS\" option, you will be prompted to select your pump model. After this selection, you will get a short description on how the pairing process will work. Then you will get the following menu's:

  1. Select Insulin Type
  2. Select Delivery speed
  3. Prepare your Dana-i / DanaRS-v3 pump
  4. Connect to your Dana-i pump or DanaRS-v3 pump
  5. (Optional): Enable silent pump tones
  6. (Optional): Check if you need a heartbeat

"},{"location":"loop-3/add-pump/#delivery-speed","title":"Delivery speed","text":"

IMPORTANT

The delivery speed can always be changed in the pump's settings, but you can only have one delivery speed active

The Dana pumps supports several bolus/delivery speeds. This might be interesting to customize if you want to slow down the bolus speed for insulin types that feel like it is burning. Dana supports 3 speeds:

"},{"location":"loop-3/add-pump/#prepare-dana-idanars-v3","title":"Prepare Dana-i/DanaRS-v3","text":"

Start by checking the device name at the back of your Dana (or inside the \"Model information\" menu). This is a 10 character code, which is listed behind the SN. The example below is from a Dana-i, but is the same for every Dana pump

After you have done the Insulin Type and Delivery speed, you will land on the Dana scanning page. This page will show all the Dana pumps it could find in your area. Once you see your device name in the list, click on it and Loop will try to connect to your Dana-i / DanaRS-v3.

"},{"location":"loop-3/add-pump/#pairing-dana-i","title":"Pairing Dana-i","text":"

Once connected, your Dana-i will prompt you with a question if you want to connect. Accept this and you will see a code on your Dana-i. Meanwhile, you will see the standard iOS Bluetooth pairing modal. Also accept this and fill in the code from your pump into iOS. After that is done, Loop is ready to use your Dana-i!

"},{"location":"loop-3/add-pump/#pairing-danars-v3","title":"Pairing DanaRS-v3","text":"

Once you see your device name in the list, click on it and Loop will try to connect to your DanaRS-v3.

Once connected, your DanaRS-v3 will prompt you with a question if you want to connect. Accept this and you will see two codes on your DanaRS-v3. Meanwhile, you will see a prompt for 2 codes in Loop. Fill in the codes from your pump into iOS and Loop is ready to use your DanaRS-v3!

"},{"location":"loop-3/add-pump/#optional-enable-silent-pump-tones","title":"(Optional) Enable silent pump tones","text":"

Normally, a Dana pump will make a sound or a vibration every time a bolus is completed. When Loop is configured with Automatic bolus, it might be anoying to have a beep or a vibration for every micro bolus. Therefore, we strongly recommend user to enable the silent tones.

Sadly, only the Dana distributors know how to enable this feature at the moment. But we do know you need to set your alarm to sound. You can do this via: \"Settings\" -> \"User options\" -> \"4. Alarm\"

"},{"location":"loop-3/add-pump/#optional-check-if-you-need-a-heartbeat","title":"(Optional) Check if you need a heartbeat","text":"

Most CGM provide a live Bluetooth connection, which the Loop app uses as a heartbeat to wake the app with each CGM reading. Without a heartbeat, the Loop app will not run the algorithm when the app is in the background or the phone is locked.

Some pumps can also provide a heartbeat if the CGM you choose cannot provide one.

DanaKit doesn't provide a heartbeat by default.

Therefore, it is important to check if your CGM provides a heartbeat. If it does not, there are battery-intensive work-around methods for Dana pump. See Dana Heartbeat Modes.

"},{"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.

"},{"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.

Why is my Prediction so High?

New Loopers are often concerned when they bolus for a meal and Loop then reduces basal and predicts a high future glucose.

That prediction is what would happen if Loop took no further action (or if you walked away from your phone). Loop suggests a bolus for that meal that keeps near-term glucose above your Glucose Safety Limit. As the food is absorbed and glucose rises, Loop will provide additional insulin. The automated part of this waits until your actual glucose is above the low-end of your correction range. But you can manually bolus earlier, or set an override for a few hours with a lower correction range.

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.

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 that are included in the Loop glucose prediction. The GIF below illustrates how the graph is changed by turning off one component of the prediction.

Below the chart you will see an explanation of the variables Loop takes into account in predicting your future glucose value. For more information about each effect, click on one of the links below:

You can tap on any of the entries to see the effects of that component by looking at the dashed lines. The last item, Suspension of Insulin Delivery, is new and was added to assist people wondering how long can they safely delay changing a site or suspending a pump.

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.

Algorithm Experiments

Algorithm Experiments is a feature added with version 3.4. One of the items available is Integral Retrospective Correction (IRC). When you have this enabled, the Predicted Glucose Chart displays the retrospective and integral retrospective components as shown on the graphic above. When this is disabled, (the default setting), only the retrospective component is calculated and used.

The example above illustrates a time when having IRC enabled helped Loop to \"put on the breaks\" earlier, leading to a soft landing in the target range. IRC is often advertised as helping \"stuck on high\", but can also assist when glucose is dropping faster than the model (without IRC) would expect.

"},{"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 No Insulin 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. The No Pod 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. The Insulin Suspended 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. The Manual Bolus 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. The No Data alert message indicates it has been more than 15 minutes since the app was able to communicate with the pump.Follow these troubleshooting steps. The Add Pump alert message indicates no pump has been added. Follow the instruction for adding a pump. The Finish Setup alert indicates the pod setup procedure was not completed. Tap on the icon to be taken to the Omnipod menu to complete the setup.(If your icon says Finish Pairing, you are running older code and will be taken to the Insert Cannula screen even if pod is still priming. Make sure priming completes before trying to insert the cannula)."},{"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 found on your Pump screen:

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/#new-with-loop-3","title":"New with Loop 3","text":"

This page discusses some features new with Loop 3.

"},{"location":"loop-3/features/#remote-carb-bolus","title":"Remote Carb / Bolus","text":"

Loop 3 has a Remote Carb and Remote Bolus feature to enable remote caregivers to better assist the person who needs support managing with Loop. This requires the Loop user have a Nightscout site. Please review these pages:

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 links listed above before getting started.

Be aware:

"},{"location":"loop-3/features/#new-with-loop-340","title":"New with Loop 3.4.0","text":"

Additional details about the 3.4.0 release are found here: Version: Releases: 3.4.0

"},{"location":"loop-3/features/#algorithm-experiments","title":"Algorithm Experiments","text":"

Two algorithm experiments are now available in the Loop app (version 3.4.0 or later). These are Glucose Based Partial Application and Integral 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":"loop-3/features/#glucose-based-partial-application-gbpa","title":"Glucose Based Partial Application (GBPA)","text":"Do you want to know more? (Click to open/close)

Glucose Based Partial Application is only used when Automatic Bolus (AB) is selected for Temp Basal Only Dosing Strategy

When AB is selected and GBPA is enabled, the percentage of the recommended dose delivered per Loop cycle 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.)

"},{"location":"loop-3/features/#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.

When Dosing Strategy is set to Temp Basal Only , Loop 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, acheiving the full 1 U (for this example).

"},{"location":"loop-3/features/#integral-retrospective-correction-irc","title":"Integral Retrospective Correction (IRC)","text":"Do you want to know more? (Click to open/close)

The IRC term is described in this (updated) comment in Loop Issue 695 which includes 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 for RC and IRC, examine these files found in LoopKit/LoopKit:

Integral Retrospective Correction, when enabled:

Refering to the Algorithm: Prediction page:

\\[ BG[t] = Insulin[t] + Carb[t] + RetrospectiveCorrection[t] + Momentum[t] \\] \\[ BG[t] = Insulin[t] + Carb[t] + IntegralRetrospectiveCorrection[t] + Momentum[t] \\]

Note that the Momemtum 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 lower blue rectangle, is the difference between the IRC and RC calculations.

"},{"location":"loop-3/features/#important-points-about-irc","title":"Important points about IRC:","text":"

  1. Known risk factors compared to standard Loop:

  2. Compared to standard RC, IRC is more likely to improve glucose control in the following scenarios:

  3. In some scenarios IRC does not differ from standard Loop RC

  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:

"},{"location":"loop-3/features/#favorite-foods","title":"Favorite Foods","text":"

This feature allows you to save Favorite Foods.

A new row on the Loop app Settings screen, see graphic below, provides access to create and edit your Favorite 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.

Note that to create a Favorite Food on the Carb Entry screen, an icon must be selected by typing on the plate icon and choosing one of the specific food emoji icons. The standard Lollipop, Taco, Pizza icons can be selected at that level, but choosing them at the top level is not sufficient to enable the Save as Favorite button. The favorite food examples seen in the graphic above were created in the Favorite Foods Settings row. The taco was chosen to go with the absorption time chosen.

"},{"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.

  2. Select the Non-Pump Insulin tab to bring up the graphic shown below

"},{"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: Change Pump Type.

"},{"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/#new-slider","title":"New Slider","text":"

The Insert Cannula and Deactivate Pod now use a Slider instead of a Button

For version 3.4.x and later there is a new slider to control insertion of the cannula and deactivation of a pod.

The slider looks like the graphic below. (The Deactivate Pod slider is red.) You place your finger on the dark circular icon and, while keeping your finger in contact with the screen, drag all the way to the other side. (The direction depends on the natural direction for your selected language). 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. There are two versions of the screen below.

"},{"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-display","title":"Pod Display","text":"

The next section on the Pod screen reports:

The graphic below shows version 3.2.3 and earlier on the left with version 3.4 and later on the right.

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/#pod-details","title":"Pod Details","text":"

Some additional details for 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/#previous-pod-details","title":"Previous Pod Details","text":"

When you tap on the Previous Pod Details row, a graphic similar to those shown below is displayed. This provides summary information about the pod before the one currently in use. If you are running version 3.2.3 or earlier, this row is at the very bottom of the Omnipod screen.

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.

"},{"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/#silence-pod","title":"Silence Pod","text":"

The Silence Pod feature is new with version 3.4.x. This allows a user to tap on silence pod to prevent any noises from the pod, other than critical faults.

What Silence Pod will not do:

When would you use Silence Pod:

Caveats:

The graphic below shows the Silence Pod control. This is only available for v3.4.x and later.

"},{"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/#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 use the slider to 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 sliding to Deactivate Pod. You can then view the Fault information in the Previous Pod Details screen.

"},{"location":"loop-3/omnipod/#updates-with-version-34x","title":"Updates with Version 3.4.x","text":"

The updates included with version 3.4.x make it easier to find the pod fault, should one occur.

The fault will appear on the Omnipod screen and more details will be shown when you tap on Replace Pod to arrive at the Deactivate screen. You can grab a quick screenshot on the Deactivate screen if desired. If there was no pod fault, you will not notice a difference in the version 3.4.x display compared to version 3.2.3.

The fault information can still be found under Previous Pod Details if you need to find it after you Deactivate the \"screaming\" pod.

"},{"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.

Screens

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

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

"},{"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/rileylink/","title":"RileyLink Display","text":""},{"location":"loop-3/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":"loop-3/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

"},{"location":"loop-3/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.

"},{"location":"loop-3/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.

"},{"location":"loop-3/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:

"},{"location":"loop-3/services/","title":"Optional: Services","text":""},{"location":"loop-3/services/#services-for-the-loop-app","title":"Services for the Loop App","text":"

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. For more information, see Nightscout Overview. 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).

"},{"location":"loop-3/services/#nightscout-login","title":"Nightscout Login","text":"

The graphic below shows the steps needed to add your Nightscout site to the Loop app. See the tip below about using stored passwords on the phone. If you have your credentials stored in passwords, simply tap the URL row to show the password option and select it.

  1. Select Settings in the Loop app and scroll down to Services and tap the Add Service Row
  2. Choose Nightscout Service
  3. Tap on the URL row
  4. This step has two options:
  5. Tap on Login to add this site

The Loop app will begin uploading your data from this point on - it does not back-fill old data to the Nightscout site.

However, if there is a temporary outage of internet service or if the Nightscout site stops working temporarily, the Loop app will fill in all data not uploaded during the outage up to a total of 7 days worth of data.

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.

Do not block your Nightscout site

Add a Password

To make it easy to access your Nightscout URL and API_SECRET, add a password to your iPhone:

  1. iOS Settings, Password
  2. Tap + to add
  3. If you use tokens, you can add those in the Notes section - they will be hidden behind the authentication for the passwords
"},{"location":"loop-3/services/#nightscout-logout","title":"Nightscout Logout","text":"

If you want to stop uploading to a given Nightscout site or change to a different Nightscout site, you must first logout. You can then login again at the new site.

The graphic below indicates how to remove your Nightscout site from the Loop app. This will stop future uploads from the Loop app to that site.

"},{"location":"loop-3/services/#tidepool","title":"Tidepool","text":"

Data can be directly uploaded from Loop to Tidepool by adding it as a Service.

Please refer to the LoopTips: Data: Tidepool page for more information about Tidepool.

When you add the Tidepool Service to Loop, be sure to disable Tidepool Mobile ability to read from Apple Health.

Double entries

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.

Even when you turn off the access to Health on the Tidepool Mobile app when you turn on Loop Tidepool service, you will still get 7 days of overlap because Loop stores 7 days of data.

There is a filter button on the Tidepool Website you can use to separate the two data sources.

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. 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. This page 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 is reached by tapping the gear icon in the Toolbar on the Main Loop Screen. The graphic below is for Loop 3.4 and later versions.

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.

"},{"location":"loop-3/settings/#temp-basal-only","title":"Temp Basal Only","text":"

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.

With Loop 3.4.0 and later versions, you have the option of using Automatic Bolus with Glucose Based Partial Application (GBPA). This feature is reached through the Algorithm Experiments row of the Settings screen. It modifies the percentage of the recommended dose that is supplied with each Loop cycle. Instead of being a fixed 40%, it changes from 20% when glucose is near your selected Correction Range and gradually increases to 80% when glucose reaches 200 mg/dL (11.1 mmol/L).

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/#alert-management","title":"Alert Management","text":"

This row enables the user to modify Alert Permissions and to enable Missed Meal Notifications.

"},{"location":"loop-3/settings/#missed-meal-notifications","title":"Missed Meal Notifications","text":"

Loop detects situations where glucose excursions indicate you may have consumed carbs but did not enter them into Loop. When Missed Meal Notifications are enabled, you will be provided an alert that suggests when the meal was consumed and how many carbs are already absorbed at the time of the alert. You have the option to increase the grams of carbs to match your actual meal.

"},{"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/#algorithm-experiments","title":"Algorithm Experiments","text":"

The Algorithm Experiments are new with Loop 3.4 and we recommend you review the details on the Features new with Loop 3 page. Many people have tested these and like them, but you need to decide whether to enable them.

"},{"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/#favorite-foods","title":"Favorite Foods","text":"

Favorite Foods, new with Loop 3.4, can simplify meal entry if you choose to use it. You can create a Favorite Food here or on the Carb Entry screen.

Note that to create a Favorite Food on the Carb Entry screen, an icon must be selected by typing on the plate icon and then choosing a food emoji. The standard Lollipop, Taco, Pizza icons selected from the top level are not sufficient to enable the Save as Favorite button.

"},{"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 is similar to what you see when you scroll down to the Support section of the Loop 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.

"},{"location":"loop-3/settings/#when-not-to-submit-a-bug-report","title":"When Not to Submit a Bug Report","text":"

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/#testflight-or-app-profile","title":"TestFlight or App Profile","text":"

At the bottom of the Settings display is a section labeled either TestFlight or App Profile. This provides the number of days remaining before the Loop app stops working along with the date and time at which the \"Loop\" is No Longer Available or \"Loop\" Beta has Expired message appears and the refuses to open. (Prior to Loop 3.4, the TestFlight warning was available only in dev.)

The link for How to update (LoopDocs) is provided for Build with Browser or Build with Mac as appropriate.

In fine print, the date and time of the expiration is reported in your local time zone. The Loop app installed from TestFlight might last a day longer than the Loop app reports - this is a conservative estimate. The time reported in the TestFlight app is correct.

"},{"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

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":""},{"location":"nightscout/loop-caregiver/#prerequisites","title":"Prerequisites:","text":"

Older Nightscout Versions

If you ignore this minimum version requirement - what happens:

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.

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.

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":"

The Timeline:

You can also use the Loop Caregiver -> Settings screen to modify:

"},{"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

"},{"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.

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.

"},{"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.

"},{"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.

"},{"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.

"},{"location":"nightscout/ns-crossref/#reports","title":"Reports","text":"

Nightscout offers some fantastic data-crunching report tools.

"},{"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

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

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.

"},{"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.

"},{"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.

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.

"},{"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.

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:

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

"},{"location":"nightscout/remote-commands/#using-safari","title":"Using Safari","text":""},{"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:

"},{"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 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:

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.

One example scenario:

Second example scenario:

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.

For more information, see:

"},{"location":"nightscout/remote-commands/#using-remote-commands","title":"Using Remote Commands","text":"

There are four ways you can trigger your commands remotely; Loop Caregiver, 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 your Nightscout site according to the directions here in\u00a0Loopdocs\u00a0in addition to setting up the Remote Configuration.

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 to the bottom of the event type menu. Refer to Command Remote Bolus or Carb Entry for more instructions and a graphic.

Please note that there are entries that do not say remote at the top of the list.

"},{"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.

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/#start-and-end-remote-override","title":"Start and End Remote Override","text":"

Starting or ending a remote override does not require a One-Time Password.

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/#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.

"},{"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

"},{"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.

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.

Consequence if Looper's phone is not configured correctly:

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:

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.

"},{"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.

"},{"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":""},{"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":""},{"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.

"},{"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 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 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 \u2018caregiver\u2019 below refer to the person sending the commands. You must have the\u00a0Loop\u00a0phone with you to troubleshoot this problem.

"},{"location":"nightscout/remote-errors/#undelivered-or-expired-commands","title":"Undelivered or Expired Commands","text":"

Apple push notifications may not always reach your app due to various settings or Apple's intentional limitations. This issue can manifest in several ways:

While\u00a0Loop\u00a0cannot control the timely delivery of push notifications, there are several steps you can take to mitigate these issues. Note that rebuilding\u00a0Loop\u00a0or Loop Caregiver generally will not resolve the problem.

Check these items on the Looper\u2019s phone, not the caregiver's.

  1. Reboot the phone.
  2. Wait 24 hours as it often takes time for the push notification limits to reset.
  3. Limit the number of\u00a0Loop\u00a0commands you send in a short period.
    • Apple may throttle notifications if too many are received.
    • Sending no more than 1 or 2 per hour may help.
  4. Disable notifications from other apps.
    • It is possible that other apps can cause the system to throttle all notifications, including\u00a0Loop.
  5. Enable Time Sensitive Notifications:
    • Apple Settings -> Notifications ->\u00a0Loop.
    • Turn on \u201cAllow Notifications\u201d.
    • Turn on \u201cTime Sensitive Notifications\u201d.
  6. Upgrade Nightscout:
    • Nightscout version 15.0 (released late 2023) and greater supports time sensitive notifications.
    • This can help iOS to deliver remote notifications faster.
  7. Adjust Focus Modes:
    • For all focus modes, make sure\u00a0Loop\u00a0is listed as an app allowing Notifications.
    • Apple Settings -> Focus
    • Select the focus mode (e.g., Do Not Disturb, Sleep).
    • Under \u201cAllow Notifications,\u201d tap \u201cChoose Apps\u201d.
    • Add\u00a0Loop\u00a0to the list.
  8. Turn on Background App Refresh:
    • Apple Settings -> General -> Background App Refresh
    • Select \u201cOn\u201d at the top.
    • Activate the\u00a0Loop\u00a0toggle in the list.
  9. Try using Wi-Fi instead of cellular if possible:
    • Apple may not deliver notifications on cellular as often as on Wi-Fi.
  10. Charge the phone:
    • If the battery is low, iOS may not deliver notifications to save battery life (e.g., while on Low Power mode).
"},{"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?
    • In both Nightscout and Caregiver, you can tap on an error to read specific error details.
    • Share screenshots of errors
  4. What\u00a0Loop\u00a0version are you using? Released (main) or development (dev)? Approximately when did you update last?
    • The minimum version that supports remote bolus and carbs is\u00a0Loop.
  5. What iOS version is being used on the Looper\u2019s device?
  6. How did you build\u00a0Loop?
    • Web browser using GitHub Actions?
    • Xcode?
    • AppCenter or Diawi? 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":"

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

"},{"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:

"},{"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.

"},{"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:

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.

The use of tokens is documented at this link to the security page in the Nightscout documentation.

You can authenticate with your API_SECRET using either of these methods:

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/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:

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":""},{"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":""},{"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 formula 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 Insulin Model Customization 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, as set in the ISF schedule in therapy settings or in accordance with any overrides. Loop uses the ISF that applied at the time of an insulin dose to predict the expected change in blood glucose due to the insulin effect, and sums the effect from all still-active doses.

"},{"location":"operation/algorithm/prediction/#expected-change-in-blood-glucose-for-each-loop-interval","title":"Expected Change in Blood Glucose for Each Loop Interval","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.

The insulin effect for a given dose can be expressed mathematically:

\\[ \\Delta BG_{dose}[t] = ISF[t_{dose}] \\times IA_{dose}[t] \\]

where \\(\\Delta BG_{I}\\) is the expected change in blood glucose due to insulin with the units (mg/dL/5min), ISF is the insulin sensitivity factor (mg/dL/U) at the time of the relevant dose, 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 insulin in the blood as it acts on glucose. Insulin activity explicitly accounts for active insulin from temporary basals and boluses, and implicitly accounts for scheduled basal which is assumed to balance out with EGP.

"},{"location":"operation/algorithm/prediction/#insulin-effect-on-blood-glucose-over-time","title":"Insulin Effect on Blood Glucose Over Time","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/#treatment-of-scheduled-basal-rates","title":"Treatment of 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-active-insulin-combining-boluses-and-temporary-basal-rates","title":"Total Active Insulin (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.

The active insulin taking into account boluses and variations from scheduled basal basal rates are visually represented for the user by Loop\u2019s insulin charts:

"},{"location":"operation/algorithm/prediction/#total-insulin-effect-combining-boluses-and-temporary-basal-rates","title":"Total Insulin Effect (combining boluses and temporary basal rates)","text":"

The sum of all doses' effects on blood glucose are shown for the user in the 'Insulin' curve in the predicted glucose screen.

The total insulin effect at time t is the sum of effects from each active dose or temporary basal rate:

\\[ \\Delta BG_{I}[t] = \\sum_{dose=1}^{n} \\Delta BG_{dose}[t] \\]"},{"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] = \\Delta BG_{O}[t] - \\Delta BG_{I}[t] \\]

where, ICE (mg/dL/5 min) is the insulin counteraction effect, \\(\\Delta BG_{O}\\) is the observed change in blood glucose (mg/dL/5min) at time t, and \\(\\Delta BG_{I}\\) is the modelled change in blood glucose due to insulin alone (i.e. the insulin effect as described above 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 both the carbohydrate-to-insulin ratio and the insulin sensitivity factor that were current at the time of a recorded meal entry.

\\[ AC[t] = ICE[t] \\times \\frac{CIR[t_{meal}]}{ISF[t_{meal}]} \\]

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) at the time of the relevant meal entry, and ISF is the insulin sensitivity factor (mg/dL/U) at the time of the relevant meal entry.

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:

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 dynamically-estimated carbohydrate absorption of a meal entry up to the current time t 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_{meal}]}{CIR[t_{meal}]} \\]"},{"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/#integral-retrospective-correction-effect","title":"Integral Retrospective Correction Effect","text":"

The integral retrospective correction effect allows the Loop algorithm to account for longer term effects that are not modeled with the insulin and carbohydrate effects, by comparing historical predictions to the actual blood glucose.

When Integral Retrospective Correction (IRC) is enabled in settings under Algorithm Experiments, this replaces the Retrospective Correction (RC).

\\[ BG[t] = Insulin[t] + Carb[t] + IntegralRetrospectiveCorrection[t] + Momentum[t] \\]

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 lower blue rectangle, is the difference between the IRC and RC calculations.

"},{"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 \\(\\Delta BG\\) over the time interval \\([t_{5}, 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":""},{"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:

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:

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":""},{"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:

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:

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

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.

"},{"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.

"},{"location":"operation/features/bolus/","title":"Bolus","text":""},{"location":"operation/features/bolus/#updates-with-version-3-and-later","title":"Updates with version 3 and later","text":""},{"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.

Avoid Double Entry of Carbohydrates

Carbohydrates are saved when the Save and Bolus or Save without Bolusing button is tapped in the Meal Bolus Screen. Once that the button is tapped, carbohydrates are saved. That is true even if the bolus does not go through to the pump.

If you see a notification after saving a carbohydrate entry, check carbohydrates entries in the Loop app. Do not just add the entry again without checking.

"},{"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:

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.

"},{"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.

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.

"},{"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.

"},{"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:

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/carbs/","title":"Meal Entries","text":""},{"location":"operation/features/carbs/#meal-entry","title":"Meal Entry","text":""},{"location":"operation/features/carbs/#loop-3-updates","title":"Loop 3 Updates:","text":""},{"location":"operation/features/carbs/#new-with-version-34x","title":"New with Version 3.4.x","text":"

The Favorite Foods feature was added with version 3.4.x. This is an even faster way to enter meals than is described in the next section, Meal Entry - Fast Version.

The graphic in the link above was taken from my Favorite Foods screen. Subsequent to that screen shot, I've renamed Medium to Lunch and Large to Dinner. Note this is a personal solution that works for me; you need to modify your settings to work for you.

For each meal I select Lunch or Dinner, save and accept the bolus.

"},{"location":"operation/features/carbs/#meal-entry-fast-version","title":"Meal Entry - Fast Version","text":"

Favorite Foods is even faster

With version 3.4.x and later, you have access to the Favorite Foods feature. This can make meal entry even faster than this Fast Version section below.

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.

Beginner's Tip

"},{"location":"operation/features/carbs/#meal-entry_1","title":"Meal Entry","text":"

The steps and graphics in this section are for users of Loop 3.

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.

Carbs are Saved in Meal Bolus Screen

Carbohydrates are saved when the Save and Bolus or Save without Bolusing button is tapped in the Meal Bolus Screen. Once that the button is tapped, carbohydrates are saved. That is true even if the bolus does not go through to the pump.

If you see a notification after saving a carbohydrate entry, check carbohydrates entries in the Loop app. Do not just add the entry again without checking.

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.

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:

Limits for time entry of when meal was consumed:

"},{"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.

Pro Tip

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.

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.

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.

"},{"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:

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 Displays: Active Carbohydrate Chart 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.

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.

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":""},{"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.

"},{"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/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):

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 positive 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

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.

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":""},{"location":"operation/features/notifications/#expiration-on-settings-screen","title":"Expiration on Settings Screen","text":"

At any time, you can tap on Settings and scroll to the bottom of the screen to see when your app will expire.

The graphic below shows the Settings display for a TestFlight build (version 3.3 or newer):

"},{"location":"operation/features/notifications/#expiration-alert","title":"Expiration Alert","text":"

Notification before an app expires is reported using this protocol:

The graphic below show an example expiration alert for a Mac build:

Notification when app expires is available in these versions or newer:

"},{"location":"operation/features/notifications/#free-7-day-loop-app-expiration-alert","title":"Free (7-day) Loop App Expiration Alert","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/#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:

"},{"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:

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:

"},{"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.

Remember: Carbs are saved when you tap Save and Bolus following a meal entry - even if the bolus fails.

"},{"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":"

Omnipod After the reservoir reports 0 U, the pod attempts to deliver insulin when requested.

"},{"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.

"},{"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:

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.

The overall insulin needs is applied to your basal rates, insulin sensitivities and carb ratios for the duration of the override.

For an override to be accepted:

"},{"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:

"},{"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

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

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

"},{"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. You can extend the duration or modify the needs value or target value based on a temporary situation.

When you edit Overall Insulin Needs, then the Loop app recalculates some effects, such as IOB, over the duration of the override and if you also quit and restart the app, it recalculates all effects. See Recalculate When Needs Change for more information.

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:

"},{"location":"operation/features/overrides/#recalculate-when-needs-change","title":"Recalculate When Needs Change","text":"

Here's a cool tip for more advanced users. Suppose you have an override running but you realize your overall insulin needs percent wasn't quite right. You can edit the override and force the Loop app to recalculate the effect from the beginning of the override. A change in IOB may show up immediately when you edit insulin needs in the override. If you also quit and restart the app, this forces a recalculation from the beginning of the override.

This is demonstrated in the following set of graphics contributed by a user - note the change in the ICE graph for carbohydrates absorbed - this requires you to quit and restart the Loop app. These examples use extreme modifications to illustrate what happens - typically the modification of insulin needs would be much smaller.

The first graphic is where the Overall Insulin need value was dramatically decreased (user much more sensitive).

The second graphic is where the Overall Insulin need value was dramatically increased (user much less sensitive).

Example

I set my biking override to be longer than my expected ride. When I return, I edit the insulin needs from 65% (needed while I'm actively biking) back to 100%. My negative IOB typically doubles at that change. I then disable the override and take the full negative IOB as a bolus. This helps prevents a post-exercise high that often follows my ride.

I do not enter any carbs while biking and almost always ride first thing in the morning while fasting, so i just edit the override. If no carbohydrates are active, there is not need to quit and restart the app.

"},{"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":""},{"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:

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.

"},{"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.)

"},{"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.

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.

"},{"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.

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.

"},{"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:

"},{"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:

"},{"location":"operation/features/widget/","title":"iPhone Widget","text":""},{"location":"operation/features/widget/#widgets","title":"Widgets","text":"

The Loop app uses the new-style widgets. With the advent of iOS 16 and 17, you can add widgets that show up on the lock screen without need to swipe to view. But only some widgets can do this and there is very limited space for those lock screen widgets. You can add more widgets to the Today View, where you do need to swipe right from the Home View or Lock Screen.

The example graphic below shows the Loop widget on the top row, with the LoopCaregiver widget next to a Scriptable widget that is fed from my Nightscout site on the middle row. Below that is the Dexcom G7 widget next to a weather widget. This Today View requires a swipe right from the Lock Screen or the Home screen. The scriptable widget is also on my lock screen. The update rate for these widgets is similar to watch complications, some will grey out when stale. If they are greyed out, tap on them to go to the app directly.

The Scriptable widget includes the time of the last update, 11:25 am, so is 11 minutes old at the current time of 11:36 am.

New to Loop or never added a widget before

"},{"location":"operation/features/widget/#old-style-loop-widget","title":"Old-Style Loop Widget","text":"

Leave this here so you can see if you have an old-style widget.

With newer versions of iOS, the old-style widgets cannot be moved to the top of the screen. Please convert to the new-style widgets.

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.

"},{"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.

"},{"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.

The ISF is also important, but basal should be evaluated first.

"},{"location":"operation/loop/close-loop/#meals","title":"Meals","text":"

Avoid Double Entry of Carbohydrates

Carbohydrates are saved when the Save and Bolus or Save without Bolusing button is tapped in the Meal Bolus Screen. Once that the button is tapped, carbohydrates are saved. That is true even if the bolus does not go through to the pump.

If you see a notification after saving a carbohydrate entry, check carbohydrates entries in the Loop app. Do not just add the entry again without checking.

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.

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

"},{"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:

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:

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.

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.

"},{"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.

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.

"},{"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.

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?

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:

\\[ 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":"troubleshooting/dana-heartbeat/","title":"Dana Heartbeat","text":""},{"location":"troubleshooting/dana-heartbeat/#danars-v3-i-heartbeat-modes","title":"Dana(RS-v3 / -i) heartbeat modes","text":"

Please read the full page and only activate this if truly needed

Enabling this feature will put a big load on your iPhone's battery or your pump's battery. Therefore, only use it if your sensor doesn't provide a heartbeat, i.e. the NightScout remote CGM, Dexcom Share, etc

Danakit provides two ways to enable a heartbeat:

"},{"location":"troubleshooting/dana-heartbeat/#which-mode-to-choose","title":"Which mode to choose?","text":"

You should choose Background sound when:

You should choose Continuous Bluetooth mode when:

"},{"location":"troubleshooting/dana-heartbeat/#background-sound","title":"Background sound","text":"

An extra feature available for the Dana pumps is the background sound. This feature was developed in order to keep the Loop app running in the background.

Normally, your CGM will have an active Bluetooth connection, which prevent the Loop app from being put into a suspended state. But when you are planning on using a CGM, like NightScout remote CGM, Dexcom Share, etc, you rely on a active internet connection, and not on an active Bluetooth connection.

In order to activate, follow these steps:

  1. Activate the UIBackgroundMode - audio:

    • When building with Mac, go to the LoopWorkspace Xcode project and select the Loop project. Go to \"Targets\" -> \"Loop\" -> \"Signing & Capabilities\" and scroll down to \"Background modes\". Enable the checkbox for \"Audio, AirPlay, and Picture in Picture\". Then rebuild the app and go to step 2.

    • When building with Browser, you will need to make a change to the GitHub Actions workflow. Go to your LoopWorkspace fork on GitHub and press . on your keyboard. You will be redirected to a github.dev page with the code of your LoopWorkspace. Now go to \".github\" -> \"workflows\" -> \"build_loop.yml\". Scroll down till you see the - name: Fastlane Build & Archive command. Just before this command, add the following to this script (example):

    - name: Update entitlement background sound\n  run: sed -i -e 's/<string>bluetooth-central<\\/string>/<string>bluetooth-central<\\/string><string>audio<\\/string>/g' Loop/Loop/Info.plist\n
    • To save your changes to the \"build_loop.yml\", go to the Source Control tab on the left (should show up with a blue 1, see image below). Enter a message and press the green \"Commit & Push\"-button. By pressing this button, GitHub will automatically make a new browser build for you and push it to TestFlight

  2. After you have done the onboarding of the pump (see steps above), go to the pump settings. Scroll down the \"Pump name\" and long-press this row. A modal should pop-up with the question, whether you want to toggle Silent tones.

    In order to activate this feature, the modal should say something like: Yes, Enable silent tones. When it says: Yes, Disable silent tones, it will disable the background sounds.

  3. Done! Every time you put the Loop app in the background, it will play a toneless sound, which prevents it from suspending the Loop app

"},{"location":"troubleshooting/dana-heartbeat/#continuous-bluetooth-mode","title":"Continuous bluetooth mode","text":"

This mode replicates how a CGM works: it keeps the bluetooth connection open even though no command's are being executed. Like stated before, this will drain your pump's battery more than usual.

"},{"location":"troubleshooting/dana-heartbeat/#how-to-unblock-the-pumps-ui","title":"How to unblock the pump's UI","text":"

If you want to replace the reservoir or want to interact with the pump's UI, you have three options to temporary disable Continuous bluetooth mode:

To use the disconnect feature, go to the Dana pump settings and use the Disconnect from pump button. You will get prompt to set a notification reminder. This reminder will be sent to you if you haven't reconnected the pump within the given time. This feature is fully optional, but is recommended.

"},{"location":"troubleshooting/dana-heartbeat/#how-to-enable-continuous-bluetooth-mode","title":"How to enable Continuous bluetooth mode","text":"

Now that you know what the risks are of this feature and how to unblock the pump's UI, can we talk about enabling the feature. Go to the Dana settings and long press the Firmware version row. You will be prompted to enable or disable the feature, choose Yes, Switch to continuous mode and the feature has been enabled!

"},{"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.

"},{"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.

"},{"location":"troubleshooting/loop-crashing/#browser-build","title":"Browser Build","text":"

Update to version 3.4 as soon as possible. The builds will then be automatic. So all you will need to do in install the latest build from TestFlight on your phone.

If you are running an older version, you 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 is supplied with version 3.4.

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

Remember that switching from free to paid changes the developer name incorporated into your Loop App

"},{"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.

"},{"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:

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.

"},{"location":"troubleshooting/omnipod-faults/#capture-the-fault","title":"Capture the Fault","text":""},{"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.

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.

"},{"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:

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

"},{"location":"troubleshooting/pod-pairing/#is-it-the-right-kind-of-pod","title":"Is it the right kind of Pod?","text":"

The DASH pods have a blue needle cap. The Eros (and the Omnipod 5) pods have a clear needle cap. Make sure the pod you are trying to pair is the right type.

"},{"location":"troubleshooting/pod-pairing/#did-the-pod-beep","title":"Did the Pod Beep?","text":"

The instructions from Insulet 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. If you did not hear the pod beep as you filled it - the pod might be defective or you may not have added enough insulin.

Inject slowly

Some users are able to get the pods to beep with smaller amounts by very slowly injecting the insulin.

"},{"location":"troubleshooting/pod-pairing/#verbose-message-hard-to-interpret","title":"Verbose Message, Hard to Interpret","text":"

This is only seen with DASH pods. Sometimes the communication error happens at a very low level and by the time the error message works its way up to the display, it seems to go on for a long time and may not make sense to the typical looper.

If you see a Pairing exception message similar to the one shown in the graphic below, you probably just need to toggle Bluetooth on the phone.

Still not working, read through the Why do pod pairings fail? section.

"},{"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 Loop app will crash while a new pod is being setup. This is rare but can happen. There are several parts to the setup process:

  1. Pair the pod to the app
  2. Prepare for and start to prime the pod
  3. Insert the cannula
"},{"location":"troubleshooting/pod-pairing/#updates-for-version-34","title":"Updates for Version 3.4","text":"

The Omnipod code was upgraded with version 3.4 to be more robust if your Loop app quits, a build is installed or the app is swiped up during pod setup.

There are initial pairing steps: exchange of encryption keys, assign the pod ID and perform a final connection step that must be completed while the app is in contact with the pod. Once those initial commands happen, then the pod can reconnect to the Loop app even if the app quit before priming starts.

"},{"location":"troubleshooting/pod-pairing/#behavior-for-version-32x-and-earlier","title":"Behavior for Version 3.2.x and earlier","text":"

For version 3.2.x and earlier, the pod needed to actually begin priming before an interruption occurred or the pod could not be recovered. However, in this case, the user was always directed to the Insert Cannula page whether priming completed or not.

  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 taken to the Insert Cannula screen before the pod is ready
    • Wait 30 seconds after clicking (priming) stops before attempting to insert the cannula
    • Note - it is not a fatal error to try to insert too soon - you will just be informed that the pod is not in the correct state - wait for priming to finish and then retry
  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 first 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":"

There are 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; see Current 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.

Read this page to understand the information you should see on your phone if your RileyLink Device is working properly:

"},{"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). Before disposing of it, however, be sure to silence it: What do you do to stop a screaming pod?.

"},{"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 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.

If you do need to try another pod. Once the new pod is operating, be sure to go to the first pod and disable the sound - it will continue beeping until it starts to scream: What do you do to stop a screaming pod?

"},{"location":"troubleshooting/pod-pairing/#step-4-check-the-pod-placement","title":"Step 4: Check the Pod Placement","text":""},{"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 Verbose Message, Hard to Interpret Pairing exception message as shown in the link above, you need to toggle Bluetooth on the phone:

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.

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

"},{"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 are required to set the time and date with each battery change. You can save time by accepting the default values; the Loop app automatically sets the time and date. (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.

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.

Omnipod Users

Do not pull a pod when there is a red loop.

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
"},{"location":"troubleshooting/red-loop/#lost-pod-information","title":"Lost Pod Information","text":"

We have not seen this issue since the update of the Loop app from version 2 to version 3 when the method for saving data was updated. Some other applications in the open-source sets of codes might still have this issue. (It was reported in iAPS, for example.) The warning below is left in LoopDocs but if you are running Loop version 3.x.x, you do not need to worry about reboots.

Be Careful with Phone Reboots with Loop 2 or iAPS

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.

Do these steps until one of them fixes the issue:

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":"

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/#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 and later, 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

  2. In addition, with the addition of Focus modes (for iOS 15, 16 and 17), you may need to explicitly allow the Loop app access for notifications for modes such as Sleep, Personal and Do Not Disturb modes.

"},{"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:

The error message from Dexcom was not as helpful. If you see this, check your phone storage:

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 are some things to check if you have frequent red loops:

"},{"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:

"},{"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.

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

"},{"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:

When you do not add that build time flag:

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.

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

"},{"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.

Other customizations require that you create your own personalized version.

"},{"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?

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.

This page is broken into two halves:

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

"},{"location":"version/code-custom-edits/#module-folder-file","title":"Module, Folder, File","text":"

Stability Information Added

Some customizations have not changed for a very long time (stable since 2.2.x days).

It was not until version 3.2.3 that we started adding a notation as to when the required customization code changed.

For those using the Browser Build method:

Each customization provides the Module, Folder and File bullet below the key phrase.

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.

"},{"location":"version/code-custom-edits/#not-stable-list","title":"Not Stable List","text":"

This list indicates personalized customization that differ between 3.2.3 and 3.4.x:

"},{"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 the *Loop* app 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 slow values are for moderate and higher-fat or large meals.

Key_Phrase
defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes\n

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

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

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

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":""},{"location":"version/code-custom-edits/#glucose-guardrails","title":"Glucose Guardrails","text":"

This code limits the absolute and recommended values for the Glucose Safety Limit and the Correction Ranges. The absolute range cannot be exceeded. The recommended range indicates values that show up as black on the picker wheel. Numbers outside the recommended range are yellow. Numbers at the min or max of the absolute range are displayed as red.

Key_Phrase
Guardrail(absoluteBounds:\n
"},{"location":"version/code-custom-edits/#version-340","title":"Version 3.4.0","text":"

This update, merged 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/#version-from-323","title":"Version from 3.2.3","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/#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
"},{"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
"},{"location":"version/code-custom-edits/#adjust-future-carbs-time-interval","title":"Adjust Future Carbs Time Interval","text":"

The Loop app limits to 1 hour the amount of time in the future that carbs can be entered.

"},{"location":"version/code-custom-edits/#version-340_1","title":"Version 3.4.0","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/#version-from-323_1","title":"Version from 3.2.3","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))\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.

"},{"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!

"},{"location":"version/code-custom-edits/#digital-crown-adjustments","title":"Digital Crown Adjustments","text":"

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

"},{"location":"version/code-custom-edits/#modify-bolus-confirmation-motion","title":"Modify Bolus Confirmation Motion","text":""},{"location":"version/code-custom-edits/#modify-bolus-picker-sensitivity","title":"Modify Bolus Picker Sensitivity","text":""},{"location":"version/code-custom-edits/#modify-carb-and-time-picker-sensitivity","title":"Modify Carb and Time Picker Sensitivity","text":""},{"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.

If you prefer a different notification time and frequency, there are two lines you can modify:

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:

Default code for line 28:

    let minimumTimeBetweenAlerts: TimeInterval = timeUntilExpiration > .hours(24) ? .days(2) : .hours(1)\n

Modify Frequency of Repeated Notifications (Three Values):

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:

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

This Loop 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 the Loop app, this controls the authorization requirement to modify Therapy Settings as well as to confirm bolus delivery.

Key_Phrase
canEvaluatePolicy(.deviceOwnerAuthentication\n

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

The Override Insulin Needs values are not limited by the default picker values of 10%.

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

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

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 major features added to dev since Loop 3.4 was released.

Right now it is empty.

"},{"location":"version/development/#updates-from-32-to-34","title":"Updates from 3.2 to 3.4","text":"

Most features, originally in the Updates in dev section before the release of version 3.4, have been inserted into the appropriate part of the LoopDocs website (indicated by the up-right arrow after the link). A few items are still in this section.

"},{"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:

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.

In addition to the easier to read error messages found with these updates, these additional simplifications include:

These sections are still useful for version 3.5.0 dev users:

"},{"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

"},{"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.5.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

You can also go directly to the git commit history for each of the branches if you'd like.

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.

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:

For more information on how to contribute code to the Loop project, please review:

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

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.

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.

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

"},{"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, there are other changes later than that commit that 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.

"},{"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.

"},{"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.

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.

"},{"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:

Older Loop release information is kept for historical reasons:

"},{"location":"version/releases-version2/","title":"Loop 2 and Older","text":""},{"location":"version/releases-version2/#compatibility-between-versions-2-and-3","title":"Compatibility between Versions 2 and 3","text":"

If you are running a much older version of the Loop app, be aware:

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.

"},{"location":"version/releases-version2/#loop-2-version-history","title":"Loop 2 Version History","text":""},{"location":"version/releases-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#new-features","title":"New Features:","text":"

Automatic Bolus (Experimental) Dosing Strategy

Provisioning Profile Expiration Notifications:

RileyLink Compatible Devices:

Omnipod Features:

"},{"location":"version/releases-version2/#code-fixes","title":"Code Fixes:","text":"

Omnipod Code Fixes:

(REMOVED) Insulin Accounting:

Dexcom Non-US Share:

For community support, please use one of the Loop Social Media help sites.

"},{"location":"version/releases-version2/#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.

"},{"location":"version/releases-version2/#loop-v223","title":"Loop v2.2.3","text":"

Released September 25, 2020

Warning - Rebuild ASAP for Pods

"},{"location":"version/releases-version2/#loop-v221","title":"Loop v2.2.1","text":"

Released August 9, 2020

"},{"location":"version/releases-version2/#loop-v22","title":"Loop v2.2","text":"

Released April 17, 2020

"},{"location":"version/releases-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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/releases/","title":"Releases","text":""},{"location":"version/releases/#loop-releases","title":"Loop Releases","text":"

The new features added with each Loop release are provided for reference.

For information about version 2 releases and compatibility between version 2 and 3, refer to Older Releases.

"},{"location":"version/releases/#current-release","title":"Current Release","text":"

The current released version for the Loop app is 3.4.1. 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.

"},{"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-3-version-history","title":"Loop 3 Version History","text":""},{"location":"version/releases/#loop-v341","title":"Loop v3.4.1","text":"

Loop v3.4.1 was released on 19 July 2024.

This was a patch that fixed errors with the Browser Build. No other changes were made.

"},{"location":"version/releases/#loop-v340","title":"Loop v3.4.0","text":"

Loop v3.4.0 was released on 13 July 2024.

"},{"location":"version/releases/#summary-of-important-new-features","title":"Summary of Important New Features","text":"

These features are added:

"},{"location":"version/releases/#summary-of-bug-fixes","title":"Summary of Bug Fixes","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.

"},{"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.

"},{"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):

Updates and new Features:

"},{"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

Branch Name Change

The branch name associated with the latest Loop release is main.

"},{"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

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:

"},{"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, iAPS, 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/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":"

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":""},{"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

"},{"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.

"},{"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:

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:

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.

"},{"location":"version/simulator/#simulated-pump-or-cgm-on-phone","title":"Simulated Pump or CGM on Phone","text":"

The simulators for the Pump and CGM, with version 3.3 and later, hide their detailed configuration screen. The initial view is a demonstration screen showing a typical CGM or Pump display. In order to configure the simulator controls or delete the simulator, you must tap on the Simulator Settings row.

If you do not see the Simulator Settings row, you have an older version. You can see the settings by doing a long-press (5 to 10 sec) in the top portion of the simulator screen. 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.

"}]} \ 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.

"},{"location":"#what-is-loop-video","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":"browser/automatic/","title":"Automatic Update & Build","text":""},{"location":"browser/automatic/#overview","title":"Overview","text":"

The instructions provided for building with a browser include settings to automatically update and build for you.

This keeps the most recent version of the Loop app available in TestFlight for you to install when you are ready.

These events are automatically scheduled:

If you do not want this automatic schedule, you can modify it.

Regardless of your choice, please Disable Automatic Installation from TestFlight. You should be alert any time your Loop app is updated. Check that all settings are maintained and pay attention to make sure the app behavior is nominal.

You still need to take these actions to ensure a recent build of the Loop app is available in TestFlight for you to install on your phone when you choose:

"},{"location":"browser/automatic/#successful-weekly-action","title":"Successful Weekly Action","text":"

Normally, you will see a successful build action once a week. This happens at 08:00 UTC every Wednesday.

If there are no updates to the main branch, your actions show a very short, successful build action as shown in the graphic below. It only takes about a minute because the logic says - no update then skip the build.

If there is an update, the build action updates your fork and creates a new build.

In that case, you should check your favorite information site to find out what the update was and then, when you are ready, install the update using the TestFlight app on your phone.

"},{"location":"browser/automatic/#successful-monthly-action","title":"Successful Monthly Action","text":"

On the first day of every month at 06:00 UTC, you will see a successful build action. The purpose of this build is to provide a recent version of the app in TestFlight so you are never in a situation where you have no app on your phone.

You start getting Notifications when there are fewer than 20 days until expiration. When you see the warning, install the newest build from your TestFlight app. You do not want to get the dreaded \"Loop Beta is not available\" message on your phone. (The warnings get very agressive when close to expiration.)

"},{"location":"browser/automatic/#what-are-the-alive-branches","title":"What are the alive branches?","text":"

The automatic update and build feature is embedded in the build_loop.yml code and uses the GitHub scheduling feature to trigger actions to run automatically.

Some may have noticed one or more branches added to your repository that start with the name alive. Don't worry about these. They are automatically created to ensure GitHub will keep building your app automatically.

You may see branches called alive, alive-dev or alive-main in your repository.

The alive branches are created and used to make sure at least one commit per month is added to an alive branch in your repository. That keeps your repository active to allow the automatic update and build process to work.

The alive branches are only used for the keep-alive functions. Do not build using an alive branch. Most people will build using the default branch of main.

"},{"location":"browser/automatic/#automatic-creation-of-alive-branch","title":"Automatic Creation of alive branch","text":"

The alive branch you need is created automatically when you run the Build Loop action.

I got an error regarding a branch with alive in the name

"},{"location":"browser/automatic/#modify-automatic-building","title":"Modify Automatic Building","text":"

For someone using development code for their own use, they could decide to choose when to update their fork to the most recent commit. They can still have the advantage of automatic building without automatic updates; in other words, they want a new build added to TestFlight every month. There may be other configurations someone would choose. These options are available starting with Loop 3.3.0 (dev branch) and later.

You can affect the default behavior:

  1. Modify Automatic Schedule
  2. Disable Automatic Actions
"},{"location":"browser/automatic/#modify-automatic-schedule","title":"Modify Automatic Schedule","text":"

This is an optional step. If you are happy with the automatic sync and update, you are done with this page.

Instructions to Modify the Automatic Actions (Click to Open/Close)

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 N/A) true (or N/A) This is the default:keep-alive, weekly update check (auto update/build), monthly build with auto update false true (or N/A) keep-alive, monthly build, no auto update true (or N/A) false keep-alive, weekly update check with auto update, only builds if update detected false false no automatic activity, no keep-alive"},{"location":"browser/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":"browser/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":"browser/automatic/#stop-building","title":"Stop Building","text":"

What if I decide I don't want the automatic building feature?

"},{"location":"browser/bb-errors/","title":"Errors with Browser","text":""},{"location":"browser/bb-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 the link to your repository. For example - this link is used to test the build instructions and generate figures for LoopDocs. You replace your GitHub username where you see loopdocs-tester:

Mentors can go to your public\u00a0GitHub repository, make sure your code is up to date, examine your customizations (if any), then click on the Action tab and 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 link or as a bare minimum your GitHub username.

But first - try to diagnose it yourself using this page.

"},{"location":"browser/bb-errors/#most-common-mistakes","title":"Most Common Mistakes","text":"

Just updated?

If you just updated to version 3.4 from version 3.2.x, you must add a new Identifier.

If you missed this step - go do it now. Update from 3.2.x to 3.4

Certificate is missing

If you get this build error message: No code signing identity found and can not create a new one because you enabled, you do not have certificates needed to run the build.

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
    • See Annotation without Clear Message (Build) for an example of this kind of failure
  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
  7. You got an error regarding a branch with alive in the name
    • You can delete any branch that starts with the name alive and try again
    • See Automatic Creation of alive branch
"},{"location":"browser/bb-errors/#error-annotations","title":"Error Annotations","text":"

Error annotations are available for the Loop app released version 3.4 and later. These were contributed by community volunteers along with the improvements to enable automatic updates and automatic builds.

Not all error messages have an annotation yet. In those cases, you will be required to search for the error string as explained in Find the Error.

"},{"location":"browser/bb-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.

"},{"location":"browser/bb-errors/#annotation-with-clear-message","title":"Annotation with Clear Message","text":"

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

"},{"location":"browser/bb-errors/#annotation-without-clear-message-certificates","title":"Annotation without Clear Message (Certificates)","text":"

Not all error messages have a clear annotation (yet).

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.

"},{"location":"browser/bb-errors/#missing-certificates","title":"Missing Certificates","text":"

If your certificates have expired, you will see this error when you try to build. It does not have a clear annotation. The error string starts with: No code signing identity found and can not create a new one because you enabled.

"},{"location":"browser/bb-errors/#annotation-without-clear-message-build","title":"Annotation without Clear Message (Build)","text":"

The GIF below shows a failure of\u00a0GitHub Action: 4. Build Loop\u00a0. The nice messages have not been added to this yet - you will have to follow the Find the Error instructions, but now, you are automatically taken to the correct section so there is less of the log to deal with.

"},{"location":"browser/bb-errors/#find-the-error","title":"Find the Error","text":"

This section is required when you need to search for a string to diagnose and error that does not have a clear annotation.

"},{"location":"browser/bb-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":"browser/bb-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 Annotation 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. For each section there are possible strings to paste to search the log.

Error annotations are available for the Loop app version 3.4 and later for some of the actions. We believe the first two actions have a complete set of error annotations.

  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":"browser/bb-errors/#still-stuck","title":"Still Stuck?","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":"browser/bb-errors/#action-validate-secrets-errors","title":"Action: Validate Secrets Errors","text":"

For Version 3.4 and later - use Examine Annotation and read the annotation.

"},{"location":"browser/bb-errors/#action-add-identifiers-errors","title":"Action: Add Identifiers Errors","text":"

For Version 3.4 and later - use Examine Annotation and read the annotation.

"},{"location":"browser/bb-errors/#action-create-certificates-errors","title":"Action: Create Certificates Errors","text":"

Review Examine Annotatios for instructions on how to use the error strings.

"},{"location":"browser/bb-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:

Click on this link to Delete Identifiers.

"},{"location":"browser/bb-errors/#rerun-steps-with-correct-teamid","title":"Rerun Steps with correct TEAMID","text":"

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

  2. Run Action: Configure to Use Browser: Add Identifiers again

  3. 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":"browser/bb-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":"browser/bb-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":"browser/bb-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":"browser/bb-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":"browser/bb-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":"browser/bb-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":"browser/bb-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":"browser/bb-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

If you had to step backward and fix an Identifier, you must run Create Certificates again.

Refer to Annotation without Clear Message (Build) for a detailed example of these steps:

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":"browser/bb-errors/#error-could-not-find-an-app-on-app-store-connect","title":"Error: 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":"browser/bb-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, you might see:

Return to First-Time: Identifiers for the Loop app and make sure you followed all the steps.

You must create certificates again before you can build Loop:

"},{"location":"browser/bb-errors/#error-a-new-one-cannot-be-created-because-you-enabled","title":"Error: 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":"browser/bb-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 Annotation instructions to find your error message.

"},{"location":"browser/bb-errors/#error-asset-validation-failed","title":"ERROR: Asset validation failed","text":"

This error indicates your fork needs to be updated. As of 29 April 2024, you are required to use Xcode 15 to build the app.

There are serveral phrases you can check for. All of them have the same solution.

Copy the words on the line below and paste them into the search function for your action log.

ERROR: Asset validation failed\n
Could not download/upload from App Store Connect\n

Solution: Update your fork. See instructions on the Update page: Update Fork

"},{"location":"browser/bb-errors/#intermittent-testflight-upload-number-error","title":"Intermittent TestFlight Upload Number Error","text":"

This is an intermittent error

Looking into history, we see that this error has been reported intermittently over the last few years.

Copy the words on the line below and paste them into the search function for your action log.

Error: The provided entity includes an attribute\n

The full error looks like this: Error: The provided entity includes an attribute with a value that has already been used The bundle version must be higher than the previously uploaded version: #

Examine the number that is there. If it is 3, you need to use 4 in the Solution step. If it is 53, you use 54.

Solution: You must force Apple to update to a build number higher than the one it has on record.

Summary of what you will do (don't do it yet); there are detailed steps and graphics below:

  1. You will edit the Fastfile in your fork and save the changes to a new patch branch
  2. Perform the Action to Build Loop and select the patch branch when you build

There is no reason to expect subsequent builds to fail with this same error, but if it does, repeat this section.

"},{"location":"browser/bb-errors/#prepare-your-fork","title":"Prepare your fork","text":"

The graphic below shows the steps to make sure your fork is up to date and to locate the fastfile folder:

  1. Select the branch that you plan to build
  2. Check the fork for that branch is up to date
    • If it is behind, sync the fork

  3. Scroll down to locate the folder fastlane and click on it (next graphic)

"},{"location":"browser/bb-errors/#prepare-to-edit-your-fastfile","title":"Prepare to Edit your Fastfile","text":"
  1. After clicking on the fastlane folder, 3 files are visible; click on Fastfile
  2. When the Fastfile file opens click on the pencil icon so you can edit the file
"},{"location":"browser/bb-errors/#edit-your-fastfile","title":"Edit your Fastfile","text":"

  1. Type either Cmd+F (Mac) or Ctrl+F (PC) to reveal the find and replace dialog shown in the graphic below

    • Copy the phrase indicated below and paste it into the find buffer, and then type into the replace buffer the build number you want to require (one more than indicated by your last error)
    previous_build_number + 1\n

  2. Tap on the Find button and the Replace button to make 2 changes to the file

  3. After modifying the two lines, click on the Commit changes button at upper right

"},{"location":"browser/bb-errors/#save-to-a-patch-branch","title":"Save to a Patch Branch","text":"

Refer to the graphic below. The number 3 by the Commit changes button indicates the selection made in the previous step; it is shown for reference.

  1. Tap on indicator that you will save to a new branch - GitHub will automatically name it for you
  2. Tap on Propose changes button and then STOP; do not click on Open pull request - you are done with this step

"},{"location":"browser/bb-errors/#build-using-patch-branch","title":"Build using Patch Branch","text":"

Select Action: Build Loop

Refer to the first graphic below:

There is not a lot of indication that the build started - be patient - or refresh the screen - do NOT start another build. Your build status should be similar to the next graphic.

Once you get a successful build, you return to using your normal branch for future builds.

There is no reason to expect subsequent builds to fail with this same error, but if it does, repeat this section.

"},{"location":"browser/bb-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":"browser/bb-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. In your fork of LoopWorkspace:
    • This will automatically create a new Match-Secrets Repository for you
    • 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
  3. 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":"browser/bb-errors/#misleading-error-message_1","title":"Misleading Error Message","text":"

If there are Apple Developer agreements you have not accepted, you will get errors when you try to build the app that indicate your Apple Secrets are incorrect.

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.

If you need detailed instructions, click on this Apple Program License Agreement Help Page.

"},{"location":"browser/bb-errors/#extra-sections","title":"Extra Sections","text":"

It is unlikely you will need these sections. They are being saved for the transition to version 3.4.x. The Match-Secrets repository is automatically created for you if you don't have one. The instructions below were used when you had to create yours manually.

"},{"location":"browser/bb-errors/#create-match-secrets","title":"Create Match-Secrets","text":"

Open your github.com URL (this is https://github.com/username), (username is your GitHub account name).

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":"browser/bb-errors/#delete-identifiers","title":"Delete Identifiers","text":"

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. If a Bundle ID has ever been associated with an app in the App Store, you cannot delete the Identifier.

If coming here because you enter the wrong TEAMID in Secrets - return to Rerun Steps with Correct TEAMID when you've deleted as many identifiers as you can.

After you delete identifiers, you must add them back, configure them and create certificate before you can build again.

"},{"location":"browser/bb-overview/","title":"Browser Overview","text":""},{"location":"browser/bb-overview/#build-with-a-browser","title":"Build with a Browser","text":""},{"location":"browser/bb-overview/#requirements","title":"Requirements","text":""},{"location":"browser/bb-overview/#phone-cgm-and-pump","title":"Phone, CGM and Pump","text":"

To use the Loop app, you need:

"},{"location":"browser/bb-overview/#accounts","title":"Accounts","text":"

To build the\u00a0Loop\u00a0app using a browser, you need:

  1. Free GitHub account: (instructions found at New GitHub Account)
  2. Paid Apple Developer account: ($99/year; instructions found at Apple Developer Account)
"},{"location":"browser/bb-overview/#instructions-to-build-with-a-browser","title":"Instructions to Build with a Browser","text":""},{"location":"browser/bb-overview/#how-to-video-to-build-with-a-browser","title":"How-to Video to Build with a Browser","text":"

In addition to the pages linked in Configure to use Browser, there is a narrated video of each step needed to build using a browser. (This video shows build steps for version 3.2.3 or older. Some items are simplified for version 3.4.1 and newer.)

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":"browser/bb-overview/#configure-to-use-browser","title":"Configure to use Browser","text":"

There is a lot of information in the introduction and summary page. Please don't skip that. it should be read before you begin. The steps on these pages must be completed for you to build an app using a browser:

  1. Introduction and Summary
  2. Collect Secrets
  3. Prepare Fork
  4. Identifiers
  5. Prepare App
  6. Create Certificates
  7. Build the Loop App
  8. TestFlight Users
"},{"location":"browser/bb-overview/#install-on-phone","title":"Install on Phone","text":"

Instructions to install on a phone are found at:

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

Try to:

"},{"location":"browser/bb-overview/#errors-while-configuring-and-building","title":"Errors while Configuring and Building","text":"

If you get an error that you cannot figure out, reach out for help before you get frustrated or begin to delete things - let a mentor help you:

"},{"location":"browser/bb-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. Once again, this was prepared for an earlier version 3.2.3 or older. With version 3.4.1 and newer, the update and build is automatic:

"},{"location":"browser/bb-overview/#other-topics","title":"Other Topics","text":""},{"location":"browser/bb-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":"browser/bb-overview/#mac-vs-browser","title":"Mac vs Browser","text":"

These considerations were prepared when most people were using a Mac computer to build the Loop app.

"},{"location":"browser/bb-update/","title":"Update/Rebuild with Browser","text":""},{"location":"browser/bb-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

One Time: Complete the information for the Digital Service Act Compliance

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 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":"browser/bb-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":"browser/bb-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":"browser/bb-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.

Digital Service Act Compliance

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":"browser/bb-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":"browser/bb-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":"browser/bb-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.

"},{"location":"browser/bb-update/#up-to-date-or-behind","title":"Up to Date or Behind","text":"

"},{"location":"browser/bb-update/#ahead-and-behind","title":"Ahead and Behind","text":"

Building a different branch

Do I need to do anything special to build a different branch?

Yes: the update steps are the same, but review information on this page: Build Loop dev with Browser

"},{"location":"browser/bb-update/#build-the-loop-app","title":"Build the Loop App","text":"

This is Step 4 of 6 - this is always required.

"},{"location":"browser/bb-update/#update-from-32x-to-34","title":"Update from 3.2.x to 3.4","text":"

For the update from 3.2.x to 3.4, you must do more than \"just\" build. If you skip this step - the build will fail.

If you built version 3.3.0 (the dev branch before release of version 3.4) or newer, you can skip ahead to Build the App.

You will (1) run Add Identifiers, (2) add the App Group to the new identifier, (3) run Create Certificates and then (4) run Build Loop.

"},{"location":"browser/bb-update/#add-identifiers","title":"Add Identifiers","text":"

In your fork of LoopWorkspace:

Detailed instructions for Add Identifier (Click to open/close)

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 dropdown menu
    • You will see your default branch (typically this is main)

  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":"browser/bb-update/#add-app-group-to-new-identifier","title":"Add App Group to New Identifier","text":"

Open the Certificates, Identifiers & Profiles: Identifiers List page.

Click on the \"LoopWidgetExtension\" identifier to open the Edit Your App ID Configuration screen.

NAME IDENTIFIER Loop Widget Extension com.TEAMID.loopkit.Loop.LoopWidgetExtension

The graphic below has numbered steps that match these directions:

  1. Looking at the App Services column, scroll down to the App Groups row and ensure the check box (under the Capabilities column) for App Groups is checked
  2. If the word Configure shows up, tap on it
    • This opens the App Group Assignment screen
    • If it said Edit instead of Configure - you can click to confirm you have the correct App Group but won't need to continue or save if it is correct
  3. Check the box by Loop App Group that uses your TEAMID in group.com.TEAMID.loopkit.LoopGroup
    • Note that if you previously built with Xcode, the name may be different, i.e., XC group com TEAMID loopkit LoopGroup
  4. Tap Continue
  5. Tap Save

If you did not need to make changes, the Save button will not be active.

The full list of Identifiers should be displayed again.

Other Identifiers

All other identifiers should be already set up.

"},{"location":"browser/bb-update/#create-certificates","title":"Create Certificates","text":"

You must run the action Create Certificates again because the Identifiers were updated. Wait for this to succeed before trying to build.

Detailed instructions (Click to open/close)

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 dropdown menu
    • You will see your default branch (typically main)

  4. Tap the green button that says \"Run workflow\".

  5. Wait a minute or two for the action to finish

"},{"location":"browser/bb-update/#build-the-app","title":"Build the App","text":"

Refer to graphic below as you follow the steps to build the Loop app.

"},{"location":"browser/bb-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. (Updating from 3.2.3 to 3.4.1 requires extra steps described above.)

If you are using the dev branch, the update steps are the same, but review information on this page: Build Loop dev with Browser.

Otherwise, head over to Errors with Browser.

"},{"location":"browser/bb-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":"browser/bb-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":"browser/bb-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 app will show up in your TestFlight app.

"},{"location":"browser/bb-update/#testflight-automatic-update-disabled","title":"TestFlight 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":"browser/bb-update/#testflight-automatic-update-enabled","title":"TestFlight 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":"browser/bb-update/#other-information","title":"Other Information","text":""},{"location":"browser/bb-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:

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. If you choose to Add Test Details to TestFlight, you can have notes show up to help you decide which version to load.

"},{"location":"browser/bb-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":"browser/bb-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.

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":"browser/bb-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":"browser/bb-update/#add-test-details-to-testflight","title":"Add Test Details to TestFlight","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":"browser/build-dev-browser/","title":"Build Loop dev with Browser","text":""},{"location":"browser/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":"browser/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":"browser/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":"browser/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":"browser/build-dev-browser/#update-branch","title":"Update Branch","text":"

If you normally build released code, but decided to build the dev branch because you want the features and bug fixes found there, please do not update the fork for the dev branch without first finding out what has changed since your last build.

Tap the Code button (upper left) and ensure this branch in your fork is up to date.

"},{"location":"browser/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.

With the release of version 3.4, no one-time changes are required. This assumes you built main after the release of 3.4.

"},{"location":"browser/build-dev-browser/#build-branch","title":"Build Branch","text":"

We recommend most users leave their default branch as main.

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. In addition to the normal steps 1, 2 and 3 in the graphic below, you must also do the (optional) step. Select the dev branch in the branch dropdown menu before continuing to step 4 and tapping on the green Run workflow button.

"},{"location":"browser/build-dev-browser/#refresh-do-not-repeat","title":"Refresh, Do Not Repeat","text":"

Hit Refresh

After you tap the green Run workflow button, GitHub can be slow to update.

"},{"location":"browser/build-dev-browser/#automatic-update-build","title":"Automatic Update & Build","text":"

The Automatic Update & Build features are applied to the default branch of your repository. Normally this is the main branch. If you are a developer or tester who wants the dev branch to be built automatically, you must configure it as your default branch. Be aware that for this situation, you will not get automatic updates of released code.

Most people should keep main as default and make a considered decision when to launch a manual build of the dev branch. At that time, it will automatically update to the latest dev commit unless you have modified your environment settings: Modify Automatic Building.

"},{"location":"browser/build-dev-browser/#change-default-branch","title":"Change Default Branch","text":"

We recommend most users leave their default branch as main.

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":"browser/build-dev-browser/#automatic-update-build_1","title":"Automatic Update & Build","text":"

The automatic update and build features are available for both the released (main) and development (dev) branch, but only for your default branch. For any other branch name set as your default branch, there is no automatic update available but the automatic build will run monthly.

Be sure to read this page: Automatic Update & Build.

"},{"location":"browser/build-yml/","title":"Build the App","text":""},{"location":"browser/build-yml/#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 dropdown 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

Be Patient

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.

You should get several emails

Your app should eventually appear on App Store Connect.

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

Congratulations

If you get the green check mark, your app successfully built. Just a few more steps.

"},{"location":"browser/build-yml/#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":"browser/build-yml/#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":"browser/build-yml/#next-steps","title":"Next Steps","text":"

If this is your first build, you need to configure your TestFlight Users

If this is a repeat build, wait up to an hour for your new build to appear in TestFlight. Then from the phone where you want to install the Loop app, use TestFlight on that phone to install the app.

"},{"location":"browser/build-yml/#caregivers","title":"Caregivers","text":"

If you are a Caregiver who helps manage a loved-ones diabetes, you may use other open-source apps that can be built the same way:

"},{"location":"browser/certs/","title":"Create Certificates","text":""},{"location":"browser/certs/#overview","title":"Overview","text":"

The instructions on this page are required to build your app intially. This action ties information in your Match-Secrets private repository to your Apple information so that the build action works. Once successful that, it only needs to be run again in a few cases.

"},{"location":"browser/certs/#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 dropdown 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

Be Patient

"},{"location":"browser/certs/#success","title":"Success","text":"

Once you see the green check mark by Create Certificates, the next step is to Build your Loop App.

"},{"location":"browser/certs/#failure","title":"Failure","text":"

If this action fails, head over to the errors page. Review these links, identify and fix your error or ask for help.

"},{"location":"browser/custom-browser/","title":"Customize using Browser","text":""},{"location":"browser/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":"browser/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":"browser/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":"browser/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":"browser/edit-browser/","title":"Custom Edits with Browser","text":""},{"location":"browser/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":"browser/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":"browser/edit-browser/#overview","title":"Overview","text":"

Time Estimate

Summary

FAQs

"},{"location":"browser/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":"browser/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":"browser/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 Personalized Customization for this Module.

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":"browser/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":"browser/edit-browser/#create-your-fork-for-selected-module","title":"Create your Fork for Selected Module","text":"

Choose your link:

"},{"location":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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.

"},{"location":"browser/edit-browser/#prepare-customization-lines","title":"Prepare customization lines","text":"

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":"browser/edit-browser/#update-loopworkspace","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":"browser/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 lines that you prepared in Prepare customization lines similar to the examples, near line 239, that are commented out and provided as an example. The best place to paste these is at the end of the # Customize Loop: Download and apply patches section and before the # Patch Fastlane Match to not print tables line.

The indenting needs to match, so tab or (shift-tab) to line up the columns.

It is best to leave a blank line between customizations.

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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/edit-browser/#special-cases","title":"Special Cases","text":""},{"location":"browser/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":"browser/edit-browser/#background-information","title":"Background Information","text":""},{"location":"browser/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":"browser/identifiers/","title":"Identifiers","text":""},{"location":"browser/identifiers/#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":"browser/identifiers/#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 dropdown 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.

Hit Refresh

After you tap the green Run workflow button, GitHub can be slow to update.

"},{"location":"browser/identifiers/#add-identifiers","title":"Add Identifiers","text":"

Update to Version 3.4

The name and identifier for \"Small Status Widget\" was renamed to \"Loop Widget Extension\". If you previously built, you will need to run the Add Identifiers as directed on the update page to add the renamed Identifier and Create Certificates for it.

If you previously built the dev branch, you already have this identifier.

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

Be Patient

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":"browser/identifiers/#next-step","title":"Next Step","text":"

The next step is to Prepare the App.

"},{"location":"browser/intro-summary/","title":"Introduction and Summary","text":""},{"location":"browser/intro-summary/#summary-of-steps","title":"Summary of Steps","text":"Time Estimate (click to open/close) Summary for Browser Build with Links (click to open/close)

You may be overwhelmed at first with all the new terms and the many steps. Take a deep breath and work through the steps one at a time.

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 LoopDocs section.

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":"browser/intro-summary/#automatic-build-of-loop","title":"Automatic Build of Loop","text":"

When you follow the directions to configure building with a browser, for Loop 3.4 and later, you configure your app to automatically build at least once a month. You also configure your app to be updated within one week of a new release, in other words, when the LoopKit/LoopWorkspace main branch is updated. For details, see Automatic Update & Build.

"},{"location":"browser/intro-summary/#tips-and-tricks","title":"Tips and Tricks","text":"

The steps to configure for building with a browser requires a lot of focused attention. Take it in steps and take breaks as needed. Some people prefer a video. Some people prefer more detailed steps on a webpage and others only high-level steps.

"},{"location":"browser/intro-summary/#how-to-video-to-build-with-a-browser","title":"How-to Video to Build with a Browser","text":"

There is a narrated video of each step needed to build using a browser. This video was created for version 3.2.x and some steps have been simplified with version 3.4.x.

Click in the comments for a full index of topics. If you have issues with a particular section, 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":"browser/intro-summary/#section-summaries","title":"Section Summaries","text":"

Some sections have a Section Summary for those who just want high-level steps without a lot of graphics. It also provides a high-level view of what you are going to do before you do it.

"},{"location":"browser/intro-summary/#sparse-instructions","title":"Sparse Instructions","text":"

For sparse instructions, with no graphics or hand-holding, click on the link below:

"},{"location":"browser/intro-summary/#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.

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 or hyphens. 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.

"},{"location":"browser/intro-summary/#make-a-secrets-reference-file","title":"Make a Secrets Reference File","text":"

Please save yourself a lot of agony. Make a Secrets Reference folder and then create a Secrets Reference file in it.

You don't need to know anything about the Secrets to do this. Come up with your own names, but make sure you know where you put this file.

  1. Decide where you want your Secrets saved and create a special folder
  2. Open a text-only editor (do not use a Smart Editor, those might change capitalization or formating and ruin your Secrets)
    • Create a blank Secrets Reference file using the text-only editor
    • Tap on the copy icon below to copy the template and paste it into your blank file
    • Save the file
  3. As you move through the steps of Collect Secrets, fill in the file
    • The ## characters are used to indicate sections or title (text only file)
    • There is a reference pattern for each SECRET: replace that with your SECRET or you can add your secret below the pattern to give yourself confidence you got the correct item
  4. In addition to the Secrets, this template has places for other pieces of information you may find handy to save in the same file
  5. At the very beginning is a place to indicate the last day you updated the file
Template to use for Secrets
MySecretsReferenceFile.txt\n\n## This file updated on: DD MMM YYYY\n\nInformation needed to use Browser Build.\nThe same secrets are used for every app you build.\n\nFirst some handy username and password information:\n\n## Apple ID username for your Developer account is the associated email:\n<your information here>\nsuggest you use your desired password tool to save the password for this account\n\n## GitHub username\n<your information here>\nsuggest you use your desired password tool to save the password for this account\n\nThese are the Six Secrets in alphabetical order - each one shows the expected format.\nDelete each prototype as you gather your own secrets.\nThe letter A indicates an alphanumeric character.\nSome may be lower case, some upper case and some numerals.\nThe FASTLANE_KEY may have additional characters included.\nFor that one copy the entire key\nincluding -----BEGIN PRIVATE KEY-----\nthrough\n-----END PRIVATE KEY-----\n\n## SECRETS BELOW:\n\nFASTLANE_ISSUER_ID\n<looks like this>\nAAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA\n\nFASTLANE_KEY_ID\n<looks like this>\nAAAAAAAAAA\n\n\nFASTLANE_KEY\n<looks like this>\n-----BEGIN PRIVATE KEY-----\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nAAAAAAAA\n-----END PRIVATE KEY-----\n\nGH_PAT\n<looks like this>\nghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\n\nMATCH_PASSWORD\n<looks like this>\nAnyThingYouWant-sameForEveryRepository\n\nTEAMID\n<looks like this>\nAAAAAAAAAA\n\n## Repository Names for my Fork:\n\nhttps://github.com/my-github-username/LoopWorkspace\n\nAdd additional apps here if you decide to build any\n
"},{"location":"browser/intro-summary/#new-terms-with-github-browser-build","title":"New Terms with GitHub Browser Build","text":"

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.

"},{"location":"browser/intro-summary/#next-step","title":"Next Step","text":"

The next step is to Collect and Save Secrets.

"},{"location":"browser/other-apps/","title":"Build Other Apps with Browser","text":""},{"location":"browser/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":"browser/other-apps/#updating-rebuilding-other-apps","title":"Updating / Rebuilding Other Apps","text":"

If you are coming to this page to update one of the other apps, follow the How to Update or Rebuild instructions provided for the Loop app, but substitute the repository name from the Table of App Repositories for the app you want to rebuild for all references to\u00a0LoopWorkspace.

"},{"location":"browser/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":"browser/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":"browser/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":"browser/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":"browser/other-apps/#fork-and-add-secrets","title":"Fork and Add Secrets","text":""},{"location":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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 dropdown 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":"browser/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 dropdown 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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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":"browser/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
      • Your screen should be similar to the graphic below
      • If you made any changes, tap Continue, otherwise, tap Cancel

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

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

  4. The full list of Identifiers should be displayed again.

  5. 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":"browser/other-apps/#create-app-in-app-store-connect","title":"Create App in App Store Connect","text":"

Same procedure as for the Loop app

You will follow the same procedure as you did with the Loop app.

You will also want to edit your new app once you create it to Remove Apple Vision Pro.

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.

  6. Edit your new app to Remove Apple Vision Pro

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":"browser/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 dropdown 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":"browser/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":"browser/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":"browser/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 dropdown 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":"browser/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":"browser/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":"browser/other-apps/#use-a-github-organization-account","title":"Use a GitHub Organization Account","text":"

This section is optional. It is provided to assist:

"},{"location":"browser/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":"browser/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

    • Not required for version 3.4 or later of the Loop app but it may be required for other apps if you haven't already built the Loop app
    • 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 dropdown 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":"browser/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":"browser/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":"browser/other-apps/#option-1-delete-repository","title":"Option 1: Delete repository","text":"

You can delete the DIY repositories from your personal account

"},{"location":"browser/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":"browser/phone-install/","title":"Install on Phone","text":""},{"location":"browser/phone-install/#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. With version 3.4.0 and later, the build is automatic. It is recommended you manually install the new build using TestFlight at your convenience.

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":"browser/phone-install/#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":"browser/phone-install/#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":"browser/phone-install/#subsequent-times-on-phone","title":"Subsequent Times on Phone","text":""},{"location":"browser/phone-install/#automatic-update-build-install","title":"Automatic Update, Build, Install","text":"

The instructions on the Configure to Use Browser page will, unless you make a change, automatically take the following actions for released versions 3.4.0 and later:

It is already true that, unless you make a change, the default setting will:

"},{"location":"browser/phone-install/#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 Automatic Update & Build.

"},{"location":"browser/phone-install/#disable-automatic-install-from-testflight","title":"Disable Automatic Install from TestFlight","text":"

Once the app is available in TestFlight, 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":"browser/phone-install/#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 the Loop app). 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":"browser/phone-install/#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":"browser/prepare-app/","title":"Prepare App","text":""},{"location":"browser/prepare-app/#prepare-the-app","title":"Prepare the App","text":"

After creating the identifiers, you will need to modify to make sure the correct App Group is associated with each identifier (there will be instructions) and you need to prepare the App - one of those identifiers just created is used as the Bundle ID for building your app. This can be a little confusing and a lot of pages over at Apple look the same. Make sure you follow the links given for each section.

"},{"location":"browser/prepare-app/#configure-identifiers-for-loop","title":"Configure Identifiers for Loop","text":"

This should only be needed one time, unless the developers add or modify an identifier. This happened between version 3.2 and version 3.4.

Some steps can be skipped if you previously built the Loop app with a Mac using Xcode.

Please read carefully to avoid confusion.

"},{"location":"browser/prepare-app/#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 Optional: App Group Description Modification.

  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

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 Optional: App Group Description Modification to update the description.

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.

If this is successful, then skip ahead to Add App Group

If you get an error saying An Application Group with Identifier 'group.com.TEAMID.loopkit.LoopGroup' is not available. Please enter a different string, that means you already have the Loop App Group assigned to your account. Continue with the next section.

"},{"location":"browser/prepare-app/#optional-app-group-description-modification","title":"Optional: App Group Description Modification","text":"

This step is not required, but if you previously built using a Mac with Xcode, it is a good idea to update the Name associated with the Identifier for the Loop App Group. Then what you see on your display will match the directions as you continue.

Optional Rename Step (click to open/close)

Click to display the App Group List

Tap on the Identifier that shows group.com.TEAMID.loopkit.LoopGroup where TEAMID is your Developer ID.

Notice in the table below that the XCode version of the NAME for the App Group is the same as the IDENTIFIER but with the . replaced with a space.

NAME XCode version IDENTIFIER Loop App Group group com TEAMID loopkit LoopGroup group.com.TEAMID.loopkit.LoopGroup"},{"location":"browser/prepare-app/#add-app-group","title":"Add App Group","text":"

First, review the Identifiers and then Add App Group to Identifiers.

"},{"location":"browser/prepare-app/#identifiers-for-the-loop-app","title":"Identifiers for the Loop app","text":"

Identifier change after version 3.2.x

One of the identifier names changed when transitioning from version 3.2.3.

This is indicated in the Table of identifiers with v3.2 or v3.4.

If you ever built the Loop app using Mac, skip ahead to Previous Xcode Builders.

"},{"location":"browser/prepare-app/#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.

"},{"location":"browser/prepare-app/#previous-xcode-builders","title":"Previous Xcode Builders","text":"

If you built previously using a Mac with Xcode, you may see the XCode version in your NAME column of the table below.

If you want your NAME column to match the documentation, follow this optional step.

Optional Rename Step (click to open/close)

Referring to the table below, tap on each IDENTIFIER that has a different NAME

Only the Identifer Bundle ID matters and that is not something you can edit.

The Description or Name can be whatever you want.

"},{"location":"browser/prepare-app/#table-with-name-and-identifier","title":"Table with Name and Identifier","text":"

One Identifier was changed after v3.2.3. (Small Status Widget is now Loop Widget Extension).

NAME XCode version IDENTIFIER Loop XC com TEAMID loopkit Loop com.TEAMID.loopkit.Loop Loop Intent Extension XC Identifier com.TEAMID.loopkit.Loop.Loop-Intent-Extension Loop Status Extension XC Identifier com.TEAMID.loopkit.Loop.statuswidget Loop Widget Extension XC Identifier com.TEAMID.loopkit.Loop.LoopWidgetExtension WatchApp XC Identifier com.TEAMID.loopkit.Loop.LoopWatch WatchAppExtension XC Identifier com.TEAMID.loopkit.Loop.LoopWatch.watchkitextension v3.2 Small Status Widget XC Identifier com.TEAMID.loopkit.Loop.SmallStatusWidgetNo longer used, harmless to leave or to delete"},{"location":"browser/prepare-app/#add-app-group-to-identifiers","title":"Add App Group to Identifiers","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. The Add Identifier Action that you completed above generates 6 identifiers, but only 4 need to be modified as indicated in this step. A table, provided above, lists both Names and Identifiers for all 6 if you are interested.

Note 2 - Depending on your build history, you may find some of the Identifiers already have your \"App Group\" and you are just verifying the status.

  1. Go to Certificates, Identifiers & Profiles on the Apple Developer site.
  2. For each of the following identifier names (be sure to look in Identifier column if names do not match):
    • Loop
    • Loop Intent Extension
    • Loop Status Extension
    • Small Status Widget (v3.2) / Loop Widget Extension (v3.4 or newer)
  3. Click on the identifier's name.
  4. 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
    • If the word Edit shows up under NOTES, the App Group is already selected
    • 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 and Save
  5. Remember to do this for each of the identifiers above.

To skip the detailed instructions, click on Create Loop App in App Store Connect

Click to open the Certificates, Identifiers & Profiles: Identifiers List page.

Look in the IDENTIFIER column to locate each Identifer. The name in the NAME column may be different if you previously built with a Mac using Xcode.

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 Loop Widget Extension com.TEAMID.loopkit.Loop.LoopWidgetExtension

Click on each IDENTIFIER in turn and the Edit Your App ID Configuration screen will open.

The example graphic below has numbered steps that match these directions:

  1. Looking at the App Services column, scroll down to the App Groups row and ensure the check box (under the Capabilities column) for App Groups is checked
  2. If the word Configure shows up, tap on it
    • This opens the App Group Assignment screen
    • If it said Edit instead of Configure - you can click to confirm you have the correct App Group but won't need to continue or save if it is correct
  3. Check the box by Loop App Group that uses your TEAMID in group.com.TEAMID.loopkit.LoopGroup
    • Note that if you previously built with Xcode, the name may be different, i.e., XC group com TEAMID loopkit LoopGroup
  4. Tap Continue
  5. Tap Save

If you did not need to make changes, the Save button will not be active.

The full list of Identifiers should be displayed again.

Repeat until the 4 Identifiers have the Loop App Group configured.

"},{"location":"browser/prepare-app/#digital-service-act-compliance","title":"Digital Service Act Compliance","text":"

In order to create an app you need to indicate whether you are a trader or a non-trader. You are a non-trader unless you use the same Developer ID to submit apps for sale.

Even if the graphic below does not match what you see exactly, it should assist in guiding you through the steps.

Open this link: App Store Connect / Apps; log in if needed.

If you do not see the banner, shown in the top of the graphic below, asking you to Complete Compliance Requirements, you can skip ahead to Create Loop App in App Store Connect.

If you do see the banner, follow the numbered steps in the graphic below:

  1. Click on the link that says \"Complete Compliance Requirements\" to open a new screen shown in the middle of the graphic below

  2. Tap on the \"Complete Compliance Requirements for Your Name\" link to bring up a pop-up shown in the bottom of the graphic below

  3. Select the \"This is a non-trader provider account\" radio button

  4. Click Save

You do not need to add a bank account or fill out tax forms if you are only using the App Store to get your own app into TestFlight. You only need to have a paid account with a valid license agreement and have completed this compliance form. Ignore other requests from Apple.

"},{"location":"browser/prepare-app/#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, make sure you Remove Apple Vision Pro and then 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.

Remove Apple Vision Pro from the app you just created.

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 dropdown, this means you need to follow Find My Loop.

  2. There might be a blue banner present at this time. If not, it will show up after you have at least one app.

    • The information banner refers to \"iOS Apps on Apple Vision Pro\"
    • You must wait until you have an app before you can edit the capabilities for the app - this will happen after the next step

  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 (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\".

  5. 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 Errors with Browser: Delete Identifiers
  6. 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.
"},{"location":"browser/prepare-app/#remove-apple-vision-pro","title":"Remove Apple Vision Pro","text":"

It is now time to edit the availability of your app on Apple Vision Pro. If you skip this step, you will get an annoying email telling you Apple Vision Pro is not supported by your app.

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":"browser/prepare-app/#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":"browser/prepare-app/#next-step","title":"Next Step","text":"

The next step is to Create Certificates.

"},{"location":"browser/prepare-fork/","title":"Prepare Fork","text":""},{"location":"browser/prepare-fork/#fork-loopworkspace","title":"Fork LoopWorkspace","text":"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

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. Click 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 a 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":"browser/prepare-fork/#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.

"},{"location":"browser/prepare-fork/#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.

"},{"location":"browser/prepare-fork/#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 dropdown menu and select \"Your repositories\"

  2. Click on LoopWorkspace to open that repository

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

  4. 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":"browser/prepare-fork/#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":"browser/prepare-fork/#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.

"},{"location":"browser/prepare-fork/#next-step","title":"Next Step","text":"

The next step is to Validate Secrets and Add Identifiers.

"},{"location":"browser/prepare-fork/#already-have-loopworkspace","title":"Already Have\u00a0LoopWorkspace?","text":"

Some people may already have a copy (fork) of LoopWorkspace.

If your copy (fork) is not from LoopKit, follow the Delete and Start Fresh directions.

If your copy (fork) is from LoopKit:

"},{"location":"browser/prepare-fork/#delete-and-start-fresh","title":"Delete and Start Fresh","text":"

If your fork is not from LoopKit:

"},{"location":"browser/secrets/","title":"Collect Secrets","text":""},{"location":"browser/secrets/#collect-and-save-secrets","title":"Collect and Save 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":"browser/secrets/#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":"browser/secrets/#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":"browser/secrets/#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":"browser/secrets/#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 dropdown menu
    • Confirm the name and that \"Admin\" is selected and then click on the \"Generate\" button.
"},{"location":"browser/secrets/#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":"browser/secrets/#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":"browser/secrets/#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":"browser/secrets/#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":"browser/secrets/#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":"browser/secrets/#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.

Default Settings

These instructions are a prerequisite for automatic update and automatic build.

Refer to Modify Automatic Building if you don't want to accept the default recommendation to automatically update and build.

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

    What does repo and workflow do?

    • repo: enables manual build actions
    • workflow: enables repo and automatic build actions

  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":"browser/secrets/#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":"browser/secrets/#next-step","title":"Next Step","text":"

The next step is to Prepare your Fork (Copy of LoopWorkspace).

"},{"location":"browser/tf-users/","title":"TestFlight Users","text":""},{"location":"browser/tf-users/#set-up-users-and-access-testflight","title":"Set Up Users and Access (TestFlight)","text":"

You repeat this step 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. But you will need to add yourself to the TestFlight group for your App.

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":"browser/tf-users/#next-step","title":"Next Step","text":"

It is now time to install your Loop app using the TestFlight app on the phone: Install on Phone.

"},{"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/#the-file-could-not-be-unlocked","title":"The File Could not be Unlocked","text":"

Error Message: This error occurs inside Xcode with a modal alert that says:

The file \"contents.xcworkspacedata\" could not be unlocked

The solution is the same as in the previous section, Unable to read included file.

"},{"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 (on the same phone) 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.

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-and-one-cgm","title":"Dexcom G7 and ONE+ CGM","text":"

The Dexcom G7 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 G7 as far as the Loop app is concerned.

"},{"location":"build/cgm/#libre-cgm","title":"Libre CGM","text":"

With Loop 3.4 and newer versions, some Libre CGM are supported.

"},{"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":"

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/#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/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-the-loop-app","title":"Pumps Compatible with the Loop app","text":"

These types of pumps are compatible with the Loop app.

"},{"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 back of your pump to locate the sticker similar to that shown in the graphic below. 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 temporary basal rates 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 the pump firmware is compatible.

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 pump moves to 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 choose from different pump models, there are some slight differences between the Loop-compatible Medtronic pumps that may influence your decision.

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 noteworthy differences 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 people with diabetes, your 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 in some countries. Insulet stopped providing Eros pods in the US end of 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/#sooil-dana-pumps","title":"Sooil Dana pumps","text":"

Future Feature Only

Sorry but the Dana pump has not landed in released code or even dev code at this time. There is a testing fork, so check out Zulipchat Dana Pump discusion.

The information below is for the convenience of people reading along in zulipchat.

Every Dana pump has built-in BLE communications. Therefore, no RileyLink-compatible device is needed to use Dana-i / DanaRS-v3 with the Loop app.

"},{"location":"build/pump/#dana-i","title":"Dana-i","text":"

The Dana-i is the latest and greatest from the Korean pump manufacturer Sooil, released in 2020.

The special fork (see link for details) works with the Dana-i. If your version of the Loop app not from that fork, you cannot use the Dana-i.

"},{"location":"build/pump/#danars","title":"DanaRS","text":"

The DanaRS was first released in 2002, with firmware version v1 which is not supported at this time. Only firmware version v3 and onwards are supported with the Loop app. Check here to see how to check your firmware version.

The special fork (see link for details) works with the DanaRS-v3. If your version of the Loop app not from that fork, you cannot use the DanaRS-v3.

"},{"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/#apple-health-storage","title":"Apple Health Storage","text":"

Is Apple Health access Required?

There is internal Loop storage of all data required for the app to operate with a 7-day history. (This is new with version 3.) So using Apple Health for data storage is not 100% required for the app to operate, but it is very useful and recommended.

If you do not give Loop permission to use Apple Health, you will see no records in the Health app from Loop for carbohydrates, insulin or glucose. LoopDocs assumes permission was enabled to Apple Health.

"},{"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":"

Choose One Method for Upload

Previously, the only method to get Loop data into Tidepool was to use their mobile app on your phone and enable that app to read from Apple Health to upload data to Tidepool.

You can now upload directly from Loop to Tidepool - this is the preferred method.

With the direct upload, be sure to disable your Tidepool mobile app from reading Apple Health on your phone. If you do not do this, you will have double uploads of all your data. You can still make notes on the mobile app; it will get your data via the internet from Tidepool.

If you are currently using the Tidepool mobile app to upload and switch to direct upload, you will get one week of double uploads. You can filter the upload source for that week on 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 following CGM are supported by some or all versions of Loop:

See also: Compatible CGM page.

"},{"location":"faqs/cgm-faqs/#dexcom-faq","title":"Dexcom FAQ","text":""},{"location":"faqs/cgm-faqs/#do-i-need-wait-for-a-new-dexcom-sensor-session-to-start-loop","title":"Do I need wait for a new Dexcom 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-dexcom-sensor-is-in-warm-up","title":"What do I do when Dexcom 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/#libre-cgm","title":"Libre CGM","text":""},{"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":"

Loop 3.4.0 and later allows any Libre sensor supported by LibreTransmitter.

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":"

It is recommended that Libre users take advantage of the LibreTransmitter that is incorporated into the Loop app itself for version 3.4 and later.

You can add xDrip4iOS and GlucoseDirect as a CGM option to the Loop app by applying a code customization. However, this uses the shared AppGroup feature to transfer data from the CGM app to Loop. This is not the preferred approach.

Please read the docs for xDrip4iOS and Glucose Direct. You must build these apps yourself so they have the same developer ID as your Loop app; 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

dynamic carb absorption\u00a0 (dynamic carb absorption): Loop models the expected glucose change based on carbs entered, absorption time and your settings; and adjusts based on measured glucose

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 - Refers to the difference between observed change in blood glucose and the change in blood glucose that Loop models based on the effects of insulin.

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/#libre-cgm","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/#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 Change Pump Type 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.

Loop 3 is compatible with the OrangeLink.

"},{"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":"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/#loopdocs-contents","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/#building-loop","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/#operating-loop","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-or-one","title":"Dexcom G7 or ONE+","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/#libre","title":"Libre","text":"

The Libre plugin for Loop, LibreTransmitter, connects directly via Near Field Communication (NFC) during pairing (for some sensors) and via Bluetooth (direct to sensor or direct to a transmitter attached to the sensor) for regular readings. No other app is needed.

Connecting to Libre

First reading for a new sensor will often take 2-4 minutes. This is due to some technicalities on how the Libre sensor announces its presence via bluetooth.

There are solutions for some Libre 3 but they cannot reside on an iPhone. The Android solution can be uploaded to Nightscout, with Loop using Nightscout as a Remote CGM; but this requires internet access to continue closed-loop performance.

Part of the problem with Libre sensors is that there are differences in region, type and \"security generations\" which makes it hard to account for all variants. For example, the Libre 2 US has a different \"security generation\" than European Libre 2 sensors (different encryption in the data transmitted over bluetooth).

Libre 3 sensors have started appearing as well, but are unsupported. Other Libre sensors that are unsupported: Libre Pro, Libre H, Libre Sense Glucose Sport Biosensors.

"},{"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. Cuustomization instructions are provided at the Loop and Learn website: Libre Support for Loop 3.2.x that explain how to modify Loop 3 to use one of those apps for Browser Build. The Mac instructions are found on the same page. 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 a direct Bluetooth connection.

The xDrip4iOS app (which can also be found in the app store under the name Shuggah) may have a problem during the warmup of a new sensor (European Libre 2 using a 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 a 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 CGM Types, you first delete your existing CGM selection 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.

"},{"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?.

With the Dexcom G7, 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 4 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/#steps-for-dana-i-danars-v3-coming-soon","title":"Steps for Dana-i / DanaRS-v3 (Coming soon)","text":""},{"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 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":"

No Need to Set the Time

If you just added a battery to a Medtronic pump you have not used for a while, the pump initiation screens require you to set the date and time for the pump. You can just accept the default values; when you connect the pump to the Loop app, the time and date are automatically set.

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 an 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
    • Note that the Orange Link battery drain is substantial
      • Some users reported batteries needed to be changed every 2-4 days compared to 10 days with MySentry off

The Medtronic status and commands available are shown in the Pump Settings page.

"},{"location":"loop-3/add-pump/#dana-i-danars-v3","title":"Dana-i / DanaRS-v3","text":"

Coming Soon

The Dana pump is not part of the released code yet. But the plug-in feature of Loop makes adding it extremely easy.

If you want to test the Dana before it added to Loop, please join the discussion of this pump in zulipchat: Dana Discussion

Support for Dana-i

All versions of the Dana-i are supported at the moment!

Check your DanaRS version before starting

Only the DanaRS firmware v3.0 or higher is supported, every other version is not supported or is untested (The korean versions are untested for example). To check your DanaRS version, please go to \"Analyze\" -> \"Model information\". The version should be at least xxx-3.0.0.

When you select the \"Dana-i/RS\" option, you will be prompted to select your pump model. After this selection, you will get a short description on how the pairing process will work. Then you will get the following menu's:

  1. Select Insulin Type
  2. Select Delivery speed
  3. Prepare your Dana-i / DanaRS-v3 pump
  4. Connect to your Dana-i pump or DanaRS-v3 pump
  5. (Optional): Enable silent pump tones
  6. (Optional): Check if you need a heartbeat

"},{"location":"loop-3/add-pump/#delivery-speed","title":"Delivery speed","text":"

IMPORTANT

The delivery speed can always be changed in the pump's settings, but you can only have one delivery speed active

The Dana pumps supports several bolus/delivery speeds. This might be interesting to customize if you want to slow down the bolus speed for insulin types that feel like it is burning. Dana supports 3 speeds:

"},{"location":"loop-3/add-pump/#prepare-dana-idanars-v3","title":"Prepare Dana-i/DanaRS-v3","text":"

Start by checking the device name at the back of your Dana (or inside the \"Model information\" menu). This is a 10 character code, which is listed behind the SN. The example below is from a Dana-i, but is the same for every Dana pump

After you have done the Insulin Type and Delivery speed, you will land on the Dana scanning page. This page will show all the Dana pumps it could find in your area. Once you see your device name in the list, click on it and Loop will try to connect to your Dana-i / DanaRS-v3.

"},{"location":"loop-3/add-pump/#pairing-dana-i","title":"Pairing Dana-i","text":"

Once connected, your Dana-i will prompt you with a question if you want to connect. Accept this and you will see a code on your Dana-i. Meanwhile, you will see the standard iOS Bluetooth pairing modal. Also accept this and fill in the code from your pump into iOS. After that is done, Loop is ready to use your Dana-i!

"},{"location":"loop-3/add-pump/#pairing-danars-v3","title":"Pairing DanaRS-v3","text":"

Once you see your device name in the list, click on it and Loop will try to connect to your DanaRS-v3.

Once connected, your DanaRS-v3 will prompt you with a question if you want to connect. Accept this and you will see two codes on your DanaRS-v3. Meanwhile, you will see a prompt for 2 codes in Loop. Fill in the codes from your pump into iOS and Loop is ready to use your DanaRS-v3!

"},{"location":"loop-3/add-pump/#optional-enable-silent-pump-tones","title":"(Optional) Enable silent pump tones","text":"

Normally, a Dana pump will make a sound or a vibration every time a bolus is completed. When Loop is configured with Automatic bolus, it might be anoying to have a beep or a vibration for every micro bolus. Therefore, we strongly recommend user to enable the silent tones.

Sadly, only the Dana distributors know how to enable this feature at the moment. But we do know you need to set your alarm to sound. You can do this via: \"Settings\" -> \"User options\" -> \"4. Alarm\"

"},{"location":"loop-3/add-pump/#optional-check-if-you-need-a-heartbeat","title":"(Optional) Check if you need a heartbeat","text":"

Most CGM provide a live Bluetooth connection, which the Loop app uses as a heartbeat to wake the app with each CGM reading. Without a heartbeat, the Loop app will not run the algorithm when the app is in the background or the phone is locked.

Some pumps can also provide a heartbeat if the CGM you choose cannot provide one.

DanaKit doesn't provide a heartbeat by default.

Therefore, it is important to check if your CGM provides a heartbeat. If it does not, there are battery-intensive work-around methods for Dana pump. See Dana Heartbeat Modes.

"},{"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.

"},{"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.

Why is my Prediction so High?

New Loopers are often concerned when they bolus for a meal and Loop then reduces basal and predicts a high future glucose.

That prediction is what would happen if Loop took no further action (or if you walked away from your phone). Loop suggests a bolus for that meal that keeps near-term glucose above your Glucose Safety Limit. As the food is absorbed and glucose rises, Loop will provide additional insulin. The automated part of this waits until your actual glucose is above the low-end of your correction range. But you can manually bolus earlier, or set an override for a few hours with a lower correction range.

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.

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 that are included in the Loop glucose prediction. The GIF below illustrates how the graph is changed by turning off one component of the prediction.

Below the chart you will see an explanation of the variables Loop takes into account in predicting your future glucose value. For more information about each effect, click on one of the links below:

You can tap on any of the entries to see the effects of that component by looking at the dashed lines. The last item, Suspension of Insulin Delivery, is new and was added to assist people wondering how long can they safely delay changing a site or suspending a pump.

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.

Algorithm Experiments

Algorithm Experiments is a feature added with version 3.4. One of the items available is Integral Retrospective Correction (IRC). When you have this enabled, the Predicted Glucose Chart displays the retrospective and integral retrospective components as shown on the graphic above. When this is disabled, (the default setting), only the retrospective component is calculated and used.

The example above illustrates a time when having IRC enabled helped Loop to \"put on the breaks\" earlier, leading to a soft landing in the target range. IRC is often advertised as helping \"stuck on high\", but can also assist when glucose is dropping faster than the model (without IRC) would expect.

"},{"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 No Insulin 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. The No Pod 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. The Insulin Suspended 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. The Manual Bolus 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. The No Data alert message indicates it has been more than 15 minutes since the app was able to communicate with the pump.Follow these troubleshooting steps. The Add Pump alert message indicates no pump has been added. Follow the instruction for adding a pump. The Finish Setup alert indicates the pod setup procedure was not completed. Tap on the icon to be taken to the Omnipod menu to complete the setup.(If your icon says Finish Pairing, you are running older code and will be taken to the Insert Cannula screen even if pod is still priming. Make sure priming completes before trying to insert the cannula)."},{"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 found on your Pump screen:

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/#new-with-loop-3","title":"New with Loop 3","text":"

This page discusses some features new with Loop 3.

"},{"location":"loop-3/features/#remote-carb-bolus","title":"Remote Carb / Bolus","text":"

Loop 3 has a Remote Carb and Remote Bolus feature to enable remote caregivers to better assist the person who needs support managing with Loop. This requires the Loop user have a Nightscout site. Please review these pages:

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 links listed above before getting started.

Be aware:

"},{"location":"loop-3/features/#new-with-loop-340","title":"New with Loop 3.4.0","text":"

Additional details about the 3.4.0 release are found here: Version: Releases: 3.4.0

"},{"location":"loop-3/features/#algorithm-experiments","title":"Algorithm Experiments","text":"

Two algorithm experiments are now available in the Loop app (version 3.4.0 or later). These are Glucose Based Partial Application and Integral 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":"loop-3/features/#glucose-based-partial-application-gbpa","title":"Glucose Based Partial Application (GBPA)","text":"Do you want to know more? (Click to open/close)

Glucose Based Partial Application is only used when Automatic Bolus (AB) is selected for Temp Basal Only Dosing Strategy

When AB is selected and GBPA is enabled, the percentage of the recommended dose delivered per Loop cycle 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.)

"},{"location":"loop-3/features/#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.

When Dosing Strategy is set to Temp Basal Only , Loop 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, acheiving the full 1 U (for this example).

"},{"location":"loop-3/features/#integral-retrospective-correction-irc","title":"Integral Retrospective Correction (IRC)","text":"Do you want to know more? (Click to open/close)

The IRC term is described in this (updated) comment in Loop Issue 695 which includes 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 for RC and IRC, examine these files found in LoopKit/LoopKit:

Integral Retrospective Correction, when enabled:

Refering to the Algorithm: Prediction page:

\\[ BG[t] = Insulin[t] + Carb[t] + RetrospectiveCorrection[t] + Momentum[t] \\] \\[ BG[t] = Insulin[t] + Carb[t] + IntegralRetrospectiveCorrection[t] + Momentum[t] \\]

Note that the Momemtum 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 lower blue rectangle, is the difference between the IRC and RC calculations.

"},{"location":"loop-3/features/#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 due to 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 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 standard Loop; at the wake-up time blood glucose should in general be closer to the correction range.
"},{"location":"loop-3/features/#favorite-foods","title":"Favorite Foods","text":"

This feature allows you to save Favorite Foods.

A new row on the Loop app Settings screen, see graphic below, provides access to create and edit your Favorite 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.

Note that to create a Favorite Food on the Carb Entry screen, an icon must be selected by typing on the plate icon and choosing one of the specific food emoji icons. The standard Lollipop, Taco, Pizza icons can be selected at that level, but choosing them at the top level is not sufficient to enable the Save as Favorite button. The favorite food examples seen in the graphic above were created in the Favorite Foods Settings row. The taco was chosen to go with the absorption time chosen.

"},{"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/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: Change Pump Type.

"},{"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/#new-slider","title":"New Slider","text":"

The Insert Cannula and Deactivate Pod now use a Slider instead of a Button

For version 3.4.x and later there is a new slider to control insertion of the cannula and deactivation of a pod.

The slider looks like the graphic below. (The Deactivate Pod slider is red.) You place your finger on the dark circular icon and, while keeping your finger in contact with the screen, drag all the way to the other side. (The direction depends on the natural direction for your selected language). 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. There are two versions of the screen below.

"},{"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-display","title":"Pod Display","text":"

The next section on the Pod screen reports:

The graphic below shows version 3.2.3 and earlier on the left with version 3.4 and later on the right.

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/#pod-details","title":"Pod Details","text":"

Some additional details for 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/#previous-pod-details","title":"Previous Pod Details","text":"

When you tap on the Previous Pod Details row, a graphic similar to those shown below is displayed. This provides summary information about the pod before the one currently in use. If you are running version 3.2.3 or earlier, this row is at the very bottom of the Omnipod screen.

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.

"},{"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/#silence-pod","title":"Silence Pod","text":"

The Silence Pod feature is new with version 3.4.x. This allows a user to tap on silence pod to prevent any noises from the pod, other than critical faults.

What Silence Pod will not do:

When would you use Silence Pod:

Caveats:

The graphic below shows the Silence Pod control. This is only available for v3.4.x and later.

"},{"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/#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 use the slider to 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 sliding to Deactivate Pod. You can then view the Fault information in the Previous Pod Details screen.

"},{"location":"loop-3/omnipod/#updates-with-version-34x","title":"Updates with Version 3.4.x","text":"

The updates included with version 3.4.x make it easier to find the pod fault, should one occur.

The fault will appear on the Omnipod screen and more details will be shown when you tap on Replace Pod to arrive at the Deactivate screen. You can grab a quick screenshot on the Deactivate screen if desired. If there was no pod fault, you will not notice a difference in the version 3.4.x display compared to version 3.2.3.

The fault information can still be found under Previous Pod Details if you need to find it after you Deactivate the \"screaming\" pod.

"},{"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.

Screens

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

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

"},{"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/rileylink/","title":"RileyLink Display","text":""},{"location":"loop-3/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":"loop-3/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

"},{"location":"loop-3/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.

"},{"location":"loop-3/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.

"},{"location":"loop-3/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:

"},{"location":"loop-3/services/","title":"Optional: Services","text":""},{"location":"loop-3/services/#services-for-the-loop-app","title":"Services for the Loop App","text":"

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. For more information, see Nightscout Overview. 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).

"},{"location":"loop-3/services/#nightscout-login","title":"Nightscout Login","text":"

The graphic below shows the steps needed to add your Nightscout site to the Loop app. See the tip below about using stored passwords on the phone. If you have your credentials stored in passwords, simply tap the URL row to show the password option and select it.

  1. Select Settings in the Loop app and scroll down to Services and tap the Add Service Row
  2. Choose Nightscout Service
  3. Tap on the URL row
    • If your credentials are not saved in your Passwords, enter the URL including https:// in this row
  4. This step has two options:
    • If your credentials are saved in Passwords, tap on the Passwords icon and select them
    • Both the URL and API_SECRET will be filled in from your Passwords
    • Otherwise, manually fill in the API_SECRET row
  5. Tap on Login to add this site

The Loop app will begin uploading your data from this point on - it does not back-fill old data to the Nightscout site.

However, if there is a temporary outage of internet service or if the Nightscout site stops working temporarily, the Loop app will fill in all data not uploaded during the outage up to a total of 7 days worth of data.

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.

Do not block your Nightscout site

Add a Password

To make it easy to access your Nightscout URL and API_SECRET, add a password to your iPhone:

  1. iOS Settings, Password
  2. Tap + to add
    • Enter a name, e.g., \"Nightscout\" in the Title row
    • Enter the URL without the \"https://\" in the Website row
    • Enter the URL including the \"https://\" in the User Name row
    • Enter the API_SECRET in the password row
  3. If you use tokens, you can add those in the Notes section - they will be hidden behind the authentication for the passwords
"},{"location":"loop-3/services/#nightscout-logout","title":"Nightscout Logout","text":"

If you want to stop uploading to a given Nightscout site or change to a different Nightscout site, you must first logout. You can then login again at the new site.

The graphic below indicates how to remove your Nightscout site from the Loop app. This will stop future uploads from the Loop app to that site.

"},{"location":"loop-3/services/#tidepool","title":"Tidepool","text":"

Data can be directly uploaded from Loop to Tidepool by adding it as a Service.

Please refer to the LoopTips: Data: Tidepool page for more information about Tidepool.

When you add the Tidepool Service to Loop, be sure to disable Tidepool Mobile ability to read from Apple Health.

Double entries

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.

Even when you turn off the access to Health on the Tidepool Mobile app when you turn on Loop Tidepool service, you will still get 7 days of overlap because Loop stores 7 days of data.

There is a filter button on the Tidepool Website you can use to separate the two data sources.

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. 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. This page 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 is reached by tapping the gear icon in the Toolbar on the Main Loop Screen. The graphic below is for Loop 3.4 and later versions.

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.

"},{"location":"loop-3/settings/#temp-basal-only","title":"Temp Basal Only","text":"

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.

With Loop 3.4.0 and later versions, you have the option of using Automatic Bolus with Glucose Based Partial Application (GBPA). This feature is reached through the Algorithm Experiments row of the Settings screen. It modifies the percentage of the recommended dose that is supplied with each Loop cycle. Instead of being a fixed 40%, it changes from 20% when glucose is near your selected Correction Range and gradually increases to 80% when glucose reaches 200 mg/dL (11.1 mmol/L).

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/#alert-management","title":"Alert Management","text":"

This row enables the user to modify Alert Permissions and to enable Missed Meal Notifications.

"},{"location":"loop-3/settings/#missed-meal-notifications","title":"Missed Meal Notifications","text":"

Loop detects situations where glucose excursions indicate you may have consumed carbs but did not enter them into Loop. When Missed Meal Notifications are enabled, you will be provided an alert that suggests when the meal was consumed and how many carbs are already absorbed at the time of the alert. You have the option to increase the grams of carbs to match your actual meal.

"},{"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/#algorithm-experiments","title":"Algorithm Experiments","text":"

The Algorithm Experiments are new with Loop 3.4 and we recommend you review the details on the Features new with Loop 3 page. Many people have tested these and like them, but you need to decide whether to enable them.

"},{"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/#favorite-foods","title":"Favorite Foods","text":"

Favorite Foods, new with Loop 3.4, can simplify meal entry if you choose to use it. You can create a Favorite Food here or on the Carb Entry screen.

Note that to create a Favorite Food on the Carb Entry screen, an icon must be selected by typing on the plate icon and then choosing a food emoji. The standard Lollipop, Taco, Pizza icons selected from the top level are not sufficient to enable the Save as Favorite button.

"},{"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 is similar to what you see when you scroll down to the Support section of the Loop 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.

"},{"location":"loop-3/settings/#when-not-to-submit-a-bug-report","title":"When Not to Submit a Bug Report","text":"

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/#testflight-or-app-profile","title":"TestFlight or App Profile","text":"

At the bottom of the Settings display is a section labeled either TestFlight or App Profile. This provides the number of days remaining before the Loop app stops working along with the date and time at which the \"Loop\" is No Longer Available or \"Loop\" Beta has Expired message appears and the refuses to open. (Prior to Loop 3.4, the TestFlight warning was available only in dev.)

The link for How to update (LoopDocs) is provided for Build with Browser or Build with Mac as appropriate.

In fine print, the date and time of the expiration is reported in your local time zone. The Loop app installed from TestFlight might last a day longer than the Loop app reports - this is a conservative estimate. The time reported in the TestFlight app is correct.

"},{"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 dropdown 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; Loop Caregiver, 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 your Nightscout site according to the directions here in\u00a0Loopdocs\u00a0in 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
  • If you changed your Loop build method (between Mac Build and Browser Build) - don't forget the extra Config Var
  • You site must be authenticated so that your \u00a0Careportal\u00a0is active to send remote overrides from the website

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 to the bottom of the event type menu. Refer to Command Remote Bolus or Carb Entry for more instructions and a graphic.

Please note that there are entries that do not say remote at the top of the list.

  • You must go all the way to the bottom of the list to see the remote commands
  • Those entries at the top of the list are for caregivers who may be recording manual treatments without access to an automated system; they are not read by the Loop app
  • For users of systems based on OpenAPS, the behavior may be different - check the documentation for your particular app
"},{"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 as shown in the graphic below

  • 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/#start-and-end-remote-override","title":"Start and End Remote Override","text":"

Starting or ending a remote override does not require a One-Time Password.

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/#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 the 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 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 \u2018caregiver\u2019 below refer to the person sending the commands. 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 the caregiver\u2019s device.
    • If the clock is incorrect, even slightly, remote commands will fail.
  • Check if One-Time Passwords (OTP) align between Loop Caregiver and\u00a0Loop.
    • In\u00a0Loop: Settings -> Services -> Nightscout
    • In Loop Caregiver : Settings -> Tap on Looper's Name
    • Observe the 6-digit OTP as they change
  • If the OTPs 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 may not always reach your app due to various settings or Apple's intentional limitations. This issue can manifest in several ways:

  • The push notification banner never appears on the Looper\u2019s device.
  • The push notification banner appears, but nothing happens in\u00a0Loop\u00a0(no error or success message afterward).
  • An error message in Nightscout or Loop Caregiver indicates the Password (OTP) is expired.

While\u00a0Loop\u00a0cannot control the timely delivery of push notifications, there are several steps you can take to mitigate these issues. Note that rebuilding\u00a0Loop\u00a0or Loop Caregiver generally will not resolve the problem.

Check these items on the Looper\u2019s phone, not the caregiver's.

  1. Reboot the phone.
  2. Wait 24 hours as it often takes time for the push notification limits to reset.
  3. Limit the number of\u00a0Loop\u00a0commands you send in a short period.
    • Apple may throttle notifications if too many are received.
    • Sending no more than 1 or 2 per hour may help.
  4. Disable notifications from other apps.
    • It is possible that other apps can cause the system to throttle all notifications, including\u00a0Loop.
  5. Enable Time Sensitive Notifications:
    • Apple Settings -> Notifications ->\u00a0Loop.
    • Turn on \u201cAllow Notifications\u201d.
    • Turn on \u201cTime Sensitive Notifications\u201d.
  6. Upgrade Nightscout:
    • Nightscout version 15.0 (released late 2023) and greater supports time sensitive notifications.
    • This can help iOS to deliver remote notifications faster.
  7. Adjust Focus Modes:
    • For all focus modes, make sure\u00a0Loop\u00a0is listed as an app allowing Notifications.
    • Apple Settings -> Focus
    • Select the focus mode (e.g., Do Not Disturb, Sleep).
    • Under \u201cAllow Notifications,\u201d tap \u201cChoose Apps\u201d.
    • Add\u00a0Loop\u00a0to the list.
  8. Turn on Background App Refresh:
    • Apple Settings -> General -> Background App Refresh
    • Select \u201cOn\u201d at the top.
    • Activate the\u00a0Loop\u00a0toggle in the list.
  9. Try using Wi-Fi instead of cellular if possible:
    • Apple may not deliver notifications on cellular as often as on Wi-Fi.
  10. Charge the phone:
    • If the battery is low, iOS may not deliver notifications to save battery life (e.g., while on Low Power mode).
"},{"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?
    • In both Nightscout and Caregiver, you can tap on an error to read specific error details.
    • Share screenshots of errors
  4. What\u00a0Loop\u00a0version are you using? Released (main) or development (dev)? Approximately when did you update last?
    • The minimum version that supports remote bolus and carbs is\u00a0Loop.
  5. What iOS version is being used on the Looper\u2019s device?
  6. How did you build\u00a0Loop?
    • Web browser using GitHub Actions?
    • Xcode?
    • AppCenter or Diawi? 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/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 formula 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 Insulin Model Customization 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, as set in the ISF schedule in therapy settings or in accordance with any overrides. Loop uses the ISF that applied at the time of an insulin dose to predict the expected change in blood glucose due to the insulin effect, and sums the effect from all still-active doses.

"},{"location":"operation/algorithm/prediction/#expected-change-in-blood-glucose-for-each-loop-interval","title":"Expected Change in Blood Glucose for Each Loop Interval","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.

The insulin effect for a given dose can be expressed mathematically:

\\[ \\Delta BG_{dose}[t] = ISF[t_{dose}] \\times IA_{dose}[t] \\]

where \\(\\Delta BG_{I}\\) is the expected change in blood glucose due to insulin with the units (mg/dL/5min), ISF is the insulin sensitivity factor (mg/dL/U) at the time of the relevant dose, 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 insulin in the blood as it acts on glucose. Insulin activity explicitly accounts for active insulin from temporary basals and boluses, and implicitly accounts for scheduled basal which is assumed to balance out with EGP.

"},{"location":"operation/algorithm/prediction/#insulin-effect-on-blood-glucose-over-time","title":"Insulin Effect on Blood Glucose Over Time","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/#treatment-of-scheduled-basal-rates","title":"Treatment of 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-active-insulin-combining-boluses-and-temporary-basal-rates","title":"Total Active Insulin (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.

The active insulin taking into account boluses and variations from scheduled basal basal rates are visually represented for the user by Loop\u2019s insulin charts:

"},{"location":"operation/algorithm/prediction/#total-insulin-effect-combining-boluses-and-temporary-basal-rates","title":"Total Insulin Effect (combining boluses and temporary basal rates)","text":"

The sum of all doses' effects on blood glucose are shown for the user in the 'Insulin' curve in the predicted glucose screen.

The total insulin effect at time t is the sum of effects from each active dose or temporary basal rate:

\\[ \\Delta BG_{I}[t] = \\sum_{dose=1}^{n} \\Delta BG_{dose}[t] \\]"},{"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] = \\Delta BG_{O}[t] - \\Delta BG_{I}[t] \\]

where, ICE (mg/dL/5 min) is the insulin counteraction effect, \\(\\Delta BG_{O}\\) is the observed change in blood glucose (mg/dL/5min) at time t, and \\(\\Delta BG_{I}\\) is the modelled change in blood glucose due to insulin alone (i.e. the insulin effect as described above 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 both the carbohydrate-to-insulin ratio and the insulin sensitivity factor that were current at the time of a recorded meal entry.

\\[ AC[t] = ICE[t] \\times \\frac{CIR[t_{meal}]}{ISF[t_{meal}]} \\]

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) at the time of the relevant meal entry, and ISF is the insulin sensitivity factor (mg/dL/U) at the time of the relevant meal entry.

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 dynamically-estimated carbohydrate absorption of a meal entry up to the current time t 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_{meal}]}{CIR[t_{meal}]} \\]"},{"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/#integral-retrospective-correction-effect","title":"Integral Retrospective Correction Effect","text":"

The integral retrospective correction effect allows the Loop algorithm to account for longer term effects that are not modeled with the insulin and carbohydrate effects, by comparing historical predictions to the actual blood glucose.

When Integral Retrospective Correction (IRC) is enabled in settings under Algorithm Experiments, this replaces the Retrospective Correction (RC).

  • When IRC is enabled the equation in Blood Glucose Prediction is modifed to:
\\[ BG[t] = Insulin[t] + Carb[t] + IntegralRetrospectiveCorrection[t] + Momentum[t] \\]

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 lower blue rectangle, is the difference between the IRC and RC calculations.

"},{"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 \\(\\Delta BG\\) over the time interval \\([t_{5}, 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/#updates-with-version-3-and-later","title":"Updates with version 3 and later","text":"
  • 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.

Avoid Double Entry of Carbohydrates

Carbohydrates are saved when the Save and Bolus or Save without Bolusing button is tapped in the Meal Bolus Screen. Once that the button is tapped, carbohydrates are saved. That is true even if the bolus does not go through to the pump.

If you see a notification after saving a carbohydrate entry, check carbohydrates entries in the Loop app. Do not just add the entry again without checking.

"},{"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.

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/carbs/","title":"Meal Entries","text":""},{"location":"operation/features/carbs/#meal-entry","title":"Meal Entry","text":""},{"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
  • Absorption Time: values for fast, medium and slow
    • Loop 3 uses 30 minutes, 3 hr, 5 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/#new-with-version-34x","title":"New with Version 3.4.x","text":"

The Favorite Foods feature was added with version 3.4.x. This is an even faster way to enter meals than is described in the next section, Meal Entry - Fast Version.

The graphic in the link above was taken from my Favorite Foods screen. Subsequent to that screen shot, I've renamed Medium to Lunch and Large to Dinner. Note this is a personal solution that works for me; you need to modify your settings to work for you.

For each meal I select Lunch or Dinner, save and accept the bolus.

  • If I know I will be eating less than usual (not often), I will edit the carb amount before saving
  • If I know I will be eating more than usual, my typical approach is:
    • Accept the normal amount when I prebolus
    • When I sit down to eat, I increase the carb amount by multiples of 15 g, depending on the situation
  • I use the fat-protein rise selection but advance the time to 4 hours after dinner
"},{"location":"operation/features/carbs/#meal-entry-fast-version","title":"Meal Entry - Fast Version","text":"

Favorite Foods is even faster

With version 3.4.x and later, you have access to the Favorite Foods feature. This can make meal entry even faster than this Fast Version section below.

  • See New with Version 3.4.x section above for an example use of this feature

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.

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

Carbohydrates are saved when the Save and Bolus or Save without Bolusing button is tapped in the Meal Bolus Screen. Once that the button is tapped, carbohydrates are saved. That is true even if the bolus does not go through to the pump.

If you see a notification after saving a carbohydrate entry, check carbohydrates entries in the Loop app. Do not just add the entry again without checking.

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

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 Displays: Active Carbohydrate Chart 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/#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/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 positive 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. This will be a combination of dynamically-estimated carb absorption (where meals are absorbing faster than Loop's conservative estimate based on your carb entries) and static absorption based on Loop's conservative, minimum-absorption-rate estimate.

  • \ud83d\udfe9: The green bars represent the observed change in blood glucose compared to Loop's prediction based on insulin alone (or 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).

    Loop falls back to a default absorption model when the total ICE for a meal up to the current time 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 observed glucose change. For example, if you overestimated the amount of carbs in a meal, the meal absorbs slower than you estimated, or exercise leads to less insulin needs than normal, the grey bars predicted at the start of a meal 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":""},{"location":"operation/features/notifications/#expiration-on-settings-screen","title":"Expiration on Settings Screen","text":"

At any time, you can tap on Settings and scroll to the bottom of the screen to see when your app will expire.

The graphic below shows the Settings display for a TestFlight build (version 3.3 or newer):

"},{"location":"operation/features/notifications/#expiration-alert","title":"Expiration Alert","text":"

Notification before an app expires is reported using this protocol:

  • When fewer than 20 days remain, you'll get an alert when you open the app but no more frequently than every 2 days
  • When fewer than 24 hours remain, you'll get an alert when you open the app, once every hour at most
  • Simply tap on the More Info button of the alert for more information
    • Build with Mac: Update/Rebuild with Mac
    • Build with Browser: Update/Rebuild with Browser

The graphic below show an example expiration alert for a Mac build:

Notification when app expires is available in these versions or newer:

  • Build with Mac: version 2.2.5 or newer
  • Build with Browser: version 3.3 or newer
"},{"location":"operation/features/notifications/#free-7-day-loop-app-expiration-alert","title":"Free (7-day) Loop App Expiration Alert","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/#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.

Remember: Carbs are saved when you tap Save and Bolus following a meal entry - even if the bolus fails.

"},{"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. You can extend the duration or modify the needs value or target value based on a temporary situation.

When you edit Overall Insulin Needs, then the Loop app recalculates some effects, such as IOB, over the duration of the override and if you also quit and restart the app, it recalculates all effects. See Recalculate When Needs Change for more information.

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/#recalculate-when-needs-change","title":"Recalculate When Needs Change","text":"

Here's a cool tip for more advanced users. Suppose you have an override running but you realize your overall insulin needs percent wasn't quite right. You can edit the override and force the Loop app to recalculate the effect from the beginning of the override. A change in IOB may show up immediately when you edit insulin needs in the override. If you also quit and restart the app, this forces a recalculation from the beginning of the override.

This is demonstrated in the following set of graphics contributed by a user - note the change in the ICE graph for carbohydrates absorbed - this requires you to quit and restart the Loop app. These examples use extreme modifications to illustrate what happens - typically the modification of insulin needs would be much smaller.

The first graphic is where the Overall Insulin need value was dramatically decreased (user much more sensitive).

The second graphic is where the Overall Insulin need value was dramatically increased (user much less sensitive).

Example

I set my biking override to be longer than my expected ride. When I return, I edit the insulin needs from 65% (needed while I'm actively biking) back to 100%. My negative IOB typically doubles at that change. I then disable the override and take the full negative IOB as a bolus. This helps prevents a post-exercise high that often follows my ride.

I do not enter any carbs while biking and almost always ride first thing in the morning while fasting, so i just edit the override. If no carbohydrates are active, there is not need to quit and restart the app.

"},{"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":"
  • 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
"},{"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:

  • You can delete the setting to deactivate the icon

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/#widgets","title":"Widgets","text":"

The Loop app uses the new-style widgets. With the advent of iOS 16 and 17, you can add widgets that show up on the lock screen without need to swipe to view. But only some widgets can do this and there is very limited space for those lock screen widgets. You can add more widgets to the Today View, where you do need to swipe right from the Home View or Lock Screen.

The example graphic below shows the Loop widget on the top row, with the LoopCaregiver widget next to a Scriptable widget that is fed from my Nightscout site on the middle row. Below that is the Dexcom G7 widget next to a weather widget. This Today View requires a swipe right from the Lock Screen or the Home screen. The scriptable widget is also on my lock screen. The update rate for these widgets is similar to watch complications, some will grey out when stale. If they are greyed out, tap on them to go to the app directly.

The Scriptable widget includes the time of the last update, 11:25 am, so is 11 minutes old at the current time of 11:36 am.

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 used a different method to install and should be removed from your screen
  • 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.
"},{"location":"operation/features/widget/#old-style-loop-widget","title":"Old-Style Loop Widget","text":"

Leave this here so you can see if you have an old-style widget.

With newer versions of iOS, the old-style widgets cannot be moved to the top of the screen. Please convert to the new-style widgets.

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.

"},{"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":"

Avoid Double Entry of Carbohydrates

Carbohydrates are saved when the Save and Bolus or Save without Bolusing button is tapped in the Meal Bolus Screen. Once that the button is tapped, carbohydrates are saved. That is true even if the bolus does not go through to the pump.

If you see a notification after saving a carbohydrate entry, check carbohydrates entries in the Loop app. Do not just add the entry again without checking.

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":"troubleshooting/dana-heartbeat/","title":"Dana Heartbeat","text":""},{"location":"troubleshooting/dana-heartbeat/#danars-v3-i-heartbeat-modes","title":"Dana(RS-v3 / -i) heartbeat modes","text":"

Please read the full page and only activate this if truly needed

Enabling this feature will put a big load on your iPhone's battery or your pump's battery. Therefore, only use it if your sensor doesn't provide a heartbeat, i.e. the NightScout remote CGM, Dexcom Share, etc

Danakit provides two ways to enable a heartbeat:

  • Background sound
  • Continuous Bluetooth mode
"},{"location":"troubleshooting/dana-heartbeat/#which-mode-to-choose","title":"Which mode to choose?","text":"

You should choose Background sound when:

  • You prefer a higher phone battery drain over a higher pump battery drain
  • You are able to change the permission of the Loop app in Xcode or change the Github action build step

You should choose Continuous Bluetooth mode when:

  • You prefer a higher pump battery drain over a higher phone battery drain
  • You are aware that the pump's UI will be blocked 24/7 unless you: disconnect in the Loop app, kill the Loop app, or disable bluetooth on your phone
"},{"location":"troubleshooting/dana-heartbeat/#background-sound","title":"Background sound","text":"

An extra feature available for the Dana pumps is the background sound. This feature was developed in order to keep the Loop app running in the background.

Normally, your CGM will have an active Bluetooth connection, which prevent the Loop app from being put into a suspended state. But when you are planning on using a CGM, like NightScout remote CGM, Dexcom Share, etc, you rely on a active internet connection, and not on an active Bluetooth connection.

In order to activate, follow these steps:

  1. Activate the UIBackgroundMode - audio:

    • When building with Mac, go to the LoopWorkspace Xcode project and select the Loop project. Go to \"Targets\" -> \"Loop\" -> \"Signing & Capabilities\" and scroll down to \"Background modes\". Enable the checkbox for \"Audio, AirPlay, and Picture in Picture\". Then rebuild the app and go to step 2.

    • When building with Browser, you will need to make a change to the GitHub Actions workflow. Go to your LoopWorkspace fork on GitHub and press . on your keyboard. You will be redirected to a github.dev page with the code of your LoopWorkspace. Now go to \".github\" -> \"workflows\" -> \"build_loop.yml\". Scroll down till you see the - name: Fastlane Build & Archive command. Just before this command, add the following to this script (example):

    - name: Update entitlement background sound\n  run: sed -i -e 's/<string>bluetooth-central<\\/string>/<string>bluetooth-central<\\/string><string>audio<\\/string>/g' Loop/Loop/Info.plist\n
    • To save your changes to the \"build_loop.yml\", go to the Source Control tab on the left (should show up with a blue 1, see image below). Enter a message and press the green \"Commit & Push\"-button. By pressing this button, GitHub will automatically make a new browser build for you and push it to TestFlight

  2. After you have done the onboarding of the pump (see steps above), go to the pump settings. Scroll down the \"Pump name\" and long-press this row. A modal should pop-up with the question, whether you want to toggle Silent tones.

    In order to activate this feature, the modal should say something like: Yes, Enable silent tones. When it says: Yes, Disable silent tones, it will disable the background sounds.

  3. Done! Every time you put the Loop app in the background, it will play a toneless sound, which prevents it from suspending the Loop app

"},{"location":"troubleshooting/dana-heartbeat/#continuous-bluetooth-mode","title":"Continuous bluetooth mode","text":"

This mode replicates how a CGM works: it keeps the bluetooth connection open even though no command's are being executed. Like stated before, this will drain your pump's battery more than usual.

"},{"location":"troubleshooting/dana-heartbeat/#how-to-unblock-the-pumps-ui","title":"How to unblock the pump's UI","text":"

If you want to replace the reservoir or want to interact with the pump's UI, you have three options to temporary disable Continuous bluetooth mode:

  • Disable bluetooth on your phone (not recommended)
  • Kill the Loop app (not recommended)
  • Using the disconnect feature (recommended)

To use the disconnect feature, go to the Dana pump settings and use the Disconnect from pump button. You will get prompt to set a notification reminder. This reminder will be sent to you if you haven't reconnected the pump within the given time. This feature is fully optional, but is recommended.

"},{"location":"troubleshooting/dana-heartbeat/#how-to-enable-continuous-bluetooth-mode","title":"How to enable Continuous bluetooth mode","text":"

Now that you know what the risks are of this feature and how to unblock the pump's UI, can we talk about enabling the feature. Go to the Dana settings and long press the Firmware version row. You will be prompted to enable or disable the feature, choose Yes, Switch to continuous mode and the feature has been enabled!

"},{"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":"

Update to version 3.4 as soon as possible. The builds will then be automatic. So all you will need to do in install the latest build from TestFlight on your phone.

If you are running an older version, you 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 is supplied with version 3.4.

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

"},{"location":"troubleshooting/pod-pairing/#is-it-the-right-kind-of-pod","title":"Is it the right kind of Pod?","text":"

The DASH pods have a blue needle cap. The Eros (and the Omnipod 5) pods have a clear needle cap. Make sure the pod you are trying to pair is the right type.

"},{"location":"troubleshooting/pod-pairing/#did-the-pod-beep","title":"Did the Pod Beep?","text":"

The instructions from Insulet 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. If you did not hear the pod beep as you filled it - the pod might be defective or you may not have added enough insulin.

Inject slowly

Some users are able to get the pods to beep with smaller amounts by very slowly injecting the insulin.

"},{"location":"troubleshooting/pod-pairing/#verbose-message-hard-to-interpret","title":"Verbose Message, Hard to Interpret","text":"

This is only seen with DASH pods. Sometimes the communication error happens at a very low level and by the time the error message works its way up to the display, it seems to go on for a long time and may not make sense to the typical looper.

If you see a Pairing exception message similar to the one shown in the graphic below, you probably just need to toggle Bluetooth on the phone.

Still not working, read through the Why do pod pairings fail? section.

"},{"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 Loop app will crash while a new pod is being setup. This is rare but can happen. There are several parts to the setup process:

  1. Pair the pod to the app
  2. Prepare for and start to prime the pod
  3. Insert the cannula
"},{"location":"troubleshooting/pod-pairing/#updates-for-version-34","title":"Updates for Version 3.4","text":"

The Omnipod code was upgraded with version 3.4 to be more robust if your Loop app quits, a build is installed or the app is swiped up during pod setup.

There are initial pairing steps: exchange of encryption keys, assign the pod ID and perform a final connection step that must be completed while the app is in contact with the pod. Once those initial commands happen, then the pod can reconnect to the Loop app even if the app quit before priming starts.

  • After the restart, if the main screen indicates Finish Setup in the Pump Status icon, you can continue with that pod
    • Tap on Finish Setup to be taken to the appropriate screen
  • After the restart, if the main screen indicates No Pod in the Pump Status icon then the pod was not fully paired to the app
    • Tap on No Pod and try to Pair Pod
    • If the pod pairs, then the interruption happened before pairing started - you got lucky
    • If you get the message no pod is found, then you are out of luck
      • In this case, move the first pod far away from the phone; you want to avoid the possibility of interference with the new pod
      • Fill a new pod and pair the new pod
      • Once the new pod is operating, be sure to go to the first pod and disable the sound - it will continue beeping until it starts to scream: What do you do to stop a screaming pod?
"},{"location":"troubleshooting/pod-pairing/#behavior-for-version-32x-and-earlier","title":"Behavior for Version 3.2.x and earlier","text":"

For version 3.2.x and earlier, the pod needed to actually begin priming before an interruption occurred or the pod could not be recovered. However, in this case, the user was always directed to the Insert Cannula page whether priming completed or not.

  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 taken to the Insert Cannula screen before the pod is ready
    • Wait 30 seconds after clicking (priming) stops before attempting to insert the cannula
    • Note - it is not a fatal error to try to insert too soon - you will just be informed that the pod is not in the correct state - wait for priming to finish and then retry
  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 first 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":"

There are 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; see Current 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.

Read this page to understand the information you should see on your phone if your RileyLink Device is working properly:

  • RileyLink Display
"},{"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). Before disposing of it, however, be sure to silence it: What do you do to stop a screaming pod?.

"},{"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 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.

If you do need to try another pod. Once the new pod is operating, be sure to go to the first pod and disable the sound - it will continue beeping until it starts to scream: What do you do to stop a screaming pod?

"},{"location":"troubleshooting/pod-pairing/#step-4-check-the-pod-placement","title":"Step 4: Check the Pod Placement","text":""},{"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 Verbose Message, Hard to Interpret Pairing exception message as shown in the link above, 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.

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/#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 are required to set the time and date with each battery change. You can save time by accepting the default values; the Loop app automatically sets the time and date. (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.

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.

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
"},{"location":"troubleshooting/red-loop/#lost-pod-information","title":"Lost Pod Information","text":"

We have not seen this issue since the update of the Loop app from version 2 to version 3 when the method for saving data was updated. Some other applications in the open-source sets of codes might still have this issue. (It was reported in iAPS, for example.) The warning below is left in LoopDocs but if you are running Loop version 3.x.x, you do not need to worry about reboots.

  • 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 iAPS

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 an older version of the Loop app in which power cycling the phone does not load the latest version of saved 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/#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 and later, 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

  2. In addition, with the addition of Focus modes (for iOS 15, 16 and 17), you may need to explicitly allow the Loop app access for notifications for modes such as Sleep, Personal and Do Not Disturb modes.

"},{"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 are 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

Some customizations have not changed for a very long time (stable since 2.2.x days).

It was not until version 3.2.3 that we started adding a notation as to when the required customization code changed.

For those using the Browser Build method:

  • If you had a customization working for 3.2.3 it will continue to work with 3.4.0 unless it is one listed in the Not Stable List
  • However, because the build_loop.yml file is significantly different for version 3.4.0, you will need to save your \"customization lines\" from the build_loop.yml file in the 3.2.3 version of your fork and add them to a new location for the 3.4.0 version of build_loop.yml in your fork
  • If one of your personalized customizations is in the Not Stable List you will need to create a new version Custom Edits with Browser: Code Updates

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: Version #\"

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 3.2.3 and 3.4.x:

  • Changed on 2024 Feb 19: 3.4.0: Glucose Guardrails
  • Changed on 2023 May 29: 3.4.0: 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 the *Loop* app 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 slow 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 (the Loop app 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":""},{"location":"version/code-custom-edits/#glucose-guardrails","title":"Glucose Guardrails","text":"

This code limits the absolute and recommended values for the Glucose Safety Limit and the Correction Ranges. The absolute range cannot be exceeded. The recommended range indicates values that show up as black on the picker wheel. Numbers outside the recommended range are yellow. Numbers at the min or max of the absolute range are displayed as red.

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 3.4.0
"},{"location":"version/code-custom-edits/#version-340","title":"Version 3.4.0","text":"

This update, merged 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/#version-from-323","title":"Version from 3.2.3","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/#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":"

The Loop app limits to 1 hour 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

  • Module: Loop

  • Folder: Loop/Loop/Models
  • File: LoopConstants.swift, Line 28
  • Stable: Changed on 2023 May 29 through 2023 Aug 20: Version 3.4.0
"},{"location":"version/code-custom-edits/#version-340_1","title":"Version 3.4.0","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/#version-from-323_1","title":"Version from 3.2.3","text":"
  • Folder: Loop/Loop/View Controllers
  • File: CarbEntryViewController.swift, Line 438
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))\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.

"},{"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!

  • This customization is provided from code inspection and one test - use with care.
"},{"location":"version/code-custom-edits/#digital-crown-adjustments","title":"Digital Crown Adjustments","text":"

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 51
  • 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 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 the Loop app, 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

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 major features added to dev since Loop 3.4 was released.

Right now it is empty.

"},{"location":"version/development/#updates-from-32-to-34","title":"Updates from 3.2 to 3.4","text":"

Most features, originally in the Updates in dev section before the release of version 3.4, have been inserted into the appropriate part of the LoopDocs website (indicated by the up-right arrow after the link). A few items are still in this section.

  • Support for Libre Sensors
  • Simulated Pump or CGM on Phone
  • Algorithm Experiments
    • Glucose Based Partial Application Factor
    • Integral Retrospective Correction
  • Favorite Foods
  • TestFlight Expiration Warning
  • GitHub Browser Build Updates
  • Miscellaneous Code Fixes
"},{"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.

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.3 users updating to the next release
    • The branches with alive in the name required to enable automatic update and building are created automatically
    • Make sure your GitHub repository is in sync with the LoopKit/LoopWorkspace repository

These sections are still useful for version 3.5.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.5.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, there are other changes later than that commit that 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 the git tool

Older Loop release information is kept for historical reasons:

  • Older Releases: Loop 2 Releases
"},{"location":"version/releases-version2/","title":"Loop 2 and Older","text":""},{"location":"version/releases-version2/#compatibility-between-versions-2-and-3","title":"Compatibility between Versions 2 and 3","text":"

If you are running a much older version of the Loop app, be aware:

  • 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-version2/#loop-2-version-history","title":"Loop 2 Version History","text":""},{"location":"version/releases-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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-version2/#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/releases/","title":"Releases","text":""},{"location":"version/releases/#loop-releases","title":"Loop Releases","text":"

The new features added with each Loop release are provided for reference.

For information about version 2 releases and compatibility between version 2 and 3, refer to Older Releases.

"},{"location":"version/releases/#current-release","title":"Current Release","text":"

The current released version for the Loop app is 3.4.1. 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.

"},{"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-3-version-history","title":"Loop 3 Version History","text":""},{"location":"version/releases/#loop-v341","title":"Loop v3.4.1","text":"

Loop v3.4.1 was released on 19 July 2024.

This was a patch that fixed errors with the Browser Build. No other changes were made.

  • Link to release notes for Loop 3.4.1
"},{"location":"version/releases/#loop-v340","title":"Loop v3.4.0","text":"

Loop v3.4.0 was released on 13 July 2024.

  • Link to release notes for Loop 3.4.0
  • There are some one-time update steps required for those who Build with Browser:
    • Update from 3.2.x to 3.4
"},{"location":"version/releases/#summary-of-important-new-features","title":"Summary of Important New Features","text":"

These features are added:

  • Libre support in the Loop app
  • Favorite Foods for easy entry of common meals
  • Algorithm Experiments:
    • Glucose Based Partial Application for Automatic Bolus corrections
    • Integral Retrospective Correction
  • In app warning when a TestFlight install build is about to expire
  • Omnipod and Nighscout Users: automatic update of CAGE to Nightscout when pod is changed
  • Dexcom and Nighscout Users: automatic update of SAGE to Nightscout when Dexcom sensor is changed
  • Medtronic and Nighscout Users: automatic update of CAGE to Nightscout when set is changed
  • Omnipod Users:
    • Cannula Insertion uses a slider to minimize accidental insertion before pod is attached to the body
    • Pod Deactivate uses a slider to minimize accidental deactivation
    • Pod Set up from Pod Pairing until Cannula is inserted now disables auto-lock of screen
  • Browser Builders:
    • improved error messages and automatic rebuild of app to TestFlight
    • automatic addition of all services except App Group to the App Service for Identifiers
"},{"location":"version/releases/#summary-of-bug-fixes","title":"Summary of Bug Fixes","text":"
  • Widgets:
    • Updated to work with iOS 17
  • Dexcom G7 Users:
    • fixed how one item was read from the G7, this bug caused a rare time discrepancy
  • Omnipod Users:
    • prevent unnecessary faults (rare but it could happen)
    • improve restarts when app is interrupted during pod setup
    • better detection of communication issues
    • improve handling of alerts
  • Fixes for mmol/L users
    • Missed Meal notification calculation is now correct
    • Glucose limits can now use the min or max value with no restrictions
  • Nightscout as a CGM works again for older iOS versions, it no longer requires iOS 17
"},{"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/#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 was the development version before Loop 3.4.0 was released
  • Loop 3.4.0 is the current version
    • Loop 3.5.0 is the current development version
"},{"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, iAPS, 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/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 Sign 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 Sign 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.

"},{"location":"version/simulator/#simulated-pump-or-cgm-on-phone","title":"Simulated Pump or CGM on Phone","text":"

The simulators for the Pump and CGM, with version 3.3 and later, hide their detailed configuration screen. The initial view is a demonstration screen showing a typical CGM or Pump display. In order to configure the simulator controls or delete the simulator, you must tap on the Simulator Settings row.

If you do not see the Simulator Settings row, you have an older version. You can see the settings by doing a long-press (5 to 10 sec) in the top portion of the simulator screen. 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.

"}]} \ No newline at end of file