Oveview

Host-layer Bluetooth Low Energy APIs and utilities. Main docs: https://pigweed.dev/pw_bluetooth.

Classes
class	pw::bluetooth::Controller2

class	pw::bluetooth::gatt::RemoteService2
	An interface for interacting with a GATT service on a peer device. More...

struct	pw::bluetooth::gatt::RemoteService2::ReadValue
	Wrapper around a possible truncated value received from the server. More...

struct	pw::bluetooth::gatt::RemoteService2::ReadByTypeResult
	A result returned by `ReadByType`. More...

struct	pw::bluetooth::gatt::RemoteService2::LongReadOptions

struct	pw::bluetooth::gatt::RemoteService2::WriteOptions

class	pw::bluetooth::gatt::Client2
	Represents a GATT client that interacts with services on a GATT server. More...

struct	pw::bluetooth::gatt::Client2::RemoteServiceInfo
	Represents a remote GATT service. More...

class	pw::bluetooth::gatt::LocalServiceDelegate2

class	pw::bluetooth::gatt::LocalService2

struct	pw::bluetooth::gatt::LocalService2::ValueChangedParameters

class	pw::bluetooth::gatt::Server2
	Interface for a GATT server that serves many GATT services. More...

struct	pw::bluetooth::gatt::Server2::LocalServiceInfo
	Parameters for registering a local GATT service. More...

class	pw::bluetooth::low_energy::Central2
	Represents the LE central role. Used to scan and connect to peripherals. More...

struct	pw::bluetooth::low_energy::Central2::ScanFilter

struct	pw::bluetooth::low_energy::Central2::ScanOptions
	Parameters used during a scan. More...

struct	pw::bluetooth::low_energy::Central2::ScanResult

class	pw::bluetooth::low_energy::Central2::ScanHandle
	Represents an ongoing LE scan. More...

struct	pw::bluetooth::low_energy::SecurityRequirements
	The authentication an encryption requirements for a channel. More...

class	pw::bluetooth::low_energy::Channel

class	pw::bluetooth::low_energy::ChannelListener

class	pw::bluetooth::low_energy::ChannelListenerRegistry

struct	pw::bluetooth::low_energy::ChannelListenerRegistry::ListenParameters
	The parameters to use for incoming channels. More...

class	pw::bluetooth::low_energy::Connection2

struct	pw::bluetooth::low_energy::Connection2::ConnectionParameters
	Actual connection parameters returned by the controller. More...

struct	pw::bluetooth::low_energy::Connection2::RequestedConnectionParameters

struct	pw::bluetooth::low_energy::Connection2::ConnectionOptions
	Represents parameters that are set on a per-connection basis. More...

struct	pw::bluetooth::low_energy::Connection2::ConnectL2capParameters

class	pw::bluetooth::low_energy::AdvertisedPeripheral2
	`AdvertisedPeripheral` instances are valid for the duration of advertising. More...

class	pw::bluetooth::low_energy::Peripheral2
	Represents the LE Peripheral role, which advertises and is connected to. More...

struct	pw::bluetooth::low_energy::Peripheral2::AdvertisingIntervalRange

struct	pw::bluetooth::low_energy::Peripheral2::LegacyAdvertising

struct	pw::bluetooth::low_energy::Peripheral2::ExtendedAdvertising

struct	pw::bluetooth::low_energy::Peripheral2::ExtendedAdvertising::Anonymous
	Anonymous advertisements do not include the address. More...

struct	pw::bluetooth::low_energy::Peripheral2::AdvertisingParameters
	Represents the parameters for configuring advertisements. More...

Typedefs
using	pw::bluetooth::gatt::RemoteService2::Ptr = internal::RaiiPtr< RemoteService2, &RemoteService2::Disconnect >

using	pw::bluetooth::gatt::LocalService2::ValueChangedResult = pw::expected< void, Error >

using	pw::bluetooth::gatt::LocalService2::Ptr = internal::RaiiPtr< LocalService2, &LocalService2::UnpublishService >

using	pw::bluetooth::gatt::Server2::PublishServiceResult = pw::expected< LocalService2::Ptr, PublishServiceError >
	The Result passed by PublishService.

using	pw::bluetooth::low_energy::Central2::ScanHandle::Ptr = internal::RaiiPtr< ScanHandle, &ScanHandle::Release >

using	pw::bluetooth::low_energy::Central2::ConnectResult = pw::expected< Connection2::Ptr, ConnectError >
	The result type returned by Connect().

using	pw::bluetooth::low_energy::Central2::ScanStartResult = pw::expected< ScanHandle::Ptr, StartScanError >
	The result type returned by Scan().

using	pw::bluetooth::low_energy::Channel::Ptr = internal::RaiiPtr< Channel, &Channel::Release >

using	pw::bluetooth::low_energy::ChannelListener::Ptr = internal::RaiiPtr< ChannelListener, &ChannelListener::Release >

using	pw::bluetooth::low_energy::Connection2::Ptr = internal::RaiiPtr< Connection2, &Connection2::Release >

using	pw::bluetooth::low_energy::AdvertisedPeripheral2::Ptr = internal::RaiiPtr< AdvertisedPeripheral2, &AdvertisedPeripheral2::Release >

using	pw::bluetooth::low_energy::Peripheral2::ScanResponse = AdvertisingData

using	pw::bluetooth::low_energy::Peripheral2::ConnectionOptions = Connection2::ConnectionOptions

using	pw::bluetooth::low_energy::Peripheral2::AdvertisingProcedure = std::variant< LegacyAdvertising, ExtendedAdvertising >

using	pw::bluetooth::low_energy::Peripheral2::AdvertiseResult = pw::expected< AdvertisedPeripheral2::Ptr, AdvertiseError >

Enumerations
enum class	pw::bluetooth::Controller2::FeaturesBits : uint32_t { pw::bluetooth::Controller2::FeaturesBits::kHciSco = (1 << 0) , pw::bluetooth::Controller2::FeaturesBits::kSetAclPriorityCommand = (1 << 1) , pw::bluetooth::Controller2::FeaturesBits::kAndroidVendorExtensions = (1 << 2) }
	Bitmask of features the controller supports. More...

enum class	ScoCodingFormat : uint8_t { kCvsd , kMsbc }

enum class	ScoEncoding : uint8_t { k8Bits , k16Bits }

enum class	ScoSampleRate : uint8_t { k8Khz , k16Khz }

enum class	pw::bluetooth::gatt::RemoteService2::RemoteServiceError { pw::bluetooth::gatt::RemoteService2::RemoteServiceError::kServiceRemoved = 0 , pw::bluetooth::gatt::RemoteService2::RemoteServiceError::kPeerDisconnected = 1 }

enum class	pw::bluetooth::gatt::RemoteService2::WriteMode : uint8_t { pw::bluetooth::gatt::RemoteService2::WriteMode::kDefault , pw::bluetooth::gatt::RemoteService2::WriteMode::kReliable , pw::bluetooth::gatt::RemoteService2::WriteMode::kWithoutResponse }

enum class	pw::bluetooth::gatt::Server2::PublishServiceError { kInternalError = 0 , pw::bluetooth::gatt::Server2::PublishServiceError::kInvalidHandle = 1 , pw::bluetooth::gatt::Server2::PublishServiceError::kInvalidUuid = 2 , pw::bluetooth::gatt::Server2::PublishServiceError::kInvalidCharacteristics = 3 , pw::bluetooth::gatt::Server2::PublishServiceError::kInvalidIncludes = 4 }

enum class	pw::bluetooth::low_energy::Central2::ScanType : uint8_t { kPassive , pw::bluetooth::low_energy::Central2::ScanType::kActiveUsePublicAddress , pw::bluetooth::low_energy::Central2::ScanType::kActiveUseRandomAddress , pw::bluetooth::low_energy::Central2::ScanType::kActiveUseResolvablePrivateAddress }

enum class	pw::bluetooth::low_energy::Central2::ConnectError : uint8_t { pw::bluetooth::low_energy::Central2::ConnectError::kUnknownPeer , pw::bluetooth::low_energy::Central2::ConnectError::kInvalidOptions , pw::bluetooth::low_energy::Central2::ConnectError::kAlreadyExists , pw::bluetooth::low_energy::Central2::ConnectError::kCouldNotBeEstablished }
	Possible errors returned by `Connect`. More...

enum class	pw::bluetooth::low_energy::Central2::StartScanError : uint8_t { pw::bluetooth::low_energy::Central2::StartScanError::kScanInProgress , pw::bluetooth::low_energy::Central2::StartScanError::kInvalidParameters , pw::bluetooth::low_energy::Central2::StartScanError::kInternal }

enum class	pw::bluetooth::low_energy::Psm : uint16_t

enum class	pw::bluetooth::low_energy::Connection2::ConnectionParameterUpdateError : uint8_t { kFailure , kInvalidParameters , kRejected }
	Possible errors when updating the connection parameters.

enum class	pw::bluetooth::low_energy::Connection2::DisconnectReason : uint8_t { kFailure , kRemoteUserTerminatedConnection , pw::bluetooth::low_energy::Connection2::DisconnectReason::kConnectionTimeout }
	Possible reasons a connection was disconnected. More...

