Add WearOS companion app

[blacklight]

Add WearOS companion app

Adds a standalone Wear OS app that displays a user's loyalty cards and renders their barcodes directly on the watch.

Addresses:

• Any plan or interest in a Wear OS companion app? #2039
• WearOS support #364

Closes:

• [Feature Request] Wear OS support #25

What's new

Wear OS module (wear/)

• Card list screen showing all non-archived loyalty cards fetched from the phone, with per-card header colours
• Card detail screen rendering the barcode (QR, EAN-13, Code 128, Aztec, Data Matrix, etc.) using ZXing, constrained to fit within a round watch face
• Swipe-to-dismiss navigation between screens
• BluetoothCardClient — GMS-free RFCOMM client that connects to any bonded device advertising the Catima service UUID and fetches card JSON over a newline-delimited protocol
• WearDataListenerService — GMS WearableListenerService retained as automatic fallback for standard Android + Google Play Services setups
• Graceful error state when neither transport can reach the phone

Phone module (app/)

• BluetoothServerService — RFCOMM server that starts on app launch, listens for CARDS_REQUEST commands from the watch and responds with card list JSON
• WearDataService — GMS WearableListenerService retained as fallback
• BLUETOOTH_CONNECT runtime permission requested on first launch (Android 12+)

Transport strategy

The watch tries Bluetooth Classic (RFCOMM) first. This works without Google Play Services and is therefore compatible with GrapheneOS and other setups where sandboxed GMS cannot route Wearable Data Layer messages. If no bonded device responds on the Catima UUID, it falls back to the GMS MessageClient path, which works on standard Android.

Key fixes

• org.json.JSONObject.optString() returns the literal string "null" for JSON null values; replaced with isNull() guards in WearCard.fromJson to prevent ZXing receiving "null" as a barcode value
• Square barcodes (QR, Aztec, Data Matrix) are now constrained with a 15 % round-screen inset via BoxWithConstraints so they do not overflow the circular display boundary

Permissions added

• BLUETOOTH / BLUETOOTH_ADMIN (≤ API 30, no prompt required)
• BLUETOOTH_CONNECT (API 31+, runtime prompt on both phone and watch)

Testing

Verified on Pixel Watch 3 (Wear OS 5) paired with Pixel 9a running GrapheneOS with the F-Droid build of Catima. Full round-trip latency phone → watch is approximately 400 ms over Bluetooth Classic.

Screenshots

[TheLastProject]

As written in the issues, WearOS requires proprietary dependencies. So this must be at very least be excluded from the foss flavour. That is a blocker, because F-Droid does not allow proprietary dependencies (and I don't want people to be forced to run proprietary Google code to run Catima, there must always be an option free is proprietary code)

Aside from that, cool :)

I don't have a WearOS device but I will look at this in an emulator soon. Are you willing to keep maintaining WearOS code long term? Just for my expectation of expected (future) workload :)

[blacklight]

@TheLastProject thank you for your reply!

I had the same uncertainty around the non-free WearOS dependencies.

