ConnectionParameters Class Reference

Parameters defining the connection initiation process. More...

#include <ConnectionParameters.h>

Public Member Functions
	ConnectionParameters (phy_t phy=phy_t::LE_1M, scan_interval_t scanInterval=scan_interval_t::min(), scan_window_t scanWindow=scan_window_t::min(), conn_interval_t minConnectionInterval=conn_interval_t(50), conn_interval_t maxConnectionInterval=conn_interval_t(100), slave_latency_t slaveLatency=slave_latency_t::min(), supervision_timeout_t connectionSupervisionTimeout=supervision_timeout_t(100), conn_event_length_t minEventLength=conn_event_length_t::min(), conn_event_length_t maxEventLength=conn_event_length_t::max())
	Create a ConnectionParameters object. More...
ConnectionParameters &	setScanParameters (phy_t phy, scan_interval_t scanInterval, scan_window_t scanWindow)
	Set the scan parameters for a given PHY. More...
ConnectionParameters &	setConnectionParameters (phy_t phy, conn_interval_t minConnectionInterval, conn_interval_t maxConnectionInterval, slave_latency_t slaveLatency, supervision_timeout_t connectionSupervisionTimeout, conn_event_length_t minEventLength=conn_event_length_t::min(), conn_event_length_t maxEventLength=conn_event_length_t::max())
	Set the conenction parameters of a given PHY. More...
ConnectionParameters &	setOwnAddressType (own_address_type_t ownAddress)
	Address type used by the local device to connect the peer. More...
ConnectionParameters &	setFilter (initiator_filter_policy_t filterPolicy)
	Set if the whitelist should be used to find the peer. More...
ConnectionParameters &	togglePhy (bool phy1M, bool phy2M, bool phyCoded)
	Enable or disable PHYs. More...
ConnectionParameters &	disablePhy (phy_t phy=phy_t::LE_1M)
	Disable an individual PHY. More...
ConnectionParameters &	enablePhy (phy_t phy=phy_t::LE_1M)
	Enable an individual PHY. More...
own_address_type_t	getOwnAddressType () const
	Return the local address type used. More...
initiator_filter_policy_t	getFilter () const
	Return the initiator policy. More...
uint8_t	getNumberOfEnabledPhys () const
	Return the number of PHY enabled. More...

Detailed Description

Parameters defining the connection initiation process.

The connection initiation process is divided in two different phases. First, the initiating device scans for the peer to which it should connect. Once it finds the peer, it sends a connection request that contains the connection parameters.

Scan parameters

The scan parameters are defined by two durations: the scan interval and the scan window. The scan interval is the duration between two scan cycles, and the scan window defines how long the device searches during a scan cycle.

You can set the scan window and the scan interval at construction time or by calling setScanParameters().

Connection parameters

A Bluetooth connection is defined by three parameters:

• Connection interval: The time between two connection events. A minimum and a maximum connection interval are requested to help the Bluetooth subsystem deal with concurrent radio processing.
• Slave latency: Number of connection events that can be ignored by the slave.
• Supervision timeout: Time after which the connection is considered lost if the connected devices haven't exchanged a single packet. It is important to note that even if the application doesn't send actual data, the Bluetooth controller takes care of sending empty data packets to maintain the connection.

You can set these parameters at construction time or by calling the function setConnectionParameters().

PHY

Bluetooth 5 has introduced the support of different physical layer to either increase the range or the throughput. You can configure multiple PHY independently for scanning and connecting.

Legacy connection happens on the 1M PHY (phy_t::LE_1M). It is the only PHY that you can configure on legacy systems.

The constructor, setScanParameters() and setConnectionParameters() accept a phy_t parameter that defines to which PHY the parameters set applies.

Other parameters:

It is possible to define what type of address is used to establish the connection and whether the whitelist should be used to find the peer to connect to.

Example:

Thanks to the fluent API, you can compose the connection parameters at instantiation point:

void do_connect(ble::Gap& gap, ble::target_peer_address_type_t addr_type, ble::address_t& address)
{
    using namespace ble;
 
    gap.connect(
        addr_type,
        address,
        ConnectionParameters()
            .setScanParameters(
                phy_t::LE_1M,
                scan_interval_t(millisecond_t(500)),
                scan_window_t(millisecond_t(250))
            )
            .setConnectionParameters(
                phy_t::LE_1M,
                conn_interval_t(millisecond_t(100)),
                conn_interval_t(millisecond_t(200)),
                slave_latency_t(0),
                supervision_timeout_t(millisecond_t(1000))
            )
            .setOwnAddressType(own_address_type_t::RANDOM)
    );
}

Note

It is not possible to configure phy_t::LE_2M for scanning.

See also

ble::Gap::connect()

Definition at line 124 of file ConnectionParameters.h.