enum class	pw::bluetooth::low_energy::Peripheral2::AdvertiseError { pw::bluetooth::low_energy::Peripheral2::AdvertiseError::kNotSupported = 1 , pw::bluetooth::low_energy::Peripheral2::AdvertiseError::kAdvertisingDataTooLong = 2 , pw::bluetooth::low_energy::Peripheral2::AdvertiseError::kScanResponseDataTooLong = 3 , pw::bluetooth::low_energy::Peripheral2::AdvertiseError::kInvalidParameters = 4 , pw::bluetooth::low_energy::Peripheral2::AdvertiseError::kNotEnoughAdvertisingSlots = 5 , pw::bluetooth::low_energy::Peripheral2::AdvertiseError::kFailed = 6 }
	Errors returned by `Advertise`. More...

Functions
virtual async2::Poll< Status >	pw::bluetooth::Controller2::PendError (async2::Context &cx)=0

virtual async2::OnceReceiver< Status >	pw::bluetooth::Controller2::Initialize ()=0

virtual async2::OnceReceiver< Status >	pw::bluetooth::Controller2::ConfigureSco (ScoCodingFormat coding_format, ScoEncoding encoding, ScoSampleRate sample_rate)=0

virtual async2::OnceReceiver< Status >	pw::bluetooth::Controller2::ResetSco ()=0

virtual async2::OnceReceiver< FeaturesBits >	pw::bluetooth::Controller2::GetFeatures ()=0

virtual async2::OnceReceiver< Result< multibuf::MultiBuf > >	pw::bluetooth::Controller2::EncodeVendorCommand (VendorCommandParameters parameters)=0

constexpr bool	pw::bluetooth::operator& (Controller2::FeaturesBits left, Controller2::FeaturesBits right)

constexpr Controller2::FeaturesBits	pw::bluetooth::operator\| (Controller2::FeaturesBits left, Controller2::FeaturesBits right)

constexpr Controller2::FeaturesBits &	pw::bluetooth::operator\|= (Controller2::FeaturesBits &left, Controller2::FeaturesBits right)

virtual async2::Poll< RemoteServiceError >	pw::bluetooth::gatt::RemoteService2::PendError (async2::Context &cx)=0

virtual void	pw::bluetooth::gatt::RemoteService2::DiscoverCharacteristics (async2::OnceRefSender< Vector< Characteristic2 > > characteristics_sender)=0

virtual async2::OnceReceiver< pw::expected< Vector< ReadByTypeResult, 5 >, Error > >	pw::bluetooth::gatt::RemoteService2::ReadByType (Uuid uuid)=0

virtual async2::OnceReceiver< pw::expected< ReadValue, Error > >	pw::bluetooth::gatt::RemoteService2::ReadCharacteristic (Handle handle, std::optional< LongReadOptions > options)=0

virtual async2::OnceReceiver< pw::expected< void, Error > >	pw::bluetooth::gatt::RemoteService2::WriteCharacteristic (Handle handle, pw::multibuf::MultiBuf &&value, WriteOptions options)=0

virtual async2::OnceReceiver< pw::expected< ReadValue, Error > >	pw::bluetooth::gatt::RemoteService2::ReadDescriptor (Handle handle, std::optional< LongReadOptions > options)=0

virtual async2::OnceReceiver< pw::expected< void, Error > >	pw::bluetooth::gatt::RemoteService2::WriteDescriptor (Handle handle, pw::multibuf::MultiBuf &&value)=0

virtual async2::OnceReceiver< pw::expected< void, Error > >	pw::bluetooth::gatt::RemoteService2::EnableNotifications (Handle handle)=0

virtual async2::Poll< ReadValue >	pw::bluetooth::gatt::RemoteService2::PendNotification (Handle handle, async2::Context &cx)=0

virtual async2::OnceReceiver< pw::expected< void, Error > >	pw::bluetooth::gatt::RemoteService2::StopNotifications (Handle handle)=0

virtual void	pw::bluetooth::gatt::RemoteService2::Disconnect ()=0

virtual async2::Poll< RemoteServiceInfo >	pw::bluetooth::gatt::Client2::PendServiceUpdate (async2::Context &cx)

virtual async2::Poll< ServiceHandle >	pw::bluetooth::gatt::Client2::PendServiceRemoved (async2::Context &cx)

virtual pw::expected< RemoteService2::Ptr, Error >	pw::bluetooth::gatt::Client2::ConnectToService (ServiceHandle handle)=0

virtual void	pw::bluetooth::gatt::LocalServiceDelegate2::OnError (Error error)=0

virtual void	pw::bluetooth::gatt::LocalServiceDelegate2::CharacteristicConfiguration (PeerId peer_id, Handle handle, bool notify, bool indicate)=0

virtual async2::OnceReceiver< pw::expected< multibuf::MultiBuf, Error > >	pw::bluetooth::gatt::LocalServiceDelegate2::ReadValue (PeerId peer_id, Handle handle, uint32_t offset)=0

virtual async2::OnceReceiver< pw::expected< void, Error > >	pw::bluetooth::gatt::LocalServiceDelegate2::WriteValue (PeerId peer_id, Handle handle, uint32_t offset, multibuf::MultiBuf &&value)=0

virtual void	pw::bluetooth::gatt::LocalServiceDelegate2::MtuUpdate (PeerId peer_id, uint16_t mtu)=0

virtual async2::OnceReceiver< ValueChangedResult >	pw::bluetooth::gatt::LocalService2::NotifyValue (ValueChangedParameters &&parameters)=0

virtual async2::OnceReceiver< ValueChangedResult >	pw::bluetooth::gatt::LocalService2::IndicateValue (ValueChangedParameters &&parameters)=0

virtual void	pw::bluetooth::gatt::LocalService2::UnpublishService ()=0

virtual async2::OnceReceiver< PublishServiceResult >	pw::bluetooth::gatt::Server2::PublishService (const LocalServiceInfo &info, LocalServiceDelegate2 &delegate)=0

pw::Result< size_t >	pw::bluetooth::GetHciHeaderSize (emboss::H4PacketType type)

pw::Result< size_t >	pw::bluetooth::GetHciPayloadSize (emboss::H4PacketType type, pw::span< const uint8_t > hci_header)

virtual	pw::bluetooth::low_energy::Central2::ScanHandle::~ScanHandle ()=default
	Stops the scan.

virtual async2::PollResult< ScanResult >	pw::bluetooth::low_energy::Central2::ScanHandle::PendResult (async2::Context &cx)=0

virtual void	pw::bluetooth::low_energy::Central2::ScanHandle::Release ()=0

virtual async2::OnceReceiver< ConnectResult >	pw::bluetooth::low_energy::Central2::Connect (PeerId peer_id, Connection2::ConnectionOptions options)=0

virtual async2::OnceReceiver< ScanStartResult >	pw::bluetooth::low_energy::Central2::Scan (const ScanOptions &options)=0

virtual uint16_t	pw::bluetooth::low_energy::Channel::max_transmit_size ()=0
	Maximum payload size (SDU) that the peer supports receiving.

virtual uint16_t	pw::bluetooth::low_energy::Channel::max_receive_size ()=0
	Maximum payload size (SDU) that this channel supports receiving.

virtual async2::Poll< Channel::Ptr >	pw::bluetooth::low_energy::ChannelListener::PendChannel (async2::Waker &&waker)=0
	Poll to receive incoming channels.

virtual Psm	pw::bluetooth::low_energy::ChannelListener::psm ()=0
	The protocol/service multiplexer for this listener.

virtual void	pw::bluetooth::low_energy::ChannelListener::Release ()=0

virtual async2::OnceReceiver< pw::Result< ChannelListener::Ptr > >	pw::bluetooth::low_energy::ChannelListenerRegistry::ListenL2cap (ListenParameters parameters)=0

virtual	pw::bluetooth::low_energy::Connection2::~Connection2 ()=default

virtual async2::Poll< DisconnectReason >	pw::bluetooth::low_energy::Connection2::PendDisconnect (async2::Context &cx)=0

virtual gatt::Client2 *	pw::bluetooth::low_energy::Connection2::GattClient ()=0

virtual uint16_t	pw::bluetooth::low_energy::Connection2::AttMtu ()=0

virtual async2::Poll< uint16_t >	pw::bluetooth::low_energy::Connection2::PendAttMtuChange (async2::Context &cx)=0

virtual ConnectionParameters	pw::bluetooth::low_energy::Connection2::Parameters ()=0
	Returns the current connection parameters.

virtual async2::OnceReceiver< pw::expected< void, ConnectionParameterUpdateError > >	pw::bluetooth::low_energy::Connection2::RequestParameterUpdate (RequestedConnectionParameters parameters)=0

virtual async2::OnceReceiver< pw::Result< Channel::Ptr > >	pw::bluetooth::low_energy::Connection2::ConnectL2cap (ConnectL2capParameters parameters)=0

virtual void	pw::bluetooth::low_energy::Connection2::Release ()=0

virtual async2::Poll< Connection2::Ptr >	pw::bluetooth::low_energy::AdvertisedPeripheral2::PendConnection (async2::Context &cx)=0

