README.md
1# Bluetooth<a name="ZH-CN_TOPIC_0000001148577119"></a>
2
3- [Introduction](#section11660541593)
4- [Directory Structure](#section161941989596)
5- [Constraints](#section119744591305)
6- [Usage](#section1312121216216)
7 - [Standard System](#section1699952017198)
8 - [Mini or Small System](#section223312597203)
9 - [C APIs](#section129654513264)
10
11- [Repositories Involved](#section1371113476307)
12
13## Introduction<a name="section11660541593"></a>
14
15The Bluetooth module provides APIs for accessing and using Bluetooth services, such as APIs for Generic Attribute Profile (GATT) operations, Bluetooth Low Energy (BLE) advertising, and scan.
16
17## Directory Structure<a name="section161941989596"></a>
18
19```
20/foundation/communication/bluetooth
21├── interfaces # API code
22│ └── innerkits # System service APIs
23│ ├── native_c # C APIs
24│ │ └── include # Header files for C APIs
25│ └── native_cpp # C++ APIs
26├── sa_profile # Service ability profile
27└── services # Bluetooth service code
28└── LICENSE # License declaration file
29```
30
31## Constraints<a name="section119744591305"></a>
32
33The Bluetooth module must be compiled in C language.
34
35## Usage<a name="section1312121216216"></a>
36
37Only BLE-related APIs and basic Bluetooth Generic Access Profile (GAP) APIs are provided.
38
39### Standard System<a name="section1699952017198"></a>
40
41The C API definition as well as the service and protocol stack code are provided for the standard system. Currently, only the BLE-related APIs, including the APIs for GATT operations on BLE devices, BLE advertising, and scan, are provided. Other APIs, such as APIs related to A2DP, AVRCP, and HFP, will be gradually provided later.
42
43The directories for the standard system are as follows:
44
45[interfaces/](https://gitee.com/openharmony/communication_bluetooth/tree/master/interfaces)
46
47[sa\_profile/](https://gitee.com/openharmony/communication_bluetooth/tree/master/sa_profile)
48
49[services/](https://gitee.com/openharmony/communication_bluetooth/tree/master/services)
50
51### Mini or Small System<a name="section223312597203"></a>
52
53Only C APIs for BLE, such as APIs for GATT operations, BLE advertising, and scan, are provided for the mini and small systems. Other APIs, such as APIs related to A2DP, AVRCP, and HFP, will be gradually provided later.
54
55The directory for the mini or standard system is as follows:
56
57interfaces/innerkits/native\_c/include
58
59### C APIs<a name="section129654513264"></a>
60
61- Enable or disable Bluetooth.
62
63```
64/* Enable classic Bluetooth.*/
65bool EnableBt(void);
66/* Disable classic Bluetooth. */
67bool DisableBt(void);
68/* Enable BLE. */
69bool EnableBle(void);
70/* Disable BLE. */
71bool DisableBle(void);
72```
73
74- Obtain Bluetooth status.
75
76```
77/* Obtain the classic Bluetooth status. */
78int GetBtState();
79/* Check whether BLE is enabled. */
80bool IsBleEnabled();
81```
82
83- Obtain the local MAC address.
84
85```
86/* Obtain the MAC address. */
87bool GetLocalAddr(unsigned char *mac, unsigned int len);
88```
89
90- Set the name of the local device.
91
92```
93/* Set the name of the local device.*/
94bool SetLocalName(unsigned char *localName, unsigned char length);
95```
96
97- Enable the GATT server feature and start the GATT service.
98
99```
100/* Initialize the Bluetooth protocol stack. */
101int InitBtStack(void);
102int EnableBtStack(void);
103/* Register an application with a specified appUuid. */
104int BleGattsRegister(BtUuid appUuid);
105/* Add a service. */
106int BleGattsAddService(int serverId, BtUuid srvcUuid, bool isPrimary, int number);
107/* Add a characteristic. */
108int BleGattsAddCharacteristic(int serverId, int srvcHandle, BtUuid characUuid, int properties, int permissions);
109/* Add a descriptor. */
110int BleGattsAddDescriptor(int serverId, int srvcHandle, BtUuid descUuid, int permissions);
111/* Start the GATT service. */
112int BleGattsStartService(int serverId, int srvcHandle);
113```
114
115- Enable BLE advertising.
116
117```
118/* Set the data to advertise. */
119int BleSetAdvData(int advId, const BleConfigAdvData *data);
120/* Start advertising. */
121int BleStartAdv(int advId, const BleAdvParams *param);
122```
123
124- Enable BLE scan.
125
126```
127/* Set scan parameters. */
128int BleSetScanParameters(int clientId, BleScanParams *param);
129/* Start a scan. */
130int BleStartScan(void);
131```
132
133## Repositories Involved<a name="section1371113476307"></a>
134
135communication\_bluetooth
136
README_zh.md
1# 蓝牙组件<a name="ZH-CN_TOPIC_0000001148577119"></a>
2
3- [简介](#section11660541593)
4- [目录](#section161941989596)
5- [约束](#section119744591305)
6- [说明](#section1312121216216)
7 - [标准系统使用说明](#section1699952017198)
8 - [轻量或小型系统使用说明](#section223312597203)
9 - [C接口使用说明](#section129654513264)
10
11- [相关仓](#section1371113476307)
12
13## 简介<a name="section11660541593"></a>
14
15蓝牙服务组件为设备提供接入与使用Bluetooth的相关接口，包括BLE设备gatt相关的操作，以及BLE广播、扫描等功能。
16
17## 目录<a name="section161941989596"></a>
18
19```
20/foundation/communication/bluetooth
21├── interfaces # 接口代码
22│ └── innerkits # 系统服务接口存放目录
23│ ├── native_c # C接口存放目录
24│ │ └── include # C接口定义目录
25│ └── native_cpp # C++接口存放目录
26│── sa_profile # 蓝牙服务定义目录
27│── services # 蓝牙服务代码目录
28└── LICENSE # 版权声明文件
29```
30
31## 约束<a name="section119744591305"></a>
32
33蓝牙服务组件使用C语言编写。
34
35## 说明<a name="section1312121216216"></a>
36
37现在提供的是BLE相关接口及GAP基本开关蓝牙的接口，其它接口暂不提供。
38
39### 标准系统使用说明<a name="section1699952017198"></a>
40
41标准系统提供C接口定义及服务和协议栈的代码，目前提供的只有BLE相关的接口，包括BLE设备gatt相关的操作，以及BLE广播、扫描等功能，其它A2DP，AVRCP，HFP等相关接口在后续增量发布。
42
43标准系统使用目录如下：
44
45[interfaces/](https://gitee.com/openharmony/communication_bluetooth/tree/master/interfaces)
46
47[sa\_profile/](https://gitee.com/openharmony/communication_bluetooth/tree/master/sa_profile)
48
49[services/](https://gitee.com/openharmony/communication_bluetooth/tree/master/services)
50
51### 轻量或小型系统使用说明<a name="section223312597203"></a>
52
53轻量或小型系统只提供C接口定义，目前只有BLE相关接口，包括BLE设备gatt相关的操作，以及BLE广播、扫描等功能，其它A2DP，AVRCP，HFP等相关接口在后续增量发布。
54
55轻量或小型系统使用目录如下：
56
57interfaces/innerkits/native\_c/include
58
59### C接口使用说明<a name="section129654513264"></a>
60
61- 打开/关闭蓝牙：
62
63```
64/* 打开传统蓝牙 */
65bool EnableBt(void);
66/* 关闭传统蓝牙 */
67bool DisableBt(void);
68/* 打开低功耗蓝牙 */
69bool EnableBle(void);
70/* 关闭低功耗蓝牙 */
71bool DisableBle(void);
72```
73
74- 获取蓝牙状态
75
76```
77/* 获取传统蓝牙状态 */
78int GetBtState();
79/* 判断低功耗蓝牙状态 */
80bool IsBleEnabled();
81```
82
83- 获取本端Mac地址
84
85```
86/* 获取mac地址 */
87bool GetLocalAddr(unsigned char *mac, unsigned int len);
88```
89
90- 设置本端设备名称
91
92```
93/* 设置本端设备名称 */
94bool SetLocalName(unsigned char *localName, unsigned char length);
95```
96
97- 设备需要完成以下接口的开发步骤，以使能Gatt server功能并开启服务：
98
99```
100/* 初始化蓝牙协议栈 */
101int InitBtStack(void);
102int EnableBtStack(void);
103/* 注册应用，appUuid由应用提供 */
104int BleGattsRegister(BtUuid appUuid);
105/* 添加服务 */
106int BleGattsAddService(int serverId, BtUuid srvcUuid, bool isPrimary, int number);
107/* 添加特征值 */
108int BleGattsAddCharacteristic(int serverId, int srvcHandle, BtUuid characUuid, int properties, int permissions);
109/* 添加描述符 */
110int BleGattsAddDescriptor(int serverId, int srvcHandle, BtUuid descUuid, int permissions);
111/* 开始服务 */
112int BleGattsStartService(int serverId, int srvcHandle);
113```
114
115- 设备需要完成以下接口的开发步骤，以使能BLE广播的发送：
116
117```
118/* 设置广播数据 */
119int BleSetAdvData(int advId, const BleConfigAdvData *data);
120/* 开始发送广播 */
121int BleStartAdv(int advId, const BleAdvParams *param);
122```
123
124- 若需要扫描功能，设备需要完成以下接口的开发步骤，以使能BLE扫描功能：
125
126```
127/* 设置扫描参数 */
128int BleSetScanParameters(int clientId, BleScanParams *param);
129/* 开始扫描 */
130int BleStartScan(void);
131```
132
133## 相关仓<a name="section1371113476307"></a>
134
135communication\_bluetooth
136
137