賽普拉斯藍牙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射頻的傳輸功耗。