Code Customizations | Loop and Learn

Customization Select Page – Table of Contents

Customization Overview

In an open-source Do-It-Yourself (DIY) community, there are always requests for code customization instructions.

Some customizations must be personalized while others are the same for everyone (if you want that particular feature). The Loop and Learn Customization Select script provides a subset of frequently requested customizations. This script is suitable for use by people using the Mac-Xcode Build method or the Browser Build method.

Customizations are even more experimental than the released version of Loop. It is your responsibility to understand the changes made to the Loop code when you apply, remove or update one of these customizations.

The Customization Select script automatically determines which customizations are compatible. The menu driven version reports customizations available, applied and incompatible each time the menu is displayed. All customizations are configured to work with either the released code (main) or development code (dev).

Sometimes updates to the dev code require the customization to be modified to maintain compatibility
- When that happens, it may take a few days before the customizations are updated
- In that case, keep using the older versions of dev

What is a script?

A script is a series of commands that are grouped together and issued for you.

Mac-Xcode Builders: the script is run by copying and pasting some text into the terminal window (on a Mac or a virtual Mac on a PC)
Browser Builders: the script is run by copying and pasting some text into a special file used by GitHub during a Build Loop Action

The Customization Select script checks the result of each command and displays a success message and continues or pauses with a warning message if you need to take action. It makes it much easier to configure your Loop app with the customizations that are right for you.

Customization

The list of customizations is shown below.

On the left (with a link leading to more information) is the name seen when menu driven
On the right, in quotes, is the text used to add this customization with the Browser Build method

Please understand the customization and check your build after completion to ensure you have the code you intended. The CustomTypeOne LoopPatches are automatically adjusted to be compatible with Algorithm Experiments customizations that you select. (There are new features in the development branch that replace some of these older LoopPatches.) Please refer to Loop Features in Development for more information about some of the development customizations.

Breaking news:

9 October 2023: Add notification of TestFlight expiration to Browser Build

23 September 2023: Several customization will not be needed with the next release and are no longer compatible with dev

CAGE: Upload Pod Start to Nightscout (main only, already in dev)

SAGE: Upload Dexcom Sensor Start to Nightscout (main only)

13 September 2023: The Profile customization was enhanced with more features. To install this update:

GitHub Browser Build: Once you’ve configured your build_loop.yml, just run a new build to get the latest version

Mac-Xcode: Run the Customization Select Script; if you’ve previously installed it, run the script again to be offered an update

25 June 2023, two Algorithm Experiments features: Glucose Based Partial Application and Integral Retrospective Correction, were added to the dev branch of Loop and LoopWorkspace. The main branch customizations have been updated to match the final look and feel of what was added to dev.

Customizations Available with Customization Select

CAGE: Upload Pod Start to Nightscout (main only, already in dev) “omnipod_cage”
SAGE: Upload Dexcom Sensor Start to Nightscout (main only) “dexcom_sage”
Change Default to Upload Dexcom Readings “dexcom_upload_readings”
Increase Future Carbs Limit to 4 hours “future_carbs_4h”
Modify Carb Warning & Limit: Low Carb to 49 & 99 “low_carb_limit”
Modify Carb Warning & Limit: High Carb to 201 & 300 “high_carb_limit”
Disable Authentication Requirement “no_auth”
Modify Override Insulin Needs Picker (50% to 200%, steps of 5%) “override_sens”
Limit CGM driven Loop Cycle to 5 minutes (main only) “limit_loop_cycle_time”
Add now line to charts “now_line”
Modify Logo to include LnL icon “lnl_icon”
CustomTypeOne LoopPatches “customtypeone_looppatches”
Profile Save & Load “2002”
Algorithm Experiments (main only) “algorithm_experiments”
TestFlight Expiration (Browser Build, main only) “testflight_expiration_warning”

Loop Customization Select Script

You can run the Loop Customization Select Script by pasting the line below into a terminal window on your Mac and following the menu instructions. If you need instructions for Browser Build, please read the menu information first and then continue to the Browser Build section.

Click on the line below to copy it. You’ll see Copied to Clipboard briefly.

