支持的平台与协议

Android-BT-Demo 是珠海杰理科技股份有限公司（JieLi Tech）为其蓝牙产品提供的 Android 端测试示例代码集合。本文档说明该仓库支持的 Android 平台版本范围、运行环境要求，以及所涉及的蓝牙通讯协议（GATT over BR/EDR 与 GATT over BLE）的技术细节、选型依据与兼容性边界。

Purpose and Scope

本页聚焦于「平台与协议」这一仓库级主题，覆盖以下内容：

• Android 系统版本要求（最低版本、目标版本、编译版本）与开发语言约束；
• 支持的蓝牙协议：GATT over BR/EDR（ATT）与 GATT over BLE 的原理、差异与适用场景；
• 协议与 Android 系统蓝牙协议栈的层次关系；
• ATTConnect 示例工程对平台/协议支持的落地情况（核心类与工程结构）；
• 兼容性风险、边界情况与测试建议。

不属于本页的内容（交由兄弟页面承载）：

• 示例工程的具体使用步骤、Gradle 构建细节 → 参见「快速开始」相关页面；
• BtScanner、BleManager 等核心类的实现细节 → 参见「ATTConnect」页面；
• 版本演进记录 → 参见「版本历史」页面。

说明：本仓库 main 分支顶层仅包含 README.md、README_en.md 与 LICENSE，示例源码位于 ATTConnect/ 目录（README 中链接指向 ATTConnect 详细说明）。本页关于平台与协议的全部结论均来自上述仓库文档。

Overview

Android-BT-Demo 目前包含一个核心用例：ATT 设备（GATT over BR/EDR）连接示例，演示如何在 Android 端通过 GATT 协议与杰理蓝牙产品进行数据通讯。该用例对应的示例工程为 ATTConnect/。

平台支持可以从三个维度理解：

1. 系统版本维度：仓库要求最低 Android 5.0（API 21），目标版本随示例工程演进（根 README 标注 Android 16+ / API 36+，ATTConnect 子工程标注 Android 14 / API 34）。
2. 开发语言维度：Kotlin / Java 均可，示例中 BtScanner 使用 Kotlin 实现、BleManager 使用 Java 实现，体现双语言并存的设计。
3. 蓝牙能力维度：示例面向双模蓝牙设备（经典蓝牙 + BLE），通过 Android 原生 GATT 框架同时覆盖两条协议路径。

协议支持的核心结论是：Android 原生系统支持 GATT 通讯，且 GATT 通讯分为 GATT over BLE 与 GATT over BR/EDR（ATT） 两种形态，本仓库对两者均标注为 ✅ 支持。其中 ATT（GATT over BR/EDR）是示例的主线能力——它基于经典蓝牙承载 GATT 服务，传输速率更高、数据量更大，但 Android 厂商对它的实现成熟度参差不齐，因此 README 明确建议在目标设备上充分测试。

Architecture

下图展示了本仓库「平台 → 系统蓝牙栈 → 协议 → 设备」的分层架构，以及示例工程在其中的位置：

flowchart TD
    subgraph sg_App["应用层（Android-BT-Demo）"]
        Demo["ATTConnect 示例"]
        Scanner["BtScanner（扫描）"]
        Manager["BleManager（设备管理）"]
    end

    subgraph sg_OS["Android 系统层"]
        BTAPI["android.bluetooth API<br/>（BluetoothAdapter / BluetoothGatt）"]
        Stack["厂商蓝牙协议栈"]
    end

    subgraph sg_Protocol["协议层"]
        ATT["GATT over BR/EDR（ATT）"]
        BLE["GATT over BLE"]
    end

    subgraph sg_Device["设备层"]
        Device["杰理双模蓝牙产品"]
    end

    Demo --> Scanner
    Demo --> Manager
    Scanner --> BTAPI
    Manager --> BTAPI
    BTAPI --> Stack
    Stack --> ATT
    Stack --> BLE
    ATT --> Device
    BLE --> Device

各层职责与连接关系：

设计意图：应用层只面向 Android 原生 API 编程，不直接操作射频硬件；协议差异由系统蓝牙栈消化。这样示例代码可以同时服务两条协议路径，客户只需关注业务封装（扫描、连接、收发），而无需关心底层承载。代价是——ATT 能力最终取决于厂商协议栈的实现质量，这也是文档反复强调「在目标设备上充分测试」的根本原因。

平台支持详解

Android 系统版本要求

仓库根 README（README.md）声明的系统要求如下：

ATTConnect 子工程（ATTConnect/README.md）则给出了更细粒度的构建参数：

