# ble_alertor_demo

**Repository Path**: yocop/ble_alertor_demo

## Basic Information

- **Project Name**: ble_alertor_demo
- **Description**: 基于HID示例实现手机回连功能
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2022-02-25
- **Last Updated**: 2024-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Title:  BLE Alertor应用开发
---

# 1. 简介

本例程作为报警器蓝牙解决方案的示例，主要说明如何开发蓝牙设备与手机的回连功能。

![](./readme/assets/overview.png)

# 2. BLE HIDS介绍

Bluetooth SIG组织定义了基于BLE的HOGP（HID Over GATT Profile）Profile，该Profile包含HIDS（HID Service）、BAS（Battery Service）、DIS（Device Information Service）服务，其中HIDS提供了人机交互设备的应用框架，BAS提供了电池服务，DIS提供了设备信息服务。一个蓝牙键盘的应用开发基本上是对这三个服务进行开发。在开始开发之前，我们先介绍一下HIDS服务的基础知识，BAS、DIS服务较为简单，这里不做赘述。

HIDS通过报告描述符（Report Map）来定义HID设备的功能。对于蓝牙键盘来说，它主要实现的功能就是蓝牙键盘的按键输入和指示灯控制。蓝牙键盘的按键输入称为Input Report，蓝牙键盘的指示灯控制称为Output Report。他们组成了HIDS的主要特征，其说明如下表所述：

| 特征名称 | 说明 |
| - | - |
| Report Map | 报告描述符，描述了HID Keyboard Device与HID Host传输数据的格式和作用 |
| Report | 包含Input Report、Output Report等子特征 |
| Report: Input Report | HID Keyboard Device通过该特征发送键盘数据到HID Host |
| Report: Output Report | HID Host通过该特征向HID Keyboard Device发送指示灯亮灭状态 |

# 3. 应用开发

本章节介绍了HID Keyboard示例程序的开发流程，包括应用初始化、报告描述符定义、蓝牙协议栈事件处理、键盘指示灯控制、按键键值的上报、电池电量的更新上报和设备信息的配置等。

## 3.1. 应用初始化

应用入口函数为app_main，主要实现蓝牙协议栈的配置，以及HIDS、DIS、BAS组件的初始化。

主要流程如下图所示：

![交互流程图](./readme/assets/HID_Keyboard_init.png)

代码分析：

```c
int main(void)
{
    int ret = 0;
    unsigned int event_flags;

     /* 板级初始化，各业务模块初始化 */
    board_yoc_init();

    /* 蓝牙协议栈初始化参数设置 */
    dev_addr_t addr = {0};
    init_param_t init = {
        .dev_name = DEVICE_NAME,
        .dev_addr = NULL,
        .conn_num_max = 1,
    };

    aos_event_new(&sync_event, 0);

    LOGI(TAG, "Bluetooth EBike demo!");
    
    /* 蓝牙协议栈初始化 */
    ble_stack_init(&init);

    ...
    
    /* 自定义报警器Profile初始化 */
    ble_ebike_init(ebike_event);

    /* 设置固定配对密钥，默认设置为000000 */
    bt_passkey_set(000000);

    /* OTA Profile服务初始化 */
    ble_ota_init(ota_event);

    /* load蓝牙协议栈配置参数，如配对密钥等 */
    ble_stack_setting_load();

    /* 注册蓝牙协议栈事件回调函数 */
    ret = ble_stack_event_register(&ble_cb);
    ...

    /* 开启广播 */
    start_adv();

    while (1) {
        /* 等待事件 */
        ret = aos_event_get(&sync_event, 0xFFFFFFFF, AOS_EVENT_OR_CLEAR, &event_flags, AOS_WAIT_FOREVER);
        ...
        /* OTA事件，处理OTA数据 */
        if ((event_flags & EVENT_OTA) == EVENT_OTA) {
            ble_ota_process();
        }
		/* 自定义报警器事件 */
        if ((event_flags & EVENT_EBIKE) == EVENT_EBIKE) {
            ble_ebike_process();
        }
        /* 断连事件，重新开启广播 */
        if ((event_flags & EVENT_DISCONN) == EVENT_DISCONN) {
            start_adv();
        }
    }
}
```

