Add User Code

Code of a typical main.c file is provided as follows:

/**@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)
    {
       /*
        * Add Application code here, e.g. GUI Update.
        */
        app_log_flush();
        pwr_mgmt_schedule();
    }
}

• STACK_HEAP_INIT(heaps_table) defines four global arrays as Heaps for BLE Stack. Do not modify the definition; otherwise, BLE Stack cannot work. For more information about Heap size, see CFG_MAX_CONNECTIONS in “Configure custom_config.h”.
• You can initialize peripherals in app_periph_init(). In development and debugging phases, the SYS_SET_BD_ADDR in this function can be used to set a temporary Public Address. The user_periph_setup.c in which this function is contained includes the following main code:

/**@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_uart_init();
   app_log_assert_init();
   pwr_mgmt_mode_set(PMR_MGMT_SLEEP_MODE);
}

• You should add main loop code of applications to “while(1) { }”, for example, code to handle external input and update GUI.
• When using the APP LOG module, call the app_log_flush() in the main loop. This is to ensure logs are output completely before the SoC enters Sleep Mode. For more information about the APP LOG module, see “Output Debug Logs”.
• Call the pwr_mgmt_shcedule() to implement automatic power management to reduce system power consumption.

Related Bluetooth LE business logics of applications are driven by a number of Bluetooth LE SDK callbacks which are defined in the GR551x SDK. Applications need to register these callbacks in the GR551x SDK to obtain operation results or state change notifications of BLE Stack. Bluetooth LE SDK callbacks are called in the interrupt context of Bluetooth LE SDK IRQ. Therefore, do not perform long-running operations in callbacks, for example, blocking function call and infinite loop; otherwise, the system is blocked, causing BLE Stack and the SDK Bluetooth LE module unable to run in a normal timing.

Bluetooth LE SDK callbacks are categorized into different files by GAP, Security Manager, L2CAP, GATT Common, and GATT Client. All callback functions supported by the GR551x SDK are listed in Table 10.

Table 10 Bluetooth LE SDK callback functions

File Name	Callback Struct	Callback Function
user_app.c	app_callback_t	app_ble_init_cmp_callback
user_gap_callback.c	gap_cb_fun_t	app_gap_param_set_cb
		app_gap_psm_manager_cb
		app_gap_phy_update_cb
		app_gap_dev_info_get_cb
		app_gap_adv_start_cb
		app_gap_adv_stop_cb
		app_gap_scan_req_ind_cb
		app_gap_adv_data_update_cb
		app_gap_scan_start_cb
		app_gap_scan_stop_cb
		app_gap_adv_report_ind_cb
		app_gap_sync_establish_cb
		app_gap_stop_sync_cb
		app_gap_sync_lost_cb
		app_gap_connect_cb
		app_gap_disconnect_cb
		app_gap_connect_cancel_cb
		app_gap_auto_connection_timeout_cb
		app_gap_peer_name_ind_cb
		app_gap_connection_update_cb
		app_gap_connection_update_req_cb
		app_gap_connection_info_get_cb
		app_gap_peer_info_get_cb
		app_gap_le_pkt_size_info_cb
		app_rslv_addr_read_cb
user_l2cap_callback.c	l2cap_lecb_cb_fun_t	app_l2cap_lecb_conn_req_cb
		app_l2cap_lecb_conn_cb
		app_l2cap_lecb_add_credits_ind_cb
		app_l2cap_lecb_disconn_cb
		app_l2cap_lecb_sdu_recv_cb
		app_l2cap_lecb_sdu_send_cb
		app_l2cap_lecb_credit_add_cmp_cb
user_sm_callback.c	sec_cb_fun_t	app_sec_enc_req_cb
		app_sec_enc_ind_cb
		app_sec_keypress_notify_cb
user_gatt_common_callback.c	gatt_common_cb_func_t	app_gatt_mtu_exchange_cb
		app_gatt_prf_register_cb
user_gattc_callback.c	gattc_cb_fun_t	app_gattc_srvc_disc_cb
		app_gattc_inc_srvc_disc_cb
		app_gattc_char_disc_cb
		app_gattc_char_desc_disc_cb
		app_gattc_read_cb
		app_gattc_write_cb
		app_gattc_ntf_ind_cb
		app_gattc_srvc_browse_cb
		app_gattc_cache_update_cb

You need to implement necessary Bluetooth LE SDK callbacks according to functional requirements of your products. For example, if a product does not support Security Manager, you do not need to implement corresponding callbacks; if the product supports GATT Server only, you do not need to implement the callbacks corresponding to GATT Client. Only those callback functions required for products are to be implemented.

For more information about the usage of Bluetooth LE APIs and callback APIs, see the source code of Bluetooth LE examples in GR551x Bluetooth Low Energy Stack User Guide, SDK_Folder\documentation\GR551x_API_Reference, and SDK_Folder\projects\ble.

BLE Stack is the implementation core of BLE protocol stacks. It directly operates the hardware mentioned in Bluetooth 5.1 Core (see “Software Architecture”). Therefore, BLE_Stack_IRQ has the second-highest priority after SVCall IRQ, which ensures that BLE Stack runs strictly in a time sequence specified in Bluetooth Core Spec.

A state change of BLE Stack triggers BLE_SDK_IRQ interrupt with lower priority. In this interrupt handler, the Bluetooth LE SDK callbacks (to be executed in applications) are called to send state change notifications of BLE Stack and related business data to applications. You should avoid performing long-running operations in these callbacks, and shall move such operations to the main loop or user thread for processing. You can use the module in SDK_Folder\components\libraries\app_queue, or your own application framework, to transfer events from Bluetooth LE SDK callbacks to the main loop. For more information about processing in the user thread, see GR551x FreeRTOS Example Application.