核心类与回调接口

本页深入解析 ATTConnect 示例工程 BLE 模块的核心类（BleManager、BleEventCallbackManager、SendBleDataThread）与回调接口体系（IBleEventCallback、BleEventCallback、IBleOp、IBtScanCallback、OnWriteDataCallback、OnThreadStateListener），说明它们的职责、协作方式与事件分发机制。

Purpose and Scope

本页面向需要理解或扩展 ATTConnect BLE 通信链路的开发者，覆盖：

• 核心门面类 BleManager 的单例设计、状态字段与超时消息机制；
• 事件回调的"注册—分发—注销"生命周期及主线程投递逻辑（BleEventCallbackManager）；
• 回调接口/抽象类的完整方法清单与设计意图（空实现适配器模式）；
• 串行发送线程 SendBleDataThread 的 MTU 分块、等待回调与重试机制；
• 核心流程（扫描 → 连接 → 服务发现 → 通知 → 写数据）的端到端时序。

不在本页范围：BLE 具体协议指令解析、设备配对与 HID 设备管理、UI 层业务逻辑、工具类（CHexConver、UuidUtil、BluetoothUtil）的细节。这些内容属于各自的能力页面（如协议层、设备管理、工具库）。

Overview

ATTConnect 是杰理科技（Jieli-Tech）的 Android 蓝牙示例工程，其 tool/ble 包封装了完整的 BLE GATT 客户端能力。整个模块采用门面模式 + 观察者模式的组合：

• BleManager 作为单例门面，对上层屏蔽 Android BluetoothAdapter / BluetoothLeScanner / BluetoothGatt 的复杂交互，所有 BLE 操作（扫描、连接、读写、MTU 协商）都经由它发起；
• BleEventCallbackManager 作为观察者分发器，接收 BleManager 内部产生的原生回调，统一切换到主线程后，扇出（fan-out）给所有注册的 BleEventCallback，使 UI 层可以安全地直接刷新界面；
• SendBleDataThread 作为串行发送引擎，解决 Android BLE 写操作必须串行、且 onCharacteristicWrite 回调需要等待的经典问题，按 MTU 自动分块、超时重试。

回调接口体系采用"接口 + 抽象类 + 管理器"三层结构：IBleEventCallback 定义契约，BleEventCallback 提供空实现（适配器模式，让调用方只需覆写关心的事件），BleEventCallbackManager 负责多订阅者分发。

Architecture

flowchart TD
    subgraph sg_App["应用层 (ATTConnect)"]
        Activity["Activity / UI 层"]
        MyApplication["MyApplication"]
    end

    subgraph sg_Core["核心层 (tool/ble)"]
        BleManager["BleManager<br/>(单例门面)"]
        CallbackMgr["BleEventCallbackManager<br/>(回调分发器)"]
        SendThread["SendBleDataThread<br/>(串行发送线程)"]
        Handler["主线程 Handler<br/>(超时消息 0x1010~0x1017)"]
    end

    subgraph sg_Interfaces["回调接口层 (interfaces)"]
        IBleEventCallback["IBleEventCallback"]
        BleEventCallback["BleEventCallback<br/>(抽象空实现)"]
        IBleOp["IBleOp"]
        IBtScanCallback["IBtScanCallback"]
        OnWriteCallback["OnWriteDataCallback"]
        OnThreadState["OnThreadStateListener"]
    end

    subgraph sg_Model["数据模型层 (model)"]
        BleDevice["BleDevice"]
        ScanDeviceInfo["ScanDeviceInfo"]
    end

    subgraph sg_Android["Android 系统层"]
        BTAdapter["BluetoothAdapter"]
        Scanner["BluetoothLeScanner"]
        Gatt["BluetoothGatt"]
    end

    Activity --> BleManager
    MyApplication --> BleManager
    BleManager --> CallbackMgr
    BleManager --> SendThread
    BleManager --> Handler
    BleManager --> BTAdapter
    BleManager --> Scanner
    BleManager --> Gatt
    BleManager --> BleDevice
    BleManager --> ScanDeviceInfo
    CallbackMgr --> BleEventCallback
    BleEventCallback --> IBleEventCallback
    SendThread --> OnWriteCallback
    SendThread --> OnThreadState
    BleManager --> IBleOp
    Activity --> IBtScanCallback
    Activity --> OnWriteCallback
    Activity --> BleEventCallback

架构要点：

