# don/bluetoothserial architecture

> Architecture diagram of the GitHub repository don/bluetoothserial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/don/bluetoothserial
- Repository: https://github.com/don/bluetoothserial

## Overview

##### Project Type and Purpose
- This is a Cordova/PhoneGap plugin (“cordova-plugin-bluetooth-serial”) that provides a JavaScript API for serial communication over Bluetooth (Classic on Android/Windows Phone, BLE on iOS).
- It plugs into the Cordova runtime, exposes a `bluetoothSerial` JS object, and routes calls to native implementations on each supported platform.
- Sample hybrid apps in the `examples/` folder demonstrate usage with Arduino hardware.

##### File-Structure Analysis
- Top-level:
- plugin.xml – plugin metadata, platform hooks, JS/native mappings
- www/bluetoothSerial.js – the common JavaScript interface used at runtime
- src/ – per-platform native code subdirectories:
– android/com/megster/cordova/*.java
– ios/*.h/.m (CoreBluetooth wrappers)
– wp/*.cs
– browser/bluetoothSerial.js (test shim)
- examples/ – sample Cordova projects demonstrating the plugin
- No backend or database; all logic resides in client-side JS and native modules calling OS Bluetooth stacks.

##### README Insights
- Defines supported platforms, limitations, installation via `cordova plugin add`, and full API reference.
- Mentions use of Android’s BluetoothChat example and RedBearLab BLE Framework on iOS.

a. Main Components
1. Hybrid Application Layer
– Your app’s web UI (HTML/CSS/JS)
– Calls to `bluetoothSerial.*` methods
2. Plugin JavaScript Bridge (www/bluetoothSerial.js)
– Defines wrapper methods, marshals parameters
– Invokes Cordova exec calls
3. Cordova Native Bridge
– Cordova exec mechanism
– plugin.xml mapping between JS calls and native class/method
4. Native Platform Modules
– Android: BluetoothSerial.java + BluetoothSerialService.java
– iOS: MEGBluetoothSerial.m, BLEFramework wrappers
– WP: BluetoothSerial.cs, BluetoothConnectionManager.cs
– Browser: Test shim in src/browser/bluetoothSerial.js
5. OS Bluetooth Stack
– Android BluetoothAdapter/BluetoothSocket
– CoreBluetooth on iOS
– Windows Phone Bluetooth APIs
6. External Hardware
– Arduino (Classic BT shields or BLE peripherals)
– Any BLE UART-like service devices
b. Relationships and Data Flow
- Callbacks flowing back along the same path in reverse.
c. Architectural Patterns & Principles
- Adapter pattern: JS wrapper adapts your calls to Cordova exec interface.
- Strategy per platform: each `src/<platform>` folder implements the same API in its native language.
- Separation of concerns: UI layer, plugin bridge, native implementation, hardware interface.
d. Key Technologies
- JavaScript, Cordova exec
- Java + Android Bluetooth APIs
- Objective-C + CoreBluetooth (plus RedBearLab BLE framework)
- C# + WP Bluetooth APIs
- Arduino firmware (.ino sketches)

##### Detail Level
- Don’t just show “Plugin” → “Native”. Break out Android, iOS, WP, Browser modules.
- That all platform modules implement the same API surface.
- `examples/` folder as a consumer, illustrating how sample apps invoke the plugin.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hybrid Application Layer
    subgraph "Hybrid Application Layer"
        direction TB
        Chat["Chat Example (www)"]:::js
        Counter["Counter Example (www)"]:::js
        LED["LED Example (www)"]:::js
        SimpleSerial["SimpleSerial Example (www)"]:::js
    end

    %% Plugin JavaScript Bridge
    subgraph "JavaScript Bridge"
        direction TB
        JSBridge["bluetoothSerial.js"]:::js
        BrowserShim["Browser Test Shim\n(src/browser/bluetoothSerial.js)"]:::js
    end

    %% Cordova Core Bridge
    subgraph "Cordova Bridge"
        direction TB
        PluginXML["plugin.xml"]:::cordova
        Exec["Cordova exec()"]:::cordova
    end

    %% Native Platform Modules
    subgraph "Native Platform Modules"
        direction TB
        subgraph Android
            direction TB
            AndroidSerial["BluetoothSerial.java"]:::native
            AndroidService["BluetoothSerialService.java"]:::native
        end
        subgraph iOS
            direction TB
            iOSSerialH["MEGBluetoothSerial.h"]:::native
            iOSSerialM["MEGBluetoothSerial.m"]:::native
            BLEH["BLE.h"]:::native
            BLEM["BLE.m"]:::native
            BLEDefines["BLEDefines.h"]:::native
            CBExtH["CBPeripheral+BTSExtensions.h"]:::native
            CBExtM["CBPeripheral+BTSExtensions.m"]:::native
        end
        subgraph WP
            direction TB
            WPSerial["BluetoothSerial.cs"]:::native
            WPManager["BluetoothConnectionManager.cs"]:::native
        end
    end

    %% OS Bluetooth Stacks
    subgraph "OS Bluetooth Stack"
        direction TB
        AndroidOS["Android BluetoothAdapter/\nBluetoothSocket"]:::os
        iOSOS["CoreBluetooth"]:::os
        WPOS["WP Bluetooth APIs"]:::os
    end

    %% External Hardware
    ExternalHW["External Hardware\n(Arduino, BLE devices)"]:::hw

    %% Data Flow
    Chat -->|"bluetoothSerial.* calls"| JSBridge
    Counter -->|"bluetoothSerial.* calls"| JSBridge
    LED -->|"bluetoothSerial.* calls"| JSBridge
    SimpleSerial -->|"bluetoothSerial.* calls"| JSBridge

    JSBridge -->|"exec(...)"| Exec
    BrowserShim -->|"exec(...)"| Exec

    Exec -->|"mapped in plugin.xml"| PluginXML
    PluginXML -->|"invokes native"| AndroidSerial
    PluginXML -->|"invokes native"| AndroidService
    PluginXML -->|"invokes native"| iOSSerialM
    PluginXML -->|"invokes native"| WPSerial
    PluginXML -->|"invokes native"| WPManager

    AndroidSerial -->|"uses"| AndroidOS
    AndroidService -->|"uses"| AndroidOS
    iOSSerialM -->|"uses"| iOSOS
    WPSerial -->|"uses"| WPOS
    WPManager -->|"uses"| WPOS

    AndroidOS -->|"radio link"| ExternalHW
    iOSOS -->|"radio link"| ExternalHW
    WPOS -->|"radio link"| ExternalHW

    %% Callbacks Flow Back
    ExternalHW -->|"data events"| AndroidOS
    ExternalHW -->|"data events"| iOSOS
    ExternalHW -->|"data events"| WPOS

    AndroidOS -->|"callback"| AndroidService
    iOSOS -->|"callback"| iOSSerialM
    WPOS -->|"callback"| WPManager

    AndroidService -->|"exec callback"| Exec
    iOSSerialM -->|"exec callback"| Exec
    WPManager -->|"exec callback"| Exec

    Exec -->|"onSuccess/onError"| JSBridge
    JSBridge -->|"returns Promise/callback"| Chat
    JSBridge -->|"returns Promise/callback"| Counter
    JSBridge -->|"returns Promise/callback"| LED
    JSBridge -->|"returns Promise/callback"| SimpleSerial

    %% Click Events
    click PluginXML "https://github.com/don/bluetoothserial/blob/master/plugin.xml"
    click JSBridge "https://github.com/don/bluetoothserial/blob/master/www/bluetoothSerial.js"
    click BrowserShim "https://github.com/don/bluetoothserial/blob/master/src/browser/bluetoothSerial.js"
    click AndroidSerial "https://github.com/don/bluetoothserial/blob/master/src/android/com/megster/cordova/BluetoothSerial.java"
    click AndroidService "https://github.com/don/bluetoothserial/blob/master/src/android/com/megster/cordova/BluetoothSerialService.java"
    click iOSSerialH "https://github.com/don/bluetoothserial/blob/master/src/ios/MEGBluetoothSerial.h"
    click iOSSerialM "https://github.com/don/bluetoothserial/blob/master/src/ios/MEGBluetoothSerial.m"
    click BLEH "https://github.com/don/bluetoothserial/blob/master/src/ios/BLE.h"
    click BLEM "https://github.com/don/bluetoothserial/blob/master/src/ios/BLE.m"
    click BLEDefines "https://github.com/don/bluetoothserial/blob/master/src/ios/BLEDefines.h"
    click CBExtH "https://github.com/don/bluetoothserial/blob/master/src/ios/CBPeripheral+BTSExtensions.h"
    click CBExtM "https://github.com/don/bluetoothserial/blob/master/src/ios/CBPeripheral+BTSExtensions.m"
    click WPSerial "https://github.com/don/bluetoothserial/blob/master/src/wp/BluetoothSerial.cs"
    click WPManager "https://github.com/don/bluetoothserial/blob/master/src/wp/BluetoothConnectionManager.cs"
    click Chat "https://github.com/don/bluetoothserial/tree/master/examples/Chat/www"
    click Counter "https://github.com/don/bluetoothserial/tree/master/examples/Counter/www"
    click LED "https://github.com/don/bluetoothserial/tree/master/examples/LED/www"
    click SimpleSerial "https://github.com/don/bluetoothserial/tree/master/examples/SimpleSerial/www"

    %% Styles
    classDef js fill:#cce5ff,stroke:#0366d6,color:#000
    classDef cordova fill:#d4edda,stroke:#28a745,color:#000
    classDef native fill:#fff3cd,stroke:#e0a800,color:#000
    classDef os fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef hw fill:#f5e1da,stroke:#b35d00,color:#000
```
