diff --git a/README.md b/README.md index ee4ab7d3b33..ab04ac8d16b 100644 --- a/README.md +++ b/README.md @@ -195,28 +195,24 @@ If the word is at the end of a line or has other punctuation, the ` ` can b ### All about Word -This ability to build Loop, from both a browser and with Mac-Xcode, is wonderful. +This ability to build Loop from either a browser or using a *Mac* is wonderful. ``` Be warned that if ` ` is part of the text in a header, the automatic link doesn't acknowledge the space. The link above would be `#all-aboutword`, not `#all-about-word`. If you want italic font with `span`, I choose to use underscore instead of asterick to make the word show up as italic font because I think that helps with clarity (opinion only): ``` -This ability to build _Loop_, from both a browser and with Mac-Xcode, is wonderful. +This ability to build _Loop_, from both a browser and with *Mac*, is wonderful. ``` These words / phrases **do not need** no-translate tags, however, they are typically rendered in italics (use astericks on either side): * Xcode -* Mac-Xcode -* GitHub -* TestFlight - -These words **do need** no-translate tags (most of the time): -* Apple -* Loop -* LoopKit/Loop +* *Mac* +* *GitHub* +* *TestFlight* +* *Apple* Look out for Loop showing up as buckle, at least in French and Spanish, in translations. That indicates `span` must be used, with the ` ` required if there is no punctuation mark. Once again, using underscore instead of asterisk in concert with `span` is a preference: @@ -224,6 +220,9 @@ Look out for Loop showing up as buckle, at least in French and Spanish, in trans  _Loop_  ``` +The no-translate tags can be avoided if used in a phrase: +* the *Loop* app + Common words like `Secrets` that will show up on `GitHub` for Building with Browser should be enclosed in `code` so tooltips will work and the word will be highlighted as important. From Eric (his rules before Marion made comments above) diff --git a/docs/build/apple-developer.md b/docs/build/apple-developer.md index 642124b8c9f..b8057f69e71 100644 --- a/docs/build/apple-developer.md +++ b/docs/build/apple-developer.md @@ -10,7 +10,7 @@ - Paid Developer Account: Go to the [Apple Developer website](https://developer.apple.com/programs/enroll/) to enroll in an individual account. - Free: No action required at this time. - * Free requires you to use the Mac-Xcode build method + * Free requires the [Build with *Mac*](overview.md) method !!! question "FAQs" - **"Can I use someone else's Apple Developer account?"** Please refer to this [Answer](../faqs/FAQs.md#can-i-use-someone-elses-apple-developer-account). @@ -29,7 +29,7 @@ The Apple ID is DIFFERENT than the Apple Developer ID. Sharing an Apple ID among two or more loopers can cause safety issues. You don't want Sally to be dosed for Joe's lunch in addition to her own and vice versa. * The recommendation for Health Permissions for [Loop 2.2.x](health.md#loop-permissions) has changed to no longer provide permission to read Carbohydrates from Apple Health - * Loop 3 does not read Carbohydrates from Apple Health by default, but if you need that feature, you can [modify your feature flags](code-customization.md#build-time-features). + * Loop 3 does not read Carbohydrates from Apple Health by default, but if you need that feature, you can [modify your feature flags](../version/build-time-flag.md). ## Developer Account @@ -41,7 +41,7 @@ You have two options for an individual account: free or paid. If you decide to use a **FREE** developer account, here's what you need to know: -1. You must use the [Mac-Xcode Build](../build/overview.md) method to build Loop. +1. You must use the [Build with *Mac*](../build/overview.md) method to build Loop. 1. Loop apps signed with a free developer account will expire after 7 days. On the 7th day, your Loop app will simply turn white when you open it and then immediately close. To rebuild the Loop app, you will have to find a computer and rebuild the app onto your iPhone again. You cannot rebuild the app on day 5 (when it is convenient, for example), hoping to reset the 7-day clock. The app will still expire on the 7th day from when it was first signed and created. 2. If you decide to switch to a paid account after trying out the free account, you will need to rebuild your Loop app to sign it with the new paid account. Furthermore, switching from a [Free to a Paid](apple-developer.md#switching-from-free-to-paid-memberships) account requires entering all the settings again (and starting a fresh pod). 3. You will have to do an extra step during the build process to remove Siri and Apple Push capabilities to build with free accounts. Because free accounts do not have access to Apple Push notifications, you will also not be able to use [Remote Commands](../nightscout/remote-overview.md) through Nightscout. @@ -55,7 +55,7 @@ If you decide to use a **PAID** developer account, here's what you need to know: 1. If you use the Browser Build method * You must [Update with Browser](../gh-actions/gh-update.md) the build once every 90 days * You must have a Paid Developer account -1. If you use the Mac-Xcode Build method +1. If you use the Build with *Mac* method * If you have a paid developer account, you must build at least once a year * If you have a free account, you must build every 7 days diff --git a/docs/build/build-app.md b/docs/build/build-app.md index 9efa75338ba..fb3804046e1 100644 --- a/docs/build/build-app.md +++ b/docs/build/build-app.md @@ -412,6 +412,11 @@ The Loop app on your phone closes (but does not quit) when you unplug the phone. If you plan to build again on a backup phone, or want to try a customization, easiest for you to leave Xcode open. Otherwise, you can quit out of Xcode now. +But wait - there's more. + +* Caregivers who help manage a loved-ones diabetes often use other open-source apps that can be built the same way +* When you are done building and installing the *Loop* app, there are instructions on the *Loop and Learn* website to [Download and Build Related Apps](https://www.loopandlearn.org/build-select/#build-other-apps) + ## Protect that App !!! danger "Protect Against Deletion" @@ -463,7 +468,7 @@ Even if you don't read all the pages under the Set Up tab now, these links are i !!! tip "Pro Tip" With a fresh download of code, it's always best to build to a simulator without customization to ensure the build works without errors. Then add the customizations and check the build again. Now you are ready to build to your phone to update your existing app. -To add custom configurations to your Loop or Loop Apple Watch apps, follow the step-by-step instructions on the [Code Customizations](code-customization.md) page and then build the app again. +To add custom configurations to your Loop or Loop Apple Watch apps, follow the step-by-step instructions on the [Code Customizations](custom-mac.md) page and then build the app again. ### Apple Watch @@ -476,7 +481,7 @@ For more information, please see [Operate: Apple Watch](../operation/features/wa ### Build Again with this Download -Follow the [Find My Downloaded Loop Code](code-customization.md#find-my-downloaded-loop-code) instructions if you later wish to build with this same dowload. Plug in an unlocked phone and start at the [Start Build](#start-build) section of this page. You may need to select the phone you just plugged in. Everything else should be ready for you the start the build process. +Follow the [Find My Downloaded Loop Code](custom-mac.md#find-my-downloaded-loop-code) instructions if you later wish to build with this same dowload. Plug in an unlocked phone and start at the [Start Build](#start-build) section of this page. You may need to select the phone you just plugged in. Everything else should be ready for you the start the build process. !!! warning "Don't use a really old download" Do not use a really old download. diff --git a/docs/build/build-dev-mac.md b/docs/build/build-dev-mac.md new file mode 100644 index 00000000000..0f5e920e92f --- /dev/null +++ b/docs/build/build-dev-mac.md @@ -0,0 +1,56 @@ +## Overview + + +**This page is only relevant when building the `dev` branch with a *Mac*.** + +**For *Browser Build*, please see: [Build Loop dev with Browser](../gh-actions/build-dev-browser.md)** + +**No matter the method used to build Loop-dev, you are testing development code. Please read this link now before continuing.** + +* **[What's going on in the `dev branch`](../version/development.md#whats-going-on-in-the-dev-branch)** + +## `BuildLoopDev` Script + +There is a script to assist in building the `dev branch`. It gives you the option to choose the tip of the `dev branch` or to build a lightly tested commit. If you have not used the [Build Select Script](../build/build-app.md#build-select-script) to build Loop previously, you may want to review that page. The command below can be pasted into the terminal of your Mac. Read the directions in the script. + +``` { .bash .copy title="Copy and Paste to start the BuildLoopDev script" } +/bin/bash -c "$(curl -fsSL \ + https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildLoopDev.sh)" +``` +Both the `dev branch` and the lightly tested branch of `dev` have Libre support. + +### BuildLoopDev Other Branches + +You can use the BuildLoopDev script to build a specific development branch, other than `dev`. See the example below that would build `other-branch`, if such a branch existed. This is just an example. You need to substitute the branch you desire for `other-branch`. There must be a space after the final quote, followed by a hyphen, another space and then the branch name. + +``` { .bash .copy title="Example using other-branch with the BuildLoopDev script" } +/bin/bash -c "$(curl -fsSL \ + https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildLoopDev.sh)" - other-branch +``` + +## Update Loop-dev + +While Loop-dev is under active development, you should monitor zulipchat and update frequently. + +Checking for updates every week is a good idea. Also - subscribe to all the streams on [Loop Zulipchat](https://loop.zulipchat.com) to make sure you don't miss critical information. + +You may choose to download fresh each time you update. + +You may prefer to use commands to fetch and pull the latest code without making a new clone. + +* Some users like to use [GitKraken](https://support.gitkraken.com/) to assist them (link takes you to a tutorial video). +* Some are comfortable with the command line git commands described on [here](../version/loopworkspace.md#updating-loop-using-loopworkspace). + +## Loop-dev Version + +The version of code that shows up under the Loop Settings screen does not change when the `dev branch` is modified. + +If you need help with your app, the mentors need more information. Please issue a Loop Report when asking for help. Refer to [Support](../loop-3/settings.md#support) for how to issue a Loop Report. If you want to keep track yourself, refer to [Identify Loop-dev Version](#identify-loop-dev-version) + +* [`Loop` Version Numbering](../version/releases.md#loop-version-numbering) + +### Identify Loop-dev Version + +The version of code that shows up under the Loop Settings screen will remain fixed until Loop-dev is released. In order to identify which version of dev you have on your phone, you need the commit. + +The commit is identified by a 7-digit alphanumeric code. That code was also appended to the folder name of the downloaded code under Downloads/BuildLoop as shown in the graphic above. You can use finder to view the folder name after the script completes. It also appears in the Loop Report, refer to [Support](../loop-3/settings.md#support) for instructions on issuing a Loop Report. After you issue the Loop Report, look at the workspaceGitRevision number near the beginning of the report. diff --git a/docs/build/build-errors.md b/docs/build/build-errors.md index ea0fdc4bf7a..379ecb23114 100644 --- a/docs/build/build-errors.md +++ b/docs/build/build-errors.md @@ -42,7 +42,7 @@ Before you start trying to resolve your red errors, start with the most obvious 1. **Did you get a fresh download of Loop code?** If you tried to build with an old download that you used a long time ago, that old version may not be compatible with the new iOS and Xcode versions. Check also, that you are actually using the new download in Xcode. When you use the Build Select Script, it automatically opens Xcode using the new download. - If you want to build using a recent download, this section tells you how to [Find My Downloaded Loop Code](code-customization.md#find-my-downloaded-loop-code). + If you want to build using a recent download, this section tells you how to [Find My Downloaded Loop Code](custom-mac.md#find-my-downloaded-loop-code). 1. **Are you are using a free developer account?** Make sure you finished the removal of Siri and Push Notification capabilities described in the [Free Account](build-free-loop.md#free-account) link. diff --git a/docs/build/code-customization.md b/docs/build/code-customization.md deleted file mode 100644 index bdf2a1e765c..00000000000 --- a/docs/build/code-customization.md +++ /dev/null @@ -1,937 +0,0 @@ -## Build then Customize - -For new Loopers, please build the code before you make any changes. Start with Open Loop and familiarize yourself with the interface. Later, you can make the customization(s) you desire and build again. The second build will be much easier than your first build. - -These customizations require you to build the Loop app onto your iPhone, they cannot be done from within the app itself. - -## Customization Options - -Read about the customizations on this page before applying them. - -!!! warning "You take responsibility" - You are responsible when you decide to use customizations. - - Be sure to report what changes you made if you need to ask for assistance with your app. - -Some customizations are the same for everyone and have been prepared for easy use. - -* Mac-Xcode builders can use the [Loop and Learn: Loop Customizations](https://www.loopandlearn.org/custom-code) script - * This script automatically finds the most recent download and when you are done selecting customizations, opens Xcode to that download - * Even if you don't want to apply customizations, you can use this script as a easy way to find and open your download -* Browser builders can use [Loop and Learn: Customization: Prepared Customizations](https://www.loopandlearn.org/custom-code#prepared-custom-list) - -Other customizations require that you create your own personalized version. - -* Mac-Xcode builders: all the information required is on this page -* Browser builders: read this page and use [LoopDocs: Customization with Browser](../gh-actions/gh-customize.md#prepare-the-patches) - -For Build with Browser, you can skip over the Mac-Xcode specific section and skip ahead to [Build-Time Features](#build-time-features). - -When applying a customization using Mac-Xcode, the downloaded code should be fairly recent. If you are not sure, get a fresh download. If you know your downloaded code is the [Current Release](../version/releases.md#current-release), you can skip the download and use the same folder as last time. - -### Find My Downloaded Loop Code - -Refer to the graphic below. The Downloads folder in Finder is highlighted on the upper left. The full path to Loop.xcworkspace is highlighted along the bottom. - -!!! success "Loop to LoopWorkspace" - Note that the directory `Loop.xcworkspace` has been renamed to `LoopWorkspace.xcworkspace` in the released code. For experienced builders - you realize this is good because the build process is easier. - - The words were updated, but it will take time for the graphics to be updated. - -* Open Finder -* Navigate to Downloads/BuildLoop and look for your download by name and date -* Open that folder, for example, Downloads/BuildLoop/Loop-220803-1145, and inside that folder open the LoopWorkspace folder -* Inside the Downloads/BuildLoop/Loop-220803-1145/LoopWorkspace folder, double-click on LoopWorkspace.xcworkspace (graphic not updated yet) -* Xcode automatically opens to that particular download -* You can then make the customizations and build to your phone - -![how to use finder to find the correct download and open xcode](img/finding-loopworkspace.svg){width="750"} -{align="center"} - -!!! tip "Experienced Builders" - Experienced builders will often build a fresh download to a simulator for their phone iOS (not their phone) to ensure download is good and is compatible with macOS, Xcode and phone iOS. Once the build is successful, they apply their customizations and build again to the simulator. Last step is to build the customized version to their real phone. - -Be sure to read the [Instructions for Finding the Lines](code-customization.md#instructions-for-finding-the-lines). - -!!! info "Line numbers may change" - Every effort will be made to update the line numbers as the code is updated, but there may be times where the screenshots and line numbers differ from the current version of Loop code. - - * You may notice some customizations list line numbers for different branches - - * If you cannot identify a line that looks exactly like the example - do not guess - go to your favorite social media group and ask for help - -!!! abstract "Loop 2.2.x vs Loop 3" - - * Loop 3 has been released but there are some people using older code. - * The labels below indicate Loop 2.2.x or Loop 3, if they are different - * Users of Loop 2.2.9 (or earlier) or FreeAPS should refer to the Loop 2.2.x examples. - * Some 2.2.x customizations will be removed as time goes on - * Users of Loop 3 should refer to the Loop 3 examples. - * Note that some changes are in a different file for Loop 3 (part of the architecture upgrade for the app). - -## Build-Time Features - -Build-time features are not available with Loop 2.2.x. - -With Loop 3, some features are enabled or disabled by default but can be modified by adding a "flag" in the LoopConfigOverride.xcconfig file. - -If you use Build with Browser, these build-time features can be added to your copy of the LoopConfigOverride.xcconfig file. Use the pencil icon in that file on your copy of LoopWorkspace and then commit the change. - -If you use the Mac-Xcode Build Method, this is the same file used to automatically sign all your targets. You can edit the version in your LoopWorkspace folder (it shows up as the top item in the Xcode folder view) - or - if you use the build script, you can edit the copy found in ~/Downloads/BuildLoop after the first time you use the script. For that second case, the "flags" you add in ~/Downloads/BuildLoop/LoopConfigOverride.xcconfig are applied to all downloads created with the script. - -These flags are always upper case with underscore separating words for clarity, for example `MY_EXAMPLE_FLAG`. If you have more than one flag, they are separated by a space. Do not enter a line break between selections; in other words, do not hit return or enter. Xcode will automatically word-wrap the line for clarity. All values need to be on a single line. - -!!! question "New Instructions" - The instructions are more robust than earlier instructions that had you editing a line instead of adding new ones. - -Copy the text below, add it to the end of your LoopConfigOverride.xcconfig file and then insert the desired flags in place of `MY_EXAMPLE_FLAG`. If you want more than one flag, separate them by a space. - -``` { .txt .copy title="Lines to add to end of file" } - -// Add Build-Time features to compilation conditions -SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(SWIFT_ACTIVE_COMPILATION_CONDITIONS) MY_EXAMPLE_FLAG -``` - -_Code Before Modification_ - -``` -// Put your team id here for signing -//LOOP_DEVELOPMENT_TEAM = UY678SP37Q -``` - -The example below is for someone who is using a Free Developer ID - which does not support Siri. - -_Code After Modification_ - -``` -// Put your team id here for signing -//LOOP_DEVELOPMENT_TEAM = UY678SP37Q - -// Add Build-Time features to compilation conditions -SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(SWIFT_ACTIVE_COMPILATION_CONDITIONS) SIRI_DISABLED -``` - -List of some flags and what they do: - -|FLAG|PURPOSE| -|---------|---------| -|SIRI_DISABLED|Required to build Loop from Xcode with a free developer account| -|ADULT_CHILD_INSULIN_MODEL_SELECTION_ENABLED|The choice for Child Model is enabled in Therapy Settings. Please read [Enable Child Model](#enable-child-model).| -|REMOTE_OVERRIDES_DISABLED|Remote commands: override, carbs or boluses will not be accepted even if all the [Remote Command](../nightscout/remote-overview.md) requirements are configured

