Offline looping - aka, running OpenAPS without internet connectivity

There are a number of ways to have an “offline” OpenAPS rig, and numerous ways to monitor offline (see the monitoring section for information about monitoring offline). Offline refers to situations where your rig moves into an area where it does not have internet access (i.e., the rig does not have a known wifi network available and the cell phone used with the rig does not have cell coverage/hotspot available). By setting up one of these offline solutions, your rig can still loop while in an offline area. Depending on the setup, the opportunities to visualize or monitor the loop actions (e.g., check what temp basal is actually being set) may vary until you can get back into an online area.

Offline looping

Medtronic CGM users

Medtronic CGM users can, by default, automatically loop offline because the rig will read CGM data directly from the pump.

Note about recovery from Camping Mode/Offline mode for Medtronic CGM users:

If you have been running offline for a significant amount of time, and use a Medtronic CGM, you may need to run

openaps first-upload

from inside your openAPS directory, before your loop will start updating correctly to your nightscout site.


Dexcom CGM users

Dexcom CGM users have a few different alternatives to retrieve blood glucose values locally for offline use. The options to choose from are:

  1. For android users, you can use xDrip or xDrip+. NOTE: All active development is being done on xDrip+. The details for setting up this configuration are described in the section below for xDrip offline.

  2. For iPhone users, you can set up a modified Loop app to bring data in locally. The directions for this configuration are provided in the section below for local, offline BGs using Loop app.

  3. EASIEST: For either Android or iPhone users, you can plug the CGM receiver directly into your rig via USB. This will pull BGs into the rig directly from the receiver and be used for looping. If you are a G4 user, this will also bring RAW BG data into the rig during sensor restarts or ??? times. The rig will loop using RAW BGs so long as the BG value is under 150 mg/dl. A few notes about how to make the direct-receiver configuration work:

    • Explorer boards built prior to late January of 2017 are not always working well/automatically with a CGM receiver plugged in. These boards can be identified by looking to see if they say “2016” on the board’s label tag, as shown in the photo below. The boards can be fixed to use a CGM receiver by making a single trace cut, but doing so will disable the board’s the ability to re-flash your Edison. Please make sure you have a second Explorer board or another base block or breakout board that you can use to re-flash the Edison if needed before considering this modification. For more details, see this issue, and if you decide to make the cut, see this document for details on how to cut the copper trace from pin 61 of the 70 pin connector. Cut in two places and dig out the copper between. Cut by poking a razor point in. Avoid the narrow trace above the one being cut.
    • Explorer Boards that shipped at or after the end of February 2017/first week of March 2017 should enable users to simply plug in the CGM receiver to the OTG port, and a USB battery into the UART port, in order to run offline and pull BGs from the receiver. Those boards will have a label of v1.2 2017.

    Old explorer board version

  • The order of the cables and ports is important. The OTG cable must be plugged into the OTG port on the Explorer board. There are two kinds of OTG cables; (1) both ends are micro-USB like the one you can order here or (2) one end is USB and one end is micro-USB like the one you can order here. Both will work, but if you have the second kind, that cable must be the one plugged into the rig directly, and the other non-OTG cable must be plugged into the receiver (as shown in photo below). That port is labeled on the underside of the port, it is the one closest to the lipo battery plug. A USB battery or wall charger must be plugged into the UART port to supply sufficient voltage to the OTG port (the lipo battery alone is not enough to power the OTG port).

OTG configurations

  • If you are using this configuration for G4 receivers and (1) are online and (2) want to see RAW BGs in NS, then you must remember to add rawbg to your ENABLE line in your Heroku/Azure settings. You will also have to go to your Nightscout site’s settings and select “always” from the Show RAW BG options. You will also have to select g4-raw (if on master branch) or g4-upload (if on dev branch) as the CGM type in the loop setup script.

xDripAPS for offline BGs and looping for Android users

Note as of 1/26/17: The below documentation is WIP and needs additional testing.

Do you use OpenAPS and the xDrip/xDrip+ Android App? Until now this required an internet connection to upload your xDrip/xDrip+ Android App CGM data to an online Nightscout instance (the OpenAPS community recommends utilizing Heroku). Then your data was downloaded to your OpenAPS rig for use in your online loop. The xDripAPS code resides on your OpenAPS rig and allows the direct transfer of xDrip/xDrip+ Android App CGM data to your OpenAPS rig without an internet connection. xDripAPS creates an offline OpenAPS rig which utilizes a “local” or “personal” network (WiFi hotspot or Bluetooth PAN tethering) for direct communication between the xDrip/xDrip+ Android device and the OpenAPS rig. Data which is ‘missing’ from Nightscout will be uploaded when the OpenAPS rig regains internet connectivity.

The OpenAPS community recommends an Explorer Board / Intel Edison rig, but xDripAPS also works with a Raspberry Pi rig.

Configuring an offline OpenAPS rig is quite easy because the OpenAPS setup script (oref0-setup.sh v0.4.0 and later) supports an automated installation of xDripAPS and dependencies. When running the OpenAPS setup script you simply specify “xdrip” (without the quotes) when promped to specify a CGM type (e.g. MDT, G4). Alternatively, manual installation instructions can be found at the bottom of this page.

