Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
GAP API

Functions

at_ble_status_t at_ble_addr_get (at_ble_addr_t *address)
 Get device public BT Address. More...
 
at_ble_status_t at_ble_addr_set (at_ble_addr_t *address)
 Set the local device BT Address. More...
 
at_ble_status_t at_ble_adv_data_set (uint8_t const *const adv_data, uint8_t adv_data_len, uint8_t const *const scan_resp_data, uint8_t scan_response_data_len)
 Set, clear or update advertisement and scan response data. More...
 
at_ble_status_t at_ble_adv_set_tx_power (int8_t power)
 Set the Advertising transmission power. More...
 
at_ble_status_t at_ble_adv_start (at_ble_adv_type_t type, at_ble_adv_mode_t mode, at_ble_addr_t *peer_addr, at_ble_filter_type_t filtered, uint16_t interval, uint16_t timeout, bool disable_randomness)
 Start advertising (GAP Discoverable, Connectable modes, Broadcast Procedure). More...
 
at_ble_status_t at_ble_adv_stop (void)
 Stop advertising (GAP Discoverable, Connectable modes, Broadcast Procedure). More...
 
at_ble_status_t at_ble_authenticate (at_ble_handle_t conn_handle, at_ble_pair_features_t *features, at_ble_LTK_t *ltk, at_ble_CSRK_t *csrk)
 Starts Pairing procedure for a given connection. More...
 
void at_ble_conn_update_reply (at_ble_handle_t conn_handle, at_ble_connection_params_t *connection_params)
 Reply to connection parameters update request AT_BLE_CONN_PARAM_UPDATE_REQUEST. More...
 
at_ble_status_t at_ble_connect (at_ble_addr_t peers[], uint8_t peer_count, uint16_t scan_interval, uint16_t scan_window, at_ble_connection_params_t *connection_params)
 Connect to a peer device. More...
 
at_ble_status_t at_ble_connect_cancel (void)
 Cancels an ongoing connection attempt. More...
 
at_ble_status_t at_ble_connection_param_update (at_ble_handle_t handle, at_ble_connection_params_t *connection_params)
 Update the connection parameters of an ongoing connection. More...
 
at_ble_status_t at_ble_device_name_set (uint8_t *dev_name, uint8_t len)
 Set device name. More...
 
at_ble_status_t at_ble_disconnect (at_ble_handle_t handle, at_ble_disconnect_reason_t reason)
 Disconnect a connected peer device. More...
 
at_ble_status_t at_ble_encryption_request_reply (at_ble_handle_t conn_handle, at_ble_auth_t auth, bool key_found, at_ble_LTK_t *key)
 Responds to encryption start request from master device AT_BLE_ENCRYPTION_REQUEST , once encryption starts AT_BLE_ENCRYPTION_STATUS_CHANGED event is delivered. More...
 
at_ble_status_t at_ble_encryption_start (at_ble_handle_t conn_handle, at_ble_LTK_t *key, at_ble_auth_t auth)
 Starts encryption, once encryption starts AT_BLE_ENCRYPTION_STATUS_CHANGED event is delivered. More...
 
at_ble_status_t at_ble_event_get (at_ble_events_t *event, void *params, uint32_t timeout)
 extracts the next event form the event queue More...
 
at_ble_status_t at_ble_event_user_defined_post (void *params)
 Posts a user defined custom event into the event queue, allowing the user code to process other events in the same event handling loop. More...
 
at_ble_status_t at_ble_gap_get_param (at_ble_parameters_t param, uint8_t *value_buff, uint16_t value_len)
 Fetch a GAP Parameter value. More...
 
at_ble_status_t at_ble_gap_set_param (at_ble_parameters_t param, uint8_t *value_buff, uint16_t value_len)
 Change the GAP related parameters. More...
 
at_ble_status_t at_ble_init (void *args)
 Reset the link layer and the host. More...
 
int8_t at_ble_max_PA_gain_get (at_ble_handle_t conn_handle)
 Gets maximum allowed TX gain of a given connection. More...
 
at_ble_status_t at_ble_pair_key_reply (at_ble_handle_t conn_handle, at_ble_pair_key_type_t type, uint8_t *key)
 Provides a passkey or OOB data that was requested via AT_BLE_PAIR_KEY_REQUEST event, If key type is AT_BLE_PAIR_PASSKEY, then a 6-byte ASCII string (digit 0..9 only). More...
 
