Merge pull request #704 from marionbarker/working-docs

Various Updates

docs/faqs/apple-health-faqs.md

@@ -155,7 +155,7 @@ If you happen to wear a *Dexcom* G6 and G7 sensor at the same time, then startin
 *Loop* only uses data from the CGM you selected as your CGM for closed-loop insulin delivery, but don't be surprised at the double trace if you want to wear both during the transition from G6 to G7.
 
 !!! tip "Add Permission to Health for *Dexcom* to Write Glucose"
-    If either the G6 or the G7 has permission to write to *Apple Health*, then Loop will delete the *Loop* glucose data in *Apple Health* that is older than 3 hours and newer than 1 week. The *Dexcom* app will write its glucose values to Health when each value is 3 hours old.
+    If either the G6 or the G7 has permission to write to *Apple Health*, then Loop will delete the *Loop* glucose data in *Apple Health* that are older than 3 hours and newer than 1 week. The *Dexcom* app will write its glucose values to Health when each value is 3 hours old.
 
     If you transition from G6 to G7 (or alternate back and forth), be sure that at least the app you are currently using has permission to write to health. (I inadvertently forgot to turn on health permission for G7. By the time I noticed, I had a gap of several days in my *Apple Health* storage of glucose values.)
 

docs/faqs/cgm-faqs.md

@@ -21,10 +21,10 @@ No, you can start Looping mid-sensor session. There's no need to do anything spe
 
 Loop will stop automatically adjusting insulin when the most recent glucose value is older than 15 minutes.  This is indicated by seeing three dashes in place of the glucose reading on the HUD.
 
-* With Loop 2.2.x or Loop 3, enter a fingerstick glucose value in Apple Health to enable Loop to provide updated projections and loop briefly
-
 * With Loop 3, a HUD status row message of `No Recent Glucose` is displayed, making it easier to add the fingerstick value directly in Loop, which also saves it in Apple Health
 
