雅特力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字段找到所需的部份。可以轻松修改报告映像以包含不同的输入或修改已经存在的输入，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、物联网、消费、商务及工控等领域。