1. BleManager 是唯一入口：上层 Activity 不直接触碰 Android BLE API，全部通过 BleManager 单例（volatile static BleManager instance，见 BleManager.java）完成，降低 Android 版本差异与权限处理复杂度。
2. 事件单向流动：Android 原生回调 → BleManager 内部转换 → BleEventCallbackManager → 主线程 Handler → 已注册的多个 BleEventCallback。UI 层只依赖 BleEventCallback 抽象类，与 BleManager 解耦。
3. 发送路径独立：写数据走 SendBleDataThread 独立线程 + OnWriteDataCallback，与事件回调路径并行，避免长数据包阻塞 UI 线程。
4. 配置驱动 UUID：服务/写/通知 UUID 均来自 Config.INSTANCE（BLE_UUID_SERVICE 等），描述符 UUID 固定为 00002902-0000-1000-8000-00805F9B34FB（见 BleManager.java），便于接入不同杰理芯片方案。

核心类详解

BleManager — BLE 连接管理单例

BleManager 是整个 BLE 模块的心脏，声明为 public class BleManager，通过 volatile static 字段实现线程安全的懒加载单例（见 BleManager.java）：

private final Context mContext;
@SuppressLint("StaticFieldLeak")
private volatile static BleManager instance;

private BaseBtAdapterReceiver mAdapterReceiver;
private final BluetoothAdapter mBluetoothAdapter;
private BluetoothLeScanner mBluetoothLeScanner;

private volatile BluetoothDevice mUsingDevice;            //正在通讯的设备

private final Map<String, BleDevice> mBleDeviceMap = new HashMap<>();
private final List<BluetoothDevice> mDiscoveredBleDevices = new ArrayList<>();
private final BleEventCallbackManager mCallbackManager = new BleEventCallbackManager();

设计意图：

• mUsingDevice 用 volatile 标记"正在通讯的设备"，因为该字段会被扫描、连接、发送等多个线程读写，可见性必须保证；
• mBleDeviceMap（按地址索引的设备信息表）与 mDiscoveredBleDevices（发现设备列表）分离，前者保存完整状态，后者仅用于扫描展示；
• mCallbackManager 是回调分发枢纽，BleManager 内部产生的所有事件都交给它转发。

关键常量与超时策略

这些常量定义于 BleManager.java。所有超时均由主线程 Handler 以消息驱动，消息码从 MSG_SCAN_BLE_TIMEOUT = 0x1010 到 MSG_BOUND_DEVICE_TIMEOUT = 0x1017，覆盖扫描、连接、通知、MTU 协商、服务发现、断开、绑定 7 类超时场景。这种"消息 + 超时"设计让每个异步 BLE 操作都有兜底，避免回调丢失时流程永久挂起。

BleEventCallbackManager — 回调分发器

BleEventCallbackManager 自身继承 BleEventCallback（见 BleEventCallbackManager.java），因此它对外呈现的仍是"一个回调"，内部则维护订阅者列表实现一对多广播：

public class BleEventCallbackManager extends BleEventCallback  {
    private final ArrayList<BleEventCallback> mCallbacks = new ArrayList<>();
    private final Handler mHandler = new Handler(Looper.getMainLooper());

    public void registerBleEventCallback(BleEventCallback callback) {
        if (callback != null && !mCallbacks.contains(callback)) {
            mCallbacks.add(callback);
        }
    }

    public void unregisterBleEventCallback(BleEventCallback callback) {
        if (callback != null && !mCallbacks.isEmpty()) {
            mCallbacks.remove(callback);
        }
    }

