ble-reticulum/COLUMBA_REFACTORING_GUIDE.md

Refactoring Columba's BLE Layer to a Driver-Based Architecture

1. Goal

This guide outlines the process of refactoring the existing BLE implementation in the Columba Android project to align with the new driver-based architecture of the ble-reticulum project.

The goal is to:

• Reuse the battle-tested BLEInterface.py from ble-reticulum as the main Reticulum logic for BLE in Columba.
• Create a new Android-specific BLE driver in Python (AndroidBLEDriver.py) that implements the BLEDriverInterface.
• Bridge this new Python driver to a dedicated Kotlin class (KotlinBLEBridge.kt) that handles all native Android BLE operations.
• Isolate the Kotlin BLE logic from the rest of the Columba UI application, with the KotlinBLEBridge acting as the sole entry point for the Python layer.

This will result in a more modular, maintainable, and testable system, and will allow Columba to easily stay up-to-date with the latest improvements in the ble-reticulum project.

2. Current State Analysis

Based on the file structure of the Columba project, the current BLE implementation is a monolithic Kotlin implementation with a Python bridge.

• Kotlin: The core BLE logic is in the com.lxmf.messenger.reticulum.ble package, with classes like BleConnectionManager, BleGattClient, BleGattServer, BleScanner, and BleAdvertiser.
• Python: The rn_ble_interface.py script acts as the Chaquopy bridge, importing and using the Kotlin classes to create a Reticulum interface.

This architecture is tightly coupled, making it difficult to update and maintain. The new driver-based architecture will address these issues.

3. Proposed Architecture

The new architecture will consist of three main components:

1. BLEInterface.py: The high-level, platform-agnostic Reticulum interface logic from the ble-reticulum project.
2. AndroidBLEDriver.py: A new Python class that implements the BLEDriverInterface and acts as a bridge to the Kotlin layer.
3. KotlinBLEBridge.kt: A new, isolated Kotlin class that exposes a clean API for the AndroidBLEDriver.py to interact with the native Android BLE stack.

This architecture will allow us to reuse the BLEInterface.py and only implement the platform-specific BLE operations in the AndroidBLEDriver.py and KotlinBLEBridge.kt.

4. Step-by-Step Refactoring Guide

Step 1: Create the KotlinBLEBridge.kt

Create a new Kotlin class, KotlinBLEBridge.kt, in the com.lxmf.messenger.reticulum.ble.service package. This class will be the single entry point for all BLE operations from the Python layer. It should be a singleton and should not have any dependencies on the Columba UI.

The KotlinBLEBridge.kt class should expose methods that correspond to the BLEDriverInterface in Python. For example:

class KotlinBLEBridge(private val context: Context) {

    fun start(serviceUuid: String, rxCharUuid: String, txCharUuid: String, identityCharUuid: String) {
        // Initialize the BLE stack
    }

    fun stop() {
        // Stop all BLE activity
    }

    fun setIdentity(identityBytes: ByteArray) {
        // Set the identity for the GATT server
    }

    fun startScanning() {
        // Start scanning for devices
    }

    fun stopScanning() {
        // Stop scanning
    }

    fun startAdvertising(deviceName: String) {
        // Start advertising
    }

    fun stopAdvertising() {
        // Stop advertising
    }

    fun connect(address: String) {
        // Connect to a device
    }

    fun disconnect(address: String) {
        // Disconnect from a device
    }

    fun send(address: String, data: ByteArray) {
        // Send data to a device
    }

    // ... other methods as needed
}

This class will also be responsible for invoking the callbacks on the Python driver. You can use a listener interface to achieve this.

Step 2: Create the AndroidBLEDriver.py

Create a new Python file, AndroidBLEDriver.py, in the columba/app/src/main/python directory. This class will implement the BLEDriverInterface and will use Chaquopy to call the methods of the KotlinBLEBridge.

from com.chaquo.python import Python
from RNS.Interfaces.bluetooth_driver import BLEDriverInterface, BLEDevice, DriverState

class AndroidBLEDriver(BLEDriverInterface):
    def __init__(self):
        self.kotlin_ble_bridge = Python.getPlatform().getApplication().getKotlinBLEBridge()
        # Set up callbacks from Kotlin to Python
        # ...

    def start(self, service_uuid, rx_char_uuid, tx_char_uuid, identity_char_uuid):
        self.kotlin_ble_bridge.start(service_uuid, rx_char_uuid, tx_char_uuid, identity_char_uuid)

    def stop(self):
        self.kotlin_ble_bridge.stop()

    # ... implement all other methods of the BLEDriverInterface

Step 3: Refactor rn_ble_interface.py

Modify the existing rn_ble_interface.py to use the new BLEInterface and AndroidBLEDriver.

# rn_ble_interface.py

from RNS.Interfaces.BLEInterface import BLEInterface
from AndroidBLEDriver import AndroidBLEDriver

# ... other imports

class RNBLEInterface(BLEInterface):
    def __init__(self, owner, config):
        driver = AndroidBLEDriver()
        super().__init__(owner, config, driver=driver)

# ... rest of the file

Step 4: Replace the old BLE implementation

Once the new driver-based architecture is in place, you can start removing the old BLE implementation in the Columba project. This includes classes like BleConnectionManager, BleGattClient, BleGattServer, etc. The new KotlinBLEBridge should encapsulate all the necessary BLE logic.

5. Testing

Thorough testing is crucial for this refactoring.

• Unit Tests: Write unit tests for the KotlinBLEBridge to ensure that it correctly interacts with the Android BLE stack.
• Integration Tests: Write integration tests that verify the communication between the AndroidBLEDriver.py and the KotlinBLEBridge.kt.
• End-to-End Tests: Run the full Columba application and test the BLE functionality to ensure that everything works as expected.

By following this guide, you can refactor the Columba BLE layer to a more modern, modular, and maintainable architecture, while at the same time reusing the battle-tested BLEInterface.py from the ble-reticulum project.