雅特力AT32 MCU HOGP開發指南

HOGP概述

HOGP(HID over GATT)是由Bluetooth SIG維護的藍牙配置文件規范，通過低功耗藍牙實現HID的配置文件并作為與計算器之間的接口，消除HID中對電線或物理連接的需求。

HID角色

在HID中，以及在HOGP的延伸中，定義了兩個角色，這些角色是HID主機和HID設備。HID設備一次只能主動連接到單個HID主機；然而一個HID主機可以連接到多個HID設備。有關主機和設備如何交互的細節，請參閱HOGP規范中的第3章HID設備需求和第4章HID主機需求和行為。

一、HID主機

HID主機實現藍牙GAP中的中心(Central)角色，接收輸入訊息并使用提供的數據進行更進一步的處理。例如，計算器會是HID主機，因為這是接收HID數據的設備。HID主機對HID功能的正確執行有許多責任與需求，但在此開發指南中所提供的范例僅實現了HID設備，因此本文檔不涉及這些內容。想要了解HID主機的職責和需求，請參閱HOGP規范中的第2章配置、第4章HID主機需求和行為、第5章連線建立。

二、HID設備HID設備實現藍牙GAP中的外設(Peripheral)角色，負責將輸入信息傳輸到中央計算器。例如，鼠標或鍵盤會是HID設備，因為它們將輸入數據發送到計算器設備。

Bluetooth Profile

要透過藍牙實現HID功能，那就必須要事先定義好規范，如此主機及裝置雙方才能夠順利通信，由于本開發指南是針對裝置的部份進行說明，故此處只列出裝置所需的服務。

表1. HID裝置的必須服務

這邊要注意到Device Information Service中的PnP特征，如果是開發一個標準的鍵盤或鼠標，請根據已經注冊的Vendor ID及Product ID填入其中。

例 HID裝置實做

HOGP 工程是一個在 AT32WB415 上實現 HOGP 規范的低功耗藍牙工程，該工程使用 HOGP 規范指定的藍牙外設角色，演示了 HOGP 的鍵盤及鼠標。通過使用通知(Notification)和 GATT 配置文件，該項目能夠通過低功耗藍牙 HID 裝置并與 HID 主機正確連接。HOGP 工程中有幾個復雜的部份，在本文檔中進行了討論，這些部份組合在一起以實現整體功能。

報告映射討論

HOGP工程依賴于報告映像，報告映射是HOGP用于實現低功耗藍牙HID功能的結構。報告映像用于告訴主機許要從HID設備獲得什么功能和什么樣的數據，在原始的HID USB規范中，報告映射稱為報告描述符，報告映射和報告描述符是相同的，它們之間唯一的區別是報告映射用于HOGP,報告描述符用于HID USB。該工程使用的報告映像可以在app_hid.c文件中找到，并且包含在gHIDReportDescriptor變量中，此工程中的報告映像包含鍵盤的輸入信息。該結構分為多個部份，應用程序以及HID主機能夠通過使用報告ID字段找到所需的部份?？梢暂p松修改報告映像以包含不同的輸入或修改已經存在的輸入，USB實現者論壇的設備工作組有一個報告描述符建構器工具，可以用于輕松創建報告映射。下面的程序代碼顯示了報告映像結構片段，所有字段都有標簽，可以輕松修改。例如，如果需要不同數量的鍵盤按鍵，則可以輕松修改相關字段。

• HID Report

修改裝置類型

只有當開發者正確地填入裝置類型參數，主機端才能顯示出合適的裝置圖標，即便在廣播的時候能夠正確辨識出裝置的類型，但如果沒有修改GAP中的Appearance數值，聯機后的裝置圖標依然會顯示異常，以下特別列出在開發時容易疏忽的地方：1. 廣播時的Appearance，主機掃描到時就會將裝置類型顯示出來，比如說鍵盤或是鼠標，在代碼中位于user_config.h里面的宏定義APP_HID_ADV_DATA_APPEARANCE, 0x03C2代表鼠標, 0x03C1代表鍵盤，更詳細的內容可以參考SIG的Spec.圖1. Appearance Part of ADV Data2.?聯機建立后，主機會來讀取裝置的GAP, 這個時候就會得到這個裝置是屬于哪一種類型，如果沒有正確填寫，在主機端的驅動安裝完成后，顯示的裝置類型會與預期的不同。這個部份的代碼位于app_task.c中的gapc_get_dev_info_req_ind_handler函式，代碼中已將鍵盤及鼠標的Appearance給定義起來，使用者可以依據需求擴充。圖2. GAP Client Gets Device Apperance3.?在新增HID Profile時，填入當前的應用類型，這位于app_hid.c中的app_hid_add_hids函式，使用者可以根據當前需求填入鍵盤或是鼠標的宏定義，但要記得一定要有Protocol Mode才能正常使用。圖3. GAP Client Gets Device Apperance