## 3.2. 板级初始化

板级初始化的入口为board_yoc_init，主要完成硬件初始化以及OS组件初始化，由app_main函数调用。

```c
void board_yoc_init(void)
{
    int ret;

    board_init();
    /* 初始化console */
    console_init(CONSOLE_UART_IDX, 115200, 128);
    /* 日志系统初始化 */
    ulog_init();
    ...

    /* 分区管理模块初始化 */
    ret = partition_init();
    ...

    /* KV系统初始化 */
    aos_kv_init("kv");

#if defined(AOS_COMP_CLI) || defined(USE_CLI)
    /* CLI模块初始化 */
    board_cli_init();
#endif  
}

```

## 3.3. 蓝牙协议栈事件处理

蓝牙协议栈的事件是通过event_callback()回调函数上报，应用程序需要对这些事件进行相应的处理，下图列举了主要的蓝牙协议栈事件:

![交互流程图](./readme/assets/HID_Keyboard_event_handle.png)

代码分析：

```c
static int event_callback(ble_event_en event, void *event_data)
{
    switch (event) {
        /* 连接成功或失败事件，此时可以开始进行安全等级协商 */
        case EVENT_GAP_CONN_CHANGE:
            conn_change(event, event_data);
            break;
		/* 连接参数更新事件 */
        case EVENT_GAP_CONN_PARAM_UPDATE:
            conn_param_update(event, event_data);
            break;
		/* 配对完成事件 */
        case EVENT_SMP_PAIRING_COMPLETE:
            event_smp_complete(event, event_data);
            break;
		/* 配对确认事件，当前是键盘设备，所以是立即确认，并回发确认消息 */
        case EVENT_SMP_PAIRING_CONFIRM:
            smp_pairing_confirm(event_data);
            ble_stack_smp_passkey_confirm(g_conn_hanlde);
            break;
		/* 配对取消事件 */
        case EVENT_SMP_CANCEL:
            event_smp_cancel(event, event_data);
            break;
		/* 安全等级更新事件 */
        case EVENT_GAP_CONN_SECURITY_CHANGE:
            conn_security_change(event, event_data);
			break;
        default:
            break;
    }

    return 0;
}
```



# 4. 例程运行

BLE HID Keyboard示例程序的运行步骤为：

- 连接串口调试工具, 配置为
  波特率: 115200, 数据位: 8, 校验位: None, 停止位: 1, 流控: None
- 复位开发板
- 设备开始广播后，将在串口上输出‘adv start’信息

```shell
[   0.033]<I>INIT find 7 partitions
Welcome to CLI...
> [   0.261]<I>INIT Build:Oct 22 2020,15:37:29
[   0.278]<I>DEMO Bluetooth Alertor demo!
[   0.455]<E>DEMO adv start!
```

- 使用手机的系统蓝牙功能，扫描到'YoC-Alertor'设备
- 点击该设备，手机界面将显示密码输入框，输入“000000”后，等待与设备配对成功
- 关闭手机蓝牙后再次打开，观察手机系统蓝牙，配对成功后的此设备会自动重新连接



# 5. 参考资料

| Specification                            | 版本 | 下载地址                                                     |
| ---------------------------------------- | ---- | ------------------------------------------------------------ |
| HID SERVICE SPECIFICATION                | 1.0  | [HIDS 1.0](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=245140) |
| HID OVER GATT PROFILE SPECIFICATION      | 1.0  | [HOGP 1.0](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=245141) |
| BATTERY SERVICE SPECIFICATION            | 1.0  | [BAS 1.0](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=245138) |
| DEVICE INFORMATION SERVICE SPECIFICATION | 1.1  | [DIS 1.1](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=244369) |
| HUMAN INTERFACE DEVICE PROFILE           | 1.1  | [HID 1.1](https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=309012) |