    public void release() {
        mCallbacks.clear();
        mHandler.removeCallbacksAndMessages(null);
    }

设计意图：

• 注册时用 contains 去重，防止同一订阅者重复注册导致事件被多次回调；
• release() 同时清空订阅者列表与主线程消息队列，用于 Activity 销毁等生命周期收尾，避免内存泄漏；
• 回调全部通过 mHandler（主线程 Looper）投递，见下方线程分派逻辑：

private void callbackBleEvent(BleEventCallbackImpl impl) {
    if (null == impl) return;
    OnBleEventRunnable runnable = new OnBleEventRunnable(impl);
    if (Thread.currentThread().getId() == Looper.getMainLooper().getThread().getId()) {
        runnable.run();          // 已在主线程 → 直接执行
    } else {
        mHandler.post(runnable); // 非主线程 → 投递到主线程队列
    }
}

来源：BleEventCallbackManager.java

该实现通过 Thread.currentThread().getId() == Looper.getMainLooper().getThread().getId() 判断是否已处于主线程：是则同步直接执行（避免不必要的消息排队延迟），否则投递到主线程消息队列。OnBleEventRunnable 遍历 mCallbacks 逐个调用对应事件方法，实现扇出分发。

SendBleDataThread — 串行发送引擎

发送线程解决 Android BLE 的三大经典问题：写操作必须串行、单包 MTU 限制、回调必须等待（见 SendBleDataThread.java）：

public boolean addSendTask(BluetoothGatt gatt, UUID serviceUUID, UUID characteristicUUID, byte[] data, OnWriteDataCallback callback) {
    if (null == mBleManager || null == gatt || null == serviceUUID || null == characteristicUUID || null == data || data.length == 0) {
        return false;   // 参数校验，任一为空直接拒绝
    }
    ...
    // 按 MTU 分块：整块 + 余数块
    if (data.length % mtu == 0) {
        for (int i = 0; i < data.length; i += mtu) {
            System.arraycopy(data, i, mBlockData, 0, mBlockData.length);
            ret = addSendData(gatt, serviceUUID, characteristicUUID, mBlockData, callback);
        }
    } else {
        // 先发送整块部分，再发送余数
        ...
        ret = addSendData(gatt, serviceUUID, characteristicUUID, noBlockData, callback);
    }
}

其内部状态机使用 volatile 标志位 isThreadWaiting（线程是否在等待队列通知）与 isWaitingForCallback（是否在等待写回调），配合 mQueue.notifyAll() / mQueue.notify() 实现生产者-消费者同步；retryNum 记录重试次数。每个任务封装为 BleSendTask（携带 gatt、UUID、数据与回调），入队后由工作线程按顺序取出执行，写入后阻塞等待 onCharacteristicWrite 回调，超时（SEND_DATA_MAX_TIMEOUT）或失败则按策略重试。

数据模型层

• BleDevice：描述一个 BLE 设备，封装地址、名称、RSSI、连接状态等（见 BleDevice.java）；
• ScanDeviceInfo：扫描结果信息体，随 onDiscoveryDevice 回调分发，供 UI 展示扫描列表（见 ScanDeviceInfo.java）。

两者均为轻量 POJO，其设计意图是将 Android 平台类型（BluetoothDevice）与业务数据解耦：BleDevice 提供业务维度的状态追踪，ScanDeviceInfo 作为扫描事件的载体，避免上层直接依赖 Android SDK 类型，便于测试与替换。

回调接口体系

回调接口全部位于 tool/ble/interfaces 包，采用"接口定义契约 → 抽象类提供空实现 → 管理器/线程负责分发"的三层结构，这是典型的适配器模式：调用方无需实现全部方法，只覆写关心的事件即可。

IBleEventCallback / BleEventCallback — BLE 事件回调

BleEventCallback 是抽象类，实现 IBleEventCallback 并为全部 11 个事件提供空实现（见 BleEventCallback.java）：

public abstract class BleEventCallback implements IBleEventCallback {

    @Override
    public void onAdapterChange(boolean bEnabled) { }

    @Override
    public void onDiscoveryState(boolean bStart) { }

    @Override
    public void onDiscoveryDevice(ScanDeviceInfo bleScanMessage) { }

    @Override
    public void onDiscoveryFail(int code, String message) { }

    @Override
    public void onBleConnection(BluetoothDevice device, int status) { }

    @Override
    public void onBleServiceDiscovery(BluetoothDevice device, int status, List<BluetoothGattService> services) { }

    @Override
    public void onBleNotificationStatus(BluetoothDevice device, UUID serviceUuid, UUID characteristicUuid, int status) { }

    @Override
    public void onBleDataBlockChanged(BluetoothDevice device, int block, int status) { }

    @Override
    public void onBleDataNotification(BluetoothDevice device, UUID serviceUuid, UUID characteristicsUuid, byte[] data) { }

    @Override
    public void onBleWriteStatus(BluetoothDevice device, UUID serviceUuid, UUID characteristicsUuid, byte[] data, int status) { }

    @Override
    public void onConnectionUpdated(BluetoothDevice device, int interval, int latency, int timeout, int status) { }
}

各事件的设计意图：

IBleOp — BLE 操作契约

IBleOp 是操作侧的最小接口（见 IBleOp.java）：

public interface IBleOp {

    int getBleMtu();

