+`nano ~/.bash_profile` +
+* Copy and paste (or make your own aliases) the following aliases into the blank profile +
+``` +alias autosens-loop="tail -n 100 -F /var/log/openaps/autosens-loop.log" +alias autotune="tail -n 100 -F /var/log/openaps/autotune.log" +alias ns-loop="tail -n 100 -F /var/log/openaps/ns-loop.log" +alias pump-loop="tail -n 100 -F /var/log/openaps/pump-loop.log" +alias cat-pref="cd ~/myopenaps && cat preferences.json" +alias edit-wifi="vi /etc/wpa_supplicant/wpa_supplicant.conf" +alias cat-wifi="cat /etc/wpa_supplicant/wpa_supplicant.conf" +alias edit-pref="cd ~/myopenaps && vi preferences.json" +alias log-wifi="tail -n 100 -F /var/log/openaps/network.log" +alias git-branch="cd ~/src/oref0 && git branch" +alias cat-autotune="cd ~/myopenaps/autotune && cat autotune_recommendations.log" +alias edit-runagain="cd ~/myopenaps && nano oref0-runagain.sh" +alias cat-runagain="cd ~/myopenaps && cat oref0-runagain.sh" +``` +
+Exit the nano editor by pressing `control-x`, then typing `y` to save file, and then `return` to save with same file name. +
+* Tell your rig to use this profile (note: this command will need to be done after each update to the profile too, or the new aliases won't be activated until you reboot) +
+`source ~/.bash_profile` diff --git a/docs/docs/walkthrough/phase-1/img/add_vars.jpg b/docs/docs/walkthrough/phase-1/img/add_vars.jpg new file mode 100644 index 000000000..6a55e2df2 Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/add_vars.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/deploy_branch.jpg b/docs/docs/walkthrough/phase-1/img/deploy_branch.jpg new file mode 100644 index 000000000..0696f96a0 Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/deploy_branch.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/deploy_button.jpg b/docs/docs/walkthrough/phase-1/img/deploy_button.jpg new file mode 100644 index 000000000..fbbc4802b Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/deploy_button.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/deploy_heroku.jpg b/docs/docs/walkthrough/phase-1/img/deploy_heroku.jpg new file mode 100644 index 000000000..757343eb4 Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/deploy_heroku.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/deploy_success.jpg b/docs/docs/walkthrough/phase-1/img/deploy_success.jpg new file mode 100644 index 000000000..ed7311ddf Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/deploy_success.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/heroku_signup.jpg b/docs/docs/walkthrough/phase-1/img/heroku_signup.jpg new file mode 100644 index 000000000..6b7739280 Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/heroku_signup.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/no_profile.jpg b/docs/docs/walkthrough/phase-1/img/no_profile.jpg new file mode 100644 index 000000000..b143ae95d Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/no_profile.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/ns_deploybranch.png b/docs/docs/walkthrough/phase-1/img/ns_deploybranch.png new file mode 100644 index 000000000..0ddf2bae7 --- /dev/null +++ b/docs/docs/walkthrough/phase-1/img/ns_deploybranch.png @@ -0,0 +1 @@ +i diff --git a/docs/docs/walkthrough/phase-1/img/ns_fork.jpg b/docs/docs/walkthrough/phase-1/img/ns_fork.jpg new file mode 100644 index 000000000..b2eb4d101 Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/ns_fork.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/open_app.jpg b/docs/docs/walkthrough/phase-1/img/open_app.jpg new file mode 100644 index 000000000..0dd142992 Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/open_app.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/profile.jpg b/docs/docs/walkthrough/phase-1/img/profile.jpg new file mode 100644 index 000000000..ec4def0ea Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/profile.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/settings_heroku.jpg b/docs/docs/walkthrough/phase-1/img/settings_heroku.jpg new file mode 100644 index 000000000..fb5b87bea Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/settings_heroku.jpg differ diff --git a/docs/docs/walkthrough/phase-1/img/settings_ns.jpg b/docs/docs/walkthrough/phase-1/img/settings_ns.jpg new file mode 100644 index 000000000..b93a24445 Binary files /dev/null and b/docs/docs/walkthrough/phase-1/img/settings_ns.jpg differ diff --git a/docs/docs/walkthrough/phase-1/index.rst b/docs/docs/walkthrough/phase-1/index.rst index 11f1e0b79..3f772991b 100644 --- a/docs/docs/walkthrough/phase-1/index.rst +++ b/docs/docs/walkthrough/phase-1/index.rst @@ -6,13 +6,6 @@ Phase 1: Monitoring and Visualization nightscout-setup - log-clean-analyze - analyze-existing-data - using-openaps-tools - visualization - openaps-to-nightscout - offline-monitoring - - - - + offline-looping-and-monitoring + papertrail + add-alias diff --git a/docs/docs/walkthrough/phase-1/nightscout-setup.md b/docs/docs/walkthrough/phase-1/nightscout-setup.md index 6f7b64b20..5f00fa393 100644 --- a/docs/docs/walkthrough/phase-1/nightscout-setup.md +++ b/docs/docs/walkthrough/phase-1/nightscout-setup.md @@ -2,133 +2,270 @@ ## Nightscout Introduction -[Nightscout](http://nightscout.info) in their own words: Nightscout (CGM in the -Cloud) is an open source, DIY project that allows real time access to a CGM data +[Nightscout](http://nightscout.info) is an open source, DIY project that allows real-time access to a CGM data via personal website, smartwatch viewers, or apps and widgets available for -smartphones. +smartphones. Setting up a Nightscout web app is the recommended way to visualize your +OpenAPS closed loop. -It basically allows a user to upload CGM data from a variety of sources, to an +Nightscout allows a user to upload CGM data from a variety of sources, to an online database and cloud computing service. The information is then processed and displayed visually as a graph. There are plugins that allow greater -information to be shown about OpenAPS too. As the data is uploaded to an online -website and then retrieved by OpenAPS it allows OpenAPS a wider range of +information to be shown about OpenAPS, too. As the data is uploaded to an online +website and then retrieved by OpenAPS, it allows OpenAPS a wider range of compatibility with various CGM solutions. **[Nightscout](http://nightscout.info) is the recommended way to visualize your OpenAPS closed loop.** -Even if you don't choose to share your Nightscout instance +Even if you don't choose to share your Nightscout site 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 and also allowing you to customize watchfaces with your OpenAPS data. -This provides a visual alternative to SSHing into your Raspberry Pi or loop -system and looking through log files. - -At this point it is recommended that you go to the -[Nightscout](http://nightscout.info) website and set Nightscout up. They have -excellent guides of how to get various CGM systems working as well as displaying -your data on a variety of additional devices. Once your website is up and -running you can integrate Nightscout to your OpenAPS using the guide below. - -**NOTE**: If you plan to use Nightscout to vizualize a production OpenAPS instance, we -recommend using the $7/mo Heroku plans, as OpenAPS' can reach the usage limits of -the free Azure plan and cause it to shut down for hours or days. - -## Nightscout Integration - -The integration requires setting up Nightscout and making changes and additions -to your OpenAPS implementation. - -### Nightscout Setup - -OpenAPS requires you to be on the Grilled Cheese master of Nightscout or any future dev versions, which can be -found [here](https://github.com/nightscout/cgm-remote-monitor/tree/dev). If you -are already using Nightscout, you may have to do a pull request (PR) to update the master branch in your repository. To update -your version to the latest dev, go to the -[Beta Test tool](http://nightscout.github.io/pages/test-beta/?branch=dev), look -for the "I'm ready" button, and create a PR to your dev branch. Once you have -completed these steps, log on to Heroku or Azure and disconnect the deployment -source. Thereafter choose your cgm-remote-monitor github repository as source -again. -_________________________ -**If this doesn't work then from the command prompt in terminal run the -following: - -``` -git clone -b dev https://github.com/
| KEY | +VALUE | +
|---|---|
| API_SECRET | +Create your own API_SECRET…this is like the password to your NS site. Please write it down somewhere safe or commit it to memory, you will be using it in the future. It needs to be at least 12 characters long and should NOT use the `@` symbol. | +
| DISPLAY_UNITS | +enter either mg/dl or mmol | +
| ENABLE | +bridge openaps pump iob basal careportal sage cage maker(Enter all of the words without commas. Just a single space between each word. Make sure autocorrect does not add space between careportal. **Notice we are not including cob here.** If you have other plugins that you would like to enable, please add them here.) | +
| DISABLE | +Leave blank | +
| ALARM_TYPES | +simple | +
| BG_HIGH | +Enter the numeric value of BG you’d like as an urgent high alarm. | +
| BG_TARGET_TOP | +Enter the numeric value of the top of your target BG. | +
| BG_TARGET_BOTTOM | +Enter the numeric value of the bottom of your target BG. | +
| BG_LOW | +Enter the numeric value of the BG you’d like as an urgent low alarm. | +
| PUSHOVER lines | +Can be left blank for now. If you decide to use Pushover later, you can come back and add your info to these lines. | +
| CUSTOM_TITLE | +This will be the text displayed in the upper left part of the NS website. | +
| THEME | +change from default to colors | +
| BRIDGE_USER_NAME | +Enter your Dexcom Share Account login name. This should be the same account name used in the Share2 or G5 Mobile app. | +
| BRIDGE_PASSWORD | +Enter your Dexcom Share Account password. | +
| BRIDGE_MAX_COUNT | +Default value is 1. Setting this to 7 will update the last 35 minutes of data. | +
| KEY | +VALUE | +
|---|---|
| DEVICESTATUS_ADVANCED | +true | +
| PUMP_FIELDS | +battery reservoir clock status | +
| PUMP_RETRO_FIELDS | +battery reservoir clock status | +
| SHOW_FORECAST | +openaps | +
| SHOW_PLUGINS | +openaps pump iob sage cage careportal | +
| PUMP_ENABLE_ALERTS | +true | +
| PUMP_URGENT_BATT_V | +1.3(This is the pump battery voltage that will trigger a red, urgent alert in NS.) | +
| PUMP_URGENT_RES | +10(This is the reservoir volume that will trigger a red, urgent alert in NS.) | +
| PUMP_URGENT_CLOCK | +30 | +
| OPENAPS_ENABLE_ALERTS | +true | +
| OPENAPS_FIELDS | +status-symbol status-label iob meal-assist rssi | +
| OPENAPS_RETRO_FIELDS | +status-symbol status-label iob meal-assist rssi | +
| OPENAPS_WARN | +20(This is the minutes since OpenAPS last successfully looped. This will be a yellow alert in NS.) | +
| OPENAPS_URGENT | +60(Same as the alert above, but will be red in color and have a shorter snooze option.) | +
-To start cron: `sudo service cron start` +To start cron: `sudo service cron start` or reboot your rig. To prevent cron running on initial boot, either clear the `crontab -e` file or "comment out" (`#`) each line of the crontab file. If you've cleared the crontab file, but would like to enable cron'd tasks, rerun the initial setup script (step 2) and indicate you'd like to use cron. This will regenerate the configuration. ## How do I know if it is working? +Please be patient. We can not emphasize this enough. + * Check your pump to see if it is setting temp basals. * "Tail" the pump log to see what is is doing: `tail -F /var/log/openaps/pump-loop.log` -* Check Nightscout to see if it is updating with your information +* A very basic test to see if the pump communication works is to issue a `openaps use pump model`. That should return your pump model. If it displays an error or an empty string your rig can't communicate with your pump. +* Check Nightscout to see if it is updating with your information. Note: that if Nightscout is not showing your loop is running, it might be running but unable to communicate with Nightscout. In those cases check the pump-loop.log on your rig. * Run commands manually (check out the [openaps toolkit basics here](http://openaps.readthedocs.io/en/latest/docs/openaps-guide/core/medtronic.html#openaps-use-pump)) ## It's not working yet: +Make sure to check through the following list before asking on Gitter if your setup is not working (yet). Remember if you just ran oref0-setup.sh, wait a good ~20 minutes as mentioned above before seeking help. Time, and the below list of steps, resolves 99% of problems. Also check out [this blog post for tips if asking for help online](https://diyps.org/2017/03/19/tips-for-troubleshooting-diy-diabetes-devices-openaps-or-otherwise/). + * Check to make sure that your pump is in absolute and not % mode for temp basals. * Did you put in the right SN for the pump? Should be numbers only... * Check to make sure your carelink and/or radio stick is plugged in. -* 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). * 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 and make sure your receiver is >50% charged (if battery low, it may drain the Pi and prevent it from operating). -* Check and make sure your pump is in range of the radio stick. +* 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). +* 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. -* 512 users - make sure that you have created your static json files as outlined in https://openaps.readthedocs.io/en/dev/docs/walkthrough/phase-0/hardware/pump.html for raw-pump/settings.json, raw-pump/bg-targets-raw.json, and raw-pump/selected-basal-profile.json. You will also have to remove the calls for them from the your get-settings alias. +* Check to make sure you have a carb ratio set manually in your Medtronic insulin pump, if it is not done, the follwoing display will appear in your pump.log: Could not parse input data: [SyntaxError: /root/myopenaps/monitor/iob.json: Unexpected end of input] +* 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). +* 512 users - make sure that you have created your static json files as outlined [here](https://openaps.readthedocs.io/en/dev/docs/walkthrough/phase-0/hardware/pump.html) for raw-pump/settings.json, raw-pump/bg-targets-raw.json, and raw-pump/selected-basal-profile.json. You will also have to remove the calls for them from the your get-settings alias. To do this: ``` + killall -g openaps + openaps alias remove get-settings + openaps alias add get-settings "report invoke settings/model.json settings/bg_targets.json settings/insulin_sensitivities_raw.json settings/insulin_sensitivities.json settings/carb_ratios.json settings/profile.json" + ``` + The 512 also does not have the ability to report bolusing so the “gather” alias also has to be adjusted. + + ``` + killall -g openaps + openaps alias remove gather + openaps alias add gather '! bash -c "(openaps monitor-pump || openaps monitor-pump) 2>/dev/null >/dev/null && echo refreshed pumphistory || (echo unable to refresh pumphistory; exit 1) 2>/dev/null"' + ``` + +## Running commands manually to see what's not working from an oref0-setup.sh setup process + +You've probably run into an error in your setup where someone has recommended "running commands manually" to drill down on an error. What to do? Some of the following: + + * Start by killing anything that's currently running. ` killall -g openaps` + * 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 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. + * Don't use `2>/dev/null` or `>/dev/null ` parts of commands, because they will hide output of commands + * If a command does not return output, check with `echo $?` if the exit code returns `0`. That means OK (no error). If it returns non-zero (e.g. `1`) then the command failed and you need to drill down further. + * You can keep drilling down until you get through all the aliases to the actual reports, which can be run manually using a command like `openaps report invoke monitor/status.json` to see the raw unfiltered output with full error details. + * Still no luck? Try the [Troubleshooting](http://openaps.readthedocs.io/en/master/docs/Resources/troubleshooting.html) page or ask for help. + +### 512 users / 712 users / x12 users + +If you have one of the x12 model pumps, you need to do the following: +* Add pump settings files manually. Certain commands like Re.ad Settings, BG Targets and certain Read Basal Profile are not available, and requires creating a static json for needed info missing to successfully run the loop. Create raw-pump/settings.json, raw-pump/bg-targets-raw.json, and raw-pump/selected-basal-profile.json See this example: https://gist.github.com/amazaheri/033b85760156054dd858 +* Adapt the aliases as following so it doesn't call for non-existing pump files: + +First, do these: + ``` + killall -g openaps openaps alias remove get-settings openaps alias add get-settings "report invoke settings/model.json settings/bg_targets.json settings/insulin_sensitivities_raw.json settings/insulin_sensitivities.json settings/carb_ratios.json settings/profile.json" ``` The 512 also does not have the ability to report bolusing so the “gather” alias also has to be adjusted. + So also do these: ``` + killall -g openaps openaps alias remove gather - openaps alias add gather '! bash -c "(openaps monitor-pump || openaps monitor-pump) 2>/dev/null >/dev/null && echo refreshed pumphistory || (echo unable to refresh pumphistory; exit 1) 2>/dev/null”' + openaps alias add gather '! bash -c "(openaps monitor-pump || openaps monitor-pump) 2>/dev/null >/dev/null && echo refreshed pumphistory || (echo unable to refresh pumphistory; exit 1) 2>/dev/null"' ``` + There may be at least another step missing. If you figure out a missing step from the above for x12, PLEASE PUT IN A PR AND DOCUMENT WHAT THIS IS! diff --git a/docs/docs/walkthrough/phase-2/update-your-rig.md b/docs/docs/walkthrough/phase-2/update-your-rig.md new file mode 100644 index 000000000..a1a11b442 --- /dev/null +++ b/docs/docs/walkthrough/phase-2/update-your-rig.md @@ -0,0 +1,22 @@ +# How to update 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/walkthrough/phase-2/oref0-setup.html#re-running-the-setup-script)). + +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`. + +## Step 1: Install the new version + +#### Recommended: To get the new stuff from the newest released master version of oref0 + +1. `cd ~/src/oref0 && git checkout master && git pull && sudo npm install -g oref0` + +#### Optional: To get on "dev" branch to test even more recently added new stuff + +Or, if the feature you want hasn't been released yet, and you want to test the latest untested development version of `oref0`, run: + +1. `cd ~/src/oref0 && git checkout dev && git pull` +2. `npm run global-install` + +## Step 2: Re-run oref0-setup + +Now that you've updated your `oref0` version, you can [re-run the oref0-setup script](http://openaps.readthedocs.io/en/latest/docs/walkthrough/phase-2/oref0-setup.html#re-running-the-setup-script) to use it. diff --git a/docs/docs/walkthrough/phase-3/Understand-determine-basal.md b/docs/docs/walkthrough/phase-3/Understand-determine-basal.md index 723afc055..b792d714c 100644 --- a/docs/docs/walkthrough/phase-3/Understand-determine-basal.md +++ b/docs/docs/walkthrough/phase-3/Understand-determine-basal.md @@ -1,51 +1,68 @@ -# Understanding the output of oref0-determine-basal +# Understanding the determine-basal logic -The key logic behind any oref0 implementation of OpenAPS lies in the oref0-determine-basal.js code, which is what takes all of the inputs you've collected and makes a temp basal recommendation you can then enact if appropriate. As such, it is important to understand how determine-basal makes its decisions, and how to interpret its output, so you can decide for yourself whether the recommendations it is making are appropriate for your situation, or if further adjustments are required before closing the loop or letting it run unattended. +The core, lowest level logic behind any oref0 implementation of OpenAPS can be found in [`oref0/lib/determine-basal/determine-basal.js`](https://github.com/openaps/oref0/blob/master/lib/determine-basal/determine-basal.js). That code pulls together the required inputs (namely, recent CGM readings; current pump settings,including insulin on board and carbohydrates consumed; and your profile settings) and performs the calculations to make the recommeneded changes in temp basal rates that OpenAPS could/will enact. -The recommendation is to run for several days in "low glucose management" loop mode, watching the output, in order to decide what your "max basal" setting should be. Based on how often you disagreed or counteracted what the loop was recommending, this might influence how you set your max basal. +Short of reading the actual code, one way to start to understand the key `determine-basal` logic is to understand the inputs passed into the script/program and how to interpret the outputs from the script/program. ## Summary of inputs -The determine-basal algorithm requires a number of inputs, which are passed in JSON files such as iob.json, currenttemp.json, glucose.json, profile.json, and optionally meal.json. When running oref0-determine-basal.js with the appropriate inputs, the first thing you'll see is a summary of all the provided inputs, which might look something like this: +The `determine-basal` algorithm requires 4 input files: +* iob.json +* currenttemp.json +* glucose.json +* profile.json + +In addition, the algorithm can accept 2 optional input files: +* meal.json +* autosens.json + +When running `oref0-determine-basal.js`, the first thing you'll see is a summary of all the inputs, which might look something like this: ``` {"carbs":0,"boluses":0} -{"delta":-2,"glucose":110,"avgdelta":-2.5} +{"delta":5,"glucose":161,"short_avgdelta":4.5,"long_avgdelta":3.92} {"duration":0,"rate":0,"temp":"absolute"} -{"iob":0,"activity":0,"bolussnooze":0,"basaliob":0} +{"iob":0,"activity":0,"bolussnooze":0,"basaliob":0,"netbasalinsulin":0,"hightempinsulin":0,"time":"2017-03-17T00:34:51.000Z"} {"carbs_hr":28,"max_iob":1,"dia":3,"type":"current","current_basal":1.1,"max_daily_basal":1.3,"max_basal":3,"max_bg":120,"min_bg":115,"carbratio":10,"sens":40} ``` * meal.json = `{"carbs":0,"boluses":0}` - * If provided, allows determine-basal to decide when it is appropriate to enable Meal Assist. - * carbs = # of carbs consumed - * boluses = amount of insulin delivered - * This data comes from what is entered by user into pump/nightscout -* glucose.json = `{"delta":-2,"glucose":110,"avgdelta":-2.5}` - * delta = change from the previous BG (usually 5 minutes earlier) - * glucose = most recent BG - * avgdelta = average change since 3 data points earlier (usually 15 minutes earlier) - * This data comes from your connected cgm or from nightscout + * `carbs` = # of carbs consumed + * `boluses` = amount of bolus insulin delivered + + Those data come from what you entered into your pump or Nightscout web app. If provided, allows determine-basal to decide when it is appropriate to enable Meal Assist. +* glucose.json = `{"delta":5,"glucose":161,"short_avgdelta":4.5,"long_avgdelta":3.92}` + * `delta` = change in BG between `glucose` (most recent BG) and an average of BG value from between 2.5 and 7.5 minutes ago (usually just a single BG value from 5 minutes ago) + * `glucose` = most recent BG + * `short_avgdelta` = change in BG between `glucose` (most recent BG) and an average of BG values from between 2.5 and 17.5 minutes ago (that average represents what BG levels were approximately 10 minutes ago) + * `long_avgdelta` = change in BG between `glucose` (most recent BG) and an average of BG values from between 17.5 and 42.5 minutes ago (that average represents what BG levels were approximately 30 minutes ago) + + Those data come from your connected CGM or from your Nightscout web app. * temp_basal.json = `{"duration":0,"rate":0,"temp":"absolute"}` - * duration = length of time temp basal will run. A duration of 0 indicates none is running - * rate = Units/hr basal rate is set to - * temp = type of temporary basal rate in use. OpenAPS uses absolute basal rates only - * This data comes from the pump -* iob.json = `{"iob":0,"activity":0,"bolussnooze":0,"basaliob":0,"netbasalinsulin":0,"hightempinsulin":0,"time":"2016-10-26T20:07:37.000Z"}` - * iob = net insulin on board compared to preprogrammed pump basal rates. This takes all basal, temp basal, and bolus information into account - * activity = the amount that BG "should" be rising or falling based on iob. - Insulin activity is used (by multiplying activity * ISF) to determine BGI (blood glucose impact), the amount that BG "should" be rising or falling based on insulin activity alone. - * bolussnooze = used to determine how long to avoid low-temping after a bolus while waiting for carbs to kick in - * basaliob = insulin on board attributed to basal rate, excluding the IOB effect of boluses - * netbasalinsulin = net of basal insulin compared to preprogrammed pump basal rate - * time = current time - * This data calculated based on information received from your pump + + * `duration` = Length of time temp basal will run. A duration of 0 indicates none is running. + * `rate` = Units/hr basal rate is set to + * `temp` = Type of temporary basal rate in use. OpenAPS uses `absolute` basal rates only. + + Those data come from your pump. +* iob.json = `{"iob":0,"activity":0,"bolussnooze":0,"basaliob":0,"netbasalinsulin":0,"hightempinsulin":0,"time":"2017-03-17T00:34:51.000Z"}` + * `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"). + * `activity` = Units of insulin active in the previous minute. Approximately equal to (net IOB, 1 minute ago) - (net IOB, now). + * `bolussnooze` = Units of bolus IOB, if duration of insulin activity (dia) was half what you specified in your pump settings. (`dia_bolussnooze_divisor` in profile.json is set by default to equal 2, but you may adjust this if you'd like OpenAPS to activate a low-temp sooner or later after bolusing.) `bolussnooze` is used in *oref0-determine-basal.js* to determine how long to avoid low-temping after a bolus while waiting for carbs to kick in. + * `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. Note: `max_iob` (described below) provides a constraint on how high this value can be. The `determine-basal` logic will not recommend a temp basal rate that will result in `basaliob` being greater than `max_iob`. + * `netbasalinsulin` = this variable isn't used in OpenAPS logic anymore, but hasn't been removed from iob.json yet. + * `hightempinsulin` = this variable isn't used in OpenAPS logic anymore, but hasn't been removed from iob.json yet. + * `time` = current time + + Those data are calculated based on information received from your pump. * preferences.json = `{"carbs_hr":28,"max_iob":1,"dia":3,"type":"current","current_basal":1.1,"max_daily_basal":1.3,"max_basal":3,"max_bg":120,"min_bg":115,"carbratio":10,"sens":40}` * Contains all of the user’s relevant pump settings - * max_iob = maximum allowed insulin on board. This is an important safety measure and integral part of the OpenAPS design. - * This data is set during the openAPS setup script (or modified by you directly) and based on information received from your pump -## Output + * max_iob = maximum amount of net IOB that OpenAPS will ever allow when setting a high-temp basal rate. **This is an important safety measure and integral part of the OpenAPS design.** You should set this value based on your current basal rates and insulin sensitivy factor (ISF, or `sens` in the OpenAPS code) and after studying how the OpenAPS algorithm performs in low-glucose suspend mode for (at least) several days. + + Those data are set during the openAPS setup script (or modified by you directly) and based on information received from your pump. + +## Summary of outputs After displaying the summary of all input data, oref0-determine-basal outputs a recommended temp basal JSON (stored in suggested.json), which includes an explanation of why it's recommending that. It might look something like this: @@ -78,8 +95,10 @@ For each different situation, the determine-basal output will be slightly differ If after reading through the code you are still unclear as to why determine-basal made a given decision (or think it may be the wrong decision for the situation), please join the #intend-to-bolus channel on Gitter, paste your output and any other context, and we'll be happy to discuss with you what it was doing and why, and whether that's the best thing to do in that and similar situations. -## Note about Square Boluses and Dual Wave Boluses +## Note about Square Boluses, Dual Wave Boluses, and Basal Pump Settings of Zero Due to the way the Medtronic Pumps operate, it should be known that temp basals can only be set when there is no bolus running, including extended (square) / dual wave boluses. Thus it should be noted that if you use an extended bolus for carb heavy meals (e.g. Pizza), which may still be the optimal approach for you, OpenAPS will not be able to provide temp basals during the extended bolus. + +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. diff --git a/docs/docs/walkthrough/phase-3/beyond-low-glucose-suspend.md b/docs/docs/walkthrough/phase-3/beyond-low-glucose-suspend.md index 8efdf8067..e91445c89 100644 --- a/docs/docs/walkthrough/phase-3/beyond-low-glucose-suspend.md +++ b/docs/docs/walkthrough/phase-3/beyond-low-glucose-suspend.md @@ -4,11 +4,11 @@ You may have noticed that in the previous phase, in observing low glucose suspen Once you have spent several days observing the loop in the previous mode and made sure your basals and bolus strategies are in good shape, you may consider moving to the next step. -This means adjusting your max iob amount in your preferences.json file. +This means adjusting your max_iob amount in your preferences.json file. Keep in mind this is one of the key safety features of OpenAPS. You do NOT want this to be a super large amount. The point of this setting is to ensure that the loop can not excessively high temp you; if you need high temps consistently to get you to this amount, your baseline basals are off OR you missed a meal bolus OR you are sick OR there is some other extenuating circumstance; but in all of these cases, they should require manual intervention and you should not expect the loop to solve for this. -A good rule of thumb is for max iob to be no more than 3 times your highest basal rate. Keep in mind you can start conservatively and change this number over time as you evaluate further how the system works for you. +A good rule of thumb is for max_iob to be no more than 3 times your highest basal rate. Keep in mind you can start conservatively and change this number over time as you evaluate further how the system works for you. (This means it should be approximate to your other settings; not an absolute amount that you set without thinking about it.) @@ -18,22 +18,33 @@ All of the settings specific to OpenAPS (that can't be read from the pump) are i Note: the “max basal” rate is the one safety setting that you set in your pump. It should not be confused with “max daily” or “max current” as described below. The system will use whichever of these three values is the lowest as the ceiling for the temps it will set. So, if your pump’s max basal is 1.0u, but your 3x and 4x multipliers would be higher, the system will not set any temps higher than 1.0u, even if it thinks you need more insulin. On the flip side, if your 4x current multiplier says you can have max 1.6u/hr and your max basal is 2u/hr; the maximum set temp at that time will be 1.6u/hr. +``` { "max_iob": 0, - "type": "current", "max_daily_safety_multiplier": 3, "current_basal_safety_multiplier": 4, "autosens_max": 1.2, "autosens_min": 0.7, "autosens_adjust_targets": true, + "maxCOB": 120 "override_high_target_with_low": false, "skip_neutral_temps": false, "bolussnooze_dia_divisor": 2, "min_5m_carbimpact": 3, "carbratio_adjustmentratio": 1 + "autotune_isf_adjustmentFraction": 0.5, + // WARNING: the following are advanced oref1 features; do not enable until you've run oref0 (basic setup) for a while + // also, do not blindly turn all of these on; only enable specifics if you know what each one does + "remainingCarbsCap": 0, + "remainingCarbsFraction": 0.7 + "enableUAM": false, + "enableSMB_with_bolus": false, + "enableSMB_with_COB": false, + "enableSMB_with_temptarget": false } +``` -#### Max IOB: +#### max_iob: This will default to zero. After several days or weeks, depending on your comfort level, you may choose to adjust this number. (Remember in the future if you re-run the setup scripts, it will default back to zero so you will come in here to adjust the max iob, as it is an OpenAPS-specific setting). @@ -57,6 +68,10 @@ The other side of the autosens safety limits, putting a cap on how low autosens This is used to allow autosens to adjust BG targets, in addition to ISF and basals. +#### maxCOB: + +This defaults maxCOB to 120 because that's the most a typical body can absorb over 4 hours. (If someone enters more carbs or stacks more; OpenAPS will just truncate dosing based on 120. Essentially, this just limits AMA as a safety cap against weird COB calculations due to fluky data.) + #### override_high_target_with_low: Defaults to false, but can be turned on if you have a situation where you want someone (a school caregiver, for example) to use the bolus wizard for meal boluses. If set to “True”, then the bolus wizard will calculate boluses with the high end of the BG target, but OpenAPS will target the low end of that range. So if you have a target range of 100-120; and set this to true; bolus wizard will adjust to 120 and the loop will target 100. If you have this on, you probably also want a wide range target, rather than a narrow (i.e. 100-100) target. @@ -77,6 +92,33 @@ This is a setting for default carb absorption impact per 5 minutes. The default This is another safety setting that may be useful for those with secondary caregivers who aren’t dedicated to looking up net IOB and being aware of the status of the closed loop system. The default is 1 (i.e. do not adjust the carb ratio; off). However, in the secondary caregiver situation you may want to set a higher carb ratio to reduce the size of a manual bolus given at any time. With this ratio set to 1.1, for example, the loop would multiple the carb inputs by 10%, and use that number to calculate additional insulin. This can also be used by OpenAPS users who rely on the bolus wizard to calculate their meal bolus, but who want to only bolus for a fraction of the meal, and allow advanced meal assist to high-temp for the rest. +#### autotune_isf_adjustmentFraction + +This keeps autotune ISF closer to pump ISF via a weighted average of fullNewISF and pumpISF. 1.0 allows full adjustment (the previous default), 0 is no adjustment from pump ISF. + +#### remainingCarbsCap + +This is the amount of the maximum number of carbs we'll assume will absorb over 4h if we don't yet see carb absorption. + +#### remainingCarbsFraction + +This is the fraction of carbs we'll assume will absorb over 4h if we don't yet see carb absorption. Most people won't need to change this - leave at the default (0.7). + +#### enableUAM + +This enables detection of unannounced meal (UAM) carb absorption. + +#### enableSMB_with_bolus + +This enables supermicrobolus for DIA hours after a manual bolus. + +#### enableSMB_with_COB + +This enables supermicrobolus (SMB) while carbs on board (COB) is positive. + +#### enableSMB_with_temptarget + +This enables supermicrobolus (SMB) with eating soon or lower temp targets. For example, if your target is usually 100mg/dL, a temp target of 99 (or 80, the typical eating soon target) will enable SMB. ## Editing your preferences.json diff --git a/docs/docs/walkthrough/phase-3/troubleshooting-loop.md b/docs/docs/walkthrough/phase-3/troubleshooting-loop.md index c82d0ccf8..4fc19f036 100644 --- a/docs/docs/walkthrough/phase-3/troubleshooting-loop.md +++ b/docs/docs/walkthrough/phase-3/troubleshooting-loop.md @@ -12,6 +12,8 @@ It may be tempting on day one to set your targets to mirror your traditional BG Don't try to do everything the first week: think long term. You should start setting your glucose target range higher and wider, i.e. 130-150 mg/dL (7.2-8.3 mmol/L). However, do not set your range wider than about 20 mg/dL, as this often causes confusions for new loopers. Once you can reproducibly get your sugars in a wider and higher band without going low, you can then *slowly* reduce the target range to your ideal target range. +Target BG target is set on your pump. Navigate to Bolus -> Bolus Wizard Setup -> Edit Settings -> BG Target + Try to remember to set your Nightscout profile to match your pump as you make changes, to also limit confusion. Update target BG, basal rates, ISF and carb ratios to stay the same as on your pump. Data from the pump not Nightscout is used to drive the closed loop; having Nightscout display different targets and incorrect settings may be confusing. ## What should pump settings be? diff --git a/docs/docs/walkthrough/phase-4/Usability-considerations.md b/docs/docs/walkthrough/phase-4/Usability-considerations.md index 7eaef3c54..b4e68aac8 100644 --- a/docs/docs/walkthrough/phase-4/Usability-considerations.md +++ b/docs/docs/walkthrough/phase-4/Usability-considerations.md @@ -5,6 +5,11 @@ Now that you've closed the loop, you probably have a lot of new "first" experien ## **What do you do with the loop in airport security when you travel**
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.) + +## **What do you do with your loop when you travel across timezones? How do you update devices for a time zone change?** +
You have a couple of options. If you are traveling briefly, or only across a couple of timezones, and would not normally feel the need to adjust the timing of your basals, then you may choose to simply leave your pump, receiver, and Pi/Edison on your home timezone. But, if you would like to adjust to the new timezone (perhaps for a longer trip or a move), you can adjust your rig's timezone using `sudo dpkg-reconfigure tzdata` and then either run `killall -g openaps; oref0-set-device-clocks` to set the devices to match, or just change your pump and receiver time manually. Make sure to test in your new location to make sure everything is working! We also recommend planning to do this when you have some extra time for troubleshooting, in case you have issues. Also, it's worth noting that your body only changes about an hour or so of timezone a day, so even if you go abroad, there's not a rush to change timezones/the time on your devices - you can wait until 2-3 days into your trip to make the swap, at a time when you have some room to update your rigs. +
After the timezone change OpenAPS sometimes gets confused about the BG and/or pump data being "in the future". The pump and CGM data are not timestamped in UTC, so being unsynchronized with the OpenAPS can cause incorrect behavior. When the BG or pump data is "in the future" the software may stop pulling current information from the pump, and stop functioning (until the current time in the system reaches the time when the monitor data is no longer "in the future"). It often makes sense to remove all files from OpenAPS monitor folder after changing the timezone. However, this is sometimes insufficient, as the devices will still have records that are "in the future" from the perspective of your new timezone. As a result, you should expect Nightscout uploads to fail until the system time catches up to the previous device time, particularly when traveling west. + ## **What do you do with the loop when you shower?**
Because the pumps aren't really waterproof, most of us choose to suspend and disconnect our pumps before we shower. You'll do the same thing even after you're looping. One trick, though, is to cancel any running temp basal rate and set a temp basal for 30 minutes with a rate of 0.0, and then suspend the pump. This will help OpenAPS accurately track your netIOB while you are off your pump. When you get out of the shower and are ready to reconnect your pump, do so. Make sure to unsuspend it. You can then either manually cancel the zero temp basal; or let OpenAPS read and decide what temp basal to issue next. @@ -12,11 +17,39 @@ Now that you've closed the loop, you probably have a lot of new "first" experien
This varies from person to person, and depends on the type and length of activity. Here's a few tidbits from [Dana](http://twitter.com/danamlewis) on how she does various activities. (Other loopers, PR into this page with your additional tips and how-to's.)
* **Hiking** - Definitely take the loop with! Think about setting a temporary target (you can enter it in Nightscout if you have connectivity) higher for the duration of the exercise. If you're offline, just change your targets in your pump. The loop will read the adjusted targets and begin looping toward that target. When you're done with the activity, change your targets back. In this scenario, I might change my loop target from 100 (normal day or nighttime) to 130 or 140 as a target. - * **Swimming, Snorkeling, Scuba Diving, etc. (water sports)** - You can't loop while you're in the water, because the pump is not waterproof. (Unless you're sitting in a hot tub and have your pump safely above water, along with your CGM sensor being above water so it can transmit to the receiver, which is also not waterproof.) You can try having your sensor on your arm and keeping it above water so it can read every now and then if the receiver is in range. That being said, again, pump is NOT waterproof so you'll need to apply shower methodology (temp to zero, suspend, take pump off) to best track your netIOB. Some people observe having the CGM, once it gets back into range and reads data after the sensor has been submerged, read falsely high. It's not a big deal for the loop (because it's looking at trends, and doses using temp basals in a conservative way), but you'll likely want to fingerstick and/or wait a while before you'll be really happy with your CGM results again. + * **Swimming, Snorkeling, Scuba Diving, etc. (water sports)** - You can't loop while you're in the water, because the pump is not waterproof. (Unless you're sitting in a hot tub and have your pump safely above water, along with your CGM sensor being above water so it can transmit to the receiver, which is also not waterproof.) You can try having your sensor on your arm and keeping it above water so it can read every now and then if the receiver is in range. That being said, again, pump is NOT waterproof so you'll need to apply shower methodology (temp to zero, suspend, take pump off) to best track your netIOB. Some people observe having the CGM, once it gets back into range and reads data after the sensor has been submerged, read falsely high. It's not a big deal for the loop (because it's looking at trends, and doses using temp basals in a conservative way), but you'll likely want to fingerstick and/or wait a while before you'll be really happy with your CGM results again. See below for another strategy that could work as well if you're much more active than usual. * **Running** - If it is a short run, (<30 minutes), I may not take the loop with me because any adjustments it would make are going to impact me after the run is done. For longer runs, I often now take my small, Edison based rig which can slip into the pocket of my hand-held running drink bottle that holds Gatorade. Before any length run, I try to make sure I don't have much positive netIOB on board (that's the biggest key to success). I also turn on activity mode (essentially a temp target of 120-140 or changing my pump targets to 120-140) an hour or so before a run and during the run; especially if I am carrying the loop during the run. For any exercise or activity or time period, if you do not choose to take your loop (or if you forget it), the loop will pick up again once you get back into range and resume. (This is why it's important to temp then suspend so it can track the amount of insulin you haven't been getting.) + +## **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?** + +Let's face it. There are some days when you just don't want to be attached to a pump. It's not uncommon for kids at diabetes camp to take a "pump holiday" where they revert to insulin injections in order to be unencumbered by the pump as they run and play and swim. Unfortunately this means a trade off - giving up the safety of closed loop control. Some have employed a strategy to be off the pump while active for extended periods but still have the advantages of closed loop assistance during less active periods of the day and overnight by using a combination of long acting basal injections in conjunction with the closed loop, in a manner similar to the following. Note that this will only work on days that you're really, really active (and as such will have significant reductions in your overall basal requirements). + + * **First -** Look at your pump and determine your 24 hour basal insulin dose. + + * **Second -** Create an alternate basal profile (Profile A or B) on your pump with settings for each time period that are half of your normal settings (we'll call this a "Half Basal" profile). You'll also want to make a "Half Basal" profile in Nightscout with the new settings, and consider establishing target glucose ranges for the entire 24 hour period that are higher than you might normally use (use values similar to what you would use for activity). For children a reasonable choice might be 140-180 but yours may be different. + + * **Third -** On the morning of the active day, record the time and give an injection of long acting basal insulin at HALF THE USUAL DOSE of your usual 24-hour basal requirement (which you determined above). At the same time switch your pump to the "Half Basal" profile you created. You'll get half the usual basal dose from the injection, and half from your pump. You should also change your blood sugar targets on your pump to whatever you decided on when you set up your alternate profile above (don't forget to change them back later). Use the + icon on Nightscout (upper right corner) and choose event Profile Switch to Half Basal (or whatever you called it) in order to assure appropriate visualization of the basal settings via Nightscout when you have connectivity. + + * **Fourth -** During periods when you're going to be very active, disconnect your pump and set an extended temp basal manually of 0.0 (choose a duration of several hours, or as long as you think you might be off the pump), and then suspend. This will allow the APS to track the negative IOB. Obviously since you're going to be off the pump (and if in the water, potentially without the benefit of CGM data as well) you'll want to remember to test more frequently. + + * **Fifth -** Hook back up to the pump for meals to bolus and/or correct for hyperglycemia, and for periods where you'll be less active during the day. Don't forget to reset a temp basal of 0.0 when you suspend again in order to track negative IOB + + * **Sixth -** At the end of the day, hook up to the pump, cancel your temp basal of 0.0 and start looping again. If you've been in the water, recognize it may take some time before your CGM data regains full accuracy, so you may still want to check more frequently. Check and make sure your pump is setting temp targets appropriately and check Nightscout to make sure all is going as you expect. You should still be on the "Half Basal" profile. + + * **Overnight -** The loop will titrate your basal up or down in response to your CGM data. The caveat is, of course, that even if it lowers your temporary basal to 0.0 you will still be subject to the effects of the dose of long acting subcutaneous insulin you took in the morning. This will render the loop somewhat less effective at avoiding hypoglycemic events, and is in part the reason that higher than usual targets for blood glucose would be appropriate. Recognize also that after intense periods of physicial activity it is likely you will be more insulin sensitive, which could exacerbate the potential for hypoglycemia. Better to be safe and run slightly higher than normal. + + * **The Next Morning -** Around 24 hours after the time you took your long acting insulin dose, switch your pump back to the normal profile, and readjust your glucose targets to your normal values on your pump. Use Profile Switch in Nightscout to switch back to your usual profile. Continue to monitor yourself somewhat more frequently until you're sure things are completely back to normal and all of the effects of the long acting insulin bolus from the prior day have resolved. Alternatively, if you're going to have several days of similar activities in a row, you could take another long acting basal dose and go at it again. Use your experience from the prior day to adjust that dose up or down slightly depending on how things went with your first day's glucose readings. + + ## **What if I want to turn off the loop for a while?**
One easy way to "turn off" the loop for a period of time so to use temp targets in your Nightscout website. You can set an wide range from -1000 to 1000 as a temp target for a period of time and it will effectively turn off the loop. What is great about this is that it is easy to do and allows you to schedule the time when you want the loop turned off (going swimming, showering, exercising, etc). You do not have to power down your device or mess with cron commands. You can also choose to leave it at home if you are going out and do not want to be looping during that time. It will start looping again when you get back into range and it can successfully read your pump and CGM data again.
+ + +## **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.
diff --git a/docs/docs/walkthrough/phase-4/advanced-features.md b/docs/docs/walkthrough/phase-4/advanced-features.md index b334f7e73..553456d54 100644 --- a/docs/docs/walkthrough/phase-4/advanced-features.md +++ b/docs/docs/walkthrough/phase-4/advanced-features.md @@ -8,8 +8,7 @@ If you choose to enable the optional advanced meal-assist feature, then after yo Like all features and steps, you'll want to carefully enable, test, and observe the outcomes of this feature. To turn this feature on, run the setup script from phase 2 and choose advanced features. -With AMA, once you enable forecast display in your Nightscout configuration (see the Nightscout documentation for the correct variables to set) you will have 3 purple line predictions in Nightscout. (Unless you have NO carbs onboard, then you will have only one purple line.) - +With AMA, once you enable forecast display in your Nightscout configuration, you will be able to see multiple purple line predictions. To do this, click the three dots next to your timeframe horizon (3HR, 6HR, 12HR, 24HR) and then enable "Show OpenAPS Forecasts". Once enabled, you will have 3 purple line predictions in Nightscout. (Unless you have NO carbs onboard, then you will have only one purple line.) * (Usually) Top line == assumes 10 mg/dL/5m carb (0.6 mmol/L/5m) absorption @@ -20,9 +19,9 @@ With AMA, once you enable forecast display in your Nightscout configuration (see ## Auto-sensitivity mode -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 advanced 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. It will then make micro adjustments to your basals. +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 advanced 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. It 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. -When you watch your loop run and Autosens is going to be detected, you might see something like this: +When you watch your loop run in the logs and sensitivity changes is going to be detected, you might see something like this: `-+>>>>>>>>>>>>+++->->+++>++>>+>>>>>>>>++-+>>>>>>>-+++-+--+>>>>>>>>>>>>>>>>>>>>>>>>>++-++++++--++>>>++>>++-++->++-+++++++>+>>>>>>>>>>>>>>>>>++-+-+-+--++-+--+++>>>>>>++---++----+---++-+++++>>>++------>>>++---->>+++++--+++-++++++++--+--+------++++++++++>>>>++--+->>>>>>>>>>++++-+-+---++++ 34% of non-meal deviations negative (target 45%-50%) Excess insulin resistance detected: ISF adjusted from 100 to 73.52941176470588` @@ -37,6 +36,13 @@ Here's what each symbol above means: "=" : BGI is doing what we expect +### Notes about autosensitivity: + +* "Autosens" works by reviewing the 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. +* 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. +* Most users will notice the changed ISF numbers in their OpenAPS pill, along with changed targets. Note that a temp target will override the autosens-adjusted target. If you do not want autosens to adjust targets, that can be turned off via a setting in preferences.json +* The reason for autosens automatically adjusting targets 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. +* Autosens is limited by the safety multipliers in preferences.json. We do not recommend widening these multipliers; but an easy way to turn "off" autosens after you've enabled it is so adjust the safety multipliers to 1. However, note that this will also disable autotune adjustments if you are running autotune. ## Eating Soon and Activity Mode (Temporary Targets) diff --git a/docs/docs/walkthrough/phase-4/autotune-ns.md b/docs/docs/walkthrough/phase-4/autotune-ns.md deleted file mode 100644 index 0de9a519b..000000000 --- a/docs/docs/walkthrough/phase-4/autotune-ns.md +++ /dev/null @@ -1,66 +0,0 @@ -# Using Autotune without OpenAPS - -[Autotune](autotune.md) is a feature created in late December 2016 and is currently in beta (early testing) mode in the oref0 dev branch. You can also see issue [#261](https://github.com/openaps/oref0/issues/261) and [#99](https://github.com/openaps/oref0/issues/99) and pull request [#313](https://github.com/openaps/oref0/pull/313) for background reading. - - -This page is currently a stub, copied from the main [Autotune](autotune.md) page. Please update it with the steps required to spin up a new cloud VM, install oref0 there, create a profile (documented below), and run autotune on retrospective data from NS. - - - -#### Phase A (Current): Running Autotune in “manual” mode on the command line - -Autotune is currently being tested by a few users on the command line. There has been some additional work to make it easier to export to Excel for review. - -How to run it: - -Run `oref0-autotune <--dir=myopenaps_directory> <--ns-host=https://mynightscout.azurewebsites.net> [--start-date=YYYY-MM-DD] [--end-date=YYYY-MM-DD] [--runs=number_of_runs] [--xlsx=autotune.xlsx]` - -If you're running this on a computer that doesn't have a myopenaps_directory, you can point it at a directory with a settings/pumpprofile.json file. An example of a too-sensitive one would be: -``` -{ - "max_iob": 4, - "type": "current", - "max_daily_safety_multiplier": 4, - "current_basal_safety_multiplier": 4, - "autosens_max": 1.2, - "autosens_min": 0.7, - "autosens_adjust_targets": true, - "override_high_target_with_low": false, - "bolussnooze_dia_divisor": 2, - "min_5m_carbimpact": 3, - "carbratio_adjustmentratio": 1, - "dia": 3, - "model": {}, - "current_basal": 1, - "basalprofile": [ - { - "i": 0, - "start": "00:00:00", - "rate": 0.1, - "minutes": 0 - } - ], - "max_daily_basal": 0.1, - "max_basal": 4, - "min_bg": 100, - "max_bg": 100, - "sens": 100, - "isfProfile": { - "units": "mg/dL", - "sensitivities": [ - { - "i": 0, - "start": "00:00:00", - "sensitivity": 100, - "offset": 0, - "x": 0, - "endOffset": 1440 - } - ], - "first": 1 - }, - "carb_ratio": 1000 -} -``` - -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). diff --git a/docs/docs/walkthrough/phase-4/autotune.md b/docs/docs/walkthrough/phase-4/autotune.md index 1dc9b52b8..8ef25b31f 100644 --- a/docs/docs/walkthrough/phase-4/autotune.md +++ b/docs/docs/walkthrough/phase-4/autotune.md @@ -1,16 +1,16 @@ -# WIP Autotune Feature +# Autotune -Autotune is a feature created in late December 2016 and is currently in beta (early testing) mode in the oref0 dev branch. You can also see issue [#261](https://github.com/openaps/oref0/issues/261) and [#99](https://github.com/openaps/oref0/issues/99) and pull request [#313](https://github.com/openaps/oref0/pull/313) for background reading. +Autotune is a feature/tool created in late December 2016 and is currently being tested within the community. You can also see issue [#261](https://github.com/openaps/oref0/issues/261) and [#99](https://github.com/openaps/oref0/issues/99) and pull request [#313](https://github.com/openaps/oref0/pull/313) for background reading. Want to pay it forward and help improve autotune? You can see [the identified issues that are known to need volunteers to help tackle here](https://github.com/openaps/oref0/projects/1). Those who are not running autotune in a closed-loop setting should use the "Phase C" instructions below. ## The difference between autotune and autosens: -Autosensitivity/resistance mode (aka “autosens”) is an advanced feature 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.) +Autosensitivity/resistance mode (aka “autosens”) is an advanced feature 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/) -Auto"tune", 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. +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. ## How Autotune works -There are two key pieces: oref0-autotune-prep and oref0-autotune-core +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:** @@ -28,149 +28,167 @@ There are two key pieces: oref0-autotune-prep and oref0-autotune-core * 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 applies a 20% limit on how much a given basal, or ISF or CSF, can vary from what is in the existing pump profile, so that if it's running as part of your loop, autotune can't get too far off without a chance for a human to review the changes. -* (FUTURE TODO: Instead of 20% hardcoded safety cap, use autosens min and max ratios.) +* 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. ### Different ways to utilize Autotune -#### Phase A (Current): Running Autotune in “manual” mode on the command line +#### Phase A: Running Autotune in “manual” mode on the command line -Autotune is currently being tested by a few users on the command line. There has been some additional work to make it easier to export to Excel for review. +If you have an OpenAPS rig and want to test autoune manually, you can do so manually on the command line. There has been some additional work to make it easier to export to Excel for review. -How to run it: +How to run it as a one-off: +* First, make sure you have the latest version of oref0: `npm list -g oref0 | egrep oref0@0.4.[0-9] || (echo Installing latest oref0 package && sudo npm install -g oref0)` +* Install jq: `sudo apt-get install jq` +* Make two copies of your profile.json, one to be the starting point for autotune, and one to provide the pump baseline for enforcing the min/max limits: `cd ~/myopenaps/settings/ && cp profile.json autotune.json && cp profile.json pumpprofile.json` +* Run `oref0-autotune --dir=~/myopenaps --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. Try 1 day first before moving on to 1 week and 1 month to better troubleshoot). -Run `oref0-autotune <--dir=myopenaps_directory> <--ns-host=https://mynightscout.azurewebsites.net> [--start-date=YYYY-MM-DD] [--end-date=YYYY-MM-DD] [--xlsx=autotune.xlsx]` +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). -If you're running this on a computer that doesn't have a myopenaps_directory, you can point it at a directory with a settings/pumpprofile.json file. An example of one (note: do NOT use this as-is; put your actual settings in) would be: -#### Example profile.json +#### Phase B: Running Autotune in OpenAPS closed loop system -``` -{ - "max_iob": 4, - "type": "current", - "max_daily_safety_multiplier": 4, - "current_basal_safety_multiplier": 4, - "autosens_max": 1.2, - "autosens_min": 0.7, - "autosens_adjust_targets": true, - "override_high_target_with_low": false, - "bolussnooze_dia_divisor": 2, - "min_5m_carbimpact": 3, - "carbratio_adjustmentratio": 1, - "dia": 3, - "model": {}, - "current_basal": 1, - "basalprofile": [ - { - "i": 0, - "start": "00:00:00", - "rate": 0.1, - "minutes": 0 - } - ], - "max_daily_basal": 0.1, - "max_basal": 4, - "min_bg": 100, - "max_bg": 100, - "isfProfile": { - "units": "mg/dL", - "sensitivities": [ - { - "i": 0, - "start": "00:00:00", - "sensitivity": 100, - "offset": 0, - "x": 0, - "endOffset": 1440 - } - ], - "first": 1 - }, - "carb_ratio": 1000 -} -``` +You can also test running autotune every night as part of a closed loop. 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. 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 is recommending changes beyond the caps, people can use this to inform whether they may want to tune the basals and ratios in those directions. -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). +You can choose to set up autotune as part of the oref0-setup script, and have it run nightly and adjust a new autotune profile. It is important to realize that 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 (e.g., steroid medication started), you may have to temporarily suspend autotune to allow loop to use your pump's adjusted basal program. +As with all new and advanced features, this is a friendly reminder that this is DIY, not approved anywhere by anyone, and bears watching to see what it does with your numbers and to decide whether you want to keep running this feature over time, vs. running it as a one-off as needed to check tuning. -#### Phase B: Running Autotune in OpenAPS closed loop system +#### Phase C: Running Autotune more easily as an average user or as a "one-off" -Autotune is in the dev branch of OpenAPS, to test running autotune every night as part of a closed loop. This means that autotune would be iteratively running (as described in 261) and making changes to the underlying basals, ISF, and carb ratio being used by the loop. However, there are safety caps in place to limit the amount of tuning that can be done at any time – by 20%, compared to the underlying pump profile. It will be tracked against the pump profile, and if over time the tuning constantly is recommending 20% (or more) than what’s on the pump, people can use this to inform whether they may want to tune the basals and ratios in those directions. +If you are not running autotune as part of a closed loop, you can still run it as a "one-off". We are actively working to make it easier for people to run autotune as a one-off analysis. Ideally, someone can run this report before their endo appointment and take these numbers in along with their other diabetes data to discuss any needed changes to basal rates, ISF, and potentially carb ratio. With the instructions below, you should be able to run this, even if you do not have a closed loop or regardless of what type of DIY closed loop you have. (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. -If you're running dev branch, you can set up autotune as part of the setup scripts, and have it run nightly and adjust a new autotune profile. +**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, though. [Read this page for more details on what you should/not pay attention to with missing data.](./understanding-autotune.md) -As with all new and advanced features, this is a friendly reminder that this is DIY, not approved anywhere by anyone, and bears watching to see what it does with your numbers and to decide whether you want to keep running this feature over time, vs. running it as a one-off as needed to check tuning. +**Note**: 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. + +**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). -#### Phase C (future/current WIP): Running Autotune more easily as an average user +**Paying it forward**: Want to pay it forward and help improve autotune? You can see [the identified issues that are known to need volunteers to help tackle here](https://github.com/openaps/oref0/projects/1). You can also create a pull request to help edit and improve this documentation. (See a "[my first PR guide](http://openaps.readthedocs.io/en/latest/docs/Resources/my-first-pr.html)" here if you haven't done a pull request before.) -We are actively working to make it easier for people to run autotune as a one-off analysis. Ideally, someone would run this report before their endo appointment and take these numbers in along with their other diabetes data to discuss any needed changes to basal rates, ISF, and potentially carb ratio. With the instructions below, you should be able to run this, even if you do not have a closed loop or regardless of what type of DIY closed loop you have. (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). +**Step 0: Decide where to run Autotune** +* The easiest way to run autotune from a Windows machine if you are unfamiliar with programming will be to create a Linux VM. If you don't already have access to a physical or virtual machine running Linux, you can either create a Linux VM locally using software like [VirtualBox](https://www.virtualbox.org/wiki/Downloads), or in the cloud with your favorite cloud service. +* Mac users may simply run Autotune locally on their Mac, by skipping down to Step 1b below. -Requirements: You should have Nightscout BG and treatment data. If you do not regularly enter carbs (meals) into Nightscout, autotune will try to raise basals at those times of days to compensate. However, you could still look at overnight bassal recommendations and probably even ISF recommendations overall, though. +**Step 1a: Create a Linux VM** + * 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-trial/) (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. + * We recommend some form of Debian distro (Ubuntu is the most common) for consistency with the Raspbian and jubilinux environments we use on the Pi and Edison for OpenAPS + * If you have no experience an easy way to start is the VirtualBox as VM and Ubuntu as Linux OS. Step-by-step setup instructions can be found here: https://www.youtube.com/watch?v=ncA85gRAJxk + * 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'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). + * Now do this: `curl -s https://raw.githubusercontent.com/openaps/docs/master/scripts/quick-packages.sh | bash -`. If the install was successful, the last line will say something like: `openaps 0.1.5 (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. -Note: 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. +**Step 1b: Prep your Mac** +* MAC USERS: Follow these steps instead of 1a 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/introduction/understand-this-guide.html#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)"` -**Step 1: Create VM** -* You'll need a Linux VM for now, until Autotune is updated to [support Mac OS X](https://github.com/openaps/oref0/issues/327) or Windows. You can either create a Linux VM locally using software like [VirtualBox](https://www.virtualbox.org/wiki/Downloads), or in the cloud with your favorite cloud service. -* For cloud servers, free options include [AWS](https://aws.amazon.com/free/) (free for 1 year) and [Google Cloud](https://cloud.google.com/free-trial/) (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. -* We recommend some form of Debian distro (Ubuntu is the most common) for consistency with the Raspbian and jubilinux environments we use on the Pi and Edison for OpenAPS +Mac install commands: -**Step 2: Install oref0 on the cloud VM** -* After VM setup, do this: `curl -s https://raw.githubusercontent.com/openaps/docs/master/scripts/quick-packages.sh | bash -`. If the install was successful, the last line will say something like: `openaps 0.1.5 (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. -* Install the jq package: `sudo apt-get install jq` -* Install the latest dev version of oref0 by running: `sudo pip install git+https://github.com/openaps/openaps.git@dev` -* If that works, move on to Step 3. If that doesn't work: - * Pull/clone the latest oref0 dev branch by running: `mkdir -p ~/src; cd ~/src && git clone -bdev git://github.com/openaps/oref0.git || (cd oref0 && git checkout dev && git pull); cd` - * And manually install the oref0 dev branch. at this stage `cd ~/src/oref0` and `git checkout dev` and `sudo npm run global-install` might be the easiest way to do that. (Copy and paste and run those three 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 2: Install oref0** +* Install the latest version of oref0: `npm list -g oref0 | egrep oref0@0.4.[0-9] || (echo Installing latest oref0 package && sudo npm install -g oref0)` **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. +* 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": 3, -"dia": 4.5, -"basalprofile": [ -{ -"i": 0, -"start": "00:00:00", -"rate": 0.5, -"minutes": 0 -} -], -"isfProfile": { -"sensitivities": [ -{ -"i": 0, -"start": "00:00:00", -"sensitivity": 43, -"offset": 0, -"x": 0, -"endOffset": 1440 + "min_5m_carbimpact": 3, + "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 } -] -}, -"carb_ratio": 14 -} ``` -Make sure to adjust these settings to match yours: - * DIA - * 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 - * "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. -* D. Create a pumpprofile.json that is the same as your settings.json. On the command line run: `cp profile.json pumpprofile.json` -* E. Do a third file from the command line: `cp profile.json autotune.json` + +* 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.azurewebsites.net --start-date=YYYY-MM-DD` * ^ Sub in your Nightscout URL. * 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). * 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. -[Click here to see an example output file from autotune](https://diyps.org/wp-content/uploads/2017/01/OpenAPS-autotune-example-by-@DanaMLewis.png). +#### Why Isn't It Working At All? + +(First - breathe, and have patience! Remember this is a brand new tool that's in EARLY testing phases. Thanks for being an early tester...but don't panic if it doesn't work on your first try.) Here are some things to check: + +* 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. +* 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. +* 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. +* 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). + +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.md). diff --git a/docs/docs/walkthrough/phase-4/bluetooth-tethering-edison.md b/docs/docs/walkthrough/phase-4/bluetooth-tethering-edison.md new file mode 100644 index 000000000..45824f454 --- /dev/null +++ b/docs/docs/walkthrough/phase-4/bluetooth-tethering-edison.md @@ -0,0 +1,199 @@ +# Bluetooth tethering on Edison (optional) + +Your cell phone can act as a mobile "hotspot" to allow your rig to access the internet. This is an important part of keeping your rig looping, if you don't have offline BG data setup, as you move around areas without known wifi networks. + +A few things to know about using your phone's hotspot feature: + +1. Hotspot is a feature of your phone AND cell phone provider. Please check with your cell phone provider and your service contract to confirm that hotspot feature is enabled and BT tethering is enabled. +2. Hotspot, when activated, uses your cell phone's data. Know what your cell phone plan data limits are and consider if you want to change/update based on your frequency of hotspot use. You can get an estimate of cell data use by resetting your cell data use, at the beginning of the day, within your phone. +3. A device (like your rig) can be connected to your phone's hotspot in one of three ways; wifi connection, BT tether, or USB plug: + + * **wifi connection**: You need to set up your wpa_supplicant list to include your hotspot information; network name and password. The wifi signal for the hotspot is not constantly broadcast by your phone, however. So when you want to use the wifi connection to your hotspot (for example, you are leaving your home wifi network and traveling), you will need to manually toggle your hotspot on so that the phone will broadcast a wifi signal for the rig to connect to. The other consideration is that since this is a wifi connection, the rig will not automatically disconnect when you come into one of your other known wifi networks. You will have to remember to manually disconnect (toggle hotspot off), if you do not wish to continue using cell data when you are home. Hotspot done by wifi connections also use more phone battery than a BT tether connection. + + * **BT tether**: BT tethering (also known as BT PAN *Personal Area Network*) requires your phone and rig to be BT-paired before they can connect (that's what this section of the docs is specifically about). The advantage of connecting to your hotspot via BT tether is that it will happen automatically. You do not have to remember to toggle hotspot. Simply leave your hotspot toggled on as usual, leave the house, and within a few minutes (or sooner) your rig will BT tether to the hotspot. (Screenshot below shows what you'll see in your network logs as you move from known wifi network to BT tether. Oref0-online will automatically find BT tether and connect.) Your rig will then use your cell phone as its internet connection. When your rig comes back into a known wifi network, it will automatically drop the BT tether and connect with the wifi network. + + * **USB plug**: You can plug devices into your cell phone to use hotspot. However, the phone would pull battery power from your rig and would drain your battery fairly quickly. This is not a recommended connection method for openaps use. + +### Pros and Cons (and usability) of Wifi Hotspot vs. BT Tethering Hotspot + +* If you choose **wifi hotspot**, you must manually turn it on; wait for the rig to connect; and when you get home, you must manually turn it off or your rig might not switch to your home wifi (depending on your settings in wpa_supplicant.conf). This option also consumes more battery on the phone. +* If you choose to enable **BT tethering**, it takes more work to set it up, but it will automatically pick up when your rig loses wifi (i.e. walking out the door) without you even having to pull your phone out of your pocket; it automatically allows the rig to pick back up on wifi when it finds a known wifi network; and it consumes less battery on the phone compared to your wifi hotspot. + + + +### Phone selection for BT Tethering + +* Certain phones don't work well using bluetooth tethering with OpenAPS. Various users have experimented, and the list below shows those that have been found to work okay, those that don't and those with variable effectiveness. If you have something that is not on the list, please feel free to add it. + +
| Cellphone | Works with Bluetooth Tethering? | Issues/Experiences with BT | Use with xDrip/xDripAPS and Dexcom G5 + |
|---|---|---|---|
| LG Nexus 5X with Android 7 | Yes | Supports tethering to both Wifi and Cellular network. No issues switching. | Works well with Dexcom G5 and xDrip. No issues with compatibility. 90%+ capture rate. + |
| Google Pixel with Android 7 | Yes | Supports tethering to both Wifi and Cellular network. No issues switching. | Works well with Dexcom G5 and xDrip. No issues with compatibility. 90%+ capture rate. + |
| Sony Xperia Z5 Compact with Android 7 | Yes | Works with tethering for network access. It regularly disconnects from the rig (which doesn't seem to affect data flow) and roughly every 24-36 hours this results in complete loss of connectivity and requires a full reboot of the rig and the phone. Doesn't work well with phone swapping between Wifi and mobile - causes BT dropouts that require a reboot of the rig. | No issues running xDrip/xDripAPS alongside the tethered connection. Achieves 90%+ packet collection from Dexcom G5. + |
| Xiaomi Redmi 4 with MIUI 8 (Android 6) | No | Tethering can be set up, but it drops regularly requiring rig reboots. When phone switches between Wifi and cellular signal requires rig to be rebooted. | Significant packet drops and data becomes almost unusable. + |
| Xiaomi Redmi 3 with MIUI 6 (Android 5) | Yes | No issues seen when tethered to cellular network. Doesn't allow tethering to wifi. | Works fine with Dexcom G5 - 90% collection rate. + |
| Samsung Galaxy S6 (Android 7) | Yes | Tethering to rig and cellular works okay. No data on swapping between cellular and wifi connections. | Use with Dexcom G5 and rig not effective. Significant packet loss. + |
| Samsung Galaxy Junior | Yes | Phone tethering switching between wifi and mobile not elegant and causes some issues | Difficulties found when using xDrip with the OpenAPS tethering. Packet loss occurs. + |
| iPhone | Yes | Users have experienced various levels of success with the iPhone bluetooth tethering and when the rig switches between wifi and BT | Not Applicable. Experimental version of Loop to do something similar doesn't yet have feedback. + |
| Acer Phone | No | Many data drops on the bluetooth connection for rig. Recommended to avoid. | xDrip compatibility is poor - numerous drops throughout the day. + |
| Samsumg Galaxy S7 Edge (G935F) Android 7.0 | Yes | Excellent BT tether using apps 'Bt AutoTether' and 'BT Tether' | xDrip+ with G5 > 95% capture. + |
+You're all done! (For now. In the future, studies accessing the OpenAPS Data Commons may choose to send additional surveys to collect things like various QOL metrics, which you can choose to participate in or not.) Thanks for donating your data! + +* **How much data should I donate?**
+You can donate as much as you want, or as little as you want. However, many of the studies are interested in looking at before/after looping - so at a minimum, I'd suggest a month or two before you started looping. If you don't have any reason to limit what you share, I'd suggest sharing all of your Nightscout data to make it the most useful to all potential researchers. (This means don't bother to put a start or end date in the Nightscout Data Transfer tool; just put in your URL and hit upload.) + +* **Who is accessing the data?**
+Any project from OpenHumans accessing the OpenAPS Data Commons should be listed on the page. We'll also keep a list going (probably here, on the [OpenAPS.org Data Commons page](https://openaps.org/outcomes/data-commons/)) to reflect the different studies using the data. + diff --git a/docs/docs/walkthrough/phase-4/ifttt-integration.md b/docs/docs/walkthrough/phase-4/ifttt-integration.md index 391ab8db6..e61e44e74 100644 --- a/docs/docs/walkthrough/phase-4/ifttt-integration.md +++ b/docs/docs/walkthrough/phase-4/ifttt-integration.md @@ -1,36 +1,104 @@ # IFTTT Integration -Want to be able to set or cancel temp targets from your Pebble, Alexa, or anything supports IFTT? You need an IFTTT.com and Maker account. Check it the YouTube Video below to see some sample integrations: +Want to be able to set or cancel temp targets from your phone, Pebble, Alexa, or anything that supports If This, Then That (IFTTT)? Check out the YouTube Video below to see some sample integrations (click on the watchface photo to start video):
-## Prerequisites
+## IFTTT Setup for phones
-* Get an IFTTT.com account
-* Make sure you have a [Maker account](https://ifttt.com/maker)
-* Find out what your NS hashed secret key is by running the command to find out: `nightscout hash-api-secret