virtual void	pw::bluetooth::low_energy::AdvertisedPeripheral2::StopAdvertising ()=0

virtual async2::Poll< pw::Status >	pw::bluetooth::low_energy::AdvertisedPeripheral2::PendStop (async2::Context &cx)=0

virtual void	pw::bluetooth::low_energy::AdvertisedPeripheral2::Release ()=0

virtual async2::OnceReceiver< AdvertiseResult >	pw::bluetooth::low_energy::Peripheral2::Advertise (const AdvertisingParameters &parameters)=0

Variables
Handle	pw::bluetooth::gatt::RemoteService2::ReadValue::handle
	Characteristic or descriptor handle.

multibuf::MultiBuf	pw::bluetooth::gatt::RemoteService2::ReadValue::value
	The value of the characteristic or descriptor.

bool	pw::bluetooth::gatt::RemoteService2::ReadValue::maybe_truncated

Handle	pw::bluetooth::gatt::RemoteService2::ReadByTypeResult::handle
	Characteristic or descriptor handle.

pw::expected< ReadValue, Error >	pw::bluetooth::gatt::RemoteService2::ReadByTypeResult::result

uint16_t	pw::bluetooth::gatt::RemoteService2::LongReadOptions::offset = 0

uint16_t	pw::bluetooth::gatt::RemoteService2::LongReadOptions::max_bytes = kMaxValueLength
	The maximum number of bytes to read.

WriteMode	pw::bluetooth::gatt::RemoteService2::WriteOptions::mode = WriteMode::kDefault

uint16_t	pw::bluetooth::gatt::RemoteService2::WriteOptions::offset = 0

ServiceHandle	pw::bluetooth::gatt::Client2::RemoteServiceInfo::handle
	Uniquely identifies this GATT service.

bool	pw::bluetooth::gatt::Client2::RemoteServiceInfo::primary
	Indicates whether this is a primary or secondary service.

Uuid	pw::bluetooth::gatt::Client2::RemoteServiceInfo::type

pw::span< const PeerId >	pw::bluetooth::gatt::LocalService2::ValueChangedParameters::peer_ids

Handle	pw::bluetooth::gatt::LocalService2::ValueChangedParameters::handle
	The handle of the characteristic value being signaled.

multibuf::MultiBuf	pw::bluetooth::gatt::LocalService2::ValueChangedParameters::value
	The new value for the descriptor/characteristic.

ServiceHandle	pw::bluetooth::gatt::Server2::LocalServiceInfo::handle
	A unique (within a Server) handle identifying this service.

bool	pw::bluetooth::gatt::Server2::LocalServiceInfo::primary
	Indicates whether this is a primary or secondary service.

Uuid	pw::bluetooth::gatt::Server2::LocalServiceInfo::type

span< const Characteristic2 >	pw::bluetooth::gatt::Server2::LocalServiceInfo::characteristics
	The characteristics of this service.

span< const ServiceHandle >	pw::bluetooth::gatt::Server2::LocalServiceInfo::includes

std::optional< Uuid >	pw::bluetooth::low_energy::Central2::ScanFilter::service_uuid
	Filter based on advertised service UUID.

std::optional< Uuid >	pw::bluetooth::low_energy::Central2::ScanFilter::service_data_uuid
	Filter based on service data containing the given UUID.

std::optional< uint16_t >	pw::bluetooth::low_energy::Central2::ScanFilter::manufacturer_id

std::optional< bool >	pw::bluetooth::low_energy::Central2::ScanFilter::connectable

std::optional< std::string_view >	pw::bluetooth::low_energy::Central2::ScanFilter::name

std::optional< int8_t >	pw::bluetooth::low_energy::Central2::ScanFilter::max_path_loss

std::optional< Uuid >	pw::bluetooth::low_energy::Central2::ScanFilter::solicitation_uuid
	Require that a peer solicits support for a service UUID.

pw::span< const ScanFilter >	pw::bluetooth::low_energy::Central2::ScanOptions::filters

uint16_t	pw::bluetooth::low_energy::Central2::ScanOptions::interval

uint16_t	pw::bluetooth::low_energy::Central2::ScanOptions::window

ScanType	pw::bluetooth::low_energy::Central2::ScanOptions::scan_type

Phy	pw::bluetooth::low_energy::Central2::ScanOptions::phys = Phy::k1Megabit

PeerId	pw::bluetooth::low_energy::Central2::ScanResult::peer_id
	Uniquely identifies this peer on the current system.

bool	pw::bluetooth::low_energy::Central2::ScanResult::connectable

std::optional< uint8_t >	pw::bluetooth::low_energy::Central2::ScanResult::rssi

pw::multibuf::MultiBuf	pw::bluetooth::low_energy::Central2::ScanResult::data
	This contains the advertising data last received from the peer.

std::optional< InlineString< 22 > >	pw::bluetooth::low_energy::Central2::ScanResult::name

chrono::SystemClock::time_point	pw::bluetooth::low_energy::Central2::ScanResult::last_updated
	Timestamp of when the information in this `ScanResult` was last updated.

bool	pw::bluetooth::low_energy::SecurityRequirements::authentication_required

bool	pw::bluetooth::low_energy::SecurityRequirements::secure_connections_required
	If true, the link must be encrypted with a Secure Connections key.

uint16_t	pw::bluetooth::low_energy::ChannelListenerRegistry::ListenParameters::max_receive_size
	Maximum supported payload size (SDU) for receiving.

SecurityRequirements	pw::bluetooth::low_energy::ChannelListenerRegistry::ListenParameters::security_requirements

uint16_t	pw::bluetooth::low_energy::Connection2::ConnectionParameters::interval

uint16_t	pw::bluetooth::low_energy::Connection2::ConnectionParameters::latency

uint16_t	pw::bluetooth::low_energy::Connection2::ConnectionParameters::supervision_timeout

uint16_t	pw::bluetooth::low_energy::Connection2::RequestedConnectionParameters::min_interval

uint16_t	pw::bluetooth::low_energy::Connection2::RequestedConnectionParameters::max_interval

uint16_t	pw::bluetooth::low_energy::Connection2::RequestedConnectionParameters::max_latency

uint16_t	pw::bluetooth::low_energy::Connection2::RequestedConnectionParameters::supervision_timeout

bool	pw::bluetooth::low_energy::Connection2::ConnectionOptions::bondable_mode = true

std::optional< Uuid >	pw::bluetooth::low_energy::Connection2::ConnectionOptions::service_filter

std::optional< RequestedConnectionParameters >	pw::bluetooth::low_energy::Connection2::ConnectionOptions::parameters

std::optional< uint16_t >	pw::bluetooth::low_energy::Connection2::ConnectionOptions::att_mtu

Psm	pw::bluetooth::low_energy::Connection2::ConnectL2capParameters::psm
	The identifier of the service to connect to.

uint16_t	pw::bluetooth::low_energy::Connection2::ConnectL2capParameters::max_receive_packet_size
	Maximum supported packet size for receiving.

SecurityRequirements	pw::bluetooth::low_energy::Connection2::ConnectL2capParameters::security_requirements

uint16_t	pw::bluetooth::low_energy::Peripheral2::AdvertisingIntervalRange::min = 0x0800
	Default: 1.28s.

uint16_t	pw::bluetooth::low_energy::Peripheral2::AdvertisingIntervalRange::max = 0x0800
	Default: 1.28s.

std::optional< ScanResponse >	pw::bluetooth::low_energy::Peripheral2::LegacyAdvertising::scan_response
	See `ScanResponse` documentation.

std::optional< ConnectionOptions >	pw::bluetooth::low_energy::Peripheral2::LegacyAdvertising::connection_options
	See `ConnectionOptions` documentation.

std::variant< std::monostate, ScanResponse, ConnectionOptions, Anonymous >	pw::bluetooth::low_energy::Peripheral2::ExtendedAdvertising::configuration

std::optional< int8_t >	pw::bluetooth::low_energy::Peripheral2::ExtendedAdvertising::tx_power

Phy	pw::bluetooth::low_energy::Peripheral2::ExtendedAdvertising::primary_phy = Phy::k1Megabit

Phy	pw::bluetooth::low_energy::Peripheral2::ExtendedAdvertising::secondary_phy = Phy::k1Megabit

AdvertisingData	pw::bluetooth::low_energy::Peripheral2::AdvertisingParameters::data

AdvertisingIntervalRange	pw::bluetooth::low_energy::Peripheral2::AdvertisingParameters::interval_range
	See `AdvertisingIntervalRange` documentation.

std::optional< Address::Type >	pw::bluetooth::low_energy::Peripheral2::AdvertisingParameters::address_type

AdvertisingProcedure	pw::bluetooth::low_energy::Peripheral2::AdvertisingParameters::procedure

Typedef Documentation

◆ ConnectionOptions

using pw::bluetooth::low_energy::Peripheral2::ConnectionOptions = Connection2::ConnectionOptions

If present, the controller will broadcast connectable advertisements which allow peers to initiate connections to the Peripheral. The fields of ConnectionOptions will configure any connections set up from advertising.

◆ Ptr [1/5]

using pw::bluetooth::gatt::RemoteService2::Ptr = internal::RaiiPtr<RemoteService2, &RemoteService2::Disconnect>

Movable RemoteService2 smart pointer. The remote server will remain connected until the returned RemoteService2::Ptr is destroyed.

◆ Ptr [2/5]

using pw::bluetooth::gatt::LocalService2::Ptr = internal::RaiiPtr<LocalService2, &LocalService2::UnpublishService>

Movable LocalService smart pointer. When the LocalService::Ptr object is destroyed the service will be unpublished.

◆ Ptr [3/5]

using pw::bluetooth::low_energy::Central2::ScanHandle::Ptr = internal::RaiiPtr<ScanHandle, &ScanHandle::Release>

Movable ScanHandle smart pointer. The controller will continue scanning until the ScanHandle::Ptr is destroyed.

◆ Ptr [4/5]

using pw::bluetooth::low_energy::Connection2::Ptr = internal::RaiiPtr<Connection2, &Connection2::Release>

Movable Connection2 smart pointer. When Connection::Ptr is destroyed the Connection2 will disconnect automatically.

◆ Ptr [5/5]

using pw::bluetooth::low_energy::AdvertisedPeripheral2::Ptr = internal::RaiiPtr<AdvertisedPeripheral2, &AdvertisedPeripheral2::Release>

Movable AdvertisedPeripheral2 smart pointer. The peripheral will continue advertising until the returned AdvertisedPeripheral::Ptr is destroyed.

◆ ScanResponse

using pw::bluetooth::low_energy::Peripheral2::ScanResponse = AdvertisingData

The fields that are to be sent in a scan response packet. Clients may use this to send additional data that does not fit inside an advertising packet on platforms that do not support the advertising data length extensions.

If present, advertisements will be configured to be scannable.

◆ ValueChangedResult

using pw::bluetooth::gatt::LocalService2::ValueChangedResult = pw::expected<void, Error>

The Result type for a ValueChanged indication or notification message. The error can be locally generated for notifications and either locally or remotely generated for indications.

Enumeration Type Documentation

◆ AdvertiseError

enum class pw::bluetooth::low_energy::Peripheral2::AdvertiseError

strong

Errors returned by Advertise.

Enumerator
kNotSupported	The operation or parameters requested are not supported on the current hardware.
kAdvertisingDataTooLong	The provided advertising data exceeds the maximum allowed length when encoded.
kScanResponseDataTooLong	The provided scan response data exceeds the maximum allowed length when encoded.
kInvalidParameters	The requested parameters are invalid.
kNotEnoughAdvertisingSlots	The maximum number of simultaneous advertisements has already been reached.
kFailed	Advertising could not be initiated due to a hardware or system error.

◆ ConnectError

enum class pw::bluetooth::low_energy::Central2::ConnectError : uint8_t

strong

Possible errors returned by Connect.

Enumerator
kUnknownPeer	The peer ID is unknown.
kInvalidOptions	The `ConnectionOptions` were invalid.
kAlreadyExists	A connection to the peer already exists.
kCouldNotBeEstablished	The connection procedure failed at the link layer or timed out immediately after being established. A "could not be established" error was reported by the controller. This may be due to interference.

◆ DisconnectReason

enum class pw::bluetooth::low_energy::Connection2::DisconnectReason : uint8_t

strong

Possible reasons a connection was disconnected.

Enumerator
kConnectionTimeout	This usually indicates that the link supervision timeout expired.

◆ FeaturesBits

enum class pw::bluetooth::Controller2::FeaturesBits : uint32_t

strong

Bitmask of features the controller supports.

Enumerator
kHciSco	Indicates support for transferring Synchronous Connection-Oriented (SCO) link data over the HCI. Offloaded SCO links may still be supported even if HCI SCO isn't.
kSetAclPriorityCommand	Indicates support for the Set Acl Priority command.
kAndroidVendorExtensions	Indicates support for the `LE_Get_Vendor_Capabilities` command documented at HCI requirements.

◆ Psm

enum class pw::bluetooth::low_energy::Psm : uint16_t

strong

An identifier for a service that accepts connection-oriented channel connections. Referred to as a (simplified) protocol/service multiplexer in the Bluetooth specification.

◆ PublishServiceError

enum class pw::bluetooth::gatt::Server2::PublishServiceError

strong

Enumerator
kInvalidHandle	The service handle provided was not unique.
kInvalidUuid	Invalid service UUID provided.
kInvalidCharacteristics	Invalid service characteristics provided.
kInvalidIncludes	Invalid service includes provided.

◆ RemoteServiceError

enum class pw::bluetooth::gatt::RemoteService2::RemoteServiceError

strong

Enumerator
kServiceRemoved	The service has been modified or removed.
kPeerDisconnected	The peer serving this service has disconnected.

◆ ScanType

enum class pw::bluetooth::low_energy::Central2::ScanType : uint8_t

strong

Enumerator
kActiveUsePublicAddress	Send scanning PDUs with the public address.
kActiveUseRandomAddress	Send scanning PDUs with the random address.
kActiveUseResolvablePrivateAddress	Send scanning PDUs with a generated Resolvable Private Address.

◆ StartScanError

enum class pw::bluetooth::low_energy::Central2::StartScanError : uint8_t

strong

Enumerator
kScanInProgress	A scan is already in progress. Only 1 scan may be active at a time.
kInvalidParameters	Some of the scan options are invalid.
kInternal	An internal error occurred and a scan could not be started.

◆ WriteMode

enum class pw::bluetooth::gatt::RemoteService2::WriteMode : uint8_t

strong

Represents the supported write modes for writing characteristics & descriptors to the server.

Enumerator
kDefault	Wait for a response from the server before returning but do not verify the echo response. Supported for both characteristics and descriptors.
kReliable	Every value blob is verified against an echo response from the server. The procedure is aborted if a value blob has not been reliably delivered to the peer. Only supported for characteristics.
kWithoutResponse	Delivery will not be confirmed before returning. Writing without a response is only supported for short characteristics with the `WRITE_WITHOUT_RESPONSE` property. The value must fit into a single message. It is guaranteed that at least 20 bytes will fit into a single message. If the value does not fit, a `kFailure` error will be produced. The value will be written at offset 0. Only supported for characteristics.

Function Documentation

◆ Advertise()

virtual async2::OnceReceiver< AdvertiseResult > pw::bluetooth::low_energy::Peripheral2::Advertise ( const AdvertisingParameters & parameters )

pure virtual

Start advertising continuously as a LE peripheral. If advertising cannot be initiated then result_callback will be called with an error. Once started, advertising can be stopped by destroying the returned AdvertisedPeripheral::Ptr.

If the system supports multiple advertising, this may be called as many times as there are advertising slots. To reconfigure an advertisement, first close the original advertisement and then initiate a new advertisement.

Parameters

parameters Parameters used while configuring the advertising instance.

Returns: Asynchronously returns a result once advertising has started or failed. On success, returns an AdvertisedPeripheral2 that models the lifetime of the advertisement. Destroying it will stop advertising.

Implemented in pw::bluetooth_sapphire::Peripheral.

◆ AttMtu()

virtual uint16_t pw::bluetooth::low_energy::Connection2::AttMtu ( )

pure virtual

Returns the current ATT Maximum Transmission Unit. By subtracting ATT headers from the MTU, the maximum payload size of messages can be calculated.

◆ CharacteristicConfiguration()

virtual void pw::bluetooth::gatt::LocalServiceDelegate2::CharacteristicConfiguration	(	PeerId	peer_id,
		Handle	handle,
		bool	notify,
		bool	indicate
	)

pure virtual

This notifies the current configuration of a particular characteristic/descriptor for a particular peer. It will be called when the peer GATT client changes the configuration.

The Bluetooth stack maintains the state of each peer's configuration across reconnections. As such, this method will be called with both notify and indicate set to false for each characteristic when a peer disconnects. Also, when a peer reconnects this method will be called again with the persisted state of the newly-connected peer's configuration. However, clients should not rely on this state being persisted indefinitely by the Bluetooth stack.

Parameters

peer_id	The PeerId of the GATT client associated with this particular CCC.
handle	The handle of the characteristic associated with the `notify` and `indicate` parameters.
notify	True if the client has enabled notifications, false otherwise.
indicate	True if the client has enabled indications, false otherwise.

◆ ConfigureSco()

virtual async2::OnceReceiver< Status > pw::bluetooth::Controller2::ConfigureSco	(	ScoCodingFormat	coding_format,
		ScoEncoding	encoding,
		ScoSampleRate	sample_rate
	)

pure virtual

Configure the HCI for a SCO connection with the indicated parameters.

Returns

OK - success, packets can be sent/received.
UNIMPLEMENTED - the implementation/controller does not support SCO over HCI
ALREADY_EXISTS - a SCO connection is already configured
INTERNAL - an internal error occurred

◆ Connect()

virtual async2::OnceReceiver< ConnectResult > pw::bluetooth::low_energy::Central2::Connect	(	PeerId	peer_id,
		Connection2::ConnectionOptions	options
	)

pure virtual

Connect to the peer with the given identifier.

The returned Connection2 represents the client's interest in the LE connection to the peer. Destroying all Connection2 instances for a peer will disconnect from the peer.

