创建Bluetooth LE Application

custom_config.h用于配置Application工程参数。开发者可选择直接修改文件或者使用Wizard界面进行配置。

• 修改文件

  GR5525 SDK提供了一个Application工程配置模板文件（SDK_Folder\build\config\custom_config.h），开发者可直接修改该模板文件，配置Application工程参数。

  表 9 custom_config.h中的参数

  宏	描述
  SOC_GR5525	定义芯片版本号。
  SYS_FAULT_TRACE_ENABLE	使能/禁用Trace信息打印。 使能该功能后，发生HardFault时，可打印Call Stack 中的Trace信息。 0：禁用Trace打印 1：使能Trace打印
  ENABLE_BACKTRACE_FEA	使能/禁用栈回溯功能。 0：禁用栈回溯功能 1：使能栈回溯功能
  APP_DRIVER_USE_ENABLE	App Drivers模块开关。 0：禁用App Drivers模块 1：使能App Drivers模块
  APP_LOG_ENABLE	APP LOG模块开关。 0：禁用Application中的Logs 1：使能Application中的Logs
  APP_LOG_STORE_ENABLE	APP LOG STORE模块开关。 0：禁用APP LOG STORE模块 1：使能APP LOG STORE模块
  DTM_TEST_ENABLE	DTM Test功能开关。 0：禁用DTM Test功能 1：使能DTM Test功能
  PMU_CALIBRATION_ENABLE	使能/禁用PMU校准功能，使能该功能后，系统将自动监控温度与电压，并自适应调整。 0：禁用PMU校准功能 1：使能PMU校准功能 说明： 在高/低温使用场景下，必须使能PMU校准功能。
  NVDS_START_ADDR	NVDS占用Flash区域的起始地址。 默认状态下该宏在cutom_config.h中已被注释，开发者若需更改NVDS占用区域的配置，可启用该宏，再设置自定义值（必须按4 KB对齐）。 说明： 该起始地址不能设置在存储器的SCA或User App等已使用的区域内。
  NVDS_NUM_SECTOR	NVDS占用的Flash Sector数。
  SYSTEM_STACK_SIZE	Application所需的Call Stack的大小，默认为32 KB。 开发者可根据实际使用情况，调整该值，但不能少于6 KB。 说明： ble_app_example示例工程编译后，可在其目录下的Keil_5\Objects\ble_app_example.htm中查看参考的Maximum Stack Usage。
  SYSTEM_HEAP_SIZE	Application所需要的Heap大小，默认为16 KB。 开发者可根据实际使用情况，调整该值。
  APP_CODE_LOAD_ADDR *	程序存储空间的起始地址。 说明： 该地址应在Flash地址范围内。
  APP_CODE_RUN_ADDR *	程序运行空间的起始地址。 若该地址的值与APP_CODE_LOAD_ADDR相等，则Application采用XIP模式运行。 若该地址的值在RAM地址范围内，则Application采用Mirror模式运行。
  SYSTEM_CLOCK *	系统时钟频率。 0：96 MHz 1：64 MHz 2：16 MHz（XO） 3：48 MHz 4：24 MHz 5：16 MHz 6：32 MHz（PLL）
  CFG_LPCLK_INTERNAL_EN	是否使用芯片内部的OSC时钟作为Bluetooth LE低频睡眠时钟。若使用，则CFG_LF_ACCURACY_PPM被强制设置为500 PPM。 0：不使用 1：使用
  CFG_LF_ACCURACY_PPM	Bluetooth LE低频睡眠时钟精度，其取值范围1 ～ 500，单位PPM。
  BOOT_LONG_TIME *	设置芯片启动时是否需要延迟1s再执行后半段启动代码。 0：不延迟 1：延迟1秒
  BOOT_CHECK_IMAGE	在XIP模式中，冷启动时是否对Image进行校验。 0：不校验 1：校验
  IO_LDO_USE_3P3_V	配置是否开启LDO 3.3 V。 0：不开启 1：开启
  SECURITY_CFG_VAL	配置算法安全等级。 0：安全等级1 1：安全等级2
  CHIP_VER	固件使用的芯片版本。
  CFG_CONTROLLER_ONLY	是否仅使用Bluetooth LE Controller。 0：使用Bluetooth LE Controller和Host 1：仅使用Bluetooth Controller
  CFG_MAX_PRFS	Application所能够包含的GATT Profile/Service的最大数量。开发者根据实际需求设置该值，其值越大占用的RAM空间就越大。
  CFG_MAX_BOND_DEVS	Application支持的最大绑定设备数，最大值为4。
  CFG_MAX_CONNECTIONS	Application支持的最大连接数量，最大值为10。开发者可以根据实际需要设置其值。该值越大，Bluetooth LE Stack Heaps需要占用的RAM空间就越大。Bluetooth LE Stack Heaps具体大小由flash_scatter_config.h中的以下四个宏定义，开发者不可修改这四个宏： ENV_HEAP_SIZE ATT_DB_HEAP_SIZE KE_MSG_HEAP_SIZE NON_RET_HEAP_SIZE
  CFG_MAX_ADVS	Application支持的Bluetooth LE传统广播和扩展广播总量的最大值。
  CFG_MAX_SCAN	是否支持扫描功能。 0：不支持 1：支持
  CFG_MUL_LINK_WITH_SAME_DEV	是否支持同一设备的多个链接。 0：不支持 1：支持
  CFG_BT_BREDR	是否支持LE链路生成Bluetooth Classic Link Key。 0：不支持 1：支持
  CFG_CAR_KEY_SUPPORT	是否支持车钥匙功能。 0：不支持 1：支持
  CFG_MASTER_SUPPORT	是否支Master功能。 0：不支持 1：支持
  CFG_SLAVE_SUPPORT	是否支持Slave功能。 0：不支持 1：支持
  CFG_LEGACY_PAIR_SUPPORT	是否支持Legacy配对功能。 0：不支持 1：支持
  CFG_SC_PAIR_SUPPORT	是否支持SC配对功能。 0：不支持 1：支持
  CFG_COC_SUPPORT	是否支持COC功能。 0：不支持 1：支持
  CFG_GATTS_SUPPORT	是否支持GATT Service模块。 0：不支持 1：支持
  CFG_GATTC_SUPPORT	是否支持GATT Client模块。 0：不支持 1：支持
  CFG_CONN_AOA_AOD_SUPPORT	是否支持连接方式的AoA/AoD功能。 0：不支持 1：支持
  CFG_CONNLESS_AOA_AOD_SUPPORT	是否支持无连接的AoA/AoD功能。 0：不支持 1：支持
  CFG_RANGING_SUPPORT	是否支持Ranging功能。 0：不支持 1：支持

  *：上表中带*的宏可用于初始化BUILD_IN_APP_INFO结构体，该结构体被定义在固件的0x200地址处，使用custom_config.h中的宏进行初始化。系统启动时，Bootloader程序会从该地址读取固件的配置信息，作为启动参数。

