Oveview

Battle-tested Bluetooth with rock-solid reliability. Main docs: https://pigweed.dev/pw_bluetooth_sapphire.

Classes
class	pw::bluetooth_sapphire::Central
	Must only be constructed and destroyed on the Bluetooth thread. More...

class	pw::bluetooth_sapphire::testing::FakeLeaseProvider
	A fake LeaseProvider used for dependency injection in unit tests. More...

class	pw::bluetooth_sapphire::Lease

class	pw::bluetooth_sapphire::LeaseProvider

class	pw::bluetooth_sapphire::NullLeaseProvider
	A no-op LeaseProvider that always successfully returns an fake lease. More...

class	pw::bluetooth_sapphire::Peripheral
	Must only be constructed and destroyed on the Bluetooth thread. More...

class	pw::bluetooth_sapphire::PowerDelegate
	Interface for Sapphire to interact with the system's power management. More...

Functions
	pw::bluetooth_sapphire::Central::Central (bt::gap::Adapter::WeakPtr adapter, pw::async::Dispatcher &dispatcher, pw::multibuf::MultiBufAllocator &allocator)

async2::OnceReceiver< ConnectResult >	pw::bluetooth_sapphire::Central::Connect (pw::bluetooth::PeerId peer_id, bluetooth::low_energy::Connection2::ConnectionOptions options) override

async2::OnceReceiver< ScanStartResult >	pw::bluetooth_sapphire::Central::Scan (const ScanOptions &options) override

static pw::sync::Mutex &	pw::bluetooth_sapphire::Central::lock ()

	pw::bluetooth_sapphire::Central::ScanHandleImpl::ScanHandleImpl (uint16_t scan_id, Central *central)

void	pw::bluetooth_sapphire::Central::ScanHandleImpl::QueueScanResultLocked (ScanResult &&result)

void	pw::bluetooth_sapphire::Central::ScanHandleImpl::WakeLocked ()

void	pw::bluetooth_sapphire::Central::ScanHandleImpl::OnScanErrorLocked ()

	pw::bluetooth_sapphire::Central::ScanState::ScanState (std::unique_ptr< bt::gap::LowEnergyDiscoverySession > session, ScanHandleImpl scan_handle, uint16_t scan_id, Central central)

void	pw::bluetooth_sapphire::Central::ScanState::OnScanHandleDestroyedLocked ()

	pw::bluetooth_sapphire::testing::FakeLeaseProvider::FakeLeaseProvider (FakeLeaseProvider &&)=delete

FakeLeaseProvider &	pw::bluetooth_sapphire::testing::FakeLeaseProvider::operator= (FakeLeaseProvider &&)=delete

Result< Lease >	pw::bluetooth_sapphire::testing::FakeLeaseProvider::Acquire (PW_SAPPHIRE_LEASE_TOKEN_TYPE) override

uint16_t	pw::bluetooth_sapphire::testing::FakeLeaseProvider::lease_count () const
	Returns the number of active leases.

void	pw::bluetooth_sapphire::testing::FakeLeaseProvider::set_acquire_status (Status status)
	Sets the status to return from the `Acquire` method.

	pw::bluetooth_sapphire::Lease::Lease (pw::Function< void()> unlock_fn)

	pw::bluetooth_sapphire::Lease::Lease (Lease &&)=default

Lease &	pw::bluetooth_sapphire::Lease::operator= (Lease &&)=default

	pw::bluetooth_sapphire::Lease::Lease (const Lease &)=delete

Lease &	pw::bluetooth_sapphire::Lease::operator= (const Lease &)=delete

virtual Result< Lease >	pw::bluetooth_sapphire::LeaseProvider::Acquire (PW_SAPPHIRE_LEASE_TOKEN_TYPE name)=0

Result< Lease >	pw::bluetooth_sapphire::NullLeaseProvider::Acquire (PW_SAPPHIRE_LEASE_TOKEN_TYPE) override

	pw::bluetooth_sapphire::Peripheral::Peripheral (bt::gap::Adapter::WeakPtr adapter, pw::async::Dispatcher &dispatcher)
	Must only be constructed on the Bluetooth thread.

	pw::bluetooth_sapphire::Peripheral::~Peripheral () override
	Must only be destroyed on the Bluetooth thread.

async2::OnceReceiver< AdvertiseResult >	pw::bluetooth_sapphire::Peripheral::Advertise (const AdvertisingParameters &parameters) override

static pw::sync::Mutex &	pw::bluetooth_sapphire::Peripheral::lock ()

	pw::bluetooth_sapphire::Peripheral::AdvertisedPeripheralImpl::AdvertisedPeripheralImpl (bt::gap::AdvertisementId id, Peripheral *peripheral)

async2::Poll< pw::bluetooth::low_energy::Connection2::Ptr >	pw::bluetooth_sapphire::Peripheral::AdvertisedPeripheralImpl::PendConnection (async2::Context &cx) override

void	pw::bluetooth_sapphire::Peripheral::AdvertisedPeripheralImpl::StopAdvertising () override

async2::Poll< pw::Status >	pw::bluetooth_sapphire::Peripheral::AdvertisedPeripheralImpl::PendStop (async2::Context &cx) override