Pro Tip

Read the instructions in the terminal screen.

The image below shows an example of Customization Select run on a Mac
The teminal window was made taller than the default by dragging the lower right corner
It is much easier to navigate when you can see all the information in one view
You can also increase or decrease the font size by holding down the Cmd key and typing + or –

List of customizations provided by the CustomizationSelect script

Script Details

The script automatically locates the most recent download of Loop in the Downloads/BuildLoop folder on your Mac, allows you to customize that download and opens Xcode for you when you are done.

You will be informed which customizations are already applied, which ones cannot be applied and which ones are available.

The customizations associated with the Loop Features in Development are subject to being updated when working with the developers in getting these added to Loop

If you have one of these applied to your download and you notice there has been an update, simply run the Customization Select script again and you will be offered the update

To apply a customization, simply type the number associated with that customization and enter. Do not worry if the green (success) message scrolls past too quickly for you to read. The script will stop with a warning message if there was a problem, and will wait for you to acknowledge the message. You can choose as many customizations as desired.

Normally, the final selection made is to type 60 and enter to exit the script and open Xcode to build your customized version of Loop.

The options shown at the bottom have fixed numbers that you type and enter to select:

40: To remove a customization (only shown if customizations have been applied)
45: To update a customization (only shown if an update is available)
50: Exit Script (or return to Build Select Script menu)
60: Exit Script and open Xcode

For a fresh build:

Use the Build Select Script to download your choice of Loop
Build to a simulator, instead of your phone, using Xcode
The script returns to the top-level menu (or you can exit and rerun the script)
Select Run Customization Select
When you have selected the customizations you desire, type 60 and enter to Return to Menu and open Xcode
Build to your phone

To add customizations to an existing (recent) download:

You can run the script directly
- The Customization Select script automatically finds the most recent download (and informs you of the directory name)
You can apply or remove the desired customizations
When done, you type 60 and enter to Exit Script and open Xcode
Build to your phone

Special Case: Customize a Specific Download

This is not typical, but there are people who might have more than one copy of Loop on their computer and want to customize a specific version. These people will know how to follow these steps. The rest of you can ignore this section.

Before starting the script

Navigate to the desired LoopWorkspace folder in the terminal
- See LoopDocs: Find My Downloaded Code
Start the Customization Script in the terminal in that folder
Once the script starts, make sure the folder reported is the one you want

Browser Build

To customize with the Browser Build method, modify the build_loop.yml file using a browser.