Overview of xDripAPS

With xDripAPS, the flow of data is as follows -

(1) CGM transmitter –> (2) xDrip/xDrip+ Android app –> (3) OpenAPS rig (e.g. Edison) –> (4) Nightscout

  1. Usually a Dexcom G5, or G4 plus xDrip wireless bridge.
  2. Either xDrip or xDrip+ can be used. In the app, the REST API Upload feature is normally used to upload CGM data to Nightscout. Instead, we use this feature to upload to xDripAPS on your OpenAPS rig (further details below).
  3. Your OpenAPS rig - usually a Raspberry Pi or an Intel Edison.
  4. The xDrip or xDrip+ app is now uploading your data to xDripAPS on your OpenAPS rig rather than to Nightscout. OpenAPS will now upload your CGM data to Nightscout as well as treatments, pump status, etc. So your Nightscout site will still be updated. Note that it will take a couple of minutes longer for CGM data to reach Nightscout, compared with when uploading directly from xDrip or xDrip+

Setup Steps (using oref0-setup.sh script)

Setting up your OpenAPS rig

Install OpenAPS as per the documentation. While running the oref0-setup script you will be prompted to specify a CGM source. Enter “xdrip” (without the quotes). The setup script takes care of the rest! Follow the remainder of the setup script as normal.

Connect your Android phone and your OpenAPS rig

For the xDrip/xDrip+ app on your Android phone to be able to send CGM data to xDripAPS on your OpenAPS rig, they both need to be connected to the same “personal” network. Note that an internet connection is not required - this solution allows you to loop without internet connectivity.

There are two approaches for establishing a “personal” network between your phone and your OpenAPS rig. The first is to run a WiFi hotspot on your phone and connect your OpenAPS rig to the WiFi network your phone exposes. This is the easiest option, but there are two drawbacks - it drains your phone battery quickly, and some phones cannot connect to a normal WiFi network while the WiFi hotspot is enabled (it can connect to the internet via 3G/4G when coverage is available).

The other option is to enable bluetooth PAN tethering on your phone and have your OpenAPS rig connect to it. This does not drain the phone’s battery as quickly and means that the phone can still connect to a normal WiFi network for internet access when available (and to 3G/4G networks when WiFi is not available). I use this approach 24/7 - my OpenAPS rig is permanently tethered to my Nexus 6P phone. I can get a full day of phone usage without running out of battery, unless I make a lot of calls or have a lot of screen-on time.

Instructions on both approaches can be found in the main OpenAPS documentation.

Configuring the xDrip/xDrip+ Android app

First, determine your OpenAPS rig’s IP address within your “personal” network. If you can open a terminal session to your rig via serial, then ifconfig wlan0 (when using the WiFi hostpost option) or ifconfig bnep0 (when using bluetooth tethering) will display your IP address. Alternatively, you can use an Android app - there are lots of “Network IP Scanner” apps in the Play store. The Hurricane Electric Network Tools app works with both the WiFi hotspot and BT tethering options.

Next, open xDrip or xDrip+ and navigate to Settings > Cloud Upload > API Upload (REST). In the Base URL setting, configure the following URL

http://<nightscout_api_secret>@<rig_ip_address>:5000/api/v1/

A few notes to clarify:

  • enter “http://” NOT “https://
  • <nightscout_api_secret> is the plain-text API secret used when creating your online Nightscout instance.
  • <rig_ip_address> is the IP address of your OpenAPS rig assigned by your WiFi, WiFi hotspot, or Bluetooth PAN tether connection. It will usually take the form of: 192.168.xxx.xxx.

REST API Upload setting

If using xDrip+ navigate to Settings > Cloud Upload > MongoDB and uncheck the “Skip LAN uploads” option. Do not turn on the “Enable Nightscout Mongo DB sync” option. Next, navigate to Settings > Cloud Upload > API Upload (REST) and uncheck the “Skip LAN uploads” option. NOTE: if you don’t have these options, update to a recent version of the xDrip+ app. These options were added to a nightly build in December 2016.

Advanced Options
  • Use both API Upload (REST) and MongoDB
    • You can use both the API Upload (REST) and the MongoDB upload options. This has the advantage of immediately showing your BG values in Nightscout and allows OpenAPS to continue to get BG values if the link ever fails between your xDrip/xDrip+ uploader phone and your rig. One disadvantage to this method is that you will have duplicate entries in your Mongo database.
  • Enter multiple REST URLs
    • If you are needing to constantly switch between two or more “personal” networks, you would have to edit the Base URL each time with the new IP address. To simplify this process, multiple URLs can be added to the REST API Upload Base URL setting, and xDrip/xDrip+ will attempt to upload to each URL. NOTE: the URLs must be “space” deliminated. For example:
http://<nightscout_api_secret>@<rig_ip_address1>:5000/api/v1/ http://<nightscout_api_secret>@<rig_ip_address2>:5000/api/v1/

Manual installation steps