HID 私有协议用户指南

本文介绍HID私有协议的使用方法，包括框架、流程和函数说明等。

术语与概念

本协议是Realtek点对点通信的私有无线协议，通信角色如下图所示。本文介绍该协议的使用方法，该协议的详细内容参考文档HID 私有协议规范。

协议共分为5个状态，协议状态机如下图所示。

初始状态是unpaired状态，即没有绑定信息，且没有链路。

paired unconnected状态有绑定信息但没有链路，忽略绑定信息（Bond Information, BI），则进入unpaired状态，可以重新配对。重新配对成功后，会覆盖原有的绑定信息。重新配对失败后，可以重新使用原来的绑定信息，从unpaired状态恢复到paired unconnected状态。

在pairing状态和paired connecting状态，master和slave的行为略有差别。master端有超时机制，即超时未成功则自动退出。而slave端无超时机制，如果需要退出此状态，需要application手动stop。

在paired connected状态，master和slave进行双向数据通信。双向数据通信以sync interval同步间隔为周期进行周期性通信。当双方没有数据交互时，可以降低通信速度，即进入心跳状态，以heartbeat interval心跳间隔为周期进行周期性通信，以降低功耗。

特性

本协议特性如下：

支持4K超高上报率
支持多种重传机制满足不同业务的可靠性需求
采用跳频技术提高抗干扰能力
支持配对实现快速绑定
支持空闲时自动切换低功耗模式

应用涉及协议的操作主要有初始化、参数配置、配对、连接和数据收发，及其回调，如图协议的接口所示。本文后续章节介绍这些操作的使用方法。

接口提供

协议提供的接口申明在以下文件中：

subsys\ppt\sync\inc\ppt_sync.h
subsys\ppt\sync\inc\ppt_sync_master.h
subsys\ppt\sync\inc\ppt_sync_slave.h

初始化与配置

MP Tool配置

需要配置 BLE master link，详情请参考 MP Tool配置。

初始化

协议运行流程如下图所示，需要首先执行初始化流程，然后才能执行pair和connect等状态机操作和数据通信。

本协议的所有 API 都以sync_开头。

初始化的具体流程如下：

调用 sync_init()，初始化协议，确认设备角色
配置参数
配置回调
调用 sync_enable()，使能协议

参数和回调在后续章节介绍。

功能

本节主要介绍 HID 私有协议不同功能或者模块如何使用和配置。

参数

此部分主要介绍协议中参数的含义以及如何配置。

信道

协议使用的信道有默认值2432、2447、2462、2477、2407、2422、2437、2452、2442、2457、2472、2413MHz，共12个信道。信道分组用于fast sync阶段快速回连，默认分3组，每组4个信道。

用户如果有客制化需求，可以调用 sync_channel_set() 配置信道。

发射功率

如果使用动态功率控制，发射功率会在 tx_power_dbm_min 和 tx_power_dbm_max 范围内变化，在链路质量较好时，降低发射功率，反之增加发射功率。如果不使用动态功率控制，固定发射功率为 tx_power_dbm_max。

发射功率配置，可以调用 sync_tx_power_set()。

配对 RSSI 阈值

配对时，支持用RSSI阈值限制配对距离。只有信号强度大于阈值时，才允许配对。

调用 sync_pair_rssi_set() 配置阈值。

绑定信息

配对时会产生绑定信息，会自动存在FTL空间。在连接时，application需要取出绑定信息进行连接。application也可以自行删除，或者覆盖绑定信息。

调用 sync_nvm_get_bond_info() 获取绑定信息。
调用 sync_nvm_set_bond_info() 存储绑定信息。
调用 sync_nvm_clear_bond_info() 删除绑定信息。

同步参数

master设备可以配置同步间隔，以对应应用数据的上报率。当同步间隔大于协议支持的传输速度时，master设备可以配置重传间隔，让协议在一个同步间隔内以重传间隔的速度进行重传。

调用 sync_time_set() 配置同步间隔和重传间隔。

例如：

同步间隔1000us，重传间隔1000us，对应了1K上报率，没有重传机会。

sync_time_set(SYNC_TIME_PARAM_CONNECT_INTERVAL, 1000);
sync_time_set(SYNC_TIME_PARAM_CONNECT_INTERVAL_HIGH, 1000);

同步间隔1000us，重传间隔250us，对应了1K上报率，且有3次重传机会。

sync_time_set(SYNC_TIME_PARAM_CONNECT_INTERVAL, 1000);
sync_time_set(SYNC_TIME_PARAM_CONNECT_INTERVAL_HIGH, 250);

同步间隔250us，重传间隔250us，对应了4K上报率，没有重传机会。

sync_time_set(SYNC_TIME_PARAM_CONNECT_INTERVAL, 250);
sync_time_set(SYNC_TIME_PARAM_CONNECT_INTERVAL_HIGH, 250);

心跳参数