void	pw::bluetooth_sapphire::Peripheral::AdvertisedPeripheralImpl::Release () override

	pw::bluetooth_sapphire::Peripheral::Advertisement::Advertisement (bt::gap::AdvertisementInstance &&instance, AdvertisedPeripheralImpl *advertised_peripheral)

void	pw::bluetooth_sapphire::Peripheral::Advertisement::OnAdvertisedPeripheralDestroyedLocked ()

void	pw::bluetooth_sapphire::Peripheral::Advertisement::OnStopLocked (pw::Status status)

virtual LeaseProvider &	pw::bluetooth_sapphire::PowerDelegate::SchedulerLeaseProvider ()=0

Variables
static constexpr uint8_t	pw::bluetooth_sapphire::Central::kMaxScanResultsQueueSize = 10

Friends
class	pw::bluetooth_sapphire::Peripheral::AdvertisedPeripheralImpl::Advertisement

class	pw::bluetooth_sapphire::Peripheral::Advertisement::AdvertisedPeripheralImpl

Function Documentation

◆ Acquire() [1/3]

virtual Result< Lease > pw::bluetooth_sapphire::LeaseProvider::Acquire ( PW_SAPPHIRE_LEASE_TOKEN_TYPE name )

pure virtual

Try to acquire a lease. Prefer to use PW_SAPPHIRE_ACQUIRE_LEASE instead.

Parameters

name	will be either a `const char*` or a `uint32_t` depending on whether tokenization is enabled.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: A `Lease` was successfully created and returned.
* 
*     UNAVAILABLE: A lease could not be created.
* 
*     INVALID_ARGUMENT: The name was invalid (e.g. empty).
* 
*

Implemented in pw::bluetooth_sapphire::testing::FakeLeaseProvider, and pw::bluetooth_sapphire::NullLeaseProvider.

◆ Acquire() [2/3]

Result< Lease > pw::bluetooth_sapphire::testing::FakeLeaseProvider::Acquire ( PW_SAPPHIRE_LEASE_TOKEN_TYPE name )

inlineoverridevirtual

Try to acquire a lease. Prefer to use PW_SAPPHIRE_ACQUIRE_LEASE instead.

Parameters

name	will be either a `const char*` or a `uint32_t` depending on whether tokenization is enabled.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: A `Lease` was successfully created and returned.
* 
*     UNAVAILABLE: A lease could not be created.
* 
*     INVALID_ARGUMENT: The name was invalid (e.g. empty).
* 
*

Implements pw::bluetooth_sapphire::LeaseProvider.

◆ Acquire() [3/3]

Result< Lease > pw::bluetooth_sapphire::NullLeaseProvider::Acquire ( PW_SAPPHIRE_LEASE_TOKEN_TYPE name )

inlineoverridevirtual

Try to acquire a lease. Prefer to use PW_SAPPHIRE_ACQUIRE_LEASE instead.

Parameters

name	will be either a `const char*` or a `uint32_t` depending on whether tokenization is enabled.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: A `Lease` was successfully created and returned.
* 
*     UNAVAILABLE: A lease could not be created.
* 
*     INVALID_ARGUMENT: The name was invalid (e.g. empty).
* 
*

Implements pw::bluetooth_sapphire::LeaseProvider.

◆ Advertise()

async2::OnceReceiver< AdvertiseResult > pw::bluetooth_sapphire::Peripheral::Advertise ( const AdvertisingParameters & parameters )

overridevirtual

Thread safe. The AdvertisedPeripheral2 returned on success is thread safe.

Implements pw::bluetooth::low_energy::Peripheral2.

◆ Central()

pw::bluetooth_sapphire::Central::Central	(	bt::gap::Adapter::WeakPtr	adapter,
		pw::async::Dispatcher &	dispatcher,
		pw::multibuf::MultiBufAllocator &	allocator
	)

Must only be constructed on the Bluetooth thread.

Parameters

allocator The allocator to use for advertising data buffers.

◆ Scan()

async2::OnceReceiver< ScanStartResult > pw::bluetooth_sapphire::Central::Scan ( const ScanOptions & options )

overridevirtual

Scans for nearby LE peripherals and broadcasters. The lifetime of the scan session is tied to the returned ScanHandle object in ScanStartResult. Once a scan is started, ScanHandle::PendResult can be called to get scan results. Only 1 scan may be active at a time.

Parameters

options Options used to configure the scan session. These options are suggestions only, and the implementation may use different parameters to meet power or radio requirements.

Returns: Returns a ScanHandle object if the scan successfully starts, or a ScanError otherwise. ScanHandle::PendResult can be called to get ScanResults for LE peers that satisfy the filters indicated in options. The initial results may report recently discovered peers. Subsequent results will be reported only when peers have been scanned or updated since the last call.

Implements pw::bluetooth::low_energy::Central2.

◆ SchedulerLeaseProvider()

virtual LeaseProvider & pw::bluetooth_sapphire::PowerDelegate::SchedulerLeaseProvider ( )

pure virtual

Provides leases that ensure the scheduler keeps scheduling Bluetooth tasks. For example, a lease will be taken while processing packets or during pairing.

Oveview

Classes

Functions

Variables

Friends

Function Documentation

◆ Acquire() [1/3]

◆ Acquire() [2/3]

◆ Acquire() [3/3]

◆ Advertise()

◆ Central()

◆ Scan()

◆ SchedulerLeaseProvider()