BlueNRG-MS pack for STM32CubeMX: GAP functions

Allows the security manager to complete the pairing procedure and re-bond with the master.

Note

This command can be issued by the application if a EVT_BLUE_GAP_BOND_LOST event is generated.

Returns

Value indicating success or error code.

Allows the security manager to complete the pairing procedure and re-bond with the master.

Note

This command can be issued by the application if a EVT_BLUE_GAP_BOND_LOST event is generated.

Parameters

conn_handle

Returns

Value indicating success or error code.

Authorize a device to access attributes.

Note

Application should send this command after it has received a EVT_BLUE_GAP_AUTHORIZATION_REQUEST.

Parameters

conn_handle	Connection handle
authorize	CONNECTION_AUTHORIZED : Authorize (accept connection) CONNECTION_REJECTED : Reject (reject connection)

Returns

Value indicating success or error code.

Clear the security database.

Note

All the devices in the security database will be removed.

Returns

Value indicating success or error code.

Add addresses of bonded devices into the controller's whitelist.

Note

The command will return an error if there are no devices in the database or if it was unable to add the device into the whitelist.

Returns

Value indicating success or error code.

Start the direct connection establishment procedure.

Note

A LE_Create_Connection call will be made to the controller by GAP with the initiator filter policy set to �ignore whitelist and process connectable advertising packets only for the specified device�. The procedure can be terminated explicitly by the upper layer by issuing the command aci_gap_terminate_gap_procedure(). When a command is issued to terminate the procedure by upper layer, a LE_Create_Connection_Cancel call will be made to the controller by GAP. On termination of the procedure, a EVT_LE_CONN_COMPLETE event is returned. The procedure can be explicitly terminated by the upper layer by issuing the command aci_gap_terminate_gap_procedure() with the procedure_code set to GAP_DIRECT_CONNECTION_ESTABLISHMENT_PROC.

Parameters

scanInterval	Time interval from when the Controller started its last LE scan until it begins the subsequent LE scan. The scan interval should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
scanWindow	Amount of time for the duration of the LE scan. Scan_Window shall be less than or equal to Scan_Interval. The scan window should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
peer_bdaddr_type	Type of the peer address (PUBLIC_ADDR, STATIC_RANDOM_ADDR).
peer_bdaddr	Address of the peer device with which a connection has to be established.
own_bdaddr_type	Type of our address used during advertising (PUBLIC_ADDR,STATIC_RANDOM_ADDR).
conn_min_interval	Minimum value for the connection event interval. This shall be less than or equal to Conn_Interval_Max. Range: 0x0006 to 0x0C80 Time = N x 1.25 msec Time Range: 7.5 msec to 4 seconds
conn_max_interval	Maximum value for the connection event interval. This shall be greater than or equal to Conn_Interval_Min. Range: 0x0006 to 0x0C80 Time = N x 1.25 msec Time Range: 7.5 msec to 4 seconds
conn_latency	Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F4
supervision_timeout	Supervision timeout for the LE Link. Range: 0x000A to 0x0C80 Time = N x 10 msec Time Range: 100 msec to 32 seconds
min_conn_length	Minimum length of connection needed for the LE connection. Range: 0x0000 - 0xFFFF Time = N x 0.625 msec.
max_conn_length	Maximum length of connection needed for the LE connection. Range: 0x0000 - 0xFFFF Time = N x 0.625 msec.

Returns

Value indicating success or error code.

Delete an AD Type.

Note

This command can be used to delete the specified AD type from the advertisement data if present.

Parameters

ad_type

One of the allowed AD types (see AD Types)

Returns

Value indicating success or error code.

This command gets the list of bonded devices.

Note

It returns the number of addresses and the corresponding address types and values. Example:

tBleStatus ret;

uint8_t num_devices = 0;

uint8_t device_list[12*7];

ret = aci_gap_get_bonded_devices(&num_devices, device_list, sizeof(device_list));

for(int i = 0; i < num_devices; i+=7){

uint8_t addr_type = device_list[i];

uint8_t addr = device_list[i+1];

printf("Type: %d, Addr: %02X%02X%02X%02X%02X%02X\n",addr_type,addr[5],addr[4],addr[3],addr[2],addr[1],addr[0]);

}

Parameters

[out]	num_devices	The number of bonded devices.
[out]	device_list	List of addresses. It contains a sequence of [address type, address] pairs, where address type can be PUBLIC_ADDR or STATIC_RANDOM_ADDR.
	device_list_size	Maximum size of the device_list buffer used to return the device list.

Returns

Value indicating success or error code.

Get the current security settings.

Note

This command can be used to get the current security settings of the device.

Parameters

mitm_protection	0: Not required 1: Required
bonding	0: No bonding mode 1: Bonding mode
oob_data	0: Data absent 1: Data present
passkey_required	0: Not required 1: Fixed pin is present which is being used 2: Passkey required for pairing. An event will be generated when required.

Returns

Value indicating success or error code.

Initialize the GAP layer.

Note

Register the GAP service with the GATT. All the standard GAP characteristics will also be added:

• Device Name
• Appearance
• Peripheral Privacy Flag (peripheral role only)
• Reconnection Address (peripheral role only)
• Peripheral Preferred Connection Parameters (peripheral role only)
  tBleStatus ret;

  uint16_t service_handle, dev_name_char_handle, appearance_char_handle;

  ret = aci_gap_init_IDB04A1(1, &service_handle, &dev_name_char_handle, &appearance_char_handle);

  if(ret){

  PRINTF("GAP_Init failed.\n");

  reboot();

  }

  const char *name = "BlueNRG";

  ret = aci_gatt_update_char_value(service_handle, dev_name_char_handle, 0, strlen(name), (uint8_t *)name);

  if(ret){

  PRINTF("aci_gatt_update_char_value failed.\n");

  }

Parameters

	role	One of the allowed roles: GAP_PERIPHERAL_ROLE or GAP_CENTRAL_ROLE. See GAP roles.
[out]	service_handle	Handle of the GAP service.
[out]	dev_name_char_handle	Device Name Characteristic handle
[out]	appearance_char_handle	Appearance Characteristic handle

Return values

tBleStatus

Value indicating success or error code.

Initialize the GAP layer.

Note

Register the GAP service with the GATT. All the standard GAP characteristics will also be added:

• Device Name
• Appearance
• Peripheral Preferred Connection Parameters (peripheral role only)
  tBleStatus ret;

  uint16_t service_handle, dev_name_char_handle, appearance_char_handle;

  ret = aci_gap_init_IDB05A1(1, 0, 0x07, &service_handle, &dev_name_char_handle, &appearance_char_handle);

  if(ret){

  PRINTF("GAP_Init failed.\n");

  reboot();

  }

  const char *name = "BlueNRG";

  ret = aci_gatt_update_char_value(service_handle, dev_name_char_handle, 0, strlen(name), (uint8_t *)name);

  if(ret){

  PRINTF("aci_gatt_update_char_value failed.\n");

  }

Parameters

	role	Bitmap of allowed roles: see GAP roles.
	privacy_enabled	Enable (1) or disable (0) privacy.
	device_name_char_len	Length of the device name characteristic
[out]	service_handle	Handle of the GAP service.
[out]	dev_name_char_handle	Device Name Characteristic handle
[out]	appearance_char_handle	Appearance Characteristic handle

Return values

tBleStatus

Value indicating success or error code.

The command finds whether a device is bonded.

Note

If the device is using a resolvable private address and it has been bonded, then the command will return BLE_STATUS_SUCCESS.

Parameters

peer_address_type	The address type of the peer device PUBLIC_ADDR. RANDOM_ADDR.
peer_address	Address used by the peer device while advertising.

Returns

Value indicating success or error code.

Provide the pass key that will be used during pairing.

Note

This command should be sent by the Host in response to EVT_BLUE_GAP_PASS_KEY_REQUEST event.

Parameters

conn_handle	Connection handle
passkey	Pass key that will be used during the pairing process. Must be a number between 0 and 999999.

Returns

Value indicating success or error code.

Resolve a private address.

Note

This command tries to resolve the address provided with the IRKs present in its database. If the address is resolved successfully with any one of the IRKs present in the database, it returns success.

Parameters

address

Address to be resolved.

Returns

Value indicating success or error code.

Resolve a private address.

Note

This command tries to resolve the address provided with the IRKs present in its database. If the address is resolved successfully with any one of the IRKs present in the database, it returns success.

Parameters

[in]	address	Address to be resolved.
[out]	actual_address	The public or static random address of the peer device, distributed during pairing phase.

Returns

Value indicating success or error code.

Send a pairing request.

Note

Send the SM pairing request to start a pairing process from a Central. The authentication requirements and IO capabilities should be set before issuing this command using aci_gap_set_io_capability() and aci_gap_set_auth_requirement(). A EVT_BLUE_GAP_PAIRING_CMPLT event is returned after the pairing process is completed.

Parameters

conn_handle	Handle of the connection for which the pairing request has to be sent.
force_rebond	0x00: Pairing request is sent only if the device has not previously bonded 0x01: Pairing request will be sent even if the device was previously bonded

Returns

Value indicating success or error code.

Set the authentication requirements for the device.

Note

If the oob_enable is set to 0, oob_data will be ignored. This command has to be given only when the device is not in a connected state.

Parameters

mitm_mode	MITM mode: MITM_PROTECTION_NOT_REQUIRED MITM_PROTECTION_REQUIRED
oob_enable	If OOB data are present or not: OOB_AUTH_DATA_ABSENT OOB_AUTH_DATA_PRESENT
oob_data	Out-Of-Band data
min_encryption_key_size	Minimum size of the encryption key to be used during the pairing process
max_encryption_key_size	Maximum size of the encryption key to be used during the pairing process
use_fixed_pin	If application wants to use a fixed pin or not: USE_FIXED_PIN_FOR_PAIRING DONOT_USE_FIXED_PIN_FOR_PAIRING If a fixed pin is not used, it has to be provided by the application with aci_gap_pass_key_response() after EVT_BLUE_GAP_PASS_KEY_REQUEST event.
fixed_pin	If use_fixed_pin is USE_FIXED_PIN_FOR_PAIRING, this is the value of the pin that will be used during pairing if MIMT protection is enabled. Any value between 0 to 999999 is accepted.
bonding_mode	One of the bonding modes: BONDING NO_BONDING

Returns

Value indicating success or error code.

Set the authorization requirements of the device.

Note

This command has to be given when connected to a device if authorization is required to access services which require authorization.

Parameters

conn_handle

Handle of the connection.

authorization_enable

AUTHORIZATION_NOT_REQUIRED : Authorization not required AUTHORIZATION_REQUIRED : Authorization required. This enables the authorization requirement in the device and when a remote device tries to read/write a characeristic with authorization requirements, the stack will send back an error response with "Insufficient authorization" error code. After pairing is complete a EVT_BLUE_GAP_AUTHORIZATION_REQUEST event will be sent to the Host.

Returns

Value indicating success or error code.

Puts the device into broadcast mode.

Note

A privacy enabled device uses either a resolvable private address or a non-resolvable private address as specified in the own_addr_type parameter of the command.

Parameters

adv_interv_min	Minimum advertising interval. Range: 0x00A0 to 0x4000 Time = N * 0.625 msec Time Range: 100 ms to 10.24 sec
adv_interv_max	Maximum advertising interval. Range: 0x00A0 to 0x4000 Time = N * 0.625 msec Time Range: 100 ms to 10.24 sec
adv_type	One of the allowed advertising types: ADV_SCAN_IND Scannable undirected advertising ADV_NONCONN_IND Non connectable undirected advertising
own_addr_type	If Privacy is disabled, the broadcaster address can be PUBLIC_ADDR. STATIC_RANDOM_ADDR. If Privacy is enabled, then the broadcaster address can be RESOLVABLE_PRIVATE_ADDR NON_RESOLVABLE_PRIVATE_ADDR
adv_data_length	Length of the advertising data in the advertising packet
adv_data	Advertising data used by the device while advertising
num_whitelist_entries	Number of devices to be added to whitelist
addr_array	It will contain the addresses that have to be added into the whitelist. The format of the addr_array should be: address type followed by address. Example: uint8_t addr_array[] = {PUBLIC_ADDR,0x01,0x00,0x00,0xe1,0x80,0x02, PUBLIC_ADDR,0x02,0x00,0x00,0xe1,0x80,0x02};

Returns

Value indicating success or error code.

Set the Device in direct connectable mode (as defined in GAP specification Volume 3, Section 9.3.3).

Note

If the privacy is enabled, the reconnection address is used for advertising, otherwise the address of the type specified in OwnAddrType is used. The device will be in directed connectable mode only for 1.28 seconds. If no connection is established within this duration, the device enters non discoverable mode and advertising will have to be again enabled explicitly. The controller generates a EVT_LE_CONN_COMPLETE event with the status set to HCI_DIRECTED_ADV_TIMEOUT if the connection was not established and 0x00 if the connection was successfully established.

Usage example:

Parameters

own_addr_type	Type of our address used during advertising (PUBLIC_ADDR,STATIC_RANDOM_ADDR).
initiator_addr_type	Type of peer address (PUBLIC_ADDR,STATIC_RANDOM_ADDR).
initiator_addr	Initiator's address (Little Endian).

Returns

Value indicating success or error code.

Set the Device in direct connectable mode (as defined in GAP specification Volume 3, Section 9.3.3).

Note

If the privacy is enabled, the reconnection address is used for advertising, otherwise the address of the type specified in OwnAddrType is used. The device will be in directed connectable mode only for 1.28 seconds. If no connection is established within this duration, the device enters non discoverable mode and advertising will have to be again enabled explicitly. The controller generates a EVT_LE_CONN_COMPLETE event with the status set to HCI_DIRECTED_ADV_TIMEOUT if the connection was not established and 0x00 if the connection was successfully established.

Usage example:

Parameters

own_addr_type	Type of our address used during advertising (PUBLIC_ADDR,STATIC_RANDOM_ADDR).
directed_adv_type	Type of directed advertising (HIGH_DUTY_CYCLE_DIRECTED_ADV, LOW_DUTY_CYCLE_DIRECTED_ADV).
initiator_addr_type	Type of peer address (PUBLIC_ADDR,STATIC_RANDOM_ADDR).
initiator_addr	Initiator's address (Little Endian).
adv_interv_min	Minimum advertising interval for low duty cycle directed advertising. Range: 0x0020 to 0x4000 Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec.
adv_interv_max	Maximum advertising interval for low duty cycle directed advertising. Range: 0x0020 to 0x4000 Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec.

Returns

Value indicating success or error code.

Put the Device in general discoverable mode (as defined in GAP specification volume 3, section 9.2.4).

Note

The device will be discoverable until the Host issue Aci_Gap_Set_Non_Discoverable command. The Adv_Interval_Min and Adv_Interval_Max parameters are optional. If both are set to 0, the GAP uses the default values for advertising intervals (1.28 s and 2.56 s respectively for IDB04A1). When using connectable undirected advertising events:

• Adv_Interval_Min = 30 ms
• Adv_Interval_Max = 60 ms using non-connectable advertising events or scannable undirected advertising events:
  
• Adv_Interval_Min = 100 ms
• Adv_Interval_Max = 150 ms Host can set the Local Name, a Service UUID list and the Slave Connection Interval Range. If provided, these data will be inserted into the advertising packet payload as AD data. These parameters are optional in this command. These values can be also set using aci_gap_update_adv_data() separately. The total size of data in advertising packet cannot exceed 31 bytes. With this command, the BLE Stack will also add automatically the following standard AD types:
• AD Flags
• TX Power Level

Usage example:

Parameters

AdvType	One of the advertising types: ADV_IND Connectable undirected advertising ADV_SCAN_IND Scannable undirected advertising ADV_NONCONN_IND Non connectable undirected advertising
AdvIntervMin	Minimum advertising interval. Range: 0x0020 to 0x4000 Default: 1.28 s Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec (minimum 100 ms for ADV_SCAN_IND or ADV_NONCONN_IND).
AdvIntervMax	Maximum advertising interval. Range: 0x0020 to 0x4000 Default: 2.56 s Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec (minimum 100 ms for ADV_SCAN_IND or ADV_NONCONN_IND).
OwnAddrType	Type of our address used during advertising (PUBLIC_ADDR,STATIC_RANDOM_ADDR).
AdvFilterPolicy	Filter policy: NO_WHITE_LIST_USE WHITE_LIST_FOR_ONLY_SCAN WHITE_LIST_FOR_ONLY_CONN WHITE_LIST_FOR_ALL
LocalNameLen	Length of LocalName array.
LocalName	Array containing the Local Name AD data. First byte is the AD type: AD_TYPE_SHORTENED_LOCAL_NAME or AD_TYPE_COMPLETE_LOCAL_NAME.
ServiceUUIDLen	Length of ServiceUUIDList array.
ServiceUUIDList	This is the list of the UUIDs AD Types as defined in Volume 3, Section 11.1.1 of GAP Specification. First byte is the AD Type. AD_TYPE_16_BIT_SERV_UUID AD_TYPE_16_BIT_SERV_UUID_CMPLT_LIST AD_TYPE_128_BIT_SERV_UUID AD_TYPE_128_BIT_SERV_UUID_CMPLT_LIST
SlaveConnIntervMin	Slave connection interval minimum value suggested by Peripheral. If SlaveConnIntervMin and SlaveConnIntervMax are not 0x0000, Slave Connection Interval Range AD structure will be added in advertising data. Connection interval is defined in the following manner: connIntervalmin = Slave_Conn_Interval_Min x 1.25ms Slave_Conn_Interval_Min range: 0x0006 to 0x0C80 Value of 0xFFFF indicates no specific minimum.
SlaveConnIntervMax	Slave connection interval maximum value suggested by Peripheral. If SlaveConnIntervMin and SlaveConnIntervMax are not 0x0000, Slave Connection Interval Range AD structure will be added in advertising data. ConnIntervalmax = Slave_Conn_Interval_Max x 1.25ms Slave_Conn_Interval_Max range: 0x0006 to 0x0C80 Slave_ Conn_Interval_Max shall be equal to or greater than the Slave_Conn_Interval_Min. Value of 0xFFFF indicates no specific maximum.

Return values

tBleStatus

Value indicating success or error code.

Set the IO capabilities of the device.

Note

This command has to be given only when the device is not in a connected state.

Parameters

io_capability

One of the allowed codes for IO Capability: IO_CAP_DISPLAY_ONLY IO_CAP_DISPLAY_YES_NO IO_CAP_KEYBOARD_ONLY IO_CAP_NO_INPUT_NO_OUTPUT IO_CAP_KEYBOARD_DISPLAY

Returns

Value indicating success or error code.

Put the device in limited discoverable mode (as defined in GAP specification volume 3, section 9.2.3).

Note

The device will be discoverable for TGAP (lim_adv_timeout) = 180 seconds. The advertising can be disabled at any time by issuing aci_gap_set_non_discoverable() command. The AdvIntervMin and AdvIntervMax parameters are optional. If both are set to 0, the GAP will use default values (250 ms and 500 ms respectively). Host can set the Local Name, a Service UUID list and the Slave Connection Minimum and Maximum. If provided, these data will be inserted into the advertising packet payload as AD data. These parameters are optional in this command. These values can be also set using aci_gap_update_adv_data() separately. The total size of data in advertising packet cannot exceed 31 bytes. With this command, the BLE Stack will also add automatically the following standard AD types:

• AD Flags
• TX Power Level

When advertising timeout happens (i.e. limited discovery period has elapsed), controller generates EVT_BLUE_GAP_LIMITED_DISCOVERABLE event.

Example:

Parameters

