赛普拉斯蓝牙BLE---Component API Reference

1、GAP 函数

1.1、GAP Peripheral函数

函数原型：

CYBLE_API_RESULT_T CyBle_GappStartAdvertisement(uint8 advertisingIntervalType);

描述：

在PSOC Creator GUI中配置好BLE组件的参数之后，调用这个函数进行广播。设备就能够被GAP Central设备发现。只有设备处于GAP Peripheral 或者GAP Peripheral + Central角色的时候，才能调用这个函数。

在广播启动的时候，GAP Peripheral会收到CYBLE_EVT_GAPP_ADVERTISEMENT_START_STOP这个事件通知。另外，在调用这个函数期间，GAP Peripheral还可能收到以下通知：

CYBLE_EVT_GAP_DEVICE_CONNECTED（设备连接）:如果设备连接到了GAP Central设备，就会收到这个消息。

CYBLE_EVT_TIMEOUT（超时）:如果在指定的超时时间内，没有GAP Central设备与设备连接，就会收到这个消息。协议栈会在Slow advertising 开始之后自动停止广播，或者在Fast adverting超时后启动Slow adverting。

CYBLE_EVT_GAPP_ADVERTISEMENT_START_STOP（GAPP广播停止）:如果设备启动或停止广播的时候都会收到这个通知。可以使用CyBle_GetState() 函数判断当前状态（是启动还是停止）。如果返回的状态是CYBLE_STATE_DISCONNECTED，那么设备会启动连续广播。

参数：

参数是快速扫描或者慢速扫描，扫描间隔为GUI中设置的时间间隔。（有待补充）

返回值：

CYBLE_ERROR_OK ：成功

CYBLE_ERROR_INVALID_PARAMETER ：参数无效

此函数位于：BLE.h中。

2、BLE Core 函数

函数原型：

CYBLE_API_RESULT_T CyBle_Start(CYBLE_CALLBACK_T CyBleApplCbFunc);
描述：
这个函数初始化BLE协议栈，BLE协议栈包括了BLE协议栈管理器、BLE控制器和BLE主机模块。函数负责初始化Profile 层、调度器、定时器和其他BLE组件需要的平台相关的资源。函数同时还在协议栈中注册响应BLE事件的回调函数。

注意！这个函数并没有复位协议栈。

调用这个函数之后，如果初始化BLE协议栈成功，则会产生CYBLE_EVT_STACK_ON通知。

函数参数：

函数的参数是接收来自协议栈的通知的函数。

函数返回值：

CYBLE_ERROR_OK:执行成功。

CYBLE_ERROR_INVALID_PARAMETER:函数参数为空指针。

CYBLE_ERROR_REPEATED_ATTEMPTS:多次调用这个函数，并且中间没有调用过CyBle_Shutdow()函数。

函数原型：

void CyBle_Stop(void);

函数描述：

这个函数会停止蓝牙协议栈中的所有操作，并且强制蓝牙协议栈关闭。调用CyBle_Start()函数之后，唯一可以调用的函数。

函数原型：

void CyBle_WdtRegisterIsrCallback(CYBLE_WDT_ISR_CALLBACK_T WdtIsrApplCallback);

函数描述：

这个函数为WDT中断事件注册回调函数。

参数：

一个接收WDT中断事件的应用层的回调函数。

函数原型：

#define CyBle_GetState (cyBle_State)

描述：

这个函数用于判断事件处理状态机的当前状态。

函数原型：

CYBLE_BLESS_STATE_T CyBle_GetBleSsState(void);

函数描述：

这个函数用于获取BLE子系统当前的运作模式。可以根据返回值管理系统级功耗模式。

返回值：

CYBLE_BLESS_STATE_T 类型的bleStateMode,可能值如下：

CYBLE_BLESS_STATE_ACTIVE: BLE子系统处于激活态，CPU可能处于激活模式或睡眠模式；

CYBLE_BLESS_STATE_SLEEP：BLE子系统处于睡眠态，CPU可能处于睡眠模式；

CYBLE_BLESS_STATE_ECO_ON：BLE子系统正在从深睡眠模式中唤醒，ECO启动，CPU可以转入深睡眠模式；

CYBLE_BLESS_STATE_STABLE：BLE子系统正在从深睡眠中唤醒，ECO已经稳定，CPU可以转入睡眠模式；

CYBLE_BLESS_STATE_DEEPSLEEP：BLE子系统处于深睡眠中，CPU可以转入深睡眠模式；

CYBLE_BLESS_STATE_HIBERNATE：BLE子系统正在冬眠，CPU可以进入深睡眠模式。

函数原型：

#define CyBle_SetState(state) (cyBle_state = (state))

函数描述：

用于设置事件程序状态机的状态。

函数原型：

CYBLE_API_RESULT_T CyBle_StoreAppData(uint8 * srcBuff, const uint8 destAddr[], uint32 buffLen, uint8 isForceWrite);

函数描述：

这个函数命令协议栈将应用程序特定数据备份到Flash里面。这个函数必须由应用程序调用，来备份应用程序指定的数据。如果函数没有被正确调用，那么重启之后数据将不可用。

函数参数：

uint8 isForceWrite ：如果这个参数是0，那么协议栈会检查Flash是否允许写入。

返回值：

成功或者Flash不允许写入。