The Connection will be closed by the system if the connection to the peer is lost or an error occurs, as indicated by Connection.OnError.

Parameters

peer_id	Identifier of the peer to initiate a connection to.
options	Options used to configure the connection.

Returns: Returns a result when a connection is successfully established, or an error occurs.

Possible errors are documented in ConnectError.

◆ ConnectL2cap()

virtual async2::OnceReceiver< pw::Result< Channel::Ptr > > pw::bluetooth::low_energy::Connection2::ConnectL2cap ( ConnectL2capParameters parameters )

pure virtual

Connect to an L2CAP LE connection-oriented channel.

Parameters

parameters The parameters to configure the channel with.

Returns: The result of the connection procedure. On success, contains a Channel that can be used to exchange data.

◆ ConnectToService()

virtual pw::expected< RemoteService2::Ptr, Error > pw::bluetooth::gatt::Client2::ConnectToService ( ServiceHandle handle )

pure virtual

Connects to a RemoteService2. Only 1 connection per service is allowed.

Parameters

handle The handle of the service to connect to.

Returns: kInvalidParameters handle does not correspond to a known service.

◆ Disconnect()

virtual void pw::bluetooth::gatt::RemoteService2::Disconnect ( )

privatepure virtual

Disconnect from the remote service. This method is called by the ~RemoteServicePtr() when it goes out of scope, the API client should never call this method.

◆ DiscoverCharacteristics()

virtual void pw::bluetooth::gatt::RemoteService2::DiscoverCharacteristics ( async2::OnceRefSender< Vector< Characteristic2 > > characteristics_sender )

pure virtual

Asynchronously sends the characteristics in this service, up to Vector::.max_size(). May perform service discovery if the characteristics are not yet known.

◆ EnableNotifications()

virtual async2::OnceReceiver< pw::expected< void, Error > > pw::bluetooth::gatt::RemoteService2::EnableNotifications ( Handle handle )

pure virtual

Subscribe to notifications & indications from the characteristic with the given handle.

Either notifications or indications will be enabled depending on characteristic properties. Indications will be preferred if they are supported. This operation fails if the characteristic does not have the "notify" or "indicate" property.

A write request will be issued to configure the characteristic for notifications/indications if it contains a Client Characteristic Configuration (CCC) descriptor. This method fails if an error occurs while writing to the descriptor.

On success, PendNotification will return Ready when the peer sends a notification or indication. Indications are automatically confirmed.

Subscriptions can be canceled with StopNotifications.

Parameters

handle the handle of the characteristic to subscribe to.

Returns

The result of enabling notifications/indications.

kFailure The characteristic does not support notifications or indications.
kInvalidHandle handle is invalid.
kWriteNotPermitted CCC descriptor write error.
kInsufficient* Insufficient security properties to write to CCC descriptor.

◆ EncodeVendorCommand()

virtual async2::OnceReceiver< Result< multibuf::MultiBuf > > pw::bluetooth::Controller2::EncodeVendorCommand ( VendorCommandParameters parameters )

pure virtual

Encode the vendor-specific HCI command for a generic type of vendor command, and return the encoded command in a buffer.

Parameters

parameters Vendor command to encode.

Returns: Returns the result of the encoding request. On success, contains the command buffer.

◆ GattClient()

virtual gatt::Client2 * pw::bluetooth::low_energy::Connection2::GattClient ( )

pure virtual

Returns a GATT client to the connected peer that is valid for the lifetime of this Connection2 object. Connection2 is considered alive as long as PendDisconnect() returns pending and the object hasn't been destroyed.

◆ GetFeatures()

virtual async2::OnceReceiver< FeaturesBits > pw::bluetooth::Controller2::GetFeatures ( )

pure virtual

Returns: A bitmask of features supported by the controller.

◆ GetHciHeaderSize()

pw::Result< size_t > pw::bluetooth::GetHciHeaderSize ( emboss::H4PacketType type )

Get the size of an Hci Header

Parameters

type	H4 Packet Type

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*    OK: Size of the Hci header
* 
*    INVALID_ARGUMENT: An invalid type was provided
* 
*

◆ GetHciPayloadSize()

pw::Result< size_t > pw::bluetooth::GetHciPayloadSize	(	emboss::H4PacketType	type,
		pw::span< const uint8_t >	hci_header
	)

Get the size of an Hci Payload

Parameters

type	H4 Packet Type
hci_header	span holding at least a full header

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*    OK: Size of the Hci payload
* 
*    INVALID_ARGUMENT: An invalid type was provided
* 
*    OUT_OF_RANGE: The span was too small
* 
*

◆ IndicateValue()

virtual async2::OnceReceiver< ValueChangedResult > pw::bluetooth::gatt::LocalService2::IndicateValue ( ValueChangedParameters && parameters )

pure virtual

Sends an indication to peers. Indications should be used instead of notifications when the service does require peer confirmation of the update.

Indications should not be sent to peers which have not enabled indications on a particular characteristic. If they are sent, they will not be propagated and the result_sender will be set to an error condition. The Bluetooth stack will track this configuration for the lifetime of the service.

If any of the peers in parameters.peer_ids fails to confirm the indication within the ATT transaction timeout (30 seconds per Bluetooth 6.0 Vol. 3 Part F 3.3.3), the link between the peer and the local adapter will be closed.

The maximum size of the parameters.value field depends on the MTU negotiated with the peer. A 3-byte header plus the value contents must fit in a packet of MTU bytes.

Parameters

parameters The parameters associated with the changed characteristic.

Returns: When all the peers listed in parameters.peer_ids have confirmed the indication, the result is returned. If the implementation wishes to receive indication confirmations on a per-peer basis, they should send this event with a single PeerId in parameters.peer_ids. Additional values should not be indicated until this procedure completes.

◆ Initialize()

virtual async2::OnceReceiver< Status > pw::bluetooth::Controller2::Initialize ( )

pure virtual

Initializes the controller interface and starts processing packets. Asynchronously returns the result of initialization.

On success, HCI packets may now be sent and received with this object.

◆ ListenL2cap()

virtual async2::OnceReceiver< pw::Result< ChannelListener::Ptr > > pw::bluetooth::low_energy::ChannelListenerRegistry::ListenL2cap ( ListenParameters parameters )

pure virtual

Register a listener for incoming channels. The registry will assign a protocol/service multiplexer value that is unique for the local device, as well as create a ChannelListener for accepting incoming channels. In the unlikely event that all PSMs have been assigned, this call will fail with RESOURCE_EXHAUSTED.

Note that the method of service discovery or advertising is defined by the service or protocol, so it is the responsibility of the caller to update the GATT database or other service discovery mechanism.

Parameters

parameters Parameters for the local side of the channel.

Returns: The result of starting the listener. On success, contains a ChannelListener that can be used to receive new channels.

◆ MtuUpdate()

virtual void pw::bluetooth::gatt::LocalServiceDelegate2::MtuUpdate	(	PeerId	peer_id,
		uint16_t	mtu
	)

pure virtual

Called when the MTU of a peer is updated. Also called for peers that are already connected when the server is published.

Notifications and indications must fit in a single packet including both the 3-byte notification/indication header and the user-provided payload. If these are not used, the MTU can be safely ignored as it is intended for use cases where the throughput needs to be optimized.

◆ NotifyValue()

virtual async2::OnceReceiver< ValueChangedResult > pw::bluetooth::gatt::LocalService2::NotifyValue ( ValueChangedParameters && parameters )

pure virtual

Sends a notification to peers. Notifications should be used instead of indications when the service does not require peer confirmation of the update.

Notifications should not be sent to peers which have not enabled notifications on a particular characteristic or that have disconnected. If notifications are sent, they will not be propagated and the result_sender will be set to an error condition. The Bluetooth stack will track this configuration for the lifetime of the service.

The maximum size of the parameters.value field depends on the Maximum Transmission Unit (MTU) negotiated with the peer. A 3-byte header plus the value contents must fit in a packet of MTU bytes.

Parameters

parameters The parameters associated with the changed characteristic.

Returns: The result is returned when the notification has been sent to all peers or an error is produced when trying to send the notification to any of the peers. This value is only set only once when all associated work is done, if the implementation wishes to receive a call on a per-peer basis, they should send this event with a single PeerId in parameters.peer_ids. Additional values should not be notified until this notification completes.

◆ OnError()

virtual void pw::bluetooth::gatt::LocalServiceDelegate2::OnError ( Error error )

pure virtual

Called when there is a fatal error related to this service that forces the service to close. LocalServiceDelegate methods will no longer be called. This invalidates the associated LocalService. It is OK to destroy both LocalServiceDelegate and the associated LocalService::Ptr from within this method.

◆ PendAttMtuChange()

virtual async2::Poll< uint16_t > pw::bluetooth::low_energy::Connection2::PendAttMtuChange ( async2::Context & cx )

pure virtual

Returns Pending until the ATT MTU changes, at which point cx will be awoken. Returns Ready with the new ATT MTU once the ATT MTU has been changed. The ATT MTU can only be changed once.

◆ PendConnection()

virtual async2::Poll< Connection2::Ptr > pw::bluetooth::low_energy::AdvertisedPeripheral2::PendConnection ( async2::Context & cx )