I eventually resorted to implementing my own Bluetooth service to let the phone and watch communicate (also because GMS didn't work on my sandboxed Google Play Services on GrapheneOS), but there's still a GMS fallback that makes the app dependent on Google's non-free libraries, I agree.

I'm not very familiar with F-Droid's requirements when it comes to WearOS apps and I don't know if there are some relevant examples I could take a look at.

But my guess is that without the GMS dependency and with a custom Bluetooth listener to replace it the lights should be green, right?

If that's still not the case I'll be happy to split the WearOS implementation and make it only available for the Play Store build.

Are you willing to keep maintaining WearOS code long term?

Of course 🙂

[TheLastProject]

I eventually resorted to implementing my own Bluetooth service to let the phone and watch communicate (also because GMS didn't work on my sandboxed Google Play Services on GrapheneOS), but there's still a GMS fallback that makes the app dependent on Google's non-free libraries, I agree.

I'm not very familiar with F-Droid's requirements when it comes to WearOS apps and I don't know if there are some relevant examples I could take a look at.

But my guess is that without the GMS dependency and with a custom Bluetooth listener to replace it the lights should be green, right?

Yeah, the issue is specifically

    // Wearable Data Layer
    implementation(libs.com.google.android.gms.play.services.wearable)

in app/build.gradle.kts. That has to be excluded from the foss flavour.

I think that can be solved by just saying gPlayImplementation instead of implementation to only include it in the gPlay flavour.

With regards to testing, I see you removed the .debug suffix from the debug builds. This will make it very hard for me to do an actual on-device test. Maybe it's possible to add a debug version to the Wear app as well with debug in the package name? I believe there is this annoying Google restricting where the wear app must almost share a package name or so, which I guess is why you did that.

Are you willing to keep maintaining WearOS code long term?

Of course 🙂

That's great :)

I see you're still pushing to this occasionally. Would you like me to start reviewing already or give you some times to finish up some stuff first? :)

[TheLastProject]

I just merged the Katastima APK scanner into main. That should make it clear which dependencies are in which flavour if you rebase your MR on main :)

[blacklight]

I just pushed two last changes:

• 744a7453 to remove all the GMS dependencies (no more GMS fallback, only Bluetooth RFCOMM service).
• aa72cc19 adds watch storage support, so cached cards will still be displayed also if the phone is disconnected.

The code should be ready for review now.

One last open question would be about the packaging/release process.

I don't know of other WearOS apps distributed on F-Droid so I'm not sure how the distribution process for companion apps would look like.

On the Play Store the APKs are usually bundled, not sure about F-Droid - if they can be released together or the WearOS app needs another store entry.

Also, I guess that a mention in the README/docs is also needed?

[TheLastProject]

The code should be ready for review now.

Great, I'll look soon. Though the lint seems to be failing. We should also see if we can do the whole build/test of the WearOS app in GitHub Actions. But that's not something to delay review (what delays review is me not having time yet but I'll make time soon!)

One last open question would be about the packaging/release process.

I don't know of other WearOS apps distributed on F-Droid so I'm not sure how the distribution process for companion apps would look like.

On the Play Store the APKs are usually bundled, not sure about F-Droid - if they can be released together or the WearOS app needs another store entry.

I don't believe it is possible to write WearOS apps without proprietary dependencies, so that's a no-go for F-Droid. However, I can post it to GitHub and maybe it can be published to IzzyOnDroid. I don't really know enough yet about installing apps on WearOS, trying to hunt down a cheap second-hand WearOS watch and then discuss with Izzy afterwards :)

Also, I guess that a mention in the README/docs is also needed?

I guess so, but no rush, we can also set the documentation up after this is merged :)

[TheLastProject]

Not completely sure but I think this may be what we want as a new wear.yml GitHub action (based on android.yml), so we can automatically build and lint the wear app too each commit :)

