Customization – Table of Contents

Customizations are the way to create your own personalized Loop app. This page has instructions for three types of Customizations:

Choose from:

1. Customization Select Script
2. Add xdrip4iOS Client to Loop
3. Add Dana-i and Dana-RS Pumps to Loop

These customizations work for both Browser Build and Mac Build.

• For Browser Build, each of the options above has its own template that you copy and paste into the build_loop.yml file using the Customize Browser Build instructions
  • These instructions work for adding xdrip4iOS or Dana as well as your choices from Customization Select
  • Once you add your customizations to the build_loop.yml file, it should work every time you run Action: Build Loop and typically continues to work across updates
• For Mac Build
  • You have options:
    • When you build Loop using the Build Select script, before building your app in Xcode, select Option 4, Customization Select or
    • Paste the Customization Select command into any terminal window to choose your options one at a time or
    • Open your terminal window to your LoopWorkspace folder and paste in the selected customizations using the same format as for Browser Build
  • You need to repeat this process each time that you update your Loop app.

Customization Select Script

1. 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. Overall Instructions for Browser Build
      5. Browser Build
         • Customization Template
         • Add xdrip4iOS Client
         • Add Dana pump
         • Browser Build Customization Troubleshooting

      6. Details for Each Customization Option
      7. Updating your Customized version of Loop

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

• Browser Builders: the script is run by copying and pasting some text into a special file called build_loop.yml used by GitHub during a Build Loop Action
• Mac-Xcode Builders: the script is run by copying and pasting some text into the terminal window and following along with the menu
  • Or – you can use the Customization Template, suitably edited and pasted into your LoopWorkspace folder in your terminal

When run on a Mac in the menu-driven mode, 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 in the Customization Select Script 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 using the Customization Template

Please refer to Loop Features in Development for more information about some of the more complex customizations.

Breaking news:

14 September 2024:  For Browser Builders

• The obscure name of “2002” was replaced with “profiles”
• This change is backwards compatible – if you have “2002” in your build_loop.yml file, your Profiles customization will still work

19 July 2024:  Loop 3.4.1 was released, fix for Browser Build

13 July 2024:  Loop 3.4.0 was released

Customizations Available with Customization Select

Do not rely the numbering shown here when making selections, always use the numbering in the script. As customizations are added or removed, their numbers may change.

1. Change Default to Upload Dexcom Readings “dexcom_upload_readings”
2. Increase Future Carbs Limit to 4 hours “future_carbs_4h”
3. Modify Carb Warning & Limit: Low Carb to 49 & 99 “low_carb_limit”
4. Modify Carb Warning & Limit: High Carb to 201 & 300 “high_carb_limit”
5. Disable Authentication Requirement “no_auth”
6. Modify Override Insulin Needs Picker (50% to 200%, steps of 5%) “override_sens”
7. Add now line to charts “now_line”
8. Modify Logo to include LnL icon “lnl_icon”
9. Remove Loop Title on Watch App “watch_title”
10. 2-hour Absorption Time for Lollipop “2hlollipop”
11. Display Two Days of Meal History “meal_days”
12. Display a Week of Meal History “meal_week”
13. Profile Save & Load “profiles”
14. Basal Lock “basal_lock”
15. Live Activity/Dynamic Island “live_activity”

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 more likely to be updated.

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

When the Live Activity customization becomes available (currently under development), you need to make sure Xcode is not open to the workspace you are modifying. This customization requires a modification to the minimum iOS supported. If Xcode is open when you apply it, you will have to do some manual clean-up before you can build. (Clean the build folder, close Xcode, re-open Xcode for your workspace).

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

Overall Instructions for 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
   • The proper execution of this file during the build action relies on blank lines between sections and proper indentation
   • After you make your edits, before you save, make sure the columns line up
6. Follow the directions below for the customization that you want (same directions for Customization Select, Add Xdri and Add Dana Pump)
7. You are going to edit your build_loop.yml file
   • Refer to the graphic below
   • You need to find the line that starts with “# Patch Fastlane” and add text above it
   • Use command-f (on a Mac) or control-f (on a PC), to find this phrase (use copy button below) and then command-v (on a Mac) or control-v (on a PC) to paste it into the search bar

 # Patch Fastlane Match to not print tables

1. • There is a blank line just above “# Patch Fastlane Match to not print tables”.  We’ll call this row your Paste Line
     • As of 21 July, the Paste Line is on 249 for Loop-dev and 279 for Loop-main, but is subject to change
   • Your cursor needs to be lined up in the correct column on the Paste Line before you paste (using either command or control-v, depending upon whether you’re using a Mac or PC)
   • Copy the template (see instructions below) and paste it into build_loop.yml
   • After pasting, hit return to insert another blank line
   • When editing is completed, save the edit by tapping the Commit Changes button on the upper right and commit to your current branch (add a message if desired) by selecting  Commit Changes again – you can edit and save as often as you need