两处目标版本标注存在差异（根 README 为 API 36+，子工程为 API 34），这反映了文档随 Android 版本演进逐步更新、而示例工程编译目标相对保守的实际情况。以「最低 API 21、Kotlin/Java 双语言」为仓库级基线，以各自工程的 compileSdk/targetSdk 为实际构建依据。

选择 Android 5.0（API 21） 作为最低版本的理由：API 21 是 Android 5.0 Lollipop 引入 BluetoothGatt 成熟能力、并广泛覆盖存量设备的版本分水岭。蓝牙 GATT API 在后续版本中主要是增强（如扫码过滤、连接参数调整），核心接口保持向后兼容，因此以 API 21 为底可以最大化客户设备的覆盖范围。

设备形态与蓝牙能力要求

• 示例面向双模蓝牙设备（经典蓝牙 + BLE），典型场景是需要通过 GATT 协议进行高速数据通讯的杰理产品（README.md）。
• 手机侧要求具备经典蓝牙与 BLE 双模射频能力，并已授予定位/蓝牙相关运行时权限（示例通过 Android 原生 API 完成扫描与连接）。
• 示例工程将系统接口封装为可复用的工具层：tool/scan/BtScanner.kt 负责扫描、tool/ble/BleManager.java 负责设备连接管理，客户可基于这些封装自行实现业务逻辑（ATTConnect/README.md）。

协议支持详解

两种 GATT 承载方式

仓库将支持的蓝牙协议归纳为两类（README.md）：

ATTConnect 子工程对两者的底层与特性做了补充说明（ATTConnect/README.md）：

GATT over BLE

• 承载于 Bluetooth Low Energy（BLE）物理层之上，GATT 服务/特征值模型不变。
• 优势：功耗低、广播/扫描机制灵活、生态兼容性好，适合传感器、穿戴、低速率控制类应用。
• 在 Android 上实现路径成熟：BluetoothLeScanner 扫描 → BluetoothGatt.connectGatt() 连接 → discoverServices() 发现服务 → 读写 characteristic / 订阅 notification。

GATT over BR/EDR（ATT）

• 将 GATT 客户端/服务器模型承载于经典蓝牙（BR/EDR）链路之上，本质上是让 ATT 协议跑在速率更高的经典蓝牙物理通道。
• 优势：传输速率更高、单次数据量更大，适合需要高速、大数据量通讯的场景（如音频数据传输、文件/固件升级）。
• Android 侧对 ATT 的支持依赖系统蓝牙协议栈对「经典蓝牙上的 GATT」的实现——并非所有厂商 ROM 都完整支持，因此存在明显的机型兼容性差异（详见下文「兼容性、边界与失败模式」）。

协议栈层次与 Android API 映射

两种协议共享同一套应用层 GATT 抽象，区别仅在于底层承载：

flowchart LR
    subgraph sg_AppAPI["应用层 GATT 抽象"]
        Gatt["BluetoothGatt<br/>（服务/特征/描述符）"]
    end

    subgraph sg_Transport["传输承载"]
        BR["BR/EDR 链路（经典蓝牙）"]
        LE["LE 链路（低功耗蓝牙）"]
    end

    subgraph sg_Stack["蓝牙协议栈"]
        ATT_L["ATT 协议"]
        L2CAP["L2CAP"]
    end

    Gatt --> ATT_L
    ATT_L --> L2CAP
    L2CAP --> BR
    L2CAP --> LE

应用层只感知 BluetoothGatt 对象，connectGatt() 时通过传输参数（transport）决定走 LE 还是 BR/EDR 通道；两条路径最终都汇聚到 ATT/L2CAP 层，这也是「一套 GATT 代码、两种协议支持」的架构基础。示例中的 BtScanner 与 BleManager 正是这一抽象在工程层面的体现：扫描结果与连接对象对上层业务透明，底层承载差异被封装在工具层内部。

核心流程：ATT 设备连接与通讯

ATTConnect 示例覆盖的完整能力链路为：扫描 → 连接 → GATT 服务发现 → 数据收发 → 断开管理（README.md）。以下是基于仓库描述还原的端到端时序：

sequenceDiagram
    participant App as ATTConnect 示例
    participant API as android.bluetooth API
    participant Stack as 蓝牙协议栈
    participant Dev as 杰理蓝牙设备

    App->>API: 扫描 ATT 设备（BtScanner）
    API-->>App: onDeviceFound 设备回调
    App->>API: 发起连接（BleManager）
    API->>Stack: 建立 BR/EDR 链路
    Stack->>Dev: 经典蓝牙连接请求
    Dev-->>Stack: 链路建立成功
    Stack-->>App: onConnected 连接回调
    App->>API: discoverServices() 服务发现
    App->>Dev: GATT 数据读写（ATT 通道）
    Dev-->>App: 数据 / 状态回调
    App->>API: disconnect() / close()
    API-->>App: onDisconnected 断开回调