    boolean writeDataByBle(BluetoothGatt gatt, UUID serviceUUID, UUID characteristicUUID, byte[] data);
}

它抽象了"查询 MTU"与"经 BLE 写数据"两个原子操作，与事件回调 IBleEventCallback 形成命令/事件分离：IBleOp 描述上层能做什么（发指令），IBleEventCallback 描述上层会收到什么（收事件）。

其他回调接口

• IBtScanCallback：扫描专用回调（tool/ble/interfaces/IBtScanCallback.java），将扫描结果与 BLE 连接事件解耦，供 BleManager 内部扫描流程使用；
• OnWriteDataCallback：写数据结果回调，由 SendBleDataThread 在写入完成或失败时触发（见 SendBleDataThread.java）；
• OnThreadStateListener：发送线程状态监听（启动/停止/异常），用于上层感知后台线程生命周期（见 SendBleDataThread.java）。

核心流程

BLE 从扫描到数据交互的完整时序如下：

sequenceDiagram
    participant App as Activity/UI 层
    participant BM as BleManager (单例)
    participant CM as BleEventCallbackManager
    participant CB as BleEventCallback (订阅者)
    participant ST as SendBleDataThread
    participant OS as Android BLE 系统

    App->>BM: registerBleEventCallback(cb)
    App->>BM: startLeScan()
    BM->>OS: BluetoothLeScanner.startScan()
    OS-->>BM: ScanCallback.onScanResult
    BM-->>CM: onDiscoveryDevice(ScanDeviceInfo)
    CM->>CB: onDiscoveryDevice(设备信息) [主线程]

    App->>BM: connectDevice(device)
    BM->>OS: BluetoothGatt.connect()
    OS-->>BM: onConnectionStateChange
    BM-->>CM: onBleConnection(device, status)
    CM->>CB: onBleConnection [主线程]

    BM->>OS: discoverServices()
    OS-->>BM: onServicesDiscovered
    BM-->>CM: onBleServiceDiscovery(services)
    CM->>CB: onBleServiceDiscovery [主线程]

    BM->>OS: setCharacteristicNotification(true)
    OS-->>BM: onDescriptorWrite
    BM-->>CM: onBleNotificationStatus(...)
    CM->>CB: onBleNotificationStatus [主线程]