pure virtual

For connectable advertisements, this method returns Ready when an LE central connects to the advertisement.

The returned Connection2 can be used to interact with the peer. It also represents a peripheral's ownership over the connection: the client can drop the object to request a disconnection. Similarly, the Connection2 error handler is called by the system to indicate that the connection to the peer has been lost. While connections are exclusive among peripherals, they may be shared with centrals, preventing disconnections.

After a connection is returned, advertising will be paused until PendConnection() is called again. This method may return multiple connections over the lifetime of an advertisement.

Parameters

cx	Awoken when a connection is established.

◆ PendDisconnect()

virtual async2::Poll< DisconnectReason > pw::bluetooth::low_energy::Connection2::PendDisconnect ( async2::Context & cx )

pure virtual

Returns Ready after the peer disconnects or there is a connection error that caused a disconnection. Awakens cx on disconnect.

◆ PendError() [1/2]

virtual async2::Poll< Status > pw::bluetooth::Controller2::PendError ( async2::Context & cx )

pure virtual

Returns Ready when fatal errors occur after initialization. After a fatal error, this object is invalid.

◆ PendError() [2/2]

virtual async2::Poll< RemoteServiceError > pw::bluetooth::gatt::RemoteService2::PendError ( async2::Context & cx )

pure virtual

Poll for an Error status on this service, waking cx and returning Ready when there is an error condition. When an error condition is present, any previous RemoteService2 Waker and OnceReceiver instances may or may not be woken and all other methods will be no-ops. Only 1 waker can be set at a time (additional calls will replace the existing waker).

◆ PendNotification()

virtual async2::Poll< ReadValue > pw::bluetooth::gatt::RemoteService2::PendNotification	(	Handle	handle,
		async2::Context &	cx
	)

pure virtual

After notifications have been enabled with EnableNotifications, this method can be used to check for notifications. This method will safely return Pending when notifications are disabled.

Parameters

handle	The handle of the characteristic to await for notifications.
cx	The Context to awaken when a notification is available. Only one Waker per handle is supported at a time (subsequent calls will overwrite the old Waker).

◆ PendResult()

virtual async2::PollResult< ScanResult > pw::bluetooth::low_energy::Central2::ScanHandle::PendResult ( async2::Context & cx )

pure virtual

Returns the next ScanResult if available. Otherwise, invokes cx.waker() when a ScanResult is available. Only one waker is supported at a time.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: ScanResult was returned.
* 
*     CANCELLED: An internal error occurred and the scan was cancelled.
* 
*

◆ PendServiceRemoved()

virtual async2::Poll< ServiceHandle > pw::bluetooth::gatt::Client2::PendServiceRemoved ( async2::Context & cx )

virtual

Returns the handles of services that have been removed. Note that handles may be reused, so it is recommended to check for removed services before calling PendServiceUpdate. This should be called repeatedly until Pending is returned.

Parameters

cx	Awoken when a service is removed after Pending is returned.

◆ PendServiceUpdate()

virtual async2::Poll< RemoteServiceInfo > pw::bluetooth::gatt::Client2::PendServiceUpdate ( async2::Context & cx )

virtual

Enumerates existing services found on the peer that this object represents and notifies of modifications to services or new services thereafter. If service discovery hasn't happened yet, it may be started. To further interact with services, clients must obtain a RemoteService2 protocol by calling ConnectToService.

Returns: Will return Ready with RemoteServiceInfo when there are services that are updated/modified. This can can be called repeatedly until Pending is returned to get all previously discovered services.

◆ PendStop()

virtual async2::Poll< pw::Status > pw::bluetooth::low_energy::AdvertisedPeripheral2::PendStop ( async2::Context & cx )

pure virtual

Returns Ready when advertising has stopped due to a call to StopAdvertising() or due to error. Awakens cx on stopping.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: Advertising was stopped successfully after a call to
*     ``StopAdvertising()``.
* 
*     CANCELLED: An internal error occurred and the advertisement was
*     cancelled.
* 
*

◆ PublishService()

virtual async2::OnceReceiver< PublishServiceResult > pw::bluetooth::gatt::Server2::PublishService	(	const LocalServiceInfo &	info,
		LocalServiceDelegate2 &	delegate
	)

pure virtual

Publishes the service defined by info and implemented by delegate so that it is available to all remote peers.

The caller must assign distinct handles to the characteristics and descriptors listed in info per call to PublishService (handles can be reused across calls). These identifiers will be used in requests sent to delegate.

Returns: On success, a LocalService::Ptr is returned via result_sender. When the LocalService::Ptr is destroyed or an error occurs (LocalServiceDelegate.OnError), the service will be unpublished.

◆ ReadByType()

virtual async2::OnceReceiver< pw::expected< Vector< ReadByTypeResult, 5 >, Error > > pw::bluetooth::gatt::RemoteService2::ReadByType ( Uuid uuid )

pure virtual

Reads characteristics and descriptors with the specified type. This method is useful for reading values before discovery has completed, thereby reducing latency.

Parameters

uuid	The UUID of the characteristics/descriptors to read.

Returns: The result of the read. Results may be empty if no matching values are read. If reading a value results in a permission error, the handle and error will be included.

This may fail with the following errors:

kInvalidParameters: if uuid refers to an internally reserved descriptor type (e.g. the Client Characteristic Configuration descriptor).
kTooManyResults: More results were read than can fit in the Vector. Consider reading characteristics/descriptors individually after performing discovery.
kFailure: The server returned an error not specific to a single result.

◆ ReadCharacteristic()

virtual async2::OnceReceiver< pw::expected< ReadValue, Error > > pw::bluetooth::gatt::RemoteService2::ReadCharacteristic	(	Handle	handle,
		std::optional< LongReadOptions >	options
	)

pure virtual

Reads the value of a characteristic.

Parameters

handle	The handle of the characteristic to be read.
options	If null, a short read will be performed, which may be truncated to what fits in a single message (at least 22 bytes). If long read options are present, performs a long read with the indicated options.

Returns

The result of the read and the value of the characteristic if successful. Returns the following errors:

kInvalidHandle handle is invalid.
kInvalidParameters options is invalid.
kReadNotPermitted The server rejected the request.
kInsufficient* The server rejected the request.
kApplicationError* An application error was returned by the GATT profile.
kFailure The server returned an error not covered by the above.

◆ ReadDescriptor()

virtual async2::OnceReceiver< pw::expected< ReadValue, Error > > pw::bluetooth::gatt::RemoteService2::ReadDescriptor	(	Handle	handle,
		std::optional< LongReadOptions >	options
	)

pure virtual

Reads the value of the characteristic descriptor with handle and returns it in the reply.

Parameters

handle	The descriptor handle to read.
options	Options that apply to the read.
result_sender	Set to a result containing the value of the descriptor on success.

Return values

kInvalidHandle	`handle` is invalid.
kInvalidParameters	`options` is invalid.
kReadNotPermitted
kInsufficient*	The server rejected the request.
kApplicationError*	An application error was returned by the GATT profile.
kFailure	The server returned an error not covered by the above errors.

◆ ReadValue()

virtual async2::OnceReceiver< pw::expected< multibuf::MultiBuf, Error > > pw::bluetooth::gatt::LocalServiceDelegate2::ReadValue	(	PeerId	peer_id,
		Handle	handle,
		uint32_t	offset
	)

pure virtual

Called when a peer requests to read the value of a characteristic or descriptor. It is guaranteed that the peer satisfies the permissions associated with this attribute.

Parameters

peer_id	The PeerId of the GATT client making the read request.
handle	The handle of the requested descriptor/characteristic.
offset	The offset at which to start reading the requested value.

Returns: Returns the value of the characteristic on success, or an Error on failure. The value will be truncated to fit in the MTU if necessary.

◆ Release() [1/4]

virtual void pw::bluetooth::low_energy::Central2::ScanHandle::Release ( )

privatepure virtual

Stop the current scan. This method is called by the ~ScanHandlePtr() when it goes out of scope, the API client should never call this method.

◆ Release() [2/4]

virtual void pw::bluetooth::low_energy::ChannelListener::Release ( )

privatepure virtual

Custom deleter called when ChannelListener::Ptr is destroyed. The implementation should free or clean up the memory used by this object. This enables the use of smart pointer semantics while leaving memory management up to the implementation. Calling the virtual destructor or not is up to the implementation.

◆ Release() [3/4]

virtual void pw::bluetooth::low_energy::Connection2::Release ( )

privatepure virtual

Request to destroy this connection. This method is called by the ~Connection2Ptr() when it goes out of scope, the API client should never call this method.

◆ Release() [4/4]

virtual void pw::bluetooth::low_energy::AdvertisedPeripheral2::Release ( )

privatepure virtual

Stop advertising and release memory. This method is called by the ~AdvertisedPeripheralPtr() when it goes out of scope, the API client should never call this method.

◆ RequestParameterUpdate()

virtual async2::OnceReceiver< pw::expected< void, ConnectionParameterUpdateError > > pw::bluetooth::low_energy::Connection2::RequestParameterUpdate ( RequestedConnectionParameters parameters )

pure virtual

Requests an update to the connection parameters.

Returns: Asynchronously returns the result of the request.

