Kenji Arai / mbed-os_TYBLE16

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

ConnectionParameters Class Reference
Public Member Functions

ConnectionParameters Class Reference
[Gap]

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.
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.
ConnectionParameters & setFilter (initiator_filter_policy_t filterPolicy)
 Set if the whitelist should be used to find the peer.
ConnectionParameters & togglePhy (bool phy1M, bool phy2M, bool phyCoded)
 Enable or disable PHYs.
ConnectionParameters & disablePhy (phy_t phy=phy_t::LE_1M)
 Disable an individual PHY.
ConnectionParameters & enablePhy (phy_t phy=phy_t::LE_1M)
 Enable an individual PHY.
own_address_type_t getOwnAddressType () const
 Return the local address type used.
initiator_filter_policy_t getFilter () const
 Return the initiator policy.
uint8_t getNumberOfEnabledPhys () const
 Return the number of PHY enabled.

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 121 of file ConnectionParameters.h.

Constructor & Destructor Documentation

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.

Definition at line 21 of file ConnectionParameters.cpp.

Member Function Documentation

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 256 of file ConnectionParameters.h.

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 271 of file ConnectionParameters.h.

initiator_filter_policy_t getFilter (  ) const

Return the initiator policy.

Returns:
The initiator policy.

Definition at line 296 of file ConnectionParameters.h.

uint8_t getNumberOfEnabledPhys (  ) const

Return the number of PHY enabled.

Returns:
The number of PHY enabled.

Definition at line 309 of file ConnectionParameters.h.

own_address_type_t getOwnAddressType (  ) const

Return the local address type used.

Returns:
The local address type to use.

Definition at line 286 of file ConnectionParameters.h.

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.

Definition at line 73 of file ConnectionParameters.cpp.

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 222 of file ConnectionParameters.h.

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 209 of file ConnectionParameters.h.

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.

Definition at line 57 of file ConnectionParameters.cpp.

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 239 of file ConnectionParameters.h.

Generated on Tue Jul 12 2022 13:55:39 by  doxygen 1.7.2