当前文档版本为 v0.9.1，您可以访问当前页面的开发中版本以获取最近可能的更新。

BLE App 开发指南¶

本文主要通过一些示例，介绍蓝牙应用开发过程中常用的方法以及可能遇到的问题。

1 基础指标¶

1.1 功耗¶

蓝牙在不同的工作模式下功耗如下表所示：

测试条件：

基于例程 bluetooth\peripheral_hr, 配置文件 prj_lp_rcl.conf / prj_lp_xtl.conf

发射功率：0 dBm，广播数据：33 Bytes，其它参数请参考项目文件

PAN1080/PAN1081 EVB 核心板功耗测试数据¶

PAN1080/PAN1081 EVB 核心板配置latency功耗测试数据¶

PAN1082 EVB 核心板功耗测试数据¶

PAN1083 EVB 核心板功耗测试数据¶

PAN3730 EVB 核心板功耗测试数据¶

注意：上述测试中，RCL 使用 1000ppm 的配置，实际项目中可根据方案实际情况，适当调整 ppm。例如 1s interval 1000ppm 连接状态下的功耗相比于 2000ppm，平均电流大约可以减少20ua。

1.2 RSSI¶

PAN1080 在天线直连模式下测试，RSSI 精度在 ±2 dB。在蓝牙扫描模式下，使用板载天线测试不同距离下ibeacon的RSSI分布，测试数据如下表：

以下数据基于例程 bluetooth\central 进行接受空中ibeacon的测试，测试扫描使用的是channel37单通道（adv实际3通道发射功率会略有差异）。

类别	3米	5米	8米	10米	13米	15米
平均值(dBm)	-66.3253012	-67.98387097	-69.18181818	-73.05084746	-75.6	-76.76136364
总体方差	0.886422806	0.85179006	0.97404329	0.928343318	0.771669272	0.881654862

2 添加GATT服务¶

2.1 确认开发环境¶

参考SDK 快速入门，确认软硬件开发环境，可以正常的编译、下载和调试SDK提供的基础例程。

建议连接板载的 micro USB，通过串口工具监测 Log。

2.2 参考相关例程¶

蓝牙开发需要了解一些蓝牙协议相关的知识，可以参考蓝牙协议规范，网上也有很多协议的介绍，此处不作为重点。

当前SDK中提供了一些蓝牙相关的例程，涵盖了 beacon、central、peripheral、hid、mesh 等。

在进行蓝牙开发之前，建议先看一下相关的例程和文档，磨刀不误砍柴工，相信这些例程会对你的开发有所帮助。

蓝牙例程目录¶

2.3 新建一个蓝牙例程¶

在对蓝牙协议以及相关例程有一些了解之后，就可以尝试进行开发了，这里我们演示一个蓝牙收、发服务例程，具体服务描述如下：

Service or Characteristic	UUID	Properties
T/Rx Service	0x12345678-1234- 5678-1234-56789abcdef0
Data From Client to Server Characteristic	0x12345678-1234- 5678-1234-56789abcdef1	Write
Data From Server to Client Characteristic	0x12345678-1234- 5678-1234-56789abcdef2	Read, Notify

2.3.1 拷贝一份相似的工程¶

当然你也可以在原有例程上进行修改，初期并不建议开发者从头开始进行开发。

例程 peripheral_hr 演示了简单的健康温度计(Health Thermometer)服务，可以在建立连接后将采集温度并上报给主机，我们将以这个例程为基础，来进行修改和补充，首先拷贝一份 peripheral_hr 并重命名为 peripheral_trx。

拷贝一份相似的工程¶

其中的必要的文件为：

src\main.c: 主程序代码
CMakeList.txt: cmake 文件
prj.conf: 项目配置文件

其它几个文件都不是必须的：

prj_minimal.conf: 编译阶段可选的项目配置文件
README.rst: 项目说明文件
sample.yaml: 用于 zephyr tests 的文件

2.3.2 进行必要的调整¶

(1) 为了简单起见，我们删掉不必要的文件。

删掉 prj_minimal.conf，README.rst，sample.yaml。

只保留必要的文件¶

(2) 在 CMakeList.txt 文件中修改项目名称为 peripheral_trx。

## SPDX-License-Identifier: Apache-2.0

cmake_minimum_required(VERSION 3.20.0)

find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(peripheral_trx)

