BLE Connection & Data Flow Overview

This diagram describes the full lifecycle of a BLE operation in the app, from checking the phone’s BLE status, to scanning and connecting, all the way to reading and writing data once the device is ready.

┌──────────┐
│   START  │
└────┬─────┘
     │
     ▼
┌─────────────────────┐
│Check BLE Status     │ ──────> getPhoneBleStatus()
└────┬────────────────┘
     │
     ▼
┌─────────────────────┐
│ Register Callbacks  │
│ - findDeviceCallback│
│ - connectSuccess    │
│ - connectFail       │
└────┬────────────────┘
     │
     ▼
┌─────────────────────┐
│  Start BLE Scan     │ ──────> startBleScan()
└────┬────────────────┘         ↓
     │                           ↓ (Scanning...)
     │                    findDeviceCallback
     │                      ↓  ↓  ↓  ↓  ↓
     │                    [Device List]
     ▼
┌─────────────────────┐
│   Stop Scan         │ ──────> stopBleScan()
└────┬────────────────┘
     │
     ▼
┌─────────────────────┐
│ Connect to Device   │ ──────> connBleByMacAddress()
└────┬────────────────┘
     │
     ├──────────────┬──────────────┐
     ▼              ▼              ▼
  Success      connectFail    Timeout
     │
     ▼
┌─────────────────────┐
│ Initialize Data     │ ──────> initBleData()
└────┬────────────────┘         ↓
     │                    Progress Updates
     │                      ↓  ↓  ↓  ↓
     │                    [Loading...]
     ▼
┌─────────────────────┐
│ Data Ready          │ ──────> onCompleteCallback
└────┬────────────────┘
     │
     ├──────────────┬──────────────┐
     ▼              ▼              ▼
┌─────────┐   ┌─────────┐   ┌─────────┐
│  Read   │   │  Write  │   │ Notify  │
│  Data   │   │  Data   │   │  Enable │
└─────────┘   └─────────┘   └─────────┘
     │              │              │
     └──────────────┴──────────────┘
                    │
                    ▼
              ┌──────────┐
              │   END    │
              └──────────┘

At a high level, the flow is:

1. Check BLE Status → getPhoneBleStatus()

• Verify that the phone supports BLE and that Bluetooth is turned on (and any required permissions are granted).
• If BLE is not available or disabled, the flow should stop here and prompt the user.

2. Register Callbacks

• Register JavaScript handlers so that the native layer can push events back into the WebView:
  • findDeviceCallback – called whenever a device is discovered during scanning.
  • connectSuccess – called when a connection to a device succeeds.
  • connectFail – called when a connection attempt fails (including timeouts or errors). This makes the whole process event-driven instead of using polling.

3. Start BLE Scan → startBleScan()

• Begin scanning for nearby BLE devices.
• While scanning:
  • Native code discovers devices.
  • For each device, the native layer calls findDeviceCallback with details (e.g. name, MAC address, RSSI).
  • The WebView updates the Device List shown to the user.

4. Stop Scan → stopBleScan()

• Once the user has selected a device from the list, scanning is stopped to save power and reduce noise.
• The selected device (typically identified by its MAC address) is then used for the connection step.

5. Connect to Device → connBleByMacAddress()

• Initiate a connection to the selected device using its MAC address.
• From here, there are three possible outcomes:
  • Success → the connectSuccess callback is invoked by native code.
  • Failure → the connectFail callback is invoked (e.g. device rejected, out of range).
  • Timeout → treated as a failure, often also reported through connectFail with a timeout reason.
• On success, the flow proceeds to data initialization.

6. Initialize Data → initBleData()

• After a successful connection, the app prepares the device for use:
  • Discover services and characteristics.
  • Set up internal mappings for read/write/notify operations.
  • Optionally load some initial values from the device. During this step, the UI typically shows Loading… with progress updates as native code reports initialization progress.

7. Data Ready → onCompleteCallback

• When initialization is complete, native notifies the WebView (e.g. via onCompleteCallback).
• At this point:
  • The loading state is removed.
  • The main device controls are enabled, and the user can now interact with the device.

8. Read / Write / Notify

• With the device fully initialized, the app supports three main interaction types:
  • Read Data – read current values from a characteristic (e.g. sensor values, battery level).
  • Write Data – send commands or configuration values to the device.
  • Notify Enable – subscribe to characteristic notifications so the device can push updates automatically.
• These operations can be repeated as needed until the user disconnects or leaves the screen, at which point the flow effectively reaches END and can be restarted if required.

This flow ensures a clear, step-by-step BLE workflow: Status Check → Callbacks → Scan → Connect → Initialize → Interact (Read/Write/Notify).