Constructor & Destructor Documentation

ConnectionParameters()

ConnectionParameters	(	phy_t	phy = phy_t::LE_1M,
		scan_interval_t	scanInterval = scan_interval_t::min(),
		scan_window_t	scanWindow = scan_window_t::min(),
		conn_interval_t	minConnectionInterval = conn_interval_t(50),
		conn_interval_t	maxConnectionInterval = conn_interval_t(100),
		slave_latency_t	slaveLatency = slave_latency_t::min(),
		supervision_timeout_t	connectionSupervisionTimeout = supervision_timeout_t(100),
		conn_event_length_t	minEventLength = conn_event_length_t::min(),
		conn_event_length_t	maxEventLength = conn_event_length_t::max()
	)

Create a ConnectionParameters object.

Parameters

phy	The PHY being configured.
scanInterval	Interval between two scans.
scanWindow	Scan duration during a scan interval.
minConnectionInterval	Minimum value of the connection interval.
maxConnectionInterval	Maximum value of the connection interval.
slaveLatency	Maximum number of packets the slave can drop.
connectionSupervisionTimeout	Time after which the connection is considered lost if no data has been exchanged.
minEventLength	Minimum duration of a connection event.
maxEventLength	Maximum duration of a connection event.

Member Function Documentation

setScanParameters()

ConnectionParameters & setScanParameters	(	phy_t	phy,
		scan_interval_t	scanInterval,
		scan_window_t	scanWindow
	)

Set the scan parameters for a given PHY.

Parameters

phy	PHY being configured.
scanInterval	Interval between two scans.
scanWindow	Scan duration within a scan interval.

Note

It is useless to configure the 2M PHY because it is not used during scanning.

Returns

A reference to this.

setConnectionParameters()

ConnectionParameters & setConnectionParameters	(	phy_t	phy,
		conn_interval_t	minConnectionInterval,
		conn_interval_t	maxConnectionInterval,
		slave_latency_t	slaveLatency,
		supervision_timeout_t	connectionSupervisionTimeout,
		conn_event_length_t	minEventLength = conn_event_length_t::min(),
		conn_event_length_t	maxEventLength = conn_event_length_t::max()
	)

Set the conenction parameters of a given PHY.

Parameters

phy	The PHY being configured.
minConnectionInterval	Minimum connection interval.
maxConnectionInterval	Maximum connection interval.
slaveLatency	Maximum number of packets the slave can drop.
connectionSupervisionTimeout	Time after which the connection is considered lost if no data has been exchanged.
minEventLength	Minimum duration of a connection event.
maxEventLength	Maximum duration of a connection event.

Returns

A reference to this.

setOwnAddressType()

ConnectionParameters & setOwnAddressType

(

own_address_type_t

ownAddress

)

Address type used by the local device to connect the peer.

Parameters

ownAddress

Type of address used to initiate the connection.

Returns

A reference to this.

Definition at line 212 of file ConnectionParameters.h.

setFilter()

ConnectionParameters & setFilter

(

initiator_filter_policy_t

filterPolicy

)

Set if the whitelist should be used to find the peer.

Parameters

filterPolicy

The initiator filter to apply.

Returns

A reference to this.

Definition at line 225 of file ConnectionParameters.h.

togglePhy()

ConnectionParameters & togglePhy	(	bool	phy1M,
		bool	phy2M,
		bool	phyCoded
	)

Enable or disable PHYs.

Parameters

phy1M	true to enable the 1M PHY and false to disable it.
phy2M	true to enable the 2M PHY and false to disable it.
phyCoded	true to enable the CODED PHY and false to disable it.

Returns

A reference to this.

Definition at line 242 of file ConnectionParameters.h.

disablePhy()

ConnectionParameters & disablePhy

(

phy_t

phy = phy_t::LE_1M

)

Disable an individual PHY.

Parameters

phy	The PHY to disable.

Returns

A reference to this.

Definition at line 259 of file ConnectionParameters.h.

enablePhy()

ConnectionParameters & enablePhy

(

phy_t

phy = phy_t::LE_1M

)

Enable an individual PHY.

Parameters

phy	The PHY to enable.

Returns

A reference to this.

Definition at line 274 of file ConnectionParameters.h.

getOwnAddressType()

own_address_type_t getOwnAddressType

(

)

const

Return the local address type used.

Returns

The local address type to use.

Definition at line 289 of file ConnectionParameters.h.

getFilter()

initiator_filter_policy_t getFilter

(

)

const

Return the initiator policy.

Returns

The initiator policy.

Definition at line 299 of file ConnectionParameters.h.

getNumberOfEnabledPhys()

uint8_t getNumberOfEnabledPhys

(

)

const

Return the number of PHY enabled.

Returns

The number of PHY enabled.

Definition at line 312 of file ConnectionParameters.h.