FILE(GLOB app_sources src/*.c)
target_sources(app PRIVATE
  ${app_sources}
  )

zephyr_library_include_directories(${ZEPHYR_BASE}/samples/bluetooth)

(3) 在 prj.conf 中修改项目的配置，关闭不必要的配置。

CONFIG_BT=y
CONFIG_BT_DEBUG_LOG=y
CONFIG_BT_PERIPHERAL=y
CONFIG_BT_DEVICE_NAME="Peripheral TRx"
CONFIG_BT_DEVICE_NAME_DYNAMIC=y

CONFIG_BT=y: 使能蓝牙
CONFIG_BT_DEBUG_LOG=y: 使能蓝牙 log
CONFIG_BT_PERIPHERAL=y: 使能 peripheral
CONFIG_BT_DEVICE_NAME="Peripheral TRx": 修改蓝牙设备名称

(4) 在 main.c 中删掉不必要的代码，如原来代码中关于 BAS、HRS、AUTH 相关的内容。

#include <zephyr/types.h>
#include <stddef.h>
#include <string.h>
#include <errno.h>
#include <sys/printk.h>
#include <sys/byteorder.h>
#include <zephyr.h>

#include <bluetooth/bluetooth.h>
#include <bluetooth/hci.h>
#include <bluetooth/conn.h>
#include <bluetooth/uuid.h>
#include <bluetooth/gatt.h>

static const struct bt_data ad[] = {
	BT_DATA_BYTES(BT_DATA_FLAGS, (BT_LE_AD_GENERAL | BT_LE_AD_NO_BREDR)),
};

static void connected(struct bt_conn *conn, uint8_t err)
{
	if (err) {
		printk("Connection failed (err 0x%02x)\n", err);
	} else {
		printk("Connected\n");
	}
}

static void disconnected(struct bt_conn *conn, uint8_t reason)
{
	printk("Disconnected (reason 0x%02x)\n", reason);
}

BT_CONN_CB_DEFINE(conn_callbacks) = {
	.connected = connected,
	.disconnected = disconnected,
};

static void bt_ready(void)
{
	int err;

	printk("Bluetooth initialized\n");

	err = bt_le_adv_start(BT_LE_ADV_CONN_NAME, ad, ARRAY_SIZE(ad), NULL, 0);
	if (err) {
		printk("Advertising failed to start (err %d)\n", err);
		return;
	}

	printk("Advertising successfully started\n");
}

void main(void)
{
	int err;

	err = bt_enable(NULL);
	if (err) {
		printk("Bluetooth init failed (err %d)\n", err);
		return;
	}

	bt_ready();
}

上述代码比较简单，但有个点需要说明一下：

你可以使用 BT_CONN_CB_DEFINE 来为连接事件注册回调函数，但却不需要对它进行额外的初始化；系统会将用这种方法定义的回调函数放到特定代码空间进行统一处理。
初次接触的开发者可能会感到困惑，但它会很方便，特别是多个文件都需要处理这个回调函数时，只需要按照同样的方式处理即可。

(5) 重新编译和下载例程

此时我们重新编译 (rebuild)，并下载。

下载成功，系统执行起来以后，串口工具将显示如下 Log：

*** Booting Zephyr OS version 2.7.0  ***
Bluetooth initialized
Advertising successfully started
[00:00:00.186,000] <inf> bt_hci_core: Identity: C4:3E:A1:88:FD:9A (random)
[00:00:00.186,000] <inf> bt_hci_core: HCI: version 5.1 (0x0a) revision 0x0003, manufacturer 0x07d1
[00:00:00.187,000] <inf> bt_hci_core: LMP: version 5.1 (0x0a) subver 0x0000

手机端可以通过 nRF Connect APP 进行搜索、连接蓝牙设备

注意，非HID相关的例程，不建议通过手机设置界面查看和连接蓝牙设备，因为这可能涉及到一些手机系统的设备过滤和功能要求。

nRF Connect 搜索广播¶

nRF Connect 成功连接并显示Service信息¶

2.3.3 添加GATT服务¶

(1) 定义 UUID

/* TRx Service Variables */
#define BT_UUID_TRX_SERVICE_VAL \
	BT_UUID_128_ENCODE(0x12345678, 0x1234, 0x5678, 0x1234, 0x56789abcdef0)

static struct bt_uuid_128 trx_svc_uuid = BT_UUID_INIT_128(
	BT_UUID_TRX_SERVICE_VAL);

static struct bt_uuid_128 trx_c2s_uuid = BT_UUID_INIT_128(
	BT_UUID_128_ENCODE(0x12345678, 0x1234, 0x5678, 0x1234, 0x56789abcdef1));

static struct bt_uuid_128 trx_s2c_uuid = BT_UUID_INIT_128(
	BT_UUID_128_ENCODE(0x12345678, 0x1234, 0x5678, 0x1234, 0x56789abcdef2));

这里把 BT_UUID_TRX_SERVICE_VAL 单独列出来，是为了后面加到广播数据中，以暴露此服务。

(2) 定义 GATT 服务

可以使用 BT_GATT_SERVICE_DEFINE 来定义服务，它和前面介绍的 BT_CONN_CB_DEFINE 一样，将被系统放到特定代码空间，不需要额外初始化。

定义了三个 buffer 来存放待收发的数据：trx_c2s_value，trx_s2c_value，trx_s2c_ntf_value。

定义了三个接口，处理数据收发：write_trx_c2s，read_trx_s2c，trx_s2c_ccc_cfg_changed。

GATT 服务一般要包含：BT_GATT_PRIMARY_SERVICE, BT_GATT_CHARACTERISTIC，包含 notify / indicate 时，还需要用到 BT_GATT_CCC 来进行管理是否使能。

更多的示例，请参考例程 bluetooth\peripheral。

#define TRX_MAX_LEN 20

static uint8_t trx_c2s_value[TRX_MAX_LEN + 1] = {
	'T', 'R', 'X', '_', 'C', '2', 'S'
};
static uint8_t trx_s2c_value[TRX_MAX_LEN + 1] = {
	'T', 'R', 'X', '_', 'S', '2', 'C'
};
static uint32_t trx_s2c_ntf_value;

static ssize_t write_trx_c2s(struct bt_conn *conn, const struct bt_gatt_attr *attr,
			 const void *buf, uint16_t len, uint16_t offset,
			 uint8_t flags)
{
	uint8_t *value = attr->user_data;

	if (offset + len > TRX_MAX_LEN) {
		return BT_GATT_ERR(BT_ATT_ERR_INVALID_OFFSET);
	}

	memcpy(value + offset, buf, len);
	value[offset + len] = 0;

	printk("write (%d): ", len);
	for (uint8_t i = 0; i < len; i++)
	{
		printk("0x%02X ", value[i]);
	}
	printk("\n");

	return len;
}

static ssize_t read_trx_s2c(struct bt_conn *conn, const struct bt_gatt_attr *attr,
			void *buf, uint16_t len, uint16_t offset)
{
	const char *value = attr->user_data;

	return bt_gatt_attr_read(conn, attr, buf, len, offset, value,
				 strlen(value));
}

static uint8_t simulate;

static void trx_s2c_ccc_cfg_changed(const struct bt_gatt_attr *attr, uint16_t value)
{
	simulate = (value == BT_GATT_CCC_NOTIFY) ? 1 : 0;
}

/* TRx Primary Service Declaration */
BT_GATT_SERVICE_DEFINE(trx_svc,
	BT_GATT_PRIMARY_SERVICE(&trx_svc_uuid),
	BT_GATT_CHARACTERISTIC(&trx_c2s_uuid.uuid,
			       BT_GATT_CHRC_WRITE, BT_GATT_PERM_WRITE,
			       NULL, write_trx_c2s, trx_c2s_value),
	BT_GATT_CHARACTERISTIC(&trx_s2c_uuid.uuid,
			       BT_GATT_CHRC_READ | BT_GATT_CHRC_NOTIFY,
			       BT_GATT_PERM_READ,
			       read_trx_s2c, NULL, trx_s2c_value),
	BT_GATT_CCC(trx_s2c_ccc_cfg_changed,
		    BT_GATT_PERM_READ | BT_GATT_PERM_WRITE),
);

(3) 定义接口

这里定义了两个接口：

trx_init：初始化 notify attribute
trx_notify：上报数据给 client

static struct bt_gatt_attr *trx_ntf_attr;

static void trx_init(void)
{
	trx_ntf_attr = bt_gatt_find_by_uuid(trx_svc.attrs, trx_svc.attr_count, &trx_s2c_uuid.uuid);
}

static void trx_notify(void)
{
	if (simulate) {
		bt_gatt_notify(NULL, trx_ntf_attr, &trx_s2c_ntf_value, sizeof(trx_s2c_ntf_value));
		trx_s2c_ntf_value++;
	}
}

(4) 修改广播数据

添加了 TRx Service UUID，以便在广播数据中发现它。

static const struct bt_data ad[] = {
	BT_DATA_BYTES(BT_DATA_FLAGS, (BT_LE_AD_GENERAL | BT_LE_AD_NO_BREDR)),
	BT_DATA_BYTES(BT_DATA_UUID128_ALL, BT_UUID_TRX_SERVICE_VAL),
};

(5) 初始化 trx service 并在连接建立且使能 notify 后上报数据

void main(void)
{
	int err;

	err = bt_enable(NULL);

	trx_init();

	if (err) {
		printk("Bluetooth init failed (err %d)\n", err);
		return;
	}

	bt_ready();

	while (1) {
		k_sleep(K_SECONDS(1));

		trx_notify();
	}
}

2.3.4 功能演示¶

(1) 扫描设备

扫描设备¶

(2) 建立连接

建立连接¶

串口工具将打印连接状态变化的信息：

Connected

(3) 写数据

写数据¶

串口工具将打印收到的数据：

write (5): 0x12 0x34 0x56 0x78 0x90

(4) 读数据

读数据¶

(5) Notify

Notify¶

Logs¶

3 蓝牙相关的接口说明¶

3.1 GAP¶

3.1.1 蓝牙地址使用¶

random addr¶

蓝牙初始化默认使用的是随机地址，随机地址每次蓝牙初始化都不一样。随机地址初始化如下：

static int set_random_address(const bt_addr_t *addr)
{
	struct net_buf *buf;
	int err;

	BT_DBG("%s", bt_addr_str(addr));

	/* Do nothing if we already have the right address */
	if (!bt_addr_cmp(addr, &bt_dev.random_addr.a)) {
		return 0;
	}

	buf = bt_hci_cmd_create(BT_HCI_OP_LE_SET_RANDOM_ADDRESS, sizeof(*addr));
	if (!buf) {
		return -ENOBUFS;
	}

	net_buf_add_mem(buf, addr, sizeof(*addr));

	err = bt_hci_cmd_send_sync(BT_HCI_OP_LE_SET_RANDOM_ADDRESS, buf, NULL);
	if (err) {
		return err;
	}

	bt_addr_copy(&bt_dev.random_addr.a, addr);
	bt_dev.random_addr.type = BT_ADDR_LE_RANDOM;
	return 0;
}

静态的随机地址，在bt_le_adv_start调用，地址的高字节的高2bit必须要强制写1。初始化如下所示：

bt_addr_le_t set_addr = {
	.type = BT_ADDR_LE_RANDOM,
	.a = { { 0x01, 0x02, 0x03, 0x04, 0x05, 0xC6 } },
};

bt_static_address_init(&set_addr.a);

public addr¶

public地址来源有三种模式:

用户自定义
INFO区(PANLINK烧录)
EFUSE(芯片的ID)

用户自定义模式：

//在工程的"prj.conf"文件中使能CONFIG_BT_USER_DEFINED_PUBLIC_MAC

CONFIG_BT_USER_DEFINED_PUBLIC_MAC=y

//地址初始化

int err;
struct ble_cfg_t *ble_cfg = (struct ble_cfg_t *)param;

bt_set_user_public_mac(ble_cfg->ble_addr);

err = bt_enable(NULL);
if (err) {
    printk("Bluetooth init failed (err %d)\n", err);
    return;
}

bt_ready(param);

INFO区和EFUSE：

//在工程的"prj.conf"文件中使能CONFIG_BT_SET_PUBLIC_MAC

CONFIG_BT_SET_PUBLIC_MAC=y

bt_addr_t pub_addr_info;
bt_addr_t pub_addr_efuse;

uint8_t addr_zero[6] = {0};
uint8_t addr_all_0xff[6] = {0xff, 0xff, 0xff, 0xff, 0xff, 0xff};

hwinfo_get_info_mac(pub_addr_info.val, 6);

hwinfo_get_efuse_mac(pub_addr_efuse.val, 6);

if (memcmp(pub_addr_efuse.val, addr_zero, 6) != 0) {
    bt_public_address_set(&pub_addr_efuse);
} else if (memcmp(pub_addr_info.val, addr_all_0xff, 6) != 0) {
    bt_public_address_set(&pub_addr_info);
}

当efuse和info区域同时存在地址值时，优先使用efuse区域中的内容，efuse区域不存在地址值就使用info区域中的。两个区域都不存在地址就可以使用用户自定义的地址。

3.2 GATT¶

16-bit或128-bit的UUID唯一决定了 Service/Characteristic.

16-bit UUID 用于标准 Bluetooth Service/Characteristic
128-bit UUID 用于厂商自定义的一些服务

3.2.1 Bluetooth Service¶

GAP Service¶

这是一个基础服务，默认开启，不建议用户修改。

如果确实需要修改，建议使用 CONFIG_BT_GAP_SERVICE=n 关掉这个服务，然后在应用层重新实现，这样可以避免代码更新导致的冲突。

源码路径：zephyr\subsys\bluetooth\host\gatt.c。

Service or Characteristics	Kconfig	Description	ROM	SRAM
GAP Service	`CONFIG_BT_GAP_SERVICE`	Enable GAP service (Enabled by default)
Device Name Characteristic	`N/A`	Device name characteristic (Always enable)	-	-
Appearance Characteristic	`N/A`	Appearance characteristic (Always enable)	-	-
Central Address Resolution Characteristic	`CONFIG_BT_CENTRAL` `CONFIG_BT_PRIVACY`	Depends on Central Role & Privacy Feature	-	-
Service Changed Characteristic	`CONFIG_BT_GAP_PERIPHERAL_PREF_PARAMS`	Configure peripheral preferred connection parameters

GATT Service¶

这是一个基础服务，默认开启，不建议用户修改。

如果确实需要修改，建议使用 CONFIG_BT_GATT_SERVICE=n 关掉这个服务，然后在应用层重新实现，这样可以避免代码更新导致的冲突。

源码路径：zephyr\subsys\bluetooth\host\gatt.c。

Service or Characteristics	Kconfig	Description
GATT Service	`CONFIG_BT_GATT_SERVICE`	Enable GATT service (Enabled by default)
Service Changed Characteristic	`CONFIG_BT_GATT_SERVICE_CHANGED`	GATT Service Changed support
Client Supported Features & Database Hash Characteristic	`CONFIG_BT_GATT_CACHING`	GATT Caching support
Server Supported Features Characteristic	`CONFIG_BT_EATT`	Enhanced ATT Bearers support [EXPERIMENTAL]

Battery Service¶

源码路径：zephyr\subsys\bluetooth\services\bas.c。

Service or Characteristics	Kconfig	Description	ROM	SRAM
Battery Service	`CONFIG_BT_BAS`	Enable GATT Battery service
Battery Level Characteristic	`N/A`	BAS Battery level characteristic (Always enable)	-	-

APIs

bt_bas_get_battery_level
bt_bas_set_battery_level

需要包含头文件 #include <bluetooth/services/bas.h>

Device Information Service¶

源码路径：zephyr\subsys\bluetooth\services\dis.c。

Service or Characteristics	Kconfig	Description	ROM	SRAM
Device Information Service	`CONFIG_BT_DIS`	Enable GATT Device Information service
	`CONFIG_BT_DIS_SETTINGS`	Enable Settings usage in Device Information Service
	`CONFIG_BT_DIS_STR_MAX`	Maximum size in bytes for DIS strings	-	-
Model Number String Characteristic	`N/A`	DIS Model number string characteristic (Always enable)	-	-
	`CONFIG_BT_DIS_MODEL`	Model name	-	-
Manufacturer Name String Characteristic	`N/A`	DIS Manufacturer name string characteristic (Always enable)	-	-
	`CONFIG_BT_DIS_MANUF`	Manufacturer name	-	-
Firmware Revision String Characteristic	`CONFIG_BT_DIS_FW_REV`	Enable DIS Firmware Revision characteristic
	`CONFIG_BT_DIS_FW_REV_STR`	Firmware revision	-	-
Hardware Revision String Characteristic	`CONFIG_BT_DIS_HW_REV`	Enable DIS Hardware Revision characteristic
	`CONFIG_BT_DIS_HW_REV_STR`	Hardware revision	-	-
PnP ID Characteristic	`CONFIG_BT_DIS_PNP`	Enable PnP_ID characteristic
	`CONFIG_BT_DIS_PNP_PID`	Product ID	-	-
	`CONFIG_BT_DIS_PNP_VER`	Product Version	-	-
	`CONFIG_BT_DIS_PNP_VID`	Vendor ID	-	-
	`CONFIG_BT_DIS_PNP_VID_SRC`	Vendor ID source	-	-
Serial Number String Characteristic	`CONFIG_BT_DIS_SERIAL_NUMBER`	Enable DIS Serial number characteristic
	`CONFIG_BT_DIS_SERIAL_NUMBER_STR`	Serial Number	-	-
Software Revision String Characteristic	`CONFIG_BT_DIS_SW_REV`	Enable DIS Software Revision characteristic
	`CONFIG_BT_DIS_SW_REV_STR`	Software revision	-	-

Heart Rate Service¶

源码路径：zephyr\subsys\bluetooth\services\hrs.c。

Service or Characteristics	Kconfig	Description	ROM	SRAM
Heart Rate Service	`CONFIG_BT_HRS`	Enable GATT Heart Rate service
	`CONFIG_BT_HRS_DEFAULT_PERM_RW`	Read and write allowed
	`CONFIG_BT_HRS_DEFAULT_PERM_RW_AUTHEN`	Require encryption and authentication for access
	`CONFIG_BT_HRS_DEFAULT_PERM_RW_ENCRYPT`	Require encryption for access
Measurement Interval Characteristic	`N/A`	HRS Measurement interval characteristic (Always enable)	-	-
Body Sensor Location Characteristic	`N/A`	HRS Body sensor location characteristic (Always enable)	-	-
Control Point Characteristic	`N/A`	HRS Control Point characteristic (Always enable)	-	-

APIs

bt_hrs_notify

需要包含头文件 #include <bluetooth/services/hrs.h>

Object Transfer Service¶

源码路径：zephyr\subsys\bluetooth\services\ots\*。

Service or Characteristics	Kconfig	Description	ROM	SRAM
Object Transfer Service	`CONFIG_BT_OTS`	Object Transfer Service (OTS) [EXPERIMENTAL]
	`CONFIG_BT_OTS_DIR_LIST_OBJ`	Enables the Directory Listing Object
	`CONFIG_BT_OTS_DIR_LIST_OBJ_NAME`	The object name of the Directory Listing Object
	`CONFIG_BT_OTS_L2CAP_CHAN_RX_MTU`	Size of RX MTU for Object Transfer Channel
	`CONFIG_BT_OTS_L2CAP_CHAN_TX_MTU`	Size of TX MTU for Object Transfer Channel
	`CONFIG_BT_OTS_MAX_INST_CNT`	Maximum number of available OTS instances
	`CONFIG_BT_OTS_MAX_OBJ_CNT`	Maximum number of objects that each service instance can store
	`CONFIG_BT_OTS_OACP_CREATE_SUPPORT`	Support OACP Create Operation
	`CONFIG_BT_OTS_OACP_DELETE_SUPPORT`	Support OACP Delete Operation
	`CONFIG_BT_OTS_OACP_PATCH_SUPPORT`	Support patching of objects
	`CONFIG_BT_OTS_OACP_READ_SUPPORT`	Support OACP Read Operation
	`CONFIG_BT_OTS_OACP_WRITE_SUPPORT`	Support OACP Write Operation
	`CONFIG_BT_OTS_OBJ_MAX_NAME_LEN`	Maximum object name length
	`CONFIG_BT_OTS_OBJ_NAME_WRITE_SUPPORT`	Support object name write
	`CONFIG_BT_OTS_OLCP_GO_TO_SUPPORT`	Support OLCP Go To Operation
	`CONFIG_BT_OTS_SECONDARY_SVC`	Register OTS as Secondary Service
OTS Feature Characteristic	`N/A`	OTS Feature characteristic (Always enable)	-	-
OTS Object Name Characteristic	`N/A`	OTS Object name characteristic (Always enable)	-	-
OTS Object Type Characteristic	`N/A`	OTS Object type characteristic (Always enable)	-	-
OTS Object Size Characteristic	`N/A`	OTS Object size characteristic (Always enable)	-	-
OTS Object ID Characteristic	`N/A`	OTS Object ID characteristic (Always enable)	-	-
OTS Object Properties Characteristic	`N/A`	OTS Object properties characteristic (Always enable)	-	-
OTS Object Action Control Point Characteristic	`N/A`	OTS Object action control point characteristic (Always enable)	-	-
OTS Object List Control Point Characteristic	`N/A`	OTS Object list control point characteristic (Always enable)	-	-

APIs

bt_ots_init
bt_ots_obj_add
bt_ots_obj_delete
bt_ots_svc_decl_get
bt_ots_free_instance_get
bt_ots_obj_id_to_str

需要包含头文件 #include <bluetooth/services/ots.h>

3.3 Notify¶

参考 bt_gatt_indicate 参数计算。

int notify_send(const void *data, uint16_t len)
{
    return bt_gatt_notify(NULL, &cvs.attrs[1], data, len);
}

3.3 Indicate¶

static void indicate_cb(struct bt_conn *conn,
						struct bt_gatt_indicate_params *params, uint8_t err)
{
	printk("Indication %s\n", err != 0U ? "fail" : "success");
}

static void indicate_destroy(struct bt_gatt_indicate_params *params)
{
	printk("Indication complete\n");
}

int indicate_send(const void *data, uint16_t len)
{
    static struct bt_gatt_attr *ind_attr;
    static struct bt_gatt_indicate_params ind_params;

    vnd_ind_attr = bt_gatt_find_by_uuid(svc.attrs, svc.attr_count,
                            			&chr_uuid.uuid);

    ind_params.attr = ind_attr;
	ind_params.func = indicate_cb;
	ind_params.destroy = indicate_destroy;
	ind_params.data = data;
	ind_params.len  = len;

    return bt_gatt_indicate(NULL, &ind_params);
}

3.4 Attribute Index¶

我们在使用 bt_gatt_indicate，bt_gatt_notify 时，需要传入一个参数 attr，这个参数与 GATT Service 的定义有关。下面介绍一下这个参数如何填写。

Service 是多个 Attribute 的集合，为了方便定义，我们使用宏进行组织服务，每个宏包含1或2个Attribute，如下：

宏	描述	数量
BT_GATT_PRIMARY_SERVICE	Primary Service Declaration Macro.	1
BT_GATT_SECONDARY_SERVICE	Secondary Service Declaration Macro.	1
BT_GATT_INCLUDE_SERVICE	Include Service Declaration Macro.	1
BT_GATT_CHARACTERISTIC	Characteristic and Value Declaration Macro.	2
BT_GATT_CCC	Client Characteristic Configuration Declaration Macro.	1
BT_GATT_CEP	Characteristic Extended Properties Declaration Macro.	1
BT_GATT_CUD	Characteristic User Format Descriptor Declaration Macro.	1
BT_GATT_CPF	Characteristic Presentation Format Descriptor Declaration Macro.	1
BT_GATT_DESCRIPTOR	Descriptor Declaration Macro.	1

如下是 Battery Service 的定义，源码位置：\subsys\bluetooth\services\bas.c

BT_GATT_SERVICE_DEFINE(bas,
	BT_GATT_PRIMARY_SERVICE(BT_UUID_BAS),
	BT_GATT_CHARACTERISTIC(BT_UUID_BAS_BATTERY_LEVEL,
			       BT_GATT_CHRC_READ | BT_GATT_CHRC_NOTIFY,
			       BT_GATT_PERM_READ, read_blvl, NULL,
			       &battery_level),
	BT_GATT_CCC(blvl_ccc_cfg_changed,
		    BT_GATT_PERM_READ | BT_GATT_PERM_WRITE),
);

其 Notify Characteristic Attribute index 为 1 (BT_GATT_PRIMARY_SERVICE)。

同样的，如下 hog_svc：

BT_GATT_SERVICE_DEFINE(hog_svc,
	BT_GATT_PRIMARY_SERVICE(BT_UUID_HIDS),
	BT_GATT_CHARACTERISTIC(BT_UUID_HIDS_INFO, BT_GATT_CHRC_READ,
			       BT_GATT_PERM_READ, read_info, NULL, &info),
	BT_GATT_CHARACTERISTIC(BT_UUID_HIDS_REPORT_MAP, BT_GATT_CHRC_READ,
			       BT_GATT_PERM_READ, read_report_map, NULL, NULL),
	BT_GATT_CHARACTERISTIC(BT_UUID_HIDS_REPORT,
			       BT_GATT_CHRC_READ | BT_GATT_CHRC_NOTIFY,
			       BT_GATT_PERM_READ_AUTHEN,
			       read_input_report, NULL, NULL),
	BT_GATT_CCC(input_ccc_changed,
		    BT_GATT_PERM_READ | BT_GATT_PERM_WRITE),
	BT_GATT_DESCRIPTOR(BT_UUID_HIDS_REPORT_REF, BT_GATT_PERM_READ,
			   read_report, NULL, &input),
	BT_GATT_CHARACTERISTIC(BT_UUID_HIDS_REPORT,
			       BT_GATT_CHRC_READ | BT_GATT_CHRC_NOTIFY,
			       BT_GATT_PERM_READ_AUTHEN,
			       read_input_report_consumer, NULL, NULL),
	BT_GATT_CCC(input_ccc_changed_consumer,
		    BT_GATT_PERM_READ | BT_GATT_PERM_WRITE),
	BT_GATT_DESCRIPTOR(BT_UUID_HIDS_REPORT_REF, BT_GATT_PERM_READ,
			   read_report_consumer, NULL, &input_consumer),
	BT_GATT_CHARACTERISTIC(BT_UUID_HIDS_CTRL_POINT,
			       BT_GATT_CHRC_WRITE_WITHOUT_RESP,
			       BT_GATT_PERM_WRITE,
			       NULL, write_ctrl_point, &ctrl_point),
);

第一个 Notify Characteristic Attribute index 为 5

BT_GATT_PRIMARY_SERVICE+BT_GATT_CHARACTERISTIC+BT_GATT_CHARACTERISTIC = 1+2+2
第二个 Notify Characteristic Attribute index 为 9

BT_GATT_PRIMARY_SERVICE+BT_GATT_CHARACTERISTIC+BT_GATT_CHARACTERISTIC + BT_GATT_CHARACTERISTIC + BT_GATT_CCC + BT_GATT_DESCRIPTOR = 1+2+2+2+1+1

3.5 INFO区 API说明¶

ssize_t hwinfo_get_efuse_mac(uint8_t *buffer, size_t length);

说明：获取EFUSE区域mac地址，其中buffer为存放的变量地址，length必须为固定值6。

ssize_t hwinfo_get_info_mac(uint8_t *buffer, size_t length);

说明：获取INFO区域mac地址，其中buffer为存放的变量地址，length必须为固定值6。INFO区mac地址为0x1B。

ssize_t hwinfo_get_triple(uint8_t read_type, uint8_t *buffer, size_t length);

说明：获取INFO区域三元组变量，read_type为获取三元组变量的类型。其中BLE_INFO_TRIPLE_PID_TYPE和BLE_INFO_TRIPLE_PID_SIZE为PID的类型和长度，BLE_INFO_TRIPLE_MAC_TYPE和BLE_INFO_TRIPLE_MAC_SIZE为MAC的类型和长度，BLE_INFO_TRIPLE_KEY_TYPE和BLE_INFO_TRIPLE_KEY_SIZE为KEY的类型和长度。

ssize_t hwinfo_read(size_t addr, uint8_t *buffer, size_t length);

说明：通用INFO区域读取函数，其中buffer为存放的变量地址，length为读取变量，不要超过4096。

3.6 ADV Filter 功能说明¶

当设备处于scan 的状态去扫描一些指定的广播包的时候，为了提高扫描的效率，PAN1080提供了一个硬件的接口去过滤掉空中其他的广播报文。例如mesh 入网的时候，只扫描和入网相关的广播报文。

3.6.1 过滤扫描广播类型¶

蓝牙spec 规定了很多广播类型，例如不可连接不可扫描的广播包，代码定义相关接口如下

#define PAN_SVC_CALL(opcode, p_data)

SVC_LL_ADV_TYPE_FILTER           			# opcode filter adv type

typedef struct {
	uint8_t enable;
	uint8_t type;
} adv_type_fi_t;						   # P_data related

#define FIL_ADV_IND_TYPE                    (1 << 0) # adv_type_fi_t.type related
#define FIL_ADV_NONCONN_IND_TYPE            (1 << 2) # adv_type_fi_t.type related
#define FIL_SCAN_RSP_TYPE                   (1 << 4) # adv_type_fi_t.type related
#define FIL_ADV_SCAN_IND_TYPE               (1 << 6) # adv_type_fi_t.type related
#define FIL_ADV_EXT_IND_OR_AUX_ADV_TYPE     (1 << 7) # adv_type_fi_t.type related

具体操作方法：

adv_type_fi_t fi;
fi.enable = 1;
fi.type = FIL_ADV_NONCONN_IND_TYPE;
PAN_SVC_CALL(SVC_LL_ADV_TYPE_FILTER, (void *)&fi);

3.6.2 过滤扫描广播数据¶

蓝牙spec 规定了广播数据的格式类型如下，PAN1080 可以过滤AD structure 1 的 length 和 AD Type，意味着只有符合我们指定的组合的广播包才会被接收，我们可以也可以添加多组。

adv数据结构¶

#define PAN_SVC_CALL(opcode, p_data)

SVC_LL_ADV_DATA_FILTER           			# opcode filter adv data

typedef struct {
	uint8_t enable;
	uint8_t index;                         # increase 1 if you has enabled a filter obj
	uint8_t len;
	uint8_t type;
} adv_date_filter_t;

具体操作方法：

adv_date_filter_t fi;
adv_date_filter_t.enable = 1;
adv_date_filter_t.index = 0;
adv_date_filter_t.len = 0; // ignor len
adv_date_filter_t.type = 0x2B //ble mesh message

PAN_SVC_CALL(SVC_LL_ADV_DATA_FILTER, (void *)&fi);