diff --git a/docs/browser/edit-browser.md b/docs/browser/edit-browser.md index 8d39cd326df..8f70a50d946 100644 --- a/docs/browser/edit-browser.md +++ b/docs/browser/edit-browser.md @@ -35,29 +35,30 @@ !!! abstract "Summary" * Prepare Customization (One Time): - * Once you have prepared a given customization, you can use it again with each update + * Once you have prepared a given customization, you can use it again with every build and even across most updates * If there is an update (new release) and the customization is no longer valid - you will get a clear error message * 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 [Version: Custom Edits](../version/code-custom-edits.md){: target="_blank" } 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){: target="_blank" } - * If there are customization not provided by the Customization List, then you need to make presonalized edits + * If there are customization not provided by the Customization List, then you need to make personalized edits * This current page explains how to make the edits using a browser * The [Version: Custom Edits](../version/code-custom-edits.md){: target="_blank" } gives instructions on identifying the Module, finding the file and editing the line(s) * *GitHub* (each Module): 1. `Fork` the Module (if needed) - this is your fork where you will make changes 1. `Sync` the Module (if needed) 1. Make the desired modification(s) using the pencil tool - 1. Save your changes + 1. Save your changes to a patch branch 1. Prepare lines needed for each customization and save - * GitHub (LoopWorkspace) - using your fork where you will make changes - 1. You will use the pencil tool to edit build_loop.yml - 1. Add customization lines to the file - 1. Save your changes - 1. Action 4: Build Loop + * New with 3.4.x release, there are 2 ways to add customizations (use only one) + * See [Update LoopWorkspace](#updateloopworkspace){: target="_blank" } + * See [How to use the `patches` Folder](#how-to-use-the-patches-folder){: target="_blank" } + * Regardless of the method, incorporate the customization with `Action 4: Build Loop` + * (Optional): [Add Test Details to *TestFlight*](bb-update.md#add-test-details-to-testflight){: target="_blank" } * Phone: Install with *TestFlight* + !!! question "FAQs" - **Do I need a Mac computer?** No. This can be done on any browser. - **Should I build without customizations first?** Yes. Make sure the build process works without customizations. You don't need to install the build on your phone, just make sure it builds without errors before you start modifying. @@ -78,23 +79,23 @@ Decide which [Version: Custom Edits](../version/code-custom-edits.md){: target=" * Do not get confused later: LoopKit is both a username and a Module name * Refer to the [Module Table](#module-table) when directed -Look also at the Stable line for the desired customization: +With the release of 3.4.x, the customizations for `main` and `dev` are the same. There are 2 customizations that require an update when moving from 3.2.3 to 3.4.x. -* Stable: Yes or Changed on date -* The method for applying that customization differs slightly in the instructions below based on that notation -* The customizations that are not stable, are summarized in [Not Stable List](../version/code-custom-edits.md#not-stable-list){: target="_blank" } +* For more information, refer to [Not Stable List](../version/code-custom-edits.md#not-stable-list){: target="_blank" } + * Glucose Guardrails + * Adjust Future Carbs Time Interval ## Outline of What Happens in the Module !!! warning "Review Only" Review this section so you know what to expect. The actual steps will come later, starting with [Create your Fork for Selected Module](#create-your-fork-for-selected-module) or [Personalized Customization for this Module](#personalized-customization-for-this-module). + Feel free to skip ahead if you think you don't need the summary. + In the next sections, the exact process for making changes will be documented. But the steps may feel confusing. There are no links here because you are supposed to review the steps before taking action in the next section. 1. First time for this module: * Make a fork - * If the customization you want is not "Stable" and you are building `main` - * Create a new branch for your fork using the SHA-1 table 1. Change the line(s) of code desired for your customization(s) in your `fork` 1. Save the change(s) using descriptive comments 1. Repeat until done with this Module @@ -175,47 +176,88 @@ When you "fork a repository", the default  ## Create `branch` if needed -* If the customization you wish to prepare indicates Stable: Yes, you can skip ahead to [Personalized Customization for this Module](#personalized-customization-for-this-module) -* If you are preparing a customization for the `dev` branch, regardless of the Stable notation, there is no need to create a special `branch`, simply update the default branch to the latest (sync it) and use the current version of the customization when you skip ahead to [Personalized Customization for this Module](#personalized-customization-for-this-module) -* Otherwise, when you a preparing a customization where the file changed sufficiently between `main` and `dev` and you want to build the `main` branch, you need to create a branch for this Module that is consistent with the version you wish to customize. +> With the release of version 3.4.x, this entire section can be skipped. It was needed when LoopWorkspace `dev` used submodules that were quite different from those used by `main`. -Open your browser to your https://github.com/username/Module URL. If you already created the `branch` you need, you do not need to create a new one. +??? abstract "Skip for Now (Click to open/close)" -If you are customizing a released version, use the [Table of SHA-1](#table-of-sha-1) under your version number below. Copy the SHA-1 for your Module so you can paste it into the URL in Step 2 below. Notice the suggested branch name for that table. You will use this in Step 3.3 below. + * If the customization you wish to prepare indicates Stable: Yes, you can skip ahead to [Personalized Customization for this Module](#personalized-customization-for-this-module) + * If you are preparing a customization for the `dev` branch, regardless of the Stable notation, there is no need to create a special `branch`, simply update the default branch to the latest (sync it) and use the current version of the customization when you skip ahead to [Personalized Customization for this Module](#personalized-customization-for-this-module) + * Otherwise, when you a preparing a customization where the file changed sufficiently between `main` and `dev` and you want to build the `main` branch, you need to create a branch for this Module that is consistent with the version you wish to customize. -You should create a `branch` following the numbered steps and watching the GIF. Each Frame in the GIF corresponds to a numbered step below. + ??? abstract "Use only if directed (Click to Open/Close)" + Open your browser to your https://github.com/username/Module URL. If you already created the `branch` you need, you do not need to create a new one. -1. Click on URL line as indicated by the arrow -1. Add the text `/tree/SHA-1` where you change SHA-1 to be the value in the table below and hit return -1. Create a new branch in three steps - * 3.1: Click on the dropdown under the `branch` icon - * 3.2: Type the suggested new `branch` name in the blank space - * 3.3: Click on the create `branch` button -1. You should see a screen similar to the example below - * Do not click on the Create Pull Request button that is marked with a big X + If you are customizing a released version, use the [Table of SHA-1](#table-of-sha-1) under your version number below. Copy the SHA-1 for your Module so you can paste it into the URL in Step 2 below. The suggested branch name is `v-#.#.#` where #.#.# corresponds to the version number for `main`. You will use this in Step 3.3 below. -![create branch for version](img/create-branch.gif){width="600"} -{align="center"} + You should create a `branch` following the numbered steps and watching the GIF. Each Frame in the GIF corresponds to a numbered step below. -### Table of SHA-1 + 1. Click on URL line as indicated by the arrow + 1. Add the text `/tree/SHA-1` where you change SHA-1 to be the value in the table below and hit return + 1. Create a new branch in three steps + * 3.1: Click on the dropdown under the `branch` icon + * 3.2: Type the suggested new `branch` name in the blank space + * 3.3: Click on the create `branch` button + 1. You should see a screen similar to the example below + * Do not click on the Create Pull Request button that is marked with a big X -This will be updated with each release. The versions for the `dev` branch are not reported here because they are frequently updated. If customizing dev, use the default branch for each Module and `sync` that branch if needed. + ![create branch for version](img/create-branch.gif){width="600"} + {align="center"} + + ### Table of SHA-1 -#### Version 3.2.3 + This will be updated with each release. You do not need this information now - it is only important when submodules that are modified as part of `dev` branch changes to LoopWorkspace are sufficiently different from the versions used for `main` branch. -Suggested `branch` name is `v-3.2.3` + #### Version 3.4.1 -| Repository | SHA-1 | -|:--|:-:| -| `LoopWorkspace` | 81a3d9b03305a4b2a844bd6bac14a14f27626fef | -| `Loop` | c6b058b4276681600979aaeba518c635f06ac135 | -| `LoopKit` |9835a29f1bac9f75023f39c376479a2e6a6c8ccd | -| `OmniBLE` | f21360781c0b8eee26c531d20f1b0aa192a227f2 | -| `OmniKit` | c1e0d395975c93d15b3f84ac21097e40b7d5d93f | + | Repository | SHA-1 | + |:--|:-:| + | `LoopWorkspace` | 8060718e78b44ef45797082817392c1c4b7a7dab | + | `Loop` | 5c3b01f7e302dca9b8bbb12fd42fdd40ed52d2c1 | + | `LoopKit` |873b3b7c406cfc982f9061afb5f5e27e88d9208d | + | `OmniBLE` | 85fc3c6d4805d580acdf6592b220717b6e842558 | + | `OmniKit` | a80e38b1b7f203014b461f8aff8cead2c067e39d | ## Personalized Customization for this Module -Navigate to the file you need to modify (using the instructions to find the lines from the [Version: Custom Edit](../version/code-custom-edits.md#instructions-for-finding-the-lines){: target="_blank" } page) +Navigate to the file you need to modify (using the instructions to find the lines from the [Version: Custom Edit](../version/code-custom-edits.md#instructions-for-finding-the-lines){: target="_blank" } page). + +??? abstract "How do I navigate to the file? (Click to open/close)" + Let's do an example. + + Suppose you want to add this customization: [Pods: Add Extra Insulin on Insertion](../version/code-custom-edits.md#pods-add-extra-insulin-on-insertion){: target="_blank" } + + The folder name is: ` OmniBLE/OmniBLE/OmnipodCommon`
+ The file name is: `Pod.swift` + + So you will go to your OmniBLE fork (see [New Fork](#new-fork){: target="_blank" } if you don't have a fork yet): + + 1. Tap to select `OmniBLE` folder in that fork + 1. Tap to select `OmnipodCommon` folder in that folder + 1. Tap to open the `Pod.swift` file + * Once the file is open, tap on the pencil icon and make your edits + * When done, review the [Example GIF](#example-gif) which shows the steps needed to save your changes after you complete the edit + + The graphic below shows the `fork` for the `OmniBLE` submodule with numbers that match the steps in the list above. If you need more detailed instructions, they are found after the graphic. + + ![example navigation to file in fork](img/navigate-submodule-omnible.svg){width="800"} + {align="center"} + + ??? info "More detailed instructions (Click to open/close)" + 1. Check that this repository is the correct submodule and that: + * Fork has your GitHub Username + * Fork says it is forked from LoopKit + * Fork is up to date with LoopKit + * Tap on the OmniBLE folder to open the next screen + 1. Check that your screen shows: + * `OmniBLE/OmniBLE` at the top (current folder location) + * Tap on the OmnipodCommon folder to open the next screen + 1. Check that your screen shows: + * `OmniBLE/OmniBLE/OmnipodCommon` at the top (current folder location) + * Tap on the Pod.swift file to open it + * Tap on the pencil icon (upper right) to start editing the file + + Now you are ready to move to the [Example GIF](#example-gif) which shows the steps needed to save your changes after you complete the edit. + !!! 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. @@ -224,13 +266,27 @@ This section provides the steps to make a single customization for the Module. I ### Example GIF -The GIF showing the creation of one customization is shown below. Please review the 4 frames of the GIF, read the detailed instructions below and then review the GIF again. In case you are concerned by the "Pull Request shown here; this is to your own fork, not back to the original. +The GIF below shows the steps needed to save an edited file, so you can configure the customization. Please review the 4 frames of the GIF, read the [Detailed Instructions](#detailed-instructions) below and then review the GIF again. + +There are 4 frames shown in this GIF; the frame number is noted at the bottom right. Take the time to cycle through several times to observe what you need to do. + +* Frame 1 shows what to do after you have completed the edits you want for this file + +* **Frame 2 shows a `Pull Request` to your own repository - that is OK** + +* Frame 3 displays a green `Compare & pull request` button that would make a `Pull Request` to a `LoopKit/repository` - **do NOT click that button** + +* Frame 4 shows how to obtain the really-long alphanumeric string (SHA-1) needed to modify your build_loop.yml file ![GitHub screen while creating a customization](img/browser-customize.gif){width="750"} {align="center"} ### Detailed Instructions +If you followed along above and made the modifations, you can skip ahead to [Prepare the Customizations](#prepare-the-customizations). + +This section provides the detailed steps just explained in [Example GIF](#example-gif). + You will be using the "pencil" tool in the browser display for your fork. !!! question "Are there detailed instructions?" @@ -292,6 +348,8 @@ Repeat this process until you've done all your customizations for this Module an ## Prepare the Customizations +There are two ways to use this customization. Keep reading for the method in which you edit the build_loop.yml file. If you are feeling adventurous, check out [How to use the `patches` Folder](#how-to-use-the-patches-folder){: target="_blank" }. + Once you prepare the commands, then you will edit the build_loop.yml file of your fork of LoopWorkspace. !!! warning "Ensure your fork is from LoopKit/LoopWorkspace" @@ -325,6 +383,8 @@ To view the exact code change associated with that patch, open a browser at the ## Update LoopWorkspace +With the release of 3.4.x, there are two ways to use this customization. Keep reading for the method in which you edit the build_loop.yml file. If you are feeling adventurous, check out [How to use the `patches` Folder](#how-to-use-the-patches-folder){: target="_blank" }. + The final step is to update your LoopWorkspace fork to apply these customizations by adding those customization lines into the build_loop.yml file. Return to your GitHub fork for LoopWorkspace and make sure to sync it if needed. @@ -334,43 +394,56 @@ Return to your GitHub fork for LoopWorkspace&nb * Click on the pencil (so you can edit this file) * If you are building version 3.4 * Skip ahead to [Add Personal Customizations to build_loop.yml](#add-personal-customizations-to-build_loopyml) -* If you are building from an older version of main (version 3.2.3 or earlier), this is left here for your convenience - it will be removed over the next few months - please update soon - * Locate line 31, which is just above the words: - * `# Patch Fastlane Match to not print tables` - * Paste the contents of the block below so it comes before that section - * In the next section - you will need to modify the line number where you do the edits +??? abstract "Older versions (Click to open/close)" + * If you are building from an older version of main (version 3.2.3 or earlier), this is left here for your convenience - it will be removed over the next few months - please update soon + * Locate line 31, which is just above the words: + * `# Patch Fastlane Match to not print tables` + * Paste the contents of the block below so it comes before that section + * In the next section - you will need to modify the line number where you do the edits -``` { .text .copy title="Paste into build_loop.yml" } - # Customize Loop: Download and apply patches - - name: Customize Loop - run: | - # For each patch, edit comment line (keep the #) then update curl (and remove the #) + ``` { .text .copy title="Paste into build_loop.yml" } + # Customize Loop: Download and apply patches + - name: Customize Loop + run: | - # Submodule Loop patches: - # Loop: Filename: customization details - #curl https://github.com/username/Loop/commit/SHA-1.patch | git apply -v --directory=Loop - - # Submodule LoopKit patches: - # LoopKit: Filename: customization details - #curl https://github.com/username/LoopKit/commit/SHA-1.patch | git apply -v --directory=LoopKit - - # Submodule xxxxx patches: Follow prototype above + # For each patch, edit comment line (keep the #) then update curl (and remove the #) + # Submodule Loop patches: + # Loop: Filename: customization details + #curl https://github.com/username/Loop/commit/SHA-1.patch | git apply -v --directory=Loop + + # Submodule LoopKit patches: + # LoopKit: Filename: customization details + #curl https://github.com/username/LoopKit/commit/SHA-1.patch | git apply -v --directory=LoopKit + + # Submodule xxxxx patches: Follow prototype above -``` + + ``` ### Add Personal Customizations to build_loop.yml Open the text file in which you saved the customization lines. -For a given submodule, paste the comment curl lines that you prepared in [Prepare customization lines](#prepare-customization-lines) similar to the examples, near line 239, that are commented out and provided as an example. The best place to paste these is at the end of the `# Customize Loop: Download and apply patches` section and before the `# Patch Fastlane Match to not print tables` line. +For a given submodule, paste the "comment" and "curl" lines that you prepared in [Prepare customization lines](#prepare-customization-lines) similar to the examples, near line 279 (`main` or 239 for `dev`), that are commented out and provided as an example. The best place to paste these is at the end of the `# Customize Loop: Download and apply patches` section and before the `# Patch Fastlane Match to not print tables` line. + +The indenting needs to match, so tab or (shift-tab) to line up the columns. The graphic below shows a couple of common mistakes. + +* All lines within a given section need to start in the same column (see the vertical dashed green line) +* Comments (lines starting with a `#`) placed in the wrong column will cause the build to fail +* Commands (line starting with `curl`) placed in the wrong column will cause the build to fail + +The command placed in the correct column has 4 "words" highlighted with red rectangles. You must have the correct values for all 4 of these places or the build will fail. -The indenting needs to match, so tab or (shift-tab) to line up the columns. +![indentation and blank lines are important](img/modify-build-loop-yml.svg){width="600"} +{align="center"} It is best to leave a blank line between customizations. +**You must have a blank line** after the last customization and before the `# Patch Fastlane Match to not print tables` line or the build will fail. + **Once you are done with all the edits for build_loop.yml you will commit the changes to your fork directly.** * Once you have finished the edits for build_loop.yml @@ -395,6 +468,42 @@ Wait about 2 minutes before walking away to make sure there are no errors. If yo In about 1 hour, your customized app will be available for installation on your phone via *TestFlight*. +## Extra Information + +The rest of this page has additional information most people can skip. If a mentor is helping you, they may use some of this information. + +### How to Use the `patches` Folder + +With the release of 3.4.x, you can add patches to your `GitHub-Username/LoopWorkspace` fork in the `patches` folder. Those patches will then be automatically added to your build every time without needing to modify the build_loop.yml file. + +Refer to [Prepare customization lines](#prepare-customization-lines){: target="_blank" }: + +* extract the text from "https:" through "patch" and paste that into a new tab +* this will open a browser similar to the following graphic + +![open patch at GitHub](img/browser-open-to-patch.png){width="750"} +{align="center"} + +Now you need to download that file (Save Page As, if using chrome). + +Once the file is downloaded to a sensible name, make a copy (or rename it) to indicate that you have edited the file to make it a Workspace level patch. An example is shown below. + +* Top file shows the original download +* Lower file shows the renamed and edited version: + * Add the name of the module to the "a" and "b" directory paths so the patch is applied to the correct folder (from LoopWorkspace) + * In this example `OmniBLE/` was added in 4 places as highlighted by red rectangles + +![download and then edit patch for Workspace](img/prepare-workspace-patch.svg){width="750"} +{align="center"} + +If you've gotten this far, keep going. No more pretty graphics, but I think you can figure it out. + +* Return to your `GitHub-Username/LoopWorkspace` fork, tap on the `patches` folder +* At the upper right, click on `Add file` dropdown and choose `Upload files` + * Drag and drop your Workspace level patch into the window + * Commit to your default branch +* Test the build to make sure everything worked + ### Customization and SHA-1 When you commit your customization to your `branch` of your `fork`, there is a new SHA-1 associated with that step. The SHA-1 for a given branch, typically `main` or `dev` identifies to a mentor exactly which version of code you used for your build. diff --git a/docs/browser/img/browser-open-to-patch.png b/docs/browser/img/browser-open-to-patch.png new file mode 100644 index 00000000000..dff1f25b499 Binary files /dev/null and b/docs/browser/img/browser-open-to-patch.png differ diff --git a/docs/browser/img/modify-build-loop-yml.svg b/docs/browser/img/modify-build-loop-yml.svg new file mode 100644 index 00000000000..2709dc3341c --- /dev/null +++ b/docs/browser/img/modify-build-loop-yml.svg @@ -0,0 +1,2586 @@ + +image/svg+xmlXX diff --git a/docs/browser/img/navigate-submodule-omnible.svg b/docs/browser/img/navigate-submodule-omnible.svg new file mode 100644 index 00000000000..f1d151029b2 --- /dev/null +++ b/docs/browser/img/navigate-submodule-omnible.svg @@ -0,0 +1,9252 @@ + +image/svg+xml123 diff --git a/docs/browser/img/prepare-workspace-patch.svg b/docs/browser/img/prepare-workspace-patch.svg new file mode 100644 index 00000000000..3909238bb81 --- /dev/null +++ b/docs/browser/img/prepare-workspace-patch.svg @@ -0,0 +1,5111 @@ + +image/svg+xml diff --git a/docs/browser/phone-install.md b/docs/browser/phone-install.md index 89326401beb..54791d78797 100644 --- a/docs/browser/phone-install.md +++ b/docs/browser/phone-install.md @@ -82,15 +82,43 @@ Once the app is available in *TestFlight*, you can adjust whether it is automati 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*, you must disable automatic update or Xcode will not be able to install to your phone. +* If you leave automatic update enabled (default), then whenever a new build is created and uploaded to *TestFlight* , it will be installed immediately (see [Unexpected *TestFlight* Expiration](#unexpected-testflight-expiration)) +* 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"} When you are ready to install, just open the *TestFlight* app and click Install to get the most recent build and then click Open when it completes the installation. All your settings and connections to CGM and Pump are maintained. -If you tap on the bottom row that says `Previous Builds`, highlighted by the dashed-green rectangle, you can view and choose an older build (as long as it has not expired). +### Previous Builds + +If you tap on the bottom row that says `Previous Builds`, highlighted by the dashed-green rectangle, you can view and choose an older (or lower version number) build (as long as it has not expired). + +* In some cases, you need to do this to see the newest build +* For example, it you build version 3.5.0 (`dev` branch) accidentally and then switched to 3.4.x (`main` branch), *TestFlight* shows you the 3.5.0 version on the screen and you need to go to previous builds to find your newer 3.4.x build + +### Unexpected *TestFlight* Beta Expiration + +!!! important "*Apple TestFlight* Bug" + It doesn't happen to everyone but it has happened a few times over the years and only for people who have Automatic Update enabled for their *TestFlight* app. + + Symptom: + + * App has plenty of time before expiration + * A new build becomes available, for example from the automatic monthly rebuild + * User is told *Loop* Beta is not available + + Solution: + + * Open *TestFlight* and turn off automatic installation for your app + * Install the previous version of the app on the phone manually (with monthly build, it should still be ok) + * Manually start a new build (if there were updates you want to get) + * Manually install the new update + + More information: + + * [Link 1: Apple forum](https://forums.developer.apple.com/forums/thread/720033){: target="_blank" } + * [Link 2: Stackoverflow thread](https://stackoverflow.com/questions/74588716/testflight-beta-has-expired){: target="_blank" } ## *TestFlight* for a Child diff --git a/docs/build/build-dev-mac.md b/docs/build/build-dev-mac.md index d35405be963..7156d4dd07e 100644 --- a/docs/build/build-dev-mac.md +++ b/docs/build/build-dev-mac.md @@ -17,7 +17,6 @@ There is a script to assist in building the `dev branch`. It gives you the optio /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 diff --git a/docs/loop-3/features.md b/docs/loop-3/features.md index e465cb941b0..3c04efec849 100644 --- a/docs/loop-3/features.md +++ b/docs/loop-3/features.md @@ -44,7 +44,7 @@ Two algorithm experiments are now available in the *Loop* app (version 3.4.0 or * The "switcher" patch is no longer compatible * The GBPA feature is intended to replace the functionality of that older customization and is controlled completely inside the *Loop* app -_Glucose Based Partial Application_ is only used when _Automatic Bolus_ (AB) is selected for _Temp Basal Only_ _Dosing Strategy_ +_Glucose Based Partial Application_ is only used when _Automatic Bolus_ (AB) is selected for _Dosing Strategy_ * This modification **does not affect the recommended dose**, only how quickly the recommended dose is automatically delivered diff --git a/docs/version/build-time-flag.md b/docs/version/build-time-flag.md index 69c104404df..29542d4a449 100644 --- a/docs/version/build-time-flag.md +++ b/docs/version/build-time-flag.md @@ -1,17 +1,21 @@ ## 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. +## Modify the `Build Time Flags` -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. +The `Build Time Flags` are available for both build methods: -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. +* **Build with Browser** + * Edit the LoopConfigOverride.xcconfig file in your fork + * Use the pencil icon in that file to make the modification shown below and commit the change to your fork + * Do not try to open a pull request to LoopKit/LoopWorkspace - only modify your-github-username/LoopWorkspace version +* **Build with *Mac* Method** + * You edit the 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. + * If you edit `~/Downloads/BuildLoop/LoopConfigOverride.xcconfig`, the "flags" you add are applied to this download and all subsequent downloads created with the script. -!!! question "New Instructions" - The instructions are more robust than earlier instructions that had you editing a line instead of adding new ones. +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. 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. @@ -40,7 +44,7 @@ _Code After Modification_ SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(SWIFT_ACTIVE_COMPILATION_CONDITIONS) SIRI_DISABLED ``` -List of some flags and what they do: +## Table of Build Time Flags |FLAG|PURPOSE| |---------|---------| diff --git a/docs/version/code-custom-edits.md b/docs/version/code-custom-edits.md index a4a38a1cccb..fe81193c02d 100644 --- a/docs/version/code-custom-edits.md +++ b/docs/version/code-custom-edits.md @@ -41,6 +41,8 @@ The instructions on this page identify the module, `Key_Phrase` or file and line * 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 * Sometimes there is a bigger change than just line numbers. The git software is really good about finding the "right" code that is just at a different line number. When you see the notation `Stable: Changed on date`, that means you must select the correct version when making your personal customization depending on which version you are modifying. + * With the release of 3.4.x, no customizations fall into this category + * The notation is kept to handle future changes that might happen when development start again This page is broken into two halves: @@ -65,22 +67,11 @@ 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)

+* 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 -!!! tip "Stability Information Added" - Some customizations have not changed for a very long time (stable since 2.2.x days). - - It was not until version 3.2.3 that we started adding a notation as to when the required customization code changed. - - For those using the Browser Build method: - - * If you had a customization working for 3.2.3 it will continue to work with 3.4.0 unless it is one listed in the [Not Stable List](#not-stable-list) - * However, because the `build_loop.yml` file is significantly different for version 3.4.0, you will need to save your "customization lines" from the `build_loop.yml` file in the 3.2.3 version of your `fork` and add them to a new location for the 3.4.0 version of `build_loop.yml` in your `fork` - * If one of your personalized customizations is in the [Not Stable List](#not-stable-list) you will need to create a new version [Custom Edits with Browser: Code Updates](../browser/edit-browser.md#code-updates){: target="_blank" } - Each customization provides the Module, Folder and File bullet below the key phrase. * Module: Loop @@ -88,7 +79,7 @@ Each customization provides the Module, Folder and File bullet below the key phr * File: filename.swift, line number(s) * Stable: "Yes" or "Changed on date: Version #" -The customizations below show the original line of code that you will be changing. +Each customization will show the original line of code that you will be changing. There may be a figure illustrating the change. @@ -97,6 +88,27 @@ Below the figure, the original, and in some cases, the modified code will be dis * 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 +### What does `Stable` mean? + +The line starting with `Stable` was previously used to indicate when code changes were sufficient to require a different customization. With the release of 3.4.x, all customizations show `Stable: Yes`. + +* A few have an additional notation of when they were last changed; if you use these with browser build, you must update the customization going from 3.2.3 to 3.4.x +* All customizations are currently identical for `main` and `dev` +* Instructions for older versions of the customization are removed from this page. + +There are two customizations, see [Not Stable List](#not-stable-list) that require an update between version 3.2.3 and 3.4.x. If you use one of those customizations for the Browser Build method, you will be required to update it if you want to continue using that customization. + +??? tip "More Information about `Stable` (Click to open/close)" + Some customizations have not changed for a very long time (stable since 2.2.x days). + + It was not until version 3.2.3 that we started adding a notation as to when the required customization code changed. + + For those using the Browser Build method: + + * If you had a customization working for 3.2.3 it will continue to work with 3.4.0 unless it is one listed in the [Not Stable List](#not-stable-list) + * However, because the `build_loop.yml` file is significantly different for version 3.4.x, you will need to save your "customization lines" from the `build_loop.yml` file in the 3.2.3 version of your `fork` and add them to a new location for the 3.4.x version of `build_loop.yml` in your `fork` + * If one of your personalized customizations is in the [Not Stable List](#not-stable-list) you will need to create a new version when upgrading from 3.2.x to 3.4.x [Custom Edits with Browser: Code Updates](../browser/edit-browser.md#code-updates){: target="_blank" } + #### Not Stable List This list indicates personalized customization that differ between 3.2.3 and 3.4.x: @@ -111,7 +123,9 @@ This list indicates personalized customization that differ between 3.2.3 and 3.4 ![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 `the *Loop* app` to 30 minutes, 3 hours and 5 hours respectively. Some people prefer different values. +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 `the *Loop* app` to 30 minutes, 3 hours and 5 hours respectively. Some people prefer different values. + +If you want to change this to 2, 3 and 5 hours - that is available as a standard customization using the [*Loop and Learn*: Customization Select Script](https://www.loopandlearn.org/custom-code/#custom-list){: target="_blank" } ??? 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 slow values are for moderate and higher-fat or large meals. @@ -171,6 +185,8 @@ Because the automatic bolus amount is also limited by the partial application fa 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. +> With the release of version 3.4.x, there is another option. If you choose to enable [Glucose Based Partial Application](../loop-3/features.md#glucose-based-partial-application-gbpa){: target="_blank" }, then the percent of the recommended bolus automatically provided adjusts from 20% to 80% depending on your glucose level. You may decide this works well enough for you that this customization is no longer desired. Please give this new feature a try. + 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.** @@ -239,11 +255,11 @@ Guardrail(absoluteBounds: * File: Guardrail+Settings.swift * Line: 12 for suspendThreshold * Line: 26 for correctionRange -* Stable: Changed on 2024 Feb 19: Version 3.4.0 - -#### Version 3.4.0 +* Stable: Yes + * Last Changed on 2024 Feb 19 -This update, merged on 2024 Feb 19 was part of a larger fix to a problem when glucose units were mmol/L. The user could not select two values (min and max) that were the same and equal to the reported absolute range. This was a rounding problem going between mmol/L and mg/dL that has now been resolved. Part of the resolution was to modify the mg/dL absolute ranges to preserve the previously reported mmol/L absolute ranges. +??? info "Update Details (Click to open/close)" + This update, merged on 2024 Feb 19 was part of a larger fix to a problem when glucose units were mmol/L. The user could not select two values (min and max) that were the same and equal to the reported absolute range. This was a rounding problem going between mmol/L and mg/dL that has now been resolved. Part of the resolution was to modify the mg/dL absolute ranges to preserve the previously reported mmol/L absolute ranges. _Code Before Modification_ @@ -257,20 +273,6 @@ Modify the absoluteBounds to change the allowed ranges or the recommendedBounds Loop automatically converts from mg/dL to mmol/L. So you must enter values reasonable for mg/dL (18 times higher than for mmol/L). -#### Version from 3.2.3 - -_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 absoluteBounds to change the allowed ranges or the recommendedBounds to change the color of the numbers on the picker wheel. - -Loop automatically converts from mg/dL to mmol/L. 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. @@ -308,9 +310,8 @@ The *Loop* app limits to 1 hour the amount of time in the future that carbs can * Module: Loop * Folder: Loop/Loop/Models * File: LoopConstants.swift, Line 28 -* Stable: Changed on 2023 May 29 through 2023 Aug 20: Version 3.4.0 - -#### Version 3.4.0 +* Stable: Yes + * Last changed 2023 Aug 20 ``` { .txt .copy title="Key_Phrase" } static let maxCarbEntryFutureTime @@ -324,23 +325,6 @@ _Code Before Modification_ Change the maxCarbEntryFutureTime 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. -#### Version from 3.2.3 - -* Folder: Loop/Loop/View Controllers -* File: CarbEntryViewController.swift, Line 438 - -``` { .txt .copy title="Key_Phrase" } -cell.datePicker.maximumDate = date.addingTimeInterval -``` - -Default shown below (for maximum and minimum): - -_Code Before Modification_ - - cell.datePicker.maximumDate = date.addingTimeInterval(.hours(1)) - -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. - ### 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! @@ -386,7 +370,7 @@ This key phrase will indicate three different files in the same folder as shown 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 Notification](../operation/features/notifications.md#loop-app-expiration-notification){: target="_blank" } to see the expiration reminder If you prefer a different notification time and frequency, there are two lines you can modify: @@ -504,6 +488,10 @@ And now you'll be the proud new owner of a custom Loop icon. ## Custom Edits Optional +The customizations listed below are incorporated into the [*Loop and Learn*: Customization Select Script](https://www.loopandlearn.org/custom-code){: target="_blank" }. + +You can use that script or make your own edit by following these directions. + ### 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. diff --git a/docs/version/development.md b/docs/version/development.md index 144f2916ff4..667ecb017c9 100644 --- a/docs/version/development.md +++ b/docs/version/development.md @@ -21,7 +21,7 @@ Right now it is empty. Most features, originally in the Updates in `dev` section before the release of version 3.4, have been inserted into the appropriate part of the *LoopDocs* website (indicated by the up-right arrow after the link). A few items are still in this section. * [Support for Libre Sensors](../loop-3/add-cgm.md#libre){: target="_blank" } -* [Simulated Pump or CGM on Phone](simulator.md#simulated-pump-or-cgm-on-phone){: target="_blank" } +* [Pump or CGM Simulator on Phone](simulator.md#pump-or-cgm-simulator-on-phone){: target="_blank" } * [Algorithm Experiments](../loop-3/settings.md#algorithm-experiments){: target="_blank" } * [Glucose Based Partial Application Factor](../loop-3/features.md#glucose-based-partial-application-gbpa){: target="_blank" } * [Integral Retrospective Correction](../loop-3/features.md#integral-retrospective-correction-irc){: target="_blank" } diff --git a/docs/version/releases.md b/docs/version/releases.md index 6f723b63f56..ec2733bf424 100644 --- a/docs/version/releases.md +++ b/docs/version/releases.md @@ -163,7 +163,7 @@ Each release uses 3 numbers: Major.Minor.Patch * Major is reserved for a significant change in the code, such as occurred going from `Loop 2.2.9` to `Loop 3.0.0` * Minor is used when the development branch is released for general use -* Patch typically indicates a modification to support external events like an Xcode or iOS version update with no feature changes in Loop +* Patch typically indicates a modification for a quick bug-fix or to support external events like an Xcode or iOS version update with no feature changes in Loop To prevent confusion between versions used for development and versions used for release (`main` `branch`), the Minor values are even for released code. The Minor value for the development `branch` (`dev`) is incremented as part of the release process and is always odd. @@ -174,7 +174,8 @@ For example: * `Loop 3.2.0` was the next released version * `Loop 3.2.1, 3.2.2 and 3.2.3` are patches to `Loop 3.2.0` without changes to the features of `Loop 3.2.x` * `Loop 3.3.0` was the development version before `Loop 3.4.0` was released -* `Loop 3.4.0` is the current version +* `Loop 3.4.0` was the next released version + * `Loop 3.4.1` is a patched version (fixed Browser Build) without changes to the features of `Loop 3.4.x` * `Loop 3.5.0` is the current development version ## Remove Apps with Shared App Group diff --git a/docs/version/simulator.md b/docs/version/simulator.md index 109960c33ac..ce88f9d1180 100644 --- a/docs/version/simulator.md +++ b/docs/version/simulator.md @@ -62,7 +62,7 @@ When building to a real phone using a *Mac*, you must have access to a [Compatib * Follow the [set up the app](../loop-3/loop-3-overview.md) instructions on your phone but choose a simulated pump * If you have a compatible CGM on this phone, you can select that or you can use the simulated CGM or enter glucose values on the main Loop screen -### What to Expect +## What to Expect with a Simulator !!! warning "Locked Phone or App in Background" Loop will not work in the background without either a real CGM or a real pump to "wake" it up. @@ -92,11 +92,19 @@ 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. -### Simulated Pump or CGM on Phone +### Pump or CGM Simulator on Phone The simulators for the Pump and CGM, with version 3.3 and later, hide their detailed configuration screen. The initial view is a demonstration screen showing a typical CGM or Pump display. In order to configure the simulator controls or delete the simulator, you must tap on the Simulator Settings row. ![tap on simulator settings row to get to controls](img/update-simulators.svg){width="500"} {align="center"} -If you do not see the Simulator Settings row, you have an older version. You can see the settings by doing a long-press (5 to 10 sec) in the top portion of the simulator screen. If you've counted to 10 and the display has not updated yet, then return to the main screen, go back to the simulator screen, and try again. \ No newline at end of file +If you do not see the Simulator Settings row, you have an older version. You can see the settings by doing a long-press (5 to 10 sec) in the top portion of the simulator screen. If you've counted to 10 and the display has not updated yet, then return to the main screen, go back to the simulator screen, and try again. + +### Delete the Pump or CGM Simulator on Phone + +To delete a pump simulator or CGM simulator from the *Loop* app on the phone, you must first tap on the Simulator Settings row, see graphic above. + +Then scroll down to the bottom of the screen and select `Delete Pump` or `Delete CGM`. + +After deleting the simulator, you can then [Add Pump](../loop-3/add-pump.md){: target="_blank" } or [Add CGM](../loop-3/add-cgm.md){: target="_blank" }.