WIP: Remora Companion App for Remote Control

[TebbeUbben]

This pull request introduces an experimental companion app for secure, app-based remote control of AndroidAPS, intended as a more user-friendly and secure alternative to the current SMS Communicator (primarily used by caregivers of children with diabetes).

Motivation

• Replace SMS commands and mobile-network dependencies with a dedicated app UI and IP-based transport (Firebase Cloud Messaging (FCM) and Firestore).
• Replace the SMS OTP mechanism with end-to-end encrypted (E2EE) authenticated messages.
• Enable more ergonomic workflows for caregivers. Help caregivers focus on what's really important instead of typing SMS commands.

Cryptography (current WIP design)

• Key exchange: out-of-band Elliptic-Curve Diffie–Hellman (ECDH, prime256v1).
• Final keys and a small key verification string are derived using HKDF.
• Message protection: AES-128 in AEAD mode (AES-GCM) for confidentiality and integrity.

Architecture

Remora consists of three components:

1. The Remora companion app, which must be installed on follower phones.
2. The Remora AndroidAPS plugin, which must be bundled with the used installation of AndroidAPS on the main phone.
3. The Remora library, which handles communcation between devices and acts as a backend to both the companion app and the AndroidAPS plugin.

Both the companion app and the library can be found in this repository: https://github.com/TebbeUbben/Remora

Remora utilizes a modern Android development stack based on Jetpack Compose, Kotlin, Coroutines, Room, Dagger etc. To keep message payloads small, the communication relies almost entirely on Protocol Buffers. The UI intends to follow Material You design principles (including dynamic theming). I hope to reuse some of the components later to integrate them in AndroidAPS, too.

How to build

1. Clone my fork of AndroidAPS: https://github.com/TebbeUbben/AndroidAPS.git
2. Clone the Remora repository: https://github.com/TebbeUbben/Remora.git
3. Append these lines to the root settings.gradle and change the path to your local copy of the Remora repository:

includeBuild("C:\\Path\\To\\Remora") {
    dependencySubstitution {
        substitute(module("de.tebbeubben.remora:lib"))
                .using(project(":lib"))
    }
}

This makes sure that the AndroidAPS build system can access the required source files of the Remora library. Later this will be replaced by providing a build artificat, by using git submodules or by fully merging the source code into the AndroidAPS repository.

5. Build the app module of both repositories and install on your phone.

Firebase setup

For legal and technical reasons, Remora requires every user to create an individual Firebase project, which takes just a few clicks:

1. Go to https://console.firebase.google.com.
2. Click "Create new Firebase project".
3. Choose a name, e.g. "Remora". Turn off Google Analytics (doesn't hurt, but we don't need it).
4. Click "Create project" and wait for the setup to complete.
5. In the menu on the left, choose "Build" -> "Firestore Database" and click "Create database"
6. Choose "Standard version", optionally change the database location and create the database in "production mode".
7. Click the "Rules" tab, paste the following into the text editor and click "Publish":

rules_version = '2';

service cloud.firestore {
  match /databases/{database}/documents {
    match /remora/status {
      allow read, write: if true;
    }
  }
}

8. Click the settings icon in the upper left corner and choose "Project settings".
9. In the section "My apps", click the Android icon to add a new Android app.
10. Type the package name "info.nightscout.androidaps" (but any arbitrary package name should work) and click "Register app".
11. Download the google-services.json and keep clicking "Next" until you're back at the Firebase console.
12. Now switch to the tab "Service accounts".
13. Click the button "Generate new private key", confirm the dialog and wait for the configuration file to download.
14. Transfer both downloaded configuration files to the AndroidAPS phone and complete setup. Remora settings can be launched by clicking the button in the Remora fragment.

Working

• Device pairing
• Basic communication between paired devices
• Transmission of 24-hour status data to peer devices, with display support
• Boluses
• Carbs
• eCarbs
• Temp Targets (when issues boluses or carb)

Not yet implemented

• Profile switches
• Temp targets alone
• Extended boluses
• Pump disconnect
• Temporary basals
• Change loop/running mode
• Bolus calculator

Important notes

• This project is work in progress and remains highly experimental.
• It must not be used in production environments.
• The are still many bugs, crashes and things that need to be done.
• The work is part of my bachelor thesis at the Hasso-Plattner-Institut, where I am pursuing a degree in IT-Systems Engineering.

Screenshots

Still very much in progress, but here's an early look:

[savek-cc]

Love it. Is it one firebase project per AAPS or one project for each follower?

[TebbeUbben]

Love it. Is it one firebase project per AAPS or one project for each follower?

Thanks for your endorsement! It uses a single Firebase project per instance of AndroidAPS, which is shared across all followers. However, you only need to configure AndroidAPS. Followers are configured using the pairing data they receive from the main phone. Right now, that's a rather long base 64 encoded string, which must be copied to the follower phone by the user upon pairing (WhatsApp, Email, Quickshare, Google Notes, whatever works). QR Code support is on the roadmap, but doesn't have priority at this time.

[MilosKozak]

if possible i'd vote for not adding another app. To make the use easy, the control should be integrated to AAPS (even via shared lib)

Right now we have these options:
AAPS client: Android
SMS: iOS, Android
NS and NS connected apps (except bolus): iOS, Android