◆ ResetSco()

virtual async2::OnceReceiver< Status > pw::bluetooth::Controller2::ResetSco ( )

pure virtual

Releases the resources held by an active SCO connection. This should be called when a SCO connection is closed. No-op if no SCO connection is configured.

Returns

OK - success, the SCO configuration was reset.
UNIMPLEMENTED - the implementation/controller does not support SCO over
HCI INTERNAL - an internal error occurred

◆ Scan()

virtual async2::OnceReceiver< ScanStartResult > pw::bluetooth::low_energy::Central2::Scan ( const ScanOptions & options )

pure virtual

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.

Implemented in pw::bluetooth_sapphire::Central.

◆ StopAdvertising()

virtual void pw::bluetooth::low_energy::AdvertisedPeripheral2::StopAdvertising ( )

pure virtual

Requests that advertising be stopped. PendStop() can be used to wait for advertising to stop (e.g. before starting another advertisement). Destroying this object will also stop advertising, but there will be no way to determine when advertising has stopped. This method is idempotent.

◆ StopNotifications()

virtual async2::OnceReceiver< pw::expected< void, Error > > pw::bluetooth::gatt::RemoteService2::StopNotifications ( Handle handle )

pure virtual

Stops notifications for the characteristic with the given handle.

Returns

The result of disabling notifications/indications. Possible errors:

kFailure The characteristic does not support notifications or indications.
kInvalidHandle handle is invalid.
kWriteNotPermitted CCC descriptor write error.
Insufficient* CCC descriptor write error.

◆ UnpublishService()

virtual void pw::bluetooth::gatt::LocalService2::UnpublishService ( )

privatepure virtual

Unpublish the local service. This method is called by the ~LocalServicePtr() when it goes out of scope, the API client should never call this method.

◆ WriteCharacteristic()

virtual async2::OnceReceiver< pw::expected< void, Error > > pw::bluetooth::gatt::RemoteService2::WriteCharacteristic	(	Handle	handle,
		pw::multibuf::MultiBuf &&	value,
		WriteOptions	options
	)

pure virtual

Writes value to the characteristic with handle using the provided options.

Parameters

handle	Handle of the characteristic to be written to
value	The value to be written.
options	Options that apply to the write.

Returns

A result is returned when a response to the write is received. For WriteWithoutResponse, this is set as soon as the write is sent. Returns the following errors:

kInvalidHandle handle is invalid.
kInvalidParameters`options is invalid.
kWriteNotPermitted The server rejected the request.
kInsufficient* The server rejected the request.
kApplicationError* An application error was returned by the GATT profile.
kFailure The server returned an error not covered by the above errors.

◆ WriteDescriptor()

virtual async2::OnceReceiver< pw::expected< void, Error > > pw::bluetooth::gatt::RemoteService2::WriteDescriptor	(	Handle	handle,
		pw::multibuf::MultiBuf &&	value
	)

pure virtual

Writes value to the descriptor with handle using the provided. It is not recommended to send additional writes while a write is already in progress.

Parameters

handle	Handle of the descriptor to be written to.
value	The value to be written.

Returns

The result upon completion of the write. Possible errors:

kInvalidHandle handle is invalid.
kInvalidParameters `options is invalid.
kWriteNotPermitted The server rejected the request.
kInsufficient* The server rejected the request.
kApplicationError* An application error was returned by the GATT profile.
kFailure The server returned an error not covered by the above errors.

◆ WriteValue()

virtual async2::OnceReceiver< pw::expected< void, Error > > pw::bluetooth::gatt::LocalServiceDelegate2::WriteValue	(	PeerId	peer_id,
		Handle	handle,
		uint32_t	offset,
		multibuf::MultiBuf &&	value
	)

pure virtual

Called when a peer issues a request to write the value of a characteristic or descriptor. It is guaranteed that the peer satisfies the permissions associated with this attribute.

Parameters

peer_id	The PeerId of the GATT client making the write request.
handle	The handle of the requested descriptor/characteristic.
offset	The offset at which to start writing the requested value. If the offset is 0, any existing value should be overwritten by the new value. Otherwise, the existing value between `offset:(offset + len(value))` should be changed to `value`.
value	The new value for the descriptor/characteristic.

Returns: The result of the write.

◆ ~Connection2()

virtual pw::bluetooth::low_energy::Connection2::~Connection2 ( )

virtualdefault

If a disconnection has not occurred, destroying this object will result in disconnection.

Variable Documentation

◆ address_type

std::optional<Address::Type> pw::bluetooth::low_energy::Peripheral2::AdvertisingParameters::address_type

The type of address to include in advertising packets. If null, the host stack will select an address type. If the address type could not be used (either because of controller error or host configuration), a kFailed error wil be returned.

◆ att_mtu

std::optional<uint16_t> pw::bluetooth::low_energy::Connection2::ConnectionOptions::att_mtu

When present, specifies the ATT MTU to request. The actual MTU used may be smaller depending on peer and controller support. If none is specified, the host implementation will select the ATT MTU. Note that an MTU of 247 is the largest that can fit into a single LE data packet with the Data Length Extension.

LE ATT MTU Range: 23 to 517
LE EATT MTU Range: 64 to 517

◆ authentication_required

bool pw::bluetooth::low_energy::SecurityRequirements::authentication_required

If true, the link must be authenticated with on-path attacker protection. If false, authentication is not required.

◆ bondable_mode

bool pw::bluetooth::low_energy::Connection2::ConnectionOptions::bondable_mode = true

When true, the connection operates in bondable mode. This means pairing will form a bond, or persist across disconnections, if the peer is also in bondable mode. When false, the connection operates in non-bondable mode, which means the local device only allows pairing that does not form a bond.

◆ configuration

std::variant<std::monostate, ScanResponse, ConnectionOptions, Anonymous> pw::bluetooth::low_energy::Peripheral2::ExtendedAdvertising::configuration

Extended advertisements can have a scan response, be connectable, be anonymous, or none of the above. See ScanResponse, ConnectionOptions, and Anonymous documentation.

◆ connectable [1/2]

std::optional<bool> pw::bluetooth::low_energy::Central2::ScanFilter::connectable

Filter based on whether or not a device is connectable. For example, a client that is only interested in peripherals that it can connect to can set this to true. Similarly a client can scan only for broadcasters by setting this to false.

◆ connectable [2/2]

bool pw::bluetooth::low_energy::Central2::ScanResult::connectable

Whether or not this peer is connectable. Non-connectable peers are typically in the LE broadcaster role.

◆ data

AdvertisingData pw::bluetooth::low_energy::Peripheral2::AdvertisingParameters::data

The fields that will be encoded in the data section of advertising packets.

◆ filters

pw::span<const ScanFilter> pw::bluetooth::low_energy::Central2::ScanOptions::filters

List of filters for use during a scan. A peripheral that satisfies any of these filters will be reported. At least 1 filter must be specified. While not recommended, clients that require that all peripherals be reported can specify an empty filter. The span memory must only be valid until the call to Scan() ends.

◆ includes

span<const ServiceHandle> pw::bluetooth::gatt::Server2::LocalServiceInfo::includes

Handles of other services that are included by this service. The included services need to already be published.

◆ interval [1/2]

uint16_t pw::bluetooth::low_energy::Central2::ScanOptions::interval

The time interval between scans.

Time = N * 0.625ms
Range: 0x0004 (2.5ms) - 10.24s (0x4000)

◆ interval [2/2]

uint16_t pw::bluetooth::low_energy::Connection2::ConnectionParameters::interval

The connection interval indicates the frequency of link layer connection events over which data channel PDUs can be transmitted. See Core Spec v6, Vol 6, Part B, Section 4.5.1 for more information on the link layer connection events.

Range: 0x0006 to 0x0C80
Time: N * 1.25 ms
Time Range: 7.5 ms to 4 s.

◆ latency

uint16_t pw::bluetooth::low_energy::Connection2::ConnectionParameters::latency

The maximum allowed peripheral connection latency in number of connection events. See Core Spec v5, Vol 6, Part B, Section 4.5.1.

Range: 0x0000 to 0x01F3

◆ manufacturer_id

std::optional<uint16_t> pw::bluetooth::low_energy::Central2::ScanFilter::manufacturer_id

Filter based on a manufacturer identifier present in the manufacturer data. If this filter parameter is set, then the advertising payload must contain manufacturer-specific data with the provided company identifier to satisfy this filter. Manufacturer identifiers can be found at Assigned Numbers.

◆ max_interval

uint16_t pw::bluetooth::low_energy::Connection2::RequestedConnectionParameters::max_interval

Maximum value for the connection interval. This shall be greater than or equal to min_interval. The connection interval indicates the frequency of link layer connection events over which data channel PDUs can be transmitted. See Core Spec v6, Vol 6, Part B, Section 4.5.1 for more information on the link layer connection events.

Range: 0x0006 to 0x0C80
Time: N * 1.25 ms
Time Range: 7.5 ms to 4 s.

◆ max_latency

uint16_t pw::bluetooth::low_energy::Connection2::RequestedConnectionParameters::max_latency

Maximum peripheral latency for the connection in number of connection events. See Core Spec v6, Vol 6, Part B, Section 4.5.1.

Range: 0x0000 to 0x01F3

◆ max_path_loss

std::optional<int8_t> pw::bluetooth::low_energy::Central2::ScanFilter::max_path_loss

Filter results based on the path loss of the radio wave. A device that matches this filter must satisfy the following:

Radio transmission power level and received signal strength must be available for the path loss calculation.
The calculated path loss value must be less than, or equal to, max_path_loss.

Note: This field is calculated using the RSSI and TX Power information obtained from advertising and scan response data during a scan procedure. It should NOT be confused with information for an active connection obtained using the "Path Loss Reporting" feature.

◆ maybe_truncated

bool pw::bluetooth::gatt::RemoteService2::ReadValue::maybe_truncated

True if value might be truncated (the buffer was completely filled by the server and the read was a short read). ReadCharacteristic or ReadDescriptor should be used to read the complete value.

◆ min_interval

uint16_t pw::bluetooth::low_energy::Connection2::RequestedConnectionParameters::min_interval

Minimum value for the connection interval. This shall be less than or equal to max_interval. The connection interval indicates the frequency of link layer connection events over which data channel PDUs can be transmitted. See Core Spec v6, Vol 6, Part B, Section 4.5.1 for more information on the link layer connection events.

Range: 0x0006 to 0x0C80
Time: N * 1.25 ms
Time Range: 7.5 ms to 4 s.

◆ mode

WriteMode pw::bluetooth::gatt::RemoteService2::WriteOptions::mode = WriteMode::kDefault

The mode of the write operation. For descriptors, only WriteMode::kDefault is supported

◆ name [1/2]

std::optional<std::string_view> pw::bluetooth::low_energy::Central2::ScanFilter::name

Filter results based on a portion of the advertised device name. Substring matches are allowed. The name length must be at most pw::bluetooth::kMaxDeviceNameLength.

◆ name [2/2]

std::optional<InlineString<22> > pw::bluetooth::low_energy::Central2::ScanResult::name

The name of this peer. The name is often obtained during a scan procedure and can get updated during the name discovery procedure following a connection.

This field is present if the name is known.

◆ offset [1/2]

uint16_t pw::bluetooth::gatt::RemoteService2::LongReadOptions::offset = 0

The byte to start the read at. Must be less than the length of the value.

◆ offset [2/2]

uint16_t pw::bluetooth::gatt::RemoteService2::WriteOptions::offset = 0

Request a write starting at the byte indicated. Must be 0 if mode is WriteMode.kWithoutResponse.

◆ parameters

std::optional<RequestedConnectionParameters> pw::bluetooth::low_energy::Connection2::ConnectionOptions::parameters

When present, specifies the initial connection parameters. Otherwise, the connection parameters will be selected by the implementation.

◆ peer_ids

pw::span<const PeerId> pw::bluetooth::gatt::LocalService2::ValueChangedParameters::peer_ids

The peers peers to signal. The LocalService should respect the Characteristic Configuration associated with a peer+handle when deciding whether to signal it. If empty, all peers which configured the handle are signalled.

◆ phys

Phy pw::bluetooth::low_energy::Central2::ScanOptions::phys = Phy::k1Megabit

A bitmask of the PHYs to scan with. Only the 1Megabit and LeCoded PHYs are supported.

◆ primary_phy

Phy pw::bluetooth::low_energy::Peripheral2::ExtendedAdvertising::primary_phy = Phy::k1Megabit

The primary physical layer configuration to advertise with. Can only be 1Megabit or LeCoded PHY. If the PHY is not supported, a kNotSupported error will be returned.

◆ procedure

AdvertisingProcedure pw::bluetooth::low_energy::Peripheral2::AdvertisingParameters::procedure

Specifies the advertising procedure to use and the parameters specific to that procedure.

◆ result

pw::expected<ReadValue, Error> pw::bluetooth::gatt::RemoteService2::ReadByTypeResult::result

The value of the characteristic or descriptor, if it was read successfully, or an error explaining why the value could not be read.

◆ rssi

std::optional<uint8_t> pw::bluetooth::low_energy::Central2::ScanResult::rssi

The last observed signal strength of this peer. This field is only present for a peer that is broadcasting. The RSSI can be stale if the peer has not been advertising.

Note: This field should NOT be confused with the "connection RSSI" of a peer that is currently connected to the system.

◆ scan_type

ScanType pw::bluetooth::low_energy::Central2::ScanOptions::scan_type

Specifies whether to send scan requests, and if so, what type of address to use in scan requests.

◆ secondary_phy

Phy pw::bluetooth::low_energy::Peripheral2::ExtendedAdvertising::secondary_phy = Phy::k1Megabit

The secondary physical layer configuration to advertise with. Can be any PHY. If the PHY is not supported, a kNotSupported error will be returned.

◆ security_requirements [1/2]

SecurityRequirements pw::bluetooth::low_energy::ChannelListenerRegistry::ListenParameters::security_requirements

The security requirements that must be met before data is exchanged on the channel. If the requirements cannot be met, channel establishment will fail.

◆ security_requirements [2/2]

SecurityRequirements pw::bluetooth::low_energy::Connection2::ConnectL2capParameters::security_requirements

The security requirements that must be met before data is exchanged on the channel. If the requirements cannot be met, channel establishment will fail.

◆ service_filter

std::optional<Uuid> pw::bluetooth::low_energy::Connection2::ConnectionOptions::service_filter

When present, service discovery performed following the connection is restricted to primary services that match this field. Otherwise, by default all available services are discovered.

◆ supervision_timeout [1/2]

uint16_t pw::bluetooth::low_energy::Connection2::ConnectionParameters::supervision_timeout

This defines the maximum time between two received data packet PDUs before the connection is considered lost. See Core Spec v6, Vol 6, Part B, Section 4.5.2.

Range: 0x000A to 0x0C80
Time: N * 10 ms
Time Range: 100 ms to 32 s

◆ supervision_timeout [2/2]

uint16_t pw::bluetooth::low_energy::Connection2::RequestedConnectionParameters::supervision_timeout

This defines the maximum time between two received data packet PDUs before the connection is considered lost. See Core Spec v6, Vol 6, Part B, Section 4.5.2.

Range: 0x000A to 0x0C80
Time: N * 10 ms
Time Range: 100 ms to 32 s

◆ tx_power

std::optional<int8_t> pw::bluetooth::low_energy::Peripheral2::ExtendedAdvertising::tx_power

The maximum power level to transmit with. Null indicates no preference. Range: -127 to +20 Units: dBm

◆ type [1/2]

Uuid pw::bluetooth::gatt::Client2::RemoteServiceInfo::type

The UUID that identifies the type of this service. There may be multiple services with the same UUID.

◆ type [2/2]

Uuid pw::bluetooth::gatt::Server2::LocalServiceInfo::type

The UUID that identifies the type of this service. There may be multiple services with the same UUID.

◆ window

uint16_t pw::bluetooth::low_energy::Central2::ScanOptions::window

The duration of the scan. The window must be less than or equal to the interval.

Time = N * 0.625ms
Range: 0x0004 (2.5ms) - 10.24s (0x4000)

Oveview

Classes

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ ConnectionOptions

◆ Ptr [1/5]

◆ Ptr [2/5]

◆ Ptr [3/5]

◆ Ptr [4/5]

◆ Ptr [5/5]

◆ ScanResponse

◆ ValueChangedResult

Enumeration Type Documentation

◆ AdvertiseError

◆ ConnectError

◆ DisconnectReason

◆ FeaturesBits

◆ Psm

◆ PublishServiceError

◆ RemoteServiceError

◆ ScanType

◆ StartScanError

◆ WriteMode

Function Documentation

◆ Advertise()

◆ AttMtu()

◆ CharacteristicConfiguration()

◆ ConfigureSco()

◆ Connect()

◆ ConnectL2cap()

◆ ConnectToService()

◆ Disconnect()

◆ DiscoverCharacteristics()

◆ EnableNotifications()

◆ EncodeVendorCommand()

◆ GattClient()

◆ GetFeatures()

◆ GetHciHeaderSize()

◆ GetHciPayloadSize()

◆ IndicateValue()

◆ Initialize()

◆ ListenL2cap()

◆ MtuUpdate()

◆ NotifyValue()

◆ OnError()

◆ PendAttMtuChange()

◆ PendConnection()

◆ PendDisconnect()

◆ PendError() [1/2]

◆ PendError() [2/2]

◆ PendNotification()

◆ PendResult()

◆ PendServiceRemoved()

◆ PendServiceUpdate()

◆ PendStop()

◆ PublishService()

◆ ReadByType()

◆ ReadCharacteristic()

◆ ReadDescriptor()

◆ ReadValue()

◆ Release() [1/4]

◆ Release() [2/4]

◆ Release() [3/4]

◆ Release() [4/4]

◆ RequestParameterUpdate()

◆ ResetSco()

◆ Scan()

◆ StopAdvertising()

◆ StopNotifications()

◆ UnpublishService()

◆ WriteCharacteristic()

◆ WriteDescriptor()

◆ WriteValue()

◆ ~Connection2()

Variable Documentation

◆ address_type

◆ att_mtu