at_ble_status_t at_ble_random_address_resolve (uint8_t nb_key, at_ble_addr_t *rand_addr, uint8_t *irk_key)
 Handles request of resolving a resolvable random address ,AT_BLE_RESOLV_RAND_ADDR_STATUS event is used to inform which key has been used to perform resolution. More...
 
int8_t at_ble_rx_power_get (at_ble_handle_t conn_handle)
 Gets RX power of a given connection. More...
 
at_ble_status_t at_ble_rx_power_subscribe (at_ble_handle_t conn_handle, uint16_t range_max, uint16_t range_min)
 Subscribes for RX power level notifications. More...
 
at_ble_status_t at_ble_rx_power_unsubscribe (at_ble_handle_t conn_handle)
 Unsubscribe form RX power level notifications. More...
 
at_ble_status_t at_ble_scan_start (uint16_t interval, uint16_t window, uint16_t timeout, at_ble_scan_type_t type, at_ble_scan_mode_t mode, bool filter_whitelist, bool filter_duplicates)
 Start scan operation. More...
 
at_ble_status_t at_ble_scan_stop (void)
 Stops an ongoing scan operation. More...
 
at_ble_status_t at_ble_sec_info_set (at_ble_handle_t handle, at_ble_signature_info_t signature_info, at_ble_auth_t authen, at_ble_author_t author)
 Set specific link security configuration and bonding data. More...
 
at_ble_status_t at_ble_send_slave_sec_request (at_ble_handle_t conn_handle, bool mitm_protection, bool bond)
 Send slave security request to master. More...
 
at_ble_status_t at_ble_set_dev_config (at_ble_gap_role role)
 Set GAP attribute data base into BLE chip. More...
 
at_ble_status_t at_ble_set_gap_deviceinfo (at_ble_gap_deviceinfo_t *gap_deviceinfo)
 Set GAP attribute data base in BLE API (Appearance , slave preferred connection parameters , device name write permissions) More...
 
at_ble_status_t at_ble_set_privacy_key (at_ble_gap_irk_t *irk, uint16_t interval)
 Set device Identity Resolving Key. More...
 
int8_t at_ble_tx_power_get (at_ble_handle_t conn_handle)
 Gets TX power of a given connection. More...
 
at_ble_status_t at_ble_tx_power_set (at_ble_handle_t conn_handle, int8_t powerdBm)
 Sets TX gain, relative to maximum gain, for a given connection. More...
 
at_ble_status_t at_ble_whitelist_add (at_ble_addr_t *address)
 Adds a peer device address to the white-list. More...
 
at_ble_status_t at_ble_whitelist_clear (void)
 Clear the white-list. More...
 
at_ble_status_t at_ble_whitelist_remove (at_ble_addr_t *address)
 Removes a peer device address from the white-list. More...
 

at_ble_status_t at_ble_addr_get ( at_ble_addr_t address)

Get device public BT Address.

Parameters
[out]addressThe current BT address
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References at_ble_addr_t::addr, AT_BLE_ADDRESS_PUBLIC, AT_BLE_INVALID_PARAM, dbg_le_get_bd_addr_req_handler(), NULL, and at_ble_addr_t::type.

Referenced by at_ble_adv_start(), at_ble_connect(), and at_ble_scan_start().

at_ble_status_t at_ble_addr_set ( at_ble_addr_t address)

Set the local device BT Address.

Parameters
[in]addressThe new BT address
Precondition
In case of using resolvable random address, at_ble_set_privacy_key is used to set device IRK key otherwise default randomness IRK key values will be used.
Note
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References at_ble_addr_t::addr, device_info::addr_auto_gen, device_info::at_addr_set, AT_BLE_ADDR_LEN, AT_BLE_ADDRESS_PUBLIC, AT_BLE_ADDRESS_RANDOM_PRIVATE_NON_RESOLVABLE, AT_BLE_ADDRESS_RANDOM_PRIVATE_RESOLVABLE, AT_BLE_ADDRESS_RANDOM_STATIC, AT_BLE_INVALID_PARAM, AT_BLE_SUCCESS, device_info::at_dev_addr, dbg_le_set_bd_addr_req_handler(), device, NULL, device_info::privacy_flags, and at_ble_addr_t::type.

at_ble_status_t at_ble_adv_data_set ( uint8_t const *const  adv_data,
uint8_t  adv_data_len,
uint8_t const *const  scan_resp_data,
uint8_t  scan_response_data_len 
)

Set, clear or update advertisement and scan response data.

