导入工程与编译运行

本文介绍如何获取 Android-BT-Demo 仓库源码、使用 Android Studio 导入示例工程（ATTConnect/）、完成 Gradle 同步与编译构建，并将 APK 安装到 Android 真机运行调试。

Purpose and Scope

本页面向第一次接触杰理蓝牙 Android 示例代码的开发者，覆盖从「拿到代码」到「在手机上跑起来」的完整链路：

• 环境准备（Android SDK / Gradle / Android Studio）
• 获取源码（git clone 或直接下载）
• 导入工程与 Gradle 同步
• 编译 Debug / Release APK 及安装运行
• 工程目录结构与构建产物说明
• 构建相关的配置项与常见失败原因

不属于本页范围的内容请参见对应页面：

• ATTConnect 示例的功能使用、扫描/连接/收发数据的 API 调用，参见「ATTConnect 使用指南」。
• BtScanner、BleManager、Config 等核心类的内部实现与接口签名，参见「ATT 连接示例核心类」相关页面。
• 蓝牙权限声明、日志调试等运行时行为在本页仅作简述，详细说明见 ATTConnect 示例文档。

概述

Android-BT-Demo 是珠海杰理科技股份有限公司提供的 Android 端蓝牙测试示例代码集合仓库，用于帮助客户快速验证杰理蓝牙产品（如双模蓝牙设备）的通讯功能。仓库当前包含一个示例工程：

• ATTConnect/ —— ATT 设备（GATT over BR/EDR）连接示例，演示通过 GATT 协议与杰理蓝牙产品进行扫描、连接、数据收发与 GATT 服务发现。

示例工程采用 Kotlin DSL 编写 Gradle 构建脚本（build.gradle.kts、settings.gradle.kts），并内置 Gradle Wrapper（gradle/ 目录），因此无需预先安装指定版本的 Gradle，Android Studio 会自动使用 Wrapper 下载匹配的 Gradle 版本完成同步与构建。

工程对 Android 系统的要求如下：

*注意：仓库根目录 README.md 声明目标版本为 Android 16+（API 36+），而 ATTConnect 子工程文档声明 target/compile 为 API 34，两者略有差异，请以你实际导入的子工程 build.gradle.kts 为准。

架构与导入编译流程

flowchart TD
    subgraph sg_Prepare["环境准备"]
        AS["Android Studio"]
        SDK["Android SDK（API 21~34）"]
    end

    subgraph sg_Source["获取源码"]
        Clone["git clone android-bt-demo"]
        OpenDir["打开 ATTConnect/ 目录"]
    end

    subgraph sg_Sync["Gradle 同步"]
        Wrapper["Gradle Wrapper 解析 build.gradle.kts"]
        Deps["下载依赖（AAR / AndroidX）"]
    end

    subgraph sg_Build["编译构建"]
        Debug["assembleDebug"]
        Release["assembleRelease"]
        Install["installDebug"]
    end

    subgraph sg_Output["产物与运行"]
        APK["app/build/outputs/apk/"]
        Phone["Android 真机"]
    end

    AS --> Clone
    SDK --> Wrapper
    Clone --> OpenDir
    OpenDir --> Wrapper
    Wrapper --> Deps
    Deps --> Debug
    Deps --> Release
    Deps --> Install
    Debug --> APK
    Release --> APK
    Install --> Phone
    APK --> Phone

流程解读： 导入工程的核心思路是「以 ATTConnect/ 为独立工程打开，而不是打开整个仓库根目录」。ATTConnect/ 自含项目级 build.gradle.kts、settings.gradle.kts 与 Gradle Wrapper，Android Studio 打开该目录后会自动触发 Gradle 同步，由 Wrapper 拉取对应 Gradle 版本并解析 Kotlin DSL 构建脚本、下载依赖。同步成功后即可通过 Gradle 任务编译 Debug/Release 变体，产物输出到 app/build/outputs/apk/，或直接安装到已连接的真机。

环境准备