• 使用Wizard配置参数

  custom_config.h文件中的注释符合Keil的Configuration Wizard Annotations规范。因此，开发者可在Keil中打开custom_config.h文件，利用图形化的Keil Configuration Wizard界面配置Application工程参数。

在Keil工程中，Scatter（.sct）文件描述链接器使用的存储区域。GR5525 SDK提供了一个Scatter示例文件（SDK_Folder\platform\soc\linker\keil\flash_scatter_common.sct），可帮助开发者快速完成存储器布局配置。另外，flash_scatter_common.sct使用的宏定义在flash_scatter_config.h中。

开发者可按照以下步骤配置存储器布局：

1. 点击Keil工具栏中的Options for Target按钮 ，打开Options for Target ‘GRxx_Soc’对话框，再选中Linker标签页。
2. 在Linker页面中的Scatter File栏，点击按钮...，浏览选择SDK_Folder\platform\soc\linker\keil下的flash_scatter_common.sct文件。开发者还可先将Scatter（.sct）和配置文件（.h）拷贝至ble_app_example工程的对应目录，再浏览选择文件。
   说明：

   flash_scatter_common.sct中的#! armcc -E -I语句指定了flash_scatter_common.sct依赖的头文件的目录。若该路径错误，则会产生Linker Error。

3. 点击Edit...按钮，打开.sct文件，然后根据实际的产品存储器布局，修改相应代码。

   

4. 点击OK按钮，保存设置。

在Keil中，After Build可用于指定工程Build完成后执行的命令行语句。

ble_app_template工程已默认配置After Build。因此，基于Template工程创建的新工程（ble_app_example）可无需手动配置。

若开发者直接通过Keil的新建工程创建一个工程，则需要按照以下步骤配置After Build：

