AT32 HOGP开发指南

Terran

5 O! p5 i# j. k
AT32 HOGP开发指南
/ d* ?/ G) e5 L" ~
, m4 }1 U/ h% ^, n/ D& s前言
人机接口设备(Human InteRFace Devices, HID)的主要目的是基于USB实现者论坛所维护的规格书，提供用户与计算器之间的接口。HID涵盖了显示器、键盘、网络摄影机和鼠标甚至到VR耳机、游戏手把和触控屏幕的各种装置。HID传统上通过USB接口连接到计算器，然而，HID设备也可以通过使用无线技术与计算器连接。通过使用HID规范，可以开发出符合通用标准的计算器外设，从而与大多数装置兼容。
支持型号 列表：
5 V8 [7 @3 a( f; ~$ n; G8 o, x  H4 QAT32WB415

2 e2 j6 j# i4 B1 r7 p3 k4 Y* W1 HOGP概述
0 a. b4 n+ o# k% B8 r. c9 y! bHOGP(HID over GATT)是由Bluetooth SIG维护的蓝牙配置文件规范，通过低功耗蓝牙实现HID的配置文件并作为与计算器之间的接口，消除HID中对电线或物理连接的需求。
- C- W( z2 m9 k2 c  E
1.1 HID 角色
在HID 中，以及在 HOGP 的延伸中，定义了两个角色，这些角色是 HID 主机和 HID 设备。 HID 设备
4 r2 U. O; w) L8 p' p一次只能主动连接到单个 HID 主机；然而一个 HID 主机可以连接到多个 HID 设备。有关主机和设备
如何交互的细节，请参阅 HOGP 规范 中的第 3 章 HID 设备需求和第 4 章 HID 主机需求和行为。

1.2 HID 主机
  J" K8 Z  a) X6 YHID主机实现蓝牙 GAP 中的中心 ( 角色，接收输入讯息并使用提供的数据进行更进一步的处
理。例如，计算器会是 HID 主机，因为这是接收 HID 数据的设备。 HID 主机对 HID 功能的正确执行
有许多责任与需求，但在此开发指南中所提供的范例仅实现了 HID 设备，因此本文檔不涉及这些内
, A" H) F7 _: W9 U2 |$ t容。想要了解 HID 主机的职责和需求，请参阅 HOGP 规范中的第 2 章配置、第 4 章 HID 主机需求和
& e9 K' b+ X7 D& y; l行为、第 5 章连线建立。

1.3 HID 设备
HID设备实现蓝牙 GAP 中的外设 ( 角色，负责将输入信息传输到中央计算器。例如，鼠标
9 W, {& y8 g6 Y2 ~4 Q或键盘会是 HID 设备，因为它们将输入数据发送到计算器设备。
6 P9 S$ ~) @. K" l8 o
' B0 I! H: p  t- C: J! u4 Z
2 例 蓝牙键盘实做
HOGP工程是一个在 AT32WB415 上实现 HOGP 规范的低功耗蓝牙工程，该工程使用 HOGP 规范 指
定的 蓝牙 外设角色，演示了 HOGP 的键盘。通过使用通知 ( 和 GATT 配置文件，该项目能
2 u8 i( v, }8 Z够通过低功耗蓝牙 HID 装置并与 HID 主机正确连接。 HOGP 工程中有几个复杂的部份，在本文档中
) x$ A) S0 T6 g3 m. P, e进行了讨论，这些部份组合在一起以实现整体功能。

2.1 报告映射讨论
HOGP工程依赖于报告映像，报告映射是 HOGP 用于实现低功耗蓝牙 HID 功能的结构。报告映像用
于告诉主机许要从 HID 设备获得什么功能和什么样的数据，在原始的 HID USB 规范中，报告映射称
$ {. k9 r2 A* A: C; V; O/ D% s6 ^为报告描述符，报告映射和报告描述符是相同的，它们之间唯一的区别是报告映射用于 HOGP, 报告
描述符用于 HID USB 。
8 w5 L# L0 L  A" H4 o; H该工程使用的报告映像可以在
app_hid.c 文件中找到，并且包含在 gHIDReportDescriptor 变量中，此
8 m3 P+ T4 g, R5 p% c+ j工程中的报告映像包含键盘的输入信息。该结构分为多个部份，应用程序以及 HID 主机能够通过使用
# b# }" E  b! E* l1 c. r) C报告 ID 字段找到所需的部份。可以轻松修改报告映像以包含不同的输入或修改已经存在的输入，
: A. s. j  n5 N! oUSB 实现者论坛的设备工作组有一个报告描述符建构器工具，可以用于轻松创建报告映射。 图 3 显
2 m, G8 U  J, x7 F' O, o示了报告映像结构的片段，所有字段都有标签，可以轻松修改。例如，如果需要不同数量的键盘按
键，则可以轻松修改相关字段。
$ u# X3 A5 K! q5 Q: D  L% ]% a
2.2 资源准备
  S1 ?- K4 F9 G# D1 h6 p' \; V1) 硬件环境:
* h& A& R  \1 H; m8 ^. V# a& X" i' R对应产品型号的AT-START BOARD
$ f  S3 ^1 W# L, @5 K6 Y/ ?; I2) 软件环境
- Y0 e/ l4 m2 U  I" Dwb415_hogp_bt_demo\projects\ble_app_remote
wb415_hogp_mcu_demo\utilities\wb415_hogp_mcu_demo\mdk_v5
* p4 u3 U( ?4 j1 E
2 l: y8 I0 z1 A* C  ]2.3 软件设计
  Z( S; R5 _, ^( q5 e1) 配置流程
a) MCU端
6 }* d. W; K1 `# D 配置USER KEY作为击键
' h  E- g; _9 A8 e3 T& |# i  ~ 编写USART3通讯函数
1 n. M" h" p2 W9 `+ L6 T6 B  e 轮询USER KEY是否按下
 根据需求去配置USER KEY按下后发出的AT command
b) BT端
 将HOGP的Profile加入database
 编写应用层与GATT之间的界面
3 I+ @- f2 d* c9 [; z, s% T% G+ t8 M4 P' h 在应用层中轮询AT command
. k; t  o! S+ \& w 透过HOGP将不同的key function发给host端
2) 代码介绍
. A  C  X1 h" l MCU端
4 _: K; A, Q( s, o main函数代码描述
( M3 P! I7 u& J9 l; o

• int main(void)
• {
• gpio_init_type gpio_init_struct;
• #ifdef BT_FLASH_WR_TEST
• uint8_t data;
• #endif
• /* 配置系统时钟 */
• system_clock_config();
• /* 初始化开发板资源 */
• at32_board_init();
• /* 初始化USER Key */
• at32_button_init();
• ....
  2 E7 T2 J4 m6 L- P: q

, K& K+ Y3 _$ b( b' Z7 ]+ @1 h BT端
原则上不需要去修改Profile层的内容，由APP层去设定HID装置的内容即可
- l. }/ I! C+ X4 ], l8 ~% x5 V" L3 T 初始化HOGP装置变量
" c1 \0 {) ^3 W" A! O' a! K

• void app_hid_init(void)
• {
• // Reset the environment
• memset(&app_hid_env, 0, sizeof(app_hid_env));
• app_hid_env.state = APP_HID_IDLE;
• app_hid_set_send_flag(true);
• }
  6 C/ I* C+ s. ?1 Y3 g& _

 将HOGP加入database
# Y6 ^- t3 |9 S% J

• void app_hid_add_hids(void)
• {
• struct hogpd_db_cfg *db_cfg;
• // Prepare the HOGPD_CREATE_DB_REQ message
• struct gapm_profile_task_add_cmd *req = KE_MSG_ALLOC_DYN(GAPM_PROFILE_TASK_ADD_CMD,
• TASK_GAPM, TASK_APP,
• gapm_profile_task_add_cmd, sizeof(struct hogpd_db_cfg));
• // Fill message
• req->operation = GAPM_PROFILE_TASK_ADD;
• req->sec_lvl = 0;
• req->prf_task_id = TASK_ID_HOGPD;
• req->app_task = TASK_APP;
• req->start_hdl = 0;
• ....
  

在main函数之中的while loop不断轮询app_user_entry()来确认有无收到AT command，如果收到有收到AT command则执行该命令的内容。
! `9 {" f2 G: C" D5 F; T* ] 解析AT command并执行对应的程序

• void app_user_entry(void)
• {
• uint8_t without_prefix_len;
• // GPIO_int_enable();
• if (ke_state_get(TASK_APP) == APPM_READY)
• {
• UART_PRINTF("start advertising\r\n");
• appm_start_advertising();
• }
• ....
  3 |6 ^$ q3 G& s, X# ^& [9 h/ f1 l

0 T& l6 p! O8 u; Q4 T2.4 实验效果
) l1 i7 U$ b% ?" E+ A% o 按下AT-START板上的USER KEY发送www back按键，则浏览器页面返回上一页
 按下AT-START板上的USER KEY发送volume up按键，则音量提高（需要修改AT command）
8 \9 ?- ]8 m6 c! c/ }4 T) }' A 按下AT-START板上的USER KEY发送volume down按键，则音量降低（需要修改AT command）

2.5 按键定义
% U5 K" q& T( Y% n$ A' @, d3 D本应用指南以多媒体按键为例，在代码中定义了多媒体按键值的数组，用户可以在app_key.c 中找到以下代码：
9 z. y$ q- A( K9 P
: v; [& K, ~2 G6 A# b( i 多媒体按键值定义
+ S# L% U* m1 ], v2 m, t* G( X: A

• const uint8_t media_key[47][2] =
• {
• {0x24, 0x02}, // WWW back 0
• {0x25, 0x02}, // WWW forward 1
• {0x26, 0x02}, // WWW Stop 2
• {0x27, 0x02}, // WWW Refresh 3
• ....
  * l' O& b: F. M8 j& \# I

7 l  S5 r/ C4 ^) A8 W: L3 G( O在app.c 中的 app_user_entry 函数，每当添加一个新的按键实例，必须透过 app_hid_send_report
这个函数，将按键值及长度发送给主机端，主机才能根据按键值做出对应的行为； 举例来说，要发出
- m; h  D  p# ~/ B  N3 z# y4 |# I降低音量的按键功能，从上面的注释可以看到 volume down 对应到第九列，是整个数组的第 18 个
数，因此调用发送函数时写成 app_hid_send_report(&key_copy[18], 2) 2)，其他按键也是如此使用。
4 k% {- U; ?3 t' d
2.6 HOGP 相关 AT command
本应用指南中，已经建立部分的AT command ，
; n! [/ o9 b3 b5 Y, s' B
3 O& ^, c& t2 ^. v6 E  X! o用户自行添加 AT command 时，需要在 MCU 端及 BT 端同时增加对应的实例； MCU 端要在
" \" j2 e; E5 Z3 v. zat_cmd.h 中新增 AT command 的请求及期待的响应； BT 端要在 app.h 中新增要解析的 AT
8 {/ n) E3 n+ Scommand 字符串、 command 的枚举以及回复的枚举，数量上如果对不上的话则发出的按键功能可
! H' v0 G3 z4 _6 s- a能会不正常。
. G1 k1 b  t, N0 Y1 M0 \) Q

RGB_lamp

常见的物联网应用，小至家庭，大至整个城市系统网络，无线则是串起IoT系统中最重要的通讯方式。AT32都能够用得到！

CRAZY_argentina

终端装置进行联网时，会产生的大量隐私数据，要确保用户隐私和数据安全，MCU在数据储存中的受保护区管理(带有硬件的访问控制)和严格的编程流程规划，以及操作中管理访问权限的应用，非常重要。。。