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

We did a quick edit of this page following release of 3.4. Let us know if you find mistakes.

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

Breaking news:

13 July 2024: Loop 3.4.0 was released

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

    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.

    The numbers and items in the adjacent image are as of 19 July 2024, and are subject to change.  The complete list is shown above.  

    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 –
    Build Select Loop 3.4<br />

    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

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

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

        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.

        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 are going to edit your build_loop.yml file,

          1. Click on the line below that starts with “# Patch Fastlane” to copy the search term into your clipboard
          2. Use command-f (on a Mac) or control f (on a PC), to find this phrase 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
             
          3. There is a blank line just above “# Patch Fastlane Match to not print tables”.  We’ll call this row your Paste Line
          4. As of 21 July, the Paste Line is on 249 for Loop-dev and 279 for Loop-main, but is subject to change
          5. 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)
          6. Copy the text (see instructions below) and paste it into build_loop.yml
          7. After pasting, hit return to insert another blank line
            (The build will fail if the columns are not aligned or there is not at least one blank line above and below the customization section.)
          8. Review the customization items and delete the ones you do not want
          9. Do not add anything at the end of the lines after the `\` character
          10. 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.

          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 \
                    2002 \
                    basal_lock \
                    watch_title
          
                    # the final customization listed above CANNOT have a continuation character "\"
                    # more customizations can be pasted after this line
          
                  

          Before saving your changes, make sure that your Paste Line (the exact line number is subject to change) is aligned with the lines below it:

           

          Adding CGM Clients to 3.2.3 using Browser

          Now that 3.4 is released, you can add CGM clients to 3.4. Read the directions but use the Copy/Paste for 3.4

          We will clean up this page when we have time.

          If you are using the Browser Build and want to add a CGM Client, then paste the 3.4 template into build_loop.yml at the Paste Line, which is described above, and is located at the blank row above Patch Fastlane Match to not Print Tables.

          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.

          Adding CGM Clients to 3.2.3 using Mac Build

          This method was updated 05 January 2024 to accomodate changes in one of the client repositories. The change to the client repository happened 12 November 2023.

          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 Xcode on your Mac.

          If you are using the Browser Build, then use instructions at this link instead.

          With the release of 3.4, you will need to use the Copy/Paste instructions for 3.4 once you’ve downloaded your Loop Code.

          This section enables someone who uses a Mac to download a fresh copy of Loop main branch and then add the two extra CGM Clients to Loop version 3.2.3. 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 add the extra CGM clients.

          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); you can choose to build to a simulator on computer if desired. This ensures a good download and build process without modifying the build on your phone until you have added the desired customization.

          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). At this point you can download and build xDrip4iOS or GlucoseDirect You only need to build the one you plan to use.

          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. (The copy/paste below is for version 3.2.3. For Loop-dev 3.3.0 or later, use the version here: Add CGM Clients with Loop 3.3 (dev) or later)

          Step 6: Paste the lines into your terminal and hit return (or enter) and wait for the process 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

          If the first build fails. Use the Xcode menu to select Product, Clean Build Folder. Close and reopen the workspace and try again.

          Add CGM Clients with Loop 3.4

          For either Browser Build or Mac Build, follow the directions above, but use the copy/paste section below. (The same text works for browser build and Mac 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 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 "Downloading code to support GlucoseDirectClient"
                    git clone --branch=dev https://github.com/creepymonster/GlucoseDirectClient.git GlucoseDirectClient
                    echo "checking out the GlucoseDirectClient commit that works with Loop 3.4.0 or later"
                    cd GlucoseDirectClient; git checkout c4223d7 --quiet; cd ..
                    echo "Applying customization to add CGM support to Loop for xDrip4iOS and GlucoseDirect"
                    curl https://github.com/loopandlearn/LoopWorkspace/commit/c97f303d15982a9b192bb90ae7ac3e89a3daf203.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.

          The Profile customizations has more details found on this page: Loop Features in Development.

          A number of customization for 3.2.3 have been 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.

          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.

          Other Customizations:

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

          Skip to content