+* With Loop 2.2.x or Loop 3, enter a fingerstick glucose value in Apple Health to enable Loop to provide updated projections and loop briefly
+
 With no recent glucose readings, your pump returns to the scheduled basal delivery (within 30 min or less).
 
 Loop continues to accept manual bolus commands. With Loop 3 only, [Manual Temp Basal](../loop-3/omnipod.md#manual-temp-basal) can also be commanded.

docs/loop-3/add-cgm.md

@@ -32,6 +32,10 @@ To add a CGM, go to the Settings screen ⚙️, tap on `Add CGM`, and tap on you
 ![graphic showing some of the CGMs available with Loop 3](img/loop-3-setting-add-cgm.svg){width="500"}
 {align="center"}
 
+If you later decide to use a different CGM type, you must first delete the CGM and then add CGM to choose the new one.
+
+*   For Dexcom G5, G6 or ONE, you must delete the CGM when you change transmitters (about once every 90 days)
+
 ### Dexcom G5, G6, ONE
 
 To use the Dexcom G5, G6 or ONE:
@@ -66,9 +70,15 @@ You can find the **transmitter ID** in your Dexcom G6 app or on the back of the
 {align="center"}
 
 
+#### Change Dexcom Sensor
+
+When you change a Dexcom G5, G6 or ONE sensor, you do this in the Dexcom app. When the sensor completes warmup and CGM values are once again reported in the Dexcom app, Loop picks these values up because you are using the same Dexcom Transmitter.
+
 #### Change Dexcom Transmitter
 
-!!! info "FYI: When You Change Dexcom Transmitters"
+When you change the Dexcom G5, G6 or ONE Transmitter, you need to delete your CGM selection from Loop and then add it back after you complete the pairing with the transmitter in your Dexcom app.
+
+??? info "FYI: When You Change Dexcom Transmitters (click to open)"
 
     Before you change Dexcom transmitters, select the `Delete CGM` button at the very bottom of the CGM info page in Loop. If you leave the transmitter connected in Loop, you may have trouble pairing your new transmitter. If pairing does work, then Loop will not get CGM data from the Dexcom app on your phone.
 
@@ -95,7 +105,7 @@ Minimal documentation is provided.
 !!! tip "Don't forget Health Permissions"
     For those switching from *Dexcom G6* to *Dexcom G7*, you might forget to add permission for the *G7* app to write to *Apple Health*. If you want long-term history of those CGM readings to persist in *Apple Health*, turn on the permission for the *Dexcom* app to write glucose to *Health*.
 
-    If either the G6 or the G7 has permission to write to *Apple Health*, then *Loop* will delete the *Loop* glucose data in *Apple Health* that is older than 3 hours and newer than 1 week. The *Dexcom* app will write its glucose values to Health when each value is 3 hours old.
+    If either the G6 or the G7 has permission to write to *Apple Health*, then *Loop* will delete the *Loop* glucose data in *Apple Health* that are older than 3 hours and newer than 1 week. The *Dexcom* app will write its glucose values to Health when each value is 3 hours old.
 
 ### Medtronic Enlite CGM
 

docs/loop-3/onboarding.md

@@ -138,11 +138,11 @@ The therapy settings are the heart of how Loop makes predictions. If your settin
         * Glucose Safety Limit
         * Correction Range
         * Pre-Meal Range
+        * Carb Ratios
         * Basal Rates
         * Delivery Limits
             * Maximum Basal Rate
             * Maximum Bolus
-        * Carb Ratios
         * Insulin Sensitivites
 
 #### Guardrails While Onboarding
@@ -199,6 +199,13 @@ The [Pre-Meal Range](therapy-settings.md#pre-meal-range), which is optional, giv
 !!! abstract "Example"
     If your normal range is 100-110 mg/dL (5.6-6.1 mmol/L) and pre-meal range is 80-80 mg/d L (4.4 mmol/L), Loop will give you extra insulin to move you towards the lower range number before the meal. This early insulin brings you into the meal with a mini-prebolus. The pre-meal range, when activated by pressing on the [pre-meal icon](../operation/features/premeal.md) in the toolbar, will stay active for one hour, until carbs are entered, or until it is manually cancelled...whichever comes first.
 
+### Carb Ratios
+
+Your [Carb Ratio](therapy-settings.md#carb-ratios) is the number of grams of carbohydrates covered by one unit of insulin.
+
+* At least one carb ratio (CR) must be entered
+* A daily schedule with varying CR can be entered
+
 ### Basal Rates
 
 You must provide a [Basal Rate](therapy-settings.md#basal-rates) schedule and the schedule must start at midnight. Loop does not provide the option for having more than one profile saved that you can switch between.
@@ -244,12 +251,7 @@ Experienced loopers typically set their maximum basal rate around 3-4 times thei
 
 For safety, don't set a maximum bolus limit any higher than your typical large meal bolus. Many people like to set a value less than 10 U, for example, 9 or 9.9 U, to avoid accidentally typing in a bolus of 10 instead of 1.0 U.
 
-### Carb Ratios
-
-Your [Carb Ratio](therapy-settings.md#carb-ratios) is the number of grams of carbohydrates covered by one unit of insulin.
-
-* At least one carb ratio (CR) must be entered
-* A daily schedule with varying CR can be entered
+This setting also limits how much **automated** dosing is allowed. Loop will not automatically increase the user's IOB above two times the Maximum Bolus. This is true with <code>Dosing Strategy</code> of <code>Temp Basal Only</code> or <code>Automatic Bolus</code>.
 
 ### Insulin Sensitivities
 

docs/loop-3/therapy-settings.md

@@ -118,9 +118,19 @@ The GIF below shows three screens from various scenarios. The red box indicates
     * If you do not add an entry, the pre-meal icon on the toolbar is disabled
     * If you add an entry, the pre-meal icon is activated for 1 hour or until carbs are entered or until the user cancels it
 
-
 [Guardrails for Pre-Meal Range](#guardrails-for-pre-meal-range)
 
+### Carb Ratios
+
+Your Carb Ratio is the number of grams of carbohydrates covered by one unit of insulin.
+
+* At least one carb ratio must be entered
+    * Use the + sign, picker wheels and then tap "Add"
+    * The method was described in the [Correction Range](#correction-range) section
+* Loop supports 1 to 48 carb ratios per day
+
+[Guardrails for Carb Ratios](#guardrails-for-carb-ratios)
+
 ### Basal Rates
 
 Your Basal Rate of insulin is the number of units per hour that you want to use to cover your background insulin needs.
@@ -151,29 +161,22 @@ If the Dosing Strategy is configured to Temp Basal Only, then the maximum basal
 
 ### Maximum Bolus
 
-Maximum Bolus is the highest bolus amount that you will allow Loop to recommend at one time to cover carbs or bring down high glucose.
+Maximum Bolus is the highest bolus amount that you will allow Loop to recommend at one time to cover carbs or bring down high glucose. The value the user selects for Maximum Bolus is also used to set a maximum level of IOB for **automated** dosing.
+
+1. Maximum Bolus is the largest single bolus that Loop will recommend or allow the user to bolus in a single action
+1. Maximum Automatic IOB is two times the value of Maximum Bolus
+    * The Loop algorithm will not **automatically** dose any value that would cause the user's IOB to exceed Maximum Automatic IOB
+    * The user can exceed Maximum Automatic IOB with a **manual** bolus
+    * The recommended manual bolus amount is limited by Maximum Bolus
 
-If you manually enter a value in the Bolus screen that is greater than the Maximum Bolus setting, Loop will show a warning message and refuse to bolus that amount.
+If you manually enter a value in the Bolus screen that is greater than the Maximum Bolus setting and press `Deliver`, Loop will show a warning message and refuse to bolus that amount.
 
 For safety, don't set a maximum bolus limit any higher than your typical large meal bolus. Many people like to set a value less than 10 U, for example, 9 or 9.9 U, to avoid accidentally typing in a bolus of 10 instead of 1.0 U.
 
-If the Dosing Strategy is configured to Automatic Bolus, then the maximum bolus that is automatically supplied is 40% of the maximum bolus, but this can be applied at 5-minute intervals.
+If the Dosing Strategy is configured to Automatic Bolus, then the maximum bolus that is automatically supplied is 40% of the maximum bolus, but this can be applied at 5-minute intervals. Automatic dosing is limited to keep the user's IOB less than two times the Maximum Bolus setting.
 
 [Guardrails for Maximum Bolus](#guardrails-for-maximum-bolus)
 
-
-### Carb Ratios
-
-Your Carb Ratio is the number of grams of carbohydrates covered by one unit of insulin.
-
-* At least one carb ratio must be entered
-    * Use the + sign, picker wheels and then tap "Add"
-    * The method was described in the [Correction Range](#correction-range) section
-* Loop supports 1 to 48 carb ratios per day
-
-[Guardrails for Carb Ratios](#guardrails-for-carb-ratios)
-
-
 ### Insulin Sensitivities
 
 Your Insulin Sensitivities refer to the drop in glucose expected from one unit of insulin over the full duration of the insulin action time. You may have also seen the term Correction Factor or Insulin Sensitivity Factor (ISF). These are all referring to the same setting.
@@ -257,7 +260,6 @@ The font color in the value picker has the following meaning:
     * Generic Pump rates from 0.05 U/hr to 30 U/hr in steps of 0.05
 * Top value available on the picker is your Maximum Basal Rate (once that is set)
 
-
 #### Guardrails for Maximum Basal Rate
 
 * Recommended maximum value available on the picker is 6.4 times the highest basal rate in your scheduled basal rates
@@ -267,7 +269,9 @@ The font color in the value picker has the following meaning:
 
 #### Guardrails for Maximum Bolus
 
-The maximum bolus is limited by your pump, but it is a good idea to limit it to the maximum you use for a common "big" meal. This only limits the bolus for a single dose.
+The maximum bolus is limited by your pump, but it is a good idea to limit it to the maximum you use for a common "big" meal. This limits the bolus for a single **manual** dose.
+
+This setting also limits how much **automated** dosing is allowed. Loop will not automatically increase the user's IOB above two times the Maximum Bolus. This is true with <code>Dosing Strategy</code> of <code>Temp Basal Only</code> or <code>Automatic Bolus</code>.
 
 #### Guardrails for Carb Ratios
 

docs/operation/features/bolus.md

@@ -8,14 +8,16 @@ Most of the information is the same for Loop 2.2.x and Loop 3.
 
 Loop 2 and 3 differences:
 
+* Loop 3 uses the setting name of Glucose Safety Limit, which has the same meaning as Suspend Threshold in Loop 2
+* With Loop 3.2 and later
+    * Loop automatic delivery of insulin is limited when users IOB is two times the [<code>Maximum Bolus</code>](../../loop-3/therapy-settings.md#maximum-bolus) amount
 * Bolus Row: 
-    * With Loop 3
+    * With Loop 3.0 and later
         * The Recommended Bolus is provided AND the default for the Bolus is the recommended value
         * If the user taps on the Bolus row, the amount is modified to 0 and the keyboard is opened for entry
     * With Loop 2.2.x
         * The Recommended Bolus is provided but the default for the Bolus value is 0
         * If the user taps on the Recommended Bolus row, the recommended amount is transferred to the Bolus row
-* Loop 3 uses the setting name of Glucose Safety Limit, which has the same meaning as Suspend Threshold in Loop 2
 
 ## Meal Bolus
 

docs/operation/loop/close-loop.md

@@ -50,21 +50,37 @@ This is definitely an area where YDMV (your diabetes may vary), so don't expect
 
 ## Automated Dosing
 
-Loop calculates a predicted glucose curve based on your programmed settings for carb ratio (CR) and insulin sensitivity factor (ISF), using your glucose, insulin and carb history. 
+Loop calculates a predicted glucose curve based on your programmed settings for carb ratio (CR) and insulin sensitivity factor (ISF), using your glucose, insulin and carb history.
+
+Two scenarios are given below to help illustrate the closed-loop automatic actions of Loop. A more typical scenario is to enter carbs and then use Loop's recommendation for an appropriate bolus.
+
+1. Enter a bolus with no carb entry
+1. Enter a carb entry without a bolus
+
+### Bolus with No Carbs
 
 If you enter a bolus without entering carbs, the prediction will be for your glucose to go low. (The Loop model calculates a negative number for recommended bolus.) For this case, Loop issues a Temp Basal to prevent the low, typically 0.0 U/hr but always less than your scheduled basal rate.
 
 !!! tip "COB and IOB"
     * <code>COB</code> is the carbohydrates (g) that Loop expects to be absorbed
     * <code>IOB</code> is the current active insulin (above or below the scheduled basal rate)
 
-If you enter carbs and select `Save without bolusing`, you have COB without associated IOB. In that case, Loop predicts your glucose will start rising and updates the recommended bolus, which includes consideration of your [`Glucose Safety Limit`](../../loop-3/therapy-settings.md#glucose-safety-limit), [`Correction Range`](../../loop-3/therapy-settings.md#correction-range) and [`Maximum Bolus`](../../loop-3/therapy-settings.md#maximum-bolus) . If that recommended bolus is positive, Loop might deliver some part of that bolus automatically - the exact percentage and timing of that delivery depends on your [`Dosing Strategy`](../../loop-3/settings.md#dosing-strategy). At each loop cycle (new glucose reading), Loop updates the prediction and calculates a new recommended bolus. When you enter carbs without bolusing, Loop may start delivering some insulin, but if your glucose doesn't start rising as Loop expects, it revises the recommended bolus.
+### Carbs with No Bolus
+
+If you enter carbs and select `Save without bolusing`, you have COB without associated IOB. In that case, Loop predicts your glucose will start rising and updates the recommended bolus, which includes consideration of your [`Glucose Safety Limit`](../../loop-3/therapy-settings.md#glucose-safety-limit), [`Correction Range`](../../loop-3/therapy-settings.md#correction-range) and [`Maximum Bolus`](../../loop-3/therapy-settings.md#maximum-bolus) . If that recommended bolus is positive, Loop might deliver some part of that bolus automatically - the exact percentage and timing of that delivery depends on your [`Dosing Strategy`](../../loop-3/settings.md#dosing-strategy). At each loop cycle (new glucose reading), Loop updates the prediction and calculates a new recommended bolus. When you enter carbs without bolusing, Loop may start delivering some insulin, but if your glucose doesn't start rising as Loop expects, it revises the recommended bolus with each new glucose value.
+
+### When does Automatic Dosing Happen
+
+Automatic dosing only happens when <code>Closed Loop</code> is enabled in the settings screen.
+
+Loop generates a glucose prediction over the next 6 hours (the duration of insulin action), which is why the predicted glucose plot is included on the bolus screen. Loop considers glucose prediction with respect to your scheduled <code>Correction Range</code> over the full DIA, weighting closer predictions more than later predictions, when calculating [Recommended Bolus](../algorithm/bolus.md).
+
+It is actually easier to answer when Loop will **not** automatically increase insulin delivery.
+
+In the situations listed below, the prediction at the end of the DIA can be significantly higher than your <code>Correction Range</code> but no automatic increase in insulin delivery will occur:
+
+* If at any time in the next 3 hours, Loop predicts glucose below <code>Glucose Safety Limit</code>, <code>Temp Basal</code> is immediately set to 0.0 U/hr and recommended bolus is set 0 U
+* If the prediction dips below the low-end of your <code>Correction Range</code>, there is no **automatic** increase over scheduled basal
+* If the current IOB is two times the <code>Maximum Bolus</code> setting, there is no **automatic** increase over scheduled basal
 
-!!! tip "When does Loop start dosing?"
-    The glucose prediction is for the next 6 hours (the duration of insulin action), which is why the predicted glucose plot is included on the bolus screen. Loop considers glucose prediction with respect to your scheduled `Correction Range` over the full DIA, weighting closer predictions more than later predictions, when calculating [Recommended Bolus](../algorithm/bolus.md).
-
-    It is actually easier to answer when Loop will **not** automatically increase insulin delivery:
-
-    * If at any time in the next 3 hours, Loop predicts glucose below `Glucose Safety Limit`, Temp Basal is immediately set to 0.0 U/hr and recommended bolus is set 0 U
-    * If the eventual glucose (at the end of 6 hours) is greater than your `Correction Range` but the prediction dips below the low-end of your `Correction Range`, there is no automatic delivery
-        * The recommended bolus can be positive, which you see if you tap on bolus icon manually
+Even in cases where Loop does not automatically increase insulin delivery, the recommended bolus might be positive, which you see if you tap on the bolus icon manually.