AdvType	One of the advertising types: ADV_IND Connectable undirected advertising ADV_SCAN_IND Scannable undirected advertising ADV_NONCONN_IND Non connectable undirected advertising
AdvIntervMin	Minimum advertising interval. Range: 0x0020 to 0x4000 Default: 250 ms Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec (minimum 100 ms for ADV_SCAN_IND or ADV_NONCONN_IND).
AdvIntervMax	Maximum advertising interval. Range: 0x0020 to 0x4000 Default: 500 ms Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec (minimum 100 ms for ADV_SCAN_IND or ADV_NONCONN_IND).
OwnAddrType	Type of our address used during advertising (PUBLIC_ADDR,STATIC_RANDOM_ADDR).
AdvFilterPolicy	Filter policy: NO_WHITE_LIST_USE WHITE_LIST_FOR_ONLY_SCAN WHITE_LIST_FOR_ONLY_CONN WHITE_LIST_FOR_ALL
LocalNameLen	Length of LocalName array.
LocalName	Array containing the Local Name AD data. First byte is the AD type: AD_TYPE_SHORTENED_LOCAL_NAME or AD_TYPE_COMPLETE_LOCAL_NAME.
ServiceUUIDLen	Length of ServiceUUIDList array.
ServiceUUIDList	This is the list of the UUIDs AD Types as defined in Volume 3, Section 11.1.1 of GAP Specification. First byte is the AD Type. AD_TYPE_16_BIT_SERV_UUID AD_TYPE_16_BIT_SERV_UUID_CMPLT_LIST AD_TYPE_128_BIT_SERV_UUID AD_TYPE_128_BIT_SERV_UUID_CMPLT_LIST
SlaveConnIntervMin	Slave connection interval minimum value suggested by Peripheral. If SlaveConnIntervMin and SlaveConnIntervMax are not 0x0000, Slave Connection Interval Range AD structure will be added in advertising data. Connection interval is defined in the following manner: connIntervalmin = Slave_Conn_Interval_Min x 1.25ms Slave_Conn_Interval_Min range: 0x0006 to 0x0C80 Value of 0xFFFF indicates no specific minimum.
SlaveConnIntervMax	Slave connection interval maximum value suggested by Peripheral. If SlaveConnIntervMin and SlaveConnIntervMax are not 0x0000, Slave Connection Interval Range AD structure will be added in advertising data. ConnIntervalmax = Slave_Conn_Interval_Max x 1.25ms Slave_Conn_Interval_Max range: 0x0006 to 0x0C80 Slave_ Conn_Interval_Max shall be equal to or greater than the Slave_Conn_Interval_Min. Value of 0xFFFF indicates no specific maximum.

Return values

tBleStatus

Value indicating success or error code.

Put the device into non-connectable mode.

Parameters

adv_type

One of the allowed advertising types: ADV_SCAN_IND : Scannable undirected advertising ADV_NONCONN_IND : Non-connectable undirected advertising

Returns

Value indicating success or error code.

Put the device into non-connectable mode.

Parameters

adv_type	One of the allowed advertising types: ADV_SCAN_IND : Scannable undirected advertising ADV_NONCONN_IND : Non-connectable undirected advertising
own_address_type	If Privacy is disabled, then the peripheral address can be PUBLIC_ADDR. STATIC_RANDOM_ADDR. If Privacy is enabled, then the peripheral address can be RESOLVABLE_PRIVATE_ADDR NON_RESOLVABLE_PRIVATE_ADDR

Returns

Value indicating success or error code.

Set the Device in non-discoverable mode.

Note

This command will disable the LL advertising.

Return values

tBleStatus

Value indicating success or error code.

Put the device into undirected connectable mode.

Note

If privacy is enabled in the device, a resolvable private address is generated and used as the advertiser's address. If not, the address of the type specified in own_addr_type is used for advertising.

Parameters

own_addr_type	Type of our address used during advertising: if BLUENRG (IDB04A1) PUBLIC_ADDR. STATIC_RANDOM_ADDR. else if BLUENRG_MS (IDB05A1) If Privacy is disabled: PUBLIC_ADDR. STATIC_RANDOM_ADDR. If Privacy is enabled: RESOLVABLE_PRIVATE_ADDR NON_RESOLVABLE_PRIVATE_ADDR
adv_filter_policy	Filter policy: NO_WHITE_LIST_USE WHITE_LIST_FOR_ALL

Returns

Value indicating success or error code.

Send a slave security request to the master.

Note

This command has to be issued to notify the master of the security requirements of the slave. The master may encrypt the link, initiate the pairing procedure, or reject the request.

Parameters

conn_handle	Connection handle
bonding	One of the bonding modes: BONDING NO_BONDING
mitm_protection	If MITM protection is required or not: MITM_PROTECTION_NOT_REQUIRED MITM_PROTECTION_REQUIRED

Returns

Value indicating success or error code.

Start the auto connection establishment procedure.

Note

The devices specified are added to the white list of the controller and a LE_Create_Connection call will be made to the controller by GAP with the initiator filter policy set to �use whitelist to determine which advertiser to connect to�. When a command is issued to terminate the procedure by upper layer, a LE_Create_Connection_Cancel call will be made to the controller by GAP. The procedure is terminated when either a connection is successfully established with one of the specified devices in the white list or the procedure is explicitly terminated by issuing the command aci_gap_terminate_gap_procedure() with the procedure code set to GAP_AUTO_CONNECTION_ESTABLISHMENT_PROC. A EVT_BLUE_GAP_PROCEDURE_COMPLETE event is returned with the procedure code set to GAP_AUTO_CONNECTION_ESTABLISHMENT_PROC.

Parameters

scanInterval	Time interval from when the Controller started its last LE scan until it begins the subsequent LE scan. The scan interval should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
scanWindow	Amount of time for the duration of the LE scan. Scan_Window shall be less than or equal to Scan_Interval. The scan window should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
own_bdaddr_type	Type of our address used during advertising (PUBLIC_ADDR,STATIC_RANDOM_ADDR).
conn_min_interval	Minimum value for the connection event interval. This shall be less than or equal to Conn_Interval_Max. Range: 0x0006 to 0x0C80 Time = N x 1.25 msec Time Range: 7.5 msec to 4 seconds
conn_max_interval	Maximum value for the connection event interval. This shall be greater than or equal to Conn_Interval_Min. Range: 0x0006 to 0x0C80 Time = N x 1.25 msec Time Range: 7.5 msec to 4 seconds
conn_latency	Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F4
supervision_timeout	Supervision timeout for the LE Link. Range: 0x000A to 0x0C80 Time = N x 10 msec Time Range: 100 msec to 32 seconds
min_conn_length	Minimum length of connection needed for the LE connection. Range: 0x0000 - 0xFFFF Time = N x 0.625 msec.
max_conn_length	Maximum length of connection needed for the LE connection. Range: 0x0000 - 0xFFFF Time = N x 0.625 msec.
num_whitelist_entries	Number of devices that have to be added to the whitelist.
addr_array	addr_array will contain the addresses that have to be added into the whitelist. The format of the addr_array should be: address type followed by address. Example: uint8_t addr_array[] = {PUBLIC_ADDR,0x01,0x00,0x00,0xe1,0x80,0x02, PUBLIC_ADDR,0x02,0x00,0x00,0xe1,0x80,0x02};

Returns

Value indicating success or error code.

Start the connection parameter update procedure.

Note

Allowed by the Central to update the connection parameter of the specified connection. A Link Layer Connection Update procedure is started on the controller. On completion of the procedure, a EVT_LE_CONN_UPDATE_COMPLETE event is returned to the upper layer.

Parameters

conn_handle	Handle of the connection for which the update procedure has to be started.
conn_min_interval	Minimum value for the connection event interval. This shall be less than or equal to Conn_Interval_Max. Range: 0x0006 to 0x0C80 Time = N x 1.25 msec Time Range: 7.5 msec to 4 seconds
conn_max_interval	Maximum value for the connection event interval. This shall be greater than or equal to Conn_Interval_Min. Range: 0x0006 to 0x0C80 Time = N x 1.25 msec Time Range: 7.5 msec to 4 seconds
conn_latency	Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F4
supervision_timeout	Supervision timeout for the LE Link. Range: 0x000A to 0x0C80 Time = N x 10 msec Time Range: 100 msec to 32 seconds
min_conn_length	Minimum length of connection needed for the LE connection. Range: 0x0000 - 0xFFFF Time = N x 0.625 msec.
max_conn_length	Maximum length of connection needed for the LE connection. Range: 0x0000 - 0xFFFF Time = N x 0.625 msec.

Returns

Value indicating success or error code.

Start a general connection establishment procedure.

Note

The host enables scanning in the controller with the scanner filter policy set to �accept all advertising packets� and from the scanning results all the devices are sent to the upper layer using the event EVT_BLUE_GAP_DEVICE_FOUND (for IDB04A1) or EVT_LE_ADVERTISING_REPORT (for IDB05A1). The upper layer then has to select one of the devices to which it wants to connect by issuing the command aci_gap_create_connection(). The procedure is terminated when a connection is established or the upper layer terminates the procedure by issuing the command aci_gap_terminate_gap_procedure() with the procedure code set to GAP_GENERAL_CONNECTION_ESTABLISHMENT_PROC. On completion of the procedure a EVT_BLUE_GAP_PROCEDURE_COMPLETE event is generated with the procedure code set to GAP_GENERAL_CONNECTION_ESTABLISHMENT_PROC.

Parameters

scan_type	Passive or active scanning (PASSIVE_SCAN, ACTIVE_SCAN)
scan_interval	Time interval from when the Controller started its last LE scan until it begins the subsequent LE scan. The scan interval should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
scan_window	Amount of time for the duration of the LE scan. Scan_Window shall be less than or equal to Scan_Interval. The scan window should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
own_address_type	Type of our address used during active scanning (PUBLIC_ADDR, STATIC_RANDOM_ADDR).
filter_duplicates	Duplicate filtering enabled or not. 0x00: Do not filter the duplicates 0x01: Filter duplicates

