GAP LE Common Exported Functions

group GAP_LE_COMMON_Exported_Functions

Typedefs

typedef T_APP_RESULT (*P_FUN_LE_APP_CB)(uint8_t cb_type, void *p_cb_data)

Callback for GAP LE to notify APP.

Param cb_type:: [in] Callback msg type GAP LE Msg Types.
Param p_cb_data:: [in] Pointer to callback data T_LE_CB_DATA.
Retval result:: T_APP_RESULT.
Return:: Result.

Functions

bool le_gap_init(uint8_t link_num)

Initialize parameters of GAP.

Example usage

int main(void)
{
    board_init();
    driver_init();
    le_gap_init(1);
    app_le_gap_init();
    app_le_profile_init();
    pwr_mgr_init();
    task_init();
    os_sched_start();

    return 0;
}

Parameters:

link_num -- [in] Initialize link number.

Return values:

true -- Operation success.
false -- Operation failure.

Returns:

Operation result.

void le_gap_msg_info_way(bool use_msg)

Set GAP message inform way.

Default value is true.

When use_msg is true, GAP will send the GAP message to io_queue registered by gap_start_bt_stack. Message type is GAP Bluetooth Message Type Definitions.
When use_msg is false, GAP will send the GAP message using callback function registered by le_register_app_cb. Message type is GAP_MSG_LE_GAP_STATE_MSG.

Example usage

int test(void)
{
    le_gap_msg_info_way(false);
}
T_APP_RESULT app_gap_callback(uint8_t cb_type, void *p_cb_data)
{
    T_APP_RESULT result = APP_RESULT_SUCCESS;
    T_LE_CB_DATA cb_data;
    memcpy(&cb_data, p_cb_data, sizeof(T_LE_CB_DATA));
    APP_PRINT_TRACE1("app_gap_callback: msgType %d", cb_type);
    switch (cb_type)
    {
    ...
    case GAP_MSG_LE_GAP_STATE_MSG:
        APP_PRINT_INFO0("GAP_MSG_LE_GAP_STATE_MSG");
        app_handle_gap_msg((T_IO_MSG *)cb_data->p_gap_state_msg);
        break;
    ...
    }
}

Parameters:: use_msg -- [in] Whether to use message.

uint8_t le_get_max_link_num(void)

Get maximum supported LE link count.

Example usage

void test(void)
{
    link_num = le_get_max_link_num();
    le_gap_init(link_num);
}

Return values:: max_link_num -- Maximum supported LE link count.

void le_register_app_cb(P_FUN_LE_APP_CB app_callback)

Register APP callback from GAP LE.

Example usage

void app_le_profile_init(void)
{
    le_register_app_cb(app_gap_callback);
    client_init(client_num);
    simple_ble_client_id = simp_ble_add_client(app_client_callback);
    client_register_general_client_cb(app_client_callback);
}

Parameters:: app_callback -- [in] Callback function defined by APP.

T_GAP_CAUSE le_set_gap_param(T_GAP_LE_PARAM_TYPE param, uint8_t len, void *p_value)

Set a GAP LE parameter.

This function can be called with a GAP LE Parameter type T_GAP_LE_PARAM_TYPE and it will set the GAP LE parameter. The 'p_value' field must point to an appropriate data type that meets the requirements for the corresponding parameter type. (For example, if required data length for parameter type is 2 octets, p_value should be cast to a pointer of uint16_t.)

Example usage

void app_le_gap_init(void)
{
    ...
    //device name and device appearance
    uint8_t  device_name[GAP_DEVICE_NAME_LEN] = "BLE_PERIPHERAL";
    uint16_t appearance = GAP_GATT_APPEARANCE_UNKNOWN;

    //Set device name and device appearance
    le_set_gap_param(GAP_PARAM_DEVICE_NAME, GAP_DEVICE_NAME_LEN, device_name);
    le_set_gap_param(GAP_PARAM_APPEARANCE, sizeof(appearance), &appearance);
    ...
}

Parameters:

param -- [in] GAP LE parameter type T_GAP_LE_PARAM_TYPE.
len -- [in] Length of data to write.
p_value -- [in] Pointer to data to write.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
Others -- Operation failure.

Returns:

Operation result.

T_GAP_CAUSE le_get_gap_param(T_GAP_LE_PARAM_TYPE param, void *p_value)

Get a GAP LE parameter.

This function can be called with a GAP LE Parameter type T_GAP_LE_PARAM_TYPE and it will get the GAP LE parameter. The 'p_value' field must point to an appropriate data type that meets the requirements for the corresponding parameter type. (For example, if required data length for parameter type is 2 octets, p_value should be cast to a pointer of uint16_t.)

Example usage

void test(void)
{
    uint8_t gap_link_credits;

    T_GAP_CAUSE cause = le_get_gap_param(GAP_PARAM_LE_REMAIN_CREDITS, &gap_link_credits);
}

Parameters:

param -- [in] GAP LE parameter type T_GAP_LE_PARAM_TYPE.
p_value -- [inout] Pointer to location to get the parameter value.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
Others -- Operation failure.

Returns:

Operation result.

T_GAP_CAUSE le_modify_white_list(T_GAP_WHITE_LIST_OP operation, uint8_t *bd_addr, T_GAP_REMOTE_ADDR_TYPE bd_type)

Modify local Filter Accept List.

If sending request operation is successful, the modifying result will be returned by callback registered by le_register_app_cb with msg type GAP_MSG_LE_MODIFY_WHITE_LIST.

Applications can only call this API after the Bluetooth Host is ready.

Explanation: If the Bluetooth Host is ready, the application will be notified by message GAP_MSG_LE_DEV_STATE_CHANGE with new_state about gap_init_state, which is configured as GAP_INIT_STATE_STACK_READY.

Example usage

void test(void)
{
    T_GAP_WHITE_LIST_OP operation = GAP_WHITE_LIST_OP_ADD;
    uint8_t bd_addr[BD_ADDR_SIZE] = {0};
    T_GAP_REMOTE_ADDR_TYPE bd_type = GAP_REMOTE_ADDR_LE_PUBLIC;
    le_modify_white_list(operation, bd_addr, bd_type);
}
T_APP_RESULT app_gap_callback(uint8_t cb_type, void *p_cb_data)
{
    T_APP_RESULT result = APP_RESULT_SUCCESS;
    T_LE_CB_DATA cb_data;
    memcpy(&cb_data, p_cb_data, sizeof(T_LE_CB_DATA));
    APP_PRINT_TRACE1("app_gap_callback: cb_type %d", cb_type);
    switch (cb_type)
    {
    ...
    case GAP_MSG_LE_MODIFY_WHITE_LIST:
       APP_PRINT_INFO2("GAP_MSG_LE_MODIFY_WHITE_LIST: operation  0x%x, cause 0x%x",
                       cb_data.p_le_modify_white_list_rsp->operation,
                       cb_data.p_le_modify_white_list_rsp->cause);
       break;
    }
    ...
}

Parameters:

operation -- [in] T_GAP_WHITE_LIST_OP.
bd_addr -- [in] Pointer to Bluetooth Device Address.
bd_type -- [in] Bluetooth Device Address type. Value is T_GAP_REMOTE_ADDR_TYPE.

Return values:

GAP_CAUSE_SUCCESS -- Sending request operation is successful.
Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_CAUSE le_gen_rand_addr(T_GAP_RAND_ADDR_TYPE rand_addr_type, uint8_t *random_bd)

Generate a local random address.

Example usage

void test(void)
{
    T_GAP_RAND_ADDR_TYPE rand_addr_type = GAP_RAND_ADDR_RESOLVABLE;
    uint8_t random_bd[BD_ADDR_SIZE] = {0};
    le_gen_rand_addr(rand_addr_type, random_bd);
}

Parameters:

rand_addr_type -- [in] Bluetooth Device Random Address type. Value is T_GAP_RAND_ADDR_TYPE.
random_bd -- [inout] Pointer to Bluetooth Device Address.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
Others -- Operation failure.

Returns:

Operation result.

T_GAP_CAUSE le_set_rand_addr(uint8_t *random_bd)

Set local random address.

If sending request operation is successful, the setting result will be returned by callback registered by le_register_app_cb with msg type GAP_MSG_LE_SET_RAND_ADDR.

Applications can only call this API after the Bluetooth Host is ready.

Explanation: If the Bluetooth Host is ready, the application will be notified by message GAP_MSG_LE_DEV_STATE_CHANGE with new_state about gap_init_state, which is configured as GAP_INIT_STATE_STACK_READY.

Example usage

void test(void)
{
    uint8_t random_bd[BD_ADDR_SIZE] = {0};
    le_set_rand_addr(random_bd);
}
T_APP_RESULT app_gap_callback(uint8_t cb_type, void *p_cb_data)
{
    T_APP_RESULT result = APP_RESULT_SUCCESS;
    T_LE_CB_DATA cb_data;
    memcpy(&cb_data, p_cb_data, sizeof(T_LE_CB_DATA));
    APP_PRINT_TRACE1("app_gap_callback: cb_type %d", cb_type);
    switch (cb_type)
    {
    ...
    case GAP_MSG_LE_SET_RAND_ADDR:
        APP_PRINT_INFO1("GAP_MSG_LE_SET_RAND_ADDR: cause 0x%x",
                   cb_data.p_le_set_rand_addr_rsp->cause);
    break;
    }
    ...
}

Parameters:

random_bd -- [in] Pointer to local random address.

Return values:

GAP_CAUSE_SUCCESS -- Sending request operation is successful.
Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_CAUSE le_cfg_local_identity_address(uint8_t *addr, T_GAP_IDENT_ADDR_TYPE type)

Configure local identity address.

This function can be called before gap_start_bt_stack is invoked.

Example usage

void test(void)
{
    T_GAP_IDENT_ADDR_TYPE type = GAP_IDENT_ADDR_PUBLIC;
    uint8_t addr[BD_ADDR_SIZE] = {0};
    le_cfg_local_identity_address(addr, type);
}

Parameters:

addr -- [in] Pointer to local identity address.
type -- [in] Local identity address type. Value is T_GAP_IDENT_ADDR_TYPE.

Return values:

GAP_CAUSE_SUCCESS -- Operation success.
GAP_CAUSE_SEND_REQ_FAILED -- Operation failure.

Returns:

Operation result.

T_GAP_CAUSE le_set_host_chann_classif(uint8_t *p_channel_map)

Set Host channel classification.

If the request to send the operation is successful, the setting result will be returned by the callback function registered by le_register_app_cb with msg type GAP_MSG_LE_SET_HOST_CHANN_CLASSIF.

Applications can only call this API after the Bluetooth Host is ready.

Explanation: If the Bluetooth Host is ready, the application will be notified by message GAP_MSG_LE_DEV_STATE_CHANGE with new_state about gap_init_state, which is configured as GAP_INIT_STATE_STACK_READY.

Example usage

void test(void)
{
    T_GAP_CAUSE cause = le_set_host_chann_classif(p_channel_map);
}
T_APP_RESULT app_gap_callback(uint8_t cb_type, void *p_cb_data)
{
    T_APP_RESULT result = APP_RESULT_SUCCESS;
    T_LE_CB_DATA cb_data;
    memcpy(&cb_data, p_cb_data, sizeof(T_LE_CB_DATA));
    APP_PRINT_TRACE1("app_gap_callback: cb_type %d", cb_type);
    switch (cb_type)
    {
    ...
    case GAP_MSG_LE_SET_HOST_CHANN_CLASSIF:
       APP_PRINT_INFO1("GAP_MSG_LE_SET_HOST_CHANN_CLASSIF: cause 0x%x",
                       cb_data.p_le_set_host_chann_classif_rsp->cause);
       break;
    }
    ...
}

Parameters:

p_channel_map -- [in] Pointer to channel map. Size: 5 octets (37 bits meaningful). This parameter contains 37 1-bit fields. The nth such field (in the range 0 to 36) contains the value for the Link Layer channel index n. Channel n is bad = 0. Channel n is unknown = 1. The most significant bits are reserved for future use. At least one channel shall be marked as unknown.

Return values:

GAP_CAUSE_SUCCESS -- Sending request operation is successful.
Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_CAUSE le_write_default_data_len(uint16_t tx_octets, uint16_t tx_time)

Specify suggested values for the maximum transmission number of payload octets and maximum packet transmission time for new connections.

If sending request operation is successful, the writing result will be returned by callback registered by le_register_app_cb with msg type GAP_MSG_LE_WRITE_DEFAULT_DATA_LEN.

Applications can only call this API after the Bluetooth Host is ready.

Explanation: If the Bluetooth Host is ready, the application will be notified by message GAP_MSG_LE_DEV_STATE_CHANGE with new_state about gap_init_state, which is configured as GAP_INIT_STATE_STACK_READY.

Example usage

void test(void)
{
    uint16_t tx_octets = 0x00FB;
    uint16_t tx_time = 0x0848;
    le_write_default_data_len(tx_octets, tx_time);
}
T_APP_RESULT app_gap_callback(uint8_t cb_type, void *p_cb_data)
{
    T_APP_RESULT result = APP_RESULT_SUCCESS;
    T_LE_CB_DATA cb_data;
    memcpy(&cb_data, p_cb_data, sizeof(T_LE_CB_DATA));
    APP_PRINT_TRACE1("app_gap_callback: cb_type %d", cb_type);
    switch (cb_type)
    {
    ...
    case GAP_MSG_LE_WRITE_DEFAULT_DATA_LEN:
       APP_PRINT_INFO1("GAP_MSG_LE_WRITE_DEFAULT_DATA_LEN: cause 0x%x",
                       cb_data->le_cause.cause);
       break;
    }
    ...
}

Parameters:

tx_octets -- [in] Maximum transmission number of payload octets.
- Range: 0x001B-0x00FB.
tx_time -- [in] Maximum packet transmission time in microseconds.
- Range: 0x0148-0x4290.

Return values:

GAP_CAUSE_SUCCESS -- Sending request operation is successful.
Others -- Sending request operation is failed.

Returns:

The result of sending request.

T_GAP_CAUSE le_vendor_set_rem_min_sca(T_GAP_SCA_FIELD_ENCODING min_sca)

Set Minimum Remote SCA.

If sending request operation is successful, the writing result will be returned by callback registered by le_register_app_cb with msg type GAP_MSG_LE_VENDOR_SET_MIN_REM_SCA.

Example usage

void test(void)
{
    T_GAP_CAUSE cause;
    T_GAP_SCA_FIELD_ENCODING index = GAP_SCA_76_TO_100_PPM;
    cause = le_vendor_set_rem_min_sca(index);
}
T_APP_RESULT app_gap_callback(uint8_t cb_type, void *p_cb_data)
{
    T_APP_RESULT result = APP_RESULT_SUCCESS;
    T_LE_CB_DATA cb_data;
    memcpy(&cb_data, p_cb_data, sizeof(T_LE_CB_DATA));
    APP_PRINT_TRACE1("app_gap_callback: cb_type %d", cb_type);
    switch (cb_type)
    {
    ...
    case GAP_MSG_LE_VENDOR_SET_MIN_REM_SCA:
        APP_PRINT_INFO1("GAP_MSG_LE_VENDOR_SET_MIN_REM_SCA: cause 0x%x",
                        p_data->le_cause.cause);
        break;
    }
    ...
}

Parameters:

min_sca -- [in] Minimum Remote SCA Index T_GAP_SCA_FIELD_ENCODING.

Return values:

GAP_CAUSE_SUCCESS -- Sending request operation is successful.
Others -- Sending request operation is failed.

Returns:

The result of sending request.