    App->>BM: writeDataByBle(gatt, uuid, data)
    BM->>ST: addSendTask(..., OnWriteDataCallback)
    ST->>OS: writeCharacteristic(分块1) → 等待回调
    OS-->>ST: onCharacteristicWrite
    ST-->>App: OnWriteDataCallback.onWrite(...)
    OS-->>BM: onCharacteristicChanged(设备上报)
    BM-->>CM: onBleDataNotification(device, uuid, data)
    CM->>CB: onBleDataNotification [主线程]

流程要点：

1. 事件全部经 BleEventCallbackManager 主线程化：无论 Android 回调来自哪个线程，订阅者始终在主线程收到事件，UI 可直接更新；
2. 下行与上行解耦：App → 设备的数据走 SendBleDataThread + OnWriteDataCallback（异步回调），设备 → App 的数据走事件回调链（onBleDataNotification），两条路径互不阻塞；
3. 每步都有超时兜底：扫描 12s、连接 40s、回调 6s、发送 8s 等 Handler 消息保证任何一步失败都不会让流程永久挂起。

使用示例

注册事件回调（UI 层订阅）

上层只需继承 BleEventCallback 并覆写关心的方法，其余方法由抽象类提供空实现：

BleManager.getInstance().registerBleEventCallback(new BleEventCallback() {
    @Override
    public void onBleConnection(BluetoothDevice device, int status) {
        // 连接状态变化，更新 UI（主线程）
    }

    @Override
    public void onBleDataNotification(BluetoothDevice device, UUID serviceUuid,
                                      UUID characteristicsUuid, byte[] data) {
        // 收到设备上报数据
    }
});

来源：BleEventCallbackManager.java

经发送线程写入数据

public boolean addSendTask(BluetoothGatt gatt, UUID serviceUUID, UUID characteristicUUID,
                           byte[] data, OnWriteDataCallback callback) {
    if (null == mBleManager || null == gatt || null == serviceUUID
            || null == characteristicUUID || null == data || data.length == 0) {
        return false;
    }
    // ... 按 MTU 分块后依次入队
    return ret;
}

来源：SendBleDataThread.java

调用方通过 OnWriteDataCallback 感知每块数据的写入结果，BleManager 内部据此决定是否继续下一块或重试。

配置选项

核心行为通过 BleManager 静态常量与 Config 配置驱动，无外部配置文件，修改需重新编译：

配置定义于 BleManager.java。设计意图：超时集中管理——BLE 异步回调可能因设备异常、信号弱而丢失，所有操作都有显式超时消息兜底，避免调用方无限等待。

API 参考

BleManager（单例门面，BleManager.java）

线程安全：mUsingDevice、instance、扫描状态等使用 volatile 保证可见性；mBleDeviceMap 等集合仅在主线程或受控路径访问。

BleEventCallback（抽象类，BleEventCallback.java）

11 个可覆写事件方法，全部在主线程回调，签名与触发时机见上文"回调接口体系"表格。返回 void，不抛受检异常；内部错误通过 onDiscoveryFail(code, message) 或 status 参数上抛。

IBleOp（接口，IBleOp.java）

• int getBleMtu()：返回当前协商的 MTU 值，用于上层计算分块大小；
• boolean writeDataByBle(BluetoothGatt gatt, UUID serviceUUID, UUID characteristicUUID, byte[] data)：写入一帧数据，返回是否成功入队（非发送完成）；实际结果经 OnWriteDataCallback 异步告知。

失败模式、边界情况与并发

失败模式

边界情况与并发

• 重复注册防护：registerBleEventCallback 用 contains 去重；unregister 在空列表时安全跳过（BleEventCallbackManager.java）；
• 主线程内联执行：callbackBleEvent 判断当前线程为主线程时直接执行而非 post，避免自阻塞；但这也意味着订阅者回调不应执行耗时操作，否则会阻塞 UI；
• 生产者-消费者同步：发送线程用 isThreadWaiting / isWaitingForCallback 两个 volatile 标志区分"等队列"与"等写回调"，配合 mQueue.notifyAll()（批量入队）与 notify()（单任务唤醒）避免死锁与丢失唤醒（SendBleDataThread.java）；
• 静态字段泄漏防护：单例持有 Context 标注 @SuppressLint("StaticFieldLeak")，要求调用方传入 Application Context，避免 Activity 泄漏（BleManager.java）；
• 竞态场景：mUsingDevice（正在通讯的设备）在扫描与连接线程间共享，volatile 保证读线程能看到最新值，但复合操作（如"读-改-写"）仍需调用方串行化。

性能与运维考虑

• 发送吞吐：SendBleDataThread 按 MTU 分块 + 每块等待 onCharacteristicWrite，是"可靠优先"而非"吞吐优先"的设计——BLE 规范要求同一连接串行写，等待回调可避免 GATT 写入溢出；
• 线程模型：主线程 Handler 承担全部事件分发与超时管理，任何回调内的重活（解析、存储）都应自行移到工作线程；
• 扫描功耗：12s 扫描超时自动停止，兼顾发现率与功耗；SCAN_BLE_TIMEOUT 注释"建议搜索 BLE 最小时间"表明该值有实测依据；
• 日志：模块使用 JL_Log（杰理日志库）输出 TAG 为 BleManager 的日志，现场排查时可按 TAG 过滤超时与连接事件。

扩展点

1. 新增业务事件：在 IBleEventCallback 增加方法 → BleEventCallback 补空实现 → BleEventCallbackManager 覆写并转发 → BleManager 触发点调用。三层各改一处，其余订阅者自动获得新事件（空实现保证不破坏现有代码）；
2. 替换发送策略：SendBleDataThread 与 IBleOp 解耦了"写什么"与"怎么串行写"，可替换为批量合并发送或基于流的传输策略，只要保持 OnWriteDataCallback 语义；
3. 多设备扩展：mBleDeviceMap 已按地址索引，可在现有单设备（mUsingDevice）基础上扩展为多连接管理；
4. 扫描策略定制：IBtScanCallback 与扫描超时消息为扫描策略替换留了口子（过滤条件、扫描间隔可调）。

相关链接

• BleManager.java — 核心单例门面
• BleEventCallbackManager.java — 回调分发器
• BleEventCallback.java — 事件回调抽象类
• IBleOp.java — BLE 操作契约接口
• SendBleDataThread.java — 串行发送线程
• BleDevice.java / ScanDeviceInfo.java — 数据模型

关联目录指引：BLE 连接与扫描的完整操作流程见架构页"3.1 整体架构"；协议指令封装见协议层相关页面；工具类（BluetoothUtil、CHexConver、UuidUtil）见工具库页面。