start to organize installation directions & consolidate flashing info

docs/docs/Build Your Rig/index.rst

@@ -1,16 +1,17 @@
+-------------------------------
 Installing OpenAPS on your rig
 -------------------------------
 
-Getting your rig with OpenAPS takes generally six steps:
+Getting OpenAPS running on your rig generally takes five steps:
 
 1. **Jubilinux installation** (called "flashing" the Edison - Pi users can skip to step 2). This may already be done for you if you purchased a pre-flashed Edison board.  
 2. **Getting first wifi network connection and installing "dependencies"** (helper code that make all the OpenAPS code function). This is done using what is called the "bootstrap" script.
 3. **Installing your OpenAPS loop**. This is done using what is called the "setup" script.
 4. **Watching the Pump-loop Log**. This is an important, required step. You need to be familiar with how to read and access your logs.
 5. **Finish your setup**: all the polishing steps to your OpenAPS setup.  Things like optimizing your settings, preferences, BT-tethering, IFTTT, etc.
 
+
 Some conventions used in these docs:
-==========================================
 
 * Wherever you see text that is formatted `like this`, it is a code snippet. You should copy and paste those code snippets instead of attempting to type these out; this will save you debugging time for finding your typos.
 * Double check that your copy-paste has copied correctly.  Sometimes a paste may drop a character or two and that will cause an error in the command that you are trying to execute.  Sometimes, depending on what step you are doing, you may not see the issue.  So, do make a point of double checking the paste before pressing return.
@@ -19,10 +20,14 @@ Some conventions used in these docs:
 * Wherever there are `<bracketed_components>` in the code, these are meant for you to insert your own information. Most of the time, it doesn't matter what you choose **as long as you stay consistent throughout this guide**. That means if you choose `myedison` as your  `<edisonhostname>`, you must use `myedison` every time you see `<edisonhostname>`. Do not include the `< >` brackets in your commands when you enter them.  So for the example above, if the code snipped says `ssh root@<edisonhostname>.local`, you would enter `ssh root@myedison.local`
 
 
+
 .. toctree::
    :maxdepth: 4
    :hidden:
 
-   OpenAPS-install
+   step-1-flashing
+   step-2-wifi-dependencies
+   step-3-setup-script
+   step-4-watching-log
+   step-5-finishing-setup
    x12-users
-   keeping-up-to-date

docs/docs/Build Your Rig/step-2-wifi-dependencies.md

