Adding 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(ble_evt_handler, &heaps_table);

    // 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 Bluetooth LE Stack. Do not modify the definition; otherwise, Bluetooth LE Stack cannot work. For more information about Heap size, see CFG_MAX_CONNECTIONS in “Configuring 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);
    board_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 “Outputting 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 events which are defined in GR551x SDK. Applications need to implement corresponding Bluetooth LE event handlers to obtain operation results or state change notifications of Bluetooth LE Stack. Bluetooth LE event handlers are called in the interrupt context of Bluetooth LE SDK IRQ. Therefore, do not perform long-running operations in handlers, for example, blocking function call and infinite loop; otherwise, the system is blocked, causing Bluetooth LE Stack and the SDK Bluetooth LE module unable to run in a normal timing.

Bluetooth LE events fall into eight categories: Common, GAP Management, GAP Connection Control, Security Manager, L2CAP, GATT Common, GATT Server, and GATT Client. All Bluetooth LE events supported by GR551x SDK are listed below.

Table 10 Bluetooth LE events

Event Type	Event	Description
Common	BLE_COMMON_EVT_STACK_INIT	Bluetooth LE Stack init complete event
GAP Management	BLE_GAPM_EVT_CH_MAP_SET	Channel Map Set complete event
	BLE_GAPM_EVT_WHITELIST_SET	Whitelist Set complete event
	BLE_GAPM_EVT_PER_ADV_LIST_SET	Periodic Advertising List Set complete event
	BLE_GAPM_EVT_PRIVACY_MODE_SET	Privacy Mode for Peer Device Set complete event
	BLE_GAPM_EVT_LEPSM_REGISTER	LEPSM Register complete event
	BLE_GAPM_EVT_LEPSM_UNREGISTER	LEPSM Unregister complete event
	BLE_GAPM_EVT_DEV_INFO_GOT	Device Info Get event
	BLE_GAPM_EVT_ADV_START	Advertising Start complete event
	BLE_GAPM_EVT_ADV_STOP	Advertising Stop complete event
	BLE_GAPM_EVT_SCAN_REQUEST	Scan Request event
	BLE_GAPM_EVT_ADV_DATA_UPDATE	Advertising Data update event
	BLE_GAPM_EVT_SCAN_START	Scan Start complete event
	BLE_GAPM_EVT_SCAN_STOP	Scan Stop complete event
	BLE_GAPM_EVT_ADV_REPORT	Advertising Report event
	BLE_GAPM_EVT_SYNC_ESTABLISH	Periodic Advertising Synchronization Establish event
	BLE_GAPM_EVT_SYNC_STOP	Periodic Advertising Synchronization Stop event
	BLE_GAPM_EVT_SYNC_LOST	Periodic Advertising Synchronization Lost event
	BLE_GAPM_EVT_READ_RSLV_ADDR	Read Resolvable Address event
GAP Connection Control	BLE_GAPC_EVT_PHY_UPDATED	PHY Update event
	BLE_GAPC_EVT_CONNECTED	Connected event
	BLE_GAPC_EVT_DISCONNECTED	Disconnected event
	BLE_GAPC_EVT_CONNECT_CANCEL	Connect Cancel event
	BLE_GAPC_EVT_AUTO_CONN_TIMEOUT	Auto Connect Timeout event
	BLE_GAPC_EVT_CONN_PARAM_UPDATED	Connect Parameter Updated event
	BLE_GAPC_EVT_CONN_PARAM_UPDATE_REQ	Connect Parameter Request event
	BLE_GAPC_EVT_PEER_NAME_GOT	Peer Name Get event
	BLE_GAPC_EVT_CONN_INFO_GOT	Connect Info Get event
	BLE_GAPC_EVT_PEER_INFO_GOT	Peer Info Get event
	BLE_GAPC_EVT_DATA_LENGTH_UPDATED	Data Length Updated event
	BLE_GAPC_EVT_DEV_INFO_SET	Device Info Set event
	BLE_GAPC_EVT_CONNECT_IQ_REPORT	Connection IQ Report info event
	BLE_GAPC_EVT_CONNECTLESS_IQ_REPORT	Connectionless IQ Report info event
	BLE_GAPC_EVT_LOCAL_TX_POWER_READ	Local transmit power read indication info event
	BLE_GAPC_EVT_REMOTE_TX_POWER_READ	Remote transmit power read indication info event
	BLE_GAPC_EVT_TX_POWER_CHANGE_REPORT	Transmit power change reporting info event
	BLE_GAPC_EVT_PATH_LOSS_THRESHOLD_REPORT	Path loss threshold reporting info event
	BLE_GAPC_EVT_RANGING_IND	Ranging indication event
	BLE_GAPC_EVT_RANGING_SAMPLE_REPORT	Ranging sample report event
	BLE_GAPC_EVT_RANGING_CMP_IND	Ranging complete indication event
	BLE_GAPC_EVT_DFT_SUBRATE_SET	Default subrate param set complete event
	BLE_GAPC_EVT_SUBRATE_CHANGE_IND	Subrate change indication event
GATT Common	BLE_GATT_COMMON_EVT_MTU_EXCHANGE	MTU Exchange event
	BLE_GATT_COMMON_EVT_PRF_REGISTER	Service Register event