Note
  • To clear the advertisement data and set it to a 0-length packet, simply provide a valid pointer (pAdvData/pSrData) with its corresponding length (dlen/srdlen) set to 0.
  • The call will fail if pAdvData and pSrData are both NULL since this would have no effect.
Parameters
[in]adv_dataRaw data to be placed in advertisement packet. If NULL, no changes are made to the current advertisement packet data.
[in]adv_data_lenData length for adv_data.
[in]scan_resp_dataRaw data to be placed in scan response packet. If NULL, no changes are made to the current scan response packet data.
[in]scan_response_data_lenData length for scan_resp_data
Returns
AT_BLE_SUCCESS Advertisement data successfully updated or cleared.
AT_BLE_INVALID_PARAM One of the length parameters is invalid.
AT_BLE_FAILURE Both pointer parameters are invalid.

References device_info::ADVData, device_info::advLen, AT_BLE_ADV_MAX_SIZE, AT_BLE_FAILURE, AT_BLE_INVALID_PARAM, AT_BLE_SUCCESS, device, NULL, device_info::SrData, and device_info::srLen.

Referenced by ble_trans_service_advertise().

at_ble_status_t at_ble_adv_set_tx_power ( int8_t  power)

Set the Advertising transmission power.

Parameters
[in]powerNew TX power in dB (attenuation 0..18 db in 3dB steps)
Returns
AT_BLE_SUCCESS TX value changed successfully
AT_BLE_INVALID_PARAM TX value is out of range
AT_BLE_FAILURE Other error
Warning
This function is NOT IMPLEMENTED and returns AT_BLE_FAILURE.

References AT_BLE_FAILURE.

at_ble_status_t at_ble_adv_start ( at_ble_adv_type_t  type,
at_ble_adv_mode_t  mode,
at_ble_addr_t peer_addr,
at_ble_filter_type_t  filtered,
uint16_t  interval,
uint16_t  timeout,
bool  disable_randomness 
)

Start advertising (GAP Discoverable, Connectable modes, Broadcast Procedure).

Parameters
[in]typeAdvertising type, see at_ble_adv_type_t for more info
[in]modeeither non-discoverable,General, Limited or Broadcaster , at_ble_adv_mode_t for more details
[in]peer_addrFor AT_BLE_ADV_TYPE_DIRECTED mode only, known peer address
[in]filteredpolicy at_ble_filter_type_t for more details
[in]intervalAdvertising interval between 0x0020 and 0x4000 in 0.625 ms units (20ms to 10.24s). This parameter must be set to 0 if type equals AT_BLE_ADV_TYPE_DIRECTED
[in]timeoutAdvertising time-out between 0x0001 and 0x3FFF in seconds, 0x0000 disables time-out. This parameter must be set to 0 if type equals AT_BLE_ADV_TYPE_DIRECTED
[in]disable_randomnessif True the device will advertise at the exact interval without adding the random 10msec
Precondition
If it is required to change BD address, at_ble_addr_set should be used otherwise default address will be used
Warning
Advertising time-out "timeout" and randomness "disable_randomness" features are not supported.
Returns
AT_BLE_SUCCESS The BLE stack has started advertising
AT_BLE_PRIVACY_CFG_PB Advertising type conflicts with local device address type
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References at_ble_addr_t::addr, device_info::addr_auto_gen, device_info::ADVData, device_info::advLen, at_ble_addr_get(), AT_BLE_ADDRESS_PUBLIC, AT_BLE_ADDRESS_RANDOM_PRIVATE_NON_RESOLVABLE, AT_BLE_ADDRESS_RANDOM_PRIVATE_RESOLVABLE, AT_BLE_ADV_BROADCASTER_MODE, AT_BLE_ADV_INTERVAL_MAX, AT_BLE_ADV_INTERVAL_MIN, AT_BLE_ADV_NONCON_INTERVAL_MIN, AT_BLE_ADV_TYPE_DIRECTED, AT_BLE_ADV_TYPE_NONCONN_UNDIRECTED, AT_BLE_ADV_TYPE_SCANNABLE_UNDIRECTED, AT_BLE_ADV_TYPE_UNDIRECTED, AT_BLE_INVALID_PARAM, AT_BLE_PRIVACY_CFG_PB, AT_BLE_SUCCESS, device_info::at_dev_addr, device, gapm_get_adv_type(), gapm_get_device_address_type(), gapm_start_adv_cmd_handler(), NULL, device_info::renew_dur, device_info::SrData, device_info::srLen, and at_ble_addr_t::type.