1. 点击Keil Toolbar的Options for Target按钮 ，打开Options for Target ‘GRxx_Soc’对话框，选择User标签页。
2. 在After Build/Rebuild展开的选项中勾选Run #1，并在对应的User Command栏输入fromelf.exe --text -c --output Listings\@L.s Objects\@L.axf，以便调用Keil fromelf工具，基于axf文件生成汇编文件。
3. 在After Build/Rebuild展开的选项中勾选Run #2，并在对应的User Command栏输入fromelf.exe --bin --output Listings\@L.bin Objects\@L.axf，以便调用Keil fromelf工具，基于axf文件生成汇编文件。
4. 点击OK，保存设置。

以下为典型的main.c文件的内容。

/**@brief Stack global variables for Bluetooth protocol stack. */
STACK_HEAP_INIT(heaps_table);
…
int main (void)
{
    /** Initialize user peripherals. */
    app_periph_init();                

    /** Initialize BLE Stack. */
    ble_stack_init(&&m_app_ble_callback, &heaps_table);
 
    // Main Loop
    while (1)
    {
        app_log_flush();
        pwr_mgmt_schedule();
    }
}

• STACK_HEAP_INIT(heaps_table)定义了7个全局数组，供Bluetooth LE协议栈作为Heap使用。开发者不可修改此定义，否则Bluetooth LE协议栈可能无法正常运行。Heap的大小与配置custom_config.h中的Bluetooth LE业务量有关。
• app_periph_init()用于初始化外设。在开发调试阶段，该函数中的SYS_SET_BD_ADDR可用于设置临时的Public Address，pwr_mgmt_mode_set()中可设置在自动功耗管理时MCU的工作模式（SLEEP/ IDLE/ACTIVE）。app_periph_init()函数实现位于user_periph_setup.c文件，其示例代码如下所示：

/**@brief Bluetooth device address. */
static const uint8_t s_bd_addr[SYS_BD_ADDR_LEN] = {0x11, 0x11, 0x11, 0x11,0x11, 0x11};
…
void app_periph_init(void)
{
   SYS_SET_BD_ADDR(s_bd_addr);
   bsp_log_init();
   pwr_mgmt_mode_set(PMR_MGMT_IDLE_MODE);
}

• 在while(1) { }中添加Application的Main Loop代码，比如处理外部输入、更新GUI。
• 若需打开APP LOG模块，则应在Main Loop中调用app_log_flush()，以保证系统进入Sleep状态之前，完整输出所有Log。关于 APP LOG模块使用，参考输出调试Log。
• 调用pwr_mgmt_shcedule()实现自动功耗管理，以降低系统功耗。

Application的Bluetooth LE业务逻辑由GR5525 SDK中定义的若干Bluetooth LE Events进行驱动。因此，Application需要实现相应的Event Handler，以获取Bluetooth LE Stack的运行结果或状态变更通知。由于Event Handler在Bluetooth LE SDK IRQ的中断上下文（Interrupt Context）中被调用，因此开发者不能在Handler中执行比较耗时的操作，例如阻塞式函数调用、无限循环等。否则，可能阻塞整个系统运行，导致Bluetooth LE Stack与SDK Bluetooth LE模块无法按照正常时序运行。

Bluetooth LE Events按照Common、GAP Management 、GAP Connection Control、Security Manager、L2CAP、GATT Common、GATT Server和GATT Client分类。GR5525 SDK支持的Bluetooth LE Events如下表所示。

开发者需根据产品的功能需求，实现所需的Bluetooth LE Event Handler。例如，若产品不支持Security Manager，则可无需实现对应的Event；若产品只支持GATT Server而不支持GATT Client，则可无需实现GATT Client对应的Event。并且，对于每一类Event的Event Handler也并非需全部实现，仅需实现产品所必须的Event Handler即可。

Bluetooth LE Stack是低功耗蓝牙协议实现核心，可直接操作Bluetooth 5.3 Core硬件（参考软件架构）。因此，BLE_Stack_IRQ具有整个系统中次高的优先级（SVCall IRQ具有最高优先级），以保证Bluetooth LE Stack严格按照Bluetooth Core Spec规定的时序运行。

Bluetooth LE Stack的状态改变会触发优先级较低的BLE_SDK_IRQ中断。在该中断处理函数，可通过调用Application实现的Bluetooth LE Event Handler，将Bluetooth LE Stack的状态变更通知以及相关的业务数据发送至Application。在这些Event Handler中，应避免操作耗时的业务，而应将耗时业务转移至Main Loop或用户级线程中处理。开发者可使用SDK_Folder\components\libraries\app_queue模块（或自定义的Application Framework）从Bluetooth LE Event Handler向Main Loop传递事件。