GATT Server	BLE_GATTS_EVT_READ_REQUEST	GATTS Read Request event
	BLE_GATTS_EVT_WRITE_REQUEST	GATTS Write Request event
	BLE_GATTS_EVT_PREP_WRITE_REQUEST	GATTS Prepare Write Request event
	BLE_GATTS_EVT_NTF_IND	GATTS Notify or Indicate Complete event
	BLE_GATTS_EVT_CCCD_RECOVERY	GATTS CCCD Recovery event
	BLE_GATTS_EVT_MULT_NTF	GATTS Multiple Notifications event
	BLE_GATTS_EVT_ENH_READ_REQUEST	GATTS Enhanced Read Request event
	BLE_GATTS_EVT_ENH_WRITE_REQUEST	GATTS Enhanced Write Request event
	BLE_GATTS_EVT_ENH_PREP_WRITE_REQUEST	GATTS Enhanced Prepare Write Request event
	BLE_GATTS_EVT_ENH_NTF_IND	GATTS Enhanced Notify or Indicate Complete event
	BLE_GATTS_EVT_ENH_CCCD_RECOVERY	GATTS Enhanced CCCD Recovery event
	BLE_GATTS_EVT_ENH_MULT_NTF	GATTS Enhanced Multiple Notifications event
GATT Client	BLE_GATTC_EVT_SRVC_BROWSE	GATTC Service Browse event
	BLE_GATTC_EVT_PRIMARY_SRVC_DISC	GATTC Primary Service Discovery event
	BLE_GATTC_EVT_INCLUDE_SRVC_DISC	GATTC Include Service Discovery event
	BLE_GATTC_EVT_CHAR_DISC	GATTC Characteristic Discovery event
	BLE_GATTC_EVT_CHAR_DESC_DISC	GATTC Characteristic Descriptor Discovery event
	BLE_GATTC_EVT_READ_RSP	GATTC Read Response event
	BLE_GATTC_EVT_WRITE_RSP	GATTC Write Response event
	BLE_GATTC_EVT_NTF_IND	GATTC Notify or Indicate Receive event
	BLE_GATTC_EVT_CACHE_UPDATE	GATTC Cache Update event
	BLE_GATTC_EVT_ENH_SRVC_BROWSE	GATTC Enhanced Service Browse event
	BLE_GATTC_EVT_ENH_PRIMARY_SRVC_DISC	GATTC Enhanced Primary Service Discovery event
	BLE_GATTC_EVT_ENH_INCLUDE_SRVC_DISC	GATTC Enhanced Include Service Discovery event
	BLE_GATTC_EVT_ENH_CHAR_DISC	GATTC Enhanced Characteristic Discovery event
	BLE_GATTC_EVT_ENH_CHAR_DESC_DISC	GATTC Enhanced Characteristic Descriptor Discovery event
	BLE_GATTC_EVT_ENH_READ_RSP	GATTC Enhanced Read Response event
	BLE_GATTC_EVT_ENH_WRITE_RSP	GATTC Enhanced Write Response event
	BLE_GATTC_EVT_ENH_NTF_IND	GATTC Enhanced Notify or Indicate Receive event
Security Manager	BLE_SEC_EVT_LINK_ENC_REQUEST	Link Encrypted Request event
	BLE_SEC_EVT_LINK_ENCRYPTED	Link Encrypted event
	BLE_SEC_EVT_KEY_PRESS_NTF	Key Press event
	BLE_SEC_EVT_KEY_MISSING	Key Missing event
L2CAP	BLE_L2CAP_EVT_CONN_REQ	L2CAP Connect Request event
	BLE_L2CAP_EVT_CONN_IND	L2CAP Connected Indicate event
	BLE_L2CAP_EVT_ADD_CREDITS_IND	L2CAP Credits Add Indicate event
	BLE_L2CAP_EVT_DISCONNECTED	L2CAP Disconnected event
	BLE_L2CAP_EVT_SDU_RECV	L2CAP SDU Receive event
	BLE_L2CAP_EVT_SDU_SEND	L2CAP SDU Send event
	BLE_L2CAP_EVT_ADD_CREDITS_CPLT	L2CAP Credits Add Completed event
	BLE_L2CAP_EVT_ENH_CONN_REQ	L2CAP Enhanced Connect Request event
	BLE_L2CAP_EVT_ENH_CONN_IND	L2CAP Enhanced Connected Indicate event
	BLE_L2CAP_EVT_ENH_RECONFIG_CPLT	L2CAP Enhanced Reconfig Completed event
	BLE_L2CAP_EVT_ENH_RECONFIG_IND	L2CAP Enhanced Reconfig Indicate event

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

For more information about the usage of Bluetooth LE APIs and event APIs, see the source code of Bluetooth LE examples in SDK_Folder\documentation\GR551x_API_Reference and SDK_Folder\projects\ble.

Bluetooth LE Stack is the implementation core of Bluetooth LE 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 Bluetooth LE Stack runs strictly in a time sequence specified in Bluetooth Core Spec.

A state change of Bluetooth LE Stack triggers BLE_SDK_IRQ interrupt with lower priority. In this interrupt handler, the Bluetooth LE event handlers (to be executed in applications) are called to send state change notifications of Bluetooth LE Stack and related business data to applications. You should avoid performing long-running operations in these event handlers, 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 event handlers to the main loop. For more information about processing in the user thread, see GR5xx FreeRTOS Example Application.