01

前言

本文檔指導用戶快速地對 BlueNRG SDK 有一個直觀、清晰的認識,了解其軟件架構，以便順利地學會利用 SDK 開發自己的用戶固件。

本文檔所述 SDK 為 BlueNRG-LP/LPS 芯片的 SDK。閱讀本文檔前，用戶應先了解BlueNRG-LP/LPS 芯片的一些基本特性，以及其配套開發板的燒錄方式。

02

SDK 目錄

從 ST 官網下載 SDK 的安裝包，成功安裝后，即可獲得一個 SDK 目錄。見圖 1：

圖1.SDK 目錄

各個目錄的功能說明見表 1：

表1. SDK 目錄說明

BlueNRG SDK 安裝目錄為用戶工程師開發 BlueNRG 平臺提供了一個便捷的入口，舉例來說，有以下幾個場景：

1. 硬件工程師設計 PCB 前，可通過 Docs 目錄找到硬件設計指導文檔。完成 PCBA 制作后，可自行使用 Navigator 工具通過串口燒錄 Firmware 下的應用固件，驗證板子功能。

2. 當工程師想用板子進行功耗、射頻測試時，也可在 Firmware 目錄下找到合適的已經編譯好的固件（測 SOC 藍牙功耗可用 Beacon，測射頻參數可用 DTM）

3. 固件工程師可在 Projects 目錄下找到豐富的例程，并且可使用 KEIL、IAR、WiSE 任一個IDE 打開工程、編譯、下載。

03

SDK 例程

SDK Projects 目錄包含了以下三類例程：

1. Periph_Examples：包含了芯片外設驅動例程。

2. External_Micro ：包含了外部單片機的例程，應用于 BlueNRG 芯片在系統中作為協處理器的場景。

3. BLE_Examples ：包含了藍牙相關的所有例程，這些例程的工程特性展示如下：

表2. BLE 例程說明

04

快速實現用戶固件功能

本章節指導用戶如何快速地在 SDK 中找到相應的 API 接口和位置，以便掌握在 SDK 例程上添加自己的配置和用戶邏輯代碼的方式。

在對 SDK 提供的例程的功能有所了解之后，假設用戶面臨的一個開發任務是：

1. BLE 從機功能，包含以下配置：

a. 一個服務，一個特征，特征具備 Write、Notify 屬性

b. 設備廣播名為“Hello”

2. 使用手機 BLE 工具和設備通訊，打印通訊過程產生的數據

3. 自定義協議，實現以下功能：

a. 控制 LED 亮滅

b. 定時 1s 上傳心跳包，內容為連接后的秒計數值

c. 每次按鍵上傳按鍵事件通知

基于以上任務，我們可以選擇 BLE_SerialPort 工程作為基礎工程并以此來進行固件開發。

4.1. 驗證原始工程

在添加用戶代碼之前，我們最好先驗證了原始工程（BLE_SerialPort）的功能，確保開發環境正常。新建一個用戶工程目錄，比如，test_sdk1.3.0，然后從 SDK 目錄拷貝以下文件到我們的用戶工程目錄，見圖 2：

圖2.用戶工程目錄

打開 Projects > BLE_SerialPort 的 Keil 工程，勾選“Browse Information”選項，以便使能工程內函數的跳轉，同時選中 Server 工程配置，見圖 3，圖 4：

圖3.Browse Information

圖4.選中 Server 工程配置

編譯、下載工程到開發板，工程運行起來后，應能見到以下打印信息：

圖5.BLE_SerialPort 工程 LOG 信息

使用 STBLE Toolbox 工具掃描該設備，應能看到設備名為“Sport_LP”，見圖 6：

圖6.STBLE Toolbox 掃描頁面

至此，原始工程已經正常運行起來了。該工程實現了自定義服務、特征的功能，并能通過串口和手機進行數據的收發。要完成此次開發任務，我們只需在特定位置修改一些代碼即可。

4.2. 配置 BLE 從機功能

原始工程有兩個特征，一個負責發（TX_CHR_UUID），一個負責收（RX_CHR_UUID）。按照要求，我們需要把他們合并為一個可以收、發的特征。圖 6 演示了定義新的特征 UUID 并注釋掉舊的兩個特征 UUID 的方式：

