• 文档
• 知识库
• 教程
• OpenHarmony

本篇技术指南基于 CangjieCorpus 语料库中的蓝牙服务开发文档，系统讲解在鸿蒙（OpenHarmony）环境下使用仓颉（Cangjie）语言进行蓝牙服务开发所需掌握的核心概念：传统蓝牙（BR/EDR）与低功耗蓝牙（BLE）的技术原理、性能差异与典型应用场景，并串联本仓库中与之配套的 BLE 开发指导、GATT 开发指导、API 参考与权限声明等资源，帮助开发者建立从技术选型到编码实现的完整认知。

蓝牙技术概述

蓝牙（Bluetooth）是一种无线通信技术，可以在短距离内传输数据，其技术规范由蓝牙技术联盟（Bluetooth Special Interest Group，SIG）制定。在鸿蒙生态中，蓝牙常被用于连接手机、耳机、音箱、键盘、鼠标、打印机等各种设备，是 Connectivity Kit（短距通信服务） 提供的基础能力之一。目前蓝牙有两种常见的技术分类：传统蓝牙（BR/EDR）和低功耗蓝牙（BLE）。

实现原理

蓝牙的实现原理是基于无线电技术的短距离通信协议：

• 使用2.4GHz 频段的无线电波进行通信；
• 使用频率跳跃技术（Frequency Hopping Spread Spectrum，FHSS）来避免与其他无线设备的干扰；
• 在通信过程中，蓝牙设备会发送和接收数据包，并且使用不同的蓝牙协议来控制通信流程和数据传输。

从协议栈角度看，蓝牙通信依赖 L2CAP（逻辑链路控制和适配协议）、RFCOMM（无线电频率通信协议）等底层协议提供面向连接或无连接的数据服务，并支持多路复用、分段和重组操作，相关术语可参考 Connectivity Kit 术语。

两种技术分类的选择依据

传统蓝牙（BR/EDR）

蓝牙基础率/增强数据率（Basic Rate/Enhanced Data Rate，BR/EDR），也被称为传统蓝牙。蓝牙 EDR 技术是蓝牙 BR 技术的增强版本，具有更高的数据传输速率，比 BR 快 2~3 倍，最高可达2~3 Mbps。在理想条件下，传统蓝牙的通信范围约100 米。

传统蓝牙提供了多样化且成熟的技术协议，从本仓库的 Connectivity Kit 术语 中可以梳理出以下几类典型协议：

• 高级音频分发（A2DP）：无线传输高品质音频流，如使用蓝牙耳机听音乐；
• 免提通话（HFP）：实现蓝牙设备间的免提通话，支持双向语音通话和控制等功能；
• 个人局域网（PAN）：支持设备间网络共享，如通过手机热点访问网络；
• 电话簿访问（PBAP）：实现蓝牙设备间的电话簿数据同步，支持联系人、通话记录等数据传输；
• 对象推送（OPP）：实现设备间数据（如图片、文档等）传输；
• 人机接口（HID）：实现键盘、鼠标、游戏手柄等设备与主机间的低延迟双向通信；
• 消息访问（MAP）：实现短信、邮件等消息的同步。

利用这些技术，传统蓝牙可以满足许多不同应用场景下的多样化需求，例如：使用蓝牙耳机、音响等设备听音乐，通过车载访问手机电话本、短信等数据，实现设备间的数据共享。

在鸿蒙开发框架中，传统蓝牙相关的典型模块包括 A2DP（高级音频分发配置文件）和 HFP（免提配置文件），对应 API 参考见 ohos.bluetooth.a2dp 与 ohos.bluetooth.hfp。

低功耗蓝牙（BLE）

低功耗蓝牙（Bluetooth Low Energy，BLE）是从蓝牙 4.0开始支持的技术。相比于传统蓝牙，BLE 在保障一定传输速率的情况下，具备更低功耗的特点，广泛使用于续航要求较高的蓝牙设备中。

• 最高传输速率可达1 Mbps；
• 通信范围通常为10 米左右；
• 相比传统蓝牙，BLE 以其低功耗特点，广泛应用于穿戴设备、智能家居和物联网传感器等领域。

BLE 的典型设备形态包括智能手表、健康监测设备、智能家居等，这些设备往往需要长时间运行，BLE 的低功耗特性使其成为最合适的技术选择（详见 Connectivity Kit 简介）。

BLE 的核心协议：GATT

GATT（Generic Attribute Profile，通用属性协议）是低功耗蓝牙（BLE）的核心协议，定义了基于**服务（Service）、特征值（Characteristic）和描述符（Descriptor）**进行蓝牙通信和传输数据的机制。开发者基于 GATT 即可实现 BLE 设备间的连接和数据传输，具体开发流程可参考本仓库的 通用属性协议开发指导。

在仓颉工程中开发蓝牙服务的路径指引

围绕上文的技术分类，本仓库提供了从 BLE 基础操作到 GATT 上层协议的完整开发文档链条，开发者可按以下顺序阅读与实践：

1. 查找设备（BLE 扫描与广播）

查找设备 提供了 BLE 扫描和 BLE 广播相关操作的开发指导，可实现发现周边 BLE 设备以及让其他设备发现本机设备的场景，核心接口包括startBleScanning()、stopBleScanning()、startAdvertising()、stopAdvertising()等，完整 API 说明见 ohos.bluetooth.ble API 参考。

2. 基于 GATT 传输数据

通用属性协议开发指导 详细讲解了 BLE 设备间连接和传输数据的实现方法，包括 GATT 客户端与服务端的完整示例代码（服务发现、读写特征值、读写描述符、接收/发送特征值变化通知或指示等）。

3. 申请蓝牙权限

开发蓝牙相关功能前，需要申请权限ohos.permission.ACCESS_BLUETOOTH。权限的配置和申请可参考 声明权限 和 向用户申请授权：在项目module.json5配置文件的requestPermissions标签中声明权限，并填写name、reason、usedScene等字段。该权限属于 user_grant 权限，reason字段必填且需要使用 string 类资源引用。

4. 错误码定位

开发过程中可通过 蓝牙服务子系统错误码 快速定位问题，例如：

• 2900001 Service stopped：蓝牙服务已停止，可重新执行打开或关闭蓝牙；
• 2900003 Bluetooth disabled：蓝牙开关已关闭，需重新打开蓝牙开关；
• 2900004 Profile not supported：当前设备环境不支持该配置文件；
• 2900099 Operation failed：操作失败，可重试该操作；
• 2901000 Read forbidden/2901001 Write forbidden：无读写操作权限。

总结

蓝牙服务是鸿蒙终端设备短距通信能力的重要组成部分。开发者应根据应用场景选择合适的蓝牙技术：需要高吞吐音频、免提通话等场景选择传统蓝牙（BR/EDR），需要长续航、低功耗连接的场景选择低功耗蓝牙（BLE）。在此基础上，借助本仓库的 查找设备、通用属性协议开发指导 以及 蓝牙 BLE API 参考，即可在仓颉工程中完成从设备发现、连接建立到数据收发的一整套蓝牙开发流程。

• 文档
• 知识库
• 教程
• OpenHarmony