Merge pull request #930 from Kdisimone/patch-25

Dev branch updates

docs/docs/Build Your Rig/OpenAPS-install.md

@@ -41,36 +41,102 @@ If anything fails during the installation, it may end early before it asks you t
 * (if you're using a Carelink, you will NOT be using mmeowlink)
 * how you are getting CGM data.  The options are `g4` (default), `g4-raw`, `g5`, `mdt`, and `xdrip`.  Note:  OpenAPS also attempts to get BG data from your Nightscout.  OpenAPS will always use the most recent BG data regardless of the source.
 * Nightscout URL and API secret
-* whether you want things like Autosensitivity (recommended), and/or Autotune
+* whether you want things like Autosensitivity and/or Autotune
 * whether you want any oref1-related advanced features - NOT RECOMMENDED until you have run oref0 and are familiar with basic OpenAPS looping
 * BT MAC address of your phone, if you want to pair for BT tethering to personal hotspot
-* After the setup script builds your myopenaps, it will ask if you want to schedule a cron (in other words, automate and turn on your loop).  Usually you'll want to answer `y` - and also then press `enter` to reboot after the cron is installed.
+* After the setup script builds your myopenaps, it will ask if you want to schedule a cron (in other words, automate and turn on your loop) and remove any existing cron.  You'll want to answer `y` to both - and also then press `enter` to reboot after the cron is installed.
+
+NOTE: screenshot below is for the dev branch build.  Your master installation may appear differently until dev branch is merged.  Screenshot is uploaded now simply in preparation for the merge.
+![Oref1 setup script](../Images/build-your-rig/sample-setup.png)
 
 #### Log in again, and change your password
 
 If this is your first build, after it reboots it will prompt you to log back in. Log in as "root" and the password from before (probably edison). It will ask you a second time for the current password (probably edison). However, now it will prompt you to change your password.  You'll want to change it to something personal so your device is secure. Make sure to write down/remember your password; this is what you'll use to log in to your rig moving forward. You'll type it twice.
 
 Once you've successfully changed your password, you'll end back at the command prompt, logged in as root and ready to watch your logs while the system begins to read your pump history, gather glucose records, and begin the calculations of any needed adjustments. So it's time to watch your logs next!
 
-## How to watch your logs - REQUIRED!
+## Watch your Pump-Loop Log - REQUIRED!
 
 THIS IS A REQUIRED MUST-LEARN HOW-TO STEP - DO NOT MOVE ON WITHOUT DOING THIS! This is a key skill for monitoring your OpenAPS setup to "check" or "monitor" or "watch" the logs. 
 
-It's easy: simply type the letter `l` (for logs). (*This is a shortcut for the full command, `tail -F /var/log/openaps/pump-loop.log`*.)
+It's easy: simply type the letter `l` (short for "log", aka the very important pump-loop.log). (*This is a shortcut for the full command, `tail -F /var/log/openaps/pump-loop.log`*.)
+
+If this is your first loop build, you are probably (1) going to underestimate how long it takes for the first loop to successfully run and (2) while underestimating the time, you'll freak out over the messages you see in the pump-loop logs.  Let's go over what are NOT errors:
+
+![First loop common messages](../Images/build-your-rig/first-loop.png)
+
+When your loop very first starts, if you are quick enough to get into the logs before the first BG is read, you will likely see: 
+```
+Waiting up to 4 minutes for new BG: jq: monitor/glucose.json: No such file or directory
+date: invalid date '@'
+```
+Don't worry...once you get a BG reading in, that error will go away.
+
+The next not-error you may see:
+```
+ls: cannot access monitor/pump_loop_completed: No such file or directory
+```
+Don't worry about that one either.  It's only going to show because there hasn't been a completely loop yet.  Once a loop completes, that file gets created and the "error" message will stop.
+
+Next frequently confused non-error:
+```
+Waiting for silence: Radio ok. Listening.....No pump comms detected from other rigs
+```
+Well, hey that's actually a good message.  It's saying "I don't hear any interruptions from other rigs, so I won't be needing to wait my turn to talk to the pump."  That message will continue to show even when your loop is successfully running.
+
+As the pump loop continues:
+```
+Refreshed jq: settings/pumphistory-25h-zoned.json: No such file or directory
+```
+That message will clear out once the pump history has successfully been read.
+
+Or how about the fact that autotune hasn't run yet, but you enabled it during setup:
+```
+Old settings refresh Could not parse autotune_data
+```
+Autotune only runs at 12:05am every evening.  So, unless you're building your rig at midnight, you'll probably have to wait overnight for that error message to clear out.  Not a big deal.  You can still loop while that message is showing.  Additionally, you'll have to wait until Autotune runs before SMBs can be enacted (SMBs won't enact unless an Autotune directory exists).
+
+And then you may have an issue about the time on your pump not matching your rig's time:
+```
+Pump clock is more than 1m off: attempting to reset it
+Waiting for ntpd to synchronize....No!
+ntpd did not synchronize.
+```
+This synchronization may fail a few times before it actually succeeds...be patient.  There's a script called oref0-set-device-clocks that will eventually (assuming you have internet connection) use the internet to sync the rig and pump's times automatically when they are more than 1 minute different.  (If you don't have internet connection, you may need to do that yourself on the pump manually.)
+
+How about these daunting messages:
+```
+Optional feature meal assist disabled: not enough glucose data to caluclate carb absorption; found: 4
+
+and
+
+carbsReq: NaN CI Duration: NaN hours and ACI Duration: NaN hours
+
+and
+
+"carbs":0, "reason": "not enough glucose data to calculate carb absorption"
+```
+Advanced meal assist requires at least 36 BG readings before it can begin to calculate its necessary data. So after about three hours of looping these messages will clear out.  You can watch the count-up of "found" BG readings and know when you are getting close.  
+
+Finally, you should eventually see colorful indications of successful looping, with a message saying "Starting with supermicrobolus pump-loop" (or simply pump-loop if you don't have SMBs enabled) and ending with "Completed supermicrobolus pump-loop"
+
+![Successful pump-loop](../Images/build-your-rig/loop-success.png)
+
+If after 20 minutes, you still have some errors showing, it may be time to head over to the Troubleshooting (TBD...which link(s) to add here) docs to figure out where your problem is.
 
-Done watching the logs? Type control-C to exit the pump-loop log.
+**Done watching the logs? Type control-C to exit the pump-loop log.**
 
-This will work anytime, anywhere when you log into your rig and is a necessary step for troubleshooting in the future. Do not move forward without having done this step. 
+Checking your pump-loop.log is a great place to start anytime you are having looping failures.  Your error may not be in the pump-loop, but the majority of the time, you'll get a good head start on the issue by looking at the logs first. So, develop a good habit of checking the pump-loop log to get to know what a normal log looks like so that when a real error appears, you can easily see it as out of place and needing to be addressed.  Additionally, knowing how to access your pump-loop log is important if you come to Gitter or Facebook looking for troubleshooting help...one of the first questions will usually be "what does your pump-loop log look like?"
 
-Also, there are several loop logs contained within your OpenAPS setup...not just a pump-loop.  For example, there are also logs for the following operations in your rig:
+Note: The pump-loop log is not the only log your rig generates.  There are also several other loop logs contained within your OpenAPS setup such as:
 
-* Autosens adjustments log: `tail -F /var/log/openaps/autosens-loop.log`
+* Autosens log: `tail -F /var/log/openaps/autosens-loop.log`
 
 * Nightscout log: `tail -F /var/log/openaps/ns-loop.log`
 
-* oref0-online or wifi connection log: `tail -F /var/log/openaps/network.log`
+* Network log: `tail -F /var/log/openaps/network.log`
 
-* Autotune log: `tail -F /var/log/openaps/autotune.log`
+* Autotune log: `tail -F /var/log/openaps/autotune.log` (remember Autotune only runs at midnight, so there's not much action in that log)
 
 (Normal docs:) Please see [Phase 1 Papertrail](http://openaps.readthedocs.io/en/latest/docs/walkthrough/phase-1/papertrail.html) for an easy way to track all your logs in one easy setup.  Papertrail will even allow you to remotely track your logs when you are not logged into your rig.  Setting up Papertrail and watching your logs will dramatically help you understand your rig and help troubleshoot if you run into problems.
 

docs/docs/Build Your Rig/x12-users.md

@@ -1,6 +1,6 @@
 # 512 and 712 Pump users
 
-If you have one of the x12 model pumps, you'll need to complete some extra setup steps before your loop will be successful. Note there are TWO major steps, of creating the files and then adjusting aliases.
+If you have one of the x12 model pumps, you can still successfully use OpenAPS.  You'll need to complete some extra setup steps before your loop will be successful, however. There are TWO major steps; (1) creating the files and (2) adjusting aliases.  x12 users will have to be aware that the files will need to be manually updated anytime the pump user wants to change basal rate schedules, ISFs, or other pump settings.  Additionally, SMB will not be enabled for x12 pumps unless/until someone with an x12 is willing to test it for safety and compatibility.
 
 ## Add pump files manually
 
@@ -178,6 +178,6 @@ The last steps are to edit the standard openaps aliases so they don't call for n
   openaps alias add gather '! bash -c "(openaps monitor-pump || openaps monitor-pump) 2>/dev/null >/dev/null && echo refreshed    pumphistory || (echo unable to refresh pumphistory; exit 1) 2>/dev/null"'
 ```
 
-## Adjust files
+## Updating your pump settings
 
 If you need to make changes to the settings contained in your pump, specifically those covered by the three files you've created (basal rates, bg-targets, max temp basal rate, or insulin duration), then you will need to edit the files and update their contents in the settings directory.  For example, if you change your basal schedule or rates in the pump...simply editing them in the pump manually will not be enough to let OpenAPS know the basal profile has been altered.  You'll need to login to the rig, access the files and update the information manually in the files.  You can make the adjustments to the file(s) you created in the raw-pump subdirectory by using `cd ~/myopenaps/raw-pump`, then the same nano command(s), and then using the same file copy command to push the edited files into the settings directory.

docs/docs/Customize-Iterate/autosens.md

@@ -1,13 +1,13 @@
 # Auto-sensitivity mode (Autosens)
 
 
-Wouldn't it be great if the system knew when you were running sensitive or resistant? That's what we thought, so we created "auto-sensitivity mode". If you explicitly configure this additional feature (again by enabling it through advanced features in setup script), it will allow the system to analyze historical data on the go and make adjustments if it recognizes that you are reacting more sensitively (or conversely, more resistant) to insulin than usual. It will then make temporary adjustments to the basal, ISF, and targets used for calculating temp basals, in order to keep BG closer to your configured target.
-
-When you watch your loop run in the logs and sensitivity changes is going to be detected, you might see something like this:
-
-`-+>>>>>>>>>>>>+++->->+++>++>>+>>>>>>>>++-+>>>>>>>-+++-+--+>>>>>>>>>>>>>>>>>>>>>>>>>++-++++++--++>>>++>>++-++->++-+++++++>+>>>>>>>>>>>>>>>>>++-+-+-+--++-+--+++>>>>>>++---++----+---++-+++++>>>++------>>>++---->>+++++--+++-++++++++--+--+------++++++++++>>>>++--+->>>>>>>>>>++++-+-+---++++ 34% of non-meal deviations negative (target 45%-50%)\
-Excess insulin resistance detected: ISF adjusted from 100 to 73.52941176470588`
+Wouldn't it be great if the system knew when you were running sensitive or resistant? That's what we thought, so we created "auto-sensitivity mode". If you explicitly configure this additional feature (again by enabling it through features in setup script), it will allow the system to analyze historical data on-the-go and make adjustments if it recognizes that you are reacting more sensitively (or conversely, more resistant) to insulin than usual. Autosens will then make temporary adjustments to the basal, ISF, and targets used for calculating temp basals, in order to keep BG closer to your configured target.
 
+When you watch your autosens log (shortcut command is `autosens-looplog`) and sensitivity changes is going to be detected, you might see something like this:
+******************
+-+>>>>>>>>>>>>+++->->+++>++>>+>>>>>>>>++-+>>>>>>>-+++-+--+>>>>>>>>>>>>>>>>>>>>>>>>>++-++++++--++>>>++>>++-++->++-+++++++>+>>>>>>>>>>>>>>>>>++-+-+-+--++-+--+++>>>>>>++---++----+---++-+++++>>>++------>>>++---->>+++++--+++-++++++++--+--+------++++++++++>>>>++--+->>>>>>>>>>++++-+-+---++++ 34% of non-meal deviations negative (target 45%-50%)\
+Excess insulin resistance detected: ISF adjusted from 100 to 73.52941176470588
+******************
 Here's what each symbol above means:
 
  ">" : deviation from BGI was high enough that we assume carbs were being absorbed, and disregard it for autosens purposes
@@ -18,11 +18,33 @@ Here's what each symbol above means:
 
  "=" : BGI is doing what we expect
 
+### Autosens adjustments
+
+If you have papertrail setup (or are watching similarly through your rig itself), you can get an idea of how often, how much, and what autosens is adjusting.  For example, here's a screen capture using "adjust" as the search filter for one of my rigs.
+
+![Autosens adjustments logged in papertrail](../Images/customize-iterate/autosens-adjust.png)
+
+As you can see, there are several types of adjustments that have occured during the day.  
+* In the morning, autosens was detecting some excess insulin sensitivity...so basals, targets, and ISF were adjusted down (by multiplier of 0.94).  
+* Later in the day (the blue boxed section), another adjustment was made to her BG targets because of a persistent high.  While not an adjustment by autosens itself, this is similar and can be set in preferences.json by setting the "adv_target_adjustments" to true.  Basically this preference will automatically lower BG targets (to as low as "eating soon" mode target of 80 mg/dl) for persistent high BGs.  
+* Later in the day, a couple brief periods of insulin sensitivity were short-lived.
+* Finally at night, we had a low-treatment for a BG.  We use an IFTTT button to enter our low treatments and at the same time, the IFTTT sets up a temp target of 110 mg/dl for 60 minutes to make sure the loop doesn't want to correct much on the recovery.  That temp target is being respected by autosens and basals and targets are not being adjusted (even though autosens may like to).  
+
 ### Notes about autosensitivity:
 
 * "Autosens" works by reviewing the last 24 hours of data (so it's a rolling calculation with a moving window of 24 hours) and assessing deviations to determine if you are more sensitive or resistant than expected. If a pattern of such deviations is detected, it will calculate the adjustment that would've been required to bring deviations back to normal.
 * Autosens does NOT take into account meal/carb deviations; it only is able to assess the impact of insulin, and thus will adjust ISF, basals, and targets to help compensate for changes in sensitivity.
-* Most users will notice the changed ISF numbers in their OpenAPS pill, along with changed targets. Note that a temp target will override the autosens-adjusted target. If you do not want autosens to adjust targets, that can be turned off via a setting in preferences.json
-* The reason for autosens automatically adjusting targets is because the other adjustments it makes can't be fully applied without creating a feedback loop, so automatically adjusting the target it thinks it's shooting for lets autosens get BG closer to your actual target most of the time. When autosens needs to adjust basal and ISF, it can very straightforwardly use that for adjusting the temp basal it's about to set, by assuming a higher or low neutral temp basal to start from, and by calculating a bigger or smaller expected impact of current IOB. What it can't do is calculate IOB in a way that reflects the adjusted basals and ISF, because doing so would change the autosens result, which would require recalculating IOB again, which would further change the result, in an unpredictable feedback loop. So instead, we simply acknowledge that the IOB calculation doesn't reflect sensitivity or resistance, and instead adjust the target to compensate. 
-* Autosens is limited by the safety multipliers in preferences.json. We do not recommend widening these multipliers; but an easy way to turn "off" autosens after you've enabled it is so adjust the safety multipliers to 1. However, note that this will also disable autotune adjustments if you are running autotune. 
-}
+* Most users will notice the changed ISF numbers in their OpenAPS pill, along with changed targets. Note that a temp target will override the autosens-adjusted target. If you do not want autosens to adjust targets, that can be turned off by editing preferences.json (shortcut command `edit-pref`) and setting the "autosens_adjust_targets" to false.
+* The reason for autosens automatically adjusting targets is because the other adjustments it makes can't be fully applied without creating a feedback loop, so automatically adjusting the target it thinks it's shooting for lets autosens get BG closer to your actual target most of the time. When autosens needs to adjust basal and ISF, it can very straightforwardly use that for adjusting the temp basal it's about to set, by assuming a higher or low neutral temp basal to start from, and by calculating a bigger or smaller expected impact of current IOB.  What it can't do is calculate IOB in a way that reflects the adjusted basals and ISF, because doing so would change the autosens result, which would require recalculating IOB again, which would further change the result, in an unpredictable feedback loop. So instead, we simply acknowledge that the IOB calculation doesn't reflect sensitivity or resistance, and instead adjust the target to compensate. 
+* Autosens is limited by the safety multipliers in preferences.json. The defaults are:
+```
+"autosens_max": 1.2, <----multiplier for adjustments during insulin resistance
+"autosens_min": 0.7, <----multiplier for adjustments during insulin sensitivity
+```
+We do not recommend widening these multipliers; but an easy way to turn "off" autosens after you've enabled it is so adjust the safety multipliers to 1. However, note that this will also disable autotune adjustments if you are running autotune. 
+
+### Autosens vs Autotune
+
+Autosens will make adjustments to whatever basal, ISF, and target profiles are currently set for the loop.  If autotune is not enabled, that means autosens will be making on-the-go adjustments based on the settings read from your pump.  If autotune is enabled, that means autosens will be using the autotuned-profile as the basis for making adjustments.
+
+Since SMBs require a minimum basal rate of 0.3 U/hr, it is possible that your auto-adjusted basal rate used by the loop may end up being lower than what is programmed in your pump.  If you expect to see SMBs enacting, but your pump basal rate is very close to 0.3 U/hr...adjustments by autosens and/or autotune may change your basal rate to be less than 0.3 U/hr.