// Collapsable Mobile Menus


FreeAPS X is an artificial pancreas system that is based on the OpenAPS (oref1) algorithm. It allows the use of this algorithm on an iPhone (iOS 14 and above). This is a completely different algorithm than the algorithm used by both Loop and the FreeAPS fork.

What does beta test mean?

You should not attempt to use this beta version of FreeAPS X unless you have a clear understanding of how DIY artificial pancreas systems work, are comfortable with the potential need to rebuild at short notice and are willing and able to provide detailed troubleshooting information to the developers when you have a problem.

If your experience of looping is that a friend once built loop for you on their aunt’s laptop, you should not be using this version of FreeAPS X.

  • FreeAPS X is now in officially beta after being tested by a group of individuals, but it is subject to frequent modifications
  • FreeAPS X is a work in progress
    • The current release has no direct Dexcom support – to use Dexcom, you must have cell or WiFi connection to the internet to access a Nightscout site that gets your Dexcom data via a bridge from Dexcom Share
      • The dev branch does have support for Dexcom and is under active testing
    • When editing a bolus Amount value, if you backspace to change just the value to the right of the decimal, you’ll need to re-enter the decimal point when editing – easiest to just hit clear and type bolus fresh.
    • The quick cancel of a bolus in the FreeAPS X app is similar to Loop – but you must tap on the square icon in the middle of the bolus progress icon
      • FreeAPS X will update the IOB based on actual delivery from the interrupted bolus, but this may not show up until the next CGM reading is detected.
      • In other words, do not panic when the IOB shows the full delivery of the interrupted bolus for the next 5 minutes
  • FreeAPS X uses biometric approval for manual bolus – it had some problems if passcode was required in pre-beta versions.  This was fixed in the first stable beta version 0.2.0 (31-May-2021).


Before entering any values into FreeAPS X, select your units. The default is mmol/l.

  • Tap Settings, Preferences and adjust Glucose Units to mg/dl if that is your system of units
  • Please read the Initial Preferences and Advanced Preferences before modifying any other preferences from the defaults 
  • If you enter settings in the wrong units – you must delete them and re-enter upon change of this preference


Please see the README for the most up-to-date information.

As of version 0.2.0 (stable beta), this was the state of required and supported hardware.


Access to a Mac (or Virtual Machine) – with Big Sur (11.x) operating system and Xcode consistent with your phone iOS, e.g., iOS 14.5 and higher requires Xcode 12.5

Because this code is early in development, you should be able to rebuild upon any announcement of a bug fix or new feature.

Smartphone requirements

All iPhones which support iOS 14 and up.


  • Start with FreeAPS X on your phone and use the simulated pump and simulated CGM
  • Or you can read your actual CGM from your Nightscout site and control a simulated pump
  • Get a feel for the layout of menus and decide if you want to continue

Supported pumps

FreeAPS X uses modified rileylink_ios library to control an insulin pump, thus supporting the same pump list as Loop:

  • Medtronic 515 or 715 (any firmware)
  • Medtronic 522 or 722 (any firmware)
  • Medtronic 523 or 723 (firmware 2.4 or lower)
  • Medtronic Worldwide Veo 554 or 754 (firmware 2.6A or lower)
  • Medtronic Canadian/Australian Veo 554 or 754 (firmware 2.7A or lower)
  • Omnipod “Eros” pods

To control an insulin pump you need to have a RileyLink compatible device: RileyLink, OrangeLink, Pickle, GNARL, EmaLink or similar device.

Supported CGM

  • Nightscout BG data source as a CGM (Online, e.g., cell or WiFi connection)
    • Before transitioning to FreeAPS X, make sure that you can get BG data from Dexcom (or other CGMs) to Nightscout
    • Understand that FreeAPS X is driven by new CGM entries and without Cell or WiFi coverage it will not update – be prepared to go Open Loop for those situations
  • Applications that mimic Nightscout as a CGM (apps like Spike and Diabox) (Offline, e.g., local on your phone)
    • Follow instructions here
  • If you build xDrip4iOS with the same bundle identifier as FreeAPS X you get CGM local on your phone
    • Additional information is found in the Build section
    • This link shows the list of supported CGM with this code (newer Dexcom G6 transmitters not supported)

Modify Nightscout

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


  • 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 FreeAPS X 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 (ver 14.2.2).

Transitioning from Loop

Loop users with Dexcom G6 or Enlite sensors who transition to FreeAPS X will need to have a working Nightscout site since Nightscout will be your CGM until other CGMs are integrated into FreeAPS X.

DIY Nightscout:

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

Make the following changes (copy and paste the values between the ” “)

