add Pi-specific install instructions

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

@@ -1,5 +1,7 @@
 # Installing OpenAPS on your rig with a jubilinux-flashed Edison
 
+If you are using a Raspberry Pi instead of an Intel Edison, switch over to the [Raspberry Pi instructions](pi-install.md).
+
 *This page assumes you have a pre-flashed (with jubilinux) Edison. Don't have a pre-flashed Edison? Follow the steps for flashing on (a) [all-computers page](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html) (with the most comprehensive [troubleshooting section](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html#troubleshooting)); b) the [Mac-specific flashing page](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/mac-flash.html); or c) the [Windows-specific flashing page](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/PC-flash.html)), then come back here before installing wifi and other steps, which is easier to do following this page's flow.* 
 
 *This page also assumes you're setting up a brand-new rig and need the full setup including wifi. Make sure to check out the ["how to update your rig in the future"](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/update-your-rig.html) page if you have already had a rig up and running!* 

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

@@ -0,0 +1,208 @@
+# Setting up a Raspberry Pi
+
+### Download Raspbian and write it to your microSD card ###
+
+Following the instructions at https://www.raspberrypi.org/documentation/installation/installing-images/README.md, download Raspbian Lite (you do *not* want Raspbian Desktop) and write it to an microSD card using Etcher.
+
+### Place your wifi and ssh configs on the new microSD card ###
+
+Once Etcher has finished writing the image to the microSD card, remove the microSD card from your computer and plug it right back in, so the boot partition shows up in Finder / Explorer.
+
+Create a file named wpa_supplicant.conf on the boot drive, with your wifi network(s) configured.  It should look something like:
+
+```
+ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
+update_config=1
+network={
+  ssid="MyWirelessNetwork"
+  psk="MyWirelessPassword"
+}
+```
+
+Also create an empty file named `ssh` (with no file extention) to enable SSH login to the Pi.
+
+### Boot up your Pi and connect to it ###
+
+Eject the microSD card from your computer, insert it into your Pi, and plug in power to the Pi to turn it on.  Give it a couple minutes to boot up.  Once the green LED stops blinking as much, you can try to log in.
+
+On Mac, open Terminal and `ssh pi@raspberrypi.local`
+On Windows, use PuTTY to connect as the `pi` user to hostname `raspberrypi.local`
+
+### Run openaps-install.sh ###
+
+Once you're logged in, run the following command to start the OpenAPS install process:
+
+`curl -s https://raw.githubusercontent.com/openaps/oref0/pi-install/bin/openaps-install.sh > /tmp/openaps-install.s && sudo bash /tmp/openaps-install.sh`
+
+You'll be prompted to set a 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.  There is no recovery of this password if you forget it.  You will have to start over from the top of this page if you forget your password.
+
+**Be prepared to enter the following items:** 
+
+* your timezone *
+* email address for github commits
+* serial number of your pump
+* whether or not you are using an Explorer Board / HAT
+   * if not an Explorer Board / HAT, and not a Carelink stick, you'll need to enter the mmeowlink port for TI stick.  See [here](https://github.com/oskarpearson/mmeowlink/wiki/Installing-MMeowlink) for directions on finding your port
+    * if you're using a Carelink, you will NOT be using mmeowlink
+* CGM method:  The options are `g4-upload`, `g4-local-only`, `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.  G4-upload will allow you to have raw data when the G4 receiver is plugged directly into the rig.
+* Nightscout URL and API secret (or NS authentication token, if you use that option)
+* whether you want Autosensitivity and/or Autotune enabled
+* whether you want advanced features (SMB) - 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 (letters should be in all caps)
+  * Note, you'll still need to do finish the BT tethering as outlined [here](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/bluetooth-tethering-edison.html) after setup.
+* 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.
+
+#### Login again, and change your password
+
+After rebooting, `ssh` back in using Terminal or PuTTY, but this time as the `root` user:
+
+On Mac, open Terminal and `ssh root@raspberrypi.local`
+On Windows, use PuTTY to connect as the `root` user to hostname `raspberrypi.local`
+
+## 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` (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`*.)
+
+#### What you'll see while waiting for your first loop (common non-error messages)
+
+If this is your first rig, 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 calculate 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.  
+
+#### What you'll see when you are looping successfully ~20+ minutes later!
+
+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)
+
+Reading these should give you an idea for what OpenAPS knows: current BG, changes in BG, information about netIOB (taking into account any temp basals it has set along with any boluses you have done), carbs on board, etc. Plus, it will give you information about the predictions and show you the data points it is using to draw the "purple prediction lines" in Nightscout. It also will tell you what, if anything, is limiting it's ability to give more insulin - i.e. if you have maxIOB at 0, or it is capped by one of the safety settings, etc. This information is a longer version of the information that will show in the "OpenAPS pill" on Nightscout. And - this is where it will tell you what insulin it thinks you need (more/less and how much) and what temporary basal rate (temp basal) it will try to set next to adjust and bring your eventualBG prediction into your target range.
+
+If after 20 minutes, you still have some errors showing instead of the above successful looping information, it may be time to head over to the [Troubleshooting oref0-setup tips page](http://openaps.readthedocs.io/en/latest/docs/Troubleshooting/oref0-setup-troubleshooting.html) for ideas on your error messages and how to resolve them.  IF you aren't able to resolve your errors, please make sure that you have captured the error messages before heading over to Gitter or Facebook to get help.  Troubleshooting is far more successful when you come prepared with the error messages.
+
+**Done watching the logs? Type control-C to exit the pump-loop log.**
+
+#### Temp basals > 6.3, ISF > 255 or carb ratio > 25 with a x23 or x54?
+
+* If your rig tries and fails to set a temp basal > 6.3 you should see "ValueError: byte must be in range(0, 256)" in the log.  
+
+* If your pump ISF setting is > 255 the ISF shown in the log and in the OpenAPS pill in Nightscout will be 256 less than the actual pump setting (257 will show as 1).  
+
+* If your pump carb ratio is > 25 and you have a x23 or x54 pump you will see a message about "carb ratio out of bounds" in the log.
+
+To fix these problems you need to update decocare.  This is easy.  Type control-C to exit the pump-loop log.  Then copy the following 3 lines to the terminal window.
+
+```
+cd ~/src && git clone git://github.com/openaps/decocare.git
+cd decocare
+python setup.py install
+```
+
+#### Rig Logs and Shortcut commands
+
+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?"
+
+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 log: `tail -F /var/log/openaps/autosens-loop.log`
+
+* Nightscout log: `tail -F /var/log/openaps/ns-loop.log`
+
+* Network log: `tail -F /var/log/openaps/network.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)
+
+These logs and other files are things you may frequently access. There are shortcuts built in to help you more easily access key files on the go. The `l` you type for logs is an example of one of these shortcuts - it's actually a shortcut for the full command `tail -F /var/log/openaps/pump-loop.log`. Here are some other shortcuts:
+
+```
+ l => tail -F /var/log/openaps/pump-loop.log
+ autosens-loop => tail -n 100 -F /var/log/openaps/autosens-loop.log
+ autotune => tail -n 100 -F /var/log/openaps/autotune.log
+ ns-loop => tail -n 100 -F /var/log/openaps/ns-loop.log
+ pump-loop => tail -n 100 -F /var/log/openaps/pump-loop.log
+ cat-pref => cd ~/myopenaps && cat preferences.json
+ edit-wifi => vi /etc/wpa_supplicant/wpa_supplicant.conf
+ cat-wifi => cat /etc/wpa_supplicant/wpa_supplicant.conf
+ edit-pref => cd ~/myopenaps && vi preferences.json
+ log-wifi => tail -n 100 -F /var/log/openaps/network.log
+ git-branch => cd ~/src/oref0 && git branch
+ cat-autotune => cd ~/myopenaps/autotune && cat autotune_recommendations.log
+ edit-runagain => cd ~/myopenaps && nano oref0-runagain.sh
+ cat-runagain => cd ~/myopenaps && cat oref0-runagain.sh
+```
+To use these shortcuts, just type in the phrase you see on the left - i.e. `edit-wifi` and hit enter.
+
+## Finish your OpenAPS setup
+
+You're looping? Congrats! However, you're not done quite done yet. 
+
+****************
+**Shortly after you confirm your loop is running, you should [set your preferences](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/preferences-and-safety-settings.html).  Don't forget, your preferences are reset to defaults after each run of a setup script, so please remember to check preferences after confirming a loop is successfully run/rerun.**
+*******************
+
+As your time permits, there's still more useful and cool things you can do to make looping more efficient and automated.
+
+* [Add more wifi networks to your rig](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/on-the-go-wifi-adding.html) so that when you are away from home, the rig has access to trusted wifi networks
+* [Setup Papertrail](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#papertrail-remote-monitoring-of-openaps-logs-recommended) 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.
+* [Setup IFTTT for your phone or watch](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/ifttt-integration.html) to allow you to use Nightscout's temp targets, carb entries, and similar for single button interactions with your rig
+* [Finish Bluetooth tethering your phone](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/bluetooth-tethering-edison.html) so that when you are away from trusted wifi networks, your rig can automatically access your phone's mobile hotspot for continued online looping. 
+* [Learn about offline looping](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/offline-looping-and-monitoring.html) for times when your rig is not able to access internet (no wifi, no hotspot).
+* [Additional access to your rig via other types of mobile apps.](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/useful-mobile-apps.html) Grab some of these other apps, based on your preference, for accessing your rig in different ways. 
+
+Remember, the performance of your DIY closed loop is up to you. Make sure you at least look at the rest of the documentation for help with troubleshooting, ideas about advanced features you can implement in the future when you're comfortable with baseline looping, and more. Plus, the docs are updated frequently, so it's worth bookmarking and checking back periodically to see what features and preference options have been added. 
+
+