iAPS (previously called FreeAPS X)

OpenAPS Pills and Forecast Display

After adding the plug-ins as discussed below, you also need to enable the display of these items. Under the Hamburger Menu, scroll down and select the desired options and then hit Save.

Show Plugins

• check the box by OpenAPS

OpenAPS

• optional to check the box by Color prediction lines (otherwise, they are the traditional purple)

On the main Nightscout display, click the three dots next to your timeframe horizon (2HR, 3HR, 6HR, 12HR, 24HR) and then enable “Show OpenAPS Forecasts”. Don’t see this option? Check and make sure you added this variable and that your iAPS app has successfully run.

Nightscout OpenAPS Specific Variables

Review the Nightscout Documentation on OpenAPS specific variables to add to an existing Nightscout site. Note the different colored lines for different predictions are already part of Nightscout (as of ver 14.2.2).

Transitioning from Loop

DIY Nightscout:

Log into your Heroku account, and tap Settings/Reveal Config Vars.

Make the following changes (copy and paste the values between the ” “). The first few rows are if you want Share to feed your Nightscout site. You can also choose to upload glucose for iAPS. The openaps must be present in the ENABLE line and should be added to SHOW_FORECAST and SHOW_PLUGINS.

Some of the config vars above may already exist, while others may need to be added. To edit an existing config var, use the pencil symbol. To add a config var, scroll to the last row and use the blank config var. Click enter when you’re done.

• Discord Channel: https://discord.gg/32VCtN3tMF

THIS IS IMPORTANT – USERS NEED TO UNDERSTAND HOW THE ALGORITHM WORKS TO USE IT SAFELY!

iAPS uses the original JavaScript files of oref0/oref1 and provides a user interface (UI) to control and set up the system.

Translation:

The internal decision making of iAPS matches that of OpenAPS but the “rig” discussed in the OpenAPS documents is replaced by the iPhone and (if needed) RileyLink compatible device.  Selection of Preferences, Settings and Meal Entry is done locally with your iPhone; you do not need to edit json files as discussed in the OpenAPS documents. Some remote entry via Nightscout is still possible.

• Thoroughly read the OpenAPS documentation site to understand how the algorithm works. 
• Read the Understanding How OpenAPS works section
• Play close attention to Preferences & Safety Settings section
• Pay close attention to the Autosens section
• Pay close attention to the Autotune and Understanding Autotune sections
• Pay close attention to the oref1: SMB and UAM section
• These two links to posts on diyps dot org are found among the pages just listed, but here’s another chance to read them:
  • Introducing oref1 and Super Micro Boluses (SMB)
  • Unannounced Meals

These instructions are slanted towards Loop Users and point to some of the LoopDocs pages.

Even if you are an experienced Loop user, plan to take this a step at a time – the algorithm, interface and displays are very different from Loop.

The figure below is the initial screen (other than the disclaimer screen) that you see once you build iAPS.

Note that these graphics are older and from the original ivalkou repository implementation.

There are different features and layout for iAPS.

• The main iAPS screen is shown on the left and the Settings Screen on the right
• The icons at the bottom of the main screen in Open Loop are, from left to right, Carbs, Temp Target, Bolus, Manual TB, Settings
• The Manual Temporary Basal icon is only present when the Setting for Closed Loop is disabled

Preferences

You should tap on Preferences and adjust Glucose Units to mg/dl if that is your system of units.

Otherwise, please read the Initial Preferences and Advanced Preferences before modifying preferences from the defaults.

Pump

The pump choices are Medtronic, Omnipod, Omnipod Dash and Simulator. Please build the simulator first to learn the menu structure and user interface.

STOP: Do not proceed with a real pump until you’ve worked with the simulator and stepped through all the links about OpenAPS. You are responsible for doing your own training.

When you do add a real pump consider Rufus the Bear.

To switch from the simulator to a real pump, tap on Settings, Insulin Pump Simulator, scroll to the bottom of the screen and tap Delete Pump and then add your pump.

Note that all the changes you’ve made with the simulator will still be there when you add a real pump. (Graphic under Initial Preferences shows the default values.)

• If you left preferences at the default values and have entered realistic values under settings, you can just delete and add a pump
• Check to make sure all your settings and preferences are reasonable – those basal rates will be loaded to the pump when you add it and for Medtronic, the CR, ISF and Delivery Limits will be loaded as well
• If you want to restore all settings and preferences to the default, consider deleting the app completely and building fresh

STOP: Do not proceed with a real pump on your body until you have completed reading about OpenAPS and understand the determine-basal logic.

