Skip to content

refactor: BLE transport and UI for Kotlin Multiplatform unification#4911

Merged
jamesarich merged 9 commits intomainfrom
feat/dedupe
Mar 25, 2026
Merged

refactor: BLE transport and UI for Kotlin Multiplatform unification#4911
jamesarich merged 9 commits intomainfrom
feat/dedupe

Conversation

@jamesarich
Copy link
Copy Markdown
Collaborator

This pull request introduces a new kmp-library-compose classification for Kotlin Multiplatform (KMP) Compose libraries and updates documentation, diagrams, and build logic to reflect this addition. It also refines the main app UI shell setup and clarifies shared helper guidance in the documentation. The most important changes are summarized below:

1. KMP Compose Library Classification and Documentation Updates

  • Added a new kmp-library-compose class definition (with color and style) to all relevant module README files and diagrams, distinguishing KMP Compose libraries from other KMP libraries. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]
  • Updated the core:navigation module’s diagram to use the new kmp-library-compose classification.
  • Added the new KmpLibraryCompose plugin type to the build logic and ensured it is included in the graph dump output. [1] [2]

2. UI Shell and Main Screen Refactoring

  • Replaced usage of MeshtasticCommonAppSetup and MeshtasticSnackbarProvider with the new MeshtasticAppShell component in the main screen (Main.kt), simplifying the UI shell setup and improving code organization. [1] [2] [3] [4]
  • Improved code formatting and readability in the main screen, especially in the handling of unread message badges and icon tinting. [1] [2] [3]

3. Documentation and Guidance Enhancements

  • Updated the architecture overview in GEMINI.md to include new shared transport (BleRadioInterface) in core:network.
  • Expanded the shared helpers guidance in GEMINI.md to reference new examples (MeshtasticAppShell, BaseRadioTransportFactory).

4. Build and Diagram Consistency

  • Updated the barcode and navigation module diagrams to use the correct class references (android-library and kmp-library-compose) for improved accuracy. [1] [2]

5. Minor Code Cleanup

  • Removed an unused import (NodeDetailRoutes) from Main.kt for clarity.

These changes improve the clarity of module classification, streamline the app’s UI structure, and ensure documentation and diagrams accurately reflect the project’s architecture.

This commit refactors the radio transport layer and application UI structure to improve code sharing between Android and Desktop platforms. A common `BleRadioInterface` and `BaseRadioTransportFactory` now handle Bluetooth Low Energy (BLE) logic in `core:network`, while `MeshtasticAppShell` provides a unified UI entry point for navigation, deep linking, and snackbars.

Specific changes include:

- **Transport Layer**:
    - Moved and renamed `BleRadioInterface` to `commonMain` within `core:network` to unify BLE handling.
    - Introduced `BaseRadioTransportFactory` in `commonMain` to handle shared transport logic (BLE, address validation) while delegating platform-specific types (TCP, Serial, USB) to subclasses.
    - Updated `AndroidRadioTransportFactory` and `DesktopRadioTransportFactory` to inherit from the new base class, reducing duplication.
    - Deleted `DesktopBleInterface` as it is now redundant.

- **UI & Navigation**:
    - Created `MeshtasticAppShell` in `core:ui` as a shared wrapper to manage deep link collection, snackbar provision, and common app setup.
    - Updated the main entry points for both Android (`Main.kt`) and Desktop (`DesktopMainScreen.kt`) to utilize the new `MeshtasticAppShell`.
    - Simplified platform-specific UI code by removing duplicate calls to `MeshtasticCommonAppSetup` and snackbar providers.

- **Infrastructure**:
    - Adjusted `core:network` dependencies to include `core:ble` in `commonMain`.
    - Applied code style cleanups and removed unused imports across modified files.

Signed-off-by: James Rich <[email protected]>
This commit continues the migration toward Kotlin Multiplatform (KMP) by moving BLE radio interfaces and top-level UI components to `commonMain`. This consolidation reduces platform-specific code and achieves better feature parity between Android and Desktop.

Key changes include:

- **Network & Transport:**
  - Moved `BleRadioInterface` to `core:network/commonMain`, leveraging Kable for multiplatform BLE support.
  - Introduced `BaseRadioTransportFactory` in `commonMain` to provide a unified factory for TCP, Serial, and BLE transports.
  - Updated documentation to reflect that BLE is now a shared KMP component.