Config Var Value
BRIDGE_PASSWORD your Dexcom password
BRIDGE_SERVER this can be left blank if you’re in the US, or you can use “EU” if outside of the US
BRIDGE_USER_NAME your Dexcom username
  1. add “openaps”
  2. if it’s not already listed, add “bridge”
SHOW_PLUGINS add “openaps”

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.


Nightscout as a Service:

T1Pal: Log into your account

  • On the Welcome Screen, scroll down to Step 2>Go Beyond CGM
  • Where it says: Visualize Therapy, make sure it says Yes
  • Tap the openaps/AndroidAps button and Save Changes
  • The OpenAPS displays should all be configured including colored forecast lines

Click on this link for more information about T1pal menus.

Current Implemented Features

Please see the Current State of FreeAPS X in the README file for the most up-to-date information.

What's Not Yet Implemented

Please see the Plans for the Future section in the README file for the most up-to-date information.

For known issues (bugs) and feature requests, please review: https://github.com/ivalkou/freeaps/issues

Getting Started Reference Information

Prerequisites Before Building FreeAPS X


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


The internal decision making of FreeAPS X matches that of OpenAPS but the “rig” discussed in the OpenAPS documents is replaced by the iPhone and 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.

Crowdin Translation Project

Please help by adding your language to the translation project for FreeAPS X. See this link for the current status of languages and to sign up to help.

The overall percentage complete for all languages is:

Don’t worry when you see the localized number go down – that probably means a new language has been added.

Onboarding Overview

If you are not an experienced DIY closed-loop system user, please wait until the code and documentation has passed the beta-test point.  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 FreeAPS X.

  • The main FreeAPS X 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


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.


The pump choices are Simulator, Omnipod and Medtronic. 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 similar to those from Loop. These LoopDocs pages may be helpful:

  • Medtronic Pump
  • Omnipod
    • The Confirmation Beeps option is more user-friendly than on Loop
    • Except for these cases, the pod remains silent when Confirmation Beeps are Enabled
      • Manual bolus upon start and completion of bolus (SMB and temp basal are silent)
      • Suspend
      • Resume, Change Time Zone, Sync Basal Schedule to Pod beeps at start and end of loading scheduled basal rate to pod
      • Read Pod and other Diagnostics (bottom of Pod Settings menu) beeps at start and end the action
    • The normal pod beeps that happen regardless of the Confirmation Beeps setting are unchanged, e.g., Replace, Expiration and other near end of life beeps


If you want to have FreeAPS X information show up on your Nightscout site, be sure to select Allow Uploads.

If you are using Nightscout as a source of CGM data or if you are using xDrip4iOS as your 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 FreeAPS X, you must tap Save on Pump.  For Medtronic pumps, this copies these limits to the pump.  For all pumps, these limits are checked by FreeAPS X 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 FreeAPS X, 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 FreeAPS X (OpenAPS).

As FreeAPS X 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 FreeAPS X (OpenAPS).

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

Target Ranges

Enter the Target Range(s) you prefer.


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.

Initial 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 FreeAPS X.

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.

Exercise Mode

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 FreeAPS X 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 FreeAPS X 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.

Advanced Preferences

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 FreeAPS X 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.


Open Loop Testing and Displays

Open Loop is required when you need to verify settings, e.g., there’s an oscillation pattern and you don’t know why.

Reminder: Test basal first.

Open Loop Basal Testing

  • Daytime:
    • Leave your settings alone (restore maxIOB if adjusted)
    • Go Open Loop (flip slider to disable Open Loop)
    • Check suggestions regularly and decide what to enact
  • Nighttime (use low glucose suspend mode):
    • Modify the maxIOB setting to zero
    • Go Closed Loop (flip slider to disable Open Loop)

Open Loop Displays

FreeAPS X is a work in progress.  The documentation for the behavior of Open Loop displays will change based on the version number.  To simplify keeping up with the documentation (and make it available to people still on the older version), the display details are found in a separate pdf file.

Considerations for Users Transitioning from Loop/FreeAPS

Katie DiSimone wrote about OpenAPS as well as Loop. You may find this post particularly appropriate: https://seemycgm.com/2017/09/05/moving-between-diy-closed-loop-systems

Please read the Onboarding, Initial Preferences and Advanced Preferences sections first.

Please note that these are general considerations and observations from some early adopters who previously used Loop. As always, Your Diabetes May Vary (YDMV)!

The quantity labeled Insulin required may be the source of some confusion to those coming from Loop.  Please review this section in the determine-basal logic page. (You have read that whole page already haven’t you?)