When ready to attach a real pump, the pump menus are identical to those from Loop 3. These LoopDocs pages may be helpful:

• Adding or Changing Pump Type
• Omnipod and Omnipod DASH
• Medtronic

Nightscout

If you want to have iAPS information show up on your Nightscout site, be sure to select Allow Uploads in your CGM app.

If you are using Nightscout as a source of CGM data:

• Assuming you configured your Nightscout site as detailed earlier, all that is required for this menu item is to enter your URL and API-secret
• Make sure there is no trailing / in the URL
• The box for Use Local Glucose Server should not be checked

If you are using Spike or Diabox, you must also do this

• Check the box for Use Local Glucose Server
• Set the port of a local server. Spike – 1979, Diabox – 17580

Pump Settings

This is where max basal and max bolus rates are set.  To save the changes in iAPS, you must tap Save on Pump.  For Medtronic pumps, this copies these limits to the pump.  For all pumps, these limits are checked by iAPS as part of the determine-basal logic.

Basal Profile

Enter the basal profile you intend to use. Tap Save on Pump when done.

The scheduled rates on your pump match these settings and if you return to Open Loop, these will be the settings used.

Note – once Autotune is in use and enabled, the Autotune basal values will be used by iAPS, but they are NOT copied to your pump.

Insulin Sensitivity

Enter the Insulin Sensitivity number you intend to use as a starting point – a single number is preferred for iAPS (OpenAPS).

As iAPS monitors your actual blood glucose response to entered carbs, a modified sensitivity shows up (Autotune – not on by default, see Autotune below) and (Autosens enabled by default).

Carb Ratios

Enter the Carb Ratio number you intend to use as a starting point – a single number is preferred for iAPS (OpenAPS).

As iAPS monitors your actual blood glucose response to entered carbs, a Calculated Ratio shows up (Autotune – this is not used by default, see Autotune below).

Target Ranges

Enter the Target Range(s) you prefer.

Autotune

This menu allows you to run Autotune.  You can choose whether to use the Autotune values or just review them (default is to just review them).  You should be comfortable with the Autotune results before modifying default preference values discussed in Advanced Preferences.

If you follow along with the OpenAPS documentation links provided above, the items highlighted in red, solid-lined boxes are the ones that should be adjusted to configure your settings with iAPS.

Note that the values shown in the graphic are the default values.  You can use this for reference if you want to compare to the values on your system to the default values.

These are the parameters associated with the oref0 algorithms (UAM and SMB are not yet enabled). It is strongly recommended that you run in this mode long enough to ensure your settings provide good glucose control with limited lows and highs.

Note that Autosens is always enabled with the default range AutosensMin = 0.7 to AutosensMax = 1.2. Typically this should be left at the default values, but if you should choose to limit Autosens, modify one or both of the values. Setting both to 1.0 effectively disables Autosens.

First Set of Modifications:

• Set Glucose Units to your preferred units – if you entered values in the settings screens using the wrong units – go back and fix them now
• Select the insulin curve for the insulin you use in your pump
• Modify MaxIOB – leaving it at 0 units makes OpenAPS a low-glucose suspend system – follow the directions found here for selecting the Max IOB setting
  • Delivery Limits: Max Bolus limits manual bolus per interaction
  • maxIOB limits automated delivery of insulin via Temp Basal or SMB; it does not regulate how much insulin can be delivered by manual bolus
• Configure the Bolus Increment to match the minimum value available for your pump

Medtronic Pump

The location of this preference is not highlighted on the graphic, but if you are a Medtronic Pump user who is bothered by the alert at the top of each hour if a Temp Basal is set, you may want to slide the Skip Neutral Temps setting to be enabled.

Instead of a link, copying the text from OpenAPS docs:

In order to reduce notifications at the top of the hour, it will also attempt to cancel temp basals (unless BG or minGuardBG is below threshold and a zero-temp is needed) prior to the top of the hour. Normally a new temp basal will be set (if still needed) after the top of the hour, but that may be delayed if the rig has issues connecting to the pump. People who want to minimize the ‘on the hour’ temp basal notification beeps/vibrations may choose to accept that risk and choose to set skip_neutral_temps to true.

The items outlined in blue dashed lines in the previous graphic are items you may want to modify starting out. The Recommended Insulin Fraction is highlighted, but that should only be adjusted once you understand the ways meals are handled.

If you used Overrides in Loop, you’ll want to enable Exercise Mode.

The exercise “override” for OpenAPS differs from Loop in that only basal rates and ISF are modified – CR is left unchanged.

