Merge pull request #2 from openaps/master

UPdating local copy of docs

Author: tim2000s

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

@@ -0,0 +1,76 @@
+# Jubilinux prerequisite
+
+*This page assumes you have a Jubilinux already flashed on your Edison. If you don't, please 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 when the flashing is complete.  You do not have to take the steps so far as installing wifi, or dependencies manually anymore.  Thanks to the bootstrap script below, all of those steps AFTER FLASHING are now automated.  So, when you get to the end of flash step, come on back here for bootstrap.*  
+
+### Prep Computer and Login to rig
+
+Assuming you don't have your computer setup yet for OpenAPS, here's the instructions for getting the environment ready and logging in, depending on computer system:
+
+* **PC users:** [follow these instructions to get PUTTY and plug in your rig](windows-putty-prep.md). Then, follow the rest of the instructions below.
+
+* **Mac users:** [follow these instructions to open Terminal and plug in your rig](mac-prep.md). Then, follow the rest of the instructions below.
+
+### Bootstrap script
+
+If you're not already, make sure you're logged into your rig via root. You should see `root@jubilinux` on the command prompt.
+
+The box below is the Bootstrap script, and it will complete steps 2 and 3 for you.  You'll get your first wifi network connection and install dependencies.  Copy this text (all of it in the box): 
+
+```
+#!/bin/bash
+(
+dmesg -D
+echo Scanning for wifi networks:
+ifup wlan0
+wpa_cli scan
+echo -e "\nStrongest networks found:"
+wpa_cli scan_res | sort -grk 3 | head | awk -F '\t' '{print $NF}' | uniq
+set -e
+echo -e /"\nWARNING: this script will back up and remove all of your current wifi configs."
+read -p "Press Ctrl-C to cancel, or press Enter to continue:" -r
+echo -e "\nNOTE: Spaces in your network name or password are ok. Do not add quotes."
+read -p "Enter your network name: " -r
+SSID=$REPLY
+read -p "Enter your network password: " -r
+PSK=$REPLY
+cd /etc/network
+cp interfaces interfaces.$(date +%s).bak
+echo -e "auto lo\niface lo inet loopback\n\nauto usb0\niface usb0 inet static\n  address 10.11.12.13\n  netmask 255.255.255.0\n\nauto wlan0\niface wlan0 inet dhcp\n  wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf" > interfaces
+echo -e "\n/etc/network/interfaces:\n"
+cat interfaces
+cd /etc/wpa_supplicant/
+cp wpa_supplicant.conf wpa_supplicant.conf.$(date +%s).bak
+echo -e "ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev\nupdate_config=1\nnetwork={\n  ssid=\"$SSID\"\n  psk=\"$PSK\"\n}" > wpa_supplicant.conf
+echo -e "\n/etc/wpa_supplicant/wpa_supplicant.conf:\n"
+cat wpa_supplicant.conf
+echo -e "\nAttempting to bring up wlan0:\n"
+ifdown wlan0; ifup wlan0
+sleep 10
+echo -ne "\nWifi SSID: "; iwgetid -r
+sleep 5
+curl https://raw.githubusercontent.com/openaps/oref0/master/bin/openaps-install.sh > /tmp/openaps-install.sh
+bash /tmp/openaps-install.sh
+)
+```
+
+Copy all of those lines; go back to Terminal/PuTTY and paste into the command line (Paste in PuTTY is just a right mouse click). Then, hit `enter`.  The screenshot below is an example of what the pasted text will look like (highlighted in blue for clarity). *(If you have trouble copying from the box, [click here](https://raw.githubusercontent.com/openaps/oref0/dev/bin/openaps-bootstrap.sh) and ctrl-a or command-a to copy the text from there.)*
+
+*************
+Note: **This setup script will require you to have an available working internet connection to be successful.**  If anything fails during the installation, the setup may end early before you get to the setup script questions.  In that case, you can just paste the script above into the command line again and try again.  (Don't try to use the up arrow, it probably won't work.)  If you get repeated failures, bring your questions and error messages into Gitter or FB for help with troubleshooting.
+*************
+
+![Example of wifi bootstrap script finding wifi options](../Images/Edison/setup-paste.png)
+
+The script will do some initial installing, check the wifi, and ask you to hit enter to proceed.  It will run for a while again, and then ask you to type in your wifi name and press `enter`; and type your wifi password and press `enter`.  Pay careful attention to capital letters, spacing, and special characters.
+
+![Example of wifi bootstrap script finding wifi options](../Images/Edison/openaps-bootstrap-wifi-setup.png)
+
+* Change your hostname (a.k.a, your rig's name). **Make sure to write down your hostname; this is how you will log in in the future as `ssh root@what-you-named-it.local`**
+
+* Pick your time zone (e.g., In the US, you'd select `US` and then scroll and find your time zone, such as `Pacific New` if you're in California).
+
+Now that step 2 is done, the bootstrap script will then continue to run awhile longer (~20+ minutes)...this next part is installing the necessary dependencies (step 3) before you move onto the setup script (step 4).  You'll see an awful lot of lines going by as the process goes on.  Eventually, the successful bootstrap ends with this screen below:
+
+![End of Bootstrap script](../Images/Edison/bootstrap-end.png)
+
+At the completion, you will be prompted to press `enter` if you want to continue the setup script (oref0-setup).  If you don't have time to run the setup script (a fresh install of setup script can take about an hour to run), then you can cancel and come back to it later.  Regardless of your answer, you should now return to [the Setup Script section](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#run-oref0-setup) for finishing step 4.

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

@@ -0,0 +1,106 @@
+# Setting up a Raspberry Pi rig
+
+### Download Raspbian and write it to your microSD card ###
+
+There are many ways setup Raspian (the operating system...like jubilinux is for Edison board) microSD card to use in your Raspberry Pi.  The easiest way for a new user is to use PiBakery, a free application you'll download from the internet.
+
+Download PiBakery [here](http://pibakery.org/download.html).  Follow the directions for installing PiBakery on your computer (the directions on their site include screenshots that are helpful).  The download is fairly large (2.2GB) so it may take a couple minutes to complete.
+
+Once you open PiBakery installer, you will be presented with a choice of installing Raspian Full or Raspian Lite.  Unselect the checkbox for Raspian Full, and keep the installation for Raspian Lite.  When the installation is done, you will be asked if you want to move the PiBakery installer to the trash.  That is fine to do.
+
+!["install piBakery"](../Images/build-your-rig/pi-raspian-lite.png)
+
+When the install has finished, find and open the PiBakery app from your applications folder on the computer.  You may be prompted for your computer's passcode; if so, enter it.
+
+The starting screen for the PiBakery is fairly empty, but we are going to basically use visual boxes to build a puzzle of what we would like to install on our SD card.  So start by clicking on the "Startup" selection on left column.  Click, drag, and drop the "on first boot" box over to the white area to the right of the window.  
+
+!["install piBakery"](../Images/build-your-rig/pi-step1.png)
+
+Next, click on the Network category and drag over the Setup Wifi box to near the On First Boot box.
+
+!["install piBakery"](../Images/build-your-rig/pi-step2.png)
+
+You want to have the boxes link together (if you have audio on, you'll hear a little click noise as the boxes link together).  You can drag more wifi network boxes if you already know the wifi networks that you'd like to add already.  Don't worry though, you'll have the opportunity to add more later...this is just an important step to get started the first time with at least one network.
+
+!["install piBakery"](../Images/build-your-rig/pi-step3.png)
+
+Note:  Raspbian requires a Country Code (such as US, UK, DE, etc) - otherwise wifi will remain disabled on the Pi.  This is different than the Edison/Jubilinux setups so be aware!  The default country code is GB, because that is where the PiBakery author is from.  Most users will need to change this.  Wondering what the codes are?  You can look up your two letter code [here](https://www.iso.org/obp/ui/#search/code/).
+
+Enter in your network name, password, and country code.  Capital and lowercase matter.  You can leave the type as WPA/WPA2 unless you specifically know your network uses a different connection type.
+
+You can add as many special "recipe ingredients" as you'd like.  Advanced users may find ingredients they are specifically interested in.  Shown below is a relatively simple setup that will have good utility (one wifi network and setting the OTG port to serial to make future offline-connections easier).  
+
+!["install piBakery"](../Images/build-your-rig/pi-step4.png)
+
+Put your microSD card into a reader for your computer.  Once you get your recipe completed in PiBakery, click on the "Write" icon in the upper left of the window. You'll select your SD card's name from the menu that appears and the Operating System will be Raspbian Lite.  Click the Start Write button.  Click yes to the warning about erasing the content of the card to begin the writing process.
+
+!["install piBakery"](../Images/build-your-rig/pi-step5.png)
+
+### Boot up your Pi and connect to it ###
+
+After a couple minutes, the writing should be done and you can eject the microSD card from your computer, insert it into your Pi (card slot location shown below), and plug in power to the Pi, and turn on the power switch (off/on positions are labeled on the HAT board for ease).
+
+!["install piBakery"](../Images/build-your-rig/pi-insert.jpg)
+
+Give the rig 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 use `ssh pi@raspberrypi.local`
+
+On Windows, use PuTTY and establish an SSH connection, with username `pi`, to hostname `raspberrypi.local`. 
+
+Troubleshooting:  If you have problems connecting, try rebooting your router.  If you have multiple channels (2.4Ghz vs 5Ghz), you could try redoing the PiBakery setup with the other channel's network name, if the first one fails.
+
+The default password for logging in as `pi` is `raspberry`.  The `pi` username and default password is only used for this initial connection: subsequently you'll log in as `root` with a password and rig hostname of your choosing.
+
+### Run openaps-install.sh ###
+
+Once you're logged in, run the following commands to start the OpenAPS install process:
+
+```
+sudo bash
+curl -s https://raw.githubusercontent.com/openaps/oref0/dev/bin/openaps-install.sh > /tmp/openaps-install.sh && bash /tmp/openaps-install.sh
+```
+
+You'll be prompted to set two passwords; one for root user and one for pi user.  You'll want to change the password 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 for each user.  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.
+
+* Change your hostname (a.k.a, your rig's name). **Make sure to write down your hostname; this is how you will log in in the future as `ssh root@whatyounamedit.local`**
+
+* Pick your time zone (e.g., In the US, you'd select `US` and then scroll and find your time zone, such as `Pacific New` if you're in California).
+
+The script will then continue to run awhile longer (10 to 30 minutes) before asking you to press `enter or control-c` for the setup script options.  Successful completion of this section should look like below.  **Do not press enter**
+
+!["install piBakery"](../Images/build-your-rig/pi-curl-success.png)
+
+
+Troubleshooting:  If your screen stops as shown below or jumps ahead to the interactive portion before successful completion (as shown above), rerun the curl -s command line shown above.  
+
+!["install piBakery"](../Images/build-your-rig/pi-curl-fail.png)
+
+
+**************************
+At this time, the master installation of oref0 is not compatible with the the newest Raspian system kernels.  So, instead of proceeding with the setup script, press `control-c` to cancel the setup script.
+
+Reboot your rig by entering `reboot`.  This will end your ssh session.  Give your rig time to reboot, reconnect to wifi, and then login to the rig again.  This time the rig will be using the rig name you chose before in the setup so use `ssh root@yourrigname.local` (or Putty equivalent for Windows users).
+
+Now we will select a Raspian-compatible updated branch by using `cd ~/src/oref0 && git checkout dev`. On your first install you should see a message returned of "Branch dev set up to track remote branch dev from origin. Switched to a new branch 'dev'". On subsequent installs or updates you would follow the direction to execute the command "git pull".
+
+Now run `npm run global-install`.  After about 10-15 minutes, the installations will end and you will be dropped off at the `root@yourrigname:~/src/oref0#` prompt.  Successful completion of this step should look like below.
+
+!["install piBakery"](../Images/build-your-rig/pi-install-success.png)
+
+Now you can run the interactive oref0 setup script:
+
+`cd && ~/src/oref0/bin/oref0-setup.sh`
+
+Answer all the setup questions.  A successful setup script will finish asking you if you want to setup cron.  Say yes to those two questions.  Finally, you'll see a message about Reboot required.  Go ahead and reboot the rig.  You've finished the loop installation.  Login to the rig again, and then **make sure to [Watch the pump loop](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#step-5-watch-your-pump-loop-log)**
+
+!["install piBakery"](../Images/build-your-rig/pi-loop-install.png)
+
+Troubleshooting: If your rig gets stuck at the point shown below, simply login to the rig again and run the setup script one more time.  Usually, running the setup script a second time will clear that glitch.
+
+!["install piBakery"](../Images/build-your-rig/pi-setup-stuck.png)
+
+*****************************
+
+
+