函数原型：

CYBLE_API_RESULT_T CyBle_StoreBondingData(uint8 isForceWrite);

函数描述：

这个函数将新绑定的数据从RAM写到指定的Flash中（Flash地址可设定）。在写之前，函数会比较RAM和Flash中的数据。如果数据相同，则无需再写。调用一次，写Flash的一行（？），应用程序应该一直调用这个函数直到函数返回CYBLE_ERROR_OK。

参数：

是否强制写入。

返回值：

成功或者无权限写入。

副作用：

这个函数会自动修改设备的时钟设置。。。。这会影响设备中的大部分硬件。

函数原型

CYBLE_API_RESULT_T CyBle_StoreStackData(uint8 isForceWrite);

函数描述：

这个函数命令协议栈将内部RAM数据存储入Flash中。

参数：

isForceWrite  是否强制写入。

函数原型：

CYBLE_API_RESULT_T CyBle_SoftReset(void);

函数描述：

调用这个函数复位BLE协议栈，包括BLE子系统的硬件寄存器。BLE协议栈转入idle模式。如果蓝牙设备在传输数据过程中出现异常，可以使用这个函数复位协议栈。这是一个阻塞函数，不会产生任何事件。

函数返回值：

返回值表明函数执行成功或者失败。

函数原型：

CYBLE_LP_MODE_T CyBle_EnterLPM(CYBLE_LP_MODE_T pwrMode);

函数描述：

这个函数要求底层BLE模块，如BLE控制器、BLE主机协议栈和BLE协议栈管理器，进入低功耗模式。应用程序应该使用这个函数使BLE低功耗子系统进入低功耗模式。

BLE协议栈进入和退出低功耗模式基于它当前的状态，因此应用程序在让CPU或者外围设备进入低功耗模式的时候应该考虑BLE协议栈的低功耗状态。

这个函数尝试设置指定的低功耗模式，如果失败，则它会尝试高一级的低功耗模式。这是因为应用程序在没事做的时候总是尝试使用最低的功耗工作。

注意，在BLE子系统处于深度睡眠状态的时候，CPU无法获取BLE子系统的寄存器值。

BLE协议栈有4种低功耗模式：

1、激活；2、睡眠；3、深度睡眠（EOF关闭）；4、冬眠；

注意，某些特定条件可能会阻止BLE子系统进入指定的低功耗状态。

激活模式：

BLE子系统有三种子模式：

1、Idle；2、传输模式；3、接收模式；

这些模式能使用最大的功耗并且CPU能获取所有寄存器值。

睡眠模式：

链路层引擎和数字调制器的时钟是带开关的（？？？），外部晶体振荡器持续运行维护链路层的时序。如果设备正在接收或者发送数据，那么应用无法进入睡眠模式。

深度睡眠模式：

ECO停止工作，WCO用于维护链路层时序。为了减小泄露电流射频发送器中所有的调节器都关闭。这部分不太了解详细原理，有待补充。

函数原型：

CYBLE_LP_MODE_T CyBle_ExitLPM(void);

函数描述：

应用程序可以异步将BLE协议栈从低功耗模式中唤醒。唤醒操作并不是将整个芯片唤醒。这个函数阻塞式调用，当BLE协议栈从低功耗模式退出时，函数返回。调用此函数不会产生事件。如果BLE协议栈已经处于激活模式，调用这个函数不会有任何作用。

返回值：

函数返回值为BLE协议栈当前处于的功耗模式，期望值为激活模式。

函数原型：

void CyBle_ProcessEvents(void);

函数描述：
这个函数检查在BLE协议栈中排队的内部任务，如果有任务在等待的话，挂起BLE协议栈的操作。这个函数在每个‘t'间隔期间至少被调用一次，t为：

1、连接间隔或扫描间隔中较小的。。。待补充

函数原型：

CYBLE_API_RESULT_T CyBle_GetDeviceAddress(CYBLE_GAP_BD_ADDR_T* bdAddr);

函数描述：

这个API从BLE控制器的内存中读取BD设备的地址。除非BLE主机明令指出，否则这个地址应该用于BLE程序？？这是一个阻塞函数，读到需要的值后它才立即返回。

函数原型：

CYBLE_API_RESULT_T CyBle_SetDeviceAddress(CYBLE_GAP_BD_ADDR_T* bdAddr);

函数描述：

这个函数将蓝牙设备地址写入BLE控制器的内存中。（此处有一句不太理解）。应用程序应该在每次改变蓝牙地址的时候调用这个函数。在蓝牙4.1核心规范中指出，蓝牙设备可以周期性的改变它私有的地址，而这个周期可以软件设定。并且对这个周期没有任何限制，应用层应该维护它的定时器已实现这个功能。

这是一个阻塞函数，且调用的时候不会产生任何事件。

函数原型：

int8 CyBle_GetRssi(void);

函数描述：

这个函数从BLE射频子系统中读取最后一次成功接收数据包的RSSI值。阻塞函数，无事件产生。

RSSI为： 接收信号强度指示值 ，范围在-85到5之间，单位dBm

函数原型：

CYBLE_API_RESULT_T CyBle_GetTxPowerLevel(CYBLE_BLESS_PWR_IN_DB_T * bleSsPwrLvl);

函数描述：

这个函数读取BLE射频的传输功耗。