@@ -0,0 +1,158 @@
+# Step 2: Wifi and Dependencies
+
+Steps 2-3 are covered in the page links below, dependent on which type of rig you are using.  
+
+* If you are using an _**Intel Edison**_, start with the [Intel Edison instructions](edison-install.md).
+
+* If you are using a _**Raspberry Pi**_, start with the [Raspberry Pi instructions](pi-install.md).
+
+Going through steps 1-3 may take about 1-3 hours depending on your internet connection, whether the edison was pre-flashed, and comfort level with the instructions.  At the end of the bootstrap script (step 3), you will be asked if you want to continue on with the set-up script (step 4).  If you need to take a break and come back to step 4 later, you can answer "no" to continuing on and come back later...picking up at the directions below for running the setup script.
+
+
+
+Below are the manual instructions for reference. It is strongly recommended that you use the easy setup scripts instead.
+
+
+## Initial Edison Setup
+
+Log in as root/edison via serial console.
+
+Type/edit the following:
+
+    myedisonhostname=<thehostname-you-want>     #Do not type the <>
+
+And then paste the following to rename your Edison accordingly:
+
+    echo $myedisonhostname > /etc/hostname
+    sed -r -i"" "s/localhost( jubilinux)?$/localhost $myedisonhostname/" /etc/hosts
+
+Run these commands to set secure passwords.  It will ask you to enter your new password for each user 2 times. Type the password in the same both times.  To use SSH (which you will need to do shortly) this password needs to be at least 8 characters long.  Do not use a dictionary word or other easy-to-guess word/phrase as the basis for your passwords.  Do not reuse passwords you've already used elsewhere.
+
+    passwd root
+    passwd edison
+
+## Set up Wifi:
+
+`vi /etc/network/interfaces`
+
+Type 'i' to get into INSERT mode
+* Uncomment 'auto wlan0' (remove the `#` at the beginning of the line)
+* Edit the next two lines to read:
+```
+auto wlan0
+iface wlan0 inet dhcp
+    wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
+```
+Comment out or delete the wpa-ssid and wpa-psk lines.
+
+After editing, your file should look like:
+
+```
+# interfaces(5) file used by ifup(8) and ifdown(8)
+auto lo
+iface lo inet loopback
+
+auto usb0
+iface usb0 inet static
+    address 192.168.2.15
+    netmask 255.255.255.0
+
+auto wlan0
+iface wlan0 inet dhcp
+    wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
+```
+
+Press Esc and then type ':wq' and press Enter to write the file and quit
+
+`vi /etc/wpa_supplicant/wpa_supplicant.conf`
+
+Type 'i' to get into INSERT mode and add the following to the end, once for each network you want to add.  Be sure to include the quotes around the network name and password.
+
+```
+network={
+    ssid="my network"
+    psk="my wifi password"
+}
+```
+
+If you want to add open networks to your list, then add:
+
+```
+network={
+        key_mgmt=NONE
+        priority=-999
+}
+```
+
+If you have a hidden wifi network add the line `scan_ssid=1`.
+
+Some wifi networks require you to accept a terms and conditions prior to allowing access.  For example, Starbucks coffee shops and many hotels.  These networks are termed "captive" networks and connecting your rig to them is currently not an option.
+
+Other wifi networks may require you to enter a login name and password at an initial screen before allowing access (such as many school district wifi networks).  Some users have success in using the following wpa network settings for those types of networks:
+
+```
+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
+}
+```
+
+Press Esc and then type ':wq' and press Enter to write the file and quit
+
+`reboot` to apply the wifi changes and (hopefully) get online
+
+After rebooting, log back in and type `iwgetid -r` to make sure you successfully connected to wifi. It should print out your network name.
+
+Run `ifconfig wlan0` to determine the IP address of the wireless interface, in case you need it to SSH below.
+
+Leave the serial window open in case you can't get in via SSH and need to fix your wifi config.
+
+If you need more details on setting up wpa_supplicant.conf, see one of these guides:
+
+* [http://weworkweplay.com/play/automatically-connect-a-raspberry-pi-to-a-wifi-network/](http://weworkweplay.com/play/automatically-connect-a-raspberry-pi-to-a-wifi-network/)
+* [http://www.geeked.info/raspberry-pi-add-multiple-wifi-access-points/](http://www.geeked.info/raspberry-pi-add-multiple-wifi-access-points/)
+* [http://raspberrypi.stackexchange.com/questions/11631/how-to-setup-multiple-wifi-networks](http://raspberrypi.stackexchange.com/questions/11631/how-to-setup-multiple-wifi-networks)
+* [http://www.cs.upc.edu/lclsi/Manuales/wireless/files/wpa_supplicant.conf](http://www.cs.upc.edu/lclsi/Manuales/wireless/files/wpa_supplicant.conf)
+
+
+## Install packages, ssh keys, and other settings
+
+From a new terminal or PuTTY window, `ssh root@myedisonhostname.local`. If you can't connect via `youredisonhostname.local` (for example, on a Windows PC without iTunes), you can instead connect directly to the IP address you found with `ifconfig` above.
+
+Log in as root (with the password you just set above), and run:
+
+    dpkg -P nodejs nodejs-dev
+    apt-get update && apt-get -y dist-upgrade && apt-get -y autoremove
+    apt-get install -y sudo strace tcpdump screen acpid vim python-pip locate
+
+And:
+
+    adduser edison sudo
+    adduser edison dialout
+    dpkg-reconfigure tzdata    # Set local time-zone
+       Use arrow button to choose zone then arrow to the right to make cursor highlight <OK> then hit ENTER
+
+Edit (with `nano` or `vi`) /etc/logrotate.conf and change the log rotation to `daily` from `weekly` and enable log compression by removing the hash on the #compress line, to reduce the probability of running out of disk space
+
+If you're *not* using the Explorer board and want to run everything as `edison` instead of `root`, log out and log back in as edison (with the password you just set above).  (If you're using an Explorer board you'll need to stay logged in as root and run everything that follows as root for libmraa to work right.)
+
+If you have an ssh key and want to be able to log into your Edison without a password, copy your ssh key to the Edison ([directions you can adapt are here](http://openaps.readthedocs.io/en/latest/docs/Resources/Deprecated-Pi/Pi-setup.html#mac-and-linux)).  For Windows/Putty users, you can use these instructions: [https://www.howtoforge.com/ssh_key_based_logins_putty](https://www.howtoforge.com/ssh_key_based_logins_putty).
+
+If you're *not* using the Explorer board, are running as the `edison` users, and want to be able to run sudo without typing a password, run:
+```
+    $ su -
+    $ visudo
+```    
+and add to the end of the file:
+``` 
+ edison ALL=(ALL) NOPASSWD: ALL   
+```    
+
+You have now installed the operating system on your Edison! You can now proceed to the next step of adding yourself to [Loops in Progress](https://openaps.readthedocs.io/en/latest/docs/While You Wait For Gear/loops-in-progress.html)

docs/docs/Build Your Rig/step-3-setup-script.md

@@ -0,0 +1,65 @@
+# Step 3: Setup script
+
+* **If you pressed `enter` to continuing on with the setup script at the end of the bootstrap script**, you do **NOT** need to specifically enter the command in the box below.  By pressing `enter` to continuing on with setup script, the command was automatically started for you.
+
+* **If you pressed `control-c` to end at the completion of the bootstrap script** and did not continue automatically with setup script, this is where you'll pick back up.  At this point, your rig should have your first wifi connection finished and your dependencies installed.  
+
+    Login to your rig and run the following command (aka "the setup script"):
+
+    `cd && ~/src/oref0/bin/oref0-setup.sh`
+
+(Note: if this is your first time logging into the rig since running bootstrap script, you will have to change your rig's password on this first login.  You will enter the default password first of `edison` and then be prompted to enter your new password twice in a row.  If you get an error, it is likely that you forgot to enter `edison` at the first prompt for changing the password.)
+
+#### Be prepared to enter the following information into the setup script:
+
+The screenshot below shows an example of the questions you'll be prompted to reply to during the setup script (oref0-setup).  Your answers will depend on the particulars of your setup.  Also, don't expect the rainbow colored background - that's just to help you see each of the sections it will ask you about!
+
+<details>
+    <summary><b>Be prepared to enter the following items (click here to expand list):</b></summary>
+<br>
+
+* 6-digit serial number of your pump
+* whether you are using an 512/712 model pump (those require special setup steps that other model pumps do not)
+* whether you are using an Explorer board
+   * if not an Explorer board, 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. After you finish setup you need to check if the line `radio_type = carelink` is present in your `pump.ini` file.
+* 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. As a consequence, if you use FreeStyle Libre or any other CGM system that gets its data only from Nightscout, you'll be fine choosing any of the options above. 
+   * Note:  For Medtronic 640G (CGM) users, it is recommended that you enter 'xdrip' - otherwise the BG values may not be read from your Nightscout. (The reason being, the 'MDT' option applies only for the enlite sensor attached to the actual pump you're looping with)
+   * Note: 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)
+* 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.
+* Your desired max-iob
+* whether you want Autosensitivity and/or Autotune enabled
+* whether you want any carbs-required Pushover notifications (and if you do, you'll need your Pushover API token and User Key)
+
+</details>
+
+![Oref1 setup script](../Images/build-your-rig/sample-setup.png)
+
+At the end of the questions, the script will ask if you want to continue.  Review the information provided in the "to run again with these same options" area...check for any typos.  If everything looks correct, then press `y` to continue.  If you see a typo, press `n` and then type `cd && ~/src/oref0/bin/oref0-setup.sh` to start the setup questions over again.
+
+After the setup script finishes building your loop (called 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.  If your setup script stalls out before those two questions happen, rerun the setup script again.
+
+**************************
+
+### Log rotate fix
+
+<details>
+    <summary><b>Click here to expand notes about checking log rotate, which was fixed in 0.6.1:</b></summary>
+<br>
+
+Make sure that at the end of the setup script, your log rotate file is set to `daily` as described below.  Most users will have the `compress` line properly edited already, but the log rotate file seems to be left at `weekly` for many users.  If you leave the setup at `weekly`, you will likely get a `device full` error in your pump logs within a week...so please check this before moving on!
+
+* Enter `vi /etc/logrotate.conf` then press “i” for INSERT mode, and make the following changes so that your file matches the one below for the highlighted areas:
+
+ * set the log rotation to `daily` from `weekly`
+ * remove the # from the “#compress” line (if it is present)
+
+* Press ESC and then type `:wq` to save and quit
+
+![Log rotation examples](../Images/Edison/log_rotation.png)
+
+</details> 
+