ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add PAL declaration for extended and periodic advertising

pull/8738/head
Vincent Coubard 2018-11-06 14:11:08 +00:00
parent ff68c94ec2
commit 74cf305452
2 changed files with 1248 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

414
features/FEATURE_BLE/ble/pal/GapTypes.h
View File

@ -409,7 +409,6 @@ struct initiator_policy_t : SafeEnum<initiator_policy_t, uint8_t> {
SafeEnum<initiator_policy_t, uint8_t>(value) { }
};
/**
* Hold advertising data.
*/
@ -531,6 +530,419 @@ struct connection_role_t : SafeEnum<connection_role_t, uint8_t> {
connection_role_t(type value) : SafeEnum<connection_role_t, uint8_t>(value) { }
};
/**
* Handle of an advertising set.
*
* @note Range of valid handle is comprised between 0x00 and 0xEF.
*/
typedef uint8_t advertising_handle_t;
/**
* Properties of an advertising event.
*/
struct advertising_event_properties_t {
/**
* Default constructor, all fields sets to 0.
*/
advertising_event_properties_t() :
connectable(false),
scannable(false),
directed(false),
high_duty_cycle(false),
use_legacy_pdu(false),
omit_advertisser_address(false),
include_tx_power(false)
{ }
/**
* Construct an advertising_event_properties_t with all fields defined by
* user.
* @param connectable @see advertising_event_properties_t::connectable
* @param scannable @see advertising_event_properties_t::scannable
* @param directed @see advertising_event_properties_t::directed
* @param high_duty_cycle @see advertising_event_properties_t::high_duty_cycle
* @param use_legacy_pdu @see advertising_event_properties_t::use_legacy_pdu
* @param omit_advertisser_address @see
* advertising_event_properties_t::omit_advertiser_address
* @param include_tx_power
* @see advertising_event_properties_t::include_tx_power
*/
advertising_event_properties_t(
bool connectable,
bool scannable,
bool directed,
bool high_duty_cycle,
bool use_legacy_pdu,
bool omit_advertisser_address,
bool include_tx_power
) :
connectable(connectable),
scannable(scannable),
directed(directed),
high_duty_cycle(high_duty_cycle),
use_legacy_pdu(use_legacy_pdu),
omit_advertisser_address(omit_advertisser_address),
include_tx_power(include_tx_power)
{ }
/**
* Construct an advertising_event_property_t from a legacy advertising_type_t.
*
* @param adv_type The legacy advertising type to convert into an
* advertising_event_properties_t.
*
* @note Conversion table can be found in table 7.2 of BLUETOOTH
* SPECIFICATION Version 5.0 | Vol 2, Part E - 7.8.53 .
*/
advertising_event_properties_t(advertising_type_t adv_type)
{
switch ((advertising_type_t::type) adv_type.value()) {
case advertising_type_t::ADV_IND:
connectable = true;
scannable = true;
use_legacy_pdu = true;
break;
case advertising_type_t::ADV_DIRECT_IND:
connectable = true;
directed = true;
use_legacy_pdu = true;
break;
case advertising_type_t::ADV_DIRECT_IND_LOW_DUTY_CYCLE:
connectable = true;
directed = true;
high_duty_cycle = true;
use_legacy_pdu = true;
break;
case advertising_type_t::ADV_SCAN_IND:
scannable = true;
use_legacy_pdu = true;
break;
case advertising_type_t::ADV_NONCONN_IND:
use_legacy_pdu = true;
break;
}
}
/**
* If set the advertising event is connectable.
*/
bool connectable :1;
/**
* If set the advertising event is scannable.
*/
bool scannable :1;
/**
* If set the advertising event targets a specific device.
*/
bool directed :1;
/**
* If set the directed advertising event operate at a high duty cycle.
*/
bool high_duty_cycle :1;
/**
* If set advertising packets use legacy advertising PDU format and the
* members omit_advertisser_address and include_tx_power are ignored.
* If not set then:
* - The advertisement can't be both connectable and scannable.
* - High duty cycle directed connectable advertising can't be use.
*/
bool use_legacy_pdu :1;
/**
* If set omit the advertiser address in all PDUs.
*/
bool omit_advertisser_address :1;
/**
* If set include the Tx power in the extended advertising header.
*/
bool include_tx_power :1;
/**
* Construct the value expected by a BT controller.
* @return All fields in a uint16_t understandable by BT stacks.
*/
uint16_t value() {
uint16_t result = 0;
result |= connectable << 0;
result |= scannable << 1;
result |= directed << 2;
result |= high_duty_cycle << 3;
result |= use_legacy_pdu << 4;
result |= omit_advertisser_address << 5;
result |= include_tx_power << 6;
return result;
}
};
/**
* Describe advertising interval for undirected and low duty cycle directed
* advertising.
*
* The value is not expressed in seconds; one unit is equal to 0.625ms.
*
* The value range is comprised between 0x20 and 0xFFFFFF which translate into
* 20ms to 10,485.759375s .
*/
typedef uint32_t advertising_interval_t;
/**
* Describe the advertising power.
*
* Value comprised between -127 and +126 are considered power values in dBm while
* the special value 127 can be used as a wildcard to indicates that the host
* has no preference or if the power informtion is not available.
*/
typedef int8_t advertising_power_t;
/**
* Describe advertising interval for periodic advertising
*
* The value is not expressed in seconds; one unit is equal to 1.25ms.
*
* The value range is comprised between 0x6 and 0xFFFF which translate into
* 7.5ms to 81.91875 s .
*/
typedef uint16_t periodic_advertising_interval_t;
// Range -127 <= N <= +20
// Special value: 127
// - RSSI not available.
typedef int8_t rssi_t;
/**
* Description of an advertising fragment.
*/
struct advertising_fragment_description_t :
SafeEnum<advertising_fragment_description_t, uint8_t >{
enum type {
/**
* Intermediate fragment of fragmented extended advertising data.
*/
INTERMEDIATE_FRAGMENT = 0x00,
/**
* First fragment of fragmented extended advertising data.
*
* @note If use, it discard existing fragments.
*/
FIRST_FRAGMENT = 0x01,
/**
* Last fragment of fragmented extended advertising data.
*/
LAST_FRAGMENT = 0x02,
/**
* Complete extended advertising data. This is also used for legacy
* advertising data.
*
* @note If use, it discard existing fragments.
*/
COMPLETE_FRAGMENT = 0x03,
/**
* Used to update the advertising DID.
*
* @note should not be used if advertising is disabled o
*/
UNCHANGED_DATA = 0x04
};
/**
* Construct a new advertising_fragment_description_t value.
*/
advertising_fragment_description_t(type value) :
SafeEnum<advertising_fragment_description_t, uint8_t>(value) { }
};
struct duplicates_filter_t : SafeEnum<duplicates_filter_t, uint8_t >{
enum type {
/**
* Disable duplicate filtering.
*/
DISABLE,
/**
* Enable duplicate filtering.
*/
ENABLE,
/**
* Enable duplicate filtering, reset the cache periodicaly.
*/
PERIODIC_RESET
};
/**
* Construct a new duplicates_filter_t value.
*/
duplicates_filter_t(type value) :
SafeEnum<duplicates_filter_t, uint8_t>(value) { }
};
/**
* Identify a periodic advertising sync.
*/
typedef uint16_t sync_handle_t;
/**
* Identify an advertising SID. Range: [0x00, 0x0F]
*/
typedef uint8_t advertising_sid_t;
struct advertising_data_status_t : SafeEnum<advertising_data_status_t, uint8_t >{
enum type {
COMPLETE = 0x00,
INCOMPLETE_MORE_DATA = 0x01,
INCOMPLETE_DATA_TRUNCATED = 0x02
};
/**
* Construct a new duplicates_filter_t value.
*/
advertising_data_status_t(type value) :
SafeEnum<advertising_data_status_t, uint8_t>(value) { }
};
struct extended_advertising_report_event_type_t {
extended_advertising_report_event_type_t(uint8_t value) : value(value) { }
bool connectable() {
return value & (1 << 0);
}
bool scannable_advertising() {
return value & (1 << 1);
}
bool directed_advertising() {
return value & (1 << 2);
}
bool scan_response() {
return value & (1 << 3);
}
bool legacy_advertising() {
return value & (1 << 4);
}
advertising_data_status_t data_status() {
return static_cast<advertising_data_status_t::type>((value >> 5) & 0x03);
}
bool complete() {
return data_status() == advertising_data_status_t::COMPLETE;
}
bool more_data_to_come() {
return data_status() == advertising_data_status_t::INCOMPLETE_MORE_DATA;
}
bool truncated() {
return data_status() == advertising_data_status_t::INCOMPLETE_DATA_TRUNCATED;
}
private:
uint8_t value;
};
struct direct_address_type_t : SafeEnum<direct_address_type_t, uint8_t> {
enum type {
/**
* Public device address
*/
PUBLIC_ADDRESS = 0x00,
/**
* Random device address
*/
RANDOM_ADDRESS = 0x01,
/**
* Public identity address.
* @note remove once privacy mode is supported.
*/
PUBLIC_IDENTITY_ADDRESS = 0x02,
/**
* Random (static) identity address.
* @note remove once privacy mode is supported.
*/
RANDOM_IDENTITY_ADDRESS = 0x03,
/**
* Random device address; controller unable to resolve.
*/
RANDOM_DEVICE_ADDRESS = 0xFE
};
/**
* Construct a new direct_address_type_t instance.
*/
direct_address_type_t(type value) :
SafeEnum<direct_address_type_t, uint8_t>(value) { }
};
/**
* Accuracy of the master clock.
*/
struct clock_accuracy_t : SafeEnum<clock_accuracy_t, uint8_t >{
enum type {
/**
* 500 PPM
*/
PPM_500 = 0x00,
/**
* 250 PPM
*/
PPM_250 = 0x01,
/**
* 150 PPM
*/
PPM_150 = 0x02,
/**
* 100 PPM
*/
PPM_100 = 0x03,
/**
* 75 PPM
*/
PPM_75 = 0x04,
/**
* 50 PPM
*/
PPM_50 = 0x05,
/**
* 30 PPM
*/
PPM_30 = 0x06,
/**
* 20 PPM
*/
PPM_20 = 0x07
};
/**
* Construct a new clock_accuracy_t value.
*/
clock_accuracy_t(type value) : SafeEnum<clock_accuracy_t, uint8_t>(value) { }
};
} // namespace pal
} // namespace ble

835
features/FEATURE_BLE/ble/pal/PalGap.h
View File

@ -80,6 +80,176 @@ struct Gap {
ble::phy_t tx_phy,
ble::phy_t rx_phy
) = 0;
/**
* Should be invoked by the Gap implementation when an enhanced
* connection complete event happens.
*
* @param status hci_error_code::SUCCESS in case of success or an error
* code.
*
* @param connection_handle The handle of the connection created.
*
* @param own_role Indicate if the local device operates as slave or
* master.
*
* @param peer_address_type Type of address of the peer.
*
* @param peer_address Address of the peer connected.
*
* @param local_resolvable_private_address Resolvable private address
* being used by the controller. If not applicable, the address is full
* of zeroes.
*
* @param peer_resolvable_private_address Resolvable private address
* being used by the peer. If not applicable, the address is full of
* zeroes.
*
* @param connection_interval Interval between two connection events.
* Unit is 1.25ms.
*
* @param connection_latency Slave latency for the connection in number
* of connection events.
*
* @param supervision_timeout Connection supervision timeout. Unit is
* 10ms.
*
* @param master_clock_accuracy This parameter is only valid for a slave.
* On a master it must be set to 0x00.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.10 LE enhanced connection
* complete event.
*/
virtual void on_enhanced_connection_complete(
hci_error_code_t status,
connection_handle_t connection_handle,
connection_role_t own_role,
connection_peer_address_type_t peer_address_type,
const address_t &peer_address,
const address_t &local_resolvable_private_address,
const address_t &peer_resolvable_private_address,
uint16_t connection_interval,
uint16_t connection_latency,
uint16_t supervision_timeout,
clock_accuracy_t master_clock_accuracy
) = 0;
/**
* Should be invoked by the Gap implementation when an extended
* advertising report event happens.
*
* @param event_type
* @param address_type
* @param address
* @param primary_phy
* @param secondary_phy
* @param advertising_sid
* @param tx_power
* @param rssi
* @param periodic_advertising_interval
* @param direct_address_type
* @param direct_address
* @param data_length
* @param data_size
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.13 LE extended advertising
* report event.
*/
virtual void on_extended_advertising_report(
extended_advertising_report_event_type_t event_type,
const connection_peer_address_type_t *address_type,
const address_t &address,
phy_t primary_phy,
const phy_t *secondary_phy,
advertising_sid_t advertising_sid,
advertising_power_t tx_power,
rssi_t rssi,
uint16_t periodic_advertising_interval,
direct_address_type_t direct_address_type,
const address_t &direct_address,
uint8_t data_length,
const uint8_t *data_size
) = 0;
/**
* TODO
* @param error
* @param sync_handle
* @param advertising_sid
* @param advertiser_address_type
* @param advertiser_address
* @param periodic_advertising_interval
* @param clock_accuracy
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.14 LE extended advertising
* report event.
*/
virtual void on_periodic_advertising_sync_established(
hci_error_code_t error,
sync_handle_t sync_handle,
advertising_sid_t advertising_sid,
connection_peer_address_type_t advertiser_address_type,
const address_t &advertiser_address,
uint16_t periodic_advertising_interval,
clock_accuracy_t clock_accuracy
) = 0;
/**
* TODO
* @param sync_handle
* @param tx_power
* @param rssi
* @param data_status
* @param data_length
* @param data
*/
virtual void on_periodic_advertising_report(
sync_handle_t sync_handle,
advertising_power_t tx_power,
rssi_t rssi,
advertising_data_status_t data_status,
uint8_t data_length,
const uint8_t *data
) = 0;
/**
* TODO
* @param sync_handle
*/
virtual void on_periodic_advertising_sync_loss(
sync_handle_t sync_handle
) = 0;
/**
* TODO
*/
virtual void on_scan_timeout() = 0;
/**
* TODO
* @param status
* @param advertising_handle
* @param connection_handle
* @param number_of_completed_extended_advertising_events
*/
virtual void on_advertising_set_terminated(
hci_error_code_t status,
advertising_handle_t advertising_handle,
connection_handle_t connection_handle,
uint8_t number_of_completed_extended_advertising_events
) = 0;
/**
* TODO
* @param advertising_handle
* @param scanner_address_type
* @param address
*/
virtual void on_scan_request_received(
advertising_handle_t advertising_handle,
connection_peer_address_type_t scanner_address_type,
const address_t &address
) = 0;
};
/**
@ -141,6 +311,31 @@ struct Gap {
*/
virtual ble_error_t set_random_address(const address_t& address) = 0;
/**
* Set the random device address used by an advertising set.
*
* @pre No connectable advertising set should be enabled.
*
* @post The new random address should be used when @p advertising_set_handle
* is enabled.
*
* @param advertising_handle Handle to the advertising set that will be
* advertised with the address @p address.
*
* @param address The random address to use when @p advertising_set_handle
* is in use.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note See Bluetooth 5 Vol 2, Part E: 7.8.52 LE Set Advertising Set Random
* Address Command
*/
virtual ble_error_t set_advertising_set_random_address(
advertising_handle_t advertising_handle,
const address_t &address
) = 0;
/**
* Set the advertising parameters which will be used during the advertising
* process.
@ -209,6 +404,116 @@ struct Gap {
advertising_filter_policy_t advertising_filter_policy
) = 0;
/**
* Define the advertising parameters of an advertising set.
*
* @param advertising_handle Identify the advertising set being configured.
*
* @param event_properties Describe the type of advertising event and its
* properties.
*
* @param primary_advertising_interval_min, primary_advertising_interval_max
* Advertising interval range for undirected and low duty cycle advertising.
* This parameter is not considered if @p event_properties.high_duty_cycle is
* set.
*
* @param primary_advertising_channel_map Map of the advertising channel to
* use while advertising.
*
* @param own_address_type The type of address being used by the local
* controller. If this parameter is a resolvable address then the peer
* address should be an identity address.
*
* @param peer_address_type, peer_address Address of the peer. This parameter
* is not evaluated if @p event_properties.directed is not set.
*
* @param advertising_filter_policy Filter applied to scan and connection
* requests. It is ignored for directed advertising (@p
* event_properties.directed set).
*
* @param advertising_power Maximum power level used during advertising.
* The controller select a power level lower than or equal to this value.
* The special value 127 should be used if the host as no preference towards
* the transmit power used.
*
* @param primary_advertising_phy PHY used to transmit data on the primary
* advertising channel. Accepted values are: phy_t::LE_1M and phy_t::LE_CODED.
*
* @param secondary_advertising_max_skip Maximum number of advertising events
* that can be skipped before the AUX_ADV_IND can be sent.
*
* @param secondary_phy PHY used to transmit data on the secondary advertising
* channel.
*
* @param advertising_sid 4bit value identifying the advertising set over the
* air. It is not used by legacy advertising.
*
* @param scan_request_notification Indicate if the host wants to receive
* scan request notification events.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.53 LE Set Extended Advertising
* Parameters Command.
*
* @note If the advertising set does not exist on the controller, it is
* created.
*
* @pre @p advertising_handle should not be enabled when this command is
* issued.
*/
virtual ble_error_t set_extended_advertising_parameters(
advertising_handle_t advertising_handle,
advertising_event_properties_t event_properties,
advertising_interval_t primary_advertising_interval_min,
advertising_interval_t primary_advertising_interval_max,
advertising_channel_map_t primary_advertising_channel_map,
own_address_type_t own_address_type,
advertising_peer_address_type_t peer_address_type,
const address_t &peer_address,
advertising_filter_policy_t advertising_filter_policy,
advertising_power_t advertising_power,
phy_t primary_advertising_phy,
uint8_t secondary_advertising_max_skip,
phy_t secondary_phy,
uint8_t advertising_sid,
bool scan_request_notification
) = 0;
/**
* Configure periodic advertising parameters of an advertising set.
*
* @pre The advertising handle must exist on the controller @see
* set_extended_advertising_parameters .
*
* @pre Periodic advertising of @p advertising_handle should not be enabled
* when this function is called.
*
* @pre The advertising set identified by @p advertising_handle should not
* be configured as anonymous advertising.
*
* @param advertising_handle The advertising set being configured.
*
* @param periodic_advertising_min, periodic_advertising_max Advertising
* interval range for periodic advertising of this set.
*
* @param advertise_power If true, the transmission power should be included
* in the advertising PDU.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.61 LE Set Periodic Advertising
* Parameters Command
*/
virtual ble_error_t set_periodic_advertising_parameters(
advertising_handle_t advertising_handle,
periodic_advertising_interval_t periodic_advertising_min,
periodic_advertising_interval_t periodic_advertising_max,
bool advertise_power
) = 0;
/**
* Set the data sends in advertising packet. If the advertising is
* currently enabled, the data shall be used when a new advertising packet
@ -231,6 +536,77 @@ struct Gap {
const advertising_data_t& advertising_data
) = 0;
/**
* Set data in advertising PDUs.
*
* @note this command can be called at anytime, whether the advertising set
* is enabled or not.
*
* @note the extended scan response can be set in one or more command.
*
* @pre @p advertising_handle should exist. To create it call
* set_extended_scan_parameters.
*
* @post The data inserted is used for subsequent advertising events.
*
* @param advertising_handle The handle identifying the advertising set
* associated with the data.
*
* @param operation Description of the operation to apply to @p
* advertising_handle data.
*
* @param minimize_fragmentation Hint for the controller to minimize
* fragmentation of data sent over the air.
*
* @param advertising_data_size, advertising_data The data to associate to @p
* advertising_handle.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.54 LE set extended advertising
* data command.
*/
virtual ble_error_t set_extended_advertising_data(
advertising_handle_t advertising_handle,
advertising_fragment_description_t operation,
bool minimize_fragmentation,
uint8_t advertising_data_size,
const uint8_t *advertising_data
);
/**
* Set the data used in periodic advertising PDUs.
*
* @note the extended scan response can be set in one or more command.
*
* @pre @p advertising_handle must exist. See set_extended_advertising_parameters.
*
* @pre @p advertising_handle must be configured for periodic advertising.
* See set_periodic_advertising_parameters .
*
* @param advertising_handle The handle identifying the advertising set
* associated with the data.
*
* @param fragment_description Description of the operation to apply to @p
* advertising_handle data.
*
* @param advertising_data_size, advertising_data The data to associate to @p
* advertising_handle.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.62 LE set periodic advertising
* data command.
*/
virtual ble_error_t set_periodic_advertising_data(
advertising_handle_t advertising_handle,
advertising_fragment_description_t fragment_description,
uint8_t advertising_data_size,
const uint8_t *advertising_data
) = 0;
/**
* 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
@ -253,6 +629,39 @@ struct Gap {
const advertising_data_t& scan_response_data
) = 0;
/**
* Set the data sends in extended scan response packets. If the advertising
* is currently enabled, the data shall be used when a new extended scan
* response is issued.
*
* @note the extended scan response can be set in one or more command.
*
* @param advertising_handle The advertising handle that owns the scan
* response data.
*
* @param operation Description of the operation to apply to @p
* advertising_handle data.
*
* @param minimize_fragmentation Hint for the controller to minimize
* fragmentation of data sent over the air.
*
* @param scan_response_data_size, scan_response_data The data to associate
* to @p advertising_handle.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.55 LE set extended scan response
* data command.
*/
virtual ble_error_t set_extended_scan_response_data(
advertising_handle_t advertising_handle,
advertising_fragment_description_t operation,
bool minimize_fragmentation,
uint8_t scan_response_data_size,
const uint8_t *scan_response_data
);
/**
* Start or stop advertising.
*
@ -295,6 +704,129 @@ struct Gap {
*/
virtual ble_error_t advertising_enable(bool enable) = 0;
/**
* Start of stop advertising of extended advertising sets.
*
* @pre advertising handles present in @p handles must exist.
*
* @pre advertising or scan response data must be complete for advertising
* handles in @p handles.
*
* @note Disabling the advertising set identified by @p handle[i] does not
* disable any periodic advertising associated with that set.
*
* @param enable If true, start advertising of the advertising sets pointed
* by @p handles. If false stop advertising for the advertising sets pointed
* by @p handles.
*
* @param number_of_sets Number of advertising sets concerned by the operation.
* @p handles, @p durations and @p max_extended_advertising_events should
* contain @p number_of_sets elements.
*
* @param handles Handle of advertising sets to start or stop.
*
* @param durations Advertising duration for @p handle. The unit is 10ms and
* the special value 0x000 disable advertising timeout.
*
* @param max_extended_advertising_events Maximum number of extended
* advertising events the controller must attempt to send prior to
* terminating the extended advertising. The special value 0 indicate that
* there is no maximum.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.56 LE extended advertising enable
* command.
*/
virtual ble_error_t extended_advertising_enable(
bool enable,
uint8_t number_of_sets,
const advertising_handle_t* handles,
const uint16_t* durations,
const uint8_t* max_extended_advertising_events
) = 0;
/**
* Enable or disable periodic advertising of an advertising set.
*
* @param enable If true enable periodic advertising of @p advertising_handle
* otherwise disable it.
*
* @param advertising_handle Handle to the advertising set to enable or
* disable.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.63 LE periodic advertising enable
* command.
*/
virtual ble_error_t periodic_advertising_enable(
bool enable,
advertising_handle_t advertising_handle
) = 0;
/**
* Query the maximum data length the controller supports in an advertising
* set.
*
* @return The length in byte the controller can support in an advertising
* set.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.57 LE read maximum advertising
* data length command.
*/
virtual uint16_t get_maximum_advertising_data_length() = 0;
/**
* Query the maximum number of concurrent advertising sets that is supported
* by the controller.
*
* @return The number of concurrent advertising sets supported by the
* controller.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.58 LE number of supported
* advertising sets command.
*/
virtual uint8_t get_max_number_of_advertising_sets();
/**
* Remove an advertising set from the controller.
*
* After this operation, configuration and data associated with @p
* advertising_handle are lost.
*
* @pre @p advertising_handle must exist.
*
* @pre Advertising of @p advertising_handle must be disabled.
*
* @param advertising_handle The advertising handle to destroy.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.59 LE remove advertising set
* command.
*/
virtual ble_error_t remove_advertising_set(
advertising_handle_t advertising_handle
) = 0;
/**
* Remove all advertising sets maintained by the controller.
*
* @pre Advertising of all advertising sets must be disabled.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.60 LE clear advertising sets
* command.
*/
virtual ble_error_t clear_advertising_sets() = 0;
/**
* Set the parameter of the scan process.
*
@ -330,6 +862,43 @@ struct Gap {
scanning_filter_policy_t filter_policy
) = 0;
/**
* Set extended scan parameters to be used on advertising channels.
*
* @param own_address_type Type of the address used in scan requests.
*
* @param filter_policy Scanning filter policy.
*
* @param scanning_phys The phy affected by the parameter change. Just
* LE_1M and LE_CODED can be set. If two phys are set then @p active_scanning,
* @p scan_interval and @p scan_window must contain two elements. The first
* being applied to LE_1M and the second being applied to LE_CODED.
*
* @param active_scanning If true, active scanning is used for the
* correcponding PHY.
*
* @param scan_interval Interval between two subsequent scan. This parameter
* shall be in the range [0x0004 : 0x4000] and is in unit of 0.625ms.
*
* @param 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.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.64 LE set extended scan parameters
* command.
*/
virtual ble_error_t set_extended_scan_parameters(
own_address_type_t own_address_type,
scanning_filter_policy_t filter_policy,
phy_set_t scanning_phys,
const bool *active_scanning,
const uint16_t *scan_interval,
const uint16_t *scan_window
) = 0;
/**
* Start/stop scanning process.
*
@ -356,6 +925,179 @@ struct Gap {
bool filter_duplicates
) = 0;
/**
* Enable or disable extended scanning.
*
* @param enable If true enable scanning and disable it otherwise.
*
* @param filter_duplicates If true filter out duplicate scan reports.
*
* @param duration Duration of the scan operation. The unit is 10ms and
* the special value 0 indicate continuous scan until explicitly disabled.
*
* @param period Interval between two scan operations. The unit is 1.28s and
* the special value 0 can be used to disable periodic scanning. If @p
* filter_duplicates is equal to duplicates_filter_t::PERIODIC_RESET then
* the duplicate cache is reset whenever a scan operation starts.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.65 LE set extended scan enable
* command.
*/
virtual ble_error_t extended_scan_enable(
bool enable,
duplicates_filter_t filter_duplicates,
uint16_t duration,
uint16_t period
) = 0;
/**
* Synchronize an observer with a periodic advertising broadcaster.
*
* One the synchronization is establish the function
* EventHandler::on_periodic_advertising_sync_established is called and for
* every periodic advertising received is reported via the function
* EventHandler::on_periodic_advertising_report .
*
* @param use_periodic_advertiser_list Determine if the periodic advertiser
* list is used or ignored.
*
* @param advertising_sid SID to sync with.
*
* @param peer_address_type, peer_address Address of the advertiser. If @p
* use_periodic_advertiser_list is true then these parameters are ignored.
*
* @param allowed_skip Number of periodic advertisement that can be skipped
* after a successful receive by the local device.
*
* @param sync_timeout Specifies the maximum permitted time between two
* successful receives. If this time is exceeded then the synchronization is
* considered lost and EventHandler::on_periodic_advertising_loss is called.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.67 LE periodic advertising create
* sync command.
*/
virtual ble_error_t periodic_advertising_create_sync(
bool use_periodic_advertiser_list,
uint8_t advertising_sid,
peer_address_type_t peer_address_type,
const address_t &peer_address,
uint16_t allowed_skip,
uint16_t sync_timeout
) = 0;
/**
* Cancel the establishment of synchronization with a periodic advertising
* broadcaster.
*
* @pre There should be an ongoing sync establishment operation.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.68 LE periodic advertising create
* sync cancel command.
*/
virtual ble_error_t cancel_periodic_advertising_create_sync() = 0;
/**
* Stop reception of the periodic advertising identified by @p sync_handle.
*
* @param sync_handle The handle identifying the periodic advertiser. It is
* obtained when EventHandler::on_periodic_advertising_sync_established is
* called.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.69 LE periodic advertising
* terminate sync command.
*/
virtual ble_error_t periodic_advertising_terminate_sync(
sync_handle_t sync_handle
) = 0;
/**
* Add a device to the periodic advertiser list stored in the controller.
* This list may be used to create a periodic advertiser sync.
*
* @pre The device should not be in the periodic advertiser list.
*
* @pre Create sync operation should not be pending
*
* @pre The periodic advertising list of the controller should not be full.
*
* @param advertiser_address_type The address type of the device to add.
*
* @param advertiser_address The address value of the device to add.
*
* @param advertising_sid The SID field used to identify periodic advertising
* from the device.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.70 LE add device to periodic
* advertising list command.
*/
virtual ble_error_t add_device_to_periodic_advertiser_list(
advertising_peer_address_type_t advertiser_address_type,
const address_t &advertiser_address,
uint8_t advertising_sid
) = 0;
/**
* Remove a device from the periodic advertiser list.
*
* @pre Create sync operation should not be pending
*
* @param advertiser_address_type The address type of the device to remove.
*
* @param advertiser_address The address value of the device to remove.
*
* @param advertising_sid The SID field used to identify periodic advertising
* from the device.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.71 LE remove device from periodic
* advertising list command.
*/
virtual ble_error_t remove_device_from_periodic_advertiser_list(
advertising_peer_address_type_t advertiser_address_type,
const address_t &advertiser_address,
uint8_t advertising_sid
) = 0;
/**
* Clear all devices from the list of periodic advertisers.
*
* @pre Create sync operation should not be pending
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.72 LE clear periodic advertising
* list command.
*/
virtual ble_error_t clear_periodic_advertiser_list() = 0;
/**
* Return the total number of entries that can be stored by the periodic
* advertiser list.
*
* @return The capacity of the periodic advertiser list.
*
* @note We (wrongfully) assume that value doesn't change over time.
*/
virtual uint8_t read_periodic_advertiser_list_size() = 0;
/**
* Create a new le connection to a connectable advertiser.
*
@ -442,6 +1184,99 @@ struct Gap {
uint16_t maximum_connection_event_length
) = 0;
/**
* Create a new le connection to a connectable advertiser.
*
* @param 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.
*
* @param own_address_type Type of address used in the connection request
* packet.
*
* @param peer_address_type Type of address used by the advertiser. Not used
* if initiator_policy use the whitelist.
*
* @param peer_address Address used by the advertiser in its advertising
* packets. Not used if initiator_policy use the whitelist.
*
* @param initiating_phys Indicates the advertising PHYs and the controller
* may use find the target and establish the connection. Subsequent
* parameters are arrays of value associated with phys present in @p
* initiating_phys. The order of phys is 1M, 2M, Coded.
*
* @param scan_intervals 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.
*
* @param scan_windows 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.
*
* @param connection_intervals_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.
*
* @param connection_intervals_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.
*
* @param connection_latencies 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].
*
* @param supervision_timeouts 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.
*
* @param minimum_connection_event_lengths 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.
*
* @param maximum_connection_event_lengths 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.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.66 LE extended create connection
* command.
*/
virtual ble_error_t extended_create_connection(
initiator_policy_t initiator_policy,
own_address_type_t own_address_type,
peer_address_type_t peer_address_type,
const address_t &peer_address,
phy_set_t initiating_phys,
const uint16_t* scan_intervals,
const uint16_t* scan_windows,
const uint16_t* connection_intervals_min,
const uint16_t* connection_intervals_max,
const uint16_t* connection_latencies,
const uint16_t* supervision_timeouts,
const uint16_t* minimum_connection_event_lengths,
const uint16_t* maximum_connection_event_lengths
) = 0;
/**
* Cancel the ongoing connection creation process.
*