圖7.特征 UUID

協議棧提供了 ble_gatt_chr_def_t 類型結構體，用戶可以定義一個結構體變量并賦值，以此來聲明一個特征。圖 7 展示了我們所需的特征配置的相關賦值過程，圖中可見特征的 UUID 聲明，特征 notify、write 屬性聲明，特征的特征描述符聲明等信息。另外，舊的兩個特征應該注釋掉。

圖8.定義特征

將新的特征配置賦值給服務聲明，特征的數量修改為 1 個：

圖9.特征聲明賦值給服務聲明

上述服務、特征相關的數據結構配置完畢，我們還需要將這些配置通過 API 傳遞給協議棧。

首先，需要先定義一個新的句柄，所謂句柄，簡單地說，用戶在進行數據收發的時候，需要選擇在哪個特征上進行數據收發，此時便需要句柄來指定特征（句柄本質上便是 attribute 的handle 字段）。原來的兩個句柄也要注釋掉，見圖 10

圖10. 句柄

然后，將上文定義好的服務、特征通過 aci_gatt_srv_add_service 函數一次性傳送給協議棧，協議棧對這些配置進行解析、構建完整的 ATT 屬性表，保存在內存中。之后，用戶可使用aci_gatt_srv_get_char_decl_handle 接口獲取已分配好的句柄（見圖 11），此后的數據交互過程將頻繁使用該句柄。

圖11. 獲取句柄

至此，GATT 相關的配置已經完成。但是，由于上層大量引用了舊的兩個句柄進行數據收發，因此此時編譯會出現比較多的錯誤，此處暫不處理這些錯誤，先完成其他的 BLE 配置。

接下來修改藍牙地址，并修改廣播名，見圖 12：

圖12. 藍牙地址和廣播名

廣播名的長度改變后，應注意指定其長度：

圖13. 廣播名長度

LOCAL_NAME 設置的是廣播包里的設備名，當設備連接成功后，主機會從 GAP Profile 的device name 特征里獲取另外一個設備名，此處應保持這兩個名字一致：

圖14. 設備名

圖15. 設置設備名

至此，關于藍牙的應用配置即告完畢。接下來可進行數據通訊相關的配置、實現。

4.3.和手機進行通訊

上一小節配置完從機功能后，編譯會產生大量錯誤，是因為 BLE 的通訊過程會比較多地引用舊的句柄。循著解決這些編譯錯誤的操作，我們能了解到 BLE 通訊的過程。具體操作如下：

全局搜索舊的發送句柄（TXCharHanlde），我們找到了用于數據發送的協議棧 API，修正之 :

圖16. 發送 Notify

手機使能訂閱后，會通過圖 17 的回調函數通知上層。此時應該修改為新的特征句柄，同時，添加一些打印指示 notify 的使能、禁用狀態：

圖17. 使能訂閱回調

添加新的特征句柄全局變量聲明，注釋掉舊的：

圖18. 句柄聲明

關于舊的發送句柄（TXCharHanlde）的問題已經全部解決。繼續搜索舊的接收句柄（RXCharHanlde），我們應能找到設備接收手機數據的函數接口，將其中的句柄替換為新的特征句柄，見圖 19：

圖19. 數據接收回調函數

至此，我們應該能通過全部編譯過程，并且已經找到了數據發送、接收的位置。此時可以在這些位置添加數據發送、接收的打印函數。接收數據的用戶接口見圖 20：

圖20. 用戶接收 BLE 數據

關于發送數據，原始工程實現了以下處理流程：

1. 從串口接收數據

2. 解析數據為命令并緩存這些命令

3. 通過輪詢的方式，不斷將命令緩沖區里的命令發送出去

該處理流程不適用于我們的任務要求，我們需要先取消這部分功能，見圖 21

圖21. 取消原有的數據處理流程

然后設計自己的發送函數，見圖 22：

圖22. 自定義 BLE 數據發送函數

至此，藍牙的通訊功能已經全部實現完畢。用戶可通過：

