Revised BGI explanation, NS upload info added, pseudo code loop examp…

…les, and pictures of the OpenAPS and NS data getting uploaded
bewest · bewest · Dec 30, 2015 · Jan 19, 2016 · Jan 26, 2016 · Jan 28, 2016
commit 29737134d732cb74477b1859900b53946d069abf
diff --git a/README.md b/README.md
@@ -16,6 +16,9 @@ The tools may be categorized as:
 
 You may also find [this flowchart](./OpenAPS_phase_visualization_Nov152015.png) helpful to further break down the areas of monitor, predict, and control into various stages of general setup; logging, cleaning, and analyzing data; building a manual system; automating your work; and iterating and improving.
 
+## What does the hardware setup look like
+![Basal Profile](docs/Images/piSetup.jpg =250x)
+
 ## A Note on DIY and the "Open" Part of OpenAPS
 
 This is a set of development tools to support a self-driven DIY implementation. Any person choosing to use these tools is solely responsible for testing and implementing these tools independently or together as a system.  

diff --git a/docs/Build-manual-system/Using-oref0-tools.md b/docs/Build-manual-system/Using-oref0-tools.md
@@ -246,3 +246,50 @@ You may experiment using `$ openaps preflight` under different conditions, e.g.
 
 At this point you are in position to put all the required reports and actions into a single alias. 
 
+
+## Upload data into Nightscout
+
+### Setting up your Nightscout website to show basal info
+
+This assumes you have a [Nightscout website](http://www.nightscout.info/) to help visualize and alert a T1D's blood sugar levels.  If you aren't running a Nightscout website, stop what you are doing and set one up!
+
+To be able to show basal information, your NS website must be running version .0.8.3 or higher.
+![How to Check NS Version](../Images/ns_version.png)
+
+You need to then enable a few attributes in your Application Setting for your NS website to be able to see things like basal data.  [This link](http://www.nightscout.info/wiki/labs/interpreting-raw-dexcom-data) shows you how to enable raw data in your application settings.  You will want to do this for the following settings at least:
+
+careportal iob basal profile bwp cage sage openaps rawbg
+![NS settings](../Images/ns_app_settings.png)
+
+
+Once you have restarted your NS website with these new values, you can go here:
+![Basal Profile](../Images/basal_profile.png)
+
+And turn on your basal profile and choose how you want to render it and be sure to save your info.
+
+You then need to enter your basal profile for the day by going to the Profile Editor and updating the information on that page so it looks like this:
+![Basal Profile](../Images/profile_editor.png)
+
+You now have a NightScout website that is able to show basal adjustments!  Congrats!  
+
+### Upload your pump history into NightScout
+I forget the commands I used to add these aliases but if you open up openaps.ini and find the section for aliases and add these lines underneath (change the items in [brackets]), you will have all the commands you need to be able to format and upload your pump history into your NS website:
+````
+latest-ns-treatment-time = ! bash -c "nightscout latest-openaps-treatment https://[yourwebsite].azurewebsites.net | json created_at"
+format-latest-nightscout-treatments = ! bash -c "nightscout cull-latest-openaps-treatments monitor/pumphistory-zoned.json settings/model.json $(openaps latest-ns-treatment-time) > upload/latest-treatments.json"
+upload-recent-treatments = ! bash -c "openaps format-latest-nightscout-treatments && test $(json -f upload/latest-treatments.json -a created_at eventType | wc -l ) -gt 0 && (ns-upload https://[yourwebsite].azurewebsites.net [your-api-password] treatments.json upload/latest-treatments.json ) || echo \"No recent treatments to upload\""
+````
+
+Order of operations is important!
+
+After you enact a suggestion / temp basal, you will want to query the pump again for pump history as you just made a change to pump data.  Once you have done this, you can run the following commands to have your data formatted and then upload into your Nightscout website.  This is roughly what your commands should look like inside your loop:
+
+````
+openaps monitor-pump
+openaps latest-ns-treatment-time
+openaps format-latest-nightscout-treatments
+openaps upload-recent-treatments
+
+````
+
+I've noticed it can take a couple of minutes after a successful load of data in NS for the data to show up in the interface so be patient!
diff --git a/docs/Build-manual-system/loop-and-retry-logic.md b/docs/Build-manual-system/loop-and-retry-logic.md
@@ -1,5 +1,29 @@
-#Creating a loop and retry logic
+# Creating a loop and retry logic
 
 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 "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
diff --git a/docs/Images/basal_profile.png b/docs/Images/basal_profile.png
diff --git a/docs/Images/nightscout.png b/docs/Images/nightscout.png
diff --git a/docs/Images/ns_app_settings.png b/docs/Images/ns_app_settings.png
diff --git a/docs/Images/ns_version.png b/docs/Images/ns_version.png
diff --git a/docs/Images/piSetup.jpg b/docs/Images/piSetup.jpg
diff --git a/docs/Images/profile_editor.png b/docs/Images/profile_editor.png
diff --git a/docs/piSetup.jpg b/docs/piSetup.jpg
diff --git a/reference-design.md b/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,32 @@ 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. 
+
+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.