创建Bluetooth LE Application

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

• 修改文件

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

  表 9 custom_config.h中的参数

  宏	描述
  SOC_GR533X	定义芯片版本号。
  CHIP_TYPE	芯片型号。 1：GR5331AENI 2：GR5331CENI 3：GR5332AENE 4：GR5331CENI 说明： 工程编译时，应根据实际使用的芯片型号配置该参数。
  SYS_FAULT_TRACE_ENABLE	使能/禁用Trace信息打印。 使能该功能后，发生HardFault时，可打印Call Stack 中的Trace信息。 0：禁用Trace打印 1：使能Trace打印
  ENABLE_BACKTRACE_FEA	使能/禁用栈回溯功能。 0：禁用栈回溯功能 1：使能栈回溯功能
  APP_LOG_ENABLE	APP LOG模块开关。 0：禁用Application Log模块 1：使能Application Log模块
  APP_LOG_STORE_ENABLE	APP LOG STORE模块开关。 0：禁用APP LOG STORE模块 1：使能APP LOG STORE模块
  APP_LOG_PORT	设置APP LOG输出方式。 0：UART 1：J-Link RTT 2：ARM ITM 说明： 默认状态下，该宏在custom_config.h中已被删除，开发者可根据需求重新定义。
  PLATFORM_SDK_INIT_ENABLE	使能/禁用Platform初始化。 0：使能Platform初始化 1：禁用Platform初始化
  PMU_CALIBRATION_ENABLE	使能/禁用PMU校准功能。 使能该功能后，系统将自动监测温度与电压，并自适应调整。建议默认使能。 0：使能PMU校准 1：禁用PMU校准 说明： 在高/低温使用场景下，必须使能PMU校准功能。
  NVDS_START_ADDR	NVDS占用Flash区域的起始地址。 说明： 默认状态下该宏在custom_config.h中已被删除。开发者如需更改NVDS占用区域的配置，可启用该宏，再设置自定义值（必须按4 KB对齐）。
  NVDS_NUM_SECTOR	NVDS占用的Flash Sector数。
  SYSTEM_STACK_SIZE	Application所需的Call Stack的大小，默认为8 KB。 开发者可根据实际使用情况，调整该值 。 说明： ble_app_example示例工程编译后，可在其目录下的Keil_5\Objects\ble_app_example.htm文件中查看参考的Maximum Stack Usage。
  SYSTEM_HEAP_SIZE	Application所需的Heap大小，默认为0 KB。 开发者可根据实际使用情况，调整该值。
  CHIP_VER	固件使用的芯片版本，默认值为0x5332。
  APP_CODE_LOAD_ADDR *	程序存储空间的起始地址。 说明： 该地址需在Flash地址范围内。
  APP_CODE_RUN_ADDR *	程序运行空间的起始地址。 说明： 该地址值需与APP_CODE_LOAD_ADDR保持一致，Application采用XIP模式运行。
  SYSTEM_CLOCK *	设置系统时钟频率。 0：64 MHz 1：32 MHz 2：16 MHz（XO） 3：16 MHz 4：8 MHz 5：2 MHz
  SYSTEM_POWER_MODE	设置系统供电方式。 0：采用DC-DC供电 1：采用SYS_LDO供电
  CFG_LF_ACCURACY_PPM	Bluetooth LE低频睡眠时钟精度，其取值范围为1 ～ 500，单位PPM。
  CFG_LPCLK_INTERNAL_EN	是否使用芯片内部的OSC时钟作为Bluetooth LE低频睡眠时钟。 若使用，则CFG_LF_ACCURACY_PPM将被强 制 设 置 为 500 PPM 。 0：不使用 1：使用
  BOOT_LONG_TIME *	设置芯片启动时是否需要延迟1s再执行后半段启动代码。 0：不延迟 1：延迟1秒
  BOOT_CHECK_IMAGE	在XIP模式下，冷启动时是否对Image进行校验。 0：不进行校验 1：进行校验
  DTM_TEST_ENABLE	使能/禁用DTM测试。 0：禁用DTM测试 1：使能DTM测试
  RF_TX_PA_SELECT	选择射频功率放大器。 1：SPA（适用于GR533x系列：GR5331支持-20 dBm ～6 dBm TX 功率；GR5332支持-20 dBm ～ 5 dBm TX功率） 2：UPA（适用于GR5331，支持-15 dBm ～ 2 dBm TX 功率） 3：HPA（适用于GR5332，支持-10 dBm ～ 15 dBm TX功率）
  CFG_PATCH_ENABLE	使能补丁。 0：禁用补丁 1：使能补丁
  CFG_MAX_PRFS	支持的最大GATT Profile/Service数。 开发者可根据实际需求，设置该值。值越大，占用的RAM空间越大。 取值范围：1 ～ 64
  CFG_MAX_BOND_DEVS	支持的最大绑定设备数，默认值为4。
  CFG_MAX_CONNECTIONS	支持的最大连接数，最大值为10。 开发者可根据实际需求，设置该值。值越大，Bluetooth LE Stack Heap占用的RAM空间就越大。 Bluetooth LE Stack Heap具体大小由以下四个宏（位于flash_scatter_config.h）定义： ENV_HEAP_SIZE ATT_DB_HEAP_SIZE KE_MSG_HEAP_SIZE NON_RET_HEAP_SIZE 说明： 开发者不可修改上述四个宏。
  CFG_ MAX_ADVS	支持的最大Bluetooth LE Legacy/Extended Advertising 数。 取值范围：0 ～ 5 注意： Bluetooth LE 广播（Legacy/Extended/Periodic Advertisings）总数不应超过 5
  CFG_ MAX_SCAN	支持的最大 Bluetooth LE 扫描数。 取值范围：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_CONTROLLER_ONLY	是否只支持 Bluetooth LE 控制器（用于外部主机或 HCI uart 传输）。 0：支持 Bluetooth LE 控制器和主机 1：仅支持 Bluetooth LE 控制器
  CFG_MASTER_SUPPORT	是否支持Master角色。 0：不支持 1：支持
  CFG_SLAVE_SUPPORT	是否支持Slave角色。 0：不支持 1：支持
  CFG_LEGACY_PAIR_SUPPORT	是否支持Legacy配对。 0：不支持 1：支持
  CFG_SC_PAIR_SUPPORT	是否支持Secure配对。 0：不支持 1：支持
  CFG_COC_SUPPORT	是否支持面向连接通道（COC）。 0：不支持 1：支持
  CFG_GATTS_SUPPORT	是否支持GATT Server。 0：不支持 1：支持
  CFG_GATTC_SUPPORT	是否支持GATT Client。 0：不支持 1：支持
  CFG_CONN_AOA_AOD_SUPPORT	是否支持基于连接AoA/AoD。 0：不支持（默认） 1：支持 说明： 该宏固定配置为0。
  CFG_CONNLESS_AOA_AOD_SUPPORT	是否支持无连接AoA/AoD。 0：不支持 1：支持 说明： 该宏固定配置为0。
  CFG_RANGING_SUPPORT	是否支持测距（Ranging）。 0：不支持 1：支持 说明： 该宏固定配置为0。
  EM_BUFF_ENABLE	是否启用EM 缓冲区。 0：不含Bluetooth LE业务，仅外设工程，关闭EM缓冲区。 1：含Bluetooth LE业务，启用EM 缓冲区。
  CFG_MESH_SUPPORT	是否支持Mesh功能。 0：不支持 1：支持
  CFG_SNIFFER_SUPPORT	是否支持RSSI监听功能。 0：不支持 1：支持 说明： 后续SDK版本将支持该功能。
  SECURITY_CFG_VAL	安全配置 0： 启用一级算法 1： 启用二级算法

  说明：

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

• 使用Wizard配置参数

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

  提示：

  推荐开发者使用Wizard进行参数配置，以避免出现非法参数值。

  

在Keil工程中，Scatter （.sct）文件描述链接器使用的存储区域。GR533x 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。
   • 在GR533x SDK的Scatter文件flash_scatter_common.sct中，可利用custom_config.h的宏定义EM_BUFF_ENABLE确定SRAM末端区域是否需要配置用于Bluetooth LE的EM。开发者需根据工程是否包含Bluetooth LE业务，对EM_BUFF_ENABLE进行定义。
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 fromeIf工具，基于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(ble_evt_handler, &heaps_table);

    // 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); 
    board_init(); 
    pwr_mgmt_mode_set(PMR_MGMT_SLEEP_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业务逻辑由GR533x 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分类。

GR533x SDK支持的Bluetooth LE Events，如下表所示：

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

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传递事件。