From 723009f434d254f00d63085448171566f5ae6209 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 9 Aug 2019 15:56:56 -0400 Subject: [PATCH 01/54] consolidate troubleshooting section and troubleshooting.md from resources --- docs/docs/Build Your Rig/OpenAPS-install.md | 9 +++ docs/docs/Troubleshooting/Carelink.md | 11 +++ .../Common-error-messages.md} | 73 +------------------ .../General_linux_troubleshooting.md | 59 ++++++++++++--- .../Medtronic-Button-Errors.md | 0 .../Wifi-and-hotspot-issues.md | 30 ++++++++ docs/docs/Troubleshooting/index.rst | 6 ++ 7 files changed, 106 insertions(+), 82 deletions(-) create mode 100644 docs/docs/Troubleshooting/Carelink.md rename docs/docs/{Resources/troubleshooting.md => Troubleshooting/Common-error-messages.md} (76%) rename docs/docs/{Resources => Troubleshooting}/Medtronic-Button-Errors.md (100%) create mode 100644 docs/docs/Troubleshooting/Wifi-and-hotspot-issues.md diff --git a/docs/docs/Build Your Rig/OpenAPS-install.md b/docs/docs/Build Your Rig/OpenAPS-install.md index f28a09bdd..b3fd2b269 100644 --- a/docs/docs/Build Your Rig/OpenAPS-install.md +++ b/docs/docs/Build Your Rig/OpenAPS-install.md @@ -15,6 +15,15 @@ Getting your rig with OpenAPS takes generally six steps: * 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. + +### 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` + ### 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)* diff --git a/docs/docs/Troubleshooting/Carelink.md b/docs/docs/Troubleshooting/Carelink.md new file mode 100644 index 000000000..6719005e6 --- /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](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/hardware.html), 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/Resources/troubleshooting.md b/docs/docs/Troubleshooting/Common-error-messages.md similarity index 76% rename from docs/docs/Resources/troubleshooting.md rename to docs/docs/Troubleshooting/Common-error-messages.md index ad892bb70..de7ceebf6 100644 --- a/docs/docs/Resources/troubleshooting.md +++ b/docs/docs/Troubleshooting/Common-error-messages.md @@ -1,75 +1,4 @@ -# 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`) +# Common error messages ## Dealing with npm run global-install errors diff --git a/docs/docs/Troubleshooting/General_linux_troubleshooting.md b/docs/docs/Troubleshooting/General_linux_troubleshooting.md index cfdadf97a..34e2faa40 100644 --- a/docs/docs/Troubleshooting/General_linux_troubleshooting.md +++ b/docs/docs/Troubleshooting/General_linux_troubleshooting.md @@ -1,14 +1,6 @@ -# General linux and other guide/troubleshooting basic +# General Linux troubleshooting -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` - -### Before you get started +## Before you get started 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. @@ -95,3 +87,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 (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` (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/Wifi-and-hotspot-issues.md b/docs/docs/Troubleshooting/Wifi-and-hotspot-issues.md new file mode 100644 index 000000000..2ded10f64 --- /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. 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. \ No newline at end of file diff --git a/docs/docs/Troubleshooting/index.rst b/docs/docs/Troubleshooting/index.rst index aec2d60a4..db7dc88df 100644 --- a/docs/docs/Troubleshooting/index.rst +++ b/docs/docs/Troubleshooting/index.rst @@ -1,11 +1,17 @@ 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/). + .. toctree:: :maxdepth: 4 oref0-setup-troubleshooting General_linux_troubleshooting + Common-error-messages + Wifi-and-hotspot-issues Pump-rig-communications-troubleshooting CGM-rig-communications-troubleshooting Rig-NS-communications-troubleshooting + Medtronic-Button-Errors + Carelink From 7c56bbb4e98f5076907a419c8f08bd57c515bddc Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 9 Aug 2019 15:57:44 -0400 Subject: [PATCH 02/54] update requirements.txt --- requirements.txt | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/requirements.txt b/requirements.txt index 96cb917bd..7e27f3a26 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,30 @@ +alabaster==0.7.12 +argcomplete==1.10.0 +Babel==2.7.0 +certifi==2019.6.16 +chardet==3.0.4 +CommonMark==0.5.4 +decocare==0.0.30.dev0 +dexcom-reader==0.1.10 +docutils==0.14 +gitdb2==2.0.5 +GitPython==2.1.11 +idna==2.8 +imagesize==1.1.0 +Jinja2==2.10.1 +MarkupSafe==1.1.1 +mock==3.0.5 +nose==1.3.7 +openaps==0.1.5 +Pygments==2.4.2 +pyserial==3.4 +python-dateutil==2.8.0 +pytz==2019.1 recommonmark==0.4.0 -sphinx==1.5.6 -git+git://github.com/bewest/decoding-carelink.git@dev -openaps +requests==2.22.0 +six==1.12.0 +smmap2==2.0.5 +snowballstemmer==1.9.0 +Sphinx==1.5.6 +sphinx-rtd-theme==0.4.3 +urllib3==1.25.3 From b6d251fe0834baaad1952bcd29098d350320a928 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 9 Aug 2019 15:57:57 -0400 Subject: [PATCH 03/54] ignore built html --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 95a36d069..6c4f342ed 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,6 @@ _book *.mobi *.pdf .*.sw[op] + +# All build output (HTML etc.) +build \ No newline at end of file From ca0c699a05b39cc764b4115fdff621b435188aa1 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 9 Aug 2019 16:31:41 -0400 Subject: [PATCH 04/54] use subdirectory index.rst files to create main toctree for maintainability (tradeoff: sidebar toctree isn't kept always 'expanded' via explicit listing of contents, but allows straightforward "summary" text for main headings in the index file) --- docs/conf.py | 28 ++---- docs/docs/Build Your Rig/index.rst | 2 +- docs/docs/Customize-Iterate/index.rst | 34 ++++---- docs/docs/Gear Up/hardware.md | 15 ---- docs/docs/Gear Up/index.rst | 34 ++++++-- docs/docs/Give Back-Pay It Forward/index.rst | 14 +-- docs/docs/Resources/index.rst | 15 ++-- docs/docs/Troubleshooting/index.rst | 1 + .../Understanding OpenAPS-Overview/index.rst | 19 ++-- docs/docs/While You Wait For Gear/index.rst | 30 ++++--- docs/index.rst | 86 +++---------------- 11 files changed, 103 insertions(+), 175 deletions(-) delete mode 100644 docs/docs/Gear Up/hardware.md diff --git a/docs/conf.py b/docs/conf.py index a21419c34..21ffa01ba 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -125,7 +125,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 +138,15 @@ # 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 diff --git a/docs/docs/Build Your Rig/index.rst b/docs/docs/Build Your Rig/index.rst index ff6d7eec7..2345f5263 100644 --- a/docs/docs/Build Your Rig/index.rst +++ b/docs/docs/Build Your Rig/index.rst @@ -3,7 +3,7 @@ Build your rig .. toctree:: :maxdepth: 4 - + :hidden: OpenAPS-install x12-users diff --git a/docs/docs/Customize-Iterate/index.rst b/docs/docs/Customize-Iterate/index.rst index 03bfb23e7..c60ec4831 100644 --- a/docs/docs/Customize-Iterate/index.rst +++ b/docs/docs/Customize-Iterate/index.rst @@ -1,19 +1,21 @@ -Customize-Iterate ----------------------- +Customize - Iterate +============================================== .. toctree:: - :maxdepth: 4 + :maxdepth: 2 + :glob: + :hidden: - - 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 + Optimizing Your Settings + Offline Looping + Enable Bluetooth tethering + Add more wifi to your rig + Useful apps for accessing your rig + IFTTT and Pebble buttons + Autosens + Autotune + Understanding Autotune + oref1: SMB and UAM + Tips & tricks + Update your rig in the future + How to run oref0-setup.sh again \ No newline at end of file diff --git a/docs/docs/Gear Up/hardware.md b/docs/docs/Gear Up/hardware.md deleted file mode 100644 index df4893ae4..000000000 --- a/docs/docs/Gear Up/hardware.md +++ /dev/null @@ -1,15 +0,0 @@ -# Hardware overview - -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:_ -* 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 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.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. diff --git a/docs/docs/Gear Up/index.rst b/docs/docs/Gear Up/index.rst index 1f78ea4a1..5091e91f7 100644 --- a/docs/docs/Gear Up/index.rst +++ b/docs/docs/Gear Up/index.rst @@ -1,11 +1,29 @@ -Gear Up ----------------------- +Hardware overview +===================== + +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: + +- 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 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. -.. toctree:: - :maxdepth: 4 +.. NOTE:: + **Note about deprecated hardware setups** - hardware - pump - CGM - Get your rig parts + 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. + + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + + Compatible Pumps + Compatible CGMs + Get your rig parts \ No newline at end of file diff --git a/docs/docs/Give Back-Pay It Forward/index.rst b/docs/docs/Give Back-Pay It Forward/index.rst index d6b25ba6e..d663a862b 100644 --- a/docs/docs/Give Back-Pay It Forward/index.rst +++ b/docs/docs/Give Back-Pay It Forward/index.rst @@ -1,9 +1,11 @@ -Give Back/Pay it Forward ----------------------- +Give Back-Pay It Forward +============================================== .. toctree:: - :maxdepth: 4 + :maxdepth: 2 + :glob: + :hidden: + + Donate your data + Help others - pay it forward - - data-commons-data-donation - contribute diff --git a/docs/docs/Resources/index.rst b/docs/docs/Resources/index.rst index ce8651fd8..92191433a 100644 --- a/docs/docs/Resources/index.rst +++ b/docs/docs/Resources/index.rst @@ -1,4 +1,3 @@ - Resources --------- @@ -9,15 +8,11 @@ Resources 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 + 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/Troubleshooting/index.rst b/docs/docs/Troubleshooting/index.rst index db7dc88df..c1218fd4a 100644 --- a/docs/docs/Troubleshooting/index.rst +++ b/docs/docs/Troubleshooting/index.rst @@ -5,6 +5,7 @@ Even those who follow this documentation precisely are bound to end up stuck at .. toctree:: :maxdepth: 4 + :hidden: oref0-setup-troubleshooting General_linux_troubleshooting diff --git a/docs/docs/Understanding OpenAPS-Overview/index.rst b/docs/docs/Understanding OpenAPS-Overview/index.rst index 61fb3bf9e..b22180279 100644 --- a/docs/docs/Understanding OpenAPS-Overview/index.rst +++ b/docs/docs/Understanding OpenAPS-Overview/index.rst @@ -1,10 +1,15 @@ -Understanding OpenAPS/Overview ----------------------- +Understanding OpenAPS (Overview) +============================================== + +Contents: .. toctree:: - :maxdepth: 4 + :maxdepth: 2 + :glob: + :hidden: - - how-openaps-works-overview - overview-of-build-process - communication-support-channels + How OpenAPS works + Overview of steps + Using this documentation + Where to go for help + \ No newline at end of file diff --git a/docs/docs/While You Wait For Gear/index.rst b/docs/docs/While You Wait For Gear/index.rst index 4b5ed2571..69e8d3c85 100644 --- a/docs/docs/While You Wait For Gear/index.rst +++ b/docs/docs/While You Wait For Gear/index.rst @@ -1,16 +1,18 @@ -While You Wait For Gear ----------------------- - +While you wait for gear +============================================== + .. toctree:: - :maxdepth: 4 - + :maxdepth: 2 + :glob: + :hidden: - 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 + 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 + diff --git a/docs/index.rst b/docs/index.rst index 48e9a28c2..08a8fe93e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,88 +25,22 @@ Note: *We do not recommend using a PDF version of this guide. The docs are updat .. toctree:: :maxdepth: 2 :glob: - :caption: Understanding OpenAPS (Overview) + :hidden: - How OpenAPS works - How this guide works/overview of steps - Where to go for help + Understanding OpenAPS (Overview) -.. toctree:: - :maxdepth: 2 - :glob: - :caption: Gear Up - - docs/Gear Up/hardware - Compatible Pumps - Compatible CGMs - Get your rig parts - -.. toctree:: - :maxdepth: 2 - :glob: - :caption: While You Wait For Gear + Gear Up - 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 - -.. toctree:: - :maxdepth: 2 - :glob: - :caption: Build Your Rig + While You Wait For Gear - Installing OpenAPS - 512/712 pump users - Tell us you’re looping - -.. 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 - Autosens - Autotune - Understanding Autotune - oref1: SMB and UAM - Tips & tricks - Update your rig in the future - How to run oref0-setup.sh again + Build your rig -.. toctree:: - :maxdepth: 2 - :glob: - :caption: Troubleshooting + Customize-Iterate - Troubleshooting oref0-setup - General linux troubleshooting - Pump-rig troubleshooting - CGM-rig troubleshooting - Rig-NS troubleshooting + Troubleshooting -.. toctree:: - :maxdepth: 2 - :glob: - :caption: Give Back-Pay It Forward - - Donate your data - Help others - pay it forward - -.. toctree:: - :maxdepth: 2 - :glob: - :caption: Resources/Reference + Give Back - Pay it Forward Resources - For Clinicians + + From ace7461c3a4d58952df92052f8c6a331a06f8f9e Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 9 Aug 2019 16:32:32 -0400 Subject: [PATCH 05/54] split up info about how to use documentation and where to connect with other users --- .../communication-support-channels.md | 34 +++---------------- .../overview-of-build-process.md | 5 --- .../using-the-docs.md | 32 +++++++++++++++++ docs/index.rst | 3 +- 4 files changed, 38 insertions(+), 36 deletions(-) create mode 100644 docs/docs/Understanding OpenAPS-Overview/using-the-docs.md diff --git a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md index 9ee530e44..9fe1c9eb8 100644 --- a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md +++ b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md @@ -1,37 +1,13 @@ # 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/index.rst) 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! - -![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. -### Google Group - everyone is recommended and 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, 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. +### Google Group +A google group focused on #OpenAPS development work can be found [here](https://groups.google.com/d/forum/openaps-dev) - everyone is recommended 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. 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/).) 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..5e2aac689 100644 --- a/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md +++ b/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md @@ -8,8 +8,3 @@ As with all things new, there is a little bit of a learning curve to building yo 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. -## What you’ll see 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. 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..cc9981d90 --- /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 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) + +## 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/index.rst b/docs/index.rst index 08a8fe93e..36833ccd0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,8 +3,7 @@ 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** From 37be92982255c9d4d36dca31fff13262d4ae1503 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 9 Aug 2019 17:09:56 -0400 Subject: [PATCH 06/54] bumping decocare to get readthedocs build working (is this really used in the docs repo?) --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 7e27f3a26..0fe4c2dbb 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,7 +4,7 @@ Babel==2.7.0 certifi==2019.6.16 chardet==3.0.4 CommonMark==0.5.4 -decocare==0.0.30.dev0 +decocare==0.0.31 dexcom-reader==0.1.10 docutils==0.14 gitdb2==2.0.5 From baa4f97904b1f70d35259fa7b73b106993fa61ad Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 9 Aug 2019 17:11:45 -0400 Subject: [PATCH 07/54] removing unused dependencies for docs --- requirements.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index 0fe4c2dbb..45d1f6917 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,8 +4,6 @@ Babel==2.7.0 certifi==2019.6.16 chardet==3.0.4 CommonMark==0.5.4 -decocare==0.0.31 -dexcom-reader==0.1.10 docutils==0.14 gitdb2==2.0.5 GitPython==2.1.11 From ec30c64c3940a42d4656a9a3a596fd4e25374188 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 9 Aug 2019 17:24:41 -0400 Subject: [PATCH 08/54] starting organization of install steps (just committing & pushing to transfer to home comp) --- docs/docs/Build Your Rig/OpenAPS-install.md | 26 +++++++------------ docs/docs/Gear Up/edison.md | 14 +++++----- .../how-openaps-works-overview.md | 2 ++ .../Understanding OpenAPS-Overview/index.rst | 1 - docs/index.rst | 4 +-- 5 files changed, 19 insertions(+), 28 deletions(-) diff --git a/docs/docs/Build Your Rig/OpenAPS-install.md b/docs/docs/Build Your Rig/OpenAPS-install.md index b3fd2b269..fcbe4ceb7 100644 --- a/docs/docs/Build Your Rig/OpenAPS-install.md +++ b/docs/docs/Build Your Rig/OpenAPS-install.md @@ -2,19 +2,11 @@ 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. - +1. **Jubilinux installation** (called "flashing" the Edison - Pi users can skip to step 2). This may already be done for you if you purchased a pre-flashed Edison board. +2. **Getting first wifi network connection and installing "dependencies"** (helper code that make all the OpenAPS code function). This is done using what is called the "bootstrap" script. +3. **Installing your OpenAPS loop**. This is done using what is called the "setup" script. +4. **Watching the Pump-loop Log**. This is an important, required step. You need to be familiar with how to read and access your logs. +5. **Finish your setup**: all the polishing steps to your OpenAPS setup. Things like optimizing your settings, preferences, BT-tethering, IFTTT, etc. ### Some conventions used in these docs: @@ -32,7 +24,7 @@ If you purchased a pre-flashed Edison, you can also skip on down to [step 2](htt 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 +### Step 2: Wifi and Dependencies Steps 2-3 are covered in the page links below, dependent on which type of rig you are using. @@ -42,7 +34,7 @@ Steps 2-3 are covered in the page links below, dependent on which type of rig yo 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 +### 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. @@ -109,7 +101,7 @@ Make sure that at the end of the setup script, your log rotate file is set to `d ************************** -## Step 5: Watch your Pump-Loop Log +## 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. @@ -259,7 +251,7 @@ These logs and other files are things you may frequently access. There are short ``` 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 +## Step 5: Finish your OpenAPS setup You're looping? Congrats! However, you're not done quite done yet. diff --git a/docs/docs/Gear Up/edison.md b/docs/docs/Gear Up/edison.md index 611f5560b..ab99d1a1f 100644 --- a/docs/docs/Gear Up/edison.md +++ b/docs/docs/Gear Up/edison.md @@ -2,15 +2,15 @@ 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. [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). +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#intel-edison-based-setups). -`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. [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). +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. [See below for the list of hardware required for Pi/HAT setups](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#pi-based-setups-with-the-explorer-hat). -**Note** - there is an experimental alternative to an Explorer HAT, which can serve as the radio on a Pi-based rig, but will not have the screen, and requires you to solder. See [below](https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#hardware-information-for-pi-based-setups-with-rfm69hcw-experimental) for more details on a setup with RFM69HCW. +**Note** - there is an experimental alternative to an Explorer HAT, which can serve as the radio on a Pi-based rig, but will not have the screen, and requires you to solder. See [below](https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#pi-based-setups-with-rfm69hcw-experimental) for more details on a setup with RFM69HCW. **** -## Hardware information for Pi-based setups with the Explorer HAT +## 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) @@ -41,7 +41,7 @@ Because we are still optimizing the software to be as power-efficient as possibl *** -## Hardware information for Pi-based setups with RFM69HCW (experimental) +## Pi-based setups with RFM69HCW (experimental) The Pi + RFM69HCW is still experimental! @@ -115,7 +115,7 @@ After that, you're ready to install OpenAPS. *** -## Hardware information for Intel Edison-based setups +## Intel Edison-based setups The high level parts list (see below for more details, and links): @@ -214,6 +214,6 @@ 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 +Other non-case protection options * [Heat Shrink Tubing](https://www.amazon.com/gp/product/B009IILEVY) 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..dbd358214 100644 --- a/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md +++ b/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md @@ -27,3 +27,5 @@ When you build an OpenAPS rig, you run through the setup described in this docum * configure it to talk to YOUR devices and have your information and safety settings on it (based on your preferences) 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. + + diff --git a/docs/docs/Understanding OpenAPS-Overview/index.rst b/docs/docs/Understanding OpenAPS-Overview/index.rst index b22180279..37c4b8736 100644 --- a/docs/docs/Understanding OpenAPS-Overview/index.rst +++ b/docs/docs/Understanding OpenAPS-Overview/index.rst @@ -5,7 +5,6 @@ Contents: .. toctree:: :maxdepth: 2 - :glob: :hidden: How OpenAPS works diff --git a/docs/index.rst b/docs/index.rst index 36833ccd0..d9745d502 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,8 +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. - - .. note:: **A Note on DIY and the "Open" Part of OpenAPS** @@ -32,7 +30,7 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of While You Wait For Gear - Build your rig + Installing OpenAPS on your rig Customize-Iterate From 0fd598cd07e1184b59a67b852b498c790e0599d8 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 9 Aug 2019 17:26:54 -0400 Subject: [PATCH 09/54] shift list of steps to overview --- docs/docs/Build Your Rig/OpenAPS-install.md | 16 --------------- docs/docs/Build Your Rig/index.rst | 22 +++++++++++++++++++-- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/docs/Build Your Rig/OpenAPS-install.md b/docs/docs/Build Your Rig/OpenAPS-install.md index fcbe4ceb7..bccaf0abf 100644 --- a/docs/docs/Build Your Rig/OpenAPS-install.md +++ b/docs/docs/Build Your Rig/OpenAPS-install.md @@ -1,21 +1,5 @@ # 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). This may already be done for you if you purchased a pre-flashed Edison board. -2. **Getting first wifi network connection and installing "dependencies"** (helper code that make all the OpenAPS code function). This is done using what is called the "bootstrap" script. -3. **Installing your OpenAPS loop**. This is done using what is called the "setup" script. -4. **Watching the Pump-loop Log**. This is an important, required step. You need to be familiar with how to read and access your logs. -5. **Finish your setup**: all the polishing steps to your OpenAPS setup. Things like optimizing your settings, preferences, BT-tethering, IFTTT, etc. - -### Some conventions used in these docs: - -* Wherever you see text that is formatted `like this`, it is a code snippet. You should copy and paste those code snippets instead of attempting to type these out; this will save you debugging time for finding your typos. -* Double check that your copy-paste has copied correctly. Sometimes a paste may drop a character or two and that will cause an error in the command that you are trying to execute. Sometimes, depending on what step you are doing, you may not see the issue. So, do make a point of double checking the paste before pressing return. -* 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` - ### 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)* diff --git a/docs/docs/Build Your Rig/index.rst b/docs/docs/Build Your Rig/index.rst index 2345f5263..b3d477450 100644 --- a/docs/docs/Build Your Rig/index.rst +++ b/docs/docs/Build Your Rig/index.rst @@ -1,5 +1,23 @@ -Build your rig ----------------------- +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). This may already be done for you if you purchased a pre-flashed Edison board. +2. **Getting first wifi network connection and installing "dependencies"** (helper code that make all the OpenAPS code function). This is done using what is called the "bootstrap" script. +3. **Installing your OpenAPS loop**. This is done using what is called the "setup" script. +4. **Watching the Pump-loop Log**. This is an important, required step. You need to be familiar with how to read and access your logs. +5. **Finish your setup**: all the polishing steps to your OpenAPS setup. Things like optimizing your settings, preferences, BT-tethering, IFTTT, etc. + +Some conventions used in these docs: +========================================== + +* Wherever you see text that is formatted `like this`, it is a code snippet. You should copy and paste those code snippets instead of attempting to type these out; this will save you debugging time for finding your typos. +* Double check that your copy-paste has copied correctly. Sometimes a paste may drop a character or two and that will cause an error in the command that you are trying to execute. Sometimes, depending on what step you are doing, you may not see the issue. So, do make a point of double checking the paste before pressing return. +* 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` + .. toctree:: :maxdepth: 4 From 0682b9a066502533aa7acf7c42cc716218ef9ef6 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 9 Aug 2019 17:38:35 -0400 Subject: [PATCH 10/54] fix 'common error messages' section --- .../Troubleshooting/Common-error-messages.md | 138 ++++++------------ 1 file changed, 47 insertions(+), 91 deletions(-) diff --git a/docs/docs/Troubleshooting/Common-error-messages.md b/docs/docs/Troubleshooting/Common-error-messages.md index de7ceebf6..0eab9da3f 100644 --- a/docs/docs/Troubleshooting/Common-error-messages.md +++ b/docs/docs/Troubleshooting/Common-error-messages.md @@ -1,85 +1,10 @@ # Common error messages -## 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. - -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. - -## 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 +## 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 @@ -89,21 +14,21 @@ Bash scripts (.sh files) need execute permissions to run. Run this command to gr chmod u+x myscript.sh ``` -### ValueError: need more than 0 values to unpack +## 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 +## 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 +## 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. -### json: error: input is not JSON +## json: error: input is not JSON ``` json: error: input is not JSON: Unexpected '<' at line 1, column 1: Document Moved @@ -111,13 +36,13 @@ json: error: input is not JSON: Unexpected '<' at line 1, column 1: 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 +## 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 date when invoking profile report Could not parse carbratio_data. Feature Meal Assist enabled but cannot find required carb_ratios. @@ -140,7 +65,7 @@ Below is correct definition remainder = insulin_sensitivities = settings/insulin_sensitivities.json -### Could not get subg rfspy state or version ccprog or cannot connect to CC111x radio +## 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)` @@ -162,7 +87,7 @@ If you are using an Intel Edison with Explorer Board or a Raspberry Pi with Expl * 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: +### 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 @@ -179,7 +104,7 @@ cd ~/src/ccprog ./ccprog -p 19,7,36 write spi1_alt2_EDISON_EXPLORER_US_STDLOC.hex ``` -#### Using a Raspberry Pi + Explorer HAT: +### 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 @@ -188,15 +113,46 @@ wget https://github.com/EnhancedRadioDevices/subg_rfspy/releases/download/v0.8-e ``` * Reboot, and try `killall -g oref0-pump-loop; openaps mmtune` to make sure it works + + +## Dealing with npm run global-install errors -## Dealing with the CareLink USB Stick +If you get an error while running an `npm global-install`, you may be able to clear it by running the following commands: -**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. +`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. -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`). +## 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. -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. +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. -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. +## Errors during `openaps report invoke monitor/ns-glucose.json` or `ns-upload.sh` -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. +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 From cabb498d14578f006bd8390f0f9a67a837a65e74 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Tue, 13 Aug 2019 23:05:31 -0400 Subject: [PATCH 11/54] start to organize installation directions & consolidate flashing info --- docs/docs/Build Your Rig/OpenAPS-install.md | 257 ------------------ docs/docs/Build Your Rig/index.rst | 13 +- .../docs/Build Your Rig/keeping-up-to-date.md | 13 - .../step-1-flashing.md} | 208 ++++---------- .../step-2-wifi-dependencies.md | 158 +++++++++++ .../Build Your Rig/step-3-setup-script.md | 65 +++++ .../Build Your Rig/step-4-watching-log.md | 149 ++++++++++ .../Build Your Rig/step-5-finishing-setup.md | 35 +++ docs/docs/Gear Up/edison.md | 17 +- .../Resources/Edison-Flashing/PC-flash.md | 4 - .../Resources/Edison-Flashing/mac-flash.md | 94 ------- 11 files changed, 480 insertions(+), 533 deletions(-) delete mode 100644 docs/docs/Build Your Rig/OpenAPS-install.md delete mode 100644 docs/docs/Build Your Rig/keeping-up-to-date.md rename docs/docs/{Resources/Edison-Flashing/all-computers-flash.md => Build Your Rig/step-1-flashing.md} (68%) 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 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 bccaf0abf..000000000 --- a/docs/docs/Build Your Rig/OpenAPS-install.md +++ /dev/null @@ -1,257 +0,0 @@ -# Installing OpenAPS on your rig - -### 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. - -### Step 2: Wifi and Dependencies - -Steps 2-3 are covered in the page links below, dependent on which type of rig you are using. - -* If you are using an _**Intel Edison**_, start with the [Intel Edison instructions](edison-install.md). - -* If you are using a _**Raspberry Pi**_, start with the [Raspberry Pi instructions](pi-install.md). - -Going through steps 1-3 may take about 1-3 hours depending on your internet connection, whether the edison was pre-flashed, and comfort level with the instructions. At the end of the bootstrap script (step 3), you will be asked if you want to continue on with the set-up script (step 4). If you need to take a break and come back to step 4 later, you can answer "no" to continuing on and come back later...picking up at the directions below for running the setup script. - -### Step 3: Setup script - -* **If you pressed `enter` to continuing on with the setup script at the end of the bootstrap script**, you do **NOT** need to specifically enter the command in the box below. By pressing `enter` to continuing on with setup script, the command was automatically started for you. - -* **If you pressed `control-c` to end at the completion of the bootstrap script** and did not continue automatically with setup script, this is where you'll pick back up. At this point, your rig should have your first wifi connection finished and your dependencies installed. - - Login to your rig and run the following command (aka "the setup script"): - - `cd && ~/src/oref0/bin/oref0-setup.sh` - -(Note: if this is your first time logging into the rig since running bootstrap script, you will have to change your rig's password on this first login. You will enter the default password first of `edison` and then be prompted to enter your new password twice in a row. If you get an error, it is likely that you forgot to enter `edison` at the first prompt for changing the password.) - -#### Be prepared to enter the following information into the setup script: - -The screenshot below shows an example of the questions you'll be prompted to reply to during the setup script (oref0-setup). Your answers will depend on the particulars of your setup. Also, don't expect the rainbow colored background - that's just to help you see each of the sections it will ask you about! - -
- Be prepared to enter the following items (click here to expand list): -
- -* 6-digit serial number of your pump -* whether you are using an 512/712 model pump (those require special setup steps that other model pumps do not) -* whether you are using an Explorer board - * if not an Explorer board, and not a Carelink stick, you'll need to enter the mmeowlink port for TI stick. See [here](https://github.com/oskarpearson/mmeowlink/wiki/Installing-MMeowlink) for directions on finding your port - * if you're using a Carelink, you will NOT be using mmeowlink. After you finish setup you need to check if the line `radio_type = carelink` is present in your `pump.ini` file. -* CGM method: The options are `g4-upload`, `g4-local-only`, `g5`, `mdt`, and `xdrip`. - * Note: OpenAPS also attempts to get BG data from your Nightscout. OpenAPS will always use the most recent BG data regardless of the source. As a consequence, if you use FreeStyle Libre or any other CGM system that gets its data only from Nightscout, you'll be fine choosing any of the options above. - * Note: For Medtronic 640G (CGM) users, it is recommended that you enter 'xdrip' - otherwise the BG values may not be read from your Nightscout. (The reason being, the 'MDT' option applies only for the enlite sensor attached to the actual pump you're looping with) - * Note: G4-upload will allow you to have raw data when the G4 receiver is plugged directly into the rig. -* Nightscout URL and API secret (or NS authentication token, if you use that option) -* BT MAC address of your phone, if you want to pair for BT tethering to personal hotspot (letters should be in all caps) - * Note, you'll still need to do finish the BT tethering as outlined [here](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/bluetooth-tethering-edison.html) after setup. -* Your desired max-iob -* whether you want Autosensitivity and/or Autotune enabled -* whether you want any carbs-required Pushover notifications (and if you do, you'll need your Pushover API token and User Key) - -
- -![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 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 - 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 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](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 index b3d477450..0981f40aa 100644 --- a/docs/docs/Build Your Rig/index.rst +++ b/docs/docs/Build Your Rig/index.rst @@ -1,7 +1,8 @@ +------------------------------- Installing OpenAPS on your rig ------------------------------- -Getting your rig with OpenAPS takes generally six steps: +Getting OpenAPS running on your rig generally takes five steps: 1. **Jubilinux installation** (called "flashing" the Edison - Pi users can skip to step 2). This may already be done for you if you purchased a pre-flashed Edison board. 2. **Getting first wifi network connection and installing "dependencies"** (helper code that make all the OpenAPS code function). This is done using what is called the "bootstrap" script. @@ -9,8 +10,8 @@ Getting your rig with OpenAPS takes generally six steps: 4. **Watching the Pump-loop Log**. This is an important, required step. You need to be familiar with how to read and access your logs. 5. **Finish your setup**: all the polishing steps to your OpenAPS setup. Things like optimizing your settings, preferences, BT-tethering, IFTTT, etc. + Some conventions used in these docs: -========================================== * Wherever you see text that is formatted `like this`, it is a code snippet. You should copy and paste those code snippets instead of attempting to type these out; this will save you debugging time for finding your typos. * Double check that your copy-paste has copied correctly. Sometimes a paste may drop a character or two and that will cause an error in the command that you are trying to execute. Sometimes, depending on what step you are doing, you may not see the issue. So, do make a point of double checking the paste before pressing return. @@ -19,10 +20,14 @@ Some conventions used in these docs: * Wherever there are `` 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` + .. toctree:: :maxdepth: 4 :hidden: - OpenAPS-install + step-1-flashing + step-2-wifi-dependencies + step-3-setup-script + step-4-watching-log + step-5-finishing-setup x12-users - keeping-up-to-date 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/Resources/Edison-Flashing/all-computers-flash.md b/docs/docs/Build Your Rig/step-1-flashing.md similarity index 68% rename from docs/docs/Resources/Edison-Flashing/all-computers-flash.md rename to docs/docs/Build Your Rig/step-1-flashing.md index ed7c31e7e..48136676b 100644 --- a/docs/docs/Resources/Edison-Flashing/all-computers-flash.md +++ b/docs/docs/Build Your Rig/step-1-flashing.md @@ -1,15 +1,17 @@ -# Setting Up Your Intel Edison - Flashing instructions for all computer types +# Step 1: Jubilinux (for Edison rigs only) -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. +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). -## 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. +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. -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. +## What is flashing? -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). +The Edison comes with a ver limited 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. -## Prerequisites +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 - prerequisites: @@ -46,19 +48,39 @@ Windows PCs with less than 6 GB of RAM may need to have the size of the page fi ### 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. +- 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). 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. -## Downloading image +## 2. 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 + - 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. + - 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: @@ -67,11 +89,21 @@ Windows PCs with less than 6 GB of RAM may need to have the size of the page fi 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 +## 3. Connecting cables to the Explorer Board and starting console + +Now we move to the rig. 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. + +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. + +![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, so if you have an option to use a PC or Laptop with directly connected USB cables, it will be easier to do so. 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). - 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 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`. @@ -90,7 +122,7 @@ Windows PCs with less than 6 GB of RAM may need to have the size of the page fi - - 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 +## 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` @@ -114,151 +146,7 @@ Windows PCs with less than 6 GB of RAM may need to have the size of the page fi 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) +Hooray! After you've flashed your Edison, head on to [step 2 - setting up wifi and installing dependencies](step-2wifi-dependencies) ## Troubleshooting 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..fda77e9f6 --- /dev/null +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -0,0 +1,158 @@ +# Step 2: Wifi and Dependencies + +Steps 2-3 are covered in the page links below, dependent on which type of rig you are using. + +* If you are using an _**Intel Edison**_, start with the [Intel Edison instructions](edison-install.md). + +* If you are using a _**Raspberry Pi**_, start with the [Raspberry Pi instructions](pi-install.md). + +Going through steps 1-3 may take about 1-3 hours depending on your internet connection, whether the edison was pre-flashed, and comfort level with the instructions. At the end of the bootstrap script (step 3), you will be asked if you want to continue on with the set-up script (step 4). If you need to take a break and come back to step 4 later, you can answer "no" to continuing on and come back later...picking up at the directions below for running the setup script. + + + +Below are the manual instructions for reference. It is strongly recommended that you use the easy setup scripts instead. + + +## Initial Edison Setup + +Log in as root/edison via serial console. + +Type/edit the following: + + myedisonhostname= #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) 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..7fb051c58 --- /dev/null +++ b/docs/docs/Build Your Rig/step-3-setup-script.md @@ -0,0 +1,65 @@ +# Step 3: Setup script + +* **If you pressed `enter` to continuing on with the setup script at the end of the bootstrap script**, you do **NOT** need to specifically enter the command in the box below. By pressing `enter` to continuing on with setup script, the command was automatically started for you. + +* **If you pressed `control-c` to end at the completion of the bootstrap script** and did not continue automatically with setup script, this is where you'll pick back up. At this point, your rig should have your first wifi connection finished and your dependencies installed. + + Login to your rig and run the following command (aka "the setup script"): + + `cd && ~/src/oref0/bin/oref0-setup.sh` + +(Note: if this is your first time logging into the rig since running bootstrap script, you will have to change your rig's password on this first login. You will enter the default password first of `edison` and then be prompted to enter your new password twice in a row. If you get an error, it is likely that you forgot to enter `edison` at the first prompt for changing the password.) + +#### Be prepared to enter the following information into the setup script: + +The screenshot below shows an example of the questions you'll be prompted to reply to during the setup script (oref0-setup). Your answers will depend on the particulars of your setup. Also, don't expect the rainbow colored background - that's just to help you see each of the sections it will ask you about! + +
+ Be prepared to enter the following items (click here to expand list): +
+ +* 6-digit serial number of your pump +* whether you are using an 512/712 model pump (those require special setup steps that other model pumps do not) +* whether you are using an Explorer board + * if not an Explorer board, and not a Carelink stick, you'll need to enter the mmeowlink port for TI stick. See [here](https://github.com/oskarpearson/mmeowlink/wiki/Installing-MMeowlink) for directions on finding your port + * if you're using a Carelink, you will NOT be using mmeowlink. After you finish setup you need to check if the line `radio_type = carelink` is present in your `pump.ini` file. +* CGM method: The options are `g4-upload`, `g4-local-only`, `g5`, `mdt`, and `xdrip`. + * Note: OpenAPS also attempts to get BG data from your Nightscout. OpenAPS will always use the most recent BG data regardless of the source. As a consequence, if you use FreeStyle Libre or any other CGM system that gets its data only from Nightscout, you'll be fine choosing any of the options above. + * Note: For Medtronic 640G (CGM) users, it is recommended that you enter 'xdrip' - otherwise the BG values may not be read from your Nightscout. (The reason being, the 'MDT' option applies only for the enlite sensor attached to the actual pump you're looping with) + * Note: G4-upload will allow you to have raw data when the G4 receiver is plugged directly into the rig. +* Nightscout URL and API secret (or NS authentication token, if you use that option) +* BT MAC address of your phone, if you want to pair for BT tethering to personal hotspot (letters should be in all caps) + * Note, you'll still need to do finish the BT tethering as outlined [here](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/bluetooth-tethering-edison.html) after setup. +* Your desired max-iob +* whether you want Autosensitivity and/or Autotune enabled +* whether you want any carbs-required Pushover notifications (and if you do, you'll need your Pushover API token and User Key) + +
+ +![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) + +
+ 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..caccd52dd --- /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 - 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. \ 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..9165cc7e1 --- /dev/null +++ b/docs/docs/Build Your Rig/step-5-finishing-setup.md @@ -0,0 +1,35 @@ +# 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.** +******************* + +## 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. :) + +## + +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/Gear Up/edison.md b/docs/docs/Gear Up/edison.md index ab99d1a1f..5cb9c210f 100644 --- a/docs/docs/Gear Up/edison.md +++ b/docs/docs/Gear Up/edison.md @@ -165,7 +165,11 @@ If you don't use an Explorer board, you can use a number of radio sticks: a [TI- ### 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). +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. @@ -173,10 +177,21 @@ Warning: bad cables cause a lot of headaches during the Edison flashing process, 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). +### 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) + ### 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. diff --git a/docs/docs/Resources/Edison-Flashing/PC-flash.md b/docs/docs/Resources/Edison-Flashing/PC-flash.md index b5f2d360d..cf8e69811 100644 --- a/docs/docs/Resources/Edison-Flashing/PC-flash.md +++ b/docs/docs/Resources/Edison-Flashing/PC-flash.md @@ -19,10 +19,6 @@ If you didn't buy your Edison with jubilinux preinstalled, it comes with an oper ****** -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) diff --git a/docs/docs/Resources/Edison-Flashing/mac-flash.md b/docs/docs/Resources/Edison-Flashing/mac-flash.md index 3d45d4a1e..6d91da064 100644 --- a/docs/docs/Resources/Edison-Flashing/mac-flash.md +++ b/docs/docs/Resources/Edison-Flashing/mac-flash.md @@ -1,63 +1,5 @@ -# 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 -3. Using a looping-compatible Medtronic pump. If using a x12 series Medtronic pump, it will require one small [extra step](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/x12-users.html). 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 - -* [**Explorer Board - link**](https://enhanced-radio-devices.myshopify.com/products/900mhz-explorer-block-pre-order) - -* [**Edison - link**](https://www.sparkfun.com/products/13024) - -* [**Nuts and Bolts - link**](https://www.sparkfun.com/products/13187) - -* **At least one Lithium Battery** (The larger battery will have a little longer battery life; but may be slightly bigger.) - * [**2500mAh battery - link**](https://www.adafruit.com/products/328) - * [**2000mAh battery - link**](https://www.sparkfun.com/products/8483) - -* **Cables** (you may already have workable USB cables; you just need 2 to complete this process. Doesn’t have to be a certain length either, just giving options if you have a preference for shorter or longer cables.) - * [**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) - -## 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 the nuts and bolts you order. - -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) - -## Software-build your rig - -Building the software into your rig is comprised of three steps: - -1. Preparing the Edison (aka flashing the Edison) -2. Installing the “looping” code (aka setup script for oref0) -3. Customizing your loop - ### 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 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). - -Note: Before starting to flash an Edison using a Mac, if you are using a Macbook with a USB-C Hub you may encounter some issues with the flashing process, including the wireless LAN setup not functioning correctly, so if you have an option to use a PC or Laptop with directly connected USB cables, it may be better to do so. - -![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) @@ -70,36 +12,8 @@ When you first launch Terminal, you will probably see something rather plain lik 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` @@ -363,11 +277,3 @@ If the rig isn't online, go back and check your /etc/network/interfaces and /etc ![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. Personalising your closed loop - -Remember to personalize your settings after you finish installing OpenAPS! From 20b2843121f4ea5468f275ef6eda0af5316f024c Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Tue, 13 Aug 2019 23:08:24 -0400 Subject: [PATCH 12/54] fix paths to images in flashing instructions --- docs/docs/Build Your Rig/step-1-flashing.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/docs/Build Your Rig/step-1-flashing.md b/docs/docs/Build Your Rig/step-1-flashing.md index 48136676b..966410c7a 100644 --- a/docs/docs/Build Your Rig/step-1-flashing.md +++ b/docs/docs/Build Your Rig/step-1-flashing.md @@ -52,7 +52,11 @@ Windows PCs with less than 6 GB of RAM may need to have the size of the page fi ```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). 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. + 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! @@ -60,7 +64,7 @@ Windows PCs with less than 6 GB of RAM may need to have the size of the page fi ```brew install dfu-util coreutils gnu-getopt``` -![After installing other stuff](../../Images/Edison/After_install_other_stuff.png) +![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` @@ -68,7 +72,7 @@ Windows PCs with less than 6 GB of RAM may need to have the size of the page fi `brew update && brew tap jlhonora/lsusb && brew install lsusb` -![After installing lsusb](../../Images/Edison/after_install_lsusb.png) +![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. From 439bc86d6e18897fd73df6f7ea0395626b9d0f5b Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 14 Aug 2019 17:12:58 -0400 Subject: [PATCH 13/54] continue consolidating flashing instructions --- docs/docs/Build Your Rig/index.rst | 1 + docs/docs/Build Your Rig/step-1-flashing.md | 84 +++++++++++++++---- .../step-2-wifi-dependencies.md | 18 ++-- 3 files changed, 80 insertions(+), 23 deletions(-) diff --git a/docs/docs/Build Your Rig/index.rst b/docs/docs/Build Your Rig/index.rst index 0981f40aa..8047356ae 100644 --- a/docs/docs/Build Your Rig/index.rst +++ b/docs/docs/Build Your Rig/index.rst @@ -10,6 +10,7 @@ Getting OpenAPS running on your rig generally takes five steps: 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. Some conventions used in these docs: diff --git a/docs/docs/Build Your Rig/step-1-flashing.md b/docs/docs/Build Your Rig/step-1-flashing.md index 966410c7a..541cc319c 100644 --- a/docs/docs/Build Your Rig/step-1-flashing.md +++ b/docs/docs/Build Your Rig/step-1-flashing.md @@ -13,7 +13,7 @@ It's best to replace this with a custom version of Debian, as this fits best wit ## 1. Prerequisites -### If you’re using a Raspberry Pi - 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. @@ -22,7 +22,7 @@ To flash the Edison using a Raspberry Pi, you’ll need a large (preferably 16GB - 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: +### If you're using a Windows PC: - 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. @@ -46,7 +46,9 @@ Windows PCs with less than 6 GB of RAM may need to have the size of the page fi - Reboot and attempt the flash process. -### If you're using a Mac to flash - prerequisites: +### If you're using a Mac: + +- If you're not familiar with using the command line, take 5-10 minutes to get familiar with the Terminal app before continuing. [Here's a good introduction.] (https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) - 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: @@ -99,32 +101,34 @@ Now we move to the rig. Your Explorer Board has 2 micro USB connectors. They ca 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. -![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, so if you have an option to use a PC or Laptop with directly connected USB cables, it will be easier to do so. 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). - 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) +![Explorer Board rig with two cables and red light on](../Images/Edison/ExplorerBoard_two_charging_cables.png) -### 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 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. ### 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. + - 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. This is your "console window" - keep it open. - - 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.) + +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. ## 4. Flashing image onto the Edison @@ -140,17 +144,67 @@ Note: If you are using a Macbook with a USB-C Hub you may encounter some issues - 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. + - 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. - - 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. + - 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. - - 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`. + - 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) -Hooray! After you've flashed your Edison, head on to [step 2 - setting up wifi and installing dependencies](step-2wifi-dependencies) +After you've flashed your Edison, head on to [step 2 - setting up wifi and installing dependencies](step-2wifi-dependencies) ## Troubleshooting 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 fda77e9f6..64516b6a7 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -6,11 +6,11 @@ Steps 2-3 are covered in the page links below, dependent on which type of rig yo * If you are using a _**Raspberry Pi**_, start with the [Raspberry Pi instructions](pi-install.md). -Going through steps 1-3 may take about 1-3 hours depending on your internet connection, whether the edison was pre-flashed, and comfort level with the instructions. At the end of the bootstrap script (step 3), you will be asked if you want to continue on with the set-up script (step 4). If you need to take a break and come back to step 4 later, you can answer "no" to continuing on and come back later...picking up at the directions below for running the setup script. -Below are the manual instructions for reference. It is strongly recommended that you use the easy setup scripts instead. + +Below are the manual instructions for reference only - it is strongly recommended that you use the easy setup scripts instead. ## Initial Edison Setup @@ -26,7 +26,7 @@ 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. +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 @@ -35,7 +35,11 @@ Run these commands to set secure passwords. It will ask you to enter your new p `vi /etc/network/interfaces` -Type 'i' to get into INSERT mode +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: ``` @@ -43,7 +47,7 @@ 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. +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: @@ -62,7 +66,7 @@ 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 +Press Esc and then type ':wq' and press Enter to write (save) the file and quit. `vi /etc/wpa_supplicant/wpa_supplicant.conf` @@ -154,5 +158,3 @@ 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) From 3eb47fae30c521b27a83eff7b158898a5ea6680a Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 14 Aug 2019 22:53:30 -0400 Subject: [PATCH 14/54] rough consolidation of all flashing instructions - still need to format and edit steps 2+ --- .gitignore | 3 +- docs/docs/Build Your Rig/edison-install.md | 76 ---- docs/docs/Build Your Rig/pi-install.md | 220 ---------- docs/docs/Build Your Rig/step-1-flashing.md | 62 +-- .../step-2-wifi-dependencies.md | 377 ++++++++++++++++-- .../Build Your Rig/step-5-finishing-setup.md | 2 +- .../on-the-go-wifi-adding.md | 15 + .../Resources/Edison-Flashing/PC-flash.md | 267 ------------- .../Resources/Edison-Flashing/mac-flash.md | 279 ------------- 9 files changed, 394 insertions(+), 907 deletions(-) delete mode 100644 docs/docs/Build Your Rig/edison-install.md delete mode 100644 docs/docs/Build Your Rig/pi-install.md delete mode 100644 docs/docs/Resources/Edison-Flashing/PC-flash.md delete mode 100644 docs/docs/Resources/Edison-Flashing/mac-flash.md diff --git a/.gitignore b/.gitignore index 6c4f342ed..b7d2b8a77 100644 --- a/.gitignore +++ b/.gitignore @@ -17,4 +17,5 @@ _book .*.sw[op] # All build output (HTML etc.) -build \ No newline at end of file +build +denv 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/pi-install.md b/docs/docs/Build Your Rig/pi-install.md deleted file mode 100644 index 1543184eb..000000000 --- a/docs/docs/Build Your Rig/pi-install.md +++ /dev/null @@ -1,220 +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) - -### 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](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#step-5-watch-your-pump-loop-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 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 [OpenAPS Install page](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#step-4-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-1-flashing.md b/docs/docs/Build Your Rig/step-1-flashing.md index 541cc319c..2ea7b33b7 100644 --- a/docs/docs/Build Your Rig/step-1-flashing.md +++ b/docs/docs/Build Your Rig/step-1-flashing.md @@ -7,7 +7,7 @@ The steps outlined below include instructions for the various build-platforms (W ## What is flashing? -The Edison comes with a ver limited 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. +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. @@ -24,15 +24,23 @@ To flash the Edison using a Raspberry Pi, you’ll need a large (preferably 16GB ### If you're using a Windows PC: -- 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. +- 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) -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_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. -- 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). +![Control Panel](../Images/Edison/64_bit.png) + +![Putty](../Images/Edison/putty.png) + +![Putty](../Images/Edison/putty2.png) + +![Putty](../Images/Edison/putty3.png) + +#### 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. @@ -48,13 +56,13 @@ Windows PCs with less than 6 GB of RAM may need to have the size of the page fi ### If you're using a Mac: -- If you're not familiar with using the command line, take 5-10 minutes to get familiar with the Terminal app before continuing. [Here's a good introduction.] (https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) +- If you're not familiar with using the command line, take 5-10 minutes to get familiar with the Terminal app before continuing. [Here's a good introduction.](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) - 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. + 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) @@ -78,22 +86,20 @@ It will take about 1-2 minutes for Homebrew to install. You’ll see a bunch of 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 image - -### Jubilinux +## 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 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! + - 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. - For Windows OS: + - 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! - 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) + - 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 @@ -117,11 +123,17 @@ Note: If you are using a Macbook with a USB-C Hub you may encounter some issues - You’ll most likely be asked for your computer password again because you're using sudo. Enter it. ### 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. + - 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. 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. This is your "console window" - keep it open. @@ -145,8 +157,8 @@ If you have a problem getting to the Edison login prompt, and possibly get a war ### 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. + - 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: @@ -204,7 +216,7 @@ After logging in, you will notice that the Terminal prompt says `root@ubilinux:~ 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-2wifi-dependencies) +After you've flashed your Edison, head on to [step 2 - setting up wifi and installing dependencies](step-2-wifi-dependencies) ## Troubleshooting @@ -234,10 +246,12 @@ c) If you recieve an `Error: Running Homebrew as root is extremely dangerous and ** 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 + ``` + :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 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 64516b6a7..4edb1b07b 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -1,19 +1,94 @@ # Step 2: Wifi and Dependencies -Steps 2-3 are covered in the page links below, dependent on which type of rig you are using. +The directions for this step depend on which type of rig you are using. -* If you are using an _**Intel Edison**_, start with the [Intel Edison instructions](edison-install.md). +## Intel Edison instructions -* If you are using a _**Raspberry Pi**_, start with the [Raspberry Pi instructions](pi-install.md). +### 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, which will set up your first wifi network connection and install dependencies. Copy this text (all of it in the box): + +TODO: this differs from the scripts in oref0, see if I can pull directly from there - otherwise either update or only link + +``` +#!/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](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#run-oref0-setup) for finishing step 4. + + + + + +### Manual instructions Below are the manual instructions for reference only - it is strongly recommended that you use the easy setup scripts instead. -## Initial Edison Setup +#### Initial Edison Setup Log in as root/edison via serial console. @@ -31,7 +106,7 @@ Run these commands to set secure passwords. Make sure you save them somewhere - passwd root passwd edison -## Set up Wifi: +#### Set up Wifi: `vi /etc/network/interfaces` @@ -68,9 +143,12 @@ iface wlan0 inet dhcp 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. +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={ @@ -79,42 +157,29 @@ network={ } ``` -If you want to add open networks to your list, then add: +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 ](http://openaps.readthedocs.io/en/latest/docs/Customize%20Iterate/on-the-go-wifi-adding.html) to add more options to your rig at any point. -``` -network={ - key_mgmt=NONE - priority=-999 -} -``` +![Wifi edit screen](../../Images/Edison/Wifi_add.png) -If you have a hidden wifi network add the line `scan_ssid=1`. +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." -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. +Press Esc and then type ':wq' and press Enter to write the file and quit. -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: +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): -``` -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 -} -``` +![ifup wlan0 example](../../Images/Edison/ifup_wlan0.png) -Press Esc and then type ':wq' and press Enter to write the file and quit +Make sure you see a message showing you are successfully connected, then `reboot` to apply the wifi changes and (hopefully) get online. -`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. -After rebooting, log back in and type `iwgetid -r` to make sure you successfully connected to wifi. It should print out your network name. +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. -Run `ifconfig wlan0` to determine the IP address of the wireless interface, in case you need it to SSH below. +![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. @@ -126,24 +191,36 @@ If you need more details on setting up wpa_supplicant.conf, see one of these gui * [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 +#### 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. -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 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. -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: + +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 -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 +![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.) @@ -158,3 +235,225 @@ 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](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#step-5-watch-your-pump-loop-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 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 [OpenAPS Install page](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#step-4-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-5-finishing-setup.md b/docs/docs/Build Your Rig/step-5-finishing-setup.md index 9165cc7e1..9a0d1d5b5 100644 --- a/docs/docs/Build Your Rig/step-5-finishing-setup.md +++ b/docs/docs/Build Your Rig/step-5-finishing-setup.md @@ -26,7 +26,7 @@ As your time permits, there's still more useful and cool things you can do to ma * [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 +* [Set up 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. diff --git a/docs/docs/Customize-Iterate/on-the-go-wifi-adding.md b/docs/docs/Customize-Iterate/on-the-go-wifi-adding.md index 7c67e91ad..661544bc5 100644 --- a/docs/docs/Customize-Iterate/on-the-go-wifi-adding.md +++ b/docs/docs/Customize-Iterate/on-the-go-wifi-adding.md @@ -14,10 +14,25 @@ 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) 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 cf8e69811..000000000 --- a/docs/docs/Resources/Edison-Flashing/PC-flash.md +++ /dev/null @@ -1,267 +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) - -****** - -![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/mac-flash.md b/docs/docs/Resources/Edison-Flashing/mac-flash.md deleted file mode 100644 index 6d91da064..000000000 --- a/docs/docs/Resources/Edison-Flashing/mac-flash.md +++ /dev/null @@ -1,279 +0,0 @@ -### 1. Preparing/flashing the Edison/reflashing the Edison - -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. - -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-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.** - -* 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** From ee5cb88dc3427bbaf4da2148b4a2217c65155762 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 21 Aug 2019 16:55:24 -0400 Subject: [PATCH 15/54] consolidate logging-in-via-console instructions that were in several places --- docs/docs/Build Your Rig/index.rst | 4 +- .../Build Your Rig/logging-into-rig-serial.md | 64 +++++++ docs/docs/Build Your Rig/mac-prep.md | 37 ---- docs/docs/Build Your Rig/step-1-flashing.md | 62 +------ .../step-2-wifi-dependencies.md | 15 +- .../Build Your Rig/step-3-setup-script.md | 165 ++++++++++++++++-- .../Build Your Rig/step-4-watching-log.md | 8 +- .../docs/Build Your Rig/windows-putty-prep.md | 44 ----- docs/docs/Build Your Rig/x12-users.md | 151 ---------------- .../Understanding OpenAPS-Overview/index.rst | 1 - docs/index.rst | 2 - 11 files changed, 238 insertions(+), 315 deletions(-) create mode 100644 docs/docs/Build Your Rig/logging-into-rig-serial.md delete mode 100644 docs/docs/Build Your Rig/mac-prep.md delete mode 100644 docs/docs/Build Your Rig/windows-putty-prep.md delete mode 100644 docs/docs/Build Your Rig/x12-users.md diff --git a/docs/docs/Build Your Rig/index.rst b/docs/docs/Build Your Rig/index.rst index 8047356ae..7677a30d0 100644 --- a/docs/docs/Build Your Rig/index.rst +++ b/docs/docs/Build Your Rig/index.rst @@ -12,6 +12,8 @@ Getting OpenAPS running on your rig generally takes five steps: 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) + 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. @@ -31,4 +33,4 @@ Some conventions used in these docs: step-3-setup-script step-4-watching-log step-5-finishing-setup - x12-users + logging-into-rig-serial 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..7d1f4c276 --- /dev/null +++ b/docs/docs/Build Your Rig/logging-into-rig-serial.md @@ -0,0 +1,64 @@ +# 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. \ 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 index 2ea7b33b7..ab5168e1b 100644 --- a/docs/docs/Build Your Rig/step-1-flashing.md +++ b/docs/docs/Build Your Rig/step-1-flashing.md @@ -22,25 +22,7 @@ To flash the Edison using a Raspberry Pi, you’ll need a large (preferably 16GB - 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: - -- 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) - -#### Windows PCs with under 6 GB of RAM +### 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. @@ -53,11 +35,8 @@ Windows PCs with less than 6 GB of RAM may need to have the size of the page fi - Click the Set button, then click OK until all windows are closed. - Reboot and attempt the flash process. - ### If you're using a Mac: -- If you're not familiar with using the command line, take 5-10 minutes to get familiar with the Terminal app before continuing. [Here's a good introduction.](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) - - 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)``` @@ -103,44 +82,11 @@ The above instructions are based on [these instructions](https://software.intel. ## 3. Connecting cables to the Explorer Board and starting console -Now we move to the rig. 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. - -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. +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. -![Edison in Finder](../Images/Edison/Edison_in_Finder_folder.png) +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. -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, so if you have an option to use a PC or Laptop with directly connected USB cables, it will be easier to do so. 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). - - - 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. - -### 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 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. 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. This is your "console window" - keep it open. - - - 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.) - -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. +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 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 4edb1b07b..6a7b603e3 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -1,16 +1,17 @@ # Step 2: Wifi and Dependencies -The directions for this step depend on which type of rig you are using. +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 -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: +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. -* **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 @@ -79,7 +80,7 @@ Now that step 2 is done, the bootstrap script will then continue to run awhile l 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. - +Now that you have a wifi connection to your rig, you can log in to it using @@ -452,7 +453,7 @@ You'll be prompted to set a password. You'll want to change it to something per The script will then continue to run awhile longer (~10+ minutes) before asking you to press `enter` to run oref0-setup. -Return to the [OpenAPS Install page](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#step-4-setup-script) to complete oref0-setup. +Return to the [OpenAPS Install page](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#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)** 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 7fb051c58..914590ed7 100644 --- a/docs/docs/Build Your Rig/step-3-setup-script.md +++ b/docs/docs/Build Your Rig/step-3-setup-script.md @@ -4,20 +4,16 @@ * **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"): +Log in to your rig and run the following command (aka "the setup script"): `cd && ~/src/oref0/bin/oref0-setup.sh` -(Note: if this is your first time logging into the rig since running bootstrap script, you will have to change your rig's password on this first login. You will enter the default password first of `edison` and then be prompted to enter your new password twice in a row. If you get an error, it is likely that you forgot to enter `edison` at the first prompt for changing the password.) +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: +## 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 512/712 model pump (those require special setup steps that other model pumps do not) * whether you are using an Explorer board @@ -34,8 +30,6 @@ The screenshot below shows an example of the questions you'll be prompted to rep * 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. @@ -44,7 +38,7 @@ After the setup script finishes building your loop (called myopenaps), it will a ************************** -### Log rotate fix +## Log rotate fix
Click here to expand notes about checking log rotate, which was fixed in 0.6.1: @@ -63,3 +57,154 @@ 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. + +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 index caccd52dd..0989a723c 100644 --- a/docs/docs/Build Your Rig/step-4-watching-log.md +++ b/docs/docs/Build Your Rig/step-4-watching-log.md @@ -4,7 +4,7 @@ THIS IS A REQUIRED MUST-LEARN HOW-TO STEP - DO NOT MOVE ON WITHOUT DOING THIS! T 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) +## 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: @@ -69,7 +69,7 @@ Advanced meal assist requires at least 36 BG readings before it can begin to cal
-#### What you'll see when you are looping successfully ~20+ minutes later! +## 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" @@ -81,7 +81,7 @@ If after 20 minutes, you still have some errors showing instead of the above suc **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? +## Temp basals > 6.3, ISF > 255 or carb ratio > 25 with a x23 or x54?
Expand here for notes: @@ -103,7 +103,7 @@ python setup.py install
-#### Rig Logs and Shortcut commands - bookmark this section! +## 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?" 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/Build Your Rig/x12-users.md b/docs/docs/Build Your Rig/x12-users.md deleted file mode 100644 index 891143006..000000000 --- a/docs/docs/Build Your Rig/x12-users.md +++ /dev/null @@ -1,151 +0,0 @@ -# 512 and 712 Pump users - -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/Understanding OpenAPS-Overview/index.rst b/docs/docs/Understanding OpenAPS-Overview/index.rst index 37c4b8736..bf44b1007 100644 --- a/docs/docs/Understanding OpenAPS-Overview/index.rst +++ b/docs/docs/Understanding OpenAPS-Overview/index.rst @@ -1,7 +1,6 @@ Understanding OpenAPS (Overview) ============================================== -Contents: .. toctree:: :maxdepth: 2 diff --git a/docs/index.rst b/docs/index.rst index d9745d502..b85004142 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,5 +39,3 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of Give Back - Pay it Forward Resources - - From 4940e90164cbf0ecbcd99ed28a362a14e02408a1 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 26 Aug 2019 17:43:36 -0400 Subject: [PATCH 16/54] minor changes, just syncing --- docs/docs/Gear Up/edison.md | 4 ++-- docs/docs/While You Wait For Gear/monitoring-OpenAPS.md | 4 +++- docs/index.rst | 2 +- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/docs/Gear Up/edison.md b/docs/docs/Gear Up/edison.md index 5cb9c210f..6cad3cca2 100644 --- a/docs/docs/Gear Up/edison.md +++ b/docs/docs/Gear Up/edison.md @@ -137,9 +137,9 @@ There are 4 types of Edison's. All of them work, but Versions 3 and 4 require an * 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. + * **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](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html). -* 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). +* 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](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html). ### Lithium-ion polymer (LiPo) battery or other battery supply diff --git a/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md b/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md index 94a666e11..ede868322 100644 --- a/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md +++ b/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md @@ -88,6 +88,8 @@ See below for different ways to access your rig: **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.** +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. + #### 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) @@ -96,7 +98,7 @@ See below for different ways to access your rig: ![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. +* 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](../Build Your Rig/step-1-flashing). A successful login will look like below. ![Mac Screen successful login](../Images/access_mac_screen.png) diff --git a/docs/index.rst b/docs/index.rst index b85004142..93c0a60c9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,7 +24,7 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of :glob: :hidden: - Understanding OpenAPS (Overview) + Overview: Understanding OpenAPS Gear Up From cb833f3ea4360a95c359b9c01b034cdcda2ed6a0 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Tue, 27 Aug 2019 18:03:18 -0400 Subject: [PATCH 17/54] consolidate info about hardware into edison section & pi section, including parts, how to put them together, antenna info for edison --- docs/docs/Build Your Rig/step-1-flashing.md | 3 +- .../step-2-wifi-dependencies.md | 19 +- .../usability-considerations.md | 12 - .../{edison.md => edison-explorer-board.md} | 204 +++++--------- docs/docs/Gear Up/index.rst | 6 +- docs/docs/Gear Up/pi-based-rigs.md | 250 ++++++++++++++++++ docs/docs/Gear Up/rig-options.md | 13 + .../understanding-your-Explorer-Board-rig.md | 136 ---------- 8 files changed, 347 insertions(+), 296 deletions(-) rename docs/docs/Gear Up/{edison.md => edison-explorer-board.md} (56%) 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/While You Wait For Gear/understanding-your-Explorer-Board-rig.md diff --git a/docs/docs/Build Your Rig/step-1-flashing.md b/docs/docs/Build Your Rig/step-1-flashing.md index ab5168e1b..2ce1d9d7d 100644 --- a/docs/docs/Build Your Rig/step-1-flashing.md +++ b/docs/docs/Build Your Rig/step-1-flashing.md @@ -82,7 +82,8 @@ The above instructions are based on [these instructions](https://software.intel. ## 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. +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:Accessing your online rig via SSH>) 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. 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 6a7b603e3..1c147bcf5 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -12,15 +12,12 @@ The directions for this step depend on which type of rig you are using: 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): -TODO: this differs from the scripts in oref0, see if I can pull directly from there - otherwise either update or only link - ``` #!/bin/bash ( @@ -80,14 +77,11 @@ Now that step 2 is done, the bootstrap script will then continue to run awhile l 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. -Now that you have a wifi connection to your rig, you can log in to it using - +Now that you have a wifi connection to your rig, you have the option of [logging into it using SSH](../While%20You%20Wait%20For%20Gear/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 -### Manual instructions - -Below are the manual instructions for reference only - it is strongly recommended that you use the easy setup scripts instead. - +Below are the manual instructions for reference only - it is strongly recommended that you use the bootstrap script above instead. #### Initial Edison Setup @@ -160,7 +154,7 @@ network={ 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 ](http://openaps.readthedocs.io/en/latest/docs/Customize%20Iterate/on-the-go-wifi-adding.html) to add more options to your rig at any point. -![Wifi edit screen](../../Images/Edison/Wifi_add.png) +![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." @@ -168,7 +162,7 @@ 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) +![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. @@ -180,7 +174,7 @@ Note: If you are reflashing an Edison, you might get a scary looking error about 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) +![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. @@ -238,6 +232,7 @@ and add to the end of the file: ``` + ## 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). diff --git a/docs/docs/Customize-Iterate/usability-considerations.md b/docs/docs/Customize-Iterate/usability-considerations.md index 02e45d6da..9ad5bcc4e 100644 --- a/docs/docs/Customize-Iterate/usability-considerations.md +++ b/docs/docs/Customize-Iterate/usability-considerations.md @@ -94,18 +94,6 @@ The use of Temporary Targets can provide additional fine tuning of insulin contr 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`). diff --git a/docs/docs/Gear Up/edison.md b/docs/docs/Gear Up/edison-explorer-board.md similarity index 56% rename from docs/docs/Gear Up/edison.md rename to docs/docs/Gear Up/edison-explorer-board.md index 6cad3cca2..176ddf396 100644 --- a/docs/docs/Gear Up/edison.md +++ b/docs/docs/Gear Up/edison-explorer-board.md @@ -1,121 +1,6 @@ -# Get your rig hardware +# Intel Edison-based setups -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. [See below for the list of hardware for Edison setups](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#intel-edison-based-setups). - -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. [See below for the list of hardware required for Pi/HAT setups](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#pi-based-setups-with-the-explorer-hat). - -**Note** - there is an experimental alternative to an Explorer HAT, which can serve as the radio on a Pi-based rig, but will not have the screen, and requires you to solder. See [below](https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison.html#pi-based-setups-with-rfm69hcw-experimental) for more details on a setup with RFM69HCW. - -**** - -## 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 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](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. - -*** - -## 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]((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 | | 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. - -*** - -## Intel Edison-based setups +## Parts you'll need The high level parts list (see below for more details, and links): @@ -143,9 +28,9 @@ There are 4 types of Edison's. All of them work, but Versions 3 and 4 require an ### 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 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. +* 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. @@ -153,10 +38,16 @@ The Explorer Boards have battery charger circuitry on board, making it easy to u 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 +#### 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](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. + ### 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. @@ -170,37 +61,29 @@ You will need two DATA micro USB cables - with a micro connector on one end and * [**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. 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). -### 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) - ### 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 +#### 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 +#### 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.** @@ -232,3 +115,58 @@ Cases for Edison plus G4 receiver: 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/index.rst b/docs/docs/Gear Up/index.rst index 5091e91f7..4c4e06afc 100644 --- a/docs/docs/Gear Up/index.rst +++ b/docs/docs/Gear Up/index.rst @@ -20,10 +20,12 @@ If you come across something that doesn't seem to work, is no longer available, .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :glob: :hidden: Compatible Pumps Compatible CGMs - Get your rig parts \ No newline at end of file + Your rig hardware options + Edison rigs + Raspberry Pi rigs \ No newline at end of file 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..e8f9964ab --- /dev/null +++ b/docs/docs/Gear Up/pi-based-rigs.md @@ -0,0 +1,250 @@ +# Pi-based setups with the Explorer HAT + +## Parts you'll need + +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](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](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. + +#### 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]((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 | | 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/rig-options.md b/docs/docs/Gear Up/rig-options.md new file mode 100644 index 000000000..5e849944d --- /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](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison-explorer-board.html). + +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](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/pi-based-rigs.html). 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/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. From 6491d1ae0a79e787f399924570899a2012554522 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 30 Aug 2019 14:14:04 -0400 Subject: [PATCH 18/54] get all links working --- docs/conf.py | 12 +++- .../Build Your Rig/logging-into-rig-serial.md | 6 +- docs/docs/Build Your Rig/step-1-flashing.md | 2 +- .../step-2-wifi-dependencies.md | 26 +++---- .../Build Your Rig/step-3-setup-script.md | 2 +- .../Build Your Rig/step-4-watching-log.md | 4 +- .../Build Your Rig/step-5-finishing-setup.md | 14 ++-- docs/docs/Customize-Iterate/autotune.md | 20 +++--- .../bluetooth-tethering-edison.md | 3 +- .../Customize-Iterate/ifttt-integration.md | 4 +- .../offline-looping-and-monitoring.md | 6 +- .../optimize-your-settings.md | 6 +- docs/docs/Customize-Iterate/oref1.md | 8 +-- .../docs/Customize-Iterate/update-your-rig.md | 6 +- .../usability-considerations.md | 2 +- .../Customize-Iterate/useful-mobile-apps.md | 2 +- docs/docs/Gear Up/CGM.md | 2 +- docs/docs/Gear Up/edison-explorer-board.md | 20 +++--- docs/docs/Gear Up/pi-based-rigs.md | 13 ++-- docs/docs/Gear Up/pump.md | 4 +- docs/docs/Gear Up/rig-options.md | 4 +- .../Resources/Deprecated-Pi/Pi-hardware.md | 2 +- docs/docs/Resources/Deprecated-Pi/Pi-setup.md | 2 +- .../Resources/clinician-guide-to-OpenAPS.md | 6 +- docs/docs/Resources/index.rst | 3 - .../switching-between-DIY-systems.md | 45 +++++------- docs/docs/Troubleshooting/Carelink.md | 2 +- .../Troubleshooting/Common-error-messages.md | 2 +- .../Rig-NS-communications-troubleshooting.md | 10 +-- .../oref0-setup-troubleshooting.md | 4 +- .../communication-support-channels.md | 2 +- .../how-openaps-works-overview.md | 8 +-- .../Understand-determine-basal.md | 6 +- .../collect-data-and-prepare.md | 8 +-- .../entering-carbs-bolus.md | 8 +-- docs/docs/While You Wait For Gear/index.rst | 1 - .../loops-in-progress.md | 2 +- .../monitoring-OpenAPS.md | 72 +++++-------------- .../nightscout-setup.md | 2 +- .../preferences-and-safety-settings.md | 4 +- .../understanding-wifi-options.md | 4 +- 41 files changed, 161 insertions(+), 198 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 21ffa01ba..508dd618b 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'] @@ -145,6 +150,8 @@ 'titles_only': False } + + # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] # html_theme_path = [alabaster.get_path( )] @@ -403,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 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 = draft-openaps-reorg # TEMPORARY to keep links working on RTD preview. os.environ.get('RTDDOMAIN', 'openaps') + 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, 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 7d1f4c276..3d4d311b9 100644 --- a/docs/docs/Build Your Rig/logging-into-rig-serial.md +++ b/docs/docs/Build Your Rig/logging-into-rig-serial.md @@ -61,4 +61,8 @@ Note: If you are using a Macbook with a USB-C Hub you may encounter some issues - 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. \ No newline at end of file +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/step-1-flashing.md b/docs/docs/Build Your Rig/step-1-flashing.md index 2ce1d9d7d..6a88c358a 100644 --- a/docs/docs/Build Your Rig/step-1-flashing.md +++ b/docs/docs/Build Your Rig/step-1-flashing.md @@ -83,7 +83,7 @@ The above instructions are based on [these instructions](https://software.intel. ## 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:Accessing your online rig via SSH>) to get set up. +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. 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 1c147bcf5..ff8951661 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -10,7 +10,7 @@ The directions for this step depend on which type of rig you are using: ### 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. +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 @@ -75,9 +75,9 @@ Now that step 2 is done, the bootstrap script will then continue to run awhile l ![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. +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](../While%20You%20Wait%20For%20Gear/monitoring-OpenAPS#accessing-your-online-rig-via-ssh) from a computer on the same network, rather than using a cable. +Now that you have a wifi connection to your rig, you have the option of [logging into it using SSH](<../While You Wait For Gear/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 @@ -152,7 +152,7 @@ network={ } ``` -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 ](http://openaps.readthedocs.io/en/latest/docs/Customize%20Iterate/on-the-go-wifi-adding.html) to add more options to your rig at any point. +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 ](<../Customize-Iterate/on-the-go-wifi-adding>) to add more options to your rig at any point. ![Wifi edit screen](../Images/Edison/Wifi_add.png) @@ -206,7 +206,7 @@ And these three (the first two will be fast, the last line will take you to a sc 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) +![Time zone examples](../Images/Edison/Time_zone.png) Enter `vi /etc/logrotate.conf`, press “i” for INSERT mode, and make the following changes: @@ -219,7 +219,7 @@ Press ESC and then type “:wq” to save and quit 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 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: ``` @@ -235,11 +235,11 @@ and add to the end of the file: ## 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). +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). +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. @@ -344,11 +344,11 @@ Answer all the setup questions. A successful setup script will finish asking yo **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: -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 options: +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. @@ -448,8 +448,8 @@ You'll be prompted to set a password. You'll want to change it to something per The script will then continue to run awhile longer (~10+ minutes) before asking you to press `enter` to run oref0-setup. -Return to the [OpenAPS Install page](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#step-3-setup-script) to complete 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 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).** +**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 index 914590ed7..b734f0896 100644 --- a/docs/docs/Build Your Rig/step-3-setup-script.md +++ b/docs/docs/Build Your Rig/step-3-setup-script.md @@ -25,7 +25,7 @@ The screenshot below shows an example of the questions you'll be prompted to rep * Note: G4-upload will allow you to have raw data when the G4 receiver is plugged directly into the rig. * Nightscout URL and API secret (or NS authentication token, if you use that option) * BT MAC address of your phone, if you want to pair for BT tethering to personal hotspot (letters should be in all caps) - * Note, you'll still need to do finish the BT tethering as outlined [here](http://openaps.readthedocs.io/en/latest/docs/Customize-Iterate/bluetooth-tethering-edison.html) after setup. + * Note, you'll still need to do finish the BT tethering as outlined [here](<../Customize-Iterate/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) 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 0989a723c..1c0d7ea87 100644 --- a/docs/docs/Build Your Rig/step-4-watching-log.md +++ b/docs/docs/Build Your Rig/step-4-watching-log.md @@ -75,9 +75,9 @@ 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 - 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).) +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](<../While You Wait For Gear/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](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. +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.** diff --git a/docs/docs/Build Your Rig/step-5-finishing-setup.md b/docs/docs/Build Your Rig/step-5-finishing-setup.md index 9a0d1d5b5..656d2327e 100644 --- a/docs/docs/Build Your Rig/step-5-finishing-setup.md +++ b/docs/docs/Build Your Rig/step-5-finishing-setup.md @@ -3,7 +3,7 @@ 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.** +**Shortly after you confirm your loop is running, you should [set your preferences](<../While You Wait For Gear/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! @@ -24,12 +24,12 @@ So that we can notify you if necessary, [please fill out this form if you have b 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. -* [Set up 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. +* [Add more wifi networks to your rig](<../Customize-Iterate/on-the-go-wifi-adding>) so that when you are away from home, the rig has access to trusted wifi networks +* [Set up Papertrail](<../While You Wait For Gear/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](<../Customize-Iterate/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/Customize-Iterate/autotune.md b/docs/docs/Customize-Iterate/autotune.md index 043f59fff..8fd4a908d 100644 --- a/docs/docs/Customize-Iterate/autotune.md +++ b/docs/docs/Customize-Iterate/autotune.md @@ -39,20 +39,20 @@ Below the ISF and carb ratio, you'll see the basal report. ### 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](<../Customize-Iterate/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](<../Customize-Iterate/autotune#phase-c-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. +5. Results don't look like what you expected to see? [See here for some suggestions](<../Customize-Iterate/autotune#why-isn-t-it-working-at-all>) that might contribute to flukey data. ## Other sections on this page -* 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)) +* Background in plain language on [how Autotune works](<../Customize-Iterate/autotune#how-autotune-works>) +* The [difference between Autotune and "autosens"](<../Customize-Iterate/autotune#the-difference-between-autotune-and-autosens>) (aka, [autosensitivity](<../Customize-Iterate/autosens>)) * 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. + * [Phase A](<../Customize-Iterate/autotune#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](<../Customize-Iterate/autotune#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](<../Customize-Iterate/autotune#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 @@ -209,7 +209,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: 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)"` @@ -346,7 +346,7 @@ oref0-autotune --dir=~/myopenaps --ns-host=https://mynightscout.herokuapp.com -- #### 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](<../Customize-Iterate/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 diff --git a/docs/docs/Customize-Iterate/bluetooth-tethering-edison.md b/docs/docs/Customize-Iterate/bluetooth-tethering-edison.md index 7a00f4816..5c6e03c20 100644 --- a/docs/docs/Customize-Iterate/bluetooth-tethering-edison.md +++ b/docs/docs/Customize-Iterate/bluetooth-tethering-edison.md @@ -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 diff --git a/docs/docs/Customize-Iterate/ifttt-integration.md b/docs/docs/Customize-Iterate/ifttt-integration.md index 412caa64d..6c91b432e 100644 --- a/docs/docs/Customize-Iterate/ifttt-integration.md +++ b/docs/docs/Customize-Iterate/ifttt-integration.md @@ -146,9 +146,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 iPhone/Android diff --git a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md index 9e98b8c55..81f5886ce 100644 --- a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md +++ b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md @@ -1,6 +1,6 @@ # 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. +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](<../While You Wait For Gear/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. ## Medtronic CGM users Medtronic CGM users can, by default, automatically loop offline because the rig will read CGM data directly from the pump. @@ -21,7 +21,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. The details for setting up offline looping with 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: +Android users can use the xDrip+ Android app. The details for setting up offline looping with 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. @@ -181,7 +181,7 @@ On your OpenAPS rig, the xdrip-js library can read directly from the Dexcom tran * 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](<../While You Wait For Gear/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/optimize-your-settings.md b/docs/docs/Customize-Iterate/optimize-your-settings.md index 60492c4c3..56e25f449 100644 --- a/docs/docs/Customize-Iterate/optimize-your-settings.md +++ b/docs/docs/Customize-Iterate/optimize-your-settings.md @@ -10,11 +10,11 @@ Think about this: when many people start looping, they often have too high basal 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. ([More about Autotune in the docs here](<../Customize-Iterate/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](<../Customize-Iterate/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 +28,6 @@ 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](<../Customize-Iterate/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>).) diff --git a/docs/docs/Customize-Iterate/oref1.md b/docs/docs/Customize-Iterate/oref1.md index 811576764..93a49e3cd 100644 --- a/docs/docs/Customize-Iterate/oref1.md +++ b/docs/docs/Customize-Iterate/oref1.md @@ -7,8 +7,8 @@ NOTE OF CAUTION: * 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. +* 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. +* See this page on [optimizing settings](<../Customize-Iterate/optimize-your-settings#optimizing-your-settings>) for reminders and tips on changing one thing at a time. ## Only run oref1 with the following caveats in mind: @@ -39,7 +39,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](<../docs/Customize-Iterate/ifttt-integration>). (History of Super Micro Bolus (SMB) development: https://github.com/openaps/oref0/issues/262 ) @@ -54,7 +54,7 @@ In addition, as of 0.6.0-master, using Bolus Wizard to input boluses and meal ca * 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](<../While You Wait For Gear/preferences-and-safety-settings#advanced-oref1-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 diff --git a/docs/docs/Customize-Iterate/update-your-rig.md b/docs/docs/Customize-Iterate/update-your-rig.md index b104135a5..ba6ca102d 100644 --- a/docs/docs/Customize-Iterate/update-your-rig.md +++ b/docs/docs/Customize-Iterate/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](<../Customize-Iterate/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](<../While You Wait For Gear/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/Customize-Iterate/usability-considerations.md index 9ad5bcc4e..29de134bc 100644 --- a/docs/docs/Customize-Iterate/usability-considerations.md +++ b/docs/docs/Customize-Iterate/usability-considerations.md @@ -96,7 +96,7 @@ Temporary Targets can be set in advance by setting a future date/time stamp in N ## 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](<../While You Wait For Gear/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. diff --git a/docs/docs/Customize-Iterate/useful-mobile-apps.md b/docs/docs/Customize-Iterate/useful-mobile-apps.md index dc4bcf18d..c5713ae69 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#before-you-get-started>) 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 cd6c40335..52f51b001 100644 --- a/docs/docs/Gear Up/CGM.md +++ b/docs/docs/Gear Up/CGM.md @@ -16,7 +16,7 @@ This refers to the Dexcom receiver hardware. Note that your Dexcom should be nea ### 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. 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 Share receiver [follow these directions](http://www.nightscout.info/wiki/welcome/nightscout-with-xdrip-and-dexcom-share-wireless) to set up your Android uploader and Nightscout website. diff --git a/docs/docs/Gear Up/edison-explorer-board.md b/docs/docs/Gear Up/edison-explorer-board.md index 176ddf396..b65128650 100644 --- a/docs/docs/Gear Up/edison-explorer-board.md +++ b/docs/docs/Gear Up/edison-explorer-board.md @@ -4,11 +4,11 @@ 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-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](<#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 @@ -22,9 +22,9 @@ There are 4 types of Edison's. All of them work, but Versions 3 and 4 require an * 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](http://openaps.readthedocs.io/en/latest/docs/Resources/Edison-Flashing/all-computers-flash.html). + * **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](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html). +* 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 @@ -44,13 +44,13 @@ You should monitor the rig periodically - **especially the LiPo battery**, check 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). +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](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. +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. @@ -126,7 +126,7 @@ The nuts and bolts are tiny, and the spaces are a little tight. I find it reall 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) +![Edison/Explorer Board rig with red light on](../Images/Edison/Edison_Explorer_Board.png) ### Optional: adding an antenna diff --git a/docs/docs/Gear Up/pi-based-rigs.md b/docs/docs/Gear Up/pi-based-rigs.md index e8f9964ab..ef1a6644e 100644 --- a/docs/docs/Gear Up/pi-based-rigs.md +++ b/docs/docs/Gear Up/pi-based-rigs.md @@ -3,10 +3,10 @@ ## Parts you'll need 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) +* [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). @@ -23,7 +23,7 @@ Lipo batteries are typically used to power the rig on the go because they charge 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). +**Note**: You will probably want to underclock your Raspberry Pi to get a longer battery life. [See this for details](<../Customize-Iterate/usability-considerations#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. @@ -202,7 +202,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/pi-based-rigs#sd-card)) * Bread board * Jumper wires * Soldering iron @@ -217,6 +217,7 @@ You can buy this board e.g. [here](https://www.adafruit.com/product/3070), but y ### 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. diff --git a/docs/docs/Gear Up/pump.md b/docs/docs/Gear Up/pump.md index 68ee26527..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, 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](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/x12-users.html)). 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, 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 index 5e849944d..32e20279d 100644 --- a/docs/docs/Gear Up/rig-options.md +++ b/docs/docs/Gear Up/rig-options.md @@ -2,9 +2,9 @@ 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](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/edison-explorer-board.html). +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](http://openaps.readthedocs.io/en/latest/docs/Gear%20Up/pi-based-rigs.html). 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. +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? 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/clinician-guide-to-OpenAPS.md b/docs/docs/Resources/clinician-guide-to-OpenAPS.md index 338a6c8ad..1e50b73c9 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](<../Customize-Iterate/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](<../Customize-Iterate/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](<../While You Wait For Gear/understand-determine-basal#understanding-the-determine-basal-logic>) diff --git a/docs/docs/Resources/index.rst b/docs/docs/Resources/index.rst index 92191433a..582fd92a6 100644 --- a/docs/docs/Resources/index.rst +++ b/docs/docs/Resources/index.rst @@ -11,8 +11,5 @@ Resources history 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/switching-between-DIY-systems.md b/docs/docs/Resources/switching-between-DIY-systems.md index 0fb80957c..e6f918ac1 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](<../While You Wait For Gear/understand-determine-basal>). +* Loop has temporary targets available by using the workout mode in the Loop app. OpenAPS can have [multiple temp targets](<../Customize-Iterate/autosens#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](<../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)](<../While You Wait For Gear/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](<../While You Wait For Gear/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](<../While You Wait For Gear/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](<../While You Wait For Gear/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](<../Customize-Iterate/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](<../While You Wait For Gear/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](<../While You Wait For Gear/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 @@ -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)](<../Customize-Iterate/autosens#advanced-meal-assist-or-ama>) algorithm, [autosensitivity](<../Customize-Iterate/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/Troubleshooting/Carelink.md b/docs/docs/Troubleshooting/Carelink.md index 6719005e6..972c846d6 100644 --- a/docs/docs/Troubleshooting/Carelink.md +++ b/docs/docs/Troubleshooting/Carelink.md @@ -1,6 +1,6 @@ # 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/index>), 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/Troubleshooting/Common-error-messages.md b/docs/docs/Troubleshooting/Common-error-messages.md index 0eab9da3f..b57061e22 100644 --- a/docs/docs/Troubleshooting/Common-error-messages.md +++ b/docs/docs/Troubleshooting/Common-error-messages.md @@ -26,7 +26,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 ``` diff --git a/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md b/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md index 37b02ad04..4bb36a856 100644 --- a/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md +++ b/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md @@ -2,17 +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](<../Troubleshooting/rig-ns-communications-troubleshooting#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. +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. ### What information is passed from rig to NS? @@ -80,7 +80,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: diff --git a/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md b/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md index 30aadba98..498b8c588 100644 --- a/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md +++ b/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md @@ -37,13 +37,13 @@ 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). +* 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>). * 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 9fe1c9eb8..f70c98732 100644 --- a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md +++ b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md @@ -20,7 +20,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. 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 dbd358214..8829cb3dc 100644 --- a/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md +++ b/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md @@ -3,9 +3,9 @@ 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. @@ -23,7 +23,7 @@ The rig runs a series of commands to collect this data, runs it through the algo When you build an OpenAPS rig, you run through the setup described in this documentation, and: * 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) +* [load the open source software on it](<../Build Your Rig/index>) * configure it to talk to YOUR devices and have your information and safety settings on it (based on your preferences) 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. diff --git a/docs/docs/While You Wait For Gear/Understand-determine-basal.md b/docs/docs/While You Wait For Gear/Understand-determine-basal.md index aeae799cd..b6541de6e 100644 --- a/docs/docs/While You Wait For Gear/Understand-determine-basal.md +++ b/docs/docs/While You Wait For Gear/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](<../While You Wait For Gear/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. @@ -38,14 +38,14 @@ This includes: ![Estimating carb impact](../Images/Carb_predictions.jpg) -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](<../While You Wait For Gear/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](<../While You Wait For Gear/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/collect-data-and-prepare.md b/docs/docs/While You Wait For Gear/collect-data-and-prepare.md index d41a4da65..499c45518 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,10 +1,10 @@ # Collect your data and get prepared -Before getting started, we ask that you store at least 30 days of CGM 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. +Before getting started, we ask that you store at least 30 days of CGM 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](<../While You Wait For Gear/nightscout-setup>). 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. 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](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. +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. 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. ## Practice good CGM habits @@ -48,7 +48,7 @@ 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](http://openaps.readthedocs.io/en/latest/docs/Build%20Your%20Rig/OpenAPS-install.html#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. +* 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. @@ -70,7 +70,7 @@ Some of the super advanced features you'll learn about later - Unannounced 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. +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](<../Customize-Iterate/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. 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: 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 index b087b45dd..14c766132 100644 --- a/docs/docs/While You Wait For Gear/entering-carbs-bolus.md +++ b/docs/docs/While You Wait For Gear/entering-carbs-bolus.md @@ -4,7 +4,7 @@ How do you enter carbs & do boluses with OpenAPS? You have a variety of ways to ## 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.) +* **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. @@ -21,8 +21,8 @@ Look at this image for the big picture: ### 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. +* 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. ### Online carb entry @@ -30,7 +30,7 @@ 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).) +* 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. diff --git a/docs/docs/While You Wait For Gear/index.rst b/docs/docs/While You Wait For Gear/index.rst index 69e8d3c85..abad1d3a5 100644 --- a/docs/docs/While You Wait For Gear/index.rst +++ b/docs/docs/While You Wait For Gear/index.rst @@ -9,7 +9,6 @@ While you wait for gear Collect your data & prepare Make Your First PR Setting up Nightscout - Understand your rig Entering carbs & boluses How OpenAPS makes decisions Monitoring OpenAPS 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 5bfdab707..124f74561 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/monitoring-OpenAPS.md b/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md index ede868322..3f533c09f 100644 --- a/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md +++ b/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md @@ -9,21 +9,21 @@ There are two general groups of ways to monitor your rigs: ## 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) +* [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>) ******************************** @@ -36,15 +36,15 @@ At this point, if you're not yet set up on OpenAPS, you won't quite be ready to ## 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 computer and rig are on different wifi networks](<#if-your-computer-and-rig-are-on-different-wifi-networks>) +* [If your iPhone and rig are on the same wifi network](<#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](../../Images/Computer_rig_same_wifi.png) +![If your computer and rig are on the same wifi network](../Images/Computer_rig_same_wifi.png) #### For Mac computers @@ -86,43 +86,7 @@ See below for different ways to access your rig: ![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.** - -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. - -#### 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](../Build Your Rig/step-1-flashing). 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) +If your computer and rig are on different wifi networks, you will need to connect using a data cable connected to the UART port on the rig. See [these instructions](<../Build Your Rig/logging-into-rig-serial>). ### autossh Reverse Tunnel @@ -169,7 +133,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 @@ -356,7 +320,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) @@ -585,7 +549,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](<../Customize-Iterate/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 @@ -598,7 +562,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. @@ -650,7 +614,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/index>) section for help on editing crontabs): ``` @reboot cd /root/myopenaps/enact && python -m SimpleHTTPServer 1337 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 7c3fd6580..56793e2f1 100644 --- a/docs/docs/While You Wait For Gear/nightscout-setup.md +++ b/docs/docs/While You Wait For Gear/nightscout-setup.md @@ -353,7 +353,7 @@ Other notes: ### It's not working - I'm missing data in Nightscout? -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). +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>). 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. diff --git a/docs/docs/While You Wait For Gear/preferences-and-safety-settings.md b/docs/docs/While You Wait For Gear/preferences-and-safety-settings.md index 5fcbfc9cd..421473dee 100644 --- a/docs/docs/While You Wait For Gear/preferences-and-safety-settings.md +++ b/docs/docs/While You Wait For Gear/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](<../Customize-Iterate/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](<../While You Wait For Gear/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 diff --git a/docs/docs/While You Wait For Gear/understanding-wifi-options.md b/docs/docs/While You Wait For Gear/understanding-wifi-options.md index 09b175be8..b91321d3f 100644 --- a/docs/docs/While You Wait For Gear/understanding-wifi-options.md +++ b/docs/docs/While You Wait For Gear/understanding-wifi-options.md @@ -2,7 +2,7 @@ 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 [(you'll be able to add more wifi networks to your rig in the future)](<../Customize-Iterate/on-the-go-wifi-adding>) * BT-tethering to your cell phone's hotspot * Wifi-tethering to your cell phone's hotspot * Wifi-tethering to mifi device @@ -11,7 +11,7 @@ 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. ### Home Wifi From b2f923b616d45c5558713006e7d22d462913e4f7 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 30 Aug 2019 14:56:29 -0400 Subject: [PATCH 19/54] organize by general topic instead of pushing information into "while you wait for gear"; preserve instruction to learn these things before installing openAPS by adding a (placeholder) 'reading list' section to the prep section --- .../step-2-wifi-dependencies.md | 4 +-- .../Build Your Rig/step-3-setup-script.md | 2 +- .../Build Your Rig/step-4-watching-log.md | 2 +- .../Build Your Rig/step-5-finishing-setup.md | 8 ++--- docs/docs/Customize-Iterate/index.rst | 14 ++------ .../offline-looping-and-monitoring.md | 4 +-- docs/docs/Customize-Iterate/oref1.md | 4 +-- docs/docs/Gear Up/pi-based-rigs.md | 2 +- .../autosens.md | 0 .../autotune.md | 26 +++++++-------- docs/docs/How it works/index.rst | 13 ++++++++ .../understand-determine-basal.md} | 4 +-- .../understanding-autotune.md | 0 ...rstanding-insulin-on-board-calculations.md | 0 .../Resources/clinician-guide-to-OpenAPS.md | 6 ++-- .../switching-between-DIY-systems.md | 20 ++++++------ .../Wifi}/bluetooth-tethering-edison.md | 10 +++--- .../docs/Usage and maintenance/Wifi/index.rst | 11 +++++++ .../Wifi}/on-the-go-wifi-adding.md | 2 +- .../Wifi}/understanding-wifi-options.md | 4 +-- .../entering-carbs-bolus.md | 0 .../example-max-safety-chart.md | 0 .../examples_safety_caps_in_play.png | Bin docs/docs/Usage and maintenance/index.rst | 16 ++++++++++ .../monitoring-OpenAPS.md | 2 +- .../optimize-your-settings.md | 6 ++-- .../oref0-runagain.md | 0 .../preferences-and-safety-settings.md | 2 +- .../update-your-rig.md | 4 +-- .../usability-considerations.md | 2 +- .../collect-data-and-prepare.md | 2 +- docs/docs/While You Wait For Gear/index.rst | 9 ++---- .../While You Wait For Gear/reading-list.md | 3 ++ docs/index.rst | 14 +++++--- requirements.txt | 30 ++---------------- 35 files changed, 118 insertions(+), 108 deletions(-) rename docs/docs/{Customize-Iterate => How it works}/autosens.md (100%) rename docs/docs/{Customize-Iterate => How it works}/autotune.md (96%) create mode 100644 docs/docs/How it works/index.rst rename docs/docs/{While You Wait For Gear/Understand-determine-basal.md => How it works/understand-determine-basal.md} (94%) rename docs/docs/{Customize-Iterate => How it works}/understanding-autotune.md (100%) rename docs/docs/{While You Wait For Gear => How it works}/understanding-insulin-on-board-calculations.md (100%) rename docs/docs/{Customize-Iterate => Usage and maintenance/Wifi}/bluetooth-tethering-edison.md (98%) create mode 100644 docs/docs/Usage and maintenance/Wifi/index.rst rename docs/docs/{Customize-Iterate => Usage and maintenance/Wifi}/on-the-go-wifi-adding.md (98%) rename docs/docs/{While You Wait For Gear => Usage and maintenance/Wifi}/understanding-wifi-options.md (98%) rename docs/docs/{While You Wait For Gear => Usage and maintenance}/entering-carbs-bolus.md (100%) 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%) create mode 100644 docs/docs/Usage and maintenance/index.rst rename docs/docs/{While You Wait For Gear => Usage and maintenance}/monitoring-OpenAPS.md (99%) rename docs/docs/{Customize-Iterate => Usage and maintenance}/optimize-your-settings.md (85%) rename docs/docs/{Customize-Iterate => Usage and maintenance}/oref0-runagain.md (100%) rename docs/docs/{While You Wait For Gear => Usage and maintenance}/preferences-and-safety-settings.md (98%) rename docs/docs/{Customize-Iterate => Usage and maintenance}/update-your-rig.md (91%) rename docs/docs/{Customize-Iterate => Usage and maintenance}/usability-considerations.md (99%) create mode 100644 docs/docs/While You Wait For Gear/reading-list.md 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 ff8951661..e0330e321 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -77,7 +77,7 @@ Now that step 2 is done, the bootstrap script will then continue to run awhile l 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](<../While You Wait For Gear/monitoring-OpenAPS#accessing-your-online-rig-via-ssh>) from a computer on the same network, rather than using a cable. +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 @@ -152,7 +152,7 @@ network={ } ``` -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 ](<../Customize-Iterate/on-the-go-wifi-adding>) to add more options to your rig at any point. +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) 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 b734f0896..d198edde2 100644 --- a/docs/docs/Build Your Rig/step-3-setup-script.md +++ b/docs/docs/Build Your Rig/step-3-setup-script.md @@ -25,7 +25,7 @@ The screenshot below shows an example of the questions you'll be prompted to rep * 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](<../Customize-Iterate/bluetooth-tethering-edison>) after setup. + * 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) 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 1c0d7ea87..140e14f68 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 - 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](<../While You Wait For Gear/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 - 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](<../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. diff --git a/docs/docs/Build Your Rig/step-5-finishing-setup.md b/docs/docs/Build Your Rig/step-5-finishing-setup.md index 656d2327e..01cffd98c 100644 --- a/docs/docs/Build Your Rig/step-5-finishing-setup.md +++ b/docs/docs/Build Your Rig/step-5-finishing-setup.md @@ -3,7 +3,7 @@ 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](<../While You Wait For Gear/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.** +**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! @@ -24,10 +24,10 @@ So that we can notify you if necessary, [please fill out this form if you have b 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](<../Customize-Iterate/on-the-go-wifi-adding>) so that when you are away from home, the rig has access to trusted wifi networks -* [Set up Papertrail](<../While You Wait For Gear/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. +* [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](<../Customize-Iterate/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. +* [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. diff --git a/docs/docs/Customize-Iterate/index.rst b/docs/docs/Customize-Iterate/index.rst index c60ec4831..d0aaa674c 100644 --- a/docs/docs/Customize-Iterate/index.rst +++ b/docs/docs/Customize-Iterate/index.rst @@ -6,16 +6,8 @@ Customize - Iterate :glob: :hidden: - Optimizing Your Settings - Offline Looping - Enable Bluetooth tethering - Add more wifi to your rig + + oref1: SMB and UAM Useful apps for accessing your rig IFTTT and Pebble buttons - Autosens - Autotune - Understanding Autotune - oref1: SMB and UAM - Tips & tricks - Update your rig in the future - How to run oref0-setup.sh again \ No newline at end of file + Offline Looping \ No newline at end of file diff --git a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md index 81f5886ce..5404183f5 100644 --- a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md +++ b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md @@ -1,6 +1,6 @@ # 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](<../While You Wait For Gear/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. +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. ## Medtronic CGM users Medtronic CGM users can, by default, automatically loop offline because the rig will read CGM data directly from the pump. @@ -181,7 +181,7 @@ On your OpenAPS rig, the xdrip-js library can read directly from the Dexcom tran * 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](<../While You Wait For Gear/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: +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 93a49e3cd..e72090cb6 100644 --- a/docs/docs/Customize-Iterate/oref1.md +++ b/docs/docs/Customize-Iterate/oref1.md @@ -8,7 +8,7 @@ NOTE OF CAUTION: * 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](<../While You Wait For Gear/collect-data-and-prepare#easy-bolus-button>)) and know how to deliver boluses without using the bolus wizard. -* See this page on [optimizing settings](<../Customize-Iterate/optimize-your-settings#optimizing-your-settings>) for reminders and tips on changing one thing at a 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. ## Only run oref1 with the following caveats in mind: @@ -54,7 +54,7 @@ In addition, as of 0.6.0-master, using Bolus Wizard to input boluses and meal ca * 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](<../While You Wait For Gear/preferences-and-safety-settings#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#advanced-oref1-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 diff --git a/docs/docs/Gear Up/pi-based-rigs.md b/docs/docs/Gear Up/pi-based-rigs.md index ef1a6644e..2859fa8b7 100644 --- a/docs/docs/Gear Up/pi-based-rigs.md +++ b/docs/docs/Gear Up/pi-based-rigs.md @@ -23,7 +23,7 @@ Lipo batteries are typically used to power the rig on the go because they charge 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](<../Customize-Iterate/usability-considerations#improving-the-battery-life-of-your-raspberry-pi>). +**Note**: You will probably want to underclock your Raspberry Pi to get a longer battery life. [See this for details](<../Usage and maintenance/usability-considerations#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. diff --git a/docs/docs/Customize-Iterate/autosens.md b/docs/docs/How it works/autosens.md similarity index 100% rename from docs/docs/Customize-Iterate/autosens.md rename to docs/docs/How it works/autosens.md diff --git a/docs/docs/Customize-Iterate/autotune.md b/docs/docs/How it works/autotune.md similarity index 96% rename from docs/docs/Customize-Iterate/autotune.md rename to docs/docs/How it works/autotune.md index 8fd4a908d..18e30af18 100644 --- a/docs/docs/Customize-Iterate/autotune.md +++ b/docs/docs/How it works/autotune.md @@ -39,20 +39,20 @@ Below the ISF and carb ratio, you'll see the basal report. ### 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](<../Customize-Iterate/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](<../Customize-Iterate/autotune#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](<../How it works/autotune#phase-c-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](<../Customize-Iterate/autotune#why-isn-t-it-working-at-all>) that might contribute to flukey data. +5. Results don't look like what you expected to see? [See here for some suggestions](<../How it works/autotune#why-isn-t-it-working-at-all>) that might contribute to flukey data. ## Other sections on this page -* Background in plain language on [how Autotune works](<../Customize-Iterate/autotune#how-autotune-works>) -* The [difference between Autotune and "autosens"](<../Customize-Iterate/autotune#the-difference-between-autotune-and-autosens>) (aka, [autosensitivity](<../Customize-Iterate/autosens>)) +* Background in plain language on [how Autotune works](<../How it works/autotune#how-autotune-works>) +* The [difference between Autotune and "autosens"](<../How it works/autotune#the-difference-between-autotune-and-autosens>) (aka, [autosensitivity](<../How it works/autosens>)) * Different ways to use Autotune * Run it with [AutotuneWeb](https://autotuneweb.azurewebsites.net/) - * [Phase A](<../Customize-Iterate/autotune#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](<../Customize-Iterate/autotune#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](<../Customize-Iterate/autotune#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. + * [Phase A](<../How it works/autotune#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](<../How it works/autotune#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](<../How it works/autotune#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 @@ -158,7 +158,7 @@ Log into the NEW rig and run the following command: 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) +**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>) **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. @@ -346,7 +346,7 @@ oref0-autotune --dir=~/myopenaps --ns-host=https://mynightscout.herokuapp.com -- #### Re-Running Autotune -Remember, to initially set-up Autotune follow the instructions [above](<../Customize-Iterate/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#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 @@ -381,7 +381,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. @@ -407,7 +407,7 @@ Other things to check: * 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). +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>). 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). @@ -415,4 +415,4 @@ Remember, autotune is still a work in progress (WIP). Please provide feedback al #### Yay, It Worked! This is Cool! -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). +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>). diff --git a/docs/docs/How it works/index.rst b/docs/docs/How it works/index.rst new file mode 100644 index 000000000..c225acea7 --- /dev/null +++ b/docs/docs/How it works/index.rst @@ -0,0 +1,13 @@ +How it works +============================================== + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + + How OpenAPS makes decisions + Insulin on board calculations + Understanding Autotune + Running Autotune + Using Autosens \ 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 94% 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 b6541de6e..a217d2aaf 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](<../While You Wait For Gear/understanding-insulin-on-board-calculations>). + * `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. @@ -38,7 +38,7 @@ This includes: ![Estimating carb impact](../Images/Carb_predictions.jpg) -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](<../While You Wait For Gear/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](<../While You Wait For Gear/preferences-and-safety-settings#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 diff --git a/docs/docs/Customize-Iterate/understanding-autotune.md b/docs/docs/How it works/understanding-autotune.md similarity index 100% rename from docs/docs/Customize-Iterate/understanding-autotune.md rename to docs/docs/How it works/understanding-autotune.md 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 100% 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 diff --git a/docs/docs/Resources/clinician-guide-to-OpenAPS.md b/docs/docs/Resources/clinician-guide-to-OpenAPS.md index 1e50b73c9..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](<../Customize-Iterate/optimize-your-settings>) 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](<../Customize-Iterate/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. +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](<../While You Wait For Gear/understand-determine-basal#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/switching-between-DIY-systems.md b/docs/docs/Resources/switching-between-DIY-systems.md index e6f918ac1..1eda14fcb 100644 --- a/docs/docs/Resources/switching-between-DIY-systems.md +++ b/docs/docs/Resources/switching-between-DIY-systems.md @@ -70,8 +70,8 @@ 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](<../While You Wait For Gear/understand-determine-basal>). -* Loop has temporary targets available by using the workout mode in the Loop app. OpenAPS can have [multiple temp targets](<../Customize-Iterate/autosens#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](<../Customize-Iterate/ifttt-integration>). +* 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>) (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](<../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 @@ -80,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)](<../While You Wait For Gear/preferences-and-safety-settings#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](<../While You Wait For Gear/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#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](<../While You Wait For Gear/preferences-and-safety-settings#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](<../While You Wait For Gear/preferences-and-safety-settings#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](<../Customize-Iterate/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 + * [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](<../While You Wait For Gear/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](<../While You Wait For Gear/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. + * 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 @@ -134,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)](<../Customize-Iterate/autosens#advanced-meal-assist-or-ama>) algorithm, [autosensitivity](<../Customize-Iterate/autosens#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. diff --git a/docs/docs/Customize-Iterate/bluetooth-tethering-edison.md b/docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md similarity index 98% rename from docs/docs/Customize-Iterate/bluetooth-tethering-edison.md rename to docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md index 5c6e03c20..e4d8d0e34 100644 --- a/docs/docs/Customize-Iterate/bluetooth-tethering-edison.md +++ b/docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md @@ -25,7 +25,7 @@ Even though some specific phones are fully capable of bluetooth tethering and th * 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 @@ -99,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. @@ -109,7 +109,7 @@ root@edisonhost:~# bluetoothd --version 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: @@ -128,7 +128,7 @@ root@edisonhost:~# bluetoothd --version `sudo /usr/local/bin/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` @@ -152,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/Usage and maintenance/Wifi/index.rst b/docs/docs/Usage and maintenance/Wifi/index.rst new file mode 100644 index 000000000..a36848b81 --- /dev/null +++ b/docs/docs/Usage and maintenance/Wifi/index.rst @@ -0,0 +1,11 @@ +Wifi setup and options +============================================== + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + + Understanding your wifi options + Enable Bluetooth tethering + Add more wifi to your rig 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 98% 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 661544bc5..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 @@ -35,7 +35,7 @@ Note for iPhone users: It is recommended that you update the name of your iPhone 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 98% 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 b91321d3f..c6e7d9961 100644 --- a/docs/docs/While You Wait For Gear/understanding-wifi-options.md +++ b/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md @@ -2,7 +2,7 @@ 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)](<../Customize-Iterate/on-the-go-wifi-adding>) +* Joining known wifi networks [(you'll be able to add more wifi networks to your rig in the future)](<../Usage and maintenance/Wifi/on-the-go-wifi-adding>) * BT-tethering to your cell phone's hotspot * Wifi-tethering to your cell phone's hotspot * Wifi-tethering to mifi device @@ -35,7 +35,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 diff --git a/docs/docs/While You Wait For Gear/entering-carbs-bolus.md b/docs/docs/Usage and maintenance/entering-carbs-bolus.md similarity index 100% rename from docs/docs/While You Wait For Gear/entering-carbs-bolus.md rename to docs/docs/Usage and maintenance/entering-carbs-bolus.md 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/Usage and maintenance/index.rst b/docs/docs/Usage and maintenance/index.rst new file mode 100644 index 000000000..241e94952 --- /dev/null +++ b/docs/docs/Usage and maintenance/index.rst @@ -0,0 +1,16 @@ +Usage and maintenance +============================================== + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + + How to enter carbs and boluses + Preferences and safety settings + Monitoring OpenAPS + Optimizing Your Settings + Tips & tricks + Update your rig in the future + How to run oref0-setup.sh again + Wifi options \ No newline at end of file diff --git a/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md similarity index 99% rename from docs/docs/While You Wait For Gear/monitoring-OpenAPS.md rename to docs/docs/Usage and maintenance/monitoring-OpenAPS.md index 3f533c09f..3966832b3 100644 --- a/docs/docs/While You Wait For Gear/monitoring-OpenAPS.md +++ b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md @@ -549,7 +549,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 [here](<../Customize-Iterate/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: +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 diff --git a/docs/docs/Customize-Iterate/optimize-your-settings.md b/docs/docs/Usage and maintenance/optimize-your-settings.md similarity index 85% rename from docs/docs/Customize-Iterate/optimize-your-settings.md rename to docs/docs/Usage and maintenance/optimize-your-settings.md index 56e25f449..3c14cadb5 100644 --- a/docs/docs/Customize-Iterate/optimize-your-settings.md +++ b/docs/docs/Usage and maintenance/optimize-your-settings.md @@ -10,11 +10,11 @@ Think about this: when many people start looping, they often have too high basal 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](<../Customize-Iterate/autotune>).) +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](<../How it works/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](<../Customize-Iterate/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: +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 +28,6 @@ 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](<../Customize-Iterate/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>).) +* 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>).) diff --git a/docs/docs/Customize-Iterate/oref0-runagain.md b/docs/docs/Usage and maintenance/oref0-runagain.md similarity index 100% rename from docs/docs/Customize-Iterate/oref0-runagain.md rename to docs/docs/Usage and maintenance/oref0-runagain.md 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 98% 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 421473dee..e3ca46e77 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](<../Customize-Iterate/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](<../While You Wait For Gear/understanding-insulin-on-board-calculations#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 diff --git a/docs/docs/Customize-Iterate/update-your-rig.md b/docs/docs/Usage and maintenance/update-your-rig.md similarity index 91% rename from docs/docs/Customize-Iterate/update-your-rig.md rename to docs/docs/Usage and maintenance/update-your-rig.md index ba6ca102d..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](<../Customize-Iterate/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). +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`. @@ -50,7 +50,7 @@ Now that you've updated your `oref0` version, you will want to run the oref0-set ## Step 3: Remember to set your preferences! -Reminder! You'll need to re-set your preferences in `preferences.json`. See [the preferences page](<../While You Wait For Gear/preferences-and-safety-settings>) 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 99% rename from docs/docs/Customize-Iterate/usability-considerations.md rename to docs/docs/Usage and maintenance/usability-considerations.md index 29de134bc..8024b6847 100644 --- a/docs/docs/Customize-Iterate/usability-considerations.md +++ b/docs/docs/Usage and maintenance/usability-considerations.md @@ -96,7 +96,7 @@ Temporary Targets can be set in advance by setting a future date/time stamp in N ## 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](<../While You Wait For Gear/preferences-and-safety-settings#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. 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 499c45518..ec4200233 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 @@ -70,7 +70,7 @@ Some of the super advanced features you'll learn about later - Unannounced 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](<../Customize-Iterate/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. +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](<../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. 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: diff --git a/docs/docs/While You Wait For Gear/index.rst b/docs/docs/While You Wait For Gear/index.rst index abad1d3a5..3a293fd74 100644 --- a/docs/docs/While You Wait For Gear/index.rst +++ b/docs/docs/While You Wait For Gear/index.rst @@ -6,12 +6,7 @@ While you wait for gear :glob: :hidden: + Setting up Nightscout Collect your data & prepare Make Your First PR - Setting up Nightscout - Entering carbs & boluses - How OpenAPS makes decisions - Monitoring OpenAPS - Preferences and Safety Settings - Understanding your wifi options - + Do some reading 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..ae7233355 --- /dev/null +++ b/docs/docs/While You Wait For Gear/reading-list.md @@ -0,0 +1,3 @@ +# Reading list + +Placeholder: list of sections to read/skim BEFORE installing anything! \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 93c0a60c9..3fe02ed91 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,13 +26,17 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of Overview: Understanding OpenAPS - Gear Up + Hardware - While You Wait For Gear + Getting ready - Installing OpenAPS on your rig - - Customize-Iterate + Installing OpenAPS + + How OpenAPS works + + Usage and maintenance + + Customizing and extra features Troubleshooting diff --git a/requirements.txt b/requirements.txt index 45d1f6917..4fa9a0478 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,28 +1,4 @@ -alabaster==0.7.12 -argcomplete==1.10.0 -Babel==2.7.0 -certifi==2019.6.16 -chardet==3.0.4 -CommonMark==0.5.4 -docutils==0.14 -gitdb2==2.0.5 -GitPython==2.1.11 -idna==2.8 -imagesize==1.1.0 -Jinja2==2.10.1 -MarkupSafe==1.1.1 -mock==3.0.5 -nose==1.3.7 -openaps==0.1.5 -Pygments==2.4.2 -pyserial==3.4 -python-dateutil==2.8.0 -pytz==2019.1 recommonmark==0.4.0 -requests==2.22.0 -six==1.12.0 -smmap2==2.0.5 -snowballstemmer==1.9.0 -Sphinx==1.5.6 -sphinx-rtd-theme==0.4.3 -urllib3==1.25.3 +sphinx==1.5.6 +git+git://github.com/bewest/decoding-carelink.git@dev +openaps \ No newline at end of file From eab93464911f722ccc65931c1f24e0fe9924a963 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 30 Aug 2019 15:05:44 -0400 Subject: [PATCH 20/54] avoid accidental extra section --- .../How it works/understanding-insulin-on-board-calculations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 e9e71e78f..c1075122e 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 @@ -92,7 +92,7 @@ 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. From 2adb54fa25efdfb1789ca339bd77fab39c8ce4ac Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 30 Aug 2019 15:07:28 -0400 Subject: [PATCH 21/54] fix typo in conf.py --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 508dd618b..3fd2708e8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -414,7 +414,7 @@ on_rtd = os.environ.get('READTHEDOCS', None) == 'True' if on_rtd: rtd_version = os.environ.get('READTHEDOCS_VERSION') - rtd_domain = draft-openaps-reorg # TEMPORARY to keep links working on RTD preview. os.environ.get('RTDDOMAIN', 'openaps') + rtd_domain = 'draft-openaps-reorg' # TEMPORARY to keep links working on RTD preview. os.environ.get('RTDDOMAIN', 'openaps') hosted_root = 'https://%s.readthedocs.org/en/%s/' % rtd_domain, rtd_version def setup(app): app.add_config_value('recommonmark_config', { From 3d668244f5ade6a315e0b076208114333ddf5abf Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Fri, 30 Aug 2019 15:12:32 -0400 Subject: [PATCH 22/54] and again --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 3fd2708e8..92e9e527a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -415,7 +415,7 @@ if on_rtd: rtd_version = os.environ.get('READTHEDOCS_VERSION') rtd_domain = 'draft-openaps-reorg' # TEMPORARY to keep links working on RTD preview. os.environ.get('RTDDOMAIN', 'openaps') - hosted_root = 'https://%s.readthedocs.org/en/%s/' % rtd_domain, rtd_version + 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, From 977308cc32f7da88d960a2848d8a11798f5adca3 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sat, 31 Aug 2019 08:20:40 -0400 Subject: [PATCH 23/54] Add a reading list to the prep section, corresponding to remaining topics previously in 'while you wait for gear' --- docs/docs/Build Your Rig/step-5-finishing-setup.md | 2 +- docs/docs/Usage and maintenance/oref0-runagain.md | 2 +- docs/docs/While You Wait For Gear/reading-list.md | 14 +++++++++++++- 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/docs/Build Your Rig/step-5-finishing-setup.md b/docs/docs/Build Your Rig/step-5-finishing-setup.md index 01cffd98c..d01b53c0d 100644 --- a/docs/docs/Build Your Rig/step-5-finishing-setup.md +++ b/docs/docs/Build Your Rig/step-5-finishing-setup.md @@ -1,4 +1,4 @@ -# Finish your OpenAPS setup +# Step 5: Finish your OpenAPS setup You're looping? Congrats! However, you're not done quite done yet. diff --git a/docs/docs/Usage and maintenance/oref0-runagain.md b/docs/docs/Usage and maintenance/oref0-runagain.md index 0e9c61995..4680420e4 100644 --- a/docs/docs/Usage and maintenance/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/reading-list.md b/docs/docs/While You Wait For Gear/reading-list.md index ae7233355..1286989ec 100644 --- a/docs/docs/While You Wait For Gear/reading-list.md +++ b/docs/docs/While You Wait For Gear/reading-list.md @@ -1,3 +1,15 @@ # Reading list -Placeholder: list of sections to read/skim BEFORE installing anything! \ No newline at end of file +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 From 2d90cd05dec5115a4056957444784f629030952d Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 2 Sep 2019 15:19:51 -0400 Subject: [PATCH 24/54] editing overview section for clarity. This gets into more personal taste than some of the other organizational efforts; e.g., removing the overview-of-steps image because I found it substantially more confusing than helpful (even though it looks very snazzy) and replacing with a text-based overview indicating that hardware and other prep can be done in parallel, then you install, then you'll likely do some additional customization. Keeping these changes separate, & not changing any filenames, in case anyone wants to cherry-pick around this one. --- .../offline-looping-and-monitoring.md | 2 ++ .../how-openaps-works-overview.md | 20 +++++++++---------- .../overview-of-build-process.md | 13 ++++++++---- .../using-the-docs.md | 2 +- .../Wifi/understanding-wifi-options.md | 2 ++ 5 files changed, 24 insertions(+), 15 deletions(-) diff --git a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md index 5404183f5..a0dc8ae40 100644 --- a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md +++ b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md @@ -1,5 +1,7 @@ # Offline looping - aka, running OpenAPS without internet connectivity +## 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. ## Medtronic CGM users 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 8829cb3dc..8a7a264a1 100644 --- a/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md +++ b/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md @@ -7,25 +7,25 @@ A DIY loop is no different. It gathers data from: * [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](<../Build Your Rig/index>) -* configure it to talk to YOUR devices and have your information and safety settings on it (based on your preferences) - -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. +* 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. 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/overview-of-build-process.md b/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md index 5e2aac689..25e6a9f94 100644 --- a/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md +++ b/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md @@ -1,10 +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/index>) 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 some time 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/index>) 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. +2. Install OpenAPS on your rig! There are detailed instructions here 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. + +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. + +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 index cc9981d90..d28513fbb 100644 --- a/docs/docs/Understanding OpenAPS-Overview/using-the-docs.md +++ b/docs/docs/Understanding OpenAPS-Overview/using-the-docs.md @@ -12,7 +12,7 @@ We recommend bookmarking the [link](http://openaps.readthedocs.org/en/latest/) t ## The docs 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. +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) diff --git a/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md b/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md index c6e7d9961..17824d0c1 100644 --- a/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md +++ b/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md @@ -13,6 +13,8 @@ Most users prefer a combination of known wifi networks and BT-tethering to maint 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 If your home wifi is flaky, your OpenAPS looping will likely be flaky as well. Speed isn't super important, but reliability of uptime is. If your router is old and hasn't been updated in awhile, simply updating your router may be a good idea. Routers are about $100 for a new, well-featured router. If you get your router as part of a package from your ISP, you can ask if they have any updated equipment to improve your home wifi network's stability. Many ISPs tend to forget about their customers' old equipment until they start complaining about it. From b546f65dffa5223ca9827282357c66e2e0f4fe46 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 2 Sep 2019 15:21:54 -0400 Subject: [PATCH 25/54] add missed link --- .../overview-of-build-process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 25e6a9f94..b2ae4e746 100644 --- a/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md +++ b/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md @@ -4,11 +4,11 @@ The OpenAPS setup process can be broken up into several parts: 1. These can be done in parallel: - A. [Choose and get your hardware.](<../Gear Up/index>) 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 some time 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. + A. [Choose and get your hardware.](<../Gear Up/index>) 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. B. [Prepare to use OpenAPS.](<../While You Wait For Gear/index>) 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. -2. Install OpenAPS on your rig! There are detailed instructions here 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. +2. [Install OpenAPS on your rig!](<../Build Your Rig/index>) 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. 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. From e398ce54e61fbbcd00bf7e21cccdb131fc6841d9 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 2 Sep 2019 21:35:56 -0400 Subject: [PATCH 26/54] move a few "tips and tricks" to other appropriate locations so they're easier to find; rename section, recommend reading when done with installation process --- .../Build Your Rig/step-5-finishing-setup.md | 28 ++++++++++- .../communication-support-channels.md | 2 +- .../entering-carbs-bolus.md | 9 +++- docs/docs/Usage and maintenance/index.rst | 6 +-- .../usability-considerations.md | 50 +++---------------- 5 files changed, 46 insertions(+), 49 deletions(-) diff --git a/docs/docs/Build Your Rig/step-5-finishing-setup.md b/docs/docs/Build Your Rig/step-5-finishing-setup.md index d01b53c0d..208bfff9c 100644 --- a/docs/docs/Build Your Rig/step-5-finishing-setup.md +++ b/docs/docs/Build Your Rig/step-5-finishing-setup.md @@ -20,10 +20,36 @@ So that we can notify you if necessary, [please fill out this form if you have b **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 diff --git a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md index f70c98732..6e7af1ba7 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. ### Google Group -A google group focused on #OpenAPS development work can be found [here](https://groups.google.com/d/forum/openaps-dev) - everyone is recommended 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. +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. 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/).) diff --git a/docs/docs/Usage and maintenance/entering-carbs-bolus.md b/docs/docs/Usage and maintenance/entering-carbs-bolus.md index 14c766132..3183f513b 100644 --- a/docs/docs/Usage and maintenance/entering-carbs-bolus.md +++ b/docs/docs/Usage and maintenance/entering-carbs-bolus.md @@ -4,6 +4,8 @@ How do you enter carbs & do boluses with OpenAPS? You have a variety of ways to ## 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. @@ -12,7 +14,10 @@ How do you enter carbs & do boluses with OpenAPS? You have a variety of ways to ## 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**. +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: @@ -24,6 +29,8 @@ Look at this image for the big picture: * 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. 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 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. diff --git a/docs/docs/Usage and maintenance/index.rst b/docs/docs/Usage and maintenance/index.rst index 241e94952..a2b1ccc50 100644 --- a/docs/docs/Usage and maintenance/index.rst +++ b/docs/docs/Usage and maintenance/index.rst @@ -9,8 +9,8 @@ Usage and maintenance How to enter carbs and boluses Preferences and safety settings Monitoring OpenAPS - Optimizing Your Settings - Tips & tricks - Update your rig in the future + Using your loop: common situations + Optimizing your settings How to run oref0-setup.sh again + Update your rig in the future Wifi options \ No newline at end of file diff --git a/docs/docs/Usage and maintenance/usability-considerations.md b/docs/docs/Usage and maintenance/usability-considerations.md index 8024b6847..b092f6f84 100644 --- a/docs/docs/Usage and maintenance/usability-considerations.md +++ b/docs/docs/Usage and maintenance/usability-considerations.md @@ -1,11 +1,8 @@ -# 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-) @@ -14,17 +11,14 @@ Now that you've closed the loop, you probably have a lot of new "first" experien - [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-) -- [Improving the battery life of your Raspberry Pi](#improving-the-battery-life-of-your-raspberry-pi) -
-## 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 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.
+## 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 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 (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.
## 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.) @@ -89,11 +83,6 @@ 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 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](<../Usage and maintenance/preferences-and-safety-settings#curve-rapid-acting>) in your `preferences.json` file (which you can edit with `edit-pref`). @@ -101,28 +90,3 @@ The most important setting for switching between insulin types in an OpenAPS rig 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. Some users who switch to Fiasp find that they need to adjust settings. Others do not need to change settings that much, and autosens and/or autotune can help adjust to any variances over time as your body's needs change related to the difference insulin type. YDMV, as always! - -## 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! From b9e41f78d43c85ed6df7d359024b9bc8ec054bf1 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 2 Sep 2019 22:09:41 -0400 Subject: [PATCH 27/54] typo --- docs/docs/Resources/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 7b96537a0b2d65946342cf8ad4f4235d9939cef7 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Mon, 2 Sep 2019 22:12:26 -0400 Subject: [PATCH 28/54] consistent tense/capitalization --- docs/docs/While You Wait For Gear/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/While You Wait For Gear/index.rst b/docs/docs/While You Wait For Gear/index.rst index 3a293fd74..4ef6f4da9 100644 --- a/docs/docs/While You Wait For Gear/index.rst +++ b/docs/docs/While You Wait For Gear/index.rst @@ -6,7 +6,7 @@ While you wait for gear :glob: :hidden: - Setting up Nightscout + Set up Nightscout Collect your data & prepare - Make Your First PR + Make your first PR Do some reading From 6b8f11c2cb2054cc1289c5b292a3168d797d8551 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 16:59:02 -0400 Subject: [PATCH 29/54] reinstate the nice already-expanded-to-one-level ToC sidebar with headings. Remove now unused subdirectory index.rst files; shift any content in those to section overviews. --- .../{index.rst => install-overview.md} | 17 +-- docs/docs/Customize-Iterate/index.rst | 13 -- docs/docs/Gear Up/hardware-overview.md | 15 ++ docs/docs/Gear Up/index.rst | 31 ---- docs/docs/Give Back-Pay It Forward/index.rst | 11 -- docs/docs/How it works/index.rst | 13 -- docs/docs/Resources/index.rst | 15 -- docs/docs/Resources/my-first-pr.md | 4 +- .../General_linux_troubleshooting.md | 6 +- docs/docs/Troubleshooting/index.rst | 18 --- .../Understanding OpenAPS-Overview/index.rst | 13 -- docs/docs/Usage and maintenance/index.rst | 16 --- docs/docs/While You Wait For Gear/index.rst | 12 -- docs/index.rst | 133 ++++++++++++++++-- 14 files changed, 144 insertions(+), 173 deletions(-) rename docs/docs/Build Your Rig/{index.rst => install-overview.md} (91%) delete mode 100644 docs/docs/Customize-Iterate/index.rst create mode 100644 docs/docs/Gear Up/hardware-overview.md delete mode 100644 docs/docs/Gear Up/index.rst delete mode 100644 docs/docs/Give Back-Pay It Forward/index.rst delete mode 100644 docs/docs/How it works/index.rst delete mode 100644 docs/docs/Resources/index.rst delete mode 100644 docs/docs/Troubleshooting/index.rst delete mode 100644 docs/docs/Understanding OpenAPS-Overview/index.rst delete mode 100644 docs/docs/Usage and maintenance/index.rst delete mode 100644 docs/docs/While You Wait For Gear/index.rst diff --git a/docs/docs/Build Your Rig/index.rst b/docs/docs/Build Your Rig/install-overview.md similarity index 91% rename from docs/docs/Build Your Rig/index.rst rename to docs/docs/Build Your Rig/install-overview.md index 7677a30d0..7750542c0 100644 --- a/docs/docs/Build Your Rig/index.rst +++ b/docs/docs/Build Your Rig/install-overview.md @@ -1,6 +1,4 @@ -------------------------------- -Installing OpenAPS on your rig -------------------------------- +# Installing OpenAPS on your rig Getting OpenAPS running on your rig generally takes five steps: @@ -21,16 +19,3 @@ Some conventions used in these docs: * 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` - - - -.. toctree:: - :maxdepth: 4 - :hidden: - - step-1-flashing - step-2-wifi-dependencies - step-3-setup-script - step-4-watching-log - step-5-finishing-setup - logging-into-rig-serial diff --git a/docs/docs/Customize-Iterate/index.rst b/docs/docs/Customize-Iterate/index.rst deleted file mode 100644 index d0aaa674c..000000000 --- a/docs/docs/Customize-Iterate/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -Customize - Iterate -============================================== - -.. toctree:: - :maxdepth: 2 - :glob: - :hidden: - - - oref1: SMB and UAM - Useful apps for accessing your rig - IFTTT and Pebble buttons - Offline Looping \ No newline at end of file diff --git a/docs/docs/Gear Up/hardware-overview.md b/docs/docs/Gear Up/hardware-overview.md new file mode 100644 index 000000000..fabd1317e --- /dev/null +++ b/docs/docs/Gear Up/hardware-overview.md @@ -0,0 +1,15 @@ +# Hardware overview + +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: + +* 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 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. + + +**Note about deprecated hardware setup:** 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. \ No newline at end of file diff --git a/docs/docs/Gear Up/index.rst b/docs/docs/Gear Up/index.rst deleted file mode 100644 index 4c4e06afc..000000000 --- a/docs/docs/Gear Up/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -Hardware overview -===================== - -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: - -- 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 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. - - -.. NOTE:: - **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. - - -.. toctree:: - :maxdepth: 3 - :glob: - :hidden: - - Compatible Pumps - Compatible CGMs - Your rig hardware options - Edison rigs - Raspberry Pi rigs \ No newline at end of file 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 d663a862b..000000000 --- a/docs/docs/Give Back-Pay It Forward/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Give Back-Pay It Forward -============================================== - -.. toctree:: - :maxdepth: 2 - :glob: - :hidden: - - Donate your data - Help others - pay it forward - diff --git a/docs/docs/How it works/index.rst b/docs/docs/How it works/index.rst deleted file mode 100644 index c225acea7..000000000 --- a/docs/docs/How it works/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -How it works -============================================== - -.. toctree:: - :maxdepth: 2 - :glob: - :hidden: - - How OpenAPS makes decisions - Insulin on board calculations - Understanding Autotune - Running Autotune - Using Autosens \ No newline at end of file diff --git a/docs/docs/Resources/index.rst b/docs/docs/Resources/index.rst deleted file mode 100644 index 582fd92a6..000000000 --- a/docs/docs/Resources/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -Resources ---------- - -.. toctree:: - :maxdepth: 4 - :glob: - - my-first-pr - clinician-guide-to-OpenAPS - technical-resources - history - glossary - switching-between-DIY-systems - 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..c3abdfd6b 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,7 +33,7 @@ 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: diff --git a/docs/docs/Troubleshooting/General_linux_troubleshooting.md b/docs/docs/Troubleshooting/General_linux_troubleshooting.md index 34e2faa40..5ade76cb4 100644 --- a/docs/docs/Troubleshooting/General_linux_troubleshooting.md +++ b/docs/docs/Troubleshooting/General_linux_troubleshooting.md @@ -1,6 +1,8 @@ -# General Linux troubleshooting +# Troubleshooting -## Before you get started +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/). + +## 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. diff --git a/docs/docs/Troubleshooting/index.rst b/docs/docs/Troubleshooting/index.rst deleted file mode 100644 index c1218fd4a..000000000 --- a/docs/docs/Troubleshooting/index.rst +++ /dev/null @@ -1,18 +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/). - -.. toctree:: - :maxdepth: 4 - :hidden: - - oref0-setup-troubleshooting - General_linux_troubleshooting - Common-error-messages - Wifi-and-hotspot-issues - Pump-rig-communications-troubleshooting - CGM-rig-communications-troubleshooting - Rig-NS-communications-troubleshooting - Medtronic-Button-Errors - Carelink diff --git a/docs/docs/Understanding OpenAPS-Overview/index.rst b/docs/docs/Understanding OpenAPS-Overview/index.rst deleted file mode 100644 index bf44b1007..000000000 --- a/docs/docs/Understanding OpenAPS-Overview/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -Understanding OpenAPS (Overview) -============================================== - - -.. toctree:: - :maxdepth: 2 - :hidden: - - How OpenAPS works - Overview of steps - Using this documentation - Where to go for help - \ No newline at end of file diff --git a/docs/docs/Usage and maintenance/index.rst b/docs/docs/Usage and maintenance/index.rst deleted file mode 100644 index a2b1ccc50..000000000 --- a/docs/docs/Usage and maintenance/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -Usage and maintenance -============================================== - -.. toctree:: - :maxdepth: 2 - :glob: - :hidden: - - How to enter carbs and boluses - Preferences and safety settings - Monitoring OpenAPS - Using your loop: common situations - Optimizing your settings - How to run oref0-setup.sh again - Update your rig in the future - Wifi options \ No newline at end of file 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 4ef6f4da9..000000000 --- a/docs/docs/While You Wait For Gear/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -While you wait for gear -============================================== - -.. toctree:: - :maxdepth: 2 - :glob: - :hidden: - - Set up Nightscout - Collect your data & prepare - Make your first PR - Do some reading diff --git a/docs/index.rst b/docs/index.rst index 3fe02ed91..276155082 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,27 +19,138 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of 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: :hidden: + :caption: Overview - Overview: Understanding OpenAPS + How OpenAPS works + Overview of steps + Using this documentation + Where to go for help + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + :caption: Hardware + + Overview + Compatible Pumps + Compatible CGMs + Your rig hardware options + Edison rigs + Raspberry Pi rigs + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + :caption: Getting ready + + Set up Nightscout + Collect your data & prepare + Make your first PR + Do some reading - Hardware +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + :caption: Installing OpenAPS - Getting ready - - 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: + :hidden: + :caption: How OpenAPS works - How OpenAPS works + How OpenAPS makes decisions + Insulin on board calculations + Understanding Autotune + Running Autotune + Using Autosens - Usage and maintenance +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + :caption: Usage and maintenance - Customizing and extra features + How to enter carbs and boluses + Preferences and safety settings + Monitoring OpenAPS + Using your loop: common situations + Optimizing your settings + How to run oref0-setup.sh again + Update your rig in the future + Wifi options - Troubleshooting +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + :caption: Customizing and extra features + + oref1: SMB and UAM + Useful apps for accessing your rig + IFTTT and Pebble buttons + Offline Looping - Give Back - Pay it Forward +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + :caption: Troubleshooting - Resources + Overview and Linux reference + oref0-setup Troubleshooting + Wifi and hotspot issues + Pump-rig communications troubleshooting + CGM-rig communications troubleshooting + NS-rig communications troubleshooting + Medtronic button errors + Carelink troubleshooting + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + :caption: Give Back-Pay It Forward + + Donate your data + Help others - pay it forward + +.. toctree:: + :maxdepth: 2 + :glob: + :hidden: + :caption: Resources/Reference + + For Clinicians + History + Glossary + Making a PR + Technical resources + Switching between DIY systems + + + + + + + + From a6aae9e89ff6438ce3e3fd611a366614363143b4 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 17:20:00 -0400 Subject: [PATCH 30/54] minor clarifying/organizing edits to collect-your-data-and-prepare --- docs/docs/Customize-Iterate/oref1.md | 4 +- docs/docs/How it works/autotune.md | 2 +- .../collect-data-and-prepare.md | 44 +++++++++---------- 3 files changed, 26 insertions(+), 24 deletions(-) diff --git a/docs/docs/Customize-Iterate/oref1.md b/docs/docs/Customize-Iterate/oref1.md index e72090cb6..9baca694f 100644 --- a/docs/docs/Customize-Iterate/oref1.md +++ b/docs/docs/Customize-Iterate/oref1.md @@ -14,7 +14,9 @@ NOTE OF CAUTION: * 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. +* **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.) * 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 diff --git a/docs/docs/How it works/autotune.md b/docs/docs/How it works/autotune.md index 18e30af18..1628f8644 100644 --- a/docs/docs/How it works/autotune.md +++ b/docs/docs/How it works/autotune.md @@ -2,7 +2,7 @@ Autotune is a tool to help calculate potential adjustments to ISF, carb ratio, and basal rates. -## 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/). 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 ec4200233..eeebbf61e 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,25 +1,36 @@ # Collect your data and get prepared -Before getting started, we ask that you store at least 30 days of CGM 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](<../While You Wait For Gear/nightscout-setup>). 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. +## Store data - CGM, and ideally carbs and insulin + +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. 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. +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](<../How it works/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: +## Use your gear -* Use your Medtronic 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 +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 of us 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 care-givers 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 memu" guides will help: @@ -66,15 +77,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](<../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. - -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 From 300f58156f3ffe3c4dac25782a8a2be1f80b1054 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 18:53:16 -0400 Subject: [PATCH 31/54] list wifi files separately in main sidebar --- docs/docs/Usage and maintenance/Wifi/index.rst | 11 ----------- docs/index.rst | 5 ++++- 2 files changed, 4 insertions(+), 12 deletions(-) delete mode 100644 docs/docs/Usage and maintenance/Wifi/index.rst diff --git a/docs/docs/Usage and maintenance/Wifi/index.rst b/docs/docs/Usage and maintenance/Wifi/index.rst deleted file mode 100644 index a36848b81..000000000 --- a/docs/docs/Usage and maintenance/Wifi/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Wifi setup and options -============================================== - -.. toctree:: - :maxdepth: 2 - :glob: - :hidden: - - Understanding your wifi options - Enable Bluetooth tethering - Add more wifi to your rig diff --git a/docs/index.rst b/docs/index.rst index 276155082..7472a9ed4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -96,7 +96,10 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of Optimizing your settings How to run oref0-setup.sh again Update your rig in the future - Wifi options + Wifi overview + Adding wifi networks to your rig + Bluetooth tethering + .. toctree:: :maxdepth: 2 From b68d5456f271c8422db19c64d6fa707c1d7f9ad8 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 18:56:26 -0400 Subject: [PATCH 32/54] a round of i.e. vs. e.g. - see https://www.grammarly.com/blog/know-your-latin-i-e-vs-e-g/ Mnemonic: In Essence vs. Example (Great) --- .../Customize-Iterate/offline-looping-and-monitoring.md | 4 ++-- docs/docs/Gear Up/edison-explorer-board.md | 2 +- docs/docs/How it works/autosens.md | 4 ++-- docs/docs/How it works/autotune.md | 4 ++-- docs/docs/How it works/understanding-autotune.md | 2 +- docs/docs/Resources/my-first-pr.md | 2 +- .../CGM-rig-communications-troubleshooting.md | 4 ++-- docs/docs/Troubleshooting/General_linux_troubleshooting.md | 6 +++--- docs/docs/Troubleshooting/oref0-setup-troubleshooting.md | 4 ++-- .../Wifi/bluetooth-tethering-edison.md | 2 +- .../preferences-and-safety-settings.md | 2 +- docs/docs/Usage and maintenance/usability-considerations.md | 2 +- 12 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md index a0dc8ae40..d78298c5a 100644 --- a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md +++ b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md @@ -69,9 +69,9 @@ On your OpenAPS rig, the xdrip-js library can read directly from the Dexcom tran * **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: diff --git a/docs/docs/Gear Up/edison-explorer-board.md b/docs/docs/Gear Up/edison-explorer-board.md index b65128650..3eeebb0be 100644 --- a/docs/docs/Gear Up/edison-explorer-board.md +++ b/docs/docs/Gear Up/edison-explorer-board.md @@ -20,7 +20,7 @@ There are 4 types of Edison's. All of them work, but Versions 3 and 4 require an * 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_. + * 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>). diff --git a/docs/docs/How it works/autosens.md b/docs/docs/How it works/autosens.md index 1723b02a7..0a720142c 100644 --- a/docs/docs/How it works/autosens.md +++ b/docs/docs/How it works/autosens.md @@ -30,11 +30,11 @@ Here's what each symbol above means: "+" : 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. diff --git a/docs/docs/How it works/autotune.md b/docs/docs/How it works/autotune.md index 1628f8644..58a2520cf 100644 --- a/docs/docs/How it works/autotune.md +++ b/docs/docs/How it works/autotune.md @@ -168,7 +168,7 @@ If you are not running autotune as part of a closed loop, you can still run it a * (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 1a: Run via a cloud-based virtual machine** @@ -180,7 +180,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` diff --git a/docs/docs/How it works/understanding-autotune.md b/docs/docs/How it works/understanding-autotune.md index 798c2b013..1ade3940b 100644 --- a/docs/docs/How it works/understanding-autotune.md +++ b/docs/docs/How it works/understanding-autotune.md @@ -2,7 +2,7 @@ ## 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. +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 diff --git a/docs/docs/Resources/my-first-pr.md b/docs/docs/Resources/my-first-pr.md index c3abdfd6b..ad0552d54 100644 --- a/docs/docs/Resources/my-first-pr.md +++ b/docs/docs/Resources/my-first-pr.md @@ -37,7 +37,7 @@ PS, your fork and branch will still be sitting on your own personal GitHub accou 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/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/General_linux_troubleshooting.md b/docs/docs/Troubleshooting/General_linux_troubleshooting.md index 5ade76cb4..a7a51ede2 100644 --- a/docs/docs/Troubleshooting/General_linux_troubleshooting.md +++ b/docs/docs/Troubleshooting/General_linux_troubleshooting.md @@ -1,4 +1,4 @@ -# Troubleshooting +# Troubleshooting overview 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/). @@ -14,7 +14,7 @@ There are many commands that are useful, but some of the commands you'll get com * `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. @@ -93,7 +93,7 @@ One other helpful thing to do before starting any software work is to log your t ## 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. +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.) diff --git a/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md b/docs/docs/Troubleshooting/oref0-setup-troubleshooting.md index 498b8c588..ed737fb2c 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. @@ -53,7 +53,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/Usage and maintenance/Wifi/bluetooth-tethering-edison.md b/docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md index e4d8d0e34..d1a970746 100644 --- a/docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md +++ b/docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md @@ -20,7 +20,7 @@ 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 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 e3ca46e77..50c6cb858 100644 --- a/docs/docs/Usage and maintenance/preferences-and-safety-settings.md +++ b/docs/docs/Usage and maintenance/preferences-and-safety-settings.md @@ -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/Usage and maintenance/usability-considerations.md b/docs/docs/Usage and maintenance/usability-considerations.md index b092f6f84..00ceda700 100644 --- a/docs/docs/Usage and maintenance/usability-considerations.md +++ b/docs/docs/Usage and maintenance/usability-considerations.md @@ -18,7 +18,7 @@ Now that you've closed the loop, you probably have a lot of new "first" experien 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. -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.
+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.) From e375eb0b4b5a71d8c9719d0c263f5e73b9870c15 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 18:57:24 -0400 Subject: [PATCH 33/54] add note about nightscout reports in optimize-your-settings --- docs/docs/Usage and maintenance/optimize-your-settings.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/docs/Usage and maintenance/optimize-your-settings.md b/docs/docs/Usage and maintenance/optimize-your-settings.md index 3c14cadb5..035d14078 100644 --- a/docs/docs/Usage and maintenance/optimize-your-settings.md +++ b/docs/docs/Usage and maintenance/optimize-your-settings.md @@ -1,10 +1,14 @@ # 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 From 377372d3c1faa7d9fa171a2f58a096b041450d7b Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 18:58:01 -0400 Subject: [PATCH 34/54] minor organizational edits to monitoring, mostly just make clear that serial connection is a way to monitor a rig regardless of internet connection --- .../monitoring-OpenAPS.md | 27 ++++++++----------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/docs/docs/Usage and maintenance/monitoring-OpenAPS.md b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md index 3966832b3..4e0f677e3 100644 --- a/docs/docs/Usage and maintenance/monitoring-OpenAPS.md +++ b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md @@ -3,6 +3,7 @@ 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) @@ -20,30 +21,27 @@ There are two general groups of ways to monitor your rigs: ## The main ways of monitoring your rig OFFLINE include: +* [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>) -******************************** - -## You'll probably come back to this page later to setup different monitoring options - -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](<#if-your-computer-and-rig-are-on-the-same-wifi-network>) -* [If your computer and rig are on different wifi networks](<#if-your-computer-and-rig-are-on-different-wifi-networks>) * [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,11 +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) - -If your computer and rig are on different wifi networks, you will need to connect using a data cable connected to the UART port on the rig. See [these instructions](<../Build Your Rig/logging-into-rig-serial>). ### autossh Reverse Tunnel @@ -121,6 +114,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. @@ -228,9 +223,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. @@ -240,7 +235,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: From 7e7656f438335efd834d3b75028900e05029a3b1 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 18:59:00 -0400 Subject: [PATCH 35/54] minor organization edits regarding wifi options, add note about networks potentially only allowing http(s) --- .../Wifi/understanding-wifi-options.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md b/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md index 17824d0c1..5ee214d56 100644 --- a/docs/docs/Usage and maintenance/Wifi/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)](<../Usage and maintenance/Wifi/on-the-go-wifi-adding>) +* 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 @@ -45,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. From 5820dca463ab3ad0edbdcb1256dacaa361012d69 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 19:14:54 -0400 Subject: [PATCH 36/54] more ie/eg --- docs/docs/Build Your Rig/step-4-watching-log.md | 4 ++-- docs/docs/Gear Up/hardware-overview.md | 2 +- .../Give Back-Pay It Forward/data-commons-data-donation.md | 2 +- docs/docs/Resources/switching-between-DIY-systems.md | 4 ++-- 4 files changed, 6 insertions(+), 6 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 140e14f68..d9ed55b2e 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 - 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](<../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#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. @@ -146,4 +146,4 @@ These logs and other files are things you may frequently access. There are short 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. \ No newline at end of file +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/Gear Up/hardware-overview.md b/docs/docs/Gear Up/hardware-overview.md index fabd1317e..2f91c9ccb 100644 --- a/docs/docs/Gear Up/hardware-overview.md +++ b/docs/docs/Gear Up/hardware-overview.md @@ -6,7 +6,7 @@ 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. 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/Resources/switching-between-DIY-systems.md b/docs/docs/Resources/switching-between-DIY-systems.md index 1eda14fcb..b8136537e 100644 --- a/docs/docs/Resources/switching-between-DIY-systems.md +++ b/docs/docs/Resources/switching-between-DIY-systems.md @@ -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>) (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](<../Customize-Iterate/ifttt-integration>). +* 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 @@ -115,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. From ec20ef99462646ee054ccc2da4de565aba653f4e Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 19:15:41 -0400 Subject: [PATCH 37/54] minor clarifications to autosens section; move one warning to oref1 section --- docs/docs/Customize-Iterate/oref1.md | 3 +++ docs/docs/How it works/autosens.md | 22 ++++++++++++---------- 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/docs/Customize-Iterate/oref1.md b/docs/docs/Customize-Iterate/oref1.md index 9baca694f..578e10941 100644 --- a/docs/docs/Customize-Iterate/oref1.md +++ b/docs/docs/Customize-Iterate/oref1.md @@ -18,6 +18,9 @@ NOTE OF CAUTION: * 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. + * 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: diff --git a/docs/docs/How it works/autosens.md b/docs/docs/How it works/autosens.md index 0a720142c..973c3697e 100644 --- a/docs/docs/How it works/autosens.md +++ b/docs/docs/How it works/autosens.md @@ -1,7 +1,14 @@ # 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. +## Autosens vs Autotune + +Autosens looks at the last 8 and 24 hours to estimate how sensitive to insulin you currently are. It 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. + +Autosens does not change your basal profile or carb ratios like Autotune does. Autotune is saying things like "you need more basal insulin in the evening" or "you need less insulin for meals." Autosens is saying, instead, things like "and TODAY you are a bit more resistant." + +## 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: ****************** @@ -42,7 +49,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 +59,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 +69,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. From 5f6b1ec75257d2579be73835a64949014e50145a Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 19:16:50 -0400 Subject: [PATCH 38/54] minor organization edits Nightscout section --- .../nightscout-setup.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) 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 56793e2f1..95926ea50 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 @@ -241,7 +241,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 @@ -349,15 +350,10 @@ Other notes: ![Deploy branch](../Images/nightscout/deploy_branch.jpg) -## Nightscout Troubleshooting and FAQ -### It's not working - I'm missing data in Nightscout? +## Understanding and 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](<../Customize-Iterate/offline-looping-and-monitoring#note-about-recovery-from-camping-mode-offline-mode-for-medtronic-cgm-users>). - -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. - -### 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.)_ @@ -411,6 +407,9 @@ minutes: Enacted, Looping, Waiting, and Warning: * 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. + +## Nightscout troubleshooting + ### 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: @@ -421,3 +420,8 @@ You probably somehow got a future-dated treatment. One possible reason is a cloc * 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) +### It's not working - I'm missing data in Nightscout? + +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>). + +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. From 4f893f58e0fe003e02b0bb799112f80cc6fc78c8 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 19:27:40 -0400 Subject: [PATCH 39/54] minor organizational changes to oref1 section --- docs/docs/Customize-Iterate/oref1.md | 81 +++++++++++++++------------- 1 file changed, 45 insertions(+), 36 deletions(-) diff --git a/docs/docs/Customize-Iterate/oref1.md b/docs/docs/Customize-Iterate/oref1.md index 578e10941..3988a2f27 100644 --- a/docs/docs/Customize-Iterate/oref1.md +++ b/docs/docs/Customize-Iterate/oref1.md @@ -1,34 +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](<../While You Wait For Gear/collect-data-and-prepare#easy-bolus-button>)) and know how to deliver boluses without using the bolus wizard. -* 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. - -## 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. 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. - -* 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) @@ -55,25 +27,62 @@ 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](<../Usage and maintenance/preferences-and-safety-settings#advanced-oref1-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 From acac894227ed69d6a5a9251e8a6ff76714dae716 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 20:42:41 -0400 Subject: [PATCH 40/54] fix typo in index --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 7472a9ed4..1b40d966d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -97,7 +97,7 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of How to run oref0-setup.sh again Update your rig in the future Wifi overview - Adding wifi networks to your rig + Adding wifi networks to your rig Bluetooth tethering From 7a6d6e3ab7adcceb5cf48c933f253b80084b9cc0 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 21:18:13 -0400 Subject: [PATCH 41/54] separate "how to run autotune" from "how to understand autotune" a bit more cleanly; include info about how to update your settings where people will hopefully see it --- docs/docs/How it works/autosens.md | 14 +- docs/docs/How it works/autotune.md | 404 ++---------------- .../How it works/understanding-autotune.md | 40 -- .../optimize-your-settings.md | 3 + .../Usage and maintenance/running-autotune.md | 359 ++++++++++++++++ docs/index.rst | 6 +- 6 files changed, 403 insertions(+), 423 deletions(-) delete mode 100644 docs/docs/How it works/understanding-autotune.md create mode 100644 docs/docs/Usage and maintenance/running-autotune.md diff --git a/docs/docs/How it works/autosens.md b/docs/docs/How it works/autosens.md index 973c3697e..ed43dd61e 100644 --- a/docs/docs/How it works/autosens.md +++ b/docs/docs/How it works/autosens.md @@ -2,16 +2,19 @@ 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. -## Autosens vs Autotune +## The difference between autotune and autosens: -Autosens looks at the last 8 and 24 hours to estimate how sensitive to insulin you currently are. It 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. +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 does not change your basal profile or carb ratios like Autotune does. Autotune is saying things like "you need more basal insulin in the evening" or "you need less insulin for meals." Autosens is saying, instead, things like "and TODAY you are a bit more resistant." +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 @@ -30,7 +33,8 @@ 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). diff --git a/docs/docs/How it works/autotune.md b/docs/docs/How it works/autotune.md index 58a2520cf..768154b85 100644 --- a/docs/docs/How it works/autotune.md +++ b/docs/docs/How it works/autotune.md @@ -2,65 +2,19 @@ Autotune is a tool to help calculate potential adjustments to ISF, carb ratio, and basal rates. -## AutotuneWeb: the easiest way to run Autotune +This page describes how Autotune works. For information on how to run it, please see [Running autotune](<../Usage and maintenance/running-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 difference between autotune and autosens -![Example screenshot from AutotuneWeb](../Images/Example_AutotuneWeb.png) +[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. 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/) -### 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.)* - -![Profile page of AutotuneWeb](../Images/AutotuneWeb_ProfileStep.jpeg) - -When you get your email (note it may take 20 minutes), it will reference your NS URL at the top of the page and the date range you ran it on. The text will also tell you whether you ran with UAM on for basals. - -On the left, you'll see your starting values from your current NS profile; on the right is the tuned recommendation from Autotune. - -![Top results from AutotuneWeb](../Images/AutotuneWeb_Results_1.png) - -Below the ISF and carb ratio, you'll see the basal report. -* Suggestions higlighted in yellow indicate a suggested change of at least 10%, and red indicates a change of +20% or -30% (the standard limits imposed by Autotune). Please always take care when adopting any changes suggested by Autotune, but especially for these larger highlighted changes. - -* The green & red blocks next to each basal suggestion indicate how many days the Autotune algorithm used actual BG data to produce the suggestion (green) and how many days it averaged the surrounding hours due to the data for that hour being dominated by other factors such as carb absorption. This is currently an experimental new feature to try to give an indication of how much trust to place in each suggestion. - -![Example basal results from AutotuneWeb](../Images/AutotuneWeb_Results2.png) - -![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](<../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](<../How it works/autotune#phase-c-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](<../How it works/autotune#why-isn-t-it-working-at-all>) that might contribute to flukey data. - -## Other sections on this page - -* Background in plain language on [how Autotune works](<../How it works/autotune#how-autotune-works>) -* The [difference between Autotune and "autosens"](<../How it works/autotune#the-difference-between-autotune-and-autosens>) (aka, [autosensitivity](<../How it works/autosens>)) -* Different ways to use Autotune - * Run it with [AutotuneWeb](https://autotuneweb.azurewebsites.net/) - * [Phase A](<../How it works/autotune#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](<../How it works/autotune#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](<../How it works/autotune#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. +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. ## 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) -
+### 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 @@ -69,350 +23,50 @@ There are two key pieces: oref0-autotune-prep and oref0-autotune-core. (For more * 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) -
+### 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.* - -## 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 - -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 -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 - -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. - -* Run this command to create a `newdirectory` and copy over the profile and pump settings files: -``` -mkdir -p ~/newdirectory/settings && cp ~/myopenaps/settings/profile.json ~/newdirectory/settings/autotune.json && cp ~/myopenaps/settings/pumpprofile.json ~/newdirectory/settings/pumpprofile.json -``` - -* Then, run Autotune manually, pointing to the new directory: - -``` -oref0-autotune --dir=~/newdirectory --ns-host=https://mynightscout.azurewebsites.net --start-date=YYYY-MM-DD -``` - * obviously, sub in your NS url and the start date you want to start with - * If you change your pump settings, you will need to re-copy your pump settings back into `newdirectory` - -**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 - -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. - -#### 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) -
- -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) +* 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. -* 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 - -**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>) - -**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. - -**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** -* (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 (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 1a: Run via a cloud-based virtual machine** - -
- Click here to expand the instructions for building via a cloud-based virtual machine: -
- - * To run a Linux VM on a cloud server, free options include [AWS](https://aws.amazon.com/free/) (free for 1 year) and [Google Cloud](https://cloud.google.com/free/) (free trial for a year; about $5/mo after that). If you're willing to pay up front, Digital Ocean is $5/mo and very fast to set up. AWS may take a day to spin up your account, so if you're in a hurry, one of the others might be a better option. - * 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 (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` - * Please note that on Google Cloud Shell, the terminal becomes inactive by default after 30 minutes inactivity, and you need to repeat the above each time you (re)start a new terminal instance. - * Now move to step 2. -
-
- - **Step 1b: Run via a Windows-based virtual machine** +*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.* -
- Click here to expand the instructions for building via a Windows-based virtual machine: -
- - * An easy way to start is the [VirtualBox](https://www.virtualbox.org/wiki/Downloads) as VM and Ubuntu as Linux OS. Step-by-step setup instructions can be found here: https://www.youtube.com/watch?v=ncA85gRAJxk. However **skip** the instructions for downloading Ubuntu (time stamp 1:15 to 2:12) because those instructions are now outdated. Download the correct 32 bit version from this link: http://releases.ubuntu.com/17.04/ubuntu-17.04-desktop-i386.iso and then go back to the Youtube video to follow the setup instructions for installing Ubuntu on VirtualBox. If you experience problems with this version 17.04 of Ubuntu you can try the LTS version of Ubuntu, which has worked for some. Here is the link for Ubuntu LTS: https://www.ubuntu.com/download/desktop/thank-you?version=16.04.3&architecture=amd64. After downloading the LTS version go back to the Youtube video to follow the setup instructions for installing Ubuntu on VirtualBox. - * 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`. - * 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. -
-
- -**Step 1c: Prep your 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 [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)"` - -Mac install commands: - - * 1.) Install Homebrew: `/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"` - * 2.) Install Coreutils: `brew install coreutils` - * 3.) Install Node for (NPM): `brew install node` - * 4.) Install JQ from Homebrew: `brew install jq` - -
-
- - **Step 1d: 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): -
- - * You must be running Windows 10 on your computer to use this option. The Windows Subsystem for Linux (WSL) is a Windows 10 feature that enables you to run native Linux command-line tools directly on Windows, alongside your traditional Windows desktop and modern store apps. - * Open PowerShell as Administrator. To open an elevated PowerShell prompt, in the taskbar search, type powershell. The result "Windows PowerShell" appears on the top. Right-click on "Windows PowerShell" and select Run as Administrator. The User Access Control (UAC) prompt will ask you for your consent. - * In PowerShell run `Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux`. - * This instruction is for Windows 10 build 16215 or later. To check your build of Windows 10 navigate to Settings > System > About. Look for the OS Build field. It will need to say 16215 or later for these next instructions to work. If you have a Windows 10 build earlier than 16215 follow these instructions to install Linux: https://docs.microsoft.com/en-us/windows/wsl/install-win10#for-anniversary-update-and-creators-update-install-using-lxrun. Only follow this link if your build of Windows 10 is earlier than 16215. - * Open the Microsoft Store and install Ubuntu using this link: https://www.microsoft.com/en-us/store/p/ubuntu/9nblggh4msv6?rtc=1. On this Ubuntu page click on the blue button that says "Get the app". The Microsoft Store will open in a new window, showing the Ubuntu app. Click on the blue button that says "Get". Your computer will start to install the Ubuntu app ("Installing, this may take a few minutes..."). When done it will say, "Installation successful!". - * You will be asked to "create a default UNIX user account". Chose whatever name works for you. It doesn't need to match your Windows username. Enter the name at the prompt, "Enter new UNIX username:". - * You will be asked for a password: "Enter new UNIX password:". Your cursor will not move when you type the password you choose. You'll then be asked to "Retype new UNIX password:". Make sure you enter the password exactly as you just typed it. Again, your cursor will not move as you retype the password. - * You will now be at a Linux prompt (like the old DOS prompt). It will look something like this, in a green font: "username@DGdesktop: $ _". - * Make sure you (that is, WSL/Ubuntu) are using the same timezone as your pump. You can change timezone using `sudo dpkg-reconfigure tzdata`. WSL/Ubuntu may respond to this command with "[sudo] password for username". If so enter your password from above. Follow the prompts to select your timezone. You likely will not be able to use your mouse to navigate on the timezone screens. Use your keyboard's arrow keys to navigate and the Enter key to select. - * If your WSL 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`. - * This step could take 10-15 minutes. Type: `sudo curl -s https://raw.githubusercontent.com/openaps/docs/master/scripts/quick-packages.sh | bash -`. If the install was successful, one of the last lines will say something like: `Successfully installed future-0.16.0 openaps-contrib-0.0.15 parsedatetime-2.4 recurrent-0.2.5` (although the version number may have been incremented). - * Install the Linux command "bc" by typing: `sudo apt-get install bc`. - -
-
- -**Step 2: Install oref0** -* Install the latest version of oref0: - -``` -npm list -g oref0 | egrep oref0@0.5.[5-9] || (echo Installing latest oref0 package && sudo npm install -g oref0) -``` - -* If you need the dev version of oref0 (for example, to run autotune with AndroidAPS as of August 2018): - -``` -cd ~/src && git clone git://github.com/openaps/oref0.git || (cd oref0 && git checkout dev && git pull) -cd ~/src/oref0 && npm run global-install -``` - -**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: - * Be sure that all of the } lines in basalprofile have a comma after them, *except* the last one. - * You need to use a 0 before any entries with a decimal point, such as a basal rate of `0.35`; without the 0 before the decimal point, your autotune will have an error. - * If you don't like editing in the terminal, you can edit the profile files in a text editor. However be aware that TextEdit will replace normal quotes (") with curly quotes (“) if you have "smartquotes" enabled in preferences, and this difference will make autotune fail. You can download BBEdit (https://www.barebones.com/products/bbedit/) if you want a simple text editor that works well. The trial version is sufficient, you won't be using advanced featues. - -Every comma, quote mark, and bracket matter on this file, so please double-check carefully. - -* Make sure to adjust these settings to match yours: - * dia - Duration of Insulin Action (DIA), in hours (e.g., 4.5, or 3). Usually determined by the type of insulin and its effectiveness on you. - * basal profile - you need at least one basal rate in here. You can create multiple of these for all of your basal rates, which will give you an easier visual comparing your current basals to what autotune recommends (see visual example), but at a minimum you just need one here for autotune to run. But we recommend putting all or most of your basals in, in order for autotune to appropriately cap at the safety limits (and compare to 20% above or below your existing basals). If you do not put your full basal profile in, it will not compare to those with the safety cap because it does not know about it. - * "sensitivity" should be your iSF - in mg/dL/U (if using mmol/L/U multiply by 18) - * "carb_ratio" at the end should be your carb ratio - -* Make sure to exit the profile.json when done editing this file - Control-X and hit yes to save. - -``` -{ - "min_5m_carbimpact": 8.0, - "dia": your_dia, - "basalprofile": [ - { - "start": "00:00:00", - "minutes": 0, - "rate": your_basal - }, - { - "start": "08:00:00", - "minutes": 480, - "rate": your_basal - }, - { - "start": "13:00:00", - "minutes": 780, - "rate": your_basal - }, - { - "start": "21:00:00", - "minutes": 1260, - "rate": your_basal - } - ], - "isfProfile": { - "sensitivities": [ - { - "i": 0, - "start": "00:00:00", - "sensitivity": your_isf, - "offset": 0, - "x": 0, - "endOffset": 1440 - } - ] - }, - "carb_ratio": your_ic_ratio, - "autosens_max": 1.2, - "autosens_min": 0.7 -} -``` - -* D. Verify your profile.json is valid json by running `jq . profile.json` - if it prints a colorful version of your profile.json, you're good to proceed. If not, go back and edit your profile.json to fix the error. -* 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** -* Run -``` -oref0-autotune --dir=~/myopenaps --ns-host=https://mynightscout.herokuapp.com --start-date=YYYY-MM-DD -``` -* ^ Sub in your Nightscout URL. Note that you mustn't use the trailing / on the Nightscout URL or that will cause an error. -* Start with one day to confirm that it works, first. Then run it for one week, and then one month. Compare results and see if the numbers are consistent or changing, and see how that aligns with your gut feeling on whether your basals, ISF, and carb ratio was correct. -* If you want to run dates in the past, add the following: --end-date=YYYY-MM-DD (otherwise, it will just default to ending yesterday). The start date should be the older date, the end date is the more recent date. -* 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. - -#### Optional configurations - -* 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 +## Understanding autotune output -#### Re-Running Autotune +### Safety reminders -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>) +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. -To subsequently re-run Autotune at a later time: -* Open Ubuntu/your machine of choice and login if necessary -* At command prompt which will start with your username: `cd ~/myopenaps/settings` -* Then: `nano profile.json` (this gets you to the pump settings section) - * Now edit your settings (using up / down arrows and backspace) – CR; ISF; basals etc. - * Press Control-X (to save your new settings) - * Press Y (to confirm save new settings) -* Now should see command prompt which will start with your user name again. -* Now follow steps D, E, F from the link above ie: - * `jq . profile.json `(if it prints a colourful version of your profile.json, you’re good to proceed) - * `cp profile.json pumpprofile.json` - * `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` +### Example output from autotune -#### Why Isn't It Working At All? +![Example output from autotune](https://diyps.org/wp-content/uploads/2017/01/OpenAPS-autotune-example-by-@DanaMLewis.png) -(First - breathe, and have patience!) Here are some things to check: +### What you'll see in autotune inputs and outputs -If you get the error `ERROR: API_SECRET is not set when calling oref0-autotune.sh` and autotune won't run, try this (note: as of oref 0.5.5, this error has been downgraded to a warning as this will only prevent autotune from running if you have "locked down" your NS to prevent anonymous read access): +* 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. -1. Log into your VM -2. At the command prompt, type `cd /etc/` and hit enter -2. Type `sudo nano environment` and hit enter -3. You are now editing the `environment` file. Add a new line to the file that says: `API_SECRET=yourAPIsecret` (Note - replace "yourAPIsecret" with your own) -4. Hit CTRL-O and enter to save the changes to the file -5. Hit CTRL-X and enter to exit the file and go back to the command prompt -6. At the command prompt, type `export API_SECRET=yourAPIsecret` (Note - replace "yourAPIsecret" with your own) +### If you are DIY closed looping and looking at autotune: -To test this fix, type `echo $API_SECRET` and hit enter. If this returns the API Secret that you set in the `environment` file, then it should work for you to run autotune. +#### With carbs logged in Nightscout +...you can look at everything that autotune outputs -Other things to check: +#### 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 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. -* 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. -     - "start" time stamps must have the format "HH:MM:SS". "HH:MM" (e.g. "00:00" instead of "00:00:00") gives erroneous calculations such as "-Infinity" or "Nan" for the ISF and CR values. This results in the ISF & Carb ratio values being unchanged. - Example output (console): - ```oldCR: 9 fullNewCR: NaN newCR: NaN - p50deviation: -0.76 p50BGI 0 p50ratios: -Infinity Old ISF: 44 fullNewISF: -Infinity adjustedISF: 44 newISF: 44 - ``` - - Telltale sign is the input and output values for ISF and carb ratio remain unchanged: - ```Parameter | Pump | Autotune - ------------------------------------- - ISF [mg/dL/U] | 44.000 | 44.000 - Carb Ratio[g/U]| 9.000 | 9.000 - Basals [U/hr] | - | - ``` - -* Also check your pumpprofile.json and autotune.json - if it worked once or twice but then stopped working, it may have a bad file copy. If needed, follow Steps 3-E and 3-F again to re-copy a good profile.json to pumpprofile.json and autotune.json again. -* If VM is already set up, and you are returning to your VM for another session of autotune, double-check that your VM timezone matches your pump: `sudo dpkg-reconfigure tzdata` -* Invalid calculations may be due to the locale settings of your VM (correct settings are `en_US.utf-8` or another locale that uses `.` as the decimal separator). An easy way to overcome such a problem is to add `env LANG=en_US.UTF-8` in front of your command for running autotune, it should look like this: `env LANG=en_US.UTF-8 oref0-autotune --dir=~/myopenaps --ns-host=https://mynightscout.azurewebsites.net --start-date=YYYY-MM-DD` -* Did you turn on Nightscout authentication with the setting `AUTH_DEFAULT_ROLES`? Currently Autotune will only work with the `readable` setting. See [issue #397](https://github.com/openaps/oref0/issues/397) in Github. -* 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>). +### If you are not DIY closed looping and are looking at autotune: -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). +#### With all boluses and carb treatments (even rescue, or low carbs) in Nightscout +...you can look at everything that autotune outputs -(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).) +#### Without boluses and carb treatments in Nightscout +...don't use autotune until you log this data. -#### Yay, It Worked! This is Cool! +#### If you don't have Nightscout -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>). +...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/How it works/understanding-autotune.md b/docs/docs/How it works/understanding-autotune.md deleted file mode 100644 index 1ade3940b..000000000 --- a/docs/docs/How it works/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 (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. 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/Usage and maintenance/optimize-your-settings.md b/docs/docs/Usage and maintenance/optimize-your-settings.md index 035d14078..978662f83 100644 --- a/docs/docs/Usage and maintenance/optimize-your-settings.md +++ b/docs/docs/Usage and maintenance/optimize-your-settings.md @@ -34,4 +34,7 @@ Human behaviors set aside, if you are still seeing hills and valleys in your BG * 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](<../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. diff --git a/docs/docs/Usage and maintenance/running-autotune.md b/docs/docs/Usage and maintenance/running-autotune.md new file mode 100644 index 000000000..a5f6daefb --- /dev/null +++ b/docs/docs/Usage and maintenance/running-autotune.md @@ -0,0 +1,359 @@ +# Running Autotune + +There are several ways to run Autotune, depending on whether you are looping and whether you want to use the results automatically. + +## 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/). This is recommended and easiest for non-OpenAPS users. + +![Example screenshot from AutotuneWeb](../Images/Example_AutotuneWeb.png) + +### What to expect when using AutotuneWeb + +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.)* + +![Profile page of AutotuneWeb](../Images/AutotuneWeb_ProfileStep.jpeg) + +When you get your email (note it may take 20 minutes), it will reference your NS URL at the top of the page and the date range you ran it on. The text will also tell you whether you ran with UAM on for basals. + +On the left, you'll see your starting values from your current NS profile; on the right is the tuned recommendation from Autotune. + +![Top results from AutotuneWeb](../Images/AutotuneWeb_Results_1.png) + +Below the ISF and carb ratio, you'll see the basal report. +* Suggestions higlighted in yellow indicate a suggested change of at least 10%, and red indicates a change of +20% or -30% (the standard limits imposed by Autotune). Please always take care when adopting any changes suggested by Autotune, but especially for these larger highlighted changes. + +* The green & red blocks next to each basal suggestion indicate how many days the Autotune algorithm used actual BG data to produce the suggestion (green) and how many days it averaged the surrounding hours due to the data for that hour being dominated by other factors such as carb absorption. This is currently an experimental new feature to try to give an indication of how much trust to place in each suggestion. + +![Example basal results from AutotuneWeb](../Images/AutotuneWeb_Results2.png) + +![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](<../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](<../How it works/autotune#phase-c-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](<../How it works/autotune#why-isn-t-it-working-at-all>) that might contribute to flukey data. + +## 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 + +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 + +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. + +* Run this command to create a `newdirectory` and copy over the profile and pump settings files: +``` +mkdir -p ~/newdirectory/settings && cp ~/myopenaps/settings/profile.json ~/newdirectory/settings/autotune.json && cp ~/myopenaps/settings/pumpprofile.json ~/newdirectory/settings/pumpprofile.json +``` + +* Then, run Autotune manually, pointing to the new directory: + +``` +oref0-autotune --dir=~/newdirectory --ns-host=https://mynightscout.azurewebsites.net --start-date=YYYY-MM-DD +``` + * obviously, sub in your NS url and the start date you want to start with + * If you change your pump settings, you will need to re-copy your pump settings back into `newdirectory` + +**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. + +## 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. + +**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: + +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) + +* 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. + +## 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. + +*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>) + +**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. + +**Feedback**: Please note 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). + +### 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 (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) + +#### Option A: Run via a cloud-based virtual machine + +
+ Click here to expand the instructions for building via a cloud-based virtual machine: +
+ + * To run a Linux VM on a cloud server, free options include [AWS](https://aws.amazon.com/free/) (free for 1 year) and [Google Cloud](https://cloud.google.com/free/) (free trial for a year; about $5/mo after that). If you're willing to pay up front, Digital Ocean is $5/mo and very fast to set up. AWS may take a day to spin up your account, so if you're in a hurry, one of the others might be a better option. + * 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 (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` + * Please note that on Google Cloud Shell, the terminal becomes inactive by default after 30 minutes inactivity, and you need to repeat the above each time you (re)start a new terminal instance. + * Now move to step 2. +
+
+ +#### Option B: Run via a Windows-based virtual machine + +
+ Click here to expand the instructions for building via a Windows-based virtual machine: +
+ + * An easy way to start is the [VirtualBox](https://www.virtualbox.org/wiki/Downloads) as VM and Ubuntu as Linux OS. Step-by-step setup instructions can be found here: https://www.youtube.com/watch?v=ncA85gRAJxk. However **skip** the instructions for downloading Ubuntu (time stamp 1:15 to 2:12) because those instructions are now outdated. Download the correct 32 bit version from this link: http://releases.ubuntu.com/17.04/ubuntu-17.04-desktop-i386.iso and then go back to the Youtube video to follow the setup instructions for installing Ubuntu on VirtualBox. If you experience problems with this version 17.04 of Ubuntu you can try the LTS version of Ubuntu, which has worked for some. Here is the link for Ubuntu LTS: https://www.ubuntu.com/download/desktop/thank-you?version=16.04.3&architecture=amd64. After downloading the LTS version go back to the Youtube video to follow the setup instructions for installing Ubuntu on VirtualBox. + * 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`. + * 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. +
+
+ +#### 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 [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)"` + +Mac install commands: + + * 1.) Install Homebrew: `/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"` + * 2.) Install Coreutils: `brew install coreutils` + * 3.) Install Node for (NPM): `brew install node` + * 4.) Install JQ from Homebrew: `brew install jq` + +
+
+ +#### 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): +
+ + * You must be running Windows 10 on your computer to use this option. The Windows Subsystem for Linux (WSL) is a Windows 10 feature that enables you to run native Linux command-line tools directly on Windows, alongside your traditional Windows desktop and modern store apps. + * Open PowerShell as Administrator. To open an elevated PowerShell prompt, in the taskbar search, type powershell. The result "Windows PowerShell" appears on the top. Right-click on "Windows PowerShell" and select Run as Administrator. The User Access Control (UAC) prompt will ask you for your consent. + * In PowerShell run `Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux`. + * This instruction is for Windows 10 build 16215 or later. To check your build of Windows 10 navigate to Settings > System > About. Look for the OS Build field. It will need to say 16215 or later for these next instructions to work. If you have a Windows 10 build earlier than 16215 follow these instructions to install Linux: https://docs.microsoft.com/en-us/windows/wsl/install-win10#for-anniversary-update-and-creators-update-install-using-lxrun. Only follow this link if your build of Windows 10 is earlier than 16215. + * Open the Microsoft Store and install Ubuntu using this link: https://www.microsoft.com/en-us/store/p/ubuntu/9nblggh4msv6?rtc=1. On this Ubuntu page click on the blue button that says "Get the app". The Microsoft Store will open in a new window, showing the Ubuntu app. Click on the blue button that says "Get". Your computer will start to install the Ubuntu app ("Installing, this may take a few minutes..."). When done it will say, "Installation successful!". + * You will be asked to "create a default UNIX user account". Chose whatever name works for you. It doesn't need to match your Windows username. Enter the name at the prompt, "Enter new UNIX username:". + * You will be asked for a password: "Enter new UNIX password:". Your cursor will not move when you type the password you choose. You'll then be asked to "Retype new UNIX password:". Make sure you enter the password exactly as you just typed it. Again, your cursor will not move as you retype the password. + * You will now be at a Linux prompt (like the old DOS prompt). It will look something like this, in a green font: "username@DGdesktop: $ _". + * Make sure you (that is, WSL/Ubuntu) are using the same timezone as your pump. You can change timezone using `sudo dpkg-reconfigure tzdata`. WSL/Ubuntu may respond to this command with "[sudo] password for username". If so enter your password from above. Follow the prompts to select your timezone. You likely will not be able to use your mouse to navigate on the timezone screens. Use your keyboard's arrow keys to navigate and the Enter key to select. + * If your WSL 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`. + * This step could take 10-15 minutes. Type: `sudo curl -s https://raw.githubusercontent.com/openaps/docs/master/scripts/quick-packages.sh | bash -`. If the install was successful, one of the last lines will say something like: `Successfully installed future-0.16.0 openaps-contrib-0.0.15 parsedatetime-2.4 recurrent-0.2.5` (although the version number may have been incremented). + * Install the Linux command "bc" by typing: `sudo apt-get install bc`. + +
+
+ +### Step 2: Install oref0 + +* Install the latest version of oref0: + +``` +npm list -g oref0 | egrep oref0@0.5.[5-9] || (echo Installing latest oref0 package && sudo npm install -g oref0) +``` + +* If you need the dev version of oref0 (for example, to run autotune with AndroidAPS as of August 2018): + +``` +cd ~/src && git clone git://github.com/openaps/oref0.git || (cd oref0 && git checkout dev && git pull) +cd ~/src/oref0 && npm run global-install +``` + +### 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: + * Be sure that all of the } lines in basalprofile have a comma after them, *except* the last one. + * You need to use a 0 before any entries with a decimal point, such as a basal rate of `0.35`; without the 0 before the decimal point, your autotune will have an error. + * If you don't like editing in the terminal, you can edit the profile files in a text editor. However be aware that TextEdit will replace normal quotes (") with curly quotes (“) if you have "smartquotes" enabled in preferences, and this difference will make autotune fail. You can download BBEdit (https://www.barebones.com/products/bbedit/) if you want a simple text editor that works well. The trial version is sufficient, you won't be using advanced featues. + +Every comma, quote mark, and bracket matter on this file, so please double-check carefully. + +* Make sure to adjust these settings to match yours: + * dia - Duration of Insulin Action (DIA), in hours (e.g., 4.5, or 3). Usually determined by the type of insulin and its effectiveness on you. + * basal profile - you need at least one basal rate in here. You can create multiple of these for all of your basal rates, which will give you an easier visual comparing your current basals to what autotune recommends (see visual example), but at a minimum you just need one here for autotune to run. But we recommend putting all or most of your basals in, in order for autotune to appropriately cap at the safety limits (and compare to 20% above or below your existing basals). If you do not put your full basal profile in, it will not compare to those with the safety cap because it does not know about it. + * "sensitivity" should be your iSF - in mg/dL/U (if using mmol/L/U multiply by 18) + * "carb_ratio" at the end should be your carb ratio + +* Make sure to exit the profile.json when done editing this file - Control-X and hit yes to save. + +``` +{ + "min_5m_carbimpact": 8.0, + "dia": your_dia, + "basalprofile": [ + { + "start": "00:00:00", + "minutes": 0, + "rate": your_basal + }, + { + "start": "08:00:00", + "minutes": 480, + "rate": your_basal + }, + { + "start": "13:00:00", + "minutes": 780, + "rate": your_basal + }, + { + "start": "21:00:00", + "minutes": 1260, + "rate": your_basal + } + ], + "isfProfile": { + "sensitivities": [ + { + "i": 0, + "start": "00:00:00", + "sensitivity": your_isf, + "offset": 0, + "x": 0, + "endOffset": 1440 + } + ] + }, + "carb_ratio": your_ic_ratio, + "autosens_max": 1.2, + "autosens_min": 0.7 +} +``` + +* D. Verify your profile.json is valid json by running `jq . profile.json` - if it prints a colorful version of your profile.json, you're good to proceed. If not, go back and edit your profile.json to fix the error. +* 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 +* Run +``` +oref0-autotune --dir=~/myopenaps --ns-host=https://mynightscout.herokuapp.com --start-date=YYYY-MM-DD +``` +* ^ Sub in your Nightscout URL. Note that you mustn't use the trailing / on the Nightscout URL or that will cause an error. +* Start with one day to confirm that it works, first. Then run it for one week, and then one month. Compare results and see if the numbers are consistent or changing, and see how that aligns with your gut feeling on whether your basals, ISF, and carb ratio was correct. +* If you want to run dates in the past, add the following: --end-date=YYYY-MM-DD (otherwise, it will just default to ending yesterday). The start date should be the older date, the end date is the more recent date. +* 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. + +### Optional configurations + +* 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 + +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 +* At command prompt which will start with your username: `cd ~/myopenaps/settings` +* Then: `nano profile.json` (this gets you to the pump settings section) + * Now edit your settings (using up / down arrows and backspace) – CR; ISF; basals etc. + * Press Control-X (to save your new settings) + * Press Y (to confirm save new settings) +* Now should see command prompt which will start with your user name again. +* Now follow steps D, E, F from the link above ie: + * `jq . profile.json `(if it prints a colourful version of your profile.json, you’re good to proceed) + * `cp profile.json pumpprofile.json` + * `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? + +(First - breathe, and have patience!) Here are some things to check: + +If you get the error `ERROR: API_SECRET is not set when calling oref0-autotune.sh` and autotune won't run, try this (note: as of oref 0.5.5, this error has been downgraded to a warning as this will only prevent autotune from running if you have "locked down" your NS to prevent anonymous read access): + +1. Log into your VM +2. At the command prompt, type `cd /etc/` and hit enter +2. Type `sudo nano environment` and hit enter +3. You are now editing the `environment` file. Add a new line to the file that says: `API_SECRET=yourAPIsecret` (Note - replace "yourAPIsecret" with your own) +4. Hit CTRL-O and enter to save the changes to the file +5. Hit CTRL-X and enter to exit the file and go back to the command prompt +6. At the command prompt, type `export API_SECRET=yourAPIsecret` (Note - replace "yourAPIsecret" with your own) + +To test this fix, type `echo $API_SECRET` and hit enter. If this returns the API Secret that you set in the `environment` file, then it should work for you to run autotune. + +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. +* 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. +     - "start" time stamps must have the format "HH:MM:SS". "HH:MM" (e.g. "00:00" instead of "00:00:00") gives erroneous calculations such as "-Infinity" or "Nan" for the ISF and CR values. This results in the ISF & Carb ratio values being unchanged. + Example output (console): + ```oldCR: 9 fullNewCR: NaN newCR: NaN + p50deviation: -0.76 p50BGI 0 p50ratios: -Infinity Old ISF: 44 fullNewISF: -Infinity adjustedISF: 44 newISF: 44 + ``` + + Telltale sign is the input and output values for ISF and carb ratio remain unchanged: + ```Parameter | Pump | Autotune + ------------------------------------- + ISF [mg/dL/U] | 44.000 | 44.000 + Carb Ratio[g/U]| 9.000 | 9.000 + Basals [U/hr] | - | + ``` + +* Also check your pumpprofile.json and autotune.json - if it worked once or twice but then stopped working, it may have a bad file copy. If needed, follow Steps 3-E and 3-F again to re-copy a good profile.json to pumpprofile.json and autotune.json again. +* If VM is already set up, and you are returning to your VM for another session of autotune, double-check that your VM timezone matches your pump: `sudo dpkg-reconfigure tzdata` +* Invalid calculations may be due to the locale settings of your VM (correct settings are `en_US.utf-8` or another locale that uses `.` as the decimal separator). An easy way to overcome such a problem is to add `env LANG=en_US.UTF-8` in front of your command for running autotune, it should look like this: `env LANG=en_US.UTF-8 oref0-autotune --dir=~/myopenaps --ns-host=https://mynightscout.azurewebsites.net --start-date=YYYY-MM-DD` +* Did you turn on Nightscout authentication with the setting `AUTH_DEFAULT_ROLES`? Currently Autotune will only work with the `readable` setting. See [issue #397](https://github.com/openaps/oref0/issues/397) in Github. +* 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](<../How it works/understanding-autotune>). + +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). + +(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).) + +## Yay, It Worked! This is Cool! + +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>). diff --git a/docs/index.rst b/docs/index.rst index 1b40d966d..4ab3a128d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -79,9 +79,8 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of How OpenAPS makes decisions Insulin on board calculations - Understanding Autotune - Running Autotune - Using Autosens + Understanding Autotune + Understanding Autosens .. toctree:: :maxdepth: 2 @@ -94,6 +93,7 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of 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 From 98445c2fe9cdbdb73308bc2b660299d1d8760e2a Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 21:19:06 -0400 Subject: [PATCH 42/54] one more i.e. that snuck by, and italics I suspect don't improve readability --- docs/docs/Customize-Iterate/oref1.md | 2 +- docs/docs/Usage and maintenance/entering-carbs-bolus.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/Customize-Iterate/oref1.md b/docs/docs/Customize-Iterate/oref1.md index 3988a2f27..5d534ae1d 100644 --- a/docs/docs/Customize-Iterate/oref1.md +++ b/docs/docs/Customize-Iterate/oref1.md @@ -87,7 +87,7 @@ By default, a higher temp target (101 if your target is 100) will disable Super ## 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/Usage and maintenance/entering-carbs-bolus.md b/docs/docs/Usage and maintenance/entering-carbs-bolus.md index 3183f513b..b6b3281d1 100644 --- a/docs/docs/Usage and maintenance/entering-carbs-bolus.md +++ b/docs/docs/Usage and maintenance/entering-carbs-bolus.md @@ -29,7 +29,7 @@ Look at this image for the big picture: * 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. 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 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. +**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 From a8c50be1128a033c6583824c42cac236f61ac898 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 21:29:24 -0400 Subject: [PATCH 43/54] also reference linux guide in installation overview --- docs/docs/Build Your Rig/install-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/Build Your Rig/install-overview.md b/docs/docs/Build Your Rig/install-overview.md index 7750542c0..b4318856b 100644 --- a/docs/docs/Build Your Rig/install-overview.md +++ b/docs/docs/Build Your Rig/install-overview.md @@ -10,7 +10,7 @@ Getting OpenAPS running on your rig generally takes five steps: 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) +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: From 69797e52f01c0fbfd2963016d0682d67a1456665 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Sun, 8 Sep 2019 21:40:56 -0400 Subject: [PATCH 44/54] fix links thru hardware --- docs/docs/Gear Up/pi-based-rigs.md | 2 +- .../communication-support-channels.md | 2 +- .../how-openaps-works-overview.md | 2 +- .../overview-of-build-process.md | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/Gear Up/pi-based-rigs.md b/docs/docs/Gear Up/pi-based-rigs.md index 2859fa8b7..400cd8ab5 100644 --- a/docs/docs/Gear Up/pi-based-rigs.md +++ b/docs/docs/Gear Up/pi-based-rigs.md @@ -23,7 +23,7 @@ Lipo batteries are typically used to power the rig on the go because they charge 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](<../Usage and maintenance/usability-considerations#improving-the-battery-life-of-your-raspberry-pi>). +**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. diff --git a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md index 6e7af1ba7..6af157ac8 100644 --- a/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md +++ b/docs/docs/Understanding OpenAPS-Overview/communication-support-channels.md @@ -1,6 +1,6 @@ # Where to go for help -First check the [Troubleshooting](../Troubleshooting/index.rst) section for assistance, and try searching within this documentation for the problem you are having (including text of any error message you are seeing). +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). 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/). 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 8a7a264a1..cceba9033 100644 --- a/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md +++ b/docs/docs/Understanding OpenAPS-Overview/how-openaps-works-overview.md @@ -4,7 +4,7 @@ How do you make decisions about your diabetes? You gather data, crunch the numbe A DIY loop is no different. It gathers data from: * [your pump](<../Gear Up/pump>) -* [your CGM](<../Gear Up/cgm>) +* [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) in order to keep or bring your BGs in your target range. 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 b2ae4e746..f9e56aeb0 100644 --- a/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md +++ b/docs/docs/Understanding OpenAPS-Overview/overview-of-build-process.md @@ -4,11 +4,11 @@ The OpenAPS setup process can be broken up into several parts: 1. These can be done in parallel: - A. [Choose and get your hardware.](<../Gear Up/index>) 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. + 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. - B. [Prepare to use OpenAPS.](<../While You Wait For Gear/index>) 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. + 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. -2. [Install OpenAPS on your rig!](<../Build Your Rig/index>) 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. +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. 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. From 00db9e04b8160a8f7a2748568b2a94e870cb5d20 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Tue, 10 Sep 2019 22:09:16 -0400 Subject: [PATCH 45/54] finish fixing links --- .../Build Your Rig/step-2-wifi-dependencies.md | 2 +- .../Build Your Rig/step-5-finishing-setup.md | 2 +- .../offline-looping-and-monitoring.md | 2 +- docs/docs/Customize-Iterate/oref1.md | 4 ++-- .../docs/Customize-Iterate/useful-mobile-apps.md | 2 +- docs/docs/How it works/autotune.md | 2 +- ...nderstanding-insulin-on-board-calculations.md | 2 +- .../Resources/switching-between-DIY-systems.md | 2 +- docs/docs/Resources/technical-resources.md | 2 ++ docs/docs/Troubleshooting/Carelink.md | 2 +- .../General_linux_troubleshooting.md | 4 +++- .../Rig-NS-communications-troubleshooting.md | 2 +- .../Troubleshooting/Wifi-and-hotspot-issues.md | 6 +++--- .../Wifi/bluetooth-tethering-edison.md | 2 +- .../Wifi/understanding-wifi-options.md | 2 +- .../Usage and maintenance/monitoring-OpenAPS.md | 4 ++-- .../Usage and maintenance/running-autotune.md | 10 +++++----- .../usability-considerations.md | 16 ++++++++-------- .../collect-data-and-prepare.md | 2 +- .../docs/While You Wait For Gear/reading-list.md | 2 +- 20 files changed, 38 insertions(+), 34 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 e0330e321..ce5d2fcc8 100644 --- a/docs/docs/Build Your Rig/step-2-wifi-dependencies.md +++ b/docs/docs/Build Your Rig/step-2-wifi-dependencies.md @@ -77,7 +77,7 @@ Now that step 2 is done, the bootstrap script will then continue to run awhile l 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. +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 diff --git a/docs/docs/Build Your Rig/step-5-finishing-setup.md b/docs/docs/Build Your Rig/step-5-finishing-setup.md index 208bfff9c..344ddac47 100644 --- a/docs/docs/Build Your Rig/step-5-finishing-setup.md +++ b/docs/docs/Build Your Rig/step-5-finishing-setup.md @@ -51,7 +51,7 @@ As your time permits, there's still more useful and cool things you can do to ma * 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 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). diff --git a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md index d78298c5a..317a97f0c 100644 --- a/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md +++ b/docs/docs/Customize-Iterate/offline-looping-and-monitoring.md @@ -2,7 +2,7 @@ ## 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. +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. ## Medtronic CGM users Medtronic CGM users can, by default, automatically loop offline because the rig will read CGM data directly from the pump. diff --git a/docs/docs/Customize-Iterate/oref1.md b/docs/docs/Customize-Iterate/oref1.md index 5d534ae1d..813783478 100644 --- a/docs/docs/Customize-Iterate/oref1.md +++ b/docs/docs/Customize-Iterate/oref1.md @@ -16,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](<../docs/Customize-Iterate/ifttt-integration>). +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 ) @@ -68,7 +68,7 @@ Remember that you are choosing to test a still-in-development feature. Do so at * 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](<../Usage and maintenance/preferences-and-safety-settings#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 diff --git a/docs/docs/Customize-Iterate/useful-mobile-apps.md b/docs/docs/Customize-Iterate/useful-mobile-apps.md index c5713ae69..019d600fe 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#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/How it works/autotune.md b/docs/docs/How it works/autotune.md index 768154b85..a9e9150d6 100644 --- a/docs/docs/How it works/autotune.md +++ b/docs/docs/How it works/autotune.md @@ -6,7 +6,7 @@ This page describes how Autotune works. For information on how to run it, please ## 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. 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/) +[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. 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 c1075122e..ef610794e 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 @@ -98,7 +98,7 @@ As mentioned at the top of this page, the next OpenAPS release will have new act 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/switching-between-DIY-systems.md b/docs/docs/Resources/switching-between-DIY-systems.md index b8136537e..f52641dae 100644 --- a/docs/docs/Resources/switching-between-DIY-systems.md +++ b/docs/docs/Resources/switching-between-DIY-systems.md @@ -103,7 +103,7 @@ See [this short list for what to buy for an Edison/Explorer Board OpenAPS rig.]( * 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](<../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](<../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. + * 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. 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/Carelink.md b/docs/docs/Troubleshooting/Carelink.md index 972c846d6..fe46bd17a 100644 --- a/docs/docs/Troubleshooting/Carelink.md +++ b/docs/docs/Troubleshooting/Carelink.md @@ -1,6 +1,6 @@ # 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/index>), 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/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`). diff --git a/docs/docs/Troubleshooting/General_linux_troubleshooting.md b/docs/docs/Troubleshooting/General_linux_troubleshooting.md index a7a51ede2..814301f85 100644 --- a/docs/docs/Troubleshooting/General_linux_troubleshooting.md +++ b/docs/docs/Troubleshooting/General_linux_troubleshooting.md @@ -10,7 +10,7 @@ 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. @@ -24,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 diff --git a/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md b/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md index 4bb36a856..44c7e13cd 100644 --- a/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md +++ b/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md @@ -2,7 +2,7 @@ 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](<../Troubleshooting/rig-ns-communications-troubleshooting#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](<#mlab-maintenance>) for how to check the size of, and compact if needed, your mlab database, which can influence what displays in Nightscout. diff --git a/docs/docs/Troubleshooting/Wifi-and-hotspot-issues.md b/docs/docs/Troubleshooting/Wifi-and-hotspot-issues.md index 2ded10f64..257329d8c 100644 --- a/docs/docs/Troubleshooting/Wifi-and-hotspot-issues.md +++ b/docs/docs/Troubleshooting/Wifi-and-hotspot-issues.md @@ -1,7 +1,7 @@ # 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. +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 @@ -9,7 +9,7 @@ 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. +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``` @@ -24,7 +24,7 @@ You can add a line to your cron that will check to see if `` is av 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: +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/Usage and maintenance/Wifi/bluetooth-tethering-edison.md b/docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md index d1a970746..eb2e34a20 100644 --- a/docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md +++ b/docs/docs/Usage and maintenance/Wifi/bluetooth-tethering-edison.md @@ -74,7 +74,7 @@ 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](<../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. +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. diff --git a/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md b/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md index 5ee214d56..5f5c31763 100644 --- a/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md +++ b/docs/docs/Usage and maintenance/Wifi/understanding-wifi-options.md @@ -11,7 +11,7 @@ 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](<../Customize-Iterate/useful-mobile-apps>) 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. diff --git a/docs/docs/Usage and maintenance/monitoring-OpenAPS.md b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md index 4e0f677e3..285f3b8cf 100644 --- a/docs/docs/Usage and maintenance/monitoring-OpenAPS.md +++ b/docs/docs/Usage and maintenance/monitoring-OpenAPS.md @@ -315,7 +315,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](<../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. +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) @@ -609,7 +609,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](<../Resources/index>) 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/Usage and maintenance/running-autotune.md b/docs/docs/Usage and maintenance/running-autotune.md index a5f6daefb..2369c95af 100644 --- a/docs/docs/Usage and maintenance/running-autotune.md +++ b/docs/docs/Usage and maintenance/running-autotune.md @@ -35,9 +35,9 @@ Below the ISF and carb ratio, you'll see the basal report. 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](<../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](<../How it works/autotune#phase-c-running-autotune-for-suggested-adjustments-without-an-openaps-rig>). +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](<../How it works/autotune#why-isn-t-it-working-at-all>) that might contribute to flukey data. +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. ## Running Autotune manually in OpenAPS @@ -72,7 +72,7 @@ oref0-autotune --dir=~/newdirectory --ns-host=https://mynightscout.azurewebsites ## 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 [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. @@ -94,7 +94,7 @@ Log into the NEW rig and run the following command: 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>) +**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>) **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. @@ -348,7 +348,7 @@ Other things to check: ## 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](<../How it works/understanding-autotune>). +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>). 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). diff --git a/docs/docs/Usage and maintenance/usability-considerations.md b/docs/docs/Usage and maintenance/usability-considerations.md index 00ceda700..942239126 100644 --- a/docs/docs/Usage and maintenance/usability-considerations.md +++ b/docs/docs/Usage and maintenance/usability-considerations.md @@ -2,16 +2,16 @@ 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: -- [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 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 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-) +- [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 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 eeebbf61e..d84094e21 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 @@ -20,7 +20,7 @@ In addition, be diligent about your sensor calibration habits. Only calibrate o ## 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](<../How it works/autotune#AutotuneWeb-the-easiest-way-to-run-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). diff --git a/docs/docs/While You Wait For Gear/reading-list.md b/docs/docs/While You Wait For Gear/reading-list.md index 1286989ec..201d246c6 100644 --- a/docs/docs/While You Wait For Gear/reading-list.md +++ b/docs/docs/While You Wait For Gear/reading-list.md @@ -8,7 +8,7 @@ Here are the most important sections to read: 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. +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. From 73f7be2f5bd0ed3f5bf4fa81a9521ac3124be00d Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Tue, 10 Sep 2019 22:30:28 -0400 Subject: [PATCH 46/54] make sure notes about autotune using a single ISF/CR are in the main prep section, not specifically for Medtronic pumps; include more detail about how that might affect automatic usage in the how it works section; consolidate several places linking to where to give feedback about Autotune --- docs/docs/How it works/autotune.md | 2 ++ .../Usage and maintenance/optimize-your-settings.md | 2 +- docs/docs/Usage and maintenance/running-autotune.md | 11 ++--------- 3 files changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/docs/How it works/autotune.md b/docs/docs/How it works/autotune.md index a9e9150d6..1eb758e80 100644 --- a/docs/docs/How it works/autotune.md +++ b/docs/docs/How it works/autotune.md @@ -10,6 +10,8 @@ This page describes how Autotune works. For information on how to run it, please 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). diff --git a/docs/docs/Usage and maintenance/optimize-your-settings.md b/docs/docs/Usage and maintenance/optimize-your-settings.md index 978662f83..eaec30132 100644 --- a/docs/docs/Usage and maintenance/optimize-your-settings.md +++ b/docs/docs/Usage and maintenance/optimize-your-settings.md @@ -14,7 +14,7 @@ If you are new to using Nightscout, you may want to start using the "reports" (v 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](<../How it works/autotune>).) +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 diff --git a/docs/docs/Usage and maintenance/running-autotune.md b/docs/docs/Usage and maintenance/running-autotune.md index 2369c95af..583758697 100644 --- a/docs/docs/Usage and maintenance/running-autotune.md +++ b/docs/docs/Usage and maintenance/running-autotune.md @@ -96,10 +96,6 @@ If you are not running autotune as part of a closed loop, you can still run it a **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>) -**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. - -**Feedback**: Please note 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). - ### 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.) @@ -350,10 +346,7 @@ Other things to check: 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>). -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). - -(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>). From c2f6387408718e769c4fe6282f464b43dd4da1af Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 11 Sep 2019 10:06:09 -0400 Subject: [PATCH 47/54] updates to nuts and bolts options for Edison & another soft case --- docs/docs/Gear Up/edison-explorer-board.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/docs/Gear Up/edison-explorer-board.md b/docs/docs/Gear Up/edison-explorer-board.md index 3eeebb0be..cc552e572 100644 --- a/docs/docs/Gear Up/edison-explorer-board.md +++ b/docs/docs/Gear Up/edison-explorer-board.md @@ -73,7 +73,13 @@ 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. 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). +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 @@ -81,6 +87,7 @@ You can use a variety of cases, either soft or hard. Make sure to check the case #### 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 From 35495ad2e6be5462c7220fef1bb1aa58d873fd5c Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 11 Sep 2019 10:29:44 -0400 Subject: [PATCH 48/54] link to updating nightscout along with making profile changes --- docs/docs/Usage and maintenance/optimize-your-settings.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docs/Usage and maintenance/optimize-your-settings.md b/docs/docs/Usage and maintenance/optimize-your-settings.md index eaec30132..b4355c4c2 100644 --- a/docs/docs/Usage and maintenance/optimize-your-settings.md +++ b/docs/docs/Usage and maintenance/optimize-your-settings.md @@ -38,3 +38,4 @@ Human behaviors set aside, if you are still seeing hills and valleys in your BG 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>). From f9c2972e66fe02e40f8dceb19363262b229c568c Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 11 Sep 2019 10:30:59 -0400 Subject: [PATCH 49/54] put info about how openaps/nightscout work together in main nightscout setup page instead of troubleshooting; put all troubleshooting info in troubleshooting page instead of split between setup and troubleshooting; put info about additional pills not to trust in the setup page --- .../Rig-NS-communications-troubleshooting.md | 53 +++++------ .../nightscout-setup.md | 92 ++++++++++++------- 2 files changed, 83 insertions(+), 62 deletions(-) diff --git a/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md b/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md index 44c7e13cd..d89b6a146 100644 --- a/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md +++ b/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md @@ -14,33 +14,6 @@ The major categories of Nightscout troubleshooting include: 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. -### 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 - ## mLab maintenance Your NS data is stored in a place called an mLab database. This mLab database is free so long as you stay below a 500mb data limit. Inevitably, after several months of OpenAPS use, you may fill that free data storage limit. Typically, you won't be notified of that issue...instead you'll start to notice sudden problems with your NS site when you haven't done anything different. Strange symptoms include, but aren't limited to: @@ -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/While You Wait For Gear/nightscout-setup.md b/docs/docs/While You Wait For Gear/nightscout-setup.md index 95926ea50..ca6706d31 100644 --- a/docs/docs/While You Wait For Gear/nightscout-setup.md +++ b/docs/docs/While You Wait For Gear/nightscout-setup.md @@ -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.** @@ -351,7 +390,20 @@ Other notes: ![Deploy branch](../Images/nightscout/deploy_branch.jpg) -## Understanding and using your Nightscout site +## Using your Nightscout site + +### 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. + +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 @@ -365,6 +417,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. @@ -395,33 +455,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. - - -## Nightscout troubleshooting - -### 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) -### It's not working - I'm missing data in Nightscout? - -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>). - -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. From 41794f9abf3b562608a07916512ccef4d864b9d5 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 11 Sep 2019 10:41:10 -0400 Subject: [PATCH 50/54] empirically checking rtd url_resolver default sorry --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 92e9e527a..70f0204d3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -419,7 +419,7 @@ def setup(app): app.add_config_value('recommonmark_config', { # 'url_resolver': lambda url: github_doc_root + url, - 'url_resolver': lambda url: hosted_root + url + '.html', + # 'url_resolver': lambda url: hosted_root + url + '.html', 'auto_toc_tree_section': 'Summary', 'enable_auto_doc_ref': True, 'enable_eval_rst': True, From 9ea76a6576f747a642bb6c4a75ff440db829dfcc Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 11 Sep 2019 10:55:42 -0400 Subject: [PATCH 51/54] get rtd links working regardless of project docs are served in --- docs/conf.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 70f0204d3..746a94a14 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -410,19 +410,18 @@ #epub_use_index = True github_doc_root = 'https://github.com/openaps/docs/tree/master/' -hosted_root = os.environ.get('HOSTEDROOT', 'http://localhost:8000/') # Allow setting custom root in local .env file +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') - rtd_domain = 'draft-openaps-reorg' # TEMPORARY to keep links working on RTD preview. os.environ.get('RTDDOMAIN', 'openaps') + 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, - # 'url_resolver': lambda url: hosted_root + url + '.html', + 'url_resolver': lambda url: hosted_root + url + '.html', 'auto_toc_tree_section': 'Summary', 'enable_auto_doc_ref': True, 'enable_eval_rst': True, }, True) - app.add_transform(AutoStructify) - + app.add_transform(AutoStructify) \ No newline at end of file From ac245a13bad3e987547ab23eff2929b4cdd261bd Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 11 Sep 2019 10:57:14 -0400 Subject: [PATCH 52/54] remove extra whitespace --- docs/index.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 4ab3a128d..a2d94c8ee 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -151,9 +151,3 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of Switching between DIY systems - - - - - - From 15520c4a29ce67af72e897237a306e3eb32da47e Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Wed, 11 Sep 2019 11:12:46 -0400 Subject: [PATCH 53/54] just call NS-rig communications troubleshooting nightscout --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index a2d94c8ee..f5973915f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -124,7 +124,7 @@ This documentation supports a self-driven Do-It-Yourself (DIY) implementation of Wifi and hotspot issues Pump-rig communications troubleshooting CGM-rig communications troubleshooting - NS-rig communications troubleshooting + Nightscout troubleshooting Medtronic button errors Carelink troubleshooting From 13b8c8ec452d614e8a0a270c9883ab827fa4dbb3 Mon Sep 17 00:00:00 2001 From: Kim Scott Date: Thu, 12 Sep 2019 10:03:58 -0400 Subject: [PATCH 54/54] move note about multiple CRs/ISFs out of pump-specific section to Autotune --- docs/docs/While You Wait For Gear/collect-data-and-prepare.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 d84094e21..b88e72466 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 @@ -26,6 +26,8 @@ How important are good basals and ISFs? You mean you weren't convinced already b 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. +**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 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! @@ -55,8 +57,6 @@ 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.