在导入工程前，请确认开发环境满足以下条件：

说明：工程自带的 gradle/ 目录包含 Gradle Wrapper，首次同步时 Android Studio 会自动下载对应版本的 Gradle 发行包，无需手工安装 Gradle。

获取源码

克隆仓库

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

Source: README.md

国内开发者也可以直接访问 Gitee 镜像仓库下载源码，或点击页面上的 Download ZIP 直接下载压缩包后解压。

克隆完成后，仓库根目录结构如下：

android-bt-demo/
├── ATTConnect/       # 📌 ATT 设备连接示例
├── LICENSE           # Apache 2.0 开源协议
└── README.md

Source: README.md

导入工程

使用 Android Studio 打开

1. 打开 Android Studio
2. 点击 File → Open，选择对应的示例目录（如 ATTConnect/）
3. 等待 Gradle 同步完成
4. 连接 Android 手机，点击 Run → Run 'app'
5. 在手机上打开 APP，测试蓝牙功能

Source: README.md

ATTConnect 子工程的导入步骤与根仓库一致，且必须选择 ATTConnect/ 目录本身（该目录是独立的 Gradle 工程根）：

1. 打开 Android Studio
2. 点击 File → Open，选择 ATTConnect/ 目录
3. 等待 Gradle 同步完成
4. 连接 Android 手机，点击 Run → Run 'app'
5. 在手机上打开 APP，测试蓝牙功能

Source: ATTConnect/README.md

设计意图： 示例工程采用「一个示例 = 一个独立 Gradle 工程」的组织方式，而不是多模块的单一工程。这样每个示例可以独立同步、独立构建、互不干扰，也便于客户直接复制某个示例作为自己产品工程的基础。

Gradle 同步要点

• 首次同步会下载 Gradle 发行包与依赖库（AndroidX、杰理 AAR 等），耗时取决于网络环境，可配置国内镜像加速。
• ATTConnect/app/libs/ 目录存放 AAR 依赖库，同步时不会从远端拉取，因此不要删除或忽略该目录。
• 如果同步失败，优先检查：网络连通性、Android SDK 平台（API 34）是否已安装、JDK 版本是否被 Android Studio 正确识别。

编译构建

使用 Gradle Wrapper 编译 APK

工程提供以下命令行构建方式（无需打开 Android Studio）：

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

# 编译 Release 版本
./gradlew assembleRelease

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

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

Source: ATTConnect/README.md

构建任务说明

注意：Release 变体默认使用 debug 签名时可直接安装，正式发布前需在 app/build.gradle.kts 中配置 release 签名证书与 minify 规则。

构建产物位置

ATTConnect/app/build/outputs/
├── apk/
│   ├── debug/          # Debug APK 输出目录
│   └── release/        # Release APK 输出目录
└── ...

此外，仓库的 ATTConnect/apk/ 目录中还提供了预编译 APK，客户在不想编译的情况下可以直接安装体验示例功能。

核心流程：从导入到运行

sequenceDiagram
    participant Dev as 开发者
    participant Studio as Android Studio
    participant Wrapper as Gradle Wrapper
    participant SDK as Android SDK / 依赖仓库
    participant Output as APK 产物
    participant Phone as Android 手机

    Dev->>Studio: File → Open 选择 ATTConnect/
    Studio->>Wrapper: 触发 Gradle Sync
    Wrapper->>SDK: 解析 build.gradle.kts / settings.gradle.kts
    SDK-->>Wrapper: 下载 Gradle 发行包与依赖（含 libs/ AAR）
    Wrapper-->>Studio: 同步完成
    Dev->>Studio: 点击 Run → Run 'app'
    Studio->>Wrapper: 执行 assembleDebug / installDebug
    Wrapper->>Output: 编译生成 APK（app/build/outputs/apk/debug/）
    Output->>Phone: 安装 APK 并启动 APP
    Phone-->>Dev: 真机运行，测试蓝牙功能

步骤说明：

