What changed in AAPS v4

This page collects the notable changes in behavior between AAPS v3 and v4 — things that work differently, have moved, or have been removed — so existing users know what to expect when they update. See also the Release Notes and the update manual.

NSClient v1 has been removed 

AAPS v3 shipped two Nightscout synchronization plugins:

NSClient — the legacy client (the old Nightscout REST / socket.io API, also called “v1”), and
NSClientV3 — the client for the newer Nightscout API v3.

In AAPS v4 the legacy NSClient (v1) plugin has been removed. Only NSClientV3 remains for synchronizing with Nightscout.

What you need to do

If you (or your AAPSClient follower) were still synchronizing with the old NSClient (v1) plugin, switch to NSClientV3 before/after updating:

Open Configuration → Communication → NSClientV3.
Enter your Nightscout URL and an access token (NSClientV3 uses an access token, not the old API secret — see creating a token).
Your Nightscout site must support the API v3 (Nightscout 15 or newer).
If you use websockets, enable or disable them on both the master and the follower — never on only one.

This affects only how the app talks to Nightscout; your data on Nightscout is unchanged.

The bottom navigation: Treatments, Scenes and Manage 

In AAPS v3 you moved around the app with a row of tabs (Overview, Actions, Treatments, …), and several features were plugins you enabled in the Config Builder (Actions, Automation, Food, …).

In AAPS v4 the tabs are gone, and so is the eye checkbox in the Config Builder that showed a plugin as a tab. The main screen is the Overview, and a bottom navigation gives you three sheets. Actions, Automation and Food are no longer plugins — there is nothing to enable in Configuration (the renamed Config Builder); their functions now live in these sheets.

Treatments — enter and deliver 

The Treatments sheet is where you record or deliver a treatment: Bolus wizard, Insulin (manual bolus), Carbs, Treatment (insulin + carbs together), Calibration, CGM (open your CGM app, when one is configured), and your QuickWizards.

The Treatments bottom sheet

On a Wear OS watch the same treatments are entered from the watch’s AAPS menu (Bolus wizard / Calculator, eCarbs, Treatment, …):

The treatment actions in the watch's AAPS menu

Scenes 

Your situation presets — see Scenes.

Manage — manage and activate 

The Manage sheet is where you manage and activate everything else: Profile, Insulin settings (your insulin configurations), Temp Target, QuickWizard presets, Scenes, Automation, Food, Site Rotation, Pump, Authorized clients — plus the pump actions that used to be on the Actions tab (Extended Bolus, cancel temp basal, Prime/Fill, Sensor Insert, Pump Battery Change).

The Manage bottom sheet

All of your existing automation rules and food entries are kept; only the way you reach these features has changed.

Where did the Actions tab go?

AAPS 3.x had an “Actions” tab. In AAPS 4 its functions live in other places:

Profile switch and Profile Percentage: tap the profile name on the main screen, or Manage → Profile. See Change the Profile Percentage.
Temporary target: press the target on the main screen, or Manage → Temp Target.
Prime/Fill, Sensor Insert, BG check and the other careportal entries: in the expanded status panel, in Manage, or as QuickLaunch buttons.
History browser, Statistics (TDD): in the menu (☰).

Profile switch and profile percentage

In AAPS v3, a long press on the profile name opened the profile switch dialog (percentage, duration, Activity temp target). In AAPS v4, tap the profile name (or Manage → Profile), then tap the round ▶ button at the bottom right to open the same settings. See Change the Profile Percentage.

Settings protection now also locks the management screens 

In AAPS v3, Settings protection asked for your password only when you opened the settings. You could still add or edit profiles in the Local Profile tab without it.

In AAPS v4, Settings protection also covers editing on the management screens: Profile, Insulin settings, Temp Target and QuickWizard. If your settings are locked, these screens open read-only:

You can browse the entries and ▶ Activate or use them.
The Add / Edit / Clone / Delete buttons are hidden. Only the ✏️ pencil in the top bar shows that you can unlock editing.

The read-only Profile screen — only Activate at the bottom, pencil in the top bar

What you need to do

To add, edit, clone or delete an entry, tap the ✏️ pencil in the top bar and enter your settings password (or use biometrics). The buttons appear.

If you don’t need to protect your settings, you can turn Settings protection off in Settings → Protection.

The insulin in use can’t be edited 

In AAPS v3, you could change the DIA of the insulin you were using at any time.

In AAPS v4, the insulin marked ACTIVE in Manage → Insulin settings is greyed out: you cannot edit or delete it.

When you upgrade, AAPS keeps the insulin and DIA that your v3 profile switches already stored. If it finds older records whose insulin is known but whose DIA is not, it uses a default DIA for them and shows a message once, for example Older records had no insulin duration, so 9.0 hours was used for Lyumjev. Check your insulin settings — already migrated records are not updated afterwards. Check your insulin settings when you see it.

What you need to do

To change the DIA or peak, add a new insulin with +, adjust it, save it and ▶ Activate it. See Changing the insulin in use.

AAPSClient remote control needs pairing 

In AAPS v3, AAPSClient controlled AAPS by writing care-portal treatments to Nightscout, and could not deliver a bolus.

In AAPS v4, the client and the main phone are paired once, and every command is signed. The main phone checks and confirms each command, and a client can now also deliver a bolus.

Each client has a role that limits what it may do.
While client control is on, the main phone is in hardened mode: treatments and changes typed directly into Nightscout (the website, other apps) are no longer applied.
Each client gets a Nightscout token of its own with only the rights it needs.

What you need to do

Pair each AAPSClient with the main phone: see Master ↔ Client control. With an admin token on the main phone, the main phone shows a QR code that sets up and pairs the client in one scan. If you used to enter treatments on the Nightscout website, enter them on a paired client instead.

Duplicate BG data now switches the loop to Low Glucose Suspend 

When AAPS receives the same BG reading twice (a red warning badge on the BG source shortcut in the bottom bar), it cannot calculate your trend reliably, so it stops giving correction insulin.

In AAPS v3 this happened quietly in the background: your loop still showed as Closed Loop, even though it could no longer correct.

In AAPS v4 the change is visible. A closed loop is switched to Low Glucose Suspend mode, and the loop dialog tells you why: “LGS mode due to doubled values in BG source”. AAPS can still reduce or suspend your basal to protect you against lows.

What you need to do

Find and remove the duplicate readings — see BG warning sign.

Once they are gone, AAPS stays in Low Glucose Suspend. It does not go back to Closed Loop on its own: press and hold the loop icon and select Closed Loop again.

Tidepool: data now shows under the device name AAPS 

In AAPS v3, the data uploaded to Tidepool was shown in Tidepool under another device name.

In AAPS v4, the data is shown under the device name AAPS. After the update, AAPS starts a new data set in Tidepool. Your older data stays in Tidepool under the old device name.

What you need to do

Usually nothing: new data simply appears under AAPS.

Do not run “Full synchronization” while the old data is still in Tidepool: the same data would then be there twice. If you want all your data under the new name, use the “Purge all data” button on the Tidepool screen first (it also deletes the old data uploaded by AAPS), then run “Full synchronization”. Only the data still stored in AAPS on your phone can be uploaded again.