Note that Exercise Mode is a synonym for high_temptarget_raises_sensitivity.

• When enabled, a temp target > 105 mg/dL high temp target adjusts the sensitivityRatio for exercise_mode
• Sensitivity for iAPS is  calculated from the mid-point of the temp target range value minus 110 mg/dl referenced to the Half Basal Exercise Target value
• If the Half Basal Exercise Target is left at 160, and you set a temp target of 120 mg/dl, your basal rate will run at 75% and your ISF will be multiplied by 1.33 (e.g., 1/0.75)
• Temp Target of 120 = 75%; 140 = 60% sensitivity; 160 = 50% sensitivity

Using the Temp Target icon on the main iAPS screen, you can configure some Exercise and PreMeal preset targets. You will want to use PreMeal as part of your meal bolusing protocol as discussed in Meals.

In the graphic below, the items highlighted with grey dashed boxes may have been adjusted during the early days when you tested all your settings.  See Initial Preferences.

Note that the values shown in the graphic are the default values.  You can use this for reference if you want to compare to the values on your system to the default values.

Please make sure you understand Optimizing Your Settings before progressing.

After you’ve successfully run with iAPS and adjusted settings and run Autotune, you can start to enable the items that control UAM / SMB aka oref1.  Please follow the Understanding SMB and UAB before adjusting these settings.

• One general observation is that your CR, and possibly ISF, setting may need to be made more aggressive (lower the number). A fair number of former Loopers have noticed this change when they transitioned over to iAPS
• In general, basal rates seem to stay fairly consistent coming from Loop, provided your rates were fairly accurate to start with.
• Ensure you have the proper Bolus Increment setting for your pump (see Initial Preferences).
• If you follow the OpenAPS docs, you will leave most of  your preferences at their default values to ensure your settings are correct as discussed in Initial Preferences
  • You will want to modify MaxIOB which defaults to 0 units – this makes OpenAPS into a low-glucose suspend system
  • Please follow the directions found here for setting Max IOB setting
  • Delivery Limits: Max Bolus limits manual bolus per interaction
  • maxIOB limits automated delivery of insulin via Temp Basal or SMB; it does not regulate how much insulin can be delivered by manual bolus
• Once you’re ready to progress, follow the OpenAPS docs as you turn on the more advanced settings discussed in Advanced Preferences
  • Keep the default Max SMB Basal Minutes and Max UAM SMB Basal Minutes to start
  • Gradually increase these after some observations of a few meals (by no more than 15 min increments each time, then observe)

If you are coming to iAPS from Loop, the bolusing strategy for iAPS is different so plan to spend some time changing your habits.

Please read Users Transitioning from Loop first (even if you have never used Loop); you need the knowledge found there.

The quantity labeled Insulin required is discussed in this section on the determine-basal logic page.

Terminology

The graphic below shows iAPS in use after SMB and UAM are enabled. These were turned on only after settings were tested.

In this case, breakfast was ready “too soon”. I was late with my PreMeal Temp Target and food was prepared faster than my normal prebolus time.  Despite these shortcomings, iAPS handled it – this meal was completely hands-off after the prebolus.

The items shown on this graphic have abbreviations across the bottom of the main iAPS screen.  The legend added to the graphic spells out the names used in the OpenAPS documentation for these quantities.  Links are provided below for each quantity.

Explanation of Quantities Plotted on iAPS Screen:

• BG = Blood Glucose values from your CGM
• For these links, you will need to click on the arrow to open up the explanation
  • IOB = IOBpredBGs
  • ZT = ZTpredBGs
  • COB = COB predBGs
  • UAM = UAMpredBGs
• arrow = eventualBG

Meal Entry

Always try to use an Eating Soon temp target for about 60 min before you want to eat your meal.

• This target should be low enough to have an impact on getting some insulin on board
• Example, if your usual target is 100, set your eating soon target to 80

The calculation of Insulin required, which iAPS shows in the Enact Bolus screen, is not a bolus calculator.

Future dating (time stamping) of Carbs is not required for iAPS; it’s OK to enter carbs when you prebolus.

For iAPS, a good place to start, once your settings are fairly solid, is to initiate a prebolus for your food for about 60% to 75% of Carbs/CR

The balance of the insulin needed will be provided by Temp Basal (initial settings) or SMB and Temp Basal (once advanced settings are configured).

Rather than pull out a calculator:

• One pre-bolus strategy might be to form a little scale for yourself like the following (you should form your own based on your needs and CR):
  • Small meal, 20g or less = 2U
  • Med meal, 20g – 40g = 3U
  • Large meal, 40g or more = 4U
  • Note:  Your scale will be based upon your carb ratio and the % of upfront bolus that you prefer.  For example, with a carb ratio of 10, the rates above would provide a 100% upfront bolus for 20g, a 75% upfront bolus for 40g, and a 67% upfront bolus for 60g
• With an appropriate pre-bolus and settings, you should not need to issue manual boluses after your meal
  • Try to let iAPS do its job
  • This may be a difficult task coming from Loop!
  • If you used automatic bolus with Loop or the FreeAPS fork, you’ll find Temp Basal a little slower than you are used to, but it’s worth taking the time to test and adjust your settings before you turn on SMB/UAM
  • Observe for a few days and make adjustments as needed so that you won’t have to issue correction boluses

Copied from Telegram Discussion Group (source: Tim Street)

Note that Tim’s comments are primarly directed at people who have progressed to turning on UAM/SMB features.

• Settings are generally not directly transferable from Loop to oref1. You’ll generally find that CR tends to being a slightly lower value, and ISF may also.
• Autosens is the dynamic adjustment of basal and ISF based on the most Conservative estimate of looking back at the last 8 and 12 hours.
  • Information about Autosens, meals etc can be found here: http://www.apsguide.info
• Autotune is a one off that runs once daily to review and renew basal, ISF and CR based on input data for the previous day.
• Scheduled is just what’s on the pump.
• For meals, you will need to bolus ahead of the meal (unless using ultra rapid insulins) and usually 60%-75% of meal bolus.
• The function Ivan has built to give a bolus is not a bolus calculator in the same way that Loop has one, so don’t expect it to give you enough insulin.
• What Ivan has done is to take the insulinReq calculation and use it to provide a bolus estimate. The insulinReq value is calculated based on a number of prediction curves, and when carbs are added, it mediates the effect of carbs with the other curves. So the insulinReq value is not necessarily as much insulin as the normal meal bolus would be (it’s conservative for safety reasons). It’s not a bolus calculator.
• The recommendation with oref1 (and the way most use it) is to bolus 60%-75% of required bolus and leave the algorithm to deal with variation in absorption.
• I personally always used the easy bolus option on the Medtronic pump to give 2, 4 or 6 units dependent on the meal size, then left oref1 to get on with the rest.

GitHub Build:

Please see these instructions: Build iAPS using GitHub

If those instructions are too sparse for you, look at the LoopDocs instructions for building Other Apps with GitHub. You will need this information (in addition to the instructions on that page):

• Fork from: https://github.com/Artificial-Pancreas/iAPS
• Identifiers Names will be: FreeAPS, FreeAPSWatch, FreeAPSWatch WatchKit Extension
  • Identifiers will be:
    • ru.artpancreas.TEAMID.FreeAPS
    • ru.artpancreas.TEAMID.FreeAPS.watchkitapp
    • ru.artpancreas.TEAMID.FreeAPS.watchkitapp.watchkitextension
  • The App Group name is the same as for Loop: group.com.TEAMID.loopkit.LoopGroup
  • You must add this App Group to all 3 identifiers
  • The FreeAPS Identifier, in addition to the App Group, must also have: HealthKit and NFC Tag Reading enabled
• In App Store Connect, the Bundle ID for App will be: ru.artpancreas.TEAMID.FreeAPS

iAPSUpdate iAPS using Xcode

Note – these figures have not been updated since the app was in a different repository, but the steps to update are unchanged.

Open Xcode. If your iAPS workspace is not already open for you, you will probably find it in the recent projects. It will look like this:

Click Source Control. Choose “Fetch changes”.

Click Source Control again and then “Pull…”.

Select the branch to pull from. The correct branch should already be selected for you, so if you have built from master, select master. If you have built from dev, select dev.
Click “Pull”.

The last steps are only relevant if you made any changes to the code:

– You may see a a pop up asking to stash your changes. In that case, name the stashed changes to something that is meaningful to you.

– Select “Apply Stash After Operation”.

– Click “Stash and Pull”

The iAPS code is now updated. That was easy, wasn’t it? If you used the build script that automatically creates your ConfigOverride file, the targets are already signed, and you are ready to build the iAPS app to your phone.

Update iAPS using Terminal

Locate the directory where the Build_iAPS script saved the code. The directory is named after the branch and the date and time for the download:

Released (main) branch:  /Downloads/Build_iAPS/iAPS_main-[date]/iAPS

(e.g /Downloads/Build_iAPS/iAPS_main-220122-1352/iAPS )

Development (dev) branch:  /Downloads/Build_iAPS/iAPS_dev-[date]/iAPS

