Wip 2016 spring

README.md

@@ -11,6 +11,8 @@ Welcome to the [openaps](https://github.com/openaps/) documentation!
 
 openaps is part of a set of tools to support a self-driven Do-It-Yourself (DIY) implementation of an artificial pancreas based on the [OpenAPS reference design](http://openaps.org/open-artificial-pancreas-system-openaps-reference-design/). 
 
+Here are two visuals to show you what the physical hardware components of an OpenAPS setup look like - [version A](./docs/IMG_1112.jpg) is without labels; [version B](docs/Images/piSetup.jpg) contains labels to describe the parts.
+
 By proceeding to use these tools or any piece within, you agree to the copyright (see LICENSE.txt for more information) and release any contributors from liability. 
 
 The tools may be categorized as: 1)  **monitor** collecting data and

docs/docs/walkthrough/phase-2/Using-oref0-tools.md

@@ -1,4 +1,4 @@
-#Using oref0 Tools
+# Using oref0 Tools
 
 ## Add the oref0 Virtual Devices
 In Phase 1, you added two physical medical devices to openaps—your pump and your cgm. This was done using the command `$ openaps device add` and then specifying the device name, type, and parameters. OpenAPS tools to gather system profile parameters such as pump settings, calculate the current insulin on board (IOB), and determine if the pump temp basal should be updated or not, are contained in the OpenAPS reference system oref0. Since there is no physical oref0 device, you are essentially adding it to the openaps environment as a virtual device or plugin.

docs/docs/walkthrough/phase-2/loop-and-retry-logic.md

@@ -3,3 +3,27 @@
 To pull all of oref0 together, you could create a "loop" alias that looks something like `openaps alias add loop '! bash -c "openaps monitor-cgm 2>/dev/null && ( openaps preflight && openaps gather && openaps enact) || echo No CGM data."'`. If you want to also add some retry logic to try again if something failed, you could then do something like `openaps alias add retry-loop '! bash -c "openaps preflight && until( ! mm-stick warmup || openaps loop); do sleep 5; done"'`.
 
 Once all that is working and tested, you will have a command that can be run manually or on a schedule to collect data from the pump and cgm, calculate IOB and a temp basal suggestion, and then enact that on the pump. 
+
+## A barebones loop
+
+- Make sure all dirs that have new files generated are cleaned out
+- Get CGM data
+- Get pump data
+- Get Basal Suggestions
+- Check if you need to put suggestions in place and if you do, then run them
+
+## A more advanced loop
+**Pull pump settings once an hour**
+
+**Log everything!**
+- Make sure only one loop runs at a time
+- Verify you can talk to the pump, you can't reset the USB carelink connection
+- Make sure all dirs that have new files generated are cleaned out
+- Get CGM data
+- Get pump data
+- Get Basal Suggestions
+- Check if you need to put suggestions in place and if you do, then run them
+	- Pull pump settings again since you just modified the pump
+	- get latest ns treatment time
+	- format latest nightscout treatments
+	- upload recent treatments

reference-design.md

@@ -1,6 +1,6 @@
-(Last updated Oct. 8, 2015)
+(Last updated Jan 27, 2016)
 
-#OpenAPS Reference Design
+# OpenAPS Reference Design
 
 The Open Artificial Pancreas System (OpenAPS) is a simplified Artificial Pancreas System (APS) designed to automatically adjust an insulin pump’s basal insulin delivery to keep blood glucose (BG) in a safe range overnight and between meals. It does this by communicating with an insulin pump to obtain details of all recent insulin dosing (basal and boluses), by communicating with a Continuous Glucose Monitor (CGM) to obtain current and recent BG estimates, and by issuing commands to the insulin pump to adjust temporary basal rates as needed.
 
@@ -14,7 +14,7 @@ By taking this approach, we believe that OpenAPS can be demonstrated to be both
 
 OpenAPS is designed to work with interoperable insulin pumps and CGMs from any manufacturer. Initial prototype implementations use Medtronic insulin pumps with either Dexcom or Medtronic CGMs, but the same design will also work with insulin pumps from any manufacturer who provides a way to issue temporary basal commands to the pump, and with any CGMs whose data can be retrieved in real time. If an OpenAPS reference design and implementation can one day be FDA approved, they will also be made available to any medical device manufacturer who wishes to create their own implementation with their own devices and/or the devices of any of their partners.
 
-##Design Constraints for OpenAPS
+## Design Constraints for OpenAPS
 
 1. In order to accomplish these goals, the first design constraint of OpenAPS is that OpenAPS cannot issue insulin boluses. This is a key safety feature, because insulin pumps, while they have limits on the maximum size of bolus they will administer, have effectively no limit on how frequently boluses may be administered. (Some pumps implement the maximum bolus size as the maximum amount of insulin that can be bolused over a certain period of time, but as the maximum bolus amount is generally set very high by default, this is insufficient to prevent severe hypoglycemia if the full bolus amount is administered inappropriately.) As a result, any system that is capable of issuing bolus commands would be capable of administering, if it erroneously issued bolus commands repeatedly, a potentially lethal quantity of insulin. To completely avoid this issue, OpenAPS instead relies solely on temporary basal commands. Repeatedly reissuing the same temporary basal command does not change the rate at which the pump infuses insulin; it simply extends the temporary basal rate slightly. In addition, insulin pumps are configured with a maximum allowed temporary basal rate, and will simply ignore any commands that instruct the pump to use a higher rate than allowed.
 2. This maximum allowed temporary basal rate is the second design constraint: OpenAPS is designed to be incapable of administering insulin any faster than can be easily counteracted with fast-acting carbohydrates. This means that OpenAPS cannot be used to substitute for mealtime insulin boluses, but more importantly it means that, even if OpenAPS were to malfunction in the worst possible way, the patient can completely prevent any adverse outcome by simply consuming additional carbs as needed, as they already have to do with standard diabetes treatment every day or two for any number of other reasons.
@@ -25,8 +25,8 @@ OpenAPS is designed to work with interoperable insulin pumps and CGMs from any m
 7. OpenAPS generally defers to the patient when they choose to issue their own boluses, either for corrections or for meals. In such a situation, OpenAPS makes an estimate of how long the (bolus-wizard inputted or assumed) meal is expected to take to digest (or how long the BG excursion is expected to continue, if it’s something other than a meal). It then continues to monitor BG, but avoids issuing any temporary basal rates until that is clearly required again.
 8. OpenAPS is designed to operate completely autonomously, without requiring any interaction from the patient, and to upload CGM and pump data in real time whenever Internet connectivity is available. The patient simply continues to use the pump per their usual therapy, and OpenAPS simply works in the background to temporarily override the underlying basal rates so that the patient rarely has to take corrective action for hyper- or hypoglycemia. The uploaded data can be made available to the patient and their caregivers / loved ones, allowing them to keep an eye on their BGs, and make sure OpenAPS is continuing to work properly, at all times. As demonstrated by the >15,000 members of the CGM in the Cloud Facebook group and the >3,000 active users of Nightscout, this kind of remote visibility for BGs is life-changing for people with type 1 diabetes, and will be even more so when coupled with OpenAPS technology. This data upload also allows for the development of real-time and retrospective reporting tools to help the clinical care team optimize the patient’s long-term diabetes care, which has the promise to revolutionize the clinical treatment of type 1 diabetes.
 
-##OpenAPS Design Details
-###Hardware
+## OpenAPS Design Details
+### Hardware
 
 OpenAPS consists of:
 
@@ -35,16 +35,16 @@ OpenAPS consists of:
     a wireless connection capable of reading from and issuing temporary basal commands to an insulin pump, and
     (Optional) a wireless Internet connection (i.e. cellular data or Wi-Fi) capable of uploading BG, pump, and operational data.
 
-###Medical device communication
+### Medical device communication
 
 OpenAPS periodically (i.e. every 5 minutes) reads new data from the CGM as it becomes available. In order to take action, OpenAPS needs at least a current CGM reading (received within the last 10-15 minutes), and a previous CGM reading (5-10 minutes before that).
 
 OpenAPS periodically (every few minutes) queries the insulin pump for current settings and recent activity, such as current (scheduled or temporary) and maximum basal rates, recent boluses, IOB (if available), ISF, DIA, IC ratio, BG target/range, etc. (If appropriate, settings such as max basal rate, ISF, DIA, IC ratio, BG targets, etc. can be queried less frequently.) If that query is successful, OpenAPS updates its bolus wizard calculations (detailed below) and determines whether any action is required (canceling or issuing a temporary basal).
 
 If action is required, OpenAPS issues the appropriate temporary basal command to the pump, confirms that it was received and acknowledged by the pump, and then performs another query for recent activity to make sure the new temporary basal successfully took effect.
 
-###Algorithms
-####Basic overnight operation
+### Algorithms
+#### Basic overnight operation
 
 OpenAPS uses the pump’s bolus and temporary basal history, combined with the pump’s DIA and published IOB curves, to calculate current net IOB. (Currently, pumps only include boluses when calculating IOB: a more correct and useful IOB calculation includes the net impact of temporary basals vs. normally scheduled basal rates.) If no boluses have been administered recently (see “Bolus Snooze” below), OpenAPS can then use the current CGM glucose reading to calculate an eventual BG estimate using simple bolus calculator math: current BG – (ISF * IOB) = eventual BG.
 
@@ -68,23 +68,33 @@ The maximum temp basal rate is set on the pump, but for safety purposes OpenAPS
 
 This helps ensure that the patient will always be able to recover from any excessive insulin delivered by OpenAPS simply by eating fast-acting carbs.
 
-####Adjusting for unexpected BG deviation
+#### Adjusting for unexpected BG deviation
 
 The algorithm above is sufficient for a simple and safe OpenAPS implementation, and has been successfully tested by several users over several months of combined use. However, in situations where BG is rising or falling unexpectedly, or remaining stubbornly high, we discovered that it is also useful to take into account how much the Blood Glucose rise/fall rate is deviating from what would be expected based on insulin activity. This allows more advanced OpenAPS implementations to respond more quickly when BG starts to rise or fall more than expected, and allows it to continue high temp basals when BG is stubbornly high and mostly flat (falling far less than expected).
 
-To calculate this deviation, OpenAPS first calculates a term we call “BG Impact” or BGI, which is simply the current insulin activity (first derivative of IOB) * insulin sensitivity. When expressed in units of mg/dL/5m, this represents the degree to which BG “should” be rising or falling, and can be directly compared to the delta between the current and last CGM reading, or an average delta over the last 15m or so. To calculate the deviation, OpenAPS does exactly this comparison, between the 15m average delta in CGM readings and the predicted BGI. It then applies that deviation as an adjustment to the eventual BG prediction. This is based on the simple assumption that if BG is rising or falling more than expected over the last 15 minutes, that trend is likely to continue over the next 15-30 minutes, and the magnitude of the projected deviation is approximately equal to what was seen over the last 15 minutes. In future OpenAPS implementations it may be possible to come up with better predictive algorithms of this sort, but this simple algorithm has worked quite well over many months of real-life use so far.
+To calculate this deviation, OpenAPS first calculates a term we call “BG Impact” or BGI. BGI is simply the expected effect of the net IOB, calculated by multiplying the current insulin activity times the ISF (see example below). the current insulin activity (first derivative of IOB) * insulin sensitivity. When expressed in units of mg/dL/5m, this represents the degree to which BG “should” be rising or falling, and can be directly compared to the delta between the current and last CGM reading, or an average delta over the last 15m or so. To calculate the deviation, OpenAPS does exactly this comparison, between the 15m average delta in CGM readings and the predicted BGI. 
+
+**The following example uses straight linear math for the purposes of simplicity in explanation.  In reality, the AP algorithm assumes that insulin effectiveness starts off flat, over time builds in efficacy, and eventually tapers off in its usefulness. ** 
+Example: take the scenario of correcting a BG of 200 (where ISF is 1u per 100 mg/dL, DIA is 4 hours, and target BG is 100).
+1. 1u insulin is given to bring BG to 100
+2. There are 48 5-minute segments in 4 hours
+3. 1u/48 = .021 (This is the current insulin activity, or how much net IOB is 'used' in a 5-minute period)
+4. Thus we expect the BG to drop -2.1 mg/dL every 5 minutes (.021 * 100 mg/dL), so the BGI is -2.1 mg/dL/5m
+5. Multiplying this by the ISF (.021 * 100 mg/dL), gives us the BGI of -2.1 mg/dL/5m (the expected BG decrease over 5 minutes)
+
+OpenAPS then applies that deviation as an adjustment to the eventual BG prediction. This is based on the simple assumption that if BG is rising or falling more than expected over the last 15 minutes, that trend is likely to continue over the next 15-30 minutes, and the magnitude of the projected deviation is approximately equal to what was seen over the last 15 minutes. In future OpenAPS implementations it may be possible to come up with better predictive algorithms of this sort, but this simple algorithm has worked quite well over many months of real-life use so far.
 
 In addition to adjusting the eventual BG predictions, the BGI calculation above is also used in advanced OpenAPS implementations to allow a high temp basal to continue running if BG is dropping slower than expected (less than ½ of BGI), and similarly to set low temp basals if BG is rising slower than expected or falling more quickly than expected.
 
-####Bolus snooze
+#### Bolus snooze
 
 By adjusting for BG deviations as described above, advanced OpenAPS implementations can avoid issuing low temp basals when BG is rising or remaining high after a meal, even without being informed about the fact that a meal has been consumed, or being provided a carbohydrate count. However, it is also useful for OpenAPS to avoid issuing low temp basals that counteract a meal bolus or prebolus when BG has not yet started to rise. To accomplish this, advanced OpenAPS implementations apply a “bolus snooze”, which causes OpenAPS to effectively go “hands off” as soon as a user executes a bolus, and only take action again if/when BG drops below the low glucose suspend threshold, rises more than expected or fails to come down after the mealtime rise, or starts to drop faster than expected. As a result, users can simply bolus appropriately for their meal, and then OpenAPS will wait and take over basal adjustment as necessary to bring BGs back into range after any mealtime excursions.
 
 The bolus snooze is currently implemented in advanced OpenAPS implementations by tracking bolus IOB (with an accelerated decay based on half the user’s normal DIA) separately from net IOB, and re-adding the BG impact of the bolus IOB (plus a small multiple) when deciding whether to set a low temporary basal. If the resulting “snooze BG” term is higher than the BG target, then OpenAPS will not set a low temporary basal, even if the eventual BG (based solely on net IOB) is much lower than target. This results in OpenAPS effectively widening the target BG range immediately after a bolus, and then gradually narrowing it over the next hour or two and gradually returning to normal behavior.
 
 As most insulin pumps do not calculate net IOB, and use bolus-only IOB in the bolus calculator, it is necessary to take an additional precaution to help prevent the patient from manually administering an excessive bolus by following the bolus calculator. This is accomplished through a “maximum IOB” setting, which instructs OpenAPS to never set high temp basals that would allow the net IOB to exceed the bolus IOB by more than a user-configured amount. Unless configured otherwise by the user setting up OpenAPS implementation, this maximum IOB defaults to zero, which means that OpenAPS will act only as a predictive low glucose suspend system, and will high-temp after BG starts to recover if IOB is negative, but will not issue high temp basals if BG is high.
 
-###Discussion
+### Discussion
 
 As a result of the principles, design constraints, and overall approach taken in designing and implementing OpenAPS, we believe that OpenAPS and similar designs represent the safest, fastest way to make Artificial Pancreas technology available to all type 1 diabetes patients, and do so at the most affordable price point possible.