How kieronquinn/utag works
• The primary “app” module contains most of the Android UI, business logic, data models, and networking/repository code (using MVVM/MVP-like patterns and Room databases).
• The “uwb” module that appears to provide support for Ultra Wideband (UWB) functionality (for precise “finding” with UWB-capable devices).
• The “xposed‐core” and “xposed‐standalone” modules supply the Xposed integration (for patching and extending the official Samsung SmartThings app) – integrated via LSPosed/LSPatch workflows.
Main Components and Their Roles
a. UI Layer (within “app”):
– Activity & Fragment screens (located in app/src/main/java/.../ui and its subpackages) that present user interfaces for tracking, setting up SmartTags, showing location history, finding a Tag, handling settings (including Content Creator Mode) and more.
– Custom views and widgets (e.g., the custom preferences, progress buttons, and map views).
b. Business Logic / ViewModels:
– Each screen has its corresponding ViewModel (e.g., in the “ui/screens”, “ui/activities” packages) which encapsulates the UI logic.
c. Data and Repository Layer:
– Repositories (under app/src/main/java/.../repositories) which mediate between the network/data sources and the UI. They interact with local Room databases (database packages under “model/database”) and other caching components.
d. Network & API Services:
– A networking module exists (in app/src/main/java/.../networking) which defines interceptors, models, and service classes for communication with external APIs (Samsung APIs, SmartThings mod, location services using Google Maps, etc.).
e. UWB Module:
– The “uwb” module provides additional functionality for devices with UWB support. It is a separate Gradle module with its own structure (and independent AndroidManifest) handling UWB protocols and specifics.
f. Xposed Integration Modules:
– “xposed-core” and “xposed-standalone” supply components and AIDL interfaces to integrate with (and patch) the official SmartThings APK, allowing uTag to modify its behavior at runtime. These modules include AIDL interfaces, providers, and helper classes that inject code via Xposed/LSPosed.
g. External Services & APIs:
– SmartThings APIs (accessed via a combination of uTag’s networking and via mod patched SmartThings).
– Google Maps API (configured via the secrets and keystore properties, used in mapping locations).
– Samsung Find My Mobile network APIs (via the extraction of shared library “libfmm_ct.so” and interactions in the “app” module).
Relationships and Data Flow
– The UI components send events (e.g., user interactions to connect a Tag, view location history, etc.) to their corresponding ViewModels.
– ViewModels call methods in the Repository layer, which decide whether to retrieve data from the local database (via Room) or remote servers (via Retrofit-type networking services).
– Networking services perform calls to external Samsung or SmartThings APIs. For Bluetooth interactions, dedicated components in the “app” module (such as within components/bluetooth) manage device discovery and connections.
– The UWB module handles a subset of these communications (where precision finding is needed) and communicates with the UI or business logic through its own abstractions.
– The xposed modules patch into the SmartThings app. They provide AIDL interfaces for services that allow seamless integration and proxying of functionality from the patched SmartThings APK. LSPosed (via LSPatch) acts as the delivery mechanism that integrates the xposed modules with the official app.
Architectural Patterns & Technologies
– Modularization: the project is split into at least three distinct modules (app, uwb, xposed modules) that are built and maintained independently.
– Android MVVM (or similar) is used to separate concerns between UI, ViewModels, and repositories.
– Offline caching/room persistence (the “database” packages in app) is used to store Tag data, location history, and settings.
– AIDL is leveraged (for the xposed modules) to define IPC interfaces for Bluetooth, location callbacks, and SmartThings integrations.
– Use of Gradle Kotlin DSL in build files (build.gradle.kts) indicates modern Android build practices.
– Integration with external APIs such as Google Maps and Samsung APIs requires secure key management and patching (as explained in the README).