Gap Struct Reference

Accept connection parameter request.

This command sends a positive response to a connection parameter request from a peer.

Parameters:

connection	Handle of the connection.
connection_interval_min	Minimum interval between two connection events allowed for the connection. It shall be less than or equal to connection_interval_max. This value shall be in range [0x0006 : 0x0C80] and is in unit of 1.25ms.
connection_interval_max	Maximum interval between two connection events allowed for the connection. It shall be greater than or equal to connection_interval_min. This value shall be in range [0x0006 : 0x0C80] and is in unit of 1.25ms.
connection_latency	Number of connection events the slave can drop if it has nothing to communicate to the master. This value shall be in the range [0x0000 : 0x01F3].
supervision_timeout	Link supervision timeout for the connection. It shall be larger than: (1 + connection_latency) * connection_interval_max * 2 Note: connection_interval_max is in ms in this formulae. Everytime the master or the slave receive a valid packet from the peer, the supervision timer is reset. If the supervision timer reaches supervision_timeout then the connection is considered lost and a disconnect event shall be emmited. This value shall be in the range [0x000A : 0x0C80] and is in unit of 10 ms.
minimum_connection_event_length	Informative parameter of the minimum length a connection event. It shall be less than or equal to maximum_connection_event_length. It shall be in the range [0x0000 : 0xFFFF]. It should also be less than the expected connection interval. The unit is 0.625ms.
maximum_connection_event_length	Informative parameter of the maximum length a connection event. It shall be more than or equal to minimum_connection_event_length. It shall be in the range [0x0000 : 0xFFFF]. It should also be less than the expected connection interval. The unit is 0.625ms.

Note:

Usually parameters of this function match the connection parameters received in the connection parameter request event.

: Once the new connection parameters are in used a Connection Update Complete event shall be emmited.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.31 LE remote connection parameter request reply command.

Add a device to the LE subsystem Whitelist.

Parameters:

address_type	address_type Type of the address to add in the whitelist.
address	Address of the device.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

This command shall not be issued if the whitelist is being used by the advertising, scanning or connection creation procedure.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.16 LE add device to white list command.

Start or stop advertising.

The process use advertising and scan response data set with set_advertising_data and set_scan_response_data while the parameters used are the one set by set_advertising_parameters.

The advertising shall continue until:

• The advertising is manually disabled (advertising_enable(false)).
• A connection is created.
• Time out in case of high duty cycle directed advertising.

If the random address has not been set and the advertising parameter own_address_type is set to 0x01 then the procedure shall fail.

If the random address has not been set and the advertising parameter own_address_type is set to RESOLVABLE_PRIVATE_ADDRESS_RANDOM_FALLBACK and the peer address is not in the resolving list then the procedure shall fail.

Parameters:

enable

If true start the advertising process, if the process was already runing and own_address_type is equal to 0x02 or 0x03, the subsystem can change the random address. If false and the advertising is running then the process should be stoped.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.9 LE set advertising enable command.

If the advertising type is ADV_DIRECT_IND and the connection is not created during the time allowed to the procedure then a ConnectionComplete event shall be emmited with its error code set to ADVERTISING_TIMEOUT.

Successfull connection shall emit a ConnectionComplete event. It also means advertising is disabled.

Cancel the ongoing connection creation process.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.13 LE create connection cancel command.

Clear the whitelist stored in the LE subsystem.

This command shall not be issued if the whitelist is being used by the advertising, scanning or connection creation procedure.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.15 LE clear white list command.

Start a connection update procedure.

This procedure change the parameter used for a connection it can be master or slave initiated.

The peer will received a connection parameters request and will either accept or reject the new parameters for the connection.

Once the peer response has been received, the procedure ends and a Connection update complete event is emmited.

Parameters:

connection	Handle of the connection.
connection_interval_min	Minimum interval between two connection events allowed for the connection. It shall be less than or equal to connection_interval_max. This value shall be in range [0x0006 : 0x0C80] and is in unit of 1.25ms.
connection_interval_max	Maximum interval between two connection events allowed for the connection. It shall be greater than or equal to connection_interval_min. This value shall be in range [0x0006 : 0x0C80] and is in unit of 1.25ms.
connection_latency	Number of connection events the slave can drop if it has nothing to communicate to the master. This value shall be in the range [0x0000 : 0x01F3].
supervision_timeout	Link supervision timeout for the connection. It shall be larger than: (1 + connection_latency) * connection_interval_max * 2 Note: connection_interval_max is in ms in this formulae. Everytime the master or the slave receive a valid packet from the peer, the supervision timer is reset. If the supervision timer reaches supervision_timeout then the connection is considered lost and a disconnect event shall be emmited. This value shall be in the range [0x000A : 0x0C80] and is in unit of 10 ms.
minimum_connection_event_length	Informative parameter of the minimum length a connection event. It shall be less than or equal to maximum_connection_event_length. It shall be in the range [0x0000 : 0xFFFF]. It should also be less than the expected connection interval. The unit is 0.625ms.
maximum_connection_event_length	Informative parameter of the maximum length a connection event. It shall be more than or equal to minimum_connection_event_length. It shall be in the range [0x0000 : 0xFFFF]. It should also be less than the expected connection interval. The unit is 0.625ms.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.18 LE Connection update command.

Create a new le connection to a connectable advertiser.

Parameters:

scan_interval	Hint to the le subsystem indicating how frequently it should scan for the peer address. It represent the time interval between two subsequent scan for the peer. It shall be in the range [0x0004 : 0x4000] and the time is in unit of 0.625ms.
scan_window	Hint to the le subsystem indicating for how long it should scan during a scan interval. The value shall be smaller or equal to scan_interval. If it is equal to scan_interval then scanning should run continuously. It shall be in the range [0x0004 : 0x4000] and the time is in unit of 0.625ms.
initiator_policy	Used to determine if the whitelist is used to determine the address to connect to. If the whitelist is not used, the connection shall be made against an advertiser matching the peer_address and the peer_address_type parameters. Otherwise those parameters are ignored.
peer_address_type	Type of address used by the advertiser. Not used if initiator_policy use the whitelist.
Address	used by the advertiser in its advertising packets. Not used if initiator_policy use the whitelist.
own_address_type	Type of address used in the connection request packet.
connection_interval_min	Minimum interval between two connection events allowed for the connection. It shall be less than or equal to connection_interval_max. This value shall be in range [0x0006 : 0x0C80] and is in unit of 1.25ms.
connection_interval_max	Maximum interval between two connection events allowed for the connection. It shall be greater than or equal to connection_interval_min. This value shall be in range [0x0006 : 0x0C80] and is in unit of 1.25ms.
connection_latency	Number of connection events the slave can drop if it has nothing to communicate to the master. This value shall be in the range [0x0000 : 0x01F3].
supervision_timeout	Link supervision timeout for the connection. It shall be larger than: (1 + connection_latency) * connection_interval_max * 2 Note: connection_interval_max is in ms in this formulae. Everytime the master or the slave receive a valid packet from the peer, the supervision timer is reset. If the supervision timer reaches supervision_timeout then the connection is considered lost and a disconnect event shall be emmited. This value shall be in the range [0x000A : 0x0C80] and is in unit of 10 ms.
minimum_connection_event_length	Informative parameter of the minimum length a connection event. It shall be less than or equal to maximum_connection_event_length. It shall be in the range [0x0000 : 0xFFFF]. It should also be less than the expected connection interval. The unit is 0.625ms.
maximum_connection_event_length	Informative parameter of the maximum length a connection event. It shall be more than or equal to minimum_connection_event_length. It shall be in the range [0x0000 : 0xFFFF]. It should also be less than the expected connection interval. The unit is 0.625ms.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.12 LE create connection command.

Start a disconnection procedure.

Once the procedure is complete it should emit a disconnection complete event.

Parameters:

connection	Handle of the connection to terminate.
disconnection_reason	Indicates the reason for ending the connection.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.1.6 disconenct command.

Implementation shall call this function whenever the LE subsystem generate a Gap event.

Parameters:

gap_event

The event to emit to higher layer.

Definition at line 675 of file PalGap.h.

Return the public device address.

Note:

The public device address is usually acquired at initialization and stored in the instance.

Returns:

the public device address.

Return the current random address.

Note:

The random address is usually acquired at initialization and stored in the instance.

Returns:

the random device address.

Initialisation of the instance.

An implementation can use this function to initialise the subsystems needed to realize the operations of this interface.

This function has to be called before any other operations.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Return the number of total whitelist entries that can be stored in the le subsystem.

Note:

The value returned can change over time.

Returns:

The number of entries that can be stored in the LE subsystem. It range from 0x01 to 0xFF.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.14 LE read white list size command.

Reject a connection parameter update request.

Parameters:

connection_handle	handle to the peer which has issued the connection parameter request.
rejection_reason	Indicate to the peer why the proposed connection parameters were rejected.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.32 LE Remote Connection Parameter Request Negative Reply Command.

Remove a device from the LE subsystem Whitelist.

Parameters:

address_type	address_type Type of the address of the device to remove from the whitelist.
address	Address of the device to remove from the whitelist

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

This command shall not be issued if the whitelist is being used by the advertising, scanning or connection creation procedure.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.17 LE remove device from white list command.