Returns

Value indicating success or error code.

Start the general discovery procedure.

Note

The controller is commanded to start active scanning. The procedure is terminated when either the upper layers issue a command to terminate the procedure by issuing the command aci_gap_terminate_gap_procedure() with the procedure code set to GAP_GENERAL_DISCOVERY_PROC or a timeout happens. When the procedure is terminated due to any of the above reasons, EVT_BLUE_GAP_PROCEDURE_COMPLETE event is returned with the procedure code set to GAP_GENERAL_DISCOVERY_PROC. The device found when the procedure is ongoing is returned to the upper layers through the event EVT_BLUE_GAP_DEVICE_FOUND (for IDB04A1) or EVT_LE_ADVERTISING_REPORT (for IDB05A1).

Parameters

scanInterval	Time interval from when the Controller started its last LE scan until it begins the subsequent LE scan. The scan interval should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
scanWindow	Amount of time for the duration of the LE scan. Scan_Window shall be less than or equal to Scan_Interval. The scan window should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
own_address_type	Type of our address used during advertising (PUBLIC_ADDR, STATIC_RANDOM_ADDR).
filterDuplicates	Duplicate filtering enabled or not. 0x00: Do not filter the duplicates 0x01: Filter duplicates

Returns

Value indicating success or error code.

Start the limited discovery procedure.

Note

The controller is commanded to start active scanning. When this procedure is started, only the devices in limited discoverable mode are returned to the upper layers. The procedure is terminated when either the upper layers issue a command to terminate the procedure by issuing the command aci_gap_terminate_gap_procedure() with the procedure code set to GAP_LIMITED_DISCOVERY_PROC or a timeout happens. When the procedure is terminated due to any of the above reasons, EVT_BLUE_GAP_PROCEDURE_COMPLETE event is returned with the procedure code set to GAP_LIMITED_DISCOVERY_PROC. The device found when the procedure is ongoing is returned to the upper layers through the event EVT_BLUE_GAP_DEVICE_FOUND (for IDB04A1) or EVT_LE_ADVERTISING_REPORT (for IDB05A1).

Parameters

scanInterval	Time interval from when the Controller started its last LE scan until it begins the subsequent LE scan. The scan interval should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
scanWindow	Amount of time for the duration of the LE scan. Scan_Window shall be less than or equal to Scan_Interval. The scan window should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
own_address_type	Type of our address used during advertising (PUBLIC_ADDR, STATIC_RANDOM_ADDR).
filterDuplicates	Duplicate filtering enabled or not. 0x00: Do not filter the duplicates 0x01: Filter duplicates

Returns

Value indicating success or error code.

Start the name discovery procedure.

Note

A LE_Create_Connection call will be made to the controller by GAP with the initiator filter policy set to �ignore whitelist and process connectable advertising packets only for the specified device�. Once a connection is established, GATT procedure is started to read the device name characteristic. When the read is completed (successfully or unsuccessfully), a EVT_BLUE_GAP_PROCEDURE_COMPLETE event is given to the upper layer. The event also contains the name of the device if the device name was read successfully.

Parameters

scanInterval	Time interval from when the Controller started its last LE scan until it begins the subsequent LE scan. The scan interval should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
scanWindow	Amount of time for the duration of the LE scan. Scan_Window shall be less than or equal to Scan_Interval. The scan window should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
peer_bdaddr_type	Type of the peer address (PUBLIC_ADDR, STATIC_RANDOM_ADDR).
peer_bdaddr	Address of the peer device with which a connection has to be established.
own_bdaddr_type	Type of our address used during advertising (PUBLIC_ADDR,STATIC_RANDOM_ADDR).
conn_min_interval	Minimum value for the connection event interval. This shall be less than or equal to Conn_Interval_Max. Range: 0x0006 to 0x0C80 Time = N x 1.25 msec Time Range: 7.5 msec to 4 seconds
conn_max_interval	Maximum value for the connection event interval. This shall be greater than or equal to Conn_Interval_Min. Range: 0x0006 to 0x0C80 Time = N x 1.25 msec Time Range: 7.5 msec to 4 seconds
conn_latency	Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F4
supervision_timeout	Supervision timeout for the LE Link. Range: 0x000A to 0x0C80 Time = N x 10 msec Time Range: 100 msec to 32 seconds
min_conn_length	Minimum length of connection needed for the LE connection. Range: 0x0000 - 0xFFFF Time = N x 0.625 msec.
max_conn_length	Maximum length of connection needed for the LE connection. Range: 0x0000 - 0xFFFF Time = N x 0.625 msec.

Returns

Value indicating success or error code.

Starts an observation procedure, when the device is in Observer role.

Note

The host enables scanning in the controller. The advertising reports are sent to the upper layer using standard EVT_LE_ADVERTISING_REPORT subevent in EVT_LE_META_EVENT. See Bluetooth Core v4.0, Vol. 2, part E, Ch. 7.7.65.2, LE Advertising Report Event.