2. To use the Customization Select script with Browser build:
   • First insert the Customization Template into build_loop.yml
   • 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
     • You cannot include both low_carb_limit and high_carb_limit; choose one or neither
     • You cannot include both meal_days and meal_week; choose one or neither
   • All but the last 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
   • The last customization in the list cannot end with the continuation character `\`, if one is there – you must remove it
3. To add the ability to use xDrip4iOS Client, insert the template found at Add xdrip4iOS Client to Loop 3.4
4. To add the ability to use the Dana pump, insert the template found at Add Dana Pump to Loop 3.4
5. When you are happy with your edits to your build_loop.yml, hit Actions: 4 Build Loop
6. 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.

The build will fail if the columns are not aligned or there is not at least one blank line above and below the customization sections.

Please be aware that the “continuation character” is used to make the template easier to read. In effect, what you are pasting is one single long line. Do not try to put in a # symbol to remove a customization. The customizations you don’t want must be deleted.

Template for Browser Build

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 Overall Instructions for Browser Build instructions before using one of these templates.

Customization Template – main

This template is for Loop 3.4.x, released 13 July 2024 or later. At the current time, it also works for the dev branch.

You must edit the template to remove customizations you do not want and if you want to Disable Authentication, you have to type it in yourself.

• For example, you cannot have both low_carb_limit and high_carb_limit in the list because they conflict with each other.
• If you choose one of the meal extensions, choose either meal_days or meal_week, not both.
• If you want to disable authentication, you must type it in yourself
  • You must add the “no_auth” yourself (no quotes) – it can be on the same line as another customization, separated by a space, or you can make a separate line following the pattern in the template

Be careful with editing. Do not delete the script lines that come above dexcom_upload_readings \.

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 \
          override_sens \
          now_line \
          lnl_icon \
          watch_title \
          2hlollipop \
          meal_days \
          meal_week \
          profiles \
          basal_lock \
          live_activity

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

        

Before saving your changes, make sure the lines you pasted are in the same column as the lines above your new lines.

Please be aware that the “continuation character” is used to make this template easier to read. In effect, what you are pasting is one single long line. Do not try to put in a # symbol to remove a customization. The customizations you don’t want must be deleted.

If your build fails after customizing, check out the Troubleshooting tips below.

Customization Template – dev branch

This is a placeholder in case it is needed later. Use the Customization Template – main until told otherwise.

The line number at which you paste the template may change, be alert.

Add xdrip4iOS Client to Loop 3.4 or Later

This template works for browser build or Mac build.

• Mac Build: paste it into Terminal open at your LoopWorkspace folder, see LoopDocs: Find My Downloaded Loop Code
• Browser Build: paste it into the Customize Loop section of build_loop.yml, see: Customize Browser Build

To copy the lines below, click on any line to copy the entire block to your clipboard. The words “Copied to Clipboard” will appear briefly. Insert the copied text into Terminal or build_loop.yml file as directed above.

        
          echo "Downloading code to support xdrip-client-swift"
          git clone https://github.com/johandegraeve/xdrip-client-swift-1.git xdrip-client-swift
          echo "checking out the xdrip-client-swift commit that works with Loop 3.4.0 or later"
          cd xdrip-client-swift; git checkout e618d67 --quiet; cd ..
          echo "Applying customization to add CGM support to Loop for xDrip4iOS"
          curl https://github.com/loopandlearn/LoopWorkspace/commit/4097af116ab869084329660c4761bbddff5b7d03.patch | git apply
          

Add Dana Pump to Loop 3.4 or Later

WARNING: The use of this pump with Loop is experimental. Be very cautious.

Follow along in zulipchat. Put a watch on the DanaKit repository to be notified of updates to the code.

This template works for browser build or Mac build.

• Mac Build: paste it into a terminal open at your LoopWorkspace folder, see LoopDocs: Find My Downloaded Loop Code
• Browser Build: paste it into the Customize Loop section of build_loop.yml, see: Customize Browser Build

To copy the lines below, click on any line to copy the entire block to your clipboard. The words “Copied to Clipboard” will appear briefly. Insert the copied text in the terminal as directed above.

        
          echo "Downloading code to support Dana pump"
          git clone --branch=dev https://github.com/bastiaanv/DanaKit
          echo "Applying customization to add Dana support to Loop"
          curl https://github.com/loopandlearn/LoopWorkspace/commit/155d2e4a89ab5e7e6b423c67f8c0ccb132517ca4.patch | git apply
          

Customization Select Details

The details for the some of the Customization Select items are found below.

With the release of 3.4, CustomTypeOne LoopPatches are no longer available. We are working on replacement patches with proper guardrails.

More complex customizations are found on this page: Loop Features in Development.

A number of customizations for 3.2.3 were removed from this page and the script because they are already included in Loop 3.4.

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.

Unlike all the other customization options, the prototype line for this customization is not included in the template for Brower Build. If you want to disable this important safety feature, you must type it in yourself.

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.

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:

Remove Loop from Watch Title

This customization removes the row with “Loop” as the watch title. This title used to show up on the upper left in the same row as the time. Now it wraps around to a new row. For some watches, this limits what can be seen without scrolling.

Removing the row with the “Loop” title isn’t a perfect fix, but some people prefer it. 

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

2-hour Absorption Time for Lollipop

This customization modifies the absorption time associated with the Lollipop to 2 hours. This value was used for Loop versions 2.2.9 and earlier.  Many Loop users prefer that time over the 30-minute absorption time provided with Loop 3.x.x.

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

Display Two Days of Meal History

This customization extends the Carbohydrates history page so the earliest data shown is from midnight a day ago. This is a shorter period that you get when you choose Display a Week of Meal History, but it loads faster after quitting and restarting the app. Only one of these can be chosen.

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

Display a Week of Meal History

This customization extends the Carbohydrates history page so the earliest data shown is from midnight a week ago. This customization slows down the time it takes for Loop to display the charts after quitting and restarting the app. If you don’t need a week, consider the using Display Two Days of Meal History customization instead. Note that you cannot incude both meal_week and meal_days customizations.

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

More Complex Customizations:

Information for more complex customizations is provided on this page

• Loop Features in Development