If you do configure this and later try to set up remote commands, they will not work and there is **no error** message. [Remote Errors: Loop REMOTE_OVERRIDES_DISABLED](../nightscout/remote-errors.md#loop-remote_overrides_disabled)| -|OBSERVE_HEALTH_KIT_CARB_SAMPLES_FROM_OTHER_APPS_ENABLED|Turns on ability for Loop to read third party carb entries. You must also make sure Health permissions allow Loop to read carbs from Health. Be vigilant if you select this; added carbs lead to added insulin dosing when closed loop is enabled| -|SHOW_EVENTUAL_BLOOD_GLUCOSE_ON_WATCH_DISABLED|The Apple Watch screens show current glucose, trend arrow and eventual glucose by default. This flag disables the display of eventual glucose on the watch if you find the display distracting.| -|PREDICTED_GLUCOSE_CHART_CLAMP_ENABLED|[Chart Clamp](#chart-clamp)| -|ALLOW_ALGORITHM_EXPERIMENTS|**dev branch only**

This is enabled by default to show Algorithm Experiments below the Therapy Settings row. This enables the user to separately enable or disable Glucose Based Partial Application and Integral Retrospective Correction| - -### Chart Clamp - -What the heck is a chart clamp? It means the range displayed will not be smaller than the clamp but it can be bigger. - -Loop automatically scales the glucose charts based on the history shown. Some people don't like to see the vertical axis changing, so they turn on the "clamp". - -When the `PREDICTED_GLUCOSE_CHART_CLAMP_ENABLED` build time flag is added: - -* the range shown is never smaller than `glucoseChartDefaultDisplayBoundClamped` -* 80 to 240 mg/dL (4.4 to 13.3 mmol/L) - -When you do not add that build time flag: - -* the range shown is never smaller than `glucoseChartDefaultDisplayBound` -* 100 to 175 mg/dL (5.6 to 9.7 mmol/L) - -If glucose within the display history is outside of the bound, the graph range expands to include that glucose level. This prevents glucose readings from being "hidden". - -You can customize chart display settings if you want. The original lines of code are shown below. You will need to read the rest of this page to figure out how to modify these to meet what you prefer. If you can't figure this out - reach out for help. - -* Module: Loop -* Loop 3 - * Folder: Loop/Models - * File: LoopConstants.swift - * Lines: 32 to 45 - -``` - // MARK - Display settings - - static let minimumChartWidthPerHour: CGFloat = 50 - - static let statusChartMinimumHistoryDisplay: TimeInterval = .hours(1) - - static let glucoseChartDefaultDisplayBound = - HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 100)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 175) - - static let glucoseChartDefaultDisplayRangeWide = - HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 60)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 200) - - static let glucoseChartDefaultDisplayBoundClamped = - HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 80)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 240) -``` - -## Instructions for Finding the Lines - -The instructions on this page were originally prepared for the Mac-Xcode method. - -The Build with Browser method instructions are similar, but each one is used edit a file using a browser in your *GitHub* account as instructed on the [Customize with Browser](../gh-actions/gh-customize.md) page. - -For each customization, you will be given landmarks to find the correct location in the code. You can choose to search using the `Key_Phrase` or navigate to the file in the folder structure and look for ( ++cmd+l++ # ) the line number. - -Some customizations are the same for all users, and do not require personalization. See [Loop and Learn: Customization: Single Customization List](https://www.loopandlearn.org/custom-code#custom-list). - -For Mac-Xcode builders: - -* Either [Key_Phrase](#key_phrase) or [Module, Folder, File](#module-folder-file) - can be used to find the lines -* Be sure to save the file when you make a change - otherwise the modification does not get built into your app -* Some folder icons show different names in Xcode, see [Folders and Icons](#folders-and-icons) - -For Build with Browser: - -* Some customizations can be copied from the [Loop and Learn: Customization: Single Customization List](https://www.loopandlearn.org/custom-code#custom-list) -* Otherwise, create your own customization for the Module identified under [Module, Folder, File](#module-folder-file) as instructed on the [Customize with Browser](../gh-actions/gh-customize.md) page - -### Key_Phrase - -``` { .txt .copy title="Example of a Key_Phrase" } -use the copy button at right, paste into search -The copy button for this exampe is just for practice -Do not paste the result anywhere -``` - -To search using the `Key_Phrase` (see graphic below for clarification): - -* A copy button is available when you hover your mouse in the right-hand side of the block below the title `Key_Phrase`; click on it to copy the phrase -* In Xcode, tap the Find menu item and select `Find in Workspace` -* Paste the text into the Find search-box that opens on upper left of Xcode screen and hit enter - * **If you don't see the phrase in the box, hit backspace - your system copied an extra return** -* You should see a message `1 result in 1 file` (for most cases) - * Some customizations will show more than one result, but that will be explained in the directions for that customization -* The file in which the line is located is reported showing the line in that file containing the `Key_Phrase` -* Click on the one you think is correct and it will display in the main middle window of Xcode with the Keyword highlighted on the line you selected - * The `Key_Phrase` was selected to limit the search to just the relevant line (if possible) - * In some cases, the `Key_Phrase` gets you close but not exactly on the line where you need to make the modifications - please read carefully - -![graphic showing how to search using the Key_Phrase](img/code-custom-xcode-search.svg){width="750"} -{align="center"} - -### Module, Folder, File - -Each customization will also show Module, Folder and File bullet below the key phrase. - - * Module: Loop - * Folder: Loop/subfolder1/subfolder2/etc. - * File: filename.swift, line number(s) - - -## Customizations: - -The customizations below show the original line of code that you will be changing. - -There may be a figure illustrating the change. - -Below the figure, the original, and in some cases, the modified code will be displayed as text. - -* Sometimes that line is long and you may need to use the scroll bar to see the entire line in LoopDocs -* In most cases, an example customization is shown to assist you in deciding how to edit the line to meet your needs - - -## Disable Authentication for Bolusing - -Depending on your iPhone Settings and model, you may have Face ID or Touch ID enabled. Those security features will also be used to authenticate bolus delivery in Loop. You can choose to disable authentication (i.e., not require Face ID, Touch ID, or passcode for bolusing) through the following code customization. - -!!! warning "Safety Measure" - If you disable this, you are removing an important safety feature. - - In addition to authenticating every manual bolus, this helps to protect against sleep bolusing and pocket bolusing. - - For Loop 3, this controls the authorization requirement to modify Therapy Settings as well as to confirm bolus delivery. - -``` { .txt .copy title="Key_Phrase" } -canEvaluatePolicy(.deviceOwnerAuthentication -``` - -* Module: LoopKit -* Loop 3 - * Folder: LoopKit/LoopKitUI/Extensions/ - * File: Environment+Authenticate.swift, Line 20 - -#### Loop 3 - -_Code Before Modification_ - - if context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) { - -_Code After Modification_ - - if false && context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) { - -#### Loop 2.2.x - -* Loop 2.2.x - * Folder: Loop/View Controllers - * File: BolusViewController.swift, Line 529 - - The screenshot below was taken with Loop v2.0 when the line number was 201; with Loop 2.2.x versions, that same code is found at line 529. Add the `false &&` as shown in the screenshot below: - -![img/custom-id.png](img/custom-id.png){width="750"} -{align="center"} - -_Code Before Modification_ - - if context.canEvaluatePolicy(.deviceOwnerAuthentication, error: nil) { - -_Code After Modification_ - - if false && context.canEvaluatePolicy(.deviceOwnerAuthentication, error: nil) { - -## Default Carb Absorption Times - -![img/carb_screen.png](img/carb_screen.png){width="200"} -{align="center"} - -Loop’s default carb absorption times are based on the high, medium, and low glycemic index absorption curves presented in *Think Like A Pancreas* by Gary Scheiner. With Loop 2.2.x, the lollipop (fast) icon is set for 2 hours, taco (medium) icon for 3 hours, and pizza (slow) icon for 4 hours. This is modified for Loop 3 to 30 minutes, 3 hours and 5 hours respectively. - -``` { .txt .copy title="Key_Phrase" } -defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes -``` - -* Module: Loop -* Loop 3 - * Folder: Loop/LoopCore - * File: LoopCoreConstants.swift - * Line: 16 - -* Loop 2.2.x - * Folder: Loop/LoopCore - * File: LoopSettings.swift - * Line: 16 (2.2.4 master), 41 (2.2.4 AB), 50 (2.2.5 and later) - - -For example, if you wanted to modify Loop 2.2.9 so that lollipop represents a 30 minute absorption and pizza a 5 hour absorption, the edit would be as follows: - - -_Code Before Modification for Loop 2.2.x_ - - public static let defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes = (fast: .hours(2), medium: .hours(3), slow: .hours(4)) - -_Code After Modification or default for Loop 3_ - - public static let defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes = (fast: .minutes(30), medium: .hours(3), slow: .hours(5)) - -Note that if you change from 2 hours to 30 minutes, you must also change the indication before the parentheses. - -## Adjust Maximum IOB for Automatic Dosing - -With version 3.2.0, a new safety feature was added. This limits automatic dosing so IOB is no more than two times the $\mathit{maximumBolus}$ set in your Delivery Limits. (The term automatic dosing refers to insulin the app automatically delivers above your scheduled basal rate.) Manual Bolus, where you initiate the bolus yourself, is not subject to this limit. Please read [How do Delivery Limits Affect Automatic Dosing?](../faqs/algorithm-faqs.md#how-do-delivery-limits-affect-automatic-dosing) for detailed information on how this safety feature works. - -The default value ($\mathit{2*maximumBolus}$) used for this feature is good for the majority of people who use the app. However, there are some individuals who might need to limit the size of any single bolus independent from the maximum IOB they want to set for their app. This is particularly true for those who find large boluses give rise to tunneling and the insulin leaks out along the cannula. - -``` { .txt .copy title="Key_Phrase" } -automaticDosingIOBLimit = maxBolus -``` - -* Module: Loop -* Folder: Loop/Managers -* File: LoopDataManager.swift, line: 1690 (main), 1796 (dev) - -The following example is for someone who limits a single bolus to 5 U but frequently needs to achieve an IOB of 15 U for meals. They want that level of IOB to be reached with automatic bolusing. In that case, they may want to modify the factor used to calculate $\mathit{automaticDosingIOBLimit}$. - -Original Code: -``` -let automaticDosingIOBLimit = maxBolus! * 2.0 -``` - -Modified Code Example: -``` -let automaticDosingIOBLimit = maxBolus! * 3.0 -``` - -Because the automatic bolus amount is also limited by the partial application factor, it still takes a few cycles to reach the higher IOB of $\mathit{3*maximumBolus}$; but they can get there without manual intervention. - -## Adjust Percent Bolus for Automatic Bolus - -If you are mostly happy with the Dosing Strategy of Automatic Bolus but wish it delivered more or less insulin during every Loop interval, then this customization is for you. - -This customization changes the percent of the recommended bolus used for automatic delivery. The method for calculating that recommendation is not changed by this modification. The default value is 40% (0.4). It is recommended you take small changes of 0.1 at a time. Once you modify it once and try it out for a while, it’s easy to go back and change it again. - -**Change just the number and double check that the value is less than 1.** - -``` { .txt .copy title="Key_Phrase" } -let bolusPartialApplicationFactor -``` - -* Module: Loop -* Loop 3 - * Folder: Loop/Loop/Models - * File: LoopConstants.swift - * Line: 53 - -_Code Before Modification_ - - static let bolusPartialApplicationFactor = 0.4 - -_Code After Modification to 50% of recommended insulin_ - - static let bolusPartialApplicationFactor = 0.5 - -!!! warning "Do not exceed 1.0" - This number should never be bigger than 1 (you’d be getting more than Loop recommends). If you think you need more than 1, consider your settings and meal entries. - -## Modify Override Insulin Needs Picker - -Some people want finer settings on the override insulin needs picker (5% instead of 10%) and may want to limit the overall range for overrides – especially for children. - -!!! tip "1% Settings Available without Customization" - With the advent of Loop 3, the Override Insulin Needs values are not limited by the default picker values of 10%. - - * Not available in Loop 2.2.x - * Not available in FreeAPS (based off Loop 2.2.x) - * [Select 1% Insulin Needs](../operation/features/overrides.md#select-1-insulin-needs) - -Any override more than a factor of 2 from 100% can cause Loop predictions to be wrong – especially if a carb count is entered. (An [override](../operation/features/overrides.md) is NOT the same as a manual temp basal - it changes insulin sensitivity factor and carb ratio in addition to the basal rate needed for zero change in IOB for the duration of the override.) - -!!! danger "A Sensitivity of 0% is NOT Valid" - Do not set the lower level of the sensitivity range to be 0%. - - If you configure to allow that and someone chooses it, they will be telling Loop to divide by zero in some of the calculations. They will see NaN (not a number) in Loop predictions until that override is removed and will continue to see that for the full duration of insulin action (6 hours). - -This example customization changes the lower bound for sensitivity to 50% (factor of 2 smaller than 100%) and provides 5% steps. - -``` { .txt .copy title="Key_Phrase" } -let allScaleFactorPercentages -``` - -* Module: LoopKit -* Folder: LoopKit/LoopKitUI/Views -* File: InsulinSensitivityScalingTableViewCell.swift, Line 19 - -_Code Before Modification_ - - private let allScaleFactorPercentages = Array(stride(from: 10, through: 200, by: 10)) - -_Code After Modification to 50% to 200% by steps of 5%_ - - private let allScaleFactorPercentages = Array(stride(from: 50, through: 200, by: 5)) - - -## Modify Maximum and Warning Carb Entry - -### Loop 3 Carb Entry Variables - -Loop 3 has both a maxCarbEntryQuantity and a warningCarbEntryQuantity, found adjacent to each other in the code. The warning value is the level at which you are asked if you really meant to enter that amount: - -``` { .txt .copy title="Key_Phrase" } -let maxCarbEntryQuantity = -``` - -* Module: Loop -* Folder: Loop/Loop/Models -* File: LoopConstants.swift, line 18 - -_Code Before Modification_ - - static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 250) // cannot exceed this value - - static let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 99) // user is warned above this value - -This first example might be used by a parent for a child with very small carb entries. - -_Code After Modification to enable the warning at lower levels and limit maximum_ - - static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 99) // cannot exceed this value - - static let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 49) // user is warned above this value - -This second example might be used by a person who routinely enters large meals and does not want to be warned with every meal. - -_Code After Modification to warn if entry is between 201 and 300g_ - - static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 300) // cannot exceed this value - - static let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 200) // user is warned above this value - -### Loop 2.2.x Max Carb Entry - -Users of Loop 2.2.9 and earlier or FreeAPS must use the following method for modifying maximum carb entry: - -Some people want to limit the maximum number of carbs that can be entered in one entry – especially for children or folks who eat lower carb. This helps prevent accidental typos, e.g., entry of 115 g instead of 15 g for a meal. - -``` { .txt .copy title="Key_Phrase" } -maxQuantity = -``` - -As shown in the graphic below, this phrase shows up in 2 places, only the first one should be modified. - -![xcode display showing the key phrase found in 2 places](img/xcode-modify-max-carb-entry.svg){width="700"} -{align="center"} - - -* Loop 2.2.x - * Folder: Loop/Loop/View Controllers - * File: CarbEntryViewController.swift, Line 33 (Loop 2.2.x) - -_Code Before Modification_ - - var maxQuantity = HKQuantity(unit: .gram(), doubleValue: 250) - -_Code After Modification to limit carb entry to 99 g_ - - var maxQuantity = HKQuantity(unit: .gram(), doubleValue: 99) - -## Pods: Add Extra Insulin on Insertion - -The default value is 0.0 U of extra insulin. If you use this customization, start with a small number and work your way up. If you are coming from manual podding and routinely gave yourself an extra bolus with your PDM at pod change time, you may not need nearly as much with Loop - be conservative. - -Note that Loop does not include the amount of insulin in the prime or insertion steps in your IOB. The pod reports every pulse that it delivers to Loop. If you look in the Pod Settings insulin delivered row, that is the total delivered by the pod minus the (prime plus insertion) amounts. The only way to know that you successfully made this change is to count the clicks. Normal insertion is 0.5 U (0.5 U / 0.05 U per click = 10 clicks). So if you add 0.35 U to the "extra" value, you should get 0.35 / 0.05 = 7 extra clicks. In other words, 17 total clicks after you press insert. - -This code change is found in one location for Eros Pods (called Omnipod throughout the app) and DASH Pods (called Omnipod Dash throughout the app). I tend to change both files, but if you're only using one kind of pod, that is really not necessary. - -``` { .txt .copy title="Key_Phrase" } -let cannulaInsertionUnitsExtra -``` - -* Module: OmniBLE (DASH) or OmniKit (Eros) -* DASH or Eros Pod (Loop 3 only) - * Folder: OmniBLE/OmniBLE/OmnipodCommon (DASH) - * Folder: OmniKit/OmniKit/OmnipodCommon (Eros) - * File: Pod.swift, Line 82 (DASH); Line 87 (Eros); -* Loop 2.2.x: Eros Pod (still configured in rileylink_ios - use Key_Phrase) - -_Code Before Modification_ - - public static let cannulaInsertionUnitsExtra = 0.0 // edit to add a fixed additional amount of insulin during cannula insertion - -_Code After Modification to add 0.35 U_ - - public static let cannulaInsertionUnitsExtra = 0.35 // edit to add a fixed additional amount of insulin during cannula insertion - -## Modify the Guardrails - -The [Therapy Setting Guardrails](../loop-3/therapy-settings.md#guardrails-for-settings) are for Loop 3 only. - -### Glucose Guardrails - -If you build Loop 3 over a version of Loop 2.2.x or FreeAPS where the Correction Range is lower than the default value of 87 mg/dL (4.8 mmol/L), your app requires you to satisfy the new guardrail before you can save that Therapy Setting when you onboard. - -``` { .txt .copy title="Key_Phrase" } -Guardrail(absoluteBounds: -``` - -* Module: LoopKit -* Folder: LoopKit/Extensions -* File: Guardrail+Settings.swift -* Line: 12 for suspendThreshold -* Line: 26 for correctionRange - -_Code Before Modification_ - - static let suspendThreshold = Guardrail(absoluteBounds: 67...110, recommendedBounds: 74...80, unit: .milligramsPerDeciliter, startingSuggestion: 80) - -and - - static let correctionRange = Guardrail(absoluteBounds: 87...180, recommendedBounds: 100...115, unit: .milligramsPerDeciliter, startingSuggestion: 100) - -Modify the 67 for suspendThreshold or 87 for correctionRange to the desired value. Loop automatically converts from mg/dL. So you must enter values reasonable for mg/dL (18 times higher than for mmol/L). - -### Modify Guardrails for Insulin Sensitivity Factor (ISF) - -Similar to the instructions for glucose guardrails above, but use this `Key_Phrase` and modify the absoluteBounds row, next line. - -``` { .txt .copy title="Key_Phrase" } -static let insulinSensitivity = Guardrail( -``` - -* Module: LoopKit -* Folder: LoopKit/Extensions -* File: Guardrail+Settings.swift, line: 81 - -### Modify Guardrails for Carb Ratio (CR) - -Similar to the instructions for glucose guardrails above, but use this `Key_Phrase` and modify the absoluteBounds row, next line. - -``` { .txt .copy title="Key_Phrase" } -static let carbRatio = Guardrail( -``` - -* Module: LoopKit -* Folder: LoopKit/Extensions -* File: Guardrail+Settings.swift, line: 88 - - -## Adjust Future Carbs Time Interval - -Loop 3 limits the future time change allowed to 1 hour. - -``` { .txt .copy title="Key_Phrase" } -cell.datePicker.maximumDate = date.addingTimeInterval -``` - -* Module: Loop -* Folder: Loop/Loop/View Controllers -* File:CarbEntryViewController.swift, Line 438 - -Default shown below (for maximum and minimum): - -_Code Before Modification_ - - cell.datePicker.maximumDate = date.addingTimeInterval(.hours(1)) - cell.datePicker.minimumDate = date.addingTimeInterval(.hours(-12)) - -Change the maximumDate to the number of hours in the future you desire. Remember that Loop may increase insulin dosing for future carbs - make sure that they actually arrive. - -The minimumDate is how far back in the past you can modify time. The default is 12 hours in the past. - -## Adjust the Watch Crown Sensitivity - -The rate of change of the carb and bolus entry pickers when using the digital crown can be altered as can the rotation required to confirm a bolus on the watch. If you are running an older series watch - you may want to make these customizations. When I switched from Series 3 to Series 7 watch - it was amazing. I got a graph on the main watch screen I didn't even know existed and the bolus acceptance was a breeze! - -There are a number of places where you need to make changes (2 for sensitivity and 2 for bolus confirmation for Loop 2.2.x), so walk though them one at a time. For the `Watch Crown Sensitivity`, the 1/24 value is the ratio of rotations of the crown to the amount of change in the value. Changing it to 1/12 would mean that half as many turns would be needed for the same amount of carb or bolus entry. - -* The Loop 2.2.x customizations are throughly tested by many users. -* The Loop 3 customization is provided from code inspection and one test - use with care. - -### Loop 2.2.x Sensitivity - - -``` { .txt .copy title="Key_Phrase" } -let rotationsPerIncrement -``` - -* Folder: Loop/WatchApp Extension/Controllers -* File: AddCarbsInterfaceController.swift, Line: 249 -* Initial Value: 1/24; try 1/12 to increase change in picker value for a given motion - -![img/sensitivity1.png](img/sensitivity2.png){width="800"} -{align="center"} - -``` { .txt .copy title="Key_Phrase" } -let rotationsPerValue -``` - -* Folder: Loop/WatchApp Extension/Controllers -* File: BolusInterfaceController.swift, Line: 191 -* Initial Value: 1/24; try 1/12 to increase change in picker value for a given motion - -![img/sensitivity1.png](img/sensitivity1.png){width="800"} -{align="center"} - -### Loop 2.2.x Bolus Confirmation - -In order to reduce the amount the user has to spin the watch crown to confirm a bolus, there are 3 numbers on 2 lines that must be modified. You will be working in the same file you just used to modify the watch sensitivity to adjusting the bolus amount, BolusInterfaceController.swift. - -For example to change rotation required to 70% of the default, change 1.0 to 0.7 in 3 places on those 2 lines. This `Key_Phrase` returns 3 lines, the second 2 of which are the ones in that file where the change is required: - - -``` { .txt .copy title="Key_Phrase" } -abs(accumulatedRotation) -``` - -* Folder: Loop/WatchApp Extension/Controllers -* File: BolusInterfaceController.swift, Lines: 311 and 360 -* Initial Value: 1.0; try 0.7 to decrease how much is needed to confirm bolus - -### Loop 3 Digital Crown Adjustments - -These are new instructions and the user should take care - and please [report back](../intro/loopdocs-how-to.md#how-to-find-help) if you have problems. - -First - try it with no customization. Then make small changes. - -This key phrase will indicate three different files in the same folder as shown in the graphic below - you can adjust each in turn as you desire. When you click on the line, the quantity you change is a few lines below where you find the `Key_Phrase`, except for the CarbAndDateInput file. - -``` { .txt .copy title="Key_Phrase" } -.digitalCrownRotation -``` - -* Module: Loop -* Folder: Loop/WatchApp Extension/Views/Carb Entry & Bolus - -![use a single Key_Phrase to identify all lines needed to customize sensitivity with loop 3](img/digital-crown-rotation.svg){width="800"} -{align="center"} - -#### Modify Bolus Confirmation Motion - -* File: BolusConfirmationView.swift, line 59 -* Initial Value for `scalingRotationBy` is 4 -* Decrease to require less motion to confirm bolus (use whole numbers only), start with 3 - -#### Modify Bolus Picker Sensitivity - -* File: BolusInput.swift, line 53 -* Initial Value for `rotationsPerIncrement` is 1/24 -* A change to 1/12 increases the change in picker value for a given motion - -#### Modify Carb and Time Picker Sensitivity - -* File: CarbAndDateInput.swift, line 68 -* Initial Value for `rotationsPerIncrement` is 1/24 -* A change to 1/12 increases the change in picker value for a given motion - - -## Expiration Notification Customization - -An expiration notification feature has been added to Loop. You get a notification when you open the Loop app to alert you that the expiration is approaching. (Not available with version v2.2.4 and earlier.) - -* Read [Loop App Expiration Notification](../operation/features/notifications.md#loop-app-expiration-notification) to see the expiration reminder -* Read [Loop App Expiration Date](../operation/features/notifications.md#loop-app-expiration-date) if you have an older version of Loop - -If you prefer a different notification time and frequency, there are two lines you can modify: - -* Module: Loop -* Folder: Loop/Managers -* File: ProfileExpirationAlerter.swift - * Line 16: modify how long before expiration you get the FIRST notification - * Line 28: modify how frequently you will be notified - -``` { .txt .copy title="Key_Phrase" } -expirationAlertWindow: TimeInterval -``` - -``` { .txt .copy title="Key_Phrase" } - minimumTimeBetweenAlerts: TimeInterval -``` - -![Profile expiration notification details](img/expiration-custom.png){width="600"} -{align="center"} - -Default code for line 16: -``` - static let expirationAlertWindow: TimeInterval = .days(20) -``` - -Example modifications to First Notification: - -* 30 days: change `.days(20)` to `.days(30)` -* 12 hours: change `.days(20)` to `.hours(12)` - -Default code for line 28: - -``` - let minimumTimeBetweenAlerts: TimeInterval = timeUntilExpiration > .hours(24) ? .days(2) : .hours(1) -``` - - -Modify Frequency of Repeated Notifications (Three Values): - -* This phrase: ```> .hours(24) ? .days(2) : .hours(1)``` -* Rewritten as: ```> Time_A ? Frequency_A : Frequency_B```, means: - * Use Frequency_A if there is more time between now and the expiration date than Time_A - * Use Frequency_B if there is less time between now and the expiration date than Time_A - -You can enter Time or Frequency as ```.days(value)```, ```.hours(value)``` or ```.minutes(value)```. - -Free App Users: - -An example change that a Free Loop App user (who has to build once a week) might choose is: - -``` - > .hours(4) ? .days(10) : .hours(2) -``` -Combined with an ```.hours(12)``` on line 16, they would get notified at 12 hours, 4 hours and 2 hours before expiration on the day of expiration and only when the app is opened. Since you'll be building once a week, you can play around with these values until you are happy. - -## Exponential Insulin Curve - -### Enable Child Model - -Loop 3, by default, does not include the concept of child versus adult for rapid-acting insulin, i.e., Humalog, Novalog and Apidra. - -* The child model can be enabled following the directions in [Build-Time Features](#build-time-features), adding ADULT_CHILD_INSULIN_MODEL_SELECTION_ENABLED to the LoopConfigOverride.xcconfig file and rebuilding -* Insulin Model is then found in the Therapy Setting section of Loop 3 with Adult selected by default -* Insulin Type continues to be associated with the pump and can be modified in the Pump Settings screen - -### Insulin Model Customization - -Each exponential model has 3 parameters that can be adjusted: - -* actionDuration: Duration of insulin activity (minutes) -* peakActivity: Peak of insulin activity (minutes) -* delay: Delay before insulin begins to acts after delivery starts (minutes) - -Please read the nitty-gritty discussion that went into the development of the "exponential insulin models" in this [Comment](https://github.com/LoopKit/Loop/issues/388#issuecomment-317938473). - -If you wish to customize these values, please make sure you know what you are doing. This is not a modification recommended for Loop novices. - -``` { .txt .copy title="Key_Phrase" } -MARK: - Model generation -``` - -* Module: LoopKit -* Loop 3 - * Folder: LoopKit/LoopKit/Insulin/ << NOTE new location - * File: ExponentialInsulinModelPreset.swift - * Lines: - * actionDuration (19 to 32) - * peakActivity (34 to 47) - * delay (49 to 62) -* Loop 2.2.x - * Folder: Loop/LoopCore/Insulin - * File: ExponentialInsulinModelPreset.swift - * Lines: - * actionDuration (20 to 29) - * peakActivity (31 to 40) - * effectDelay (42 to 51) - -![img/exponential.png](img/exponential.png){width="750"} -{align="center"} - -This Loop 3 table of default values is provided for convenience. The times are all in minutes. - -|Model|DIA|Peak|Delay| -|---------|---------|---------|---------| -|rapidActingAdult|360|75|10| -|rapidActingChild|360|65|10| -|fiasp|360|55|10| -|lyumjev|360|55|10| -|afrezza|300|29|10| - - -## Loop Logo - -!!! warning "Mac-Xcode Instructions" - This can be done with Build with Browser but the instructions might need to be adjusted for that case. - -If you want an app logo other than the default green circle for your Loop app, you can easily customize this. To make it easy to generate the correct sizes of icons, you can use a site like [appicon.build](http://www.appicon.build/) or [appicon.co](https://appicon.co/) and just drag and drop your source image. The source image needs to be 1024 pixels x 1024 pixels. The site will email you a zip file or automatically download a set of files. Highlight and copy the contents of the Appicon.appiconset that you are sent, including the Contents.json file - -Use Finder to Navigate to the LoopWorkspace folder. These instructions assume you used the Build Select Script - if your files are in a different folder, make the appropriate adjustment. - -For Loop 2.2.x: - -1. Use Finder to navigate to Downloads / BuildLoop and open the folder with the most recent date (e.g., Loop-Master-211006-0524) -1. Double-click on the LoopWorkspace folder -1. Double-click on the AdditionaAssets.xcassets folder -1. Double-click on the CustomLoopIcon.appiconset folder -1. Delete the contents of the CustomLoopIcon.appiconset folder and copy/paste your new images and Contents.json file. -1. Rebuild your app - -For Loop 3: - -1. Make sure Xcode is closed -1. Use Finder to navigate to Downloads / BuildLoop and open the folder with the most recent date (e.g., Loop-230114-1153) -1. Double-click on the LoopWorkspace folder -1. Double-click on the OverrideAssetsLoop.xcassets folder -1. Double-click on the AppIcon.appiconset folder -1. Delete the contents of the Appicon.appiconset and copy/paste your new images and Contents.json file. -1. Rebuild your app - -You may see a yellow warning that there are “unassigned children” depending on the images the app icon generator tool produced. The unassigned children alert will not prevent your app from building, it’s simply because there are more sizes of images than Loop app uses. You can just leave the unassigned children alone (wow...how often do you get to say that phrase?). - -And now you'll be the proud new owner of a custom Loop icon. - -## Open a Terminal in LoopWorkspace Folder - -If you use the [Loop and Learn: Customization Select Script](https://www.loopandlearn.org/custom-code), it automatically locates your most recent download, makes the customization you select in that download and then opens Xcode for you. - -But sometimes, you need to find your downloaded code and make your own changes in Xcode. This section tells you how to do this. - -Refer to the graphic below. The Downloads folder in Finder is highlighted on the upper left. The full path to Loop.xcworkspace is highlighted along the bottom. Double clicking on that file opens Xcode; but to apply customizations, you need to type commands in the terminal. - -* Open Finder -* Navigate to Downloads/BuildLoop and look for your download by name and date -* Open that folder, for example, Downloads/BuildLoop/Loop-220803-1145 -* Find the LoopWorkspace folder icon (dashed-blue rectangle) -* Hold down the CTRL key and click (or right-click) LoopWorkspace -* A menu appears - select `New Terminal at Folder` (near the bottom of the list) - -This new terminal window is ready to accept commands as needed when the instructions say to start a terminal in the LoopWorkspace folder. - -To confirm you are in the correct location, type `pwd` and return in the terminal. The response must end in LoopWorkspace. For example, using the graphic below, the response to `pwd` should be similar to: - -` -/Users/marion/Downloads/BuildLoop/Loop-20220803-1145/LoopWorkspace -` - -![how to use finder to find the correct download and open xcode](img/finding-loopworkspace.svg){width="750"} -{align="center"} - -## Additional Customizations for Loop 3 - -Some customizations on this page add support for Libre CGM. If you are willing to build a dev branch, then Libre CGM support is already added to that version. Please read [Support for Libre Sensors](../version/development.md#support-for-libre-sensors). - -### Custom Type One LoopPatches - -**If you do not already use this set of customizations, please do not start. These will not be available for the next release of code.** - -Several items were consolidated into a set of patches known as [CustomTypeOne LoopPatches](https://www.loopandlearn.org/custom-type-one-loop-patches). The easiest way to get CustomTypeOne LoopPatches is to use the [Loop and Learn: Customization Select Script](https://www.loopandlearn.org/custom-code#custom). This script can be used with either Mac-Xcode or Build with Browser methods and is compatible up through Loop 3.2.x and dev; but will be not be offered with the next release. - -Please read the documentation and test any patch that you enable. These patches don't have the nice guardrails found in Loop 3 and must be configured at the iOS Settings, Loop interface. They cannot be adjusted inside the Loop app. - -## Libre Support for Loop 3.2.x Code - -!!! tip "Libre included in dev branch" - Libre support is now included in dev branch, which will soon be released as Loop 3.4. - - If you are willing to [build Loop-dev](../version/build-dev.md), you do not need any of these customizations to use a compatible Libre sensor. - -### Add Libre App to Loop Phone - -LibreTransmitter for Loop is already included in the dev branch. [README file for LibreTransmitter](https://github.com/dabear/LibreTransmitter#libretransmitter-for-loop). If you [Build Loop-dev](../version/build-dev.md), you do not need to add a Libre app to your phone. - -You must do your own research to decide which code to use. Be aware that you must perform careful calibrations to maintain accurate glucose estimates. - -These are Libre iOS app options that work with Loop 3.2.x. In other words, you install one of these CGM apps on your phone **and** modify Loop 3.2.x to interface with the CGM app using a shared App Group. - -* xDrip4iOS: [Documentation](https://xdrip4ios.readthedocs.io/en/latest/) - * Check to see if your sensor is [compatible](https://xdrip4ios.readthedocs.io/en/latest/#compatible-sensors) - * To use this code with Loop, you must "build it yourself" with the same developer ID as you use with Loop - * You can use the [Loop and Learn: Build Select Script](https://www.loopandlearn.org/build-select/) and choose Option 2: Build Related Apps and then select xDrip4iOS - * If you use the TestFlight installation method with someone else's apple developer id, you will need an internet connection to Loop -* GlucoseDirect: [README file for GlucoseDirect](https://github.com/creepymonster/GlucoseDirect#glucose-direct) - * To use this code with Loop, you must "build it yourself" with the same developer ID as you use with Loop - * You can use the [Loop and Learn: Build Select Script](https://www.loopandlearn.org/build-select/) and choose Option 2: Build Related Apps and then select GlucoseDirect - * If you use the TestFlight installation method with someone else's apple developer id, you will need an internet connection to Loop - -### Modify Loop to use Libre - -There are some commands to use with Build with Browser or with Mac-Xcode that add an interface to these CGM inside Loop. But this is valid only up through version 3.2.x. - -* [Add CGM Clients: Build with Browser](https://www.loopandlearn.org/custom-code/#add-lnl-patches) -* [Add CGM Clients: Mac-Xcode](https://www.loopandlearn.org/custom-code/#add-cgm-323) - -These customizations are only for Loop 3.2.x. They do not work for the dev branch, soon to be released as Loop 3.4. - -### LibreTransmitter - -LibreTransmitter is included in Loop dev and will be in Loop 3.4 when it is released: - -* LibreTransmitter for Loop: [README file for LibreTransmitter](https://github.com/dabear/LibreTransmitter#libretransmitter-for-loop) - * LibreTransmitter is incorporated into Loop directly, so there not a separate app to be installed - * See [BuildLoopDev Script](../version/build-dev.md#buildloopdev-script) - -## Limit Loop for Faster CGM - -The released code of Loop 3 (3.0.0 through 3.2.3) allows Loop to run at higher rates of CGM updates. One consequence of this can be increased usage of pump batteries. This can contribute to pod faults with Eros pods or even DASH pods when using a Libre sensor with 1-minute CGM updates. Medtronic pumps are very unhappy with faster Loop cycles and should not be subjected to this. - -This modification limits the period for Loop cycles to 4.2 minutes or longer. See also [Loop and Learn: Customization List](https://www.loopandlearn.org/custom-code#custom-list). - -!!! important "If your CGM updates at 1-minute rates, please add this customization" - This customization is consistent with the code currently in the dev branch, soon to be released as Loop 3.4. - - This is only needed for Loop 3.2.2 and earlier versions. - -* When using Build with Browser, please refer to [Loop and Learn: Code Customization: Prepared Customizations](https://www.loopandlearn.org/custom-code#prepared-custom-list) - -* When building with Mac-Xcode, copy the command (below), paste into a terminal window on the Mac and choose `Limit CGM driven Loop Cycle to 5 minutes`: - -``` { .txt .copy title="Customization Select script" } -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/CustomizationSelect.sh)" -``` - -## Folders and Icons - -The folders listed in the code customization steps are the actual directory names as stored on your computer. However, a shortened name is used for some folders when being displayed as icons in Xcode. Some people prefer to search through the folder icons to find a file instead of using the `Find in Workspace` feature. - -In the graphic below, the user searched for an item found for both Eros and DASH pods (in two different files). The top part of the graphic shows the result of the search with user clicking on one instance. On the right side of the top graphic (highlighted by red rectangle) is the name of the selected file on the computer with the full directory name. - -* Inset 1: User clicked on the folder icon (highlighted by red square) to see the list of icons for folders included in the LoopWorkspace -* Inset 2: User opens folders under RileyLink icon to open OmniKit, then OmnipodCommon to find the Pod.swift file (NOTE - the Eros information is in a different Module now, OmniKit, but the graphic has not been updated.) - -![graphic showing folder icons vs folder names](img/xcode-folder-names.svg){width="750"} -{align="center"} - -These folder icon names are different from the directory names on the computer: - -| Folder Icon Name | Directory Name | | -|:--|:--|| -| ShareClient | dexcom-share-client-swift | -| RileyLink | rileylink_ios | -| Amplitude | Amplitude-iOS | - -All other icons and directory names match. - diff --git a/docs/build/community.md b/docs/build/community.md index f65174c8184..7fe0ae79816 100644 --- a/docs/build/community.md +++ b/docs/build/community.md @@ -80,11 +80,11 @@ Now you are ready to build or continue with setting up the *Loop* app. If you are a new looper who got to these pages from the Set Up app page - congratulations. Now that you've reviewed these introductory pages, please continue with the [Brand New Loopers](../loop-3/loop-3-overview.md#brand-new-loopers) section of the Set Up Overview page. -### Browser Build +### Build with Browser -Click here if you want to build with github build actions: [Browser Build](../gh-actions/gh-overview.md) +Click here if you want to [Build with Browser](../gh-actions/gh-overview.md). -### Mac-Xcode Build: +### Build with *Mac*: -Click here if you want to build on a Mac using Xcode: [Mac-Xcode Build](../build/overview.md) +Click here if you want to [Build with *Mac*](../build/overview.md). diff --git a/docs/build/computer.md b/docs/build/computer.md index 71157598bb8..5b53ee2ae7b 100644 --- a/docs/build/computer.md +++ b/docs/build/computer.md @@ -18,17 +18,17 @@ - You need a [compatible Pump](pump.md) and [CGM](cgm.md) if you want to actually use the app (and not just explore the app) !!! abstract "Summary" - Your computer, iPhone and Xcode must have compatible versions to build Loop using Mac-Xcode. + Your computer, iPhone and Xcode must have compatible versions to build the *Loop* app using a *Mac*. * A summary list of [Compatible Versions](#compatible-versions) is found on this page with more detail in a later page - If you are buying a Mac specifically to use the Mac-Xcode build method, chose one with capabably of being updated to the Sonoma (macOS 14) operating system and at least 256 GB (512 GB is better). The Build with Browser method works on any computer or tablet. + If you are buying a Mac specifically to use the build with *Mac* method, chose one with capabably of being updated to the Sonoma (macOS 14) operating system and at least 256 GB (512 GB is better). The Build with Browser method works on any computer or tablet. !!! question "FAQs" - **"Do I need a Mac or Virtual Machine?."** Not any more! You can build [Loop 3](../gh-actions/gh-overview.md) with any browser on any computer. - - **"I want to use the Mac-Xcode build method. Can I use a PC or Windows computer? I don't own an Apple computer."** Yes, you can. Please read this FAQ about using a [Virtual Machine](../faqs/FAQs.md#can-i-use-a-pc-or-windows-computer-to-build). - - **"How often do I need to use the computer if I choose the Mac-Xcode build method?"** Computer access is required when + - **"I want to use the build with *Mac* method. Can I use a PC or Windows computer? I don't own an Apple computer."** Yes, you can but only if your PC uses Intel chips. Please read this FAQ about using a [Virtual Machine](../faqs/FAQs.md#can-i-use-a-pc-or-windows-computer-to-build). + - **"How often do I need to use the computer if I choose the build with *Mac* method?"** Computer access is required when * Initially installing the Loop app * Loop app expires (Annually for a paid account or weekly for a free account) * Updating to a newer Loop release @@ -42,7 +42,7 @@ The current development version and the next release of _Loop 3.2.3. If your macOS or Xcode version is higher, you can build with Mac-Xcode. +The table below lists the **minimum** requirements to build the current release of Loop 3.2.3. If your macOS or Xcode version is higher, you can build with *Mac*. Find your phone iOS in the table below. If your iOS is not listed, e.g., 16.6, choose the first row that is less than your iOS. @@ -55,7 +55,7 @@ Find your phone iOS in the table below. If your iOS is not listed, e.g., 16.6, c !!! warning "iOS Dictates Your Computer Needs" - The more up-to-date you keep your phone iOS, the more up-to-date your computer and macOS needs to be to build Loop with the Mac-Xcode build method. A new build is required at least once a year. More information on iOS is on the [Xcode Version](xcode-version.md#how-do-all-the-minimum-versions-relate-to-each-other) page. + The more up-to-date you keep your phone iOS, the more up-to-date your computer and macOS needs to be to build the *Loop* app with the *Mac* build method. A new build is required at least once a year. More information on iOS is on the [Xcode Version](xcode-version.md#how-do-all-the-minimum-versions-relate-to-each-other) page. There are important security updates that go along with iOS updates. Please install those iOS updates as soon as you can. @@ -89,7 +89,7 @@ If you are evaluating a used computer, it's best to have at least 256 GB total d ## Which Macs Are Compatible with macOS Ventura? -Ventura is required for building Loop on a phone running iOS 16.4 or higher with the Mac-Xcode method. You can install Ventura on the following: +Ventura is required for building the *Loop* app on a phone running iOS 16.4 or higher with the *Mac* method. You can install Ventura on the following: * MacBook Pro introduced in 2017 or later * MacBook Air introduced in 2018 or later @@ -110,4 +110,4 @@ Look into building with [GitHub Actions](../gh-actions/gh-overview.md) - no need If you already have an [Apple Developer ID](apple-developer.md) or you are using a free ID, next step is [Xcode Version](xcode-version.md). !!! warning "Free ID" - The free ID method only works when using the Mac-Xcode build method. The [Browser Build](../gh-actions/gh-overview.md) method requires a paid developer ID ($99/year) but does not require a Mac computer. + The free ID method only works when using the build with *Mac* method. The [Build with Browser](../gh-actions/gh-overview.md) method requires a paid developer ID ($99/year) but does not require a Mac computer. diff --git a/docs/build/custom-mac.md b/docs/build/custom-mac.md new file mode 100644 index 00000000000..9ecf6a42201 --- /dev/null +++ b/docs/build/custom-mac.md @@ -0,0 +1,51 @@ +## Overview + +**This page is only relevant when building with a Mac.** + +**For Building with a Browser, please see: [Customize using Browser](../gh-actions/custom-browser.md)** + +For new Loopers, please build the code before you make any changes. Start with Open Loop and familiarize yourself with the interface. Later, you can make the customization(s) you desire and build again. The second build will be much easier than your first build. + +These customizations require you to modify the code used to build the *Loop* app and then build the app again with the modified code. + +!!! warning "You take responsibility" + You are responsible when you decide to use customizations. + + Be sure to report what changes you made if you need to ask for assistance with your app. + +## Customizations Prepared for You + +Some customizations are the same for everyone and have been prepared for easy use. + +The *Loop and Learn* team commit to maintaining these prepared customizations and provide an easy method to add your selection from these customization to your version of *Loop*. + +Please read the documentation for these on the [Loop and Learn: Customization Select Page](https://www.loopandlearn.org/custom-code): + +* [List of Customizations Available](https://www.loopandlearn.org/custom-code/#custom-list) +* [Customization Select Script](https://www.loopandlearn.org/custom-code/#customization-select) + +### Add Libre Support to 3.2.3 + +If you are using `main` branch to build `Loop 3.2.3` and rely on either *xDrip4iOS* or *GlucoseDirect* to read your CGM and transfer the readings to the *Loop* app, you need to review this [section of the *Loop and Learn* customization page](https://www.loopandlearn.org/custom-code/#add-cgm-323). + +Alternatively, you can switch to the `dev` branch, which already supports Libre. [Build Loop dev with Mac](build-dev-mac.md) + +## Personal Customizations + +Some customizations must be created for yourself. These are of two basic types: Custom Edits and Build-Time Flag. + +The information needed to modify the code to make these customizations is found in the Versions tab because the information is independent of build method (think of these as your personal versions). The links are found below. + +* [Version: Custom Edits](../version/code-custom-edits.md) + * The page linked above indicates how you can modify behavior by editing the code +* [Version: Build-Time Flag](../version/build-time-flag.md) + * By enabling or disabling features controlled by a Build-Time Flag, you are turning on or off features included in the code by the developers that they configured to be off or on by default + * Please read about these flags on the page linked above + +When preparing these personal edits using a *Mac*, there is a page explaining how to open *Xcode* to the correct folder (where code is stored on your *Mac*) and incorporate those changes into your personal copy of `LoopWorkspace` on your Mac before building. + +* [Custom Edits with Mac](edit-mac.md) + +## Details at Links + +The code changes required for these customizations are the same regardless of the build method. The pages that provide the documentation on modifying and incorporating these changes are found at the links above. diff --git a/docs/build/edit-mac.md b/docs/build/edit-mac.md new file mode 100644 index 00000000000..2eb7c33ac94 --- /dev/null +++ b/docs/build/edit-mac.md @@ -0,0 +1,121 @@ +## Overview + +When applying a customization using *Mac*, the downloaded code should be fairly recent. If you are not sure, get a fresh download. If you know your downloaded code is the [Current Release](../version/releases.md#current-release), you can skip the download and use the same folder as last time. + +### Find My Downloaded Loop Code + +Refer to the graphic below. The Downloads folder in Finder is highlighted on the upper left. The full path to Loop.xcworkspace is highlighted along the bottom. + +!!! success "Loop to LoopWorkspace" + Note that the directory `Loop.xcworkspace` has been renamed to `LoopWorkspace.xcworkspace` in the released code. For experienced builders - you realize this is good because the build process is easier. + + The words were updated, but it will take time for the graphics to be updated. + +* Open Finder +* Navigate to Downloads/BuildLoop and look for your download by name and date +* Open that folder, for example, Downloads/BuildLoop/Loop-220803-1145, and inside that folder open the LoopWorkspace folder +* Inside the Downloads/BuildLoop/Loop-220803-1145/LoopWorkspace folder, double-click on LoopWorkspace.xcworkspace (graphic not updated yet) +* Xcode automatically opens to that particular download +* You can then make the customizations and build to your phone + +![how to use finder to find the correct download and open xcode](img/finding-loopworkspace.svg){width="750"} +{align="center"} + +!!! tip "Experienced Builders" + Experienced builders will often build a fresh download to a simulator for their phone iOS (not their phone) to ensure download is good and is compatible with macOS, Xcode and phone iOS. Once the build is successful, they apply their customizations and build again to the simulator. Last step is to build the customized version to their real phone. + +## Instructions for Finding the Lines + +For each customization, you are given landmarks to find the correct location in the code when you review [Version: Custom Edits](../version/code-custom-edits.md). You can choose to search using the `Key_Phrase` or navigate to the file in the folder structure and look for ( ++cmd+l++ # ) the line number. + +* Either [Key_Phrase](#key_phrase) or [Module, Folder, File](#module-folder-file) + can be used to find the lines +* Be sure to save the file when you make a change - otherwise the modification does not get built into your app +* Some folder icons show different names in Xcode, see [Folders and Icons](#folders-and-icons) + +### Key_Phrase + +``` { .txt .copy title="Example of a Key_Phrase" } +use the copy button at right, paste into search +The copy button for this exampe is just for practice +Do not paste the result anywhere +``` + +To search using the `Key_Phrase` (see graphic below for clarification): + +* A copy button is available when you hover your mouse in the right-hand side of the block below the title `Key_Phrase`; click on it to copy the phrase +* In Xcode, tap the Find menu item and select `Find in Workspace` +* Paste the text into the Find search-box that opens on upper left of Xcode screen and hit enter + * **If you don't see the phrase in the box, hit backspace - your system copied an extra return** +* You should see a message `1 result in 1 file` (for most cases) + * Some customizations will show more than one result, but that will be explained in the directions for that customization +* The file in which the line is located is reported showing the line in that file containing the `Key_Phrase` +* Click on the one you think is correct and it will display in the main middle window of Xcode with the Keyword highlighted on the line you selected + * The `Key_Phrase` was selected to limit the search to just the relevant line (if possible) + * In some cases, the `Key_Phrase` gets you close but not exactly on the line where you need to make the modifications - please read carefully + +![graphic showing how to search using the Key_Phrase](img/code-custom-xcode-search.svg){width="750"} +{align="center"} + +### Module, Folder, File + +Each customization will also show Module, Folder and File bullet below the key phrase. + + * Module: Loop + * Folder: Loop/subfolder1/subfolder2/etc. + * File: filename.swift, line number(s) + +## Open a Terminal in LoopWorkspace Folder + +If you use the [Loop and Learn: Customization Select Script](https://www.loopandlearn.org/custom-code), it automatically locates your most recent download, makes the customization you select in that download and then opens Xcode for you. + +But sometimes, you need to find your downloaded code and make your own changes in Xcode. This section tells you how to do this. + +Refer to the graphic below. The Downloads folder in Finder is highlighted on the upper left. The full path to Loop.xcworkspace is highlighted along the bottom. Double clicking on that file opens Xcode; but to apply customizations, you need to type commands in the terminal. + +* Open Finder +* Navigate to Downloads/BuildLoop and look for your download by name and date +* Open that folder, for example, Downloads/BuildLoop/Loop-220803-1145 +* Find the LoopWorkspace folder icon (dashed-blue rectangle) +* Hold down the CTRL key and click (or right-click) LoopWorkspace +* A menu appears - select `New Terminal at Folder` (near the bottom of the list) + +This new terminal window is ready to accept commands as needed when the instructions say to start a terminal in the LoopWorkspace folder. + +To confirm you are in the correct location, type `pwd` and return in the terminal. The response must end in LoopWorkspace. For example, using the graphic below, the response to `pwd` should be similar to: + +` +/Users/marion/Downloads/BuildLoop/Loop-20220803-1145/LoopWorkspace +` + +![how to use finder to find the correct download and open xcode](img/finding-loopworkspace.svg){width="750"} +{align="center"} + +## Modify and Save + +* Either `Key_Phrase` or `Module, Folder, File` method described on [Version: Custom Code Edits](../version/code-custom-edits.md) can be used to find the lines inside *Xcode* on your *Mac* +* Be sure to save the file when you make a change - otherwise the modification does not get built into your app +* Some folder icons show different names in Xcode, see [Folders and Icons](#folders-and-icons) + + +## Folders and Icons + +The folders listed in the code customization steps are the actual directory names as stored on your computer. However, a shortened name is used for some folders when being displayed as icons in Xcode. Some people prefer to search through the folder icons to find a file instead of using the `Find in Workspace` feature. + +In the graphic below, the user searched for an item found for both Eros and DASH pods (in two different files). The top part of the graphic shows the result of the search with user clicking on one instance. On the right side of the top graphic (highlighted by red rectangle) is the name of the selected file on the computer with the full directory name. + +* Inset 1: User clicked on the folder icon (highlighted by red square) to see the list of icons for folders included in the LoopWorkspace +* Inset 2: User opens folders under RileyLink icon to open OmniKit, then OmnipodCommon to find the Pod.swift file (NOTE - the Eros information is in a different Module now, OmniKit, but the graphic has not been updated.) + +![graphic showing folder icons vs folder names](img/xcode-folder-names.svg){width="750"} +{align="center"} + +These folder icon names are different from the directory names on the computer: + +| Folder Icon Name | Directory Name | | +|:--|:--|| +| ShareClient | dexcom-share-client-swift | +| RileyLink | rileylink_ios | +| Amplitude | Amplitude-iOS | + +All other icons and directory names match. diff --git a/docs/build/img/custom-id.png b/docs/build/img/custom-id.png deleted file mode 100644 index 0022a65e850..00000000000 Binary files a/docs/build/img/custom-id.png and /dev/null differ diff --git a/docs/build/img/sensitivity1.png b/docs/build/img/sensitivity1.png deleted file mode 100644 index 46e505670b6..00000000000 Binary files a/docs/build/img/sensitivity1.png and /dev/null differ diff --git a/docs/build/img/sensitivity2.png b/docs/build/img/sensitivity2.png deleted file mode 100644 index 72ff2c5f24b..00000000000 Binary files a/docs/build/img/sensitivity2.png and /dev/null differ diff --git a/docs/build/img/xcode-modify-max-carb-entry.svg b/docs/build/img/xcode-modify-max-carb-entry.svg deleted file mode 100644 index 70705e7e0c0..00000000000 --- a/docs/build/img/xcode-modify-max-carb-entry.svg +++ /dev/null @@ -1,2465 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - diff --git a/docs/build/overview.md b/docs/build/overview.md index 458086160a0..2e458e68c14 100644 --- a/docs/build/overview.md +++ b/docs/build/overview.md @@ -1,6 +1,6 @@ -## Mac-Xcode Build Requirements +## Build with *Mac* Requirements -The complete requirements for building Loop with a Mac and Xcode are given in the next two sections. The first list contains the common requirements that are the same regardless of build method. The second list contains the additional requirements for building with a Mac and Xcode. +The complete requirements for building Loop with a *Mac* and *Xcode* are given in the next two sections. The first list contains the common requirements that are the same regardless of build method. The second list contains the additional requirements for building with a Mac and Xcode. Each requirement in the list is linked to the LoopDocs pages with more information. @@ -10,14 +10,14 @@ Each requirement in the list is linked to the LoopDocs pages with more informati 1. [Compatible Pump](../build/pump.md) 1. [Compatible CGM](../build/cgm.md) 1. [RileyLink Compatible Device](../build/rileylink.md) (not needed for Omnipod DASH) -1. [Apple Developer Membership](../build/apple-developer.md) (not needed if you rebuild weekly using the Mac-Xcode method) +1. [Apple Developer Membership](../build/apple-developer.md) (not needed if you rebuild weekly using the *Mac* method) -### Mac-Xcode Build Additional Requirements +### Build with *Mac* Additional Requirements 1. [Compatible Computer](../build/computer.md#macos) 1. [Xcode](../build/xcode-version.md) (a free Apple application) -If building to a [Simulator](../version/simulator.md) to try things out, the only requirements are a computer and Xcode. +If using a *Mac* to build to a [Simulator](../version/simulator.md) to try things out, the only requirements are a computer and Xcode. ## Getting Ready to Build diff --git a/docs/build/phone.md b/docs/build/phone.md index 87221c6cb0e..01296ff3466 100644 --- a/docs/build/phone.md +++ b/docs/build/phone.md @@ -57,7 +57,7 @@ Your *iOS* version can be found under the phone Settings -> General -> About dis Do not use any of the beta *iOS* versions. (If you are uncertain what that means, then you are not using one.) -### Developer Mode - *Mac-Xcode* Build Only +### Developer Mode - *Mac* Build Only > When you build the *Loop* app using [Build with Browser](../gh-actions/gh-overview.md), you are not required to enable Developer Mode on the phone or watch. diff --git a/docs/build/pump.md b/docs/build/pump.md index 8c85b8c3b42..8126e90127e 100644 --- a/docs/build/pump.md +++ b/docs/build/pump.md @@ -1,7 +1,7 @@ ## Compatible Pump !!! info "Time Estimate" - - Omnipod users: 3 seconds to remember which PDM you've been using. + - Omnipod users: 3 seconds to remember which Personal Diabetes Manager (PDM) you've been using. - Medtronic users: 10 minutes to put a battery in and look at model and firmware - Other pump users: 5 days to email friends asking them to check closets for their old Medtronic pump or call your insurance to start prior authorization for Omnipod @@ -164,16 +164,18 @@ Eros pods (also known as Gen 3) were launched in 2013 and continue to be sold by Pharmacy sites sometimes may refer to the **Eros pods** as **Gen 3** but they are the same exact pods. -Eros system has a big PDM that does not look like a phone. +Eros system has a big Personal Diabetes Manager (PDM) that does not look like a phone. ![img/eros.png](img/eros.png){width="750"} {align="center"} ### Omnipod DASH -Insulet has announced their DASH system as an eventual replacement for the Eros/Omnipod System. The DASH system has the newer, slimmer locked-android PDM and built-in BLE communications in the pod, so there is no requirement for a RileyLink compatible device. +The DASH system has the newer, slimmer locked-android Personal Diabetes Manager (PDM) and built-in BLE communications in the pod, so there is no requirement for a RileyLink compatible device. -Loop 3.0 and later works with DASH pods. If your version of the *Loop* app is 2.2.9 or earlier, you cannot use DASH pods. +**A RileyLink-compatible device is not required to use DASH wioth the *Loop* app. The communication with your iPhone uses Bluetooth.** + +`Loop 3.0` and later works with DASH pods. If your version of the *Loop* app is 2.2.9 or earlier, you cannot use DASH pods. ![img/dash.png](img/dash.png){width="750"} {align="center"} diff --git a/docs/build/test-settings.md b/docs/build/test-settings.md index 895df2ec477..eac9486e117 100644 --- a/docs/build/test-settings.md +++ b/docs/build/test-settings.md @@ -10,7 +10,7 @@ * DASH pods can be used without a RileyLink * restarting your app or turning Bluetooth on and off replaces the Rileylink power cycle trouble-shooting tip * Nightscout with Heroku is no longer free, but there are other options - * you do NOT need a Mac computer if you use [Browser Build](../gh-actions/gh-overview.md) + * you do NOT need a Mac computer if you use [Build with Browser](../gh-actions/gh-overview.md) - 1-3 days to test settings for safety and to get the most out of the *Loop* app * This step can be done after you build the *Loop* app, just stay in [`Open Loop`](../operation/loop/open-loop.md) while you test diff --git a/docs/build/testflight-xcode.md b/docs/build/testflight-xcode.md index 1daeac46ce9..1044a805d20 100644 --- a/docs/build/testflight-xcode.md +++ b/docs/build/testflight-xcode.md @@ -3,8 +3,8 @@ There are several different methods for making use of TestFlight: * Test an app someone else is developing -* Use the GitHub [Browser Build](../gh-actions/gh-overview.md) method to build and distribute your own Loop app -* Use TestFlight as a remote distribution (and backup) for an app you build using Xcode +* Use the [Build with Browser](../gh-actions/gh-overview.md) method to build and distribute your Loop app to your iPhone or that of a family member +* Use *TestFlight* as a remote distribution (and backup) for an app you build using *Xcode* This guide can also be followed to install other apps you build with *Xcode* via *TestFlight*. Examples include Loop Follow, Loop Caregiver, xDrip4iOS and GlucoseDirect. @@ -14,7 +14,7 @@ Some useful features of using TestFlight to install Loop: * You can update Loop on your kid's phone while they're away at college * Reinstalling Loop on the fly is quick and easy from your phone, even if you accidentally delete the app, see [Protect that App](build-app.md#protect-that-app), or need to install Loop on a brand new phone -Since apps built with TestFlight expire after 90 days, it is recommended you also setup a build using the GitHub [Browser Build](../gh-actions/gh-overview.md) method even if you don't plan on using it. The GitHub build can be updated in a few minutes from any browser and is an extra layer of protection in these scenarios if you do not have access to your Mac for a rebuild: +Since apps built with TestFlight expire after 90 days, it is recommended you also setup a build using the [Build with Browser](../gh-actions/gh-overview.md) method even if you don't plan on using it. The GitHub build can be updated in a few minutes from any browser and is an extra layer of protection in these scenarios if you do not have access to your Mac for a rebuild: * Your Xcode built Loop in TestFlight expires * An urgent update to Loop is released @@ -25,7 +25,7 @@ In all cases, except accidental deletion of Loop or loss of phone, the Loop you ### Initial Steps -Before creating or uploading to a TestFlight, use the [Mac-Xcode Build](../build/overview.md) guide to [sign your targets](../build/build-free-loop.md#select-signing-capabilities-tab) and build Loop to a [simulator phone](../build/build-free-loop.md#build-to-a-simulator) in Xcode. This checks to ensure the app you upload to your TestFlight will work as expected. +Before creating the app or uploading it to *TestFlight*, use the [Build with *Mac*](../build/overview.md) guide to [sign your targets](../build/build-free-loop.md#select-signing-capabilities-tab) and build Loop to a [simulator phone](../build/build-free-loop.md#build-to-a-simulator) in Xcode. This checks to ensure the app you upload to your TestFlight will work as expected. ### Archive the Project diff --git a/docs/build/updating.md b/docs/build/updating.md index bf93f8e299d..4f432b42f62 100644 --- a/docs/build/updating.md +++ b/docs/build/updating.md @@ -66,7 +66,7 @@ Between Loop app builds, there's a high likelihood that Apple has updated one or Based on the iOS on your phone, or the iOS you plan to install on your phone, determine the required macOS and Xcode versions. Click on this link [versions for iOS, macOS and Xcode](xcode-version.md#how-do-all-the-minimum-versions-relate-to-each-other) to determine the versions needed and then hit the back button in your browser to finish the steps on this updating page. -If you are tired of the macOS and Xcode version update requirements, check out the [Browser Build](../gh-actions/gh-overview.md) option. +If you are tired of the macOS and Xcode version update requirements, check out the [Build with Browser](../gh-actions/gh-overview.md) option. !!! warning "First macOS and Then Xcode" Your macOS must meet the minimum requirement for the Xcode version you need to support your current iOS as detailed in that link above. diff --git a/docs/build/xcode-version.md b/docs/build/xcode-version.md index fe1fe29781b..cf4154cc159 100644 --- a/docs/build/xcode-version.md +++ b/docs/build/xcode-version.md @@ -2,7 +2,7 @@ !!! info "Time Estimate" - 45 minutes to 2 hours, depending on internet connection...but you don't need to babysit the download. - - 0 minutes if you decide to use the GitHub [Browser Build](../gh-actions/gh-overview.md) method to build Loop + - 0 minutes if you decide to use the [Build with Browser](../gh-actions/gh-overview.md) method to build Loop !!! abstract "Summary" - Check iPhone iOS version @@ -81,7 +81,7 @@ The current development version and the next release of _Loop 3.2.3. If your macOS or Xcode version is higher, you can build with Mac-Xcode. +The table below lists the **minimum** requirements to build the current release of Loop 3.2.3. If your macOS or Xcode version is higher, you can build with *Mac*. Find your phone iOS in the table below. If your iOS is not listed, e.g., 16.6, choose the first row that is less than your iOS. diff --git a/docs/faqs/FAQs.md b/docs/faqs/FAQs.md index f53d111c2be..c21d497daaa 100644 --- a/docs/faqs/FAQs.md +++ b/docs/faqs/FAQs.md @@ -38,8 +38,8 @@ Yes, there are some costs, beyond the obvious costs of owning a pump and CGM. * If you have a pump the requires a [RileyLink Compatible Devices](../build/rileylink.md#rileylink-compatible-devices), expect to spend $150 each (or find a used one). You should have two, one as a spare. * Most people use a paid Apple Developer Account ($99/year) - * With a paid developer account, you can build using the [Browser Build](../gh-actions/gh-overview.md); no Mac required -* If you build on a Mac using Xcode [Mac-Xcode Build](../build/overview.md), you need a Mac or a PC with Intel chips on which you include a virtual Mac + * With a paid developer account, you can build using the [Build with Browser](../gh-actions/gh-overview.md); no Mac required +* If you build on a Mac using Xcode [Build with *Mac*](../build/overview.md), you need a Mac or a PC with Intel chips on which you include a virtual Mac There are no other costs, ongoing or initial, to use Loop beyond what you already pay for your CGM, pump supplies and insulin. @@ -51,34 +51,34 @@ There are several options for the [RileyLink Compatible Devices](../build/rileyl ## Free Developer Account Options -The Apple Developer License can be done for free, however, you will have to rebuild your Loop app every 7 days and you must use a computer with Xcode, [Mac-Xcode Build](../build/overview.md). That could get very tedious. The $99 annual Apple Developer program enrollment is an excellent investment. +The Apple Developer License can be done for free, however, you will have to rebuild your Loop app every 7 days and you must use a computer with Xcode, [Build with *Mac*](../build/overview.md). That could get very tedious. The $99 annual Apple Developer program enrollment is an excellent investment. ## Do I need to own my own Apple computer? -You no longer need to own an Apple computer - see [Browser Build](../gh-actions/gh-overview.md). +You no longer need to own an Apple computer - see [Build with Browser](../gh-actions/gh-overview.md). -If you chose [Mac-Xcode Build](../build/overview.md), then you still don't **have** to own an Apple computer, but you do need to at least borrow one - or you can build using a virtual Mac if you have a PC with Intel chips (see next section). +If you chose [Build with *Mac*](../build/overview.md), then you still don't **have** to own an Apple computer, but you do need to at least borrow one - or you can build using a virtual Mac if you have a PC with Intel chips (see next section). If you are borrowing an Apple computer, look at the required minimum settings associated with your iPhone [Compatible Computer](../build/computer.md#macos) and [Xcode Version](../build/xcode-version.md#how-do-all-the-minimum-versions-relate-to-each-other). It would be really good to have longer term ability to borrow that computer again for [updating Loop](../build/updating.md#when-to-update) later, when needed. ## Can I use a PC or Windows computer to build? -You can build Loop using just a browser on any device: [Browser Build](../gh-actions/gh-overview.md). +You can build Loop using just a browser on any device: [Build with Browser](../gh-actions/gh-overview.md). -If you want to use [Mac-Xcode Build](../build/overview.md), there is a hacked way of installing macOS on a Windows computer called a **Virtual Machine**. [This link](https://macosvmware.tech.blog/) provides some helpful information. This **Virtual Machine** method will not work on PCs that have AMD processors, only Intel. Double check that your computer uses an Intel processor before attempting the virtual machine method. If you want to try this, there are mentors on [The Looped Facebook Group](https://www.facebook.com/groups/TheLoopedGroup) who can assist. +If you want to use [Build with *Mac*](../build/overview.md), there is a hacked way of installing macOS on a Windows computer called a **Virtual Machine**. [This link](https://macosvmware.tech.blog/) provides some helpful information. This **Virtual Machine** method will not work on PCs that have AMD processors, only Intel. Double check that your computer uses an Intel processor before attempting the virtual machine method. If you want to try this, there are mentors on [The Looped Facebook Group](https://www.facebook.com/groups/TheLoopedGroup) who can assist. ## How often do I need to get on the computer for Loop? When you use the Browser Build method, you need to access a browser at least once every 90 days to [Update with Browser](../gh-actions/gh-update.md). This is simple enough to do that you can do the steps on your phone in just a few minutes. Several people are already working on automated methods so that won't be required, but a manual Build Actions step is required for now. -When you use Mac-Xcode Build: the short answer is (1) when you first build and (2) once per year minimum after that. (If you decide to use a free Apple Developer Account, you will need to get on the computer every 7 days.) +When you use Build with *Mac*: the short answer is (1) when you first build and (2) once per year minimum after that. (If you decide to use a free Apple Developer Account, you will need to get on the computer every 7 days.) Loop code is updated periodically to include new features and bug fixes. When those updates are released, you'll need access to a browser or an Apple computer again to update your Loop app. Loop updates are **not** available through the iPhone's app store...instead you do the app update yourself -* If using Mac-Xcode build: use this link: [update instructions](../build/updating.md) -* If using Browser build: use this link: [Update with Browser](../gh-actions/gh-update.md#how-to-update-or-rebuild) +* If using Browser build method: use this link: [Update with Browser](../gh-actions/gh-update.md#how-to-update-or-rebuild) +* If using build with *Mac* method: use this link: [update instructions](../build/updating.md) In general, there are updates to Loop released a few times a year - these can occur more frequently after a major release. @@ -90,7 +90,7 @@ No. Loop lets you move between different pump types from within the same Loop ap If there is more than one Looper in the family, you only need to have one Apple Developer ID and only one annual payment. The adult who builds can use their Apple Dev ID to put the app on the Looper's phone. You will have no problem supporting everyone in your family. Building Loop on the second phone is much faster than the first one. It's a good idea to let someone else in the family know how to build and have access to your Apple password in case you're out of town. It's also a good idea to build Loop on a backup phone especially for travel. The Apple Developer ID and the Apple ID are two different things. PLEASE read this: [Loopers Need Their Own Apple ID](../build/apple-developer.md#loopers-need-their-own-apple-id). -If you used the [Browser Build](../gh-actions/gh-overview.md) method, you just add each Looper to your TestFlight test group and they get updates whenever you issue a new Build Action on github. +If you used the [Build with Browser](../gh-actions/gh-overview.md) method, you just add each Looper to your TestFlight test group and they get updates whenever you issue a new Build Action on github. ## What happens when I switch Apple Developer ID? @@ -176,10 +176,13 @@ One exception - if you've chosen to use a CGM source that does require the inter ## What happened to FreeAPS? -[FreeAPS](https://www.loopandlearn.org/freeapsdoc) hasn't really had an owner to develop it for several years, but many depended on it. Because of that, the Loop and Learn team kept it on life-support. It was updated to include DASH, but that is the last expected improvement. It is strongly recommended people switch to Loop 3. +[FreeAPS](https://www.loopandlearn.org/freeapsdoc) hasn't really had an owner to develop it for several years, but many depended on it. Because of that, the *Loop and Learn* team kept it on life-support. It was updated in early 2023 to include DASH, but that was the last improvement. It is strongly recommended people switch to `Loop 3` or `iAPS`. Do not use an application without an owner. -Many features people used with FreeAPS are now included in Loop 3 or can be added with customization. The dev branch has Libre support, see [Build Loop Dev](../version/build-dev.md). +Many features people used with FreeAPS are now included in `Loop 3` or can be added with customization. The `dev` branch has Libre support, see [Build Loop Dev](../version/build-dev.md). -The addition of customizations has been simplified with the [Loop and Learn: Customization Select Script](https://www.loopandlearn.org/custom-code). That script can be run stand-alone, selected as an option as part of the Build Select Script when doing a Mac-Xcode build or incorporated in a [GitHub Browser build customization](../gh-actions/gh-customize.md) by editing the build_loop.yml file. +The addition of customizations has been simplified. -Please do not blindly apply customizations. You should first read [LoopDocs: Customize Your Loop](../build/code-customization.md) and then [Loop and Learn: Code Customization](https://www.loopandlearn.org/custom-code/). +* If you build with a browser, refer to [Customize with Browser](../gh-actions/custom-browser.md) +* If you build with a *Mac*, refer to [Customize with *Mac*](../build/custom-mac.md) + +Please do not blindly apply customizations. First read the documentation provided at the links above carefully. \ No newline at end of file diff --git a/docs/faqs/new-phone.md b/docs/faqs/new-phone.md index a5d34b439cc..5bfa6dcdd18 100644 --- a/docs/faqs/new-phone.md +++ b/docs/faqs/new-phone.md @@ -1,6 +1,6 @@ ## Overview -Changing phones means you have to rebuild the *Loop* app onto the new phone. When you transfer information from your old phone to your new one, all your _Loop_ information is included and the _Loop_ icon will appear, but the app will not open until you install _Loop_ from either [*TestFlight*](../gh-actions/gh-deploy.md#install-app-with-testflight) or [*Mac-Xcode*](../build/build-app.md). +Changing phones means you have to rebuild the *Loop* app onto the new phone. When you transfer information from your old phone to your new one, all your _Loop_ information is included and the _Loop_ icon will appear, but the app will not open until you install _Loop_ from either [*TestFlight*](../gh-actions/gh-deploy.md#install-app-with-testflight) or [*Mac* with *Xcode*](../build/build-app.md). Some people don't have access to their old phone. There are instructions for handling that on this page. It makes the whole process more stressful, but remember, pods continue to deliver basal rate and *Medtronic* pumps can be controlled on the pump itself. Use your backup plan until you can get _Loop_ running on a new phone. @@ -27,9 +27,10 @@ Update your old phone to the latest iOS the hardware supports - this simplifies * The *Loop* app will install from *TestFlight* onto the most recent iOS * If a new version is available, we recommend updating and building to the latest [Update with Browser](../gh-actions/gh-update.md) -!!! abstract "New Phone Checklist for *Mac-Xcode* Build" +!!! abstract "New Phone Checklist for Build with *Mac*" * Are your [Mac and Xcode versions](../build/xcode-version.md#how-do-all-the-minimum-versions-relate-to-each-other) compatible with the latest iOS version? - * If not, you should configure and build the app with [Build with Browser](../gh-actions/gh-overview.md) + * If not, you need to install the correct versions on your *Mac* + * If you cannot do that, you should consider [Build with Browser](../gh-actions/gh-overview.md) ### Different Developer ID @@ -70,7 +71,7 @@ It is easier if you transfer information from the old phone to the new phone bef * *Medtronic* users will have all their information transferred but will only have one phone connected to the *RileyLink* 1. Install _Loop_ on the new phone (all your settings should be there) * [Install from *TestFlight*](#install-from-testflight)
or - * [Build using *Mac-Xcode*](#build-using-mac-xcode) + * [Build using *Mac*](#build-using-mac) 1. As soon as you install the *Loop* app on the new phone, go ahead and disable Closed Loop. * Keep Closed Loop disabled until you complete the full transfer and checkout. @@ -80,7 +81,7 @@ It is easier if you transfer information from the old phone to the new phone bef * Install the app on your new phone from *TestFlight* * If necessary, review [*TestFlight* for a Child](../gh-actions/gh-deploy.md#testflight-for-a-child) -#### Build using **Mac-Xcode** +#### Build using *Mac* * Open *Xcode* – use the same build as you used for the old phone * Plug in the new phone to the computer (trust phone/computer) and hit build diff --git a/docs/faqs/safety-faqs.md b/docs/faqs/safety-faqs.md index 79723fb0998..36a2944a291 100644 --- a/docs/faqs/safety-faqs.md +++ b/docs/faqs/safety-faqs.md @@ -62,7 +62,7 @@ For older versions of _Loop_, or if you customi If you let other apps, such as MyFitnessPal, write carbohydrates to the Health app, _Loop_ could read those carbohydrates and you could be dosed for those carbohydrates. -* Loop 3: review [Customization: Build Time Features](../build/code-customization.md#build-time-features) +* Loop 3: review [Customization: Build Time Features](../version/build-time-flag.md) * Loop 2: Check your [Health](../build/health.md#loop-permissions) permissions and review. ## Glucose Prediction is Scary diff --git a/docs/faqs/update-faqs.md b/docs/faqs/update-faqs.md index fbfb0c60056..b5c04b95493 100644 --- a/docs/faqs/update-faqs.md +++ b/docs/faqs/update-faqs.md @@ -17,8 +17,8 @@ In both cases, you build the code to install over an existing app on your phone * If you use the Browser build method: * Follow the steps on [Update/Rebuild with Browser](../gh-actions/gh-update.md) * Within an hour that new build should be available via TestFlight to install on your phone -* If you use the *Mac-Xcode* build method: - * Follow the steps on [Update/Rebuild with *Mac-Xcode*](../build/updating.md) +* If you use the build with *Mac* method: + * Follow the steps on [Update/Rebuild with *Mac*](../build/updating.md) * First make sure your *Mac* operating system and *Xcode* version are compatible with your *iPhone* version, and then * Use the [Build Select Script](../build/build-app.md#build-select-script) to download the latest released version of the code * See note below if your internet speed or your *Mac* is very slow @@ -28,7 +28,7 @@ In both cases, you build the code to install over an existing app on your phone * Use Finder to check the date of your last download by looking in the Downloads/BuildLoop folder * Check the date of the last release at [*GitHub* `LoopKit/Loop releases`](https://github.com/LoopKit/Loop/releases) - * If the date in Finder is after the release date, follow [Find my Downloaded *Loop* Code](../build/code-customization.md#find-my-downloaded-loop-code) + * If the date in Finder is after the release date, follow [Find my Downloaded *Loop* Code](../build/edit-mac.md#find-my-downloaded-loop-code) * Double click on the Loop.xcworkspace file in that folder * This opens Xcode and you can just plug in your phone and build with your existing download @@ -41,11 +41,11 @@ There's a whole page devoted to just this topic: [New Phone](new-phone.md) * **Best Practice** * Build if a serious bug-fix is reported * Build, two to four times a year so that it becomes easier and you are ready in case of an emergency - * Each time you build, the app expiration date is bumped out a full year for Mac-Xcode build method and 90-days for Browser build + * Each time you build, the app expiration date is bumped out a full year for build with *Mac* method and 90-days for Browser build * **Required** * When your expiration date forces you * Do not wait until the app expires - it will stop working - * For *Mac-Xcode*, you will see [Loop is No Longer Available](../build/updating.md#loop-is-no-longer-available) + * For *Mac*, you will see [Loop is No Longer Available](../build/updating.md#loop-is-no-longer-available) * For Browser Build, the message is "Loop Beta has expired" * Hint - start a few weeks early and take your time * **Optional** @@ -83,9 +83,9 @@ Regardless of build method, always check your *Apple* Developer Account status. Go to [Update/Rebuild with Browser](../gh-actions/gh-update.md) and follow the instructions. -#### Updates with the *Mac-Xcode* build method: +#### Updates with the build with *Mac* method: -**ALWAYS start with the [Update/Rebuild with *Mac-Xcode*](../build/updating.md) before any new *Mac-Xcode* build.** That page is important because it will offer information on the updates you may need for your *Mac* and *Xcode* before building. +**ALWAYS start with the [Update/Rebuild with *Mac*](../build/updating.md) before any new build with *Mac*.** That page is important because it will offer information on the updates you may need for your *Mac* and *Xcode* before building. Do not simply build with your old downloaded folder from months ago. There is a high likelihood that your original code from awhile ago is outdated and might not build with the current phone iOS. Grab new code and you will get the compatible version that has all the latest and greatest features and bug fixes. diff --git a/docs/gh-actions/automatic.md b/docs/gh-actions/automatic.md new file mode 100644 index 00000000000..70c79de9939 --- /dev/null +++ b/docs/gh-actions/automatic.md @@ -0,0 +1,88 @@ +## Overview + +**After the next release of the *Loop* app (version 3.4.0), this page will be required for all versions when building with a browser.** + +**Before that release, this page is only relevant when building the `dev` branch with a browser and only when the `dev` branch is the default branch.** + +## Modify Automatic Building + +For someone using [development code](build-dev-browser.md) for their own use, they probably want to decide when to update their `fork` to the most recent commit. They can still have the advantage of automatic building without automatic updates. There may be other configurations someone would choose. These options are added to Loop 3.3.0 (`dev` branch) and later. + +You can affect the default behavior: + +1. [Modify Automatic Schedule](#modify-automatic-schedule) +1. [Disable Automatic Actions](#disable-automatic-actions) + +### Modify Automatic Schedule + +You can modify the automation by creating and using some variables. + +To configure the automated build more granularly involves creating up to two environment variables: `SCHEDULED_BUILD` and/or `SCHEDULED_SYNC`. See [How to configure a variable](#how-to-configure-a-variable). + +Note that the weekly and monthly `Build Loop` actions will continue, but the actions are modified if one or more of these variables is set to false. **A successful Action Log will still appear, even if no automatic activity happens**. + +* If you want to manually decide when to update your repository to the latest commit, but you want the monthly builds and keep-alive to continue: set `SCHEDULED_SYNC` to false and either do not create `SCHEDULED_BUILD` or set it to true +* If you want to only build when an update has been found: set `SCHEDULED_BUILD` to false and either do not create `SCHEDULED_SYNC` or set it to true + * **Warning**: if no updates to your default branch are detected within 90 days, your previous TestFlight build may expire requiring a manual build + +|`SCHEDULED _SYNC`|`SCHEDULED _BUILD`|Automatic Actions| +|---|---|---| +| `true` (or NA) | `true` (or NA) | keep-alive, weekly update check (auto update/build), monthly build with auto update| +| `true` (or NA) | `false` | keep-alive, weekly update check with auto update, only builds if update detected| +| `false` | `true` (or NA) | keep-alive, monthly build, no auto update | +| `false` | `false` | no automatic activity, no keep-alive| + +### How to configure a variable + +1. Go to the "Settings" tab of your LoopWorkspace repository. +2. Click on `Secrets and Variables`. +3. Click on `Actions` +4. You will now see a page titled *Actions secrets and variables*. Click on the `Variables` tab +5. To disable ONLY scheduled building, do the following: + - Click on the green `New repository variable` button (upper right) + - Type `SCHEDULED_BUILD` in the "Name" field + - Type `false` in the "Value" field + - Click the green `Add variable` button to save. +7. To disable scheduled syncing, add a variable: + - Click on the green `New repository variable` button (upper right) + - - Type `SCHEDULED_SYNC` in the "Name" field + - Type `false` in the "Value" field + - Click the green `Add variable` button to save + +Your build will run on the following conditions: + +- Default behaviour: + - Run weekly, every Wednesday at 08:00 UTC to check for changes; if there are changes, it will update your repository and build + - Run monthly, every first of the month at 06:00 UTC, if there are changes, it will update your repository; regardless of changes, it will build + - Each time the action runs, it makes a keep-alive commit to the `alive` branch if necessary +- If you disable any automation (both variables set to `false`), no updates, keep-alive or building happens when `Build Loop` runs +- If you disabled just scheduled synchronization (`SCHEDULED_SYNC` set to`false`), it will only run once a month, on the first of the month, no update will happen; keep-alive will run +- If you disabled just scheduled build (`SCHEDULED_BUILD` set to`false`), it will run once weekly, every Wednesday, to check for changes; if there are changes, it will update and build; keep-alive will run + +### Disable Automatic Actions + +To enable the scheduled build and sync, the `GH_PAT` must hold the `workflow` permission scopes. This permission serves as the enabler for automatic and scheduled builds with browser build. To disable this, follow these steps: + +1. Go to your [FastLane Access Token](https://github.com/settings/tokens) +1. If it says `repo`, `workflow` next to the `FastLane Access Token` link, then automatic building is enabled +1. To disable automatic update and build, click on the link to open the token detail view + * Click to uncheck the `workflow` box + * Click to check the `repo` box +1. Scroll all the way down to and click the green `Update token` button +1. Your token now holds only the `repo` permission + +If you choose not to have automatic building enabled, be sure the `GH_PAT` has `repo` scope or you won't be able to manually build. + +## Stop Building + +What if I decide I don't want the automatic building feature? + +* If you are using the released version of Loop, please leave automatic building running + * Please read [TestFlight Automatic Updates](gh-deploy.md#testflight-automatic-updates) on how to configure TestFlight so you choose when the updated app gets installed on your phone + * Otherwise, you may see the dreaded "Loop Beta has expired" message, have a Loop that won't open and not have a version ready to go in TestFlight that you can install within a few seconds + +* If you are taking a break from Loop and want to stop monthly Build emails, consider disabling actions for the `Build Loop` action for your app. + * [GitHub Directions to Disable and Enable a Workflow](https://docs.github.com/en/actions/using-workflows/disabling-and-enabling-a-workflow#disabling-a-workflow) + * It is the Build action that kicks off the update and build steps, so simply disabling the one action is sufficient + +* If you are done with Loop, you can delete the whole repository; but you should be sure about this because you'll need to start over with [Configure to Use Browser](gh-first-time.md) to restore ability to build Loop with GitHub. diff --git a/docs/gh-actions/build-dev-browser.md b/docs/gh-actions/build-dev-browser.md new file mode 100644 index 00000000000..90089c71871 --- /dev/null +++ b/docs/gh-actions/build-dev-browser.md @@ -0,0 +1,177 @@ +## Overview + +**This page is only relevant when building the `dev` branch with a browser.** + +**For *Mac*, please see: [Build Loop `dev` with *Mac*](../build/build-dev-mac.md)** + +**No matter the method used to build Loop-dev, you are testing development code. Please read this link now before continuing.** + +* **[What's going on in the `dev` branch](../version/development.md#whats-going-on-in-the-dev-branch)** + +## Build Development Version + +!!! warning "For Experienced Builders" + Building the development (`dev` branch) is not typically used for your first attempt at building the *Loop* app. + + The instructions on this page assume you are familiar with building the *Loop* app using a browser as detailed on [Configure to use Browser](gh-first-time.md) + + * You should be following along with zulipchat when using the `dev branch` + * Summary build updates can be found under the [One-Time Changes](#one-time-changes) section + +You can build any desired branch (available at LoopKit/LoopWorkspace) using the *GitHub* Browser build method. This section is suitable if you have already built either `dev` or main branch using the [GitHub First-Time](gh-first-time.md) instructions. + +The graphics on this page show the `dev` branch. If you want a different branch, just substitute that branch name for `dev`. + +!!! tip "Overview of what you will do" + 1. Your `LoopWorkspace fork` must have the `branch` you want + * You will either add it or make sure it is up to date + * You cannot just rename your existing branch to `dev` - you must get the `dev` branch from LoopKit + 1. When you select the action `4. Build Loop` and then click on the `Run Workflow` dropdown, you must select `dev` there before clicking the green `Run workflow` button - see [Build `Branch`](#build-branch) + + +### Check Current `Branch` + +Your `LoopWorkspace fork` is at `https://github.com/username/LoopWorkspace` where you substitute your actual *GitHub* `username`. You need to be logged into *GitHub*. Review the graphic below as you go through the steps. + +1. Click on the `branch` icon to display the `branches` as shown in the lower half of the graphic below: + * If the `branch` you want is not listed, then continue with Step 2 + * Otherwise, skip ahead to [Update `Branch`](#update-branch) +1. Click on the `New branch` button and follow the [Add `Branch`](#add-branch) steps + +![steps to add a branch](img/add-branch-01.svg){width="700"} +{align="center"} + +### Add `Branch` + +Each step in the list below matches with the number in the graphic. In the top half of the graphic, the left side shows the initial display and the right side shows the display after making the indicated selections: + +1. Click on the drop down menu labeled 1 in the graphic and choose LoopKit/LoopWorkspace as show in the top right graphic +2. Click on the drop down menu labeled 2 in the graphic and choose `dev` +3. Click on the `Branch` name box labeled 3 in the graphic and type `dev` + * The branch name in your `fork` should always match the branch name you are adding; check that you type it correctly +4. Review the dialog items to make sure everything is correct and then tap on Create branch + +![steps to add a branch continued](img/add-branch-02.svg){width="700"} +{align="center"} + +### Update `Branch` + +Tap the `Code` button (upper left) and ensure this branch in your `fork` is up to date. + +* Select the desired branch in the dropdown menu (this graphic shows `dev` branch) +* If the message indicates this branch is "behind", tap on the sync `fork` button and then the Update branch button + +![message displayed when your fork of LoopWorkspace is behind LoopKit version](img/github-build-check-fork-status.svg){width="700"} +{align="center"} + +### One-Time Changes + +Look in this section for one-time changes for building `dev` with a browser that require special, one-time actions. + +If you have already completed the One-Time Changes, skip ahead to [Build `Branch`](#build-branch). + +#### Transition to `dev` + +When updating from _Loop_ 3.2.x to `dev`, you will need to take some extra steps. + +You have a choice: + +* You can change your default branch to `dev`, see [Change Default `Branch`](#change-default-branch) and then your _Loop_ app will be automatically updated and automatically built at least once a month + * Be sure to review the [Modify Automatic Building](automatic.md#modify-automatic-building) section +* You can leave your default branch at main, but no automated updates will happen + * Running each action below requires you to select the `dev` branch in the drop-down menu + +Here is a summary of the extra steps; each step has an associated link. This assumes you have already updated your `fork` and are at the correct branch. + +1. Confirm the status of your  *GitHub* Personal Access Token + * It should be configured with permission scope of `repo, workflow` and to never expire + * You can check this using directions at [*GitHub* Token](gh-update.md#github-token) +1. Next, follow along in this section to perform these steps before you build + * Add and Update `New Indentifier` + * `Create Certificates` + +#### Automatic Creation of `alive branch` + +!!! warning "What about the `alive branch`" + * Sometimes you get an error about the `alive branch` + * It should be created for you automatically if you are building with the `dev branch` **and** you have `workflow` permission added to the `scope` for your *GitHub* `Personal Access Token` + * If necessary, delete the `alive branch` and run the `Create Certificates` again + +#### Add and Update New `Identifier` + +The `bundle ID` for the "`widget`" changed from "`SmallStatusWidget`" to the more descriptive "`LoopWidgetExtension`". + +* You need to run Add Identifier - be sure that you run this for the `dev branch` +* Wait for it to succeed +* Add the `App Group` to this one new Identifier + +All other identifiers should be already set up. If they are not, please go through the steps on the [Configure to Use Browser](gh-first-time.md) page to figure out what you are missing. + +| `NAME` | `IDENTIFIER` | +|-------|------------| +| `Loop Widget Extension` | `com.TEAMID.loopkit.Loop.LoopWidgetExtension` | + +* Open the [Certificates, Identifiers & Profiles: Identifiers List](https://developer.apple.com/account/resources/identifiers/list) page. +* Click on the "`LoopWidgetExtension`" identifier +* Edit the App Group to include `group.com.TEAMID.loopkit.LoopGroup` where you use your `TEAMID` + +#### Create Certificates and Build + +You must create certificates again to cover the new Identifier name and to provide support for the addition of the Libre sensors. (This step is required whether you use Libre or not - Loop needs permission to have that capability). Once the certificate action succeeds, then run the action to build Loop. + +1. Run the Action for Create Certificates - be sure that you run this for the `dev branch` +1. Run the Action for `Build Loop` (see [Build `Branch`](#build-branch)) + +### Build `Branch` + +If you want a branch to be the one you build all the time, you may choose to [Change Default `Branch`](#change-default-branch). This is not necessary except for special cases. + +If you have one branch as default, for example main, and choose to build a different branch, there is an extra step when you `Build Loop`. Refer to step 4 in the graphic below. Use the branch dropdown menu to select the branch you want before hitting the green Run workflow button. + +![build loop using github actions](img/action-04-build-loop.svg){width="700"} +{align="center"} + +!!! + +## Change Default `Branch` + +There can be several reasons why you would change your default branch. + +* It can be convenient to have the branch you build most be configured as the default branch +* The branch you want to build has a different workflow than your default branch (not typical) + * In this case, you **must** modify the default branch + * Check the zulipchat conversation about the branch you are testing to see if it is necessary to make it default + +These are the steps to modify the default branch. + +For this example, we show how to change from a default branch of `main` to a default branch of `dev`. Note - only the owner of the repository can take this action and they must be logged in. Otherwise the Settings tab does not appear. + +For the numbered steps below, refer to the graphic found under each group of steps. + +1. Click on the Settings Icon near the top right of your LoopWorkspace + * You may need to scroll down to see the `Default Branch` as shown in the graphic + * Do not tap on the Branches tab to the left under Code and Automation, that is not the correct menu + + ![show default branch](img/gh-settings-branch-01.svg){width="700"} + {align="center"} + +1. To the right of the default branch name there is a pencil and a left-right arrow icon + * Tap on the left-right arrow icon to bring up the `Switch default branch to another branch` dialog +1. Click on the dropdown next to the current default branch, in this example, `main` +1. Select the desired default branch, in this example, `dev` +1. Click on the `Update` button + + ![modify default branch](img/gh-settings-branch-02.svg){width="700"} + {align="center"} + +1. You will be presented with an are-you-sure question. + * Click on the red `I understand, update the default branch.` button + + ![confirm default branch](img/gh-settings-branch-03.svg){width="400"} + {align="center"} + +Your default branch has been changed. + +## Automatic Update & Build + +The automatic update and build features of the development branch are only available if you set the `dev` branch as your default branch. Be sure to read the [Automatic Update & Build](automatic.md) if you did this. \ No newline at end of file diff --git a/docs/gh-actions/custom-browser.md b/docs/gh-actions/custom-browser.md new file mode 100644 index 00000000000..21eca12944a --- /dev/null +++ b/docs/gh-actions/custom-browser.md @@ -0,0 +1,55 @@ +## Overview + +**This page is only relevant when building with a browser.** + +**For *Mac*, please see: [Customize with *Mac*](../build/custom-mac.md)** + +For new Loopers, please build the code before you make any changes. Start with Open Loop and familiarize yourself with the interface. Later, you can make the customization(s) you desire and build again. The second build will be much easier than your first build. + +These customizations require you to modify the code used to build the *Loop* app and then build the app again with the modified code. + +!!! warning "You take responsibility" + You are responsible when you decide to use customizations. + + Be sure to report what changes you made if you need to ask for assistance with your app. + +## Customizations Prepared for You + +Some customizations are the same for everyone and have been prepared for easy use. + +The *Loop and Learn* team commit to maintaining these prepared customizations and provide an easy method to add your selection from these customization to your version of *Loop*. + +Please read the documentation for these on the [Loop and Learn: Customization Select Page](https://www.loopandlearn.org/custom-code): + +* [List of Customizations Available](https://www.loopandlearn.org/custom-code#custom-list) +* When building using a browser you will be modifying one of the special files that enables the *GitHub* action to build the *Loop* app. This file is called the build_loop.yml file and can be located at your `fork` of your `LoopWorkspace` repository. There are several sections you need to review on the *Loop and Learn* page: + * [Overview](https://www.loopandlearn.org/custom-code/#github-intro) of how to modify the build_loop.yml file + * You will copy a template that you paste into that file and then edit to keep just the customizations you want + * [Template for `main`](https://www.loopandlearn.org/custom-code#template) + * [Template for `dev`](https://www.loopandlearn.org/custom-code#template-dev) + +### Add Libre Support to 3.2.3 + +If you are using `main` branch to build `Loop 3.2.3` and rely on either *xDrip4iOS* or *GlucoseDirect* to read your CGM and transfer the readings to the *Loop* app, you need to review this [section of the *Loop and Learn* customization page](https://www.loopandlearn.org/custom-code#add-cgm-323-browser). + +Alternatively, you can switch to the `dev` branch, which already supports Libre. [Build Loop dev with Browser](build-dev-browser.md) + +## Personal Customizations + +Some customizations must be created for yourself. These are of two basic types: Custom Edits and Build-Time Flag. + +The information needed to modify the code to make these customizations is found in the Versions tab because the information is independent of build method (think of these as your personal versions). The links are found below. + +* [Version: Custom Edits](../version/code-custom-edits.md) + * The page linked above indicates how you can modify behavior by editing the code +* [Version: Build-Time Flag](../version/build-time-flag.md) + * By enabling or disabling features controlled by a Build-Time Flag, you are turning on or off features included in the code by the developers that they configured to be off or on by default + * Please read about these flags on the page linked above + +When preparing these personal edits using a browser, there is a page explaining how to get these edits into your personal `fork` of `LoopWorkspace` prior to building. + +* [Custom Edits with Browser](edit-browser.md) + +## Details at Links + +The code changes required for these customizations are the same regardless of the build method. The pages that provide the documentation on modifying and incorporating these changes are found at the links above. diff --git a/docs/gh-actions/gh-customize.md b/docs/gh-actions/edit-browser.md similarity index 97% rename from docs/gh-actions/gh-customize.md rename to docs/gh-actions/edit-browser.md index dd2be91dff8..6578b3269e5 100644 --- a/docs/gh-actions/gh-customize.md +++ b/docs/gh-actions/edit-browser.md @@ -1,9 +1,9 @@ ## Hot Topics !!! tip "Pro Tip" - The method on this page allows you to create a set of personalized customizations that you can use in addition to the [Loop and Learn: Prepared Customizations](https://www.loopandlearn.org/custom-code#prepared-custom-list). You can use (and re-use) your customizations with either Browser Build or Mac-Xcode builds so you don't have to repeat the customization with every update. + The method on this page allows you to create a set of personalized customizations that you can use in addition to the [Loop and Learn: Prepared Customizations](https://www.loopandlearn.org/custom-code#prepared-custom-list). You can use (and re-use) your customizations with either Browser Build or *Mac* builds so you don't have to repeat the customization with every update. - * If you are building with Mac-Xcode method, you can use the same lines prepared for Build with Browser method and simply paste them in your terminal at the LoopWorkspace folder to customize your code + * If you are building with *Mac* method, you can use the same lines prepared for Build with Browser method and simply paste them in your terminal at the LoopWorkspace folder to customize your code * You can often use the same customization for several releases * If a customization that you prepared for an older release says "does not apply" when you use it, you'll need to prepare a new one @@ -44,7 +44,7 @@ * Just follow the steps on this page again to replace the customization that did not work * If there is an update (new release) and the customization applies with no errors, then you do NOT need to create an update * It is a good idea to test each customization as soon as you install the new build on your phone - * LoopDocs: Decide on Modules to modify using the [LoopDocs: Code Customization](../build/code-customization.md) page + * LoopDocs: Decide on Modules to modify using the [LoopDocs: Code Customization](../version/code-custom-edits.md) page * You only need to create your own customization if what you want is not provided at [Loop and Learn: Customization List](https://www.loopandlearn.org/custom-code#custom-list) * *GitHub* (each Module): 1. Copy Module (if needed) - this is your copy where you will make changes @@ -71,7 +71,7 @@ There is some background information at the bottom of this page starting at  ## Decide Which Modules You Want to Modify -Decide which [LoopDocs: Code Customization](../build/code-customization.md) changes you want to make. Each customization lists a Module name. +Decide which [LoopDocs: Code Customization](../version/code-custom-edits.md) changes you want to make. Each customization lists a Module name. * DASH Pods: Use OmniBLE * Eros Pods: Use OmniKit @@ -168,7 +168,7 @@ When you "fork a repository" (make a copy), the Open your browser to your https://github.com/username/Module URL. Be sure to sync your copy if it shows it is behind the LoopKit repository. -Navigate to the file you need to modify (using the instructions to find the lines from the [LoopDocs: Customization Page](../build/code-customization.md#instructions-for-finding-the-lines)) +Navigate to the file you need to modify (using the instructions to find the lines from the [LoopDocs: Customization Page](../version/code-custom-edits.md#instructions-for-finding-the-lines)) !!! tip "Pro Tip" Look at the files you want to change - if more than one change is desired for a single file - do them at the same time. diff --git a/docs/gh-actions/gh-deploy.md b/docs/gh-actions/gh-deploy.md index cd98613d3c5..4a57090780b 100644 --- a/docs/gh-actions/gh-deploy.md +++ b/docs/gh-actions/gh-deploy.md @@ -82,7 +82,7 @@ Once the app is installed one time, you can adjust whether it is automatically i Go back to the *TestFlight* app on your phone and tap on your app name in the list to see an expanded screen similar to the graphic below. The row to enable or disable automatic updates is highlighted in the graphic, which shows the feature disabled. This is recommended for all users. * If you leave automatic update enabled (default), then whenever a new build is created and uploaded to *TestFlight* , it will be installed immediately. -* WARNING: If you switch between Building with Browser and Mac-Xcode, you must disable automatic update or Xcode will not be able to install to your phone. +* WARNING: If you switch between Building with Browser and *Mac*, you must disable automatic update or Xcode will not be able to install to your phone. ![enable or disable automatic update for Loop](img/testflight-auto-update.png){width="300"} {align="center"} diff --git a/docs/gh-actions/gh-errors.md b/docs/gh-actions/gh-errors.md index 92c2ae21e00..f193ff7ca96 100644 --- a/docs/gh-actions/gh-errors.md +++ b/docs/gh-actions/gh-errors.md @@ -492,3 +492,4 @@ For example, the graphic below shows a failure of GitH This is an example of a message that is not terribly descriptive - which is why it is shown here. In this case, you can click on just the one job that failed. There will be less to sort through to find your error. The most likely reason for this error is [Error: Could not Create](#error-could-not-create). If you run across an error that does not have a nice message, be sure to post as discussed in [Help with Errors](#help-with-errors). You may be contributing to future improvements for this process. + diff --git a/docs/gh-actions/gh-first-time.md b/docs/gh-actions/gh-first-time.md index 782d3c32716..f6796992d37 100644 --- a/docs/gh-actions/gh-first-time.md +++ b/docs/gh-actions/gh-first-time.md @@ -48,9 +48,9 @@ ???+ question "FAQs (click to open/close)" - **Do I need a Mac computer?** No. This can be done on any browser, although it will be easier using a computer or tablet than just using a phone. - **Can I do this on my phone?** Yes, but the graphics shown on this page are from a computer browser. - - **Isn't it hard to build every 90 days?** The initial setup and installation take a lot of your focused time. But once you build once, subsequent builds take very little of your time to start, then the rest is done automatically. + - **Isn't it hard to build every 90 days?** The initial setup and installation take a lot of your focused time. But once you build once, subsequent builds take very little of your time to start the build. The rest is done automatically. - **Can I use this for my child?** You, as the adult, can install using *TestFlight* on your child's phone. The explicit steps are provided at [Install on Phone: *TestFlight* for a Child](gh-deploy.md#testflight-for-a-child). - - **Can I still use my customizations?** Yes. [Customize with Browser](gh-customize.md) + - **Can I still use my customizations?** Yes. [Customize using Browser](custom-browser.md) - **Is there a build video?** Yes. [How to Build the *Loop* App With a Web Browser](https://www.youtube.com/watch?v=kiu5ho0MTW8) ## Tips and Tricks @@ -335,7 +335,7 @@ Review the graphic and then follow the directions below to save more parameters 1. The contents of this file will be used for `FASTLANE_KEY` * Copy the full text, including the "`-----BEGIN PRIVATE KEY-----`" and "`-----END PRIVATE KEY-----`" lines - * On a **Mac**, use ++command+"A"++, then ++command+"C"++ to copy all the contents + * On a *Mac*, use ++command+"A"++, then ++command+"C"++ to copy all the contents * On a **PC**, use ++control+"A"++ , then ++control+"C"++ to copy all the contents * In the file where you are saving information, paste this with the indication that it is for `FASTLANE_KEY` @@ -725,7 +725,7 @@ The `Add Identifiers`  Action  should s ## Configure Identifiers for Loop -Some steps can be skipped if you previously built the *Loop* app with `Mac-Xcode`. +Some steps can be skipped if you previously built the *Loop* app with `*Mac*`. Please read carefully to avoid confusion. @@ -754,7 +754,7 @@ If you have never built the *Loop* app with *Xcode* using your `TEAMID`, you nee ### Add `App Group` to Identifiers -[:material-skip-forward:](#previous-xcode-builders) If you ever built the *Loop* app using Mac-Xcode, skip ahead to [Previous Xcode Builders](#previous-xcode-builders). +[:material-skip-forward:](#previous-xcode-builders) If you ever built the *Loop* app using *Mac*, skip ahead to [Previous Xcode Builders](#previous-xcode-builders). #### New Builders @@ -784,7 +784,7 @@ Because you built the *Loop* app using *Xcode*, then the **`NAME`** associated w !!! warning "Loop dev Builders" The name and identifier for "`Small Status Widget`" has been renamed to "`Loop Widget Extension`". This only affects those using the dev branch until the next release. At that time, this table will be updated. - If you are building with the dev branch, follow the directions at [One-Time Changes](../gh-actions/gh-update.md#one-time-changes). + If you are building with the dev branch, follow the directions at [One-Time Changes](../gh-actions/build-dev-browser.md#one-time-changes). ### Add or Review Configuration for `Loop Identifier` @@ -1062,10 +1062,34 @@ Refer to the graphic below for the first four steps: * Ignore the one that says you need to fix "issues" in your app. You are not selling the app in the app store; so no action is required. The app you built is for personal use for you or a family member. 1. Your app should eventually appear on [`App Store Connect`](https://appstoreconnect.apple.com/apps). +## Build Failed? + +Did you get a red X? Head over to the [Errors with Browser](gh-errors.md) to page find a solution. + +## Successful Build + +**Congratulations** + +If you get the green check mark, your app successfully built. Just a few more steps. + +### One Time Only (per User) + +* Add users to your `App Store Connect` Users and Access by following the directions at [Set Up Users and Access (TestFlight)](#set-up-users-and-access-testflight) +* Continue following instructions to create an Internal Testing group for *TestFlight* for the *Loop* app +* Add the Users to the Internal Group and they get an email they must confirm + +### Each Time + +* Go to the phone for installing the updated app from *TestFlight* +* If you already set up your users, skip ahead to [Install on Phone](gh-deploy.md) + ## Set Up Users and Access (TestFlight) Once the first build completes, you will be able to configure *TestFlight* for the app. +!!! tip "Add Each Users One Time" + Once you add a user to have access to your TestFlight for this app, you don't need to do it again - it remains available to them across rebuilds and different versions for that app. + You are configuring a private capability for your family using an Internal Testing group. You need the *Apple ID* email address for each adult installing from your build. When building for a child, you will use your own *Apple ID*, not theirs. See [*TestFlight* for a Child](gh-deploy.md#testflight-for-a-child). 1. First you need to add the email address(es) to your *App Store Connect* Access Users list: @@ -1102,6 +1126,10 @@ You are configuring a private capability for your family using an Internal Testi The [Install on Phone](gh-deploy.md) page walks you through the steps to use the *TestFlight* app to install the *Loop* app on a phone. +But wait - there's more. + +* Caregivers who help manage a loved-ones diabetes often use other open-source apps that can be built the same way +* When you are done building and installing the *Loop* app, there are instructions to [Build Other Apps with Browser](gh-other-apps.md) ## Extra Steps @@ -1116,7 +1144,7 @@ If your copy is **not** from `LoopKit`, follow the [Delete and Start Fresh](#del If your copy is from `LoopKit`: * Open your LoopWorkspace repository (`https://github.com/username/LoopWorkspace`) where you use your *GitHub* `username` in the URL -* Review the graphic in the [Successful Fork](#successful-fork) section +* Review the graphic in the [Configure: Successful Fork](#successful-fork) section * Make sure all the items highlighted by red rectangles are correct with the possible exception of your fork being up to date * If you see a message that your *fork* is not up to date - tap on the `Sync fork` button and follow the instructions * Continue with [Create `GitHub Personal Access Token`](#create-github-personal-access-token) @@ -1161,4 +1189,3 @@ If you were just trying to clean up the identifiers, then follow these steps: * Complete the [Add `App Group` to Other Identifiers](#add-app-group-to-other-identifiers) * If you did not complete the [Create Loop App in App Store Connect](#create-loop-app-in-app-store-connect) step, do it now * Continue with [Create Certificates](#create-certificates) and then [Build the *Loop* App](#build-the-loop-app) - diff --git a/docs/gh-actions/gh-other-apps.md b/docs/gh-actions/gh-other-apps.md index 33715565321..f0d4d8bd65b 100644 --- a/docs/gh-actions/gh-other-apps.md +++ b/docs/gh-actions/gh-other-apps.md @@ -40,7 +40,7 @@ The same technique is used and the same six Secrets are applied to ### Multiple Copies of `Loop Follow` -For the convenience of caregivers who use `Loop Follow` to monitor multiple people, updates were added in v2.1.2 to make this more convenient. This works regardless of the build method. (Build with Browser or [Build with Mac-Xcode](https://www.loopandlearn.org/loop-follow#lf-script)). +For the convenience of caregivers who use `Loop Follow` to monitor multiple people, updates were added in v2.1.2 to make this more convenient. This works regardless of the build method. (Build with Browser or [Build with *Mac*](https://www.loopandlearn.org/loop-follow#lf-script)). * Build up to three instances of `Loop Follow` * Customize the name of the app that appears on your phone diff --git a/docs/gh-actions/gh-overview.md b/docs/gh-actions/gh-overview.md index 4e55a15147f..fb0f86f5d6f 100644 --- a/docs/gh-actions/gh-overview.md +++ b/docs/gh-actions/gh-overview.md @@ -8,23 +8,19 @@ * *Mac* computer is not required to build or install the app * Anything with a browser works to build the *Loop* app: PC, Tablet, Mac or iPad * The *TestFlight* app is used to install the *Loop* app on your iPhone -* Xcode is not required - * The time required for the initial setup for building with a browser may take less time than one *macOS* and *Xcode* version update for those using [*Mac-Xcode* Build](../build/overview.md) +* Compatible version of *Xcode* is provided by *GitHub* + * The time required for the initial setup to build with a browser may take less time than one *macOS* and *Xcode* version update for those using [Build with *Mac*](../build/overview.md) * Updates are easy * Starting an update takes a few minutes of your time; the rest is automatic * Planned for the next release: app will build automatically at least once a month and is checked for updates once a week ### Considerations for Building with a Browser +* After the *GitHub* Build starts, your app is ready to install on your *iPhone* in about an hour * The app is delivered to your phone via *TestFlight* * The app is considered "Beta" by *Apple* and expires after 90 days * With the next release, which includes automatic builds, this will be even easier than it is now -* After the *GitHub* Build starts, the process takes about an hour to complete - * You receive an email indicating success (or failure) - * The _Loop_ app appears in the *TestFlight* app on the phone, where it can be installed in seconds -* Frequently used customizations are easy to copy and paste as documented at [_Loop and Learn: Loop Customization_](https://www.loopandlearn.org/custom-code#custom-list) -* Personalized code customizations are tedious to set up but easy to maintain - * Instructions are documented at [Customize using Browser](../gh-actions/gh-customize.md) +* Customization methods are documented at [Customize with Browser](custom-browser.md) ## Requirements @@ -85,7 +81,7 @@ If you get an error, please consult: For experienced and/or advanced users who want to build the development version of the app, there is additional information at the link below. If you have not built using the browser build method before, it is strongly recommended you first build the released version. Once you have a successful build, then follow the steps for the development version. Building the app is independent of installing the app on your phone from *TestFlight*. -* [Build Development Version](gh-update.md#build-development-version) +* [Build Development Version](build-dev-browser.md) ## What if I get stuck? diff --git a/docs/gh-actions/gh-update.md b/docs/gh-actions/gh-update.md index 23fa1d9b952..8d72e1e4365 100644 --- a/docs/gh-actions/gh-update.md +++ b/docs/gh-actions/gh-update.md @@ -2,7 +2,7 @@ **This page is only relevant when building with a browser.** -**For *Mac-Xcode*, please see: [Update/Rebuild with *Mac-Xcode*](../build/updating.md)** +**For *Mac*, please see: [Update/Rebuild with *Mac*](../build/updating.md)** ???+ info "Time Estimate (click to open/close)" Build the *Loop* App @@ -27,10 +27,8 @@ If your *GitHub* `Personal Access Token` has expired, we recommend you update it with `No Expiration` as explained at [GitHub Token](#github-token). - If you are running `Loop-dev`, be sure to review [Build Development Version](#build-development-version) + If you are running `Loop-dev`, be sure to review these instructions but modify for the branch you are using: refer to [Build Loop dev with Browser](build-dev-browser.md) - * You should be following along with zulipchat when using the `dev branch` - * Summary build updates can be found under the [One-Time Changes](#one-time-changes) section ???+ question "FAQs (click to open/close)" - **"What is an update?"** Anytime you want to change versions or if your *TestFlight* build is about to expire, follow the instructions on this page. @@ -255,7 +253,7 @@ In this example, the branch and commit number are included followed by an indica !!! tip "Commit Number" If your build includes customizations, your commit number will not match what the developer expects to see if you need to ask for help. - Use this section [Customization and SHA-1](gh-customize.md#customization-and-sha-1) to determine the SHA-1 before customization. + Use this section [Customization and SHA-1](edit-browser.md#customization-and-sha-1) to determine the SHA-1 before customization. ### Select a Previous Build @@ -391,302 +389,4 @@ Scroll all the way to the top of the screen and tap on your LoopWorkspace link. ## Build Development Version -You can build any desired branch (available at LoopKit/LoopWorkspace) using the *GitHub* Browser build method. This section is suitable if you have already built either dev or main branch using the [GitHub First-Time](gh-first-time.md) instructions. - -**No matter the method used to build Loop for any branch other than main, you are testing development code. Please read this link now before continuing.** - -* **[What's going on in the dev branch](../version/development.md#whats-going-on-in-the-dev-branch)** - -The graphics show the dev branch. If you want a different branch, just substitute that branch name for dev. - -!!! tip "Overview of what you will do" - 1. Your `LoopWorkspace fork` must have the `branch` you want - * You will either add it or make sure it is up to date - * You cannot just rename your existing branch to dev - you must get the dev branch from LoopKit - 1. When you select the action `4. Build Loop` and then click on the `Run Workflow` dropdown, you must select `dev` there before clicking the green `Run workflow` button - see [Build `Branch`](#build-branch) - - -### Check Current `Branch` - -Your `LoopWorkspace fork` is at `https://github.com/username/LoopWorkspace` where you substitute your actual *GitHub* `username`. You need to be logged into *GitHub*. Review the graphic below as you go through the steps. - -1. Click on the `branch` icon to display the `branches` as shown in the lower half of the graphic below: - * If the `branch` you want is not listed, then continue with Step 2 - * Otherwise, skip ahead to [Update `Branch`](#update-branch) -1. Click on the `New branch` button and follow the [Add `Branch`](#add-branch) steps - -![steps to add a branch](img/add-branch-01.svg){width="700"} -{align="center"} - -### Add `Branch` - -Each step in the list below matches with the number in the graphic. In the top half of the graphic, the left side shows the initial display and the right side shows the display after making the indicated selections: - -1. Click on the drop down menu labeled 1 in the graphic and choose LoopKit/LoopWorkspace as show in the top right graphic -2. Click on the drop down menu labeled 2 in the graphic and choose dev -3. Click on the `Branch` name box labeled 3 in the graphic and type dev - * The branch name in your `fork` should always match the branch name you are adding; check that you type it correctly -4. Review the dialog items to make sure everything is correct and then tap on Create branch - -![steps to add a branch continued](img/add-branch-02.svg){width="700"} -{align="center"} - -### Update `Branch` - -Tap the `Code` button (upper left) and ensure this branch in your `fork` is up to date. - -* Select the desired branch in the dropdown menu (this graphic shows dev branch) -* If the message indicates this branch is "behind", tap on the sync `fork` button and then the Update branch button - -![message displayed when your fork of LoopWorkspace is behind LoopKit version](img/github-build-check-fork-status.svg){width="700"} -{align="center"} - -### One-Time Changes - -Look in this section for one-time changes for building dev with a browser that require special, one-time actions. - -If you have already completed the One-Time Changes, skip ahead to [Build `Branch`](#build-branch). - -#### Transition to dev - -When updating from _Loop_ 3.2.x to dev, you will need to take some extra steps. - -You have a choice: - -* You can change your default branch to dev, see [Change Default `Branch`](#change-default-branch) and then your _Loop_ app will be automatically updated and automatically built at least once a month - * Be sure to review the [Modify Automatic Building](#modify-automatic-building) section -* You can leave your default branch at main, but no automated updates will happen - * Running each action below requires you to select the dev branch in the drop-down menu - -Here is a summary of the extra steps; each step has an associated link. This assumes you have already updated your `fork` and are at the correct branch. - -1. Confirm the status of your  *GitHub* Personal Access Token - * It should be configured with permission scope of `repo, workflow` and to never expire - * You can check this using directions at [*GitHub* Token](#github-token) -1. Next, follow along in this section to perform these steps before you build - * Add and Update `New Indentifier` - * `Create Certificates` - -#### Automatic Creation of `alive branch` - -!!! warning "What about the `alive branch`" - * Sometimes you get an error about the `alive branch` - * It should be created for you automatically if you are building with the `dev branch` **and** you have `workflow` permission added to the `scope` for your *GitHub* `Personal Access Token` - * Try one more time and if it still fails, you can [Create the `alive branch` Manually](#create-the-alive-branch-manually) - -#### Add and Update New `Identifier` - -The `bundle ID` for the "`widget`" changed from "`SmallStatusWidget`" to the more descriptive "`LoopWidgetExtension`". - -* You need to run Add Identifier - be sure that you run this for the dev branch -* Wait for it to succeed -* Add the `App Group` to this one new Identifier - -All other identifiers should be already set up. If they are not, please go through the steps on the [Configure to Use Browser](gh-first-time.md) page to figure out what you are missing. - -| `NAME` | `IDENTIFIER` | -|-------|------------| -| `Loop Widget Extension` | `com.TEAMID.loopkit.Loop.LoopWidgetExtension` | - -* Open the [Certificates, Identifiers & Profiles: Identifiers List](https://developer.apple.com/account/resources/identifiers/list) page. -* Click on the "`LoopWidgetExtension`" identifier -* Edit the App Group to include `group.com.TEAMID.loopkit.LoopGroup` where you use your `TEAMID` - -#### Create Certificates and Build - -You must create certificates again to cover the new Identifier name and to provide support for the addition of the Libre sensors. (This step is required whether you use Libre or not - Loop needs permission to have that capability). Once the certificate action succeeds, then run the action to build Loop. - -1. Run the Action for Create Certificates - be sure that you run this for the dev branch -1. Run the Action for `Build Loop` (see [Build `Branch`](#build-branch)) - -### Build `Branch` - -If you want a branch to be the one you build all the time, you may choose to [Change Default `Branch`](#change-default-branch). This is not necessary except for special cases. - -If you have one branch as default, for example main, and choose to build a different branch, there is an extra step when you `Build Loop`. Refer to step 4 in the graphic below. Use the branch dropdown menu to select the branch you want before hitting the green Run workflow button. - -![build loop using github actions](img/action-04-build-loop.svg){width="700"} -{align="center"} - -!!! - -## Change Default `Branch` - -There can be several reasons why you would change your default branch. - -* It can be convenient to have the branch you build most be configured as the default branch -* The branch you want to build has a different workflow than your default branch (not typical) - * In this case, you **must** modify the default branch - * Check the zulipchat conversation about the branch you are testing to see if it is necessary to make it default - -These are the steps to modify the default branch. - -For this example, we show how to change from a default branch of `main` to a default branch of `dev`. Note - only the owner of the repository can take this action and they must be logged in. Otherwise the Settings tab does not appear. - -For the numbered steps below, refer to the graphic found under each group of steps. - -1. Click on the Settings Icon near the top right of your LoopWorkspace - * You may need to scroll down to see the `Default Branch` as shown in the graphic - * Do not tap on the Branches tab to the left under Code and Automation, that is not the correct menu - - ![show default branch](img/gh-settings-branch-01.svg){width="700"} - {align="center"} - -1. To the right of the default branch name there is a pencil and a left-right arrow icon - * Tap on the left-right arrow icon to bring up the `Switch default branch to another branch` dialog -1. Click on the dropdown next to the current default branch, in this example, `main` -1. Select the desired default branch, in this example, `dev` -1. Click on the `Update` button - - ![modify default branch](img/gh-settings-branch-02.svg){width="700"} - {align="center"} - -1. You will be presented with an are-you-sure question. - * Click on the red `I understand, update the default branch.` button - - ![confirm default branch](img/gh-settings-branch-03.svg){width="400"} - {align="center"} - -Your default branch has been changed. - - -## Modify Automatic Building - -For someone using [development code](#build-development-version) for their own use, they probably want to decide when to update their `fork` to the most recent commit. They can still have the advantage of automatic building without automatic updates. There may be other configurations someone would choose. These options are added to Loop 3.3.0 and later. - -You can affect the default behavior: - -1. [Modify Automatic Schedule](#modify-automatic-schedule) -1. [Disable Automatic Actions](#disable-automatic-actions) - -### Modify Automatic Schedule - -You can modify the automation by creating and using some variables. - -To configure the automated build more granularly involves creating up to two environment variables: `SCHEDULED_BUILD` and/or `SCHEDULED_SYNC`. See [How to configure a variable](#how-to-configure-a-variable). - -Note that the weekly and monthly `Build Loop` actions will continue, but the actions are modified if one or more of these variables is set to false. **A successful Action Log will still appear, even if no automatic activity happens**. - -* If you want to manually decide when to update your repository to the latest commit, but you want the monthly builds and keep-alive to continue: set `SCHEDULED_SYNC` to false and either do not create `SCHEDULED_BUILD` or set it to true -* If you want to only build when an update has been found: set `SCHEDULED_BUILD` to false and either do not create `SCHEDULED_SYNC` or set it to true - * **Warning**: if no updates to your default branch are detected within 90 days, your previous TestFlight build may expire requiring a manual build - -|`SCHEDULED _SYNC`|`SCHEDULED _BUILD`|Automatic Actions| -|---|---|---| -| `true` (or NA) | `true` (or NA) | keep-alive, weekly update check (auto update/build), monthly build with auto update| -| `true` (or NA) | `false` | keep-alive, weekly update check with auto update, only builds if update detected| -| `false` | `true` (or NA) | keep-alive, monthly build, no auto update | -| `false` | `false` | no automatic activity, no keep-alive| - -### How to configure a variable - -1. Go to the "Settings" tab of your LoopWorkspace repository. -2. Click on `Secrets and Variables`. -3. Click on `Actions` -4. You will now see a page titled *Actions secrets and variables*. Click on the `Variables` tab -5. To disable ONLY scheduled building, do the following: - - Click on the green `New repository variable` button (upper right) - - Type `SCHEDULED_BUILD` in the "Name" field - - Type `false` in the "Value" field - - Click the green `Add variable` button to save. -7. To disable scheduled syncing, add a variable: - - Click on the green `New repository variable` button (upper right) - - - Type `SCHEDULED_SYNC` in the "Name" field - - Type `false` in the "Value" field - - Click the green `Add variable` button to save - -Your build will run on the following conditions: - -- Default behaviour: - - Run weekly, every Wednesday at 08:00 UTC to check for changes; if there are changes, it will update your repository and build - - Run monthly, every first of the month at 06:00 UTC, if there are changes, it will update your repository; regardless of changes, it will build - - Each time the action runs, it makes a keep-alive commit to the `alive` branch if necessary -- If you disable any automation (both variables set to `false`), no updates, keep-alive or building happens when `Build Loop` runs -- If you disabled just scheduled synchronization (`SCHEDULED_SYNC` set to`false`), it will only run once a month, on the first of the month, no update will happen; keep-alive will run -- If you disabled just scheduled build (`SCHEDULED_BUILD` set to`false`), it will run once weekly, every Wednesday, to check for changes; if there are changes, it will update and build; keep-alive will run - -### Disable Automatic Actions - -To enable the scheduled build and sync, the `GH_PAT` must hold the `workflow` permission scopes. This permission serves as the enabler for automatic and scheduled builds with browser build. To disable this, follow these steps: - -1. Go to your [FastLane Access Token](https://github.com/settings/tokens) -1. If it says `repo`, `workflow` next to the `FastLane Access Token` link, then automatic building is enabled -1. To disable automatic update and build, click on the link to open the token detail view - * Click to uncheck the `workflow` box - * Click to check the `repo` box -1. Scroll all the way down to and click the green `Update token` button -1. Your token now holds only the `repo` permission - -If you choose not to have automatic building enabled, be sure the `GH_PAT` has `repo` scope or you won't be able to manually build. - -## Stop Building - -What if I decide I don't want the automatic building feature? - -* If you are using the released version of Loop, please leave automatic building running - * Please read [TestFlight Automatic Updates](gh-deploy.md#testflight-automatic-updates) on how to configure TestFlight so you choose when the updated app gets installed on your phone - * Otherwise, you may see the dreaded "Loop Beta has expired" message, have a Loop that won't open and not have a version ready to go in TestFlight that you can install within a few seconds - -* If you are taking a break from Loop and want to stop monthly Build emails, consider disabling actions for the `Build Loop` action for your app. - * [GitHub Directions to Disable and Enable a Workflow](https://docs.github.com/en/actions/using-workflows/disabling-and-enabling-a-workflow#disabling-a-workflow) - * It is the Build action that kicks off the update and build steps, so simply disabling the one action is sufficient - -* If you are done with Loop, you can delete the whole repository; but you should be sure about this because you'll need to start over with [Configure to Use Browser](gh-first-time.md) to restore ability to build Loop with GitHub. - -## Historical Interest Only - -### Historical One-Time Changes - -You don't need this - it is left for historical reasons for people who have been following along with dev. - -**26-July-2023** - -The `bundle ID` for the "`widget`" changed from "`SmallStatusWidget`" to the more descriptive "`LoopWidgetExtension`". - -The table in LoopDocs (for main) will be updated after the next release. - -For those using dev, you must follow these one-time steps: - -1. Sync your `fork` to latest version of dev -1. Run the Action for Add Identifiers (this adds "`LoopWidgetExtension`" to identifiers) - * Open the [Certificates, Identifiers & Profiles: Identifiers List](https://developer.apple.com/account/resources/identifiers/list) page. - * Click on the "`LoopWidgetExtension`" identifier - * Edit the App Group to include `group.com.TEAMID.loopkit.LoopGroup` where you use your `TEAMID` -1. Run the Action for Create Certificates -1. Run the Action for `Build Loop` - -**03-July-2023** - -1. Libre support was added to dev (03 July 2023) using the LibreTransmitter code - * This requires (one-time) that the `Actions` for `2. Add Identifiers` and `3. Create Certificates` be run before attempting `4. Build Loop` - * The LibreTransmitter code requires `Near Field Communication` and doing these steps automatically adds the required capability -1. Automatic update and automatic monthly build was added to dev (13 July 2023) - * Once a month, *GitHub* will attempt to update and build Loop from your `default branch` using the instructions in the `Action: 4. Build Loop` (`build_loop.yml` file) and send the new app to *TestFlight* - * As part of this monthly build, *GitHub* will check to see if updates are required for your `default branch` - * When updates are not required, it just builds the app - * When updates are required: - * If it can figure out how to do the `sync` automatically, it does so - * If it cannot figure out how to do the `sync` automatically, the `Action` to `4. Build Loop` will fail and you will need to take manual steps - * You will get an email that the `Build` either succeeded or failed - -!!! info "Automatic Update Requirements" - To enable the automatic update and rebuild, two steps are required. These are one-time steps. - - * The GH_PAT must be updated (not regenerated) to add `workflow` - * Examine your [`FastLane Access Token`](https://github.com/settings/tokens) - * If it says `repo, workflow`, then no further action is needed for your GH_PAT - * If it say `repo` only, then click on the `FastLane Access Token` link, click to add a check to the `workflow` box and scroll all the way down to select the green `Update token` button - * A new branch called `alive` must be created from the LoopKit `dev` branch - * This is now created automatically for you - -### Create the `alive branch` Manually - -The `alive branch` will receive some additional commits to its history. This is part of automating the process. The `alive branch` is not used for building the app. You do not need to interact with it. Make sure you don't already have an `alive branch`. If you do and you are getting errors, then delete the `alive branch` and try again. - -1. Go to the `Code` tab of your `repository` -1. Click the `branch` icon dropdown button, and then View all branches -1. Click the green `New branch` button (upper right) -1. Type `alive` in the `New branch name` field -1. Select `LoopKit/LoopWorkspace` as `Source` -1. Select `dev` in the `branch` dropdown. -1. Click the green `Create new branch` button \ No newline at end of file +The information to build a development (`dev` or any other branch) has been moved to a new page: [Build dev with Browser](build-dev-browser.md) diff --git a/docs/index.md b/docs/index.md index 5544dba251f..9beb4e5b237 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,29 +3,35 @@ hide: - navigation --- -## Welcome to _Loop_ +## The *Loop* App -Welcome to the *LoopDocs* website where you can learn about _Loop_. +Welcome to the *LoopDocs* website where you can learn about the *Loop* app. -This site shows you step-by-step how to **build**, **set up** and **operate** the _Loop_ app. +This site shows you step-by-step how to [**build**](intro/requirements.md), [**set up**](loop-3/loop-3-overview.md) and [**operate**](operation/loop/open-loop.md) the *Loop* app. * **You do not need a technical or computer background to do this** -* **You can choose to build the _Loop_ app using a [browser](gh-actions/gh-overview.md) on any computer and install it on your Apple phone via *TestFlight* ** +* **You can choose to build the *Loop* app several ways:** + * Use a [browser](gh-actions/gh-overview.md) on any computer or tablet and install it on your *iPhone* via *TestFlight* + * Use an up-to-date [*Mac* Computer](build/overview.md) and install it directly on your *iPhone* -In order to become a proficient with the app, you should learn the information on this site. Consider doing this over a period of time and reviewing the materials more than once. +In order to become proficient with the app, you should learn the information on this site. Consider doing this over a period of time and reviewing the materials more than once. -* You should test and perhaps adjust your settings to be successful with _Loop_ (or any hybrid closed-loop system) +* You should test and perhaps adjust your settings to be successful with the *Loop* app (or any hybrid closed-loop system) * You will find links as you read to a robust volunteer support community -Once you are using the app, you should regularly follow one or more support forums for important updates on _Loop_. Spending this time is important for success in building and operating _Loop_ safely. +There is a common saying in our community: -This website is updated regularly to keep pace with _Loop_ developments and *Apple* releases. +> Do It Yourself (DIY) does not mean Do It Alone! -## What is _Loop_? +Once you are using the app, you should regularly follow one or more support forums for important updates on the *Loop* app. Spending this time is important for success in building and operating the *Loop* app safely. -_Loop_ is an app you build and load on an iPhone. +This website is updated regularly to keep pace with development of the *Loop* app and *Apple* releases. -After building the _Loop_ app: +## What is the *Loop* App? + +The *Loop* app is an automated insulin delivery application that you build and load on an iPhone. + +After building the *Loop* app: * You enter your personal therapy settings (e.g., carbohydrate ratio, basal rates, insulin sensitivity) * You enter the carbs you eat @@ -37,7 +43,7 @@ After building the _Loop_ app: ### What is _Loop_ Video -If you have never used _Loop_, click on links below for an introduction. +If you have never used the *Loop* app, click on links below for an introduction. !!! success " _Loop_ Video" * This [What is _Loop_](https://youtu.be/64qhgnmkyAE) video with associated [pdf deck](http://www.loopandlearn.org/wp-content/uploads/2021/05/What-is-Loop.pdf) was created by the Loop and Learn team @@ -48,12 +54,11 @@ If you have never used _Loop_, click on links b Please consult with your health care professional regarding your diabetes management. -* The _Loop_ app is an open source project used by many, but it is not approved for therapy by any government organization. +* The *Loop* app is an open source project used by many, but it is not approved for therapy by any government organization. * **You take full responsibility for building and running this system and do so at your own risk.** ## Volunteer Community -_Loop_ has been, and continues to be, developed and supported by volunteers. From the code to this website, you are able to use this app because many volunteers have given their personal and family time. +The *Loop* app has been, and continues to be, developed and supported by volunteers. From the code to this website, you are able to use this app because many volunteers have given their personal and family time. Please add your time by reading this website before embarking on your _Loop_ journey. - diff --git a/docs/intro/overview-intro.md b/docs/intro/overview-intro.md index 2b658a4514d..8889dac4c12 100644 --- a/docs/intro/overview-intro.md +++ b/docs/intro/overview-intro.md @@ -9,7 +9,7 @@ The LoopDocs website is organized as follo * [Requirements](requirements.md): What is needed regardless of build method * New with Loop 3: Two ways to build - you get the same app either way * [Build with Browser](../gh-actions/gh-overview.md): Build Loop app using a browser - * [Build with Mac-Xcode](../build/overview.md): Build Loop app with a Mac the first time, or [Update](../build/updating.md) next time + * [Build with *Mac*](../build/overview.md): Build Loop app with a Mac the first time, or [Update](../build/updating.md) next time * [Set Up](../loop-3/loop-3-overview.md): How to set up the Loop app * [Operate](../operation/loop/open-loop.md): How to use the Loop app * [Troubleshoot](../troubleshooting/overview.md): What to do if you're having trouble with the Loop app diff --git a/docs/intro/requirements.md b/docs/intro/requirements.md index 2ca00269742..96bdc974696 100644 --- a/docs/intro/requirements.md +++ b/docs/intro/requirements.md @@ -3,16 +3,16 @@ With the release of _Loop 3_ , there are two ways to build the app. * If you have never built _Loop_ before, we recommend you use the Build with Browser method. -* If you use a Mac and keep the operating system up to date all the time, then you may prefer the Mac-Xcode method. +* If you use a Mac and keep the operating system up to date all the time, then you may prefer the Build with *Mac* method. The Build Steps have been split into two tabs: * [Build with Browser](../gh-actions/gh-overview.md) * Build with a browser on any computer or tablet - * App is installed on the phone using *TestFlight* -* [Build with Mac-Xcode](../build/overview.md) - * App is built on a Mac with Xcode connected to the phone - * The operating system on the Mac and the version of Xcode must be kept up-to-date + * App is installed on the iPhone using *TestFlight* +* [Build with *Mac*](../build/overview.md) + * App is built on a *Mac* with *Xcode* connected to the iPhone + * The operating system on the *Mac* and the version of *Xcode* must be kept up-to-date There are some requirements common to both methods. Some requirements are specific to only one method. @@ -23,10 +23,13 @@ These requirements are independent of how you build the Loop app: 1. [Compatible iPhone](../build/phone.md) 1. [Compatible Pump](../build/pump.md) 1. [Compatible CGM](../build/cgm.md) -1. [RileyLink Compatible Device](../build/rileylink.md) (not needed for Omnipod DASH) +1. [RileyLink Compatible Device](../build/rileylink.md) + * Not needed with Omnipod DASH + * Required for Medtronic and Omnipod Eros 1. [Apple Developer Membership](../build/apple-developer.md) - * For Browser Build - must be a paid developer account * If building for a child, be sure to read [Loopers Need Their Own Apple ID](../build/apple-developer.md#loopers-need-their-own-apple-id) + * Build with Browser - requires a paid developer account + * Build with *Mac* - can build a free version with some limitations and must rebuild weekly ### Added Requirements to [Build with Browser](../gh-actions/gh-overview.md) @@ -36,9 +39,9 @@ If you plan to build using the Build with Browser instructions, you also need: Detailed instructions are included in the link above. -### Added Requirements to [Build with Mac-Xcode](../build/overview.md) +### Added Requirements to [Build with *Mac*](../build/overview.md) -If you plan to build using the Mac-Xcode Build instructions, you also need: +If you plan to build using the Build with *Mac* instructions, you also need: 1. [Compatible Computer](../build/computer.md#macos) 1. [Xcode](../build/xcode-version.md) (a free Apple application) @@ -71,6 +74,6 @@ Before you start either build method, review the Common Requirements. First one Click on the link if you are done reviewing the common requirements and you want to skip ahead to [Build with Browser](../gh-actions/gh-overview.md). -### Build with Mac-Xcode +### Build with *Mac* -Click on the link if you are done reviewing the common requirements and you want to skip ahead to [Build with Mac-Xcode](../build/overview.md). +Click on the link if you are done reviewing the common requirements and you want to skip ahead to [Build with *Mac*](../build/overview.md). diff --git a/docs/loop-3/add-cgm.md b/docs/loop-3/add-cgm.md index 90e013fb24c..76de333bd60 100644 --- a/docs/loop-3/add-cgm.md +++ b/docs/loop-3/add-cgm.md @@ -166,7 +166,7 @@ In addition to the risks of missing data if the internet is not reliable, you mu _Sensors that can be added to Nightscout via other apps include Dexcom, some Libre and some Medtronic sensors. Please refer to [Nightscout Docs: Configure your Uploader](https://nightscout.github.io/uploader/setup/)._ - There are third party apps that bring Libre data to your Loop phone and there are customization instructions starting at [Libre Support for Loop 3.2.x Code](../build/code-customization.md#libre-support-for-loop-32x-code) that explain how to modify Loop 3 to use one of those apps. Please use these steps to get a version of Loop that does not rely on internet access to work. + There are third party apps that bring Libre data to your Loop phone and there are customization instructions starting at [Libre Support for Loop 3.2.x Code](../version/code-custom-edits.md#libre-support-for-loop-32x-code) that explain how to modify Loop 3 to use one of those apps. Please use these steps to get a version of Loop that does not rely on internet access to work. It is recommended that you use Open Loop during warmup until the new sensor begins to provide reasonable data. This is especially important with European Libre 2 using direct bluetooth connection. diff --git a/docs/loop-3/onboarding.md b/docs/loop-3/onboarding.md index c10cc8414fe..2f2347cb3dd 100644 --- a/docs/loop-3/onboarding.md +++ b/docs/loop-3/onboarding.md @@ -357,6 +357,6 @@ If you used earlier versions of Loop, please be aware that absorption times have ### Carb Data Source -Loop 3 does not read non-Loop carbohydrate entries from Apple Health, as previous versions did. It still writes to Apple Health. Some experienced loopers want to modify the code to enable Loop to read carbohydrate records from Apple Health with the full understanding of how that works. The instructions for this code customization option, using a flag set in the LoopConfigOverride.xcconfig file, see the [Customize: Build-Time Features](../build/code-customization.md#build-time-features) section. +Loop 3 does not read non-Loop carbohydrate entries from Apple Health, as previous versions did. It still writes to Apple Health. Some experienced loopers want to modify the code to enable Loop to read carbohydrate records from Apple Health with the full understanding of how that works. The instructions for this code customization option, using a flag set in the LoopConfigOverride.xcconfig file, see the [Customize: Build-Time Features](../version/build-time-flag.md) section. Users who build Loop 3 over Loop 2.2.x, may find a permission switch to give Loop permission to read carb data from health, but without making the customization mentioned above, changing permission does not change the behavior of Loop. diff --git a/docs/loop-3/settings.md b/docs/loop-3/settings.md index d6fc0e870b6..07e2febfb3b 100644 --- a/docs/loop-3/settings.md +++ b/docs/loop-3/settings.md @@ -220,11 +220,11 @@ The time stamps within the JSON files use UTC. The Profile Expiration is reported at the bottom of the Settings display along with the number of days remaining before Loop stops working. -The link for `How to update (LoopDocs)` is provided for Mac-Xcode build. +The link for `How to update (LoopDocs)` is provided for build with *Mac*. In fine print, the exact date and time of the expiration is reported in your local time zone. -![display of profile expiration appropriate for Mac-Xcode build method](img/app-profile.png){width="350"} +![display of profile expiration appropriate for build with *Mac* method](img/app-profile.png){width="350"} {align="center"} The Profile Expiration is different for GitHub Browser Build method. A feature request is in place (but not yet added to the code) to report the TestFlight expiration for that build method. diff --git a/docs/loop-3/therapy-settings.md b/docs/loop-3/therapy-settings.md index 68190f3f940..2e54784632d 100644 --- a/docs/loop-3/therapy-settings.md +++ b/docs/loop-3/therapy-settings.md @@ -198,7 +198,7 @@ Loop has guardrails for Therapy Settings. * The limits for some settings can be altered by other therapy settings you have selected !!! tip "Experienced Loopers" - The guardrails for each therapy setting used by Loop can be modified with [Code Customization](../build/code-customization.md). + The guardrails for each therapy setting used by Loop can be modified with [Code Customization](../version/code-custom-edits.md). !!! danger "mmol/L" People using mmol/L should avoid the red (the min or max end points) glucose values for their settings. They sometimes cause a crash. diff --git a/docs/nightscout/loop-caregiver.md b/docs/nightscout/loop-caregiver.md index b14600a5596..7b131055913 100644 --- a/docs/nightscout/loop-caregiver.md +++ b/docs/nightscout/loop-caregiver.md @@ -1,4 +1,4 @@ -## *Loop Caregiver* ![icon for *Loop Caregiver* app](img/lcg-icon.jpg){width="50"} +## The *Loop Caregiver* App ![icon for *Loop Caregiver* app](img/lcg-icon.jpg){width="50"} The *Loop Caregiver* app is under development to make remote commands easier to implement and monitor. @@ -32,15 +32,15 @@ If you use *Loop Caregiver*, please join [*Loop Caregiver* App](https://loop.zul **As with all development code, monitor *Zulipchat* for announcements, report any problems you experience, be prepared to build frequently, and pay attention.** -## Build *Loop Caregiver* +## Build the *Loop Caregiver* App -You can build *Loop Caregiver* using the  GitHub Browser Build  method or the  [Mac-Xcode Build](#mac-xcode-build) method. +You can build the *Loop Caregiver* app using the [Build with Browser](#build-with-browser) method or the [Build with *Mac*](#build-with-mac) method. -### GitHub Browser Build: +### Build with Browser -The  GitHub Browser Build  method is documented on the [Other Apps](../gh-actions/gh-other-apps.md) page. +The Build with Browser method is documented on the [Build Other Apps with Browser](../gh-actions/gh-other-apps.md) page. -### Mac-Xcode Build: +### Build with *Mac* A build script is available to assist in building *Loop Caregiver*. This should be straightforward for anyone who has previously built  Loop 3  using the script. @@ -63,18 +63,18 @@ A build script is available to assist in building *Loop Caregiver*. This should - The script displays the directions for downloading and building. Please read them carefully. -!!! warning "Not _Loop_" - The output you see in the Terminal may look very similar to when you build *Loop 3* from a script. +!!! warning "Read Carefully" + The output you see in the Terminal may look very similar to when you build the *Loop* app from a script. - It is pulling down a clone from a different location (*LoopKit/LoopCaregiver*). It uses some modules from _Loop_. The target and scheme are automatically selected for *Loop Caregiver* and if you follow directions for a paid Developer account, the signing is automatic. + It is pulling down a clone from a different location (`LoopKit/LoopCaregiver`). It uses some modules from `Loop`. The target and scheme are automatically selected for `Loop Caregiver` and if you follow directions for a paid Developer account, the signing is automatic. -## Use *Loop Caregiver* +## Use the *Loop Caregiver* App Some limited directions for using the *Loop Caregiver* app are provided - please also read the *Zulipchat* stream to stay up-to-date with improvements - especially if you are using a development branch of  _Loop_. -### *Loop Caregiver* Add Looper +### Add Looper to the *Loop Caregiver* App -You must add a Looper to continue with *Loop Caregiver* as shown in the graphic below. +You must add a Looper to continue with the *Loop Caregiver* app as shown in the graphic below. ![add Looper to Loop Caregiver](img/lcg-add-looper.png){width="300"} {align="center"} @@ -97,9 +97,9 @@ You must add a Looper to continue with *Loop Caregiver* as shown in the graphic You can add additional more people under settings. (**Loop Caregiver* * can monitor more than one Looper). -### *Loop Caregiver* Main Screen +### Main Screen of the *Loop Caregiver* App -* *Loop Caregiver* * uses a lot of features from _Loop_ with some Nightscout-like features in the Timeline. +* *Loop Caregiver* uses a lot of features from _Loop_ with some Nightscout-like features in the Timeline. The Timeline: @@ -117,7 +117,7 @@ You can also use the *Loop Caregiver* -> `Settings` screen to modify: * Units used for glucose display: `mg/dL` or `mmol/L` * Include the _Loop_ forecast display on the Timeline chart as well as the Glucose chart of the main display (`Show Prediction` is turned off in the graphic above) -### Issue Remote Commands with *Loop Caregiver* +### Issue Remote Commands with the *Loop Caregiver* App You issue override, carb, and bolus commands using a toolbar similar to the one seen on _Loop_. In the example graphic above, the carb and bolus entries visible were issued remotely. diff --git a/docs/nightscout/remote-config.md b/docs/nightscout/remote-config.md index 0cd637cd05f..aa8b8fc158b 100644 --- a/docs/nightscout/remote-config.md +++ b/docs/nightscout/remote-config.md @@ -87,7 +87,7 @@ The step is required for the *Loop* app to give permissions to your *Nightscout* * **Click inside that file** * Highlight **all** the text, and then * Copy **all** the text to the clipboard (Cf. screenshot below). - * On a **Mac**, press ++command+"A"++ to select all, then press ++command+"C"++ to copy the selection. + * On a *Mac*, press ++command+"A"++ to select all, then press ++command+"C"++ to copy the selection. * On a **PC**, press ++control+"A"++ to select all, then press ++control+"C"++ to copy the selection. You don't have to do it right now...just keep that window open in the background for now until we need it a little further down. Then we will copy all that text. @@ -149,19 +149,19 @@ When executed properly, you should have something that looks like this for the t When the *Nightscout* config var LOOP_PUSH_SERVER_ENVIRONMENT does not match the *Loop* app build method; the error message contains the phrase `APNs delivery failed: BadDeviceToken`. * If _Loop_ was installed remotely (typically from TestFlight following GitHub Browser Build), you **must** have *Nightscout* config var `LOOP_PUSH_SERVER_ENVIRONMENT` set to `production` -* If _Loop_ was built using Mac-Xcode, you **cannot** have `LOOP_PUSH_SERVER_ENVIRONMENT` as one of your *Nightscout* config vars +* If _Loop_ was built using *Mac*, you **cannot** have `LOOP_PUSH_SERVER_ENVIRONMENT` as one of your *Nightscout* config vars ### Do Not Confuse Your Keys !!! danger "API Key vs APN Key" - If you build with the *GitHub* [Browser Build](../gh-actions/gh-overview.md), you may notice  the  Application Programming Interface (API)  key  has the same type of format as  the  Apple Push Notification (APN)  key. The keys for both purposes are of type `p8`, but should not be confused. + If you build with the [Build with Browser](../gh-actions/gh-overview.md), you may notice  the  Application Programming Interface (API)  key  has the same type of format as  the  Apple Push Notification (APN)  key. The keys for both purposes are of type `p8`, but should not be confused. The Secrets for building with *GitHub* use the API Key. The config vars for *Nightscout* use the APN Key. * If you are using remote commands with *Nightscout* and building with the **GitHub Browser** build method, you must also add the config var of `LOOP_PUSH_SERVER_ENVIRONMENT` with a value of `production` to your *Nightscout* site or the remote commands will not work. - * If you are using the **Mac-Xcode** build method, you should not have a config var of `LOOP_PUSH_SERVER_ENVIRONMENT` entered - remove it if it is present. + * If you are using the *Mac* build method, you should not have a config var of `LOOP_PUSH_SERVER_ENVIRONMENT` entered - remove it if it is present. ## Step 4: Test Remote Overrides diff --git a/docs/nightscout/remote-errors.md b/docs/nightscout/remote-errors.md index 4e5868e2cc9..56f1605b0a3 100644 --- a/docs/nightscout/remote-errors.md +++ b/docs/nightscout/remote-errors.md @@ -27,7 +27,7 @@ Verify that you performed all the [Remote Configuration](remote-config.md) steps When the *Nightscout* config var LOOP_PUSH_SERVER_ENVIRONMENT does not match the _Loop_ app build method; the error message contains the phrase `APNs delivery failed: BadDeviceToken`. * If _Loop_ was installed remotely (typically from TestFlight following GitHub Browser Build), you **must** have *Nightscout* config var `LOOP_PUSH_SERVER_ENVIRONMENT` set to `production` -* If _Loop_ was built using Mac-Xcode, you **cannot** have `LOOP_PUSH_SERVER_ENVIRONMENT` as one of your *Nightscout* config vars +* If _Loop_ was built using *Mac*, you **cannot** have `LOOP_PUSH_SERVER_ENVIRONMENT` as one of your *Nightscout* config vars If you attempt to issue a command from *Nightscout* Careportal; after you hit submit and then OK, you will see the error message: @@ -48,7 +48,7 @@ body: APNs delivery failed: BadDeviceToken ### *Loop* `REMOTE_OVERRIDES_DISABLED` -You can build Loop with [Build-Time Features](../build/code-customization.md#build-time-features) as part of code customization. +You can build Loop with [Build-Time Features](../version/build-time-flag.md) as part of code customization. If you added this Build-Time Flag: `REMOTE_OVERRIDES_DISABLED` diff --git a/docs/operation/algorithm/prediction.md b/docs/operation/algorithm/prediction.md index 3c2c453a98f..ead750d5ce1 100644 --- a/docs/operation/algorithm/prediction.md +++ b/docs/operation/algorithm/prediction.md @@ -26,7 +26,7 @@ Most traditional pump users and caregivers are already familiar with the concept Loop 2.x provides users with two different classes of insulin models (i.e., an exponential model and the Walsh model). All of the exponential models have an insulin activity duration of 6 hours, whereas the insulin activity duration is customizable for the Walsh model. The rapid-acting and Fiasp insulin activity curves are modeled as exponential curves that match the shape of the insulin activity curves from insulin labeling, and as observed in both adults and children. -Loop 3 drops the Walsh model and, by default, does not include the concept of child versus adult for "rapid" acting insulin, i.e., Humalog, Novalog and Apidra. Loop 3 adds the concept of non-pump insulin to account for injections or inhaled insulin. The Afrezza model is added as a non-pump insulin. The Insulin Type is selected in the Pump Settings screen. All insulin types are modeled by selecting parameters in the exponential model. See also [Exponential Insulin Curve](../../build/code-customization.md#exponential-insulin-curve) on the Code Customization page. +Loop 3 drops the Walsh model and, by default, does not include the concept of child versus adult for "rapid" acting insulin, i.e., Humalog, Novalog and Apidra. Loop 3 adds the concept of non-pump insulin to account for injections or inhaled insulin. The Afrezza model is added as a non-pump insulin. The Insulin Type is selected in the Pump Settings screen. All insulin types are modeled by selecting parameters in the exponential model. See also [Exponential Insulin Curve](../../version/code-custom-edits.md#exponential-insulin-curve) on the Code Customization page. ![insulin models](img/insulin_models.png) diff --git a/docs/operation/features/notifications.md b/docs/operation/features/notifications.md index efdd49d2016..f186ff2721a 100644 --- a/docs/operation/features/notifications.md +++ b/docs/operation/features/notifications.md @@ -29,7 +29,7 @@ Profile expiration notification was added with Loop 2.2.5. ### Free (7-day) Loop App Expiration Notification -The expiration notification pattern is the same as for the Paid Loop App. You may want to add an [Expiration Notification Customization](../../build/code-customization.md#expiration-notification-customization) to modify the first appearance and frequency of the notification. +The expiration notification pattern is the same as for the Paid Loop App. You may want to add an [Expiration Notification Customization](../../version/code-custom-edits.md#expiration-notification-customization) to modify the first appearance and frequency of the notification. ## Loop App Expiration Date diff --git a/docs/operation/features/watch.md b/docs/operation/features/watch.md index 72764200878..c49af48954b 100644 --- a/docs/operation/features/watch.md +++ b/docs/operation/features/watch.md @@ -119,7 +119,7 @@ If you enter carbs on your watch while not connected to the phone, they will app One feature on the Watch app that can be turned on and off with Loop 3 is the eventual glucose display on the watch. That display is shown on the graphic above with current glucose on left, trend arrow beside it and eventual (from prediction) glucose on the right. -If this is a feature you want turned off, please follow the directions on the Code Customization page (found under the Version tab): [Build Time Features](../../build/code-customization.md#build-time-features). +If this is a feature you want turned off, please follow the directions on the Code Customization page (found under the Version tab): [Build Time Features](../../version/build-time-flag.md). ## Adding a Watch to Existing Loop diff --git a/docs/operation/loop-settings/cgm.md b/docs/operation/loop-settings/cgm.md index ffa7ba26005..d2403fab8d4 100644 --- a/docs/operation/loop-settings/cgm.md +++ b/docs/operation/loop-settings/cgm.md @@ -63,7 +63,7 @@ If you switch to Loop 3, there are additional CGM options: * You can choose to download the Loop with patches option when building with the script. * As a prerequisite, you must interface your iPhone to the Libre - * Please read [Libre Support for Loop 3.2.x Code](../../build/code-customization.md#libre-support-for-loop-32x-code) + * Please read [Libre Support for Loop 3.2.x Code](../../version/code-custom-edits.md#libre-support-for-loop-32x-code) ## Next Step: Loop 2 Configuration diff --git a/docs/operation/loop-settings/configurations.md b/docs/operation/loop-settings/configurations.md index 6e8b6901283..1758f3ae120 100644 --- a/docs/operation/loop-settings/configurations.md +++ b/docs/operation/loop-settings/configurations.md @@ -112,7 +112,7 @@ There are four insulin models to choose from with Loop 2.x; Walsh, Rapid-Acting Loop 3 drops the Walsh model and, by default, does not include the concept of child versus adult for "rapid" acting insulin, i.e., Humalog, Novalog and Apidra. * Insulin Type is selected when the user adds a pump - * The user can choose to customize Loop 3 to [Enable Child Model](../../build/code-customization.md#enable-child-model) + * The user can choose to customize Loop 3 to [Enable Child Model](../../version/code-custom-edits.md#enable-child-model) **We highly recommend selecting one of the exponential insulin models for Loop 2.2.x (in other words, not the Walsh model).** diff --git a/docs/version/build-dev.md b/docs/version/build-dev.md index a7548db6e10..d2ba2b86bc1 100644 --- a/docs/version/build-dev.md +++ b/docs/version/build-dev.md @@ -2,72 +2,19 @@ **No matter the method used to build Loop-dev: GitHub actions or git commands, you are testing development code. Please read this link now before continuing.** -* **[What's going on in the dev branch](../version/development.md#whats-going-on-in-the-dev-branch)** +* **[What's going on in the `dev branch`](../version/development.md#whats-going-on-in-the-dev-branch)** -Several methods to build Loop-dev are mentioned on this page: +There are several methods to build Loop-dev. First review the general information on this page then choose the link for the method of your choice: -1. For the GitHub Browser Build method - * [Update Loop-dev: GitHub Build method](#github-build-method) -1. For the Mac-Xcode method: - * [Update Loop-dev: Mac-Xcode Build method](#mac-xcode-build-method) +## Update Frequently -## BuildLoopDev Script - -There is a script to assist in building the dev branch. It gives you the option to choose the tip of the dev branch or to build a lightly tested commit. If you have not used the [Build Select Script](../build/build-app.md#build-select-script) to build Loop previously, you may want to review that page. - -``` { .bash .copy title="Copy and Paste to start the BuildLoopDev script" } -/bin/bash -c "$(curl -fsSL \ - https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildLoopDev.sh)" -``` -### BuildLoopDev Script Libre - -There used to be a section here telling you how to build a special branch that had Libre support included. That is no longer necessary because [LibreTransmitter](https://github.com/dabear/LibreTransmitter#libretransmitter-for-loop) support was merged into dev in July 2023. - -If you use the Browser Build method to build the dev branch, be sure to read about and do the [One Time Steps for dev](../gh-actions/gh-update.md#one-time-changes). - -Both the dev branch and the lightly tested branch of dev have Libre support. - -### BuildLoopDev Other Branches - -You can use the BuildLoopDev script to build a specific development branch, other than dev. See the example below that would build `other-branch`, if such a branch existed. This is just an example. You need to substitute the branch you desire for `other-branch`. There must be a space after the final quote, followed by a hyphen, another space and then the branch name. - -``` { .bash .copy title="Example using other-branch with the BuildLoopDev script" } -/bin/bash -c "$(curl -fsSL \ - https://raw.githubusercontent.com/loopandlearn/lnl-scripts/main/BuildLoopDev.sh)" - other-branch -``` - -## Update Loop-dev - -While Loop-dev is under active development, you should monitor zulipchat and update frequently. - -### GitHub Build Method - -If you are using the GitHub method, once you have configured your fork to point to the dev branch, just follow the update instructions. - -* [Browser Build for dev](../gh-actions/gh-update.md#build-development-version) - -### Mac-Xcode Build Method - -You can use TestFlight with this method if you want the convenience of a remote build. See [TestFlight with your Mac-Xcode build](../build/testflight-xcode.md). With TestFlight, you need to renew the build every 90 days. - -When building frequently, it is optional to update your provisioning profile with every new build. If you want to always ensure one year, copy and paste the following command into the terminal before building. This forces Xcode to create a new provisioning profile instead of reusing one with an older expiration date. - -```title="Copy and Paste to remove Provisioning Profiles" -rm ~/Library/MobileDevice/Provisioning\ Profiles/*.mobileprovision -``` +While Loop-dev is under active development, you should monitor zulipchat and update frequently. Sometimes the `dev` branch is quiet for a month or more and other times it gets updated daily. Please pay attention. Checking for updates every week is a good idea. Also - subscribe to all the streams on [Loop Zulipchat](https://loop.zulipchat.com) to make sure you don't miss critical information. -You may choose to download fresh each time you update. - -You may prefer to use commands to fetch and pull the latest code without making a new clone. - -* Some users like to use [GitKraken](https://support.gitkraken.com/) to assist them (link takes you to a tutorial video). -* Some are comfortable with the command line git commands described on [here](../version/loopworkspace.md#updating-loop-using-loopworkspace). - ## Loop-dev Version -The version of code that shows up under the Loop Settings screen does not change when the dev branch is modified. +The version of code that shows up under the Loop Settings screen does not change when the `dev branch` is modified. If you need help with your app, the mentors need more information. Please issue a Loop Report when asking for help. Refer to [Support](../loop-3/settings.md#support) for how to issue a Loop Report. If you want to keep track yourself, refer to [Identify Loop-dev Version](#identify-loop-dev-version) @@ -78,3 +25,10 @@ If you need help with your app, the mentors need more information. Please issue The version of code that shows up under the Loop Settings screen will remain fixed until Loop-dev is released. In order to identify which version of dev you have on your phone, you need the commit. The commit is identified by a 7-digit alphanumeric code. That code was also appended to the folder name of the downloaded code under Downloads/BuildLoop as shown in the graphic above. You can use finder to view the folder name after the script completes. It also appears in the Loop Report, refer to [Support](../loop-3/settings.md#support) for instructions on issuing a Loop Report. After you issue the Loop Report, look at the workspaceGitRevision number near the beginning of the report. + +## Build `Loop` `dev` + +1. For the Build with Browser method + * [Build dev with Browser](../gh-actions/build-dev-browser.md) +1. For the Build with *Mac* method: + * [Build dev with *Mac*](../build/build-dev-mac.md) diff --git a/docs/version/build-time-flag.md b/docs/version/build-time-flag.md new file mode 100644 index 00000000000..69c104404df --- /dev/null +++ b/docs/version/build-time-flag.md @@ -0,0 +1,104 @@ +## Overview + +Build-time features are not available with Loop 2.2.x. + +With Loop 3, some features are enabled or disabled by default but can be modified by adding a "flag" in the LoopConfigOverride.xcconfig file. + +If you use Build with Browser, these build-time features can be added to your copy of the LoopConfigOverride.xcconfig file. Use the pencil icon in that file on your copy of LoopWorkspace and then commit the change. + +If you use the Build with *Mac* Method, this is the same file used to automatically sign all your targets. You can edit the version in your LoopWorkspace folder (it shows up as the top item in the Xcode folder view) - or - if you use the build script, you can edit the copy found in ~/Downloads/BuildLoop after the first time you use the script. For that second case, the "flags" you add in ~/Downloads/BuildLoop/LoopConfigOverride.xcconfig are applied to all downloads created with the script. + +These flags are always upper case with underscore separating words for clarity, for example `MY_EXAMPLE_FLAG`. If you have more than one flag, they are separated by a space. Do not enter a line break between selections; in other words, do not hit return or enter. Xcode will automatically word-wrap the line for clarity. All values need to be on a single line. + +!!! question "New Instructions" + The instructions are more robust than earlier instructions that had you editing a line instead of adding new ones. + +Copy the text below, add it to the end of your LoopConfigOverride.xcconfig file and then insert the desired flags in place of `MY_EXAMPLE_FLAG`. If you want more than one flag, separate them by a space. + +``` { .txt .copy title="Lines to add to end of file" } + +// Add Build-Time features to compilation conditions +SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(SWIFT_ACTIVE_COMPILATION_CONDITIONS) MY_EXAMPLE_FLAG +``` + +_Code Before Modification_ + +``` +// Put your team id here for signing +//LOOP_DEVELOPMENT_TEAM = UY678SP37Q +``` + +The example below is for someone who is using a Free Developer ID - which does not support Siri. + +_Code After Modification_ + +``` +// Put your team id here for signing +//LOOP_DEVELOPMENT_TEAM = UY678SP37Q + +// Add Build-Time features to compilation conditions +SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(SWIFT_ACTIVE_COMPILATION_CONDITIONS) SIRI_DISABLED +``` + +List of some flags and what they do: + +|FLAG|PURPOSE| +|---------|---------| +|SIRI_DISABLED|Required to build Loop from Xcode with a free developer account| +|ADULT_CHILD_INSULIN_MODEL_SELECTION_ENABLED|The choice for Child Model is enabled in Therapy Settings. Please read [Enable Child Model](#enable-child-model).| +|REMOTE_OVERRIDES_DISABLED|Remote commands: override, carbs or boluses will not be accepted even if all the [Remote Command](../nightscout/remote-overview.md) requirements are configured

If you do configure this and later try to set up remote commands, they will not work and there is **no error** message. [Remote Errors: Loop REMOTE_OVERRIDES_DISABLED](../nightscout/remote-errors.md#loop-remote_overrides_disabled)| +|OBSERVE_HEALTH_KIT_CARB_SAMPLES_FROM_OTHER_APPS_ENABLED|Turns on ability for Loop to read third party carb entries. You must also make sure Health permissions allow Loop to read carbs from Health. Be vigilant if you select this; added carbs lead to added insulin dosing when closed loop is enabled| +|SHOW_EVENTUAL_BLOOD_GLUCOSE_ON_WATCH_DISABLED|The Apple Watch screens show current glucose, trend arrow and eventual glucose by default. This flag disables the display of eventual glucose on the watch if you find the display distracting.| +|PREDICTED_GLUCOSE_CHART_CLAMP_ENABLED|[Chart Clamp](#chart-clamp)| +|ALLOW_ALGORITHM_EXPERIMENTS|**dev branch only**

This is enabled by default to show Algorithm Experiments below the Therapy Settings row. This enables the user to separately enable or disable Glucose Based Partial Application and Integral Retrospective Correction| + +### Chart Clamp + +What the heck is a chart clamp? It means the range displayed will not be smaller than the clamp but it can be bigger. + +Loop automatically scales the glucose charts based on the history shown. Some people don't like to see the vertical axis changing, so they turn on the "clamp". + +When the `PREDICTED_GLUCOSE_CHART_CLAMP_ENABLED` build time flag is added: + +* the range shown is never smaller than `glucoseChartDefaultDisplayBoundClamped` +* 80 to 240 mg/dL (4.4 to 13.3 mmol/L) + +When you do not add that build time flag: + +* the range shown is never smaller than `glucoseChartDefaultDisplayBound` +* 100 to 175 mg/dL (5.6 to 9.7 mmol/L) + +If glucose within the display history is outside of the bound, the graph range expands to include that glucose level. This prevents glucose readings from being "hidden". + +You can customize chart display settings if you want. The original lines of code are shown below. You will need to read the rest of this page to figure out how to modify these to meet what you prefer. If you can't figure this out - reach out for help. + +* Module: Loop +* Loop 3 + * Folder: Loop/Models + * File: LoopConstants.swift + * Lines: 32 to 45 + +``` + // MARK - Display settings + + static let minimumChartWidthPerHour: CGFloat = 50 + + static let statusChartMinimumHistoryDisplay: TimeInterval = .hours(1) + + static let glucoseChartDefaultDisplayBound = + HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 100)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 175) + + static let glucoseChartDefaultDisplayRangeWide = + HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 60)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 200) + + static let glucoseChartDefaultDisplayBoundClamped = + HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 80)...HKQuantity(unit: .milligramsPerDeciliter, doubleValue: 240) +``` + +### Enable Child Model + +Loop 3, by default, does not include the concept of child versus adult for rapid-acting insulin, i.e., Humalog, Novalog and Apidra. + +* The child model can be enabled following the directions above, adding ADULT_CHILD_INSULIN_MODEL_SELECTION_ENABLED to the LoopConfigOverride.xcconfig file and rebuilding +* Insulin Model is then found in the Therapy Setting section of Loop 3 with Adult selected by default +* Insulin Type continues to be associated with the pump and can be modified in the Pump Settings screen diff --git a/docs/version/code-custom-edits.md b/docs/version/code-custom-edits.md new file mode 100644 index 00000000000..870c9d31358 --- /dev/null +++ b/docs/version/code-custom-edits.md @@ -0,0 +1,538 @@ +## Build then Customize + +For new Loopers, please build the code before you make any changes. Start with Open Loop and familiarize yourself with the interface. Later, you can make the customization(s) you desire and build again. The second build will be much easier than your first build. + +These customizations require you modify the *Loop* app code and then build the app after making these customizations. This page supports version 3 and greater for the *Loop* app. + +## Customization Options + +Read about the customizations on this page before applying them. + +!!! warning "You take responsibility" + You are responsible when you decide to use customizations. + + Be sure to report what changes you made if you need to ask for assistance with your app. + +Some customizations are the same for everyone and have been prepared for easy use. Refer to the build method that you use for information about applying these prepared changes - the same set is available for both build methods. + +* [Customize with Browser](../gh-actions/custom-browser.md) +* [Customize with *Mac*](../build/custom-mac.md) + +Other customizations require that you create your own personalized version. + +* On this page are instructions for what modifications are required to your code to achieve each desired customization +* On [Version: Build-Time Flag](../version/build-time-flag.md) are details about how to change the default settings for the build-time flags by editing the `LoopConfigOverride.xcconfig` file. + +## Instructions for Finding the Lines + +The instructions on this page identify the module, `Key_Phrase` or file and line numbers required to locate the code you need to modify. + +The how-to instructions for making these changes are different for each build method. They are found in the respective build-method tabs: + +* [Custom Edits with Browser](../gh-actions/edit-browser.md) +* [Custom Edits with *Mac*](../build/edit-mac.md) + +!!! info "Line numbers may change" + Every effort will be made to update the line numbers as the code is updated, but there may be times where the screenshots and line numbers differ from the current version of Loop code. + + * You may notice some customizations list line numbers for different branches + + * If you cannot identify a line that looks exactly like the example - do not guess - go to your favorite social media group and ask for help + +This page is broken into two halves: + +* [Custom Edits Required](#custom-edits-optional): + * The first half of this page is for customizations that require you to edit your own code. + +* [Custom Edits Optional](#custom-edits-optional): + * The second half of this page provides instructions for some of the prepared customizations included in the [*Loop and Learn*: Customization Select Script](https://www.loopandlearn.org/custom-code). Some people prefer to make all their own edits. + +For each customization, you will be given landmarks to find the correct location in the code. You can choose to search using the `Key_Phrase` or navigate to the file in the folder structure and look for the line number. + +### Key_Phrase + +``` { .txt .copy title="Example of a Key_Phrase" } +use the copy button at right, paste into search +The copy button for this exampe is just for practice +Do not paste the result anywhere +``` + +To search using the `Key_Phrase` (see graphic above for an example): + +* A copy button is available when you hover your mouse in the right-hand side +of the block below the title `Key_Phrase`; click on it to copy the phrase into your paste buffer +* You can paste this into the search function of the tool you are using if desired (warning, you may have to hit back-space to remove a return character from the pasted text)

+* Alternatively, navigate to the required file using Module, Folder, File and line number + +### Module, Folder, File + +Each customization provides the Module, Folder and File bullet below the key phrase. + + * Module: Loop + * Folder: Loop/subfolder1/subfolder2/etc. + * File: filename.swift, line number(s) + +The customizations below show the original line of code that you will be changing. + +There may be a figure illustrating the change. + +Below the figure, the original, and in some cases, the modified code will be displayed as text. + +* Sometimes that line is long and you may need to use the scroll bar to see the entire line in LoopDocs +* In most cases, an example customization is shown to assist you in deciding how to edit the line to meet your needs + +## Custom Edits Required + +### Default Carb Absorption Times + +![img/carb_screen.png](img/carb_screen.png){width="200"} +{align="center"} + +Loop’s default carb absorption times are based on the high, medium, and low glycemic index absorption curves presented in *Think Like A Pancreas* by Gary Scheiner. In prior versions of the *Loop* app, for example version 2.2.x, the lollipop (fast) icon was set for 2 hours, taco (medium) icon for 3 hours, and pizza (slow) icon for 4 hours. This is modified for `Loop 3` to 30 minutes, 3 hours and 5 hours respectively. Some people prefer different values. + +??? question "Do you want to know more? (Click to open/close)" + The developers did this because they expect fast to only be used for rapid-acting low treatments. The medium and fast values are for moderate and higher-fat or large meals. + +``` { .txt .copy title="Key_Phrase" } +defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes +``` + +* Module: Loop +* Folder: Loop/LoopCore +* File: LoopCoreConstants.swift +* Line: 19 + +For example, if you wanted to change `fast` to be slightly longer, the edit would be as follows: + +_Code Before Modification + + public static let defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes = (fast: .minutes(30), medium: .hours(3), slow: .hours(5)) + +_Code After Modification + + public static let defaultCarbAbsorptionTimes: CarbStore.DefaultAbsorptionTimes = (fast: .hours(1.5), medium: .hours(3), slow: .hours(5)) + +Note that if you change `fast` from 30 minutes to 1.5 hours, you must also change the indication before the parentheses. + +### Adjust Maximum IOB for Automatic Dosing + +With version 3.2.0, a new safety feature was added. This limits automatic dosing so IOB is no more than two times the $\mathit{maximumBolus}$ set in your Delivery Limits. (The term automatic dosing refers to insulin the app automatically delivers above your scheduled basal rate.) Manual Bolus, where you initiate the bolus yourself, is not subject to this limit. Please read [How do Delivery Limits Affect Automatic Dosing?](../faqs/algorithm-faqs.md#how-do-delivery-limits-affect-automatic-dosing) for detailed information on how this safety feature works. + +The default value ($\mathit{2*maximumBolus}$) used for this feature is good for the majority of people who use the app. However, there are some individuals who might need to limit the size of any single bolus independent from the maximum IOB they want to set for their app. This is particularly true for those who find large boluses give rise to tunneling and the insulin leaks out along the cannula. + +``` { .txt .copy title="Key_Phrase" } +automaticDosingIOBLimit = maxBolus +``` + +* Module: Loop +* Folder: Loop/Managers +* File: LoopDataManager.swift, line: 1690 (main), 1796 (dev) + +The following example is for someone who limits a single bolus to 5 U but frequently needs to achieve an IOB of 15 U for meals. They want that level of IOB to be reached with automatic bolusing. In that case, they may want to modify the factor used to calculate $\mathit{automaticDosingIOBLimit}$. + +Original Code: +``` +let automaticDosingIOBLimit = maxBolus! * 2.0 +``` + +Modified Code Example: +``` +let automaticDosingIOBLimit = maxBolus! * 3.0 +``` + +Because the automatic bolus amount is also limited by the partial application factor, it still takes a few cycles to reach the higher IOB of $\mathit{3*maximumBolus}$; but they can get there without manual intervention. + +### Adjust Percent Bolus for Automatic Bolus + +If you are mostly happy with the Dosing Strategy of Automatic Bolus but wish it delivered more or less insulin during every Loop interval, then this customization is for you. + +This customization changes the percent of the recommended bolus used for automatic delivery. The method for calculating that recommendation is not changed by this modification. The default value is 40% (0.4). It is recommended you take small changes of 0.1 at a time. Once you modify it once and try it out for a while, it’s easy to go back and change it again. + +**Change just the number and double check that the value is less than 1.** + +``` { .txt .copy title="Key_Phrase" } +let bolusPartialApplicationFactor +``` + +* Module: Loop +* Folder: Loop/Loop/Models +* File: LoopConstants.swift +* Line: 53 + +_Code Before Modification_ + + static let bolusPartialApplicationFactor = 0.4 + +_Code After Modification to 50% of recommended insulin_ + + static let bolusPartialApplicationFactor = 0.5 + +!!! warning "Do not exceed 1.0" + This number should never be bigger than 1 (you’d be getting more than Loop recommends). If you think you need more than 1, consider your settings and meal entries. + + +### Pods: Add Extra Insulin on Insertion + +The default value is 0.0 U of extra insulin. If you use this customization, start with a small number and work your way up. If you are coming from manual podding and routinely gave yourself an extra bolus with your PDM at pod change time, you may not need nearly as much with Loop - be conservative. + +Note that Loop does not include the amount of insulin in the prime or insertion steps in your IOB. The pod reports every pulse that it delivers to Loop. If you look in the Pod Settings insulin delivered row, that is the total delivered by the pod minus the (prime plus insertion) amounts. The only way to know that you successfully made this change is to count the clicks. Normal insertion is 0.5 U (0.5 U / 0.05 U per click = 10 clicks). So if you add 0.35 U to the "extra" value, you should get 0.35 / 0.05 = 7 extra clicks. In other words, 17 total clicks after you press insert. + +This code change is found in one location for Eros Pods (called Omnipod throughout the app) and DASH Pods (called Omnipod Dash throughout the app). I tend to change both files, but if you're only using one kind of pod, that is really not necessary. + +``` { .txt .copy title="Key_Phrase" } +let cannulaInsertionUnitsExtra +``` + +* Module: OmniBLE (DASH) or OmniKit (Eros) +* DASH or Eros Pod (Loop 3 only) + * Folder: OmniBLE/OmniBLE/OmnipodCommon (DASH) + * Folder: OmniKit/OmniKit/OmnipodCommon (Eros) + * File: Pod.swift, Line 82 (DASH); Line 87 (Eros); +* Loop 2.2.x: Eros Pod (still configured in rileylink_ios - use Key_Phrase) + +_Code Before Modification_ + + public static let cannulaInsertionUnitsExtra = 0.0 // edit to add a fixed additional amount of insulin during cannula insertion + +_Code After Modification to add 0.35 U_ + + public static let cannulaInsertionUnitsExtra = 0.35 // edit to add a fixed additional amount of insulin during cannula insertion + +### Modify the Guardrails + +The [Therapy Setting Guardrails](../loop-3/therapy-settings.md#guardrails-for-settings) are for Loop 3 only. + +### Glucose Guardrails + +If you build Loop 3 over a version of Loop 2.2.x or FreeAPS where the Correction Range is lower than the default value of 87 mg/dL (4.8 mmol/L), your app requires you to satisfy the new guardrail before you can save that Therapy Setting when you onboard. + +``` { .txt .copy title="Key_Phrase" } +Guardrail(absoluteBounds: +``` + +* Module: LoopKit +* Folder: LoopKit/Extensions +* File: Guardrail+Settings.swift +* Line: 12 for suspendThreshold +* Line: 26 for correctionRange + +_Code Before Modification_ + + static let suspendThreshold = Guardrail(absoluteBounds: 67...110, recommendedBounds: 74...80, unit: .milligramsPerDeciliter, startingSuggestion: 80) + +and + + static let correctionRange = Guardrail(absoluteBounds: 87...180, recommendedBounds: 100...115, unit: .milligramsPerDeciliter, startingSuggestion: 100) + +Modify the 67 for suspendThreshold or 87 for correctionRange to the desired value. Loop automatically converts from mg/dL. So you must enter values reasonable for mg/dL (18 times higher than for mmol/L). + +### Modify Guardrails for Insulin Sensitivity Factor (ISF) + +Similar to the instructions for glucose guardrails above, but use this `Key_Phrase` and modify the absoluteBounds row, next line. + +``` { .txt .copy title="Key_Phrase" } +static let insulinSensitivity = Guardrail( +``` + +* Module: LoopKit +* Folder: LoopKit/Extensions +* File: Guardrail+Settings.swift, line: 81 + +### Modify Guardrails for Carb Ratio (CR) + +Similar to the instructions for glucose guardrails above, but use this `Key_Phrase` and modify the absoluteBounds row, next line. + +``` { .txt .copy title="Key_Phrase" } +static let carbRatio = Guardrail( +``` + +* Module: LoopKit +* Folder: LoopKit/Extensions +* File: Guardrail+Settings.swift, line: 88 + + +### Adjust Future Carbs Time Interval + +Loop 3 limits the future time change allowed to 1 hour. + +``` { .txt .copy title="Key_Phrase" } +cell.datePicker.maximumDate = date.addingTimeInterval +``` + +* Module: Loop +* Folder: Loop/Loop/View Controllers +* File:CarbEntryViewController.swift, Line 438 + +Default shown below (for maximum and minimum): + +_Code Before Modification_ + + cell.datePicker.maximumDate = date.addingTimeInterval(.hours(1)) + cell.datePicker.minimumDate = date.addingTimeInterval(.hours(-12)) + +Change the maximumDate to the number of hours in the future you desire. Remember that Loop may increase insulin dosing for future carbs - make sure that they actually arrive. + +The minimumDate is how far back in the past you can modify time. The default is 12 hours in the past. + +### Adjust the Watch Crown Sensitivity + +The rate of change of the carb and bolus entry pickers when using the digital crown can be altered as can the rotation required to confirm a bolus on the watch. If you are running an older series watch - you may want to make these customizations. When I switched from Series 3 to Series 7 watch - it was amazing. I got a graph on the main watch screen I didn't even know existed and the bolus acceptance was a breeze! + +* The Loop 3 customization is provided from code inspection and one test - use with care. + +### Loop 3 Digital Crown Adjustments + +These are new instructions and the user should take care - and please [report back](../intro/loopdocs-how-to.md#how-to-find-help) if you have problems. + +First - try it with no customization. Then make small changes. + +This key phrase will indicate three different files in the same folder as shown in the graphic below - you can adjust each in turn as you desire. When you click on the line, the quantity you change is a few lines below where you find the `Key_Phrase`, except for the CarbAndDateInput file. + +``` { .txt .copy title="Key_Phrase" } +.digitalCrownRotation +``` + +* Module: Loop +* Folder: Loop/WatchApp Extension/Views/Carb Entry & Bolus + +![use a single Key_Phrase to identify all lines needed to customize sensitivity with loop 3](img/digital-crown-rotation.svg){width="800"} +{align="center"} + +#### Modify Bolus Confirmation Motion + +* File: BolusConfirmationView.swift, line 59 +* Initial Value for `scalingRotationBy` is 4 +* Decrease to require less motion to confirm bolus (use whole numbers only), start with 3 + +#### Modify Bolus Picker Sensitivity + +* File: BolusInput.swift, line 53 +* Initial Value for `rotationsPerIncrement` is 1/24 +* A change to 1/12 increases the change in picker value for a given motion + +#### Modify Carb and Time Picker Sensitivity + +* File: CarbAndDateInput.swift, line 68 +* Initial Value for `rotationsPerIncrement` is 1/24 +* A change to 1/12 increases the change in picker value for a given motion + +### Expiration Notification Customization + +An expiration notification feature has been added to Loop. You get a notification when you open the Loop app to alert you that the expiration is approaching. + +* Read [Loop App Expiration Notification](../operation/features/notifications.md#loop-app-expiration-notification) to see the expiration reminder +* Read [Loop App Expiration Date](../operation/features/notifications.md#loop-app-expiration-date) if you have an older version of Loop + +If you prefer a different notification time and frequency, there are two lines you can modify: + +* Module: Loop +* Folder: Loop/Managers +* File: ProfileExpirationAlerter.swift + * Line 16: modify how long before expiration you get the FIRST notification + * Line 28: modify how frequently you will be notified + +``` { .txt .copy title="Key_Phrase" } +expirationAlertWindow: TimeInterval +``` + +``` { .txt .copy title="Key_Phrase" } + minimumTimeBetweenAlerts: TimeInterval +``` + +![Profile expiration notification details](img/expiration-custom.png){width="600"} +{align="center"} + +Default code for line 16: +``` + static let expirationAlertWindow: TimeInterval = .days(20) +``` + +Example modifications to First Notification: + +* 30 days: change `.days(20)` to `.days(30)` +* 12 hours: change `.days(20)` to `.hours(12)` + +Default code for line 28: + +``` + let minimumTimeBetweenAlerts: TimeInterval = timeUntilExpiration > .hours(24) ? .days(2) : .hours(1) +``` + + +Modify Frequency of Repeated Notifications (Three Values): + +* This phrase: ```> .hours(24) ? .days(2) : .hours(1)``` +* Rewritten as: ```> Time_A ? Frequency_A : Frequency_B```, means: + * Use Frequency_A if there is more time between now and the expiration date than Time_A + * Use Frequency_B if there is less time between now and the expiration date than Time_A + +You can enter Time or Frequency as ```.days(value)```, ```.hours(value)``` or ```.minutes(value)```. + +Free App Users: + +An example change that a Free Loop App user (who has to build once a week) might choose is: + +``` + > .hours(4) ? .days(10) : .hours(2) +``` +Combined with an ```.hours(12)``` on line 16, they would get notified at 12 hours, 4 hours and 2 hours before expiration on the day of expiration and only when the app is opened. Since you'll be building once a week, you can play around with these values until you are happy. + +### Enable Child Model + +Please see the [Build-Time Flag](build-time-flag.md) page for this customization. + +### Insulin Model Customization + +Each exponential model has 3 parameters that can be adjusted: + +* actionDuration: Duration of insulin activity (minutes) +* peakActivity: Peak of insulin activity (minutes) +* delay: Delay before insulin begins to acts after delivery starts (minutes) + +Please read the nitty-gritty discussion that went into the development of the "exponential insulin models" in this [Comment](https://github.com/LoopKit/Loop/issues/388#issuecomment-317938473). + +If you wish to customize these values, please make sure you know what you are doing. This is not a modification recommended for Loop novices. + +``` { .txt .copy title="Key_Phrase" } +MARK: - Model generation +``` + +* Module: LoopKit +* Folder: LoopKit/LoopKit/Insulin/ << NOTE new location +* File: ExponentialInsulinModelPreset.swift +* Lines: + * actionDuration (19 to 32) + * peakActivity (34 to 47) + * delay (49 to 62) + +![img/exponential.png](img/exponential.png){width="750"} +{align="center"} + +This Loop 3 table of default values is provided for convenience. The times are all in minutes. + +|Model|DIA|Peak|Delay| +|---------|---------|---------|---------| +|rapidActingAdult|360|75|10| +|rapidActingChild|360|65|10| +|fiasp|360|55|10| +|lyumjev|360|55|10| +|afrezza|300|29|10| + +### Loop Logo + +!!! warning "*Mac* Instructions" + This can be done with Build with Browser but the instructions might need to be adjusted for that case. + +If you want an app logo other than the default green circle for your Loop app, you can easily customize this. To make it easy to generate the correct sizes of icons, you can use a site like [appicon.build](http://www.appicon.build/) or [appicon.co](https://appicon.co/) and just drag and drop your source image. The source image needs to be 1024 pixels x 1024 pixels. The site will email you a zip file or automatically download a set of files. Highlight and copy the contents of the Appicon.appiconset that you are sent, including the Contents.json file + +1. Navigate to the LoopWorkspace folder +1. Open the OverrideAssetsLoop.xcassets folder +1. Open the AppIcon.appiconset folder +1. Delete the contents of the Appicon.appiconset and copy/paste your new images and Contents.json file. +1. Rebuild your app + +You may see a yellow warning that there are “unassigned children” depending on the images the app icon generator tool produced. The unassigned children alert will not prevent your app from building, it’s simply because there are more sizes of images than Loop app uses. You can just leave the unassigned children alone (wow...how often do you get to say that phrase?). + +And now you'll be the proud new owner of a custom Loop icon. + +## Custom Edits Optional + +### Disable Authentication for Bolusing + +Depending on your iPhone Settings and model, you may have Face ID or Touch ID enabled. Those security features will also be used to authenticate bolus delivery in Loop. You can choose to disable authentication (i.e., not require Face ID, Touch ID, or passcode for bolusing) through the following code customization. + +!!! warning "Safety Measure" + If you disable this, you are removing an important safety feature. + + In addition to authenticating every manual bolus, this helps to protect against sleep bolusing and pocket bolusing. + + For Loop 3, this controls the authorization requirement to modify Therapy Settings as well as to confirm bolus delivery. + +``` { .txt .copy title="Key_Phrase" } +canEvaluatePolicy(.deviceOwnerAuthentication +``` + +* Module: LoopKit +* Folder: LoopKit/LoopKitUI/Extensions/ +* File: Environment+Authenticate.swift, Line 20 + +_Code Before Modification_ + + if context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) { + +_Code After Modification_ + + if false && context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) { + +### Modify Override Insulin Needs Picker + +Some people want finer settings on the override insulin needs picker (5% instead of 10%) and may want to limit the overall range for overrides – especially for children. + +!!! tip "1% Settings Available without Customization" + With the advent of Loop 3, the Override Insulin Needs values are not limited by the default picker values of 10%. + + * [Select 1% Insulin Needs](../operation/features/overrides.md#select-1-insulin-needs) + +Any override more than a factor of 2 from 100% can cause Loop predictions to be wrong – especially if a carb count is entered. (An [override](../operation/features/overrides.md) is NOT the same as a manual temp basal - it changes insulin sensitivity factor and carb ratio in addition to the basal rate needed for zero change in IOB for the duration of the override.) + +!!! danger "A Sensitivity of 0% is NOT Valid" + Do not set the lower level of the sensitivity range to be 0%. + + If you configure to allow that and someone chooses it, they will be telling Loop to divide by zero in some of the calculations. They will see NaN (not a number) in Loop predictions until that override is removed and will continue to see that for the full duration of insulin action (6 hours). + +This example customization changes the lower bound for sensitivity to 50% (factor of 2 smaller than 100%) and provides 5% steps. This is the same as the prepared customization offered by the *Loop and Learn* team. + +``` { .txt .copy title="Key_Phrase" } +let allScaleFactorPercentages +``` + +* Module: LoopKit +* Folder: LoopKit/LoopKitUI/Views +* File: InsulinSensitivityScalingTableViewCell.swift, Line 19 + +_Code Before Modification_ + + private let allScaleFactorPercentages = Array(stride(from: 10, through: 200, by: 10)) + +_Code After Modification to 50% to 200% by steps of 5%_ + + private let allScaleFactorPercentages = Array(stride(from: 50, through: 200, by: 5)) + +### Modify Maximum and Warning Carb Entry + +Version 3.x of the *Loop* app has both a `maxCarbEntryQuantity` and a `warningCarbEntryQuantity`, found adjacent to each other in the code. The warning value is the level at which you are asked if you really meant to enter that amount: + +``` { .txt .copy title="Key_Phrase" } +let maxCarbEntryQuantity = +``` + +* Module: Loop +* Folder: Loop/Loop/Models +* File: LoopConstants.swift, line 18 + +_Code Before Modification_ + + static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 250) // cannot exceed this value + + static let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 99) // user is warned above this value + +#### `"low_carb_limit"` + +This first example might be used by a parent for a child with very small carb entries. It is provided as one of the prepared customizations supplied by the [*Loop and Learn* Customization as `"low_carb_limit`"](https://www.loopandlearn.org/custom-code/#custom-list). + +_Code After Modification to enable the warning at lower levels and limit maximum_ + + static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 99) // cannot exceed this value + + static let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 49) // user is warned above this value + +#### `"high_carb_limit"` + +This second example might be used by a person who routinely enters large meals and does not want to be warned with every meal. It is provided as one of the prepared customizations supplied by the [*Loop and Learn* Customization as `"high_carb_limit`"](https://www.loopandlearn.org/custom-code/#custom-list). + +_Code After Modification to warn if entry is between 201 and 300g_ + + static let maxCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 300) // cannot exceed this value + + static let warningCarbEntryQuantity = HKQuantity(unit: .gram(), doubleValue: 200) // user is warned above this value + diff --git a/docs/version/development.md b/docs/version/development.md index a5c4b92be19..65774689dce 100644 --- a/docs/version/development.md +++ b/docs/version/development.md @@ -1,4 +1,4 @@ -## Loop  Development +## Overview The early history of the *Loop* app was touched on in the introductory [*LoopDocs* Overview: Development History](../intro/overview-intro.md#development-history) section. @@ -32,7 +32,7 @@ This section is an early look at what has been added to `dev` since* GitHub Browser Build  for `dev` branch -* [Browser Build: One-Time Changes](../gh-actions/gh-update.md#one-time-changes): New steps and dates at which the new steps were added +* [Browser Build for dev](../gh-actions/build-dev-browser.md): How to use  GitHub Browser Build  for `dev` branch +* [Browser Build: One-Time Changes](../gh-actions/build-dev-browser.md#one-time-changes): New steps and dates at which the new steps were added ### Miscellaneous Code Fixes diff --git a/docs/build/img/carb_screen.png b/docs/version/img/carb_screen.png similarity index 100% rename from docs/build/img/carb_screen.png rename to docs/version/img/carb_screen.png diff --git a/docs/build/img/digital-crown-rotation.svg b/docs/version/img/digital-crown-rotation.svg similarity index 100% rename from docs/build/img/digital-crown-rotation.svg rename to docs/version/img/digital-crown-rotation.svg diff --git a/docs/build/img/expiration-custom.png b/docs/version/img/expiration-custom.png similarity index 100% rename from docs/build/img/expiration-custom.png rename to docs/version/img/expiration-custom.png diff --git a/docs/build/img/exponential.png b/docs/version/img/exponential.png similarity index 100% rename from docs/build/img/exponential.png rename to docs/version/img/exponential.png diff --git a/docs/version/loopworkspace.md b/docs/version/loopworkspace.md index 92a65db301a..6f753e1208d 100644 --- a/docs/version/loopworkspace.md +++ b/docs/version/loopworkspace.md @@ -147,7 +147,7 @@ For this graphic, the cloned `LoopWorkspace` is in the home directory. When it's time to update the copy of `LoopWorkspace` on your computer - you have choices. You can use the method below or redo the whole cloning process. -Be sure your terminal is in the correct location using [Open a Terminal in `LoopWorkspace` Folder](../build/code-customization.md#open-a-terminal-in-loopworkspace-folder) +Be sure your terminal is in the correct location using [Open a Terminal in `LoopWorkspace` Folder](../version/code-custom-edits.md#open-a-terminal-in-loopworkspace-folder) 1. Make sure you are in the correct branch using this git command: ``` { .bash .copy } @@ -172,7 +172,7 @@ If you are testing the LoopKit dev branch, you need to be on [zulipchat](https:/ Sometimes, you know a feature you want was added at a specific commit number; however, you know there are other changes later than that commit which you do not want to test. There is a solution. -Be sure your terminal is in the correct location using [Open a Terminal in LoopWorkspace Folder](../build/code-customization.md#open-a-terminal-in-loopworkspace-folder). First you have to bring down all the latest dev commits. Then you will back up to the one you want. +Be sure your terminal is in the correct location using [Open a Terminal in LoopWorkspace Folder](../version/code-custom-edits.md#open-a-terminal-in-loopworkspace-folder). First you have to bring down all the latest dev commits. Then you will back up to the one you want. 1. Make sure you are in the correct branch using this git command: ``` { .bash .copy } diff --git a/docs/version/overview-version.md b/docs/version/overview-version.md index 0aa0fb111c4..07c09eea6b3 100644 --- a/docs/version/overview-version.md +++ b/docs/version/overview-version.md @@ -1,24 +1,23 @@ ## Version Overview -The Version tab of LoopDocs contains information about Loop versions, code customization and development. +The Version tab of *LoopDocs* contains information about releases (versions), code customization and development. Map to this section: -* [Loop Releases](../version/releases.md) - - Description of the current released version of Loop including when it was released +* [Releases](releases.md) + - Description of the current released version of the *Loop* app including when it was released - Reverse chronology of earlier releases -* [Code Customization](../build/code-customization.md) - - Instructions for customizing your DIY code - - Think of this as your personalized version -* [Customize with Browser](../gh-actions/gh-customize.md) - - Instructions for customizing using a browser +* Information needed to Personalize (Customize) your app (regardless of build method) + * [Custom Edits](../version/code-custom-edits.md) + * [Build-Time Flag](build-time-flag.md) * [Simulator Build](simulator.md) - - Instructions for building to a simulator + - Considerations when using a simulator * [Loop Development](../version/development.md) - Description of the development process for Loop - Information you need if you want to participate * [Build Dev](../version/build-dev.md) - - Discussion of methods to build the dev branch + - Considerations when using the dev branch + - Links to the two build methods * [LoopWorkspace](../version/loopworkspace.md) - If you are interested in development, this page goes into more detail - The primary focus is on techniques for using git diff --git a/docs/version/releases.md b/docs/version/releases.md index 1c62a22b1e1..8518ffc3173 100644 --- a/docs/version/releases.md +++ b/docs/version/releases.md @@ -7,7 +7,7 @@ The new features added with each Loop release (starting with Loop version 2.0) a Be aware that Loop 3 is forward compatible: * You can build Loop 3 over older versions of Loop and maintain therapy settings as well as your configuration for CGM and pump (including a pod) -* You can build Loop 3 using a browser on any computer (no Mac required) with GitHub [Browser Build](../gh-actions/gh-overview.md) +* You can build Loop 3 using a browser on any computer (no Mac required) with [Build with Browser](../gh-actions/gh-overview.md) * Your phone must be running at least iOS 15.1 (although some people report they needed newer iOS than that when building with GitHub Browser Build) Loop 3 is **NOT backwards** compatible. Once you build Loop 3 or later on your phone, you cannot return to Loop 2.2.x or FreeAPS without some additional work. @@ -60,7 +60,7 @@ For example: *Loop* v3.2.3 was released on September 19, 2023. -This patch release was required for those who build using the Mac-Xcode method. +This patch release was required for those who build using the *Mac* method. * There are no changes to app functionality * Version 3.2.2 and earlier cannot be built using Xcode 15, see [Cycle Inside Loop](../build/build-errors.md#cycle-inside-loop) @@ -125,7 +125,7 @@ Loop v3.0.0 was released on January 14, 2023. * Do not try to build from the zip link * For Browser Build, refer to: [GitHub Overview](../gh-actions/gh-overview.md) - * For Mac-Xcode Build refer to: + * For Build with *Mac* refer to: * [Updating](../build/updating.md) * [Build the *Loop* App](../build/build-app.md) diff --git a/docs/version/simulator.md b/docs/version/simulator.md index bb5efd496c4..e5137eea2c5 100644 --- a/docs/version/simulator.md +++ b/docs/version/simulator.md @@ -12,7 +12,7 @@ Please, review all the Intro and Build pages, even if you will not complete them Follow the normal instructions to build with browser, install the app on a compatible phone and explore the app using the Pump Simulator, CGM Simulator or both. -### Simulator using Mac-Xcode Build: +### Simulator using Build with *Mac*: * Must have a Mac computer (or virtual machine, Intel chips only) * Can build the simulator with a free Apple Developer ID @@ -85,7 +85,7 @@ These CGM and pump options work to provide glucose readings or accept pump comma The Loop app, when open, will be quite aggressive at warning you that you have disabled Notifications, so you can reverse those directions to enable notifications when actually using the app. -### Mac-Xcode Build to a Real Phone using Free Account +### Build with *Mac* to a Real Phone using Free Account * Need access to a mac or virtual computer, see [Compatible Computer](../build/computer.md) diff --git a/mkdocs.yml b/mkdocs.yml index 38c8a9a2042..aae0f2dfc0b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -81,7 +81,7 @@ plugins: - redirects: redirect_maps: 'build/build_errors.md': 'build/build-errors.md' - 'build/code_customization.md': 'build/code-customization.md' + 'build/code_customization.md': 'version/code-custom-edits.md' 'build/step1.md': 'build/computer.md' 'build/step10.md': 'build/test-settings.md' 'build/step11.md': 'build/loop-data.md' @@ -94,6 +94,7 @@ plugins: 'build/step6.md': 'build/apple-developer.md' 'build/step8.md': 'build/xcode-version.md' 'build/step9.md': 'build/xcode-settings.md' + 'gh-actions/gh-customize.md': 'gh-actions/edit-browser.md' 'loop-3/displays_v3.md': 'loop-3/displays-v3.md' 'nightscout/new_user.md': 'nightscout/new-user.md' 'nightscout/ns_crossref.md': 'nightscout/ns-crossref.md' @@ -135,18 +136,25 @@ nav: - Build with Browser: - 'Browser Overview': gh-actions/gh-overview.md - 'Configure to use Browser': gh-actions/gh-first-time.md + - 'Errors with Browser': gh-actions/gh-errors.md - 'Install on Phone': gh-actions/gh-deploy.md - 'Update/Rebuild with Browser': gh-actions/gh-update.md - - 'Errors with Browser': gh-actions/gh-errors.md + - 'Automatic Update & Build': gh-actions/automatic.md + - 'Customize using Browser': 'gh-actions/custom-browser.md' + - 'Custom Edits with Browser': 'gh-actions/edit-browser.md' + - 'Build Loop dev with Browser': gh-actions/build-dev-browser.md - 'Build Other Apps with Browser': gh-actions/gh-other-apps.md -- Build with Mac-Xcode: - - 'Mac-Xcode Overview': 'build/overview.md' +- Build with Mac: + - 'Mac Overview': 'build/overview.md' - 'Compatible Computer': 'build/computer.md' - 'Xcode Version': 'build/xcode-version.md' - 'Xcode Settings': 'build/xcode-settings.md' - 'Build Loop': 'build/build-app.md' - 'Oh dear! Build errors?': 'build/build-errors.md' - - 'Update/Rebuild with Mac-Xcode': 'build/updating.md' + - 'Update/Rebuild with Mac': 'build/updating.md' + - 'Customize using Mac': 'build/custom-mac.md' + - 'Custom Edits with Mac': 'build/edit-mac.md' + - 'Build Loop dev with Mac': 'build/build-dev-mac.md' - 'Build Free Loop': 'build/build-free-loop.md' - 'TestFlight from Xcode': 'build/testflight-xcode.md' - Set Up: @@ -200,14 +208,14 @@ nav: - 'MDT Pump Battery': 'operation/features/battery.md' - 'Version': - 'Version Overview': 'version/overview-version.md' - - 'Loop Releases': 'version/releases.md' - - 'Code Customization': 'build/code-customization.md' - - 'Customize using Browser': 'gh-actions/gh-customize.md' + - 'Releases': 'version/releases.md' + - 'Custom Edits': 'version/code-custom-edits.md' + - 'Build-Time Flag': 'version/build-time-flag.md' - 'Simulator Build': 'version/simulator.md' - 'Loop Development': 'version/development.md' - - 'Build Loop Dev': 'version/build-dev.md' + - 'Build Dev': 'version/build-dev.md' - 'LoopWorkspace': 'version/loopworkspace.md' -- 'Nightscout': +- Nightscout: - 'Nightscout Overview': 'nightscout/overview.md' - 'New Nightscout': 'nightscout/new-user.md' - 'Nightscout with Loop': 'nightscout/update-user.md'