- **UI & Architecture:**
  - Migrated top-level UI composition (`MeshtasticAppShell`) to `commonMain`, eliminating the need for `ui/Main.kt` in the app module.
  - Extracted shared logic and helpers (`handleNodeAction`, `findNodeByNameSuffix`, etc.) to `commonMain` to reduce code duplication across Android and Desktop.
  - Completed migration of node detail and message composables to `commonMain`.

- **Documentation & Maintenance:**
  - Updated `kmp-status.md`, `roadmap.md`, and module READMEs to reflect the current state of KMP integration, including MQTT and BLE parity.
  - Tracked progress on Desktop feature gaps, marking map integration and node detail migration as complete.

Specific changes:
- Updated `core:network` to include `BleRadioInterface` and `BaseRadioTransportFactory` in its exported components.
- Refactored `docs/roadmap.md` to show BLE support as "All (KMP)" instead of platform-specific.
- Updated `GEMINI.md` and `kmp-status.md` to include new shared helpers and unified app shell components.

Signed-off-by: James Rich <[email protected]>
This commit removes the legacy `BleRadioInterfaceFactory` and `BleRadioInterfaceSpec` from the `androidMain` source set. These components are being phased out in favor of a platform-agnostic Bluetooth implementation.

Specific changes include:
- Deleted `BleRadioInterfaceFactory.kt` and `BleRadioInterfaceSpec.kt`.
- Updated `InterfaceFactory` to remove the dependency on `BleRadioInterfaceSpec`.
- Removed `InterfaceId.BLUETOOTH` from the `specMap` within `InterfaceFactory`.

Signed-off-by: James Rich <[email protected]>
…mentations

This commit refactors `BaseRadioTransportFactory` and its platform-specific implementations (Android and Desktop) to improve code readability and maintainability. It transitions from imperative if-else chains to more idiomatic Kotlin `when` expressions and collection-based checks.

Specific changes include:
- **BaseRadioTransportFactory**:
    - Simplified `isAddressValid` logic by using a list of valid `InterfaceId` values and updating the prefix check for "!".
    - Refactored `createTransport` to use a `when` expression for identifying BLE and platform-specific transports.
- **AndroidRadioTransportFactory**: Updated KDoc to clarify the delegation pattern between KMP transports (BLE) and legacy Android-specific interfaces (USB/Serial, TCP, Mock).
- **DesktopRadioTransportFactory**:
    - Refactored `createPlatformTransport` to use a `when` expression for TCP and Serial transport creation.
    - Enhanced KDoc to describe the delegation of multiplatform vs. platform-specific (jSerialComm) transports.
- **Code Style**: Replaced `getOrNull(0)` with `firstOrNull()` and standardized prefix removal logic across transport creation.

Signed-off-by: James Rich <[email protected]>
This commit removes the `core:prefs` dependency from the `androidMain` source set in the `core:network` module to reduce unnecessary coupling.

Specific changes include:
- Removed `projects.core.prefs` from `androidMain` dependencies in `core/network/build.gradle.kts`.

Signed-off-by: James Rich <[email protected]>
This commit updates the documentation and visual dependency graphs across the project to align with recent Kotlin Multiplatform (KMP) refactoring. It introduces new styling for KMP libraries and streamlines the documentation for core testing utilities.

Specific changes include:
- **Build Logic & Graph Generation**:
    - Added `KmpLibraryCompose` to the `PluginType` configuration in `Graph.kt`.
    - Updated `ComposeDesktopApplication` identification logic.
    - Added "KMP Library" to the Mermaid legend generated for module READMEs.
- **Documentation Updates**:
    - Rewrote `core/testing/README.md` to be more concise, focusing on its role as a KMP library providing shared fakes, coroutine utilities, and Mokkery support.
    - Updated Mermaid diagrams in nearly all module `README.md` files to include the `kmp-library-compose` class definition.
- **Module Classification**:
    - Reclassified several modules (e.g., `core:nfc`, `core:navigation`, `core:resources`, `core:ui`) from `compose-desktop-application` to `kmp-library-compose` in their respective graph definitions.
    - Updated `core:barcode` classification to `android-library`.

Signed-off-by: James Rich <[email protected]>
Signed-off-by: James Rich <[email protected]>
@github-actions github-actions bot added the enhancement New feature or request label Mar 25, 2026
Signed-off-by: James Rich <[email protected]>
Signed-off-by: James Rich <[email protected]>
@jamesarich jamesarich added this pull request to the merge queue Mar 25, 2026
Merged via the queue into main with commit 6516287 Mar 25, 2026
7 checks passed
@jamesarich jamesarich deleted the feat/dedupe branch March 25, 2026 02:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant