#include "btstack_defines.h"
#include "btstack_util.h"

Data Structures
struct	le_connection_parameter_range

Typedefs
typedef struct le_connection_parameter_range	le_connection_parameter_range_t

Enumerations
enum	gap_connection_type_t { GAP_CONNECTION_INVALID, GAP_CONNECTION_ACL, GAP_CONNECTION_SCO, GAP_CONNECTION_LE }

enum	gap_random_address_type_t { GAP_RANDOM_ADDRESS_TYPE_OFF = 0, GAP_RANDOM_ADDRESS_TYPE_STATIC, GAP_RANDOM_ADDRESS_NON_RESOLVABLE, GAP_RANDOM_ADDRESS_RESOLVABLE }

enum	gap_security_level_t { LEVEL_0 = 0, LEVEL_1, LEVEL_2, LEVEL_3, LEVEL_4 }

enum	gap_security_state { GAP_SECURITY_NONE, GAP_SECUIRTY_ENCRYPTED, GAP_SECURITY_AUTHENTICATED }

Functions
void	gap_advertisements_enable (int enabled)
	Enable/Disable Advertisements. More...

void	gap_advertisements_set_data (uint8_t advertising_data_length, uint8_t *advertising_data)
	Set Advertisement Data. More...

void	gap_advertisements_set_params (uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type, uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy)
	Set Advertisement Paramters. More...

int	gap_auto_connection_start (bd_addr_type_t address_typ, bd_addr_t address)
	Auto Connection Establishment - Start Connecting to device. More...

int	gap_auto_connection_stop (bd_addr_type_t address_typ, bd_addr_t address)
	Auto Connection Establishment - Stop Connecting to device. More...

void	gap_auto_connection_stop_all (void)
	Auto Connection Establishment - Stop everything. More...

uint8_t	gap_connect (bd_addr_t addr, bd_addr_type_t addr_type)
	Connect to remote LE device. More...

uint8_t	gap_connect_cancel (void)
	Cancel connection process initiated by gap_connect. More...

void	gap_connectable_control (uint8_t enable)
	Override page scan mode. More...

int	gap_dedicated_bonding (bd_addr_t device, int mitm_protection_required)
	Start dedicated bonding with device. More...

uint8_t	gap_disconnect (hci_con_handle_t handle)
	Disconnect connection with handle. More...

void	gap_discoverable_control (uint8_t enable)
	Allows to control if device is discoverable. More...

void	gap_drop_link_key_for_bd_addr (bd_addr_t addr)
	Deletes link key for remote device with baseband address. More...

int	gap_get_bondable_mode (void)
	Get bondable mode. More...

void	gap_get_connection_parameter_range (le_connection_parameter_range_t *range)
	Set accepted connection parameter range. More...

gap_connection_type_t	gap_get_connection_type (hci_con_handle_t connection_handle)
	Get connection type. More...

int	gap_inquiry_start (uint8_t duration_in_1280ms_units)
	Start GAP Classic Inquiry. More...

int	gap_inquiry_stop (void)
	Stop GAP Classic Inquiry. More...

void	gap_le_get_own_address (uint8_t *addr_type, bd_addr_t addr)
	Get own addr type and address used for LE. More...

void	gap_local_bd_addr (bd_addr_t address_buffer)
	Gets local address. More...

int	gap_mitm_protection_required_for_security_level (gap_security_level_t level)

int	gap_pin_code_negative (bd_addr_t addr)
	Abort Legacy Pairing. More...

int	gap_pin_code_response (bd_addr_t addr, const char *pin)
	Legacy Pairing Pin Code Response. More...

gap_random_address_type_t	gap_random_address_get_mode (void)
	Get privacy mode. More...

void	gap_random_address_set (bd_addr_t addr)
	Sets a fixed random address for advertising. More...

void	gap_random_address_set_mode (gap_random_address_type_t random_address_type)
	Enable privacy by using random addresses. More...

void	gap_random_address_set_update_period (int period_ms)
	Sets update period for random address. More...

int	gap_remote_name_request (bd_addr_t addr, uint8_t page_scan_repetition_mode, uint16_t clock_offset)
	Remote Name Request. More...

int	gap_request_connection_parameter_update (hci_con_handle_t con_handle, uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout)
	Request an update of the connection parameter for a given LE connection. More...

void	gap_request_security_level (hci_con_handle_t con_handle, gap_security_level_t level)

void	gap_scan_response_set_data (uint8_t scan_response_data_length, uint8_t *scan_response_data)
	Set Scan Response Data. More...

gap_security_level_t	gap_security_level (hci_con_handle_t con_handle)

gap_security_level_t	gap_security_level_for_link_key_type (link_key_type_t link_key_type)

void	gap_set_bondable_mode (int enabled)
	Enable/disable bonding. More...

void	gap_set_class_of_device (uint32_t class_of_device)
	Set class of device that will be set during Bluetooth init. More...

void	gap_set_connection_parameter_range (le_connection_parameter_range_t *range)
	Get accepted connection parameter range. More...

void	gap_set_connection_parameters (uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout, uint16_t min_ce_length, uint16_t max_ce_length)
	Set connection parameters for outgoing connections. More...

void	gap_set_extended_inquiry_response (const uint8_t *data)
	Set Extended Inquiry Response data. More...

void	gap_set_local_name (const char *local_name)
	Sets local name. More...

void	gap_set_scan_parameters (uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window)
	Set parameters for LE Scan. More...

int	gap_ssp_confirmation_negative (bd_addr_t addr)
	Abort SSP Numeric Comparison/Pairing. More...

int	gap_ssp_confirmation_response (bd_addr_t addr)
	Accept SSP Numeric Comparison. More...

int	gap_ssp_passkey_negative (bd_addr_t addr)
	Abort SSP Passkey Entry/Pairing. More...

int	gap_ssp_passkey_response (bd_addr_t addr, uint32_t passkey)
	SSP Passkey Response. More...

void	gap_ssp_set_authentication_requirement (int authentication_requirement)
	Set Authentication Requirements using during SSP. More...

void	gap_ssp_set_auto_accept (int auto_accept)
	If set, BTstack will confirm a numeric comparison and enter '000000' if requested. More...

void	gap_ssp_set_enable (int enable)
	Enable will enable SSP during init. More...

void	gap_ssp_set_io_capability (int ssp_io_capability)
	Set IO Capability. More...

void	gap_start_scan (void)
	Start LE Scan. More...

void	gap_stop_scan (void)
	Stop LE Scan. More...

void	gap_store_link_key_for_bd_addr (bd_addr_t addr, link_key_t link_key, link_key_type_t type)
	Store link key for remote device with baseband address. More...

int	gap_update_connection_parameters (hci_con_handle_t con_handle, uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout)
	Updates the connection parameters for a given LE connection. More...

typedef struct le_connection_parameter_range le_connection_parameter_range_t

enum gap_connection_type_t

Enumerator
GAP_CONNECTION_INVALID
GAP_CONNECTION_ACL
GAP_CONNECTION_SCO
GAP_CONNECTION_LE

enum gap_random_address_type_t

Enumerator
GAP_RANDOM_ADDRESS_TYPE_OFF
GAP_RANDOM_ADDRESS_TYPE_STATIC
GAP_RANDOM_ADDRESS_NON_RESOLVABLE
GAP_RANDOM_ADDRESS_RESOLVABLE

enum gap_security_level_t

Enumerator
LEVEL_0
LEVEL_1
LEVEL_2
LEVEL_3
LEVEL_4

enum gap_security_state

Enumerator
GAP_SECURITY_NONE
GAP_SECUIRTY_ENCRYPTED
GAP_SECURITY_AUTHENTICATED

void gap_advertisements_enable ( int enabled )

Enable/Disable Advertisements.

OFF by default.

Parameters

enabled

Referenced by le_counter_setup(), le_prov_adv_start(), and tss_start_advertising().

void gap_advertisements_set_data	(	uint8_t	advertising_data_length,
		uint8_t *	advertising_data
	)

Set Advertisement Data.

Parameters

advertising_data_length
advertising_data	(max 31 octets)

Note: data is not copied, pointer has to stay valid; '00:00:00:00:00:00' in advertising_data will be replaced with actual bd addr

Referenced by le_counter_setup(), le_prov_adv_start(), and tss_start_advertising().

void gap_advertisements_set_params	(	uint16_t	adv_int_min,
		uint16_t	adv_int_max,
		uint8_t	adv_type,
		uint8_t	direct_address_typ,
		bd_addr_t	direct_address,
		uint8_t	channel_map,
		uint8_t	filter_policy
	)

Set Advertisement Paramters.

Parameters

adv_int_min
adv_int_max
adv_type
direct_address_type
direct_address
channel_map
filter_policy

Note: own_address_type is used from gap_random_address_set_mode

Referenced by le_counter_setup(), le_prov_adv_start(), and tss_start_advertising().

int gap_auto_connection_start	(	bd_addr_type_t	address_typ,
		bd_addr_t	address
	)

Auto Connection Establishment - Start Connecting to device.

Parameters

address_typ
address

Returns: 0 if ok

int gap_auto_connection_stop	(	bd_addr_type_t	address_typ,
		bd_addr_t	address
	)

Auto Connection Establishment - Stop Connecting to device.

Parameters

address_typ
address

Returns: 0 if ok

void gap_auto_connection_stop_all ( void )

Auto Connection Establishment - Stop everything.

Note: Convenience function to stop all active auto connection attempts

uint8_t gap_connect	(	bd_addr_t	addr,
		bd_addr_type_t	addr_type
	)

Connect to remote LE device.

uint8_t gap_connect_cancel ( void )

Cancel connection process initiated by gap_connect.

void gap_connectable_control ( uint8_t enable )

Override page scan mode.

Page scan mode enabled by l2cap when services are registered

Note: Might be used to reduce power consumption while Bluetooth module stays powered but no (new) connections are expected

Referenced by l2cap_init().

int gap_dedicated_bonding	(	bd_addr_t	device,
		int	mitm_protection_required
	)

Start dedicated bonding with device.

Disconnect after bonding.

Parameters

device
request	MITM protection

Returns: error, if max num acl connections active; GAP_DEDICATED_BONDING_COMPLETE

uint8_t gap_disconnect ( hci_con_handle_t handle )

Disconnect connection with handle.

Parameters

handle

References hci_connection_for_handle(), hci_emit_disconnection_complete(), hci_run(), SEND_DISCONNECT, and hci_connection_t::state.

void gap_discoverable_control ( uint8_t enable )

Allows to control if device is discoverable.

OFF by default.

void gap_drop_link_key_for_bd_addr ( bd_addr_t addr )

Deletes link key for remote device with baseband address.

Parameters

addr

Referenced by event_handler().

int gap_get_bondable_mode ( void )

Get bondable mode.

Returns: 1 if bondable

void gap_get_connection_parameter_range ( le_connection_parameter_range_t * range )

Set accepted connection parameter range.

Parameters

range Set accepted connection parameter range.

Returns: le connection parameter range struct

References hci_stack_t::le_connection_parameter_range.

gap_connection_type_t gap_get_connection_type ( hci_con_handle_t connection_handle )

Get connection type.

Parameters

con_handle

Returns: connection_type

References hci_connection_t::address_type, BD_ADDR_TYPE_CLASSIC, BD_ADDR_TYPE_LE_PUBLIC, BD_ADDR_TYPE_LE_RANDOM, BD_ADDR_TYPE_SCO, GAP_CONNECTION_ACL, GAP_CONNECTION_INVALID, GAP_CONNECTION_LE, GAP_CONNECTION_SCO, and hci_connection_for_handle().

Referenced by l2cap_hci_event_handler().

int gap_inquiry_start ( uint8_t duration_in_1280ms_units )

Start GAP Classic Inquiry.

Parameters

duration in 1.28s units

Returns: 0 if ok : GAP_EVENT_INQUIRY_RESULT, GAP_EVENT_INQUIRY_COMPLETE