Referenced by ble_trans_service_advertise().

at_ble_status_t at_ble_adv_stop ( void  )

Stop advertising (GAP Discoverable, Connectable modes, Broadcast Procedure).

Returns
AT_BLE_SUCCESS The BLE stack has stopped advertising
AT_BLE_FAILURE Error to stop advertising (most probably not in advertising state)

References gapm_cancel_cmd_handler().

at_ble_status_t at_ble_authenticate ( at_ble_handle_t  conn_handle,
at_ble_pair_features_t features,
at_ble_LTK_t ltk,
at_ble_CSRK_t csrk 
)

Starts Pairing procedure for a given connection.

This API will initiate the authentication procedure, given local device requirements and IO capabilities the authentication will proceed in a number of ways, progress is monitored and controlled via the events : AT_BLE_PAIR_KEY_REQUEST ,AT_BLE_PAIR_DONE

In the central role, this function will send an SMP Pairing Request, otherwise in the peripheral role, this function will reply to AT_BLE_PAIR_REQUEST.

Note
  • Bonding information(information exchanged during pairing)such as key , authentication level should be stored by application in order to be reused during another connection
  • According to IO capabilities or Out Of Band (OOB), if it is possible to perform a pairing using PIN code or OOB data then AT_BLE_PAIR_KEY_REQUEST event will be received by application.
Parameters
[in]conn_handleHandle of the ongoing connection
[in]featuresLocal device requirements and IO capabilities
[in]ltkLocal device Long Term Key, null if not available
[in]csrkLocal device Connection Signature Resolution Key , null if not available
Returns
AT_BLE_SUCCESS Operation programmed successfully
AT_BLE_FAILURE Generic error

References AT_BLE_FAILURE, AT_BLE_INVALID_PARAM, AT_BLE_KEY_DIST_ENC, AT_BLE_KEY_DIST_SIGN, at_ble_pair_features_t::bond, device_info::csrk, at_ble_pair_features_t::desired_auth, device, GAP_AUTH_REQ_MITM_BOND, GAP_AUTH_REQ_MITM_NO_BOND, GAP_AUTH_REQ_NO_MITM_BOND, GAP_AUTH_REQ_NO_MITM_NO_BOND, gapc_bond_cfm_handler_pair_resp(), gapc_bond_cmd_handler(), at_ble_pair_features_t::initiator_keys, at_ble_pair_features_t::io_capabilities, device_info::ltk, at_ble_pair_features_t::max_key_size, at_ble_pair_features_t::mitm_protection, NULL, at_ble_pair_features_t::oob_available, at_ble_pair_features_t::responder_keys, device_info::role, ROLE_MASTER, and ROLE_SLAVE.

Referenced by ble_pair_request_handler(), and ble_slave_security_handler().

void at_ble_conn_update_reply ( at_ble_handle_t  conn_handle,
at_ble_connection_params_t connection_params 
)

Reply to connection parameters update request AT_BLE_CONN_PARAM_UPDATE_REQUEST.

Parameters
[in]conn_handleHandle of the connection to be updated
[in]connection_paramsNew parameters to be used
Returns
AT_BLE_SUCCESS Operation programmed successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References at_ble_connection_params_t::ce_len_max, at_ble_connection_params_t::ce_len_min, and gapc_param_update_cfm_handler().

at_ble_status_t at_ble_connect ( at_ble_addr_t  peers[],
uint8_t  peer_count,
uint16_t  scan_interval,
uint16_t  scan_window,
at_ble_connection_params_t connection_params 
)

Connect to a peer device.

Connecting to a peer device, implicitly starting the necessary scan operation then connecting if a device in the peers list is found. This API returns immediately after the operation is programmed, actual connection establishment or failure is marked with AT_BLE_CONNECTED event

Parameters
[in]peersa list of peers that the device will connect to one of them
[in]peer_countnumber of elements in peers, 0 to connect to any peer device
[in]scan_intervalscan interval in 625us units
[in]scan_windowscan window in 625us units
[in]connection_paramsparameters of the established connection
Returns
AT_BLE_SUCCESS Operation programmed successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References at_ble_addr_t::addr, device_info::addr_auto_gen, at_ble_addr_get(), AT_BLE_INVALID_PARAM, AT_BLE_SUCCESS, AT_CNX_INTERVAL_MAX, AT_CNX_INTERVAL_MIN, AT_CNX_LATENCY_MAX, AT_CNX_SUP_TO_MAX, AT_CNX_SUP_TO_MIN, at_ble_connection_params_t::ce_len_max, at_ble_connection_params_t::ce_len_min, at_ble_connection_params_t::con_intv_max, at_ble_connection_params_t::con_intv_min, at_ble_connection_params_t::con_latency, device, GAPM_CONNECTION_AUTO, gapm_get_device_address_type(), gapm_start_connection_cmd_handler(), device_info::renew_dur, device_info::role, ROLE_MASTER, at_ble_connection_params_t::superv_to, and at_ble_addr_t::type.