資源類型

1) 硬件環境:對應產品型號的AT-START BOARD2) 軟件環境wb415_hogp_bt_demo\projects\ble_app_remotewb415_hogp_mcu_demo\utilities\wb415_hogp_mcu_demo\mdk_v5

軟件設計

1) 配置流程a) MCU端

• 配置USER KEY作為擊鍵
• 編寫USART3通訊函數
• 輪詢USER KEY是否按下
• 根據需求去配置USER KEY按下后發出的AT command

b) BT端

• 將HOGP的Profile加入database
• 編寫應用層與GATT之間的界面
• 在應用層中輪詢AT command
• 透過HOGP將不同的key function發給host端

2) 代碼介紹a)MCU端

• main函數代碼描述

b)?BT端
原則上不需要去修改Profile層的內容，由APP層去設定HID裝置的內容即可

• 初始化HOGP裝置變量

• 將HOGP加入database
  

在main函數之中的while loop不斷輪詢app_user_entry()來確認有無收到AT command，如果收到有收到AT command則執行該命令的內容。

• 解析AT command并執行對應的程序

實驗效果

• 按下AT-START板上的USER KEY發送www back按鍵，則瀏覽器頁面返回上一頁
• 按下AT-START板上的USER KEY發送volume up按鍵，則音量提高（需要修改ATcommand）
• 按下AT-START板上的USER KEY發送volume down按鍵，則音量降低（需要修改AT command）

按鍵定義

本應用指南以多媒體按鍵為例，在代碼中定義了多媒體按鍵值的數組，用戶可以在app_key.c中找到以下代碼：

• 多媒體按鍵值定義

在app.c中的app_user_entry函數，每當添加一個新的按鍵實例，必須透過app_hid_send_report這個函數，將按鍵值及長度發送給主機端，主機才能根據按鍵值做出對應的行為；舉例來說，要發出降低音量的按鍵功能，從上面的注釋可以看到volume down對應到第九列，是整個數組的第18個數，因此調用發送函數時寫成app_hid_send_report(&key_copy[18], 2)，其他按鍵也是如此使用。

HOGP相關AT command

本應用指南中，已經建立部分的AT command，如下表：表2. HOGP相關AT command

用戶自行添加AT command時，需要在MCU端及BT端同時增加對應的實例；MCU端要在at_cmd.h中新增AT command的請求及期待的響應；BT端要在app.h中新增要解析的AT command字符串、command的枚舉以及回復的枚舉，數量上如果對不上的話則發出的按鍵功能可能會不正常。另外鼠目標AT command及位移都是填入Dummy Data, 使用者如果要反應真實的位移及實作按鍵、滾輪等功能，需要自己由傳感器讀取數據，并修改鼠標的AT command讓它可以攜帶真實參數，接收AT command的部份也要實做解析函數去取出AT command中的參數內容，并填入Notification之中。關于雅特力雅特力科技于2016年成立，是一家致力于推動全球市場32位微控制器(MCU)創新趨勢的芯片設計公司，專注于ARM Cortex-M4/M0+的32位微控制器研發與創新，全系列采用55nm先進工藝及ARM Cortex-M4高效能或M0+低功耗內核，締造M4業界最高主頻288MHz運算效能，并支持工業級別芯片工作溫度范圍（-40°~105°）。雅特力目前已累積相當多元的終端產品成功案例：如微型打印機、掃地機、光流無人機、熱成像儀、激光雷達、工業縫紉機、伺服驅控、電競周邊市場、斷路器、ADAS、T-BOX、數字電源、電動工具等終端設備應用，廣泛地覆蓋5G、物聯網、消費、商務及工控等領域。