(e.g /Downloads/Build_iAPS/iAPS_dev-220108-1827/iAPS)

Open a Terminal window at the iAPS directory by right-clicking on it and select “New Terminal at Folder”. 

 Copy (tap on each line) below and paste into the terminal window and hit enter for each line:

git stash

git pull

git stash pop

The iAPS code is now updated. That was easy too, wasn’t it? To open the workspace in Xcode, copy and paste

xed .

and hit enter. The targets should be signed and you are ready to build the iAPS app to your phone.

Verify successful updating of iAPS code

To check that the iAPS code was successfully updated, you can find the BUILD_VERSION in the FreeAPS Config file. Compare this to the expected version in the iAPS GitHub Releases page.

Code Customizations

Several customizations are provided – use at your own risk. NOTE – these are really old and were for early ivalkou verions. Leaving them here as a guide.

Modify Enact Bolus Confirmation

Reason: In earlier versions, if FaceID or Fingerprint fails, user cannot get to passcode screen.

NOTE – this is fixed in release/0.2.0, the graphics in this section are from release/0.1.23

File: freeaps-0.1.23/FreeAPS/Sources/Services/UnlockManager/UnlockManager.swift

Graphic shows original code on left, with two options on the right.

This portion NOT needed for release/0.2.0: If you prevent the “if block” starting on line 28 from executing, the biometric ID is attempted once and then the passcode is presented.

To Remove Bolus Confirmation

For release/0.1.23, if you replaced the entire segment with success, the bolus is enacted as soon as user taps on Enact Bolus. This still works for release/0.2.0 but the original code and line number are different from the graphic shown.

For release/0.2.0, it is much easier to simply add a “false, ” between the if and context on line 28 similar to what is in loopdocs customization instructions.

For Omnipod – Continue Looping Past Reservoir = 0

Reason: FreeAPS X, by default, stops looping when the reservoir reports 0 u of insulin.

Omnipods will attempt to deliver up to 4 u more past report of 0 u of insulin.  There is no guarantee that many units are available.  Once 4 u is successfully delivered, pod session ends with an alarm.  If pod senses no more insulin can be delivered, pod session ends with alarm.

File: freeaps-0.2.0/FreeAPS/Sources/APS/APSManager.swift

Line # 190:

from:

guard reservoir > 0 else {

to:

guard reservoir >= 0 else {

For Omnipod – Extra Bolus at Insertion

If you prefer to have an extra bolus at Insertion, without it counting as IOB.

File: freeaps-0.2.0/Dependecies/rileylink_ios/OmniKit/Model/Pod.swift

Line: 65; for freeaps-0.2.1.1, this is on Line 72

Default:

public static let cannulaInsertionUnitsExtra = 0.0 // edit to add a fixed additional amount of insulin during cannula insertion

Tim Street wrote a nice introduction to FreeAPS X (as iAPS was called at the time):

• https://www.diabettech.com/diyaps/freeapsx-the-new-entry-to-the-diyaps-world

The OpenAPS documentation covers how you configure a “rig” to talk to your pump and CGM. So the pages about the “rig” can be skipped.  With iAPS, your “rig” is your iPhone with RileyLink compatible device. However, this is the core documentation of how to use the OpenAPS algorithm, so spend some time with the OpenAPS docs.

OpenAPS Pages to Review

• How OpenAPS Makes Decisions
• OpenAPS Preferences and Safey Settings
  • Note- iPhone Preferences menu for iAPS replace entries in json files for OpenAPS
• Optimize Your Settings
• Advanced Features
• Summary for Clinicians
• Nightscout with OpenAPS

Katie DiSimone wrote about OpenAPS as well as Loop. As usual, her blog plots are well worth your time. (Note: list generated by a search of seemycgm for OpenAPS – provided in chronological order)

SeeMyCGM Pages to Review

• https://seemycgm.com/2017/03/08/remote-monitoring-of-openaps/
• https://seemycgm.com/2017/05/10/openaps-new-feature/
• https://seemycgm.com/2017/05/12/openaps-smb-and-panda-express/
• https://seemycgm.com/2017/05/15/openaps-and-hormones-and-smb
• https://seemycgm.com/2017/05/24/openaps-and-uam/
• https://seemycgm.com/2017/05/24/under-the-hood/
• https://seemycgm.com/2017/09/02/loop-vs-openaps-update/
• https://seemycgm.com/2017/09/05/moving-between-diy-closed-loop-systems/
• https://seemycgm.com/2017/10/29/fine-tuning-settings/