at_ble_status_t at_ble_connect_cancel ( void  )

Cancels an ongoing connection attempt.

Returns
AT_BLE_SUCCESS Operation canceled successfully
AT_BLE_FAILURE Generic error

References gapm_cancel_cmd_handler().

at_ble_status_t at_ble_connection_param_update ( at_ble_handle_t  handle,
at_ble_connection_params_t connection_params 
)

Update the connection parameters of an ongoing connection.

This API returns after programming the new values but before they take effect; the actual effect of the parameters is marked by the event AT_BLE_CONN_PARAM_UPDATE_DONE

Parameters
[in]handleHandle of the connection to be updated
[in]connection_paramsNew parameters to be used
Returns
AT_BLE_SUCCESS Operation programmed successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References AT_BLE_INVALID_PARAM, AT_CNX_INTERVAL_MAX, AT_CNX_INTERVAL_MIN, AT_CNX_LATENCY_MAX, AT_CNX_SUP_TO_MAX, AT_CNX_SUP_TO_MIN, at_ble_connection_params_t::ce_len_max, at_ble_connection_params_t::ce_len_min, at_ble_connection_params_t::con_intv_max, at_ble_connection_params_t::con_intv_min, at_ble_connection_params_t::con_latency, gapc_param_update_cmd_handler(), and at_ble_connection_params_t::superv_to.

at_ble_status_t at_ble_device_name_set ( uint8_t *  dev_name,
uint8_t  len 
)

Set device name.

Parameters
[in]dev_namethe new device name
[in]lenname length
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References AT_BLE_INVALID_PARAM, gapm_set_dev_name_handler(), and NULL.

Referenced by at_ble_init(), and ble_set_device_name().

at_ble_status_t at_ble_disconnect ( at_ble_handle_t  handle,
at_ble_disconnect_reason_t  reason 
)

Disconnect a connected peer device.

Parameters
[in]handleHandle of the connection to be terminated
[in]reasonDisconnection reason, more info at at_ble_disconnect_reason_t
Returns
AT_BLE_SUCCESS Operation programmed successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References AT_BLE_TERMINATED_BY_USER, AT_BLE_UNACCEPTABLE_INTERVAL, device_info::conn_handle, device, and gapc_disconnect_cmd_handler().

Referenced by ble_pair_done_handler(), and ble_pair_key_request_handler().

at_ble_status_t at_ble_encryption_request_reply ( at_ble_handle_t  conn_handle,
at_ble_auth_t  auth,
bool  key_found,
at_ble_LTK_t key 
)

Responds to encryption start request from master device AT_BLE_ENCRYPTION_REQUEST , once encryption starts AT_BLE_ENCRYPTION_STATUS_CHANGED event is delivered.

Parameters
[in]conn_handleHandle of the connection to be updated
[in]key_foundIf true then a valid key is found in device database and will be used
[in]authAuthentication level
[in]keyLTK key used for encryption
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References AT_BLE_FAILURE, gapc_encrypt_cfm_handler(), at_ble_LTK_t::key, at_ble_LTK_t::key_size, and NULL.

Referenced by ble_encryption_request_handler().

at_ble_status_t at_ble_encryption_start ( at_ble_handle_t  conn_handle,
at_ble_LTK_t key,
at_ble_auth_t  auth 
)

Starts encryption, once encryption starts AT_BLE_ENCRYPTION_STATUS_CHANGED event is delivered.

Parameters
[in]conn_handleHandle of the connection to be updated
[in]keyLTK key used for encryption
[in]authAuthentication level , this information must be stored in device database after each pairing process at_ble_pair_done_t
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References AT_BLE_FAILURE, at_ble_LTK_t::ediv, gapc_encrypt_cmd_handler(), at_ble_LTK_t::key, at_ble_LTK_t::key_size, at_ble_LTK_t::nb, and NULL.

