From de0ca6f308ff6954db6d43af9c90d935727d8ca4 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 5 Feb 2020 17:54:58 -0500 Subject: [PATCH 01/13] apply changes from general-cleanup to current master branch --- .gitignore | 4 + docs/conf.py | 41 +- docs/docs/Build Your Rig/edison-install.md | 76 --- docs/docs/Build Your Rig/install-overview.md | 21 + .../docs/Build Your Rig/keeping-up-to-date.md | 13 - .../Build Your Rig/logging-into-rig-serial.md | 68 +++ docs/docs/Build Your Rig/mac-prep.md | 37 -- docs/docs/Build Your Rig/step-1-flashing.md | 349 ++++++++++++++ .../step-2-wifi-dependencies.md | 455 ++++++++++++++++++ .../Build Your Rig/step-3-setup-script.md | 210 ++++++++ .../Build Your Rig/step-4-watching-log.md | 149 ++++++ .../Build Your Rig/step-5-finishing-setup.md | 61 +++ .../docs/Build Your Rig/windows-putty-prep.md | 44 -- .../Customize-Iterate/ifttt-integration.md | 4 +- docs/docs/Customize-Iterate/index.rst | 19 - .../offline-looping-and-monitoring.md | 15 +- docs/docs/Customize-Iterate/oref1.md | 82 ++-- .../understanding-autotune.md | 40 -- .../Customize-Iterate/useful-mobile-apps.md | 2 +- docs/docs/Gear Up/CGM.md | 2 +- docs/docs/Gear Up/edison-explorer-board.md | 179 +++++++ .../{hardware.md => hardware-overview.md} | 9 +- docs/docs/Gear Up/index.rst | 11 - docs/docs/Gear Up/pi-based-rigs.md | 251 ++++++++++ docs/docs/Gear Up/pump.md | 4 +- docs/docs/Gear Up/rig-options.md | 13 + .../data-commons-data-donation.md | 2 +- docs/docs/Give Back-Pay It Forward/index.rst | 9 - .../autosens.md | 34 +- docs/docs/How it works/autotune.md | 74 +++ .../understand-determine-basal.md} | 6 +- ...rstanding-insulin-on-board-calculations.md | 4 +- .../Resources/Deprecated-Pi/Pi-hardware.md | 2 +- docs/docs/Resources/Deprecated-Pi/Pi-setup.md | 2 +- .../Resources/Edison-Flashing/PC-flash.md | 271 ----------- .../Edison-Flashing/all-computers-flash.md | 442 ----------------- .../Resources/clinician-guide-to-OpenAPS.md | 6 +- docs/docs/Resources/glossary.md | 2 +- docs/docs/Resources/index.rst | 23 - docs/docs/Resources/my-first-pr.md | 6 +- .../switching-between-DIY-systems.md | 47 +- docs/docs/Resources/technical-resources.md | 2 + .../CGM-rig-communications-troubleshooting.md | 4 +- docs/docs/Troubleshooting/Carelink.md | 11 + .../Troubleshooting/Common-error-messages.md | 158 ++++++ .../General_linux_troubleshooting.md | 65 ++- .../Medtronic-Button-Errors.md | 0 .../Rig-NS-communications-troubleshooting.md | 63 ++- .../Wifi-and-hotspot-issues.md | 30 ++ docs/docs/Troubleshooting/index.rst | 11 - .../oref0-setup-troubleshooting.md | 12 +- .../communication-support-channels.md | 76 +-- .../how-openaps-works-overview.md | 26 +- .../Understanding OpenAPS-Overview/index.rst | 10 - .../overview-of-build-process.md | 14 +- .../using-the-docs.md | 32 ++ .../Wifi}/bluetooth-tethering-edison.md | 15 +- .../Wifi}/on-the-go-wifi-adding.md | 17 +- .../Wifi}/understanding-wifi-options.md | 12 +- .../entering-carbs-bolus.md | 48 ++ .../example-max-safety-chart.md | 0 .../examples_safety_caps_in_play.png | Bin .../monitoring-OpenAPS.md | 91 +--- .../optimize-your-settings.md | 18 +- .../oref0-runagain.md | 2 +- .../preferences-and-safety-settings.md | 6 +- .../running-autotune.md} | 153 ++---- .../update-your-rig.md | 6 +- .../usability-considerations.md | 83 +--- .../collect-data-and-prepare.md | 52 +- .../entering-carbs-bolus.md | 38 -- docs/docs/While You Wait For Gear/index.rst | 16 - .../loops-in-progress.md | 2 +- .../nightscout-setup.md | 92 ++-- .../While You Wait For Gear/reading-list.md | 15 + .../understanding-your-Explorer-Board-rig.md | 136 ------ docs/index.rst | 129 +++-- requirements.txt | 2 +- 78 files changed, 2705 insertions(+), 1831 deletions(-) delete mode 100644 docs/docs/Build Your Rig/edison-install.md create mode 100644 docs/docs/Build Your Rig/install-overview.md delete mode 100644 docs/docs/Build Your Rig/keeping-up-to-date.md create mode 100644 docs/docs/Build Your Rig/logging-into-rig-serial.md delete mode 100644 docs/docs/Build Your Rig/mac-prep.md create mode 100644 docs/docs/Build Your Rig/step-1-flashing.md create mode 100644 docs/docs/Build Your Rig/step-2-wifi-dependencies.md create mode 100644 docs/docs/Build Your Rig/step-3-setup-script.md create mode 100644 docs/docs/Build Your Rig/step-4-watching-log.md create mode 100644 docs/docs/Build Your Rig/step-5-finishing-setup.md delete mode 100644 docs/docs/Build Your Rig/windows-putty-prep.md delete mode 100644 docs/docs/Customize-Iterate/index.rst delete mode 100644 docs/docs/Customize-Iterate/understanding-autotune.md create mode 100644 docs/docs/Gear Up/edison-explorer-board.md rename docs/docs/Gear Up/{hardware.md => hardware-overview.md} (66%) delete mode 100644 docs/docs/Gear Up/index.rst create mode 100644 docs/docs/Gear Up/pi-based-rigs.md create mode 100644 docs/docs/Gear Up/rig-options.md delete mode 100644 docs/docs/Give Back-Pay It Forward/index.rst rename docs/docs/{Customize-Iterate => How it works}/autosens.md (74%) create mode 100644 docs/docs/How it works/autotune.md rename docs/docs/{While You Wait For Gear/Understand-determine-basal.md => How it works/understand-determine-basal.md} (96%) rename docs/docs/{While You Wait For Gear => How it works}/understanding-insulin-on-board-calculations.md (99%) delete mode 100644 docs/docs/Resources/Edison-Flashing/PC-flash.md delete mode 100644 docs/docs/Resources/Edison-Flashing/all-computers-flash.md delete mode 100644 docs/docs/Resources/index.rst create mode 100644 docs/docs/Troubleshooting/Carelink.md create mode 100644 docs/docs/Troubleshooting/Common-error-messages.md rename docs/docs/{Resources => Troubleshooting}/Medtronic-Button-Errors.md (100%) create mode 100644 docs/docs/Troubleshooting/Wifi-and-hotspot-issues.md delete mode 100644 docs/docs/Troubleshooting/index.rst delete mode 100644 docs/docs/Understanding OpenAPS-Overview/index.rst create mode 100644 docs/docs/Understanding OpenAPS-Overview/using-the-docs.md rename docs/docs/{Customize-Iterate => Usage and maintenance/Wifi}/bluetooth-tethering-edison.md (97%) rename docs/docs/{Customize-Iterate => Usage and maintenance/Wifi}/on-the-go-wifi-adding.md (69%) rename docs/docs/{While You Wait For Gear => Usage and maintenance/Wifi}/understanding-wifi-options.md (91%) create mode 100644 docs/docs/Usage and maintenance/entering-carbs-bolus.md rename docs/docs/{While You Wait For Gear => Usage and maintenance}/example-max-safety-chart.md (100%) rename docs/docs/{While You Wait For Gear => Usage and maintenance}/examples_safety_caps_in_play.png (100%) rename docs/docs/{While You Wait For Gear => Usage and maintenance}/monitoring-OpenAPS.md (81%) rename docs/docs/{Customize-Iterate => Usage and maintenance}/optimize-your-settings.md (60%) rename docs/docs/{Customize-Iterate => Usage and maintenance}/oref0-runagain.md (81%) rename docs/docs/{While You Wait For Gear => Usage and maintenance}/preferences-and-safety-settings.md (97%) rename docs/docs/{Customize-Iterate/autotune.md => Usage and maintenance/running-autotune.md} (74%) rename docs/docs/{Customize-Iterate => Usage and maintenance}/update-your-rig.md (84%) rename docs/docs/{Customize-Iterate => Usage and maintenance}/usability-considerations.md (74%) delete mode 100644 docs/docs/While You Wait For Gear/entering-carbs-bolus.md delete mode 100644 docs/docs/While You Wait For Gear/index.rst create mode 100644 docs/docs/While You Wait For Gear/reading-list.md delete mode 100644 docs/docs/While You Wait For Gear/understanding-your-Explorer-Board-rig.md diff --git a/.gitignore b/.gitignore index 95a36d069..b7d2b8a77 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,7 @@ _book *.mobi *.pdf .*.sw[op] + +# All build output (HTML etc.) +build +denv diff --git a/docs/conf.py b/docs/conf.py index a21419c34..746a94a14 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,8 +41,13 @@ 'sphinx.ext.autodoc', 'sphinx.ext.todo', # 'alabaster', + 'sphinx.ext.autosectionlabel', # Auto-generate section labels. ] +# Prefix document path to section labels, otherwise autogenerated labels would look like 'heading' +# rather than 'path/to/file:heading' +autosectionlabel_prefix_document = True + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -125,7 +130,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -#html_theme = 'default` +html_theme = 'sphinx_rtd_theme' extra_nav_links = { @@ -138,31 +143,17 @@ # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -# alabaster -theme_github_user = 'openaps' -theme_github_repo = 'docs' html_theme_options = { - 'show_related': True, - 'github_user': theme_github_user, - 'github_repo': theme_github_repo, - 'logo': 'openaps-logo.png', - # TODO: ???? doesn't work? - 'extra_nav_links': extra_nav_links, + 'collapse_navigation': False, + 'sticky_navigation': False, + 'navigation_depth': 3, + 'titles_only': False } -""" -html_theme = 'default' -html_theme_options = { - 'display_github': True, - 'github_user': 'openaps', - 'github_repo': 'docs', -} -import sphinx_rtd_theme -html_theme_path = [sphinx_rtd_theme.get_html_theme_path( )] -""" + # Add any paths that contain custom themes here, relative to this directory. -html_theme_path = [] +# html_theme_path = [] # html_theme_path = [alabaster.get_path( )] # The name for this set of Sphinx documents. If None, it defaults to @@ -419,11 +410,12 @@ #epub_use_index = True github_doc_root = 'https://github.com/openaps/docs/tree/master/' -hosted_root = 'http://localhost:8000/' +hosted_root = os.environ.get('HOSTEDROOT', 'http://localhost:8000/') # Allow setting custom root in local .env file for serving static files on_rtd = os.environ.get('READTHEDOCS', None) == 'True' if on_rtd: rtd_version = os.environ.get('READTHEDOCS_VERSION') - hosted_root = 'https://openaps.readthedocs.org/en/%s/' % rtd_version + rtd_domain = os.environ.get('READTHEDOCS_PROJECT') + hosted_root = 'https://%s.readthedocs.org/en/%s/' % (rtd_domain, rtd_version) def setup(app): app.add_config_value('recommonmark_config', { # 'url_resolver': lambda url: github_doc_root + url, @@ -432,5 +424,4 @@ def setup(app): 'enable_auto_doc_ref': True, 'enable_eval_rst': True, }, True) - app.add_transform(AutoStructify) - + app.add_transform(AutoStructify) \ No newline at end of file diff --git a/docs/docs/Build Your Rig/edison-install.md b/docs/docs/Build Your Rig/edison-install.md deleted file mode 100644 index 6c3eeb703..000000000 --- a/docs/docs/Build Your Rig/edison-install.md +++ /dev/null @@ -1,76 +0,0 @@ -# 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. diff --git a/docs/docs/Build Your Rig/install-overview.md b/docs/docs/Build Your Rig/install-overview.md new file mode 100644 index 000000000..b4318856b --- /dev/null +++ b/docs/docs/Build Your Rig/install-overview.md @@ -0,0 +1,21 @@ +# Installing OpenAPS on your rig + +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. + +Going through steps 1-2 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 2), you will be asked if you want to continue on with the set-up script (step 3). If you need to take a break and come back to step 3 later, you can answer "no" to continuing on and come back later. + +Before you start, it's a good idea to have some basic familiarity with using the command line on your computer, via a program like Terminal (on Mac) or Command Line (on Windows). This will be helpful not just for initial installation, but for monitoring and adjusting your setup later. [Here's a good introduction to using Terminal on Mac.](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) You can also reference the [generally-useful Linux commands](<../Troubleshooting/General_linux_troubleshooting>) from the troubleshooting guide. + +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. +* You will see a $ at the beginning of many of the lines of code. This + indicates that it is to be entered and executed at the terminal prompt. Do not type in the dollar sign $. +* Wherever there are `` 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 ``, you must use `myedison` every time you see ``. Do not include the `< >` brackets in your commands when you enter them. So for the example above, if the code snipped says `ssh root@.local`, you would enter `ssh root@myedison.local` diff --git a/docs/docs/Build Your Rig/keeping-up-to-date.md b/docs/docs/Build Your Rig/keeping-up-to-date.md deleted file mode 100644 index 7295e2d6f..000000000 --- a/docs/docs/Build Your Rig/keeping-up-to-date.md +++ /dev/null @@ -1,13 +0,0 @@ -# So you think you're looping? Now keep up to date! - -If you've gone "live" with your loop, congratulations! You'll probably want to keep a very close eye on the system and validate the outputs for a while. (For every person, this amount of time varies). - -One important final step, in addition to continuing to keep an eye on your system, is letting us know that you are looping. - -**This is important in case there are any major changes to the system that we need to notify you about**. One example where this was necessary is when we switched from 2015 to 2016: the dates were incorrectly reporting as 2000, resulting in incorrect IOB calculations. As a result, we needed to notify current loopers so they could make the necessary update/upgrade. - -## After you have looped for three consecutive nights: - -So that we can notify you if necessary, [please fill out this form if you have been looping for 3+ days](http://bit.ly/nowlooping). Your information will not be shared in any way. You can indicate your preferred privacy levels in the form. As an alternative, if you do not want to input info, please email dana@openaps.org. Again, this is so you can be notified in the case of a major bug find/fix that needs to be deployed. - -**Note**: you only ever need to fill this form out once. If you're building multiple rigs, or switching between DIY systems, no need to fill this out multiple times. We're just counting - and wanting to connect with in terms of safety announcements - humans. :) diff --git a/docs/docs/Build Your Rig/logging-into-rig-serial.md b/docs/docs/Build Your Rig/logging-into-rig-serial.md new file mode 100644 index 000000000..3d4d311b9 --- /dev/null +++ b/docs/docs/Build Your Rig/logging-into-rig-serial.md @@ -0,0 +1,68 @@ +# Logging into your Explorer Board rig via console + +## Prerequisites for Windows users + +- Install the [Intel Edison drivers for Windows](https://software.intel.com/en-us/iot/hardware/edison/downloads). Select the "Windows standalone driver" download if available. (Note: Intel has announced the Edison will be discontinued at the end of 2017. As part of this, apparently, the old link to Edison drivers has been removed. We are unsure if this is a temporary issue or long term. Therefore, if the link above for Intel Edison Drivers is not working, you can use [this link](https://www.dropbox.com/s/d5ooojru5jxsilp/IntelEdisonDriverSetup1.2.1.exe?dl=0) to download them directly from an OpenAPS user's dropbox. Obviously screenshots below will be different if Intel has not fixed or repaired their driver downloads page for Edisons.) After it is done downloading, click on the downloaded file and it will execute installation. You do not need to reflash the Edison or setup security or Wi-Fi with this tool because later steps in this process will overwrite those settings. + +![Edison Drivers](../Images/Edison/edison_driver.png) + +![Edison Drivers](../Images/Edison/edison_driver2.png) + +- Install [PuTTY]( http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html). PuTTY is the program you will normally use to login to your rig in the future from the computer. Creating a desktop shortcut for it is a good idea, since you will likely use it often. Download the installation file that matches your PC's architecture (32-bit or 64-bit). If you are unsure, you can check your computer's build and memory in the Control Panel. Example shown is for a 64-bit computer. If unsure, installing the 32-bit version won't harm anything...it just might be a little slower to use PuTTY. + +![Control Panel](../Images/Edison/64_bit.png) + +![Putty](../Images/Edison/putty.png) + +![Putty](../Images/Edison/putty2.png) + +![Putty](../Images/Edison/putty3.png) + + +## Plugging in cables and starting console + +Your Explorer Board has 2 micro USB connectors. They can both provide power. On the community developed Edison Explorer Board, the port labeled OTG is for flashing, and the one labeled UART provides console login. You must connect both ports to your computer to complete the flash process. If you need to log into the rig using the console in the future, you will only need to connect to the UART port. + +You must use DATA micro USB to USB cables. How do you know if your cable is for data? One good way is to plug the cable into your computer USB port and the explorer board OTG port. If your folder/window explorer shows Edison as a drive then the cable supports data. +If you don’t… 1) Try unplugging and replugging the existing cables; 2) try different cables. If your USB port is bad and not recognizing the device, you may need to [reset your SMC first](https://support.apple.com/en-au/HT201295) (it’s not hard to do, takes 2 minutes.) + +![Edison in Finder](../Images/Edison/Edison_in_Finder_folder.png) + +![Edison in Finder](../Images/Edison/Edison_in_Finder_folder.png) + +Note: If you are using a Macbook with a USB-C Hub you may encounter some issues with the flashing process, including unexpected rebooting and the wireless LAN setup not functioning correctly. If you have an option to use a PC or Laptop with directly connected USB cables, it will be easier to do so. Direct USB-C to micro-USB cables are better than a hub and a USB-to-microUSB cable, but still not as good as a regular USB port. + + - Connect a USB cable (one that carries data, not just power) to the USB console port. On the Explorer board or Sparkfun base block, this is the port labeled `UART`. On the Intel mini breakout board, this is the USB port that is labeled P6 (should be the USB closest to the JST battery connector). Plug the other end into the computer (or Pi) you want to use to connect to console. + - Plug another USB cable (one that carries data, not just power) into the USB port labeled OTG on the Explorer board or Sparkfun base block, or the port that is almost in the on the bottom right (if reading the Intel logo) if setting up with the Intel mini breakout board. Plug the other end into the computer (or Pi) you want to flash from. + +![Explorer Board rig with two cables and red light on](../Images/Edison/ExplorerBoard_two_charging_cables.png) + +## If you're using a Raspberry Pi or Mac for console: + - Open a terminal window and type `sudo screen /dev/tty.usbserial-* 115200` + - If you do not have screen installed you can install with `sudo apt-get install screen`. + - If necessary, replace the '*' with your Edison UART serial number, obtained using lsusb. + - You’ll most likely be asked for your computer password again because you're using sudo. Enter it. + - Continue with the All platforms section below. + +## If you're using a Windows PC for console: + + - Once you plug in the cable, you need to determine which COM number it's using. On your computer, go to Control Panel\All Control Panel Items\Device Manager\Ports\ and look for USB Serial Port COMXX. If you have multiple and are unsure of which is the port you need: Make note of existing ports. Unplug the cable from the Explorer board. Notice which port disappears. This is the port you are looking for. (If only one shows up, that is your Edison's port.) + + ![Port Select](../Images/Edison/port.png) + + - Open PuTTY, and change from SSH to Serial. It normally defaults to COM1 and speed of 9600. Change the COM number to the number you found when you plugged into the Explorer board. Change the speed (baud rate) to 115200. + + ![Putty port](../Images/Edison/putty_port.png) + - Once you've made those changes, Click on OPEN at the bottom of your Putty configuration window. + - Continue with the All platforms section below. + +## All platforms: + - Once the screen comes up, press enter a few times to wake things up. This will give you a "console" view of what is happening on your Edison. + - Now you will see a login prompt for the edison on the console screen. + - Don't resize your console window: it will likely mess up your terminal's line wrapping. (Once you get wifi working and connect with SSH you can resize safely.) + +If you have a problem getting to the Edison login prompt, and possibly get a warning like "can't find a PTY", exit your console window. Then unplug the usb cables from your computer (not from the Edison... leave those ones as is) and swap the USB ports they were plugged into. Then try the above directions again. Usually just changing the USB ports for the cables will fix that "can't find a PTY" error. + +### Not sure of your password? + +You should have changed your rig's root password during setup; if not, please [go back and do so now](../Build Your Rig/step-1-flashing). The default password is most likely "edison" without quotes, but check the slip of paper that might have come with your pre-flashed Edison. \ No newline at end of file diff --git a/docs/docs/Build Your Rig/mac-prep.md b/docs/docs/Build Your Rig/mac-prep.md deleted file mode 100644 index b5ddcd847..000000000 --- a/docs/docs/Build Your Rig/mac-prep.md +++ /dev/null @@ -1,37 +0,0 @@ -# Mac users: Use Terminal to log into your rig - -## Plug into your rig - -Plug both cables into the rig and your Mac. - -![Explorer Board rig with two cables and red light on](../Images/Edison/ExplorerBoard_two_charging_cables.png) - -Once you plug in the cables, you should see your Edison board in your Finder as a connected “device” (similar to what you would see if you plug in a USB thumb drive). If you don’t… 1) Try unplugging and replugging the existing cables; 2) try different cables. If your USB port is bad and not recognizing the device, you may need to [reset your SMC first](https://support.apple.com/en-au/HT201295) (it’s not hard to do, takes 2 minutes.) - -![Edison in Finder](../Images/Edison/Edison_in_Finder_folder.png) - -## Open Terminal - -Go to your Applications folder and find the Terminal App in the Utilities folder. Double click to open it. - -![Terminal example](../Images/Edison/Terminal_example.png) - -Terminal is how we communicate with the Edison. Basically, the Edison is a computer that lacks a keyboard and display. By using a cable connected to the rig, we can login to the Edison and use Terminal as a way of interacting with the Edison. - -When you first launch Terminal, you will probably see something rather plain like below. The important thing to know is that the Terminal helps show you WHERE you are in your computer or Edison. So, in the screenshot below, it’s telling me I am in my “iMac4K” user account. If you are ever a little confused where you are…you can look to the left of the $ prompt and get an idea. - -![Terminal](../Images/Edison/Inside_terminal.png) - -## Log into your rig - -First, copy and paste: `sudo screen /dev/tty.usbserial-* 115200`, then hit enter. - -You’ll most likely be asked for your **computer password**. Enter it, but don't expect to see the characters logging as you type. Terminal app doesn't show keystrokes for password entries. A blank screen will likely come up, then press enter to wake things up to show an Edison login prompt. Use login: “root” and the password will likely be "edison". No quotes on either. If you purchased a preflashed board from Hamshield...a slip of paper is included that will confirm the password to use. Unflashed edisons do not have a password initially. - -If you have a problem getting to the Edison login prompt, and possibly get a warning like "can't find a PTY", close that terminal window. Then unplug the usb cables from your computer (not from the Edison...leave those ones as is) and swap the USB ports they were plugged in. Open a new terminal window, use the `sudo screen /dev/tty.usbserial-* 115200` command again. Usually just changing the USB ports for the cables will fix that "can't find a PTY" error. - -(**Note**: In the future, you will log into your rig by typing `ssh root@edison.local`, when you do not have the rig plugged into your computer. Also note that if you change your hostname, it will be `ssh root@whatyounamedit.local`) - -You should now see the command prompt change to be root. - -Head back to the other docs to continue the setup process. diff --git a/docs/docs/Build Your Rig/step-1-flashing.md b/docs/docs/Build Your Rig/step-1-flashing.md new file mode 100644 index 000000000..6a88c358a --- /dev/null +++ b/docs/docs/Build Your Rig/step-1-flashing.md @@ -0,0 +1,349 @@ +# Step 1: Jubilinux (for Edison rigs only) + +This is only necessary for Edison rigs. Pi users can skip to +[step 2](step-2-wifi-dependencies). If you purchased a pre-flashed Edison, you can also skip on down to [step 2](step-2-wifi-dependencies). + +The steps outlined below include instructions for the various build-platforms (Windows PC, Mac, and Raspberry Pi). Linux users in general should be able to follow the steps for the Raspberry Pi. + +## What is flashing? + +The Edison comes with a very limited operating system, called Yocto, that doesn’t work easily with OpenAPS. The first step is to replace the operating system with a new one. This is called “flashing” the Edison. + +It's best to replace this with a custom version of Debian, as this fits best with OpenAPS, and it also means you have the latest security and stability patches. (These setup instructions were pulled from the mmeowlink wiki; if you're an advanced user and want/need to use Ubilinux instead of the recommended Jubilinux, [go here](https://github.com/oskarpearson/mmeowlink/wiki/Prepare-the-Edison-for-OpenAPS).) The setup instructions also are going to assume you're using the Explorer Board that has a built in radio stick. If you're using any other base board and/or any other radio sticks (TI, ERF, Rileylink, etc.), check out [the mmeowlink wiki](https://github.com/oskarpearson/mmeowlink/wiki) for support of those hardware options. + +## 1. Prerequisites + +### If you’re using a Raspberry Pi: + +To flash the Edison using a Raspberry Pi, you’ll need a large (preferably 16GB+) SD card for your Pi. The Edison image is almost 2GB, so you’ll not only need space for the compressed and uncompressed image, but you’ll also need to enable a large swapfile on your Pi to fit the image into virtual memory while it is being flashed. Using an SD card as memory is very slow, so allow extra time to flash the Edison image using a Pi. + + - Run `sudo bash -c 'echo CONF_SWAPSIZE=2000 > /etc/dphys-swapfile'` to configure a 2GB swap file. + *Note: if you don't have enough space on the SD card for a 2G swap a 1G swap will probably work* + - Run `sudo /etc/init.d/dphys-swapfile stop` and then `sudo /etc/init.d/dphys-swapfile start` to enable the new swap file. + - If you installed `watchdog` on the pi, it's a good idea to stop it since loading the image into memory to flash is intensive + +### Windows PCs with under 6 GB of RAM + +Windows PCs with less than 6 GB of RAM may need to have the size of the page file increased to flash the Edison. Close all unnecessary programs and attempt to flash the device. If the flash operation fails follow these steps to ensure enough swap space is allocated when the computer boots, then restart and try again. Only do this if flashing the device doesn't work without changing these settings. + +*Important: Write down the settings in the Virtual Memory window before you make any changes to your system. When you finish the flash process you must return these settings to their original values or Windows may become unstable.* + + - Go to the Control Panel, click All Control Panel Items, then click System. At top left click the Remote Settings link. + - Select the Advanced tab in the System Properties window, then under Performance click Settings. + - On the Advanced tab click the Change... button to change the page size. + - In the Virtual Memory window uncheck "Automatically manage paging file size for all drives," click "Custom size," and set the initial size to at least 4096 MB. If you have already attempted this process at least once continue to increase this number by 1024 MB. Set the maximum size to 2048 MB higher than the initial size you used. + - Click the Set button, then click OK until all windows are closed. + - Reboot and attempt the flash process. + +### If you're using a Mac: + +- Install Homebrew, a tool which allows you to easily install other software packages and keep them up to date. Enter the following command in the Terminal app to install Homebrew: + + ```ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)``` + + You will be prompted to enter “RETURN” to continue and then enter your passcode for the user account (your computer password). When you type the password, you will not see any letters appear in the Terminal screen--that is normal. Terminal does not show keystrokes for passwords. + +![Enter return example](../Images/Edison/Enter_return.png) + +It will take about 1-2 minutes for Homebrew to install. You’ll see a bunch of commands scrolling by in Terminal window. Just wait it out until you see the screen showing Installation successful and you’ll be returned to the Terminal prompt. + + If you get a message that Homebrew is already installed, that's also fine! + +- Install several other utilities by entering the command: + + ```brew install dfu-util coreutils gnu-getopt``` + +![After installing other stuff](../Images/Edison/After_install_other_stuff.png) + +- If you are reflashing an Edison, you might see a recommendation to upgrade coreutils, in which case, run `brew upgrade coreutils gnu-getopt` + +- Install lsusb: + +`brew update && brew tap jlhonora/lsusb && brew install lsusb` + +![After installing lsusb](../Images/Edison/after_install_lsusb.png) + +The above instructions are based on [these instructions](https://software.intel.com/en-us/node/637974#manual-flash-process) which may be useful as a reference. + +## 2. Downloading Jubilinux image + +[Jubilinux](http://www.jubilinux.org/) "is an update to the stock ubilinux edison distribution to make it more useful as a server, most significantly by upgrading from wheezy to jessie." That means we can skip many of the time-consuming upgrade steps that are required when starting from ubilinux. + + - Download [Jubilinux](http://www.jubilinux.org/dist/) - the jubilinux-v0.3.0.zip is known to work; jubilinux 0.2.0 runs Debian jessie, which is NOT supported by Debian any longer. + - In the download folder, right-click on file and extract (or use `unzip jubilinux.zip` from the command line). You will access this directory from a command prompt in the next step. It is a good idea to create the Jubilinux in your root directory to make this easier to access. + + **Note** On Windows, you should see an `extract all` option when you right-click. However, in some instances, it may not be active for zipped files. If you do not see the `extract all` option in the right-click menu, right-click the zipped file, choose `Properties` at the bottom of the context menu. On the General tab, click on the button next to the "opens with" and change it to use Windows Explorer. Apply the change and select `OK` to save the change. You should now be able to right-click the jubilinux.zip file to extract all. + + - Open a Terminal (Mac) or Command Prompt (Windows) window and navigate to the extracted folder: `cd jubilinux`. This is your "flash window." Keep it open for later! + + - If using Windows, you will need two additional utilities. Download [DFU-Util](https://cdn.sparkfun.com/assets/learn_tutorials/3/3/4/dfu-util-0.8-binaries.tar.xz). Extract the two files, libusb-1.0.dll and dfu-util.exe, to the directory where you extracted jublinux.zip. (Alternately, you can download the two files [libusb-1.0.dll](http://dfu-util.sourceforge.net/releases/dfu-util-0.8-binaries/win32-mingw32/libusb-1.0.dll) and [dfu-util.exe](http://dfu-util.sourceforge.net/releases/dfu-util-0.8-binaries/win32-mingw32/dfu-util.exe) directly.) When you have successfully moved those two folders into the jubilinux folder, you should see files/folders inside the jubilinux folder like so: + +![Ready to Flashall](../Images/Edison/ready.png) + +## 3. Connecting cables to the Explorer Board and starting console + +Now we move to the rig. You'll need to connect two cables from the rig to your computer. +Follow the [console login directions](<../Build Your Rig/logging-into-rig-serial>) to get set up. + +Once you get to the login prompt, log in using the username "root" (all lowercase) and no password. This will have us ready to reboot from the command line when we are ready. This is your "console window" - keep it open. + +If you do not have your Edison password at this point, don't panic. We are only logging in to reboot the Edison and that can be accomplished via the black button on the explorer board as well. Without the root password you may continue. + +## 4. Flashing image onto the Edison + +### If you’re using a Raspberry Pi - starting flash: + - In the "flash window" from the Download Image instructions above, run `sudo ./flashall.sh`. If you receive an `dfu-util: command not found` error, you can install dfu-util by running `sudo apt-get install dfu-util` + +### If you’re using a Mac - starting flash: + - In the "flash window" from the Download Image instructions above, run `./flashall.sh`. + - If you receive an `dfu-util: command not found` error, you can install dfu-util by following [the Mac instructions here](https://software.intel.com/en-us/node/637974#manual-flash-process). + - If you receive an `Error: Running Homebrew as root is extremely dangerous and no longer supported. As Homebrew does not drop privileges on installation you would be giving all build scripts full access to your system.` see the troubleshooting section below. + +### If you're using a Windows PC - starting flash: + - In the "flash window" from the Download Image instructions above, run `flashall.bat` + +### All platforms: + - The flashall script will ask you to "plug and reboot" the Edison. + - If you have your edison root password: Go back to your console window and type `reboot`. + - If you do not have your edison root password: Press the black button on the explorer board until the LED between the usb connectors shuts off. Then press it again until the light comes back on. + - Switch back to the other window and you will see the flash process begin. You can monitor both the flash and console windows throughout the rest of the flash process. If nothing else works and you are feeling brave, you can try pulling the Edison out and reconnecting it to the board to start the flash process. + - In the console window where you typed `reboot`, you should see: + +``` +Hit any key to stop autoboot: 0 +Target:blank +Partitioning using GPT +Writing GPT: success! +Saving Environment to MMC... +Writing to redundant MMC(0)... done +Flashing already done... +GADGET DRIVER: usb_dnl_dfu +# +DFU complete CRC32: 0x77ccc805 +DOWNLOAD ... OK +Ctrl+C to exit ... +###################################################################################################################### +``` + And in the flash window, you should see +``` +Using U-Boot target: edison-blankcdc +Now waiting for dfu device 8087:0a99 +Please plug and reboot the board +Flashing IFWI +Download [=========================] 100% 4194304 bytes +Download [=========================] 100% 4194304 bytes +Flashing U-Boot +Download [=========================] 100% 245760 bytes +Flashing U-Boot Environment +Download [=========================] 100% 65536 bytes +Flashing U-Boot Environment Backup +Download [=========================] 100% 65536 bytes +Rebooting to apply partition changes +Now waiting for dfu device 8087:0a99 +Flashing boot partition (kernel) +Download [=========================] 100% 5980160 bytes +Flashing rootfs, (it can take up to 10 minutes... Please be patient) +``` + + - Like it says, it will take about 10 minutes to flash from Mac or Windows. If the step that flashall says should take up to 10 minutes completes in seconds, then the flash did not complete successfully, perhaps because you didn't set up the virtual memory / swap settings correctly; check the troubleshooting section. If you’re using a Raspberry Pi, it may take up to 45 minutes, and for the first 10-15 minutes it may appear like nothing is happening, but eventually you will start to see a progress bar in the console. + - After flashing is complete and the Edison begins rebooting, watch the console: you may get asked to type `control-D` to continue after one or more reboots. If so, press `Ctrl-d` to allow it to continue. + - The Edison will reboot several times. You may see +``` +[** ] A start job is running for /etc/rc.local Compatibili...14s / no limit) +``` +for a few minutes: that's fine. You can also expect to see an ugly red: +``` +[FAILED] Failed to start Hostname Service. +``` +That is also fine, and you can ignore it too. Just about when you'll start to get concerned that it is stuck in a loop, you should get a login prompt. If so, congratulations! Your Edison is flashed. Use login `root` and password `edison` to login to your newly flashed Edison. + +After logging in, you will notice that the Terminal prompt says `root@ubilinux:~#`. This is the correct prompt for the jubilinux system. You will not see jubilinux in the prompt. If you bought a pre-flashed Edison, this is how your initial Terminal prompt will look. + +![Terminal Prompt for Jubilinux](../Images/Edison/name.png) + +If you have any difficulty with flashing, skip down to [Troubleshooting](#troubleshooting) + +After you've flashed your Edison, head on to [step 2 - setting up wifi and installing dependencies](step-2-wifi-dependencies) + + +## Troubleshooting + +### Troubleshooting the flash process + +a) If you get: +``` +dfu-util: Device has DFU interface, but has no DFU functional descriptor +dfu-util: Cannot open DFU device 8087:0a99 +``` +that likely means you ran ./flashall.sh without sudo. + +b) If you get: +``` +Flashing rootfs, (it can take up to 10 minutes... Please be patient) +dfu-util -v -d 8087:0a99 --alt rootfs -D /home/pi/toFlash/edison-image-edison.ext4 -R 2>&1 | tee -a flash.log | ( sed -n '19 q'; head -n 1; cat >/dev/null ) +Rebooting +U-boot & Kernel System Flash Success... +``` +in something closer to 10 seconds than 10 minutes, then you likely didn't set up swap properly. To verify, `cat flash.log` and look for `dfu-util: Cannot allocate memory of size 1610612736 bytes` near the end. +Alternatively, [this newer version of DFU Util](https://sourceforge.net/projects/dfu-util/files/latest/download) (DFU Util v0.9) seems to work better on computers with lots of RAM. + +c) If you recieve an `Error: Running Homebrew as root is extremely dangerous and no longer supported. As Homebrew does not drop privileges on installation you would be giving all build scripts full access to your system.` it means that you have a recent copy of homebrew (that's good) which doesn't allow sudo to even do a `brew list`. + + * The _easiest_ - but perhaps not so forward compatible - thing is to figure out what the brew command was trying to do and edit the `flashall.sh` script accordingly. + ** The v0.2.0 version of `flashapp.sh` has `$(brew list gnu-getopt | grep bin/getopt)`. + ** Running `brew list gnu-getopt | grep bin/getopt` for me (Dec 2017) gave me `/usr/local/Cellar/gnu-getopt/1.1.6/bin/getopt` + * Edit the `flashall.sh` from + ``` + :bash + GETOPTS="$(which getopt)" + if [[ "$OSTYPE" == "darwin"* ]] ; then READLINK=greadlink; GETOPTS="$(brew l ist gnu-getopt | grep bin/getopt)"; else READLINK=readlink;fi; + ``` + + to + + ```:bash + GETOPTS="$(which getopt)" + if [[ "$OSTYPE" == "darwin"* ]] + then + READLINK=greadlink + GETOPTS=/usr/local/Cellar/gnu-getopt/1.1.6/bin/getopt + else + READLINK=readline + fi + ``` + +d) If you have a failed flash or have problems with the reboot, try starting the console and hitting enter a bunch of times while connecting to stop autoboot. You'll then be at a `boot>` prompt. Run `sudo ./flashall.sh` and when it asks you to reboot type and enter `run do_flash` at the `boot>` prompt. + +e) If you get stuck on an error that says "Ready to receive application" on the Edison the problem is you don't have enough power to properly boot up the Edison. This can happen if you are powering from your Pi. You should either connect a battery to the Edison board to give it a little boost, or use a powered USB hub between the Pi and the Edison. + +f) If Edison reboots correctly but never gets picked up by the flashall.sh script and the flashing process does not start, check that you have DATA micro USB to USB cables - both of them. A large proportion of USB cables are not "data" - just power - and even cables previously used for data can degrade to no longer reliably carry data. How do you know if each cable is for data? One good way is to unplug both cables from the Edison, plug each cable in turn into your computer USB port and the explorer board OTG port. If your folder/window explorer shows Edison as a drive then the cable supports data. You need both to be data cables. + +g) If Edison reboots correctly but never gets picked up by the flashall.sh script and the flashing process does not start, and you've re-confirmed that the two cables you are using are indeed good data cables, check the Edison device ID. It will probably come out automatically after the flashall.sh script fails with a list of available devices connected to the machine. On Linux, you can run lsusb to get a list of usb devices with their device ID. If the device ID is different from the one expected on flashall.sh, you can edit the script and change lines containing: USB_VID=8087 & USB_PID=0a99 to whatever the Edison has for an ID. Some users have encountered their devices ID to be 8087:0a9e + +h) If you have attempted the firmware flash with Jubilinux several times and the flash will not complete successfully, it is highly recommended that you follow the mmeowlink [deprecated Ubilinux instructions](https://github.com/oskarpearson/mmeowlink/wiki/Prepare-the-Edison-for-OpenAPS#ubilinux-deprecated). Note that those instructions will have notes throughout for steps which are specific to the flash of Ubilinux. Additional steps help to align the Edison's operating system with Jubilinux. You must do these steps. + +If you're having issues with a *Windows* flash of Jubilinux, try following along with the videos below. OpenAPS users have cited their instructions in successful flashes of Ubilinux. You will still need to go through the extra Ubilinux configuration steps mentioned in the linked mmeowlink wiki above. + +1. [Flash Ubilinux Onto Intel Edison via Windows, 5 Part Video](https://www.youtube.com/watch?v=L57RC8POJzM) (Cygwin) +2. [uCast #21: Installing Ubilinux on the Edison (Windows)](https://www.youtube.com/watch?v=BSnXjuttSgY&t=16s) (Windows Command Prompt) + +i) If none of the above has worked with the Explorer board, try swapping the two microUSB cables, or replacing them with new ones. See "f)" above too. + +j) If you've attempted all of the troubleshooting steps above but still aren't successful, it's worth trying to use a different computer to flash. + + +### Troubleshooting rescue mode + +* If your edison boots to a console and says it is in rescue mode (you can hit ctrl-d to continue or enter the root password), you may need to change a u-boot environment variable to make it boot normally. During the boot process you will see: +``` +*** Ready to receive application *** + + +U-Boot 2014.04 (Feb 09 2015 - 15:40:31) + + Watchdog enabled +DRAM: 980.6 MiB +MMC: tangier_sdhci: 0 +In: serial +Out: serial +Err: serial +Hit any key to stop autoboot: 0 +``` +1. Hit any key to drop to a prompt and type: +`printenv bootargs_target` +2. If the answer is +`bootargs_target=first-install` +then type: +`setenv bootargs_target multi-user` +`saveenv` +3. And to exit that firmware u-boot prompt: +`run do_boot` + +* If this doesn't fix the problem, and your boot gets stuck here: +``` +[ OK ] Mounted /home. + + Starting Rescue Shell... + +[ OK ] Started Rescue Shell. + +[ OK ] Reached target Rescue Mode. +``` +You may have an issue with the flashall.sh script. (This seems to only impact mac users). +In the "flash window" terminal where you downloaded Jubilinux + +1. Edit the flashall script +`nano flashall.sh` +2. Find the following text (around line 220) Your text may vary slightly, with additional echo statements or such +``` +echo "Flashing U-Boot Environment Backup and rebooting to apply partiton changes" + flash-command --alt u-boot-env1 -D "${VARIANT_FILE}" -R + + dfu-wait +``` +3. Modify this line to remove the -R and the dfu-wait command +``` +echo "Flashing U-Boot Environment Backup and rebooting to apply partiton changes" + flash-command --alt u-boot-env1 -D "${VARIANT_FILE}" +``` +4. Reboot one last time - install should take a good deal longer than previous executions. + + +### Override DNS resolvers + +Some users have reported problems with connecting to internet sites. If you are experience poor internet connections, try 'nano /etc/resolv.conf' and change the first two nameservers to: + + nameserver 8.8.4.4 + nameserver 8.8.8.8 + +Also see the instructions [here](https://wiki.debian.org/NetworkConfiguration#The_resolvconf_program) to add these nameservers to your `/network/interfaces` file as the `resolv.conf` file is likely to be overwritten. + +Alternatively, add the nameservers you want to see in `resolv.conf` to `/etc/resolvconf/resolv.conf.d/tail` and they'll be automatically added to `resolv.conf`. (You may need to create the folder by running this command first: `mkdir -p /etc/resolvconf/resolv.conf.d`) + + +### IP address conflicts (able to ping external but not LAN addresses) + +Some users have reported problems where the local router uses the same IP block as that of usb0 config. The default configuration for usb0 in `/etc/network/interfaces` uses 192.168.2.15, so if your local router also uses 192.168.2.xx you may not be able to properly connect to your Edison using SSH, and external connectivity may intermittently fail. + +To check which IP address your router is using, you can run `ipconfig` on Windows or `ifconfig` on Mac/Linux. If you're getting an address starting with 192.168.2.x, you'll want to edit your Edison's configuration to use a different subnet for usb0: + +Use `vi /etc/network/interfaces` to edit the static usb0 interface address from 192.168.2.15 to another valid private IP, like 192.168.29.29. The resulting config 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.29.29 + netmask 255.255.255.0 + +auto wlan0 +iface wlan0 inet dhcp + wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf +``` + +Once that looks correct, save the file and `reboot` your rig for the changes to take effect. + + +### Interrupting Kernel Messages in Console/Screen Mode + +![Example kernel message](https://user-images.githubusercontent.com/24418738/27111189-17c4acd8-5074-11e7-8873-54470e94c638.jpg) + +#### Fix for individual console/screen session: + +Type this at the prompt: `dmesg -D` + +#### Permanent solution: + +`vi /etc/rc.local` +press i for insert mode + +add this line: sudo dmesg -n 1 + +![adding dmesg](https://user-images.githubusercontent.com/24418738/27111188-17c46c3c-5074-11e7-8a5f-d29c85873293.jpg) + +(remember to save and exit the vi editor by using esc and then :wq) + + diff --git a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md new file mode 100644 index 000000000..ce5d2fcc8 --- /dev/null +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -0,0 +1,455 @@ +# Step 2: Wifi and Dependencies + +The directions for this step depend on which type of rig you are using: + +- [Intel Edison](#Intel-Edison-instructions) + +- [Raspberry Pi](#Raspberry-Pi-instructions) + +## Intel Edison instructions + +### Prep Computer and Login to rig + +To get your first wifi connection set up and install OpenAPS, you'll need to log in to the rig via the console. Follow the [console login directions](<../Build Your Rig/logging-into-rig-serial>) to get a console window open, then 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, which will set up 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/master/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](<../Build Your Rig/step-3-setup-script>) for finishing step 3. + +Now that you have a wifi connection to your rig, you have the option of [logging into it using SSH](<../Usage and maintenance/monitoring-OpenAPS#accessing-your-online-rig-via-ssh>) from a computer on the same network, rather than using a cable. + +### Manual instructions for Intel Edison + +Below are the manual instructions for reference only - it is strongly recommended that you use the bootstrap script above instead. + +#### Initial Edison Setup + +Log in as root/edison via serial console. + +Type/edit the following: + + myedisonhostname= #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. Make sure you save them somewhere - you will need them! 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` + +A screen similar to the one below will appear. Type “i” to enter INSERT mode for editing on the file. + +![Wifi edit screen](../Images/Edison/Wifi_edit_screen.png) + +Type 'i' to get into INSERT mode. In 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 (add # at the start of the line) 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 (save) the file and quit. + +To set up a wireless connection, enter + +`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. If you have a hidden wifi network add the line `scan_ssid=1`. + + +``` +network={ + ssid="my network" + psk="my wifi password" +} +``` + +The networks you enter here are the wifi networks that your rig will be able to use to stay connected to internet. After getting your initial wireless connection set up, you can return to [the instructions for adding additional wireless connections ](<../Usage and maintenance/Wifi/on-the-go-wifi-adding>) to add more options to your rig at any point. + +![Wifi edit screen](../Images/Edison/Wifi_add.png) + +On a Mac, if you experience any erratic behavior while using the screen editor, such as the cursor overwriting or deleting adjacent words when typing or even when using the cursor arrow keys, this may be due to incorrectly set Mac Terminal window settings. Try going to the "Shell" on the menu bar above and selecting "Show Inspector." Ensure the Columns setting is set to "80" and the Rows setting is set to "25." + +Press Esc and then type ':wq' and press Enter to write the file and quit. + +Run `ifup wlan0` to make sure you can connect to wifi. A successful connection should look similar (IP address numbers will be different than mine): + +![ifup wlan0 example](../Images/Edison/ifup_wlan0.png) + +Make sure you see a message showing you are successfully connected, then `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. If the rig isn't online, go back and check your /etc/network/interfaces and /etc/wpa_supplicant/wpa_supplicant.conf files above: you probably either missed a step or made a typo. + +Note: If you are reflashing an Edison, you might get a scary looking error about "WARNING: POSSIBLE DNS SPOOFING DECTECTED WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!" that is likely because you are attempting to login to a rig that has the same hostname as a previous rig that has been logged into on the computer. You can delete the history of known hosts for the rig by entering the commands `cd .ssh` and then `rm known_hosts`. This will delete the log of known hosts on your computer. There's no significant downside to removing the known_host log, except that you will need to answer yes to the key fingerprint additions again for the first time you login to old rigs again. + +![Mac spoofing error](../Images/spoof-no-box.png) + +Run `ifconfig wlan0` to determine the IP address of the wireless interface, in case you need it to SSH below. Alternatively, if you know how to login to your router, you can also see the Edison's IP address there. + +![IP address](../Images/Edison/ip_address.png) + +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. + +If you see warnings about the authenticity of host can't be established, you can say yes to continue and add the new edison to your known hosts list. This message typically appears when you've set-up multiple edisons on the same computer. + +Log in as root (with the password you just set above), and run these three lines one by one. The first line "dpkg -P ... " will be quick. Check the printout to see that it ran without error. Then run the apt-get lines one at a time. They may take several minutes. + + + 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 these three (the first two will be fast, the last line will take you to a screen for setting up your timezone): + + 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 then hit ENTER + +![Time zone examples](../Images/Edison/Time_zone.png) + +Enter `vi /etc/logrotate.conf`, press “i” for INSERT mode, and make the following changes: + + * set the log rotation to `daily` instead of `weekly` + * remove the # from the “#compress” line, in order to enable log compression; this reduces the probability of running out of disk space + +Press ESC and then type “:wq” to save and quit + +![Log rotation examples](../Images/Edison/log_rotation.png) + +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](<../Resources/Deprecated-Pi/Pi-setup#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 +``` + + + +## Raspberry Pi instructions + +Note: there are two key ways to setup a Pi rig. One uses Pi Bakery, the other is a manual method. If your Pi Bakery process does not work, just use [Option B](<#option-b>). + +### Option A - Use Pi Bakery + +There are many ways setup Raspian (the operating system...like jubilinux is for Edison board) microSD card to use in your Raspberry Pi. One easy way for a new user is to use PiBakery, a free application you'll download from the internet. (Note that if this is not successful, you can switch to [Option B](<#option-b>) below). + +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`. If you receive a warning that the rig's host key is not yet cached, respond YES to add it. + +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 +``` + +* 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`** + +* 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. + +* 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. + +!["install piBakery"](../Images/build-your-rig/pi-curl-success.png) + +**If you are installing to a Pi with a legacy radio (Ti-stick, SliceOfRadio, etc.) - Press enter. [Jump to finishing the installation](#finish-installation)** + +**If you are installing to a newer Pi with a HAT or RFM69HCW as radio: Do not press enter! [Continue on to Pi-Hat instructions.](#switch-to-dev-branch-for-your-pi-hat).** + +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) + + +#### Switch to dev branch for your pi HAT +If you are here - you should be building a rig with a Pi HAT(recommended) or RFM69HCW (experimental). 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` on a Mac. On a Windows PC with PuTTY, the hostname can be either `yourrigname` or `yourrigname.local`, and the username will be `root`. + +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". + +#### Finish installation + +First, update npm to the latest version. Run `npm install npm@latest -g`. + +Next, change to the oref0 directory if you are not in it already. Run `cd ~/src/oref0`. + +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. +!["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) + +Once your setup script finishes, **make sure to [watch the pump loop logs](<../Build Your Rig/step-4-watching-log>)** + +**NOTE**: If you are using RFM69HCW as RF module: + +If you have connected your RFM69HCW module as described in [Soldering RFM69HCW](<../Gear Up/pi-based-rigs#soldering>), while running interactive setup use following options: +```Are you using an Explorer Board? [Y]/n n +Are you using an Explorer HAT? [Y]/n n +Are you using mmeowlink (i.e. with a TI stick)? If not, press enter. If so, paste your full port address: it looks like "/dev/ttySOMETHING" without the quotes. +What is your TTY port? /dev/spidev0.0 +Ok, TTY /dev/spidev0.0 it is. + +Would you like to [D]ownload released precompiled Go pump communication library or install an [U]nofficial (possibly untested) version.[D]/U u +You could either build the Medtronic library from [S]ource, or type the version tag you would like to use, example 'v2018.08.08' [S]/ s +Building Go pump binaries from source +What type of radio do you use? [1] for cc1101 [2] for CC1110 or CC1111 [3] for RFM69HCW radio module 1/[2]/3 3 +Building Go pump binaries from source with + radiotags + tags. +``` +after running oref0-setup.sh run the following: +```$ cd ~ && export PATH="$PATH:/usr/local/go/bin" +$ rm -rf ~/go/src/github.com/ecc1 +$ go get -u -v -tags "rfm69 walrus" github.com/ecc1/medtronic/... +$ cp -pruv $HOME/go/bin/* /usr/local/bin/ +$ mv /usr/local/bin/mmtune /usr/local/bin/Go-mmtune +``` +This will help in building the right pump communication libraries. + +* You'll want to also delete the openaps-menu folder to avoid error messages in your logs. `rm -rf ~/src/openaps-menu/` +* If you experience something like this: +```mmtune: radio_locale = WW +2019/01/14 15:14:25 cannot connect to CC111x radio on /dev/spidev0.0 +2019/01/14 15:14:25 cc111x: no response +Usage: grep [OPTION]... PATTERN [FILE]... +Try 'grep --help' for more information. +``` +That means you have probably run the oref-runagain.sh script. Currently, with RFM69HCW, you can't use the runagain script. Please run the interactive setup script (`cd && ~/src/oref0/bin/oref0-setup.sh`). Other option would be you didn't solder diligently enough. Before disassembling and resoldering, try running the interactive script first. It's less work. + + +***************************** + +### Option B + +#### Download Raspbian and write it to your microSD card + +Following the [install instructions](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. The file must be in a Unix format. If creating the file in Windows, use an editor that allows you to save the file in Unix format instead of DOS format. There are many editors with this ability. `Notepad++` is one that works well. The file should look something like: + +``` +country=xx +ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev +update_config=1 +network={ + ssid="MyWirelessNetwork" + psk="MyWirelessPassword" +} +``` + +You will need to replace xx after country with the correct ISO3166-1 Alpha-2 country code for your country (such as US, UK, DE, etc) - otherwise wifi will remain disabled on the Pi. + +To enable SSH login to the Pi, you will need to create an empty file named `ssh` (with no file extention). +On Windows, you can make this file appear on your Desktop by opening the command prompt and typing: +``` +cd %HOMEPATH%\Desktop +type NUL > ssh +``` +On a Mac, the equivalent command is: +``` +cd ~/Desktop/ +touch ssh +``` + +When you are done, copy it from your Desktop to the boot drive of your SD card. + +#### 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 and establish an SSH connection, with username `pi`, to hostname `raspberrypi.local`. + +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 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. + +* 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+ minutes) before asking you to press `enter` to run oref0-setup. + +Return to the [setup script page](<../Build Your Rig/step-3-setup-script>) to complete oref0-setup. + +**If you are installing to a Pi with a legacy radio (Ti-stick, SliceOfRadio, etc.) - Press enter. [Jump to finishing the installation](<#finish-installation>)** + +**If you are installing to a newer Pi with a HAT as radio: Do not press enter! [Continue on to Pi-Hat instructions.](<#switch-to-dev-branch-for-your-pi-hat>).** diff --git a/docs/docs/Build Your Rig/step-3-setup-script.md b/docs/docs/Build Your Rig/step-3-setup-script.md new file mode 100644 index 000000000..d198edde2 --- /dev/null +++ b/docs/docs/Build Your Rig/step-3-setup-script.md @@ -0,0 +1,210 @@ +# 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. + +Log in to your rig and run the following command (aka "the setup script"): + + `cd && ~/src/oref0/bin/oref0-setup.sh` + +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! + +* 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](<../Usage and maintenance/Wifi/bluetooth-tethering-edison>) 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) + +![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 + +
+ Click here to expand notes about checking log rotate, which was fixed in 0.6.1: +
+ +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) + +
+ +## 512 and 712 Pump users only - important extra setup steps + +If you have one of the x12 model pumps, you can still successfully use OpenAPS for basic looping (but not some advanced featuers like SMB). You'll need to complete some extra setup tweaks before your loop will be successful, however. + +Note: If you have an old rig running oref0 0.5.3 or below, you'll need to follow historical instructions. The instructions below reflect the adjusted oref0-setup.sh in 0.6.0 and beyond, that does some of this work manually. + +### Most important step - make sure you said yes (y) in oref0-setup.sh + +During the interactive setup script, one early question is about whether you have an x12 pump. This means you, if you have a 512 or 712 pump you're setting up. Make sure to type Y or y and see the confirmation that you'll be using an x12 pump. + +### Edit the three (3) necessary files: basal, settings, and targets + +At the end of the oref0-setup.sh script, it will open the most important file for you to edit - your basal profile. Edit this file to match your preferred basal rates and timing. + +``` +Note: The "minutes" is "minutes from midnight". e.g., a basal starting at 5:00am +will have a minutes entry of 5 x 60 = 300 minutes and a basal starting at 7:30am +will have a minutes entry of 7.5 x 60 = 450 minutes. +If you have a basal rate less than 1.0 unit/hour, +make sure to include a zero before the decimal point such as `0.55` +``` + +After you ctrl-x and hit "y" to save the file, you'll also see a reminder to further adjust other files with your settings in order to loop off of your information. + +* If you need to edit your basal rate file in the future, simply type `nano ~/myopenaps/settings/basal_profile.json` from the command line. + +To edit and set your maxBasal or your DIA: +* `nano ~/myopenaps/settings/settings.json` + +Finally, to set your targets: +* `nano ~/myopenaps/settings/bg_targets_raw.json` + + +#### Examples of the three file types + +To see examples of each of these three files, see below. + +##### Sample file for settings.json + +notes are added with `#` on the lines you want to adjust or pay attention to in particular + +``` +{ + "maxBasal": 1.5, #adjust to your preferred max temp basal rate + "temp_basal": { + "percent": 100, + "type": "Units/hour" + }, + "insulin_action_curve": 6 #adjust to your selected duration of insulin action in whole hour increments +} +``` + +##### Sample file for bg-targets-raw.json + +Note: the "offset" entry is the minutes since midnight for that particular target to start. The profile always starts with a midnight rate first, offset is 0. The next BG target, in this example, starts at 6 am and therefore has an offset of 360 minutes (6 hours from midnight at 60 minutes per hour). Target range can have the same bg value for high and low, if desired, but be careful not to have a high target set lower than the low target. + +You can add or delete bg targets to the sample file below, but pay close attention to syntax. The last bg target range in the profile needs end without a comma after the last `}` + +``` +{ + "units": "mg/dL", + "targets": [ + { + "high": 120, + "start": "00:00:00", + "low": 110, + "offset": 0, + "i": 0, + "x": 0 + }, + { + "high": 110, + "start": "06:00:00", + "low": 110, + "offset": 360, + "i": 12, + "x": 1 + }, + { + "high": 120, + "start": "20:00:00", + "low": 110, + "offset": 1200, + "i": 40, + "x": 2 + } + ], + "first": 1 +} +``` + +##### Sample file for selected-basal-profile.json + +Note: The format for the basal rates is the "minutes" value refers to the "minutes from midnight" for whatever rate schedule you are setting. For example, the 6:00 am rate in the example file below is a rate of 1.15 units/hour and 6:00 am is 360 minutes since midnight passed (6 hours x 60 minutes per hour). + +If you have a basal rate less than 1.0 unit/hour, make sure to include a zero before the decimal point such as `0.55` + +You can add or delete basal rates to the sample file below, but pay close attention to syntax. The last basal rate in the profile needs end without a comma after the last `}` + +``` + [ + { + "i": 0, + "start": "00:00:00", + "rate": 1.15, + "minutes": 0 + }, + { + "i": 1, + "start": "02:30:00", + "rate": 1.20, + "minutes": 150 + }, + { + "i": 2, + "start": "06:00:00", + "rate": 1.15, + "minutes": 360 + }, + { + "i": 3, + "start": "09:00:00", + "rate": 1.05, + "minutes": 600 + }, + { + "i": 4, + "start": "11:30:00", + "rate": 1.05, + "minutes": 690 + }, + { + "i": 5, + "start": "14:00:00", + "rate": 1.05, + "minutes": 840 + }, + { + "i": 6, + "start": "18:30:00", + "rate": 1.05, + "minutes": 1110 + }, + { + "i": 7, + "start": "23:00:00", + "rate": 1.05, + "minutes": 1380 + } + ] +``` diff --git a/docs/docs/Build Your Rig/step-4-watching-log.md b/docs/docs/Build Your Rig/step-4-watching-log.md new file mode 100644 index 000000000..d9ed55b2e --- /dev/null +++ b/docs/docs/Build Your Rig/step-4-watching-log.md @@ -0,0 +1,149 @@ +# Step 4: Watch your Pump-Loop Log + +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) +
+ Click here to expand the explanation of the non-error messages +
+ +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-24h-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 4:05am every morning. So if autotune has not yet run, you must wait for that error message to clear out, or run it manually. 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 oref0-pump-loop" and ending with "Completed oref0-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 - e.g. 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. ([For more details on how to interpret the OpenAPS math and information, see this page for understanding OpenAPS determine-basal](<../How it works/understand-determine-basal#summary-of-outputs>).) + +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](<../Troubleshooting/oref0-setup-troubleshooting>) 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? + +
+ Expand here for notes: +
+ +* 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 - bookmark this section! + +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?" or "what do the logs say?" + +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 (or at 4AM starting from 0.6.0-rc1), 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 other shortcuts: + +``` + --View live logs-- + l => tail -F /var/log/openaps/pump-loop.log + autosens-looplog => tail -n 100 -F /var/log/openaps/autosens-loop.log + autotunelog => tail -n 100 -F /var/log/openaps/autotune.log + ns-looplog => tail -n 100 -F /var/log/openaps/ns-loop.log + pump-looplog => tail -n 100 -F /var/log/openaps/pump-loop.log + networklog => tail -n 100 -F /var/log/openaps/network.log + xdrip-looplog => tail -n 100 -F /var/log/openaps/xdrip-loop.log + cgm-looplog => tail -n 100 -F /var/log/openaps/cgm-loop.log + urchin-looplog => tail -n 100 -F /var/log/openaps/urchin-loop.log + * to quit watching, press Ctrl+C + + --View settings/logs/info-- + cat-pref => cd ~/myopenaps && cat preferences.json + cat-wifi => cat /etc/wpa_supplicant/wpa_supplicant.conf + cat-autotune => cd ~/myopenaps/autotune && cat autotune_recommendations.log + cat-runagain => cd ~/myopenaps && cat oref0-runagain.sh + git-branch => cd ~/src/oref0 && git branch + edison-battery => cd ~/myopenaps/monitor && cat edison-battery.json + cat-reservoir => cd ~/myopenaps/monitor && cat reservoir.json + + --Edit settings-- + edit-wifi => vi /etc/wpa_supplicant/wpa_supplicant.conf + edit-pref => cd ~/myopenaps && vi preferences.json + edit-runagain => cd ~/myopenaps && nano oref0-runagain.sh + ``` +To use these shortcuts, just type in the phrase you see on the left - e.g. `edit-wifi` and hit enter. \ No newline at end of file diff --git a/docs/docs/Build Your Rig/step-5-finishing-setup.md b/docs/docs/Build Your Rig/step-5-finishing-setup.md new file mode 100644 index 000000000..344ddac47 --- /dev/null +++ b/docs/docs/Build Your Rig/step-5-finishing-setup.md @@ -0,0 +1,61 @@ +# Step 5: 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](<../Usage and maintenance/preferences-and-safety-settings>). 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.** +******************* + +## So you think you're looping? Now keep up to date! + +If you've gone "live" with your loop, congratulations! You'll probably want to keep a very close eye on the system and validate the outputs for a while. (For every person, this amount of time varies). + +One important final step, in addition to continuing to keep an eye on your system, is letting us know that you are looping. + +**This is important in case there are any major changes to the system that we need to notify you about**. One example where this was necessary is when we switched from 2015 to 2016: the dates were incorrectly reporting as 2000, resulting in incorrect IOB calculations. As a result, we needed to notify current loopers so they could make the necessary update/upgrade. + +### After you have looped for three consecutive nights: + +So that we can notify you if necessary, [please fill out this form if you have been looping for 3+ days](http://bit.ly/nowlooping). Your information will not be shared in any way. You can indicate your preferred privacy levels in the form. As an alternative, if you do not want to input info, please email dana@openaps.org. Again, this is so you can be notified in the case of a major bug find/fix that needs to be deployed. + +**Note**: you only ever need to fill this form out once. If you're building multiple rigs, or switching between DIY systems, no need to fill this out multiple times. We're just counting - and wanting to connect with in terms of safety announcements - humans. :) + +## Optional step: improving the battery life of your Raspberry Pi + +!! Important for Enlite users: If you are using Enlite as CGM source, your rig will not work when it's underclocked, since the loop will not run fast enough! (You will always see the "BG too old" error). We are aware of that issue and try to find a solution... + +Version - CPU Clock - Battery Life @ 2500mAh (Li-Po) +___ +* 0.6.2 - 1000 MHz - **8 hours** +* 0.7.0-dev - 1000 MHz - **9 hours** +* 0.7.0-dev - 500 MHz - **14.5 hours** +___ + +As you can see, 0.7.0 made some battery life improvements, but under-clocking the CPU makes an even more significant improvement. + +To accomplish this, log into your rig via SSH and modify the file `/boot/config.txt`. + +Scroll down to find the line + +`#arm_freq=1000` + +and change it to + +`arm_freq=500` + +Note the removal of the `#` at the beginning of the line. Save your change and reboot your rig! + +## Customizing your closed loop + +As your time permits, there's still more useful and cool things you can do to make looping more efficient and automated. + +* First, review some [common situations you may encounter and practical advice for using your loop.](<../Usage and maintenance/usability-considerations>) +* [Add more wifi networks to your rig](<../Usage and maintenance/Wifi/on-the-go-wifi-adding>) so that when you are away from home, the rig has access to trusted wifi networks +* [Set up Papertrail](<../Usage and maintenance/monitoring-OpenAPS#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. +* [Set up IFTTT for your phone or watch](<../Customize-Iterate/ifttt-integration>) 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](<../Usage and maintenance/Wifi/bluetooth-tethering-edison>) 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](<../Customize-Iterate/offline-looping-and-monitoring>) 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.](<../Customize-Iterate/useful-mobile-apps>) 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. + diff --git a/docs/docs/Build Your Rig/windows-putty-prep.md b/docs/docs/Build Your Rig/windows-putty-prep.md deleted file mode 100644 index 731d5e01f..000000000 --- a/docs/docs/Build Your Rig/windows-putty-prep.md +++ /dev/null @@ -1,44 +0,0 @@ -# Windows Users: Getting drivers and PUTTY so you can access your rig - -### **1-1 Prepare Windows Computer** - -- Install the [Intel Edison drivers for Windows]( https://downloadcenter.intel.com/download/26993/Intel-Edison-Configuration-Tool). Select the "...setup...exe" download, for example, "IntelEdisonDriverSetup1.2.1.exe". After it is done downloading, click on the downloaded file and it will execute installation. - -![Edison Drivers](../Images/Edison/edison_driver_121.png) - -![Edison Drivers](../Images/Edison/edison_driver2.png) - - -- Install [PuTTY]( http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html). PuTTY is the program you will normally use to login to your rig in the future from the computer. Creating a desktop shortcut for it is a good idea, since you will likely use it often. Download the installation file that matches your PC's architecture (32-bit or 64-bit). If you are unsure, you can check your computer's build and memory in the Control Panel. Example shown is for a 64-bit computer. If unsure, installing the 32-bit version won't harm anything...it just might be a little slower to use PuTTY. - -![Control Panel](../Images/Edison/64_bit.png) - -![Putty](../Images/Edison/putty.png) - -![Putty](../Images/Edison/putty2.png) - -![Putty](../Images/Edison/putty3.png) - -### **1-2 Prepare Edison** -Now we move to the Edison. You’ll see two microB USB ports on your explorer board. One is labeled OTG (that’s for flashing) and one is labeled UART (that’s for logging into the Edison from a computer). Connect the board's UART port with your computer’s USB port using one of the cables listed in the parts list (Dexcom’s charging cable will work too). - -![Explorer Board rig with two cables and red light on](../Images/Edison/ExplorerBoard_two_charging_cables.png) -Note: This photo displays two cables plugged into the Edison board, but only one is necessary for connecting to your computer. - -- Once you plug in the cable, you need to determine which COM number it's using. On your computer, go to Control Panel\All Control Panel Items\Device Manager\Ports\ and look for USB Serial Port COMXX. If you see multiple entries and are unsure of which is the port you need: Make note of existing ports. Unplug the cable from the Explorer Board. Notice which port disappears. This is the port you are looking for. If only one shows up while your Edison is plugged in, and none appear when your Edison is unplugged from your computer, then that is your Edison's port. - -![Port Select](../Images/Edison/port.png) - -Note: If your Edison's port doesn't appear, make sure its battery is charged and/or the Edison is powered on. - - - Open PuTTY, change from SSH to Serial. It normally defaults to COM1 and speed of 9600. Change the COM number to the number you found when you plugged into the Explorer Board. Change the speed (baud rate) to 115200. - - Once you've made those changes, Click on OPEN at the bottom of your Putty configuration window. - -![Putty port](../Images/Edison/putty_port.png) - - - Once the screen comes up, press enter a few times to wake things up. This will give you a "console" window of what is happening on your Edison. -- Now you will see a login prompt for the Edison on the console screen. Login using the username "root" (all lowercase) and default password (most likely "edison" without quotes, but check the slip of paper that might have come with your pre-flashed Edison). - -Head back to the other directions to continue the setup. - - diff --git a/docs/docs/Customize-Iterate/ifttt-integration.md b/docs/docs/Customize-Iterate/ifttt-integration.md index c3b9e94f9..b02255553 100644 --- a/docs/docs/Customize-Iterate/ifttt-integration.md +++ b/docs/docs/Customize-Iterate/ifttt-integration.md @@ -149,9 +149,9 @@ Reservoir Change * Login to your Nightscout site host (azure or heroku) and (1) add your Maker Key to the MAKER_KEY line and (2) add "maker" to your ENABLE line. -![IFTTT NS marker key](../../Images/IFTTT_NSkey.png) +![IFTTT NS marker key](../Images/IFTTT_NSkey.png) -![IFTTT NS enable](../../Images/IFTTT_enable.png) +![IFTTT NS enable](../Images/IFTTT_enable.png) ## Install IFTTT app on your Android diff --git a/docs/docs/Customize-Iterate/index.rst b/docs/docs/Customize-Iterate/index.rst deleted file mode 100644 index 03bfb23e7..000000000 --- a/docs/docs/Customize-Iterate/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -Customize-Iterate ----------------------- - -.. toctree:: - :maxdepth: 4 - - - bluetooth-tethering-edison - ifttt-integration - autosens - autotune - understanding-autotune - oref1 - offline-looping-and-monitoring - on-the-go-wifi-adding - useful-mobile-apps - usability-considerations - update-your-rig - oref0-runagain diff --git a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md index 90d97c91a..7a7555aaa 100644 --- a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md +++ b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md @@ -1,6 +1,8 @@ # Offline looping - aka, running OpenAPS without internet connectivity -There are a number of ways to have an "offline" OpenAPS rig, and numerous ways to monitor offline ([see the monitoring section for information about monitoring offline](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#the-main-ways-of-monitoring-your-rig-offline-include)). Offline refers to situations where your rig moves into an area where it does not have internet access (i.e., the rig does not have a known WiFi network available and the cell phone used with the rig does not have cell coverage/hotspot available). By setting up one of these offline solutions, your rig can still loop while in an offline area. Depending on the setup, the opportunities to visualize or monitor the loop actions (e.g., check what temp basal is actually being set) may vary until you can get back into an online area. +## Overview + +There are a number of ways to have an "offline" OpenAPS rig, and numerous ways to monitor offline ([see the monitoring section for information about monitoring offline](<../Usage and maintenance/monitoring-OpenAPS#the-main-ways-of-monitoring-your-rig-offline-include>)). Offline refers to situations where your rig moves into an area where it does not have internet access (i.e., the rig does not have a known WiFi network available and the cell phone used with the rig does not have cell coverage/hotspot available). By setting up one of these offline solutions, your rig can still loop while in an offline area. Depending on the setup, the opportunities to visualize or monitor the loop actions (e.g., check what temp basal is actually being set) may vary until you can get back into an online area. **NOTE: TRY BEFORE YOU FLY!** Remember this when you decide to use an offline looping method for the first time - try it before you go offline for the situation in which you likely need it (e.g. flying, camping, hiking, etc.). Sometimes there's something small and easy like remembering to plug a secondary power source to your rig that can make your offline looping method work, but you'll forget on your first try - so try before you go! @@ -23,7 +25,7 @@ Dexcom CGM users have a few different alternatives to retrieve blood glucose val ### A. xDrip+ for Android users -Android users can use the xDrip+ Android app for offline looking, assuming xDrip+ is used as the CGM data source. There are two ways to get offline looping to work with xDrip+. Firstly, when connected to an Android phone running xDrip+, you can enable the phone to share the CGM information to OpenAPS, after which OpenAPS will automatically fetch the CGM data directly from the phone when connected onto the phone hotspot, even in cases where the phone is actually offline. +Android users can use the xDrip+ Android app for offline looping, assuming xDrip+ is used as the CGM data source. There are two ways to get offline looping to work with xDrip+. Firstly, when connected to an Android phone running xDrip+, you can enable the phone to share the CGM information to OpenAPS, after which OpenAPS will automatically fetch the CGM data directly from the phone when connected onto the phone hotspot, even in cases where the phone is actually offline. To enable the xDrip service for OpenAPS, go to the Inter-app settings section in xDrip settings and enable the xDrip Web Service and Open Web Service settings, then enter xDrip Web Service Secret, which has to match the same secret you have configured for Nightscout. After these settings are turned on,OpenAPS will query your phone for the CGM data automatically without additional configuration settings. You can validate the offline looping works by connecting your rig to the xDrip hotspot and checking the ns-loop.log has a line saying `CGM results loaded from xDrip`. @@ -37,7 +39,8 @@ To enable the xDrip service for OpenAPS, go to the Inter-app settings section in -The second method involves installing an application called xDripAPS onto your rig. The details for setting up xDripAPS are described in the [section below](https://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/offline-looping-and-monitoring.html#xdripaps-offline-looping-for-users-of-the-xdrip-android-app). The naming can be confusing. xDrip+ (maintained by [@jamorham](https://jamorham.github.io/#xdrip-plus)) is the app being actively developed. While Google may lead you to several older versions of the xDrip/xDrip+ Android app, you can always get the latest version here: +The second method involves installing an application called xDripAPS onto your rig. The details for setting up xDripAPS are described in the [section below](<../Customize-Iterate/offline-looping-and-monitoring#xdripaps-offline-looping-for-users-of-the-xdrip-android-app>). The naming can be confusing. xDrip+ (maintained by [@jamorham](https://jamorham.github.io/#xdrip-plus)) is the app being actively developed. While Google may lead you to several older versions of the xDrip/xDrip+ Android app, you can always get the latest version here: + * xDrip+: [https://github.com/NightscoutFoundation/xDrip](https://github.com/NightscoutFoundation/xDrip) * There is no direct iOS version of xDrip+. [Spike](https://spike-app.com/) is a different app with a different set of features. @@ -83,9 +86,9 @@ The oref0-setup option for `xdrip-js` installs Logger by default. * **Lookout** - this application runs on your rig and uses the xdrip-js library to read from the G5 or G6 transmitter directly. It uses the transmitter's built-in calibration algorithm, and you can enter BG calibrations either from the receiver or from a browser on your phone or computer, when connected to a web server that Lookout manages on your rig. The Lookout web pages also allow you to view CGM, pump, and OpenAPS status. Regardless of whether you use the receiver or Lookout to enter calibrations, they will be sent to the transmitter and both devices will report the same resulting BG values (though they may take a reading or two to 'catch up' after a calibration). Depending on your phone's hotspot capabilities, you may be able to access the Lookout web server even when cellular data is not available. Lookout will read Dexcom transmitter BG data and update OpenAPS locally (via xDripAPS), so your rig will continue to loop while offline, as well as send to Nightscout when your rig is online. Since Lookout uses the official transmitter calibration algorithm, it still requires sensor restarts every 7 days, with 2-hour warmups, and cannot be used with transmitters that have reached the Dexcom expiration (105-112 days from their first use). - * **Logger** (xdrip-js-logger) - this application is restarted regularly from your rig's crontab, and uses the xdrip-js library to read from the Dexcom G5 or G6 transmitter directly. It can use non-expired or expired transmitters. It leverages both the in transmitter session calibration algorithms and falls back to LSR calibrations automatically when the sensor has an issue or stops (i.e. after 7 days). For LSR calibration, Logger uses the raw filtered/unfiltered values from the Dexcom transmitter, instead of the official calibrated value, and so can be used with transmitters that are past their standard expiration (including those with replaced batteries). Logger also has the ability to reset an expired transmitter to new so that in transmitter calibrations can be used (even for battery replaced transmitters). Calibrations for Logger are entered through nightscout as BG Treatments, or through the pump (e.g., via the Contour Next Link meter that automatically loads to the pump), or through the command line. BG data is sent to both OpenAPS (via xDripAPS) locally, so your rig will continue to loop while offline, and include Nightscout when online. You can use a receiver with Logger, but the BG values will not necessarily match between the two, and the calibrations on the receiver must be entered separately. Nightscout is the user interface for entering calibration and getting sensor status / requests such as "Needs calibration" as Announcements. Nightscout also shows the transmitter battery status, voltages, resistance, temperature every 12 hours as a note. Nightscout is also used to let Logger know that a new sensor has been inserted and to start a sensor. You can set the time back on a start - i.e. 2 hours (if you soaked the sensor). Logger has command line scripts that run on the rig (cgm-reset, cgm-start, cgm-stop, cgm-battery, and calibrate). There is currently no local web browser for entering calibrations or interacting with Logger, so the only way to view its data is through a terminal, xDripAPS web server, or Nightscout. **NOTE: for expired transmitters, Logger LSR calibration method is an approximation of what the Dexcom transmitter does internally so caution and serious oversite and testing should be exercised when using.** + * **Logger** (xdrip-js-logger) - this application is restarted regularly from your rig's crontab, and uses the xdrip-js library to read from the Dexcom G5 or G6 transmitter directly. It can use non-expired or expired transmitters. It leverages both the in transmitter session calibration algorithms and falls back to LSR calibrations automatically when the sensor has an issue or stops (i.e. after 7 days). For LSR calibration, Logger uses the raw filtered/unfiltered values from the Dexcom transmitter, instead of the official calibrated value, and so can be used with transmitters that are past their standard expiration (including those with replaced batteries). Logger also has the ability to reset an expired transmitter to new so that in transmitter calibrations can be used (even for battery replaced transmitters). Calibrations for Logger are entered through nightscout as BG Treatments, or through the pump (e.g., via the Contour Next Link meter that automatically loads to the pump), or through the command line. BG data is sent to both OpenAPS (via xDripAPS) locally, so your rig will continue to loop while offline, and include Nightscout when online. You can use a receiver with Logger, but the BG values will not necessarily match between the two, and the calibrations on the receiver must be entered separately. Nightscout is the user interface for entering calibration and getting sensor status / requests such as "Needs calibration" as Announcements. Nightscout also shows the transmitter battery status, voltages, resistance, temperature every 12 hours as a note. Nightscout is also used to let Logger know that a new sensor has been inserted and to start a sensor. You can set the time back on a start - e.g. 2 hours (if you soaked the sensor). Logger has command line scripts that run on the rig (cgm-reset, cgm-start, cgm-stop, cgm-battery, and calibrate). There is currently no local web browser for entering calibrations or interacting with Logger, so the only way to view its data is through a terminal, xDripAPS web server, or Nightscout. **NOTE: for expired transmitters, Logger LSR calibration method is an approximation of what the Dexcom transmitter does internally so caution and serious oversite and testing should be exercised when using.** -> NOTE: Lookout, Logger (xdrip-js-logger), and xdrip-js library should be considered a WIP (Work In Progress), i.e., do not use if you cannot watch your BG and loop very carefully, and tolerate issues, failures, idiosynchrosies. Also please plan on contributing either through testing and feedback, updates, documentation, etc. +> NOTE: Lookout, Logger (xdrip-js-logger), and xdrip-js library should be considered a WIP (Work In Progress), i.e., do not use if you cannot watch your BG and loop very carefully, and tolerate issues, failures, idiosyncrasies. Also please plan on contributing either through testing and feedback, updates, documentation, etc. A summary of their features: @@ -197,7 +200,7 @@ The oref0-setup option for `xdrip-js` installs Logger by default. * Logger: [https://github.com/xdrip-js/Logger/blob/dev/README.md](https://github.com/xdrip-js/Logger/blob/dev/README.md) ### Entering carbs while offline -While offline you will not be able to enter carbs and set temporary targets using Nightscout. You have two options to enter carbs while offline. You can use the Medtronic pump's Bolus Wizard. When using the Bolus Wizard, be careful to avoid an A52 error if you have enabled SMB. By default, use of the Bolus Wizard disables SMB for 6 hours ([learn more here](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/preferences-and-safety-settings.html#a52-risk-enable-a52-risk-mitigation)). The second option, which as far as we know avoids the A52 risk, is to use the Medtronic pump's Capture Event feature. To turn on the Capture Event feature, do these steps: +While offline you will not be able to enter carbs and set temporary targets using Nightscout. You have two options to enter carbs while offline. You can use the Medtronic pump's Bolus Wizard. When using the Bolus Wizard, be careful to avoid an A52 error if you have enabled SMB. By default, use of the Bolus Wizard disables SMB for 6 hours ([learn more here](<../Usage and maintenance/preferences-and-safety-settings#a52-risk-enable-a52-risk-mitigation>)). The second option, which as far as we know avoids the A52 risk, is to use the Medtronic pump's Capture Event feature. To turn on the Capture Event feature, do these steps: 1. Go to the CAPTURE EVENT ON/OFF screen: Main > Utilities > Capture Option 2. Select On, then press ACT. diff --git a/docs/docs/Customize-Iterate/oref1.md b/docs/docs/Customize-Iterate/oref1.md index 811576764..813783478 100644 --- a/docs/docs/Customize-Iterate/oref1.md +++ b/docs/docs/Customize-Iterate/oref1.md @@ -1,29 +1,6 @@ # oref1 (super advanced features) -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 than one rig, you will want to make sure all rigs are running an Super Micro Bolus (SMB) aware oref0 version (release 0.5.1 or higher) before enabling Super Micro Bolus (SMB) on any of them (even if Super Micro Bolus (SMB) is not enacted on all rigs, all rigs need to know about it). -* Super Micro Bolus (SMB) is about front-shifting insulin activity. It is NOT a synonym for no-bolus, although it can enable no-bolus options (with very close monitoring and testing). But you should first test Super Micro Bolus (SMB) with your existing bolus method. - * Take steps one by one to turn on Super Micro Boluses; validate that Super Micro Boluses are working and understand if it is working for you; and only then should you approach changing behaviors related to meal-time boluses. - * Do not combine turning on Super Micro Bolus (SMB) and trying to do no-bolus or partial-bolus meals at the same time. -* Make sure you have your easy bolus button on ([details here](https://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/collect-data-and-prepare.html#easy-bolus-button)) and know how to deliver boluses without using the bolus wizard. -* See this page on [optimizing settings](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/optimize-your-settings.html#optimizing-your-settings) for reminders and tips on changing one thing at a time. - -## Only run oref1 with the following caveats in mind: - -* Remember that you are choosing to test a still-in-development feature. Do so at your own risk & with due diligence to keep yourself safe. -* 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. -* **We are requiring that you also have run autotune prior to enabling Super Micro Bolus (SMB).** Why? Because if you have wonky ISF settings, for example, you may be more likely to go low or high with Super Micro Bolus (SMB). It will help a lot to have run autotune and be aware if the algorithm is recommending changes to ISF, basal, and/or carb ratio. You are not required to run autotune automatically/nightly as part of your loop with Super Micro Bolus (SMB); but you should at least run it manually and get an idea for how confident you are in your settings being right or not; and keep that in mind when evaluating Super Micro Bolus (SMB) outcomes for yourself. -* You should have basals of > 0.5 U/hr. (Super Micro Bolus (SMB) is *not* advisable for those with very small basals; since 0.1U is the smallest increment that can be bolused by Super Micro Bolus (SMB). We also added a basal check to disable Super Micro Bolus (SMB) when basals are < 0.3 U/hr. If your "regular" basal in the pump is 0.3 U/hr and autosens or autotune has adjusted your basal rate to below 0.3 U/hr, Super Micro Bolus (SMB)s will be disabled as well.) -* Read the following: - * A. The updated reference design ([https://openaps.org/reference-design/](https://openaps.org/reference-design/)) that explains the differences between oref0 and oref1 - * B. The following two posts for background on oref1: - * [https://diyps.org/2017/04/30/introducing-oref1-and-super-microboluses-smb-and-what-it-means-compared-to-oref0-the-original-openaps-algorithm/](https://diyps.org/2017/04/30/introducing-oref1-and-super-microboluses-smb-and-what-it-means-compared-to-oref0-the-original-openaps-algorithm/) - * [https://diyps.org/2017/05/08/choose-one-what-would-you-give-up-if-you-could-with-openaps-maybe-you-can-oref1-includes-unannounced-meals-or-uam/](https://diyps.org/2017/05/08/choose-one-what-would-you-give-up-if-you-could-with-openaps-maybe-you-can-oref1-includes-unannounced-meals-or-uam/) -* Make sure you understand what Super Micro Bolus (SMB) & Unannounced Meals (UAM) stand for (**read the above posts, we know you skipped them**!) -* Plan to have a learning curve. You will interact with oref1 differently when on Super Micro Bolus (SMB) and Unannounced Meal (UAM) than how you were interacting with oref0. In particular: **do not do correction boluses based on insulinReq**; instead use temp targets to give the rig a "nudge". You are very likely to overshoot if you try to do things manually on top of what Super Micro Bolus (SMB) has already done! -* Super Micro Bolus (SMB) may not be for everyone. Like everything else, plan to test it, fall back to previous methods of diabetes treatment if needed, and give yourself a time period for deciding whether or not it works well for you. +oref1, the use of "super-microboluses (SMB)" and/or "unannounced meals (UAM)" is different from oref0, the baseline "traditional" OpenAPS implementation that only uses temporary basal rates. ## Understanding Super Micro Bolus (SMB) @@ -39,7 +16,7 @@ Single Super Micro Bolus (SMB) amounts are limited by several factors. The larg It's important to note that maxIOB will limit Super Micro Bolus (SMB)s from being issued if your Insulin On Board (IOB) (for instance, from an easy bolus you have inputted before a meal) exceeds your maxIOB. So if your maxIOB is relatively low and you are running high post-meal, you may want to examine your logs to see if it is routinely preventing Super Micro Bolus (SMB)s. -In addition, as of 0.6.0-master, using Bolus Wizard to input boluses and meal carbs is no longer recommended because of the possibility of errors when the rig attempts to issue an Super Micro Bolus (SMB) while Bolus Wizard is in use. Instead, many users [use IFTTT to notify their rig of upcoming carbs](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/ifttt-integration.html). +In addition, as of 0.6.0-master, using Bolus Wizard to input boluses and meal carbs is no longer recommended because of the possibility of errors when the rig attempts to issue an Super Micro Bolus (SMB) while Bolus Wizard is in use. Instead, many users [use IFTTT to notify their rig of upcoming carbs](<./ifttt-integration>). (History of Super Micro Bolus (SMB) development: https://github.com/openaps/oref0/issues/262 ) @@ -50,30 +27,67 @@ In addition, as of 0.6.0-master, using Bolus Wizard to input boluses and meal ca (History of Unannounced Meals (UAM) development: https://github.com/openaps/oref0/issues/297 ) + +## Getting ready to enable oref1 + +* 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. + +* Read the following: + * A. The updated reference design ([https://openaps.org/reference-design/](https://openaps.org/reference-design/)) that explains the differences between oref0 and oref1 + * B. The following two posts for background on oref1: + * [https://diyps.org/2017/04/30/introducing-oref1-and-super-microboluses-smb-and-what-it-means-compared-to-oref0-the-original-openaps-algorithm/](https://diyps.org/2017/04/30/introducing-oref1-and-super-microboluses-smb-and-what-it-means-compared-to-oref0-the-original-openaps-algorithm/) + * [https://diyps.org/2017/05/08/choose-one-what-would-you-give-up-if-you-could-with-openaps-maybe-you-can-oref1-includes-unannounced-meals-or-uam/](https://diyps.org/2017/05/08/choose-one-what-would-you-give-up-if-you-could-with-openaps-maybe-you-can-oref1-includes-unannounced-meals-or-uam/) + +* Make sure you understand what Super Micro Bolus (SMB) & Unannounced Meals (UAM) stand for (**read the above posts, we know you skipped them**!) + +* Plan to have a learning curve. You will interact with oref1 differently when on Super Micro Bolus (SMB) and Unannounced Meal (UAM) than how you were interacting with oref0. In particular: **do not do correction boluses based on insulinReq**; instead use temp targets to give the rig a "nudge". You are very likely to overshoot if you try to do things manually on top of what Super Micro Bolus (SMB) has already done! + +* If running more than one rig, you will want to make sure all rigs are running an Super Micro Bolus (SMB) aware oref0 version (release 0.5.1 or higher) before enabling Super Micro Bolus (SMB) on any of them (even if Super Micro Bolus (SMB) is not enacted on all rigs, all rigs need to know about it). + +* Make sure you have your easy bolus button on ([details here](<../While You Wait For Gear/collect-data-and-prepare#easy-bolus-button>)) and know how to deliver boluses without using the bolus wizard. + +* **We are requiring that you also have run autotune prior to enabling Super Micro Bolus (SMB).** Why? Because if you have wonky ISF settings, for example, you may be more likely to go low or high with Super Micro Bolus (SMB). It will help a lot to have run autotune and be aware if the algorithm is recommending changes to ISF, basal, and/or carb ratio. You are not required to run autotune automatically/nightly as part of your loop with Super Micro Bolus (SMB); but you should at least run it manually and get an idea for how confident you are in your settings being right or not; and keep that in mind when evaluating Super Micro Bolus (SMB) outcomes for yourself. To fulfill this requirement you can do one of the following which will create an autotune directory where it needs to be: + * enable autotune during your OpenAPS setup script and autotune will run automatically as part of your loop + * run autotune as a one-off (single run) on your rig + +* You should have basals of > 0.5 U/hr. (Super Micro Bolus (SMB) is *not* advisable for those with very small basals; since 0.1U is the smallest increment that can be bolused by Super Micro Bolus (SMB). We also added a basal check to disable Super Micro Bolus (SMB) when basals are < 0.3 U/hr. If your "regular" basal in the pump is 0.3 U/hr and autosens or autotune has adjusted your basal rate to below 0.3 U/hr, Super Micro Bolus (SMB)s will be disabled as well.) + * ***Note about Autosens, Autotune, and SMBs**: 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. Since SMBs require a minimum basal rate of 0.3 U/hr, 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 have changed your basal rate to be less than 0.3 U/hr. + +## Getting started + +Super Micro Bolus (SMB) is about front-shifting insulin activity. It is NOT a synonym for no-bolus, although it can enable no-bolus options (with very close monitoring and testing). But you should first test Super Micro Bolus (SMB) with your existing bolus method. + +Take steps one by one to turn on Super Micro Boluses; validate that Super Micro Boluses are working and understand if it is working for you; and only then should you approach changing behaviors related to meal-time boluses. + +Do not combine turning on Super Micro Bolus (SMB) and trying to do no-bolus or partial-bolus meals at the same time. See this page on [optimizing settings](<../Usage and maintenance/optimize-your-settings#optimizing-your-settings>) for reminders and tips on changing one thing at a time. + +Remember that you are choosing to test a still-in-development feature. Do so at your own risk & with due diligence to keep yourself safe. Super Micro Bolus (SMB) may not be for everyone. Like everything else, plan to test it, fall back to previous methods of diabetes treatment if needed, and give yourself a time period for deciding whether or not it works well for you. + + ## How to turn on Super Micro Bolus (SMB) * In oref0 0.6.0 and later, you will enable Super Micro Bolus (SMB)s by adding the related preferences to your preferences.json. You may want to experiment with turning only one enableSMB option 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 Super Micro Bolus (SMB). 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: +There are multiple preference toggles for Super Micro Bolus (SMB). Check out the [preferences page](<../Usage and maintenance/preferences-and-safety-settings#oref1-related-preferences>) for more details on all the settings, but the short version is: -``` - * enableSMB_with_COB means Super Micro Bolus (SMB) will be enabled as long as COB is above zero - * enableSMB_after_carbs means Super Micro Bolus (SMB) will be enabled for 6h after carb entry - * enableSMB_with_temptarget means Super Micro Bolus (SMB) will be enabled with a low temp target (< 100 mg/dL). + * `enableSMB_with_COB` means Super Micro Bolus (SMB) will be enabled as long as COB is above zero + * `enableSMB_after_carbs` means Super Micro Bolus (SMB) will be enabled for 6h after carb entry + * `enableSMB_with_temptarget` means Super Micro Bolus (SMB) will be enabled with a low temp target (< 100 mg/dL). + By default, a higher temp target (101 if your target is 100) will disable Super Micro Bolus (SMB). -``` ## Troubleshooting -1. Make sure you read the above, especially the "only enable oref1 if..." section. Super Micro Bolus (SMB) will behave differently than oref0 would. Watch carefully, and use your common sense and do what's right for you & your diabetes. +1. Make sure you read the above. Super Micro Bolus (SMB) will behave differently than oref0 would. Watch carefully, and use your common sense and do what's right for you & your diabetes. 2. Common errors include: -* Not changing the preferences to be "true" for the relevant settings after you've enabled the oref1 features. +* Not changing the preferences to be "true" for the relevant settings. * Not running autotune. Remember, you don't have to enable it to run as part of your loop at night, but you should run it manually, review the results, and otherwise be VERY confident in your underlying pump settings (basals, ISF, carb ratio) before using oref1. +* Having basals below 0.3u/hour, either in a pump profile or after adjustment by autotune and/or autosens. (This isn't an error, but will prevent SMBs from being enacted for safety reasons!) * Pump clock being >1 minute off from rig's time. This means 60 seconds. Not 61 seconds; 68 seconds; 90 seconds. Needs to be less than 60 seconds apart. `"Checking pump clock: "2017-05-16T15:46:32-04:00" is within 1m of current time: Tue May 16 15:47:40 EDT 2017` is an example of a >60 second gap that needs fixing before it will work properly. We added a script to automatically attempt to fix the pump time in case of a >60 second difference, but you may occasionally see this type of error in the logs until the script is able to properly adjust the pump time. ## Pushover, Super Micro Bolus (SMB), and OpenAPS -_This is for OpenAPS-specific pushovers related to oref1 features about insulin required (insulinReq) and carbs required (carbsReq). Pushover is a way to easily send messages to your phone from another device with simple messages. If you have Pushover set up for Nightscout, you still need to tell your OpenAPS rig your Pushover information to get these rig-driven alerts. Nightscout Pushover alerts are separate and distinct from OpenAPS-generated Pushover alerts. Each can exists with or without the other._ +This is for OpenAPS-specific pushovers related to oref1 features about insulin required (insulinReq) and carbs required (carbsReq). Pushover is a way to easily send messages to your phone from another device with simple messages. If you have Pushover set up for Nightscout, you still need to tell your OpenAPS rig your Pushover information to get these rig-driven alerts. Nightscout Pushover alerts are separate and distinct from OpenAPS-generated Pushover alerts. Each can exist with or without the other. If Pushover API token and User key were added during the setup script and you have oref1 enabled, you can get Pushover alerts in the following situations: diff --git a/docs/docs/Customize-Iterate/understanding-autotune.md b/docs/docs/Customize-Iterate/understanding-autotune.md deleted file mode 100644 index 798c2b013..000000000 --- a/docs/docs/Customize-Iterate/understanding-autotune.md +++ /dev/null @@ -1,40 +0,0 @@ -# Understanding autotune - -## Safety reminders - -Autotune is a WIP (work in progress) tool. Do not blindly make changes to your pump settings without careful consideration. You may want to print the output of this tool and discuss any particular changes with your care team. Make note that you probably do not want to make long-term changes based on short term (i.e. 24 hour) data. Most people will choose to make long term changes after reviewing carefully autotune output of 3-4 weeks worth of data. - -## Example output from autotune - -![Example output from autotune](https://diyps.org/wp-content/uploads/2017/01/OpenAPS-autotune-example-by-@DanaMLewis.png) - -## What you'll see in autotune inputs and outputs - -* You might wonder what CSF in the autotune results refers to: Carb Sensitivity Factor is the amount your blood sugar will rise for a given quantity of carbs consumed. And initial value for CSF is calculated from your ISF and carb:insulin ratio (CR), i.e., CSF = ISF / CR (e.g., for an ISF of 42(mg/dL)/U and CR of 14g/U, CSF is 3(mg/dL)/g.) Subsequent autotune estimates for CSF are adjusted for the actual observed post-meal BG rise (relative to what would be expected based on insulin activity) compared to the number of carbs eaten. -* You might wonder what min_5m_carbimpact in profile.json refers to: It tells autotune how fast to decay carbs when your BG isn't rising. The default value means to assume 8mg/dL per 5m of carb absorption, even when your BG is falling or rising less than that. -* If you only input one basal rate in the profile.json, it will only show one basal in the left hand column, and tune the day around that basal. You can go back and edit the profile.json (and cp again to make all files the same) with your multiple basal rates if you want to appropriately tune and most easily compare the output suggested against what your existing basal schedule is. - -## If you are DIY closed looping and looking at autotune: - -#### With carbs logged in Nightscout -...you can look at everything that autotune outputs - -#### Without carb information in Nightscout -...you should only look at overnight basals, daytime basals that are not around typical meal times, and (with caution) ISF. Ignore carb ratio. - - -## If you are not DIY closed looping and are looking at autotune: - -#### With all boluses and carb treatments (even rescue, or low carbs) in Nightscout -...you can look at everything that autotune outputs - -#### Without boluses and carb treatments in Nightscout -...don't use autotune until you log this data. - -#### If you don't have Nightscout - -...it's probably easiest to set up [Nightscout](http://nightscout.info) and log some data in order to use autotune. This may change in the future (and let us know if you want to work on ways to bring other data types into autotune). - - - - diff --git a/docs/docs/Customize-Iterate/useful-mobile-apps.md b/docs/docs/Customize-Iterate/useful-mobile-apps.md index 5ec6f3f5a..73c749a3c 100644 --- a/docs/docs/Customize-Iterate/useful-mobile-apps.md +++ b/docs/docs/Customize-Iterate/useful-mobile-apps.md @@ -123,7 +123,7 @@ If you want to run a particular command, just click on the command & confirm whi #### SimpleSSH file navigation -Perhaps a more slightly advanced-user (or curious-user) feature of SimpleSSH is the ability to use the file/directory navigator. The navigator (accessed using the magnifying glass icon in Hosts page) will allow you to peruse the various directories and files used by your rig and openaps. If you wanted to see your oref0 code, it is stored in the `root/src/oref0` folder. Or if you wanted to see your loop directory, you could navigate to your `root/myopenaps` folder. This can be particularly useful if you are getting troubleshooting help and someone asks "What does your pumphistory.json show?"...you could easily navigate to that file and copy the contents of it. (Note: For further reading about the file structure of your loop and rig, see [here](http://openaps.readthedocs.io/en/latest/docs/Troubleshooting/General_linux_troubleshooting.html#before-you-get-started) For example, here's the navigation chain to find your pumphistory.json: +Perhaps a more slightly advanced-user (or curious-user) feature of SimpleSSH is the ability to use the file/directory navigator. The navigator (accessed using the magnifying glass icon in Hosts page) will allow you to peruse the various directories and files used by your rig and openaps. If you wanted to see your oref0 code, it is stored in the `root/src/oref0` folder. Or if you wanted to see your loop directory, you could navigate to your `root/myopenaps` folder. This can be particularly useful if you are getting troubleshooting help and someone asks "What does your pumphistory.json show?"...you could easily navigate to that file and copy the contents of it. (Note: For further reading about the file structure of your loop and rig, see [here](<../Troubleshooting/general_linux_troubleshooting#directories-on-your-rig>) For example, here's the navigation chain to find your pumphistory.json: ![SimpleSSH navigation example](../Images/navigate.png) diff --git a/docs/docs/Gear Up/CGM.md b/docs/docs/Gear Up/CGM.md index edf8deff0..aba45d985 100644 --- a/docs/docs/Gear Up/CGM.md +++ b/docs/docs/Gear Up/CGM.md @@ -18,7 +18,7 @@ As the Medtronic pump collects data directly from the Enlite sensors, OpenAPS wi ### Pulling CGM data from the cloud -Your OpenAPS implementation can also pull CGM data from a Nightscout site in addition to pulling from the CGM directly, when your rig has internet connectivity. You can find more documentation about pulling CGM data from a Nightscout site [here](https://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/nightscout-setup.html). +Your OpenAPS implementation can also pull CGM data from a Nightscout site in addition to pulling from the CGM directly. You can find more documentation about pulling CGM data from a Nightscout site [here](<../While You Wait For Gear/nightscout-setup>). * If you have an Android phone, you can use the xDrip app to get your data from the Dexcom to Nightscout, to then be used in OpenAPS. * If you have a Dexcom G4 Share receiver or Dexcom G5/G6 paired with your phone, you can send that data to Nightscout to be used by OpenAPS. diff --git a/docs/docs/Gear Up/edison-explorer-board.md b/docs/docs/Gear Up/edison-explorer-board.md new file mode 100644 index 000000000..cc552e572 --- /dev/null +++ b/docs/docs/Gear Up/edison-explorer-board.md @@ -0,0 +1,179 @@ +# Intel Edison-based setups + +## Parts you'll need + +The high level parts list (see below for more details, and links): + +* [Explorer Board Block](<#explorer-board-block>) +* [Edison](<#edison>) +* [Nuts and Bolts to attach the Edison to the Explorer Board Block](<#nuts-and-bolts>) +* [At least one Lithium battery](<#lithium-ion-polymer-lipo-battery-or-other-battery-supply>) +* [2 USB cables](<#usb-cables>) + +### Explorer Board Block + +The recommended board to use is the [Explorer Board Block](https://enhanced-radio-devices.myshopify.com/products/900mhz-explorer-block-pre-order), which was co-designed by this community. It also has the benefits of a built-in radio. It's only available from Hamshield/Enhanced Radio Devices. + +### Edison + +There are 4 types of Edison's. All of them work, but Versions 3 and 4 require an extra antenna, so 1 and 2 are preferred (1-EDI2.LPON, 2-EDI2.SPON, 3-EDI2.LPOF, and 4-EDI2.SPOF). If the seller does not specify the Edison model/version, you can see from the picture whether or not it has a white ceramic antenna in the corner. If it does not, then it will require an external antenna, but that version is fairly rare. + +* Option 1 - Buy it from places like Ebay, Craiglist, or your nearest store - and follow the instructions to flash it. + + * You may need to hunt for an Edison as supplies of them are dwindling - if you get it as part of a "kit" (e.g. breakoutboard + Edison), keep in mind _you'll still need to get the Explorer Board Block from Hamshield_. + + * **Note:** If you are doing Option 1 (an Edison from wherever you can find it) - you are getting an UNFLASHED Edison. Not a big deal - flashing it with jubilinux is just a few more steps (~15 minutes) - but remember you'll need to start with the [flashing instructions](<../Build Your Rig/step-1-flashing>). + +* Option 2 - (previously [buy an Edison that is already flashed with jublinux when supplies were available](https://enhanced-radio-devices.myshopify.com/products/intel-edison-w-jubilinux). If you get a pre-flashed Edison, you can start with [step 2](<../Build Your Rig/step-2-wifi-dependencies>). + +### Lithium-ion polymer (LiPo) battery or other battery supply + +The Explorer Boards have battery charger circuitry on board, making it easy to use a LiPo battery. + +* The example setup uses a [2000mah LiPo battery](http://www.robotshop.com/en/37v-2000mah-5c-lipo-battery.html); also [Lithium Ion Battery - 3.7v 2000mAh](https://www.adafruit.com/products/2011) or [Adafruit Battery Packs Lithium Ion Battery 3.7v 2000mAh](https://www.amazon.com/Battery-Packs-Lithium-3-7v-2000mAh/dp/B0137ITW46) are similar options. A 2000 mAh LiPo will get you about 12-14 hours of use, assuming you have the standard setup (which is what you get following these docs) running. Many people prefer a higher capacity battery to get a full day from the rig (such as [Adafruit Lithium Ion Polymer Battery - 3.7v 2500mAh (PRODUCT ID: 328) and the Adafruit Lithium Ion Cylindrical Battery - 3.7v 2200mAh (PRODUCT ID: 1781)](https://www.adafruit.com/category/574)). This battery uses a 2mm 2 pin JST connector to match the Explorer boards' power plugs. +* For people in the UK, you may find you have to shop around to find the correct battery, as shipping restrictions appears to have reduced the supply somewhat. [Pimoroni](https://shop.pimoroni.com/products/lipo-battery-pack) appear to stock the same Adafruit 2000mAh battery as mentioned above. Another source looks to be [Cool Components](https://www.coolcomponents.co.uk/en/lithium-polymer-battery-2000mah.html), but you may find shipping costs expensive. CAUTION: [RS Online](https://uk.rs-online.com/mobile/p/lithium-rechargeable-battery-packs/1251266/) sell a similar battery, but unfortunately it comes with the wrong JST connector (it comes with a 2.5mm JST XHP-2, and you need a 2mm JST PH). It is possible, however, to buy the [right connectors](https://www.technobotsonline.com/jst-ph-2mm-2-way-housing-excludes-female-pins.html) and fit them yourself (numerous 'how to' videos on YouTube). +* For people in Australia you can find 2000mAh, 2200mAh and 2500mAh batteries from [Little bird electronics](https://www.littlebirdelectronics.com.au/batteries/), prices are very competitive and shipping is quick. These are the same Adafruit batteries that can be obtained from the US above. + +**Note**: It's best to buy from a reputable supplier, because if the internal two cells are mismatched the Explorer board cannot charge them separately and they are prone to catching fire. Make sure that it *includes a protection circuit* to protect over-discharge. **NEVER** connect the battery to an Explorer board the wrong way round. There is no manufacturing standard so never assume correct polarity. The connector JP1 on the Explorer Block has two terminals. The left side is positive, the right side is negative. The side with the JP1 label is the positive side. Typically a battery's red wire is the positive wire. Ideally you want a battery that has a 10k ohm thermistor for temperature protection by the Edison too. + +You can also use any charger with a USB plug, including a wall power charger. The Explorer boards have pass through charging, so this is also how you will charge the LiPo battery. + +#### Battery safety and care + +You should monitor the rig periodically - **especially the LiPo battery**, checking for swelling or damage. Immediately discontinue use of any battery that shows sign of swelling or damage. + +LiPo batteries are great for a lot of things, but taking damage is not one of them. Please treat LiPo batteries with care. Keep them protected from puncture. The Explorer board has some “pointy” parts on the underside, so providing some protection from the board’s squish is a good idea. A small piece of protection (such as a business card or non-conductive thin foam sheet) will help protect the battery from the board above it. + +Since there is some warmth with an OpenAPS rig, it is also not recommended to put a rig unprotected in a pocket close to the body. The LiPo battery can become warped from the heat or bent from being in the pocket and potentially compromised. A durable case or waist-belt pouch is a good idea (see [here](<#cases>) for both hard and soft case ideas). + +The connections between the LiPo battery and its red and black wires are fragile and can break easily. Consider taping the wires to the battery with electrical tape as described in SparkFun's LiPo battery care [tutorial](https://www.sparkfun.com/tutorials/241). (See the Reinforcing the Power Cables section.) This will stabilize the wires and relieve tension on the connections. + +### Radio stick (only if not using Explorer board) + +We recommend an Explorer Board with a built-in radio ([see above](<#explorer-board-block>)), because if you get an Explorer Board, you don't need an additional radio stick or CC-Debugger. + +If you don't use an Explorer board, you can use a number of radio sticks: a [TI-USB-Sticks](http://www.ti.com/tool/cc1111emk868-915), running [subg_rfspy](https://github.com/ps2/subg_rfspy); [Wireless Things ERF](https://www.wirelessthings.net/erf-0-1-pin-spaced-radio-module); [Wireless Things Slice of Radio](https://www.wirelessthings.net/slice-of-radio-wireless-rf-transciever-for-the-raspberry-pi) a Slice of Radio; or a Rileylink. For details about setup with these other stick and board options, [the best instructions will be found in the mmeowlink wiki](https://github.com/oskarpearson/mmeowlink/wiki) for setting up your board and stick. Note you may also need a CC debugger for these, and also note that it will be more work as the documentation is designed for the Edison/Explorer Board setup as the easiest path forward. + +### USB Cables + +You will need two DATA micro USB cables - with a micro connector on one end and a standard (Type A) connector on the other. Most cables will work fine, but some prefer to select lengths. You may already have one for charging a Dexcom receiver, or an Android phone, lying around at home. If you don't, here are examples of ones that will work: + * [Monoprice Premium USB to Micro USB Charge, Sync Cable - 3ft](http://www.monoprice.com/Product?c_id=103&cp_id=10303&cs_id=1030307&p_id=9763&seq=1&format=2). + * [**3 ft long cable, USB-microB - link**](https://www.adafruit.com/products/592) + * [**6 inch long cable, USB-microB - link**](https://www.adafruit.com/products/898) + +Warning: bad cables cause a lot of headaches during the Edison flashing process, so it may be worth verifying before you start if you have good cables that can transfer data. + +### Optional: Micro USB to Micro USB OTG Cable for offline looping + +You may want to connect your Dexcom receiver (G4 or non-touchscreen G5) to your Explorer Block for offline looping. For this you will need to use a micro USB to micro USB OTG cable (or an OTG adapter). Here is an example of a cable that will work: [BestGameSetups Micro USB to Micro USB OTG (On-The-Go) 12" (30cm) Data Cable](https://www.amazon.com/dp/B00TQOEST0/ref=cm_sw_r_cp_api_Niqfzb3B4RJJW). + +### Optional: antenna to increase pump - rig range + +The easiest way to increase the range of your rig is to purchase a "wire whip" antenna to add to your rig. [Here is one available at Mouser (915MHz only)](https://www.mouser.com/ProductDetail/620-66089-0930?R=66089-0930virtualkey65480000virtualkey620-66089-0930) or for 866/868 MHz [also availabe at Mouser](https://www.mouser.at/ProductDetail/Anaren/66089-0830?qs=pH7abCSN9NPb5X5zwyxl2w==). You can buy one [at Enhanced Radio Devices](https://www.enhancedradio.com/collections/all) as well. You may consider ordering this along with your Explorer Board, or you can wait and see how happy you are with the range without it. + +### Nuts and Bolts + +You will likely want to screw your Edison onto the Explorer Block to stabilize the rig. You will need two M2 screws, two M2 nuts, and two spacers or standoffs to support the 3mm +between the Edison and Explorer Board. The Explorer Board is currently being shipped with M2 screws, 3mm spacers, and M2 nuts, but you may want spares (or may have gotten it used). Here are some examples of options: +- [M2 cap screws](https://www.amazon.com/iExcell-Stainless-Steel-Socket-Screws/dp/B07FLLGW19). +- [M3 nuts to use as spacers](https://www.amazon.com/uxcell-Thread-Stainless-Metric-Fastener/dp/B01M0D7U5V/) - if using these, or another 3mm spacer option, your M2 screws should be just long enough to fit through the spacers and screw into the M2 nuts on the other side. You can also use a stack of washers or some [3mm nylon spacers](https://www.amazon.com/Electronics-Salon-Assortment-Screws-Plastic-Standoff/dp/B074N5HD42/). +- [M2 nuts](https://www.amazon.com/gp/product/B07H3SXSN2/) + +(Note: Sparkfun has discontinued its kits of hardware specifically for the Edison, but for reference here are the specs for the [Sparkfun Intel Edison Hardware Pack](https://www.sparkfun.com/products/13187).) + +### Cases + +You can use a variety of cases, either soft or hard. Make sure to check the case design to make sure it will support your preferred rig setup and battery size/type. Also, be careful with inserting your rig into some 3D-printed cases so you do not harm the board and/or the battery. + +#### Soft Cases +* [TallyGear soft case](http://www.tallygear.com/index.php?route=product/category&path=120) - these are the soft cases Dana uses ([see this example](https://twitter.com/danamlewis/status/792782116140388353)). The OpenAPS-sized case can be made any any pattern/fabric she uses elsewhere on the site. +* [Custom soft case from Tallygear with a neoprene divider between battery and rig compartments](https://photos.app.goo.gl/gSubQDMDUqwDsJu18) +* [JD Burrows SD card case](https://www.officeworks.com.au/shop/officeworks/p/j-burrows-sd-and-usb-case-blue-jbsdcasbu) - this is a hard / soft case which fits the rig with a 2500mAh battery perfectly, can also fit a spare AAA pump battery (Australia) + +#### Hard cases + +**Warning: be careful if you select a hard case. Some may be designed for a certain size/shape battery; and attempting to jam a rig in may harm the board and/or the battery.** + +Also: a hard case may make you less likely to look at your rig directly. You should monitor the rig periodically - **especially the battery**, checking for swelling or damage. Immediately discontinue use of any battery that shows sign of swelling or damage. + +Generic hard cases: + +* [RadioShack Project Enclosure (3x2x1 inch)](https://www.radioshack.com/products/radioshack-project-enclosure-3x2x1?utm_medium=cpc&utm_source=googlepla&variant=20332262405&gclid=Cj0KEQiA-MPCBRCZ0q23tPGm6_8BEiQAgw_bAkpDZCXfIgbEw8bq76VHtV5mLwR2kHKfJrsGsF3uqqgaAtxP8P8HAQ) +* [Small clear plastic case perfect for larger Sparkfun 2000 mAh battery: #8483](http://www.ebay.com/itm/272062812611) +* [Small Plastic Clear Case for 2500 mAh battery](http://www.ebay.com/itm/272062812611) - Since a Tic-Tac box is too small for the 2500 mAh battery. + +Cases for Edison plus battery: + +* [Ken Stack's 3D design for a case with the battery next to the board](https://github.com/Perceptus/explorer_board_case) +* [Rob Kresha's design with the battery compartment stacked on-top of the board compartment](http://www.thingiverse.com/thing:2020161) +* [Gustavo's 3D design](https://github.com/Perceptus/explorer_board_case_2) +* [Sulka Haro's 3D design](https://www.tinkercad.com/things/4a6VffpcuNt) +* [tazitoo's 3D design: CAD](https://www.tinkercad.com/things/aRYGnHXt7Ta-explorer-case/editv2) ([or STL for 3D printing](http://www.thingiverse.com/thing:2106917)) +* [danimaniac's Protective Cases & Accessories](https://github.com/danimaniac/OpenAPS-Explorer-Board-Edison-vented-case) +* [Luis's ventilated acrylic simple design](https://drive.google.com/drive/folders/0BxeFg9yJZ_FZdWJEcG5KMXdUMjg?usp=sharing) +* [Robert Silvers and Eric Burt's case for Explorer and 2500 mAh battery](http://www.thingiverse.com/thing:2282398) +* [Robert Silvers' case for Explorer and 2000 or 2500 mAh battery](http://www.thingiverse.com/thing:2291125) +* [tynbendad's case for 18650 battery](https://www.thingiverse.com/thing:2798858) + +Cases for Edison plus G4 receiver: + +* [jimrandomh's 3D printed design for Edison and a G4 receiver together](http://conceptspacecartography.com/my-openaps-g4-case/) + +Other non-case protection options + +* [Heat Shrink Tubing](https://www.amazon.com/gp/product/B009IILEVY) + +## Building and understanding your Edison-based rig + +### Putting the Edison and Explorer Board together + +The Explorer board is where all the communications are housed for the rig, as well as the battery charger. The Edison is the mini-computer where all the OpenAPS code will be sent and used. In order for this to work, first you have to screw and connect the Edison and Explorer Board together with the nuts and bolts. + +The nuts and bolts are tiny, and the spaces are a little tight. I find it really helps to use a set of tweezers and a small Phillips head screwdriver. + +It's easiest to start with the Explorer board and put on 2 nuts and gold screws (nuts on the side with most of the wiring) inside the little outline where the Edison will eventually sit. Gold screws should be placed as shown, with nuts on the backside. Then, lay the Edison board on top, aligning the screw holes. Use a small Phillips head screwdriver to tighten the screws into the gold screws beneath them. The Edison board should not wobble, and should feel secure when you are done. Attach your battery into the explorer board plug. A single red light should appear and stay lit. During the course of your OpenAPS rig use, it's good practice to periodically check that the nuts and screws stay tightened. If they come loose, the Edison can wobble off the connection to the Explorer board and you will either get looping failures (if it's loose) or be unable to connect to the Edison (if it comes completely off). + +![Edison/Explorer Board rig with red light on](../Images/Edison/Edison_Explorer_Board.png) + +### Optional: adding an antenna + +If you are adding a wire whip antenna to improve the range of your rig, it simply clips on to the Explorer Board. The picture below shows the antenna clipped on and extended from the board; but you can experiment with wrapping the antenna around your rig to fit in your preferred case to see various impacts to the range. + +![Image of Antenna](../Images/antenna1.jpg) + +### Where is the power button? + +The little black button on the end of the board near the JST connector is the power button. If you want to reboot your rig, the easiest way is to hold down the tiny power button for 10-15 seconds until the power light turns off. Wait a couple seconds and then press and hold the power button again until the light turns back on. Give the loop a couple minutes to get itself going again. Rebooting solves a majority of rig issues. + +### Where is the radio? + +The radio and antenna are down on the end of the Explorer board where you see a little white stick (opposite end of the board from where your battery connects at the JST connector). + +### What the lights mean and where they are + +* The LED between the two ports is the power. If this light is on, your rig is on. +* The LED in the corner is the charging indictator. +* The two next to the microUSBs (one green on the latest boards) are for the cc1110 radio chip. By default they just blink once each when you mmtune or otherwise reset it. + +### Charging the LiPo Battery + +You can use the little white block that comes with an iPhone (or similar charger) and a microB-USB cable. The same cables you used to setup the rig and connect to the computer will work for charging, too. Either one of the USB ports on the Explorer board will work for charging. When charging is active, there is an extra red light on in the corner of the Explorer board. When charging is complete, that corner red light will turn off. It may come back on periodically as the battery "tops off". You won’t do any damage leaving the rig plugged in for longer than the charge takes. + +While the rig is plugged in for charging, the Nightscout battery pill will read approximately 65%. This is because it is reading the charging voltage rather than the battery voltage. Once you disconnect from the charger, the Nightscout battery pill will display the LiPo battery's voltage and percent again. + +### Optional: increasing range for North American pumps by cutting radio trace + +Another option to increase the range of your rig is to tune the existing on-board antenna by cutting it. The antenna on the Explorer Block is a hidden strip of copper underneath the green outer coating. + +The antenna is labeled A1. It will have its maximum power at 868 MHz. The antenna has a line across it at one point with a label that says "915". The antenna defaults to the 868 MHz range, which is what WW pumps use. + +If you have a US pump, mmtune will run and tune to something near 916MHz. Even with the 868 MHz antenna, you should get half a dozen feet or more of range on average. If you want to boost the range of your antenna by a couple more feet, then you cut through the outer coating and the copper on that line. For North American (NA) or Canadian/Australian (CA) pumps (using the 916MHz band), you're looking to cut near the white line that is between the 1 and the 5 in the "915." Consider cutting on the 1-side rather than the exact spot where the white "cut" line is drawn because it is so close to the corner where the rest of the copper wire goes. + +![Image of Antenna](../Images/antenna0.jpg) + +Before doing this, remember to disconnect any attached battery or power source. To make the cut, use a sharp x-acto blade to cut through the copper just beneath the green surface of board. It will take a few swipes and you'll hear a small scraping noise when you get through the wire. Make sure you've cut all the way through the wire to the green circuit board material on the other side. A single clean cut is sufficient, but if the cut doesn't look clean you could make two cuts and then dig out the circumscribed piece and then reseal the copper with nail polish. With that cut, the antenna will have maximum power near 915 MHz. + +Watch this [video](https://www.facebook.com/groups/TheLoopedGroup/permalink/1854229718127019/?hc_location=ufi) for an example. + +If you're unsure whether you need to cut your Explorer Block's antenna, you probably don't. And if you decide you need slightly more range after using the Edison+Explorer rig for a few weeks, you can always come back later and do so then. + diff --git a/docs/docs/Gear Up/hardware.md b/docs/docs/Gear Up/hardware-overview.md similarity index 66% rename from docs/docs/Gear Up/hardware.md rename to docs/docs/Gear Up/hardware-overview.md index 17a020198..7800e6426 100644 --- a/docs/docs/Gear Up/hardware.md +++ b/docs/docs/Gear Up/hardware-overview.md @@ -2,16 +2,15 @@ This section describes the hardware components required for a 'typical' OpenAPS implementation. There are numerous variations and substitutions that can be made but the following items are recommended for getting started. -_The basic setup requires:_ +The basic setup requires: + * a compatible insulin pump * a CGM -* a small computer (Intel Edison, or Raspberry Pi for example) and a radio board/stick (i.e. Explorer Board for Edison or Explorer HAT for Pi) +* a small computer (Intel Edison, or Raspberry Pi for example) and a radio board/stick (e.g. Explorer Board for Edison or Explorer HAT for Pi) * a battery If you come across something that doesn't seem to work, is no longer available, or if you have a notable alternative, feel free to edit this documentation with your suggestions. -#### Notes about deprecated hardware setups - -Carelink can be used with up to oref0 0.6.3. However, it will not be used with oref0 0.7.0 moving forward. Carelink has poor range and will likely frustrate you. Please see the rig parts page for current hardware recommendations. +**Note about deprecated hardware setups:** Carelink can be used with up to oref0 0.6.2. However, it will not be used with oref0 0.7.0 moving forward. Carelink has poor range and will likely frustrate you. Please see the rig parts page for current hardware recommendations. TI sticks (via USB) are not supported in oref0 0.7.0, but they can be wired to the SPI or UART pins on the Raspberry Pi. Please see the rig parts page for documentation on how to do this. diff --git a/docs/docs/Gear Up/index.rst b/docs/docs/Gear Up/index.rst deleted file mode 100644 index 1f78ea4a1..000000000 --- a/docs/docs/Gear Up/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Gear Up ----------------------- - -.. toctree:: - :maxdepth: 4 - - - hardware - pump - CGM - Get your rig parts diff --git a/docs/docs/Gear Up/pi-based-rigs.md b/docs/docs/Gear Up/pi-based-rigs.md new file mode 100644 index 000000000..400cd8ab5 --- /dev/null +++ b/docs/docs/Gear Up/pi-based-rigs.md @@ -0,0 +1,251 @@ +# Pi-based setups with the Explorer HAT + +## Parts you'll need + +Summary of what you need for a Pi/HAT rig: +* [Explorer HAT](<#hat>) +* [Pi0WH (recommended) or Pi 3](<#pi>) +* [Battery](<#battery>) +* [SD Card](<#sd-card>) + +### HAT: +As of April 2018, there is be a Pi+HAT rig as an option for closing the loop with OpenAPS. The HAT can be ordered from the same place that makes the Explorer Board ([click here](https://enhanced-radio-devices.myshopify.com/products/900mhz-explorer-hat?variant=1950212653065)). We call it the "Explorer HAT", to differentiate from the Explorer "Board" that goes with the Edison (see below). + +![Explorer Hat](../Images/explorerhat.png) + +### PI +You also need a Raspberry Pi. Many users are opting for the "Raspberry Pi Zero WH" - with headers - so you don't have to solder, and can simply add the HAT onto the Pi. See this [PiZeroWH from Adafruit](https://www.adafruit.com/product/3708), or [from other sellers around the world](https://www.raspberrypi.org/products/#buy-now-modal) + +As an alternative, you can also use the HAT with a Raspberry Pi 3. + +### Battery +Lipo batteries are typically used to power the rig on the go because they charge quickly and come in a variety of compact sizes. When choosing a battery, you have a trade-off between a larger battery with longer duration or a smaller battery with shorter duration that is easier to carry around. A 2000 mah battery is roughly the size of the Raspberry Pi0, and can last around 4 hours. You'll want a "1S" type, which uses a single cell and outputs at 3.7 VDC. It needs a JST connector to plug into the Raspberry Pi. See this [battery from HobbyKing](https://hobbyking.com/en_us/turnigy-2000mah-1s-1c-lipoly-w-2-pin-jst-ph-connector.html?___store=en_us). + +If you will need to run longer than that while unplugged from wall power, consider a portable charger. These are in widespread use for cell phones and commonly available in a large number of sizes. Here is an example [portable charger from Amazon](https://www.amazon.com/Anker-PowerCore-Ultra-Compact-High-speed-Technology/dp/B0194WDVHI/ref=sr_1_6?ie=UTF8&qid=1532089932&sr=8-6&keywords=backup+battery&dpID=31B5rBNP%252B8L&preST=_SY300_QL70_&dpSrc=srch). Using a USB to micro-USB adapter you can power the rig from the portable charger by plugging the charger into the Power port, which is the micro-USB port nearest the corner of the Pi0. + +**Note**: You will probably want to underclock your Raspberry Pi to get a longer battery life. [See this for details](<../Build Your Rig/step-5-finishing-setup#optional-step-improving-the-battery-life-of-your-raspberry-pi>). + +### SD card +An 8 GB SD card should provide plenty of space for the linux operating system, OpenAPS code and storage for log files. The ability to use larger and removable storage is one of the advantages of the Raspberry Pi. You can get a [MicroSD card and adapter from Adafruit](https://www.adafruit.com/product/2692) when you order your Pi and Hat. Or you can get an equivalent [8 GB SD card from Amazon](https://www.amazon.com/Kingston-microSDHC-Class-Memory-SDC4/dp/B00200K1TS/ref=sr_1_8?s=wireless&ie=UTF8&qid=1532090813&sr=1-8&keywords=8gb+micro+sd) or other sellers. + +### Note about Pi+HAT cases +Because we are still optimizing the software to be as power-efficient as possible, we have not narrowed down on the best recommended battery. You may want to use a soft case for ease of access to the components, flexible arrangement and the ability to use a variety of battery sizes. If you are using the 2000 mah battery above, you can use this [3d printed hard case](https://www.thingiverse.com/thing:3010231) to protect the rig and battery in a relatively compact package. The [design is built in OnShape](https://cad.onshape.com/documents/74459dfcb527ad12c33660aa/w/2be92a72bb7f1c83eb091de2/e/b4fa9c3be204ffa3dea128a1), which has a free access level subscription for public domain documents. You can make a copy and tweak the design to your liking. + +#### Putting together and using your Pi/HAT rig + +If you chose a "Pi Zero WH" (with headers), you will place the HAT on the Pi. + +##### Buttons and Menu System + +The Explorer Board Pi HAT includes a 128x64 OLED display with two general purpose buttons to navigate an included menu system. + +##### Button Navigation + +The Pi HAT has two general purpose buttons labeled "Up" and "Down". A single press of the "Up" button will move the menu selection cursor up a single menu item and a single press of the "Down" button will move the menu selection cursor down a single menu item. + +A double press of the "Down" button will enter in currently selected menu item as indicated by the ">" next to a menu item. + +A double press of the "Up" button will take you back to the previous screen. + +##### LEDs + +The Pi HAT offers 4 LEDs labeled with D1-D4. D1 is the charging LED and works as described above. D2 is the battery low indicator. It turns orange when the LiPo battery voltage goes below 3.6 V or when the rig is plugged and the battery switch is on OFF. D3 and D4 are connected to the CC1110 radio processor and are controlled by the subg_rfspy radio firmware while resetting the radio. That happens repeatedly during wait-for-silence. + +##### Menu Items + +
+ The current tree of available menu items (click to expand): +
+ +* OpenAPS + * Status Graph + * Set Temp Target + * Cancel temp Target + * Eating Soon: 60m@80 + * Speaking: 45m@110 + * Walking: 45m@120 + * Running: 60m@140 + * Status Text + * Enacted Reason + * Show pump-loop.log + * Unicorn Logo +* Wifi + * Current Wifi Network + * Current Hostname + * Current IP Address + * Show network.log +* System + * Voltage + * Display Tests + * Checkerboard 1 + * Checkerboard 2 + * All On + * Boxes 1 + * Boxes 2 + * lsusb + * Reboot + * Cancel Reboot + +
+
+ +A series of images of the menu items can be [viewed here](https://imgur.com/a/9qLf93B). + +##### Charging + +The rig can be charged via microUSB. Like an Edison rig, you can use a single cell (1s) lipo battery or similar; or use wall power. + +**Note:** the charging LED on the board is not working currently (unless you remove the Q3 transistor). Currently, it’s basically just a “plugged into the wall” indicator. The only side effect of removing Q3 is on the binary charging signal to the Pi (which doesn’t work anyway, and we’ve not tried to use). The voltage monitoring should work fine either way, but while the rig is charging will report 4.2V (“fully charged”) any time the battery is more than about 50% charged. So to be sure if it’s charged you should unplug the rig. + +**2nd Note:** make sure the battery plug is switched to ON while the rig is plugged. Otherwise the battery won't charge. + + +*** + + +## Building and using your Pi/HAT rig + +If you chose a "Pi Zero WH" (with headers), you will place the HAT on the Pi. + +### Buttons and Menu System + +The Explorer Board Pi HAT includes a 128x64 OLED display with two general purpose buttons to navigate an included menu system. + +### Button Navigation + +The Pi HAT has two general purpose buttons labeled "Up" and "Down". A single press of the "Up" button will move the menu selection cursor up a single menu item and a single press of the "Down" button will move the menu selection cursor down a single menu item. + +A double press of the "Down" button will enter in currently selected menu item as indicated by the ">" next to a menu item. + +A double press of the "Up" button will take you back to the previous screen. + +#### Menu Items + +
+ The current tree of available menu items (click to expand): +
+ +* OpenAPS + * Status Graph + * Set Temp Target + * Cancel temp Target + * Eating Soon: 60m@80 + * Speaking: 45m@110 + * Walking: 45m@120 + * Running: 60m@140 + * Status Text + * Enacted Reason + * Show pump-loop.log + * Unicorn Logo +* Wifi + * Current Wifi Network + * Current Hostname + * Current IP Address + * Show network.log +* System + * Voltage + * Display Tests + * Checkerboard 1 + * Checkerboard 2 + * All On + * Boxes 1 + * Boxes 2 + * lsusb + * Reboot + * Cancel Reboot + +
+
+ +A series of images of the menu items can be [viewed here](https://imgur.com/a/9qLf93B). + +### Charging and power + +The rig can be charged via microUSB. Like an Edison rig, you can use a single cell (1s) lipo battery or similar; or use wall power. + +**Note:** the charging LED on the board is not working currently (unless you remove the Q3 transistor). Currently, it’s basically just a “plugged into the wall” indicator. The only side effect of removing Q3 is on the binary charging signal to the Pi (which doesn’t work anyway, and we’ve not tried to use). The voltage monitoring should work fine either way, but while the rig is charging will report 4.2V (“fully charged”) any time the battery is more than about 50% charged. So to be sure if it’s charged you should unplug the rig. + +**2nd Note:** make sure the battery plug is switched to ON while the rig is plugged. Otherwise the battery won't charge. + +### LEDs + +The Pi HAT offers 4 LEDs labeled with D1-D4. D1 is the charging LED and works as described above. D2 is the battery low indicator. It turns orange when the LiPo battery voltage goes below 3.6 V or when the rig is plugged and the battery switch is on OFF. D3 and D4 are connected to the CC1110 radio processor and are controlled by the subg_rfspy radio firmware while resetting the radio. That happens repeatedly during wait-for-silence. + + +## Pi-based setups with RFM69HCW (experimental) + +The Pi + RFM69HCW is still experimental! + +If you are a maker person or a bit into soldering electronics at least, you may also build your rig with a piece of hardware, that is a lot cheaper than the Explorer HAT, although it does **not** have the screen. You also won't have LEDs indicating status, no battery charging and there will not be (m)any 3d printable case models. If it's your only option because you're on a budget and can't afford to spend 150 bucks on a rig, please think about this step twice. This one will cost you only 30, but a lot of extra time. + +
+ +Click here to expand and see pictures of a rig with a Pi0WH and RFM69HCW:: +
+ +![Picture of RPI0WH with FM69HCW connected via breadboard](../Images/build-your-rig/RPi_breadboard_connected_to_RFM69HCW.jpg) + +![Picture of RPI0WH with FM69HCW view from the top ](../Images/build-your-rig/RPi_soldered_RFM69HCW_top_view.jpg) + +![Picture of RPI0WH with FM69HCW view of soldered connections](../Images/build-your-rig/RPi_soldered_RFM69HCW.jpg) + +![Picture of RPI0WH with FM69HCW and case](../Images/build-your-rig/RPi_open_case_with_battery_view_on_RFM69HCW.jpg) + +Here's a rough-and-ready budget version of a rig put together: contents of a 2000mAh powerbank, a plastic housing, a micro USB cable and some more soldering and hot glue. BE AWARE that this case will most likely overheat the Pi after a while. You need to at least drill some venting holes into the lid. + +![Picture of the RPI0WH with case](../Images/build-your-rig/RPi_open_case_with_Pi_on_top.jpg) +![Picture of the RPI0WH with case open and a view of the battery](../Images/build-your-rig/RPi_open_case_with_battery_view_on_RFM69HCW.jpg) +![Picture of the RPI0WH with case next to the pump](../Images/build-your-rig/Rig_case_with_pump.jpg) + +
+ +### Summary of what you need: +* Raspberry Pi Zero +* RFM69HCW +* [microSD Card]((<../Gear Up/pi-based-rigs#sd-card)) +* Bread board +* Jumper wires +* Soldering iron +* Power source via Micro USB + +### The Raspberry Pi Zero + +For this setup, you want a Raspberry Pi Zero WH. (The "H" means it has Header pins). (Also, a regular Raspberry Pi 3 model B works fine.) + +### RFM69HCW +You can buy this board e.g. [here](https://www.adafruit.com/product/3070), but you can really buy it wherever you want. These boards are, like the RPi Zero, very common. Just make sure you get the right frequency. 868/915 MHz is correct. All others are wrong. + +### Breadboard +Any breadboard will do, no special requirements. + +### Soldering +You need to solder the pin stripe into the RFM69HCW. Insert the pin stripe from the bottom of the board, with the short endings reaching through the holes. Fixate a bit, so you can rest the soldering iron tip on the pins and the board. + +Solder the included pin stripe diligently into the 9 holes named +VIN GND EN G0 SCK MISO MOSI CS RST + +Cut an antenna at your preferred length corresponding to your frequency. This can be a simple piece of isolated, unshielded wire. (I simply took one of the jumper wires for my first try.) +Calculate your length here: https://m0ukd.com/calculators/quarter-wave-ground-plane-antenna-calculator/ and just use the value from A (first green box). This should be the length of your antenna, from the soldering point on the board to the tip. + +Solder it to the board. It's the hole near the "o" from Radio. Make sure to not connect the soldering to the ground plates left and right from the hole. This antenna is really only connected to the one hole. + +This is your connection scheme for the RPi to RFM69HCW. Stick the RFM69HCW on a bread board, and connect: + +Board | Connect | Connect | Connect | Connect | Connect | Connect | Connect | Connect +------|------|------|------|------|------|------|------|------ +RPi | 3.3V | GND | MOSI | MISO | SCLK | | CEO_N || +RPi PIN | 17 | 25 | 19 | 21 | 23 | 16 | 24 | 18 +RFM69HCW | VIN or 3.3V | GND | MOSI | MISO | SCK or CLK | G0 or DIO0 | CS or NSS | RST or RESET + +![Picture of RPI0WH with FM69HCW connection diagram](../Images/build-your-rig/rpii2RFM69HCW.JPG) + + +[Here is a copy of a a sophisticated schematic](https://easyeda.com/editor#id=4128da76dc1644c9a1cf6fd53ec1885f|003da073fac94f058c872b643d1d9e22). (Press "miniloop v1.0" to see the diagram). + +After that, you're ready to install OpenAPS. + +*** + + + + diff --git a/docs/docs/Gear Up/pump.md b/docs/docs/Gear Up/pump.md index 291147a78..3602800d8 100644 --- a/docs/docs/Gear Up/pump.md +++ b/docs/docs/Gear Up/pump.md @@ -25,7 +25,7 @@ A double-check for pump compatibility is to look for the ABSENCE of PC connect i * If "PC Connect" is absent, then the pump should be able to receive temp basal commands and be compatible. * If there is no "Connect Devices" menu, then the pump should be able to receive temp basal commands and be compatible. * This is the case for the 512/712, the 515/715 and 522/722 models. - * For 512/712 pumps, you will not be able to use an advanced feature (SMB) but will be able to do basic temp-basal based looping. + * For 512/712 pumps, certain commands like Read Settings, BG Targets and certain Read Basal Profile are not available, and require creating special files for the missing info to successfully run the loop ([Instructions for 512/712 users, click here](<../Build Your Rig/step-3-setup-script#512-and-712-pump-users-only-important-extra-setup-steps>)). 512/712 users are not going to be able to use an advanced feature - (e)SMB - but will be able to do basic looping. Note that not _all_ possible sellers of pumps will accuratly describe the model number: if they are willing to sell a pump they may not have interest in setting it up for looping, and the distinctions about model numbers and firmware version may not be important to them. It will be for you though! Therefore, it's prudent to verify the model by seeing pctures and/or videos of the pump in action. @@ -73,4 +73,4 @@ If you need to send your pump away to Medtronic for repair, be aware that during ## Tips for longer battery life -If you are new to looping, one of the first things you will notice is that you will go through batteries _very_ quickly. Even known good alkaline batteries may only last a few days of 24/7 looping. Many OpenAPS users recommend [Energizer Ultimate Lithium](https://www.amazon.com/Energizer-Ultimate-Lithium-Batteries-Count/dp/B06ZYWKBRB/) batteries. These should last a week or more. Just ensure you use the correct settings if you are using NightScout - [see here for details about alert settings in Nightscout for the different battery types](https://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/nightscout-setup.html#battery-monitoring) +If you are new to looping, one of the first things you will notice is that you will go through batteries _very_ quickly. Even known good alkaline batteries may only last a few days of 24/7 looping. Many OpenAPS users recommend [Energizer Ultimate Lithium](https://www.amazon.com/Energizer-Ultimate-Lithium-Batteries-Count/dp/B06ZYWKBRB/) batteries. These should last a week or more. Just ensure you use the correct settings if you are using NightScout - [see here for details about alert settings in Nightscout for the different battery types](<../While You Wait For Gear/nightscout-setup#battery-monitoring>) diff --git a/docs/docs/Gear Up/rig-options.md b/docs/docs/Gear Up/rig-options.md new file mode 100644 index 000000000..32e20279d --- /dev/null +++ b/docs/docs/Gear Up/rig-options.md @@ -0,0 +1,13 @@ +# Your rig hardware options + +You have two main options for hardware: + +1. The most recommended rig has been an Edison + Explorer Board. Unfortunately Intel stopped making the Edison boards as of 2018. If you can find an Intel Edison (eBay, local stores, etc - this is still very possible), this is still a highly recommmended rig. It is the smallest rig (and easily portable), with better battery life because it is power efficient. [Go here for the list of hardware and setup instructions for Edison setups](<../Gear Up/edison-explorer-board>). + +2. The other option is a Raspberry Pi-based setup, with the new Explorer HAT. This rig setup makes it easier to see information when offline because it has an onboard screen for displaying readouts. [Go here for hardware required and setup instructions for Pi/HAT setups](<../Gear Up/pi-based-rigs>). There is also an experimental alternative to an Explorer HAT, RFM69HCW, which can serve as the radio on a Pi-based rig, but will not have the screen, and requires you to solder. + +## What happens if you have multiple rigs? + +If you have multiple OpenAPS rigs, they’re built to be polite to each other. Even if you had two or more rigs in same room, they won’t trip each other up. They “wait for silence” before issuing any commands to the pump. By having multiple rigs throughout a house, you can move from room-to-room without carrying rigs because the rigs will pass-off comms as you moves in and out of the rig’s range. Stationary rigs will not need LiPo batteries and can be plugged directly into a wall charger from the Explorer board. + +Just like multiple Edison rigs play well together, an Edison and a Pi rig can also work fine side by side. As always, best practice is to make sure they're in the same feature set - don't have one type of rig using SMB's if the other hardware has an old code version that isn't aware of SMB's. diff --git a/docs/docs/Give Back-Pay It Forward/data-commons-data-donation.md b/docs/docs/Give Back-Pay It Forward/data-commons-data-donation.md index 29c3f5413..af1062ae7 100644 --- a/docs/docs/Give Back-Pay It Forward/data-commons-data-donation.md +++ b/docs/docs/Give Back-Pay It Forward/data-commons-data-donation.md @@ -35,7 +35,7 @@ For more background, see [the OpenAPS.org Data Commons page](https://openaps.org * **C**. Now that you have data in Open Humans, next [click here to go directly to the OpenAPS Data Commons project](https://www.openhumans.org/activity/openaps-data-commons/). * **1**. Scroll down and click "join". Carefully read the terms & consent to make sure you understand how your data is going to be used. You can also read the OpenAPS Data Commons research criteria here to better understand what criteria research projects are held to before they may be granted access to the data commons data. Note: the data will not be publicly available; it will only be shared privately and securely with individuals or research groups that meet this criteria and are vetted by a volunteer group from our community. * **2**. Agree to share your data with the OpenAPS Data Commons. - * **3**. You will then be redirected to a survey to also provide basic data to be added to the data you uploaded – please also fill out this survey information. (This data will be tied to your OpenHumansdata shared with the Data Commons, which should prevent having to answer the same questions (i.e. how long you have had diabetes) on any future research studies that have questionnaires.) + * **3**. You will then be redirected to a survey to also provide basic data to be added to the data you uploaded – please also fill out this survey information. (This data will be tied to your OpenHumansdata shared with the Data Commons, which should prevent having to answer the same questions (e.g. how long you have had diabetes) on any future research studies that have questionnaires.) * **4**. Hooray! You’ve just added data to the OpenAPS Data Commons.Thank you for contributing your data! * Please note: * We may contact you in the future (we will not see your email address) to request to upload a new batch of data or fill out a survey for another research study that is accessing the Data Commons data. diff --git a/docs/docs/Give Back-Pay It Forward/index.rst b/docs/docs/Give Back-Pay It Forward/index.rst deleted file mode 100644 index d6b25ba6e..000000000 --- a/docs/docs/Give Back-Pay It Forward/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Give Back/Pay it Forward ----------------------- - -.. toctree:: - :maxdepth: 4 - - - data-commons-data-donation - contribute diff --git a/docs/docs/Customize-Iterate/autosens.md b/docs/docs/How it works/autosens.md similarity index 74% rename from docs/docs/Customize-Iterate/autosens.md rename to docs/docs/How it works/autosens.md index 1723b02a7..ed43dd61e 100644 --- a/docs/docs/Customize-Iterate/autosens.md +++ b/docs/docs/How it works/autosens.md @@ -1,10 +1,20 @@ # 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". Autosens allows 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. -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. +## The difference between autotune and autosens: + +Autosensitivity/resistance mode (aka “autosens”) is an advanced feature in OpenAPS that you can enable that looks at 24 hours of data and makes adjustments to ISF and targets based on the resulting sensitivity calculations. If you have a dying pump site, or have been sick and are resistant, your ISF is likely to be calculated down by autosens and then used in OpenAPS calculations accordingly. The opposite for being more sensitive is true as well. [(Here’s a blog post describing autosensitivity during sick days.)](https://diyps.org/2016/12/01/sick-days-with-a-diy-closed-loop-openaps/) + +Autosens will make temporary 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. + +Autotune, by contrast, is designed to iteratively adjust basals, ISF, and carb ratio over the course of weeks. Because it makes changes more slowly than autosens, autotune ends up drawing on a larger pool of data, and is therefore able to differentiate whether and how basals and/or ISF need to be adjusted, and also whether carb ratio needs to be changed. Whereas we don’t recommend changing basals or ISF based on the output of autosens (because it’s only looking at 24h of data, and can't tell apart the effects of basals vs. the effect of ISF), autotune is intended to be used to help guide basal, ISF, *and* carb ratio changes because it’s tracking trends over a large period of time. + +## Understanding autosens logs 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: -****************** + +``` Calculating sensitivity using 8h of non-exluded data Setting lastSiteChange to Tue Dec 19 2017 09:42:24 GMT-0600 (CST) using timestamp 2017-12-19T09:42:24-06:00 u(xxxxxxxxxxxx11hxxxxxxxxxxxx12h=43g(xxxxxxxxxxxx13hxxxxxxxxxxxx14h=xxx45gxxxxxxxxx15hxxxxxxxxxxx16h=xxxxxxxx17hxxxxxx0gx)u(xxxxx18h=x35g(xx46gxxxxxxxxx19hxxxxxxx38gxxxxx20h=xxxxxxxxxxxx21hxxxxxx-x-x-x-x-x-x-22h=x-x-x-x-x-xxxxxxx23hxx0gx @@ -23,18 +33,19 @@ Sensitivity normal. ISF adjusted from 120 to 120 Using 24h autosens ratio of 1 (ISF 120) Autosens refreshed: {"ratio":1} -****************** +``` + Here's what each symbol above means: "x" : deviation is excluded. All deviations are excluded when there is COB through the time that COB drops to zero (carbs are fully absorbed) and deviations go negative once again. This is appropriate to eliminate the impact of rising BG due to carb absorption from sensitivity calcualations and not falsely attribute it to insulin resistance. Deviations may also be excluded becuase of an unexplained high deviation (site failure, etc). "+" : deviation was above what was expected - "-" : deviation was below what was expected. In addition, if a high temp target is running (i.e. activity mode), a negative deviation is added every 5 minutes, to nudge sensitivityRatio downward to reflect the sensitivity likely to result from activity. + "-" : deviation was below what was expected. In addition, if a high temp target is running (e.g. activity mode), a negative deviation is added every 5 minutes, to nudge sensitivityRatio downward to reflect the sensitivity likely to result from activity. "=" : BGI is doing what we expect. Neutral deviations are also added every 2h to help decay sensitivityRatio back toward 1 if all data is excluded. - "4h" : time stamp to mark hour of day - i.e. 4h = 4am, 22h = 10pm, etc. + "4h" : time stamp to mark hour of day - e.g. 4h = 4am, 22h = 10pm, etc. "8g" : COB is displayed at any time a new carbs are recorded. Initial carb entry will show as full carbohydrate count followed by "(" with subsequent COB notes (4g) as calculated net COB at any time when additional carbs are entered. @@ -42,7 +53,7 @@ Here's what each symbol above means: The symbols are in chronological order, moving from oldest to newest. As there are typically CGM readings every 5 minutes, there are usually 12 comparisons each hour -### Autosens adjustments +## Reviewing 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. @@ -52,9 +63,9 @@ As you can see, there are several types of adjustments that have occurred during * 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). +* Finally at night, we had a low-treatment for a BG. We used an IFTTT button to enter our low treatments and at the same time, the IFTTT set up a temp target of 110 mg/dl for 60 minutes to make sure the loop didn't want to correct much on the recovery. That temp target was respected by autosens and basals and targets were not adjusted (even though autosens might have liked to). -### Notes about autosensitivity: +## Notes about autosensitivity * "Autosens" works by reviewing the both the last 8 hours and 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. It will then use the more conservative between the rolling 8 hour calculation or the 24 hour calculation. * 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. @@ -62,14 +73,9 @@ As you can see, there are several types of adjustments that have occurred during * Note that a Nightscout care portal or IFTTT temp target (for activity/exercise as an example) will override the autosens-adjusted target but IT WILL NOT override an advance target adjustment to bring high BG down. This is because in 0.5.x, the temp target is honored, but the advanced target adjustment is applied after the temp target. So, if current BG is high, the advanced target adjustment will be applied starting from the activity temp target, so if BG is high enough it will still reduce the active target to 80 mg/dL / 4,4 mmol/L. Consequently, be cautious of activity periods that follow a high BG; your IOB could be quite significant and cause you to go low quite fast as you start moving. If you do not want OpenAPS to apply advanced target adjustment that can be turned off by editing preferences.json (shortcut command edit-pref) and setting the “adv_target_adjustments” to false. Finally, if you do not want autosens to adjusted target that can be turned off by editing preferences.json (shortcut command edit-pref) and setting the “autosens_adjust_targets” to false. In oref0 0.6.0, adv_target_adjustments is set to false by default, as its functionality has been replaced by instead using the (safer) zero-temp BG predictions to decide when it's safe to dose additional insulin when high. The 0.6.0 exercise_mode feature also helps improve OpenAPS' response to high temp targets. * The reason for autosens automatically adjusting targets in 0.5.x 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. These limitations have been addressed in oref0 0.6.0. * 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 to 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. diff --git a/docs/docs/How it works/autotune.md b/docs/docs/How it works/autotune.md new file mode 100644 index 000000000..1eb758e80 --- /dev/null +++ b/docs/docs/How it works/autotune.md @@ -0,0 +1,74 @@ +# Autotune + +Autotune is a tool to help calculate potential adjustments to ISF, carb ratio, and basal rates. + +This page describes how Autotune works. For information on how to run it, please see [Running autotune](<../Usage and maintenance/running-autotune>). + +## The difference between autotune and autosens + +[Autosensitivity/resistance mode (aka “autosens”)](<./autosens>) is a feature in OpenAPS that looks at 24 hours of data and makes adjustments to ISF and targets based on the resulting sensitivity calculations. This can help make global adjustments to your insulin needs for transient changes such as illness, an aging pump site, or variation in activity level. + +Autotune, by contrast, is designed to iteratively adjust basals, ISF, and carb ratio over the course of weeks. Because it makes changes more slowly than autosens, autotune ends up drawing on a larger pool of data, and is therefore able to differentiate whether and how basals and/or ISF need to be adjusted, and also whether carb ratio needs to be changed. Whereas we don’t recommend changing basals or ISF based on the output of autosens (because it’s only looking at 24h of data, and can't tell apart the effects of basals vs. the effect of ISF), autotune is intended to be used to help guide basal, ISF, *and* carb ratio changes because it’s tracking trends over a large period of time. + +**Note**: Autotune currently tries to tune **one** ISF and carb ratio throughout the day. Here is the [issue](https://github.com/openaps/oref0/issues/326) if you want to keep track of the work to make autotune work with multiple ISF or carb ratios. If you are running Autotune on an OpenAPS rig and using the results, note that Autotune will only adjust the FIRST ISF and the FIRST carb ratio in your profile. If you have widely-varying ISFs and carb ratios throughout the day, or if Autotune is making relatively large adjustments, this may lead to suboptimal results, as you will be using your original settings the rest of the day. For instance, if Autotune thinks you should receive less basal but use a stronger correction factor (lower ISF), it will make the adjustments to your basal, but the stronger correction factor will be used only during the first segment - which might be say 12am to 4am! Review the output carefully, and consider whether [your varying carb ratios and correction factors might be compensating for other variation](<../While You Wait For Gear/collect-data-and-prepare#optimize-your-settings-with-autotune>). + +## How Autotune works + +There are two key pieces: oref0-autotune-prep and oref0-autotune-core. (For more autotune code, you can see [oref0-autotune-(multiple files) listed in oref0/bin here](https://github.com/openaps/oref0/tree/dev/bin) - and there are also some autotune files in [oref0/lib](https://github.com/openaps/oref0/tree/dev/lib). + +### 1. oref0-autotune-prep: + +* autotune-prep takes three things initially: glucose data; treatments data; and starting profile (originally from pump; afterwards autotune will set a profile) +* It calculates BGI and deviation for each glucose value based on treatments +* Then, it categorizes each glucose value as attributable to either carb sensitivity factor (CSF), ISF, or basals +* To determine if a "datum" is attributable to CSF, carbs on board (COB) are calculated and decayed over time based on observed BGI deviations, using the same algorithm used by Advanced Meal Assist. Glucose values after carb entry are attributed to CSF until COB = 0 and BGI deviation <= 0. Subsequent data is attributed as ISF or basals. +* If BGI is positive (meaning insulin activity is negative), BGI is smaller than 1/4 of basal BGI, or average delta is positive, that data is attributed to basals. +* Otherwise, the data is attributed to ISF. +* All this data is output to a single file with 3 sections: ISF, CSF, and basals. + +### 2. oref0-autotune-core + +* autotune-core reads the prepped glucose file with 3 sections. It calculates what adjustments should be made to ISF, CSF, and basals accordingly. +* For basals, it divides the day into hour long increments. It calculates the total deviations for that hour increment and calculates what change in basal would be required to adjust those deviations to 0. It then applies 20% of that change needed to the three hours prior (because of insulin impact time). If increasing basal, it increases each of the 3 hour increments by the same amount. If decreasing basal, it does so proportionally, so the biggest basal is reduced the most. +* For ISF, it calculates the 50th percentile (median) deviation for the entire day and determines how much ISF would need to change to get that deviation to 0. It applies 10% of that as an adjustment to ISF. +* For CSF, it calculates the total deviations over all of the day's mealtimes and compares to the deviations that are expected based on existing CSF and the known amount of carbs entered, and applies 10% of that adjustment to CSF. +* Autotune limits how far it can adjust (or recommend adjustment, if running autotune outside oref0 closed loop) basal, or ISF or CSF, from what is in the existing pump profile. Autotune uses the same `autosens_max` and `autosens_min` multipliers found in your preferences.json for oref0. So if autotune is running as part of your loop, autotune can't get too far off without a chance for a human to review the changes. + +*Note: Autotune does not read from the active profile (e.g. Pattern A or Pattern B if set). The Standard Basal Pattern is what will be pulled to be used and tuned by Autotune.* + +## Understanding autotune output + +### Safety reminders + +Autotune is a WIP (work in progress) tool. Do not blindly make changes to your pump settings without careful consideration. You may want to print the output of this tool and discuss any particular changes with your care team. Make note that you probably do not want to make long-term changes based on short term (e.g. 24 hour) data. Most people will choose to make long term changes after reviewing carefully autotune output of 3-4 weeks worth of data. + +### Example output from autotune + +![Example output from autotune](https://diyps.org/wp-content/uploads/2017/01/OpenAPS-autotune-example-by-@DanaMLewis.png) + +### What you'll see in autotune inputs and outputs + +* You might wonder what CSF in the autotune results refers to: Carb Sensitivity Factor is the amount your blood sugar will rise for a given quantity of carbs consumed. An initial value for CSF is calculated from your ISF and carb:insulin ratio (CR), i.e., CSF = ISF / CR (e.g., for an ISF of 42(mg/dL)/U and CR of 14g/U, CSF is 3(mg/dL)/g.) Subsequent autotune estimates for CSF are adjusted for the actual observed post-meal BG rise (relative to what would be expected based on insulin activity) compared to the number of carbs eaten. +* You might wonder what `min_5m_carbimpact` in profile.json refers to: It tells autotune how fast to decay carbs when your BG isn't rising. The default value means to assume 8mg/dL per 5m of carb absorption, even when your BG is falling or rising less than that. +* If you only input one basal rate in the profile.json, it will only show one basal in the left hand column, and tune the day around that basal. You can go back and edit the profile.json (and cp again to make all files the same) with your multiple basal rates if you want to appropriately tune and most easily compare the output suggested against what your existing basal schedule is. + +### If you are DIY closed looping and looking at autotune: + +#### With carbs logged in Nightscout +...you can look at everything that autotune outputs + +#### Without carb information in Nightscout +...you should only look at overnight basals, daytime basals that are not around typical meal times, and (with caution) ISF. Ignore carb ratio. + + +### If you are not DIY closed looping and are looking at autotune: + +#### With all boluses and carb treatments (even rescue, or low carbs) in Nightscout +...you can look at everything that autotune outputs + +#### Without boluses and carb treatments in Nightscout +...don't use autotune until you log this data. + +#### If you don't have Nightscout + +...it's probably easiest to set up [Nightscout](http://nightscout.info) and log some data in order to use autotune. This may change in the future (and let us know if you want to work on ways to bring other data types into autotune). \ No newline at end of file diff --git a/docs/docs/While You Wait For Gear/Understand-determine-basal.md b/docs/docs/How it works/understand-determine-basal.md similarity index 96% rename from docs/docs/While You Wait For Gear/Understand-determine-basal.md rename to docs/docs/How it works/understand-determine-basal.md index 860ff88be..474e5a74f 100644 --- a/docs/docs/While You Wait For Gear/Understand-determine-basal.md +++ b/docs/docs/How it works/understand-determine-basal.md @@ -20,7 +20,7 @@ This includes: * `short_avgdelta` = average rate of change (per 5m) in BG values between `glucose` (most recent BG) and each BG reading from 2.5 to 17.5 minutes ago * `long_avgdelta` = average rate of change (per 5m) in BG values between `glucose` (most recent BG) and each BG reading from 17.5 to 42.5 minutes ago * Past insulin dosing information, pulled from your pump - * `iob` = Units of Insulin on Board (IOB), ***net*** of your pre-programmed basal rates. Net IOB takes all pre-programmed basal, OpenAPS temp basal, and bolus insulin into account. Note: `iob` can be negative when OpenAPS temp basal rate is below your pre-programmed basal rate (referred to as "low-temping"). *This will always be different than pump-calculated IOB, because it only takes into account boluses - ignore pump IOB.* This is a high level overview, but you can dive into more detail around how insulin activity is calculated [here](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/understanding-insulin-on-board-calculations.html). + * `iob` = Units of Insulin on Board (IOB), ***net*** of your pre-programmed basal rates. Net IOB takes all pre-programmed basal, OpenAPS temp basal, and bolus insulin into account. Note: `iob` can be negative when OpenAPS temp basal rate is below your pre-programmed basal rate (referred to as "low-temping"). *This will always be different than pump-calculated IOB, because it only takes into account boluses - ignore pump IOB.* This is a high level overview, but you can dive into more detail around how insulin activity is calculated [here](<../How it works/understanding-insulin-on-board-calculations>). * `basaliob` = Units of ***net*** basal Insulin on Board (IOB). This value does not include the IOB effects of boluses; just the difference between OpenAPS temp basal rates and your pre-programmed basal rates. As such, this value can be negative when OpenAPS has set a low-temp basal rate. * `bolusiob` = Units of bolus Insulin on Board. Does not take into account any temp basals. @@ -36,14 +36,14 @@ This includes: * `Carb Impact` = we estimate carb impact by looking at what we predict to happen with your carbs entered (`predCI`) and adding it to our estimate of the remaining carb impact (`remainingCI`) * `Safety Threshold` = `min_bg - 0.5*(min_bg-40)` where `min_bg` is your BG target -You may also see information about settings, either from your pump or from your `preferences.json` file, that are limiting the insulin dosing decisions that OpenAPS would otherwise make. Make sure to [read the preferences page](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/preferences-and-safety-settings.html) before you set up OpenAPS to understand what settings you have by default, and know how to get back to that page if you ever see a setting displayed in your pill. There is also [a handy chart with examples](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/preferences-and-safety-settings.html#a-few-examples) to help you understand how settings may impact the dosing output. +You may also see information about settings, either from your pump or from your `preferences.json` file, that are limiting the insulin dosing decisions that OpenAPS would otherwise make. Make sure to [read the preferences page](<../Usage and maintenance/preferences-and-safety-settings>) before you set up OpenAPS to understand what settings you have by default, and know how to get back to that page if you ever see a setting displayed in your pill. There is also [a handy chart with examples](<../Usage and maintenance/preferences-and-safety-settings#a-few-examples>) to help you understand how settings may impact the dosing output. ## OpenAPS decision outputs After taking into account all of the above, oref0 will put out a recommendation of what needs to be done. This also includes the explanation of the variables above, so you can check and assess if you think it's doing the right thing. Generally, it will display all of the above values, plus the output of the decision of any temporary basal rates and/or boluses it decides it needs. This is the "reason" field. * Temp basals will be displayed with the `duration` (length of time temp basal will run. A duration of 0 indicates none is running) and `rate` (units/hr basal rate). -* You may also see `insulinReq`, showing how much insulin is needed. This usually displays when OpenAPS is prepping to issue SMB's ([an advanced setting](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/oref1.html)). +* You may also see `insulinReq`, showing how much insulin is needed. This usually displays when OpenAPS is prepping to issue SMB's ([an advanced setting](<../Customize-Iterate/oref1>)). ## Understanding the purple prediction lines diff --git a/docs/docs/While You Wait For Gear/understanding-insulin-on-board-calculations.md b/docs/docs/How it works/understanding-insulin-on-board-calculations.md similarity index 99% rename from docs/docs/While You Wait For Gear/understanding-insulin-on-board-calculations.md rename to docs/docs/How it works/understanding-insulin-on-board-calculations.md index e9e71e78f..ef610794e 100644 --- a/docs/docs/While You Wait For Gear/understanding-insulin-on-board-calculations.md +++ b/docs/docs/How it works/understanding-insulin-on-board-calculations.md @@ -92,13 +92,13 @@ Finally, two sources to benchmark the `iob` curves against can be found [here](h --- -# Understanding the New IOB Curves Based on Exponential Activity Curves +## Understanding the New IOB Curves Based on Exponential Activity Curves As mentioned at the top of this page, the next OpenAPS release will have new activity curves available for users to use. In the new release, users will be able to select between using a "bilinear" (looks like what was plotted above: /\) or "exponential" curves. Unlike the bilinear `activity` curve (which varies only based on `dia` values in a user's pump), the new exponential curves will allow users to specify both the `dia` value to use AND where they believe their `peak` insulin activity occurs. -A user can select one of three curve defaul settings: +A user can select one of three curve default settings: * **bilinear:** Same as how the curves work in oref0, version 0.5 -- IOB curve is calculated based on a bilinear `activity` curve that varies by user's `dia` setting in their pump. diff --git a/docs/docs/Resources/Deprecated-Pi/Pi-hardware.md b/docs/docs/Resources/Deprecated-Pi/Pi-hardware.md index 6e9a68809..4fcb04d6b 100644 --- a/docs/docs/Resources/Deprecated-Pi/Pi-hardware.md +++ b/docs/docs/Resources/Deprecated-Pi/Pi-hardware.md @@ -2,7 +2,7 @@ ## WARNING: THIS SETUP IS CURRENTLY DEPRECATED AND NOT RECOMMENDED (July 2017) -(**Note:** _If you're defaulting to Raspberry Pi because that's what you've seen pictures or heard stories of - you should also check out the Edison-based setup instructions for details on a smaller, more mobile friendly option. A Pi/TI stick rig is a good "at home" rig, but most people want the smallest, which is an Edision/Explorer Board rig [(pictured here)](https://twitter.com/danamlewis/status/776248916077522944?ref_src=twsrc%5Etfw) that they can slip in their pocket. The [next page](http://openaps.readthedocs.io/en/latest/docs/Gear Up/edison.html) has the Edison required hardware._ The Edison/Explorer Board setup is the main community-supported setup moving forward after March 2017.) +(**Note:** _If you're defaulting to Raspberry Pi because that's what you've seen pictures or heard stories of - you should also check out the Edison-based setup instructions for details on a smaller, more mobile friendly option. A Pi/TI stick rig is a good "at home" rig, but most people want the smallest, which is an Edision/Explorer Board rig [(pictured here)](https://twitter.com/danamlewis/status/776248916077522944?ref_src=twsrc%5Etfw) that they can slip in their pocket. The [next page](<../Gear Up/edison-explorer-board>) has the Edison required hardware. The Edison/Explorer Board setup is the main community-supported setup moving forward after March 2017.) The Raspberry Pi (RPi) is a credit-card sized single-board computer. The RPi primarily uses Linux kernel based operating systems, which must be installed by diff --git a/docs/docs/Resources/Deprecated-Pi/Pi-setup.md b/docs/docs/Resources/Deprecated-Pi/Pi-setup.md index 8ae844861..3444be7df 100644 --- a/docs/docs/Resources/Deprecated-Pi/Pi-setup.md +++ b/docs/docs/Resources/Deprecated-Pi/Pi-setup.md @@ -2,7 +2,7 @@ ## WARNING - THIS DOCUMENT IS DEPRECATED (NOT RECOMMENDED) AND UNMAINTAINED. We suggest you look to the top of the docs for information on the currently recommended hardware setup instead. As of November 2017 there are new and simplified Raspberry Pi setup instructions linked from there. The instructions below should only be used for troubleshooting purposes if the new instructions aren't working. -Note: There are two setup flows described on this page. The [one toward the bottom of the page is the older setup instructions](http://openaps.readthedocs.io/en/latest/docs/Resources/Deprecated-Pi/Pi-setup.html#older-instructions-for-original-pi-based-setups) that worked back in the day. The [one at the top of the page (all prefaced with "newer path")](http://openaps.readthedocs.io/en/latest/docs/Resources/Deprecated-Pi/Pi-setup.html#newer-path) is an attempt by someone to make the Pi instructions work for Pi3 and Pi0W. There may be issues with BOTH setups, so please do make PRs to this page and/or discuss on Gitter about which setup flow works. +Note: There are two setup flows described on this page. The [one toward the bottom of the page is the older setup instructions](<../Resources/Deprecated-Pi/pi-setup#older-instructions-for-original-pi-based-setups>) that worked back in the day. The [one at the top of the page (all prefaced with "newer path")](<../Resources/Deprecated-Pi/pi-setup#newer-path>) is an attempt by someone to make the Pi instructions work for Pi3 and Pi0W. There may be issues with BOTH setups, so please do make PRs to this page and/or discuss on Gitter about which setup flow works. ## Newer Path diff --git a/docs/docs/Resources/Edison-Flashing/PC-flash.md b/docs/docs/Resources/Edison-Flashing/PC-flash.md deleted file mode 100644 index b5f2d360d..000000000 --- a/docs/docs/Resources/Edison-Flashing/PC-flash.md +++ /dev/null @@ -1,271 +0,0 @@ -# Setting up Edison/Explorer Board on Windows/PC - -(This is testing a separate workflow for Windows only. Please refer to the [main Edison setup guide](./all-computers-flash.html) as well for troubleshooting & full instructions for other computer setup processes.) - -### Hardware Assumptions for this page - -1. Using an Explorer Board and Edison -2. Using an Windows computer - -## Preparing/flashing the Edison - -We recommend [buying an Edison that is preinstalled with jubilinux](hardware/edison.md#edison). If you did that, head back to the [main install instructions to begin installing Wifi and Dependencies](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#steps-2-3-wifi-and-dependencies). - -If you didn't buy your Edison with jubilinux preinstalled, it comes with an operating system, called Yocto, that doesn’t work easily with OpenAPS. The first step is to replace the operating system with a new one. This is called “flashing” the Edison. Both your Windows computer and the Edison board will need some work. - -### **1-1 Prepare Windows Computer** - -- Install the [Intel Edison drivers for Windows](https://software.intel.com/en-us/iot/hardware/edison/downloads). Select the "Windows standalone driver" download. After it is done downloading, click on the downloaded file and it will execute installation. (this link no longer contains the 'Windows standalone driver', see the note below) - -****** - -Note: Intel has announced the Edison will be discontinued at the end of 2017. As part of this, apparently, the old link to Edison drivers has been removed. We are unsure if this is a temporary issue or long term. Therefore, if the link above for Intel Edison Drivers is not working, you can use [this link](https://www.dropbox.com/s/d5ooojru5jxsilp/IntelEdisonDriverSetup1.2.1.exe?dl=0) to download them directly from an OpenAPS user's dropbox. Obviously screenshots below will be different if Intel has not fixed or repaired their driver downloads page for Edisons. - -******** - -![Edison Drivers](../../Images/Edison/edison_driver.png) - -![Edison Drivers](../../Images/Edison/edison_driver2.png) - - -- Install [PuTTY]( http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html). PuTTY is the program you will normally use to login to your rig in the future from the computer. Creating a desktop shortcut for it is a good idea, since you will likely use it often. Download the installation file that matches your PC's architecture (32-bit or 64-bit). If you are unsure, you can check your computer's build and memory in the Control Panel. Example shown is for a 64-bit computer. If unsure, installing the 32-bit version won't harm anything...it just might be a little slower to use PuTTY. - -![Control Panel](../../Images/Edison/64_bit.png) - -![Putty](../../Images/Edison/putty.png) - -![Putty](../../Images/Edison/putty2.png) - -![Putty](../../Images/Edison/putty3.png) - -**************************** -#### Side Note regarding computers with less than 6 GB RAM - -Windows PCs with less than 6 GB of RAM may need to have the size of the page file increased to flash the Edison. You can check your RAM as shown in the Control Panel picture above. If less than 6 GB is showing, then close all unnecessary programs and attempt to flash the device. If the flash operation fails follow these steps to ensure enough swap space is allocated when the computer boots, then restart and try again. Only do this if flashing the device doesn't work without changing these settings. - -*Important: Write down the settings in the Virtual Memory window before you make any changes to your system. When you finish the flash process you must return these settings to their original values or Windows may become unstable.* - - - Go to the Control Panel, click All Control Panel Items, then click System. At top left click the Remote Settings link. - - Select the Advanced tab in the System Properties window, then under Performance click Settings. - - On the Advanced tab click the Change... button to change the page size. - - In the Virtual Memory window uncheck "Automatically manage paging file size for all drives," - - Click "Custom size," below - - Set the initial size to 4096 MB - - Set maximum size to 6144 MB (2048 MB larger thand the initial size) - (If you have already attempted this process at least once and the flashing still hasn't worked, increase both size settings by 1024 MB and try again.) - - Click the Set button, then click OK until all windows are closed. - - Reboot and attempt the flash process. -****************************** - -#### Download jubilinux and dfu-util - -- Download [Jubilinux](http://www.jubilinux.org/dist/) (jubilinux version 0.3.0 is the current version known to work; jubilinux 0.2.0 runs Debian jessie, which is NOT supported by Debian any longer). Jubilinux will download in a zipped format to your Downloads folder. Locate the folder in your Downloads and right-click the `jubilinux.zip` folder. Select `extract all` from the menu. Saving it to your root user directory is a good idea. Your root directory is the set of folders that exist under your User name in Windows. For example, the destination for saving jubilinux to your root directory would be `C:\Users\yourusername\jubilinux` - -**Note** The `extract all` command comes standard for all Windows machines. However, in some instances, it may not be active for zipped files. If you do not see the `extract all` option in the right-click menu, right-click the zipped file, choose `Properties` at the bottom of the context menu. On the General tab, click on the button next to the "opens with" and change it to use Windows Explorer. Apply the change and select `OK` to save the change. You should now be able to right-click the jubilinux.zip file to extract all. - -- Now we are going to download two files from DFU-UTIL: [libusb-1.0.dll](http://dfu-util.sourceforge.net/releases/dfu-util-0.8-binaries/win32-mingw32/libusb-1.0.dll) and [dfu-util.exe](http://dfu-util.sourceforge.net/releases/dfu-util-0.8-binaries/win32-mingw32/dfu-util.exe). Click on those two links to download the files to your Downloads folder. Navigate to your Downloads folder and choose to "move" those folders to the jubilinux folder that you unzipped earlier. When you successfully move those two folders into the jubilinux folder, you should see files/folders inside the jubilinux folder like so: - -![Ready to Flashall](../../Images/Edison/ready.png) - -### **1-2 Prepare Edison** -Now we move to the Edison. You’ll see two microB USB ports on your explorer board. One is labeled OTG (that’s for flashing) and one is labeled UART (that’s for logging into the Edison from a computer). We will need to use both to flash. We’re going to plug both of those into our computer’s USB ports using the cables listed in the parts list (Dexcom’s charging cable will work too). - -![Explorer Board rig with two cables and red light on](../../Images/Edison/ExplorerBoard_two_charging_cables.png) - -Once you plug in the cables, you should see your Edison board pop-up as a connected “device”. If you don’t…try different cables. - -![Edison popup](../../Images/Edison/edison_popup.png) - - - Go to Control Panel\All Control Panel Items\Device Manager\Ports\ and look for USB Serial Port COMXX. If you have multiple and unsure of which is the port you need: Make note of existing ports. Unplug the cable from the Explorer Board. Notice which port disappears. this is the port you are looking for. If only one shows up, that is your Edison's port. - -![Port Select](../../Images/Edison/port.png) - - - Open PuTTY, change from SSH to Serial. It normally defaults to COM1 and speed of 9600. Change the COM number to the number you found when you plugged into the Explorer Board. Change the speed (baud rate) to 115200. - - Once you've made those changes, Click on OPEN at the bottom of your Putty configuration window. - - ![Putty port](../../Images/Edison/putty_port.png) - - - Once the screen comes up, press enter a few times to wake things up. This will give you a "console" window of what is happening on your Edison. Move that window over to the right side of your screen without resizing it, if you can. (We are going to open another window later on the left side.) -- Now you will see a login prompt for the Edison on the console screen. Login using the username "root" (all lowercase) and no password. This will have us ready to enter the commands coming up in the next steps later. - -- Now we are going to open a second window...a "flash" window...using a different program than PuTTY. Go to your Windows Start menu and search for a program called Command Prompt. Open Command Prompt and you should be given at a prompt for your User Root directory. Assuming you saved your jubilinux folder to your user root directory (as described above), enter `cd jubilinux` in the prompt and press return. If you saved it somewhere else, you will need to navigate to that location. Move that flash window to the left side of the screen. - -Your screens should look like this: - - ![Ready to Flash](../../Images/Edison/ready_to_flash.png) - -### **1-3 Flash the Edison** - -* In your flash window on the left (command prompt window), enter `flashall.bat` - -* You’ll get a prompt that asks you to "plug and reboot" the Edison board. You’re done with this screen for now. Just leave it alone (**don’t close window**) and go to next step. - - ![Reboot](../../Images/Edison/flash.png) - -* Return to the screen on the right (the PuTTY window) and enter `reboot` - -You will see many, many messages go by on the screens (mostly on the right-side screen). - -![flash continues](../../Images/Edison/mid_flash.png) - -After several reboots (don’t panic), you should get a ubilinux login prompt (If you see Yocto instead of ubilinux, then you need to go back to Step 1-2 and start the flash process over again). Use login `root` and password `edison`. - -![Successful flash](../../Images/Edison/successful.png) - -CONGRATULATIONS! You just flashed the Edison! Wahoo! Now, let's keep going. [Head back to the main install instructions for the easiest route of installing wifi, dependencies, and installing OpenAPS](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#steps-2-3-wifi-and-dependencies). (Below is manual instructions, but the main install instructions have an easier path to automate the below.) - -### **1-4 Hostname for Edison** - -Now that you’ve finished flashing, the Edison is going to need a couple things to finish setting it up; Hostname/passwords and Multiple WiFi networks - -Hostname and password - -* From that same screen we just left off , enter these three commands in succession -`myedisonhostname=` <---But replace the <> section with your chosen hostname. -Then run the next two lines, one at a time, without modification. -``` -echo $myedisonhostname > /etc/hostname -sed -r -i"" "s/localhost( jubilinux)?$/localhost $myedisonhostname/" /etc/hosts -``` - -***************************** -**IMPORTANT** - -* To change the password for your Edison to a more secure password than “edison”, enter `passwd root` - -* Follow the commands to reset the password. Repeat for `passwd edison` - -* SAVE PASSWORDS somewhere, you’ll want them. -***************************** - - -### **1.5 Set up Wifi** - -Enter `vi /etc/network/interfaces` - -Type “i” to enter INSERT mode for editing on the file. - -**HELPFUL TIP**: If you are new to insert mode, realize that it inserts characters at the highlighted cursor (it does not overwrite the character showing beneath the cursor). And, the default is that the cursor will be at the top left of the screen to start, so you will need to use the arrow keys to move the cursor to the area where you want to start typing. If you freak out that you’ve made a change that you don’t want to commit...you can simply press the ESC key and then type (no quotes) “:q!” to quit without saving any of your typing/changes. - -* 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 -``` - -![Wifi Interfaces](../../Images/Edison/wifi_interfaces.png) - -Press Esc and then type ':wq' and press Enter to write the file and quit - -Enter `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. - -### **1.6 Test internet connection** - -`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. - -Run `ifconfig wlan0` to determine the IP address of the wireless interface, in case you need it to SSH below. Alternatively, if you know how to login to your router, you can also see the Edison's IP address there. - -![IP address](../../Images/Edison/ip_address.png) - -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) - - -### **1.7 Install packages, ssh keys, and other settings** - -From a new terminal or PuTTY window, `ssh myedisonhostname.local`. If you can't connect via `myedisonhostname.local` (for example, on a Windows PC without iTunes), you can instead connect directly to the IP address you found with `ifconfig` above. - -Login as root (with the password you just set above), and run the following lines one by one. The first line "dpkg -P ... " will be quick. Check the printout to see that it ran without error. Then run the apt-get lines one at a time. They will take a long while. - - -``` -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 then run the next lines (first two will be quick, the last one will take you into a timezone selection menu. Run each line separately until finished) - -``` -adduser edison sudo - -adduser edison dialout - -dpkg-reconfigure tzdata -``` - -`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. - -![Log Rotate edits](../../Images/Edison/logrotate.png) - -You have now installed the operating system and wifi networks on your Edison! You can move onto the next steps in building your OpenAPS rig. diff --git a/docs/docs/Resources/Edison-Flashing/all-computers-flash.md b/docs/docs/Resources/Edison-Flashing/all-computers-flash.md deleted file mode 100644 index ed7c31e7e..000000000 --- a/docs/docs/Resources/Edison-Flashing/all-computers-flash.md +++ /dev/null @@ -1,442 +0,0 @@ -# Setting Up Your Intel Edison - Flashing instructions for all computer types - -The Intel Edison system comes with a very limited Operating System. It's best to replace this with a custom version of Debian, as this fits best with OpenAPS, and it also means you have the latest security and stability patches. (These setup instructions were pulled from the mmeowlink wiki; if you're an advanced user and want/need to use Ubilinux instead of the recommended Jubilinux, [go here](https://github.com/oskarpearson/mmeowlink/wiki/Prepare-the-Edison-for-OpenAPS).) The setup instructions also are going to assume you're using the Explorer Board that has a built in radio stick. If you're using any other base board and/or any other radio sticks (TI, ERF, Rileylink, etc.), check out [the mmeowlink wiki](https://github.com/oskarpearson/mmeowlink/wiki) for support of those hardware options. - -## Helpful notes before you get started -Your Explorer Board has 2 micro USB connectors, they both provide power. On the community developed Edison Explorer Board the port labeled OTG is for flashing, and the one labeled UART provides console login. You must connect both ports to your computer to complete the flash process. - -You must use a DATA micro USB to USB cable. How do you know if your cable is for data? One good way is to plug the cable into your computer USB port and the explorer board OTG port. If your folder/window explorer shows Edison as a drive then the cable supports data. - -The steps outlined below include instructions for the various build-platforms (Windows PC, Mac, and Raspberry Pi). Linux users in general should be able to follow the steps for the Raspberry Pi. If you'd prefer to follow directions specific to one platform you are using, you can use the [Windows PC cheat sheet](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/PC-flash.html) or the [Mac OSX cheat sheet](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/mac-flash.html). - -## Prerequisites - -### If you’re using a Raspberry Pi - prerequisites: - -To flash the Edison using a Raspberry Pi, you’ll need a large (preferably 16GB+) SD card for your Pi. The Edison image is almost 2GB, so you’ll not only need space for the compressed and uncompressed image, but you’ll also need to enable a large swapfile on your Pi to fit the image into virtual memory while it is being flashed. Using an SD card as memory is very slow, so allow extra time to flash the Edison image using a Pi. - - - Run `sudo bash -c 'echo CONF_SWAPSIZE=2000 > /etc/dphys-swapfile'` to configure a 2GB swap file. - *Note: if you don't have enough space on the SD card for a 2G swap a 1G swap will probably work* - - Run `sudo /etc/init.d/dphys-swapfile stop` and then `sudo /etc/init.d/dphys-swapfile start` to enable the new swap file. - - If you installed `watchdog` on the pi, it's a good idea to stop it since loading the image into memory to flash is intensive - -### If you're using a Windows PC - prerequisites: - -- Install the [Intel Edison drivers for Windows](https://downloadcenter.intel.com/download/26993/Intel-Edison-Configuration-Tool?product=84572). Select the "Windows standalone driver" download. You do not need to reflash the Edison or setup security or Wi-Fi with this tool because later steps in this process will overwrite those settings. - -****** - -Note: Intel has announced the Edison will be discontinued at the end of 2017. As part of this, apparently, the old link to Edison drivers has been removed. We are unsure if this is a temporary issue or long term. Therefore, if the link above for Intel Edison Drivers is not working, you can use [this link](https://www.dropbox.com/s/d5ooojru5jxsilp/IntelEdisonDriverSetup1.2.1.exe?dl=0) to download them directly from an OpenAPS user's dropbox. Obviously screenshots below will be different if Intel has not fixed or repaired their driver downloads page for Edisons. - -****** - -- Install [PuTTY]( http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html). Download the installation file that matches your PC's architecture (32-bit or 64-bit). - -Windows PCs with less than 6 GB of RAM may need to have the size of the page file increased to flash the Edison. Close all unnecessary programs and attempt to flash the device. If the flash operation fails follow these steps to ensure enough swap space is allocated when the computer boots, then restart and try again. Only do this if flashing the device doesn't work without changing these settings. - -*Important: Write down the settings in the Virtual Memory window before you make any changes to your system. When you finish the flash process you must return these settings to their original values or Windows may become unstable.* - - - Go to the Control Panel, click All Control Panel Items, then click System. At top left click the Remote Settings link. - - Select the Advanced tab in the System Properties window, then under Performance click Settings. - - On the Advanced tab click the Change... button to change the page size. - - In the Virtual Memory window uncheck "Automatically manage paging file size for all drives," click "Custom size," and set the initial size to at least 4096 MB. If you have already attempted this process at least once continue to increase this number by 1024 MB. Set the maximum size to 2048 MB higher than the initial size you used. - - Click the Set button, then click OK until all windows are closed. - - Reboot and attempt the flash process. - - -### If you're using a Mac to flash - prerequisites: - - - Read, but only follow steps 3-5 of, [these instructions](https://software.intel.com/en-us/node/637974#manual-flash-process) first. When you get to step 6, you'll need to cd into the jubilinux directory (see how to create it in the Jubilinux section below if you don't already have it) instead of the Intel image one, and continue with the directions below. - - Check also to see if you have lsusb installed prior to proceeding. If not, follow the instructions here to add: https://github.com/jlhonora/homebrew-lsusb - - Read the [Mac instructions for flashing](mac-flash.md) too, but note that they are now a little older than this. - - -## Downloading image - -### Jubilinux -[Jubilinux](http://www.jubilinux.org/) "is an update to the stock ubilinux edison distribution to make it more useful as a server, most significantly by upgrading from wheezy to jessie." That means we can skip many of the time-consuming upgrade steps that are required when starting from ubilinux. - - - Download [Jubilinux](http://www.jubilinux.org/dist/) - the jubilinux-v0.3.0.zip is known to work; jubilinux 0.2.0 runs Debian jessie, which is NOT supported by Debian any longer - - In download folder, right-click on file and extract (or use `unzip jubilinux.zip` from the command line) You will access this directory from a command prompt in the next step. It is a good idea to create the Jubilinux in your root directory to make this easier to access. - - Open a terminal window and navigate to the extracted folder: `cd jubilinux`. If using Windows OS use the command prompt (cmd). This is your "flash window", keep it open for later. - - For Windows OS: - - You will need an additional utility prior to flashing from Windows. - Download [DFU-Util](https://cdn.sparkfun.com/assets/learn_tutorials/3/3/4/dfu-util-0.8-binaries.tar.xz). - Extract the two files, libusb-1.0.dll and dfu-util.exe, to the directory where you extracted jublinux.zip. - (you can also extract all files to a separate folder and then copy the files to the jublinux directory) - -## Connecting cables and starting console - - - Connect a USB cable (one that carries data, not just power) to the USB console port. On the Explorer board or Sparkfun base block, this is the port labeled `UART`. On the Intel mini breakout board, this is the USB port that is labeled P6 (should be the USB closest to the JST battery connector). Plug the other end into the computer (or Pi) you want to use to connect to console. - - Plug another USB cable (one that carries data, not just power) into the USB port labeled OTG on the Explorer board or Sparkfun base block, or the port that is almost in the on the bottom right (if reading the Intel logo) if setting up with the Intel mini breakout board. Plug the other end into the computer (or Pi) you want to flash from. - -### If you’re using a Raspberry Pi for console: - - Open a terminal window and type `sudo screen /dev/ttyUSB0 115200` or similar. If you do not have screen installed you can install with `sudo apt-get install screen`. - -### If you're using a Windows PC for console: - - Go to Control Panel\All Control Panel Items\Device Manager\Ports\ and look for USB Serial Port COMXX. If you have multiple and unsure of which is the port you need: Make note of existing ports. Unplug the cable from the Explorer board. Notice which port disappears. this is the port you are looking for. - - Open PuTTY, change from SSH to Serial. It normally defaults to COM1 and speed of 9600. Change the COM number to the number you found when you plugged into the Explorer board. Change the speed (baud rate) to 115200. - - Once you've made those changes, Click on OPEN at the bottom of your Putty configuration window. - - Continue with the All platforms section below. - -### If you're using a Mac for console: - - Open a terminal window and type `sudo screen /dev/tty.usbserial-* 115200` If necessary, replace the '*' with your Edison UART serial number, obtained using lsusb. - -### All platforms: - - Once the screen comes up, press enter a few times to wake things up. This will give you a "console" view of what is happening on your Edison. - - Now you will see a login prompt for the edison on the console screen. Login using the username "root" (all lowercase) and no password. This will have us ready to reboot from the command line when we are ready. - - - Note! If you do not have your edison password at this point don't panic. We are only logging in to reboot the edison and that can be accomplished via the black button on the explorer board as well. Without the root password you may continue. - - Don't resize your console window: it will likely mess up your terminal's line wrapping. (Once you get wifi working and connect with SSH you can resize safely.) - -## Flashing image onto the Edison - -### If you’re using a Raspberry Pi - starting flash: - - In the "flash window" from the Download Image instructions above, run `sudo ./flashall.sh`. If you receive an `dfu-util: command not found` error, you can install dfu-util by running `sudo apt-get install dfu-util` - -### If you’re using a Mac - starting flash: - - In the "flash window" from the Download Image instructions above, run `./flashall.sh`. - - If you receive an `dfu-util: command not found` error, you can install dfu-util by following [the Mac instructions here](https://software.intel.com/en-us/node/637974#manual-flash-process). - - If you receive an `Error: Running Homebrew as root is extremely dangerous and no longer supported. As Homebrew does not drop privileges on installation you would be giving all build scripts full access to your system.` see the troubleshooting section below. - -### If you're using a Windows PC - starting flash: - - In the "flash window" from the Download Image instructions above, run `flashall.bat` - -### All platforms: - - The flashall script will ask you to reboot the Edison. - - - If you have your edison root password: Go back to your console window and type `reboot`. - - - If you do not have your edison root password: Press the black button on the explorer board until the LED between the usb connectors shuts off. Then press it again until the light comes back on. - - Switch back to the other window and you will see the flash process begin. You can monitor both the flash and console windows throughout the rest of the flash process. If nothing else works and you are feeling brave, you can try pulling the Edison out and reconnecting it to the board to start the flash process. - - It will take about 10 minutes to flash from Mac or Windows. If the step that flashall says should take up to 10 minutes completes in seconds, then the flash did not complete successfully, perhaps because you didn't set up the virtual memory / swap settings correctly. If you’re using a Raspberry Pi, it may take up to 45 minutes, and for the first 10-15 minutes it may appear like nothing is happening, but eventually you will start to see a progress bar in the console. - - After flashing is complete and the Edison begins rebooting, watch the console: you may get asked to type `control-D` to continue after one or more reboots. If so, press `Ctrl-d` to allow it to continue. - - After several more reboots (just about when you'll start to get concerned that it is stuck in a loop), you should get a login prompt. If so, congratulations! Your Edison is flashed. The default password is `edison`. - -If you have any difficulty with flashing, skip down to [Troubleshooting](#troubleshooting) - -Hooray! After you've flashed your Edison, head back to the main [install instructions for wifi and dependencies](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#steps-2-3-wifi-and-dependencies) to use the easy automated scripts. (Below are manual install instructions). - -## Initial Edison Setup - -Log in as root/edison via serial console. - -Type/edit the following: - - myedisonhostname= #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 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) - - -## Troubleshooting - -### Troubleshooting the flash process - -a) If you get: -``` -dfu-util: Device has DFU interface, but has no DFU functional descriptor -dfu-util: Cannot open DFU device 8087:0a99 -``` -that likely means you ran ./flashall.sh without sudo. - -b) If you get: -``` -Flashing rootfs, (it can take up to 10 minutes... Please be patient) -dfu-util -v -d 8087:0a99 --alt rootfs -D /home/pi/toFlash/edison-image-edison.ext4 -R 2>&1 | tee -a flash.log | ( sed -n '19 q'; head -n 1; cat >/dev/null ) -Rebooting -U-boot & Kernel System Flash Success... -``` -in something closer to 10 seconds than 10 minutes, then you likely didn't set up swap properly. To verify, `cat flash.log` and look for `dfu-util: Cannot allocate memory of size 1610612736 bytes` near the end. -Alternatively, [this newer version of DFU Util](https://sourceforge.net/projects/dfu-util/files/latest/download) (DFU Util v0.9) seems to work better on computers with lots of RAM. - -c) If you recieve an `Error: Running Homebrew as root is extremely dangerous and no longer supported. As Homebrew does not drop privileges on installation you would be giving all build scripts full access to your system.` it means that you have a recent copy of homebrew (that's good) which doesn't allow sudo to even do a `brew list`. - - * The _easiest_ - but perhaps not so forward compatible - thing is to figure out what the brew command was trying to do and edit the `flashall.sh` script accordingly. - ** The v0.2.0 version of `flashapp.sh` has `$(brew list gnu-getopt | grep bin/getopt)`. - ** Running `brew list gnu-getopt | grep bin/getopt` for me (Dec 2017) gave me `/usr/local/Cellar/gnu-getopt/1.1.6/bin/getopt` - * Edit the `flashall.sh` from - ```:bash - GETOPTS="$(which getopt)" - if [[ "$OSTYPE" == "darwin"* ]] ; then READLINK=greadlink; GETOPTS="$(brew l ist gnu-getopt | grep bin/getopt)"; else READLINK=readlink;fi; - ``` - to - - ```:bash - GETOPTS="$(which getopt)" - if [[ "$OSTYPE" == "darwin"* ]] - then - READLINK=greadlink - GETOPTS=/usr/local/Cellar/gnu-getopt/1.1.6/bin/getopt - else - READLINK=readline - fi - ``` - -d) If you have a failed flash or have problems with the reboot, try starting the console and hitting enter a bunch of times while connecting to stop autoboot. You'll then be at a `boot>` prompt. Run `sudo ./flashall.sh` and when it asks you to reboot type and enter `run do_flash` at the `boot>` prompt. - -e) If you get stuck on an error that says "Ready to receive application" on the Edison the problem is you don't have enough power to properly boot up the Edison. This can happen if you are powering from your Pi. You should either connect a battery to the Edison board to give it a little boost, or use a powered USB hub between the Pi and the Edison. - -f) If Edison reboots correctly but never gets picked up by the flashall.sh script and the flashing process does not start, check that you have DATA micro USB to USB cables - both of them. A large proportion of USB cables are not "data" - just power - and even cables previously used for data can degrade to no longer reliably carry data. How do you know if each cable is for data? One good way is to unplug both cables from the Edison, plug each cable in turn into your computer USB port and the explorer board OTG port. If your folder/window explorer shows Edison as a drive then the cable supports data. You need both to be data cables. - -g) If Edison reboots correctly but never gets picked up by the flashall.sh script and the flashing process does not start, and you've re-confirmed that the two cables you are using are indeed good data cables, check the Edison device ID. It will probably come out automatically after the flashall.sh script fails with a list of available devices connected to the machine. On Linux, you can run lsusb to get a list of usb devices with their device ID. If the device ID is different from the one expected on flashall.sh, you can edit the script and change lines containing: USB_VID=8087 & USB_PID=0a99 to whatever the Edison has for an ID. Some users have encountered their devices ID to be 8087:0a9e - -h) If you have attempted the firmware flash with Jubilinux several times and the flash will not complete successfully, it is highly recommended that you follow the mmeowlink [deprecated Ubilinux instructions](https://github.com/oskarpearson/mmeowlink/wiki/Prepare-the-Edison-for-OpenAPS#ubilinux-deprecated). Note that those instructions will have notes throughout for steps which are specific to the flash of Ubilinux. Additional steps help to align the Edison's operating system with Jubilinux. You must do these steps. - -If you're having issues with a *Windows* flash of Jubilinux, try following along with the videos below. OpenAPS users have cited their instructions in successful flashes of Ubilinux. You will still need to go through the extra Ubilinux configuration steps mentioned in the linked mmeowlink wiki above. - -1. [Flash Ubilinux Onto Intel Edison via Windows, 5 Part Video](https://www.youtube.com/watch?v=L57RC8POJzM) (Cygwin) -2. [uCast #21: Installing Ubilinux on the Edison (Windows)](https://www.youtube.com/watch?v=BSnXjuttSgY&t=16s) (Windows Command Prompt) - -i) If none of the above has worked with the Explorer board, try swapping the two microUSB cables, or replacing them with new ones. See "f)" above too. - -j) If you've attempted all of the troubleshooting steps above but still aren't successful, it's worth trying to use a different computer to flash. - - -### Troubleshooting rescue mode - -* If your edison boots to a console and says it is in rescue mode (you can hit ctrl-d to continue or enter the root password), you may need to change a u-boot environment variable to make it boot normally. During the boot process you will see: -``` -*** Ready to receive application *** - - -U-Boot 2014.04 (Feb 09 2015 - 15:40:31) - - Watchdog enabled -DRAM: 980.6 MiB -MMC: tangier_sdhci: 0 -In: serial -Out: serial -Err: serial -Hit any key to stop autoboot: 0 -``` -1. Hit any key to drop to a prompt and type: -`printenv bootargs_target` -2. If the answer is -`bootargs_target=first-install` -then type: -`setenv bootargs_target multi-user` -`saveenv` -3. And to exit that firmware u-boot prompt: -`run do_boot` - -* If this doesn't fix the problem, and your boot gets stuck here: -``` -[ OK ] Mounted /home. - - Starting Rescue Shell... - -[ OK ] Started Rescue Shell. - -[ OK ] Reached target Rescue Mode. -``` -You may have an issue with the flashall.sh script. (This seems to only impact mac users). -In the "flash window" terminal where you downloaded Jubilinux - -1. Edit the flashall script -`nano flashall.sh` -2. Find the following text (around line 220) Your text may vary slightly, with additional echo statements or such -``` -echo "Flashing U-Boot Environment Backup and rebooting to apply partiton changes" - flash-command --alt u-boot-env1 -D "${VARIANT_FILE}" -R - - dfu-wait -``` -3. Modify this line to remove the -R and the dfu-wait command -``` -echo "Flashing U-Boot Environment Backup and rebooting to apply partiton changes" - flash-command --alt u-boot-env1 -D "${VARIANT_FILE}" -``` -4. Reboot one last time - install should take a good deal longer than previous executions. - - -### Override DNS resolvers - -Some users have reported problems with connecting to internet sites. If you are experience poor internet connections, try 'nano /etc/resolv.conf' and change the first two nameservers to: - - nameserver 8.8.4.4 - nameserver 8.8.8.8 - -Also see the instructions [here](https://wiki.debian.org/NetworkConfiguration#The_resolvconf_program) to add these nameservers to your `/network/interfaces` file as the `resolv.conf` file is likely to be overwritten. - -Alternatively, add the nameservers you want to see in `resolv.conf` to `/etc/resolvconf/resolv.conf.d/tail` and they'll be automatically added to `resolv.conf`. (You may need to create the folder by running this command first: `mkdir -p /etc/resolvconf/resolv.conf.d`) - - -### IP address conflicts (able to ping external but not LAN addresses) - -Some users have reported problems where the local router uses the same IP block as that of usb0 config. The default configuration for usb0 in `/etc/network/interfaces` uses 192.168.2.15, so if your local router also uses 192.168.2.xx you may not be able to properly connect to your Edison using SSH, and external connectivity may intermittently fail. - -To check which IP address your router is using, you can run `ipconfig` on Windows or `ifconfig` on Mac/Linux. If you're getting an address starting with 192.168.2.x, you'll want to edit your Edison's configuration to use a different subnet for usb0: - -Use `vi /etc/network/interfaces` to edit the static usb0 interface address from 192.168.2.15 to another valid private IP, like 192.168.29.29. The resulting config 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.29.29 - netmask 255.255.255.0 - -auto wlan0 -iface wlan0 inet dhcp - wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf -``` - -Once that looks correct, save the file and `reboot` your rig for the changes to take effect. - - -### Interrupting Kernel Messages in Console/Screen Mode - -![Example kernel message](https://user-images.githubusercontent.com/24418738/27111189-17c4acd8-5074-11e7-8873-54470e94c638.jpg) - -#### Fix for individual console/screen session: - -Type this at the prompt: `dmesg -D` - -#### Permanent solution: - -`vi /etc/rc.local` -press i for insert mode - -add this line: sudo dmesg -n 1 - -![adding dmesg](https://user-images.githubusercontent.com/24418738/27111188-17c46c3c-5074-11e7-8a5f-d29c85873293.jpg) - -(remember to save and exit the vi editor by using esc and then :wq) - - diff --git a/docs/docs/Resources/clinician-guide-to-OpenAPS.md b/docs/docs/Resources/clinician-guide-to-OpenAPS.md index 338a6c8ad..c1b320de8 100644 --- a/docs/docs/Resources/clinician-guide-to-OpenAPS.md +++ b/docs/docs/Resources/clinician-guide-to-OpenAPS.md @@ -73,11 +73,11 @@ In this example, OpenAPS sees that BG is spiking well above target. However, due ### Optimizing settings and making changes -As a clinician who may not have experience with OpenAPS or DIY closed loops, you may find it challenging to help your patient optimize their settings or make changes to improve their outcomes. We have multiple tools and [guides](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/optimize-your-settings.html) in the community that help patients make small, tested adjustments to improve their settings. +As a clinician who may not have experience with OpenAPS or DIY closed loops, you may find it challenging to help your patient optimize their settings or make changes to improve their outcomes. We have multiple tools and [guides](<../Usage and maintenance/optimize-your-settings>) in the community that help patients make small, tested adjustments to improve their settings. The most important thing for patients to do is make one change at a time, and observe the impact for 2-3 days before choosing to change or modify another setting (unless it’s obviously a bad change that makes things worse, in which case they should revert immediately to the previous setting). The human tendency is to turn all the knobs and change everything at once; but if someone does so, then they may end up with further sub-optimal settings for the future, and find it hard to get back to a known good state. -One of the most powerful tools for making settings changes is an automated calculation tool for basal rates, ISF, and carb ratio. This is called “[Autotune](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html)”. It can also be run independently/manually, and allow the data to guide you or your patient in making incremental changes to settings. It is best practice in the community to run (or review) Autotune reports first, prior to attempting to make manual adjustments to settings. +One of the most powerful tools for making settings changes is an automated calculation tool for basal rates, ISF, and carb ratio. This is called “[Autotune](<../How it works/autotune>)”. It can also be run independently/manually, and allow the data to guide you or your patient in making incremental changes to settings. It is best practice in the community to run (or review) Autotune reports first, prior to attempting to make manual adjustments to settings. Additionally, human behavior (learned from manual diabetes mode) often influences outcomes, even with a DIY closed loop. For example, if BG is predicted to go low and OpenAPS reduces insulin on the way down, only a small amount of carbs (e.g. 3-4 carbs) may be needed to bring BG up from 70. However, in many cases, someone may choose to treat with many more carbs (e.g. sticking to the 15 rule), which will cause a resulting faster spike both from the extra glucose and because insulin had been reduced in the timeframe leading up to the low. One feature that aids patients in making behavior changes as they transition to DIY closed loops is to set up Pushover, an app that enables them to get push alerts from the rig that specify if carbs are needed, and if so, how many. They can then make an informed decision about carbs needed to adjust for the BG, and this data is helpful for understanding the cause and effect between the amount of low treatment and the resulting BG levels after that. @@ -88,4 +88,4 @@ This is meant to be a high-level overview of how OpenAPS works. For more details Additional recommended reading: * The [OpenAPS Reference Design](https://OpenAPS.org/reference-design/), which explains how OpenAPS is designed for safety: https://openaps.org/reference-design/ * The [full OpenAPS documentation](http://openaps.readthedocs.io/en/latest/index.html) - * More [details on OpenAPS calculations](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/Understand-determine-basal.html#understanding-the-determine-basal-logic) + * More [details on OpenAPS calculations](<../How it works/understand-determine-basal#understanding-the-determine-basal-logic>) diff --git a/docs/docs/Resources/glossary.md b/docs/docs/Resources/glossary.md index d2a60aff0..6602d45c4 100644 --- a/docs/docs/Resources/glossary.md +++ b/docs/docs/Resources/glossary.md @@ -11,7 +11,7 @@ BG - Blood Glucose -BGI (Blood Glucos Impact) - The degree to which Blood Glucose (BG) "should" be rising or falling. OpenAPS calculates this value to determine the 'Eventual Blood Glucose'. This value can be used to make other high/low basal decisions in advanced implementations of OpenAPS. +BGI (Blood Glucose Impact) - The degree to which Blood Glucose (BG) "should" be rising or falling. OpenAPS calculates this value to determine the 'Eventual Blood Glucose'. This value can be used to make other high/low basal decisions in advanced implementations of OpenAPS. Bolus - extra insulin given by a pump, usually to correct for a high Blood Glucose (BG) or for carbohydrates diff --git a/docs/docs/Resources/index.rst b/docs/docs/Resources/index.rst deleted file mode 100644 index ce8651fd8..000000000 --- a/docs/docs/Resources/index.rst +++ /dev/null @@ -1,23 +0,0 @@ - -Resources ---------- - -.. toctree:: - :maxdepth: 4 - :glob: - - my-first-pr - clinician-guide-to-OpenAPS - technical-resources - Medtronic-Button-Errors - troubleshooting - wifi - history - faq - glossary - switching-between-DIY-systems - Manual Edison Flashing instructions - all computer types - Manual Edison Flashing instructions - FOR MAC - Manual Edison Flashing instructions - FOR WINDOWS - Deprecated: Pi Hardware info - Deprecated: Pi Setup info diff --git a/docs/docs/Resources/my-first-pr.md b/docs/docs/Resources/my-first-pr.md index 79b8549e6..ad0552d54 100644 --- a/docs/docs/Resources/my-first-pr.md +++ b/docs/docs/Resources/my-first-pr.md @@ -1,4 +1,4 @@ -### Making your first PR (pull request) +# Making your first PR (pull request) At some point it will be suggested that you make a PR. PR is short for pull request, and it is a way of adding or editing information stored in GitHub. It's actually not too hard to do one and it is a great way to contribute. This documentation is here because people like you made PRs. Don't worry about making a mistake or somehow editing the wrong documents. There is always a review process before changes are merged into the "formal" OpenAPS documentation repository. You can't mess up the originals through any accidents in the PR process. The general process is: @@ -33,11 +33,11 @@ Congrats, you made your first contribution! PS, your fork and branch will still be sitting on your own personal GitHub account. After you get a notification that your PR has been merged, you can delete your branch if you are done with it (Step 8's notification area will provide a link to delete the branch once it has been closed or merged). For future edits, if you follow this procedure the edits will always start with an updated version of the openaps repositories. If you choose to use another method to start a PR request (e.g., editing starting from your forked repo's master branch as the starting point), you will need to ensure your repo is up-to-date by performing a "compare" first and merging in any updates that have happened since you last updated your fork. Since people tend to forget to update their repos, we recommend using the PR process outlined above until you get familiar with performing "compares". -### Advanced tips for adding multiple images to documentation +## Advanced tips for adding multiple images to documentation If you are planning to make a lot of edits, including adding images to help illustrate parts of the documentation (thank you!), you may want to take the following approach: -* As you go and save screenshots, rename the screenshots to a descriptive name - but try not to use spaces as that confuses Github. Instead, use underscores. I.e. Example_batch_images_upload.png rather than "Example batch images upload.png". +* As you go and save screenshots, rename the screenshots to a descriptive name - but try not to use spaces as that confuses Github. Instead, use underscores. E.g. Example_batch_images_upload.png rather than "Example batch images upload.png". * You can upload images in batches easily by: diff --git a/docs/docs/Resources/switching-between-DIY-systems.md b/docs/docs/Resources/switching-between-DIY-systems.md index b050764e3..70beea447 100644 --- a/docs/docs/Resources/switching-between-DIY-systems.md +++ b/docs/docs/Resources/switching-between-DIY-systems.md @@ -4,9 +4,9 @@ ### Other things you should know before starting: -* OpenAPS is similar to Loop (they’re both temp basal-based DIY closed loops), but different, even beyond the hardware. The algorithm (looping code) of OpenAPS is referred to as “[oref0](https://github.com/openaps/oref0/)”. You can look at that code (it’s written to be pretty straight forward - [see this example](https://github.com/openaps/oref0/blob/master/lib/determine-basal/determine-basal.js#L346), and the [glossary](http://openaps.readthedocs.io/en/latest/docs/Resources/glossary.html) may be helpful as well), but you can also read this plain language “[reference design](https://openaps.org/reference-design/)” that guides how OpenAPS was built. +* OpenAPS is similar to Loop (they’re both temp basal-based DIY closed loops), but different, even beyond the hardware. The algorithm (looping code) of OpenAPS is referred to as “[oref0](https://github.com/openaps/oref0/)”. You can look at that code (it’s written to be pretty straight forward - [see this example](https://github.com/openaps/oref0/blob/master/lib/determine-basal/determine-basal.js#L346), and the [glossary](<../Resources/glossary>) may be helpful as well), but you can also read this plain language “[reference design](https://openaps.org/reference-design/)” that guides how OpenAPS was built. * _Paying it forward_: OpenAPS is part of the #WeAreNotWaiting movement...built 100% by volunteers...and that also includes the documentation! If you spot something in the documentation that needs fixing or improving, please flag it and/or submit an edit yourself to fix the documentation then and there! - * This is called “making a pull request” or “making a PR”, which presents your edit for someone to review, approve, and update the overall documentation - which means everyone can use your fix moving forward! We all have a responsibility to keep adding to and improving the documentation. You can find [a guide to creating a pull request/submitting your edit here](http://openaps.readthedocs.io/en/latest/docs/Resources/my-first-pr.html), and if you ask, we’re happy to help answer questions as you do your first pull request. + * This is called “making a pull request” or “making a PR”, which presents your edit for someone to review, approve, and update the overall documentation - which means everyone can use your fix moving forward! We all have a responsibility to keep adding to and improving the documentation. You can find [a guide to creating a pull request/submitting your edit here](<../Resources/my-first-pr>), and if you ask, we’re happy to help answer questions as you do your first pull request. * **You can do this**. * One user estimates setting up OpenAPS takes only 20 mouse clicks; 29 copy and paste lines of code; 10 entries of passwords or logins; and probably about 15-20 random small entries at prompts (like your NS site address or your email address or wifi addresses). So if you can copy and paste, you’ll be able to do this! @@ -54,35 +54,24 @@ If you’re coming to try OpenAPS from a Loop system, there’s going to be some ### High Level Recommended Rig parts list -See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/mac-flash.html#high-level-recommended-rig-parts-list ) +See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.](<../Gear Up/edison-explorer-board#parts-you-ll-need>) ### Getting started on OpenAPS - the setup links -#### Building your Rig: -* [Start here for the Mac version]( http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/mac-flash.html ) (with pictures!) -* ([Reference this page](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html ) if you’re using any other type of computer to build.) - -#### Flashing your rig: -* [For Mac](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/mac-flash.html#preparing-flashing-the-edison) (with pictures!) -* ([For other computers.](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html)) +#### Installing OpenAPS on your rig +* [Follow these instructions](<../Build Your Rig/index>) (with pictures!) #### Nightscout * We highly recommend Nightscout. Go to [nightscout.info](http://nightscout.info) if you have not yet setup * If you’re already on Nightscout, you just need to add openaps, like you did Loop, to enable the OpenAPS pill. You will also want to enable the OpenAPS forecast line(s) when you switch to an OpenAPS rig. -* [See this page for more details about Nightscout and OpenAPS]( http://openaps.readthedocs.io/en/latest/docs/walkthrough/phase-1/index.html ) - -#### Installing oref0/”installing the loop” -* [Existing instructions for this (Phase 2 of OpenAPS documentation) are here.](http://openaps.readthedocs.io/en/latest/docs/walkthrough/phase-2/index.html) - -#### Personalizing your loop: -* [Phase 3 instructions are here.](http://openaps.readthedocs.io/en/latest/docs/walkthrough/phase-3/index.html) +* [See this page for more details about Nightscout and OpenAPS](<../While You Wait For Gear/nightscout-setup>) ## The big differences between Loop and OpenAPS: ### Targets and algorithm differences -* Loop pulled targets from the app. OpenAPS pulls targets from the pump. Here’s [more detail on the data OpenAPS pulls and how it outputs data for you to understand the algorithm in action](http://openaps.readthedocs.io/en/latest/docs/While You Wait For Gear/Understand-determine-basal.html). -* Loop has temporary targets available by using the workout mode in the Loop app. OpenAPS can have [multiple temp targets](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autosens.html#eating-soon-and-activity-mode-temporary-targets) (i.e. Eating Soon and Workout, etc., and can be set via the Nightscout Care Portal if the rig is online, and via [IFTTT/Alexa/pebble/scheduled in advance/location based triggers](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/ifttt-integration.html). +* Loop pulled targets from the app. OpenAPS pulls targets from the pump. Here’s [more detail on the data OpenAPS pulls and how it outputs data for you to understand the algorithm in action](<../How it works/understand-determine-basal>). +* Loop has temporary targets available by using the workout mode in the Loop app. OpenAPS can have [multiple temp targets](<../How it works/autosens#eating-soon-and-activity-mode-temporary-targets>) (e.g. Eating Soon and Workout, etc., and can be set via the Nightscout Care Portal if the rig is online, and via [IFTTT/Alexa/pebble/scheduled in advance/location based triggers](<../Customize-Iterate/ifttt-integration>). * OpenAPS has no bolus momentum or safety guard that prevent boluses; but has other key safety settings (see below) ### “MaxIOB” and other safety settings @@ -91,31 +80,31 @@ See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.]( * This is the max cap of how much IOB you want to allow before OpenAPS stops dosing additional insulin. It is not the same as a max basal rate. The default setting is 0, but if you’re coming from Loop, you’re probably ok starting with something other than 0 for maxIOB. You will want to consider how you are going to use OpenAPS, particularly if you are new to the closed loop community. The most conservative setting would be to set something lower than your typical meal bolus. This is a reasonable place to start if you are new and as you get used to how yours (or your child's) blood sugar is managed by the algorithims within OpenAPS. This will prevent OpenAPS from adding any additional insulin on top of your meal bolus, until that IOB has decayed down to the configured value. * Once you have watched the rig for a while, and you have a good understanding of it's response, you may be considering turning on the advanced feature of SMB, at which point you will want to reconsider your max_iob setting. In this case, you will want to reflect on several factors before you re-set your max_iob. The first important consideration is how you will want SMB to function. If you are intending that SMB will moderate carb counting that was not accurate, or will be used to catch those unexpected BG rises, but you still intend to carb count and fully bolus, then you may not need to make any changes. For new users, it is recommended that you start using this advanced feature in this stepwise way, so you will have a good understanding by watching how it responds in your loop. If you watch in your OpenAPS pill, you will see if you are frequenty hitting the max_iob as a limitation, and then you can begin adjusting accordingly. * Once you are comfortable with the added functionality of SMB, you may want to have SMB take over some, or all, of the responsibility for dosing insulin for foods and reducing your upfront bolus amount. In this case, you will need to adjust your max_iob rate in consideration of how much you may typically want SMB to be responsible for. Extending the example from above, if your initial max_iob is set to 2.0, then you may find that SMB is unable to be rapidly helpful in the case of foods for which you have not fully bolused, as it will be restricted by the max_iob setting. This will be magnified significantly if you are using Fiasp and intending to have SMB take over all bolus needs. In instances such as this, you will want to increase your max_iob, giving consideration of your regular carb load, your regular bolus ratio and the amount of insulin you would usually need to give that you now want SMB to be responsible for. Of course, as YDMV, this number will be very individual. We strongly encourage you to be conservative, particularly as you start out, as safety should always be the first consideration. -* After you get comfortable with how OpenAPS operates, you can easily [(here's how)](http://openaps.readthedocs.io/en/latest/docs/While You Wait For Gear/preferences-and-safety-settings.html#editing-your-preferences-json) update this number later. +* After you get comfortable with how OpenAPS operates, you can easily [(here's how)](<../Usage and maintenance/preferences-and-safety-settings#editing-your-preferences-json>) update this number later. #### Other safety settings * In addition to maxIOB, there are other basal-related safety caps built into OpenAPS to help protect you. These are to prevent people from getting into dangerous territory by setting excessively high max temp basals before understanding how the algorithm works. There are default values provided when the OpenAPS loop is first built; most people will never need to adjust these and are instead more likely to need to adjust other settings if they feel like they are “running into” or restricted by these safety caps. If you do want to adjust these default values, they are located in the same preferences file as linked in the max-iob discussion above. **NOTE:** OpenAPS's loop will use the LOWEST of the following three values to cap your temp basal rate, to make sure you don’t get a disproportionate amount of insulin. * **“Max Basal”** refers to the max basal set on the pump. (If you change this, it will be read in the next time your rig pulls pump settings.) * **“Max Daily Safety Multiplier”** limits the temp basal set by OpenAPS loop to be a multiplier of your HIGHEST regularly-scheduled basal rate in the pump. The default setting for this multiplier is 3x...meaning no more than three times your maximum programmed basal rate for the day. If someone tells you your basal is capped by the “3x max daily; 4x current” for safety caps, this is what they'd be referring to. * **“Max Current Basal Safety Multiplier”:** limits the temp basal set by OpenAPS loop to be a multiplier of your CURRENT regularly-scheduled basal rate in the pump. The default setting for this multiplier is 4x...meaning no more than four times your current programmed basal rate. -* Read about [all of the other optional safety settings here](http://openaps.readthedocs.io/en/latest/docs/While You Wait For Gear/preferences-and-safety-settings.html#understanding-your-preferences-json). +* Read about [all of the other optional safety settings here](<../Usage and maintenance/preferences-and-safety-settings#understanding-your-preferences-json>). ### Parents in particular may want to review the optional settings * Parents should [read this blog post by Katie DiSimone for a parent's perspective about various pros/cons](http://seemycgm.com/2017/02/01/loop-vs-openaps/) for parents and kids evaluating DIY closed loop systems. -* **Override the high target with the low** ([see this explanation](http://openaps.readthedocs.io/en/latest/docs/While You Wait For Gear/preferences-and-safety-settings.html#override-high-target-with-low) for enabling this feature) +* **Override the high target with the low** ([see this explanation](<../Usage and maintenance/preferences-and-safety-settings#override-high-target-with-low>) for enabling this feature) * This makes it easier for secondary caregivers (like school nurses) to do conservative boluses at lunch/snack time, and allow the closed loop to pick up from there. The secondary caregiver can use the bolus wizard, which will correct down to the high end of the target; and setting this value in preferences to “true” allows the closed loop to target the low end of the target. Based on anecdotal reports from those using it, this feature sounds like it’s prevented a lot of (unintentional, diabetes is hard) overreacting by secondary caregivers when the closed loop can more easily deal with BG fluctuations. -* **Carb ratio adjustment ratio** ([see this explanation](http://openaps.readthedocs.io/en/latest/docs/While You Wait For Gear/preferences-and-safety-settings.html#carbratio-adjustmentratio) for enabling this feature) +* **Carb ratio adjustment ratio** ([see this explanation](<../Usage and maintenance/preferences-and-safety-settings#carbratio-adjustmentratio>) for enabling this feature) * If parents would prefer for secondary caregivers to bolus with a more conservative carb ratio, this can be set so the closed loop ultimately uses the correct carb amount for any needed additional calculations. ### Connectivity * Loop works offline automatically; but may often need tuning and fixing if you go out of range and come back in range. * OpenAPS needs some tricks to maximize connectivity (see below), but tends to resume working correctly once you come back into range without having to do anything special. - * [Bluetooth tethering](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/bluetooth-tethering-edison.html) is one good option; as soon as you walk out of wifi range, it can automatically bluetooth tether to your phone to get connectivity + * [Bluetooth tethering](<../Usage and maintenance/Wifi/bluetooth-tethering-edison>) is one good option; as soon as you walk out of wifi range, it can automatically bluetooth tether to your phone to get connectivity * Mifi is one good option, if you travel and are without wifi networks, as it will provide a network without draining your iPhone battery. Mifi systems typically use your cell phone data plan and needs cell data coverage (3g or 4g LTE). - * You can add ([here's how](http://openaps.readthedocs.io/en/latest/docs/While You Wait For Gear/monitoring-OpenAPS.html#accessing-your-rig-via-ssh)) your school or work or as many locations as you have as “known” wifi networks so your rig will automatically connect to the wifi in these places. You may want to contact the school before attempting to connect to their wifi network to see if you need any special accommodations in a 504 plan or IT department involvement to allow the rig to connect. -* OpenAPS will also default to always setting a temp basal (this can be turned off; [see description here](http://openaps.readthedocs.io/en/latest/docs/While You Wait For Gear/preferences-and-safety-settings.html#skip-neutral-temps)), which means it’ll be easier to look down at the pump and see if a temp basal is active to know that the loop has been working recently. + * You can add ([here's how](<../Usage and maintenance/monitoring-OpenAPS#accessing-your-rig-via-ssh>)) your school or work or as many locations as you have as “known” wifi networks so your rig will automatically connect to the wifi in these places. You may want to contact the school before attempting to connect to their wifi network to see if you need any special accommodations in a 504 plan or IT department involvement to allow the rig to connect. +* OpenAPS will also default to always setting a temp basal (this can be turned off; [see description here](<../Usage and maintenance/preferences-and-safety-settings#skip-neutral-temps>)), which means it’ll be easier to look down at the pump and see if a temp basal is active to know that the loop has been working recently. * The existing SkyLoop watchface for Pebble watches works seamlessly with OpenAPS looping. No changes are needed if you plan to try OpenAPS or Loop. ### Carbs @@ -126,7 +115,7 @@ See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.]( * Loop users must bolus from Loop app or Apple watch. Loop tracks IOB through reservoir volume changes as the default, and will fallback to the pump's event history in the event reservoir readings aren't continuous. * OpenAPS users bolus from the pump (either bolus wizard, or easy bolus button). OpenAPS will read the information about the bolus and other insulin activity based on the pump’s event history. * The pros of this means you won’t have to do anything special for pump rewinds/primes/site changes. OpenAPS will also provide treatment notes on your Nightscout site showing pump events such as suspensions, bolus wizard changes, basal profile edits, and primes. - * The downside of this means you DO need to set a temp basal to 0 unit/hour before suspending, so OpenAPS will know that you didn’t get insulin during the time of suspend (i.e. for shower or taking off the pump to swim, etc.) + * The downside of this means you DO need to set a temp basal to 0 unit/hour before suspending, so OpenAPS will know that you didn’t get insulin during the time of suspend (e.g. for shower or taking off the pump to swim, etc.) ### Multiple rigs * Loop uses one RileyLink paired via bluetooth. Typically users keep their RileyLink fairly close to the pump (like using a pants pocket) to help maintain communications. @@ -145,7 +134,7 @@ See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.]( ## Running multiple kinds of DIY systems * You can run different DIY systems (like Loop and OpenAPS) side-by-side, if you want to compare algorithms and how they behave. -* For those who like Loop's capabilities for bolusing from the phone, but don't want the requirement to enter carb absorption rates by meal, you can set Loop to "open loop" mode and use it for bolusing, and otherwise allow OpenAPS to be the primary closed loop to take advantage of the [Advanced Meal Assist (AMA)](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autosens.html#advanced-meal-assist-or-ama) algorithm, [autosensitivity](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autosens.html#auto-sensitivity-mode) to automatically adjust ISF, etc. However, see the following safety warnings below. +* For those who like Loop's capabilities for bolusing from the phone, but don't want the requirement to enter carb absorption rates by meal, you can set Loop to "open loop" mode and use it for bolusing, and otherwise allow OpenAPS to be the primary closed loop to take advantage of the [Advanced Meal Assist (AMA)](<../How it works/autosens#advanced-meal-assist-or-ama>) algorithm, [autosensitivity](<../How it works/autosens#auto-sensitivity-mode>) to automatically adjust ISF, etc. However, see the following safety warnings below. * **SAFETY WARNING:** If you choose to keep a Loop rig running alongside OpenAPS, you MUST turn off Loop's ability to write to Nightscout. If you neglect to do this, Nightscout will display double entries of carbs and/or boluses and greatly confuse you in the future. To enter carbs, you can enter directly through Nightscout Care Portal; [use the variety of IFTTT configurations to enter carbs to Nightscout via your Pebble watch, Alexa, Siri, etc.](../walkthrough/phase-4/ifttt-integration.md); or enter using the pump's bolus wizard. Even if you're just using the Loop app in open loop mode, and enter carbs or bolus from the pump bolus wizard for use in OpenAPS, you need to turn off Loop's ability to write to Nightscout. If you don't, Loop will read the boluses and carbs entered via the pump, upload them to Nightscout, and the duplicate entries will result in suboptimal post-meal decisions. You can either turn off Loop's ability to write to Nightscout, or simply close the app, but reopening the app for even a few minutes may still cause it to double enter to Nightscout if uploads are not disabled. If you do not plan to actively use Loop and DO want to bolus from the pump (via bolus wizard or easy bolus button) with OpenAPS, you should either disable Loop's Nightscout uploads, or plan to close the Loop app and not run them side-by-side. * **Caution**: You may want to disable the Nightscout COB pill, especially if you are using multiple DIY closed loop systems, as it will likely cause confusion. You should look to the (DIY closed loop system you are using)'s pill for information about COB. This means looking in the OpenAPS or Loop pill for information about COB. @@ -157,6 +146,6 @@ See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.]( Click [here](http://openaps.readthedocs.org/en/latest/) to go to a high-level view of the OpenAPS docs #### Where to get help with OpenAPS setup and maintenance: -* See [this page](http://openaps.readthedocs.io/en/latest/docs/Understanding OpenAPS-Overview/communication-support-channels.html) for various places for OpenAPS support; [the intend-to-bolus Gitter channel](https://gitter.im/nightscout/intend-to-bolus) is the best place for real-time troubleshooting assistance! +* See [this page](<../Understanding OpenAPS-Overview/communication-support-channels>) for various places for OpenAPS support; [the intend-to-bolus Gitter channel](https://gitter.im/nightscout/intend-to-bolus) is the best place for real-time troubleshooting assistance! * Don't hesitate to ask any question, any time. If it gets missed because there's a lot of activity, feel free to ask again! * You’ll probably also want to make sure and join [the openaps-dev Google Group](https://groups.google.com/forum/#!forum/openaps-dev), where new features and tools are most commonly announced and shared via email, so you’ll know when there are new things available to try. diff --git a/docs/docs/Resources/technical-resources.md b/docs/docs/Resources/technical-resources.md index 13a0dff77..f6244ca60 100644 --- a/docs/docs/Resources/technical-resources.md +++ b/docs/docs/Resources/technical-resources.md @@ -23,6 +23,8 @@ These represent a small selection of guides, tutorials, and quick references for [Codecademy Command Line Course](https://www.codecademy.com/en/courses/learn-the-command-line) +[Introduction to using Terminal on Mac](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) + [Cron How To Guide](https://help.ubuntu.com/community/CronHowto) ## Python diff --git a/docs/docs/Troubleshooting/CGM-rig-communications-troubleshooting.md b/docs/docs/Troubleshooting/CGM-rig-communications-troubleshooting.md index 1debd5a4d..ad16a2ddd 100644 --- a/docs/docs/Troubleshooting/CGM-rig-communications-troubleshooting.md +++ b/docs/docs/Troubleshooting/CGM-rig-communications-troubleshooting.md @@ -20,8 +20,8 @@ Depending on how you're getting BG to the rig, you'll need to do some basic trou ### If you're using Nightscout: -* **Make sure your BGs are getting TO Nightscout**. If you're using something to upload, check the uploader. If you're using the Share bridge to Nightscout, the #1 reason BGs don't get to Nightscout is because of Share. Make sure a) that you are getting BGs from the receiver/transmitter to the Share app; then b) that the Share app is open (i.e. re-open the app after your phone is restarted); then c) make sure the *Dexcom follow* app is getting data. Checking all of those usually resolves data to Nightscout. -* To get data FROM Nightscout, the most common problem is if your rig is offline. If your rig is not connected to the internet, it can't pull BGs from Nightscout. Troubleshoot your internet connectivity (i.e. ping google.com and do what you need to do to get the rig online). After that, also make sure your NS URL and API secret are correct. If they're not, re-run the setup script with those things corrected. +* **Make sure your BGs are getting TO Nightscout**. If you're using something to upload, check the uploader. If you're using the Share bridge to Nightscout, the #1 reason BGs don't get to Nightscout is because of Share. Make sure a) that you are getting BGs from the receiver/transmitter to the Share app; then b) that the Share app is open (e.g. re-open the app after your phone is restarted); then c) make sure the *Dexcom follow* app is getting data. Checking all of those usually resolves data to Nightscout. +* To get data FROM Nightscout, the most common problem is if your rig is offline. If your rig is not connected to the internet, it can't pull BGs from Nightscout. Troubleshoot your internet connectivity (e.g. ping google.com and do what you need to do to get the rig online). After that, also make sure your NS URL and API secret are correct. If they're not, re-run the setup script with those things corrected. ### If you're using xdrip+ or xdripAPS * **For Xdrip+ users** If you have no data in Nightscout, first check your uploader phone for data in xdrip+. If your uploader phone has data then there is likely a problem getting data from the uploader phone to Nightscout - check wifi and/or cellular connectivity of the phone/device similarly to the section above outlining getting BGs to Nightscout. diff --git a/docs/docs/Troubleshooting/Carelink.md b/docs/docs/Troubleshooting/Carelink.md new file mode 100644 index 000000000..fe46bd17a --- /dev/null +++ b/docs/docs/Troubleshooting/Carelink.md @@ -0,0 +1,11 @@ +# Dealing with the CareLink USB Stick + +**Note:** Generally, the Carelink stick is no longer supported. We *highly* recommend moving forward with a different radio stick. See [the hardware currently recommended in the docs](<../Gear Up/rig-options>), or ask on Gitter. + +The `model` command is a quick way to verify whether you can communicate with the pump. Test this with `openaps use model` (after you do a `killall -g oref0-pump-loop`). + +If you can't get a response, it may be a range issue. The range of the CareLink radio is not particularly good, and orientation matters; see [range testing report](https://gist.github.com/channemann/0ff376e350d94ccc9f00) for more information. + +Sometimes the Carelink will get into an unresponsive state that it will not recover from without help. You can tell this has happened if the pump is within range of the Carelink and you see a repeating series of "Attempting to use a port that is not open" or "ACK is 0 bytes" errors in pump-loop.log. When this happens the Carelink can be recovered by rebooting or physically unplugging and replugging the CareLink stick. + +Once you're setting up your loop, you may want to detect these errors and recover the Carelink programmatically. This can be done by running oref0-reset-usb (`oref0-reset-usb.sh`) to reset the USB connection. For example, you could create a cron job that would run `openaps use model`, or tail the 100 most recent lines in pump-loop.log, and grep the output looking for the errors noted above. If grep finds the errors, the cron job would run oref0-reset-usb. Just note that during USB reset you will lose the connection to all of your USB peripherals. This includes your Wi-Fi connection if your rig uses a USB Wi-Fi dongle. diff --git a/docs/docs/Troubleshooting/Common-error-messages.md b/docs/docs/Troubleshooting/Common-error-messages.md new file mode 100644 index 000000000..b57061e22 --- /dev/null +++ b/docs/docs/Troubleshooting/Common-error-messages.md @@ -0,0 +1,158 @@ +# Common error messages + +**WARNING:** Pay close attention to errors. An error may indicate a serious operational or functional problem with a computer system or component. + +These error messages may appear in response to openaps commands in the console, or in the system log (located at /var/log/syslog when using raspbian OS). Some errors can be safely ignored, like timeout errors that occur when the pump is out of range. + +## Permission not allowed + +The command you are running likely needs to be run with root permissions, try the same command again with ```sudo ``` in front of it + +Bash scripts (.sh files) need execute permissions to run. Run this command to grant execute permissions to the owner of a file. + +``` +chmod u+x myscript.sh +``` + +## ValueError: need more than 0 values to unpack + +A JSON file did not contain entries. It usually will self-resolve with the next successful pump history read. + +## Unable to upload to Nightscout + +OpenAPS has failed to upload to the configured nightscout website. If you're using a Medtronic CGM and no BG readings appear in nightscout, connect to your rig and the directory of your openaps app (default is myopenaps) run + +`openaps first-upload` + +## No JSON object could be decoded + +Usually means the file does not exist. It usually will self-resolve with the next successful pump history read. If it recurs, you will need to [drill down](<../Troubleshooting/oref0-setup-troubleshooting#running-commands-manually-to-see-what-s-not-working-from-an-oref0-setup-sh-setup-process>) to find the area where it is not successfully reading. + +## json: error: input is not JSON +``` +json: error: input is not JSON: Unexpected '<' at line 1, column 1: + Document Moved +``` + + This error usually comes up when you have pulled a file down from Nightscout that was an invalid file. Typically you might see this when trying to pull down treatments. Make sure that you have your HOST and API_KEY set correctly at the top of your cron, in your ~/.profile + +## TypeError: Cannot read property 'zzzz' of undefined + +example: `TypeError: Cannot read property 'rate' of undefined` + +Usually is related to a typo if you have manually been editing files. Otherwise, should self-resolve. + +## Could not parse carbratio date when invoking profile report + + Could not parse carbratio_data. + Feature Meal Assist enabled but cannot find required carb_ratios. + +This error may occur when you invoke `settings/profile.json` report. + +Check report definition in `openaps.ini`. If you have line `remainder = []` change it to `remainder = ` + +Below is correct definition + + [report "settings/profile.json"] + use = shell + bg_targets = settings/bg_targets.json + settings = settings/settings.json + basal_profile = settings/basal_profile.json + reporter = text + json_default = True + max_iob = preferences.json + device = get-profile + remainder = + insulin_sensitivities = settings/insulin_sensitivities.json + +## Could not get subg rfspy state or version ccprog or cannot connect to CC111x radio + +Full error is usually: +`Could not get subg_rfspy state or version. Have you got the right port/device and radio_type? (ccprog)` + +Or (on an intel edison): +`cannot connect to CC111x radio on /dev/spidev5.1` + +Basic steps using an Intel Edison with Explorer Board or a Raspberry Pi with Explorer HAT: + * checking with `killall -g oref0-pump-loop; openaps mmtune` to see if it is resolved yet + * Make sure the Explorer board or HAT has not become loose and is sitting correctly on the Edison board or Pi + * Check that your rig is in close range of your pump + * Check that your pump battery is not empty + * Reboot, or fully power down and start up your rig + +If you are using an Intel Edison with Explorer Board or a Raspberry Pi with Explorer HAT, and that does not resolve your issue, or if the two LEDs next to the microUSB ports on your Explorer board (respectively D1/D2 on Explorer HAT) stay on even after an mmtune, you may need to re-flash your radio chip: + * Stop the reboot loop: `sudo service cron stop && killall -g oref0-pump-loop && shutdown -c` + * Install ccprog tools on your Edison: `cd ~/src; git clone https://github.com/ps2/ccprog.git` + * Build (compile) ccprog so you can run it: `cd ccprog; make ccprog` + * If using a Raspberry Pi with Explorer HAT make sure you've installed MRAA (folder `~/src/mraa` present) + * Flash the radio chip: + +### Using an Intel Edision + Explorer Block: +``` +wget https://github.com/EnhancedRadioDevices/subg_rfspy/releases/download/v0.8-explorer/spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex +./ccprog -p 19,7,36 erase +./ccprog -p 19,7,36 write spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex +``` +If you receive an error saying that ccprog is only tested on C1110 chips then reboot the rig and try again. i.e. +``` +reboot +``` +Then: +``` +cd ~/src/ccprog +./ccprog -p 19,7,36 erase +./ccprog -p 19,7,36 write spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex +``` + +### Using a Raspberry Pi + Explorer HAT: +``` +wget https://github.com/EnhancedRadioDevices/subg_rfspy/releases/download/v0.8-explorer/spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex +./ccprog -p 16,18,7 reset +./ccprog -p 16,18,7 erase +./ccprog -p 16,18,7 write spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex +``` + + * Reboot, and try `killall -g oref0-pump-loop; openaps mmtune` to make sure it works + + +## Dealing with npm run global-install errors + +If you get an error while running an `npm global-install`, you may be able to clear it by running the following commands: + +`rm -rf /usr/lib/node_modules/.staging/ && rm -rf ~/src/oref0 && cd ~/src && git clone git://github.com/openaps/oref0.git || (cd oref0 && git checkout master && git pull)` + +then run `cd ~/src/oref0 && git checkout master && git pull` or if you are running dev then `cd ~/src/oref0 && git checkout dev && git pull` + +then run `cd ~/src/oref0 && npm run global-install` and then re-run oref0-setup. + +## Dealing with a corrupted git repository + +In oref0 versions prior to oref0 0.6.0, OpenAPS used git as the logging mechanism, so it commits report changes on each report invoke. Sometimes, due to "unexpected" power-offs (battery dying, unplugging, etc.),the git repository gets broken. You may see an error that references a loose object, or a corrupted git repository. To fix a corrupted git repository you can run `oref0-reset-git`, which will first run `oref0-fix-git-corruption` to try to fix the repository, and in case when repository is definitely broken it copies the .git history to a temporary location (`tmp`) and initializes a new git repo. In some versions of oref0 (up to 0.5.5), `oref0-reset-git` is in cron so that if the repository gets corrupted it can quickly reset itself. + +If you're still having git issues, you should `cd ~/myopenaps; rm -rf .git ; git init` . If you do this, git will re-initialize from scratch. This only applies to 0.5.x (or earlier) or upgrades to dev from master and does not apply to a fresh 0.6.x install. + +Warning: do not run any openaps commands with sudo in front of it `sudo openaps`. If you do, your .git permissions will get messed up. Sudo should only be used when a command needs root permissions, and openaps does not need that. Such permission problems can be corrected by running `sudo chown -R pi.pi .git` in the openaps directory. If you are using an Intel Edison, run `sudo chown -R edison.users .git`. + +oref0 0.6.x and beyond will not use git and will not have git-related errors to deal with. + +## Memory or disk space errors + +If you are having errors related to disk space shortages as determined by `df -h`, but you still have some room on your /root drive (i.e., it is not 100% in use), you can use a very lightweight and fast tool called ncdu (a command-line disk usage analyzer) to determine what folders and files on your system are using the most disk space. You can install ncdu as follows: `sudo apt-get install ncdu`. You can run it by running the following command: `cd / && sudo ncdu` and follow the interactive screen to find your disk hogging folders. + +An alternative approach to disk troubleshooting is to simply run the following command from the base unix directory after running `cd /`: + +`du -xh -d 3 | egrep "[1-9][0-9][0-9]M|[0-9]G"` (reports disk usage of all directories 3 levels deep from the current directory) + +Then, based on which folders are using the most space cd to those folders and run the above du command again until you find the folder that is using up the disk space. + +It is common that log files (i.e., the /var/log directory) are the cause for disk space issues. If you determine that log file(s) are the problem, use a command like `less` to view the last entries in the logfile to attempt to figure out what is causing the logfile to fill up. If you still have some room on your /root drive (i.e., it is not 100% in use according to `df /root`), you can temporarily free up space by forcing the logfiles to rotate immediately, with the following command: + +`logrotate -f /etc/logrotate.conf` + +If your /root drive is 100% in use according to `df /root`, you may need to free up space by removing log files. It should be safe to remove archived log files with the command `rm /var/log/*.[0-9] /var/log/*.gz`. Check again with `df /root` that you have plenty of space - normally your /root drive should have 80% or less space in use. If you have more in use but still less than 100% you can use one of the above techniques to free more space. + +If your disk is still 100% full, you may have to remove a live log file. Run the command `du /var/log/openaps/* /var/log/*|sort -n |tail -5`, which will show the largest 5 log files. Pick the largest file, use the command `less` to view the last entries to determine if there is a problem, and when you're sure you don't need the file any longer you can use the command `rm log_file_name` to delete it (replace log_file_name with the large log file's name). You should `reboot` after removing any of the live log files so the system resumes logging properly. + +## Errors during `openaps report invoke monitor/ns-glucose.json` or `ns-upload.sh` + +If you are getting your BG from Nightscout or you want to upload loop status/results to Nightscout, among other things you'll need to set 2 environment variables: `NIGHTSCOUT_HOST` and `API_SECRET`. This is handled in the setup script. If you do not set and export these variables you will receive errors while running `openaps report invoke monitor/ns-glucose.json` and while executing `ns-upload.sh` script which is most probably part of your `upload-recent-treatments` alias.Make sure your `API_SECRET` is in hashed format. Please see [this page](https://github.com/openaps/oref0#ns-upload-entries) or [this issue](https://github.com/openaps/oref0/issues/397) for details. Additionally, your `NIGHTSCOUT_HOST` should be in a format like `http://yourname.herokuapp.com` (without trailing slash). For the complete visualization guide use [this page](https://github.com/openaps/docs/blob/master/docs/Automate-system/vizualization.md) from the OpenAPS documentation. \ No newline at end of file diff --git a/docs/docs/Troubleshooting/General_linux_troubleshooting.md b/docs/docs/Troubleshooting/General_linux_troubleshooting.md index cfdadf97a..814301f85 100644 --- a/docs/docs/Troubleshooting/General_linux_troubleshooting.md +++ b/docs/docs/Troubleshooting/General_linux_troubleshooting.md @@ -1,14 +1,8 @@ -# General linux and other guide/troubleshooting basic +# Troubleshooting overview -Some conventions used in these docs: +Even those who follow this documentation precisely are bound to end up stuck at some point. This could be due to something unique to your system, a mistyped command, actions performed out of order, or even a typo in this guide. This section provides some tools to help diagnose the issue as well as some common errors that have been experienced and resolved before. If you get stuck, try re-reading the documentation again and after that, share what you've been working on, attempted steps to resolve, and other pertinent details in [#intend-to-bolus in Gitter](https://gitter.im/nightscout/intend-to-bolus) when asking for help troubleshooting. Here is also a [good blog post to read with tips on how to best seek help online to troubleshoot](https://diyps.org/2017/03/19/tips-for-troubleshooting-diy-diabetes-devices-openaps-or-otherwise/). -* 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. -* You will see a $ at the beginning of many of the lines of code. This - indicates that it is to be entered and executed at the terminal prompt. Do not type in the dollar sign $. -* Wherever there are `` 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 ``, you must use `myedison` every time you see ``. Do not include the `< >` brackets in your commands when you enter them. So for the example above, if the code snipped says `ssh root@.local`, you would enter `ssh root@myedison.local` - -### Before you get started +## Introduction to using Linux Some familiarity with using the Terminal app (Mac computers) or Putty (Windows computers) will go a long way, but is not required for getting started. Terminal (or PuTTY) is basically a portal into your rig, allowing us to use our computer's display and keyboard to communicate with the little [Edison or Pi] computer in your rig. The active terminal line will show your current location, within the computer's file structure, where commands will be executed. The line will end with a $ and then have a prompt for you to enter your command. @@ -16,11 +10,11 @@ There are many commands that are useful, but some of the commands you'll get com * `cd` means "change directory" - you can `cd ` to change into a directory; and `cd ..` will take you backward one directory and `cd` will take you back to the root directory. If you try to `cd` into a file, your computer will tell you that's not going to happen. -* `ls` means "list", is also your friend - it will tell you what is inside a directory. If you don't see what you expect, you likely want to `cd ..` to back up a level until you can orient yourself. If you aren't comfortable with what `cd` and `ls` do or how to use them, take a look at some of the Linux Shell / Terminal commands on the [Troubleshooting](../Resources/troubleshooting.md) page and the reference links on the [Technical Resources](../Resources/technical-resources.md) page. +* `ls` means "list", is also your friend - it will tell you what is inside a directory. If you don't see what you expect, you likely want to `cd ..` to back up a level until you can orient yourself. If you aren't comfortable with what `cd` and `ls` do or how to use them, take a look at some of the reference links on the [Technical Resources](<../Resources/technical-resources>) page. * `cat` means "concatenation" - it will show you the contents of a file if you `cat `. Very useful when trying to see what you have in preferences or other oref0 files. -* `vi` and `nano` are both editing command prefixes. Using those will bring you into files for the purposes of editing their contents. It is like `cat` except you will be able to edit. +* `vi` and `nano` are both text editors. Using those will bring you into files for the purposes of editing their contents. It is like `cat` except you will be able to edit. * Within `vi` editor, you will need to enter the letter `i` to begin INSERT mode (and a little INSERT word will be shown at the bottom of the screen once you do that). While in INSERT mode, you will be able to make edits. To exit INSERT mode, you will press `esc`. To save your changes and quit, you need to exit INSERT mode and then type `:wq`. * Within `nano` editor, you are automatically in editing mode. You can make your edits and then to exit and save, you'll use `control-x`, `y` (to save the edits), and then `return` to save the edits to the same filename you started with. @@ -30,6 +24,8 @@ There are many commands that are useful, but some of the commands you'll get com One other helpful thing to do before starting any software work is to log your terminal session. This will allow you to go back and see what you did at a later date. This will also be immensely helpful if you request help from other OpenAPS contributors as you will be able to provide an entire history of the commands you used. To enable this, just run `script ` at the beginning of your session. It will inform you that `Script started, file is `. When you are done, simply `exit` and it will announce `Script done, file is `. At that point, you can review the file as necessary. +## Directories on your rig + `ls ` will show the following files and subdirectories contained within the directory: * autotune * cgm @@ -95,3 +91,50 @@ One other helpful thing to do before starting any software work is to log your t `ls enact` will show the contents of the `enact` subdirectory; loop's suggested and enacted temp basals and changes. * enacted.json * suggested.json + + +## Generally useful linux commands + +More comprehensive command line references can be found [here](http://www.computerworld.com/article/2598082/linux/linux-linux-command-line-cheat-sheet.html) and [here](http://www.pixelbeat.org/cmdline.html). For the below, since these are basic linux things, also try using a basic search engine (e.g. Google) to learn more about them and their intended use. + +`ls -alt` (List all of the files in the current directory with additional details.) + +`cd` (Change directory) + +`pwd` (Show the present working directory (your current location within the filesystem).) + +`sudo ` (Super-user do. Temporarily elevates the current users permission to that of root.) + +`apt-get install ` (Aptitude is a package manager, when a package is missing it will (usually) be there and can be installed by issuing 'apt-get install .) + +`tail -f /var/log/syslog` + +`grep LOOP /var/log/syslog` (Display lines in file that contain a string, in this example, 'LOOP') + +`df -h` (shows available memory on your rig) + +`ifconfig` + +`cat ` (Display the contents of the file.) + +`nano ` (Open and edit the file in the nano text editor.) + +`stat ` + +`head ` (Display the beginning of the file.) + +`less ` (Display the contents of the file, with advanced navigation) + +`pip freeze` + +`sudo reboot` (Reboot the system) + +`sudo shutdown -h now` (The correct way to shut down the Raspberry Pi from the command line. Wait for the green light to stop blinking before removing the power supply.) + +`dmesg` (Displays all the kernel output since boot. It’s pretty difficult to read, but sometimes you see things in there about the wifi getting disconnected and so forth.) + +`uptime` (Shows how long the system has been running and the load average of last minute/5 minutes/15 minutes) + +`crontab -l` (Display cron jobs) + +`sudo service cron status` (Display info on cron service. Also use `stop` and `start`) \ No newline at end of file diff --git a/docs/docs/Resources/Medtronic-Button-Errors.md b/docs/docs/Troubleshooting/Medtronic-Button-Errors.md similarity index 100% rename from docs/docs/Resources/Medtronic-Button-Errors.md rename to docs/docs/Troubleshooting/Medtronic-Button-Errors.md diff --git a/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md b/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md index 37b02ad04..d89b6a146 100644 --- a/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md +++ b/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md @@ -2,44 +2,17 @@ The major categories of Nightscout troubleshooting include: -**Connectivity**. The rig and Nightscout are good friends. Information is usually two-way so long as the rig has access to the internet (aka, online use). When rigs go "offline", NS will go stale until internet is again available. If you're having issues with NS and it's a brand new setup, you'll want to double check [per the below](http://openaps.readthedocs.io/en/latest/docs/Troubleshooting/Rig-NS-communications-troubleshooting.html#setting-up-your-ns-hosting-site) that URL, API secret, etc. are correct. +**Connectivity**. The rig and Nightscout are good friends. Information is usually two-way so long as the rig has access to the internet (aka, online use). When rigs go "offline", NS will go stale until internet is again available. If you're having issues with NS and it's a brand new setup, you'll want to double check [per the below](<#setting-up-your-ns-hosting-site>) that URL, API secret, etc. are correct. -**Mlab size is too big and you need to clean it**. [See below](http://openaps.readthedocs.io/en/latest/docs/Troubleshooting/Rig-NS-communications-troubleshooting.html#mlab-maintenance) for how to check the size of, and compact if needed, your mlab database, which can influence what displays in Nightscout. +**Mlab size is too big and you need to clean it**. [See below](<#mlab-maintenance>) for how to check the size of, and compact if needed, your mlab database, which can influence what displays in Nightscout. -**Future data**. Sometimes entries will get time stamped incorrectly, or the device time zones are off. [See below](http://openaps.readthedocs.io/en/latest/docs/Troubleshooting/Rig-NS-communications-troubleshooting.html#nightscout-admin-tools) for how to resolve. +**Future data**. Sometimes entries will get time stamped incorrectly, or the device time zones are off. [See below](<#nightscout-admin-tools>) for how to resolve. ![Top level troubleshooting for rig-Nightscout issues](../Images/Rig-NS_troubleshooting.jpg) ## Setting up your NS hosting site -You will need to make sure that you have setup you site configuration settings in your NS hosting site (usually that means Heroku) according to the docs. See the [Nightscout Setup page](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/nightscout-setup.html) for help in setting up your NS site. If you don't add the OpenAPS-specific settings to your setup, the communications with the rig will not work properly. - -### What information is passed from rig to NS? - -The rig uploads the following information to NS: - -* Assuming pump communications are good, the rig will read information from the pump as follows: - * boluses and carbs; entered through either the pump bolus wizard or the easy bolus button - * current temp basal rate and duration/time set - * pump status; bolusing or suspended, reservoir volume, pump battery voltage - * pump notes; time changes, profile changes, battery changes, alarms (these show as grey dots on NS site) - * if a MDT enlite user, BGs will be read directly from the pump - -* From OpenAPS looping, the additional information is also uploaded: - * determine-basal information (such as IOB, COB, temp basal enacted, etc) goes to fill out the OpenAPS pill in NS - * rig battery voltage and estimated % - -* If (1) a dexcom receiver is connected to the rig and (2) the loop is setup with G4-upload as the CGM type and (3) the rig has internet, then the rig will also upload BGs and/or rawBG directly to NS. This keeps the loop functional even if the Share app fails. For example, if the phone battery dies during the night, and Share App therefore goes down...the rig can read BGs/rawBGs directly from the receiver and use your home wifi to upload to NS still. - -### What information is passed from NS to rig? - -The careportal "treatment" entries and BG data are the two most important items transmitted from NS to the rig. - -* Careportal entries transmitted and **USED** by the loop are: - * carb entries - * temp BG targets - -* BG values from Dexcom share servers via the NS bridge +You will need to make sure that you have setup you site configuration settings in your NS hosting site (usually that means Heroku) according to the docs. See the [Nightscout Setup page](<../While You Wait For Gear/nightscout-setup>) for help in setting up your NS site. If you don't add the OpenAPS-specific settings to your setup, the communications with the rig will not work properly. ## mLab maintenance @@ -80,7 +53,7 @@ Return to your home screen and you will be able to verify the `Size on Disk` has ### Cleanout data - **NOTE:** Before you cleanout your data, please check out the option to upload (or "donate") your data anonymously to the [OpenAPS Data Commons](http://openaps.readthedocs.io/en/latest/docs/Give%20Back-Pay%20It%20Forward/data-commons-data-donation.html) project. The OpenAPS Data Commons was created to enable a simple way to share data sets from the community, both with traditional researchers who will create traditional research studies, and with groups or individuals from the community who want to review data as part of their own research projects. So before you delete or cleanout any data from your mLab, consider doing an upload to OpenAPS Data Commons first. + **NOTE:** Before you cleanout your data, please check out the option to upload (or "donate") your data anonymously to the [OpenAPS Data Commons](<../Give Back-Pay It Forward/data-commons-data-donation>) project. The OpenAPS Data Commons was created to enable a simple way to share data sets from the community, both with traditional researchers who will create traditional research studies, and with groups or individuals from the community who want to review data as part of their own research projects. So before you delete or cleanout any data from your mLab, consider doing an upload to OpenAPS Data Commons first. If your mLab database issue is `size `, then you will need to cleanout some of the historical data collected by your NS site. There are two methods to cleanout space and delete data in your mLab database: @@ -109,11 +82,29 @@ If you go to your Nightscout site's settings (the three horizontal bars in the u ![mLab collection select](../Images/admin_tools.jpg) -## Future data +## Future data: all of a sudden, Nightscout is no longer showing treatments (bolus, carbs, finger BGs) on the graph or rendering my basals. + +If you suddenly find that Nightscout is not showing treatments (bolus, carbs, finger BGs etc.) on the graph; and/or that your basals are no longer being rendered in the blue basal line; but otherwise, everything looks normal and you are looping properly: + +You probably somehow got a future-dated treatment. Sometimes data gets recorded into your NS site that can be date stamped into the future - for example, if your CGM, BG meter, OpenAPS rig, or pump had the wrong time or date set. + +These future-data will cause problems in rendering (displaying) data correctly, and can usually cause loop failures as well. + +To remove future treatments: + +Check your NS Admin Tools section (click the three horizontal bars in the upper right of your Nightscout site, then Admin Tools) to easily identify and clean out your database of future data points (press the "remove treatments in the future" button). If the future treatments were caused by a time mismatch, you'll need to resolve that first, or the future dated treatments may simply be re-uploaded. + +![How to delete future-dated treaments](../Images/Remove_future_treatments.png) + +Every once in a while, however, that future data point tool will not work effectively because the future data will actually be stored within the `devicestatus` collection's information. If that is the case, you should try cleaning out the `devicestatus` collection, as described above in the Cleanout Data section. + +## No data is being displayed, or no Nightscout pills are displayed + +If you are using a "test pump" that has not received sufficient data in some time, Nightscout pills will NOT be displayed onscreen. Nightscout may also not work if it hasn't had CGM data in a while - so if you haven't been using a CGM and uploading CGM data to Nightscout for the past few days, the site may be empty as well. If this happens, simply use this pump in tandem with a CGM so glucose values are recorded and eventually uploaded to Nightscout. Once sufficient data has been collected (and OpenAPS plugin is enabled and saved) the OpenAPS pills should appear automatically. Medtronic CGM users may also [need to do this to get their CGM data flowing into Nightscout after a gap in uploading data](<../Customize-Iterate/offline-looping-and-monitoring#note-about-recovery-from-camping-mode-offline-mode-for-medtronic-cgm-users>). -Sometimes data gets recorded into your NS site that can be date stamped into the future. For example, if your CGM or pump had the wrong time or date set. These future-data will cause problems in rendering (displaying) data correctly, and can usually cause loop failures as well. Check your NS Admin Tools section (described above) to easily identify and cleanout your database of future data points. Every once in awhile however, that future data point tool will not work effectively because the future data will actually be stored within the `devicestatus` collection's information. If that is the case, you should try cleaning out the `devicestatus` collection, as described above in the Cleanout Data section. +Dexcom CGM users should make sure they have "share" enabled and have actively shared their data with at least one follower, before data will begin flowing to Nightscout. If you don't want to share your data with another person, you can just follow yourself. -## Nightscout info incorrect +## Nightscout pill info is incorrect There are three pills (aka, information boxes) that are noteworthy about your NS display, and that people commonly interpret as "incorrect" despite all the warnings/explanations in these docs. @@ -121,4 +112,4 @@ There are three pills (aka, information boxes) that are noteworthy about your NS * **COB** pill should NOT be included on your heroku settings "ENABLE" line. If you go against this advice, you may experience laggy NS performance and see incorrect COB reported in your COB pill on the NS site. Don't say you haven't been warned. Until NS dev team can address these issues, the recommendation stands to NOT include COB in your NS site settings. -* **BASAL** pill should NOT be used in your NS site. The information on that pill updates so slowly sometimes, that you may incorrectly jump to assumptions that your rig is behaving differently than it actually is. Instead, use the OpenAPS pill to find current information about your current basal rate...or press the ESC button on your pump in order to directly read the current temp basal. Additionally, the basal rendering (the blue lines of the NS display) can sometimes lag by up to 2-5 minutes, depending on loop activities...so again use the OpenAPS pill or pump if you are interested in the most up-to-date information on temp basals. +* **BASAL** pill should NOT be used in your NS site. The information on that pill updates so slowly sometimes, that you may incorrectly jump to assumptions that your rig is behaving differently than it actually is. Instead, use the OpenAPS pill to find current information about your current basal rate...or press the ESC button on your pump in order to directly read the current temp basal. Additionally, the basal rendering (the blue lines of the NS display) can sometimes lag by up to 2-5 minutes, depending on loop activities...so again use the OpenAPS pill or pump if you are interested in the most up-to-date information on temp basals. \ No newline at end of file diff --git a/docs/docs/Troubleshooting/Wifi-and-hotspot-issues.md b/docs/docs/Troubleshooting/Wifi-and-hotspot-issues.md new file mode 100644 index 000000000..257329d8c --- /dev/null +++ b/docs/docs/Troubleshooting/Wifi-and-hotspot-issues.md @@ -0,0 +1,30 @@ +# Wifi and hotspot issues + +## My wifi connection keeps dropping or I keep getting kicked out of ssh +There is a script that you can add to your root cron that will test your connection and reset it if it is down. Note, this does not have to be for an Edison, you can set this up for a Pi, etc as well. + +``` +cd ~/src +git clone https://github.com/TC2013/edison_wifi +cd edison_wifi +chmod 0755 /root/src/edison_wifi/wifi.sh +``` +Next, add the script to your root cron. Note this is a different cron that what your loops runs on, so when you open it don't expect to see your loop and other items you have added. Here is an example that runs every two minutes (odd minutes). You could also do it every 5 minutes or less. + * Log in as root ```su root``` + * Edit your root cron ```crontab -e``` + * Add the following line ```1-59/2 * * * * /root/src/edison_wifi/wifi.sh google.com 2>&1 | logger -t wifi-reset``` + +## I forget to switch back to home wifi and it runs up my data plan +You can add a line to your cron that will check to see if `` is available and automatically switch to it if you are on a different network. + * Log in as root ```su root``` + * Edit your root cron ```crontab -e``` + * Add the following line ```*/2 * * * * ( (wpa_cli status | grep > /dev/null && echo already on ) || (wpa_cli scan > /dev/null && wpa_cli scan_results | egrep > /dev/null && sudo wpa_cli select_network $(wpa_cli list_networks | grep jsqrd | cut -f 1) && echo switched to && sleep 15 && (for i in $(wpa_cli list_networks | grep DISABLED | cut -f 1); do wpa_cli enable_network $i > /dev/null; done) && echo and re-enabled other networks) ) 2>&1 | logger -t wifi-select``` + +## I am having trouble consistently connecting to my wifi hotspot when I leave the house +When you turn on your hotspot it will only broadcast for 90 seconds and then stop (even if it is flipped on). So, when you leave your house you need to go into the hotspot setting screen (and flip on if needed). Leave this screen open until you see your rig has connected. It may only take a few seconds or a full minute. + +## I am not able to connect to my wireless access point on my iPhone +Consider changing your iPhone's name. In most cases iPhone will set the phone's SSID to something like "James’s iPhone" By default Apple puts a curly apostrophe (’) into the SSID instead of a straight one ('). Your choices from here are either paste in the curly apostrophe in wpa_supplicant.conf, or change the name on the phone. To change the name on the iPhone: + * On your iOS device, go to Settings > General > About. + * Tap the first line, which shows the name of your device. + * Rename your device, then tap Done. \ No newline at end of file diff --git a/docs/docs/Troubleshooting/index.rst b/docs/docs/Troubleshooting/index.rst deleted file mode 100644 index aec2d60a4..000000000 --- a/docs/docs/Troubleshooting/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Troubleshooting ----------------------- - -.. toctree:: - :maxdepth: 4 - - oref0-setup-troubleshooting - General_linux_troubleshooting - Pump-rig-communications-troubleshooting - CGM-rig-communications-troubleshooting - Rig-NS-communications-troubleshooting diff --git a/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md b/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md index 240653be8..cebe839e7 100644 --- a/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md +++ b/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md @@ -8,7 +8,7 @@ You won't hurt anything by running the script multiple times. If you already hav ## Should I enact cron? -Cron is the scheduler that runs the loop. I.e. this is the automation feature to automate your closed loop. If you're using a test pump, it's pretty safe to go ahead and automate your loop. But if you're not sure, you can always come back and do this later. +Cron is the scheduler that runs the loop. This is the automation feature to automate your closed loop. If you're using a test pump, it's pretty safe to go ahead and automate your loop. But if you're not sure, you can always come back and do this later. If you're troubleshooting and looking to use `openaps` manually, cron must be momentarily disabled to free access to local resources. To check if cron is running use `crontab -e` or `crontab -l`. If you see a file filled with content, chances are cron is enabled. @@ -37,15 +37,15 @@ Make sure to check through the following list before asking on Gitter if your se * Check and make sure your pump is near your rig. Closer is better, e.g. check if it works when the pump and rig are at most 20 inches (50 cm) apart. * Check that your pump battery is not empty. * Check and make sure your pump is not suspended or stuck in rewind or prime screens. If it's a test pump, you don't even have to fill a reservoir, but put your pinky finger or eraser-end of a pencil in for slight pressure when priming so the pump will "sense" it and stop. Make sure to back out of the prime screen. -* If using a pump that has been without power for some time, it is a good practice to set a small temporary basal rate and bolus before trying to loop with that pump. Otherwise, you could see seemingly-unrelated errors in your log files as OpenAPS attempts to loop with missing information from the history. ([Best practice is to use the pump before you start looping with it](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/collect-data-and-prepare.html#use-your-gear), regardless, so this is likely to be an issue for a "test" pump setup rather than one you have been using.) +* If using a pump that has been without power for some time, it is a good practice to set a small temporary basal rate and bolus before trying to loop with that pump. Otherwise, you could see seemingly-unrelated errors in your log files as OpenAPS attempts to loop with missing information from the history. ([Best practice is to use the pump before you start looping with it](<../While You Wait For Gear/collect-data-and-prepare#use-your-gear>), regardless, so this is likely to be an issue for a "test" pump setup rather than one you have been using.) * Check to make sure you have a carb ratio set manually in your Medtronic insulin pump, if it is not done, the following display will appear in your pump.log: Could not parse input data: [SyntaxError: /root/myopenaps/monitor/iob.json: Unexpected end of input] * Check to make sure your carelink and/or radio stick is plugged in. * Check to make sure your receiver is plugged in, if you're plugging a receiver in. * Don't have data in Nightscout? Make sure there is no trailing slash `/` on the URL that you are entering and that the API secret is correct. Check your Nightscout URL, too - it's one of the most common errors to mistype that. (And FWIW, you shouldn't be typing things like that in the first place: that's what copy and paste are for.) * Check and make sure your receiver is >50% charged (if battery low, it may drain the rig battery and prevent it from operating). -* A reboot may be required after running oref0-setup if the Carelink is unable to communicate with the pump (e.g. you see "Attempting to use a port that is not open" errors in pump-loop.log). Additional Carelink troubleshooting steps can be found in [Dealing with the CareLink USB Stick](http://openaps.readthedocs.io/en/latest/docs/Resources/troubleshooting.html#dealing-with-the-carelink-usb-stick). -* If you see the error `failed to get string preference .pump_serial`, that usually means you copied your preferences over or ran runagain, instead of following the directions and using the full interactive setup script, when upgrading to a new version/installing a new version (such as going from 0.6.x to 0.7.0). To resolve, run `oref0-setup.sh` manually per the [directions](https://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/update-your-rig.html#step-2-re-run-oref0-setup). (*This means you'll enter your responses into the interactive setup script again*.) - +* A reboot may be required after running oref0-setup if the Carelink is unable to communicate with the pump (e.g. you see "Attempting to use a port that is not open" errors in pump-loop.log). Additional Carelink troubleshooting steps can be found in [Dealing with the CareLink USB Stick](<../Troubleshooting/carelink>). +* If you see the error `failed to get string preference .pump_serial`, that usually means you copied your preferences over or ran runagain, instead of following the directions and using the full interactive setup script, when upgrading to a new version/installing a new version (such as going from 0.6.x to 0.7.0). To resolve, run `oref0-setup.sh` manually per the [directions](<../Customize-Iterate/update-your-rig#step-2-re-run-oref0-setup>). (*This means you'll enter your responses into the interactive setup script again*.) +* 512/712 users - make sure you follow the additional instructions for the 512/712 before asking for help troubleshooting. You have a few additional steps you need to do. ## Running commands manually to see what's not working from an oref0-setup.sh setup process @@ -54,7 +54,7 @@ You've probably run into an error in your setup where someone has recommended "r * Start by killing anything that's currently running. ` killall-g oref0-pump-loop` * Look and see what's running in your cron. `crontab -l` * If you want to do more than one command of debugging, it's best to disable your cronjobs, use `/etc/init.d/cron stop`. Don't forget to start the cronjobs afterwards or reboot your rig to make sure the cronjobs will be running. - * Run whichever alias is failing to see what commands it is running. I.e. if the pump loop is failing, it's `openaps pump-loop`, which you can run to show what's inside it by `openaps alias show pump-loop`. + * Run whichever alias is failing to see what commands it is running. E.g. if the pump loop is failing, it's `openaps pump-loop`, which you can run to show what's inside it by `openaps alias show pump-loop`. * Run each of those commands next individually, and that should give you a better idea of where it's failing or getting stuck. Do this, and share back (if needed) with your troubleshooter about where you think it's getting stuck. If that still doesn't give you or your troubleshooter enough info, keep drilling down further: * **For example**, if your pump-loop.log always shows `Error, retrying` after `Old pumphistory:`, then you'd want to run `openaps refresh-old-pumphistory` manually to reproduce the problem and see if you can get more error details. * If necessary, you can drill down further. So in this example, you might want to run `openaps alias show refresh-old-pumphistory` to see what *that* alias does, and then `openaps gather` to drill down further. diff --git a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md index a8b7d3397..c7bc16fd4 100644 --- a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md +++ b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md @@ -1,69 +1,17 @@ # Where to go for help -There are several ways to communicate with other participants and contributors in the #OpenAPS project. See also the [Resources](../Resources/index.rst) section for additional assistance. +First check the [Troubleshooting](<../Troubleshooting/General_linux_troubleshooting>) section for assistance, and try searching within this documentation for the problem you are having (including text of any error message you are seeing). -**Note:** It's best practice not to share your pump's serial number, so make sure not to include it in pictures or pasted text output when seeking help on pump communication. Ditto for Nightscout URL and API secret and other private information that could enable someone to access your setup. - -**Related**: You may want to read [this blog post for tips on how to best seek help when troubleshooting online](https://diyps.org/2017/03/19/tips-for-troubleshooting-diy-diabetes-devices-openaps-or-otherwise/) - there is a lot of information you can provide proactively when seeking help that will aid in getting your issue resolved more quickly. - -### Read the documentation! - -One huge resource is this documentation. We recommend bookmarking the [link](http://openaps.readthedocs.org/en/latest/) to the docs, as they are frequently updated (sometimes daily!) as we add more information, troubleshooting tips, and more. Anytime we are asked a question on one of the below channels, we try to add it to the documentation. So chances are, your question may already be answered here! - -#### Tips for navigating the documentation - -You may notice that the left hand side of the documentation has navigation. It is organized in order of setting up OpenAPS, and has various sections on finding your gear; what you should do before you build a rig; how to setup up your rig; and additional features and tips and tricks for optimizing your looping setup. This navigation is long, you can mouse over the section and scroll down to see all the pages listed in the top-level navigation! - -
- Click here to expand some pictures that shows you the left hand navigation - -![Show documentation navigation](../Images/Understand_documentation_basic_1.png) +There are several ways to communicate with other participants and contributors in the #OpenAPS project. To help get your issue resolved more quickly, you can proactively provide information as described in [this blog post for tips on how to best seek help when troubleshooting online](https://diyps.org/2017/03/19/tips-for-troubleshooting-diy-diabetes-devices-openaps-or-otherwise/). -![Show documentation navigation 2](../Images/Understand_documentation_basic_2.png) - -![Show troubleshooting section of docs](../Images/Troublshooting_docs_section.png) -
- -You'll also notice that there is more content than just these high-level pages! If you click on a link in the left, many of them expand to show the sub-sections include, which make it easy to jump directly to the section you're looking for. If there is a `+`, that means there is more content you can expand. - -![Show how menu expands in the navigation of the docs](../Images/Show_nav_expand.png) - -#### The docs also have their own search function! - -See the top left of the docs for the search box. It's helpful to search *inside* the documentation itself, rather than Google, because you'll stay inside the most up to date version of the documentation. You may want to try a different word or shorter phrase if you don't get any results for your search phrase, as we may have worded a section differently. - -![Show documentation search](../Images/Search_documentation.png) +**Note:** It's best practice not to share your pump's serial number, so make sure not to include it in pictures or pasted text output when seeking help on pump communication. Ditto for Nightscout URL and API secret and other private information that could enable someone to access your setup. ### Slack -There is a [Slack channel](https://omniapsslack.azurewebsites.net/) that you can add yourself to - then look for the `#OpenAPS` channel to post questions. That slack can also be used to stay up to date on other, broader DIY diabetes projects such as communication around other pumps that are being explored and worked on, but aren't yet DIY loopable. +There is a [Slack channel](https://omniapsslack.azurewebsites.net/) that you can add yourself to - then look for the `#OpenAPS` channel to post questions. This is the best place to get real-time support with anything related to OpenAPS. It is a great place to introduce yourself and get some help from those who are a few steps further down the road. That slack can also be used to stay up to date on other, broader DIY diabetes projects such as communication around other pumps that are being explored and worked on, but aren't yet DIY loopable. (Here's [why we often recommend asking questions in an archived community space, written when the primary place to go for support was Gitter instead of Slack](https://diyps.org/2016/08/17/why-you-should-post-questions-in-gitter/).) -### Gitter -[Gitter](https://gitter.im/) is a messaging/chat service similar to IRC. It provides integration with GitHub and several other services. It's the best place to get real-time support with anything related to OpenAPS. (Here's [why we often recommend asking questions on Gitter](https://diyps.org/2016/08/17/why-you-should-post-questions-in-gitter/).) - -* The [nightscout/intend-to-bolus]( https://gitter.im/nightscout/intend-to-bolus) channel is where you will find active #OpenAPS discussions ranging from technical issues with openaps tools to control theory to general information. It is a great place to introduce yourself and get some help from those who are a few steps further down the road. -* For Autotune conversations, use the [openaps/autotune channel](https://gitter.im/openaps/autotune) - -
- Click here to expand a list of tips for using Gitter, from using the search function to tagging someone to posting screenshots or posting logs -
- -**Search** -Gitter has a search function to find old information, but since it isn't threaded conversations, you may need to spend some time reading the posts after the search result to find the ultimate resolution to the question. So, if you find a particularly useful bit of information that you couldn't find in the docs...please make a [PR to the docs](http://openaps.readthedocs.io/en/latest/docs/Resources/my-first-pr.html) so that the information is permanently stored for others to find. - -**Tag/mention someone** -Tag someone! You can tag particular people if you are responding to them directly by using the `@` symbol and then typing their username. This will help notify the person that you are "speaking to them". If someone asks you for information that shouldn't be shared in the public channel, you can also private message people by hovering over their profile picture and choosing the "chat privately" button. Please do not abuse the tagging or PM features: most questions are best asked untagged in the appropriate channel, so that anyone can respond to them as soon as they read Gitter and see the question. There are people from all over the world online at all hours who can help with most kinds of questions, and the core developers usually read every message in Gitter a few times per day and try to answer any questions that got missed. - -![Gitter PM sample](../Images/gitter_pm.jpg) +#### Posting logs -**Posting photos or screenshots in Gitter** - -Gitter has a mobile app which works great for posting text, but does not allow for posting images directly. If you need to post a photo using the mobile app, you'll have to host your photo file somewhere like Dropbox and post the link to the file location. - -Using the desktop application, you can simply drag and drop the file into the Gitter chat window. The file will upload and then display in the chat thread after a short period of time to upload. - -**Posting logs** - -Posting copy-paste code from your rig is also another valuable activity for troubleshooting. To post a single line of information, you can use the single-backtick-quote that is found on the key to the left of the number 1 key on the keyboard. (hint: it is under the ~ on the same key). You can also long-press the single quote key on your iPhone keypad to bring up the single-backtick-quote that will work in Gitter. If you start and stop a portion of your text with those single quotes, it will `look like this`. +Posting copy-paste output from your rig is also another valuable activity for troubleshooting. To post a single line of information, you can use the single-backtick-quote that is found on the key to the left of the number 1 key on the keyboard. (hint: it is under the ~ on the same key). You can also long-press the single quote key on your iPhone keypad to bring up the single-backtick-quote that will work in Gitter. If you start and stop a portion of your text with those single quotes, it will `look like this`. Posting multiple lines of copy-paste from your rig will also sometimes be needed. You can do that by: @@ -73,11 +21,17 @@ Posting multiple lines of copy-paste from your rig will also sometimes be needed * press `control-enter` again to get another new line * enter 3 single quotes to end the section -The copy-pasted lines should have 3 backticks on the line above and the line below. The example below shows, on the bottom, how the formatted text yielded the black box of text in Gitter. Using this format helps troubleshooters read your information easier than unformatted copy and paste. +The copy-pasted lines should have 3 backticks on the line above and the line below. Using this format helps troubleshooters read your information easier than unformatted copy and paste. -![Gitter tickmarks](../Images/gitter_marks.jpg) +### Google Group +A google group focused on #OpenAPS development work can be found [here](https://groups.google.com/d/forum/openaps-dev) - everyone is encouraged and welcome to join! You can add yourself directly to the group. It's worth setting your preferences to receive all email from the group; there's not a huge volume, and this is one of the ways we share updates about hardware or release announcements if you're not hanging out on Gitter or Facebook or Twitter. -
+### Gitter +[Gitter](https://gitter.im/) is a messaging/chat service similar to IRC. It provides integration with GitHub and several other services. This has been replaced by the Slack channel, but the history on Gitter may still have relevant answers. + +* The [nightscout/intend-to-bolus]( https://gitter.im/nightscout/intend-to-bolus) channel is where you will find active #OpenAPS discussions ranging from technical issues with openaps tools to control theory to general information. +* For Autotune conversations, use the [openaps/autotune channel](https://gitter.im/openaps/autotune) +* Searching: Note that Gitter has a search function to find old information, but since it isn't threaded conversations, you may need to spend some time reading the posts after the search result to find the ultimate resolution to the question. So, if you find a particularly useful bit of information that you couldn't find in the docs...please make a [PR to the docs](<../Resources/my-first-pr>) so that the information is permanently stored for others to find. ### Facebook diff --git a/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md b/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md index 8f0e54d0f..cceba9033 100644 --- a/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md +++ b/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md @@ -3,27 +3,29 @@ How do you make decisions about your diabetes? You gather data, crunch the numbers, and take action. A DIY loop is no different. It gathers data from: -* [your pump](https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/pump.html) -* [your CGM](https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/CGM.html) -* any other place you log information, like [Nightscout](https://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/nightscout-setup.html) +* [your pump](<../Gear Up/pump>) +* [your CGM](<../Gear Up/CGM>) +* any other place you log information, like [Nightscout](<../While You Wait For Gear/nightscout-setup>) -It then uses this information to do the math and decide how your basal rates might need to be adjusted (above or below your underlying basal rate), to adjust and eventually keep or bring your BGs into your target range. +It then uses this information to do the math and decide how your basal rates might need to be adjusted (above or below your underlying basal rate) in order to keep or bring your BGs in your target range. -## How does your closed loop gather data? +## How does the closed loop gather data? -With OpenAPS, there is a “rig” that is a physical piece of hardware. It has “brains” on the computer chip to do the math; plus a radio stick to communicate with your pump; plus it can talk to your phone and to the cloud via wifi to gather additional information, plus report to the world about what it’s doing. +With OpenAPS, there is a “rig” that is a physical piece of hardware. It has “brains” on the computer chip to do the math; plus a radio stick to communicate with your pump; plus it can talk to your phone and to the cloud via wifi to gather additional information and report to the world about what it’s doing. The rig needs to: * communicate with the pump and read history - what insulin has been delivered * communicate with the CGM (either directly, or via the cloud) - to see what BGs are/have been doing -The rig runs a series of commands to collect this data, runs it through the algorithm and does the decision-making math based on the settings (ISF, carb ratio, DIA, target, etc.) in your pump. +The rig runs a series of commands to collect this data, runs it through the algorithm, and does the decision-making math based on the settings (ISF, carb ratio, DIA, target, etc.) in your pump. -## But how does it do everything it needs to do to gather data and make decisions and tell the pump what to do? +## How does it control the pump based on its decisions? -When you build an OpenAPS rig, you run through the setup described in this documentation, and: +When you build an OpenAPS rig, you follow the instructions in this documentation to: * physically put the pieces of your rig together -* [load the open source software on it](https://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html) -* configure it to talk to YOUR devices and have your information and safety settings on it (based on your preferences) +* install the open source software on it +* configure it to talk to YOUR devices and use your preferences and safety settings -The open source software is designed to make it easy for the computer to do the work you used to do to calculate what needs to be done. It runs a series of reports to collect data from all the devices and places. Then it prepares the data and runs the calculations. Then it attempts to communicate and send any necessary adjustments to your pump. Then it reads the data back, and does it over and over again. You can see what it's doing in the logs of the rig, or by viewing the information on your watch or on Nightscout. +The open source software is designed to make it easy for the computer to do the work you used to do to calculate what needs to be done. During each "loop" - about every five minutes - the rig collects data from your pump and CGM. It prepares the data and runs the calculations. Then it sends any necessary adjustments to your pump. You can see what it's doing in the logs of the rig, or by viewing the information on your watch or on Nightscout. + +You can learn more about how the system is designed for safety in the [OpenAPS Reference Design](https://OpenAPS.org/reference-design/) and read more about the calculations [in the 'How it Works' section](<../How it works/understand-determine-basal#understanding-the-determine-basal-logic>). \ No newline at end of file diff --git a/docs/docs/Understanding OpenAPS-Overview/index.rst b/docs/docs/Understanding OpenAPS-Overview/index.rst deleted file mode 100644 index 61fb3bf9e..000000000 --- a/docs/docs/Understanding OpenAPS-Overview/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Understanding OpenAPS/Overview ----------------------- - -.. toctree:: - :maxdepth: 4 - - - how-openaps-works-overview - overview-of-build-process - communication-support-channels diff --git a/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md b/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md index 7ee1e2bad..f9e56aeb0 100644 --- a/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md +++ b/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md @@ -1,15 +1,15 @@ -# How you will build your rig +# How to get your own OpenAPS system up and running The OpenAPS setup process can be broken up into several parts: -![Basic steps of building and using OpenAPS](../Images/Building_OpenAPS_steps.jpg) +1. These can be done in parallel: -As with all things new, there is a little bit of a learning curve to building your first OpenAPS rig. Read slowly, double-check your spelling and make sure you don't skip steps. If you get stuck or are unsure, you can use the screenshots to compare how the resulting screens should look. You can also post to Gitter or Facebook to ask for specific help if you find yourself stuck. + A. [Choose and get your hardware.](<../Gear Up/hardware-overview>) You have several options for compatible pumps, CGMs, and rig components. While you will likely already have some of the gear you'll need (e.g., you'll likely keep using your CGM) it may take a few weeks to choose and find a compatible pump and to collect your rig hardware. Once you have your rig pieces (a computer, a radio board, and a battery) you'll need to put them together. -Over time, you may also choose to enable advanced features or update your rig, as more features and algorithm improvements become available. You should make sure to stay plugged in to key channels (like openaps-dev google group; Looped on Facebook; and on Twitter by following @OpenAPS) so you can be aware when updates become available. You should also make sure to tell us when you’ve closed your loop, which includes notes on how to join the safety-critical announcement list in case we need to alert you to any safety-related changes or updates. + B. [Prepare to use OpenAPS.](<../While You Wait For Gear/collect-data-and-prepare>) You'll need to set up Nightscout if you haven't already, and make a few tweaks if you have; review your pump settings; and make sure you're comfortable using your pump if it's new to you. You'll also do some reading to make sure you understand how OpenAPS works, how you'll use your new closed loop, and what options are available to you. -## What you’ll see in this guide +2. [Install OpenAPS on your rig!](<../Build Your Rig/install-overview>) There are detailed instructions that walk you through this process. This may take approximately 1-3 hours, but it's doable regardless of how much of a "tech person" you are. -* Wherever you see text that is formatted `like this`, it is usually a code snippet. You should copy and paste instead of attempting to type this out; this will save you debugging time for finding your typos. +3. Customize your system: once you're comfortable with basic usage of your new closed loop, you can try out advanced features, add integrations, etc. Over time, you may also choose to enable advanced features or update your rig, as more features and algorithm improvements become available. -* Wherever there are ``, 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 `myopenaps` as your `` directory, you must use `myopenaps` every time you see ``. Choose carefully when naming things so it’s easy to remember. Do not include the `< >` brackets in your name. +As with all things new, there is a little bit of a learning curve to building your first OpenAPS rig. Read slowly, double-check your spelling and make sure you don't skip steps. If you get stuck or are unsure, you can use the screenshots to compare how the resulting screens should look. You can also [ask for specific help](<./communication-support-channels>) if you find yourself stuck. diff --git a/docs/docs/Understanding OpenAPS-Overview/using-the-docs.md b/docs/docs/Understanding OpenAPS-Overview/using-the-docs.md new file mode 100644 index 000000000..d28513fbb --- /dev/null +++ b/docs/docs/Understanding OpenAPS-Overview/using-the-docs.md @@ -0,0 +1,32 @@ +# Using this documentation + +We recommend bookmarking the [link](http://openaps.readthedocs.org/en/latest/) to the docs, as they are frequently updated (sometimes daily!) as we add more information, troubleshooting tips, and more. Anytime we are asked a question on one of the below channels, we try to add it to the documentation. So chances are, your question may already be answered here! + +**Warning:** We do not recommend using a PDF version of this guide. The docs are updated continuously, and with a PDF, you will not get the freshest real-time edits. If you have Internet connectivity, we recommend instead having the docs pulled up in an Internet browser so you can refresh. This is especially true if you are working on a setup over the course of multiple days. + +## Formatting in this guide + +* Wherever you see text that is formatted `like this`, it is usually a code snippet. You should copy and paste instead of attempting to type this out; this will save you debugging time for finding your typos. + +* Wherever there are ``, 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 `myopenaps` as your `` directory, you must use `myopenaps` every time you see ``. Choose carefully when naming things so it’s easy to remember. Do not include the `< >` brackets in your name. + +## The docs have their own search function! + +See the top left of the docs for the search box. It's best to search *inside* the documentation itself, rather than Google, because you'll stay inside the most up to date version of the documentation. You may want to try a different word or shorter phrase if you don't get any results for your search phrase, as we may have worded a section differently. + +![Show documentation search](../Images/Search_documentation.png) + +## Tips for navigating the documentation + +You may notice that the left hand side of the documentation has navigation. It is organized in order of setting up OpenAPS, and has various sections on finding your gear; what you should do before you build a rig; how to setup up your rig; and additional features and tips and tricks for optimizing your looping setup. This navigation is long, you can mouse over the section and scroll down to see all the pages listed in the top-level navigation! + +![Show documentation navigation](../Images/Understand_documentation_basic_1.png) + +![Show documentation navigation 2](../Images/Understand_documentation_basic_2.png) + +![Show troubleshooting section of docs](../Images/Troublshooting_docs_section.png) + +You'll also notice that there is more content than just these high-level pages! If you click on a link in the left, many of them expand to show the sub-sections include, which make it easy to jump directly to the section you're looking for. If there is a `+`, that means there is more content you can expand. + +![Show how menu expands in the navigation of the docs](../Images/Show_nav_expand.png) + diff --git a/docs/docs/Customize-Iterate/bluetooth-tethering-edison.md b/docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md similarity index 97% rename from docs/docs/Customize-Iterate/bluetooth-tethering-edison.md rename to docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md index 9400ae9bf..6bb60a09b 100644 --- a/docs/docs/Customize-Iterate/bluetooth-tethering-edison.md +++ b/docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md @@ -20,12 +20,12 @@ Even though some specific phones are fully capable of bluetooth tethering and th ### Benefit of Using BT Tethering to Your Phone's Hotspot -* BT tethering automatically picks up when your rig loses wifi (i.e. walking out the door) without you even having to pull your phone out of your pocket +* BT tethering automatically picks up when your rig loses wifi (e.g. walking out the door) without you even having to pull your phone out of your pocket * It also automatically allows the rig to pick back up on wifi when it finds a known wifi network * It consumes less battery on your phone compared to a wifi connection to your phone's hotspot Below is an image that shows how a rig automatically switches from a known wifi network to an internet connection through a BT tether to a phone: -![Bluetooth papertrail oref0 online switch](../Images/BT_papertrail.PNG) +![Bluetooth papertrail oref0 online switch](../../Images/BT_papertrail.PNG) ### Phone selection for BT Tethering @@ -74,7 +74,8 @@ Certain phones don't work well using bluetooth tethering with OpenAPS. Various u ## Configure Bluetooth tethering on Edison running Jubilinux [optional] -This section is completed by the install method found [here](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#copy-and-paste-to-run-the-wifi-and-oref0-setup-scripts) . If you selected the option of installing Bluetooth at a later time during installation you may skip to Bluetooth Setup, the next section. +This section is completed by the install method found [here](<../../Build Your Rig/step-3-setup-script>) . If you selected the option of installing Bluetooth at a later time during installation you may skip to Bluetooth Setup, the next section. + ### Install dependencies You will need to get the MAC address from your phone or whatever device you are using. * On Android, go to Settings/About Phone/ Status; you will find your Bluetooth address looking like AA:BB:CC:DD:EE:FF @@ -98,7 +99,7 @@ root@edisonhost:~# bluetoothd --version 5.37 ``` -### Bluetooth setup +### Bluetooth setupUsage and maintenance/optimize-your-settings `1.` First, check that your wpa_supplicant.conf file doesn't contain any content that will interfere with oref0-online. @@ -108,7 +109,7 @@ a) Open the wpa_supplicant.conf file to make sure it is set up to allow oref0-on b) Delete the phrase `update_config=1` from the file if it is present. -![Remove update_config](../Images/update_config_adjustment.png) + ![Remove update_config](../../Images/update_config_adjustment.png) `2.` Next, stop cron to make sure oref0-online doesn't interfere: @@ -127,7 +128,7 @@ b) Delete the phrase `update_config=1` from the file if it is present. `sudo bluetoothd --experimental &` As shown in the "success" section below, you should see a single line returned with a short string of numbers and then be returned to a clean prompt. If you instead see messages about D-bus Setup failed (as shown in the "Failure" part of screenshot), or otherwise see that you don't have a clean prompt returned in order to enter the next command...go back to the `sudo killall bluetoothd` and try again. -![Bluetooth sudo commands](../Images/BT_sudos.png) +![Bluetooth sudo commands](../../Images/BT_sudos.png) c) Wait at least 10 seconds, and then run: `sudo hciconfig hci0 name $HOSTNAME` @@ -151,7 +152,7 @@ agent on default-agent ``` -![Bluetooth pairing](../Images/BT_pairing.png) +![Bluetooth pairing](../../Images/BT_pairing.png) For Android ******************************** diff --git a/docs/docs/Customize-Iterate/on-the-go-wifi-adding.md b/docs/docs/Usage and maintenance/Wifi/on-the-go-wifi-adding.md similarity index 69% rename from docs/docs/Customize-Iterate/on-the-go-wifi-adding.md rename to docs/docs/Usage and maintenance/Wifi/on-the-go-wifi-adding.md index 7c67e91ad..8efe9993f 100644 --- a/docs/docs/Customize-Iterate/on-the-go-wifi-adding.md +++ b/docs/docs/Usage and maintenance/Wifi/on-the-go-wifi-adding.md @@ -14,13 +14,28 @@ network={ psk="my wifi password" } ``` + + +If you want to add open networks to your list, then add: + +``` +network={ + key_mgmt=NONE + priority=-999 +} +``` + Newer versions of the setup script enact the editor `vi` instead of `nano`. The important commands to know in vi are `i` to turn on insert mode on and `esc` to turn it off. Once insert mode is on, edit your file and when you are done hit `esc`. To exit vi you have a few choices: `:q!` will exit and not save any changes, in case you mess up badly. `:w` will write your changes and keep you in vi. Once you are satisfied with your edits, `:wq` will write your changes and quit vi. Older version use `nano`, which is more intuitive, but doesn't work well over USB serial console connections, unless your window is exactly 80 characters wide. If you're using `nano`, you can save the edits to the file using `control-x`, `y`, and `enter`. If you mess up, you can do `control-x` and `n`. +It is a good idea to add your phone's personal hotspot to the list of wifi networks at least as a backup, even if using Bluetooth tethering. By toggling your hotspot off-on, it will generate a wifi-tether signal for approximately 90 seconds, so that your rig can find it and connect. Since wifi-tethers are similar to a regular wifi connection, your rig will not automatically hop off this connection when it gets to your home wifi network. You will need to remember to turn off your wifi-tether if you want your rig to connect back to your home wifi network. By contrast, a hotspot connection done by BT-tether does not require any toggling and your rig will connect/disconnect as it leaves/comes to a known wifi network in your wp_supplicant list. + +Note for iPhone users: It is recommended that you update the name of your iPhone to remove any apostrophes. Apple's default is to name iPhones with an apostrophe such as "Katie's iPhone". This can cause some problems for wifi connections sometimes. You can rename your iPhone by going into your iPhone's Settings, General, About, and then Name. + 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. -![Edit wifi file](../Images/sample-wifi-file.png) +![Edit wifi file](../../Images/sample-wifi-file.png) 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: diff --git a/docs/docs/While You Wait For Gear/understanding-wifi-options.md b/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md similarity index 91% rename from docs/docs/While You Wait For Gear/understanding-wifi-options.md rename to docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md index 09b175be8..5f5c31763 100644 --- a/docs/docs/While You Wait For Gear/understanding-wifi-options.md +++ b/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md @@ -1,8 +1,8 @@ -# Understanding your wifi options +# Wifi overview If you want to keep your rig small and portable, using the internet will be important (assuming you are using a Dexcom CGM) to keep BG values flowing to the loop. Ways your rig can stay online and access the internet are: -* Joining known wifi networks [(you'll be able to add more wifi networks to your rig in the future)](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/on-the-go-wifi-adding.html) +* Joining known wifi networks * BT-tethering to your cell phone's hotspot * Wifi-tethering to your cell phone's hotspot * Wifi-tethering to mifi device @@ -11,7 +11,9 @@ By default, the rig's programming in OpenAPS is to prefer joining known wifi con Most users prefer a combination of known wifi networks and BT-tethering to maintain internet access for their rig. This minimizes cell phone data use while at the same time requiring no intentional action on the user's part when they enter/leave their known network areas. The rig will move seamlessly off/on known networks and BT-tethers without needing help. Using wifi-tethers requires the user to manually turn the connections on/off when they get into the range of a preferred wifi network to save cell data, therefore those connections aren't preferred. -These [helpful mobile apps](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/useful-mobile-apps.html) are worth checking out, as they'll aid you with accessing your rig when it gets connected online. +These [helpful mobile apps](<../../Customize-Iterate/useful-mobile-apps>) are worth checking out, as they'll aid you with accessing your rig when it gets connected online. + +It is also possible to have your rig [loop offline](<../../Customize-Iterate/offline-looping-and-monitoring>) but this requires some additional setup. ### Home Wifi @@ -35,7 +37,7 @@ Most home routers can be accessed by going to the URL `http://192.168.1.1` on yo By having access to your home router, you can easily see if you rig is listed as a connected device. You can also bring up the MAC address and IP address of the rig, which may be helpful in other areas of the rig setup that are discussed later. -![Home Router](../Images/access_ip.png) +![Home Router](../../Images/access_ip.png) ### School wifi networks @@ -43,6 +45,8 @@ School districts vary widely in their wifi structure and access. Start talking If you are sending your t1d kid to school with an OpenAPS rig, getting on the school's wifi network will save you cell phone data and phone battery. Some school districts will need the MAC address of the rig to add it to their "approved" devices list. Other school districts may provide a special login for the rig. +It is common for educational networks not to provide full Internet access, just web - i.e., they allow HTTP(S) but not other protocols like SSH. In this case, your child's online rig may "work" at school and send/receive data from Nightscout, but will not be accessible via SSH and may not send logs to Papertrail. + If the school district refuses to allow the rig access to the school's wifi network, you can use BT tethering to your phone's hotspot to stay online while at school. The downside is that you will be using your cell data during the school day and it will cause added drain on the phone's battery. In some cases, schools have let the phone on the school's wifi but not the rig. Unfortunately though, this won't help much if your kid uses an iPhone. IPhones do not allow the rig to be on the phone's hotspot while the phone is also on school's wifi. So, when the rig connects to the iPhone, the iPhone will disconnect from the school's wifi. Androids (some of them at least) are able to maintain a wifi connection while the rig is tethered to its hotspot. diff --git a/docs/docs/Usage and maintenance/entering-carbs-bolus.md b/docs/docs/Usage and maintenance/entering-carbs-bolus.md new file mode 100644 index 000000000..e43139905 --- /dev/null +++ b/docs/docs/Usage and maintenance/entering-carbs-bolus.md @@ -0,0 +1,48 @@ +# Entering carbs & doing boluses + +How do you enter carbs & do boluses with OpenAPS? You have a variety of ways to do things. + +## Doing boluses + +Boluses always have to be set on the pump for OpenAPS to take them into consideration. For safety reasons, insulin added to Nightscout NOT via the pump - for instance, logging an event when using an insulin pen - will not be taken into account. (If you are briefly away from your pump and using injections, the simplest solution to keep OpenAPS up to date is to bolus into air!) + +* **Easy bolus button**: Previously before OpenAPS, you probably used the [easy bolus button](<../While You Wait For Gear/collect-data-and-prepare#easy-bolus-button>) to add up a bolus in increments. (E.g. if your pump had increments of 0.5u, you could quickly dial up to a bolus by pressing the up button as many times as needed; hitting enter to confirm it; hitting enter again to deliver the bolus.) + +* **Bolus wizard**: Or, you may have used the bolus wizard, sometimes with BG or carb entry, or just as a bolus. + +**In OpenAPS, you can still use those same methods for delivering manual doses of insulin (boluses).** + +## Entering carbs into OpenAPS + +Before OpenAPS, you may or may not have entered carbs into your pump. With OpenAPS, most people *do* want the rig to know about carbs. + +Carbs can be either entered on the pump (for example, using Bolus Wizard) or into Nightscout (carb entries in Nightscout can either be made directly using the Care Portal) or via IFTTT or XDrip. +You have a variety of ways to enter them, depending on whether your rig is **online** or **offline**. + +Look at this image for the big picture: + +![Different methods for entering carbs](../Images/Carb_data_to_rig.jpg) + +### Offline carb entry + +* You can still use the bolus wizard to enter carbs, although a non-zero amount of bolus must be delivered in order for OpenAPS to record the carbs. If you adjust the bolus recommended by the bolus wizard down to zero and deliver the zero units (as you might ordinarily do if you ate carbs in order to treat a low), the pump may (depending on your pump version) fail to record a bolus wizard record in pumphistory, causing OpenAPS to ignore the carbs as if you hadn't entered them. In that situation, consider delivering the smallest unit of bolus possible (like 0.05u or 0.1u) so that OpenAPS will record the carbs entered into the bolus wizard. +* Some pumps can use the ['meal marker' feature](<../Customize-Iterate/offline-looping-and-monitoring#entering-carbs-while-offline>). +* See section on [extended and dual wave substitutes](<../While You Wait For Gear/collect-data-and-prepare#extended-and-dual-wave-substitute>) for information on how extended boluses are handled in OpenAPS. + +**SAFETY WARNING ABOUT BOLUS WIZARD:** If the pump has a target range high end set lower than the BG input into the Bolus Wizard, the Bolus Wizard will add insulin to cover the carbs as well as bring BG down to the high end. E.g. if your high end is 110 and you enter a 160 BG and 45g of carbs in the Bolus Wizard, the Bolus Wizard will dose 1U to bring BG to 110 and 3U for carbs (assuming 50 (mg/dL)/U and 15g/U factors). The rig will likely have already dosed insulin to bring your BG to your low target, and you are potentially "double dosing". In these scenarios, you will have too much insulin onboard and can experience a severe low. If you use the Bolus Wizard, ensure the high end of the BG target range is a high number such as 250 mg/dL. OpenAPS default behavior (`wide_bg_target_range` preference) is to only use the target range lower end. Setting the high end does not impact the OpenAPS algorithms. + +### Online carb entry + +If your rig is online, you have a variety of ways to enter carbs online. + +* Nightscout Care Portal +* AndroidAPS NS Client ([Download the app-nsclient-release APK from here](https://github.com/MilosKozak/AndroidAPS/releases).) +* Many options for using IFTTT to get carbs into Nightscout Care portal. ([See the IFTTT page here for instructions](<../Customize-Iterate/ifttt-integration>).) + * Pebble or Apple watch + * Google Calendar + * Siri, Alexa, Google, etc. +* Via an HTTPS POST to the treatments API, for example using the iOS Shortcuts app +* Android users: you can use the Care portal option in [NSClient app found here](https://github.com/nightscout/NSClient-Android/releases). +* via [xDrip](https://github.com/NightscoutFoundation/xDrip), +* via [CarbDialer (iOS App)](https://apps.apple.com/us/app/carbdialer/id1315809661). + diff --git a/docs/docs/While You Wait For Gear/example-max-safety-chart.md b/docs/docs/Usage and maintenance/example-max-safety-chart.md similarity index 100% rename from docs/docs/While You Wait For Gear/example-max-safety-chart.md rename to docs/docs/Usage and maintenance/example-max-safety-chart.md diff --git a/docs/docs/While You Wait For Gear/examples_safety_caps_in_play.png b/docs/docs/Usage and maintenance/examples_safety_caps_in_play.png similarity index 100% rename from docs/docs/While You Wait For Gear/examples_safety_caps_in_play.png rename to docs/docs/Usage and maintenance/examples_safety_caps_in_play.png diff --git a/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md similarity index 81% rename from docs/docs/While You Wait For Gear/monitoring-OpenAPS.md rename to docs/docs/Usage and maintenance/monitoring-OpenAPS.md index 341635017..d9db8a6da 100644 --- a/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md +++ b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md @@ -3,47 +3,45 @@ There are two general groups of ways to monitor your rigs: * Online, meaning it requires the rig to have internet connectivity (via a wifi or hotspot/tethered connection) + * Offline, meaning the rig does not have any internet connectivity ![Examples of online and offline monitoring](../Images/Online_Offline_monitoring.jpg) ## The main ways of monitoring your rig ONLINE include: -* [Papertrail](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#papertrail-remote-monitoring-of-openaps-logs-recommended) -* [Accessing via SSH (either using an app on your phone, or your computer)](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#accessing-your-online-rig-via-ssh) -* [Nightscout](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/nightscout-setup.html) +* [Papertrail](<#papertrail-remote-monitoring-of-openaps-logs-recommended>) +* [Accessing via SSH (either using an app on your phone, or your computer)](<#accessing-your-online-rig-via-ssh>) +* [Nightscout](<../While You Wait For Gear/nightscout-setup>) * AndroidAPS NS Client ([Download the app-nsclient-release APK from here](https://github.com/MilosKozak/AndroidAPS/releases).) * Pebble watch (your watchface of choice, such as [Urchin](https://github.com/mddub/urchin-cgm)) -* [Apache Chainsaw](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#apache-chainsaw) +* [Apache Chainsaw](<#apache-chainsaw>) ******************************** ## The main ways of monitoring your rig OFFLINE include: -* [Pancreabble](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#pancreabble-offline-connection-to-pebble-watch) (offline connection to your Pebble watch) -* For Android users: "[Hot Button](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#hot-button-for-android-users)" -* Accessing via [SSH over Bluetooth](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#accessing-your-offline-rig-via-ssh-over-bluetooth), or [by using a mobile router so your phone/rig can connect to the same network offline](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#accessing-your-offline-rig-via-ssh-when-your-phone-and-rig-are-connected-to-the-same-network) -* For any phone type: [Creating a web page that can be accessed on the phone via the rig's IP address](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#offline-web-page-from-rig-for-any-phone-user) - -******************************** - -## You'll probably come back to this page later to setup different monitoring options +* [Connecting via SSH over a serial connection](<../Build Your Rig/logging-into-rig-serial>). +* [Pancreabble](<#pancreabble-offline-connection-to-pebble-watch>) (offline connection to your Pebble watch) +* For Android users: "[Hot Button](<#hot-button-for-android-users>)" +* Accessing via [SSH over Bluetooth](<#accessing-your-offline-rig-via-ssh-over-bluetooth>), or [by using a mobile router so your phone/rig can connect to the same network offline](<#accessing-your-offline-rig-via-ssh-when-your-phone-and-rig-are-connected-to-the-same-network>) +* For any phone type: [Creating a web page that can be accessed on the phone via the rig's IP address](<#offline-web-page-from-rig-for-any-phone-user>) -At this point, if you're not yet set up on OpenAPS, you won't quite be ready to set up all of the below options for accessing your rig - because your rig is not built yet! But, just know that there are different "online" and "offline" ways to **monitor** your rig, so you'll want to think about your preferences for both situations, and know that the instructions on the rest of this page are here when you're more familiar and are ready to set up some or all of them. - -******************************** +********************************* ## Accessing your online rig via SSH See below for different ways to access your rig: -* [If your computer and rig are on the same wifi network](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#if-your-computer-and-rig-are-on-the-same-wifi-network) -* [If your computer and rig are on different wifi networks](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#if-your-computer-and-rig-are-on-different-wifi-networks) -* [If your iPhone and rig are on the same wifi network](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#if-your-iphone-and-rig-are-on-the-same-wifi-network) +* [If your computer and rig are on the same wifi network](<#if-your-computer-and-rig-are-on-the-same-wifi-network>) +* [If your iPhone and rig are on the same wifi network](<#if-your-iphone-and-rig-are-on-the-same-wifi-network>) +* [Set up an autossh reverse tunnel to access from a different network](#autossh-reverse-tunnel) ******************************** ### If your computer and rig are on the same wifi network +These instructions will work only if your computer and rig are on the same wifi network. If they are on different networks, you will need to connect using a data cable connected to the UART port on the rig to use SSH. See [these instructions](<../Build Your Rig/logging-into-rig-serial>). + ![If your computer and rig are on the same wifi network](../Images/Computer_rig_same_wifi.png) #### For Mac computers @@ -82,45 +80,6 @@ See below for different ways to access your rig: ![Windows IP address for rig](../Images/access_7.png) -### If your computer and rig are on different wifi networks - -![If your computer and rig are on different wifi networks](../Images/Computer_rig_different_wifi.png) - -**Access to the rig will need a cable to connect the UART port on the rig with the USB port on the computer. You will need a cable capable of transmitting data. If you try all of the steps below and are unsuccessful at connecting, try a new cable.** - -#### For Mac computers - -* Use the Terminal app on the Mac, or follow [these directions for Windows](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html#if-you-re-using-a-windows-pc-for-console) - -* If you're using a Mac, use the command `sudo screen /dev/tty.usbserial-* 115200` to enable “screen” mode. You will be prompted to enter a password. Enter your **computer's password** not the rig's password here. - -![Mac Screen first password](../Images/access_mac_password.png) - -* You may see a blank screen. Press RETURN to bring up the edison’s login screen. Login as `root` and use your root password (you should have changed it from the default of `edison` during the setup of the rig - if not, please [go back and do so now](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html#initial-edison-setup). A successful login will look like below. - -![Mac Screen successful login](../Images/access_mac_screen.png) - -* If instead, you see a message at the bottom of the screen that says "Sorry, could not find a PTY." that usually means the system has not cleared a previous screen session. If you only had the rig connected by one cable in the UART port on rig, you can simply unplug the rig from the computer and move to a new USB port on the computer. If you don't have any "new" USB ports that were not used by the previous login attempt, then close out terminal app, restart the computer, and try again. This will clear the error. - -![Mac Screen message for busy port](../Images/access_mac_sorry.png) - -* If instead you see a message at the bottom of the screen that says "Cannot exec '/dev/tty.usbserial-*': No such file or directory", double check that you have your rig and computer connected via the rig's UART port. Using the OTG port will cause this error message. Or typos in the screen command will have same result. Double check your spelling, or better yet...use copy and paste whenever possible. - -![Mac Screen message for OTG port](../Images/access_mac_no_exec.png) - -#### For Windows Users - -* Navigate to your Control Panel and then to Device Manager. Click on the Ports to open your USB serial port. Find the COM port that the rig is connected to. In the screenshot below, COM7. Note: different USB ports will have different numbers. If you regularly plug your rig into the computer and use this connection type, you may need to make sure you update the COM number in the steps below if you are switching between different USB ports. - -![Windows COM port number](../Images/access_1.png) - -* Open PuTTY program. Click on the Serial radio button, enter the COM number you got from the previous step into the Serial line number and change the speed to 115200. Click on Open button. - -![Windows serial setup](../Images/access_2.png) - -* Enter `root` for the login and the password is whatever you changed it to during setup in Phase 0. The default password was edison. As you type the password, no keystrokes will appear on the screen. Successful login will leave you at a prompt for the root user as shown below. - -![Windows serial login success](../Images/access_3.png) ### autossh Reverse Tunnel @@ -164,6 +123,8 @@ Once the test are successful, add a line to your rig crontab to launch autossh a ******************************** + + ## Papertrail remote monitoring of OpenAPS logs (RECOMMENDED) If you want to remotely view the rig's logs/loops, you can use Papertrail service. We HIGHLY recommend setting up this service for at least the first month of your OpenAPS use to help remotely and quickly troubleshoot your rig, if you have problems. The first month of Papertrail comes with a very generous amount of free data. If you decide you like the service, you can sign up for monthly plan. Typically, the monthly cost for using Papertrail with OpenAPS is approximately $5-7 depending on how many rigs you use and how long you'd want to save old data. @@ -176,7 +137,7 @@ Go to http://papertrailapp.com and setup a new account. Choose to setup a new s ## System logging -Login to your rig. If you need help with that, please see the [Accessing Your Rig](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#accessing-your-online-rig-via-ssh) section of these docs. Copy and paste the code that is displayed in your new system setup's shaded box, as shown in the red arrowed area in the screen shot above. This will setup papertrail for just your syslogs. But, we now will need to add more (aggregate) your logs such as pump-loop and ns-loop. +Login to your rig. If you need help with that, please see the [Accessing Your Rig](<#accessing-your-online-rig-via-ssh>) section of these docs. Copy and paste the code that is displayed in your new system setup's shaded box, as shown in the red arrowed area in the screen shot above. This will setup papertrail for just your syslogs. But, we now will need to add more (aggregate) your logs such as pump-loop and ns-loop. ### Aggregating logs @@ -271,9 +232,9 @@ and then go to your papertrailapp website to see the log ### Optimize Papertrail use -To make the most of your Papertrail logs, setting up some of your account settings and filters will help streamline your troubleshooting +To make the most of your Papertrail logs, setting up some of your account settings and filters will help streamline your troubleshooting. -##### Account Filters +#### Account Filters Adding filters to your incoming Papertrail logs will help minimize unuseful data (and help keep you below your data caps) and streamline your review of your relevant OpenAPS logs. You can go to your Papertrail account's `Settings` and then choose the `Log Destinations`. Click on `Log Filters` to go to the screen where you can add specific filters. @@ -283,7 +244,7 @@ Click on the `Add Log Filter` button and add three filters for `CRON`, `libmraa` ![papertrail log filters](../Images/log_filters.png) -##### Saved Searches +#### Saved Searches Unfortunately, Papertrail does not currently have an app for use on mobile devices. Instead, you will be using an internet browser to view your papertrail. Setting up saved searches, in advance, can help you sort through your logs more efficiently. Most OpenAPS troubleshooting will involve either wifi connection issues or pump communications. Some helpful searches to save in order to find those issues fastest are: @@ -363,7 +324,7 @@ AND also make this edit using `vi /etc/default/avahi-daemon` Change the number **subg_rfspy state or version??** -If your loop is failing, lights are staying on, and you see repeated error messages about "Do you have the right subg_rfsby state or version?" as below, then you need to head to [this section of docs](http://openaps.readthedocs.io/en/latest/docs/Resources/troubleshooting.html#could-not-get-subg-rfspy-state-or-version-have-you-got-the-right-port-device-and-radio-type) to fix that issue. Don't worry, it is a 5 minute fix. Very straight-forward. +If your loop is failing, lights are staying on, and you see repeated error messages about "Do you have the right subg_rfsby state or version?" as below, then you need to head to [this section of docs](<../Troubleshooting/Common-error-messages#could-not-get-subg-rfspy-state-or-version-ccprog-or-cannot-connect-to-cc111x-radio>) to fix that issue. Don't worry, it is a 5 minute fix. Very straight-forward. ![papertrail subg error message](../Images/subg_rfspy.png) @@ -592,7 +553,7 @@ To speed up the command execution you can add to the `/etc/ssh/sshd_config` the ### Accessing your offline rig via SSH over Bluetooth -Your phone and rig must be BT paired and connected over BT PAN. See https://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/bluetooth-tethering-edison.html for BT PAN configuration. When you first open Termius on your mobile device (JuiceSSH and SimpleSSH are also good choices) it will prompt you to add a new host. Click the + button to add a new host. Turn the toggle on for Use SSH and then fill out the following information: +Your phone and rig must be BT paired and connected over BT PAN. See [here](<../Usage and maintenance/Wifi/bluetooth-tethering-edison>) for BT PAN configuration. When you first open Termius on your mobile device (JuiceSSH and SimpleSSH are also good choices) it will prompt you to add a new host. Click the + button to add a new host. Turn the toggle on for Use SSH and then fill out the following information: Alias – use an alias name that let’s you know which rig and which connection point this host is for, for example YourRigName on device BT Hostname – Enter the IP address of the rig as assigned by your BT PAN @@ -605,7 +566,7 @@ Click Save in the upper right corner. You should now see the host you just creat Just like the trick for getting internet to your rig through a network that requires you to log in via a portal (a "captive" network), a mobile router (e.g. [HooToo](https://www.hootoo.com/network-devices.html)) or other brand) can create a network that allows your phone and rig both to be connected, allowing you to then SSH into your rig, just as if they were connected via cellular. -You can then use the [same methods to SSH in for the phone or computer (that you're using to SSH) being on the same network as the rig](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/monitoring-OpenAPS.html#accessing-your-online-rig-via-ssh). +You can then use the [same methods to SSH in for the phone or computer (that you're using to SSH) being on the same network as the rig](<#accessing-your-online-rig-via-ssh>). Note: you will want to set your mobile router up in advance, and give it the same network name and password as a network already on your rig; or otherwise make sure to add the network and password to your rig before you travel and want to use this offline. @@ -657,7 +618,7 @@ Create the above script by running `nano /root/myopenaps/http.sh` , then paste t You may need to adjust the values in `'{print substr($0,12,5)}'` - whilst I know these work on the rigs I have set them up on, other's have had better results with `{print substr($0,13,5)}'` -B. You will also need to start up the SimpleHTTPserver service that is already installed on jubilinux in the location you will place your file. This is done by adding the following line to your Cron (refer to the [resources](http://openaps.readthedocs.io/en/latest/docs/Resources/index.html) section for help on editing crontabs): +B. You will also need to start up the SimpleHTTPserver service that is already installed on jubilinux in the location you will place your file. This is done by adding the following line to your Cron (refer to the [resources](<../Resources/technical-resources#linux-shell-terminal>) section for help on editing crontabs): ``` @reboot cd /root/myopenaps/enact && python -m SimpleHTTPServer 1337 diff --git a/docs/docs/Customize-Iterate/optimize-your-settings.md b/docs/docs/Usage and maintenance/optimize-your-settings.md similarity index 60% rename from docs/docs/Customize-Iterate/optimize-your-settings.md rename to docs/docs/Usage and maintenance/optimize-your-settings.md index 60492c4c3..b4355c4c2 100644 --- a/docs/docs/Customize-Iterate/optimize-your-settings.md +++ b/docs/docs/Usage and maintenance/optimize-your-settings.md @@ -1,20 +1,24 @@ # Optimizing your settings -Once you've been looping, you may look at your graphs and wonder how to achieve different results. It takes some time to do, but optimizing your settings is one of the keys to improving things, once you have basic looping up and running. +Once you've been looping for a while, you may look at your graphs and wonder how to achieve different results. It takes some time to do, but optimizing your settings is one of the keys to improving things, once you have basic looping up and running. Note: if you're not familiar with the approach of optimizing settings, it's very important to understand that you should only change ONE thing at a time, and observe the impact for 2-3 days before choosing to change or modify another setting (unless it's obviously a bad change that makes things worse, in which case you should revert immediately to your previous setting). The human tendency is to turn all the knobs and change everything at once; but if you do so, then you may end up with further sub-optimal settings for the future, and find it hard to get back to a known good state. -Think about this: when many people start looping, they often have too high basal and too low carb ratio or ISF. What this means is they're using basal insulin around mealtimes to compensate for not usually giving the amount of insulin needed for food. When you go on a DIY closed loop and the system begins to help with adjusting insulin for BGs, it can become apparent that settings need to be tweaked. Here are a series of general approaches you can take for optimizing your settings, with example patterns: +When people start looping, they often have too high basal and too low carb ratio or ISF. What this means is they're using basal insulin around mealtimes to compensate for not usually giving the amount of insulin needed for food. When you go on a DIY closed loop and the system begins to help with adjusting insulin for BGs, it can become apparent that settings need to be tweaked. Here are a series of general approaches you can take for optimizing your settings, with example patterns: + +## Using Nightscout reports + +If you are new to using Nightscout, you may want to start using the "reports" (via hamburger menu in top right corner) to view aggregate data and look for trends. ## Using Autotune The most powerful tool at your disposal for adjusting settings is Autotune, which you can run nightly as part of your loop, and which will automatically start adjusting your basals, carb ratio, and ISF based on observed trends. If your pump settings are too far from what autotune thinks is necessary, it won't be able to adjust further without some manual action on your part, so you'll want to review autotune's recommendations periodically and consider adjusting pump settings in the recommended direction. As noted before, it's best to change things gradually, and observe the results before changing additional settings. -In oref0 0.6.0 and beyond, autotune runs every night on your rig automatically. You can `cat-autotune` to view your autotune recommendations log. ([More about Autotune in the docs here](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html).) +In oref0 0.6.0 and beyond, autotune runs every night on your rig automatically. You can `cat-autotune` to view your autotune recommendations log. Learn more about [how autotune works](<../How it works/autotune>) or [how to run it](<../Usage and maintenance/running-autotune>). ## Frequent negative IOB at the same time every day -Negative IOB happens when you are getting less insulin than your normal basal amount. We created [Autotune](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html) to help deal with these situations and to automatically tune your basal rates for any recurring patterns where you need more or less basal. However, if you're not running autotune, and you're observing patterns of negative IOB (for more than a day or two in a row), indicating a trend, you may need to change your settings. Things to test include: +Negative IOB happens when you are getting less insulin than your normal basal amount. We created [Autotune](<../How it works/autotune>) to help deal with these situations and to automatically tune your basal rates for any recurring patterns where you need more or less basal. However, if you're not running autotune, and you're observing patterns of negative IOB (for more than a day or two in a row), indicating a trend, you may need to change your settings. Things to test include: * Adjusting your DIA. In oref0 0.6.0 and beyond, regardless of what is in your pump, it will default to using a DIA of 5. It is also very common for OpenAPS users to have DIA of 6 or 7 set (in `preferences.json`) * Basal rates are too high for the hours preceding the pattern of negative IOB. @@ -28,6 +32,10 @@ First, you should eliminate human behaviors that cause these. Usually, it's thin Human behaviors set aside, if you are still seeing hills and valleys in your BG graphs, consider the following: * ISF may be off, so you may want to raise ISF to make corrections less aggressive. Remember, make small changes (say, 2-5 points for mg/dl, and .5 or less for mmol) and observe over 2-3 days. Before changing ISF or any other setting, check to see what autotune recommends. -* If you're seeing highs followed by lows after meals, CR may need adjusting. One common mistake is to compensate for rapid post-meal rises with a very aggressive (low) CR, which then causes subsequent low BG. One tool for preventing meal spikes include setting an "eating soon" low temp target before and/or right after a meal, to get more insulin started earlier, and then allow OpenAPS to reduce insulin once the temp target expires, to help prevent a post-meal low. Similarly, a small manual "eating soon" bolus up to an hour before a meal, or a larger prebolus right before a fast-carbs meal, can help match insulin timing to carb absorption without increasing the total amount of insulin delivered (and subsequently causing a post-meal low). ([Here are some tips on using temp targets](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/usability-considerations.html#how-can-you-make-adjustments-to-insulin-delivery-while-on-the-go-optimizing-with-temporary-targets), and you can [use IFTTT to make it easy to enter them from your phone or watch or device of choice](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/ifttt-integration.html).) +* If you're seeing highs followed by lows after meals, CR may need adjusting. One common mistake is to compensate for rapid post-meal rises with a very aggressive (low) CR, which then causes subsequent low BG. One tool for preventing meal spikes include setting an "eating soon" low temp target before and/or right after a meal, to get more insulin started earlier, and then allow OpenAPS to reduce insulin once the temp target expires, to help prevent a post-meal low. Similarly, a small manual "eating soon" bolus up to an hour before a meal, or a larger prebolus right before a fast-carbs meal, can help match insulin timing to carb absorption without increasing the total amount of insulin delivered (and subsequently causing a post-meal low). ([Here are some tips on using temp targets](<../Usage and maintenance/usability-considerations#how-can-you-make-adjustments-to-insulin-delivery-while-on-the-go-optimizing-with-temporary-targets>), and you can [use IFTTT to make it easy to enter them from your phone or watch or device of choice](<../Customize-Iterate/ifttt-integration>).) + +## How to change your settings +To make a change to your basal profile, ISF, or CR, change these values on your pump the way you would normally. Assuming Autotune is enabled to run automatically on your rig, changes to your basal profile within the pump during the middle of the day will NOT cause an immediate change to the basal profile the loop is using. You can either wait until 4am when Autotune runs, or force the adjustment to happen by [running Autotune manually in your `myopenaps` directory](<../Usage and maintenance/running-autotune#running-manually-in-your-myopenaps-directory-to-use-recommendations>). When you re-run Autotune, it will use your pump profile as the starting point. +Nightscout will not automatically reflect the updated pump profile or the adjustments made by Autotune! To upload your new profile to Nightscout, [follow these directions](<../While You Wait For Gear/nightscout-setup#how-to-automatically-sync-your-profile-from-autotune>). diff --git a/docs/docs/Customize-Iterate/oref0-runagain.md b/docs/docs/Usage and maintenance/oref0-runagain.md similarity index 81% rename from docs/docs/Customize-Iterate/oref0-runagain.md rename to docs/docs/Usage and maintenance/oref0-runagain.md index 0e9c61995..4680420e4 100644 --- a/docs/docs/Customize-Iterate/oref0-runagain.md +++ b/docs/docs/Usage and maintenance/oref0-runagain.md @@ -10,7 +10,7 @@ To **run again**: `bash ~/myopenaps/oref0-runagain.sh` will run oref0-setup with Don't have a runagain or want to start fresh? `cd && ~/src/oref0/bin/oref0-setup.sh` -Because you're re-running, **remember you will need to also re-do adjustments to your `preferences.json` once you finish re-running setup with either of the methods above. You can do that by `edit-pref`.** +Because you're re-running, **remember you will need to also [re-do adjustments to your `preferences.json`](<../Usage and maintenance/preferences-and-safety-settings>) once you finish re-running setup with either of the methods above. You can do that by `edit-pref`.** Note: The following items are not impacted by re-running the setup script: diff --git a/docs/docs/While You Wait For Gear/preferences-and-safety-settings.md b/docs/docs/Usage and maintenance/preferences-and-safety-settings.md similarity index 97% rename from docs/docs/While You Wait For Gear/preferences-and-safety-settings.md rename to docs/docs/Usage and maintenance/preferences-and-safety-settings.md index 5fcbfc9cd..50c6cb858 100644 --- a/docs/docs/While You Wait For Gear/preferences-and-safety-settings.md +++ b/docs/docs/Usage and maintenance/preferences-and-safety-settings.md @@ -171,7 +171,7 @@ grams of carbsReq to trigger a pushover. Defaults to 1 (for 1 gram of carbohydra #### curve: "rapid-acting" -Rapid-acting is the default in 0.6.0 and beyond. You can change this to "ultra-rapid" for Fiasp ([see here for other tips on switching to Fiasp](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/usability-considerations.html#how-do-i-switch-between-insulin-types-or-switch-to-fiasp-what-should-i-change)), or "bilinear" for using the old curve. Most people prefer the rapid-acting curve over bilinear for Humalog/Novolog. [Read more here to understand the differences in the activity curves](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/understanding-insulin-on-board-calculations.html#understanding-the-new-iob-curves-based-on-exponential-activity-curves). +Rapid-acting is the default in 0.6.0 and beyond. You can change this to "ultra-rapid" for Fiasp ([see here for other tips on switching to Fiasp](<../Usage and maintenance/usability-considerations#how-do-i-switch-between-insulin-types-or-switch-to-fiasp-what-should-i-change>)), or "bilinear" for using the old curve. Most people prefer the rapid-acting curve over bilinear for Humalog/Novolog. [Read more here to understand the differences in the activity curves](<../How it works/understanding-insulin-on-board-calculations#understanding-the-new-iob-curves-based-on-exponential-activity-curves>). #### useCustomPeakTime @@ -184,7 +184,7 @@ Defaults to 55m for Fiasp if `useCustomPeakTime: false` ## oref1-related preferences: -These preference should **not** be enabled until you've been looping (and running autotune) for several weeks and are confident that all of your basals and ratios are correct. Please read the [oref1 section of the docs](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/oref1.html) before doing so. +These preference should **not** be enabled until you've been looping (and running autotune) for several weeks and are confident that all of your basals and ratios are correct. Please read the [oref1 section of the docs](<../Customize-Iterate/oref1>) before doing so. #### enableSMB_with_COB @@ -330,7 +330,7 @@ Default hotspot network name is the rig name; default password is "#OpenAPS" (no Defaults to false, which means by default only the low end of the pump's BG target range is used as OpenAPS target. This is a safety feature to prevent too-wide targets and less-optimal outcomes. Therefore the higher end of the target range is used only for avoiding bolus wizard overcorrections. Use `wide_bg_target_range: true` to force neutral temps over a wider range of eventualBGs. -**SAFETY WARNING:** If the pump has a target range high end set lower than the BG input into the Bolus Wizard, the Bolus Wizard will add insulin to cover the carbs as well as bring BG down to the high end. I.e. if your high end is 110 and you enter a 160 BG and 45g of carbs in the Bolus Wizard, the Bolus Wizard will dose 1U to bring BG to 110 and 3U for carbs (assuming 50 (mg/dL)/U and 15g/U factors). The rig will likely have already dosed insulin to bring your BG to your low target, and you are potentially "double dosing". In these scenarios, you will have too much insulin onboard and can experience a severe low. If you use the Boluz Wizard, ensure the high end of the BG target range is a high number such as 250 mg/dL. +**SAFETY WARNING:** If the pump has a target range high end set lower than the BG input into the Bolus Wizard, the Bolus Wizard will add insulin to cover the carbs as well as bring BG down to the high end. E.g. if your high end is 110 and you enter a 160 BG and 45g of carbs in the Bolus Wizard, the Bolus Wizard will dose 1U to bring BG to 110 and 3U for carbs (assuming 50 (mg/dL)/U and 15g/U factors). The rig will likely have already dosed insulin to bring your BG to your low target, and you are potentially "double dosing". In these scenarios, you will have too much insulin onboard and can experience a severe low. If you use the Boluz Wizard, ensure the high end of the BG target range is a high number such as 250 mg/dL. #### A52_risk_enable (A52 risk mitigation) diff --git a/docs/docs/Customize-Iterate/autotune.md b/docs/docs/Usage and maintenance/running-autotune.md similarity index 74% rename from docs/docs/Customize-Iterate/autotune.md rename to docs/docs/Usage and maintenance/running-autotune.md index e3d209c08..fbba8ce8a 100644 --- a/docs/docs/Customize-Iterate/autotune.md +++ b/docs/docs/Usage and maintenance/running-autotune.md @@ -1,18 +1,15 @@ -# Autotune +# Running Autotune -Autotune is a tool to help calculate potential adjustments to ISF, carb ratio, and basal rates. +There are several ways to run Autotune, depending on whether you are looping and whether you want to use the results automatically. -## The easiest way to run Autotune +## AutotuneWeb: the easiest way to run Autotune -The easiest way to run Autotune, if you don't have an OpenAPS rig, is to use "AutotuneWeb". It's a website where you enter your Nightscout URL, confirm your profile, and get results emailed directly to you. [Click here to go use AutotuneWeb](https://autotuneweb.azurewebsites.net/). +The easiest way to run Autotune, if you don't have an OpenAPS rig, is to use "AutotuneWeb". It's a website where you enter your Nightscout URL, confirm your profile, and get results emailed directly to you. [Click here to go use AutotuneWeb](https://autotuneweb.azurewebsites.net/). This is recommended and easiest for non-OpenAPS users. ![Example screenshot from AutotuneWeb](../Images/Example_AutotuneWeb.png) ### What to expect when using AutotuneWeb -
- Click here to expand and see more images from AutouneWeb -
After you check your Nightscout profile to make sure it's up to date, and submit your URL, it will take you to the profile page. You should check again and make sure it's pulling from a current profile. This is where you can tell it what type of insulin you're using; how many days to run (up to 30, we recommend at least 7 to start); and provide your email address to get the results emailed to you. * *(Also note that if you want to use the generated files and run Autotune yourself over a longer time frame or with more customized options, you can grab the generated profile files here.)* @@ -34,83 +31,27 @@ Below the ISF and carb ratio, you'll see the basal report. ![Example red/yellow results from AutotuneWeb](../Images/AutotuneWeb_Results_RedYellow.png) -
- ### If it's your first time using AutotuneWeb: 1. Make sure your Nightscout profile is up to date. This is where the "starting" settings are pulled from. -2. If you've not read about Autotune, please see below to get an understanding of [how Autotune works](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html#how-autotune-works) and how you might use the results. -3. Want to run over a different time frame? Keep in mind you can also get a profile generated from AutotuneWeb and then [follow the manual instructions below for running Autotune on your own computer](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html#phase-c-running-autotune-for-suggested-adjustments-without-an-openaps-rig). +2. If you've not read about Autotune, please see below to get an understanding of [how Autotune works](<../How it works/autotune#how-autotune-works>) and how you might use the results. +3. Want to run over a different time frame? Keep in mind you can also get a profile generated from AutotuneWeb and then [follow the manual instructions below for running Autotune on your own computer](<#running-autotune-for-suggested-adjustments-without-an-openaps-rig>). 4. Make sure to check out the [privacy policy for AutotuneWeb](https://autotuneweb.azurewebsites.net/Home/Privacy), which includes directions for requesting your data to be deleted. -5. Results don't look like what you expected to see? [See here for some suggestions](https://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html#why-isn-t-it-working-at-all) that might contribute to flukey data. - -## Other sections on this page +5. Results don't look like what you expected to see? [See here for some suggestions](<#why-isn-t-it-working-at-all>) that might contribute to flukey data. -* Background in plain language on [how Autotune works](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html#how-autotune-works) -* The [difference between Autotune and "autosens"](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html#the-difference-between-autotune-and-autosens) (aka, [autosensitivity](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autosens.html)) -* Different ways to use Autotune - * Run it with [AutotuneWeb](https://autotuneweb.azurewebsites.net/) - * [Phase A](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html#phase-a-running-autotune-manually-in-openaps) - running it on the OpenAPS rig, but not using it to automatically update your rig's settings - * [Phase B](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html#phase-a-running-autotune-manually-in-openaps) - running it on the OpenAPS rig automatically overnight, and OpenAPS will use these settings (**DEFAULT OPENAPS BEHAVIOR**) - * [Phase C](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html#phase-c-running-autotune-for-suggested-adjustments-without-an-openaps-rig) - Those who are not running autotune on an OpenAPS rig should use Phase C to run it on the computer of their choice. - -## How Autotune works - -There are two key pieces: oref0-autotune-prep and oref0-autotune-core. (For more autotune code, you can see [oref0-autotune-(multiple files) listed in oref0/bin here](https://github.com/openaps/oref0/tree/dev/bin) - and there are also some autotune files in [oref0/lib](https://github.com/openaps/oref0/tree/dev/lib). - -
- 1. oref0-autotune-prep: (click to expand) -
- -* autotune-prep takes three things initially: glucose data; treatments data; and starting profile (originally from pump; afterwards autotune will set a profile) -* It calculates BGI and deviation for each glucose value based on treatments -* Then, it categorizes each glucose value as attributable to either carb sensitivity factor (CSF), ISF, or basals -* To determine if a "datum" is attributable to CSF, carbs on board (COB) are calculated and decayed over time based on observed BGI deviations, using the same algorithm used by Advanced Meal Assist. Glucose values after carb entry are attributed to CSF until COB = 0 and BGI deviation <= 0. Subsequent data is attributed as ISF or basals. -* If BGI is positive (meaning insulin activity is negative), BGI is smaller than 1/4 of basal BGI, or average delta is positive, that data is attributed to basals. -* Otherwise, the data is attributed to ISF. -* All this data is output to a single file with 3 sections: ISF, CSF, and basals. -
- -
- 2. oref0-autotune-core: (click to expand) -
- -* autotune-core reads the prepped glucose file with 3 sections. It calculates what adjustments should be made to ISF, CSF, and basals accordingly. -* For basals, it divides the day into hour long increments. It calculates the total deviations for that hour increment and calculates what change in basal would be required to adjust those deviations to 0. It then applies 20% of that change needed to the three hours prior (because of insulin impact time). If increasing basal, it increases each of the 3 hour increments by the same amount. If decreasing basal, it does so proportionally, so the biggest basal is reduced the most. -* For ISF, it calculates the 50th percentile (median) deviation for the entire day and determines how much ISF would need to change to get that deviation to 0. It applies 10% of that as an adjustment to ISF. -* For CSF, it calculates the total deviations over all of the day's mealtimes and compares to the deviations that are expected based on existing CSF and the known amount of carbs entered, and applies 10% of that adjustment to CSF. -* Autotune limits how far it can adjust (or recommend adjustment, if running autotune outside oref0 closed loop) basal, or ISF or CSF, from what is in the existing pump profile. Autotune uses the same autosens_max and autosens_min multipliers found in your preferences.json for oref0. So if autotune is running as part of your loop, autotune can't get too far off without a chance for a human to review the changes. -
- - - *Note: Autotune does not read from the active profile (e.g. Pattern A or Pattern B if set). The Standard Basal Pattern is what will be pulled to be used and tuned by Autotune.* - -## The difference between autotune and autosens: - -Autosensitivity/resistance mode (aka “autosens”) is an advanced feature in OpenAPS that you can enable that looks at 24 hours of data and makes adjustments to ISF and targets based on the resulting sensitivity calculations. If you have a dying pump site, or have been sick and are resistant, your ISF is likely to be calculated down by autosens and then used in OpenAPS calculations accordingly. The opposite for being more sensitive is true as well. [(Here’s a blog post describing autosensitivity during sick days.)](https://diyps.org/2016/12/01/sick-days-with-a-diy-closed-loop-openaps/) - -Autotune, by contrast, is designed to iteratively adjust basals, ISF, and carb ratio over the course of weeks. Because it makes changes more slowly than autosens, autotune ends up drawing on a larger pool of data, and is therefore able to differentiate whether and how basals and/or ISF need to be adjusted, and also whether carb ratio needs to be changed. Whereas we don’t recommend changing basals or ISF based on the output of autosens (because it’s only looking at 24h of data, and can't tell apart the effects of basals vs. the effect of ISF), autotune is intended to be used to help guide basal, ISF, *and* carb ratio changes because it’s tracking trends over a large period of time. See below for how it can be used as a manual one-off calculation or in a closed loop setting, along with notes about the safety caps designed to go with it. - -### Different ways to utilize Autotune - -* (Recommended & easiest for non-OpenAPS users) Run it with [AutotuneWeb](https://autotuneweb.azurewebsites.net/) -* Phase A - run autotune as a one-off on an OpenAPS rig (aka, manually) -* Phase B - run autotune nightly in an OpenAPS rig (**DEFAULT OPENAPS BEHAVIOR**) -* Phase C - run autotune as a "one-off" on a computer of your choice. - -#### Phase A: Running Autotune manually in OpenAPS +## Running Autotune manually in OpenAPS If you have an OpenAPS rig and want to run autotune manually, you can do so on the command line. +### Running manually in your myopenaps directory to use recommendations -##### Running manually in your myopenaps directory If you want to have OpenAPS use your autotune results (e.g. you changed pump settings and just want it to be tuned sooner than 4am), run the following: ``` oref0-autotune --dir=~/myopenaps --ns-host=https://mynightscout.herokuapp.com --start-date=YYYY-MM-DD ``` -##### Running manually in a *different* directory to not use the results automatically +### Running manually in a *different* directory to not use the results automatically You will want to run Autotune in a different directory on your rig if you do not want OpenAPS to use the autotune settings by default. @@ -129,17 +70,15 @@ oref0-autotune --dir=~/newdirectory --ns-host=https://mynightscout.azurewebsites **Note:** If you did this correctly in your `newdirectory`, settings will not be used by OpenAPS. You will need to `cd ~/newdirectory/autotune && cat autotune_recommendations.log` to see your autotune recommendations, and autotune will only run when you manually run it. The recommended behavior is to run Autotune inside of your OpenAPS directory, per Phase B, which is the default and will automatically run every night and have OpenAPS use the settings from Autotune automatically. -#### Phase B: Running Autotune automatically in OpenAPS +## Running Autotune automatically in OpenAPS (default OpenAPS behavior) -In oref0 0.6.0 and beyond, autotune will run by default. This means that autotune would be iteratively running (as described in [#261](https://github.com/openaps/oref0/issues/261)) and making changes to the underlying basals, ISF, and carb ratio being used by the loop, making small adjustments from the previously autotuned settings based on each day’s new data. However, there are safety caps (your autosens_max and autosens_min) in place to limit the amount of tuning that can be done at any time compared to the underlying pump profile. The autotune_recommendations will be tracked against the current pump profile, and if over time the tuning constantly recommends changes beyond the caps, you can use this to determine whether to tune the basals and ratios in those directions. +In oref0 0.6.0 and beyond, autotune will run by default. This means that autotune would be iteratively running (as described in [#261](https://github.com/openaps/oref0/issues/261)) and making changes to the underlying basals, ISF, and carb ratio being used by the loop, making small adjustments from the previously autotuned settings based on each day’s new data. However, there are safety caps (your `autosens_max` and `autosens_min`) in place to limit the amount of tuning that can be done at any time compared to the underlying pump profile. The autotune_recommendations will be tracked against the current pump profile, and if over time the tuning constantly recommends changes beyond the caps, you can use this to determine whether to tune the basals and ratios in those directions. -**Important** When autotune is enabled in your loop to run automatically, changes to your basal profile within the pump during the middle of the day will NOT cause an immediate change to the basal profile the loop is using. The loop will continue to use your autotune-generated profile until a new one is updated just after midnight each night. Each autotune nightly run will pull the current pump profile as its baseline for being able to make adjustments. If you have reason to want a want a mid-day change to your basal program immediately, you should run autotune manually (see A for directions) to have it re-pull the settings from the pump and tune from the new settings. +**Important** When autotune is enabled in your loop to run automatically, changes to your basal profile within the pump during the middle of the day will NOT cause an immediate change to the basal profile the loop is using. The loop will continue to use your autotune-generated profile until a new one is updated just after midnight each night. Each autotune nightly run will pull the current pump profile as its baseline for being able to make adjustments. If you have reason to want a want a mid-day change to your basal program immediately, you should run autotune manually (see [directions](<#running-manually-in-your-myopenaps-directory-to-use-recommendations>)) to have it re-pull the settings from the pump and tune from the new settings. -#### How to copy over autotune files from another rig: +### How to copy over autotune files from another rig: -
- If you have multiple rigs and would like to sync up autotune results, or move an existing autotune over to a brand new rig, you'll want to copy files over. (Click to expand these instructions) -
+If you have multiple rigs and would like to sync up autotune results, or move an existing autotune over to a brand new rig, you'll want to copy files over. Log into the NEW rig and run the following command: `scp -r root@my-edison-original.local:~/myopenaps/autotune/ ~/myopenaps/autotune` (where "my-edison-original" is substituted for your rig name that you want to copy files from) @@ -147,30 +86,26 @@ Log into the NEW rig and run the following command: * You'll be asked for your my-edison-original rig's password (where you are copying FROM). * This will copy everything in the autotune directory over. -
-
- -#### Phase C: Running Autotune for suggested adjustments without an OpenAPS rig +## Running Autotune for suggested adjustments without an OpenAPS rig -**Note:*** the easiest way of running Autotune is now "AutotuneWeb". See the top of this page for instructions on running it via the web service, without having to set it up on your own computer. If you do want to manually set up your own computer to be able to run it over a time period >30 days or other reasons, see below. +**Note:** the easiest way of running Autotune is now "AutotuneWeb". See the top of this page for instructions on running it via the web service, without having to set it up on your own computer. If you do want to manually set up your own computer to be able to run it over a time period >30 days or other reasons, see below. *Caution for AndroidAPS users:* Currently, the master oref0 version with Autotune does not parse AndroidAPS entries correctly. **You must set AndroidAPS to upload all temp basals as "absolute" rates, instead of %, *and* use the dev branch of oref0.** If you do not do both of these things, your results will be wrong! Future versions of Autotune will allow using AndroidAPS data as long as the option to upload temp basals as absolute values instead of / in addition to percent is enabled in AndroidAPS. If you are not running autotune as part of a closed loop, you can still run it as a "one-off".(OpenAPS/existing oref0 users may want to use the above instructions instead, however, from phase A or phase B on this page.) For more about autotune, you can read [Dana's autotune blog post for some background/additional detail](http://bit.ly/2jKvzQl) and scroll up in the page to see more details about how autotune works. -**Requirements**: You should have Nightscout BG and treatment data. If you do not regularly enter carbs (meals) into Nightscout (this happens automatically when you use the "Bolus Wizard" on the Medtronic pump and should not be manually added to Nightscout if you use the Bolus Wizard), autotune will try to raise basals at those times of days to compensate. However, you could still look at overnight basal recommendations and probably even ISF recommendations overall. [Read this page for more details on what you should/not pay attention to with missing data.](./understanding-autotune.md) - -**Note**: this is currently based on *one* ISF and carb ratio throughout the day. Here is the [issue](https://github.com/openaps/oref0/issues/326) if you want to keep track of the work to make autotune work with multiple ISF or carb ratios. +**Requirements**: You should have Nightscout BG and treatment data. If you do not regularly enter carbs (meals) into Nightscout (this happens automatically when you use the "Bolus Wizard" on the Medtronic pump and should not be manually added to Nightscout if you use the Bolus Wizard), autotune will try to raise basals at those times of days to compensate. However, you could still look at overnight basal recommendations and probably even ISF recommendations overall. [Read this page for more details on what you should/not pay attention to with missing data.](../How it works/autotune#if-you-are-diy-closed-looping-and-looking-at-autotune>) -**Feedback**: Please note autotune is brand new, and still a work in progress (WIP). Please provide feedback along the way, or after you run it. You can share your thoughts in [Gitter](https://gitter.im/openaps/autotune), or via this short [Google form](https://goo.gl/forms/Cxbkt9H2z05F93Mg2). +### Step 0: Decide where to run Autotune -**Step 0: Decide where to run Autotune** * (Remember you can use [AutotuneWeb](https://autotuneweb.azurewebsites.net/) if you don't want to run it on your computer.) * There are five main ways to run Autotune on your own: via (a) a cloud-based virtual machine (Linux VM through Google Cloud Platform, for example), (b) on via a virtual machine on Windows (e.g., VirtualBox), (c) on a Mac directly, (d) on a Windows 10 computer running the Windows Subsystem for Linux (WSL), or (e) direct on a physical machine running Linux. Instructions for the first four are below. * Whichever route you are using, we recommend some form of Debian distro (Ubuntu is the most common) for consistency with the Raspbian and jubilinux environments used on the Pi and Edison for OpenAPS. - * If you're interacting with your VM via its graphical interface, make sure you have installed a browser at your VM (i.e. Firefox) then open the correct page from your VM. You may think that copying from your Windows/iOS and pasting in your Linux terminal would work but is not as simple ...and yes, there is lots of copying / pasting! To make copying and pasting simpler, it is often better to `ssh` directly to your VM, rather than using its graphical interface (or the cloud provider's console interface). + * If you're interacting with your VM via its graphical interface, make sure you have installed a browser at your VM (e.g. Firefox) then open the correct page from your VM. You may think that copying from your Windows/iOS and pasting in your Linux terminal would work but is not as simple ...and yes, there is lots of copying / pasting! To make copying and pasting simpler, it is often better to `ssh` directly to your VM, rather than using its graphical interface (or the cloud provider's console interface). + +### Step 1: Install dependencies (instructions vary by setup) -**Step 1a: Run via a cloud-based virtual machine** +#### Option A: Run via a cloud-based virtual machine
Click here to expand the instructions for building via a cloud-based virtual machine: @@ -180,7 +115,7 @@ If you are not running autotune as part of a closed loop, you can still run it a * Once signed up to Google Cloud Platform (if you are using that route), click the terminal icon near the top right to activate the cloud shell - a black window will appear at the bottom of the screen. Note that you can easily cut & paste into this terminal without the need to do anything special. * Make sure your VM is using the same timezone as your pump. You can change timezone using `sudo dpkg-reconfigure tzdata` * If your VM is outside the US, particularly in a country that uses `,` as a decimal separator, make sure your system locale is set to `en_US.utf8` or another locale that uses `.` as the decimal separator. If you think this may be incorrect, you can check it by typing `locale`. - * If you're interacting with your VM via its graphical interface, make sure you have installed a browser at your VM (i.e. Firefox) then open the currect page from your VM. You may think that copying from your Windows/iOS and pasting in your Linux terminal would work but is not as simple .. and yes, there is lots of copying / pasting! To make copying and pasting simpler, it is often better to `ssh` directly to your VM, rather than using its graphical interface (or the cloud provider's console interface). + * If you're interacting with your VM via its graphical interface, make sure you have installed a browser at your VM (e.g. Firefox) then open the currect page from your VM. You may think that copying from your Windows/iOS and pasting in your Linux terminal would work but is not as simple .. and yes, there is lots of copying / pasting! To make copying and pasting simpler, it is often better to `ssh` directly to your VM, rather than using its graphical interface (or the cloud provider's console interface). * Now do this: `sudo curl -s https://raw.githubusercontent.com/openaps/docs/master/scripts/quick-packages.sh | bash -`. This will take a minute or so. If the install was successful, the last line will say something like: `Successfully installed openaps-contrib-0.0.15` (although the version number may have been incremented). If you do not see this or see error messages, try running it multiple times. It will not hurt to run this multiple times. * On Google Cloud Shell do: `sudo npm install -g json` * On Google Cloud shell at least, you need to set your NightScout API_SECRET as an environment variable. To do this type `sudo env API_SECRET=xxxxxx` (where xxxxxx is your API_SECRET, either as the string you gave Nightscout, or as `token=xxxxx` which you generated in Nightscout admin interface) followed by `sudo export API_SECRET` @@ -189,7 +124,7 @@ If you are not running autotune as part of a closed loop, you can still run it a

- **Step 1b: Run via a Windows-based virtual machine** +#### Option B: Run via a Windows-based virtual machine
Click here to expand the instructions for building via a Windows-based virtual machine: @@ -202,14 +137,14 @@ If you are not running autotune as part of a closed loop, you can still run it a

-**Step 1c: Prep your Mac** +#### Option C: Run on a Mac
Click here to expand the instructions for building via your Mac:
* MAC USERS: Follow these steps instead of 1a / 1b above if you want to run autotune on your Mac. (Mac users can instead do the above instructions if they prefer to create a Linux virtual machine to run it on): -* To run AutoTune using a Mac you will use the Terminal application. Open the Terminal application on your Mac (it is located in the Utilities application folder on your Mac). For more information about using Terminal see: http://openaps.readthedocs.io/en/latest/docs/Understanding OpenAPS-Overview/overview-of-build-process.html#before-you-get-started +* To run AutoTune using a Mac you will use the Terminal application. Open the Terminal application on your Mac (it is located in the Utilities application folder on your Mac). For more information about using Terminal see [here](<../Understanding OpenAPS-Overview/overview-of-build-process#before-you-get-started>) * After you open a Terminal window, copy and paste the command for each of the Mac install command steps below, and then hit the return key after you paste each command, which will execute it. If you are asked for a password, enter the password for your Mac. * Tip for New Mac Users: If you typically use a Windows machine and you keep trying to do a control-c (copy) and control-v (paste), remember, on a Mac use command-c (copy) and command-v (paste) instead. * For example, the first step is to install Homebrew on your Mac. To do this you need to copy and paste the following command from step 1.) of the Mac install commands below and then hit the return key: `/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"` @@ -224,7 +159,7 @@ Mac install commands:

- **Step 1d: Run on a Windows 10 computer using the Windows Subsystem for Linux (WSL)** +#### Option D: Run on a Windows 10 computer using the Windows Subsystem for Linux (WSL)
Click here to expand the instructions for building via a Windows 10 computer using the Windows Subsystem for Linux (WSL): @@ -246,7 +181,8 @@ Mac install commands:

-**Step 2: Install oref0** +### Step 2: Install oref0 + * Install the latest version of oref0: ``` @@ -260,7 +196,7 @@ cd ~/src && git clone -b dev git://github.com/openaps/oref0.git || (cd oref0 && cd ~/src/oref0 && npm run global-install ``` -**Step 3: Create a profile.json with your settings** +### Step 3: Create a profile.json with your settings * A. Create a myopenaps and settings directory. `mkdir -p ~/myopenaps/settings` * B. Change into that directory: `cd ~/myopenaps/settings`. * C. Create a profile file by typing `nano profile.json`. Copy and paste the example below, but input your information from your pump. Change the basal profile times to match yours (update the minutes to match your basal start time; the minutes are number of minutes from midnight to the start of basal, e.g., a basal starting at 5:00am will have a minutes entry of 5 x 60 = 300 minutes and a basal starting at 7:30am will have a minutes entry of 7.5 x 60 = 450 minutes), and add more entries if needed. It's very common for first-time users to have problems that result from mistakes introduced into this file. Some common ones to check: @@ -326,7 +262,7 @@ Every comma, quote mark, and bracket matter on this file, so please double-check * E. Create a pumpprofile.json that is the same as your profile.json. On the command line run: `cp profile.json pumpprofile.json` * F. Create a third file from the command line by running: `cp profile.json autotune.json` -**Step 4: Run autotune on retrospective data from Nightscout** +### Step 4: Run autotune on retrospective data from Nightscout * Run ``` oref0-autotune --dir=~/myopenaps --ns-host=https://mynightscout.herokuapp.com --start-date=YYYY-MM-DD @@ -337,7 +273,7 @@ oref0-autotune --dir=~/myopenaps --ns-host=https://mynightscout.herokuapp.com -- * Remember, this is currently based on *one* ISF and carb ratio throughout the day at the moment. Here is the [issue](https://github.com/openaps/oref0/issues/326) if you want to keep track of the work to make autotune work with multiple ISF or carb ratios. * If useCustomPeak is not set in preferences.json and --tune-insulin-curve=true is not used, the DIA used by autotune is obtained from the pump and the peak time is obtained from the defaults of the insulin curve selected in preferences.json. -**Step 5: Upload resulting profile to Nightscout** +### Step 5: Upload resulting profile to Nightscout * Run ``` oref0-upload-profile ./myopenaps/autotune/profile.json $NS_SITE $API_SECRET @@ -346,7 +282,7 @@ oref0-upload-profile ./myopenaps/autotune/profile.json $NS_SITE $API_SECRET * Upload may fail if the profile doesn't have settings that OpenAPS or Nightscout deem required for a profile to have. Unfortunately, the messages about this are somewhat cryptic. * This will make a copy of all the profiles you currently have, and upload the generated one, naming it `OpenAPS Autosync` -**Step 5a: Upload resulting profile to Nightscout and switch to it** +### Alternate Step 5A: Upload resulting profile to Nightscout and switch to it * Run ``` oref0-upload-profile --switch ./myopenaps/autotune/profile.json $NS_SITE $API_SECRET @@ -354,16 +290,17 @@ oref0-upload-profile --switch ./myopenaps/autotune/profile.json $NS_SITE $API_SE * ^ Replace `$NS_SITE` with address to your Nightscout, and `$API_SECRET` with your API secret or token * In addition to uploading the profile like described above, it will issue a `Profile Switch` event, as [described in AndroidAPS documentation](https://androidaps.readthedocs.io/en/latest/EN/Usage/Profiles.html). This will make AndroidAPS automatically pick up the new profile and switch to it, also *resetting autosens*. Keep this in mind, since, as [diabettech writes](https://www.diabettech.com/artificial-pancreas/automating-hypo-hyper-temp-targets-a-quick-hack/) *Frequent profile switches will stop Autosens from working properly*. -#### Optional configurations +### Optional configurations +>>>>>>> general-cleanup:docs/docs/Usage and maintenance/running-autotune.md * For most people, autotune's UAM detection does a good job of excluding anomalous data from unannounced or imprecisely estimated carbs, stress spikes, etc., and is able to properly tune basals using the non-excluded data. In rare cases, some people's basal settings are so far below their real basal rates when starting out with autotune that they find the algorithm unable to suggest raising basals because it is classifying all periods when basals are too low as unannounced meals. If you notice this issue, you are certain you have precisely entered carb counts for all carb intake events, and you want autotune to raise basal for abrupt BG rises due to stress etc., then you can force the algorithm to classify unannounced meal periods as basal periods using the --categorize-uam-as-basal=true option. Most people should not need this option, and it should only be used with care. **\*\*SAFETY WARNING\*\*** If you use this option and treat lows without entering the low treatment carbs, an amplifying cycle will begin with autotune raising basals, treated lows get categorizes as basals being too low, basals are raised causing lows, etc. * If running 0.7.0 or later, autotune has a --tune-insulin-curve=true option that enables autotune to tune the insulin end time (DIA) and insulin peak. The values listed below are calculated for insulin end times 2 hours less than the current end time to 2 hours more. If they agree in moving the insulin end time in the same direction, the insulin end time is moved by 1 hour. Insulin peak time is tuned similarly in steps of 5 minutes for peak times 10 minutes less than the current peak time to 10 minutes more than the current peak time. **\*\*SAFETY WARNING\*\*** This tuning method is still very much experimental and not recommended to be run unattended. * Average deviations observed in the data * Square root of the average of the squared deviations -#### Re-Running Autotune +### Re-Running Autotune -Remember, to initially set-up Autotune follow the instructions [above](https://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html#phase-c-running-autotune-for-suggested-adjustments-without-an-openaps-rig) +Remember, to initially set-up Autotune follow the instructions [above](<../How it works/autotune#phase-c-running-autotune-for-suggested-adjustments-without-an-openaps-rig>) To subsequently re-run Autotune at a later time: * Open Ubuntu/your machine of choice and login if necessary @@ -379,7 +316,7 @@ To subsequently re-run Autotune at a later time: * `cp profile.json autotune.json` * Then to re-run Autotune, subbing in your URL: `oref0-autotune --dir=~/myopenaps --ns-host=https://mynightscout.herokuapp.com --start-date=YYYY-MM-DD` -#### Why Isn't It Working At All? +### Why Isn't It Working At All? (First - breathe, and have patience!) Here are some things to check: @@ -398,7 +335,7 @@ To test this fix, type `echo $API_SECRET` and hit enter. If this returns the AP Other things to check: * If you see error like `TypeError: opts.glucose.map is not a function` check that you have `API_SECRET` in the right format, [as described in this issue](https://github.com/openaps/oref0/issues/397). You either need `API_SECRET=xxxx` where `xxxx` is the string you gave Nightscout, or `API_SECRET=token=xxxxx` where `xxxxx` is the token you generated in Nightscout admin interface. -* Does your Nightscout have data? It definitely needs BG data, but you may also get odd results if you do not have treatment (carb, bolus) data logged. See [this page](./understanding-autotune.md) with what output you should get and pay attention to depending on data input. +* Does your Nightscout have data? It definitely needs BG data, but you may also get odd results if you do not have treatment (carb, bolus) data logged. See [this page](<./understanding-autotune>) with what output you should get and pay attention to depending on data input. * Did you pull too much data? Start with one day, and make sure it's a day where you had data in Nightscout. Work your way up to 1 week or 1 month of data. If you run into errors on a longer data pull, there may be something funky in Nightscout that's messing up the data format file and you'll want to exclude that date by picking a batch that does not include that particular date. * Make sure when you sub in your Nightscout URL you do not include a "/" at the end of the URL * Check your profile.json and make sure it really matches the example - chances are there's a stray character in there. @@ -423,13 +360,11 @@ Other things to check: * If you are using [NightScoutLoader](https://github.com/gh-davidr/NightscoutLoader) to load the Diasend data to your Nightscout site, ensure the Diasend xls date format is the same as the date format selected in the NightScoutLoader Settings. For USA users, the Diasend xls date format is "mm/yy/yyyy HH:mm" format which isn't supported by NightScoutLoader at this time. The NightScoutLoader app currently only supports {"Default", "dd/MM/yy hh:mm", "MM/dd/yy hh:mm", "dd/MM/yy", "MM/dd/yy"] formats. "Default" corresponds to your OS date format for the English locale. If none of these formats correspond to your Diasend xls data, as a workaround until NightScoutLoader is remedied, either set your system default date format to correspond to Diasend's date format or change the date format in the Diasend xls data file for all Times and Dates to correspond to NightScoutLoader Settings. For example, the tabs "Name and glucose", "CGM", "Insulin use and carbs", and "Alarms and events" all have date and time data. * Still not working? Post a question in [Gitter](https://gitter.im/openaps/autotune). To best help you troubleshoot: Specify if you're on MDI or using a pump. Specify if you're using xDrip as a data source, or if you are otherwise logging data into Nightscout in a way that's not through Care Portal app directly, etc. -#### What does this output from autotune mean? -Go here to read more about [understanding the output, to see an example visual of what the output might look like, and scenarios when you may want to disregard portions of the output based on the data you provide it](./understanding-autotune.md). +## What does this output from autotune mean? -Remember, autotune is still a work in progress (WIP). Please provide feedback along the way, or after you run it. You can share your thoughts in [Gitter](https://gitter.im/openaps/autotune), or via this short [Google form](https://goo.gl/forms/Cxbkt9H2z05F93Mg2). +Go here to read more about [understanding the output, to see an example visual of what the output might look like, and scenarios when you may want to disregard portions of the output based on the data you provide it](<../How it works/autotune>). -(If you have issues running it, questions about reviewing the data, or want to provide input for direction of the feature, please comment on [this issue in Github](https://github.com/openaps/oref0/issues/261).) +## Feedback, issues, and contributing -#### Yay, It Worked! This is Cool! +Please note autotune is still a work in progress (WIP)! We'd love to hear if it worked well, plus any additional feedback - please also provide input via this short [Google form](https://goo.gl/forms/Cxbkt9H2z05F93Mg2) and/or comment on [this issue in Github](https://github.com/openaps/oref0/issues/261) for more detailed feedback about the tool. You can also join the discussion in [Gitter](https://gitter.im/openaps/autotune). -Great! We'd love to hear if it worked well, plus any additional feedback - please also provide input via this short [Google form](https://goo.gl/forms/Cxbkt9H2z05F93Mg2) and/or comment on [this issue in Github](https://github.com/openaps/oref0/issues/261) for more detailed feedback about the tool. You can also help us tackle some of the known issues and feature requests listed [here](./understanding-autotune.md). diff --git a/docs/docs/Customize-Iterate/update-your-rig.md b/docs/docs/Usage and maintenance/update-your-rig.md similarity index 84% rename from docs/docs/Customize-Iterate/update-your-rig.md rename to docs/docs/Usage and maintenance/update-your-rig.md index b104135a5..e16fcd9c8 100644 --- a/docs/docs/Customize-Iterate/update-your-rig.md +++ b/docs/docs/Usage and maintenance/update-your-rig.md @@ -1,6 +1,6 @@ # How to update oref0 on your OpenAPS rig in the future -You've probably heard about all kinds of cool new features that you want to try. If they're part of the master branch already, you just need to go enable them (usually by [re-running the oref0-setup script](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/oref0-runagain.html)). You can see notes about what is included in a particular release in [the release notes page for oref0](https://github.com/openaps/oref0/releases). +You've probably heard about all kinds of cool new features that you want to try. If they're part of the master branch already, you just need to go enable them (usually by [re-running the oref0-setup script](<../Usage and maintenance/oref0-runagain>)). You can see notes about what is included in a particular release in [the release notes page for oref0](https://github.com/openaps/oref0/releases). However, if it's a brand-new feature that's being tested or is recently added to master, you'll need to install the new version of `oref0` first. By the way, if you want to check which version of oref0 you are currently running, `npm list -g oref0` and if you want to check which branch `cd ~/src/oref0` and then `git branch`. @@ -46,11 +46,11 @@ In case you want to test even more advanced stuff you've read about on gitter ch ## Step 2: Re-run oref0-setup -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. +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](<../Build Your Rig/step-3-setup-script#be-prepared-to-enter-the-following-information-into-oref0-setup>) for a guide of what the setup script will be prompting you to enter. ## Step 3: Remember to set your preferences! -Reminder! You'll need to re-set your preferences in `preferences.json`. See [the preferences page](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/preferences-and-safety-settings.html) to see what preferences might have changed or become available since your last update. +Reminder! You'll need to re-set your preferences in `preferences.json`. See [the preferences page](<../Usage and maintenance/preferences-and-safety-settings>) to see what preferences might have changed or become available since your last update. To edit any of your preferences, you can enter `edit-pref` (as a shortcut) or `cd ~/myopenaps && nano preferences.json` diff --git a/docs/docs/Customize-Iterate/usability-considerations.md b/docs/docs/Usage and maintenance/usability-considerations.md similarity index 74% rename from docs/docs/Customize-Iterate/usability-considerations.md rename to docs/docs/Usage and maintenance/usability-considerations.md index 7fde5af38..cce3bb769 100644 --- a/docs/docs/Customize-Iterate/usability-considerations.md +++ b/docs/docs/Usage and maintenance/usability-considerations.md @@ -1,37 +1,24 @@ -# Usability Considerations +# Using your loop: practical advice for common situations -Now that you've closed the loop, you probably have a lot of new "first" experiences to deal with. Like much of this looping experience, you'll figure it out as you go along, and figure out what's right for you. But here are some ideas or tips to consider: +Now that you've closed the loop, you probably have a lot of new "first" experiences to deal with. Like much of this looping experience, you'll figure it out as you go along, and figure out what's right for you. But here are some common situations and questions you may encounter: -
- Click here to expand a clickable list to see all tips on this page: - -- [How do I enter carbs and boluses so OpenAPS can use them?](#how-do-i-enter-carbs-and-boluses-so-openaps-can-use-them-) +- [How can you make adjustments to insulin delivery while on the go? - Optimizing with Temporary Targets](#how-can-you-make-adjustments-to-insulin-delivery-while-on-the-go-optimizing-with-temporary-targets) - [What do you do with the loop in airport security when you travel](#what-do-you-do-with-the-loop-in-airport-security-when-you-travel) -- [What do you do with your loop when you travel across timezones? How do you update devices for a time zone change?](#what-do-you-do-with-your-loop-when-you-travel-across-timezones--how-do-you-update-devices-for-a-time-zone-change-) -- [What do you do with the loop when you shower?](#what-do-you-do-with-the-loop-when-you-shower-) +- [What do you do with your loop when you travel across timezones? How do you update devices for a time zone change?](#what-do-you-do-with-your-loop-when-you-travel-across-timezones-how-do-you-update-devices-for-a-time-zone-change) +- [What do you do with the loop when you shower?](#what-do-you-do-with-the-loop-when-you-shower) - [What do you do when you change sites?](#what-do-you-do-when-you-change-sites-) -- [What do you do when you exercise?](#what-do-you-do-when-you-exercise-) -- [What do you do if you want to be off the pump for long periods during a day when you're really active? Like for the beach or water park or sporting activity or similar?](#what-do-you-do-if-you-want-to-be-off-the-pump-for-long-periods-during-a-day-when-you-re-really-active---like-for-the-beach-or-water-park-or-sporting-activity-or-similar-) -- [What if I want to turn off the loop for a while?](#what-if-i-want-to-turn-off-the-loop-for-a-while-) -- [How do I open loop?](#how-do-i-open-loop-) -- [How can you make adjustments to insulin delivery while on the go? - Optimizing with Temporary Targets:](#how-can-you-make-adjustments-to-insulin-delivery-while-on-the-go----optimizing-with-temporary-targets-) -- [How do I improve the range of my Edison/Explorer Board?](#how-do-i-improve-the-range-of-my-edison-explorer-board-) -- [How do I switch between insulin types, or switch to Fiasp? What should I change?](#how-do-i-switch-between-insulin-types--or-switch-to-fiasp--what-should-i-change-) - [How do I switch to a different Medtronic pump?](#how-do-i-switch-to-a-different-medtronic-pump-) -- [Improving the battery life of your Raspberry Pi](#improving-the-battery-life-of-your-raspberry-pi) +- [What do you do when you exercise?](#what-do-you-do-when-you-exercise) +- [What do you do if you want to be off the pump for long periods during a day when you're really active? Like for the beach or water park or sporting activity or similar?](#what-do-you-do-if-you-want-to-be-off-the-pump-for-long-periods-during-a-day-when-you-re-really-active-like-for-the-beach-or-water-park-or-sporting-activity-or-similar) +- [What if I want to turn off the loop for a while?](#what-if-i-want-to-turn-off-the-loop-for-a-while) +- [How do I open loop?](#how-do-i-open-loop) +- [How do I switch between insulin types, or switch to Fiasp? What should I change?](#how-do-i-switch-between-insulin-types-or-switch-to-fiasp-what-should-i-change) -
+## How can you make adjustments to insulin delivery while on the go? - Optimizing with Temporary Targets -## How do I enter carbs and boluses so OpenAPS can use them? -Boluses always have to be set on the pump for OpenAPS to take them into consideration. Carbs can be either entered in any of several ways:
-- on the pump (for example, using Bolus Wizard), -- into the Nightscout UI (using the Care Portal), -- via an HTTPS POST to the treatments API, for example using the iOS Shortcuts app, -- via [IFTTT](./ifttt-integration.html?highlight=IFTTT), -- via [xDrip](https://github.com/NightscoutFoundation/xDrip), -- via [CarbDialer (iOS App)](https://apps.apple.com/us/app/carbdialer/id1315809661). +The use of Temporary Targets can provide additional fine tuning of insulin control on the go, or remotely for parents monitoring children when they are at school or away from home. As described elsewhere in this documentation, an Eating Soon-type (lower than normal) Temporary Target can be used in advance of a meal or activity. Lower Temporary Targets can also be used to force the OpenAPS system to be somewhat more aggressive in correcting a rising blood sugar. Similarly, a higher temporary target can soften a blood sugar drop and help avoid a low, or help limit stacking of insulin that is likely to peak during activity. Temp targets can be set by entering them in Nightscout Care Portal; you can also set up IFTTT buttons to set common temp targets from your watch or phone with a single button. -**SAFETY WARNING:** If the pump has a target range high end set lower than the BG input into the Bolus Wizard, the Bolus Wizard will add insulin to cover the carbs as well as bring BG down to the high end. I.e. if your high end is 110 and you enter a 160 BG and 45g of carbs in the Bolus Wizard, the Bolus Wizard will dose 1U to bring BG to 110 and 3U for carbs (assuming 50 (mg/dL)/U and 15g/U factors). The rig will likely have already dosed insulin to bring your BG to your low target, and you are potentially "double dosing". In these scenarios, you will have too much insulin onboard and can experience a severe low. If you use the Boluz Wizard, ensure the high end of the BG target range is a high number such as 250 mg/dL. OpenAPS default behavior (`wide_bg_target_range` preference) is to only use the target range lower end. Setting the high end does not impact the OpenAPS algorithms. +Temporary Targets can be set in advance by setting a future date/time stamp in Nightscout when you set them. For example, a parent may wish to set a week's worth of Eating Soon or Activity Modes in advance of a regular school week. This may be particularly helpful for meals or activity (e.g. gym class) which are regularly scheduled but for which you may have difficulty remembering to trigger the Temporary Target at the right time. Scheduled or remotely activated Temporary Targets can also be very useful in supporting children in optimal management at school or other locations where there may not be an adult who is in a position to set the Temporary Target each time it is needed. It's also helpful even for adult PWDs when traveling; a loved one at home in a different time zone can set temp targets as needed to help direct the rig's activity while the PWD might be asleep or otherwise occupied.
## What do you do with the loop in airport security when you travel The loop is off the shelf hardware - it's no different than your phone or other small gadgets, so leave it in your carry-on bag when going through security. (Dana note: I have traveled [well](https://twitter.com/danamlewis/status/811682733445496833) over 100 times with my loop, and in some cases with 3-4 Pis and batteries and related accessories, and have never had issues going through security because of my loop.) @@ -96,26 +83,9 @@ The easiest way to "open loop" is to set the temp basal type on your pump to be You can then watch the OpenAPS pill in Nightscout, or your logs (`l`) on the rig to see what OpenAPS would be doing. -## How can you make adjustments to insulin delivery while on the go? - Optimizing with Temporary Targets: -The use of Temporary Targets can provide additional fine tuning of insulin control on the go, or remotely for parents monitoring children when they are at school or away from home. As described elsewhere in this documentation, an Eating Soon-type (lower than normal) Temporary Target can be used in advance of a meal or activity. Lower Temporary Targets can also be used to force the OpenAPS system to be somewhat more aggressive in correcting a rising blood sugar. Similarly, a higher temporary target can soften a blood sugar drop and help avoid a low, or help limit stacking of insulin that is likely to peak during activity. Temp targets can be set a number of ways, from using IFTTT so you can set them easily from your watch or phone; or by entering them in Nightscout Care Portal. - -Temporary Targets can be set in advance by setting a future date/time stamp in Nightscout when you set them. For example, a parent may wish to set a week's worth of Eating Soon or Activity Modes in advance of a regular school week. This may be particularly helpful for meals or activity (i.e. gym class) which are regularly scheduled but for which you may have difficulty remembering to trigger the Temporary Target at the right time. Scheduled or remotely activated Temporary Targets can also be very useful in supporting children in optimal management at school or other locations where there may not be an adult who is in a position to set the Temporary Target each time it is needed. It's also helpful even for adult PWDs when traveling; a loved one at home in a different time zone can set temp targets as needed to help direct the rig's activity while the PWD might be asleep or otherwise occupied.
- -## How do I improve the range of my Edison/Explorer Board? - -There are two options for improving the range of an Explorer Board. The easiest way is to purchase a "wire whip" antenna to add to your rig. [Here is one available at Mouser (915MHz only)](https://www.mouser.com/ProductDetail/620-66089-0930?R=66089-0930virtualkey65480000virtualkey620-66089-0930) or for 866/868 MHz [also availabe at Mouser](https://www.mouser.at/ProductDetail/Anaren/66089-0830?qs=pH7abCSN9NPb5X5zwyxl2w==). You can buy one [at Enhanced Radio Devices](https://www.enhancedradio.com/collections/all) as well, you may consider ordering it with your Explorer Board. It physically clips on to your rig. The picture below shows the antenna clipped on and extended from the board; but you can experiment with wrapping the antenna around your rig to fit in your preferred case to see various impacts to the range. - -![Image of Antenna](../Images/antenna1.jpg) - -The other option is to tune the existing on-board antenna by cutting it. The antenna on the Explorer Block is a strip of copper underneath the green outer coating. The antenna is labeled A1. It will have its maximum power at 868 MHz. The antenna has a line across it at one point with a label that says "915". The antenna defaults to the 868 MHz range, which is what WW pumps use. If you have a US pump, mmtune will run and tune to something near 916MHz. Even with the 868 MHz antenna, you should get half a dozen feet or more of range on average. If you (optionally) want to boost the range of your antenna by a couple more feet, then you cut through the outer coating and the copper on that line with an X-ACTO knife. A single clean cut is sufficient, but if the cut doesn't look clean you could make two cuts and then dig out the circumscribed piece and then reseal the copper with nail polish. With that cut, the antenna will have maximum power near 915 MHz. - -If you're unsure whether you need to cut your Explorer Block's antenna, you probably don't. And if you decide you need slightly more range after using the Edison+Explorer rig for a few weeks, you can always come back later and do so then. - -![Image of Antenna](../Images/antenna0.jpg) - ## How do I switch between insulin types, or switch to Fiasp? What should I change? -The most important setting for switching between insulin types in an OpenAPS rig is the "curve" type for duration of insulin activity. In oref0 0.6.0, most users will use the rapid-acting curve if they are using Humalog, Novolog, or similar. Fiasp users should use the "ultra-rapid" curve type. [See the preferences page here for more details on how to change your curve](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/preferences-and-safety-settings.html#curve-rapid-acting) in your `preferences.json` file (which you can edit with `edit-pref`). +The most important setting for switching between insulin types in an OpenAPS rig is the "curve" type for duration of insulin activity. In oref0 0.6.0, most users will use the rapid-acting curve if they are using Humalog, Novolog, or similar. Fiasp users should use the "ultra-rapid" curve type. [See the preferences page here for more details on how to change your curve](<../Usage and maintenance/preferences-and-safety-settings#curve-rapid-acting>) in your `preferences.json` file (which you can edit with `edit-pref`). Additionally, because Fiasp has a slightly faster peak time, you may need to adjust your behavior around meal-time dosing. If you pre-bolus, you may want to consider *not* pre-bolusing for the first few meals with Fiasp until you understand the differences, to avoid lows during or after the meal. @@ -146,28 +116,3 @@ Now look at the pump loop logs again. `l` After some time, all errors should resolve and you should begin looping successfully with your new pump! - -## Improving the battery life of your Raspberry Pi - -!! Important for Enlite users: If you are using Enlite as CGM source, your rig will not work when it's underclocked, since the loop will not run fast enough! (You will always see the "BG too old" error). We are aware of that issue and try to find a solution... - -Version - CPU Clock - Battery Life @ 2500mAh (Li-Po) -___ -* 0.6.2 - 1000 MHz - **8 hours** -* 0.7.0-dev - 1000 MHz - **9 hours** -* 0.7.0-dev - 500 MHz - **14.5 hours** -___ - -As you can see, 0.7.0 made some battery life improvements, but under-clocking the CPU makes an even more significant improvement. - -To accomplish this, log into your rig via SSH and modify the file `/boot/config.txt`. - -Scroll down to find the line - -`#arm_freq=1000` - -and change it to - -`arm_freq=500` - -Note the removal of the `#` at the beginning of the line. Save your change and reboot your rig! diff --git a/docs/docs/While You Wait For Gear/collect-data-and-prepare.md b/docs/docs/While You Wait For Gear/collect-data-and-prepare.md index 3f549c185..6657d67d4 100644 --- a/docs/docs/While You Wait For Gear/collect-data-and-prepare.md +++ b/docs/docs/While You Wait For Gear/collect-data-and-prepare.md @@ -1,23 +1,38 @@ # Collect your data and get prepared -Before getting started, we suggest that you store at least 30 days of CGM data. People often like to compare their before and after looping data. Nightscout is an excellent tool to capture your CGM history, as well as log your carbs and boluses. For instructions on setting up your own Nightscout site (or updating your existing one for OpenAPS use), see [here](https://openaps.readthedocs.org/en/latest/docs/While%20You%20Wait%20For%20Gear/nightscout-setup.html). By logging and collecting a recent history of your insulin+BG patterns, you can also take advantage of the Autotune feature which uses Nightscout databases, as well as use Nightscout reports, which are often helpful for showing your data to your healthcare provider. +## Store data - CGM, and ideally carbs and insulin -Later in these docs is a link to donate your data to a project called [OpenHumans](https://openaps.readthedocs.org/en/latest/docs/Give%20Back-Pay%20It%20Forward/data-commons-data-donation.html). There is no requirement to share your data or participate in OpenHumans. If you choose to, you can donate your data whether you are looping or not. Individuals within the project who share their data do so willingly and you should do the same only if you feel comfortable. That being said, it is always a good idea to record your data before embarking on a new set of experiments. This will be helpful to understand the effects of the system as well as gain a better understanding of your response to different control strategies. +Before getting started, we ask that you store at least 30 days of CGM data. It is always a good idea to record your data before embarking on a new set of experiments. This will be helpful to understand the effects of the system as well as gain a better understanding of your response to different control strategies. + +Nightscout is an excellent tool to capture your CGM history, as well as log your carbs and boluses. Your Nightscout site will (in a typical setup) be the source of CGM data for your OpenAPS rig. For instructions on setting up your own Nightscout site (or updating your existing one for OpenAPS use), see [here](<../While You Wait For Gear/nightscout-setup>). + +By logging and collecting a recent history of your basal, bolus, carb, and BG patterns, you can also take advantage of the Autotune feature which uses Nightscout databases (see below). You can log carbs and boluses using the Nightscout "careportal," and tell it about your basal insulin using a "profile." + +If you aren't using Nightscout, you can upload your Dexcom G4 receiver to Dexcom Studio or if you use Dexcom G5 the data is in the cloud at Dexcom Clarity. If you use a Medtronic CGM, upload your CGM data to CareLink. If you use an Animas Vibe, upload your data to Tidepool or Diasend. We suggest you get in the habit of doing this regularly so that you have ongoing data to show trends in your overall estimated average glucose (eAG, a good indicator in trends in A1c) and variations in your "time in range." + +Later in these docs is a link to donate your data to a project called [OpenHumans](<../Give Back-Pay It Forward/data-commons-data-donation>). There is no requirement to share your data or participate in OpenHumans. If you choose to, you can donate your data whether you are looping or not. Individuals within the project who share their data do so willingly and you should do the same only if you feel comfortable. ## Practice good CGM habits -A good quality CGM session is a critical part of successful looping. If you're used to stretching your sensor sessions out until failure, you may want to reconsider this approach as you will have failed looping times, too. One technique that has helped eliminate early sensor jumpiness in a session is to "presoak" a new sensor before the old one dies when you notice the old sensor is getting jumpy or loses calibration. To read more about this presoak technique, check out this [blog post](https://diyps.org/2016/06/27/how-to-soak-a-new-cgm-sensor-for-better-first-day-bgs/). In addition, be diligent about your sensor calibration habits. Only calibrate on flat arrows and when BGs are steady. Many loopers calibrate once or twice a day only; at bedtime (after dinner has finished digesting) and/or just before getting out of bed. A good guide to sensor calibration - which generally applies regardless of which sensor you have - can be found [here](https://forum.fudiabetes.org/t/how-to-calibrate-a-dexcom-g4-g5-cgm/2049/). +A good quality CGM session is a critical part of successful looping. If you're used to stretching your sensor sessions out until failure, you may want to reconsider this approach as you will have failed looping times, too. One technique that has helped eliminate early sensor jumpiness in a session is to "presoak" a new sensor before the old one dies when you notice the old sensor is getting jumpy or loses calibration. To read more about this presoak technique, check out this [blog post](https://diyps.org/2016/06/27/how-to-soak-a-new-cgm-sensor-for-better-first-day-bgs/). -## Use your gear +In addition, be diligent about your sensor calibration habits. Only calibrate on flat arrows and when BGs are steady. Many loopers calibrate once or twice a day only; at bedtime (after dinner has finished digesting) and/or just before getting out of bed. A good guide to sensor calibration - which generally applies regardless of which sensor you have - can be found [here](https://forum.fudiabetes.org/t/how-to-calibrate-a-dexcom-g4-g5-cgm/2049/). + +## Optimize your settings with Autotune + +You've been logging and recording your carbs and boluses in Nightscout, right? You have your CGM data flowing into Nightscout too? Great... now autotune can give you a head start on fine-tuning your basals and ISF. There are some restrictions on autotune still (only a single daily carb ratio and single daily ISF), but there are tips on the [autotune page](<../How it works/autotune>) for how to deal with multiple values. You can run autotune before you get your loop setup - it doesn't have to run on a rig, it just needs your Nightscout data. The easiest way is to [run it on AutotuneWeb](<../Usage and maintenance/running-autotune#autotuneweb-the-easiest-way-to-run-autotune>). + +How important are good basals and ISFs? You mean you weren't convinced already by the amount of work put into autotune itself? Well, autotune is a required step in order to enable the most advanced features (SMB and UAM). OpenAPS will check to see if you have an autotune directory in your rig before the loop will be allowed to actually enact any SMBs (no matter what your preferences say). + +Regardless of if you want to use advanced features later, we highly recommend running autotune as part of the rig nightly, or as a one-off and periodically checking the output to see if the settings on the pump that you are using reflect what the data says your body really needs. -Starting a DIY loop system like OpenAPS means you are probably switching pumps, and quite possibly using Nightscout for the first time. You may find, like many new users, that settings you thought you had dialed in before will need to be adjusted. Good news, there are several tools and techiques to get you off to the right start. They include: +**Safety note**: your carb ratio is unlikely to vary significantly throughout the course of day. If you have carb ratios that vary significantly (such as more than 2x) between different times of day, you may get unexpected results in looping, such as COB reappearing when the CR schedule changes. For safety, we recommend checking your settings against Autotune, which currently uses a single CR for the entire day. If you are using a schedule with widely varying carb ratios or ISFs, that may be compensating for something other than an actual diurnal variation in carb ratio: perhaps different absorption speeds of different foods, or perhaps related to different macronutrient composition (instead of entering carb equivalents for fat/protein), differing basal insulin needs around mealtime, or something else. -* Use your pump **BEFORE** you begin looping -* Practice good CGM habits -* Collect your carb, bolus, and BG history using Nightscout -* Use Autotune to analyze and fine-tune your pump settings +## Use your gear + +Starting a DIY loop system like OpenAPS means you are probably switching pumps, and quite possibly using Nightscout for the first time. It is worth taking some time to get familiar with your new gear and with using Nightscout ahead of adding your DIY closed loop to the mix! -### Start Medtronic pump +### Starting Medtronic pump Many loopers have come from Animas, OmniPods, Roche, or t:slim pumps in order to pump using old Medtronic pumps. The menus will be different and you need to get proficient with the pump's normal use before complicating things with looping. Become familiar with the reservoir changes and teach your T1D kid, if that's the person who will be using the pump. Train caregivers on the new pump, as well. Assuming that you're already familiar with insulin pumping (and you should be before trying to loop) but new to these old Medtronic pumps, these "quick menu" guides will help: @@ -41,10 +56,10 @@ There are a couple areas in the pump that will need to be set specifically in or * Set basal profile, carb ratios, and ISF values. - * **Safety note**: your carb ratio is unlikely to vary significantly throughout the course of day. If you have carb ratios that vary significantly (such as more than 2x) between different times of day, you may get unexpected results in looping, such as COB reappearing when the CR schedule changes. For safety, we recommend checking your settings against Autotune, which currently uses a single CR for the entire day. If you are using a schedule with widely varying carb ratios or ISFs, that may be compensating for something other than an actual diurnal variation in carb ratio: perhaps different absorption speeds of different foods, or perhaps related to different macronutrient composition (instead of entering carb equivalents for fat/protein), differing basal insulin needs around mealtime, or something else. - * Set your DIA. **Note**: Most people have their DIA for traditional pumping to be too short (e.g. 2 or 3). For looping, OpenAPS will default to using 5. Many people find they actually need it to be 6 or 7 with properly adjusted other settings. +* ISFs over 250 mg/dl per unit will need a special step in loop setup once your setup script is finished (see [here](<../Build Your Rig/step-4-watching-log#temp-basals-6-3-isf-255-or-carb-ratio-25-with-a-x23-or-x54)), even though the pump currently will allow you to set them higher. Just remember, you will need to run a couple extra commands when you setup your loop. + * If you have periods in the day where your pump normally has basal settings of zero - your loop will not work! You can resolve this by setting the lowest possible basal setting your pump will permit. OpenAPS will then issue temp basals of zero, as needed. #### Easy Bolus Button @@ -61,15 +76,4 @@ Due to the way Medtronic pumps operate, temp basals can only be set when there i But, you don't need the square/dual wave boluses anymore, as OpenAPS will help simulate the longer tail insulin needed if you've entered carbs into the system. Also, many loopers have found they can convert to a split bolus strategy to effectively deal with the same meals. There is a carb+insulin+BG simulator called [Glucodyn](http://perceptus.org) that can be used to model a split bolus strategy for those meals. By setting different bolus times and bolus amounts, the model allows the user to slide adjustments to minimize early-meal lows as well as late meal rises. For example, you may find that a 20 minute pre-bolus of 50% of the carbs and a later bolus for the remaining 50% will work well, with looping helping to make up the difference that an extended bolus used to provide. You can practice the transition to split bolusing even before you get your loop running. -Some of the super advanced features you'll learn about later - Unannounced Meals and Supermicrobolus (UAM/SMBs) - also help smooth the transition from extended bolusing. Some users have found that entering in carbs alone can be effective, especially in helping later BG rises from slow-absorping carbs. Once you get your loop running, and are ready for the advanced features, you may be interested in playing with the various techniques available for heavy, slow carb meals. - -### Autotune - -You've been logging and recording your carbs and boluses in Nightscout, right? You have your CGM data flowing into Nightscout too? Great...now autotune can give you a headstart to fine-tuning your basals and ISF. There are some restrictions on autotune still (only a single daily carb ratio and single daily ISF), but there are tips on the [autotune page](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/autotune.html) for how to deal with multiple values. You can run autotune before you get your loop setup...it doesn't have to run on a rig. - -How important are good basals and ISFs? You mean you weren't convinced already by the amount of work put into autotune itself? Well, autotune is a required step in order to enable the most advanced features (SMB and UAM). The new version will check to see if you have an autotune directory in your rig before the loop will be allowed to actually enact any SMBs (no matter what your preferences say). To fulfill this requirement you can do one of the following which will create an autotune directory where it needs to be: - -* enable autotune during your OpenAPS setup script and autotune will run automatically as part of your loop. -* run autotune as a one-off (single run) on your rig using the directions given in the link above - -Regardless of if you want to use advanced features later, we highly recommend running autotune as part of the rig nightly, or as a one-off and periodically checking the output to see if the settings on the pump that you are using reflect what the data says your body really needs. +Some of the super advanced features you'll learn about later - Unannounced Meals and Supermicrobolus (UAM/SMBs) - also help smooth the transition from extended bolusing. Some users have found that entering in carbs alone can be effective, especially in helping later BG rises from slow-absorping carbs. Once you get your loop running, and are ready for the advanced features, you may be interested in playing with the various techniques available for heavy, slow carb meals. \ No newline at end of file diff --git a/docs/docs/While You Wait For Gear/entering-carbs-bolus.md b/docs/docs/While You Wait For Gear/entering-carbs-bolus.md deleted file mode 100644 index b087b45dd..000000000 --- a/docs/docs/While You Wait For Gear/entering-carbs-bolus.md +++ /dev/null @@ -1,38 +0,0 @@ -# Entering carbs & doing boluses - -How do you enter carbs & do boluses with OpenAPS? You have a variety of ways to do things. - -## Doing boluses - -* **Easy bolus button**: Previously before OpenAPS, you probably used the [easy bolus button](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/collect-data-and-prepare.html#easy-bolus-button) to add up a bolus in increments. (E.g. if your pump had increments of 0.5u, you could quickly dial up to a bolus by pressing the up button as many times as needed; hitting enter to confirm it; hitting enter again to deliver the bolus.) - -* **Bolus wizard**: Or, you may have used the bolus wizard, sometimes with BG or carb entry, or just as a bolus. - -**In OpenAPS, you can still use those same methods for delivering manual doses of insulin (boluses).** - -## Entering carbs into OpenAPS - -Before OpenAPS, you may or may not have entered carbs into your pump. With OpenAPS, most people *do* want the rig to know about carbs. You have a variety of ways to enter them, depending on whether your rig is **online** or **offline**. - -Look at this image for the big picture: - -![Different methods for entering carbs](../Images/Carb_data_to_rig.jpg) - -### Offline carb entry - -* You can still use the bolus wizard to enter carbs, although a non-zero amount of bolus must be delivered in order for OpenAPS to record the carbs. If you adjust the bolus recommended by the bolus wizard down to zero and deliver the zero units (as you might ordinarily do if you ate carbs in order to treat a low), the pump may (depending on your pump version) fail to record a bolus wizard record in pumphistory, causing OpenAPS to ignore the carbs as if you hadn't entered them. In that situation, consider delivering the smallest unit of bolus possible (like 0.05u or 0.1u) so that OpenAPS will record the carbs entered into the bolus wizard. -* Some pumps can use the ['meal marker' feature](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/offline-looping-and-monitoring.html#entering-carbs-while-offline). -* See section on [extended and dual wave substitutes](https://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/collect-data-and-prepare.html#extended-and-dual-wave-substitute) for information on how extended boluses are handled in OpenAPS. - -### Online carb entry - -If your rig is online, you have a variety of ways to enter carbs online. - -* Nightscout care portal -* AndroidAPS NS Client ([Download the app-nsclient-release APK from here](https://github.com/MilosKozak/AndroidAPS/releases).) -* Many options for using IFTTT to get carbs into Nightscout Care portal. ([See the IFTTT page here for instructions](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/ifttt-integration.html).) - * Pebble or Apple watch - * Google Calendar - * Siri, Alexa, Google, etc. -* Android users: you can use the Care portal option in [NSClient app found here](https://github.com/nightscout/NSClient-Android/releases). - diff --git a/docs/docs/While You Wait For Gear/index.rst b/docs/docs/While You Wait For Gear/index.rst deleted file mode 100644 index 4b5ed2571..000000000 --- a/docs/docs/While You Wait For Gear/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -While You Wait For Gear ----------------------- - -.. toctree:: - :maxdepth: 4 - - - collect-data-and-prepare - loops-in-progress - nightscout-setup - understanding-your-Explorer-Board-rig - Understand-determine-basal - understanding-insulin-on-board-calculations - monitoring-OpenAPS - preferences-and-safety-settings - understanding-wifi-options diff --git a/docs/docs/While You Wait For Gear/loops-in-progress.md b/docs/docs/While You Wait For Gear/loops-in-progress.md index 967e8d744..d498821a2 100644 --- a/docs/docs/While You Wait For Gear/loops-in-progress.md +++ b/docs/docs/While You Wait For Gear/loops-in-progress.md @@ -2,7 +2,7 @@ To get you comfortable with submitting a "PR" (stands for pull request), test it out by submitting a PR to this page, adding your name to the list of people who have loops in progress. -New to Github, and PRs? [Check out how to submit your first PR](http://openaps.readthedocs.io/en/latest/docs/Resources/my-first-pr.html). +New to Github, and PRs? [Check out how to submit your first PR](<../Resources/my-first-pr>). List of people who are working on closed loops: diff --git a/docs/docs/While You Wait For Gear/nightscout-setup.md b/docs/docs/While You Wait For Gear/nightscout-setup.md index 9464509b7..09e5a7b89 100644 --- a/docs/docs/While You Wait For Gear/nightscout-setup.md +++ b/docs/docs/While You Wait For Gear/nightscout-setup.md @@ -1,4 +1,4 @@ -# Visualization and Monitoring +# Visualization and Monitoring using Nightscout ## Nightscout Introduction @@ -19,6 +19,45 @@ with another person, it will be helpful for you to visualize what the loop is doing; what it's been doing; plus generate helpful reports for understanding your data, customized watchfaces with your OpenAPS data, and integration with IFTTT. You can read more about latest Nightscout features [here](http://www.nightscout.info/wiki/welcome/website-features) +If you already have a Nightscout site, still review the directions below to change your config variables to prepare for using OpenAPS! See [Using your Nightscout site](<#using-your-nightscout-site>) for important details about how to display and interpret OpenAPS-related information. + +## How Nightscout and OpenAPS work together + +OpenAPS is designed to work closely with Nightscout. + +### What information is passed from rig to NS? + +The rig uploads the following information to NS: + +* Assuming pump communications are good, the rig will read information from the pump as follows: + * boluses and carbs; entered through either the pump bolus wizard or the easy bolus button + * current temp basal rate and duration/time set + * pump status; bolusing or suspended, reservoir volume, pump battery voltage + * pump notes; time changes, profile changes, battery changes, alarms (these show as grey dots on NS site) + * if a MDT enlite user, BGs will be read directly from the pump + +* From OpenAPS looping, the additional information is also uploaded: + * determine-basal information (such as IOB, COB, temp basal enacted, etc) goes to fill out the OpenAPS pill in NS + * rig battery voltage and estimated % + +* If (1) a dexcom receiver is connected to the rig and (2) the loop is setup with G4-upload as the CGM type and (3) the rig has internet, then the rig will also upload BGs and/or rawBG directly to NS. This keeps the loop functional even if the Share app fails. For example, if the phone battery dies during the night, and Share App therefore goes down...the rig can read BGs/rawBGs directly from the receiver and use your home wifi to upload to NS still. + +### What information is passed from NS to rig? + +The careportal "treatment" entries and BG data are the two most important items transmitted from NS to the rig. + +* Careportal entries transmitted and **USED** by the loop are: + * carb entries - these are taken into account by OpenAPS to predict your blood glucose curve + * temp BG targets - you can set a "temporary target" from Nightscout which will be used by OpenAPS + +* BG values from Dexcom share servers via the NS bridge + +Note that insulin logged on Nightscout but not read from the pump (e.g., an injection logged) is not directly used by the loop. + +## Troubleshooting Nightscout issues + +Please see the [Nightscout troubleshooting](<../Troubleshooting/rig-ns-communications-troubleshooting>) page if you experience problems with the setup process or with communications with Nightscout. + ## Nightscout Setup with Heroku * If you plan to use Nightscout with OpenAPS, we recommend using Heroku, as OpenAPS can reach the usage limits of the free Azure plan and cause it to shut down for hours or days. If you end up needing a paid tier, the $7/mo Heroku plan is also much cheaper than the first paid tier of Azure. Currently, the only added benefit to choosing the $7/mo Heroku plan vs the free Heroku plan is a section showing site use metrics for performance (such as response time). This has limited benefit to the average OpenAPS user. **In short, Heroku is the free and OpenAPS-friendly option for NS hosting.** @@ -241,7 +280,8 @@ If you are using the Nightscout Bridge to bring in CGM data from Dexcom servers Because running OpenAPS requires frequent communication with your pump, your pump battery tends to drain more quickly than you'd experience when not looping. Some users have had good experiences with Energizer Ultimate Lithium AAA batteries (getting ~1.5weeks) rather than alkaline batteries (getting ~2-3 days). Regardless of whether you use alkaline or lithium, you may want to consider a Nightscout alarm to alert you to when the battery is running low. You can do this by setting (in your Nightscout config vars) `PUMP_WARN_BATT_V` to 1.39 for lithium batteries or 1.2 or 1.25 for alkaline batteries, and adding `battery` to your `PUMP_FIELDS` setting so that voltage is displayed on your Nightscout site. The voltage warning will give you many hours (reportedly ~8+ for lithium and ~6+ for alkaline) heads up that you will need to change your battery. Note: If you don't change the battery in time and end up with a "low battery" warning on the pump, the pump will still function, but RF communications will be turned off and you will not be able to loop until you put a new battery in. -Your NIGHTSCOUT site is now all set-up. Congrats! +Your NIGHTSCOUT site is now all set up. Congrats! + ## Nightscout Migrations @@ -351,15 +391,23 @@ Other notes: ![Deploy branch](../Images/nightscout/deploy_branch.jpg) -## Nightscout Troubleshooting and FAQ -### It's not working - I'm missing data in Nightscout? +## Using your Nightscout site -If you are using a "test pump" that has not received sufficient data in some time, Nightscout pills will NOT be displayed onscreen. Nightscout may also not work if it hasn't had CGM data in a while - so if you haven't been using a CGM and uploading CGM data to Nightscout for the past few days, the site may be empty as well. If this happens, simply use this pump in tandem with a CGM so glucose values are recorded and eventually uploaded to Nightscout. Once sufficient data has been collected (and OpenAPS plugin is enabled and saved) the OpenAPS pills should appear automatically. Medtronic CGM users may also [need to do this to get their CGM data flowing into Nightscout after a gap in uploading data](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/offline-looping-and-monitoring.html#note-about-recovery-from-camping-mode-offline-mode-for-medtronic-cgm-users). +### Understanding the OpenAPS pill + +The OpenAPS pill box has four states, based on what happened in the last 15 +minutes: Enacted, Looping, Waiting, and Warning: + +* Waiting is when OpenAPS is uploading, but hasn't seen the pump in a while +* Warning is when there hasn't been a status upload in the last 15 minutes +* Enacted means OpenAPS has recently enacted the pump +* Looping means OpenAPS is running but has not enacted the pump +* Unknown means Error or Timeout; OpenAPS has reported a failure, or has reported no status for many hours. -Dexcom CGM users should make sure they have "share" enabled and have actively shared their data with at least one follower, before data will begin flowing to Nightscout. If you don't want to share your data with another person, you can just follow yourself. +If you click/tap on the pill, you will see more information about the most recent information used and decisions made by OpenAPS, including calculated IOB and COB; predicted eventual BG; any temp basal set; and any problems such as too-old BG data if your CGM is not working. -### A Note about Nightscout's COB Pill +### A note about Nightscout's COB Pill If you have the Advanced Meal Assist (AMA) OpenAPS feature turned on, OpenAPS calculates COB *dynamically*. To see your COB on your Nightscout web app, look inside the OpenAPS pill. _(If it says "undefined", this means you do NOT have AMA turned on.)_ @@ -371,6 +419,14 @@ Nightscout, however, has its own COB pill, which decays carbs *statically*, and * **To avoid confusion: Turn off all other Nightscout pills that use *static* COB calculations.** +### The IOB pill + +This pill will normally display the IOB reported by your OpenAPS pill. If your loop is failing or NS communications are down because the rig has gone offline, there's a good possibility that your IOB pill will be displaying an incorrect IOB based on the careportal's method of calculating IOB (rather than OpenAPS's way). You can determine the source of your IOB pill's information by clicking or hovering on the pill. If the pills says "OpenAPS", then it's good to use that data. Additionally, it should report the portion of IOB termed "basal IOB", which is the IOB from of temp basal adjustments and SMBs, if enabled. + +### The Basal pill + +This pill should NOT be used in your NS site. The information on that pill updates so slowly sometimes, that you may incorrectly jump to assumptions that your rig is behaving differently than it actually is. Instead, use the OpenAPS pill to find current information about your current basal rate...or press the ESC button on your pump in order to directly read the current temp basal. Additionally, the basal rendering (the blue lines of the NS display) can sometimes lag by up to 2-5 minutes, depending on loop activities...so again use the OpenAPS pill or pump if you are interested in the most up-to-date information on temp basals. + ### How to display basal changes ("render basal") * In case you missed it during setup: we recommend that you "render"/display the basal rates (the blue lines to show what temp basals have been enacted, if any.) To do so, select "Default" or "Icicle" from the "Render Basal" pull-down menu in the Settings. @@ -401,25 +457,3 @@ Afterward, your profile will probably look something like this: * There are up to four purple prediction lines that you will see: IOBpredBG; ZTpredBG; UAM; and COBpredBG. ![Purple prediction line examples](../Images/Prediction_lines.jpg) - -### Understanding the OpenAPS pill - -The OpenAPS pill box has four states, based on what happened in the last 15 -minutes: Enacted, Looping, Waiting, and Warning: - -* Waiting is when OpenAPS is uploading, but hasn't seen the pump in a while -* Warning is when there hasn't been a status upload in the last 15 minutes -* Enacted means OpenAPS has recently enacted the pump -* Looping means OpenAPS is running but has not enacted the pump -* Unknown means Error or Timeout; OpenAPS has reported a failure, or has reported no status for many hours. - -### All of a sudden, Nightscout is no longer showing treatments (bolus, carbs, finger BGs) on the graph or rendering my basals. - -If you suddenly find that Nightscout is not showing treatments (bolus, carbs, finger BGs etc.) on the graph; and/or that your basals are no longer being rendered in the blue basal line; but otherwise, everything looks normal and you are looping properly: - -You probably somehow got a future-dated treatment. One possible reason is a clock-time mismatch between your devices - for example, your BG meter, pump, CGM, or OpenAPS rig may have different dates or times set. - -**To remove future treatments:** -* Go into Nightscout under "Settings" and "Admin tools" and delete any future-dated treatments (press the "remove treatments in the future" button). If the future treatments were caused by a time mismatch, you'll need to resolve that first, or the future dated treatments may simply be re-uploaded. - -![How to delete future-dated treaments](../Images/Remove_future_treatments.png) diff --git a/docs/docs/While You Wait For Gear/reading-list.md b/docs/docs/While You Wait For Gear/reading-list.md new file mode 100644 index 000000000..201d246c6 --- /dev/null +++ b/docs/docs/While You Wait For Gear/reading-list.md @@ -0,0 +1,15 @@ +# Reading list + +Before you actually install OpenAPS on your rig - perhaps while you're waiting for gear to arrive, or while you're learning to use your new pump or logging data on Nightscout - you should familiarize yourself with the system. + +Here are the most important sections to read: + +1. Make sure you know [how you will enter carbs and boluses so OpenAPS knows about them](<../Usage and maintenance/entering-carbs-bolus>). + +2. Read and understand [how OpenAPS decides on adjustments to your basal insulin](<../How it works/understand-determine-basal>). + +3. Skim the section on [monitoring OpenAPS](<../Usage and maintenance/monitoring-OpenAPS>) so you're aware of the various options for monitoring your rig once it's looping. It's not necessary to understand all the options in detail, just be aware of them; you'll probably want to return to that section to set up additional options in the future. + +4. Skim the section on [preferences and safety settings](<../Usage and maintenance/preferences-and-safety-settings>) you can set so you're aware of the things you can easily adjust. You'll be returning to set these in Step 5 of the installation process. + +5. Skim the section on [your wifi options](<../Usage and maintenance/Wifi/understanding-wifi-options>) to understand the various ways you can get your rig online. Again, you don't need to memorize all the information here, just be aware of the options and ready to return in the future as needed. \ No newline at end of file diff --git a/docs/docs/While You Wait For Gear/understanding-your-Explorer-Board-rig.md b/docs/docs/While You Wait For Gear/understanding-your-Explorer-Board-rig.md deleted file mode 100644 index cf5e5a3f4..000000000 --- a/docs/docs/While You Wait For Gear/understanding-your-Explorer-Board-rig.md +++ /dev/null @@ -1,136 +0,0 @@ -# Understanding your OpenAPS rig - -## Pi HAT rig - -After April 2018, there is a Pi+HAT rig as an option for closing the loop with OpenAPS. The HAT can be ordered from the same place that makes the Explorer Board ([click here](https://enhanced-radio-devices.myshopify.com/products/900mhz-explorer-hat?variant=1950212653065). We call it the "Explorer HAT", to differentiate from the Explorer "Board" that goes with the Edison. - -![Explorer Hat](../Images/explorerhat.png) - -#### Getting Physical: Build your Pi/HAT rig - -If you chose a "Pi Zero WH" (with headers), you will place the HAT on the Pi. - -##### Buttons and Menu System - -The Explorer Board Pi HAT includes a 128x64 OLED display with two general purpose buttons to navigate an included menu system. - -##### Button Navigation - -The Pi HAT has two general purpose buttons labeled "Up" and "Down". A single press of the "Up" button will move the menu selection cursor up a single menu item and a single press of the "Down" button will move the menu selection cursor down a single menu item. - -A double press of the "Down" button will enter in currently selected menu item as indicated by the ">" next to a menu item. - -A double press of the "Up" button will take you back to the previous screen. - -##### Menu Items - -
- The current tree of available menu items (click to expand): -
- -* OpenAPS - * Status Graph - * Set Temp Target - * Cancel temp Target - * Eating Soon: 60m@80 - * Speaking: 45m@110 - * Walking: 45m@120 - * Running: 60m@140 - * Status Text - * Enacted Reason - * Show pump-loop.log - * Unicorn Logo -* Wifi - * Current Wifi Network - * Current Hostname - * Current IP Address - * Show network.log -* System - * Voltage - * Display Tests - * Checkerboard 1 - * Checkerboard 2 - * All On - * Boxes 1 - * Boxes 2 - * lsusb - * Reboot - * Cancel Reboot - -
-
- -A series of images of the menu items can be [viewed here](https://imgur.com/a/9qLf93B). - -#### Charging - -The rig can be charged via microUSB. - -**Note:** the charging LED on the board is not working currently (unless you remove the Q3 transistor). Currently, it’s basically just a “plugged into the wall” indicator. The only side effect of removing Q3 is on the binary charging signal to the Pi (which doesn’t work anyway, and we’ve not tried to use). The voltage monitoring should work fine either way, but while the rig is charging will report 4.2V (“fully charged”) any time the battery is more than about 50% charged. So to be sure if it’s charged you should unplug the rig. - -**2nd Note:** make sure the battery plug is switched to ON while the rig is plugged. Otherwise the battery won't charge. - -#### Power - -Like an Edison rig, you can use a single cell (1s) lipo battery or similar; or use wall power. - -#### LED - -The Pi HAT offers 4 LEDs labeled with D1-D4. D1 is the charging LED and works as described above. D2 is the battery low indicator. It turns orange when the LiPo battery voltage goes below 3.6 V or when the rig is plugged and the battery switch is on OFF. D3 and D4 are connected to the CC1110 radio processor and are controlled by the subg_rfspy radio firmware while resetting the radio. That happens repeatedly during wait-for-silence. - -#### Multiple Rigs? What if I have an Edison AND a Pi rig? - -Just like multiple Edison rigs play well together, an Edison and a Pi rig can also work fine side by side. As always, best practice is to make sure they're in the same feature set - don't have one type of rig using SMB's if the other hardware has an old code version that isn't aware of SMB's. - -## Edison/Explorer Board rig - -The Edison/Explorer Board is one of the "rig" types you can use to close the loop with OpenAPS. - -#### Getting Physical: Build your Edison/Explorer Board rig/put the physical pieces together - -The Explorer board is where all the communications are housed for the rig, as well as the battery charger. The Edison is the mini-computer where all the OpenAPS code will be sent and used. In order for this to work, first you have to screw and connect the Edison and Explorer Board together with the nuts and bolts you order. - -The nuts and bolts are tiny, and the spaces are a little tight. It really helps to use a set of tweezers and a small Phillips head screwdriver. You will need 2 small gold screws, 2 small nuts, and 2 small silver screws. - -It's easiest to start with the Explorer board and put on 2 nuts and gold screws (nuts on the side with most of the wiring) inside the little outline where the Edison will eventually sit. The gold screws should be placed as shown, with nuts on the backside. Then, lay the Edison board on top of the gold screws, aligning the screw holes on the Edison board with the gold screw heads (which have screw holes in them). Use a small Phillips head screwdriver to tighten the silver screws into the gold screws beneath them. The Edison board should not wobble, and should feel secure when you are done. Attach your battery into the explorer board plug. A single red light should appear and stay lit. During the course of your OpenAPS rig use, it's good practice to periodically check that the nuts and screws stay tightened. If they come loose, the Edison can wobble off the connection to the Explorer board and you will either get looping failures (if it's loose) or be unable to connect to the Edison (if it comes completely off). - -![Edison/Explorer Board rig with red light on](../Images/Edison/Edison_Explorer_Board.png) - -#### Charging LiPo Battery - -You can use the little white block that comes with an iPhone (or similar charger) and a microB-USB cable. The same cables you used to setup the rig and connect to the computer will work for charging, too. Either one of the USB ports on the Explorer board will work for charging. When charging is active, there is an extra red light on in the corner of the Explorer board. When charging is complete, that corner red light will turn off. It may come back on periodically as the battery "tops off". You won’t do any damage leaving the rig plugged in for longer than the charge takes. - -While the rig is plugged in for charging, the Nightscout battery pill will read approximately 65%. This is because it is reading the charging voltage rather than the battery voltage. Once you disconnect from the charger, the Nightscout battery pill will display the LiPo battery's voltage and percent again. - -#### What the lights mean and where they are - -* The LED between the two ports is the power. If this light is on, your rig is on. -* The LED in the corner is the charging indictator. -* The two next to the microUSBs (one green on the latest boards) are for the cc1110 radio chip. By default they just blink once each when you mmtune or otherwise reset it. - -#### Where is the power button? - -The little black button on the end of the board near the JST connector is the power button. If you want to reboot your rig, the easiest way is to hold down the tiny power button for 10-15 seconds until the power light turns off. Wait a couple seconds and then press and hold the power button again until the light turns back on. Give the loop a couple minutes to get itself going again. Rebooting solves a majority of rig issues. - -#### Where is the radio? - -The radio and antenna are down on the end of the Explorer board where you see a little white stick (opposite end of the board from where your battery connects at the JST connector). - -### Cutting the trace to improve radio communication -Some OpenAPS users have found that cutting a portion of the Explorer Board's hidden copper antenna wire (called a trace) will improve radio comms with the pump. Before doing this, remember to disconnect any attached battery or power source. For North American (NA) or Canadian/Australian (CA) pumps (using the 916MHz band), you're looking to cut near the white line that is between the 1 and the 5 in the "915." Consider cutting on the 1-side rather than the exact spot where the white "cut" line is drawn because it is so close to the corner where the rest of the copper wire goes. To make the cut, use a sharp x-acto blade to cut through the copper just beneath the green surface of board. It will take a few swipes and you'll hear a small scraping noise when you get through the wire. Make sure you've cut all the way through the wire to the green circuit board material on the other side. - -Watch this [video](https://www.facebook.com/groups/TheLoopedGroup/permalink/1854229718127019/?hc_location=ufi) for an example. - -#### LiPo Battery - -LiPo batteries are great for a lot of things, but taking damage is not one of them. Please treat LiPo batteries with care. Keep them protected from puncture. The Explorer board has some “pointy” parts on the underside, so providing some protection from the board’s squish is a good idea. A small piece of protection (such as a business card or non-conductive thin foam sheet) will help protect the battery from the board above it. - -Since there is some warmth with an OpenAPS rig, it is also not recommended to put a rig unprotected in a pocket close to the body. The LiPo battery can become warped from the heat or bent from being in the pocket and potentially compromised. A durable case or waist-belt pouch is a good idea (see [here](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#cases) for both hard and soft case ideas). - -The connections between the LiPo battery and its red and black wires are fragile and can break easily. Consider taping the wires to the battery with electrical tape as described in SparkFun's LiPo battery care [tutorial](https://www.sparkfun.com/tutorials/241). (See the Reinforcing the Power Cables section.) This will stabilize the wires and relieve tension on the connections. - -There are several places to get LiPo batteries, with lots of different dimensions and capacities. A 2000 mAh LiPo will get you about 12-14 hours of use, assuming you have the standard setup (which is what you get following these docs) running. - -#### What happens if you have multiple rigs? - -If you have multiple OpenAPS rigs, they’re built to be polite to each other. Even if you had two or more rigs in same room, they won’t trip each other up. They “wait for silence” before issuing any commands to the pump. By having multiple rigs throughout a house, you can move from room-to-room without carrying rigs because the rigs will pass-off comms as you moves in and out of the rig’s range. Stationary rigs will not need LiPo batteries and can be plugged directly into a wall charger from the Explorer board. diff --git a/docs/index.rst b/docs/index.rst index 6b7eb5424..f5973915f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,9 +3,6 @@ Welcome to OpenAPS's documentation! This documentation supports a self-driven Do-It-Yourself (DIY) implementation of an artificial pancreas based on the OpenAPS reference design. By proceeding to use these tools or any piece within, you agree to `the copyright `_ for more information; and `the full README here `_ and release any contributors from liability, and assume full responsibility for all of your actions and outcomes related to usage of these tools or ideas. -.. WARNING:: -Note: *We do not recommend using a PDF version of this guide. The docs are updated continuously, and with a PDF, you will not get the freshest real-time edits. Be aware if you download a PDF that when you have Internet connectivity, we recommend instead having the docs pulled up in an Internet browser so you can refresh. This is especially true if you are working on a setup over the course of multiple days.* - .. note:: **A Note on DIY and the "Open" Part of OpenAPS** @@ -22,82 +19,119 @@ Note: *We do not recommend using a PDF version of this guide. The docs are updat Additionally, it is equally important to only use original supplies such as inserters, cannulas and insulin containers approved by the manufacturer for use with your pump or CGM. Using untested or modified supplies can cause CGM inaccuracy and insulin dosing errors. Insulin is highly dangerous when misdosed - please do not play with your life by hacking with your supplies. + + .. toctree:: :maxdepth: 2 :glob: - :caption: Understanding OpenAPS (Overview) + :hidden: + :caption: Overview How OpenAPS works - How this guide works/overview of steps + Overview of steps + Using this documentation Where to go for help .. toctree:: :maxdepth: 2 :glob: - :caption: Gear Up - - docs/Gear Up/hardware + :hidden: + :caption: Hardware + + Overview Compatible Pumps Compatible CGMs - Get your rig parts + Your rig hardware options + Edison rigs + Raspberry Pi rigs .. toctree:: :maxdepth: 2 :glob: - :caption: While You Wait For Gear + :hidden: + :caption: Getting ready + Set up Nightscout Collect your data & prepare - Make Your First PR - Setting up Nightscout - Understand your rig - Entering carbs & boluses - How OpenAPS makes decisions - Monitoring OpenAPS - Preferences and Safety Settings - Understanding your wifi options + Make your first PR + Do some reading .. toctree:: :maxdepth: 2 :glob: - :caption: Build Your Rig - - Installing OpenAPS - Tell us you’re looping - + :hidden: + :caption: Installing OpenAPS + + Overview + Step 1: Flashing + Step 2: Wifi and dependencies + Step 3: Setup script + Step 4: Watching logs + Step 5: Finishing setup + Logging into the rig using a serial connection + + .. toctree:: :maxdepth: 2 :glob: - :caption: Customize-Iterate - - Optimizing Your Settings - Offline Looping - Enable Bluetooth tethering - Add more wifi to your rig - Useful apps for accessing your rig - IFTTT and Pebble buttons - iPhone Shortcuts buttons - Autosens - Autotune - Understanding Autotune + :hidden: + :caption: How OpenAPS works + + How OpenAPS makes decisions + Insulin on board calculations + Understanding Autotune + Understanding Autosens + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + :caption: Usage and maintenance + + How to enter carbs and boluses + Preferences and safety settings + Monitoring OpenAPS + Using your loop: common situations + Optimizing your settings + Running Autotune + How to run oref0-setup.sh again + Update your rig in the future + Wifi overview + Adding wifi networks to your rig + Bluetooth tethering + + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + :caption: Customizing and extra features + oref1: SMB and UAM - Tips & tricks - Update your rig in the future - How to run oref0-setup.sh again + Useful apps for accessing your rig + IFTTT and Pebble buttons + Offline Looping .. toctree:: :maxdepth: 2 :glob: + :hidden: :caption: Troubleshooting - Troubleshooting oref0-setup - General linux troubleshooting - Pump-rig troubleshooting - CGM-rig troubleshooting - Rig-NS troubleshooting + Overview and Linux reference + oref0-setup Troubleshooting + Wifi and hotspot issues + Pump-rig communications troubleshooting + CGM-rig communications troubleshooting + Nightscout troubleshooting + Medtronic button errors + Carelink troubleshooting .. toctree:: :maxdepth: 2 :glob: + :hidden: :caption: Give Back-Pay It Forward Donate your data @@ -106,7 +140,14 @@ Note: *We do not recommend using a PDF version of this guide. The docs are updat .. toctree:: :maxdepth: 2 :glob: + :hidden: :caption: Resources/Reference - Resources For Clinicians + History + Glossary + Making a PR + Technical resources + Switching between DIY systems + + diff --git a/requirements.txt b/requirements.txt index 96cb917bd..4fa9a0478 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ recommonmark==0.4.0 sphinx==1.5.6 git+git://github.com/bewest/decoding-carelink.git@dev -openaps +openaps \ No newline at end of file From 21269a4d715b22e2a7d3dec4d8500a6ce656cf8e Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sat, 22 Feb 2020 14:26:49 -0500 Subject: [PATCH 02/13] manually review all commits to master from sep 2019 - present and ensure changes are applied here --- docs/docs/Build Your Rig/pi-install.md | 2 +- .../step-2-wifi-dependencies.md | 165 ++++++++++-------- .../Build Your Rig/step-3-setup-script.md | 9 +- .../Customize-Iterate/ifttt-integration.md | 2 +- .../Customize-Iterate/useful-mobile-apps.md | 2 +- docs/docs/Gear Up/CGM.md | 2 +- docs/docs/Gear Up/edison-explorer-board.md | 2 + docs/docs/Gear Up/edison.md | 4 +- docs/docs/Gear Up/pi-based-rigs.md | 135 +++++++++++++- docs/docs/Gear Up/pump.md | 2 +- docs/docs/Gear Up/rig-options.md | 8 +- docs/docs/Troubleshooting/Carelink.md | 2 +- .../Troubleshooting/Common-error-messages.md | 4 +- .../oref0-setup-troubleshooting.md | 1 - .../communication-support-channels.md | 47 +++-- .../monitoring-OpenAPS.md | 38 ++-- .../collect-data-and-prepare.md | 2 - docs/index.rst | 1 + 18 files changed, 301 insertions(+), 127 deletions(-) diff --git a/docs/docs/Build Your Rig/pi-install.md b/docs/docs/Build Your Rig/pi-install.md index eecf16b15..b3f8ee6db 100644 --- a/docs/docs/Build Your Rig/pi-install.md +++ b/docs/docs/Build Your Rig/pi-install.md @@ -124,7 +124,7 @@ Press enter and answer all the setup questions. A successful setup script will **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) -Once your setup script finishes, **make sure to [watch the pump loop logs](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#step-5-watch-your-pump-loop-log)** +Once your setup script finishes, **make sure to [watch the pump loop logs](<../Build Your Rig/step-4-watching-log>)** **NOTE**: If you are using RFM69HCW as RF module: diff --git a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md index ce5d2fcc8..6d41b24ce 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -69,6 +69,8 @@ The script will do some initial installing, check the wifi, and ask you to hit e * 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`** +* 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. + * 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: @@ -273,21 +275,9 @@ Put your microSD card into a reader for your computer. Once you get your recipe !["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) +Now you will need to [boot up your Pi and connect to it](#boot-up-your-pi-and-connect-to-it). -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`. If you receive a warning that the rig's host key is not yet cached, respond YES to add it. - -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 @@ -308,77 +298,38 @@ The script will then continue to run awhile longer (10 to 30 minutes) before ask !["install piBakery"](../Images/build-your-rig/pi-curl-success.png) -**If you are installing to a Pi with a legacy radio (Ti-stick, SliceOfRadio, etc.) - Press enter. [Jump to finishing the installation](#finish-installation)** - -**If you are installing to a newer Pi with a HAT or RFM69HCW as radio: Do not press enter! [Continue on to Pi-Hat instructions.](#switch-to-dev-branch-for-your-pi-hat).** - -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. +### Finish installation ### -!["install piBakery"](../Images/build-your-rig/pi-curl-fail.png) - - -#### Switch to dev branch for your pi HAT -If you are here - you should be building a rig with a Pi HAT(recommended) or RFM69HCW (experimental). 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` on a Mac. On a Windows PC with PuTTY, the hostname can be either `yourrigname` or `yourrigname.local`, and the username will be `root`. - -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". - -#### Finish installation - -First, update npm to the latest version. Run `npm install npm@latest -g`. - -Next, change to the oref0 directory if you are not in it already. Run `cd ~/src/oref0`. - -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. +Press enter and 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. !["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) Once your setup script finishes, **make sure to [watch the pump loop logs](<../Build Your Rig/step-4-watching-log>)** **NOTE**: If you are using RFM69HCW as RF module: -If you have connected your RFM69HCW module as described in [Soldering RFM69HCW](<../Gear Up/pi-based-rigs#soldering>), while running interactive setup use following options: -```Are you using an Explorer Board? [Y]/n n -Are you using an Explorer HAT? [Y]/n n -Are you using mmeowlink (i.e. with a TI stick)? If not, press enter. If so, paste your full port address: it looks like "/dev/ttySOMETHING" without the quotes. -What is your TTY port? /dev/spidev0.0 -Ok, TTY /dev/spidev0.0 it is. - -Would you like to [D]ownload released precompiled Go pump communication library or install an [U]nofficial (possibly untested) version.[D]/U u -You could either build the Medtronic library from [S]ource, or type the version tag you would like to use, example 'v2018.08.08' [S]/ s -Building Go pump binaries from source -What type of radio do you use? [1] for cc1101 [2] for CC1110 or CC1111 [3] for RFM69HCW radio module 1/[2]/3 3 -Building Go pump binaries from source with + radiotags + tags. +If you have connected your RFM69HCW module as described in [Soldering RFM69HCW](https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#soldering), while running interactive setup use following option: ``` -after running oref0-setup.sh run the following: -```$ cd ~ && export PATH="$PATH:/usr/local/go/bin" -$ rm -rf ~/go/src/github.com/ecc1 -$ go get -u -v -tags "rfm69 walrus" github.com/ecc1/medtronic/... -$ cp -pruv $HOME/go/bin/* /usr/local/bin/ -$ mv /usr/local/bin/mmtune /usr/local/bin/Go-mmtune +3) RFM69HCW (DIY: SPI) ``` -This will help in building the right pump communication libraries. - -* You'll want to also delete the openaps-menu folder to avoid error messages in your logs. `rm -rf ~/src/openaps-menu/` -* If you experience something like this: -```mmtune: radio_locale = WW -2019/01/14 15:14:25 cannot connect to CC111x radio on /dev/spidev0.0 -2019/01/14 15:14:25 cc111x: no response -Usage: grep [OPTION]... PATTERN [FILE]... -Try 'grep --help' for more information. +and then select your ttyport, depending on which you have wired your RFM69HCW to (CE0 on RPi pin 24 will be `/dev/spidev0.0`, CE1 on RPi pin 26 will be `/dev/spidev0.1`): +``` +3) RFM69HCW on /dev/spidev0.0 (walrus) +4) RFM69HCW on /dev/spidev0.1 (radiofruit bonnet) ``` -That means you have probably run the oref-runagain.sh script. Currently, with RFM69HCW, you can't use the runagain script. Please run the interactive setup script (`cd && ~/src/oref0/bin/oref0-setup.sh`). Other option would be you didn't solder diligently enough. Before disassembling and resoldering, try running the interactive script first. It's less work. + + +#### Switch to dev branch for your pi HAT + +If you are here - you should be building a rig with a Pi HAT(recommended) or RFM69HCW (experimental). 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` on a Mac. On a Windows PC with PuTTY, the hostname can be either `yourrigname` or `yourrigname.local`, and the username will be `root`. + +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". + ***************************** @@ -419,25 +370,32 @@ cd ~/Desktop/ touch ssh ``` -When you are done, copy it from your Desktop to the boot drive of your SD card. +When you are done, copy it from your Desktop to the boot drive of your SD card. Now you will need to [boot up your Pi and connect to it](#boot-up-your-pi-and-connect-to-it). #### 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. +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 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 and establish an SSH connection, with username `pi`, to hostname `raspberrypi.local`. +On Windows, use PuTTY and establish an SSH connection, with username `pi`, to hostname `raspberrypi.local`. If you receive a warning that the rig's host key is not yet cached, respond YES to add it. + +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 +curl -s https://raw.githubusercontent.com/openaps/oref0/master/bin/openaps-install.sh > /tmp/openaps-install.sh && 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. @@ -453,3 +411,60 @@ Return to the [setup script page](<../Build Your Rig/step-3-setup-script>) to co **If you are installing to a Pi with a legacy radio (Ti-stick, SliceOfRadio, etc.) - Press enter. [Jump to finishing the installation](<#finish-installation>)** **If you are installing to a newer Pi with a HAT as radio: Do not press enter! [Continue on to Pi-Hat instructions.](<#switch-to-dev-branch-for-your-pi-hat>).** + +#### Finish installation + +First, update npm to the latest version. Run `npm install npm@latest -g`. + +Next, change to the oref0 directory if you are not in it already. Run `cd ~/src/oref0`. + +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. +!["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) + +Once your setup script finishes, **make sure to [watch the pump loop logs](<../Build Your Rig/step-4-watching-log>)** + +**NOTE**: If you are using RFM69HCW as RF module: + +If you have connected your RFM69HCW module as described in [Soldering RFM69HCW](<../Gear Up/pi-based-rigs#soldering>), while running interactive setup use following options: +```Are you using an Explorer Board? [Y]/n n +Are you using an Explorer HAT? [Y]/n n +Are you using mmeowlink (i.e. with a TI stick)? If not, press enter. If so, paste your full port address: it looks like "/dev/ttySOMETHING" without the quotes. +What is your TTY port? /dev/spidev0.0 +Ok, TTY /dev/spidev0.0 it is. + +Would you like to [D]ownload released precompiled Go pump communication library or install an [U]nofficial (possibly untested) version.[D]/U u +You could either build the Medtronic library from [S]ource, or type the version tag you would like to use, example 'v2018.08.08' [S]/ s +Building Go pump binaries from source +What type of radio do you use? [1] for cc1101 [2] for CC1110 or CC1111 [3] for RFM69HCW radio module 1/[2]/3 3 +Building Go pump binaries from source with + radiotags + tags. +``` +after running oref0-setup.sh run the following: +```$ cd ~ && export PATH="$PATH:/usr/local/go/bin" +$ rm -rf ~/go/src/github.com/ecc1 +$ go get -u -v -tags "rfm69 walrus" github.com/ecc1/medtronic/... +$ cp -pruv $HOME/go/bin/* /usr/local/bin/ +$ mv /usr/local/bin/mmtune /usr/local/bin/Go-mmtune +``` +This will help in building the right pump communication libraries. + +* You'll want to also delete the openaps-menu folder to avoid error messages in your logs. `rm -rf ~/src/openaps-menu/` +* If you experience something like this: +```mmtune: radio_locale = WW +2019/01/14 15:14:25 cannot connect to CC111x radio on /dev/spidev0.0 +2019/01/14 15:14:25 cc111x: no response +Usage: grep [OPTION]... PATTERN [FILE]... +Try 'grep --help' for more information. +``` +That means you have probably run the oref-runagain.sh script. Currently, with RFM69HCW, you can't use the runagain script. Please run the interactive setup script (`cd && ~/src/oref0/bin/oref0-setup.sh`). Other option would be you didn't solder diligently enough. Before disassembling and resoldering, try running the interactive script first. It's less work. + diff --git a/docs/docs/Build Your Rig/step-3-setup-script.md b/docs/docs/Build Your Rig/step-3-setup-script.md index d198edde2..141d06e9b 100644 --- a/docs/docs/Build Your Rig/step-3-setup-script.md +++ b/docs/docs/Build Your Rig/step-3-setup-script.md @@ -8,14 +8,13 @@ Log in to your rig and run the following command (aka "the setup script"): `cd && ~/src/oref0/bin/oref0-setup.sh` -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. +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, you likely 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! * 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. @@ -59,9 +58,11 @@ Make sure that at the end of the setup script, your log rotate file is set to `d ## 512 and 712 Pump users only - important extra setup steps -If you have one of the x12 model pumps, you can still successfully use OpenAPS for basic looping (but not some advanced featuers like SMB). You'll need to complete some extra setup tweaks before your loop will be successful, however. +**For releases 0.7.0 and beyond, all of this is done automatically; please skip this step.** -Note: If you have an old rig running oref0 0.5.3 or below, you'll need to follow historical instructions. The instructions below reflect the adjusted oref0-setup.sh in 0.6.0 and beyond, that does some of this work manually. +Note: If you have an old rig running oref0 0.5.3 or below, you'll need to follow historical instructions. The instructions below reflect the adjusted oref0-setup.sh in 0.6.x which does some of this work manually. + +If you have one of the x12 model pumps, you can still successfully use OpenAPS for basic looping (but not some advanced features like SMB). You'll need to complete some extra setup tweaks before your loop will be successful, however. ### Most important step - make sure you said yes (y) in oref0-setup.sh diff --git a/docs/docs/Customize-Iterate/ifttt-integration.md b/docs/docs/Customize-Iterate/ifttt-integration.md index b02255553..a2cba3b87 100644 --- a/docs/docs/Customize-Iterate/ifttt-integration.md +++ b/docs/docs/Customize-Iterate/ifttt-integration.md @@ -8,7 +8,7 @@ You can also create desktop widgets on your Android device to directly enter dat **Note for iPhone users** In June 2018 Apple released iOS 12 which renamed Workflow to Shortcuts and unfortunately removed the IFTTT integration. You can however achieve the same result of a button press on an iPhone sending -instructions to your Nightscout site by following the [iPhone Shortcuts Integration](https://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/iPhone%20Shortcuts%20Integration.html) instructions. +instructions to your Nightscout site by following the [iPhone Shortcuts Integration](<./iPhone Shortcuts Integration>) instructions. ## IFTTT Setup for phones diff --git a/docs/docs/Customize-Iterate/useful-mobile-apps.md b/docs/docs/Customize-Iterate/useful-mobile-apps.md index 73c749a3c..1c2030b53 100644 --- a/docs/docs/Customize-Iterate/useful-mobile-apps.md +++ b/docs/docs/Customize-Iterate/useful-mobile-apps.md @@ -4,7 +4,7 @@ Beyond just services, such as IFTTT and Papertrail, there are times where your m ## IP address of rig -In order to connect to your rig wirelessly, sometimes you'll need it's IP address. There's several places you can get your rig's IP address if you aren't currently logged in, including: +In order to connect to your rig wirelessly, sometimes you'll need its IP address. There's several places you can get your rig's IP address if you aren't currently logged in, including: * Papertrail through doing a search for `network` and reading the rig's private IP address * Logging into your home router, if rig is on your home network diff --git a/docs/docs/Gear Up/CGM.md b/docs/docs/Gear Up/CGM.md index aba45d985..881e52e88 100644 --- a/docs/docs/Gear Up/CGM.md +++ b/docs/docs/Gear Up/CGM.md @@ -3,7 +3,7 @@ OpenAPS currently primarily supports these different CGM systems: * the Dexcom G4 Platinum system (with or without the Share functionality), * the Dexcom G5 system * the Dexcom G6 system -* the older Medtronic CGM system (MiniMed Paradigm REAL-Time Revel or Enlite), +* the older [Medtronic CGM system](https://www.medtronicdiabetes.com/treatments/continuous-glucose-monitoring) (MiniMed Paradigm REAL-Time Revel or Enlite), * and other CGM or CGM-like devices (Abbott's FreeStyle Libre) if the data is uploaded to Nightscout and the OpenAPS rig has Internet connectivity. ### Using a Dexcom CGM diff --git a/docs/docs/Gear Up/edison-explorer-board.md b/docs/docs/Gear Up/edison-explorer-board.md index cc552e572..bd2c47dbe 100644 --- a/docs/docs/Gear Up/edison-explorer-board.md +++ b/docs/docs/Gear Up/edison-explorer-board.md @@ -52,6 +52,8 @@ The connections between the LiPo battery and its red and black wires are fragile We recommend an Explorer Board with a built-in radio ([see above](<#explorer-board-block>)), because if you get an Explorer Board, you don't need an additional radio stick or CC-Debugger. +The following options are not yet documented for oref0 versions < 0.7.0, and may not work anymore: + If you don't use an Explorer board, you can use a number of radio sticks: a [TI-USB-Sticks](http://www.ti.com/tool/cc1111emk868-915), running [subg_rfspy](https://github.com/ps2/subg_rfspy); [Wireless Things ERF](https://www.wirelessthings.net/erf-0-1-pin-spaced-radio-module); [Wireless Things Slice of Radio](https://www.wirelessthings.net/slice-of-radio-wireless-rf-transciever-for-the-raspberry-pi) a Slice of Radio; or a Rileylink. For details about setup with these other stick and board options, [the best instructions will be found in the mmeowlink wiki](https://github.com/oskarpearson/mmeowlink/wiki) for setting up your board and stick. Note you may also need a CC debugger for these, and also note that it will be more work as the documentation is designed for the Edison/Explorer Board setup as the easiest path forward. ### USB Cables diff --git a/docs/docs/Gear Up/edison.md b/docs/docs/Gear Up/edison.md index d1bf3ff9e..0d7485e32 100644 --- a/docs/docs/Gear Up/edison.md +++ b/docs/docs/Gear Up/edison.md @@ -43,7 +43,7 @@ An 8 GB SD card should provide plenty of space for the linux operating system, O #### Note about Pi+HAT cases Because we are still optimizing the software to be as power-efficient as possible, we have not narrowed down on the best recommended battery. You may want to use a soft case for ease of access to the components, flexible arrangement and the ability to use a variety of battery sizes. If you are using the 2000 mAh battery above, you can use this [3d printed hard case](https://www.thingiverse.com/thing:3010231) to protect the rig and battery in a relatively compact package. The [design is built in OnShape](https://cad.onshape.com/documents/74459dfcb527ad12c33660aa/w/2be92a72bb7f1c83eb091de2/e/b4fa9c3be204ffa3dea128a1), which has a free access level subscription for public domain documents. You can make a copy and tweak the design to your liking. -Alternatives 3d printed cases for Pi0+HAT include this [hard case with room for 2x2000 mAh Li-Po batteries](https://www.thingiverse.com/thing:3038806/) and this [hard case with room for 2x18650 batteries (6800 mAh total, 86x77x25mm)](https://www.thingiverse.com/thing:3502320/). +Alternative 3d printed cases for Pi0+HAT include this [hard case with room for 2x2000 mAh Li-Po batteries](https://www.thingiverse.com/thing:3038806/) and this [hard case with room for 2x18650 batteries (6800 mAh total, 86x77x25mm)](https://www.thingiverse.com/thing:3502320/). *** @@ -179,7 +179,7 @@ When prompted in oref0-setup.sh, you will need to select the "TI Stick (SPI-conn The high level parts list (see below for more details, and links): -* [Explorer Board Block](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#explorer-board-block) +* [Explorer Board Block]<#explorer-board-block> * [Edison](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#edison) * [Nuts and Bolts to attach the Edison to the Explorer Board Block](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#nuts-and-bolts) * [At least one Lithium battery](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#lithium-ion-polymer-lipo-battery-or-other-battery-supply) diff --git a/docs/docs/Gear Up/pi-based-rigs.md b/docs/docs/Gear Up/pi-based-rigs.md index 400cd8ab5..4120e610e 100644 --- a/docs/docs/Gear Up/pi-based-rigs.md +++ b/docs/docs/Gear Up/pi-based-rigs.md @@ -16,7 +16,7 @@ As of April 2018, there is be a Pi+HAT rig as an option for closing the loop wit ### PI You also need a Raspberry Pi. Many users are opting for the "Raspberry Pi Zero WH" - with headers - so you don't have to solder, and can simply add the HAT onto the Pi. See this [PiZeroWH from Adafruit](https://www.adafruit.com/product/3708), or [from other sellers around the world](https://www.raspberrypi.org/products/#buy-now-modal) -As an alternative, you can also use the HAT with a Raspberry Pi 3. +As an alternative, you can also use the HAT with a Raspberry Pi 2/3/4. ### Battery Lipo batteries are typically used to power the rig on the go because they charge quickly and come in a variety of compact sizes. When choosing a battery, you have a trade-off between a larger battery with longer duration or a smaller battery with shorter duration that is easier to carry around. A 2000 mah battery is roughly the size of the Raspberry Pi0, and can last around 4 hours. You'll want a "1S" type, which uses a single cell and outputs at 3.7 VDC. It needs a JST connector to plug into the Raspberry Pi. See this [battery from HobbyKing](https://hobbyking.com/en_us/turnigy-2000mah-1s-1c-lipoly-w-2-pin-jst-ph-connector.html?___store=en_us). @@ -28,8 +28,11 @@ If you will need to run longer than that while unplugged from wall power, consid ### SD card An 8 GB SD card should provide plenty of space for the linux operating system, OpenAPS code and storage for log files. The ability to use larger and removable storage is one of the advantages of the Raspberry Pi. You can get a [MicroSD card and adapter from Adafruit](https://www.adafruit.com/product/2692) when you order your Pi and Hat. Or you can get an equivalent [8 GB SD card from Amazon](https://www.amazon.com/Kingston-microSDHC-Class-Memory-SDC4/dp/B00200K1TS/ref=sr_1_8?s=wireless&ie=UTF8&qid=1532090813&sr=1-8&keywords=8gb+micro+sd) or other sellers. -### Note about Pi+HAT cases -Because we are still optimizing the software to be as power-efficient as possible, we have not narrowed down on the best recommended battery. You may want to use a soft case for ease of access to the components, flexible arrangement and the ability to use a variety of battery sizes. If you are using the 2000 mah battery above, you can use this [3d printed hard case](https://www.thingiverse.com/thing:3010231) to protect the rig and battery in a relatively compact package. The [design is built in OnShape](https://cad.onshape.com/documents/74459dfcb527ad12c33660aa/w/2be92a72bb7f1c83eb091de2/e/b4fa9c3be204ffa3dea128a1), which has a free access level subscription for public domain documents. You can make a copy and tweak the design to your liking. +#### Note about Pi+HAT cases + +Because we are still optimizing the software to be as power-efficient as possible, we have not narrowed down on the best recommended battery. You may want to use a soft case for ease of access to the components, flexible arrangement and the ability to use a variety of battery sizes. If you are using the 2000 mAh battery above, you can use this [3d printed hard case](https://www.thingiverse.com/thing:3010231) to protect the rig and battery in a relatively compact package. The [design is built in OnShape](https://cad.onshape.com/documents/74459dfcb527ad12c33660aa/w/2be92a72bb7f1c83eb091de2/e/b4fa9c3be204ffa3dea128a1), which has a free access level subscription for public domain documents. You can make a copy and tweak the design to your liking. + +Alternative 3d printed cases for Pi0+HAT include this [hard case with room for 2x2000 mAh Li-Po batteries](https://www.thingiverse.com/thing:3038806/) and this [hard case with room for 2x18650 batteries (6800 mAh total, 86x77x25mm)](https://www.thingiverse.com/thing:3502320/). #### Putting together and using your Pi/HAT rig @@ -99,6 +102,132 @@ The rig can be charged via microUSB. Like an Edison rig, you can use a single ce **2nd Note:** make sure the battery plug is switched to ON while the rig is plugged. Otherwise the battery won't charge. +## Hardware information for Pi-based setups with RFM69HCW (experimental) + +This Pi + RFM69HCW is still experimental! + +If you are a maker person or a bit into soldering electronics at least, you may also build your rig with a piece of hardware, that is a lot cheaper than the Explorer HAT, although it does **not** have the screen. You also won't have LEDs indicating status, no battery charging and there will not be (m)any 3d printable case models. If it's your only option because you're on a budget and can't afford to spend 150 bucks on a rig, please think about this step twice. This one will cost you only 30, but a lot of extra time. + +
+ +Click here to expand and see pictures of a rig with a Pi0WH and RFM69HCW:: +
+ +![Picture of RPI0WH with FM69HCW connected via breadboard](../Images/build-your-rig/RPi_breadboard_connected_to_RFM69HCW.jpg) + +![Picture of RPI0WH with FM69HCW view from the top ](../Images/build-your-rig/RPi_soldered_RFM69HCW_top_view.jpg) + +![Picture of RPI0WH with FM69HCW view of soldered connections](../Images/build-your-rig/RPi_soldered_RFM69HCW.jpg) + +![Picture of RPI0WH with FM69HCW and case](../Images/build-your-rig/RPi_open_case_with_battery_view_on_RFM69HCW.jpg) + +Here's a rough-and-ready budget version of a rig put together: contents of a 2000mAh powerbank, a plastic housing, a micro USB cable and some more soldering and hot glue. BE AWARE that this case will most likely overheat the Pi after a while. You need to at least drill some venting holes into the lid. + +![Picture of the RPI0WH with case](../Images/build-your-rig/RPi_open_case_with_Pi_on_top.jpg) +![Picture of the RPI0WH with case open and a view of the battery](../Images/build-your-rig/RPi_open_case_with_battery_view_on_RFM69HCW.jpg) +![Picture of the RPI0WH with case next to the pump](../Images/build-your-rig/Rig_case_with_pump.jpg) + +
+ +### Summary of what you need: +* Raspberry Pi Zero +* RFM69HCW +* [microSD Card]((http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#sd-card)) +* Bread board +* Jumper wires +* Soldering iron +* Power source via Micro USB + +### The Raspberry Pi Zero + +For this setup, you want a Raspberry Pi Zero WH. (The "H" means it has Header pins). (Also, a regular Raspberry Pi 3 model B works fine.) + +### RFM69HCW +You can buy this board e.g. [here](https://www.adafruit.com/product/3070), but you can really buy it wherever you want. These boards are, like the RPi Zero, very common. Just make sure you get the right frequency. 868/915 MHz is correct. All others are wrong. + +### Breadboard +Any breadboard will do, no special requirements. + +### Soldering +You need to solder the pin stripe into the RFM69HCW. Insert the pin stripe from the bottom of the board, with the short endings reaching through the holes. Fixate a bit, so you can rest the soldering iron tip on the pins and the board. + +Solder the included pin stripe diligently into the 9 holes named +VIN GND EN G0 SCK MISO MOSI CS RST + +Cut an antenna at your preferred length corresponding to your frequency. This can be a simple piece of isolated, unshielded wire. (I simply took one of the jumper wires for my first try.) +Calculate your length here: https://m0ukd.com/calculators/quarter-wave-ground-plane-antenna-calculator/ and just use the value from A (first green box). This should be the length of your antenna, from the soldering point on the board to the tip. + +Solder it to the board. It's the hole near the "o" from Radio. Make sure to not connect the soldering to the ground plates left and right from the hole. This antenna is really only connected to the one hole. + +This is your connection scheme for the RPi to RFM69HCW. Stick the RFM69HCW on a bread board, and connect: + +Board | Connect | Connect | Connect | Connect | Connect | Connect | Connect | Connect +------|------|------|------|------|------|------|------|------ +RPi | 3.3V | GND | MOSI | MISO | SCLK | | CE1_N || +RPi PIN | 17 | 25 | 19 | 21 | 23 | 15 | 26 | 22 +RFM69HCW | VIN or 3.3V | GND | MOSI | MISO | SCK or CLK | G0 or DIO0 | CS or NSS | RST or RESET + +![Picture of RPI0WH with FM69HCW connection diagram](../Images/build-your-rig/rpii2RFM69HCW.JPG) + +[See more info here](https://github.com/ecc1/rfm69/blob/master/README.md). + +After that, you're ready to install OpenAPS. + +*** + +## Hardware information for Pi-based setups with the Adafruit RHM69HCW Bonnet + +Summary of what you need for a Pi/Bonnet rig: +* [Explorer HAT](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#Bonnet) +* [Pi0WH (recommended) or Pi 3](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#pi) +* [Antenna](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#antenna) +* [SD Card](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#sd-card) + +#### Bonnet: + +There is be a Pi+Bonnet rig as an option for closing the loop with OpenAPS. This hardware is available from Adafruit, and is called the [Adafruit RFM69HCW Transceiver Radio Bonnet - 868 or 915 MHz - RadioFruit](https://www.adafruit.com/product/4072). As of October 2019, this hardware is supported via automated setup via `oref0-setup.sh`. + +#### PI +You also need a Raspberry Pi. Many users are opting for the "Raspberry Pi Zero WH" - with headers - so you don't have to solder, and can simply add the HAT onto the Pi. See this [PiZeroWH from Adafruit](https://www.adafruit.com/product/3708), or [from other sellers around the world](https://www.raspberrypi.org/products/#buy-now-modal) + +As an alternative, you can also use the bonnet with a Raspberry Pi 2/3/4. + +#### Antenna + +The bonnet does not come with an antenna, so you will need to purchase (or make) one. The end connector needs to be of the u.fl type, and the antenna length that you need will be determined by the frequency on which that your pump operates. The following antennas work well for either 868MHz (WW) or 915MHz (NA): + +[Slim Sticker-type GSM/Cellular Quad-Band Antenna - 3dBi uFL](https://www.adafruit.com/product/1991) + +[900Mhz Antenna Kit - For LoPy, LoRa, etc](https://www.adafruit.com/product/3340) + +#### SD card +An 8 GB SD card should provide plenty of space for the linux operating system, OpenAPS code and storage for log files. The ability to use larger and removable storage is one of the advantages of the Raspberry Pi. You can get a [MicroSD card and adapter from Adafruit](https://www.adafruit.com/product/2692) when you order your Pi and Hat. Or you can get an equivalent [8 GB SD card from Amazon](https://www.amazon.com/Kingston-microSDHC-Class-Memory-SDC4/dp/B00200K1TS/ref=sr_1_8?s=wireless&ie=UTF8&qid=1532090813&sr=1-8&keywords=8gb+micro+sd) or other sellers. + +#### Optional - case for the bonnet +There is one 3D printable case [available on thingiverse](https://www.thingiverse.com/thing:3656500), where Raspberry Pi Zero fits with the bonnet. + +*** + +## Hardware information for Pi-based setups with rewired TI-stick + +This hardware setup is **not recommended unless you already have a USB TI stick** and want to continue using it with 0.7.0. This part of the documentation is a work-in-progress and as of 11/9/2019 not fully tested -- if you can help with this, we would appreciate it very much! + +You will need a CC-Debugger to re-flash your TI stick with an SPI-compatible firmware, [located here](https://github.com/ps2/subg_rfspy/releases). Any of the v0.8 `spi1_alt2` versions should work. + +You will also need jumpers to wire your TI stick to the Raspberry Pi's GPIO header in the following configuration: +``` +SPI0 CS0 (Pi pin 24) -> debug pin 5 +SPI0 CLK (Pi pin 23) -> debug pin 6 +SPI0 MISO (Pi pin 21) -> debug pin 8 +SPI0 MOSI (Pi pin 19) -> debug pin 10 +any Pi 3.3V pin -> debug pin 2 +any Pi ground pin -> debug pin 1 +GPIO 4 (Pi pin 7) -> debug pin 7 +``` + +When prompted in oref0-setup.sh, you will need to select the "TI Stick (SPI-connected)" option. + + *** diff --git a/docs/docs/Gear Up/pump.md b/docs/docs/Gear Up/pump.md index 3602800d8..f4efb8daf 100644 --- a/docs/docs/Gear Up/pump.md +++ b/docs/docs/Gear Up/pump.md @@ -25,7 +25,7 @@ A double-check for pump compatibility is to look for the ABSENCE of PC connect i * If "PC Connect" is absent, then the pump should be able to receive temp basal commands and be compatible. * If there is no "Connect Devices" menu, then the pump should be able to receive temp basal commands and be compatible. * This is the case for the 512/712, the 515/715 and 522/722 models. - * For 512/712 pumps, certain commands like Read Settings, BG Targets and certain Read Basal Profile are not available, and require creating special files for the missing info to successfully run the loop ([Instructions for 512/712 users, click here](<../Build Your Rig/step-3-setup-script#512-and-712-pump-users-only-important-extra-setup-steps>)). 512/712 users are not going to be able to use an advanced feature - (e)SMB - but will be able to do basic looping. + * For 512/712 pumps, you will not be able to use an advanced feature (SMB) but will be able to do basic temp-basal based looping. Note that not _all_ possible sellers of pumps will accuratly describe the model number: if they are willing to sell a pump they may not have interest in setting it up for looping, and the distinctions about model numbers and firmware version may not be important to them. It will be for you though! Therefore, it's prudent to verify the model by seeing pctures and/or videos of the pump in action. diff --git a/docs/docs/Gear Up/rig-options.md b/docs/docs/Gear Up/rig-options.md index 32e20279d..38046d773 100644 --- a/docs/docs/Gear Up/rig-options.md +++ b/docs/docs/Gear Up/rig-options.md @@ -1,11 +1,17 @@ # Your rig hardware options -You have two main options for hardware: +You have several options for hardware: 1. The most recommended rig has been an Edison + Explorer Board. Unfortunately Intel stopped making the Edison boards as of 2018. If you can find an Intel Edison (eBay, local stores, etc - this is still very possible), this is still a highly recommmended rig. It is the smallest rig (and easily portable), with better battery life because it is power efficient. [Go here for the list of hardware and setup instructions for Edison setups](<../Gear Up/edison-explorer-board>). 2. The other option is a Raspberry Pi-based setup, with the new Explorer HAT. This rig setup makes it easier to see information when offline because it has an onboard screen for displaying readouts. [Go here for hardware required and setup instructions for Pi/HAT setups](<../Gear Up/pi-based-rigs>). There is also an experimental alternative to an Explorer HAT, RFM69HCW, which can serve as the radio on a Pi-based rig, but will not have the screen, and requires you to solder. +`3.` Yet another option is a Raspberry Pi-based setup, with an Adafruit RFM69HCW Bonnet. This rig setup makes it easier to see information when offline because it has a small onboard screen for displaying readouts, but it does not come with charging hardware for a battery like the Explorer HAT or Explorer Board. You will need to build your own charging circuit or use a USB power block if you want to make this rig portable. However, this makes an excellent stationary or backup rig! [See below for the list of hardware required for Pi/Bonnet setups](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-the-adafruit-rfm69hcw-bonnet>). + +`4.` (Not recommended, but supported) There is an experimental alternative to prefabricated hardware on the Raspberry Pi (Explorer HAT or Adafruit Bonnet), which can serve as the radio on a Pi-based rig, but will not have the screen and requires you to solder. [See here for the list of hardware required for more details on a setup with RFM69HCW breakout board](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-rfm69hcw-experimental>). + +`5.` (Not recommended, but supported) If you *already have* a USB TI stick (from an older rig build), you can continue using it in 0.7.0 if you reflash it with new firmware and wire it to the SPI header on the Raspberry Pi. [See here for the instructions on how to re-flash and re-wire your TI stick](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-rewired-TI-stick>). + ## What happens if you have multiple rigs? If you have multiple OpenAPS rigs, they’re built to be polite to each other. Even if you had two or more rigs in same room, they won’t trip each other up. They “wait for silence” before issuing any commands to the pump. By having multiple rigs throughout a house, you can move from room-to-room without carrying rigs because the rigs will pass-off comms as you moves in and out of the rig’s range. Stationary rigs will not need LiPo batteries and can be plugged directly into a wall charger from the Explorer board. diff --git a/docs/docs/Troubleshooting/Carelink.md b/docs/docs/Troubleshooting/Carelink.md index fe46bd17a..bd1047b42 100644 --- a/docs/docs/Troubleshooting/Carelink.md +++ b/docs/docs/Troubleshooting/Carelink.md @@ -2,7 +2,7 @@ **Note:** Generally, the Carelink stick is no longer supported. We *highly* recommend moving forward with a different radio stick. See [the hardware currently recommended in the docs](<../Gear Up/rig-options>), or ask on Gitter. -The `model` command is a quick way to verify whether you can communicate with the pump. Test this with `openaps use model` (after you do a `killall -g oref0-pump-loop`). +The `model` command is a quick way to verify whether you can communicate with the pump. Test this with `openaps use model` (after you do a `killall-g oref0-pump-loop`). If you can't get a response, it may be a range issue. The range of the CareLink radio is not particularly good, and orientation matters; see [range testing report](https://gist.github.com/channemann/0ff376e350d94ccc9f00) for more information. diff --git a/docs/docs/Troubleshooting/Common-error-messages.md b/docs/docs/Troubleshooting/Common-error-messages.md index b57061e22..fbffe6fdb 100644 --- a/docs/docs/Troubleshooting/Common-error-messages.md +++ b/docs/docs/Troubleshooting/Common-error-messages.md @@ -74,7 +74,7 @@ Or (on an intel edison): `cannot connect to CC111x radio on /dev/spidev5.1` Basic steps using an Intel Edison with Explorer Board or a Raspberry Pi with Explorer HAT: - * checking with `killall -g oref0-pump-loop; openaps mmtune` to see if it is resolved yet + * checking with `cd ~/myopenaps && sudo service cron stop && killall -g openaps ; killall-g oref0-pump-loop; oref0-mmtune && sudo service cron start` to see if it is resolved yet * Make sure the Explorer board or HAT has not become loose and is sitting correctly on the Edison board or Pi * Check that your rig is in close range of your pump * Check that your pump battery is not empty @@ -112,7 +112,7 @@ wget https://github.com/EnhancedRadioDevices/subg_rfspy/releases/download/v0.8-e ./ccprog -p 16,18,7 write spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex ``` - * Reboot, and try `killall -g oref0-pump-loop; openaps mmtune` to make sure it works + * Reboot, and try `cd ~/myopenaps && sudo service cron stop && killall -g openaps ; killall-g oref0-pump-loop; oref0-mmtune && sudo service cron start` to make sure it works ## Dealing with npm run global-install errors diff --git a/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md b/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md index cebe839e7..778f02087 100644 --- a/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md +++ b/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md @@ -45,7 +45,6 @@ Make sure to check through the following list before asking on Gitter if your se * Check and make sure your receiver is >50% charged (if battery low, it may drain the rig battery and prevent it from operating). * A reboot may be required after running oref0-setup if the Carelink is unable to communicate with the pump (e.g. you see "Attempting to use a port that is not open" errors in pump-loop.log). Additional Carelink troubleshooting steps can be found in [Dealing with the CareLink USB Stick](<../Troubleshooting/carelink>). * If you see the error `failed to get string preference .pump_serial`, that usually means you copied your preferences over or ran runagain, instead of following the directions and using the full interactive setup script, when upgrading to a new version/installing a new version (such as going from 0.6.x to 0.7.0). To resolve, run `oref0-setup.sh` manually per the [directions](<../Customize-Iterate/update-your-rig#step-2-re-run-oref0-setup>). (*This means you'll enter your responses into the interactive setup script again*.) -* 512/712 users - make sure you follow the additional instructions for the 512/712 before asking for help troubleshooting. You have a few additional steps you need to do. ## Running commands manually to see what's not working from an oref0-setup.sh setup process diff --git a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md index c7bc16fd4..c0fd998ef 100644 --- a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md +++ b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md @@ -9,9 +9,40 @@ There are several ways to communicate with other participants and contributors i ### Slack There is a [Slack channel](https://omniapsslack.azurewebsites.net/) that you can add yourself to - then look for the `#OpenAPS` channel to post questions. This is the best place to get real-time support with anything related to OpenAPS. It is a great place to introduce yourself and get some help from those who are a few steps further down the road. That slack can also be used to stay up to date on other, broader DIY diabetes projects such as communication around other pumps that are being explored and worked on, but aren't yet DIY loopable. (Here's [why we often recommend asking questions in an archived community space, written when the primary place to go for support was Gitter instead of Slack](https://diyps.org/2016/08/17/why-you-should-post-questions-in-gitter/).) -#### Posting logs +### Google Group +A google group focused on #OpenAPS development work can be found [here](https://groups.google.com/d/forum/openaps-dev) - everyone is encouraged and welcome to join! You can add yourself directly to the group. It's worth setting your preferences to receive all email from the group; there's not a huge volume, and this is one of the ways we share updates about hardware or release announcements if you're not hanging out on Gitter or Facebook or Twitter. However, please note that troubleshooting questions about rig setups are best posted to Slack - email tends to be slower and you will likely be redirected to another channel if you're actively working to resolve a setup problem. + +### Gitter +[Gitter](https://gitter.im/) is a messaging/chat service similar to IRC. It provides integration with GitHub and several other services. It's the best place to get real-time support with anything related to OpenAPS. (Here's [why we often recommend asking questions on Gitter](https://diyps.org/2016/08/17/why-you-should-post-questions-in-gitter/).) + +* The [nightscout/intend-to-bolus]( https://gitter.im/nightscout/intend-to-bolus) channel is where you will find active #OpenAPS discussions ranging from technical issues with openaps tools to control theory to general information. +* For Autotune conversations, use the [openaps/autotune channel](https://gitter.im/openaps/autotune) +* Searching: Note that Gitter has a search function to find old information, but since it isn't threaded conversations, you may need to spend some time reading the posts after the search result to find the ultimate resolution to the question. So, if you find a particularly useful bit of information that you couldn't find in the docs...please make a [PR to the docs](<../Resources/my-first-pr>) so that the information is permanently stored for others to find. + + The [nightscout/intend-to-bolus]( https://gitter.im/nightscout/intend-to-bolus) channel is where you will find active #OpenAPS discussions ranging from technical issues with openaps tools to control theory to general information. It is a great place to introduce yourself and get some help from those who are a few steps further down the road. +* For Autotune conversations, use the [openaps/autotune channel](https://gitter.im/openaps/autotune) + +
+ Click here to expand a list of tips for using Gitter, from using the search function to tagging someone to posting screenshots or posting logs +
+ +**Search** +Gitter has a search function to find old information, but since it isn't threaded conversations, you may need to spend some time reading the posts after the search result to find the ultimate resolution to the question. So, if you find a particularly useful bit of information that you couldn't find in the docs...please make a [PR to the docs](http://openaps.readthedocs.io/en/latest/docs/Resources/my-first-pr.html) so that the information is permanently stored for others to find. + +**Tag/mention someone** +Tag someone! You can tag particular people if you are responding to them directly by using the `@` symbol and then typing their username. This will help notify the person that you are "speaking to them". If someone asks you for information that shouldn't be shared in the public channel, you can also private message people by hovering over their profile picture and choosing the "chat privately" button. Please do not abuse the tagging or PM features: most questions are best asked untagged in the appropriate channel, so that anyone can respond to them as soon as they read Gitter and see the question. There are people from all over the world online at all hours who can help with most kinds of questions, and the core developers usually read every message in Gitter a few times per day and try to answer any questions that got missed. -Posting copy-paste output from your rig is also another valuable activity for troubleshooting. To post a single line of information, you can use the single-backtick-quote that is found on the key to the left of the number 1 key on the keyboard. (hint: it is under the ~ on the same key). You can also long-press the single quote key on your iPhone keypad to bring up the single-backtick-quote that will work in Gitter. If you start and stop a portion of your text with those single quotes, it will `look like this`. +![Gitter PM sample](../Images/gitter_pm.jpg) + +**Posting photos or screenshots in Gitter** + +Gitter has a mobile app which works great for posting text, but does not allow for posting images directly. If you need to post a photo using the mobile app, you'll have to host your photo file somewhere like Dropbox and post the link to the file location. + +Using the desktop application, you can simply drag and drop the file into the Gitter chat window. The file will upload and then display in the chat thread after a short period of time to upload. + +**Posting logs** + +Posting copy-paste code from your rig is also another valuable activity for troubleshooting. To post a single line of information, you can use the single-backtick-quote that is found on the key to the left of the number 1 key on the keyboard. (hint: it is under the ~ on the same key). You can also long-press the single quote key on your iPhone keypad to bring up the single-backtick-quote that will work in Gitter. If you start and stop a portion of your text with those single quotes, it will `look like this`. Posting multiple lines of copy-paste from your rig will also sometimes be needed. You can do that by: @@ -21,17 +52,11 @@ Posting multiple lines of copy-paste from your rig will also sometimes be needed * press `control-enter` again to get another new line * enter 3 single quotes to end the section -The copy-pasted lines should have 3 backticks on the line above and the line below. Using this format helps troubleshooters read your information easier than unformatted copy and paste. +The copy-pasted lines should have 3 backticks on the line above and the line below. The example below shows, on the bottom, how the formatted text yielded the black box of text in Gitter. Using this format helps troubleshooters read your information easier than unformatted copy and paste. -### Google Group -A google group focused on #OpenAPS development work can be found [here](https://groups.google.com/d/forum/openaps-dev) - everyone is encouraged and welcome to join! You can add yourself directly to the group. It's worth setting your preferences to receive all email from the group; there's not a huge volume, and this is one of the ways we share updates about hardware or release announcements if you're not hanging out on Gitter or Facebook or Twitter. +![Gitter tickmarks](../Images/gitter_marks.jpg) -### Gitter -[Gitter](https://gitter.im/) is a messaging/chat service similar to IRC. It provides integration with GitHub and several other services. This has been replaced by the Slack channel, but the history on Gitter may still have relevant answers. - -* The [nightscout/intend-to-bolus]( https://gitter.im/nightscout/intend-to-bolus) channel is where you will find active #OpenAPS discussions ranging from technical issues with openaps tools to control theory to general information. -* For Autotune conversations, use the [openaps/autotune channel](https://gitter.im/openaps/autotune) -* Searching: Note that Gitter has a search function to find old information, but since it isn't threaded conversations, you may need to spend some time reading the posts after the search result to find the ultimate resolution to the question. So, if you find a particularly useful bit of information that you couldn't find in the docs...please make a [PR to the docs](<../Resources/my-first-pr>) so that the information is permanently stored for others to find. +
### Facebook diff --git a/docs/docs/Usage and maintenance/monitoring-OpenAPS.md b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md index d9db8a6da..333dcb1cd 100644 --- a/docs/docs/Usage and maintenance/monitoring-OpenAPS.md +++ b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md @@ -333,20 +333,18 @@ If your loop is failing, lights are staying on, and you see repeated error messa ## Apache-chainsaw ![Apache picture](../Images/apache_chainsaw.jpg) If your computer and rig are on the same wifi network you can use Apache Chainsaw2 from a pc (running windows/mac/linux) to watch your logs. Chainsaw2 main advantages are: -1) Easy setup. -1) Strong filtering capabilities. -1) Strong finding capabilities. -1) Coloring capabilities. -1) Adding marker capabilities. -1) Logs can be searched for a long time (kept localy on the rig). -1) Can tail new data. - -example picture: +* Easy setup. +* Strong filtering capabilities. +* Strong finding capabilities. +* Coloring capabilities. +* Adding marker capabilities. +* Logs can be searched for a long time (kept localy on the rig). +* Can tail new data. ### To setup apache chainsaw on your computer, follow the following instructons: 1) Download the following version of apache chainsaw from here: https://github.com/tzachi-dar/logging-chainsaw/releases/download/2.0.0.1/apache-chainsaw-2.0.0-standalone.zip (please note this version was changed to fit the openaps project, other releases of appach chainsaw will not work with a rpii). -1) Unzip the file. -1) On your pc, create a configuration file called openaps.xml with the following data (for example notepad openaps.xml): +2) Unzip the file. +3) On your pc, create a configuration file called openaps.xml with the following data (for example notepad openaps.xml): ``` @@ -373,17 +371,17 @@ example picture: ``` Make sure to replace the password, with your rig's password, and 192.168.1.20 with the ip/hostname of your rig. 1) run chainsaw by the command: bin\chainsaw.bat (pc) or bin/chainsaw (linux and mac) -1) From the file menu choose 'load chainsaw configuration' -1) Choose use chainsaw configuration file. -1) press open file. -1) choose the file openaps.xml -1) (optional) mark the checkbox "always start chainsaw with this configuration." +2) From the file menu choose 'load chainsaw configuration' +4) Choose use chainsaw configuration file. +5) press open file. +6) choose the file openaps.xml +7) (optional) mark the checkbox "always start chainsaw with this configuration." Chainsaw has a welcome tab and a good tutorial, use them. Still here are a few highlights: -1) To see only pump-loop you can either select 'focus on openaps.pump-loop.log' or on the refine focus on field enter 'logger==openaps.pump-loop' -1) To filter only messages that contain the words 'autosens ratio' enter on the 'refine focus' logger==openaps.pump-loop && msg~='autosens ratio' -1) To highlight lines that contain 'refine focus', enter msg~='autosens ratio' on the find tab. +* To see only pump-loop you can either select 'focus on openaps.pump-loop.log' or on the refine focus on field enter 'logger==openaps.pump-loop' +* To filter only messages that contain the words 'autosens ratio' enter on the 'refine focus' logger==openaps.pump-loop && msg~='autosens ratio' +* To highlight lines that contain 'refine focus', enter msg~='autosens ratio' on the find tab. ******************************** @@ -446,7 +444,7 @@ Once you've installed, you will need to pair the watch to your Edison. * Wait a few seconds, and run it again, until you get `bluetoothd: no process found` returned. Then start it back up again: -`sudo /usr/local/bin/bluetoothd --experimental &` +`sudo bluetoothd --experimental &` * Wait at least 10 seconds, and then run: diff --git a/docs/docs/While You Wait For Gear/collect-data-and-prepare.md b/docs/docs/While You Wait For Gear/collect-data-and-prepare.md index 6657d67d4..d4f138adb 100644 --- a/docs/docs/While You Wait For Gear/collect-data-and-prepare.md +++ b/docs/docs/While You Wait For Gear/collect-data-and-prepare.md @@ -8,8 +8,6 @@ Nightscout is an excellent tool to capture your CGM history, as well as log your By logging and collecting a recent history of your basal, bolus, carb, and BG patterns, you can also take advantage of the Autotune feature which uses Nightscout databases (see below). You can log carbs and boluses using the Nightscout "careportal," and tell it about your basal insulin using a "profile." -If you aren't using Nightscout, you can upload your Dexcom G4 receiver to Dexcom Studio or if you use Dexcom G5 the data is in the cloud at Dexcom Clarity. If you use a Medtronic CGM, upload your CGM data to CareLink. If you use an Animas Vibe, upload your data to Tidepool or Diasend. We suggest you get in the habit of doing this regularly so that you have ongoing data to show trends in your overall estimated average glucose (eAG, a good indicator in trends in A1c) and variations in your "time in range." - Later in these docs is a link to donate your data to a project called [OpenHumans](<../Give Back-Pay It Forward/data-commons-data-donation>). There is no requirement to share your data or participate in OpenHumans. If you choose to, you can donate your data whether you are looping or not. Individuals within the project who share their data do so willingly and you should do the same only if you feel comfortable. ## Practice good CGM habits diff --git a/docs/index.rst b/docs/index.rst index f5973915f..71d88956e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -111,6 +111,7 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of Useful apps for accessing your rig IFTTT and Pebble buttons Offline Looping + iPhone Shortcuts .. toctree:: :maxdepth: 2 From 159d0a323fda20de51ecdd7c25f2252527b72ea7 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sat, 22 Feb 2020 14:39:46 -0500 Subject: [PATCH 03/13] review links --- docs/docs/Build Your Rig/step-2-wifi-dependencies.md | 2 +- docs/docs/Gear Up/CGM.md | 4 ++-- docs/docs/Gear Up/pi-based-rigs.md | 10 +++++----- docs/docs/How it works/understand-determine-basal.md | 2 +- docs/docs/Resources/troubleshooting.md | 8 ++++---- .../communication-support-channels.md | 2 +- 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md index 6d41b24ce..5862fa7e7 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -311,7 +311,7 @@ Once your setup script finishes, **make sure to [watch the pump loop logs](<../B **NOTE**: If you are using RFM69HCW as RF module: -If you have connected your RFM69HCW module as described in [Soldering RFM69HCW](https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#soldering), while running interactive setup use following option: +If you have connected your RFM69HCW module as described in [Soldering RFM69HCW](<../Gear Up/edison#soldering>), while running interactive setup use following option: ``` 3) RFM69HCW (DIY: SPI) ``` diff --git a/docs/docs/Gear Up/CGM.md b/docs/docs/Gear Up/CGM.md index 881e52e88..2d70473f2 100644 --- a/docs/docs/Gear Up/CGM.md +++ b/docs/docs/Gear Up/CGM.md @@ -10,7 +10,7 @@ OpenAPS currently primarily supports these different CGM systems: With Dexcom G4, the Share platform is not required; but is valuable for uploading BG data to the cloud (and into Nightscout, which can then send BGs to the rig). However, without Share, a G4 receiver can instead be plugged in directly to the OpenAPS rig. For Dexcom G5 you can also use a compatible receiver (software upgraded G4 with Share receiver or a G5 Mobile Receiver), or also pull data from the Dexcom Share servers into Nightscout for use with an Internet-connected OpenAPS rig. The same applies for G6 as it does for a G5. -Also note that an easy way to [loop offline](https://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/offline-looping-and-monitoring.html#c-send-g5-or-g6-bgs-direct-to-rig-xdrip-js-lookout-logger) is to choose the `xdrip-js` setup option during `oref0-setup` (in 0.7.0 and later versions) to have the rig pull directly from a G5 or G6 receiver. +Also note that an easy way to [loop offline](<../Customize-Iterate/offline-looping-and-monitoring#c-send-g5-or-g6-bgs-direct-to-rig-xdrip-js-lookout-logger>) is to choose the `xdrip-js` setup option during `oref0-setup` (in 0.7.0 and later versions) to have the rig pull directly from a G5 or G6 receiver. ### Using the Medtronic CGM @@ -28,4 +28,4 @@ Your OpenAPS implementation can also pull CGM data from a Nightscout site in add ### Offline looping options -See [this page for much more detail on all of your offline looping options](https://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/offline-looping-and-monitoring.html) with various CGM types. +See [this page for much more detail on all of your offline looping options](<../Customize-Iterate/offline-looping-and-monitoring>) with various CGM types. diff --git a/docs/docs/Gear Up/pi-based-rigs.md b/docs/docs/Gear Up/pi-based-rigs.md index 4120e610e..f99454205 100644 --- a/docs/docs/Gear Up/pi-based-rigs.md +++ b/docs/docs/Gear Up/pi-based-rigs.md @@ -132,7 +132,7 @@ Here's a rough-and-ready budget version of a rig put together: contents of a 200 ### Summary of what you need: * Raspberry Pi Zero * RFM69HCW -* [microSD Card]((http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#sd-card)) +* [microSD Card](<../Gear Up/edison-explorer-board#sd-card>) * Bread board * Jumper wires * Soldering iron @@ -178,10 +178,10 @@ After that, you're ready to install OpenAPS. ## Hardware information for Pi-based setups with the Adafruit RHM69HCW Bonnet Summary of what you need for a Pi/Bonnet rig: -* [Explorer HAT](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#Bonnet) -* [Pi0WH (recommended) or Pi 3](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#pi) -* [Antenna](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#antenna) -* [SD Card](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#sd-card) +* [Explorer HAT](<#bonnet>) +* [Pi0WH (recommended) or Pi 3](<#pi>) +* [Antenna](<#antenna>) +* [SD Card](<#sd-card>) #### Bonnet: diff --git a/docs/docs/How it works/understand-determine-basal.md b/docs/docs/How it works/understand-determine-basal.md index 474e5a74f..7d7f69e1a 100644 --- a/docs/docs/How it works/understand-determine-basal.md +++ b/docs/docs/How it works/understand-determine-basal.md @@ -55,7 +55,7 @@ These purple lines are helpful in understanding, at a glance, *why* OpenAPS is m ## Understanding the basic logic (written version) -Here is a written explanation of the code that you can explore. For some visual and practical examples, see the [OpenAPS algorithm examples](https://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/Understand-determine-basal.html#openaps-algorithm-examples) section. +Here is a written explanation of the code that you can explore. For some visual and practical examples, see the [OpenAPS algorithm examples](<#openaps-algorithm-examples>) section. The OpenAPS reference design algorithm, oref0, determines insulin dosing based on a number of scenarios that it forecasts with different types of predictions. Two of these scenarios, the “eventual” (eventualBG) and “IOB-based” (IOBpredBGs) ones, attempt to predict BGs in situations without (much) carb absorption. Another scenario, the “zero-temp” (ZTpredBGs) one, attempts to predict the “worst likely case” if observed carb absorption suddenly ceases and if a zero-temp were applied until BG begins rising at/above target. The final two scenarios, the COB-based (COBpredBGs) one and the unannounced meal (UAM)-based (UAMpredBGs) one, attempt to predict how long an observed BG rise will continue, to dose appropriately for announced and unannounced meals, and for anything else that causes a sustained rise in BG. diff --git a/docs/docs/Resources/troubleshooting.md b/docs/docs/Resources/troubleshooting.md index e57b61b00..ee05845bf 100644 --- a/docs/docs/Resources/troubleshooting.md +++ b/docs/docs/Resources/troubleshooting.md @@ -174,7 +174,7 @@ OpenAPS has failed to upload to the configured nightscout website. If you're usi ### No JSON object could be decoded -Usually means the file does not exist. It usually will self-resolve with the next successful pump history read. If it recurs, you will need to [drill down](http://openaps.readthedocs.io/en/latest/docs/Troubleshooting/oref0-setup-troubleshooting.html#running-commands-manually-to-see-what-s-not-working-from-an-oref0-setup-sh-setup-process) to find the area where it is not successfully reading. +Usually means the file does not exist. It usually will self-resolve with the next successful pump history read. If it recurs, you will need to [drill down](<../Troubleshooting/oref0-setup-troubleshooting#running-commands-manually-to-see-what-s-not-working-from-an-oref0-setup-sh-setup-process>) to find the area where it is not successfully reading. ### json: error: input is not JSON ``` @@ -286,13 +286,13 @@ If you're affected by this particular issue, the two LEDs next to the microUSB p **Note:** Starting the Jubilinux flash from the beginning will overwrite everything, so you may want to copy and save any configuration files you don't want to lose, like your `wpa_supplicant.conf` Wi-Fi settings for example. -Instructions to reinstall OpenAPS are [here](https://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#step-1-jubilinux-for-edison-rigs-only) +Instructions to reinstall OpenAPS are [here](<../Build Your Rig/index>) Once you have finished running the OpenAPS setup script, view your loop by entering `l`. Your loop will probably still be failing, but with a different error message: ``` Could not get subg_rfspy state or version. Have you got the right port/device and radio_type? ``` -Now you should be able to follow [the directions above](https://openaps.readthedocs.io/en/latest/docs/Resources/troubleshooting.html?highlight=ccprog#could-not-get-subg-rfspy-state-or-version-ccprog-or-cannot-connect-to-cc111x-radio) to reflash the radio. +Now you should be able to follow [the directions above](<#could-not-get-subg-rfspy-state-or-version-ccprog-or-cannot-connect-to-cc111x-radio>) to reflash the radio. This time the reflash should be successful and you should see: ``` Erasing chip. @@ -308,7 +308,7 @@ You have now successfully reflashed the radio. Now `reboot` and your loop should ## Dealing with the CareLink USB Stick -**Note:** Generally, the Carelink stick is no longer supported. We *highly* recommend moving forward with a different radio stick. See [the hardware currently recommended in the docs](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/hardware.html), or ask on Gitter. +**Note:** Generally, the Carelink stick is no longer supported. We *highly* recommend moving forward with a different radio stick. See [the hardware currently recommended in the docs](<../Gear Up/hardware-overview>), or ask on Gitter. The `model` command is a quick way to verify whether you can communicate with the pump. Test this with `openaps use model` (after you do a `killall-g oref0-pump-loop`). diff --git a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md index c0fd998ef..8e09d8c48 100644 --- a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md +++ b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md @@ -27,7 +27,7 @@ A google group focused on #OpenAPS development work can be found [here](https://
**Search** -Gitter has a search function to find old information, but since it isn't threaded conversations, you may need to spend some time reading the posts after the search result to find the ultimate resolution to the question. So, if you find a particularly useful bit of information that you couldn't find in the docs...please make a [PR to the docs](http://openaps.readthedocs.io/en/latest/docs/Resources/my-first-pr.html) so that the information is permanently stored for others to find. +Gitter has a search function to find old information, but since it isn't threaded conversations, you may need to spend some time reading the posts after the search result to find the ultimate resolution to the question. So, if you find a particularly useful bit of information that you couldn't find in the docs...please make a [PR to the docs](<../Resources/my-first-pr>) so that the information is permanently stored for others to find. **Tag/mention someone** Tag someone! You can tag particular people if you are responding to them directly by using the `@` symbol and then typing their username. This will help notify the person that you are "speaking to them". If someone asks you for information that shouldn't be shared in the public channel, you can also private message people by hovering over their profile picture and choosing the "chat privately" button. Please do not abuse the tagging or PM features: most questions are best asked untagged in the appropriate channel, so that anyone can respond to them as soon as they read Gitter and see the question. There are people from all over the world online at all hours who can help with most kinds of questions, and the core developers usually read every message in Gitter a few times per day and try to answer any questions that got missed. From 95e7059c2180c0e0ef7eecc3eb38eb97de303474 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sat, 22 Feb 2020 16:13:12 -0500 Subject: [PATCH 04/13] finish resolving conflicts and reviewing all changes since September (https://github.com/openaps/docs/compare/af8322ecd17c7a112a8952010ed06ee4e240b160...openaps:master) to ensure they are added --- docs/docs/Build Your Rig/OpenAPS-install.md | 271 ------------ docs/docs/Build Your Rig/index.rst | 9 - .../Build Your Rig/logging-into-rig-serial.md | 2 +- docs/docs/Build Your Rig/pi-install.md | 139 ------ .../step-2-wifi-dependencies.md | 6 +- docs/docs/Gear Up/edison-explorer-board.md | 18 +- docs/docs/Gear Up/edison.md | 282 ------------ docs/docs/Gear Up/rig-options.md | 6 +- .../Resources/Edison-Flashing/mac-flash.md | 401 ------------------ docs/docs/Resources/troubleshooting.md | 319 -------------- .../communication-support-channels.md | 2 +- .../collect-data-and-prepare.md | 2 - .../nightscout-setup.md | 2 +- 13 files changed, 25 insertions(+), 1434 deletions(-) delete mode 100644 docs/docs/Build Your Rig/OpenAPS-install.md delete mode 100644 docs/docs/Build Your Rig/index.rst delete mode 100644 docs/docs/Build Your Rig/pi-install.md delete mode 100644 docs/docs/Gear Up/edison.md delete mode 100644 docs/docs/Resources/Edison-Flashing/mac-flash.md delete mode 100644 docs/docs/Resources/troubleshooting.md diff --git a/docs/docs/Build Your Rig/OpenAPS-install.md b/docs/docs/Build Your Rig/OpenAPS-install.md deleted file mode 100644 index 21318b467..000000000 --- a/docs/docs/Build Your Rig/OpenAPS-install.md +++ /dev/null @@ -1,271 +0,0 @@ -# Installing OpenAPS on your rig - -Getting your rig with OpenAPS takes generally six steps: - -1. Jubilinux installation (called "flashing" the Edison - Pi users can skip to step 2) -2. Getting first wifi network connection -3. Installing "dependencies" (helper code that make all the OpenAPS code function) -4. Installing your OpenAPS loop -5. Watching Pump-loop Log -6. Finish your setup - -* The **first step** may already be done for you if you purchased a pre-flashed Edison board. -* The **second and third steps** are accomplished through what is called the "bootstrap" script. -* The **fourth step** is accomplished through what is called the "setup script". -* The **fifth step** is an important, required step. You need to be familiar with how to read and access your logs. -* The **sixth step** is all the polishing steps to your OpenAPS setup. Things like optimizing your settings, preferences, BT-tethering, IFTTT, etc. - -### Step 1: Jubilinux (for Edison rigs only) - -*Pi users can skip to [step 2](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#steps-2-3-wifi-and-dependencies)* - -If you purchased a pre-flashed Edison, you can also skip on down to [step 2](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#steps-2-3-wifi-and-dependencies). - -If you need to flash your Edison, the directions are slightly different depending on the computer you are using. Please see the [Mac-specific flashing page](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/mac-flash.html) or the [Windows-specific flashing page](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/PC-flash.html) for detailed info on how to flash jubilinux. There is also a more general flashing page [here](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html) that has some good [troubleshooting tips](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html#troubleshooting) at the end of the page, if you flashing stalls out. - -### Steps 2-3: 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. - -### Step 4: 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, you likely 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! - -
- Be prepared to enter the following items (click here to expand list): -
- -* 6-digit serial number of your pump -* 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-go`, `g5`, `g5-upload`, `g6`, `g6-upload`, `mdt`, `xdrip`, and `xdrip-js`. - * The various G4/G5/G6 options are for plugging a physical receiver into the rig with USB. - * If you would like the rig to communicate directly with your G5/G6 transmitter over Bluetooth (most likely in place of a receiver, using Alternate Channel mode), choose xdrip-js. - * Do *not* choose MDT unless you are using an Enlite sensor attached to the pump you're looping with. If you use FreeStyle Libre or Medtronic 640G as a CGM, or any other CGM system that gets its data only from Nightscout, you should choose g4-go, g5, or g6. OpenAPS also attempts to get BG data from your Nightscout. OpenAPS will always use the most recent BG data regardless of the source, so if offline looping is unavailable, if will try to pull from NS, and vice versa. -* 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) - -
- -![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 - -
- Click here to expand notes about checking log rotate, which was fixed in 0.6.1: -
- -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) - -
- -************************** - -## Step 5: Watch your Pump-Loop Log - -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) -
- Click here to expand the explanation of the non-error messages -
- -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-24h-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 4:05am every morning. So if autotune has not yet run, you must wait for that error message to clear out, or run it manually. 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 oref0-pump-loop" and ending with "Completed oref0-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. ([For more details on how to interpret the OpenAPS math and information, see this page for understanding OpenAPS determine-basal](http://openaps.readthedocs.io/en/latest/docs/While%20You%20Wait%20For%20Gear/Understand-determine-basal.html#summary-of-outputs).) - -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? - -
- Expand here for notes: -
- -* 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 - bookmark this section! - -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?" or "what do the logs say?" - -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 (or at 4AM starting from 0.6.0-rc1), 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 other shortcuts: - -``` - --View live logs-- - l => tail -F /var/log/openaps/pump-loop.log - autosens-looplog => tail -n 100 -F /var/log/openaps/autosens-loop.log - autotunelog => tail -n 100 -F /var/log/openaps/autotune.log - ns-looplog => tail -n 100 -F /var/log/openaps/ns-loop.log - pump-looplog => tail -n 100 -F /var/log/openaps/pump-loop.log - networklog => tail -n 100 -F /var/log/openaps/network.log - xdrip-looplog => tail -n 100 -F /var/log/openaps/xdrip-loop.log - cgm-looplog => tail -n 100 -F /var/log/openaps/cgm-loop.log - urchin-looplog => tail -n 100 -F /var/log/openaps/urchin-loop.log - * to quit watching, press Ctrl+C - - --View settings/logs/info-- - cat-pref => cd ~/myopenaps && cat preferences.json - cat-wifi => cat /etc/wpa_supplicant/wpa_supplicant.conf - cat-autotune => cd ~/myopenaps/autotune && cat autotune_recommendations.log - cat-runagain => cd ~/myopenaps && cat oref0-runagain.sh - git-branch => cd ~/src/oref0 && git branch - edison-battery => cd ~/myopenaps/monitor && cat edison-battery.json - cat-reservoir => cd ~/myopenaps/monitor && cat reservoir.json - - --Edit settings-- - edit-wifi => vi /etc/wpa_supplicant/wpa_supplicant.conf - edit-pref => cd ~/myopenaps && vi preferences.json - edit-runagain => cd ~/myopenaps && nano oref0-runagain.sh - ``` -To use these shortcuts, just type in the phrase you see on the left - i.e. `edit-wifi` and hit enter. - -## Step 6: 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. - - diff --git a/docs/docs/Build Your Rig/index.rst b/docs/docs/Build Your Rig/index.rst deleted file mode 100644 index 9228e5f61..000000000 --- a/docs/docs/Build Your Rig/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Build your rig ----------------------- - -.. toctree:: - :maxdepth: 4 - - - OpenAPS-install - keeping-up-to-date diff --git a/docs/docs/Build Your Rig/logging-into-rig-serial.md b/docs/docs/Build Your Rig/logging-into-rig-serial.md index 3d4d311b9..3f9edb5d3 100644 --- a/docs/docs/Build Your Rig/logging-into-rig-serial.md +++ b/docs/docs/Build Your Rig/logging-into-rig-serial.md @@ -30,7 +30,7 @@ If you don’t… 1) Try unplugging and replugging the existing cables; 2) try d ![Edison in Finder](../Images/Edison/Edison_in_Finder_folder.png) -Note: If you are using a Macbook with a USB-C Hub you may encounter some issues with the flashing process, including unexpected rebooting and the wireless LAN setup not functioning correctly. If you have an option to use a PC or Laptop with directly connected USB cables, it will be easier to do so. Direct USB-C to micro-USB cables are better than a hub and a USB-to-microUSB cable, but still not as good as a regular USB port. +Note: It's strongly recommended to connect all USB cables directly to the computer, without using a hub or USB-C to USB-A adapters. If you use hubs or adapters, you increase the risk of problems during flashing that can prevent you from getting the rig ready to loop, including unexpected rebooting and the wireless LAN setup not functioning correctly. Use USB-C to Micro USB cables for newer MacBooks instead of hubs or adapters. If you do run into problems during flashing and installation, tiny power glitches or connection issues might be the cause. When this happens, try new cables, and remember to keep a battery attached to the rig during flashing. - Connect a USB cable (one that carries data, not just power) to the USB console port. On the Explorer board or Sparkfun base block, this is the port labeled `UART`. On the Intel mini breakout board, this is the USB port that is labeled P6 (should be the USB closest to the JST battery connector). Plug the other end into the computer (or Pi) you want to use to connect to console. - Plug another USB cable (one that carries data, not just power) into the USB port labeled OTG on the Explorer board or Sparkfun base block, or the port that is almost in the on the bottom right (if reading the Intel logo) if setting up with the Intel mini breakout board. Plug the other end into the computer (or Pi) you want to flash from. diff --git a/docs/docs/Build Your Rig/pi-install.md b/docs/docs/Build Your Rig/pi-install.md deleted file mode 100644 index b3f8ee6db..000000000 --- a/docs/docs/Build Your Rig/pi-install.md +++ /dev/null @@ -1,139 +0,0 @@ -# Setting up a Raspberry Pi rig - -Note: there are two key ways to setup a Pi rig. One uses Pi Bakery, the other is a manual method. If your Pi Bakery process does not work, just use [Option B](#option-b). - -## Option A - Use Pi Bakery - -There are many ways setup Raspian (the operating system...like jubilinux is for Edison board) microSD card to use in your Raspberry Pi. One easy way for a new user is to use PiBakery, a free application you'll download from the internet. (Note that if this is not successful, you can switch to [Option B](#option-b) below). - -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) - -Now you will need to [boot up your Pi and connect to it](#boot-up-your-pi-and-connect-to-it). -***************************** - -## Option B - -### Download Raspbian and write it to your microSD card ### - -Following the [install instructions](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. The file must be in a Unix format. If creating the file in Windows, use an editor that allows you to save the file in Unix format instead of DOS format. There are many editors with this ability. `Notepad++` is one that works well. The file should look something like: - -``` -country=xx -ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev -update_config=1 -network={ - ssid="MyWirelessNetwork" - psk="MyWirelessPassword" -} -``` - -You will need to replace xx after country with the correct ISO3166-1 Alpha-2 country code for your country (such as US, UK, DE, etc) - otherwise wifi will remain disabled on the Pi. - -To enable SSH login to the Pi, you will need to create an empty file named `ssh` (with no file extention). -On Windows, you can make this file appear on your Desktop by opening the command prompt and typing: -``` -cd %HOMEPATH%\Desktop -type NUL > ssh -``` -On a Mac, the equivalent command is: -``` -cd ~/Desktop/ -touch ssh -``` - -When you are done, copy it from your Desktop to the boot drive of your SD card. Now you will need to [boot up your Pi and connect to it](#boot-up-your-pi-and-connect-to-it). - -**** - -## Boot up your Pi and connect to it ## - -After the writing is done, you can eject the microSD card from your computer and insert it into your Pi (card slot location shown below), then 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`. If you receive a warning that the rig's host key is not yet cached, respond YES to add it. - -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/master/bin/openaps-install.sh > /tmp/openaps-install.sh && bash /tmp/openaps-install.sh -``` - -* 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`** - -* 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. - -* 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. - -!["install piBakery"](../Images/build-your-rig/pi-curl-success.png) - -### Finish installation ### - -Press enter and 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. -!["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) - -Once your setup script finishes, **make sure to [watch the pump loop logs](<../Build Your Rig/step-4-watching-log>)** - -**NOTE**: If you are using RFM69HCW as RF module: - -If you have connected your RFM69HCW module as described in [Soldering RFM69HCW](https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#soldering), while running interactive setup use following option: -``` -3) RFM69HCW (DIY: SPI) -``` -and then select your ttyport, depending on which you have wired your RFM69HCW to (CE0 on RPi pin 24 will be `/dev/spidev0.0`, CE1 on RPi pin 26 will be `/dev/spidev0.1`): -``` -3) RFM69HCW on /dev/spidev0.0 (walrus) -4) RFM69HCW on /dev/spidev0.1 (radiofruit bonnet) -``` diff --git a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md index 5862fa7e7..72f0b3d7f 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -2,9 +2,9 @@ The directions for this step depend on which type of rig you are using: -- [Intel Edison](#Intel-Edison-instructions) +- [Intel Edison](#intel-edison-instructions) -- [Raspberry Pi](#Raspberry-Pi-instructions) +- [Raspberry Pi](#raspberry-pi-instructions) ## Intel Edison instructions @@ -275,7 +275,7 @@ Put your microSD card into a reader for your computer. Once you get your recipe !["install piBakery"](../Images/build-your-rig/pi-step5.png) -Now you will need to [boot up your Pi and connect to it](#boot-up-your-pi-and-connect-to-it). +Now you will need to [boot up your Pi and connect to it](#boot-up-your-pi-and-connect-to-it); continue following the directions from there. diff --git a/docs/docs/Gear Up/edison-explorer-board.md b/docs/docs/Gear Up/edison-explorer-board.md index bd2c47dbe..9faf25d6b 100644 --- a/docs/docs/Gear Up/edison-explorer-board.md +++ b/docs/docs/Gear Up/edison-explorer-board.md @@ -76,10 +76,12 @@ The easiest way to increase the range of your rig is to purchase a "wire whip" a ### Nuts and Bolts You will likely want to screw your Edison onto the Explorer Block to stabilize the rig. You will need two M2 screws, two M2 nuts, and two spacers or standoffs to support the 3mm -between the Edison and Explorer Board. The Explorer Board is currently being shipped with M2 screws, 3mm spacers, and M2 nuts, but you may want spares (or may have gotten it used). Here are some examples of options: +between the Edison and Explorer Board. +As of early 2019, Enhanced Radio Devices shipped their Explorer boards with suitable M2 screws, 3mm spacers, and M2 nuts, and plastic spacers. However, you may want spares (or may have gotten it used). Here are some examples of options: - [M2 cap screws](https://www.amazon.com/iExcell-Stainless-Steel-Socket-Screws/dp/B07FLLGW19). - [M3 nuts to use as spacers](https://www.amazon.com/uxcell-Thread-Stainless-Metric-Fastener/dp/B01M0D7U5V/) - if using these, or another 3mm spacer option, your M2 screws should be just long enough to fit through the spacers and screw into the M2 nuts on the other side. You can also use a stack of washers or some [3mm nylon spacers](https://www.amazon.com/Electronics-Salon-Assortment-Screws-Plastic-Standoff/dp/B074N5HD42/). - [M2 nuts](https://www.amazon.com/gp/product/B07H3SXSN2/) +- Once you have two suitable matching sets of screws and nuts (M2, or slightly smaller), you can fashion spacers from a thin tube, e.g. a drinking straw that you cut to a length to snugly fit between the board and the Edison chip. (Note: Sparkfun has discontinued its kits of hardware specifically for the Edison, but for reference here are the specs for the [Sparkfun Intel Edison Hardware Pack](https://www.sparkfun.com/products/13187).) @@ -133,7 +135,19 @@ The Explorer board is where all the communications are housed for the rig, as we The nuts and bolts are tiny, and the spaces are a little tight. I find it really helps to use a set of tweezers and a small Phillips head screwdriver. -It's easiest to start with the Explorer board and put on 2 nuts and gold screws (nuts on the side with most of the wiring) inside the little outline where the Edison will eventually sit. Gold screws should be placed as shown, with nuts on the backside. Then, lay the Edison board on top, aligning the screw holes. Use a small Phillips head screwdriver to tighten the screws into the gold screws beneath them. The Edison board should not wobble, and should feel secure when you are done. Attach your battery into the explorer board plug. A single red light should appear and stay lit. During the course of your OpenAPS rig use, it's good practice to periodically check that the nuts and screws stay tightened. If they come loose, the Edison can wobble off the connection to the Explorer board and you will either get looping failures (if it's loose) or be unable to connect to the Edison (if it comes completely off). +Start by looking at the board and chip, to locate where the chip will be seated on the board. + +Then place the two spacers between the board and the Edison chip where the holes for the screws are, holding the spacers in that area while seating the chip carefully. The spacers should fit tightly, but can't be too long, as that would prevent the chip from clicking into its seat once everything's aligned. Arrange the spacers so they don't cover the screw holes. + +Now you can lay the Edison board on top, aligning the screw holes. It clicks into place when it's fully seated. Only then use a small Phillips head screwdriver to tighten the screws into the gold screws beneath them. It is helpful to hold each nut by pressing it against the board with one finger while turning the screwdriver. The Edison board should not wobble, and should feel secure when you are done. + +### Attach your battery into the explorer board plug + +A single red light should appear and stay lit. + +Note: You *can* flash the chip and install the software without a battery attached. However, a battery reduces the risk of having problems from power glitches during the flashing and installation process (Example: Corrupted Jubilinux installations, frequent rebooting.) Practice Safe Flashing - Flash with Battery Attached! + +During the course of your OpenAPS rig use, it's good practice to periodically check that the nuts and screws stay tightened. If they come loose, the Edison can wobble off the connection to the Explorer board and you will either get looping failures (if it's loose) or be unable to connect to the Edison (if it comes completely off). ![Edison/Explorer Board rig with red light on](../Images/Edison/Edison_Explorer_Board.png) diff --git a/docs/docs/Gear Up/edison.md b/docs/docs/Gear Up/edison.md deleted file mode 100644 index 0d7485e32..000000000 --- a/docs/docs/Gear Up/edison.md +++ /dev/null @@ -1,282 +0,0 @@ -# Get your rig hardware - -You have several options for hardware: - -`1.` The most recommended rig has been an Edison + Explorer Board. Unfortunately Intel stopped making the Edison boards as of 2018. If you can find an Intel Edison (eBay, local stores, etc - this is still very possible), this is still a highly recommmended rig. It is the smallest rig (and easily portable), with better battery life because it is power efficient. [See below for the list of hardware for Edison setups](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#hardware-information-for-intel-edison-based-setups). - -`2.` Another recommended option is a Raspberry Pi-based setup, with the new Explorer HAT. This rig setup makes it easier to see information when offline because it has an onboard screen for displaying readouts. [See below for the list of hardware required for Pi/HAT setups](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#hardware-information-for-pi-based-setups-with-the-explorer-hat). - -`3.` Yet another option is a Raspberry Pi-based setup, with an Adafruit RFM69HCW Bonnet. This rig setup makes it easier to see information when offline because it has a small onboard screen for displaying readouts, but it does not come with charging hardware for a battery like the Explorer HAT or Explorer Board. You will need to build your own charging circuit or use a USB power block if you want to make this rig portable. However, this makes an excellent stationary or backup rig! [See below for the list of hardware required for Pi/Bonnet setups](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#hardware-information-for-pi-based-setups-with-the-adafruit-rfm69hcw-bonnet). - -`4.` (Not recommended, but supported) There is an experimental alternative to prefabricated hardware on the Raspberry Pi (Explorer HAT or Adafruit Bonnet), which can serve as the radio on a Pi-based rig, but will not have the screen and requires you to solder. [See below for the list of hardware required for more details on a setup with RFM69HCW breakout board](https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#hardware-information-for-pi-based-setups-with-rfm69hcw-experimental). - -`5.` (Not recommended, but supported) If you *already have* a USB TI stick (from an older rig build), you can continue using it in 0.7.0 if you reflash it with new firmware and wire it to the SPI header on the Raspberry Pi. [See below for the instructions on how to re-flash and re-wire your TI stick](https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#hardware-information-for-pi-based-setups-with-rewired-TI-stick). - -**** - -## Hardware information for Pi-based setups with the Explorer HAT - -Summary of what you need for a Pi/HAT rig: -* [Explorer HAT](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#hat) -* [Pi0WH (recommended) or Pi 3](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#pi) -* [Battery](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#battery) -* [SD Card](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#sd-card) - -#### HAT: -As of April 2018, there is be a Pi+HAT rig as an option for closing the loop with OpenAPS. The HAT can be ordered from the same place that makes the Explorer Board ([click here to pre-order](https://enhanced-radio-devices.myshopify.com/products/900mhz-explorer-hat?variant=1950212653065)). We call it the "Explorer HAT", to differentiate from the Explorer "Board" that goes with the Edison (see below). - -#### PI -You also need a Raspberry Pi. Many users are opting for the "Raspberry Pi Zero WH" - with headers - so you don't have to solder, and can simply add the HAT onto the Pi. See this [PiZeroWH from Adafruit](https://www.adafruit.com/product/3708), or [from other sellers around the world](https://www.raspberrypi.org/products/#buy-now-modal) - -As an alternative, you can also use the HAT with a Raspberry Pi 2/3/4. - -#### Battery -Lipo batteries are typically used to power the rig on the go because they charge quickly and come in a variety of compact sizes. When choosing a battery, you have a trade-off between a larger battery with longer duration or a smaller battery with shorter duration that is easier to carry around. A 2000 mah battery is roughly the size of the Raspberry Pi0, and can last around 4 hours. You'll want a "1S" type, which uses a single cell and outputs at 3.7 VDC. It needs a JST connector to plug into the Raspberry Pi. See this [battery from HobbyKing](https://hobbyking.com/en_us/turnigy-2000mah-1s-1c-lipoly-w-2-pin-jst-ph-connector.html?___store=en_us). - -If you will need to run longer than that while unplugged from wall power, consider a portable charger. These are in widespread use for cell phones and commonly available in a large number of sizes. Here is an example [portable charger from Amazon](https://www.amazon.com/Anker-PowerCore-Ultra-Compact-High-speed-Technology/dp/B0194WDVHI/ref=sr_1_6?ie=UTF8&qid=1532089932&sr=8-6&keywords=backup+battery&dpID=31B5rBNP%252B8L&preST=_SY300_QL70_&dpSrc=srch). Using a USB to micro-USB adapter you can power the rig from the portable charger by plugging the charger into the Power port, which is the micro-USB port nearest the corner of the Pi0. - -**Note**: You will probably want to underclock your Raspberry Pi to get a longer battery life. [See this for details](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/usability-considerations.html#improving-the-battery-life-of-your-raspberry-pi). - -#### SD card -An 8 GB SD card should provide plenty of space for the linux operating system, OpenAPS code and storage for log files. The ability to use larger and removable storage is one of the advantages of the Raspberry Pi. You can get a [MicroSD card and adapter from Adafruit](https://www.adafruit.com/product/2692) when you order your Pi and Hat. Or you can get an equivalent [8 GB SD card from Amazon](https://www.amazon.com/Kingston-microSDHC-Class-Memory-SDC4/dp/B00200K1TS/ref=sr_1_8?s=wireless&ie=UTF8&qid=1532090813&sr=1-8&keywords=8gb+micro+sd) or other sellers. - -#### Note about Pi+HAT cases -Because we are still optimizing the software to be as power-efficient as possible, we have not narrowed down on the best recommended battery. You may want to use a soft case for ease of access to the components, flexible arrangement and the ability to use a variety of battery sizes. If you are using the 2000 mAh battery above, you can use this [3d printed hard case](https://www.thingiverse.com/thing:3010231) to protect the rig and battery in a relatively compact package. The [design is built in OnShape](https://cad.onshape.com/documents/74459dfcb527ad12c33660aa/w/2be92a72bb7f1c83eb091de2/e/b4fa9c3be204ffa3dea128a1), which has a free access level subscription for public domain documents. You can make a copy and tweak the design to your liking. - -Alternative 3d printed cases for Pi0+HAT include this [hard case with room for 2x2000 mAh Li-Po batteries](https://www.thingiverse.com/thing:3038806/) and this [hard case with room for 2x18650 batteries (6800 mAh total, 86x77x25mm)](https://www.thingiverse.com/thing:3502320/). - -*** - -## Hardware information for Pi-based setups with RFM69HCW (experimental) - -This Pi + RFM69HCW is still experimental! - -If you are a maker person or a bit into soldering electronics at least, you may also build your rig with a piece of hardware, that is a lot cheaper than the Explorer HAT, although it does **not** have the screen. You also won't have LEDs indicating status, no battery charging and there will not be (m)any 3d printable case models. If it's your only option because you're on a budget and can't afford to spend 150 bucks on a rig, please think about this step twice. This one will cost you only 30, but a lot of extra time. - -
- -Click here to expand and see pictures of a rig with a Pi0WH and RFM69HCW:: -
- -![Picture of RPI0WH with FM69HCW connected via breadboard](../Images/build-your-rig/RPi_breadboard_connected_to_RFM69HCW.jpg) - -![Picture of RPI0WH with FM69HCW view from the top ](../Images/build-your-rig/RPi_soldered_RFM69HCW_top_view.jpg) - -![Picture of RPI0WH with FM69HCW view of soldered connections](../Images/build-your-rig/RPi_soldered_RFM69HCW.jpg) - -![Picture of RPI0WH with FM69HCW and case](../Images/build-your-rig/RPi_open_case_with_battery_view_on_RFM69HCW.jpg) - -Here's a rough-and-ready budget version of a rig put together: contents of a 2000mAh powerbank, a plastic housing, a micro USB cable and some more soldering and hot glue. BE AWARE that this case will most likely overheat the Pi after a while. You need to at least drill some venting holes into the lid. - -![Picture of the RPI0WH with case](../Images/build-your-rig/RPi_open_case_with_Pi_on_top.jpg) -![Picture of the RPI0WH with case open and a view of the battery](../Images/build-your-rig/RPi_open_case_with_battery_view_on_RFM69HCW.jpg) -![Picture of the RPI0WH with case next to the pump](../Images/build-your-rig/Rig_case_with_pump.jpg) - -
- -### Summary of what you need: -* Raspberry Pi Zero -* RFM69HCW -* [microSD Card]((http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#sd-card)) -* Bread board -* Jumper wires -* Soldering iron -* Power source via Micro USB - -### The Raspberry Pi Zero - -For this setup, you want a Raspberry Pi Zero WH. (The "H" means it has Header pins). (Also, a regular Raspberry Pi 3 model B works fine.) - -### RFM69HCW -You can buy this board e.g. [here](https://www.adafruit.com/product/3070), but you can really buy it wherever you want. These boards are, like the RPi Zero, very common. Just make sure you get the right frequency. 868/915 MHz is correct. All others are wrong. - -### Breadboard -Any breadboard will do, no special requirements. - -### Soldering -You need to solder the pin stripe into the RFM69HCW. Insert the pin stripe from the bottom of the board, with the short endings reaching through the holes. Fixate a bit, so you can rest the soldering iron tip on the pins and the board. - -Solder the included pin stripe diligently into the 9 holes named -VIN GND EN G0 SCK MISO MOSI CS RST - -Cut an antenna at your preferred length corresponding to your frequency. This can be a simple piece of isolated, unshielded wire. (I simply took one of the jumper wires for my first try.) -Calculate your length here: https://m0ukd.com/calculators/quarter-wave-ground-plane-antenna-calculator/ and just use the value from A (first green box). This should be the length of your antenna, from the soldering point on the board to the tip. - -Solder it to the board. It's the hole near the "o" from Radio. Make sure to not connect the soldering to the ground plates left and right from the hole. This antenna is really only connected to the one hole. - -This is your connection scheme for the RPi to RFM69HCW. Stick the RFM69HCW on a bread board, and connect: - -Board | Connect | Connect | Connect | Connect | Connect | Connect | Connect | Connect -------|------|------|------|------|------|------|------|------ -RPi | 3.3V | GND | MOSI | MISO | SCLK | | CE1_N || -RPi PIN | 17 | 25 | 19 | 21 | 23 | 15 | 26 | 22 -RFM69HCW | VIN or 3.3V | GND | MOSI | MISO | SCK or CLK | G0 or DIO0 | CS or NSS | RST or RESET - -![Picture of RPI0WH with FM69HCW connection diagram](../Images/build-your-rig/rpii2RFM69HCW.JPG) - -[See more info here](https://github.com/ecc1/rfm69/blob/master/README.md). - -After that, you're ready to install OpenAPS. - -*** - -## Hardware information for Pi-based setups with the Adafruit RHM69HCW Bonnet - -Summary of what you need for a Pi/Bonnet rig: -* [Explorer HAT](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#Bonnet) -* [Pi0WH (recommended) or Pi 3](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#pi) -* [Antenna](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#antenna) -* [SD Card](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#sd-card) - -#### Bonnet: - -There is be a Pi+Bonnet rig as an option for closing the loop with OpenAPS. This hardware is available from Adafruit, and is called the [Adafruit RFM69HCW Transceiver Radio Bonnet - 868 or 915 MHz - RadioFruit](https://www.adafruit.com/product/4072). As of October 2019, this hardware is supported via automated setup via `oref0-setup.sh`. - -#### PI -You also need a Raspberry Pi. Many users are opting for the "Raspberry Pi Zero WH" - with headers - so you don't have to solder, and can simply add the HAT onto the Pi. See this [PiZeroWH from Adafruit](https://www.adafruit.com/product/3708), or [from other sellers around the world](https://www.raspberrypi.org/products/#buy-now-modal) - -As an alternative, you can also use the bonnet with a Raspberry Pi 2/3/4. - -#### Antenna - -The bonnet does not come with an antenna, so you will need to purchase (or make) one. The end connector needs to be of the u.fl type, and the antenna length that you need will be determined by the frequency on which that your pump operates. The following antennas work well for either 868MHz (WW) or 915MHz (NA): - -[Slim Sticker-type GSM/Cellular Quad-Band Antenna - 3dBi uFL](https://www.adafruit.com/product/1991) - -[900Mhz Antenna Kit - For LoPy, LoRa, etc](https://www.adafruit.com/product/3340) - -#### SD card -An 8 GB SD card should provide plenty of space for the linux operating system, OpenAPS code and storage for log files. The ability to use larger and removable storage is one of the advantages of the Raspberry Pi. You can get a [MicroSD card and adapter from Adafruit](https://www.adafruit.com/product/2692) when you order your Pi and Hat. Or you can get an equivalent [8 GB SD card from Amazon](https://www.amazon.com/Kingston-microSDHC-Class-Memory-SDC4/dp/B00200K1TS/ref=sr_1_8?s=wireless&ie=UTF8&qid=1532090813&sr=1-8&keywords=8gb+micro+sd) or other sellers. - -#### Optional - case for the bonnet -There is one 3D printable case [available on thingiverse](https://www.thingiverse.com/thing:3656500), where Raspberry Pi Zero fits with the bonnet. - -*** - -## Hardware information for Pi-based setups with rewired TI-stick - -This hardware setup is **not recommended unless you already have a USB TI stick** and want to continue using it with 0.7.0. This part of the documentation is a work-in-progress and as of 11/9/2019 not fully tested -- if you can help with this, we would appreciate it very much! - -You will need a CC-Debugger to re-flash your TI stick with an SPI-compatible firmware, [located here](https://github.com/ps2/subg_rfspy/releases). Any of the v0.8 `spi1_alt2` versions should work. - -You will also need jumpers to wire your TI stick to the Raspberry Pi's GPIO header in the following configuration: -``` -SPI0 CS0 (Pi pin 24) -> debug pin 5 -SPI0 CLK (Pi pin 23) -> debug pin 6 -SPI0 MISO (Pi pin 21) -> debug pin 8 -SPI0 MOSI (Pi pin 19) -> debug pin 10 -any Pi 3.3V pin -> debug pin 2 -any Pi ground pin -> debug pin 1 -GPIO 4 (Pi pin 7) -> debug pin 7 -``` - -When prompted in oref0-setup.sh, you will need to select the "TI Stick (SPI-connected)" option. - - -*** - -## Hardware information for Intel Edison-based setups - -The high level parts list (see below for more details, and links): - -* [Explorer Board Block]<#explorer-board-block> -* [Edison](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#edison) -* [Nuts and Bolts to attach the Edison to the Explorer Board Block](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#nuts-and-bolts) -* [At least one Lithium battery](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#lithium-ion-polymer-lipo-battery-or-other-battery-supply) -* [2 USB cables](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#usb-cables) - -### Explorer Board Block - -The recommended board to use is the [Explorer Board Block](https://enhanced-radio-devices.myshopify.com/products/900mhz-explorer-block-pre-order), which was co-designed by this community. It also has the benefits of a built-in radio. It's only available from Hamshield/Enhanced Radio Devices. - -### Edison - -There are 4 types of Edison's. All of them work, but Versions 3 and 4 require an extra antenna, so 1 and 2 are preferred (1-EDI2.LPON, 2-EDI2.SPON, 3-EDI2.LPOF, and 4-EDI2.SPOF). If the seller does not specify the Edison model/version, you can see from the picture whether or not it has a white ceramic antenna in the corner. If it does not, then it will require an external antenna, but that version is fairly rare. - -* Option 1 - Buy it from places like Ebay, Craiglist, or your nearest store - and follow the instructions to flash it. - - * You may need to hunt for an Edison as supplies of them are dwindling - if you get it as part of a "kit" (i.e. breakoutboard + Edison), keep in mind _you'll still need to get the Explorer Board Block from Hamshield_. - - * **Note:** If you are doing Option 1 (an Edison from wherever you can find it) - you are getting an UNFLASHED Edison. Not a big deal - flashing it with jubilinux is just a few more steps (~15 minutes) - but remember you'll need to start with the flashing instructions. 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)), but stop before installing wifi and other steps and instead jump over to the "[Install OpenAPS](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html)" page from there. - -* Option 2 - (previously [buy an Edison that is already flashed with jublinux when supplies were available](https://enhanced-radio-devices.myshopify.com/products/intel-edison-w-jubilinux). If you get a pre-flashed Edison, you can start [installing and setup OpenAPS](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html). (You would not need to "flash" the Edison). - -### Lithium-ion polymer (LiPo) battery or other battery supply - -The Explorer Boards have battery charger circuitry on board, making it easy to use a LiPo battery. - -* The example setup uses a [2000mah LiPo battery](http://www.robotshop.com/en/37v-2000mah-5c-lipo-battery.html); also [Lithium Ion Battery - 3.7v 2000mAh](https://www.adafruit.com/products/2011) or [Adafruit Battery Packs Lithium Ion Battery 3.7v 2000mAh](https://www.amazon.com/Battery-Packs-Lithium-3-7v-2000mAh/dp/B0137ITW46) are similar options, although many people prefer a higher capacity battery to get a full day from the rig (such as [Adafruit Lithium Ion Polymer Battery - 3.7v 2500mAh (PRODUCT ID: 328) and the Adafruit Lithium Ion Cylindrical Battery - 3.7v 2200mAh (PRODUCT ID: 1781)](https://www.adafruit.com/category/574)). This battery uses a 2mm 2 pin JST connector to match the Explorer boards' power plugs. -* For people in the UK, you may find you have to shop around to find the correct battery, as shipping restrictions appears to have reduced the supply somewhat. [Pimoroni](https://shop.pimoroni.com/products/lipo-battery-pack) appear to stock the same Adafruit 2000mAh battery as mentioned above. Another source looks to be [Cool Components](https://www.coolcomponents.co.uk/en/lithium-polymer-battery-2000mah.html), but you may find shipping costs expensive. CAUTION: [RS Online](https://uk.rs-online.com/mobile/p/lithium-rechargeable-battery-packs/1251266/) sell a similar battery, but unfortunately it comes with the wrong JST connector (it comes with a 2.5mm JST XHP-2, and you need a 2mm JST PH). It is possible, however, to buy the [right connectors](https://www.technobotsonline.com/jst-ph-2mm-2-way-housing-excludes-female-pins.html) and fit them yourself (numerous 'how to' videos on YouTube). -* For people in Australia you can find 2000mAh, 2200mAh and 2500mAh batteries from [Little bird electronics](https://www.littlebirdelectronics.com.au/batteries/), prices are very competitive and shipping is quick. These are the same Adafruit batteries that can be obtained from the US above. - -**Note**: It's best to buy from a reputable supplier, because if the internal two cells are mismatched the Explorer board cannot charge them separately and they are prone to catching fire. Make sure that it *includes a protection circuit* to protect over-discharge. **NEVER** connect the battery to an Explorer board the wrong way round. There is no manufacturing standard so never assume correct polarity. The connector JP1 on the Explorer Block has two terminals. The left side is positive, the right side is negative. The side with the JP1 label is the positive side. Typically a battery's red wire is the positive wire. Ideally you want a battery that has a 10k ohm thermistor for temperature protection by the Edison too. - -You can also use any charger with a USB plug, including a wall power charger. The Explorer boards have pass through charging, so this is also how you will charge the LiPo battery. - -#### Battery safety - -You should monitor the rig periodically - **especially the LiPo battery**, checking for swelling or damage. Immediately discontinue use of any battery that shows sign of swelling or damage. - -**** - -### Radio stick (only if not using Explorer board) - -We recommend an Explorer Board with a built-in radio ([see above](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#explorer-block)), because if you get an Explorer Board, you don't need an additional radio stick or CC-Debugger. - -The following options are not yet documented for oref0 versions < 0.7.0, and may not work anymore: -If you don't use an Explorer board, you can use a number of radio sticks: a [TI-USB-Sticks](http://www.ti.com/tool/cc1111emk868-915), running [subg_rfspy](https://github.com/ps2/subg_rfspy); [Wireless Things ERF](https://www.wirelessthings.net/erf-0-1-pin-spaced-radio-module); [Wireless Things Slice of Radio](https://www.wirelessthings.net/slice-of-radio-wireless-rf-transciever-for-the-raspberry-pi) a Slice of Radio; or a Rileylink. For details about setup with these other stick and board options, [the best instructions will be found in the mmeowlink wiki](https://github.com/oskarpearson/mmeowlink/wiki) for setting up your board and stick. Note you may also need a CC debugger for these, and also note that it will be more work as the documentation is designed for the Edison/Explorer Board setup as the easiest path forward. - -### USB Cables - -You will need two micro USB cables - with a micro connector on one end and a standard (Type A) connector on the other. Most cables will work fine, but some prefer to select lengths. You may already have one for charging a Dexcom receiver, or an Android phone, lying around at home. If you don't, here's an example of one that will work: [Monoprice Premium USB to Micro USB Charge, Sync Cable - 3ft](http://www.monoprice.com/Product?c_id=103&cp_id=10303&cs_id=1030307&p_id=9763&seq=1&format=2). - -Warning: bad cables cause a lot of headaches during the Edison flashing process, so it may be worth verifying before you start if you have good cables that can transfer data. - -### Optional: Micro USB to Micro USB OTG Cable for offline looping - -You may want to connect your Dexcom receiver (G4 or non-touchscreen G5) to your Explorer Block for offline looping. For this you will need to use a micro USB to micro USB OTG cable (or an OTG adapter). Here is an example of a cable that will work: [BestGameSetups Micro USB to Micro USB OTG (On-The-Go) 12" (30cm) Data Cable](https://www.amazon.com/dp/B00TQOEST0/ref=cm_sw_r_cp_api_Niqfzb3B4RJJW). - -### Nuts and Bolts - -You will likely want to screw your Edison onto the Explorer Block to stabilize the rig. There are two methods to do this. The simplest is to order a kit like the [Sparkfun Intel Edison Hardware Pack](https://www.sparkfun.com/products/13187), which provides standoffs, screws, and nuts specifically designed for the Edison. Alternatively, you can use (2) M2 screws and (2) M2 nuts and (4) M3 nuts (M3 or a bit larger to used as spacers). In this configuration, the screws should be just long enough to fit through the spacer nuts and screw into the M2 nuts on the other side. (Note: Sparkfun is no longer selling these screw kits. There are some available on Amazon [lock nuts](https://www.amazon.com/Uxcell-a15072100ux0228-Plated-Nylock-Insert/dp/B015A3BZJQ) and [cap screws](https://www.amazon.com/iExcell-Stainless-Steel-Socket-Screws/dp/B07FLLGW19). - -### Cases - -You can use a variety of cases, either soft or hard. Make sure to check the case design to make sure it will support your preferred rig setup and battery size/type. Also, be careful with inserting your rig into some 3D-printed cases so you do not harm the board and/or the battery. - -### Soft Cases -* [TallyGear soft case](http://www.tallygear.com/index.php?route=product/category&path=120) - these are the soft cases Dana uses ([see this example](https://twitter.com/danamlewis/status/792782116140388353)). The OpenAPS-sized case can be made any any pattern/fabric she uses elsewhere on the site. -* [JD Burrows SD card case](https://www.officeworks.com.au/shop/officeworks/p/j-burrows-sd-and-usb-case-blue-jbsdcasbu) - this is a hard / soft case which fits the rig with a 2500mAh battery perfectly, can also fit a spare AAA pump battery (Australia) - -### Hard cases - -**Warning: be careful if you select a hard case. Some may be designed for a certain size/shape battery; and attempting to jam a rig in may harm the board and/or the battery.** - -Also: a hard case may make you less likely to look at your rig directly. You should monitor the rig periodically - **especially the battery**, checking for swelling or damage. Immediately discontinue use of any battery that shows sign of swelling or damage. - -Generic hard cases: - -* [RadioShack Project Enclosure (3x2x1 inch)](https://www.radioshack.com/products/radioshack-project-enclosure-3x2x1?utm_medium=cpc&utm_source=googlepla&variant=20332262405&gclid=Cj0KEQiA-MPCBRCZ0q23tPGm6_8BEiQAgw_bAkpDZCXfIgbEw8bq76VHtV5mLwR2kHKfJrsGsF3uqqgaAtxP8P8HAQ) -* [Small clear plastic case perfect for larger Sparkfun 2000 mAh battery: #8483](http://www.ebay.com/itm/272062812611) -* [Small Plastic Clear Case for 2500 mAh battery](http://www.ebay.com/itm/272062812611) - Since a Tic-Tac box is too small for the 2500 mAh battery. - -Cases for Edison plus battery: - -* [Ken Stack's 3D design for a case with the battery next to the board](https://github.com/Perceptus/explorer_board_case) -* [Rob Kresha's design with the battery compartment stacked on-top of the board compartment](http://www.thingiverse.com/thing:2020161) -* [Gustavo's 3D design](https://github.com/Perceptus/explorer_board_case_2) -* [Sulka Haro's 3D design](https://www.tinkercad.com/things/4a6VffpcuNt) -* [tazitoo's 3D design: CAD](https://www.tinkercad.com/things/aRYGnHXt7Ta-explorer-case/editv2) ([or STL for 3D printing](http://www.thingiverse.com/thing:2106917)) -* [danimaniac's Protective Cases & Accessories](https://github.com/danimaniac/OpenAPS-Explorer-Board-Edison-vented-case) -* [Luis's ventilated acrylic simple design](https://drive.google.com/drive/folders/0BxeFg9yJZ_FZdWJEcG5KMXdUMjg?usp=sharing) -* [Robert Silvers and Eric Burt's case for Explorer and 2500 mAh battery](http://www.thingiverse.com/thing:2282398) -* [Robert Silvers' case for Explorer and 2000 or 2500 mAh battery](http://www.thingiverse.com/thing:2291125) -* [tynbendad's case for 18650 battery](https://www.thingiverse.com/thing:2798858) - -Cases for Edison plus G4 receiver: - -* [jimrandomh's 3D printed design for Edison and a G4 receiver together](http://conceptspacecartography.com/my-openaps-g4-case/) - -### Other non-case protection options - -* [Heat Shrink Tubing](https://www.amazon.com/gp/product/B009IILEVY) diff --git a/docs/docs/Gear Up/rig-options.md b/docs/docs/Gear Up/rig-options.md index 38046d773..439cca11d 100644 --- a/docs/docs/Gear Up/rig-options.md +++ b/docs/docs/Gear Up/rig-options.md @@ -6,11 +6,11 @@ You have several options for hardware: 2. The other option is a Raspberry Pi-based setup, with the new Explorer HAT. This rig setup makes it easier to see information when offline because it has an onboard screen for displaying readouts. [Go here for hardware required and setup instructions for Pi/HAT setups](<../Gear Up/pi-based-rigs>). There is also an experimental alternative to an Explorer HAT, RFM69HCW, which can serve as the radio on a Pi-based rig, but will not have the screen, and requires you to solder. -`3.` Yet another option is a Raspberry Pi-based setup, with an Adafruit RFM69HCW Bonnet. This rig setup makes it easier to see information when offline because it has a small onboard screen for displaying readouts, but it does not come with charging hardware for a battery like the Explorer HAT or Explorer Board. You will need to build your own charging circuit or use a USB power block if you want to make this rig portable. However, this makes an excellent stationary or backup rig! [See below for the list of hardware required for Pi/Bonnet setups](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-the-adafruit-rfm69hcw-bonnet>). +3. Yet another option is a Raspberry Pi-based setup, with an Adafruit RFM69HCW Bonnet. This rig setup makes it easier to see information when offline because it has a small onboard screen for displaying readouts, but it does not come with charging hardware for a battery like the Explorer HAT or Explorer Board. You will need to build your own charging circuit or use a USB power block if you want to make this rig portable. However, this makes an excellent stationary or backup rig! [See here for the list of hardware required for Pi/Bonnet setups](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-the-adafruit-rfm69hcw-bonnet>). -`4.` (Not recommended, but supported) There is an experimental alternative to prefabricated hardware on the Raspberry Pi (Explorer HAT or Adafruit Bonnet), which can serve as the radio on a Pi-based rig, but will not have the screen and requires you to solder. [See here for the list of hardware required for more details on a setup with RFM69HCW breakout board](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-rfm69hcw-experimental>). +4. (Not recommended, but supported) There is an experimental alternative to prefabricated hardware on the Raspberry Pi (Explorer HAT or Adafruit Bonnet), which can serve as the radio on a Pi-based rig, but will not have the screen and requires you to solder. [See here for the list of hardware required for more details on a setup with RFM69HCW breakout board](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-rfm69hcw-experimental>). -`5.` (Not recommended, but supported) If you *already have* a USB TI stick (from an older rig build), you can continue using it in 0.7.0 if you reflash it with new firmware and wire it to the SPI header on the Raspberry Pi. [See here for the instructions on how to re-flash and re-wire your TI stick](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-rewired-TI-stick>). +5. (Not recommended, but supported) If you *already have* a USB TI stick (from an older rig build), you can continue using it in 0.7.0 if you reflash it with new firmware and wire it to the SPI header on the Raspberry Pi. [See here for the instructions on how to re-flash and re-wire your TI stick](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-rewired-ti-stick>). ## What happens if you have multiple rigs? diff --git a/docs/docs/Resources/Edison-Flashing/mac-flash.md b/docs/docs/Resources/Edison-Flashing/mac-flash.md deleted file mode 100644 index eca316f2e..000000000 --- a/docs/docs/Resources/Edison-Flashing/mac-flash.md +++ /dev/null @@ -1,401 +0,0 @@ -# Setting up Edison/Explorer Board on a Mac - -(This is a separate workflow for Mac only. Please refer to the all-computer flashing instructions as well for troubleshooting & full instructions for other computer setup processes.) - -## Hardware Assumptions for this page - -1. Using an Explorer board and Edison -2. Using an Apple computer (with either USB-A or USB-C ports) -3. Using a looping-compatible Medtronic pump. See [all compatible pumps](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/pump.html#information-about-compatible-insulin-pumps). - -## High Level Recommended Rig parts list - -a) [**Explorer Board - link**](https://enhanced-radio-devices.myshopify.com/products/900mhz-explorer-block-pre-order) - -b) [**Edison - link**](https://www.sparkfun.com/products/13024). (Intel has discontinued the Edison, and the link is mostly so you can look at what the chip looks like. You can still find Edison chips on EBay. They are often sold as a part of a kit (e.g. Arduino), check with the seller to confirm that the chip is included. (https://www.ebay.com/sch/i.html?_from=R40&_trksid=p2060353.m570.l1312.R2.TR10.TRC3.A0.H0.XIntel+.TRS2&_nkw=intel+edison&_sacat=175673) ~$30-$50 is a typical price for a new-in-box Edison chip, usually more for a kit. Since it's EBay, you will see them occasionally offered for much more, or much less. - -c) **Nuts and Bolts** -Enhanced Radio Devices shipped their Explorer boards with suitable nuts and screws, and plastic spacers in early 2019. -My first explorer board did not come with usable nuts and screws, and I had trouble locating suitable spacers. An easy workaround: Once you have two suitable matching sets of screws and nuts (M2, or slightly smaller), you can fashion spacers from a thin tube, e.g. a drinking straw that you cut to a length to snugly fit between the board and the Edison chip. - -d) **At least one Lithium Battery** Larger capacity batteries allow longer runtime before needing to be recharged. The cylindrical batteries hold up better if you carry the rig in a soft case than the flat ones. Most 3-D-printed cases only work with specific battery sizes. - - * [2500mAh battery - link](https://www.adafruit.com/products/328) - * [2000mAh battery - link](https://www.sparkfun.com/products/8483) - * [2200mAh Lithium Ion Cylindrical Battery - link](https://www.adafruit.com/product/1781) - * [4400mAh Lithium Ion Battery Pack - link](https://www.adafruit.com/product/354) - -e)* **USB cables** You may already have workable USB cables; you need two cables that are long enough to connect the rig to the computer to complete this process. "Bad" cables can cause problems during flashing; when in doubt, get a couple of new USB cables. - - Example USB-A to Micro USB cables: - * [3 ft long cable, USB A - Micro USB - link](https://www.adafruit.com/products/592) - * [6 inch long cable, USB A - Micro USB - link](https://www.adafruit.com/products/898) - - Example USB-C to Micro USB cables: - * [1 ft long cable, USB C - Micro USB - link](https://www.amazon.com/AmazonBasics-Double-Braided-Type-C-Micro-B/dp/B07CWFNSSN/ref=sr_1_5?crid=1KOKFYDQR41WY&keywords=usb%2Bc%2Bto%2Bmicro%2Busb&qid=1574060073&sprefix=usb%2Bc%2Bto%2Bmicro%2Caps%2C215&sr=8-5&th=1) - -## Getting Physical: Build your rig/put the physical pieces together - -The Explorer board is where all the communications are housed for the rig, as well as the battery charger. The Edison is the mini-computer where all the OpenAPS code will be sent and used. In order for this to work, first you have to screw and connect the Edison and Explorer Board together with nuts and bolts. - -The nuts and bolts are tiny, and the spaces are a little tight. I find it really helps to use a set of tweezers and a small Phillips head screwdriver. The Edison board should not wobble, and be securely seated when you are done. - -This is a bit challenging to do the first few times - everything is small, you don't want to damage the chip or the board, or lose the spacers, nuts and screws. - -I generally start by looking at the board and chip, to locate where the chip will be seated on the board. - -Then I place the two spacers between the board and the Edison chip where the holes for the screws are, holding the spacers in that area while seating the chip carefully. The spacers should fit tightly, but can't be too long, as that would prevent the chip from clicking into its seat once everything's aligned. Then I arrange the spacers so they don't cover the screw holes. Typically this is the time I can fully seat the Edison, and it clicks into place when it's fully seated. Only then I install the screws, and nuts. I find it helpful to hold each nut by pressing it against the board with one finger while turning the screwdriver. I re-check the seating of the chip befor moving on to the next step. It must be firmly seated. - -Did you notice a click when it settled into its place? Good job! - -You'll probably drop a nut or spacer at some point during this step. Working at a table can save you lengthy searches for tiny dropped parts. Use a small screwdriver that fits your screws to tighten them - not too tight - on the nuts. You can find tiny screwdrivers in "eye glass repair kits", or at electronic stores, hardware stores, etc. - -### Attach your battery into the explorer board plug. -A single red light should appear and stay lit. -Note: You *can* flash the chip and install the software without a battery attached. However, a battery reduces the risk of having problems from power glitches during the flashing and installation process (Example: Corrupted Jubilinux installations, frequent rebooting.) #Practice Safe Flashing - Flash with Battery Attached!# - -During the course of your OpenAPS rig use, it's good practice to periodically check that the nuts and screws stay tightened. If they come loose, the Edison can wobble off the connection to the Explorer board and you will either get looping failures (if it's loose) or be unable to connect to the Edison (if it comes completely off). - -![Edison/Explorer Board rig with red light on](../../Images/Edison/Edison_Explorer_Board.png) - - -## Software-build your rig - -This is a three-step process: -1. Preparing the Edison (aka flashing the Edison) -2. Installing the “looping” code (aka setup script for oref0) -3. Personalizing your settings ("setting your preferences") - -### 1. Preparing/flashing the Edison/reflashing the Edison - -The Edison comes with an operating system that doesn’t work easily with OpenAPS. The first step is to replace the operating system with a new one. This is called “flashing” the Edison. - -Let’s start by downloading the updated operating system (it’s called Jubilinux) to your computer so that we can install it later onto the Edison. Go to Safari and download [Jubilinux](http://www.jubilinux.org/dist/) (jubilinux 0.3.0 is the only fully supported version; jubilinux 0.2.0 runs Debian jessie, which is NOT supported by Debian any longer). - -Now we move to the Edison. You’ll see two Micro USB ports on your explorer board. One is labeled OTG (that’s for flashing) and one is labeled UART (that’s for logging into the Edison from a computer). We will need to use both to flash. We’re going to connect both of those to our computer’s USB ports using USB-cables that are appropriate for your computer (USB-A to Micro USB for most computers, USB-C to Micro USB for newer MacBooks). - -Plug in the battery, if you have not done that yet. - -Note: It's strongly recommended to connect all USB cables directly to the computer. This means, do not use a hub (e.g. a USB-C to USB-A hub), and do not use adapters). If you use hubs or adapters, you increase the risk to run into problems during flashing that can prevent you from getting the rig ready to loop. Use USB-C to Micro USB cables for the newer MacBooks instead of hubs or adapters. If you do run into problems during flashing and installation, tiny power glitches or connection issues might be the cause. When this happens, try new cables, and remember to keep a battery attached to the rig during flashing. - -![Explorer Board rig with two cables and red light on](../../Images/Edison/ExplorerBoard_two_charging_cables.png) - -Once you plug in the cables, you should see your Edison board in your Finder as a connected “device” (similar to what you would see if you plug in a USB thumb drive). If you don’t…try different cables. If your USB port is bad and not recognizing the device, you may need to [reset your SMC first](https://support.apple.com/en-au/HT201295) (it’s not hard to do, takes 2 minutes.) - -![Edison in Finder](../../Images/Edison/Edison_in_Finder_folder.png) - -The OpenAPS uses Terminal, kind of like Loop uses Xcode. It’s our interaction with the code that forms the basis of the loop. You may have never even used the Terminal app. Go to your Applications folder and find the Terminal App in the Utilities folder. Double click to open it. - -![Terminal example](../../Images/Edison/Terminal_example.png) - -Terminal app is an ugly, plain interface … but it does what we need to do, communicate with the Edison. Basically, the Edison is a computer that lacks a keyboard and display. By using a cable connected to the rig, we can login to the Edison and use Terminal as a way of interacting with the Edison. - -When you first launch Terminal, you will probably see something rather plain like below. The important thing to know is that the Terminal helps show you WHERE you are in your computer or Edison. So, in the screenshot below, it’s telling me I am in my “iMac4K” user account. If you are ever a little confused where you are…you can look to the left of the $ prompt and get an idea. - -![A look inside terminal](../../Images/Edison/Inside_terminal.png) - -If you’re like me, you don’t “speak linux” (or python or java or…) nor do you really know what linux is. So, you’ll be comforted to know that most of this setup is copy and paste commands into Terminal. You won’t need to suddenly learn linux…just will need to follow directions and be willing learn some basics. - -**IMPORTANT NOTE**: STEPS 1-10 will be updated periodically, and also will likely be out of date. Since this is just a cheat sheet for Mac users, it may not have all the troubleshooting tips or updated info that the main OpenAPS docs have. If you get stuck and this guide’s set of instructions do not work at the moment, the place to look is the [OpenAPS Walkthrough Phase 0, Setting up your Intel Edison](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html) for the full information on this part of the OpenAPS setup. - -The next steps will be done in the Terminal app. If you see red colored text/code lines in a box, that’s what you want to copy and paste into Terminal, and then press enter. Don’t try typing it…you’ll likely miss a space or add a typo. So, let’s start… - -#### **1-1. Install homebrew** - -`ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"` - -You will be prompted to enter “RETURN” to continue and then enter your passcode for the user account (your computer password). When you type the password, you will not see any letters appear in the Terminal screen..that is normal. Terminal does not show keystrokes for passwords. - -![Enter return example](../../Images/Edison/Enter_return.png) - -It will take about 1-2 minutes for Homebrew to install. You’ll see a bunch of commands scrolling by in Terminal window. Just wait it out until you see the screen showing Installation successful and you’ll be returned to the $ Terminal prompt. - -![After Homebrew](../../Images/Edison/After_Homebrew.png) - -#### **1-2. Install a bunch of other stuff (dfu-util, coreutils, gnu-getopt)** - -`brew install dfu-util coreutils gnu-getopt` - -* If you are reflashing an Edison, it might suggest upgrading coreutils, in which case, run `brew upgrade coreutils gnu-getopt` - -![After installing other stuff](../../Images/Edison/After_install_other_stuff.png) - -#### **1-3. Install lsusb** - -`brew update && brew tap jlhonora/lsusb && brew install lsusb` - -![After installing lsusb](../../Images/Edison/after_install_lsusb.png) - -#### **1-4. Start Edison in screen mode** - -`sudo screen /dev/tty.usbserial-* 115200` - -You’ll most likely be asked for your computer password again. Enter it. A blank screen will likely come up, then press enter to wake things up to show an Edison login prompt. Login with username “root” (no quotes) and no password will be needed. Leave this window alone for a bit as we proceed with next steps. - -![Example terminal screen](../../Images/Edison/change_me_out_for_jubilinux.png) - -If you have a problem getting to the Edison login prompt, and possibly get a warning like "can't find a PTY", close that terminal window. Then unplug the usb cables from your computer (not from the Edison...leave those ones as is) and swap the USB ports they were plugged in. Open a new terminal window, use the `sudo screen /dev/tty.usbserial-* 115200` command again. Usually just changing the USB ports for the cables will fix that "can't find a PTY" error. - -#### **1-5. Flash the Edison** - -* Open a new Terminal Window (leave the existing one from that last screenshot open…we need a second window) by selecting command-N or using menu bar Shell>New Window>New Window with Settings-Basic. - -* In the new window, enter `cd ~/Downloads/jubilinux` This will change your directory. - -![Change directories](../../Images/Edison/cd_jubilinux.png) - -* Enter `./flashall.sh` -* You’ll get a prompt that asks you to "plug and reboot" the Edison board. You’re done with this screen for now. Just leave it alone (**don’t close window**) and go to next step. - -![Reboot](../../Images/Edison/reboot.png) - -#### **1-6. Return to the other Terminal Window that we left off of in Step 4.** - -* Is the battery attached? No? Go get it and plug it in now. - -* Enter `reboot` - -#### **1-7. Now we wait and watch.** - -You may see a message notification that the Edison “Disk Not Ejected Properly”. Don’t worry...it is rebooting. You will see some processes going on in the background. - -![Don't worry during Reboot](../../Images/Edison/dont_worry_during_reboot.png) - -You should see: - -``` -Hit any key to stop autoboot: 0 -Target:blank -Partitioning using GPT -Writing GPT: success! -Saving Environment to MMC... -Writing to redundant MMC(0)... done -Flashing already done... -GADGET DRIVER: usb_dnl_dfu -# -DFU complete CRC32: 0x77ccc805 -DOWNLOAD ... OK -Ctrl+C to exit ... -###################################################################################################################### -``` -in the terminal window where you typed `reboot`, and -``` -Using U-Boot target: edison-blankcdc -Now waiting for dfu device 8087:0a99 -Please plug and reboot the board -Flashing IFWI -Download [=========================] 100% 4194304 bytes -Download [=========================] 100% 4194304 bytes -Flashing U-Boot -Download [=========================] 100% 245760 bytes -Flashing U-Boot Environment -Download [=========================] 100% 65536 bytes -Flashing U-Boot Environment Backup -Download [=========================] 100% 65536 bytes -Rebooting to apply partition changes -Now waiting for dfu device 8087:0a99 -Flashing boot partition (kernel) -Download [=========================] 100% 5980160 bytes -Flashing rootfs, (it can take up to 10 minutes... Please be patient) -``` -in the terminal window where you ran `./flashall.sh`. As it says, this should take about 10 minutes. It may appear like nothing is happening for awhile, but wait it out. If it didn’t take long at all...chances are that the flash didn’t really work, in which case you should read through the [full docs] and try again, and/or check out the Troubleshooting section at the bottom. - -**OLDER JUBILINUX VERSIONS**: After flashing is complete, watch the window as you should get asked to type **control-D to continue**. If so, go ahead and press (don’t type that out, just press the keys) control-D to keep going. - -![Control-D prompt for Jubilinux flash](../../Images/Edison/control_d.png) - -**NEWER JUBLINUX VERSIONS (0.1.0 and later)**: You probably won't get asked to Control-D and that is fine. - -After one of the reboots, you'll probably see: - -``` -[** ] A start job is running for /etc/rc.local Compatibili...14s / no limit) -``` -for a few minutes: that's fine. You can also expect to see an ugly red: -``` -[FAILED] Failed to start Hostname Service. -``` -That is also fine, and you can ignore it too. - -Eventually, you should get a ubilinux login prompt (If you see Yocto instead of ubliniux, then you need to go back to Steps 1-4 and start the flash process over again. Or if you are reflashing and your old rig name appears, then the reflashing did not work. Go back to Steps 1-4.) - -![Login after successful Reboot](../../Images/Edison/login_after_successful_reboot.png) - -Use login `root` and password `edison` to login to your newly flashed Edison. After logging in, you will notice that the Terminal prompt says `root@ubilinux:~#`. This is the correct prompt for the jubilinux system. You will not see jubilinux in the prompt. If you bought a pre-flashed Edison, this is how your initial Terminal prompt will look. - -![Terminal Prompt for Jubilinux](../../Images/Edison/name.png) - -CONGRATULATIONS! You just flashed the edison! Wahoo! Now, [head back to the install instructions for the easy bootstrap script process of setting up wifi](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#steps-2-3-wifi-and-dependencies). (Below has the manual instructions, but most people prefer the quick bootstrap script option). - -#### **1-8. Wifi for Edison** - -Now that you’ve finished flashing, the Edison is going to need a couple things to finish setting it up; Hostname/passwords and Multiple WiFi networks - -**Hostname and password** - -* From that same screen we just left off , enter these commands to rename your Edison's hostname. - -`myedisonhostname=` <---But replace the <> section with your chosen hostname. I used “edisonhost” as the name, as shown in screenshot below. - -Then run each of these commands with no modifications, just copy and paste: - -`echo $myedisonhostname > /etc/hostname` - -`sed -r -i"" "s/localhost( jubilinux)?$/localhost $myedisonhostname/" /etc/hosts` - -Now your Edison has a new hostname. (note: screenshot below is a little different than you will see on your screen. You will see root@ubilinux) - -![Edison hostname and password screen](../../Images/Edison/edison_hostname_password.png) - -**IMPORTANT** - -* To change the password for your Edison to a more secure password than “edison”, enter `passwd root` - -* Follow the commands to reset the password. Repeat for `passwd edison` - -* SAVE PASSWORDS somewhere, you’ll want them. - -![Changing password screen](../../Images/Edison/changing_edison_password.png) - -#### **1-9. Multiple wifi networks** - -**A-1.** Enter -`vi /etc/network/interfaces` - -**A-2.** A screen similar to the one below will appear. Type “i” to enter INSERT mode for editing on the file. - -![Wifi edit screen](../../Images/Edison/Wifi_edit_screen.png) - -.. note:: - **Helpful Tip for Insert Mode** - - If you are new to INSERT MODE, realize that INSERT MODE inserts characters at the highlighted cursor (it does not overwrite the character showing beneath the cursor). And, the default is that the cursor will be at the top left of the screen to start, so you will need to use the arrow keys to move the cursor to the area where you want to start typing. If you freak out that you’ve made a change that you don’t want to commit...you can simply press the ESC key and then type (no quotes) “:q!” to quit without saving any of your typing/changes. - - If you experience any erratic behavior while using the screen editor, such as the cursor overwriting or deleting adjacent words when typing or even when using the cursor arrow keys, this may be due to incorrectly set Mac Terminal window settings. Try going to the "Shell" on the menu bar above and selecting "Show Inspector." Ensure the Columns setting is set to "80" and the Rows setting is set to "25." - -**A-3.** Make the changes so they match the areas highlighted in yellow, above: -* uncomment (remove the #) from the auto wlan0 line -* add ` wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf` right below the iface wlan0 line. -* comment out (add #) to the wpa-ssid and wpa-psk lines as shown - -**A-4.** Press ESC then type “:wq” (no quotes) and enter to write (save) and quit that screen. When you press ESC, you won't initially see much different, but when you type ":wq", you will see the characters appear in the lower left of the screen. - - -**B-1.** Enter `vi /etc/wpa_supplicant/wpa_supplicant.conf` - -**B-2.** Type “i” to enter INSERT mode for editing on the file. - -**B-3.** Add the following for each wifi network you’d like to add. - -``` -network={ - ssid="my network" - psk="my wifi password" -} -``` - -The networks you enter here are the wifi networks that your rig will be able to use to stay connected to internet. Examples shown below. One is my home wifi, the other is my iphone’s personal hotspot. - -![Wifi edit screen](../../Images/Edison/Wifi_add.png) - -![Phone wifi hotspot screen](../../Images/Edison/Phone_hotspot_wifi.png) - -* Note: If you don’t know your personal hotspot’s information, you can find it under your iPhone's Settings, Personal Hotspot as shown in the screenshot. - -* You should add your personal hotspot to the list of wifi networks as a backup if your BT-tethering to hotspot does not work. By toggling your hotspot off-on, it will generate a wifi-tether signal for approximately 90 seconds, so that your rig can find it and connect. Since wifi-tethers are similar to a regular wifi connection, your rig will not automatically hop off this connection when it gets to your home wifi network. You will need to remember to turn off your wifi-tether if you want your rig to connect back to your home wifi network. By contrast, a hotspot connection done by BT-tether does not require any toggling and your rig will connect/disconnect as it leaves/comes to a known wifi network in your wp_supplicant list. - -* If you haven't done it, a good idea is to update the name of your iPhone to remove any apostrophes. Apple's default is to name iPhones with an apostrophe such as "Katie's iPhone". This can cause some problems for wifi connections sometimes. You can rename your iPhone by going into your iPhone's Settings, General, About, and then Name. - -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 captive networks 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 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 -} -``` - -**B-4.** Press ESC then type “:wq” to write (save) and quit that screen when you have finished adding the wifi networks. You can always come back and add more networks as needed, using the same process. - -**C** Run `ifup wlan0` to make sure you can connect to wifi. A successful connection should look similar (IP address numbers will be different than mine): - -![ifup wlan0 example](../../Images/Edison/ifup_wlan0.png) - -If you don't see a message showing you are successfully connected, go back to the start of Step 1-9 and make sure that you don't have any typos in those two files. - -#### **1-10. Installing packages, SSH keys, and other settings** - -ALRIGHTY...Your Edison is coming along. Now we are going to set aside the Edison “screen” terminal window (in case we can't get in via ssh), reboot, and login using an “ssh” command from a new Terminal window. - -* Type `reboot` -* Wait as many lines of action go by in the Terminal window...eventually you will get to a prompt that has your new edisonhost name login. We aren't going to login right now. Just saving that window in case we need it later. -* Open a new Terminal window by pressing Command-N -* Login to your Edison by entering `ssh root@edisonhost.local` (changing edisonhost to the hostname you selected earlier above). If you see warnings about the authenticity of host can't be established, you can say yes to continue and add the new edison to your known hosts list. This message typically appears when you've set-up multiple edisons on the same computer. -* Enter your password that you set earlier - -![Login to your rig](../../Images/Edison/Rig_login_time.png) - -* Run `ping google.com` to make sure your rig is online. If your rig shows up as online successfully, you can enter control-c to exit the ping. A successful ping should look like the screen below. - -![Ping success](../../Images/Edison/ping_success.png) - -* If you are reflashing an Edison, you might get a scary looking error about "WARNING: POSSIBLE DNS SPOOFING DECTECTED WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!" that is likely because you are attempting to login to a rig that has the same hostname as a previous rig that has been logged into on the computer. You can delete the history of known hosts for the rig by entering the commands `cd .ssh` and then `rm known_hosts`. This will delete the log of known hosts on your computer. There's no significant downside to removing the known_host log, except that you will need to answer yes to the key fingerprint additions again for the first time you login to old rigs again. - -![Mac spoofing error](../../Images/spoof-no-box.png) - - -If the rig isn't online, go back and check your /etc/network/interfaces and /etc/wpa_supplicant/wpa_supplicant.conf files above: you probably either missed a step or made a typo. Usually you will see `ping: unknown host google.com` if you are not connected to the internet, as shown below. - -![Ping Unsuccessful](../../Images/Edison/ping_unsuccessful.png) - -* Enter these three lines, one-at-a-time (the first line will run fast, and the second and third lines may take several minutes to complete) - -`dpkg -P nodejs nodejs-dev` - -![Nodejs install](../../Images/Edison/nodejs.png) - -`apt-get update && apt-get -y dist-upgrade && apt-get -y autoremove` - -![Apt-get install](../../Images/Edison/apt-get.png) - -`apt-get install -y sudo strace tcpdump screen acpid vim python-pip locate` - -![python and sudo install](../../Images/Edison/python.png) - -* Enter these three lines, one-at-a-time (the first two will be fast, the last line will take you to a screen for setting up your timezone. Screenshots are just for examples...in this case PST - -`adduser edison sudo` - -`adduser edison dialout` - -`dpkg-reconfigure tzdata # Set local time-zone` - -![Time zone examples](../../Images/Edison/Time_zone.png) - -* Enter `vi /etc/logrotate.conf` then press “i” for INSERT mode, and make the following changes: - - * set the log rotation to daily from weekly - * remove the # from the “#compress” line - -* Press ESC and then type “:wq” to save and quit - -![Log rotation examples](../../Images/Edison/log_rotation.png) - -**Congratulations you have successfully flashed your edison and configured some basic settings. Time to move onto OpenAPS install** - -### 2. Installing the looping script (openaps-setup.sh) - -You'll now want to move on to the [rest of the install instuctions](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html). - -### 3. Personalizing your settings - -Remember to personalize your settings after you finish installing OpenAPS! diff --git a/docs/docs/Resources/troubleshooting.md b/docs/docs/Resources/troubleshooting.md deleted file mode 100644 index ee05845bf..000000000 --- a/docs/docs/Resources/troubleshooting.md +++ /dev/null @@ -1,319 +0,0 @@ -# Troubleshooting - -Even those who follow this documentation precisely are bound to end up stuck at some point. This could be due to something unique to your system, a mistyped command, actions performed out of order, or even a typo in this guide. This section provides some tools to help diagnose the issue as well as some common errors that have been experienced and resolved before. If you get stuck, try re-reading the documentation again and after that, share what you've been working on, attempted steps to resolve, and other pertinent details in [#intend-to-bolus in Gitter](https://gitter.im/nightscout/intend-to-bolus) when asking for help troubleshooting. Here is also a [good blog post to read with tips on how to best seek help online to troubleshoot](https://diyps.org/2017/03/19/tips-for-troubleshooting-diy-diabetes-devices-openaps-or-otherwise/). - -What's on this page: - -- [Generally useful linux commands](#generally-useful-linux-commands) -- [Dealing with npm run global-install errors](#dealing-with-npm-run-global-install-errors) -- [Dealing with a corrupted git repository](#dealing-with-a-corrupted-git-repository) -- [Debugging Disk Space Issues](#debugging-disk-space-issues) -- [Environment variables](#environment-variables) -- [Wifi and hotspot issues](#wifi-and-hotspot-issues) - * [My wifi connection keeps dropping or I keep getting kicked out of ssh](#my-wifi-connection-keeps-dropping-or-i-keep-getting-kicked-out-of-ssh) - * [I forget to switch back to home wifi and it runs up my data plan](#i-forget-to-switch-back-to-home-wifi-and-it-runs-up-my-data-plan) - * [I am having trouble consistently connecting to my wifi hotspot when I leave the house](#i-am-having-trouble-consistently-connecting-to-my-wifi-hotspot-when-i-leave-the-house) - * [I am not able to connect to my wireless access point on my iPhone](#i-am-not-able-to-connect-to-my-wireless-access-point-on-my-iphone) -- [Common error messages](#common-error-messages) - * [Don't have permission, permission not allowed, etc](#permission-not-allowed) - * [ValueError: need more than 0 values to unpack](#valueerror-need-more-than-0-values-to-unpack) - * [Unable to upload to Nightscout](#unable-to-upload-to-Nightscout) - * [No JSON object could be decoded](#no-json-object-could-be-decoded) - * [json: error: input is not JSON](#json-error-input-is-not-json) - * [TypeError: Cannot read property 'zzzz' of undefined](#typeerror-cannot-read-property-zzzz-of-undefined) - * [Could not parse carbratio date when invoking profile report](#could-not-parse-carbratio-date-when-invoking-profile-report) - * [Could not get subg rfspy state or version ccprog](#could-not-get-subg-rfspy-state-or-version-ccprog) - * [Dealing with the CareLink USB Stick](#dealing-with-the-carelink-usb-stick) - -## Generally useful linux commands - -More comprehensive command line references can be found [here](http://www.computerworld.com/article/2598082/linux/linux-linux-command-line-cheat-sheet.html) and [here](http://www.pixelbeat.org/cmdline.html). For the below, since these are basic linux things, also try using a basic search engine (i.e. Google) to learn more about them and their intended use. - -`ls -alt` (List all of the files in the current directory with additional details.) - -`cd` (Change directory) - -`pwd` (Show the present working directory (your current location within the filesystem).) - -`sudo ` (Super-user do. Temporarily elevates the current users permission to that of root.) - -`apt-get install ` (Aptitude is a package manager, when a package is missing it will (usually) be there and can be installed by issuing 'apt-get install .) - -`tail -f /var/log/syslog` - -`grep LOOP /var/log/syslog` (Display lines in file that contain a string, in this example, 'LOOP') - -`df -h` - -`ifconfig` - -`cat ` (Display the contents of the file.) - -`nano ` (Open and edit the file in the nano text editor.) - -`stat ` - -`head ` (Display the beginning of the file.) - -`less ` (Display the contents of the file, with advanced navigation) - -`pip freeze` - -`sudo reboot` (Reboot the system) - -`sudo shutdown -h now` (The correct way to shut down the Raspberry Pi from the command line. Wait for the green light to stop blinking before removing the power supply.) - -`dmesg` (Displays all the kernel output since boot. It’s pretty difficult to read, but sometimes you see things in there about the wifi getting disconnected and so forth.) - -`uptime` (Shows how long the system has been running and the load average of last minute/5 minutes/15 minutes) - -`crontab -l` (Display cron jobs) - -`sudo service cron status` (Display info on cron service. Also use `stop` and `start`) - -## Dealing with npm run global-install errors - -If you get an error while running an `npm global-install`, you may be able to clear it by running the following commands: - -`rm -rf /usr/lib/node_modules/.staging/ && rm -rf ~/src/oref0 && cd ~/src && git clone git://github.com/openaps/oref0.git || (cd oref0 && git checkout master && git pull)` - -then run `cd ~/src/oref0 && git checkout master && git pull` or if you are running dev then `cd ~/src/oref0 && git checkout dev && git pull` - -then run `cd ~/src/oref0 && npm run global-install` and then re-run oref0-setup. - -## Dealing with a corrupted git repository - -In oref0 versions prior to oref0 0.6.0, OpenAPS used git as the logging mechanism, so it commits report changes on each report invoke. Sometimes, due to "unexpected" power-offs (battery dying, unplugging, etc.),the git repository gets broken. You may see an error that references a loose object, or a corrupted git repository. To fix a corrupted git repository you can run `oref0-reset-git`, which will first run `oref0-fix-git-corruption` to try to fix the repository, and in case when repository is definitely broken it copies the .git history to a temporary location (`tmp`) and initializes a new git repo. In some versions of oref0 (up to 0.5.5), `oref0-reset-git` is in cron so that if the repository gets corrupted it can quickly reset itself. - -If you're still having git issues, you should `cd ~/myopenaps; rm -rf .git ; git init` . If you do this, git will re-initialize from scratch. This only applies to 0.5.x (or earlier) or upgrades to dev from master and does not apply to a fresh 0.6.x install. - -Warning: do not run any openaps commands with sudo in front of it `sudo openaps`. If you do, your .git permissions will get messed up. Sudo should only be used when a command needs root permissions, and openaps does not need that. Such permission problems can be corrected by running `sudo chown -R pi.pi .git` in the openaps directory. If you are using an Intel Edison, run `sudo chown -R edison.users .git`. - -oref0 0.6.x and beyond will not use git and will not have git-related errors to deal with. - -## Debugging Disk Space Issues - -If you are having errors related to disk space shortages as determined by `df -h`, but you still have some room on your /root drive (i.e., it is not 100% in use), you can use a very lightweight and fast tool called ncdu (a command-line disk usage analyzer) to determine what folders and files on your system are using the most disk space. You can install ncdu as follows: `sudo apt-get install ncdu`. You can run it by running the following command: `cd / && sudo ncdu` and follow the interactive screen to find your disk hogging folders. - -An alternative approach to disk troubleshooting is to simply run the following command from the base unix directory after running `cd /`: - -`du -xh -d 3 | egrep "[1-9][0-9][0-9]M|[0-9]G"` (reports disk usage of all directories 3 levels deep from the current directory) - -Then, based on which folders are using the most space cd to those folders and run the above du command again until you find the folder that is using up the disk space. - -One potential culprit can be cached software packages, which can be removed with `sudo apt-get clean` and/or `sudo apt-get autoremove --purge` - -It is also common that log files (i.e., the /var/log directory) are the cause for disk space issues. If you determine that log file(s) are the problem, use a command like `less` to view the last entries in the logfile to attempt to figure out what is causing the logfile to fill up. If you still have some room on your /root drive (i.e., it is not 100% in use according to `df /root`), you can temporarily free up space by forcing the logfiles to rotate immediately, with the following command: - -`logrotate -f /etc/logrotate.conf` - -If your /root drive is 100% in use according to `df /root`, you may need to free up space by removing log files. It should be safe to remove archived log files with the command `rm /var/log/*.[0-9] /var/log/*.gz`. Check again with `df /root` that you have plenty of space - normally your /root drive should have 80% or less space in use. If you have more in use but still less than 100% you can use one of the above techniques to free more space. - -If your disk is still 100% full, you may have to remove a live log file. Run the command `du /var/log/openaps/* /var/log/*|sort -n |tail -5`, which will show the largest 5 log files. Pick the largest file, use the command `less` to view the last entries to determine if there is a problem, and when you're sure you don't need the file any longer you can use the command `rm log_file_name` to delete it (replace log_file_name with the large log file's name). You should `reboot` after removing any of the live log files so the system resumes logging properly. - -## Environment variables - -If you are getting your BG from Nightscout or you want to upload loop status/results to Nightscout, among other things you'll need to set 2 environment variables: `NIGHTSCOUT_HOST` and `API_SECRET`. If you do not set and export these variables you will receive errors while running `openaps report invoke monitor/ns-glucose.json` and while executing `ns-upload.sh` script which is most probably part of your `upload-recent-treatments` alias.Make sure your `API_SECRET` is in hashed format. Please see [this page](https://github.com/openaps/oref0#ns-upload-entries) or [this issue](https://github.com/openaps/oref0/issues/397) for details. Additionally, your `NIGHTSCOUT_HOST` should be in a format like `http://yourname.herokuapp.com` (without trailing slash). For the complete visualization guide use [this page](https://github.com/openaps/docs/blob/master/docs/Automate-system/vizualization.md) from the OpenAPS documentation. - -## Wifi and hotspot issues - -### My wifi connection keeps dropping or I keep getting kicked out of ssh -There is a script that you can add to your root cron that will test your connection and reset it if it is down. Here is an example that runs every two minuntes (odd minutes). You could also do it every 5 minutes or less. Note, this does not have to be for an Edison, you can set this up for a Pi, etc as well. - -``` -cd ~/src -git clone https://github.com/TC2013/edison_wifi -cd edison_wifi -chmod 0755 /root/src/edison_wifi/wifi.sh -``` -Next, add the script to your root cron. Note this is a different cron that what your loops runs on, so when you open it don't expect to see your loop and other items you have added. - * Log in as root ```su root``` - * Edit your root cron ```crontab -e``` - * Add the following line ```1-59/2 * * * * /root/src/edison_wifi/wifi.sh google.com 2>&1 | logger -t wifi-reset``` - -### I forget to switch back to home wifi and it runs up my data plan -You can add a line to your cron that will check to see if `` is available and automatically switch to it if you are on a different network. - * Log in as root ```su root``` - * Edit your root cron ```crontab -e``` - * Add the following line ```*/2 * * * * ( (wpa_cli status | grep > /dev/null && echo already on ) || (wpa_cli scan > /dev/null && wpa_cli scan_results | egrep > /dev/null && sudo wpa_cli select_network $(wpa_cli list_networks | grep jsqrd | cut -f 1) && echo switched to && sleep 15 && (for i in $(wpa_cli list_networks | grep DISABLED | cut -f 1); do wpa_cli enable_network $i > /dev/null; done) && echo and re-enabled other networks) ) 2>&1 | logger -t wifi-select``` - -### I am having trouble consistently connecting to my wifi hotspot when I leave the house -When you turn on your hotspot it will only broadcast for 90 seconds and then stop (even if it is flipped on). So, when you leave your house you need to go into the hotspot setting screen (and flip on if needed). Leave this screen open until you see your rig has connected. It may only take a few seconds or a full minute. - -### I am not able to connect to my wireless access point on my iPhone -Consider changing your iPhone's name... In most cases iPhone will set the phone's SSID to something like "James’s iPhone" By default Apple puts a curly apostrophe (’) into the SSID instead of a straight one ('). Your choices from here are either paste in the curly apostrophe in wpa_supplicant.conf, or change the name on the phone. To change the name on the iPhone: - * On your iOS device, go to Settings > General > About. - * Tap the first line, which shows the name of your device. - * Rename your device, then tap Done. - -## Common error messages - -**WARNING:** Pay close attention to errors. An error may indicate a serious operational or functional problem with a computer system or component. - -These error messages may appear in response to openaps commands in the console, or in the system log (located at /var/log/syslog when using raspbian OS). Some errors can be safely ignored, like timeout errors that occur when the pump is out of range. - -### Permission not allowed - -The command you are running likely needs to be run with root permissions, try the same command again with ```sudo ``` in front of it - -Bash scripts (.sh files) need execute permissions to run. Run this command to grant execute permissions to the owner of a file. - -``` -chmod u+x myscript.sh -``` - -### ValueError: need more than 0 values to unpack - -A JSON file did not contain entries. It usually will self-resolve with the next successful pump history read. - -### Unable to upload to Nightscout - -OpenAPS has failed to upload to the configured nightscout website. If you're using a Medtronic CGM and no BG readings appear in nightscout, connect to your rig and the directory of your openaps app (default is myopenaps) run - -`openaps first-upload` - -### No JSON object could be decoded - -Usually means the file does not exist. It usually will self-resolve with the next successful pump history read. If it recurs, you will need to [drill down](<../Troubleshooting/oref0-setup-troubleshooting#running-commands-manually-to-see-what-s-not-working-from-an-oref0-setup-sh-setup-process>) to find the area where it is not successfully reading. - -### json: error: input is not JSON -``` -json: error: input is not JSON: Unexpected '<' at line 1, column 1: - Document Moved -``` - - This error usually comes up when you have pulled a file down from Nightscout that was an invalid file. Typically you might see this when trying to pull down treatments. Make sure that you have your HOST and API_KEY set correctly at the top of your cron, in your ~/.profile - -### TypeError: Cannot read property 'zzzz' of undefined - -example: `TypeError: Cannot read property 'rate' of undefined` - -Usually is related to a typo if you have manually been editing files. Otherwise, should self-resolve. - -### Could not parse carbratio date when invoking profile report - - Could not parse carbratio_data. - Feature Meal Assist enabled but cannot find required carb_ratios. - -This error may occur when you invoke `settings/profile.json` report. - -Check report definition in `openaps.ini`. If you have line `remainder = []` change it to `remainder = ` - -Below is correct definition - - [report "settings/profile.json"] - use = shell - bg_targets = settings/bg_targets.json - settings = settings/settings.json - basal_profile = settings/basal_profile.json - reporter = text - json_default = True - max_iob = preferences.json - device = get-profile - remainder = - insulin_sensitivities = settings/insulin_sensitivities.json - -### Could not get subg rfspy state or version ccprog or cannot connect to CC111x radio - -Full error is usually: -`Could not get subg_rfspy state or version. Have you got the right port/device and radio_type? (ccprog)` - -Or (on an intel edison): -`cannot connect to CC111x radio on /dev/spidev5.1` - -Or (on a Raspberry Pi): -`cannot connect to CC111x radio on /dev/spidev0.0` - -Basic steps using an Intel Edison with Explorer Board or a Raspberry Pi with Explorer HAT: - * checking with `cd ~/myopenaps && sudo service cron stop && `killall -g openaps ; killall-g oref0-pump-loop; oref0-mmtune && sudo service cron start` to see if it is resolved yet - * Make sure the Explorer board or HAT has not become loose and is sitting correctly on the Edison board or Pi - * Check that your rig is in close range of your pump - * Check that your pump battery is not empty - * Reboot, or fully power down and start up your rig - -If you are using an Intel Edison with Explorer Board or a Raspberry Pi with Explorer HAT, and that does not resolve your issue, or if the two LEDs next to the microUSB ports on your Explorer board (respectively D1/D2 on Explorer HAT) stay on even after an mmtune, you may need to re-flash your radio chip: - * Stop the reboot loop: `sudo service cron stop && killall-g oref0-pump-loop && shutdown -c` - * (for versions >0.7.0) Install MRAA (you only need to do this once per rig): `oref0-mraa-install` - * Reboot manually, and if necessary stop the reboot loop again: `sudo service cron stop && killall-g oref0-pump-loop && shutdown -c` - * Install ccprog tools on your Edison: `cd ~/src; git clone https://github.com/ps2/ccprog.git` - * Build (compile) ccprog so you can run it: `cd ccprog; make ccprog` - * Flash the radio chip: - -#### Using an Intel Edision + Explorer Block: -``` -wget https://github.com/EnhancedRadioDevices/subg_rfspy/releases/download/v0.8-explorer/spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex -./ccprog -p 19,7,36 erase -./ccprog -p 19,7,36 write spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex -``` -If you receive an error saying that ccprog is only tested on C1110 chips then reboot the rig and try again. i.e. -``` -reboot -``` -Then: -``` -cd ~/src/ccprog -./ccprog -p 19,7,36 erase -./ccprog -p 19,7,36 write spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex -``` - - -#### Using a Raspberry Pi + Explorer HAT: -``` -wget https://github.com/EnhancedRadioDevices/subg_rfspy/releases/download/v0.8-explorer/spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex -./ccprog -p 16,18,7 reset -./ccprog -p 16,18,7 erase -./ccprog -p 16,18,7 write spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex -``` - - * Reboot, and try `cd ~/myopenaps && sudo service cron stop && killall -g openaps ; killall-g oref0-pump-loop; oref0-mmtune && sudo service cron start` to make sure it works - - -### Monitor/mmtune.json is empty or does not exist -#### Only verified to work with Intel Edison + Explorer Block -Full error is: -``` -cannot connect to CC111x radio on /dev/spidev5.1 -1999/12/31 19:14:23 cc111x: no response -monitor/mmtune.json is empty or does not exist -``` -Trying to reflash the radio may result in: -``` -Erasing chip. -This code is only tested on CC1110. Unsupported chip id = 0x00. -Chip erase failed. -``` -If you're affected by this particular issue, the two LEDs next to the microUSB ports on your Explorer board may stay on continuously, or they may flash during loop attempts, but stay on between loops. If this is the case, you may need to completely reinstall OpenAPS. This requires redoing everything from the Jubilinux flash, to the bootstrap script and finally the OpenAPS setup. - -**Note:** Starting the Jubilinux flash from the beginning will overwrite everything, so you may want to copy and save any configuration files you don't want to lose, like your `wpa_supplicant.conf` Wi-Fi settings for example. - -Instructions to reinstall OpenAPS are [here](<../Build Your Rig/index>) - -Once you have finished running the OpenAPS setup script, view your loop by entering `l`. Your loop will probably still be failing, but with a different error message: -``` -Could not get subg_rfspy state or version. Have you got the right port/device and radio_type? -``` -Now you should be able to follow [the directions above](<#could-not-get-subg-rfspy-state-or-version-ccprog-or-cannot-connect-to-cc111x-radio>) to reflash the radio. -This time the reflash should be successful and you should see: -``` -Erasing chip. -Chip erased. -root@yourrig:~/src/ccprog# ./ccprog -p 19,7,36 write spi1_alt2_EDISON_EXPLORES_STDLOC.hex -``` -Press enter, then you should see: -``` -Writing 2769 bytes to flash.... -``` -You have now successfully reflashed the radio. Now `reboot` and your loop should start running with red and green LEDs off (except for an occasional blink). - - -## Dealing with the CareLink USB Stick - -**Note:** Generally, the Carelink stick is no longer supported. We *highly* recommend moving forward with a different radio stick. See [the hardware currently recommended in the docs](<../Gear Up/hardware-overview>), or ask on Gitter. - -The `model` command is a quick way to verify whether you can communicate with the pump. Test this with `openaps use model` (after you do a `killall-g oref0-pump-loop`). - -If you can't get a response, it may be a range issue. The range of the CareLink radio is not particularly good, and orientation matters; see [range testing report](https://gist.github.com/channemann/0ff376e350d94ccc9f00) for more information. - -Sometimes the Carelink will get into an unresponsive state that it will not recover from without help. You can tell this has happened if the pump is within range of the Carelink and you see a repeating series of "Attempting to use a port that is not open" or "ACK is 0 bytes" errors in pump-loop.log. When this happens the Carelink can be recovered by rebooting or physically unplugging and replugging the CareLink stick. - -Once you're setting up your loop, you may want to detect these errors and recover the Carelink programmatically. This can be done by running oref0-reset-usb (`oref0-reset-usb.sh`) to reset the USB connection. For example, you could create a cron job that would run `openaps use model`, or tail the 100 most recent lines in pump-loop.log, and grep the output looking for the errors noted above. If grep finds the errors, the cron job would run oref0-reset-usb. Just note that during USB reset you will lose the connection to all of your USB peripherals. This includes your Wi-Fi connection if your rig uses a USB Wi-Fi dongle. diff --git a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md index 8e09d8c48..ca0f8488e 100644 --- a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md +++ b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md @@ -7,7 +7,7 @@ There are several ways to communicate with other participants and contributors i **Note:** It's best practice not to share your pump's serial number, so make sure not to include it in pictures or pasted text output when seeking help on pump communication. Ditto for Nightscout URL and API secret and other private information that could enable someone to access your setup. ### Slack -There is a [Slack channel](https://omniapsslack.azurewebsites.net/) that you can add yourself to - then look for the `#OpenAPS` channel to post questions. This is the best place to get real-time support with anything related to OpenAPS. It is a great place to introduce yourself and get some help from those who are a few steps further down the road. That slack can also be used to stay up to date on other, broader DIY diabetes projects such as communication around other pumps that are being explored and worked on, but aren't yet DIY loopable. (Here's [why we often recommend asking questions in an archived community space, written when the primary place to go for support was Gitter instead of Slack](https://diyps.org/2016/08/17/why-you-should-post-questions-in-gitter/).) +There is a [Slack channel](https://omniapsslack.azurewebsites.net/) that you can add yourself to - then look for the `#OpenAPS` channel to post questions. This is the best place to get real-time support with anything related to OpenAPS. It is a great place to introduce yourself and get some help from those who are a few steps further down the road. That slack can also be used to stay up to date on other, broader DIY diabetes projects such as communication around other pumps that are being explored and worked on, but aren't yet DIY loopable. ### Google Group A google group focused on #OpenAPS development work can be found [here](https://groups.google.com/d/forum/openaps-dev) - everyone is encouraged and welcome to join! You can add yourself directly to the group. It's worth setting your preferences to receive all email from the group; there's not a huge volume, and this is one of the ways we share updates about hardware or release announcements if you're not hanging out on Gitter or Facebook or Twitter. However, please note that troubleshooting questions about rig setups are best posted to Slack - email tends to be slower and you will likely be redirected to another channel if you're actively working to resolve a setup problem. diff --git a/docs/docs/While You Wait For Gear/collect-data-and-prepare.md b/docs/docs/While You Wait For Gear/collect-data-and-prepare.md index d4f138adb..9d6eb50b7 100644 --- a/docs/docs/While You Wait For Gear/collect-data-and-prepare.md +++ b/docs/docs/While You Wait For Gear/collect-data-and-prepare.md @@ -56,8 +56,6 @@ There are a couple areas in the pump that will need to be set specifically in or * Set your DIA. **Note**: Most people have their DIA for traditional pumping to be too short (e.g. 2 or 3). For looping, OpenAPS will default to using 5. Many people find they actually need it to be 6 or 7 with properly adjusted other settings. -* ISFs over 250 mg/dl per unit will need a special step in loop setup once your setup script is finished (see [here](<../Build Your Rig/step-4-watching-log#temp-basals-6-3-isf-255-or-carb-ratio-25-with-a-x23-or-x54)), even though the pump currently will allow you to set them higher. Just remember, you will need to run a couple extra commands when you setup your loop. - * If you have periods in the day where your pump normally has basal settings of zero - your loop will not work! You can resolve this by setting the lowest possible basal setting your pump will permit. OpenAPS will then issue temp basals of zero, as needed. #### Easy Bolus Button diff --git a/docs/docs/While You Wait For Gear/nightscout-setup.md b/docs/docs/While You Wait For Gear/nightscout-setup.md index 09e5a7b89..cd9d15b90 100644 --- a/docs/docs/While You Wait For Gear/nightscout-setup.md +++ b/docs/docs/While You Wait For Gear/nightscout-setup.md @@ -56,7 +56,7 @@ Note that insulin logged on Nightscout but not read from the pump (e.g., an inje ## Troubleshooting Nightscout issues -Please see the [Nightscout troubleshooting](<../Troubleshooting/rig-ns-communications-troubleshooting>) page if you experience problems with the setup process or with communications with Nightscout. +Please see the [Nightscout troubleshooting](<../Troubleshooting/Rig-NS-communications-troubleshooting>) page if you experience problems with the setup process or with communications with Nightscout. ## Nightscout Setup with Heroku From 0c05e511ce5615a56e16b30d5346a8893a43deef Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sat, 22 Feb 2020 21:43:00 -0500 Subject: [PATCH 05/13] finish applying changes to sneaky files that did not get saved --- docs/docs/Build Your Rig/step-3-setup-script.md | 8 ++++---- docs/docs/Troubleshooting/Common-error-messages.md | 7 ++++++- .../docs/Understanding OpenAPS-Overview/using-the-docs.md | 5 +++++ 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/docs/Build Your Rig/step-3-setup-script.md b/docs/docs/Build Your Rig/step-3-setup-script.md index 141d06e9b..a1cd99d52 100644 --- a/docs/docs/Build Your Rig/step-3-setup-script.md +++ b/docs/docs/Build Your Rig/step-3-setup-script.md @@ -18,10 +18,10 @@ The screenshot below shows an example of the questions you'll be prompted to rep * 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. +* CGM method: The options are `g4-go`, `g5`, `g5-upload`, `g6`, `g6-upload`, `mdt`, `xdrip`, and `xdrip-js`. + * The various G4/G5/G6 options are for plugging a physical receiver into the rig with USB. + * If you would like the rig to communicate directly with your G5/G6 transmitter over Bluetooth (most likely in place of a receiver, using Alternate Channel mode), choose xdrip-js. + * Do *not* choose MDT unless you are using an Enlite sensor attached to the pump you're looping with. If you use FreeStyle Libre or Medtronic 640G as a CGM, or any other CGM system that gets its data only from Nightscout, you should choose g4-go, g5, or g6. OpenAPS also attempts to get BG data from your Nightscout. OpenAPS will always use the most recent BG data regardless of the source, so if offline looping is unavailable, if will try to pull from NS, and vice versa. * 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](<../Usage and maintenance/Wifi/bluetooth-tethering-edison>) after setup. diff --git a/docs/docs/Troubleshooting/Common-error-messages.md b/docs/docs/Troubleshooting/Common-error-messages.md index fbffe6fdb..8cc3d98a8 100644 --- a/docs/docs/Troubleshooting/Common-error-messages.md +++ b/docs/docs/Troubleshooting/Common-error-messages.md @@ -73,6 +73,9 @@ Full error is usually: Or (on an intel edison): `cannot connect to CC111x radio on /dev/spidev5.1` +Or (on a Raspberry Pi): +`cannot connect to CC111x radio on /dev/spidev0.0` + Basic steps using an Intel Edison with Explorer Board or a Raspberry Pi with Explorer HAT: * checking with `cd ~/myopenaps && sudo service cron stop && killall -g openaps ; killall-g oref0-pump-loop; oref0-mmtune && sudo service cron start` to see if it is resolved yet * Make sure the Explorer board or HAT has not become loose and is sitting correctly on the Edison board or Pi @@ -81,7 +84,9 @@ Basic steps using an Intel Edison with Explorer Board or a Raspberry Pi with Exp * Reboot, or fully power down and start up your rig If you are using an Intel Edison with Explorer Board or a Raspberry Pi with Explorer HAT, and that does not resolve your issue, or if the two LEDs next to the microUSB ports on your Explorer board (respectively D1/D2 on Explorer HAT) stay on even after an mmtune, you may need to re-flash your radio chip: - * Stop the reboot loop: `sudo service cron stop && killall -g oref0-pump-loop && shutdown -c` + * Stop the reboot loop: `sudo service cron stop && killall-g oref0-pump-loop && shutdown -c` + * (for versions >0.7.0) Install MRAA (you only need to do this once per rig): `oref0-mraa-install` + * Reboot manually, and if necessary stop the reboot loop again: `sudo service cron stop && killall-g oref0-pump-loop && shutdown -c` * Install ccprog tools on your Edison: `cd ~/src; git clone https://github.com/ps2/ccprog.git` * Build (compile) ccprog so you can run it: `cd ccprog; make ccprog` * If using a Raspberry Pi with Explorer HAT make sure you've installed MRAA (folder `~/src/mraa` present) diff --git a/docs/docs/Understanding OpenAPS-Overview/using-the-docs.md b/docs/docs/Understanding OpenAPS-Overview/using-the-docs.md index d28513fbb..5ed9bfb70 100644 --- a/docs/docs/Understanding OpenAPS-Overview/using-the-docs.md +++ b/docs/docs/Understanding OpenAPS-Overview/using-the-docs.md @@ -20,12 +20,17 @@ See the top left of the docs for the search box. It's best to search *inside* th You may notice that the left hand side of the documentation has navigation. It is organized in order of setting up OpenAPS, and has various sections on finding your gear; what you should do before you build a rig; how to setup up your rig; and additional features and tips and tricks for optimizing your looping setup. This navigation is long, you can mouse over the section and scroll down to see all the pages listed in the top-level navigation! +
+ Click here to expand some pictures that show the left hand navigation + ![Show documentation navigation](../Images/Understand_documentation_basic_1.png) ![Show documentation navigation 2](../Images/Understand_documentation_basic_2.png) ![Show troubleshooting section of docs](../Images/Troublshooting_docs_section.png) +
+ You'll also notice that there is more content than just these high-level pages! If you click on a link in the left, many of them expand to show the sub-sections include, which make it easy to jump directly to the section you're looking for. If there is a `+`, that means there is more content you can expand. ![Show how menu expands in the navigation of the docs](../Images/Show_nav_expand.png) From 17d69bec528e68e663dae9f2f3784086b7a0ee82 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 24 Feb 2020 12:10:26 -0500 Subject: [PATCH 06/13] Preserve text primarily directing people to Gitter for real-time support --- .../communication-support-channels.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md index ca0f8488e..795fd4838 100644 --- a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md +++ b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md @@ -7,13 +7,13 @@ There are several ways to communicate with other participants and contributors i **Note:** It's best practice not to share your pump's serial number, so make sure not to include it in pictures or pasted text output when seeking help on pump communication. Ditto for Nightscout URL and API secret and other private information that could enable someone to access your setup. ### Slack -There is a [Slack channel](https://omniapsslack.azurewebsites.net/) that you can add yourself to - then look for the `#OpenAPS` channel to post questions. This is the best place to get real-time support with anything related to OpenAPS. It is a great place to introduce yourself and get some help from those who are a few steps further down the road. That slack can also be used to stay up to date on other, broader DIY diabetes projects such as communication around other pumps that are being explored and worked on, but aren't yet DIY loopable. +There is a [Slack channel](https://omniapsslack.azurewebsites.net/) that you can add yourself to - then look for the `#OpenAPS` channel to post questions. That slack can also be used to stay up to date on other, broader DIY diabetes projects such as communication around other pumps that are being explored and worked on, but aren't yet DIY loopable. ### Google Group A google group focused on #OpenAPS development work can be found [here](https://groups.google.com/d/forum/openaps-dev) - everyone is encouraged and welcome to join! You can add yourself directly to the group. It's worth setting your preferences to receive all email from the group; there's not a huge volume, and this is one of the ways we share updates about hardware or release announcements if you're not hanging out on Gitter or Facebook or Twitter. However, please note that troubleshooting questions about rig setups are best posted to Slack - email tends to be slower and you will likely be redirected to another channel if you're actively working to resolve a setup problem. ### Gitter -[Gitter](https://gitter.im/) is a messaging/chat service similar to IRC. It provides integration with GitHub and several other services. It's the best place to get real-time support with anything related to OpenAPS. (Here's [why we often recommend asking questions on Gitter](https://diyps.org/2016/08/17/why-you-should-post-questions-in-gitter/).) +[Gitter](https://gitter.im/) is a messaging/chat service similar to IRC. It provides integration with GitHub and several other services. It's the best place to get real-time support with anything related to OpenAPS. It is a great place to introduce yourself and get some help from those who are a few steps further down the road. (Here's [why we often recommend asking questions on Gitter](https://diyps.org/2016/08/17/why-you-should-post-questions-in-gitter/).) * The [nightscout/intend-to-bolus]( https://gitter.im/nightscout/intend-to-bolus) channel is where you will find active #OpenAPS discussions ranging from technical issues with openaps tools to control theory to general information. * For Autotune conversations, use the [openaps/autotune channel](https://gitter.im/openaps/autotune) From b8e81226133ae81976c653aed24c418487b95ea3 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 24 Feb 2020 12:58:56 -0500 Subject: [PATCH 07/13] de-duplicate Google Group info --- .../communication-support-channels.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md index 795fd4838..e971a32cf 100644 --- a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md +++ b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md @@ -9,9 +9,6 @@ There are several ways to communicate with other participants and contributors i ### Slack There is a [Slack channel](https://omniapsslack.azurewebsites.net/) that you can add yourself to - then look for the `#OpenAPS` channel to post questions. That slack can also be used to stay up to date on other, broader DIY diabetes projects such as communication around other pumps that are being explored and worked on, but aren't yet DIY loopable. -### Google Group -A google group focused on #OpenAPS development work can be found [here](https://groups.google.com/d/forum/openaps-dev) - everyone is encouraged and welcome to join! You can add yourself directly to the group. It's worth setting your preferences to receive all email from the group; there's not a huge volume, and this is one of the ways we share updates about hardware or release announcements if you're not hanging out on Gitter or Facebook or Twitter. However, please note that troubleshooting questions about rig setups are best posted to Slack - email tends to be slower and you will likely be redirected to another channel if you're actively working to resolve a setup problem. - ### Gitter [Gitter](https://gitter.im/) is a messaging/chat service similar to IRC. It provides integration with GitHub and several other services. It's the best place to get real-time support with anything related to OpenAPS. It is a great place to introduce yourself and get some help from those who are a few steps further down the road. (Here's [why we often recommend asking questions on Gitter](https://diyps.org/2016/08/17/why-you-should-post-questions-in-gitter/).) @@ -77,5 +74,5 @@ One of the above channels is the best place for real-time or near-time troublesh ### Other online forums Those in the #OpenAPS community are frequently found in other forums, such as on Twitter (using [the #OpenAPS hashtag](https://twitter.com/search?f=tweets&vertical=default&q=%23OpenAPS&src=typd), as well as [#WeAreNotWaiting](https://twitter.com/search?f=tweets&vertical=default&q=%23WeAreNotWaiting&src=typd)) and on Facebook in the ["CGM In The Cloud"](https://www.facebook.com/groups/cgminthecloud/) and ["Looped"](https://www.facebook.com/groups/TheLoopedGroup/)group. -### Google Group - everyone is welcome to join! -A google group focused on #OpenAPS development work can be found [here](https://groups.google.com/d/forum/openaps-dev). You can add yourself directly to the group. It's worth setting your preferences to receive all email from the group; there's not a huge volume. However, please note that troubleshooting questions about rig setups are best posted to Slack or Gitter - email tends to be slower and you will likely be redirected to another channel if you're actively working to resolve a setup problem. +### Google Group +A google group focused on #OpenAPS development work can be found [here](https://groups.google.com/d/forum/openaps-dev) - everyone is encouraged and welcome to join! You can add yourself directly to the group. It's worth setting your preferences to receive all email from the group; there's not a huge volume, and this is one of the ways we share updates about hardware or release announcements if you're not hanging out on Gitter or Facebook or Twitter. However, please note that troubleshooting questions about rig setups are best posted to Gitter or Slack - email tends to be slower and you will likely be redirected to another channel if you're actively working to resolve a setup problem. \ No newline at end of file From 0875fca710b1612bb454ddcf8cc54fdc1baddbd1 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 24 Feb 2020 13:16:26 -0500 Subject: [PATCH 08/13] fix long error lines that run off the page --- docs/docs/Build Your Rig/step-1-flashing.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/docs/Build Your Rig/step-1-flashing.md b/docs/docs/Build Your Rig/step-1-flashing.md index 6a88c358a..50d03f7b4 100644 --- a/docs/docs/Build Your Rig/step-1-flashing.md +++ b/docs/docs/Build Your Rig/step-1-flashing.md @@ -97,7 +97,11 @@ If you do not have your Edison password at this point, don't panic. We are only ### If you’re using a Mac - starting flash: - In the "flash window" from the Download Image instructions above, run `./flashall.sh`. - If you receive an `dfu-util: command not found` error, you can install dfu-util by following [the Mac instructions here](https://software.intel.com/en-us/node/637974#manual-flash-process). - - If you receive an `Error: Running Homebrew as root is extremely dangerous and no longer supported. As Homebrew does not drop privileges on installation you would be giving all build scripts full access to your system.` see the troubleshooting section below. + - If you receive an + ``` + Error: Running Homebrew as root is extremely dangerous and no longer supported. As Homebrew does not drop privileges on installation you would be giving all build scripts full access to your system. + ``` + see the troubleshooting section below. ### If you're using a Windows PC - starting flash: - In the "flash window" from the Download Image instructions above, run `flashall.bat` @@ -187,7 +191,11 @@ U-boot & Kernel System Flash Success... in something closer to 10 seconds than 10 minutes, then you likely didn't set up swap properly. To verify, `cat flash.log` and look for `dfu-util: Cannot allocate memory of size 1610612736 bytes` near the end. Alternatively, [this newer version of DFU Util](https://sourceforge.net/projects/dfu-util/files/latest/download) (DFU Util v0.9) seems to work better on computers with lots of RAM. -c) If you recieve an `Error: Running Homebrew as root is extremely dangerous and no longer supported. As Homebrew does not drop privileges on installation you would be giving all build scripts full access to your system.` it means that you have a recent copy of homebrew (that's good) which doesn't allow sudo to even do a `brew list`. +c) If you recieve an +``` +Error: Running Homebrew as root is extremely dangerous and no longer supported. As Homebrew does not drop privileges on installation you would be giving all build scripts full access to your system. +``` +it means that you have a recent copy of homebrew (that's good) which doesn't allow sudo to even do a `brew list`. * The _easiest_ - but perhaps not so forward compatible - thing is to figure out what the brew command was trying to do and edit the `flashall.sh` script accordingly. ** The v0.2.0 version of `flashapp.sh` has `$(brew list gnu-getopt | grep bin/getopt)`. From aea842631ae6d550917fb9b37e84de994ba7238a Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 24 Feb 2020 13:23:25 -0500 Subject: [PATCH 09/13] fix typo to make sure oref0-setup actually shows up in TOC --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 71d88956e..501aa507d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -120,7 +120,7 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of :caption: Troubleshooting Overview and Linux reference - oref0-setup Troubleshooting Common error messages Wifi and hotspot issues Pump-rig communications troubleshooting From 2818d005d2b2055aa1c878f07eaef4493e81958f Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 24 Feb 2020 13:26:55 -0500 Subject: [PATCH 10/13] fix quoted tick marks in setup script command; put who should do log rotate fix in header --- docs/docs/Build Your Rig/step-3-setup-script.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/docs/Build Your Rig/step-3-setup-script.md b/docs/docs/Build Your Rig/step-3-setup-script.md index a1cd99d52..d8b97b517 100644 --- a/docs/docs/Build Your Rig/step-3-setup-script.md +++ b/docs/docs/Build Your Rig/step-3-setup-script.md @@ -6,7 +6,9 @@ Log in to your rig and run the following command (aka "the setup script"): - `cd && ~/src/oref0/bin/oref0-setup.sh` +``` +cd && ~/src/oref0/bin/oref0-setup.sh +``` 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, you likely forgot to enter `edison` at the first prompt for changing the password. @@ -37,11 +39,9 @@ After the setup script finishes building your loop (called myopenaps), it will a ************************** -## Log rotate fix +## Log rotate fix for versions < 0.6.1 -
- Click here to expand notes about checking log rotate, which was fixed in 0.6.1: -
+This was fixed in version 0.6.1, but if you are running an older version you should complete the following: 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! @@ -54,8 +54,6 @@ Make sure that at the end of the setup script, your log rotate file is set to `d ![Log rotation examples](../Images/Edison/log_rotation.png) -
- ## 512 and 712 Pump users only - important extra setup steps **For releases 0.7.0 and beyond, all of this is done automatically; please skip this step.** From 0b613bf2ee4f6ded0b5b77e582502bb020a2ca91 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 26 Feb 2020 10:12:46 -0500 Subject: [PATCH 11/13] fix or remove broken links --- docs/docs/Build Your Rig/step-4-watching-log.md | 2 +- docs/docs/Gear Up/edison-explorer-board.md | 10 ++++------ docs/docs/Resources/Deprecated-Pi/Pi-setup.md | 2 +- docs/docs/Troubleshooting/Common-error-messages.md | 2 +- docs/docs/Usage and maintenance/update-your-rig.md | 2 +- .../Usage and maintenance/usability-considerations.md | 5 +++-- 6 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/docs/Build Your Rig/step-4-watching-log.md b/docs/docs/Build Your Rig/step-4-watching-log.md index d9ed55b2e..f70cb851a 100644 --- a/docs/docs/Build Your Rig/step-4-watching-log.md +++ b/docs/docs/Build Your Rig/step-4-watching-log.md @@ -75,7 +75,7 @@ Finally, you should eventually see colorful indications of successful looping, w ![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 - e.g. 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. ([For more details on how to interpret the OpenAPS math and information, see this page for understanding OpenAPS determine-basal](<../How it works/understand-determine-basal#summary-of-outputs>).) +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 - e.g. 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. ([For more details on how to interpret the OpenAPS math and information, see this page for understanding OpenAPS determine-basal](<../How it works/understand-determine-basal>).) 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](<../Troubleshooting/oref0-setup-troubleshooting>) 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. diff --git a/docs/docs/Gear Up/edison-explorer-board.md b/docs/docs/Gear Up/edison-explorer-board.md index 9faf25d6b..9e01707f0 100644 --- a/docs/docs/Gear Up/edison-explorer-board.md +++ b/docs/docs/Gear Up/edison-explorer-board.md @@ -30,7 +30,7 @@ There are 4 types of Edison's. All of them work, but Versions 3 and 4 require an The Explorer Boards have battery charger circuitry on board, making it easy to use a LiPo battery. -* The example setup uses a [2000mah LiPo battery](http://www.robotshop.com/en/37v-2000mah-5c-lipo-battery.html); also [Lithium Ion Battery - 3.7v 2000mAh](https://www.adafruit.com/products/2011) or [Adafruit Battery Packs Lithium Ion Battery 3.7v 2000mAh](https://www.amazon.com/Battery-Packs-Lithium-3-7v-2000mAh/dp/B0137ITW46) are similar options. A 2000 mAh LiPo will get you about 12-14 hours of use, assuming you have the standard setup (which is what you get following these docs) running. Many people prefer a higher capacity battery to get a full day from the rig (such as [Adafruit Lithium Ion Polymer Battery - 3.7v 2500mAh (PRODUCT ID: 328) and the Adafruit Lithium Ion Cylindrical Battery - 3.7v 2200mAh (PRODUCT ID: 1781)](https://www.adafruit.com/category/574)). This battery uses a 2mm 2 pin JST connector to match the Explorer boards' power plugs. +* The example setup uses a [2000mah LiPo battery](http://www.robotshop.com/en/37v-2000mah-5c-lipo-battery.html); this [Lithium Ion Battery - 3.7v 2000mAh](https://www.adafruit.com/products/2011) is a similar option. A 2000 mAh LiPo will get you about 12-14 hours of use, assuming you have the standard setup (which is what you get following these docs) running. Many people prefer a higher capacity battery to get a full day from the rig (such as [Adafruit Lithium Ion Polymer Battery - 3.7v 2500mAh (PRODUCT ID: 328) and the Adafruit Lithium Ion Cylindrical Battery - 3.7v 2200mAh (PRODUCT ID: 1781)](https://www.adafruit.com/category/574)). This battery uses a 2mm 2 pin JST connector to match the Explorer boards' power plugs. * For people in the UK, you may find you have to shop around to find the correct battery, as shipping restrictions appears to have reduced the supply somewhat. [Pimoroni](https://shop.pimoroni.com/products/lipo-battery-pack) appear to stock the same Adafruit 2000mAh battery as mentioned above. Another source looks to be [Cool Components](https://www.coolcomponents.co.uk/en/lithium-polymer-battery-2000mah.html), but you may find shipping costs expensive. CAUTION: [RS Online](https://uk.rs-online.com/mobile/p/lithium-rechargeable-battery-packs/1251266/) sell a similar battery, but unfortunately it comes with the wrong JST connector (it comes with a 2.5mm JST XHP-2, and you need a 2mm JST PH). It is possible, however, to buy the [right connectors](https://www.technobotsonline.com/jst-ph-2mm-2-way-housing-excludes-female-pins.html) and fit them yourself (numerous 'how to' videos on YouTube). * For people in Australia you can find 2000mAh, 2200mAh and 2500mAh batteries from [Little bird electronics](https://www.littlebirdelectronics.com.au/batteries/), prices are very competitive and shipping is quick. These are the same Adafruit batteries that can be obtained from the US above. @@ -54,7 +54,7 @@ We recommend an Explorer Board with a built-in radio ([see above](<#explorer-boa The following options are not yet documented for oref0 versions < 0.7.0, and may not work anymore: -If you don't use an Explorer board, you can use a number of radio sticks: a [TI-USB-Sticks](http://www.ti.com/tool/cc1111emk868-915), running [subg_rfspy](https://github.com/ps2/subg_rfspy); [Wireless Things ERF](https://www.wirelessthings.net/erf-0-1-pin-spaced-radio-module); [Wireless Things Slice of Radio](https://www.wirelessthings.net/slice-of-radio-wireless-rf-transciever-for-the-raspberry-pi) a Slice of Radio; or a Rileylink. For details about setup with these other stick and board options, [the best instructions will be found in the mmeowlink wiki](https://github.com/oskarpearson/mmeowlink/wiki) for setting up your board and stick. Note you may also need a CC debugger for these, and also note that it will be more work as the documentation is designed for the Edison/Explorer Board setup as the easiest path forward. +If you don't use an Explorer board, you can use a number of radio sticks: a [TI-USB-Sticks](http://www.ti.com/tool/cc1111emk868-915), running [subg_rfspy](https://github.com/ps2/subg_rfspy); a Wireless Things ERF or Slide of Radio (not currently available); or a Rileylink. For details about setup with these other stick and board options, [the best instructions will be found in the mmeowlink wiki](https://github.com/oskarpearson/mmeowlink/wiki) for setting up your board and stick. Note you may also need a CC debugger for these, and also note that it will be more work as the documentation is designed for the Edison/Explorer Board setup as the easiest path forward. ### USB Cables @@ -102,9 +102,8 @@ Also: a hard case may make you less likely to look at your rig directly. You sho Generic hard cases: -* [RadioShack Project Enclosure (3x2x1 inch)](https://www.radioshack.com/products/radioshack-project-enclosure-3x2x1?utm_medium=cpc&utm_source=googlepla&variant=20332262405&gclid=Cj0KEQiA-MPCBRCZ0q23tPGm6_8BEiQAgw_bAkpDZCXfIgbEw8bq76VHtV5mLwR2kHKfJrsGsF3uqqgaAtxP8P8HAQ) -* [Small clear plastic case perfect for larger Sparkfun 2000 mAh battery: #8483](http://www.ebay.com/itm/272062812611) -* [Small Plastic Clear Case for 2500 mAh battery](http://www.ebay.com/itm/272062812611) - Since a Tic-Tac box is too small for the 2500 mAh battery. +* [RadioShack Project Enclosure (3x2x1 inch)](https://www.radioshack.com/products/radioshack-project-enclosure-3x2x1) +* People have sometimes found small clear plastic cases that fit well, but the specific items previously listed here are no longer sold. If you find a case that's just right for your rig, add a link here! Cases for Edison plus battery: @@ -114,7 +113,6 @@ Cases for Edison plus battery: * [Sulka Haro's 3D design](https://www.tinkercad.com/things/4a6VffpcuNt) * [tazitoo's 3D design: CAD](https://www.tinkercad.com/things/aRYGnHXt7Ta-explorer-case/editv2) ([or STL for 3D printing](http://www.thingiverse.com/thing:2106917)) * [danimaniac's Protective Cases & Accessories](https://github.com/danimaniac/OpenAPS-Explorer-Board-Edison-vented-case) -* [Luis's ventilated acrylic simple design](https://drive.google.com/drive/folders/0BxeFg9yJZ_FZdWJEcG5KMXdUMjg?usp=sharing) * [Robert Silvers and Eric Burt's case for Explorer and 2500 mAh battery](http://www.thingiverse.com/thing:2282398) * [Robert Silvers' case for Explorer and 2000 or 2500 mAh battery](http://www.thingiverse.com/thing:2291125) * [tynbendad's case for 18650 battery](https://www.thingiverse.com/thing:2798858) diff --git a/docs/docs/Resources/Deprecated-Pi/Pi-setup.md b/docs/docs/Resources/Deprecated-Pi/Pi-setup.md index 3444be7df..a5e8bab2f 100644 --- a/docs/docs/Resources/Deprecated-Pi/Pi-setup.md +++ b/docs/docs/Resources/Deprecated-Pi/Pi-setup.md @@ -2,7 +2,7 @@ ## WARNING - THIS DOCUMENT IS DEPRECATED (NOT RECOMMENDED) AND UNMAINTAINED. We suggest you look to the top of the docs for information on the currently recommended hardware setup instead. As of November 2017 there are new and simplified Raspberry Pi setup instructions linked from there. The instructions below should only be used for troubleshooting purposes if the new instructions aren't working. -Note: There are two setup flows described on this page. The [one toward the bottom of the page is the older setup instructions](<../Resources/Deprecated-Pi/pi-setup#older-instructions-for-original-pi-based-setups>) that worked back in the day. The [one at the top of the page (all prefaced with "newer path")](<../Resources/Deprecated-Pi/pi-setup#newer-path>) is an attempt by someone to make the Pi instructions work for Pi3 and Pi0W. There may be issues with BOTH setups, so please do make PRs to this page and/or discuss on Gitter about which setup flow works. +Note: There are two setup flows described on this page. The [one toward the bottom of the page is the older setup instructions](<#older-instructions-for-original-pi-based-setups>) that worked back in the day. The [one at the top of the page (all prefaced with "newer path")](<#newer-path>) is an attempt by someone to make the Pi instructions work for Pi3 and Pi0W. There may be issues with BOTH setups, so please do make PRs to this page and/or discuss on Gitter about which setup flow works. ## Newer Path diff --git a/docs/docs/Troubleshooting/Common-error-messages.md b/docs/docs/Troubleshooting/Common-error-messages.md index 8cc3d98a8..908834b01 100644 --- a/docs/docs/Troubleshooting/Common-error-messages.md +++ b/docs/docs/Troubleshooting/Common-error-messages.md @@ -160,4 +160,4 @@ If your disk is still 100% full, you may have to remove a live log file. Run the ## Errors during `openaps report invoke monitor/ns-glucose.json` or `ns-upload.sh` -If you are getting your BG from Nightscout or you want to upload loop status/results to Nightscout, among other things you'll need to set 2 environment variables: `NIGHTSCOUT_HOST` and `API_SECRET`. This is handled in the setup script. If you do not set and export these variables you will receive errors while running `openaps report invoke monitor/ns-glucose.json` and while executing `ns-upload.sh` script which is most probably part of your `upload-recent-treatments` alias.Make sure your `API_SECRET` is in hashed format. Please see [this page](https://github.com/openaps/oref0#ns-upload-entries) or [this issue](https://github.com/openaps/oref0/issues/397) for details. Additionally, your `NIGHTSCOUT_HOST` should be in a format like `http://yourname.herokuapp.com` (without trailing slash). For the complete visualization guide use [this page](https://github.com/openaps/docs/blob/master/docs/Automate-system/vizualization.md) from the OpenAPS documentation. \ No newline at end of file +If you are getting your BG from Nightscout or you want to upload loop status/results to Nightscout, among other things you'll need to set 2 environment variables: `NIGHTSCOUT_HOST` and `API_SECRET`. This is handled in the setup script. If you do not set and export these variables you will receive errors while running `openaps report invoke monitor/ns-glucose.json` and while executing `ns-upload.sh` script which is most probably part of your `upload-recent-treatments` alias.Make sure your `API_SECRET` is in hashed format. Please see [this page](https://github.com/openaps/oref0#ns-upload-entries) or [this issue](https://github.com/openaps/oref0/issues/397) for details. Additionally, your `NIGHTSCOUT_HOST` should be in a format like `http://yourname.herokuapp.com` (without trailing slash). For the complete guide to setting up Nightscout see [this page](<../While You Wait For Gear/nightscout-setup>). \ No newline at end of file diff --git a/docs/docs/Usage and maintenance/update-your-rig.md b/docs/docs/Usage and maintenance/update-your-rig.md index e16fcd9c8..395f13aba 100644 --- a/docs/docs/Usage and maintenance/update-your-rig.md +++ b/docs/docs/Usage and maintenance/update-your-rig.md @@ -46,7 +46,7 @@ In case you want to test even more advanced stuff you've read about on gitter ch ## Step 2: Re-run oref0-setup -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](<../Build Your Rig/step-3-setup-script#be-prepared-to-enter-the-following-information-into-oref0-setup>) for a guide of what the setup script will be prompting you to enter. +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](<../Build Your Rig/step-3-setup-script#be-prepared-to-enter-the-following-information-into-the-setup-script>) for a guide of what the setup script will be prompting you to enter. ## Step 3: Remember to set your preferences! diff --git a/docs/docs/Usage and maintenance/usability-considerations.md b/docs/docs/Usage and maintenance/usability-considerations.md index cce3bb769..22c25b92b 100644 --- a/docs/docs/Usage and maintenance/usability-considerations.md +++ b/docs/docs/Usage and maintenance/usability-considerations.md @@ -6,8 +6,9 @@ Now that you've closed the loop, you probably have a lot of new "first" experien - [What do you do with the loop in airport security when you travel](#what-do-you-do-with-the-loop-in-airport-security-when-you-travel) - [What do you do with your loop when you travel across timezones? How do you update devices for a time zone change?](#what-do-you-do-with-your-loop-when-you-travel-across-timezones-how-do-you-update-devices-for-a-time-zone-change) - [What do you do with the loop when you shower?](#what-do-you-do-with-the-loop-when-you-shower) -- [What do you do when you change sites?](#what-do-you-do-when-you-change-sites-) -- [How do I switch to a different Medtronic pump?](#how-do-i-switch-to-a-different-medtronic-pump-) +- [What do you do when you change sites?](#what-do-you-do-when-you-change-sites) +- [How do I switch to a different Medtronic pump?](#how-do-i-switch-to-a-different-medtronic-pump) +https://draft-openaps-reorg.readthedocs.io/en/reapply-cleanup/docs/Usage%20and%20maintenance/usability-considerations.html#how-do-i-switch-to-a-different-medtronic-pump - [What do you do when you exercise?](#what-do-you-do-when-you-exercise) - [What do you do if you want to be off the pump for long periods during a day when you're really active? Like for the beach or water park or sporting activity or similar?](#what-do-you-do-if-you-want-to-be-off-the-pump-for-long-periods-during-a-day-when-you-re-really-active-like-for-the-beach-or-water-park-or-sporting-activity-or-similar) - [What if I want to turn off the loop for a while?](#what-if-i-want-to-turn-off-the-loop-for-a-while) From 147033eab953e580ccc020e5232b96de0c31bb31 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 26 Feb 2020 11:32:14 -0500 Subject: [PATCH 12/13] update or remove most remaining broken links, with the exception of a few that are already noted in the text as not working (e.g. hot button app link) and images in the deprecated pi setup page --- .../Build Your Rig/step-2-wifi-dependencies.md | 2 +- .../offline-looping-and-monitoring.md | 2 +- docs/docs/Customize-Iterate/useful-mobile-apps.md | 2 +- docs/docs/Gear Up/pi-based-rigs.md | 6 +++--- docs/docs/Gear Up/rig-options.md | 2 +- .../understanding-insulin-on-board-calculations.md | 2 +- .../Resources/switching-between-DIY-systems.md | 14 +++++++------- docs/docs/Resources/technical-resources.md | 4 ++-- .../Troubleshooting/oref0-setup-troubleshooting.md | 4 ++-- .../Usage and maintenance/monitoring-OpenAPS.md | 2 +- .../preferences-and-safety-settings.md | 4 ++-- .../docs/Usage and maintenance/running-autotune.md | 6 +++--- 12 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md index 72f0b3d7f..12c6ed430 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -311,7 +311,7 @@ Once your setup script finishes, **make sure to [watch the pump loop logs](<../B **NOTE**: If you are using RFM69HCW as RF module: -If you have connected your RFM69HCW module as described in [Soldering RFM69HCW](<../Gear Up/edison#soldering>), while running interactive setup use following option: +If you have connected your RFM69HCW module as described in [Soldering RFM69HCW](<../Gear Up/pi-based-rigs#soldering>), while running interactive setup use following option: ``` 3) RFM69HCW (DIY: SPI) ``` diff --git a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md index 7a7555aaa..9f357f38e 100644 --- a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md +++ b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md @@ -48,7 +48,7 @@ The second method involves installing an application called xDripAPS onto your r **EASIEST:** For either Android or iPhone G4/G5 users, you can plug the CGM receiver directly into your rig via USB. This will pull BGs into the rig directly from the receiver and be used for looping. If you are a G4 user, this should also bring RAW BG data into the rig during sensor restarts or ??? times (although multiple users with pediatric model G4 receivers have reported inability to obtain raw data. This seems to be related to a firmware difference between adult and pediatric G4 receivers). The rig will loop using RAW BGs so long as the BG value is under 150 mg/dl. A few notes about how to make the direct-receiver configuration work: - * Explorer boards built prior to late January of 2017 are not always working well/automatically with a CGM receiver plugged in. These boards can be identified by looking to see if they say "2016" on the board's label tag, as shown in the photo below. The boards can be fixed to use a CGM receiver by making a single trace cut, but doing so will disable the board's the ability to re-flash your Edison. Please make sure you have a second Explorer board or another base block or breakout board that you can use to re-flash the Edison if needed before considering this modification. For more details, see [this issue](https://github.com/EnhancedRadioDevices/915MHzEdisonExplorer/issues/14), and if you decide to make the cut, see [this document for details on how to cut the copper trace from pin 61 of the 70 pin connector](https://github.com/EnhancedRadioDevices/915MHzEdisonExplorer/wiki#usb-otg-flakiness). Cut in two places and dig out the copper between. Cut by poking a razor point in. Avoid the narrow trace above the one being cut. + * Explorer boards built prior to late January of 2017 are not always working well/automatically with a CGM receiver plugged in. These boards can be identified by looking to see if they say "2016" on the board's label tag, as shown in the photo below. The boards can be fixed to use a CGM receiver by making a single trace cut, but doing so will disable the board's the ability to re-flash your Edison. Please make sure you have a second Explorer board or another base block or breakout board that you can use to re-flash the Edison if needed before considering this modification. For more details, see [this issue](https://github.com/EnhancedRadioDevices/915MHzEdisonExplorer/issues/14), and if you decide to make the cut, see [this document for details on how to cut the copper trace from pin 61 of the 70 pin connector](https://github.com/EnhancedRadioDevices/915MHzEdisonExplorer/wiki#usb-otg-issue-on-beta-board). Cut in two places and dig out the copper between. Cut by poking a razor point in. Avoid the narrow trace above the one being cut. * Explorer Boards that shipped at or after the end of February 2017/first week of March 2017 should enable users to simply plug in the CGM receiver to the OTG port, and a USB battery into the UART port, in order to run offline and pull BGs from the receiver. Those boards will have a label of v1.2 2017. diff --git a/docs/docs/Customize-Iterate/useful-mobile-apps.md b/docs/docs/Customize-Iterate/useful-mobile-apps.md index 1c2030b53..a0033cd05 100644 --- a/docs/docs/Customize-Iterate/useful-mobile-apps.md +++ b/docs/docs/Customize-Iterate/useful-mobile-apps.md @@ -123,7 +123,7 @@ If you want to run a particular command, just click on the command & confirm whi #### SimpleSSH file navigation -Perhaps a more slightly advanced-user (or curious-user) feature of SimpleSSH is the ability to use the file/directory navigator. The navigator (accessed using the magnifying glass icon in Hosts page) will allow you to peruse the various directories and files used by your rig and openaps. If you wanted to see your oref0 code, it is stored in the `root/src/oref0` folder. Or if you wanted to see your loop directory, you could navigate to your `root/myopenaps` folder. This can be particularly useful if you are getting troubleshooting help and someone asks "What does your pumphistory.json show?"...you could easily navigate to that file and copy the contents of it. (Note: For further reading about the file structure of your loop and rig, see [here](<../Troubleshooting/general_linux_troubleshooting#directories-on-your-rig>) For example, here's the navigation chain to find your pumphistory.json: +Perhaps a more slightly advanced-user (or curious-user) feature of SimpleSSH is the ability to use the file/directory navigator. The navigator (accessed using the magnifying glass icon in Hosts page) will allow you to peruse the various directories and files used by your rig and openaps. If you wanted to see your oref0 code, it is stored in the `root/src/oref0` folder. Or if you wanted to see your loop directory, you could navigate to your `root/myopenaps` folder. This can be particularly useful if you are getting troubleshooting help and someone asks "What does your pumphistory.json show?"...you could easily navigate to that file and copy the contents of it. (Note: For further reading about the file structure of your loop and rig, see [here](<../Troubleshooting/General_linux_troubleshooting#directories-on-your-rig>) For example, here's the navigation chain to find your pumphistory.json: ![SimpleSSH navigation example](../Images/navigate.png) diff --git a/docs/docs/Gear Up/pi-based-rigs.md b/docs/docs/Gear Up/pi-based-rigs.md index f99454205..79ee50800 100644 --- a/docs/docs/Gear Up/pi-based-rigs.md +++ b/docs/docs/Gear Up/pi-based-rigs.md @@ -132,7 +132,7 @@ Here's a rough-and-ready budget version of a rig put together: contents of a 200 ### Summary of what you need: * Raspberry Pi Zero * RFM69HCW -* [microSD Card](<../Gear Up/edison-explorer-board#sd-card>) +* [microSD Card](<#sd-card>) * Bread board * Jumper wires * Soldering iron @@ -188,7 +188,7 @@ Summary of what you need for a Pi/Bonnet rig: There is be a Pi+Bonnet rig as an option for closing the loop with OpenAPS. This hardware is available from Adafruit, and is called the [Adafruit RFM69HCW Transceiver Radio Bonnet - 868 or 915 MHz - RadioFruit](https://www.adafruit.com/product/4072). As of October 2019, this hardware is supported via automated setup via `oref0-setup.sh`. #### PI -You also need a Raspberry Pi. Many users are opting for the "Raspberry Pi Zero WH" - with headers - so you don't have to solder, and can simply add the HAT onto the Pi. See this [PiZeroWH from Adafruit](https://www.adafruit.com/product/3708), or [from other sellers around the world](https://www.raspberrypi.org/products/#buy-now-modal) +You also need a Raspberry Pi. Many users are opting for the "Raspberry Pi Zero WH" - with headers - so you don't have to solder, and can simply add the HAT onto the Pi. See this [PiZeroWH from Adafruit](https://www.adafruit.com/product/3708), or [from other sellers around the world](https://www.raspberrypi.org/products/) As an alternative, you can also use the bonnet with a Raspberry Pi 2/3/4. @@ -331,7 +331,7 @@ Here's a rough-and-ready budget version of a rig put together: contents of a 200 ### Summary of what you need: * Raspberry Pi Zero * RFM69HCW -* [microSD Card]((<../Gear Up/pi-based-rigs#sd-card)) +* [microSD Card]((<../Gear Up/pi-based-rigs#sd-card>)) * Bread board * Jumper wires * Soldering iron diff --git a/docs/docs/Gear Up/rig-options.md b/docs/docs/Gear Up/rig-options.md index 439cca11d..21cde1a31 100644 --- a/docs/docs/Gear Up/rig-options.md +++ b/docs/docs/Gear Up/rig-options.md @@ -6,7 +6,7 @@ You have several options for hardware: 2. The other option is a Raspberry Pi-based setup, with the new Explorer HAT. This rig setup makes it easier to see information when offline because it has an onboard screen for displaying readouts. [Go here for hardware required and setup instructions for Pi/HAT setups](<../Gear Up/pi-based-rigs>). There is also an experimental alternative to an Explorer HAT, RFM69HCW, which can serve as the radio on a Pi-based rig, but will not have the screen, and requires you to solder. -3. Yet another option is a Raspberry Pi-based setup, with an Adafruit RFM69HCW Bonnet. This rig setup makes it easier to see information when offline because it has a small onboard screen for displaying readouts, but it does not come with charging hardware for a battery like the Explorer HAT or Explorer Board. You will need to build your own charging circuit or use a USB power block if you want to make this rig portable. However, this makes an excellent stationary or backup rig! [See here for the list of hardware required for Pi/Bonnet setups](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-the-adafruit-rfm69hcw-bonnet>). +3. Yet another option is a Raspberry Pi-based setup, with an Adafruit RFM69HCW Bonnet. This rig setup makes it easier to see information when offline because it has a small onboard screen for displaying readouts, but it does not come with charging hardware for a battery like the Explorer HAT or Explorer Board. You will need to build your own charging circuit or use a USB power block if you want to make this rig portable. However, this makes an excellent stationary or backup rig! [See here for the list of hardware required for Pi/Bonnet setups](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-the-adafruit-rhm69hcw-bonnet>). 4. (Not recommended, but supported) There is an experimental alternative to prefabricated hardware on the Raspberry Pi (Explorer HAT or Adafruit Bonnet), which can serve as the radio on a Pi-based rig, but will not have the screen and requires you to solder. [See here for the list of hardware required for more details on a setup with RFM69HCW breakout board](<../Gear Up/pi-based-rigs#hardware-information-for-pi-based-setups-with-rfm69hcw-experimental>). diff --git a/docs/docs/How it works/understanding-insulin-on-board-calculations.md b/docs/docs/How it works/understanding-insulin-on-board-calculations.md index ef610794e..e899c1cf0 100644 --- a/docs/docs/How it works/understanding-insulin-on-board-calculations.md +++ b/docs/docs/How it works/understanding-insulin-on-board-calculations.md @@ -33,7 +33,7 @@ There are three key assumptions the OpenAPS algorithm makes about how insulin ac 100 = (4 \* 60 \* (75 / 180)) -> **NOTE:** The insulin action assumptions described here are set to change with the release of [oref0, version 0.6.0](https://github.com/openaps/oref0/tree/0.6.0-dev). The new assumptions will use exponential functions for the insulin action curves and will allow some user flexibility to use pre-set parameters for different classes of fast-acting insulins (Humalog, Novolog, and Apidra vs. Fiasp, for example). For a discussion of the alternate specifications of insulin action curves, see [oref0 Issue #544](https://github.com/openaps/oref0/issues/544). When oref0, version 0.6.0 is released and the current assumptions are no longer recommended, this documentation will be updated. +> **NOTE:** The insulin action assumptions described here are set to change with the release of [oref0, version 0.6.0](https://github.com/openaps/oref0/releases/tag/v0.6.0). The new assumptions will use exponential functions for the insulin action curves and will allow some user flexibility to use pre-set parameters for different classes of fast-acting insulins (Humalog, Novolog, and Apidra vs. Fiasp, for example). For a discussion of the alternate specifications of insulin action curves, see [oref0 Issue #544](https://github.com/openaps/oref0/issues/544). When oref0, version 0.6.0 is released and the current assumptions are no longer recommended, this documentation will be updated. ## What The Insulin Activity Assumptions Look Like diff --git a/docs/docs/Resources/switching-between-DIY-systems.md b/docs/docs/Resources/switching-between-DIY-systems.md index 70beea447..6944b285d 100644 --- a/docs/docs/Resources/switching-between-DIY-systems.md +++ b/docs/docs/Resources/switching-between-DIY-systems.md @@ -59,7 +59,7 @@ See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.]( ### Getting started on OpenAPS - the setup links #### Installing OpenAPS on your rig -* [Follow these instructions](<../Build Your Rig/index>) (with pictures!) +* [Follow these instructions](<../Build Your Rig/install-overview>) (with pictures!) #### Nightscout * We highly recommend Nightscout. Go to [nightscout.info](http://nightscout.info) if you have not yet setup @@ -71,7 +71,7 @@ See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.]( ### Targets and algorithm differences * Loop pulled targets from the app. OpenAPS pulls targets from the pump. Here’s [more detail on the data OpenAPS pulls and how it outputs data for you to understand the algorithm in action](<../How it works/understand-determine-basal>). -* Loop has temporary targets available by using the workout mode in the Loop app. OpenAPS can have [multiple temp targets](<../How it works/autosens#eating-soon-and-activity-mode-temporary-targets>) (e.g. Eating Soon and Workout, etc., and can be set via the Nightscout Care Portal if the rig is online, and via [IFTTT/Alexa/pebble/scheduled in advance/location based triggers](<../Customize-Iterate/ifttt-integration>). +* Loop has temporary targets available by using the workout mode in the Loop app. OpenAPS can have [multiple temp targets](<../Usage and maintenance/usability-considerations#how-can-you-make-adjustments-to-insulin-delivery-while-on-the-go-optimizing-with-temporary-targets>) (e.g. Eating Soon and Workout, etc., and can be set via the Nightscout Care Portal if the rig is online, and via [IFTTT/Alexa/pebble/scheduled in advance/location based triggers](<../Customize-Iterate/ifttt-integration>). * OpenAPS has no bolus momentum or safety guard that prevent boluses; but has other key safety settings (see below) ### “MaxIOB” and other safety settings @@ -87,13 +87,13 @@ See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.]( * **“Max Basal”** refers to the max basal set on the pump. (If you change this, it will be read in the next time your rig pulls pump settings.) * **“Max Daily Safety Multiplier”** limits the temp basal set by OpenAPS loop to be a multiplier of your HIGHEST regularly-scheduled basal rate in the pump. The default setting for this multiplier is 3x...meaning no more than three times your maximum programmed basal rate for the day. If someone tells you your basal is capped by the “3x max daily; 4x current” for safety caps, this is what they'd be referring to. * **“Max Current Basal Safety Multiplier”:** limits the temp basal set by OpenAPS loop to be a multiplier of your CURRENT regularly-scheduled basal rate in the pump. The default setting for this multiplier is 4x...meaning no more than four times your current programmed basal rate. -* Read about [all of the other optional safety settings here](<../Usage and maintenance/preferences-and-safety-settings#understanding-your-preferences-json>). +* Read about [all of the other optional safety settings here](<../Usage and maintenance/preferences-and-safety-settings>). ### Parents in particular may want to review the optional settings * Parents should [read this blog post by Katie DiSimone for a parent's perspective about various pros/cons](http://seemycgm.com/2017/02/01/loop-vs-openaps/) for parents and kids evaluating DIY closed loop systems. -* **Override the high target with the low** ([see this explanation](<../Usage and maintenance/preferences-and-safety-settings#override-high-target-with-low>) for enabling this feature) - * This makes it easier for secondary caregivers (like school nurses) to do conservative boluses at lunch/snack time, and allow the closed loop to pick up from there. The secondary caregiver can use the bolus wizard, which will correct down to the high end of the target; and setting this value in preferences to “true” allows the closed loop to target the low end of the target. Based on anecdotal reports from those using it, this feature sounds like it’s prevented a lot of (unintentional, diabetes is hard) overreacting by secondary caregivers when the closed loop can more easily deal with BG fluctuations. +* **Override the high target with the low** ([see this explanation](<../Usage and maintenance/preferences-and-safety-settings#wide-bg-target-range>) about this feature which is enabled by default + * This makes it easier for secondary caregivers (like school nurses) to do conservative boluses at lunch/snack time, and allow the closed loop to pick up from there. The secondary caregiver can use the bolus wizard, which will correct down to the high end of the target; the default behavior allows the closed loop to target the low end of the target. Based on anecdotal reports from those using it, this feature sounds like it’s prevented a lot of (unintentional, diabetes is hard) overreacting by secondary caregivers when the closed loop can more easily deal with BG fluctuations. * **Carb ratio adjustment ratio** ([see this explanation](<../Usage and maintenance/preferences-and-safety-settings#carbratio-adjustmentratio>) for enabling this feature) * If parents would prefer for secondary caregivers to bolus with a more conservative carb ratio, this can be set so the closed loop ultimately uses the correct carb amount for any needed additional calculations. @@ -134,8 +134,8 @@ See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.]( ## Running multiple kinds of DIY systems * You can run different DIY systems (like Loop and OpenAPS) side-by-side, if you want to compare algorithms and how they behave. -* For those who like Loop's capabilities for bolusing from the phone, but don't want the requirement to enter carb absorption rates by meal, you can set Loop to "open loop" mode and use it for bolusing, and otherwise allow OpenAPS to be the primary closed loop to take advantage of the [Advanced Meal Assist (AMA)](<../How it works/autosens#advanced-meal-assist-or-ama>) algorithm, [autosensitivity](<../How it works/autosens#auto-sensitivity-mode>) to automatically adjust ISF, etc. However, see the following safety warnings below. - * **SAFETY WARNING:** If you choose to keep a Loop rig running alongside OpenAPS, you MUST turn off Loop's ability to write to Nightscout. If you neglect to do this, Nightscout will display double entries of carbs and/or boluses and greatly confuse you in the future. To enter carbs, you can enter directly through Nightscout Care Portal; [use the variety of IFTTT configurations to enter carbs to Nightscout via your Pebble watch, Alexa, Siri, etc.](../walkthrough/phase-4/ifttt-integration.md); or enter using the pump's bolus wizard. Even if you're just using the Loop app in open loop mode, and enter carbs or bolus from the pump bolus wizard for use in OpenAPS, you need to turn off Loop's ability to write to Nightscout. If you don't, Loop will read the boluses and carbs entered via the pump, upload them to Nightscout, and the duplicate entries will result in suboptimal post-meal decisions. You can either turn off Loop's ability to write to Nightscout, or simply close the app, but reopening the app for even a few minutes may still cause it to double enter to Nightscout if uploads are not disabled. If you do not plan to actively use Loop and DO want to bolus from the pump (via bolus wizard or easy bolus button) with OpenAPS, you should either disable Loop's Nightscout uploads, or plan to close the Loop app and not run them side-by-side. +* For those who like Loop's capabilities for bolusing from the phone, but don't want the requirement to enter carb absorption rates by meal, you can set Loop to "open loop" mode and use it for bolusing, and otherwise allow OpenAPS to be the primary closed loop to take advantage of the [Super Micro Bolus and Unannounced Meals](<../Customize-Iterate/oref1>) features, [autosensitivity](<../How it works/autosens>) to automatically adjust ISF, etc. However, see the following safety warnings below. + * **SAFETY WARNING:** If you choose to keep a Loop rig running alongside OpenAPS, you MUST turn off Loop's ability to write to Nightscout. If you neglect to do this, Nightscout will display double entries of carbs and/or boluses and greatly confuse you in the future. To enter carbs, you can enter directly through Nightscout Care Portal; [use the variety of IFTTT configurations to enter carbs to Nightscout via your Pebble watch, Alexa, Siri, etc.](<../Customize-Iterate/ifttt-integration>); or enter using the pump's bolus wizard. Even if you're just using the Loop app in open loop mode, and enter carbs or bolus from the pump bolus wizard for use in OpenAPS, you need to turn off Loop's ability to write to Nightscout. If you don't, Loop will read the boluses and carbs entered via the pump, upload them to Nightscout, and the duplicate entries will result in suboptimal post-meal decisions. You can either turn off Loop's ability to write to Nightscout, or simply close the app, but reopening the app for even a few minutes may still cause it to double enter to Nightscout if uploads are not disabled. If you do not plan to actively use Loop and DO want to bolus from the pump (via bolus wizard or easy bolus button) with OpenAPS, you should either disable Loop's Nightscout uploads, or plan to close the Loop app and not run them side-by-side. * **Caution**: You may want to disable the Nightscout COB pill, especially if you are using multiple DIY closed loop systems, as it will likely cause confusion. You should look to the (DIY closed loop system you are using)'s pill for information about COB. This means looking in the OpenAPS or Loop pill for information about COB. diff --git a/docs/docs/Resources/technical-resources.md b/docs/docs/Resources/technical-resources.md index f6244ca60..778eedbd8 100644 --- a/docs/docs/Resources/technical-resources.md +++ b/docs/docs/Resources/technical-resources.md @@ -35,7 +35,7 @@ These represent a small selection of guides, tutorials, and quick references for [Automate the Boring Stuff with Python](https://automatetheboringstuff.com/) -[Codecademy Python Course](https://www.codecademy.com/tracks/python) +[Codecademy Python Course](https://www.codecademy.com/learn/learn-python) [Python 2.7 Quick Reference](http://rgruet.free.fr/PQR27/PQR2.7.html) @@ -43,7 +43,7 @@ These represent a small selection of guides, tutorials, and quick references for ## Useful Apps -[Fing](http://www.overlooksoft.com/download) (Android and Apple): Identify IP address of devices on a network. Useful for finding the IP address of RPi on new networks. +[Fing](https://www.fing.com/) (Android and Apple): Identify IP address of devices on a network. Useful for finding the IP address of RPi on new networks. [JuiceSSH](https://play.google.com/store/apps/details?id=com.sonelli.juicessh&hl=en) (Android): SSH client for Android devices diff --git a/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md b/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md index 778f02087..eb630011e 100644 --- a/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md +++ b/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md @@ -43,8 +43,8 @@ Make sure to check through the following list before asking on Gitter if your se * Check to make sure your receiver is plugged in, if you're plugging a receiver in. * Don't have data in Nightscout? Make sure there is no trailing slash `/` on the URL that you are entering and that the API secret is correct. Check your Nightscout URL, too - it's one of the most common errors to mistype that. (And FWIW, you shouldn't be typing things like that in the first place: that's what copy and paste are for.) * Check and make sure your receiver is >50% charged (if battery low, it may drain the rig battery and prevent it from operating). -* A reboot may be required after running oref0-setup if the Carelink is unable to communicate with the pump (e.g. you see "Attempting to use a port that is not open" errors in pump-loop.log). Additional Carelink troubleshooting steps can be found in [Dealing with the CareLink USB Stick](<../Troubleshooting/carelink>). -* If you see the error `failed to get string preference .pump_serial`, that usually means you copied your preferences over or ran runagain, instead of following the directions and using the full interactive setup script, when upgrading to a new version/installing a new version (such as going from 0.6.x to 0.7.0). To resolve, run `oref0-setup.sh` manually per the [directions](<../Customize-Iterate/update-your-rig#step-2-re-run-oref0-setup>). (*This means you'll enter your responses into the interactive setup script again*.) +* A reboot may be required after running oref0-setup if the Carelink is unable to communicate with the pump (e.g. you see "Attempting to use a port that is not open" errors in pump-loop.log). Additional Carelink troubleshooting steps can be found in [Dealing with the CareLink USB Stick](<../Troubleshooting/Carelink>). +* If you see the error `failed to get string preference .pump_serial`, that usually means you copied your preferences over or ran runagain, instead of following the directions and using the full interactive setup script, when upgrading to a new version/installing a new version (such as going from 0.6.x to 0.7.0). To resolve, run `oref0-setup.sh` manually per the [directions](<../Usage and maintenance/update-your-rig#step-2-re-run-oref0-setup>). (*This means you'll enter your responses into the interactive setup script again*.) ## Running commands manually to see what's not working from an oref0-setup.sh setup process diff --git a/docs/docs/Usage and maintenance/monitoring-OpenAPS.md b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md index 333dcb1cd..06060cd72 100644 --- a/docs/docs/Usage and maintenance/monitoring-OpenAPS.md +++ b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md @@ -33,7 +33,7 @@ There are two general groups of ways to monitor your rigs: See below for different ways to access your rig: * [If your computer and rig are on the same wifi network](<#if-your-computer-and-rig-are-on-the-same-wifi-network>) -* [If your iPhone and rig are on the same wifi network](<#if-your-iphone-and-rig-are-on-the-same-wifi-network>) +* [If your phone and rig are on the same wifi network](<#offline-web-page-from-rig-for-any-phone-user>) * [Set up an autossh reverse tunnel to access from a different network](#autossh-reverse-tunnel) ******************************** diff --git a/docs/docs/Usage and maintenance/preferences-and-safety-settings.md b/docs/docs/Usage and maintenance/preferences-and-safety-settings.md index 50c6cb858..94a255b93 100644 --- a/docs/docs/Usage and maintenance/preferences-and-safety-settings.md +++ b/docs/docs/Usage and maintenance/preferences-and-safety-settings.md @@ -8,7 +8,7 @@ All of the settings specific to OpenAPS (that can't be read from the pump) will
Click here to expand a clickable list to jump to each preference: -- [Editing your preferences.json](#editing-your-preferencesjson) +- [Editing your preferences.json](#editing-your-preferences-json) - [Commonly-adjusted preferences:](#commonly-adjusted-preferences) * [max IOB:](#max-iob) * [max daily safety multiplier:](#max-daily-safety-multiplier) @@ -32,7 +32,7 @@ All of the settings specific to OpenAPS (that can't be read from the pump) will * [enableSMB_after_carbs](#enablesmb-after-carbs) * [allowSMB_with_high_temptarget](#allowsmb-with-high-temptarget) * [maxSMBBasalMinutes](#maxsmbbasalminutes) - * [maxUAMSMBBasalMinutes](#maxUAMSMBBasalMinutes) + * [maxUAMSMBBasalMinutes](#maxuamsmbbasalminutes) - [Exercise-mode related preferences:](#exercise-mode-related-preferences) * [exercise_mode](#exercise-mode) * [high_temptarget_raises_sensitivity](#high-temptarget-raises-sensitivity) diff --git a/docs/docs/Usage and maintenance/running-autotune.md b/docs/docs/Usage and maintenance/running-autotune.md index fbba8ce8a..1238b5b9e 100644 --- a/docs/docs/Usage and maintenance/running-autotune.md +++ b/docs/docs/Usage and maintenance/running-autotune.md @@ -144,7 +144,7 @@ If you are not running autotune as part of a closed loop, you can still run it a
* MAC USERS: Follow these steps instead of 1a / 1b above if you want to run autotune on your Mac. (Mac users can instead do the above instructions if they prefer to create a Linux virtual machine to run it on): -* To run AutoTune using a Mac you will use the Terminal application. Open the Terminal application on your Mac (it is located in the Utilities application folder on your Mac). For more information about using Terminal see [here](<../Understanding OpenAPS-Overview/overview-of-build-process#before-you-get-started>) +* To run AutoTune using a Mac you will use the Terminal application. Open the Terminal application on your Mac (it is located in the Utilities application folder on your Mac). For more information about using Terminal see [here](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) * After you open a Terminal window, copy and paste the command for each of the Mac install command steps below, and then hit the return key after you paste each command, which will execute it. If you are asked for a password, enter the password for your Mac. * Tip for New Mac Users: If you typically use a Windows machine and you keep trying to do a control-c (copy) and control-v (paste), remember, on a Mac use command-c (copy) and command-v (paste) instead. * For example, the first step is to install Homebrew on your Mac. To do this you need to copy and paste the following command from step 1.) of the Mac install commands below and then hit the return key: `/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"` @@ -300,7 +300,7 @@ oref0-upload-profile --switch ./myopenaps/autotune/profile.json $NS_SITE $API_SE ### Re-Running Autotune -Remember, to initially set-up Autotune follow the instructions [above](<../How it works/autotune#phase-c-running-autotune-for-suggested-adjustments-without-an-openaps-rig>) +Remember, to initially set-up Autotune follow the instructions [above](<../How it works/autotune#running-autotune-for-suggested-adjustments-without-an-openaps-rig>) To subsequently re-run Autotune at a later time: * Open Ubuntu/your machine of choice and login if necessary @@ -335,7 +335,7 @@ To test this fix, type `echo $API_SECRET` and hit enter. If this returns the AP Other things to check: * If you see error like `TypeError: opts.glucose.map is not a function` check that you have `API_SECRET` in the right format, [as described in this issue](https://github.com/openaps/oref0/issues/397). You either need `API_SECRET=xxxx` where `xxxx` is the string you gave Nightscout, or `API_SECRET=token=xxxxx` where `xxxxx` is the token you generated in Nightscout admin interface. -* Does your Nightscout have data? It definitely needs BG data, but you may also get odd results if you do not have treatment (carb, bolus) data logged. See [this page](<./understanding-autotune>) with what output you should get and pay attention to depending on data input. +* Does your Nightscout have data? It definitely needs BG data, but you may also get odd results if you do not have treatment (carb, bolus) data logged. See [this page](<../How it works/understanding-autotune>) with what output you should get and pay attention to depending on data input. * Did you pull too much data? Start with one day, and make sure it's a day where you had data in Nightscout. Work your way up to 1 week or 1 month of data. If you run into errors on a longer data pull, there may be something funky in Nightscout that's messing up the data format file and you'll want to exclude that date by picking a batch that does not include that particular date. * Make sure when you sub in your Nightscout URL you do not include a "/" at the end of the URL * Check your profile.json and make sure it really matches the example - chances are there's a stray character in there. From e12e3bf31b4bf265d27f043f2c425ed5f7daa226 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 26 Feb 2020 13:32:52 -0500 Subject: [PATCH 13/13] remove url accidentally left in from editing links --- docs/docs/Usage and maintenance/usability-considerations.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docs/Usage and maintenance/usability-considerations.md b/docs/docs/Usage and maintenance/usability-considerations.md index 22c25b92b..7ee76232a 100644 --- a/docs/docs/Usage and maintenance/usability-considerations.md +++ b/docs/docs/Usage and maintenance/usability-considerations.md @@ -8,7 +8,6 @@ Now that you've closed the loop, you probably have a lot of new "first" experien - [What do you do with the loop when you shower?](#what-do-you-do-with-the-loop-when-you-shower) - [What do you do when you change sites?](#what-do-you-do-when-you-change-sites) - [How do I switch to a different Medtronic pump?](#how-do-i-switch-to-a-different-medtronic-pump) -https://draft-openaps-reorg.readthedocs.io/en/reapply-cleanup/docs/Usage%20and%20maintenance/usability-considerations.html#how-do-i-switch-to-a-different-medtronic-pump - [What do you do when you exercise?](#what-do-you-do-when-you-exercise) - [What do you do if you want to be off the pump for long periods during a day when you're really active? Like for the beach or water park or sporting activity or similar?](#what-do-you-do-if-you-want-to-be-off-the-pump-for-long-periods-during-a-day-when-you-re-really-active-like-for-the-beach-or-water-park-or-sporting-activity-or-similar) - [What if I want to turn off the loop for a while?](#what-if-i-want-to-turn-off-the-loop-for-a-while)