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]

address

The 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]

address

The 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

• If address type is AT_BLE_ADDRESS_RANDOM_PRIVATE_RESOLVABLE or AT_BLE_ADDRESS_RANDOM_PRIVATE_NON_RESOLVABLE , the given address is ignored and address will be auto generated. If address type is AT_BLE_ADDRESS_RANDOM_STATIC and address value is NULL , address will be auto generated.
• If address type is random , then AT_BLE_RAND_ADDR_CHANGED event is triggered after first air operation either advertising, connecting, or scanning to inform application about the used random address.
• The default duration before regenerating device address is 10 minutes , to change renew address duration use at_ble_set_privacy_key.

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_data	Raw data to be placed in advertisement packet. If NULL, no changes are made to the current advertisement packet data.
[in]	adv_data_len	Data length for adv_data.
[in]	scan_resp_data	Raw 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_len	Data 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.

at_ble_status_t at_ble_adv_set_tx_power

(

int8_t

power

)

Set the Advertising transmission power.

Parameters

[in]

power

New 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]	type	Advertising type, see at_ble_adv_type_t for more info
[in]	mode	either non-discoverable,General, Limited or Broadcaster , at_ble_adv_mode_t for more details
[in]	peer_addr	For AT_BLE_ADV_TYPE_DIRECTED mode only, known peer address
[in]	filtered	policy at_ble_filter_type_t for more details
[in]	interval	Advertising 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]	timeout	Advertising 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_randomness	if 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.

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_handle	Handle of the ongoing connection
[in]	features	Local device requirements and IO capabilities
[in]	ltk	Local device Long Term Key, null if not available
[in]	csrk	Local 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_handle	Handle of the connection to be updated
[in]	connection_params	New 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]	peers	a list of peers that the device will connect to one of them
[in]	peer_count	number of elements in peers, 0 to connect to any peer device
[in]	scan_interval	scan interval in 625us units
[in]	scan_window	scan window in 625us units
[in]	connection_params	parameters 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]	handle	Handle of the connection to be updated
[in]	connection_params	New 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_name	the new device name
[in]	len	name 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]	handle	Handle of the connection to be terminated
[in]	reason	Disconnection 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_handle	Handle of the connection to be updated
[in]	key_found	If true then a valid key is found in device database and will be used
[in]	auth	Authentication level
[in]	key	LTK 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_handle	Handle of the connection to be updated
[in]	key	LTK key used for encryption
[in]	auth	Authentication 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]	event	The received event
[out]	params	Received event data
[in]	timeout	Time 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]

params

Parameters 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]	param	Parameter to get
[out]	value_buff	Buffer to store the value in
[out]	value_len	Value 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]	param	Parameter to set
[in]	value_buff	Buffer where value is stored
[in]	value_len	Value length

Warning

Not Supported

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_FAILURE Generic error

at_ble_status_t at_ble_init

(

void *

args

)

Reset the link layer and the host.

Parameters

[in]

args

Pointer passed to platform_init() and interpreted by the platform.

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_INVALID_PARAM Invalid parameter supplied

AT_BLE_FAILURE Generic error

References device_info::addr_auto_gen, device_info::advLen, APP_CON_INTV_MAX, APP_CON_INTV_MIN, APP_CON_LATENCY, APP_SUPERV_TO, device_info::appearance, device_info::at_addr_set, at_ble_device_name_set(), AT_BLE_MAX_KEY_LEN, AT_BLE_SUCCESS, at_ble_spcp_t::con_intv_max, at_ble_spcp_t::con_intv_min, at_ble_spcp_t::con_latency, device_info::conn_handle, device_info::dev_name_write_perm, device, event_init(), GAP_device_name, GAP_TMR_PRIV_ADDR_INT, gapm_reset_req_handler(), GAPM_WRITE_DISABLE, device_info::irk, at_ble_IRK_t::key, platform_init(), device_info::privacy_flags, device_info::renew_dur, device_info::role, ROLE_SLAVE, device_info::spcp_param, device_info::srLen, and at_ble_spcp_t::superv_to.

Referenced by m2m_ble_init().

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_handle

Handle 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_handle	Handle of the ongoing connection
[in]	type	Type of requested key, must match the one asked for in AT_BLE_PAIR_KEY_REQUEST
[in]	key	The 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_key	Number of provided IRK
[in]	rand_addr	Pointer to the random address
[in]	irk_key	Array 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_handle

Handle 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_handle	Handle of the connection
[in]	range_max	Notifications will be received if RX power falls under this value but over range_min
[in]	range_min	Notifications 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_handle

Handle 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]	interval	Scan interval in 625us units
[in]	window	Scan window in 625us units
[in]	timeout	Scan time-out, 0x0000 disables time-out.
[in]	type	Controls the type of scan to perform either Passive or Active at_ble_scan_type_t for more details.
[in]	mode	Either General, Limited or Observer only, at_ble_scan_mode_t for more details
[in]	filter_whitelist	If 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_duplicates	If 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]	handle	Handle of the connection to be terminated
[in]	signature_info	Signature_info, more info at at_ble_signature_info_t
[in]	authen	Authentication value, one of at_ble_auth_t
[in]	author	Authorization 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_handle	Handle of the ongoing connection
[in]	mitm_protection	Boolean value for Man-In-The-Middle protection 0 -> Disable, 1 -> Enable
[in]	bond	Boolean 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_dev_config

(

at_ble_gap_role

role

)

Set GAP attribute data base into BLE chip.

Parameters

[in]

role

BLE role to set

Precondition

Must be called before at_ble_adv_start or at_ble_scan_start or at_ble_connect

Returns

AT_BLE_SUCCESS Operation completed successfully

AT_BLE_INVALID_PARAM Invalid parameter supplied

AT_BLE_FAILURE Generic error

References APP_MAX_MTU, device_info::appearance, at_ble_spcp_t::con_intv_max, at_ble_spcp_t::con_intv_min, at_ble_spcp_t::con_latency, device_info::dev_name_write_perm, device, gapm_set_dev_config_cmd_handler(), GAPM_WRITE_DISABLE, device_info::irk, at_ble_IRK_t::key, device_info::privacy_flags, device_info::spcp_param, and at_ble_spcp_t::superv_to.

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_deviceinfo

gap 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]	irk	device IRK used for resolvable random BD address generation
[in]	interval	duration 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_handle

handle 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_handle	Handle of the connection
[in]	powerdBm	Reduction 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]

address

Peer 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]

address

Peer 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.