1. 打开工程：ATTConnect/ 是独立 Gradle 工程，包含项目级 build.gradle.kts、settings.gradle.kts 和 gradle/（Wrapper），Android Studio 以该目录为工程根。
2. Gradle 同步：Wrapper 依据 gradle-wrapper.properties 下载对应 Gradle 版本，随后解析 Kotlin DSL 脚本并解析依赖；app/libs/ 中的 AAR 直接以本地文件方式参与编译。
3. 编译安装：Run 'app' 实际执行 assembleDebug 与 installDebug 任务链，产物先落到 app/build/outputs/apk/debug/，再通过 adb 安装到真机。
4. 真机验证：APP 启动后即可使用扫描、连接等蓝牙功能（需先完成系统蓝牙权限授权）。

工程结构解析

flowchart TD
    subgraph sg_ATTConnect["ATTConnect 工程根"]
        App["app/ 应用主模块"]
        Libs["libs/ AAR 依赖库"]
        PreApk["apk/ 预编译 APK"]
        ProjBuild["build.gradle.kts 项目级构建配置"]
        Settings["settings.gradle.kts 项目设置"]
        Wrapper["gradle/ Gradle Wrapper"]
        Image["image/ 图片资源"]
        License["LICENSE Apache 2.0"]
    end

    subgraph sg_AppModule["app 模块（Kotlin/Java 源码）"]
        Src["src/main/java/com/jieli/bt/att/"]
        AppBuild["build.gradle.kts 应用构建配置"]
    end

    App --> Src
    App --> AppBuild
    Src --> Data["data/ 配置常量与数据模型"]
    Src --> Tool["tool/ BtScanner（扫描）+ BleManager（连接/收发）"]
    Src --> Ui["ui/ 首页/设备/设置界面"]
    Src --> Util["util/ 蓝牙、权限、文件工具类"]

Source: ATTConnect/README.md

关键目录与文件说明

设计意图： 包结构按 data（数据与常量）、tool（能力封装）、ui（界面）、util（工具）分层，把扫描器（BtScanner）与连接管理器（BleManager）独立成工具类，界面层只做展示与交互编排。客户复用代码时，可只拷贝 tool/ 与 data/ 到自己的工程，无需引入整个 UI 层。

配置说明

Config.kt 关键常量

编译运行后，APP 与设备通讯的协议参数由 Config.kt 控制，修改后需重新编译安装生效：

object Config {
    /**
     * 是否跳过没有名字的设备
     */
    const val IS_FILTER_NO_NAME_DEVICE = false

    /**
     * 调整 BLE 的 MTU
     * <p>
     *     注意: GATT over BR/EDR 不支持调整 MTU
     * </p>
     */
    const val REQUEST_BLE_MTU = 509

    /**
     * BLE 服务 UUID
     * <p>
     *     BLE: 服务 UUID 是 0xae00 <br/>
     *     GATT over BR/EDR: 服务 UUID 是 0x1801
     * </p>
     */
    val BLE_SERVICE_UUID: UUID = UuidUtil.to16BitUUID("1801")

    /**
     * BLE 写特征 UUID
     */
    val BLE_WRITE_UUID: UUID = UuidUtil.to16BitUUID("ae01")

    /**
     * BLE 通知特征 UUID
     */
    val BLE_NOTIFY_UUID: UUID = UuidUtil.to16BitUUID("ae02")
}

Source: ATTConnect/README.md

💡 请根据实际设备端的 UUID 配置修改上述常量，确保 APP 端与设备端的 UUID 一致，否则无法正确收发数据。

蓝牙权限声明（AndroidManifest.xml）

APP 使用蓝牙功能需要在 AndroidManifest.xml 中静态声明以下权限：

<!-- 使用蓝牙权限 -->
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<!-- 高版本安卓，要求声明蓝牙功能权限 -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<!-- 定位权限，官方要求使用蓝牙或网络开发，需要位置信息 -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Source: ATTConnect/README.md

