Merge pull request #952 from openaps/master

Master back to dev on July 16

docs/docs/Customize-Iterate/autosens.md

@@ -41,7 +41,7 @@ As you can see, there are several types of adjustments that have occured during
 "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. 
+We do not recommend widening these multipliers; but an easy way to turn "off" autosens after you've enabled it is to adjust the safety multipliers to 1. However, note that this will also disable autotune adjustments if you are running autotune. 
 
 ### Autosens vs Autotune
 

docs/docs/Customize-Iterate/index.rst

@@ -13,6 +13,7 @@ Customize-Iterate
    oref1
    offline-looping-and-monitoring
    on-the-go-wifi-adding
+   useful-mobile-apps
    usability-considerations
    update-your-rig
    oref0-runagain

docs/docs/Customize-Iterate/on-the-go-wifi-adding.md

@@ -1,111 +1,33 @@
-# How to add a new wifi network while out and about
+# How to add new wifi network(s)
 
-Since OpenAPS rig needs internet connection, most of the times we would prefer to have the rig on a wifi connection.  Using our iPhones as hotspots can rack up data use and burn iPhone battery pretty quick.  So, let’s say your kid is going to a sleepover at a friend’s house and you’d like to put her rig on the friend’s wifi network.  Unless you bring your laptop with you…you might be stumped how to do that?  Here’s a walkthrough for how to get that done…the setup is a bit long at first, but you can use the resulting connection to do many other things with your rig on-the-go.
+Adding a wifi network is pretty easy once your initial loop has been setup.  Simply enter `edit-wifi` (which is a shortcut command for `nano /etc/wpa_supplicant/wpa_supplicant.conf` and add networks using the template:
 
-1. Get a couple iPhone apps to help us
-2. Hotspot connect the iPhone and rig
-3. Get an IP address for the rig
-4. Set up a connection to the rig on the iPhone
-5. Edit the list of wifi networks on the rig
-
-
-## 1. Get a couple of iPhone apps
-
-On the iPhone, download these two apps:
-
-* Termius – SSH Shell/Console/Terminal 
-* iNet
-
-![Example of apps](../Images/Example_iphone_apps.png)
-
-## 2. Hotspot connect iPhone and rig
-
-You should have already added your iPhone’s hotspot info to the wifi network list previously.  If you have questions about how to do that, see the [Simple Mac setup guide](../phase-0/edison-explorer-board-Mac.md).  
-
-But, as a hint, you can find your iPhone hotspot information under Settings, Personal Hotspot. Your network name and password are listed there.  Use the `vi /etc/wpa_supplicant/wpa_supplicant.conf` command while logged on the rig from a computer.
-
-![Personal hotspot](../Images/personal_hotspot.png)
-
-We’ve made sure your iPhone is in the rig’s network list (technically called a “wpa supplicant list”).  Now get in a place where your rig is not on another network.  In other words, if you are at home…turn off your wifi for a bit by unplugging your router.  Or get in your car and drive a few blocks away.  We need the rig to connect to your iPhone hotspot.  
-
-You can tell your rig is connected to your iPhone when you see a blue bar above the screen.  It will tell you one “1 Connection”…and that is your rig!  Yes.
-
-![Successful hotspotting](../Images/hotspot_running.png)
-
-## 3. Get an IP address for the rig
-
-* Open the iNet app
-
-* Click on the big “NETWORK SCANNER” 
-![Network scanner app](../Images/network_scanner.png)
-
-* Click on the three little bars in the upper right, and then choose “Scan Settings” from the drop down list that will appear.
-
-![Scan settings](../Images/scan_settings.png)
-
-* Edit the Start IP and End IP scan settings to  172.20.10.1 and 172.20.10.20  (devices connected to your iPhone hotspot will be in that range).
-
-* Press the blue/black “Scan” button on the bottom right of the screen (it may be a little hidden because the display gets a little pushed down by the hotspot bar on the top of iPhone).
-
-![Edit start and end IP and pres scan](../Images/edit_network_scanner.png)
-
-* The scan results should show a device labeled “edisonhost” (or whatever name you chose for the rig in the setup process.  If you don’t see it quickly, try rescanning.
-
-* Copy down  or screenshot the IP address listed under the device. (in this example, 172.20.10.10) 
-
-![Successful network scanner screen](../Images/successful_network_scanner.png)
-
-We are all done with the iNet app. 
-
-
-## 4. Set up a connection to the rig on the iPhone
-
-Now we are moving over to the Termius app.  When you first open the app, it will prompt you to add a new host.  Go ahead and click the button to add a new host.  You are going to fill out the following lines:
 ```
-Alias – pick a name that let’s you know this is the rig when it’s hotspotted with your iPhone
-
-Username – click to the left of the little blue man and type “root”
-
-Hostname – Enter the IP address we just got from the iNet app
-
-Password – Enter your rig’s root password (default is “edison” but you likely changed it during setup)
+network={
+    ssid="my network"
+    psk="my wifi password"
+}
 ```
+Save the edits to the file using `control-x`, `y`, and `enter`.
 
-Click “Save” in the upper right corner.
-
-![Termius adding new hosts](../Images/Terminus_add_new_host.png)
-
-Congrats…you should now see the host you just created.  If you click on that host, you’ll see a message that it is connecting and then…
-
-![Termius with hosts showing](../Images/Terminus_with_hosts.png)
-
-## 5. Edit the list of wifi networks on the rig 
-
-You’re IN!  Congrats!  
+Helpful tip:  Add a couple "blank" networks to the file (see screenshot below), so that if you ever need to add new wifi networks while on-the-road, the process will be much faster and easier.  You'll only need to edit the network name and password then...instead of needing to type in the whole string of the template. 
 
-**Warning** The instructions below describe how to edit your rig's network settings, which determine whether your rig can connect to your hotspot.  Just in case you might mess up the config and "step on your own air hose", be sure you have a backup method of connecting to your rig (perhaps using Bluetooth, or your laptop and a USB console connection) or a backup rig available.  Be careful when editing wpa_supplicant.conf to copy the syntax exactly, to avoid having it refuse to load the config at all due to a misplaced quote or curly brace or something.
+![Edit wifi file](../Images/sample-wifi-file.png)
 
-If you are out and about, don't have a backup method of connecting, and this is your only rig, you might want to consider waiting until you get home to change your wpa_supplicant config.
+Some wifi networks may require you to enter a login name and password at an initial screen before allowing access (such as many school wifi networks).  Some users have success in using the following wpa network settings for those types of networks:
 
-If you're ready to proceed, you’ll want to enter :
-
-`vi /etc/wpa_supplicant/wpa_supplicant.conf`
-
-and that will bring up your network list for the rig:
-
-![network list in the rig](../Images/network_list_in_rig.png)
-
-**HINT:**  Turn your iPhone sideways and the keyboard will show some useful options.  Like those arrow keys to navigate with.
-
-**HINT 2:**  you can also use this host portal to run any other commands (not just adding wifi networks).  This host will work anytime your iPhone and rig are hotspotted together.
-
-* Type “i” to enter INSERT mode.
-
-![Insert mode to add new wifi](../Images/add_new_wifi.png)
-
-* Add your new wifi network 
-
-* Press the “esc” key and then type “:wq” to save and quit
-(or “:q!” if you panic and don’t want to save the changes)
+```
+network={
+   scan_ssid=1
+   ssid="network name"
+   password="wifi password"
+   identity="wifi username"
+   key_mgmt=WPA-EAP
+   pairwise=CCMP TKIP
+   group=CCMP TKIP WEP104 WEP40
+   eap=TTLS PEAP TLS
+   priority=1
+}
+```
 
-CONGRATS! You just set up a convenient on-the-go editing tool!
+Other wifi networks require you to accept a terms and conditions (or enter a room number and last name) prior to allowing access.  For example, Starbucks coffee shops and many hotels.  These networks are termed "captive" networks and connecting your rig to captive networks is currently not an option for a standard rig setup.  A device like [Hootoo mobile router](https://www.hootoo.com/network-devices.html) is an excellent tool in these situations.  A Hootoo mobile router will login to the hotel/Starbucks network via an app on your phone, and then the Hootoo "bridge" (non-technical word) the hotel's network for your rig to be able to connect to once you add the network to the rig.

docs/docs/Customize-Iterate/oref1.md

@@ -2,6 +2,8 @@
 
 NOTE OF CAUTION:
 * oref1 is different than oref0, the baseline "traditional" OpenAPS implementation that only uses temporary basal rates.
+* You should have run oref0 (basic OpenAPS looping) for more than two weeks, and be very aware of all the types of situations in which your rig might fail, before you enable oref1-related features.
+* If running more then one rig, you will want to make sure all rigs are running an SMB-aware oref0 version (release 0.5.1 or higher) before enabling SMB on any of them (even if SMB is not enacted on all rigs, all rigs need to know about it).
 
 ## Only run oref1 with the following caveats in mind: 
 
@@ -40,7 +42,7 @@ UAM will be triggered if the preference is toggled on and there is carb activity
 
 * As of July 13, 2017, SMB/UAM are in the master branch of oref0 (oref0 0.5.0). They are under the advanced features menu, and require you to read these docs carefully from top to bottom on this page in order to enable it during the setup script. Afterward, you also need to turn on the relevant settings in preferences.json. You may want to experiment with turning only one of them on at a time so you can closely observe the behavior (via both Nightscout and pump-loop.log) in the enabled situation. In addition to testing oref1 in "normal" situations, pay special attention to how it behaves in more extreme situations, such as with rescue carbs (announced or not), post-meal activity, etc. 
 
-There are multiple preference toggles for SMB/UAM. Check out the [preferences page](http://openaps.readthedocs.io/en/dev/docs/While%20You%20Wait%20For%20Gear/preferences-and-safety-settings.html#advanced-oref1-preferences) for more details on all the settings, but the short version is:
+There are multiple preference toggles for SMB/UAM. Check out the [preferences page](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/preferences-and-safety-settings.html#advanced-oref1-preferences) for more details on all the settings, but the short version is:
 
 ```
  * enableSMB_with_bolus means SMB will be enabled DIA hours after a manual bolus

docs/docs/Customize-Iterate/update-your-rig.md

@@ -10,7 +10,9 @@ However, if it's a brand-new feature that's being tested or is recently added to
 
 1. `cd ~/src/oref0 && git checkout master && git pull && sudo npm install -g oref0`
 
-#### Optional: To get on "dev" branch to test even more recently added new stuff
+*(If you get a message that you need to commit or stash, use command `git stash`*)
+
+##### **Optional: To get on "dev" branch to test even more recently added new stuff**
 
 Or, if the feature you want hasn't been released yet, and you want to test the latest untested development version of `oref0`, run:
 
@@ -19,4 +21,4 @@ Or, if the feature you want hasn't been released yet, and you want to test the l
 
 ## Step 2: Re-run oref0-setup
 
-Now that you've updated your `oref0` version, you can [re-run the oref0-setup script](http://openaps.readthedocs.io/en/latest/docs/walkthrough/phase-2/oref0-setup.html#re-running-the-setup-script) to use it. 
+Now that you've updated your `oref0` version, you will want to run the oref0-setup script (`cd && ~/src/oref0/bin/oref0-setup.sh`) again. See [this section](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#be-prepared-to-enter-the-following-information-into-oref0-setup) for a guide of what the setup script will be prompting you to enter.