心跳有0/1/2共3档，每档都有心跳间隔和次数。档位越高，心跳间隔越大，对应更低功耗的状态。其中第0档是使用的同步间隔，不需要额外设置心跳间隔，第2档不需要额外设置心跳次数。

调用 sync_master_set_hb_param() 配置心跳各档参数。

例如关闭心跳：

sync_master_set_hb_param(0, 0, SYNC_MASTER_HB_RHY_PERIOD_MAX);

例如打开心跳，且档位0为40次，档位1为10ms乘以200次，档位2为100ms。

sync_master_set_hb_param(0, 0, 40);
sync_master_set_hb_param(1, 10000, 200);
sync_master_set_hb_param(2, 100000, 0);

重传和缓冲

根据消息发送的重传次数，将消息分为以下4类：

零重传：消息不管有没有被应答，只发送一次。
有限重传：消息如果没有被应答，则重传。重传一定次数后还没有被应答，则取消重传。
无限重传：消息如果没有被应答，则一直重传，直到被应答。
动态重传：消息如果没有被应答，需要重传时，如果有其他消息要发送，则取消重传，如果没有其他消息要发送，则继续重传。

调用 sync_msg_set_finite_retrans() 设置有限重传的重传次数。

每类消息有独立的缓冲池，缓冲消息笔数可以用 sync_msg_set_quota() 一起配置，也可以用 sync_msg_set_quota_by_type() 按消息类型分别配置。

Log 开关

协议运行时的部分log可以被application打开或关闭，默认是打开的。

调用 sync_log_set() 开关log。

回调

协议通知application的回调有四类：

event callback：通知配对和连接状态。
message send result callback：通知消息发送结果。
message receive callback：通知消息接收。
send prepare callback：master通知消息发送准备，用于触发application采集和发送数据。

Event Callback

Event callback的注册函数是 sync_event_cb_reg() ，其中函数指针的类型为 sync_event_cb_t()。

event类型详情如下所示：

Event Summary
Event类型	前置条件	上报时机	说明
SYNC_EVENT_PAIRED	配对	配对成功时上报	通知配对成功
SYNC_EVENT_PAIR_TIMEOUT	配对	配对超时	Master通知配对超时
SYNC_EVENT_CONNECTED	配对或者连接	配对成功时上报，或者连接成功时上报	通知连接成功
SYNC_EVENT_CONNECT_TIMEOUT	连接	连接超时	Master通知连接超时
SYNC_EVENT_CONNECT_LOST	连接成功	链路超时	通知链路断开

Message Send Result Callback

message send result callback是每条消息都有独立的的callback，在消息发送时 sync_msg_send() 里注册。发送结果回调的函数指针类型为 sync_msg_send_cb_t()。

Message Receive Callback

Message receive callback的注册函数为sync_msg_reg_receive_cb()。注册的函数指针类型为sync_msg_receive_cb_t()。

Message Send Prepare Callback

Message send prepare callback在master tx前触发，可以用于让application跟随协议tx节奏来采集和发送数据。注册函数为 sync_master_reg_tx_prepare_cb()。

状态机操作

状态机的操作类型有：

pair：配对
connect：连接
stop：停止配对、连接，或者断开链路

调用 sync_pair() 触发pair。
调用 sync_connect() 触发connect。
调用 sync_stop() 触发stop。

数据收发

数据发送同章节 Message Send Result Callback。

数据接收同章节 Message Receive Callback。

DLPS 

如果要支持DLPS，需要调用协议的DLPS初始化API sync_dlps_init()。它应该在 sync_init() 之后调用，且应该在platform DLPS init ( DLPS_IORegUserDlpsEnterCb()， DLPS_IORegUserDlpsExitCb()，DLPS_IORegister() 等API)之前调用。

常见问题

本节介绍了一些常见问题和注意事项。

协议占用资源

协议运行会占用一些资源，application需要避开这些被占用的资源。

占用资源：

ENHANCE TIMER

支持DLPS时，需要在 board.h 里打开宏 USE_ENHTIM_DLPS。

ENHANCE TIMER的API不是中断安全的。application如果也有使用ENHANCE TIMER，则需要调用 __disable_irq() 和 __enable_irq() 进行保护。例如：
```
__disable_irq();
ENHTIM_Cmd(ENH_TIM2, ENABLE);
__enable_irq();
```
具体占用情况如下表所示。

Timer占用
Timer使用情况	<=4K	8K
Master (Mouseetc.)	ENH_TIM1	ENH_TIM0 / ENH_TIM1
Slave (Dongle)	ENH_TIM1	ENH_TIM0 / ENH_TIM1 / ENH_TIM2

FTL空间：offset 0 Byte, length 8 Bytes。

中断优先级

为了避免干扰协议运行，application使用的外设的中断优先级应该≥3，且请尽量缩小临界区的执行时间。

示例工程

本协议有提供示例供用户参考，详见 Sync示例。