Customization Select Page – Table of Contents

1. 1. Overview
      • What is a Script?
   2. Customization
      • Customization List
   3. Loop Customization Select Script
      • Script Details
      • Special Case: Customize a Specific Download
   4. Browser Build
      • Prepared Customizations
      • Customization Template
      • Customization Template – dev
   5. Adding Loop with Patches to 3.2.3
   6. Customization Select Details

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

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:

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

1. CAGE: Upload Pod Start to Nightscout “omnipod_cage”
2. SAGE: Upload Dexcom Sensor Start to Nightscout “dexcom_sage”
3. Change Default to Upload Dexcom Readings “dexcom_upload_readings”
4. Increase Future Carbs Limit to 4 hours “future_carbs_4h”
5. Modify Carb Warning & Limit: Low Carb to 49 & 99 “low_carb_limit”
6. Modify Carb Warning & Limit: High Carb to 201 & 300 “high_carb_limit”
7. Disable Authentication Requirement “no_auth”
8. Modify Override Insulin Needs Picker (50% to 200%, steps of 5%) “override_sens”
9. Limit CGM driven Loop Cycle to 5 minutes “limit_loop_cycle_time”
10. Modify Logo to include LnL icon “lnl_icon”
11. CustomTypeOne LoopPatches “customtypeone_looppatches”
12. Profile Save & Load “2002”
13. Algorithm Experiments “algorithm_experiments”

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

Browser Build

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

1. Make sure you are logged into your GitHub account
2. Go to your fork ( github dot com / username / LoopWorkspace )
3. Navigate by tapping on Code, then the folder “.github/workflows” and then build_loop.yml
4. When you tap on build_loop.yml, you see the text for that file
5. 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
6. 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
   • 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
7. The last customization in the list cannot end with the continuation character `\`
8. 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
9. When you are happy with your build_loop.yml, hit Actions: 4 Build Loop
10. Assuming there are no build errors, your new build will be ready in TestFlight in about an hour

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.

Customization Template

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

While you are editing your build_loop.yml file,

1. Locate line 31, (as of version Loop 3.2.x)
2. This is just above the words:
   “# Patch Fastlane Match to not print tables”
3. Your cursor can be anywhere on that line (should be a blank line)
4. Hit return to insert a blank line
5. Copy the text (see instructions below) and paste it into build_loop.yml
6. 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)
7. Review the customization items and delete the ones you do not want
8. When done, commit this change so you can use it

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.

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.

          
      # 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 \
          lnl_icon \
          customtypeone_looppatches \
          2002 \
          algorithm_experiments

          # 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,

1. Locate line 249
2. This is just above the words:
   “# Patch Fastlane Match to not print tables”
3. Your cursor can be anywhere on that line (should be a blank line)
4. Hit return to insert a blank line
5. Copy the text (see instructions below) and paste it into build_loop.yml
6. 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)
7. Review the customization items and delete the ones you do not want
8. When done, commit this change so you can use it

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.

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.

          

          # 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 \
          lnl_icon \
          customtypeone_looppatches \
          2002

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

Adding Loop with Patches to 3.2.3

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, simply paste the lines below into your terminal window in the LoopWorkspace folder, watch the extra clients be cloned and then type `xed .` when done. Click on this link for instructions on opening a terminal in the right location.

If you are using the Browser Build, 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 some or all of the items added to Loop with Patches, you need to add additional lines to build_loop.yml file.

This section enables someone who uses the Browser Build method and used the LoopKit LoopWorkspace main branch for their fork to have the same version that is currently available to Mac-Xcode builders who select Loop with Patches in the Build Select Script: Build Loop menu.

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. If you want Loop with Patches and no other customizations, then keep only the “customtypeone_looppatches” and the “lnl_icon” lines from the Customization Template.

        
          # 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
          

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

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:

Other Customizations:

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

• CustomTypeOne LoopPatches
• Loop Features in Development