Welcome. This documentation aims to guide users who are preparing to set up and start using the Android Artificial Pancreas System (AAPS).
An index and explanation of the documentation structure can be found here, you can also reach it by clicking on the AAPS symbol at the top left of the documentation. There you will find an overview of the purpose of the different documentation sections. You can also use the headings to the left of this page to navigate through the documentation. Finally, there is a handy search function, directly below the AAPS symbol.
We aim to make it easy to determine both the capabilities and limitations of AAPS. It can be disappointing to discover after investing time in reading the documentation that you might not have a compatible insulin pump or CGM, or that AAPS offers different functionality than hoped for.
Many experience-related details in the AAPS documentation make more sense when you are actually using AAPS in real-time. Just as it is difficult to learn a sport only by reading the rules, it takes a combination of learning the foundations of the rules for safely operating AAPS and then learning how best to apply those rules as you start to use AAPS.
(preparing-safety-first)=
“With great power comes great responsibility…”
AAPS has an extensive set of safety features. These impose constraints which are gradually removed through staged completion of a series of Objectives which involve testing specific parameters and answering multiple choice questions. AAPS features are unlocked as the Objectives are successfully completed. This process allows the user to migrate safely in stages from Open Loop to Closed Loop, while learning about the different features of AAPS.
The Objectives have been designed to achieve the best possible introduction to AAPS, taking into consideration the typical errors and general trends AAPS developers have observed with new users. Mistakes can happen because the beginner is inexperienced and too eager to get started with AAPS, or has overlooked key points. The Objectives aim to minimize these issues.
:class: danger
Caution is advised concerning rapid improvements in blood glucose control and lowering of HbA1c
An important safety consideration is that a rapid reduction in HbA1c and improved blood glucose control in those who have had elevated glucose levels for some time can cause permanent damage. Many people with diabetes are unaware of this, and not all clinicians make their patients aware of this issue.
This damage can include sight loss, and permanent neuropathy (pain). It is possible to avoid this damage occurring, by reducing average glucose levels more slowly. If you currently have an elevated HbA1c and are moving to AAPS (or any other closed loop system), please discuss this potential risk with your clinical team before starting, and agree a timescale with gradually decreasing safe glucose targets with them. You can easily set higher glucose targets in AAPS initially (currently, the highest target you can select is 11.1 mmol/L but you can also maintain a purposefully weak profile if needed), and then reduce the target as the months pass.
One retrospective study of 76 patients reported that the risk of progression of retinopathy increased by 1.6 times, 2.4 times and 3.8 times if the Hba1C dropped 1%, 2% or 3% respectively over a 6 month period. They suggested that the "decrease in HbA1c value during any 6-month period should be limited to less than 2% in order to prevent the progression of retinopathy....Too rapid a decrease at the initiation of glycemic control could cause severe or transient exacerbation of the progression of retinopathy."
N.B. If you use different HbA1c units (mmol/mol rather than %), click here for an HbA1c calculator tool.
In another retrospective evaluation of 954 patients, researchers noted that:
"With a decrease in HbA1c of 2–3% points over 3 months there was a 20% absolute risk of developing treatment-induced neuropathy in diabetes, with a decrease in HbA1c of >4% points over 3 months the absolute risk of developing treatment-induced neuropathy in diabetes exceeded 80%."
A commentary on this work agreed that to avoid complications the goal should be to reduce A1c by <2% over 3 months. You can read other reviews on the topic here and here.
It is generally recognized that newly diagnosed type 1 diabetics (who often have very high HbA1c at diagnosis, before starting insulin therapy) appear to be able to rapidly reduce their HbA1c immediately after diagnosis without encountering these risks to the same extent, because they have not had elevated blood glucose levels for such a sustained period. However, it is still a consideration which you should discuss with your clinician.
(PreparingForAaps-no-sglt-2-inhibitors)=
:class: danger
SGLT-2 inhibitors, also called gliflozins, inhibit reabsorption of glucose in the kidney. Gliflozins incalculably lower blood sugar levels, and so you MUST NOT take them while using a closed loop system like AAPS! There would be a significant risk of ketoacidosis and/or hypoglycemia! The combination of this medication with a system that lowers basal rates in order to increase BG is especially dangerous.
In a nutshell:
- **Example 1: risk of Hypo**
>During lunch, you use **AAPS** to bolus based on consuming 45 g of glucose. The problem is that, unbeknownst to AAPS, the inhibitors cause the body to eliminate some of the carbs. This leaves your body with too much insulin compared to the absorbed carbs, resulting in hypoglycemia.
- **Example 2: risk of Ketoacidosis**
>The inhibitors eliminate some of the carbs in the background, causing a reduction in your BG. **AAPS** will automatically instruct the pump to decrease insulin intake, including basal. Over time this can result in your BG remaining below target value, to the point where the body does not have enough background insulin to absorb any carbs, resulting in ketoacidosis. Ordinarily, ketoacidosis develops in T1D patients because their pump fails, which would trigger alerts on their phone and be noticeable due to a high BG value. However, the danger with gliflozins is that there would be no AAPS alerts, as the pump remains operational and the BG potentially remains within target.
Common brand names of SGLT-2 inhibitors include: Invokana, Farxiga, Jardiance, Glyxambi, Synjardy, Steglatro, and Xigduo XR, others.
The key principles and concepts of looping must be understood before using AAPS. This is achieved by investing your personal time into reading the AAPS documentation, and completing the Objectives which aim to provide you with a solid platform for safe and effective use of AAPS. The volume of AAPS documentation may seem overwhelming at first but be patient and trust the process - with the proper approach, you'll get there!
The speed of progression will depend upon the individual, but be aware that completion of all the objectives typically takes 6 - 9 weeks. Many people start to build, install and set up AAPS well in advance of starting to use it. To aid with this, the system has a "virtual pump" which can be used during completion of the early objectives, so that you can become familiar with AAPS without actually using it to deliver insulin. A detailed breakdown of the timeline is given below, be aware that by objective 8 of AAPS you are closed looping, the later objectives add in additional features like SMS commands and automations which are useful to some users, but not essential to the core function of AAPS.
Success with AAPS requires a proactive approach, a willingness to reflect on the BG data and flexibility to make the necessary adjustments to AAPS in order to improve your outcomes. Just as it is nearly impossible to learn to play a sport by reading about the rules alone, the same can be said of AAPS.
In the preliminary stages of getting started with AAPS, you may experience difficulties getting all the components of the loop communicating effectively with each other (and potential followers), and when fine-tuning your settings. Some glitches cannot be resolved until AAPS is used in everyday life, but plenty of help is available on the Facebook group and Discord. Please plan accordingly and choose "good" times, like a quiet morning of a weekend (i.e. not late at night or when you are tired, or before a big meeting or travel) to troubleshoot and resolve issues.
AAPS is only compatible with certain types of insulin pumps, CGMs and phones, and some technology may not be available for use in various countries. In order to avoid any disappointment or frustrations, please read the CGM, pump and phone sections.
The time to build the AAPS app depends on your level of expertise and technical ability. Typically for inexperienced users, it can take up to half a day or a full day (with help from the community) in order to build AAPS. The process will significantly speed up for newer AAPS versions, as you become more experienced.
Several parts of this documentation are dedicated to helping you through the build process:
-
Building AAPS takes you step-by-step through building the app and installing it on your phone;
-
the FAQ answers common questions and explains the errors most likely to occur; and
-
the Troubleshooting hub collects solutions to the most frequent problems, organised by topic.
How long it takes to get to closed looping depends on the individual; an approximate timeline for reaching full looping with AAPS is given below.
A “keystore” (.jks file) is a password encrypted file unique to your own copy of AAPS. Your Android phone uses it to ensure that nobody else can upgrade your own copy without the keystore. In short, as part of the AAPS build, you should:
-
Save your keystore file (.jks file used to sign your app) in a safe place;
-
Keep a note of your password for your keystore file.
How you save the keystore depends on your build method:
- Android Studio (computer) build: the keystore is created during the build — see Generate signed APK for instructions on where to save it.
- Browser build: use the dedicated Export keystore workflow to download a copy to your Google Drive.
This will ensure that you can use that exact same keystore file each time an updated version of AAPS is created. On average, there will be 2 AAPS updates required each year.
In addition, AAPS provides the ability to export all your configuration settings. This ensures that you can safely recover your system while changing phones, upgrading/reinstalling the application with minimum disruption.
Please feel free to reach out to the AAPS community if there is anything you feel unsure about - there is no such thing as a silly question! All users with various levels of experience are encouraged to ask questions. Response times to questions are usually quick due to the number of AAPS users.
This section is aimed to provide new users with links on resources in order to get help including accessing community support made up of both new and experienced users who can clarify questions, and resolve the usual pitfalls that come with AAPS.
This is a section specifically for clinicians who want to know more about AAPS and open source artificial pancreas technology. There is also guidance on how to talk to your clinical team in the Introduction.
This diagram provides an overview of the key components (both hardware and software) of the AAPS system:
In addition to the three basic hardware components (phone, pump, glucose sensor), we also need:
- The AAPS app
- A reporting server and
- A continuous glucose monitor (CGM) app
AAPS is an app that runs on Android smartphones & devices. You are going to build the AAPS app (an apk file) yourself, using a step-by-step guide, by downloading the AAPS source code from GitHub, installing the necessary programs (Android Studio, GitHub desktop) on your computer and building your own copy of AAPS app. You will then transfer the AAPS app across to your smartphone (by email, USB cable etc.) and install it.
In order to fully take advantage of AAPS, you need to set up a Nightscout server. You can do this yourself or alternatively, pay a small fee for a managed Nightscout service to be set up for you. Nightscout is used to collect data from AAPS over time and can generate detailed reports correlating CGM and insulin patterns. It is also possible for caregivers to use Nightscout to remotely communicate with the AAPS application, to oversee their child’s diabetic management. Such remote communication features include real-time monitoring of glucose and insulin levels, remote bolusing of insulin (by texting) and meal announcements. Attempting to analyze your diabetes performance by looking at CGM data separately from the pump data is like driving a car where the driver is blind and the passenger describes the scene. Tidepool is also available as an alternative to Nightscout, for AAPS versions 3.2 and later.
Depending on your glucose sensor/CGM, you will need a compatible app for receiving glucose readings and sending them to AAPS. The different options are shown below and more information is given in the compatible CGMs section:
Both Nightscout and AAPS must be updated approximately once a year, as improved versions are released. In some cases, the update can be delayed, in others it is strongly recommended or considered essential for safety. Notification of these updates will be given on the Facebook groups and Discord servers. The release notes will make it clear what the scenario is. There are likely to be many people asking similar questions to you at update time, and you will have support for performing the updates.
(preparing-how-long-will-it-take)=
As mentioned earlier, using AAPS is more of a “journey” that requires investment of your personal time. It is not a one-time setup. Current estimates for building AAPS, installing and configuring AAPS and CGM software and getting from open loop to hybrid closed looping with AAPS are about 4 to 6 months overall. It is therefore suggested that you prioritize building the AAPS app and working through the early objectives as soon as possible, even if you are still using a different insulin delivery system (you can use a virtual pump up to objective 5).
Some of the objectives require a given amount of days to pass to make sure you understand the new functionality. It is not possible to bypass this waiting time; these minimum waiting times have been set for your own safety.
Here is an approximate timeframe:
| Tasks | Approx time |
|---|---|
| Initial reading of the documentation | 1-2 days |
| Installing/configuring PC to allow the build | 2-8 hours |
| Setting up a reporting server | 1 hour |
| Installing a CGM app (xDrip, BYODA, …) | 1 hour |
| Configuring CGM → xDrip → APPS initially | 1 hour |
| Configuring AAPS → pump initially | 1 hour |
| Configuring AAPS → Nightscout/Tidepool (reporting only) | 1 hour |
| Optional : Configuring NightScout ↔ AAPS & NSFollowers | 1 hour |
| Objective 1: Setting up visualization and monitoring | 1 hour |
| Objective 2: Learn how to control AAPS | 2 hour |
| Objective 3: Prove your knowledge | Up to 14 days |
| Objective 4: Starting on an open loop | Minimum of 7 days |
| Objective 5: Understanding your open loop | 7 days |
| Objective 6: Starting to close the loop (Low Glucose Suspend) | Minimum of 5, up to 14 days |
| Objective 7: Tuning the closed loop | Minimum of 1 day, up to 7 days |
| Objective 8: Adjust basals and ratios, enable Autosens | Minimum of 7 days, up to 14 days |
| Objective 9: Enabling Super Micro Bolus (SMB) | Minimum of 28 days |
| Objective 10: Automation | Minimum of 28 days |
| Objective 11: Dynamic ISF | Minimum of 28 days |
Once you are fully operational on AAPS, you will still need to regularly fine tune your settings in order to improve your overall diabetic management.
In addition to the medical warnings in the safety section there are also different parameters, depending on which insulin you are using in the pump.
AAPS calculations are based on insulin concentrations of 100U/ml (same as pump’s standard). The following types of insulin profile presets are supported:
- Rapid-Acting Oref: Humalog/NovoRapid/NovoLog
- Ultra-Rapid ORef: Fiasp
- Lyumjev:
For Experimental/Advanced users only:
- Free-Peak Oref: Allows you to define peak of the insulin activity
This documentation aims to reduce the technical expertise required to an absolute minimum. To build the AAPS app, you have several options — see Building AAPS for an overview:
- Browser build (recommended): build the app directly from your smartphone using GitHub Actions, with no computer or Android Studio required. You will need a GitHub account and a Google account to store the resulting app in your Google Drive.
- Android Studio build: build the app on your computer using Android Studio. This is mostly used by developers who intend to make code changes.
- Command-line build: for users who prefer to build locally without installing Android Studio.
Beyond building the app, you also need to set up a reporting server, configure several Android phone apps and develop expertise in diabetes management. This can be achieved by moving step-by-step, being patient, and with help from the AAPS community. If you are already able to navigate the internet and manage your own Gmail emails, building AAPS is a feasible task. Just take your time.
The current version of AAPS (3.4) requires an Android smartphone with Google Android 12.0 or above. If you are considering buying a new phone, (as of January 2026), Android 16 is preferred.
Users are strongly encouraged to keep their build of AAPS up to date for safety reasons. However, for users unable to use a device with Android 12.0 or newer, earlier versions of AAPS compatible for older Android versions, remain available, see: Release notes.
The exact model you buy depends on the desired function(s). You can find on the Phones page recommendations and user feedback about working setups.
Users are encouraged to keep their phone Android version up-to-date, including with security parameters. However, if you are new with AAPS or are not a technical expert you might want to delay updating your phone until others have done so and confirmed it is safe to do so, on our various forums.
:class: warning
Samsung has an unfortunate track record of forcing updates on their phones, which can cause Bluetooth connectivity issues. To disable these forced updates, you need to switch the phone to "developer mode":
1. Go to **Settings** > **About phone** > **Software information**, then tap **Build number** until it confirms you have unlocked developer mode.
2. Go back to the main **Settings** menu, where you should see a new **Developer options** menu item.
3. Open **Developer options**, scroll to find **Auto system update**, and turn it off.
:class: warning
There have been several reports of **AAPS** being shut down arbitrarily by Google Play Protect every morning. If this happens, you will have to go to the Google Play options and disable **Google Play Protect**. Not all phone models or all Android versions are affected.