at_ble_status_t at_ble_event_get ( at_ble_events_t event,
void *  params,
uint32_t  timeout 
)

extracts the next event form the event queue

Parameters
[out]eventThe received event
[out]paramsReceived event data
[in]timeoutTime in millisecond this function will block waiting of an event (0xFFFFFFFF to block indefinitely) in this case, if the user wishes to unblock the function at_ble_event_user_defined_post can be used
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References AT_BLE_CUSTOM_EVENT, AT_BLE_SUCCESS, event::data, event_get(), handle_ble_event(), event::msg_id, NULL, and event::src_id.

Referenced by at_ble_max_PA_gain_get(), at_ble_rx_power_get(), at_ble_tx_power_get(), at_ble_tx_power_set(), ble_event_task(), and m2m_ble_event_get().

at_ble_status_t at_ble_event_user_defined_post ( void *  params)

Posts a user defined custom event into the event queue, allowing the user code to process other events in the same event handling loop.

Events will be received with the as AT_BLE_CUSTOM_EVENT

Parameters
[in]paramsParameters sent to the custom event
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References AT_BLE_SUCCESS, and event_post().

at_ble_status_t at_ble_gap_get_param ( at_ble_parameters_t  param,
uint8_t *  value_buff,
uint16_t  value_len 
)

Fetch a GAP Parameter value.

Parameters
[in]paramParameter to get
[out]value_buffBuffer to store the value in
[out]value_lenValue length
Warning
Not Supported
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error
at_ble_status_t at_ble_gap_set_param ( at_ble_parameters_t  param,
uint8_t *  value_buff,
uint16_t  value_len 
)

Change the GAP related parameters.

Parameters
[in]paramParameter to set
[in]value_buffBuffer where value is stored
[in]value_lenValue length
Warning
Not Supported
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error
int8_t at_ble_max_PA_gain_get ( at_ble_handle_t  conn_handle)

Gets maximum allowed TX gain of a given connection.

Parameters
[in]conn_handleHandle of the connection
Returns
Maximum PA gain in dB

References at_ble_event_get(), AT_BLE_MAX_PA_GAIN_VALUE, AT_BLE_SUCCESS, event, gapc_get_tx_pwr_req_handler(), gapc_con_max_PA_gain_get_ind::max_PA_gain, and params.

at_ble_status_t at_ble_pair_key_reply ( at_ble_handle_t  conn_handle,
at_ble_pair_key_type_t  type,
uint8_t *  key 
)

Provides a passkey or OOB data that was requested via AT_BLE_PAIR_KEY_REQUEST event, If key type is AT_BLE_PAIR_PASSKEY, then a 6-byte ASCII string (digit 0..9 only).

If key type is AT_BLE_PAIR_OOB , then a 16-byte OOB key value in Little Endian format

Parameters
[in]conn_handleHandle of the ongoing connection
[in]typeType of requested key, must match the one asked for in AT_BLE_PAIR_KEY_REQUEST
[in]keyThe key requested
Returns
AT_BLE_SUCCESS Operation programmed successfully
AT_BLE_FAILURE Generic error

References AT_BLE_FAILURE, AT_BLE_PAIR_OOB, AT_BLE_PAIR_PASSKEY, AT_BLE_PASSKEY_LEN, gapc_bond_cfm_handler_key_exch(), GAPC_TK_EXCH, KEY_LEN, and NULL.

Referenced by ble_pair_key_request_handler().

at_ble_status_t at_ble_random_address_resolve ( uint8_t  nb_key,
at_ble_addr_t rand_addr,
uint8_t *  irk_key 
)

Handles request of resolving a resolvable random address ,AT_BLE_RESOLV_RAND_ADDR_STATUS event is used to inform which key has been used to perform resolution.

Parameters
[in]nb_keyNumber of provided IRK
[in]rand_addrPointer to the random address
[in]irk_keyArray of IRK used for address resolution
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References at_ble_addr_t::addr, AT_BLE_ADDRESS_RANDOM_PRIVATE_RESOLVABLE, AT_BLE_INVALID_PARAM, gapm_resolv_addr_cmd_handler(), NULL, and at_ble_addr_t::type.

int8_t at_ble_rx_power_get ( at_ble_handle_t  conn_handle)

Gets RX power of a given connection.

Parameters
[in]conn_handleHandle of the connection
Returns
RX power (RSSI) in dBm 0 or -1: Failed to get RX power