OpenAPS was originally designed to be used with Medtronic pumps using the pump bolus calculator and an Easy Bolus button. The calculation of Insulin required that FreeAPS X displays in the Enact Bolus screen, displayed (with default preferences) following carb entry, is not a bolus calculator in the same way that Loop has one.

  • A bolus calculator is not part of the standard OpenAPS protocol
  • When first starting out, with UAM and SMB disabled, the rule of thumb is to prebolus 60%-75% of your typical meal bolus (carbs/CR)
  • As you progress, and eventually enable UAM and SMB, you may need to adjust that meal prebolus
  • For more discussion about how to bolus for meals, read the Meals section

Add Carbs screen:

  • As soon as you tap Add in the Add Carbs screen, the carbs are saved and FreeAPS X will use those for the Insulin required calculations
  • There is no concept of entering a carb absorption time in OpenAPS, the algorithm estimates the carb absorption dynamically

Enact Bolus screen:

  • First line: Insulin required
  • Second line: Insulin recommended = Insulin required * Recommended Insulin Fraction (70% by default)
  • Third line: empty
  • If you tap on Insulin recommended, it is transferred to the Amount line
    • To edit the Amount, best to hit Clear and type desired amount

Temp Basal

  • When new CGM values arrive, FreeAPS X recalculates and may adjust Temp Basal and/or SMB  assuming pump communication is possible
  • If CGM or pump communciation stops, the last issued Temp Basal expires at the end of its duration and the pump returns to the scheduled rate
    • The maximum time for a temp basal above scheduled rate is 30 minutes
    • The maximum time for a zero temp basal is 120 minutes

Know how to cancel a bolus

  • If you enacted a bolus and you’ve changed your mind, you must tap on the square icon inside the progress indicator
  • It is not like Loop where you can tap anywhere on the line
  • FreeAPS X will update the IOB based on actual delivery from the interrupted bolus, but this may not show up until the next CGM reading is detected.
  • In other words, do not panic when the IOB shows the full delivery of the interrupted bolus for the next 5 minutes

Keep Nightscout Profiles in Sync

FreeAPS X does not current upload profile changes (basal, ISF, CR) to Nightscout like Loop does.  If you’ve never handled that manually, use the duplicate button instead of Add (blank profile) or editing the time.

This page in Nightscout docs is useful for reference.

Quick Taps from Main Screen

In addition to the toolbar at the bottom of the screen, there are some locations (see dashed boxes in graphic below) for quick access to other information.

  • Tap in area of the BG, the CGM screen is opened (known to work with Nightscout as a CGM – not sure about other CGM options)
  • Tap in the area of the pump reservoir/life or battery and pump menu opens (known to work for Pod – not sure about Medtronic)
  • Tap in area of the Loop and the last enacted item displays (swipe up to dismiss)
  • Tap in main screen area to see the history for Carbs, Temp Basal and Bolus
  • You cannot edit a carb entry, but you can delete it and add a new carb entry with a different value and/or time


More hints are provided in the Settings and Meals sections

  • Please, don’t let these hints be your only source of information
  • Please, read the OpenAPS documents and the More Reading documents
  • There is an active discussion ongoing in the FreeAPS X discussion group – you should check this daily for updates and information

FreeAPS X can use Nightscout BG data source as a CGM (there are other options – not yet added this documentation)

  • If you currently Upload Readings to get your BG data from Loop to Nightscout, this will not work for FreeAPS X
  • If you have removed “bridge” from your Heroku enable config var, you need to add it back
  • If you have removed your bridge username, bridge password, and bridge server from your Heroku config vars, these will also need to be added back
  • Before transitioning to FreeAPS X, make sure that you can get BG data from Dexcom (or other CGMs) to Nightscout


  • 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 FreeAPS X.
  • 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 FreeAPS X from Loop, the bolusing strategy for FreeAPS X 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.


The graphic below shows FreeAPS X 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, FreeAPS X 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 FreeAPS X 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 FreeAPS X Screen:

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 FreeAPS X shows in the Enact Bolus screen, is not a bolus calculator.

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

For FreeAPS X, 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 FreeAPS X 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

More Advice

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.
  • 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.

Build Instructions

Stay Informed

Whenever a new release is made available, a summary is provided in the FreeAPS X News and there will be discussion about it in the discussion channel.  Do NOT build or update without first reviewing recent news and discussion. Please update whenever a new release is available.

CGM Source

For Dexcom or other CGM sensor that can be uploaded to Nightscout, you can add Nightscout credentials to bring in that CGM data, but this requires cell or WiFi connection for closed loop operation.