? Data_Received()接口接收數據

? user_send_data_over_ble()接口發送數據

4.4.添加其它功能

根據任務要求，我們還需實現下面三個功能：

1. 控制 LED 亮滅

2. 定時 1s 上傳心跳包，內容為連接后的秒計數值

3. 每次按鍵上傳按鍵事件通知下面開始逐個實現：

4.4.1. 控制 LED 亮滅

首先，實現 LED 亮滅處理函數，

圖23. LED 命令處理函數

將其添加到 BLE 數據接收函數處，見圖 24。LED 控制功能實現完畢。

圖24. 接收數據后進行 LED 命令處理

4.4.2. 每秒上傳心跳包

首先，實現心跳上傳處理函數，實現當設備連接后，每秒上傳一個 4 字節的計數值，并使用0xaa 作為命令字。見圖 25：

圖25. 心跳上傳處理

將心跳處理函數添加到系統任務處理函數 App_Tick 中，App_Tick 會在 main loop 中不斷地被調用。心跳包需要在藍牙連接成功并且使能了訂閱之后才可以發送。另外，使用 timeout_flag變量來控制其每秒只被調用一次，實現方法如下：

圖26. 心跳處理

上述 timeout_flag 變量需要使用每秒循環的軟件定時器來周期性置位。軟件定時器的應用方式很簡單。

首先，實例化一個定時器，并定義超時回調函數：

圖27. 軟件定時器實例化

然后，在 Serial_port_DeviceInit 函數的末端位置注冊超時回調函數并啟動定時器。

圖28. 啟動定時器

4.4.3. 上傳按鍵事件

首先，實現按鍵回調函數，該函數在按鍵按下時被調用。發送按鍵事件前，應檢查此時藍牙是否處理連接、已訂閱狀態。見圖 29：

圖29. 按鍵回調

按鍵中斷服務函數中調用：

圖30. 按鍵中斷服務函數

至此，開發任務的要求已經全部實現完畢。接下來進行功能驗證。

4.5.驗證功能

用戶工程運行起來后，用 STBLE Toolbox 掃描，可見廣播名已經修改過來了。

圖31. 用戶工程廣播名

連上設備并點擊 Notify 開關以使能訂閱，可觀察到底部已經開始接收到設備的心跳包數據（以 AA 開頭的 5 字節數據），該數據每秒鐘變化一次，見圖 32：

圖32. 使能訂閱

通過 LOG 也能觀察到心跳包發送情況，此時如果按動按鍵，也能觀察到按鍵事件已經發送：

圖33. 用戶工程 LOG

05

小結

跑完了上述用戶任務開發的流程后，相信用戶對 BlueNRG SDK 的軟件架構應有所理解了。BlueNRG SDK 的軟件層次架構為 STM32 典型的三層架構，分別為驅動層、中間層、用戶層：

圖34. 軟件層次架構

上述添加用戶功能的整個過程，其實只改動到了用戶層的功能，用戶層包含以下幾個文件：

圖35. 用戶層文件

這些文件的含義是：

? serial_port.c，用戶應用邏輯的實現

? BLE_SerialPort_main.c，程序入口，程序主流程

? gatt_db.c，BLE GATT 層功能的實現

? rf_device_it.c，存放所有的中斷服務函數

上述用戶固件的功能，大多都在 serial_port.c 中實現。BLE_SerialPort_main.c 函數則實現了系統的主要流程。簡單來說，BlueNRG SDK 的裸機系統即是一個前后臺系統。藍牙事件、按鍵中斷等屬于前臺處理，負責置位相關標志位和狀態，main 函數的 while1 屬于后臺處理，運行藍牙協議棧、用戶任務處理等后臺任務，見圖 36：

圖36. 系統流程

BlueNRG SDK 中的絕大多數例程都使用了本文檔所述的軟件架構，即前后臺系統。該軟件架構比較簡單，優點是用戶能非常快速地掌握其流程，能夠依據本文檔的示例快速構建自己的用戶功能。缺點是功能比較簡單，用戶需要在此基礎上再添加一個調度器以應對復雜功能的要求。

審核編輯：劉清