除静态声明外，运行时还需动态申请权限：Android 6.0+ 需申请位置权限；Android 12.0+ 需申请位置权限 + 蓝牙功能权限（BLUETOOTH_SCAN、BLUETOOTH_CONNECT）。

运行与调试

在 Android Studio 中运行

1. 用 USB 连接 Android 真机并开启「开发者选项 → USB 调试」。
2. 在工具栏选择目标设备，点击 Run → Run 'app'（或直接点击绿色 ▶ 按钮）。
3. 首次安装会弹出运行时权限请求，需依次授权位置与蓝牙权限（Android 12+ 还会请求附近设备权限）。
4. APP 启动后进入主页，即可开始扫描与连接测试。

日志开关与查看

工程内置 JL_Log 日志工具，可在设置界面开关日志：

JL_Log.setLog(isLog)
JL_Log.setSaveLogFile(isLog, context)
if (isLog) {
    JL_Log.configure(JL_Log.getLogOption().apply {
        isLogcatCrash = true
    })
}

Source: ATTConnect/README.md

日志文件命名格式为 app_log_[时间戳].txt，可通过 APP 的「设置 → 日志存储位置」进入日志管理界面：

• 选择异常发生时间最近的日志，可分享到微信/钉钉/QQ/企业微信，或下载到 Download 文件夹后发送给技术支持；
• 右上角图标可清除所有日志，日志条目侧滑可删除，点击日志可浏览内容。

失败模式、边界情况与注意事项

以下内容基于官方示例文档的「注意事项」与协议特性整理，构建/运行遇到问题时优先排查：

构建相关

蓝牙协议边界（运行时）

1. 连接传统 BLE 设备时，需要调整 MTU，MTU 取值范围：[20, 509]。
2. 连接 GATT over BR/EDR（ATT）设备时：
   • 设备必须是双模设备；
   • 连接之前必须先配对（这是 BR/EDR 底层协议决定的）；
   • 不支持 MTU 调整功能（MTU 调整是 BLE 底层协议能力，BR/EDR 不支持）。
3. Android 端对 ATT（GATT over BR/EDR）功能的支持可能存在兼容性问题，建议在目标设备上进行充分测试。

Source: ATTConnect/README.md

并发与状态注意

• BtScanner 与 BleManager 均为单例（getInstance()），扫描与连接操作是全局共享状态；重复调用连接接口会返回失败（设备正在连接中）。
• 注册的 BleEventCallback 在不需要监听时需调用 unregisterBleEventCallback 移除，避免回调泄漏。
• 扫描超时由调用方传入（示例中为 30 秒），扫描结束后需自行处理回调中的失败码 onDiscoveryFail(code, message)。

性能与运维建议

• 构建提速：Gradle 同步与首次构建较慢时，可在 gradle.properties 中开启 org.gradle.daemon、org.gradle.parallel、org.gradle.caching，并配置国内 Maven 镜像（阿里云等）。
• 真机验证：蓝牙功能依赖真实硬件与系统蓝牙栈，务必使用真机测试；ATT 兼容性问题需覆盖多台目标设备。
• 日志留档：反馈问题时按「时间戳日志 + 复现步骤 + 设备型号/系统版本」提交，可大幅缩短排查周期。

扩展点

• 接入自有产品工程：将 tool/（BtScanner、BleManager 及 interfaces/model）与 data/constant/Config.kt 拷贝到客户工程，按需调整 UUID 常量即可复用核心通讯能力。
• 协议自定义：修改 Config.kt 中的 BLE_SERVICE_UUID、BLE_WRITE_UUID、BLE_NOTIFY_UUID 以匹配设备端协议（注意区分 BLE 0xae00 与 ATT 0x1801 两套服务 UUID）。
• UI 定制：示例的 ui/ 层为参考实现，客户可完全替换为自己的界面，仅保留 data/tool/util 层。

相关链接

• 仓库 README（中文）
• ATTConnect 示例文档
• ATTConnect 英文文档
• 仓库英文 README
• 杰理在线文档中心
• 许可证（Apache 2.0）