int gap_inquiry_stop ( void )

Stop GAP Classic Inquiry.

Stop GAP Classic Inquiry

Returns: 0 if ok : GAP_EVENT_INQUIRY_COMPLETE

void gap_le_get_own_address	(	uint8_t *	addr_type,
		bd_addr_t	addr
	)

Get own addr type and address used for LE.

Referenced by sm_init_setup(), and sm_run().

void gap_local_bd_addr ( bd_addr_t address_buffer )

Gets local address.

References hci_stack_t::local_bd_addr.

Referenced by sm_run().

int gap_mitm_protection_required_for_security_level ( gap_security_level_t level )

Referenced by hci_run().

int gap_pin_code_negative ( bd_addr_t addr )

Abort Legacy Pairing.

Parameters

addr
pin

Returns: 0 if ok

int gap_pin_code_response	(	bd_addr_t	addr,
		const char *	pin
	)

Legacy Pairing Pin Code Response.

Parameters

addr
pin

Returns: 0 if ok

gap_random_address_type_t gap_random_address_get_mode ( void )

Get privacy mode.

References gap_random_adress_type.

Referenced by sm_run().

void gap_random_address_set ( bd_addr_t addr )

Sets a fixed random address for advertising.

Parameters

addr

Note: Sets random address mode to type off

References gap_random_address_set_mode(), GAP_RANDOM_ADDRESS_TYPE_STATIC, RAU_SET_ADDRESS, rau_state, RAU_W4_WORKING, sm_random_address, and sm_run().

void gap_random_address_set_mode ( gap_random_address_type_t random_address_type )

Enable privacy by using random addresses.

Parameters

random_address_type to use (incl. OFF)

References gap_random_address_trigger(), gap_random_address_type_requires_updates(), gap_random_address_update_start(), gap_random_address_update_stop(), gap_random_adress_type, hci_le_set_own_address_type(), and own_address_type().

Referenced by gap_random_address_set().

void gap_random_address_set_update_period ( int period_ms )

Sets update period for random address.

Parameters

period_ms in ms

References gap_random_address_type_requires_updates(), gap_random_address_update_start(), gap_random_address_update_stop(), and gap_random_adress_update_period.

int gap_remote_name_request	(	bd_addr_t	addr,
		uint8_t	page_scan_repetition_mode,
		uint16_t	clock_offset
	)

Remote Name Request.

Parameters

addr
page_scan_repetition_mode
clock_offset	only used when bit 15 is set - pass 0 if not known : HCI_EVENT_REMOTE_NAME_REQUEST_COMPLETE

int gap_request_connection_parameter_update	(	hci_con_handle_t	con_handle,
		uint16_t	conn_interval_min,
		uint16_t	conn_interval_max,
		uint16_t	conn_latency,
		uint16_t	supervision_timeout
	)

Request an update of the connection parameter for a given LE connection.

Parameters

handle
conn_interval_min	(unit: 1.25ms)
conn_interval_max	(unit: 1.25ms)
conn_latency
supervision_timeout	(unit: 10ms)

Returns: 0 if ok

void gap_request_security_level	(	hci_con_handle_t	con_handle,
		gap_security_level_t	level
	)

void gap_scan_response_set_data	(	uint8_t	scan_response_data_length,
		uint8_t *	scan_response_data
	)

Set Scan Response Data.

Note: For scan response data, scannable undirected advertising (ADV_SCAN_IND) need to be used

Parameters

advertising_data_length
advertising_data	(max 31 octets)

Note: data is not copied, pointer has to stay valid; '00:00:00:00:00:00' in scan_response_data will be replaced with actual bd addr

Referenced by le_prov_adv_start().

gap_security_level_t gap_security_level ( hci_con_handle_t con_handle )

gap_security_level_t gap_security_level_for_link_key_type ( link_key_type_t link_key_type )

Referenced by event_handler(), and hci_run().

void gap_set_bondable_mode ( int enabled )

Enable/disable bonding.

Default is enabled.

Parameters

enabled