What is missing is direct communication between main and client app (NS independent) which I believe is what you are trying to achieve. That's why I'm not voting for another man in the middle. Ideal would be just QR scan done by AAPS client or another app which should exchange keys etc ....

Anyway .... good move 👍

[savek-cc]

My 2ct:
@MilosKozak from what I've seen, this (in a while?) could be another build option for AAPS - just like pump control or nsclient.However: It also looks similar to AAPS - but it brings a lot of "modernization" on top of the actual functionality which probably would be hard to integrate into AAPS within the scope of a bachelor's or master thesis.
So I would envision this "additional app" to be a "technology speedboat" to test out this new stuff, gradually bring over the improvements to AAPS and then discontinue the external build/app.
But that will take time and effort.
Also: By showcasing it as an external/lightweight app, we might finally be able to motivate an iOS developer to actually do an implementation of this on iPhone, giving iOS users a decent remote control possibility.
If we were to do it bundled from the start, the entry barrier would be a lot higher.

[TebbeUbben]

if possible i'd vote for not adding another app. To make the use easy, the control should be integrated to AAPS (even via shared lib)

Right now we have these options: AAPS client: Android SMS: iOS, Android NS and NS connected apps (except bolus): iOS, Android

What is missing is direct communication between main and client app (NS independent) which I believe is what you are trying to achieve. That's why I'm not voting for another man in the middle. Ideal would be just QR scan done by AAPS client or another app which should exchange keys etc ....

Anyway .... good move 👍

I can absolutely see the appeal of having everything integrated directly into AAPS, and in the long run that would indeed be the ideal direction. For now, however, I decided to build Remora as a separate companion app, mainly because of the different architectural and security requirements compared to AndroidAPS itself.

Why not build directly into AAPS?

The key question is: how do we securely move information from one phone to another?

Nightscout + SMS (current approach):

Nightscout is self-hosted and can be fragile from a security perspective (weak passwords, missing updates, lack of enforced TLS, etc.). Its API works by pushing/pulling individual records without a guaranteed delivery mechanism. There is no way to ensure completeness of data, which makes it vulnerable to selective denial-of-service. It also does not reliably wake devices.

FCM + Firestore (Remora’s approach):

Remora transmits an encrypted bundle of the last 24 hours of data in one block. This guarantees consistency (either all or nothing) and prevents manipulation along the way. Any cloud service is treated as untrusted: everything is end-to-end encrypted, with keys stored in the Android Keystore. The app never uses passwords; instead, it relies on the phone’s unlock mechanism and the physical “ownership” of the device as the trust anchor.

Architectural rationale

Remora is deliberately lightweight:

• It does no independent calculations (IOB, COB, basal). Instead, it mirrors exactly what AAPS shows avoiding that devices get out-of-sync due to bad settings.
• It avoids introducing a parallel database or additional state management. AAPS remains the single source of truth. For example, if we want to add carbs, set a temp target or do a profile switch, we don't just add them to the database and hope for the best. Instead, the request is sent to the main phone, which applies the change itself and then propagates the updated state back to the follower.
• The Remora plugin simply exports information and accepts commands via the library. This keeps the new functionality isolated and reduces the risk of destabilizing AAPS. The overall fingerprint of this PR is fairly small. Changing the information flow within AndroidAPS is something that I'd be very careful about.

User impact

• To use Remora, users currently need to compile a second APK. However, anyone able to compile AndroidAPS is already capable of doing this as well.
• If Remora is added as a submodule to AndroidAPS, it becomes even simpler: you don’t have to open a separate project, you can just switch build targets in the same environment.

Future opportunities

• As @savek-cc mentioned, having a companion app opens the door to a future iOS version. Remora is already built with Jetpack Compose and Kotlin, so Kotlin Multiplatform could be an interesting path to explore later.
• Over time, if the approach proves stable and secure, integration into AAPS could still be considered. For now, separating concerns allows us to move faster while minimizing risks for the core app.

[andyrozman]

Looks like interesting project... When I have little time I will try it out...

But if its based on Android/Firebase... How could IPhone app connect to it?

[savek-cc]

@andyrozman https://firebase.google.com/docs/ios/setup - but I guess we'd need someone that actually knows 2ct about iOS development to verify ;)

[TebbeUbben]

Looks like interesting project... When I have little time I will try it out...

But if its based on Android/Firebase... How could IPhone app connect to it?

Firebase is able to send push notifications to iOS devices by relaying through APNS (Apple Push Notification service). A brief look at the reference documentation also suggests that it is able to dynamically configure the FirebaseApp instance at runtime, which is what I use to load the user's Firebase API keys without baking them into the app. This is also just needed for receiving messages as that requires some special handling (waking up the device, launching the app etc.), whereas for sending messages, a REST API is used. APNS restricts the payload size to 4KB - just like on Android. Firestore is also available via the Firebase SDK for iOS - and much less of a problem as it's just a websocket or something similiar to my understanding.

[TebbeUbben]

Here's a screen capture that showcases a bolus delivery using Remora: https://drive.google.com/file/d/1SqARfdtKxih6ZZwEMuICc9fogB9pd9Wi/view?usp=sharing

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud