01

前言

本文檔指導(dǎo)用戶(hù)快速地對(duì) BlueNRG SDK 有一個(gè)直觀、清晰的認(rèn)識(shí),了解其軟件架構(gòu)，以便順利地學(xué)會(huì)利用 SDK 開(kāi)發(fā)自己的用戶(hù)固件。

本文檔所述 SDK 為 BlueNRG-LP/LPS 芯片的 SDK。閱讀本文檔前，用戶(hù)應(yīng)先了解BlueNRG-LP/LPS 芯片的一些基本特性，以及其配套開(kāi)發(fā)板的燒錄方式。

02

SDK 目錄

從 ST 官網(wǎng)下載 SDK 的安裝包，成功安裝后，即可獲得一個(gè) SDK 目錄。見(jiàn)圖 1：

圖1.SDK 目錄

各個(gè)目錄的功能說(shuō)明見(jiàn)表 1：

表1. SDK 目錄說(shuō)明

BlueNRG SDK 安裝目錄為用戶(hù)工程師開(kāi)發(fā) BlueNRG 平臺(tái)提供了一個(gè)便捷的入口，舉例來(lái)說(shuō)，有以下幾個(gè)場(chǎng)景：

1. 硬件工程師設(shè)計(jì) PCB 前，可通過(guò) Docs 目錄找到硬件設(shè)計(jì)指導(dǎo)文檔。完成 PCBA 制作后，可自行使用 Navigator 工具通過(guò)串口燒錄 Firmware 下的應(yīng)用固件，驗(yàn)證板子功能。

2. 當(dāng)工程師想用板子進(jìn)行功耗、射頻測(cè)試時(shí)，也可在 Firmware 目錄下找到合適的已經(jīng)編譯好的固件（測(cè) SOC 藍(lán)牙功耗可用 Beacon，測(cè)射頻參數(shù)可用 DTM）

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

03

SDK 例程

SDK Projects 目錄包含了以下三類(lèi)例程：

1. Periph_Examples：包含了芯片外設(shè)驅(qū)動(dòng)例程。

2. External_Micro ：包含了外部單片機(jī)的例程，應(yīng)用于 BlueNRG 芯片在系統(tǒng)中作為協(xié)處理器的場(chǎng)景。

3. BLE_Examples ：包含了藍(lán)牙相關(guān)的所有例程，這些例程的工程特性展示如下：

表2. BLE 例程說(shuō)明

04

快速實(shí)現(xiàn)用戶(hù)固件功能

本章節(jié)指導(dǎo)用戶(hù)如何快速地在 SDK 中找到相應(yīng)的 API 接口和位置，以便掌握在 SDK 例程上添加自己的配置和用戶(hù)邏輯代碼的方式。

在對(duì) SDK 提供的例程的功能有所了解之后，假設(shè)用戶(hù)面臨的一個(gè)開(kāi)發(fā)任務(wù)是：

1. BLE 從機(jī)功能，包含以下配置：

a. 一個(gè)服務(wù)，一個(gè)特征，特征具備 Write、Notify 屬性

b. 設(shè)備廣播名為“Hello”

2. 使用手機(jī) BLE 工具和設(shè)備通訊，打印通訊過(guò)程產(chǎn)生的數(shù)據(jù)

3. 自定義協(xié)議，實(shí)現(xiàn)以下功能：

a. 控制 LED 亮滅

b. 定時(shí) 1s 上傳心跳包，內(nèi)容為連接后的秒計(jì)數(shù)值

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

基于以上任務(wù)，我們可以選擇 BLE_SerialPort 工程作為基礎(chǔ)工程并以此來(lái)進(jìn)行固件開(kāi)發(fā)。

4.1. 驗(yàn)證原始工程

在添加用戶(hù)代碼之前，我們最好先驗(yàn)證了原始工程（BLE_SerialPort）的功能，確保開(kāi)發(fā)環(huán)境正常。新建一個(gè)用戶(hù)工程目錄，比如，test_sdk1.3.0，然后從 SDK 目錄拷貝以下文件到我們的用戶(hù)工程目錄，見(jiàn)圖 2：

圖2.用戶(hù)工程目錄

打開(kāi) Projects > BLE_SerialPort 的 Keil 工程，勾選“Browse Information”選項(xiàng)，以便使能工程內(nèi)函數(shù)的跳轉(zhuǎn)，同時(shí)選中 Server 工程配置，見(jiàn)圖 3，圖 4：

圖3.Browse Information

圖4.選中 Server 工程配置

編譯、下載工程到開(kāi)發(fā)板，工程運(yùn)行起來(lái)后，應(yīng)能見(jiàn)到以下打印信息：

圖5.BLE_SerialPort 工程 LOG 信息

使用 STBLE Toolbox 工具掃描該設(shè)備，應(yīng)能看到設(shè)備名為“Sport_LP”，見(jiàn)圖 6：

圖6.STBLE Toolbox 掃描頁(yè)面

至此，原始工程已經(jīng)正常運(yùn)行起來(lái)了。該工程實(shí)現(xiàn)了自定義服務(wù)、特征的功能，并能通過(guò)串口和手機(jī)進(jìn)行數(shù)據(jù)的收發(fā)。要完成此次開(kāi)發(fā)任務(wù)，我們只需在特定位置修改一些代碼即可。

4.2. 配置 BLE 從機(jī)功能

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

圖7.特征 UUID

協(xié)議棧提供了 ble_gatt_chr_def_t 類(lèi)型結(jié)構(gòu)體，用戶(hù)可以定義一個(gè)結(jié)構(gòu)體變量并賦值，以此來(lái)聲明一個(gè)特征。圖 7 展示了我們所需的特征配置的相關(guān)賦值過(guò)程，圖中可見(jiàn)特征的 UUID 聲明，特征 notify、write 屬性聲明，特征的特征描述符聲明等信息。另外，舊的兩個(gè)特征應(yīng)該注釋掉。

圖8.定義特征

將新的特征配置賦值給服務(wù)聲明，特征的數(shù)量修改為 1 個(gè)：

圖9.特征聲明賦值給服務(wù)聲明

上述服務(wù)、特征相關(guān)的數(shù)據(jù)結(jié)構(gòu)配置完畢，我們還需要將這些配置通過(guò) API 傳遞給協(xié)議棧。

首先，需要先定義一個(gè)新的句柄，所謂句柄，簡(jiǎn)單地說(shuō)，用戶(hù)在進(jìn)行數(shù)據(jù)收發(fā)的時(shí)候，需要選擇在哪個(gè)特征上進(jìn)行數(shù)據(jù)收發(fā)，此時(shí)便需要句柄來(lái)指定特征（句柄本質(zhì)上便是 attribute 的handle 字段）。原來(lái)的兩個(gè)句柄也要注釋掉，見(jiàn)圖 10

圖10. 句柄

然后，將上文定義好的服務(wù)、特征通過(guò) aci_gatt_srv_add_service 函數(shù)一次性傳送給協(xié)議棧，協(xié)議棧對(duì)這些配置進(jìn)行解析、構(gòu)建完整的 ATT 屬性表，保存在內(nèi)存中。之后，用戶(hù)可使用aci_gatt_srv_get_char_decl_handle 接口獲取已分配好的句柄（見(jiàn)圖 11），此后的數(shù)據(jù)交互過(guò)程將頻繁使用該句柄。

圖11. 獲取句柄

至此，GATT 相關(guān)的配置已經(jīng)完成。但是，由于上層大量引用了舊的兩個(gè)句柄進(jìn)行數(shù)據(jù)收發(fā)，因此此時(shí)編譯會(huì)出現(xiàn)比較多的錯(cuò)誤，此處暫不處理這些錯(cuò)誤，先完成其他的 BLE 配置。

接下來(lái)修改藍(lán)牙地址，并修改廣播名，見(jiàn)圖 12：

圖12. 藍(lán)牙地址和廣播名

廣播名的長(zhǎng)度改變后，應(yīng)注意指定其長(zhǎng)度：

圖13. 廣播名長(zhǎng)度

LOCAL_NAME 設(shè)置的是廣播包里的設(shè)備名，當(dāng)設(shè)備連接成功后，主機(jī)會(huì)從 GAP Profile 的device name 特征里獲取另外一個(gè)設(shè)備名，此處應(yīng)保持這兩個(gè)名字一致：

圖14. 設(shè)備名

圖15. 設(shè)置設(shè)備名

至此，關(guān)于藍(lán)牙的應(yīng)用配置即告完畢。接下來(lái)可進(jìn)行數(shù)據(jù)通訊相關(guān)的配置、實(shí)現(xiàn)。

4.3.和手機(jī)進(jìn)行通訊

上一小節(jié)配置完從機(jī)功能后，編譯會(huì)產(chǎn)生大量錯(cuò)誤，是因?yàn)?BLE 的通訊過(guò)程會(huì)比較多地引用舊的句柄。循著解決這些編譯錯(cuò)誤的操作，我們能了解到 BLE 通訊的過(guò)程。具體操作如下：

全局搜索舊的發(fā)送句柄（TXCharHanlde），我們找到了用于數(shù)據(jù)發(fā)送的協(xié)議棧 API，修正之 :

圖16. 發(fā)送 Notify

手機(jī)使能訂閱后，會(huì)通過(guò)圖 17 的回調(diào)函數(shù)通知上層。此時(shí)應(yīng)該修改為新的特征句柄，同時(shí)，添加一些打印指示 notify 的使能、禁用狀態(tài)：

圖17. 使能訂閱回調(diào)

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

圖18. 句柄聲明

關(guān)于舊的發(fā)送句柄（TXCharHanlde）的問(wèn)題已經(jīng)全部解決。繼續(xù)搜索舊的接收句柄（RXCharHanlde），我們應(yīng)能找到設(shè)備接收手機(jī)數(shù)據(jù)的函數(shù)接口，將其中的句柄替換為新的特征句柄，見(jiàn)圖 19：

圖19. 數(shù)據(jù)接收回調(diào)函數(shù)

至此，我們應(yīng)該能通過(guò)全部編譯過(guò)程，并且已經(jīng)找到了數(shù)據(jù)發(fā)送、接收的位置。此時(shí)可以在這些位置添加數(shù)據(jù)發(fā)送、接收的打印函數(shù)。接收數(shù)據(jù)的用戶(hù)接口見(jiàn)圖 20：

圖20. 用戶(hù)接收 BLE 數(shù)據(jù)

關(guān)于發(fā)送數(shù)據(jù)，原始工程實(shí)現(xiàn)了以下處理流程：

1. 從串口接收數(shù)據(jù)

2. 解析數(shù)據(jù)為命令并緩存這些命令

3. 通過(guò)輪詢(xún)的方式，不斷將命令緩沖區(qū)里的命令發(fā)送出去

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

圖21. 取消原有的數(shù)據(jù)處理流程

然后設(shè)計(jì)自己的發(fā)送函數(shù)，見(jiàn)圖 22：

圖22. 自定義 BLE 數(shù)據(jù)發(fā)送函數(shù)

至此，藍(lán)牙的通訊功能已經(jīng)全部實(shí)現(xiàn)完畢。用戶(hù)可通過(guò)：

? Data_Received()接口接收數(shù)據(jù)

? user_send_data_over_ble()接口發(fā)送數(shù)據(jù)

4.4.添加其它功能

根據(jù)任務(wù)要求，我們還需實(shí)現(xiàn)下面三個(gè)功能：

1. 控制 LED 亮滅

2. 定時(shí) 1s 上傳心跳包，內(nèi)容為連接后的秒計(jì)數(shù)值

3. 每次按鍵上傳按鍵事件通知下面開(kāi)始逐個(gè)實(shí)現(xiàn)：

4.4.1. 控制 LED 亮滅

首先，實(shí)現(xiàn) LED 亮滅處理函數(shù)，

圖23. LED 命令處理函數(shù)

將其添加到 BLE 數(shù)據(jù)接收函數(shù)處，見(jiàn)圖 24。LED 控制功能實(shí)現(xiàn)完畢。

圖24. 接收數(shù)據(jù)后進(jìn)行 LED 命令處理

4.4.2. 每秒上傳心跳包

首先，實(shí)現(xiàn)心跳上傳處理函數(shù)，實(shí)現(xiàn)當(dāng)設(shè)備連接后，每秒上傳一個(gè) 4 字節(jié)的計(jì)數(shù)值，并使用0xaa 作為命令字。見(jiàn)圖 25：

圖25. 心跳上傳處理

將心跳處理函數(shù)添加到系統(tǒng)任務(wù)處理函數(shù) App_Tick 中，App_Tick 會(huì)在 main loop 中不斷地被調(diào)用。心跳包需要在藍(lán)牙連接成功并且使能了訂閱之后才可以發(fā)送。另外，使用 timeout_flag變量來(lái)控制其每秒只被調(diào)用一次，實(shí)現(xiàn)方法如下：

圖26. 心跳處理

上述 timeout_flag 變量需要使用每秒循環(huán)的軟件定時(shí)器來(lái)周期性置位。軟件定時(shí)器的應(yīng)用方式很簡(jiǎn)單。

首先，實(shí)例化一個(gè)定時(shí)器，并定義超時(shí)回調(diào)函數(shù)：