References at_ble_event_get(), AT_BLE_RX_POWER_VALUE, AT_BLE_SUCCESS, event, GAPC_GET_CON_RSSI, gapc_get_info_cmd_handler(), params, and gapc_con_rssi_ind::rssi.

at_ble_status_t at_ble_rx_power_subscribe ( at_ble_handle_t  conn_handle,
uint16_t  range_max,
uint16_t  range_min 
)

Subscribes for RX power level notifications.

If RX power falls between range_min and range_max the event AT_BLE_RX_POWER_VALUE will be received.

Parameters
[in]conn_handleHandle of the connection
[in]range_maxNotifications will be received if RX power falls under this value but over range_min
[in]range_minNotifications will be received if RX power falls over this value but under range_max
Warning
Not Supported
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error
at_ble_status_t at_ble_rx_power_unsubscribe ( at_ble_handle_t  conn_handle)

Unsubscribe form RX power level notifications.

no more AT_BLE_RX_POWER_VALUE events will be received

Parameters
[in]conn_handleHandle of the connection
Warning
Not Supported
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error
at_ble_status_t at_ble_scan_start ( uint16_t  interval,
uint16_t  window,
uint16_t  timeout,
at_ble_scan_type_t  type,
at_ble_scan_mode_t  mode,
bool  filter_whitelist,
bool  filter_duplicates 
)

Start scan operation.

While the scan operation is ongoing, the application will always receive AT_BLE_SCAN_INFO event per found device.
In case of using AT_BLE_SCAN_GEN_DISCOVERY or AT_BLE_SCAN_LIM_DISCOVERY, also AT_BLE_SCAN_REPORT event will be received at the end of scan process.

Parameters
[in]intervalScan interval in 625us units
[in]windowScan window in 625us units
[in]timeoutScan time-out, 0x0000 disables time-out.
[in]typeControls the type of scan to perform either Passive or Active at_ble_scan_type_t for more details.
[in]modeEither General, Limited or Observer only, at_ble_scan_mode_t for more details
[in]filter_whitelistIf true, get scan results only from white-listed devices added by at_ble_whitelist_add otherwise scan results will be got from any advertising device.
[in]filter_duplicatesIf true, scan event will be generated only once per device. If false, multiple events per device may be generated. Note that if more than 10 devices are found, filtering only applies to the first 10 found; multiple scan events may be generated for 11th and subsequent devices.
Warning
Scan time-out feature is not supported.
Returns
AT_BLE_SUCCESS Scan operation started successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References at_ble_addr_t::addr, device_info::addr_auto_gen, at_ble_addr_get(), AT_BLE_INVALID_PARAM, AT_BLE_SCAN_ACTIVE, AT_BLE_SCAN_INTERVAL_MAX, AT_BLE_SCAN_INTERVAL_MIN, AT_BLE_SCAN_OBSERVER_MODE, AT_BLE_SCAN_PASSIVE, AT_BLE_SCAN_WINDOW_MAX, AT_BLE_SCAN_WINDOW_MIN, AT_BLE_SUCCESS, device, gapm_get_device_address_type(), GAPM_SCAN_ACTIVE, gapm_start_scan_cmd_handler(), device_info::renew_dur, SCAN_PASSIVE, and at_ble_addr_t::type.

at_ble_status_t at_ble_scan_stop ( void  )

Stops an ongoing scan operation.

Returns
AT_BLE_SUCCESS Scan operation stopped successfully
AT_BLE_FAILURE Generic error

References gapm_cancel_cmd_handler().

at_ble_status_t at_ble_sec_info_set ( at_ble_handle_t  handle,
at_ble_signature_info_t  signature_info,
at_ble_auth_t  authen,
at_ble_author_t  author 
)

Set specific link security configuration and bonding data.

Parameters
[in]handleHandle of the connection to be terminated
[in]signature_infoSignature_info, more info at at_ble_signature_info_t
[in]authenAuthentication value, one of at_ble_auth_t
[in]authorAuthorization value, one of at_ble_author_t
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References gapc_connection_cfm_handler(), at_ble_CSRK_t::key, at_ble_signature_info_t::local_csrk, at_ble_signature_info_t::lsign_counter, at_ble_signature_info_t::peer_csrk, and at_ble_signature_info_t::peer_sign_counter.

at_ble_status_t at_ble_send_slave_sec_request ( at_ble_handle_t  conn_handle,
bool  mitm_protection,
bool  bond 
)

Send slave security request to master.