void gap_set_class_of_device ( uint32_t class_of_device )

Set class of device that will be set during Bluetooth init.

Note: has to be done before stack starts up

void gap_set_connection_parameter_range ( le_connection_parameter_range_t * range )

Get accepted connection parameter range.

Parameters

range Get accepted connection parameter range.

References hci_stack_t::le_connection_parameter_range.

void gap_set_connection_parameters	(	uint16_t	conn_interval_min,
		uint16_t	conn_interval_max,
		uint16_t	conn_latency,
		uint16_t	supervision_timeout,
		uint16_t	min_ce_length,
		uint16_t	max_ce_length
	)

Set connection parameters for outgoing connections.

Parameters

conn_interval_min	(unit: 1.25ms), default: 10 ms
conn_interval_max	(unit: 1.25ms), default: 30 ms
conn_latency,default,:	4
supervision_timeout	(unit: 10ms), default: 720 ms
min_ce_length	(unit: 0.625ms), default: 10 ms
max_ce_length	(unit: 0.625ms), default: 30 ms

void gap_set_extended_inquiry_response ( const uint8_t * data )

Set Extended Inquiry Response data.

Note: has to be done before stack starts up; If not set, local name will be used for EIR data (see gap_set_local_name); '00:00:00:00:00:00' in local_name will be replaced with actual bd addr

Parameters

eir_data size 240 bytes, is not copied make sure memory is accessible during stack startup

void gap_set_local_name ( const char * local_name )

Sets local name.

Note: has to be done before stack starts up; Default name is 'BTstack 00:00:00:00:00:00'; '00:00:00:00:00:00' in local_name will be replaced with actual bd addr

Parameters

name	is not copied, make sure memory is accessible during stack startup

References hci_stack_t::local_name.

void gap_set_scan_parameters	(	uint8_t	scan_type,
		uint16_t	scan_interval,
		uint16_t	scan_window
	)

Set parameters for LE Scan.

int gap_ssp_confirmation_negative ( bd_addr_t addr )

Abort SSP Numeric Comparison/Pairing.

Parameters

addr
pin

Returns: 0 if ok

int gap_ssp_confirmation_response ( bd_addr_t addr )

Accept SSP Numeric Comparison.

Parameters

addr
passkey

Returns: 0 if ok

int gap_ssp_passkey_negative ( bd_addr_t addr )

Abort SSP Passkey Entry/Pairing.

Parameters

addr
pin

Returns: 0 if ok

int gap_ssp_passkey_response	(	bd_addr_t	addr,
		uint32_t	passkey
	)

SSP Passkey Response.

Parameters

addr
passkey	[0..999999]

Returns: 0 if ok

void gap_ssp_set_authentication_requirement ( int authentication_requirement )

Set Authentication Requirements using during SSP.

void gap_ssp_set_auto_accept ( int auto_accept )

If set, BTstack will confirm a numeric comparison and enter '000000' if requested.

void gap_ssp_set_enable ( int enable )

Enable will enable SSP during init.

void gap_ssp_set_io_capability ( int ssp_io_capability )

Set IO Capability.

BTstack will return capability to SSP requests

void gap_start_scan ( void )

Start LE Scan.

void gap_stop_scan ( void )

Stop LE Scan.

void gap_store_link_key_for_bd_addr	(	bd_addr_t	addr,
		link_key_t	link_key,
		link_key_type_t	type
	)

Store link key for remote device with baseband address.

Parameters

addr
link_key
link_key_type

Referenced by event_handler().

int gap_update_connection_parameters	(	hci_con_handle_t	con_handle,
		uint16_t	conn_interval_min,
		uint16_t	conn_interval_max,
		uint16_t	conn_latency,
		uint16_t	supervision_timeout
	)

Updates the connection parameters for a given LE connection.

Parameters

handle
conn_interval_min	(unit: 1.25ms)
conn_interval_max	(unit: 1.25ms)
conn_latency
supervision_timeout	(unit: 10ms)

Returns: 0 if ok

Microchip® Advanced Software Framework

Data Structures

Typedefs

Enumerations

Functions