Parameters

scan_interval	Time interval from when the Controller started its last LE scan until it begins the subsequent LE scan. The scan interval should be a number in the range 0x0004 to 0x4000. This corresponds to a time range from 2.5 msec to 10240 msec. For a number N, Time = N * 0.625 msec.
scan_window	Amount of time for the duration of the LE scan. scan_window shall be less than or equal to scan_interval. The scan window should be a number in the range 0x0004 to 0x4000. This corresponds to a time range from 2.5 msec to 10240 msec. For a number N, Time = N * 0.625 msec.
scan_type	Passive or active scanning (PASSIVE_SCAN, ACTIVE_SCAN)
own_address_type	If Privacy is disabled, then the scanner address can be PUBLIC_ADDR. STATIC_RANDOM_ADDR. If Privacy is enabled, then the scanner address can be RESOLVABLE_PRIVATE_ADDR NON_RESOLVABLE_PRIVATE_ADDR
filter_duplicates	Duplicate filtering enabled or not. 0x00: Do not filter the duplicates 0x01: Filter duplicates

Returns

Value indicating success or error code.

Start a selective connection establishment procedure.

Note

The GAP adds the specified device addresses into white list and enables scanning in the controller with the scanner filter policy set to �accept packets only from devices in whitelist�. All the devices found are sent to the upper layer by the event EVT_BLUE_GAP_DEVICE_FOUND (for IDB04A1) or EVT_LE_ADVERTISING_REPORT (for IDB05A1). The upper layer then has to select one of the devices to which it wants to connect by issuing the command aci_gap_create_connection(). On completion of the procedure a EVT_BLUE_GAP_PROCEDURE_COMPLETE event is generated with the procedure code set to GAP_SELECTIVE_CONNECTION_ESTABLISHMENT_PROC. The procedure is terminated when a connection is established or the upper layer terminates the procedure by issuing the command aci_gap_terminate_gap_procedure with the procedure code set to GAP_SELECTIVE_CONNECTION_ESTABLISHMENT_PROC.

Parameters

scan_type	Passive or active scanning (PASSIVE_SCAN, ACTIVE_SCAN)
scan_interval	Time interval from when the Controller started its last LE scan until it begins the subsequent LE scan. The scan interval should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
scan_window	Amount of time for the duration of the LE scan. Scan_Window shall be less than or equal to Scan_Interval. The scan window should be a number in the range 0x0004 to 0x4000. This corresponds to a time range 2.5 msec to 10240 msec. For a number N, Time = N x 0.625 msec.
own_address_type	Type of our address used during active scanning (PUBLIC_ADDR, STATIC_RANDOM_ADDR).
filter_duplicates	Duplicate filtering enabled or not. 0x00: Do not filter the duplicates 0x01: Filter duplicates
num_whitelist_entries	Number of devices that have to be added to the whitelist.
addr_array	addr_array will contain the addresses that have to be added into the whitelist. The format of the addr_array should be: address type followed by address. Example: uint8_t addr_array[] = {PUBLIC_ADDR,0x01,0x00,0x00,0xe1,0x80,0x02, PUBLIC_ADDR,0x02,0x00,0x00,0xe1,0x80,0x02};

Returns

Value indicating success or error code.

Terminate a connection.

Note

A EVT_DISCONN_COMPLETE event will be generated when the link is disconnected.

Parameters

conn_handle	Connection handle
reason	Reason for requesting disconnection. The error code can be any of ones as specified for the disconnected command in the HCI specification (See HCI Error codes).

Returns

Value indicating success or error code.

Terminate the specified GAP procedure. EVT_BLUE_GAP_PROCEDURE_COMPLETE event is returned with the procedure code set to the corresponding procedure.

Parameters

procedure_code

One of the procedure codes (GAP procedure codes).

Returns

Value indicating success or error code.

Update advertising data.

Note

This command can be used to update the advertising data for a particular AD type. If the AD type specified does not exist, then it is added to the advertising data. If the overall advertising data length is more than 31 octets after the update, then the command is rejected and the old data is retained.

Parameters

AdvLen

Length of AdvData array

AdvData

Advertisement Data, formatted as specified in Bluetooth specification (Volume 3, Part C, 11), including data length. It can contain more than one AD type. Example tBleStatus ret; const char local_name[] = {AD_TYPE_COMPLETE_LOCAL_NAME,'B','l','u','e','N','R','G'}; const uint8_t serviceUUIDList[] = {AD_TYPE_16_BIT_SERV_UUID,0x34,0x12}; const uint8_t manuf_data[] = {4, AD_TYPE_MANUFACTURER_SPECIFIC_DATA, 0x05, 0x02, 0x01}; ret = aci_gap_set_discoverable(ADV_IND, 0, 0, STATIC_RANDOM_ADDR, NO_WHITE_LIST_USE, 8, local_name, 3, serviceUUIDList, 0, 0); ret = aci_gap_update_adv_data(5, manuf_data);

Returns

Value indicating success or error code.