Make sure you are logged into your GitHub account
Go to your fork ( github dot com / username / LoopWorkspace )
Navigate by tapping on Code, then the folder “.github/workflows” and then build_loop.yml
When you tap on build_loop.yml, you see the text for that file
There is a pencil on the right side – tap on the pencil and now you can edit the file
- You need to add a blank line before and after the template – this file relies on blank lines between sections and the indentation is also important
- After you click on the pencil and find where to insert the customization, you will hit return, paste the template and hit return again for proper formatting
Follow the directions below until you make the changes you want
- First insert the Customization Template into build_loop.yml (for Loop 3.2.2 and earlier) (if not already present)
- This template includes all customizations for your convenience – you need to delete the lines you don’t want
- Each line ends in a continuation character `\`
  - There can be nothing after that on the line
  - If you insert spaces after the `\`, your build will fail
- If you don’t delete the lines you don’t want – your build will fail
  - For example, low_carb_limit and high_carb_limit are incompatible
The last customization in the list cannot end with the continuation character `\`
Save the changes by committing directly to your fork with an appropriate comment (make as many edits and commits as you want) but make sure there are blank lines before and after the customization section you added
When you are happy with your build_loop.yml, hit Actions: 4 Build Loop
Assuming there are no build errors, your new build will be ready in TestFlight in about an hour

WARNING – these templates only work from the original language version – do not copy and paste from a translated page.

If your fork points to the loopnlearn version of LoopWorkspace, main_lnl_patches branch, then the lnl_icon and customtypeone_looppatches are already installed. Trying to install them again will cause an error and your Loop will not build.

If your fork points to the LoopKit version of LoopWorkspace, main branch, and you need to add xDrip4iOS or GlucoseDirect to your build, be sure to add the extra lines listed in the Build Loop with Patches section (you need both).

If you previously added customizations “1988” and “2008” to your build_loop.yml file – please update that file before trying to build.

The customization for the main branch was modified to match the look and feel of what was merged into the dev branch and is added with “algorithm_experiments”

The dev branch (25 June 2023 or later) already has that code included – no need for customization

For those who use the dev branch:

There was a new update to the Browser Build method on 12 July 2023
This new method provides the capability to automatically update your TestFlight build
Please be aware you will need to sync your branch to dev (discarding any customization in your build_loop.yml file) and then reapply customizations after updating
There are also changes to a few more things as described in the Customization Template – dev section
As this is tested, there may be a few more updates – please pay attention

Prepared Customizations

Be sure to read the documentation links found in the Customization List before using these prepared customizations in your Browser Build.

Be sure to review the Browser Build instructions before using one of these templates.

Customization Template

If you are building the dev branch, there’s a different template: Customization Template – dev

Even if you do not want any other customizations, please use “testflight_expiration_warning”:

This provides an in-app warning that alerts you 20 days before your “Beta” app will expire.

While you are editing your build_loop.yml file,

Locate line 31, (as of version Loop 3.2.x)
This is just above the words:
“# Patch Fastlane Match to not print tables”
Your cursor can be anywhere on that line (should be a blank line)
Hit return to insert a blank line
Copy the text (see instructions below) and paste it into build_loop.yml
After pasting, hit return to insert another blank line
(The build will fail if you don’t have a blank line above and below the customization section)
Review the customization items and delete the ones you do not want
Do not add anything at the end of the lines after the `\` character
When done, commit this change so you can use it

Don’t forget that you must edit the template to remove customizations you do not want. For example, you cannot have both low_carb_limit and high_carb_limit in the list because they conflict with each other. You can choose to add the “now” line on your charts (now_line) or you can choose customtypeone_looppatches – but not both.

WARNING – these templates only work from the original language version – do not copy and paste from a translated page.

How to Copy:

Click on one of the lines in the template of text below to copy the entire template to your paste buffer
The words “Copied to Clipboard” will appear briefly

     
      
      # Customize Loop: Download and apply patches
      - name: Customize Loop
        run: | 

          # The lines below add the customizations listed using the CustomizationSelect script
          # The "\" is a continuation character 
          #   the line following a "\" cannot be blank - that causes the Action to never complete
          /bin/bash -c "$(curl -fsSL \
          https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/CustomizationSelect.sh)" \
          omnipod_cage \
          dexcom_sage \
          dexcom_upload_readings \
          future_carbs_4h \
          low_carb_limit \
          high_carb_limit \
          no_auth \
          override_sens \
          limit_loop_cycle_time \
          now_line \
          lnl_icon \
          customtypeone_looppatches \
          2002 \
          algorithm_experiments \
          testflight_expiration_warning

          # the final customization listed above CANNOT have a continuation character "\"
          # more customizations can be pasted after this line

Customization Template – dev

This template is ONLY for the dev branch; last updated 23 Septempber 2023

On 22 and 23 September 2023, updates were made to the dev code to upload Sensor Start and Omnipod Cannula Start to Nightscout for the SAGE and CAGE fields.

On 9 July 2023, modifications were added to the dev branch to ensure a Loop cycle begins in response to a CGM entry and limits the cycle frequency to ~5 minutes.

This modification prevents a sensor with a 1-minute update rate, such as Libre, from driving the Loop app too frequently

The same code modification was used to update the “limit_loop_cycle_time” customization for the released code

The “limit_loop_cycle_time” customization was removed from the dev template; it is not compatible because the code is already in dev

On 12 July 2023, modifications were added to the dev branch for the Browser Build method

The new method adds automatic updates and rebuilds so your TestFlight always has an up-to-date and unexpired version of Loop

You will probably need to discard customizations you might have merged into your version of the dev branch (on your fork) – use the `Discard Changes` in the sync dialog on GitHub

To enable this to work without failing, you must add workflow permission to your GH_PAT and create a new branch called `alive`

Please see this zulipchat link to add permission to GH_PAT (you do NOT need to regenerate, just add a capability)

Please use these instructions for adding the `alive` branch.

While you are editing your build_loop.yml file,

Locate line 249
This is just above the words:
“# Patch Fastlane Match to not print tables”
Your cursor can be anywhere on that line (should be a blank line)
Hit return to insert a blank line
Copy the text (see instructions below) and paste it into build_loop.yml
After pasting, hit return to insert another blank line
(The build may fail if you don’t have a blank line above and below the customization section)
Review the customization items and delete the ones you do not want
Do not add anything at the end of the lines after the `\` character
When done, commit this change so you can use it

WARNING – these templates only work from the original language version – do not copy and paste from a translated page.

How to Copy:

Click on one of the lines in the template of text below to copy the entire template to your paste buffer
The words “Copied to Clipboard” will appear briefly.

          

          # The lines below add the customizations listed using the CustomizationSelect script
          # The "\" is a continuation character 
          #   the line following a "\" should not be blank
          /bin/bash -c "$(curl -fsSL \
          https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/CustomizationSelect.sh)" \
          dexcom_upload_readings \
          future_carbs_4h \
          low_carb_limit \
          high_carb_limit \
          no_auth \
          override_sens \
          now_line \
          lnl_icon \
          customtypeone_looppatches \
          2002

          # the final customization listed above CANNOT have a continuation character "\"
          # more customizations can be pasted after this line

Adding CGM Clients to 3.2.3 using Browser

The prepared fork at loopnlearn used to download Loop with Patches will not work with Xcode 15.

If you are using the Browser Build and want to add a CGM Client, then follow the directions below and paste those lines into build_loop.yml

Warning – This will not work with the next release of Loop (3.4.0) and does not work with Loop dev.

If you built the released version of Loop using the GitHub Build Method and want to add CGM clients (xDrip4iOS or GlucoseDirect), you need to add additional lines to build_loop.yml file in addition to having the desired CGM app on your phone.

You must first add the Customization Template as described above.

Click on any line in the block of text below to copy the entire block to your clipboad. The words “Copied to Clipboard” will appear briefly. Insert a blank line, then paste the lines below the Customization Select section you just added, below the line that warns about not ending with a continuation character and above the “# Patch Fastlane Match to not print tables” section. Then add another blank line after what you just inserted.


        
          # LoopWorkspace commit: Adds xDrip4iOS and GlucoseDirect CGM clients
          # Note - the added submodules must be cloned before the patch will work
          echo "Downloading code to support xdrip-client-swift"
          git clone https://github.com/johandegraeve/xdrip-client-swift-1.git xdrip-client-swift
          echo "Downloading code to support GlucoseDirectClient"
          git clone https://github.com/creepymonster/GlucoseDirectClient.git GlucoseDirectClient
          # This patch configures LoopWorkspace to use the added CGM submodules
          echo "Applying customization to add CGM support to Loop for xDrip4iOS and GlucoseDirect"
          curl https://github.com/loopnlearn/LoopWorkspace/commit/4092277a21fa44a1258b693a5fbcce4d8d9dbd17.patch | git apply
          
          # more customizations can be pasted after this line

Adding CGM Clients to 3.2.3 using Mac-Xcode Build

The prepared fork at loopnlearn used to download Loop with Patches will not work with Xcode 15.

If you download Loop 3.2.3 so you can build with Xcode 15 and you want to use xDrip4iOS or GlucoseDirect, this section has instructions for building using Mac-Xcode.

If you are using the Browser Build, then follow the directions in the previous section.

Warning – This will not work with the next release of Loop (3.4.0) and does not work with Loop dev.

This section enables someone who uses the Mac-Xcode method to download a fresh copy of Loop using the Build Select Script to add the two extra CGM Clients to 3.2.3 with Xcode 15. These instructions are not for a novice – it gives guidance, but does not hold your hand. If you want to add customizations – do it after you successfully build with the client you desire.

Step 0: Start the BuildSelectScript

Click on the line below to copy it. You’ll see Copied to Clipboard briefly.

Step 1: Download Loop using BuildSelectScript:

Type: 1 (agree), 1 (build loop), 1 (start download)

download and build Loop (no customizations) can choose simulator on computer if desired.

Step 2: You should be at the main menu for BuildSelectScript again (skip this if you already have the client you want on your phone – the example below is for GlucoseDirect)

Type: 2 (build related app), 4 (build Glucose Direct), 1 (start download)

download and build GlucoseDirect on your phone

Step 3: You should be at the main menu for BuildSelectScript again – type 5 to exit the script but keep terminal open

Step 4: Find your folder

Scroll up in the terminal until you find the line: ` — Downloading Loop to your Downloads folder –`

The next line tells you where the download went; mine says: `/Users/marion/Downloads/BuildLoop/Loop-230928-0416`

Copy that folder name into your paste buffer and you’re going to type in a new line in the terminal: `cd ` with a space, then paste the folder name and then one more thing `/LoopWorkspace` and hit return. My line would be:

`cd /Users/marion/Downloads/BuildLoop/Loop-230928-0416/LoopWorkspace`

Step 5: Click on any line in the block of text below to copy the entire block to your clipboad. The words “Copied to Clipboard” will appear briefly.

Step 6: Paste the lines into your terminal and wait for it to complete. Make sure there are no errors

If Xcode is still open, you will be warned that `LoopWorkspace.xcworkspace` has been updated. Choose to use the version on disk.

If Xcode is not open, then type `xed .`, (that’s the characters xed space period or full stop) then return to open Xcode

Press the “play” symbol to build with Xcode


        
          echo "Downloading code to support xdrip-client-swift"
          git clone https://github.com/johandegraeve/xdrip-client-swift-1.git xdrip-client-swift
          echo "Downloading code to support GlucoseDirectClient"
          git clone https://github.com/creepymonster/GlucoseDirectClient.git GlucoseDirectClient
          echo "Applying customization to add CGM support to Loop for xDrip4iOS and GlucoseDirect"
          curl https://github.com/loopnlearn/LoopWorkspace/commit/4092277a21fa44a1258b693a5fbcce4d8d9dbd17.patch | git apply

Customization Select Details

The details for the some of the Customization Select items are found below. Information is also provided on two other pages for CustomTypeOne LoopPatches and Loop Features in Development.

CAGE: Upload Pod Start to Nightscout

This (main only) customization modifies both OmniKit (Eros) and OmniBLE (DASH) so it works regardless of pod type. This customization is not needed for dev.

To view the code change associated with “omnipod_cage”, click on this URL and open the cage.patch file in that folder.

SAGE: Upload Dexcom Sensor Start to Nightscout

This (main only) modification uploads to Nightscout to reset the SAGE counter when a Dexcom Sensor (G6 or G7) is started. This customization is not needed for dev.

To view the code change associated with “dexcom_sage”, click on this URL and open the appropriate g6g7_sage.patch file in that folder. The one with the “dev_” prefix works for development code.

Change Default to Upload Dexcom Readings

This modification changes the default setting for G6 or G7 Sensor to upload to the remote services, for example, Nightscout and/or Tidepool.

With this patch, the user no longer needs to remember to check the box with each transmitter change (G6)
Some people like to switch between G6 and G7 – this patch works for both

To view the code change associated with “dexcom_upload_readings”, click on this URL and open the g6g7_upload_readings.patch file in that folder.

Increase Future Carbs Limit to 4 hours

This customization enables the user to enter carbs up to 4 hours in the future. This removes the safety limit for future carbs of 1 hours found in released Loop.

To view the code change associated with “future_carbs_4h”, click on this URL and open the future_carbs_4h.patch file in that folder.

Modify Carb Warning & Limit: Low Carb to 49 & 99

This is one of two Carb Warning & Limit modifcations to choose from – select ONLY one.

The Low Carb version warns when a meal is over 49 g and refuses to allow a single meal entry over 99 g.

To view the code change associated with “low_carb_limit”, click on this URL and open the low_carb_limit.patch file in that folder.

Modify Carb Warning & Limit: High Carb to 201 & 300

This is one of two Carb Warning & Limit modifcations to choose from – select ONLY one.

The High Carb version warns when a meal contains 202 g or more and refuses to allow a single meal entry over 300 g.

To view the code change associated with “high_carb_limit”, click on this URL and open the high_carb_limit.patch file in that folder.

Disable Authentication Requirement

This customization removes the requirement to provide authentication for bolusing and therapy settings changes.

This removes an important safety feature.

To view the code change associated with “no_auth”, click on this URL and open the no_auth.patch file in that folder.

Modify Override Insulin Needs Picker (50% to 200%, steps of 5%)

This modification changes the overall insulin needs picker (lower number for increased sensitivity) to 50% to 200% in steps of 5%. This is often requested for young Loopers.

To view the code change associated with “override_sens”, click on this URL and open the override_sens.patch file in that folder.

Limit CGM driven Loop Cycle to 5 minutes

This (main only) customization modifies the released code (3.2.x) to match the dev branch (development code) with respect to the CGM driven Loop cycle time. This customization is not needed for dev.

The Customization Select Script was modified on 10 August 2023 to match this update to dev. Those using the old version of this customization should update it (main) or remove it (dev).

Browser build for main: sync your LoopWorkspace repository, confirm “limit_loop_cycle_time” is in build_loop.yml and repeat the Action: Build Loop
Browser build for dev: sync your LoopWorkspace repository, remove “limit_loop_cycle_time” from build_loop.yml and repeat the Action: Build Loop
Mac-Xcode build: run Customization Select Script again and an update will be offered (main-updates to new version, dev-removes old version)

The Loop calculation cycle is started when a new CGM value is detected. When using dev or main with this customization, the CGM driven cycle is limited to occur no more frequently than 4.2 minutes. This is very helpful for anyone using a sensor, such as Libre, which reports a value at 1-minute intervals. The pumps compatible with Loop are not designed to be commanded every minute and work better with a 5-minute update rate.

When running released code (3.2.x) without this customization, if the CGM values are updated too fast (to Loop or to Apple Health) this can cause communication issues with Medtronic pumps and early pod failures.

To view the code change associated with “limit_loop_cycle_time”, click on this URL and open the main_pr2039.patch file in that folder. (Pull Request 2039 was merged into dev on 9 August 2023.)

Add now line to charts

This customization adds a vertical line to all the charts on the main Loop screen and the glucose prediction on the bolus screen. This vertical line indicates the current time in the charts. Some people find this helps them interpret the charts.

These are the same style of vertical lines that are part of the CustomTypeOne LoopPatches (LoopPatches)
This is offered as a stand-alone customization
The two customizations are not compatible; you must choose one or the other
Heads Up: LoopPatches will no longer be offered when Loop 3.4.0 is released

The Customization Select Script was modified on 25 September 2023 to add this as a separate option.

To view the code change associated with “now_line”, click on this URL and open the main or dev patch file in that folder.

Modify Loop Logo with Loop and Learn icon

This customization replaces the Loop icon seen on your iPhone with the Loop and Learn icon instead. After applying the customization (or removing it when previously applied), you may need to reboot your phone to see the change.

The code change associated with “lnl_icon” is in the lnl_icon.patch file at this URL.

The modified icon seen on your iPhone looks like this:

TestFlight Expiration (Browser Build, main only)

This customization adds a warning internal to the Loop app for when a Browser Build (TestFlight) version will expire. The TestFlight distribution method expires 90-days after the app is built, regardless of when it installed on your phone.

The Template to add to the build_loop.yml file is updated with this new customization (9 Oct 2023).

Adding this customization to build_loop.yml means you won’t need it for another 90 days; but allows you to view, at the bottom of the Loop Settings screen, when your app “Beta” will expire.

To view the code change associated with “testflight_expiration_warning”, click on this URL and open the main_tf_alert.patch file in that folder. This customization will not longer be needed with the next release. This feature is already incorporated in dev.

Other Customizations:

Information is provided for some of the customizations on two other pages