Mbed OS Reference
Loading...
Searching...
No Matches
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...
 
ConnectionParameterssetScanParameters (phy_t phy, scan_interval_t scanInterval, scan_window_t scanWindow)
 Set the scan parameters for a given PHY. More...
 
ConnectionParameterssetConnectionParameters (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...
 
ConnectionParameterssetOwnAddressType (own_address_type_t ownAddress)
 Address type used by the local device to connect the peer. More...
 
ConnectionParameterssetFilter (initiator_filter_policy_t filterPolicy)
 Set if the whitelist should be used to find the peer. More...
 
ConnectionParameterstogglePhy (bool phy1M, bool phy2M, bool phyCoded)
 Enable or disable PHYs. More...
 
ConnectionParametersdisablePhy (phy_t phy=phy_t::LE_1M)
 Disable an individual PHY. More...
 
ConnectionParametersenablePhy (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,
scan_interval_t(millisecond_t(500)),
scan_window_t(millisecond_t(250))
)
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)
);
}
Parameters defining the connection initiation process.
ConnectionParameters & setScanParameters(phy_t phy, scan_interval_t scanInterval, scan_window_t scanWindow)
Set the scan parameters for a given PHY.
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.
ConnectionParameters & setOwnAddressType(own_address_type_t ownAddress)
Address type used by the local device to connect the peer.
Define device discovery, connection and link management procedures.
Definition: Gap.h:282
ble_error_t connect(peer_address_type_t peerAddressType, const address_t &peerAddress, const ConnectionParameters &connectionParams)
Initiate a connection to a peer.
Entry namespace for all BLE API definitions.
Duration< uint32_t, 1000 *microsecond_t::TIME_BASE > millisecond_t
Type that represents milliseconds.
Definition: Duration.h:303
MAC address data type.
@ LE_1M
1Mbit/s LE.
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
phyThe PHY being configured.
scanIntervalInterval between two scans.
scanWindowScan duration during a scan interval.
minConnectionIntervalMinimum value of the connection interval.
maxConnectionIntervalMaximum value of the connection interval.
slaveLatencyMaximum number of packets the slave can drop.
connectionSupervisionTimeoutTime after which the connection is considered lost if no data has been exchanged.
minEventLengthMinimum duration of a connection event.
maxEventLengthMaximum 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
phyPHY being configured.
scanIntervalInterval between two scans.
scanWindowScan 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
phyThe PHY being configured.
minConnectionIntervalMinimum connection interval.
maxConnectionIntervalMaximum connection interval.
slaveLatencyMaximum number of packets the slave can drop.
connectionSupervisionTimeoutTime after which the connection is considered lost if no data has been exchanged.
minEventLengthMinimum duration of a connection event.
maxEventLengthMaximum 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
ownAddressType 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
filterPolicyThe 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
phy1Mtrue to enable the 1M PHY and false to disable it.
phy2Mtrue to enable the 2M PHY and false to disable it.
phyCodedtrue 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
phyThe 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
phyThe 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.