Start/stop scanning process.

Parameters of the scanning process shall be set before the scan launch by using the function set_scan_parameters.

enable Start the scanning process if true and stop it if false. If the scan process is already started, enabling it again will only update the duplicate filtering; based on the new parameter.

filter_duplicates Enable duplicate filtering if true, otherwise disable it.

advertising data or scan response data is not considered significant when determining duplicate advertising reports.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.11 LE set scan enable command.

Set the data sends in advertising packet.

If the advertising is currently enabled, the data shall be used when a new advertising packet is issued.

Parameters:

advertising_data_length	Number of significant bytes in the advertising data.
advertising_data	The data sends in advertising packets. Non significant bytes shall be equal to 0.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.5 LE set advertising data command.

Set the advertising parameters which will be used during the advertising process.

Parameters:

advertising_interval_min,:	Minimum advertising interval which can be used during undirected and low duty cycle directed advertising. This parameter shall be less than or equal to advertising_interval_max. This parameter shall be in the range [0x20 : 0x4000] where each unit is equal to 0.625ms. This parameter is not used by directed high duty cycle advertising.
advertising_interval_max,:	Maximum advertising interval which can be used during undirected and low duty cycle directed advertising. This parameter shall be more than or equal to advertising_interval_min. This parameter shall be in the range [0x20 : 0x4000] where each unit is equal to 0.625ms. This parameter is not used by directed high duty cycle advertising.
advertising_type	Packet type that is used during the advertising process. Direct advertising require valid peer addresses parameters and ignore the filter policy set. If the High duty cycle advertising is used then the advertising parameter intervals are ignored.
own_address_type	Own address type used during advertising. If own address type is equal to RESOLVABLE_PRIVATE_ADDRESS_PUBLIC_FALLBACK or RESOLVABLE_PRIVATE_ADDRESS_RANDOM_FALLBACK then the peer address parameters (type and address) will be used to find the local IRK.
peer_address_type	Address type of the peer. This parameter shall be valid if directed advertising is used ( ADV_DIRECT_IND or ADV_DIRECT_IND_LOW_DUTY_CYCLE). This parameter should be valid if the own address type is equal to 0x02 or 0x03. In other cases, this parameter is ignored.
peer_address	Public device address, Random device addres, Public identity address or Random static identity address of the device targeted by the advertising. This parameter shall be valid if directed advertising is used ( ADV_DIRECT_IND or ADV_DIRECT_IND_LOW_DUTY_CYCLE). This parameter should be valid if the own address type is equal to 0x02 or 0x03. In other cases, this parameter is ignored.
advertising_channel_map	Map of the channel used to send advertising data.
advertising_filter_policy	Filter policy applied during the advertising process. The subsystem should use the whitelist to apply the policy. This parameter is ignored if the advertising type is directed ( ADV_DIRECT_IND or ADV_DIRECT_IND_LOW_DUTY_CYCLE).

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.5 LE set advertising parameters command.

Set the random address which will used be during scan, connection or advertising process if the own address type selected is random.

Changing the address during scan, connection or advertising process is forbiden.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.4 LE set random address command.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Set the parameter of the scan process.

This command shall not be effective when the scanning process is running.

Parameters:

active_scanning	If true the subsystem does active scanning and the bluetooth subsystem shall send scanning PDUs. It shall also listen to scan responses. If false no scanning PDUs are sent during the scan process.
scan_interval	The time interval between two subsequent LE scans in unit of 0.625ms. This parameter shall be in the range [0x0004 : 0x4000].
scan_window	Duration of the LE scan. It shall be less than or equal to scan_interval value. This parameter shall be in the range [0x0004 : 0x4000] and is in unit of 0.625ms.
own_address_type	Own address type used in scan request packets.
filter_policy	Filter policy applied when scanning.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.10 LE set scan parameters command.

Set the data sends in scan response packets.

If the advertising is currently enabled, the data shall be used when a new scan response is issued.

Parameters:

scan_response_data_length	Number of significant bytes in the scan response data.
scan_response_data	The data sends in scan response packets. Non significant bytes shall be equal to 0.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Note:

: See Bluetooth 5 Vol 2 PartE: 7.8.8 LE set scan response data command.

Termination of the instance.

An implementation can use this function to release the subsystems initialised to realise the operations of this interface.

After a call to this function, initialise should be called again to allow use of the interface.

Returns:

BLE_ERROR_NONE if the request has been successfully sent or the appropriate error otherwise.

Register a callback which will handle Gap events.

Parameters:

cb	The callback object which will handle Gap events from the LE subsystem. It accept a single parameter in input: The event received.

Definition at line 659 of file PalGap.h.