圖27. 軟件定時(shí)器實(shí)例化

然后，在 Serial_port_DeviceInit 函數(shù)的末端位置注冊(cè)超時(shí)回調(diào)函數(shù)并啟動(dòng)定時(shí)器。

圖28. 啟動(dòng)定時(shí)器

4.4.3. 上傳按鍵事件

首先，實(shí)現(xiàn)按鍵回調(diào)函數(shù)，該函數(shù)在按鍵按下時(shí)被調(diào)用。發(fā)送按鍵事件前，應(yīng)檢查此時(shí)藍(lán)牙是否處理連接、已訂閱狀態(tài)。見(jiàn)圖 29：

圖29. 按鍵回調(diào)

按鍵中斷服務(wù)函數(shù)中調(diào)用：

圖30. 按鍵中斷服務(wù)函數(shù)

至此，開(kāi)發(fā)任務(wù)的要求已經(jīng)全部實(shí)現(xiàn)完畢。接下來(lái)進(jìn)行功能驗(yàn)證。

4.5.驗(yàn)證功能

用戶(hù)工程運(yùn)行起來(lái)后，用 STBLE Toolbox 掃描，可見(jiàn)廣播名已經(jīng)修改過(guò)來(lái)了。

圖31. 用戶(hù)工程廣播名

連上設(shè)備并點(diǎn)擊 Notify 開(kāi)關(guān)以使能訂閱，可觀察到底部已經(jīng)開(kāi)始接收到設(shè)備的心跳包數(shù)據(jù)（以 AA 開(kāi)頭的 5 字節(jié)數(shù)據(jù)），該數(shù)據(jù)每秒鐘變化一次，見(jiàn)圖 32：

圖32. 使能訂閱

通過(guò) LOG 也能觀察到心跳包發(fā)送情況，此時(shí)如果按動(dòng)按鍵，也能觀察到按鍵事件已經(jīng)發(fā)送：

圖33. 用戶(hù)工程 LOG

05

小結(jié)

跑完了上述用戶(hù)任務(wù)開(kāi)發(fā)的流程后，相信用戶(hù)對(duì) BlueNRG SDK 的軟件架構(gòu)應(yīng)有所理解了。BlueNRG SDK 的軟件層次架構(gòu)為 STM32 典型的三層架構(gòu)，分別為驅(qū)動(dòng)層、中間層、用戶(hù)層：

圖34. 軟件層次架構(gòu)

上述添加用戶(hù)功能的整個(gè)過(guò)程，其實(shí)只改動(dòng)到了用戶(hù)層的功能，用戶(hù)層包含以下幾個(gè)文件：

圖35. 用戶(hù)層文件

這些文件的含義是：

? serial_port.c，用戶(hù)應(yīng)用邏輯的實(shí)現(xiàn)

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

? gatt_db.c，BLE GATT 層功能的實(shí)現(xiàn)

? rf_device_it.c，存放所有的中斷服務(wù)函數(shù)

上述用戶(hù)固件的功能，大多都在 serial_port.c 中實(shí)現(xiàn)。BLE_SerialPort_main.c 函數(shù)則實(shí)現(xiàn)了系統(tǒng)的主要流程。簡(jiǎn)單來(lái)說(shuō)，BlueNRG SDK 的裸機(jī)系統(tǒng)即是一個(gè)前后臺(tái)系統(tǒng)。藍(lán)牙事件、按鍵中斷等屬于前臺(tái)處理，負(fù)責(zé)置位相關(guān)標(biāo)志位和狀態(tài)，main 函數(shù)的 while1 屬于后臺(tái)處理，運(yùn)行藍(lán)牙協(xié)議棧、用戶(hù)任務(wù)處理等后臺(tái)任務(wù)，見(jiàn)圖 36：

圖36. 系統(tǒng)流程

BlueNRG SDK 中的絕大多數(shù)例程都使用了本文檔所述的軟件架構(gòu)，即前后臺(tái)系統(tǒng)。該軟件架構(gòu)比較簡(jiǎn)單，優(yōu)點(diǎn)是用戶(hù)能非常快速地掌握其流程，能夠依據(jù)本文檔的示例快速構(gòu)建自己的用戶(hù)功能。缺點(diǎn)是功能比較簡(jiǎn)單，用戶(hù)需要在此基礎(chǔ)上再添加一個(gè)調(diào)度器以應(yīng)對(duì)復(fù)雜功能的要求。

審核編輯：劉清