Any supported sensor that connects to the xDrip4iOS app can be used as an offline CGM source in FreeAPS X (cell / WiFi not required for closed loop operation).

  • Both FreeAPS X and xDrip4iOS must be built with the same “App Group”
  • This is entered both in the “Signing and Capabilities” section AND in the “User-Defined APP_GROUP_ID” in “Build Settings” in Xcode

Getting Ready to Build:

If you do not have a Mac (or Virtual Machine) with Xcode ready to use, you may find the Build Step 1 through 9 in LoopDocs helpful.

Download Directions:

Name Confusion Alert

  • FreeAPS is a fork of Loop and is found under LoopWorkspace in the ivalkou repository with the freeaps branch name
  • FreeAPS X is an OpenAPS implementation on the iPhone, found under freeaps in the ivalkou repository; the branch name is release/v#.#.#

The numbered instructions in this list are shown on the Download Directions figure below:

  1. Open a browser to this site: https://github.com/ivalkou/freeaps/releases
  2. While in active beta testing phase, always select the latest release from this page
  3. Download the zip file
  4. Open your finder to see the Downloads folder
  5. If your finder did not automatically unzip the zip file, double click on the zip to unzip it
  6. Open the folder for freeaps-#.#.#
    • Find the file called FreeAPS.xcworkspace and double click on it
    • If you accidentally click on FreeAPS.xcodeproj, you’ll get an error message LoopKit not found when you try to build and you won’t see the LoopKit or RileyLink folders in your Xcode window as illustrated in the Build Directions figure.
  7. A warning window pops up
    • Click on Trust and Open
    • Xcode automatically opens

steps for downloading code

Build Directions:

The numbered instructions in this list are shown on the Build Directions figure below:

  1. Click on the folder icon, then FreeAPS icon in upper left of Xcode window
  2. Click on the Signing & Capabilities section in the upper middle of the Xcode window
  3. Choose your Team (if you do not know how to do this, please review LoopDocs and reconsider if you should be building this beta-test code)
  4. Make up your own name for your bundle identifier – and record it
    • Use the same bundle identifier every time you build and it must be unique (someone has already taken IvanTheGreat)
      • This way all your settings and your current pod are available in an updated build
      • If you forget your bundle identifier: connect your phone, open Xcode, click ’Window’, ’Devices and Simulators’
      • Under Name you’ll see FreeAPS X, uner Version the version number you last built and under Identifier the bundle identifier you used
    • If you are using the xDrip4iOS app
      • It cannot be the test flight version
      • It must be built using the same App Group as FreeAPS X entered in the “Signing and Capabilities” section AND in the the “User-Defined APP_GROUP_ID” in “Build Settings” in Xcode
      • Note – a link to preliminary documentation for building xDrip4iOS so it can be read directly by FreeAPS X is provided below; the instructions about modifying the plist and URL can be skipped
      • Link to preliminary google doc: https://docs.google.com/document/d/1B3RIEW5QecKqXQku4Q-I8oYzBbMQnHxL88WEWTq9eSY/edit?usp=sharing
  5. Select your phone
  6. Click on the Build arrow

Report Issues:

Please get in the habit of reviewing the formally reported Issues that can be viewed on github.

You can informally report or ask about issues in the Telegram Discussion group, but valued beta-testers should be able to add a new issue as well as review them. If you’re not sure how to do that, use your favorite search engine for instructions.

FreeAPS X Code Customization

Recommended Customization for Pod Users: release/v0.2.0 and Earlier Builds

The rileylink_ios package that is linked to FreeAPS X for release/v0.2.0 and earlier builds has an optimization feature, recently added and still being tested, that reduces the total number of messages exchanged between the loopers phone and the pods. This was incorporated to reduce the pod errors caused by low-battery conditions near end-of-pod life that some users experience. The rileylink_ios package has the optimization enabled by default.  This modification has instructions to disable the optimzation.

A FreeAPS X user reported an error in which an uncertain bolus was not resolved. The pod software expert suggests turning off the optimization feature to make it less likely to experience this situation.

For Omnipod – Turn off Message Exchange Optimization

For those working with dev – this is not needed.  It’s incorporated into the code.

This disables the message exchange optimization and restores a more robust sequence for every bolus request from FreeAPS X.

File: freeaps-0.2.0/Dependecies/rileylink_ios/OmniKit/PumpManager/OmnipodPumpManager.swift

Line: 1411


var getStatusNeeded = false


var getStatusNeeded = true

The  bold font in the from and to lines is to emphasize the single word to change.

Other Customizations

Several other customizations are provided – use at your own risk.

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:


guard reservoir > 0 else {


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


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

More Reading

Tim Street wrote a nice introduction to FreeAPS X:

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 FreeAPS X, 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

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

Skip to content