流程要点：

1. 扫描阶段：BtScanner 基于 Android 蓝牙扫描接口发现 ATT 设备，向 UI 层回调设备列表；
2. 连接阶段：BleManager 封装 connectGatt() 等系统接口建立链路——ATT 场景走 BR/EDR 承载，BLE 场景走 LE 承载；
3. 服务发现：连接成功后执行 discoverServices()，获取设备暴露的 GATT 服务与特征值；
4. 数据收发：通过 ATT 通道读写 characteristic、接收通知，实现与杰理产品的高速数据通讯；
5. 断开管理：显式 disconnect()/close() 释放资源，回调通知 UI 更新状态。

设计意图：将系统接口封装为 BtScanner + BleManager 两个职责单一的工具类，业务层与 Android API 解耦。客户既可以开箱即用地测试杰理产品，也可以把这两个类直接搬进自有工程作为连接层基础。

兼容性、边界与失败模式

ATT 的机型兼容性风险

README 在协议表后特别标注了警告（README.md）：

注意：Android 端对 ATT（GATT over BR/EDR）功能的支持可能存在兼容性问题，建议在目标设备上进行充分测试。

这是本仓库最重要的边界声明。具体表现与应对：

边界情况

• 最低版本边界：API 21 以下的设备不在支持范围，相关 API 调用无降级路径；
• 目标版本漂移：根 README（API 36+）与子工程（API 34）目标版本不一致，升级 targetSdk 时需同步处理新增的蓝牙权限与行为变更（如后台扫描限制、附近的设备权限）；
• 单用例仓库现状：仓库当前仅提供 ATTConnect 一个示例，README 注明「更多示例持续更新中」，其它协议（如经典 RFCOMM SPP）未被本仓库覆盖，不应视为支持承诺。

失败模式概览

这些失败最终都通过 Android 原生回调暴露给 BleManager/BtScanner 的接口层，示例工程的结构（data/result/ 操作结果模型、tool/ble/interfaces/ 回调接口定义）正是为了将这些异步结果规整为可预期的业务回调（ATTConnect/README.md）。

使用示例

以下代码与配置片段均提取自仓库实际文档，展示如何按声明的平台/协议要求落地。

克隆仓库并选择示例

根据产品需求选择示例工程，ATT 场景选择 ATTConnect/ 目录：

git clone https://github.com/Jieli-Tech/android-bt-demo.git
cd android-bt-demo

Source: README.md

仓库顶层结构：

android-bt-demo/
├── ATTConnect/       # ATT 设备（GATT over BR/EDR）连接示例
└── .../              # 更多示例持续更新中

Source: README.md

ATTConnect 工程结构（平台/协议能力的落点）

ATTConnect/
├── app/                                 # 应用主模块
│   └── src/main/java/com/jieli/bt/att/
│       ├── data/
│       │   ├── constant/                #   配置常量（Config.kt）
│       │   ├── device/                  #   设备连接数据模型
│       │   └── result/                  #   操作结果模型
│       ├── tool/
│       │   ├── ble/                     #   BLE 设备管理（BleManager.java）
│       │   │   ├── interfaces/          #     回调接口定义
│       │   │   └── model/               #     设备数据模型
│       │   └── scan/                    #   蓝牙扫描器（BtScanner.kt）
│       └── ui/                          #   界面层

Source: ATTConnect/README.md

其中 tool/scan/（BtScanner.kt，Kotlin）与 tool/ble/（BleManager.java，Java）正是本页「支持的平台与协议」在工程层面的直接体现：Kotlin/Java 双语言并存、扫描与连接双职责分离、GATT 抽象对两种承载透明。

编译与安装（验证平台支持）

# 编译 Debug 版本
./gradlew assembleDebug        # Linux/macOS
gradlew.bat assembleDebug      # Windows

# 编译 Release 版本
./gradlew assembleRelease

# 安装到已连接设备
./gradlew installDebug

APK 默认生成路径：app/build/outputs/apk/debug/

Source: ATTConnect/README.md

配置汇总

本页涉及的平台/协议相关配置项（来自根 README 与 ATTConnect README）：

相关链接

• README.md（仓库主文档）
• README_en.md（英文版）
• ATTConnect/README.md（示例工程说明）
• LICENSE（Apache 2.0）
• 杰理在线文档中心：https://doc.zh-jieli.com/vue/#/home

相关页面导航：示例的详细使用步骤参见「ATTConnect」页面；版本演进参见「版本历史」页面；社区支持与问题反馈参见仓库 README「社区与支持」章节。