Parameters
[in]conn_handleHandle of the ongoing connection
[in]mitm_protectionBoolean value for Man-In-The-Middle protection 0 -> Disable, 1 -> Enable
[in]bondBoolean value for bonding 0 -> Disable, 1 -> Enable
Returns
AT_BLE_SUCCESS Operation programmed successfully
AT_BLE_FAILURE Generic error

References GAP_AUTH_REQ_MITM_BOND, GAP_AUTH_REQ_MITM_NO_BOND, GAP_AUTH_REQ_NO_MITM_BOND, GAP_AUTH_REQ_NO_MITM_NO_BOND, and gapc_security_cmd_handler().

Referenced by ble_send_slave_sec_request().

at_ble_status_t at_ble_set_gap_deviceinfo ( at_ble_gap_deviceinfo_t gap_deviceinfo)

Set GAP attribute data base in BLE API (Appearance , slave preferred connection parameters , device name write permissions)

Parameters
[in]gap_deviceinfogap device information
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
AT_BLE_FAILURE Generic error

References device_info::appearance, at_ble_gap_deviceinfo_t::appearance, AT_BLE_INVALID_PARAM, AT_BLE_SUCCESS, AT_BLE_WRITE_AUTH, AT_BLE_WRITE_DISABLE, AT_BLE_WRITE_ENABLE, AT_BLE_WRITE_UNAUTH, at_ble_gap_deviceinfo_t::dev_name_perm, device_info::dev_name_write_perm, device, GAPM_WRITE_AUTH, GAPM_WRITE_DISABLE, GAPM_WRITE_ENABLE, GAPM_WRITE_UNAUTH, NULL, device_info::spcp_param, and at_ble_gap_deviceinfo_t::spcp_param.

at_ble_status_t at_ble_set_privacy_key ( at_ble_gap_irk_t irk,
uint16_t  interval 
)

Set device Identity Resolving Key.

Parameters
[in]irkdevice IRK used for resolvable random BD address generation
[in]intervalduration before regenerate device address in 10 ms units
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References AT_BLE_INVALID_PARAM, AT_BLE_MAX_KEY_LEN, AT_BLE_SUCCESS, device, device_info::irk, at_ble_gap_irk_t::irk, at_ble_IRK_t::key, NULL, and device_info::renew_dur.

int8_t at_ble_tx_power_get ( at_ble_handle_t  conn_handle)

Gets TX power of a given connection.

Parameters
[in]conn_handlehandle of the connection
Returns
PA gain in dB

References at_ble_event_get(), AT_BLE_SUCCESS, AT_BLE_TX_POWER_VALUE, event, gapc_get_tx_pwr_req_handler(), params, and gapc_con_tx_pow_get_ind::tx_pow_lvl.

at_ble_status_t at_ble_tx_power_set ( at_ble_handle_t  conn_handle,
int8_t  powerdBm 
)

Sets TX gain, relative to maximum gain, for a given connection.

Parameters
[in]conn_handleHandle of the connection
[in]powerdBmReduction of TX gain in dB (attenuation 0..18 dB in 3dB steps). Valid inputs are 0,3,6,...,18.
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid parameter supplied
1: Operation completed. In this case, the gain reduction requested is greater than the maximum gain for some channels; for those channels, the gain has been reduced to 0.

References at_ble_event_get(), AT_BLE_SUCCESS, AT_BLE_TX_POWER_SET, event, gapc_set_tx_pwr_req_handler(), params, and gapc_con_tx_pow_set_ind::status.

at_ble_status_t at_ble_whitelist_add ( at_ble_addr_t address)

Adds a peer device address to the white-list.

Parameters
[in]addressPeer device address
Note
To get scan results from only peers added to white list, make sure that "filter_whitelist" argument of at_ble_scan_start is true.
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References at_ble_addr_t::addr, AT_BLE_FAILURE, GAPM_ADD_DEV_IN_WLIST, gapm_white_list_mgm_cmd(), NULL, and at_ble_addr_t::type.

at_ble_status_t at_ble_whitelist_clear ( void  )

Clear the white-list.

Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References GAPM_CLEAR_WLIST, gapm_white_list_mgm_cmd(), and NULL.

at_ble_status_t at_ble_whitelist_remove ( at_ble_addr_t address)

Removes a peer device address from the white-list.

Parameters
[in]addressPeer device address
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References at_ble_addr_t::addr, AT_BLE_FAILURE, GAPM_RMV_DEV_FRM_WLIST, gapm_white_list_mgm_cmd(), NULL, and at_ble_addr_t::type.