I removed all the test stuff, as the wear app seems to lack tests (which is understandable, I'm not going to complain).

name: Android Wear CI
on:
  workflow_dispatch:
  push:
    branches:
      - main
      - staging
      - trying
  pull_request:
    branches:
      - main
permissions:
  actions: none
  checks: none
  contents: read
  deployments: none
  discussions: none
  id-token: none
  issues: none
  packages: none
  pages: none
  pull-requests: none
  repository-projects: none
  security-events: none
  statuses: none
env:
  JAVA_HOME: /usr/lib/jvm/java-25-openjdk-amd64
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.0
      - uses: gradle/actions/wrapper-validation@v6.2.0
      - name: set up OpenJDK 25
        run: |
          sudo apt-get update
          sudo apt-get install -y openjdk-25-jdk-headless
          sudo update-alternatives --auto java
      - name: Build
        run: ./gradlew :wear:assembleRelease
      - name: Check for non-free libraries
        run: |
          wget -q https://codeberg.org/Katastima/apkscanner/releases/download/v0.0.7/apk-scanner_v0.0.7.jar
          java -jar apk-scanner_v0.0.7.jar scan-apk "$(echo 'wear/build/outputs/apk/release/wear-release-unsigned.apk')"
      - name: Check lint
        run: ./gradlew :wear:lintRelease

[TheLastProject]

Sadly my attempts to test this have been foiled by the Google Pixel Watch app, which is required to link a WearOS app according to Android Studio, crashing on real devices and emulators for me.

Maybe the link-to-emulated-watch flow is just broken. I'll try to get my hands on a second hand Android WearOS watch soon and see if that behaves better.

I'll take a look at the code itself soon :)

[TheLastProject]

This looks quite reasonable! I feel I don't have much complaints about the general structure, great.

I haven't been able to test it yet, but I'm in talks with someone to get a second hand WearOS device. I may run into some more issues when testing on device, but for now, this is my feedback (also don't forget about the suggested GitHub Actions workflow please :))

[TheLastProject]

I expect to have a WearOS smartwatch by tuesday evening so I may be able to test this on-device Tuesday evening or Wednesday, assuming the official WearOS app actually works properly. So I can return to this with more on-device experience then.

[TheLastProject]

I think this may almost be ready to be merged at least into a wearos branch. I'm a bit hesitant to release this as-is because I'm not sure if the assumption that any paired Bluetooth device can be trusted is one that holds true.

However, I think that it may be good to do some security hardening in a separate MR after this base v1 MR is merged, to prevent scope creeping too much.

I think this is basically ready aside from a small refactor.

I do seem to have performance issues, but I do think they may just be issues with the watch itself? I'm not seeing any obvious big mistakes. And it's usable enough, so whatever :)

[TheLastProject]

FYI, you have a merge conflict on gradle/libs.versions.toml now, probably due to the new release, so that needs fixing.

Also still have some nitpicks, sorry 😅

[TheLastProject]

I agree it's a good improvement, especially because Google notes the old system is deprecated. I made a new issue for that, we can do that for app + wear after this I think: #3208

[TheLastProject]

I agree it would be an improvement as soon as we can use targetSdk 37.

I configured it in https://github.com/CatimaLoyalty/Android/pull/3161/changes, will also bump the wear app after it's been merged. Let me know in that PR if you think I'm making a mistake. For now, the tests fails because Robolectric doesn't support SDK 37 yet.

[TheLastProject]

I trust @theimpulson's judgment in that we should use navigation3. However, I'm okay with leaving that for a future PR as well so we can move forward with getting this merged and getting something usable into the hands of users :)

[TheLastProject]

Sorry if this review is a bit chaotic, some of your comments came in while I was responding and I missed them. I think I looked at everything and replied to everything but if I missed something please let me know

[TheLastProject]

When activating "Sync with Wear OS", when the user denies the permission request, the toggle will still be activated. It shouldn't be.

[TheLastProject]

Even worse, that seems to have broken the main screen and settings screen. I couldn't use anything anymore and when closing and reopening Catima the home screen was so sluggish it became basically unusable.

My logs are being spammed so much I can't see what's happening. Is it maybe stuck in a loop in permission handling?

[steel101]

There is a state bug with permission request in settings.kt I see remove the extra state or add a expection for it to prevent crashes in the future

[blacklight]

That's a good catch. I also noticed slugginess but I didn't connect it to the repeated BT permissions check.

I've tried to make the logic a bit smarter here: 6fa800d

[TheLastProject]

That seems to work fine. It recovered and it doesn't crash even when declining the permission too often.

I'd say this is pretty much perfect now (I quite like how the Wear app will try to sync on resume, meaning that if you start the app or wake it up for sleep you see your cards while it syncs on the background), I just have one final nitpick on permission handling: if you deny the permission twice, the toggle will stay disabled with no feedback when you try to enable it again (because of Android blocking constant re-requesting). Can we maybe show a toast, just when tapping it on the settings activity when the permission is denied stating something like "Allow Catima access to nearby devices to sync with your smartwatch"? Or maybe a Snackbar would be even better, then you could open the permissions screen straight from that snackbar:

Android/app/src/main/java/protect/card_locker/ScanActivity.kt

Lines 530 to 537 in dbd0727

	private fun navigateToSystemPermissionSetting() {
	val permissionIntent = Intent(
	Settings.ACTION_APPLICATION_DETAILS_SETTINGS,
	Uri.fromParts("package", getPackageName(), null)
	)
	permissionIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
	startActivity(permissionIntent)
	}

[blacklight]

There you go with your snackbar on denied sync permissions :) c64c3b8

[TheLastProject]

Thanks a lot for this. I do have some things I still want to deal with before going live with this (see #25 (comment)), but this part is approved at least, so I merged it into a new temporary wip/wearos branch.

Once we have these last fixes/features merged into the branch I think we can merge it into main and make a new release :)

[TheLastProject]

Oh, I also forgot to test below Android 12, will still have to do so