pw_bluetooth: Add Host API Doxygen docs
Add Host API Doxygen docs to pw_bluetooth docs.
Rename Central::Scan type to Central::ScanHandle because the name
conflicts with Central::Scan(), and Doxygen throws an error.
Change-Id: I4a5bab1887997ef104ea20d2f0d1c08f55fd91fe
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/130932
Reviewed-by: Ali Saeed <saeedali@google.com>
Reviewed-by: Anthony DiGirolamo <tonymd@google.com>
Commit-Queue: Ben Lawson <benlawson@google.com>
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index a45ec50..ca399d0 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -111,6 +111,12 @@
# All sources with doxygen comment blocks.
"$dir_pw_async/public/pw_async/dispatcher.h",
"$dir_pw_async/public/pw_async/task.h",
+ "$dir_pw_bluetooth/public/pw_bluetooth/host.h",
+ "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/central.h",
+ "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/peripheral.h",
+ "$dir_pw_bluetooth/public/pw_bluetooth/low_energy/connection.h",
+ "$dir_pw_bluetooth/public/pw_bluetooth/gatt/client.h",
+ "$dir_pw_bluetooth/public/pw_bluetooth/gatt/server.h",
"$dir_pw_chrono/public/pw_chrono/system_clock.h",
"$dir_pw_chrono/public/pw_chrono/system_timer.h",
"$dir_pw_string/public/pw_string/string_builder.h",
diff --git a/pw_bluetooth/docs.rst b/pw_bluetooth/docs.rst
index 62bad33..428f625 100644
--- a/pw_bluetooth/docs.rst
+++ b/pw_bluetooth/docs.rst
@@ -17,6 +17,76 @@
is the entry point from which all other APIs are exposed. Currently, only Low
Energy APIs exist.
+Host
+====
+.. doxygenclass:: pw::bluetooth::Host
+ :members:
+
+low_energy::Central
+===================
+.. doxygenclass:: pw::bluetooth::low_energy::Central
+ :members:
+
+low_energy::Peripheral
+======================
+.. doxygenclass:: pw::bluetooth::low_energy::Peripheral
+ :members:
+
+low_energy::AdvertisedPeripheral
+================================
+.. doxygenclass:: pw::bluetooth::low_energy::AdvertisedPeripheral
+ :members:
+
+low_energy::Connection
+======================
+.. doxygenclass:: pw::bluetooth::low_energy::Connection
+ :members:
+
+low_energy::ConnectionOptions
+=============================
+.. doxygenstruct:: pw::bluetooth::low_energy::ConnectionOptions
+ :members:
+
+low_energy::RequestedConnectionParameters
+=========================================
+.. doxygenstruct:: pw::bluetooth::low_energy::RequestedConnectionParameters
+ :members:
+
+low_energy::ConnectionParameters
+================================
+.. doxygenstruct:: pw::bluetooth::low_energy::ConnectionParameters
+ :members:
+
+gatt::Server
+============
+.. doxygenclass:: pw::bluetooth::gatt::Server
+ :members:
+
+gatt::LocalServiceInfo
+======================
+.. doxygenstruct:: pw::bluetooth::gatt::LocalServiceInfo
+ :members:
+
+gatt::LocalService
+==================
+.. doxygenclass:: pw::bluetooth::gatt::LocalService
+ :members:
+
+gatt::LocalServiceDelegate
+==========================
+.. doxygenclass:: pw::bluetooth::gatt::LocalServiceDelegate
+ :members:
+
+gatt::Client
+============
+.. doxygenclass:: pw::bluetooth::gatt::Client
+ :members:
+
+gatt::RemoteService
+===================
+.. doxygenclass:: pw::bluetooth::gatt::RemoteService
+ :members:
+
Callbacks
=========
This module contains callback-heavy APIs. Callbacks must not call back into the
diff --git a/pw_bluetooth/public/pw_bluetooth/gatt/client.h b/pw_bluetooth/public/pw_bluetooth/gatt/client.h
index a8346f8..e12de22 100644
--- a/pw_bluetooth/public/pw_bluetooth/gatt/client.h
+++ b/pw_bluetooth/public/pw_bluetooth/gatt/client.h
@@ -27,86 +27,86 @@
namespace pw::bluetooth::gatt {
-// Represents a GATT service on a remote GATT server.
-// Clients should call `SetErrorCallback` before using in order to handle fatal
-// errors.
+/// Represents a GATT service on a remote GATT server.
+/// Clients should call `SetErrorCallback` before using in order to handle fatal
+/// errors.
class RemoteService {
public:
enum class RemoteServiceError {
- // The service has been modified or removed.
+ /// The service has been modified or removed.
kServiceRemoved = 0,
- // The peer serving this service has disconnected.
+ /// The peer serving this service has disconnected.
kPeerDisconnected = 1,
};
- // Wrapper around a possible truncated value received from the server.
+ /// Wrapper around a possible truncated value received from the server.
struct ReadValue {
- // Characteristic or descriptor handle.
+ /// Characteristic or descriptor handle.
Handle handle;
- // The value of the characteristic or descriptor.
+ /// The value of the characteristic or descriptor.
Vector<std::byte> value;
- // 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.
+ /// 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.
bool maybe_truncated;
};
- // A result returned by `ReadByType`.
+ /// A result returned by `ReadByType`.
struct ReadByTypeResult {
- // Characteristic or descriptor handle.
+ /// Characteristic or descriptor handle.
Handle handle;
- // The value of the characteristic or descriptor, if it was read
- // successfully, or an error explaining why the value could not be read.
+ /// The value of the characteristic or descriptor, if it was read
+ /// successfully, or an error explaining why the value could not be read.
Result<Error, ReadValue> result;
};
- // Represents the supported options to read a long characteristic or
- // descriptor value from a server. Long values are those that may not fit in a
- // single message (longer than 22 bytes).
+ /// Represents the supported options to read a long characteristic or
+ /// descriptor value from a server. Long values are those that may not fit in
+ /// a single message (longer than 22 bytes).
struct LongReadOptions {
- // The byte to start the read at. Must be less than the length of the
- // value.
+ /// The byte to start the read at. Must be less than the length of the
+ /// value.
uint16_t offset = 0;
- // The maximum number of bytes to read.
+ /// The maximum number of bytes to read.
uint16_t max_bytes = kMaxValueLength;
};
- // Represents the supported write modes for writing characteristics &
- // descriptors to the server.
+ /// Represents the supported write modes for writing characteristics &
+ /// descriptors to the server.
enum class WriteMode : uint8_t {
- // Wait for a response from the server before returning but do not verify
- // the echo response. Supported for both characteristics and descriptors.
+ /// Wait for a response from the server before returning but do not verify
+ /// the echo response. Supported for both characteristics and descriptors.
kDefault = 0,
- // 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.
+ /// 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.
kReliable = 1,
- // 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.
+ /// 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.
kWithoutResponse = 2,
};
- // Represents the supported options to write a characteristic/descriptor value
- // to a server.
+ /// Represents the supported options to write a characteristic/descriptor
+ /// value to a server.
struct WriteOptions {
- // The mode of the write operation. For descriptors, only
- // `WriteMode::kDefault` is supported
+ /// The mode of the write operation. For descriptors, only
+ /// `WriteMode::kDefault` is supported
WriteMode mode = WriteMode::kDefault;
- // Request a write starting at the byte indicated.
- // Must be 0 if `mode` is `WriteMode.kWithoutResponse`.
+ /// Request a write starting at the byte indicated.
+ /// Must be 0 if `mode` is `WriteMode.kWithoutResponse`.
uint16_t offset = 0;
};
@@ -114,181 +114,193 @@
using ReadCallback = Function<void(Result<ReadValue>)>;
using NotificationCallback = Function<void(ReadValue)>;
- // Set a callback that will be called when there is an error with this
- // RemoteService, after which this RemoteService will be invalid.
+ /// Set a callback that will be called when there is an error with this
+ /// RemoteService, after which this RemoteService will be invalid.
void SetErrorCallback(Function<void(RemoteServiceError)>&& error_callback);
- // Calls `characteristic_callback` with the characteristics and descriptors in
- // this service.
+ /// Calls `characteristic_callback` with the characteristics and descriptors
+ /// in this service.
void DiscoverCharacteristics(
Function<void(Characteristic)>&& characteristic_callback);
- // Reads characteristics and descriptors with the specified type. This method
- // is useful for reading values before discovery has completed, thereby
- // reducing latency.
- // `uuid` - The UUID of the characteristics/descriptors to read.
- // `result_callback` - Results are returned via this callback. 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 a Vector. Consider reading characteristics/descriptors individually
- // after performing discovery.
- // kFailure: The server returned an error not specific to a single result.
+ /// Reads characteristics and descriptors with the specified type. This method
+ /// is useful for reading values before discovery has completed, thereby
+ /// reducing latency.
+ /// @param uuid The UUID of the characteristics/descriptors to read.
+ /// @param result_callback Results are returned via this callback. 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 a Vector.
+ /// Consider reading characteristics/descriptors individually after performing
+ /// discovery.
+ /// - kFailure: The server returned an error not specific to a single result.
void ReadByType(Uuid uuid, ReadByTypeCallback&& result_callback);
- // Reads the value of a characteristic.
- // `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.
- // `result_callback` - called with the result of the read and the value of the
- // characteristic if successful.
- //
- // This may fail with the following errors:
- // kInvalidHandle - if `handle` is invalid
- // kInvalidParameters - if `options is invalid
- // kReadNotPermitted or kInsufficient* if the server rejects the request.
- // kFailure if the server returns an error not covered by the above errors.
+ /// Reads the value of a characteristic.
+ /// @param handle The handle of the characteristic to be read.
+ /// @param 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.
+ /// @param result_callback called with the result of the read and the value of
+ /// the characteristic if successful.
+ /// @retval kInvalidHandle `handle` is invalid.
+ /// @retval kInvalidParameters `options` is invalid.
+ /// @retval kReadNotPermitted The server rejected the request.
+ /// @retval kInsufficient* The server rejected the request.
+ /// @retval kFailure The server returned an error not covered by the above.
void ReadCharacteristic(Handle handle,
std::optional<LongReadOptions> options,
ReadCallback&& result_callback);
- // Writes `value` to the characteristic with `handle` using the provided
- // `options`. It is not recommended to send additional writes while a write
- // is already in progress (the server may receive simultaneous writes in any
- // order).
- //
- // Parameters:
- // `handle` - Handle of the characteristic to be written to
- // `value` - The value to be written.
- // `options` - Options that apply to the write.
- //
- // This may fail with the following errors:
- // kInvalidHandle - if `handle` is invalid
- // kInvalidParameters - if `options is invalid
- // kWriteNotPermitted or kInsufficient* if the server rejects the request.
- // kFailure if the server returns an error not covered by the above errors.
+ /// Writes `value` to the characteristic with `handle` using the provided
+ /// `options`. It is not recommended to send additional writes while a write
+ /// is already in progress (the server may receive simultaneous writes in any
+ /// order).
+ ///
+ /// @param handle Handle of the characteristic to be written to
+ /// @param value The value to be written.
+ /// @param options Options that apply to the write.
+ /// @param result_callback Returns a result upon completion of the write.
+ /// @retval kInvalidHandle `handle` is invalid.
+ /// @retval kInvalidParameters`options is invalid.
+ /// @retval kWriteNotPermitted The server rejected the request.
+ /// @retval kInsufficient* The server rejected the request.
+ /// @retval kFailure The server returned an error not covered by the above
+ /// errors.
void WriteCharacteristic(Handle handle,
span<const std::byte> value,
WriteOptions options,
Function<void(Result<Error>)>&& result_callback);
- // Reads the value of the characteristic descriptor with `handle` and
- // returns it in the reply.
- // `handle` - The descriptor handle to read.
- // `options` - Options that apply to the read.
- // `result_callback` - Returns a result containing the value of the descriptor
- // on success.
- //
- // This may fail with the following errors:
- // `kInvalidHandle` - if `handle` is invalid.
- // `kInvalidParameters` - if `options` is invalid.
- // `kReadNotPermitted` or `INSUFFICIENT_*` - if the server rejects the read
- // request. `kFailure` - if the server returns an error.
+ /// Reads the value of the characteristic descriptor with `handle` and
+ /// returns it in the reply.
+ /// @param handle The descriptor handle to read.
+ /// @param options Options that apply to the read.
+ /// @param result_callback Returns a result containing the value of the
+ /// descriptor on success.
+ /// @retval kInvalidHandle `handle` is invalid.
+ /// @retval kInvalidParameters`options` is invalid.
+ /// @retval kReadNotPermitted
+ /// @retval kInsufficient* The server rejected the request.
+ /// @retval kFailure The server returned an error not covered by the above
+ /// errors.
void ReadDescriptor(Handle handle,
std::optional<LongReadOptions> options,
ReadCallback&& result_callback);
+ /// Writes `value` to the descriptor with `handle` using the provided
+ /// `options`. It is not recommended to send additional writes while a write
+ /// is already in progress (the server may receive simultaneous writes in any
+ /// order).
+ ///
+ /// @param handle Handle of the descriptor to be written to
+ /// @param value The value to be written.
+ /// @param options Options that apply to the write.
+ /// @param result_callback Returns a result upon completion of the write.
+ /// @retval kInvalidHandle `handle` is invalid.
+ /// @retval kInvalidParameters `options is invalid
+ /// @retval kWriteNotPermitted The server rejected the request.
+ /// @retval kInsufficient* The server rejected the request.
+ /// @retval kFailure The server returned an error not covered by the above
+ /// errors.
void WriteDescriptor(Handle handle,
span<const std::byte> value,
WriteOptions options,
Function<void(Result<Error>)>&& result_callback);
- // 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 descriptor. This method fails if an error occurs while
- // writing to the descriptor.
- //
- // On success, `notification_callback` will be called 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.
- // `notification_callback` - will be called with the values of
- // notifications/indications when received.
- // `result_callback` - called with the result of enabling
- // notifications/indications.
- //
- // This may fail with the following errors:
- // `kFailure` - the characteristic does not support notifications or
- // indications.
- // `kInvalidHandle` - `handle` is invalid.
- // `kWriteNotPermitted`or `kInsufficient*` - descriptor write error.
+ /// 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 descriptor. This method fails if an error occurs while
+ /// writing to the descriptor.
+ ///
+ /// On success, `notification_callback` will be called when
+ /// the peer sends a notification or indication. Indications are
+ /// automatically confirmed.
+ ///
+ /// Subscriptions can be canceled with `StopNotifications`.
+ ///
+ /// @param handle the handle of the characteristic to subscribe to.
+ /// @param notification_callback will be called with the values of
+ /// notifications/indications when received.
+ /// @param result_callback called with the result of enabling
+ /// notifications/indications.
+ /// @retval kFailure The characteristic does not support notifications or
+ /// indications.
+ /// @retval kInvalidHandle `handle` is invalid.
+ /// @retval kWriteNotPermitted CCC descriptor write error.
+ /// @retval Insufficient* CCC descriptor write error.
void RegisterNotificationCallback(
Handle handle,
NotificationCallback&& notification_callback,
Function<void(Result<Error>)>&& result_callback);
- // Stops notifications for the characteristic with the given `handle`.
+ /// Stops notifications for the characteristic with the given `handle`.
void StopNotifications(Handle handle);
private:
- // Disconnect from the remote service. This method is called by the
- // ~RemoteService::Ptr() when it goes out of scope, the API client should
- // never call this method.
+ /// Disconnect from the remote service. This method is called by the
+ /// ~RemoteService::Ptr() when it goes out of scope, the API client should
+ /// never call this method.
void Disconnect();
public:
- // Movable RemoteService smart pointer. The remote server will remain
- // connected until the returned RemoteService::Ptr is destroyed.
+ /// Movable RemoteService smart pointer. The remote server will remain
+ /// connected until the returned RemoteService::Ptr is destroyed.
using Ptr = internal::RaiiPtr<RemoteService, &RemoteService::Disconnect>;
};
-// Represents a GATT client that interacts with services on a GATT server.
+/// Represents a GATT client that interacts with services on a GATT server.
class Client {
public:
- // Represents a remote GATT service.
+ /// Represents a remote GATT service.
struct RemoteServiceInfo {
- // Uniquely identifies this GATT service.
+ /// Uniquely identifies this GATT service.
Handle handle;
- // Indicates whether this is a primary or secondary service.
+ /// Indicates whether this is a primary or secondary service.
bool primary;
- // The UUID that identifies the type of this service.
- // There may be multiple services with the same UUID.
+ /// The UUID that identifies the type of this service.
+ /// There may be multiple services with the same UUID.
Uuid type;
};
virtual ~Client() = default;
- // Enumerates existing services found on the peer that this Client represents,
- // and provides a stream of updates thereafter. Results can be filtered by
- // specifying a list of UUIDs in `uuids`. To further interact with services,
- // clients must obtain a RemoteService protocol by calling ConnectToService().
- // `uuid_allowlist` - The allowlist of UUIDs to filter services with.
- // `updated_callback` - Will be called with services that are
- // updated/modified.
- // `removed_callback` - Called with the handles of services
- // that have been removed. Note that handles may be reused.
+ /// Enumerates existing services found on the peer that this Client
+ /// represents, and provides a stream of updates thereafter. Results can be
+ /// filtered by specifying a list of UUIDs in `uuids`. To further interact
+ /// with services, clients must obtain a RemoteService protocol by calling
+ /// ConnectToService(). `uuid_allowlist` - The allowlist of UUIDs to filter
+ /// services with. `updated_callback` - Will be called with services that are
+ /// updated/modified.
+ /// `removed_callback` - Called with the handles of services
+ /// that have been removed. Note that handles may be reused.
virtual void WatchServices(
Vector<Uuid> uuid_allowlist,
Function<void(RemoteServiceInfo)>&& updated_callback,
Function<void(Handle)>&& removed_callback) = 0;
- // Stops service watching if started by `WatchServices`.
+ /// Stops service watching if started by `WatchServices`.
virtual void StopWatchingServices();
- // Connects to a RemoteService. Only 1 connection per service is allowed.
- // `handle` - the handle of the service to connect to.
- //
- // This may fail with the following errors:
- // kInvalidParameters - `handle` does not correspond to a known service.
+ /// Connects to a RemoteService. Only 1 connection per service is allowed.
+ /// `handle` - the handle of the service to connect to.
+ ///
+ /// This may fail with the following errors:
+ /// kInvalidParameters - `handle` does not correspond to a known service.
virtual Result<Error, RemoteService::Ptr> ConnectToService(Handle handle) = 0;
};
diff --git a/pw_bluetooth/public/pw_bluetooth/gatt/server.h b/pw_bluetooth/public/pw_bluetooth/gatt/server.h
index 3cf6fc0..4dc719d 100644
--- a/pw_bluetooth/public/pw_bluetooth/gatt/server.h
+++ b/pw_bluetooth/public/pw_bluetooth/gatt/server.h
@@ -28,208 +28,207 @@
namespace pw::bluetooth::gatt {
-// Parameters for registering a local GATT service.
+/// Parameters for registering a local GATT service.
struct LocalServiceInfo {
- // A unique (within a Server) handle identifying this service.
+ /// A unique (within a Server) handle identifying this service.
Handle handle;
- // Indicates whether this is a primary or secondary service.
+ /// Indicates whether this is a primary or secondary service.
bool primary;
- // The UUID that identifies the type of this service.
- // There may be multiple services with the same UUID.
+ /// The UUID that identifies the type of this service.
+ /// There may be multiple services with the same UUID.
Uuid type;
- // The characteristics of this service.
+ /// The characteristics of this service.
span<const Characteristic> characteristics;
- // Handles of other services that are included by this service.
+ /// Handles of other services that are included by this service.
span<const Handle> includes;
};
-// Interface for serving a local GATT service. This is implemented by the API
-// client.
+/// Interface for serving a local GATT service. This is implemented by the API
+/// client.
class LocalServiceDelegate {
public:
virtual ~LocalServiceDelegate() = default;
- // 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.
+ /// 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.
virtual void OnError(Error error) = 0;
- // 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 also be called when a peer
- // connects for each characteristic with the initial, 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.
+ /// 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 also be called when a peer
+ /// connects for each characteristic with the initial, persisted state of the
+ /// newly-connected peer's configuration. However, clients should not rely on
+ /// this state being persisted indefinitely by the Bluetooth stack.
+ ///
+ /// @param peer_id The PeerId of the GATT client associated with this
+ /// particular CCC.
+ /// @param handle The handle of the characteristic associated with the
+ /// `notify` and `indicate` parameters.
+ /// @param notify True if the client has enabled notifications, false
+ /// otherwise.
+ /// @param indicate True if the client has enabled indications, false
+ /// otherwise.
virtual void CharacteristicConfiguration(PeerId peer_id,
Handle handle,
bool notify,
bool indicate) = 0;
- // 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.
- // `result_callback` - Called with the value of the characteristic on success,
- // or an Error on failure. The value will be truncated to fit in the MTU
- // if necessary. It is OK to call `result_callback` in `ReadValue`.
+ /// 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.
+ ///
+ /// @param peer_id The PeerId of the GATT client making the read request.
+ /// @param handle The handle of the requested descriptor/characteristic.
+ /// @param offset The offset at which to start reading the requested value.
+ /// @param result_callback Called with the value of the characteristic on
+ /// success, or an Error on failure. The value will be truncated to fit in the
+ /// MTU if necessary. It is OK to call `result_callback` in `ReadValue`.
virtual void ReadValue(PeerId peer_id,
Handle handle,
uint32_t offset,
Function<void(Result<Error, span<const std::byte>>)>&&
result_callback) = 0;
- // 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.
- // `status_callback` - Called with the result of the write.
+ /// 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.
+ ///
+ /// @param peer_id The PeerId of the GATT client making the write request.
+ /// @param handle The handle of the requested descriptor/characteristic.
+ /// @param 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`.
+ /// @param value The new value for the descriptor/characteristic.
+ /// @param status_callback Called with the result of the write.
virtual void WriteValue(PeerId peer_id,
Handle handle,
uint32_t offset,
span<const std::byte> value,
Function<void(Result<Error>)>&& status_callback) = 0;
- // Called when the MTU of a peer is updated. Also called for peers that are
- // already connected when the server is published. This method is safe to
- // ignore if you do not care about the MTU. It is intended for use cases where
- // throughput needs to be optimized.
+ /// Called when the MTU of a peer is updated. Also called for peers that are
+ /// already connected when the server is published. This method is safe to
+ /// ignore if you do not care about the MTU. It is intended for use cases
+ /// where throughput needs to be optimized.
virtual void MtuUpdate(PeerId peer_id, uint16_t mtu) = 0;
};
-// Interface provided by the backend to interact with a published service.
-// LocalService is valid for the lifetime of a published GATT service. It is
-// used to control the service and send notifications/indications.
+/// Interface provided by the backend to interact with a published service.
+/// LocalService is valid for the lifetime of a published GATT service. It is
+/// used to control the service and send notifications/indications.
class LocalService {
public:
- // The parameters used to signal a characteristic value change from a
- // LocalService to a peer.
+ /// The parameters used to signal a characteristic value change from a
+ /// LocalService to a peer.
struct ValueChangedParameters {
- // The PeerIds of the 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 are signalled.
+ /// The PeerIds of the 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 are signalled.
span<const PeerId> peer_ids;
- // The handle of the characteristic value being signaled.
+ /// The handle of the characteristic value being signaled.
Handle handle;
- // The new value for the descriptor/characteristic.
+ /// The new value for the descriptor/characteristic.
span<const std::byte> value;
};
virtual ~LocalService() = default;
- // 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 - if they are sent, they will
- // not be propagated. The Bluetooth stack will track this configuration for
- // the lifetime of the service.
- //
- // Parameters:
- // `parameters` - The parameters associated with the changed characteristic.
- // `completion_callback` - Called when the notification has been sent.
- // Additional values should not be notified until this callback is called.
+ /// 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 - if they are sent, they will
+ /// not be propagated. The Bluetooth stack will track this configuration for
+ /// the lifetime of the service.
+ ///
+ /// @param parameters The parameters associated with the changed
+ /// characteristic.
+ /// @param completion_callback Called when the notification has been sent.
+ /// Additional values should not be notified until this callback is called.
virtual void NotifyValue(const ValueChangedParameters& parameters,
Closure&& completion_callback) = 0;
- // 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. The Bluetooth stack will track this configuration for the
- // lifetime of the service.
- //
- // If any of the peers in `update.peer_ids` fails to confirm the indication
- // within the ATT transaction timeout (30 seconds per Bluetooth 5.2 Vol. 4
- // Part G 3.3.3), the link between the peer and the local adapter will be
- // closed.
- //
- // Parameters:
- // `parameters` - The parameters associated with the changed characteristic.
- // `confirmation` - When all the peers listed in `parameters.peer_ids` have
- // confirmed the indication, `confirmation` is called. 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 callback is called.
+ /// 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. The Bluetooth stack will track this configuration for the
+ /// lifetime of the service.
+ ///
+ /// If any of the peers in `update.peer_ids` fails to confirm the indication
+ /// within the ATT transaction timeout (30 seconds per Bluetooth 5.2 Vol. 4
+ /// Part G 3.3.3), the link between the peer and the local adapter will be
+ /// closed.
+ ///
+ /// @param parameters The parameters associated with the changed
+ /// characteristic.
+ /// @param confirmation When all the peers listed in `parameters.peer_ids`
+ /// have confirmed the indication, `confirmation` is called. 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 callback is called.
virtual void IndicateValue(const ValueChangedParameters& parameters,
Function<void(Result<Error>)>&& confirmation) = 0;
private:
- // Unpublish the local service. This method is called by the
- // ~LocalService::Ptr() when it goes out of scope, the API client should never
- // call this method.
+ /// Unpublish the local service. This method is called by the
+ /// ~LocalService::Ptr() when it goes out of scope, the API client should
+ /// never call this method.
virtual void UnpublishService() = 0;
public:
- // Movable LocalService smart pointer. When the LocalService::Ptr object is
- // destroyed the service will be unpublished.
+ /// Movable LocalService smart pointer. When the LocalService::Ptr object is
+ /// destroyed the service will be unpublished.
using Ptr = internal::RaiiPtr<LocalService, &LocalService::UnpublishService>;
};
-// Interface for a GATT server that serves many GATT services.
+/// Interface for a GATT server that serves many GATT services.
class Server {
public:
enum class PublishServiceError {
kInternalError = 0,
- // The service handle provided was not unique.
+ /// The service handle provided was not unique.
kInvalidHandle = 1,
- // Invalid service UUID provided.
+ /// Invalid service UUID provided.
kInvalidUuid = 2,
- // Invalid service characteristics provided.
+ /// Invalid service characteristics provided.
kInvalidCharacteristics = 3,
- // Invalid service includes provided.
+ /// Invalid service includes provided.
kInvalidIncludes = 4,
};
- // The Result passed by PublishService.
+ /// The Result passed by PublishService.
using PublishServiceResult = Result<PublishServiceError, LocalService::Ptr>;
virtual ~Server() = default;
- // 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`. These identifiers will be used in requests
- // sent to `delegate`. On success, a `LocalService::Ptr` is returned. When the
- // `LocalService::Ptr` is destroyed or an error occurs
- // (LocalServiceDelegate.OnError), the service will be unpublished.
+ /// 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`. These identifiers will be used in requests
+ /// sent to `delegate`. On success, a `LocalService::Ptr` is returned. When
+ /// the `LocalService::Ptr` is destroyed or an error occurs
+ /// (LocalServiceDelegate.OnError), the service will be unpublished.
virtual void PublishService(
const LocalServiceInfo& info,
LocalServiceDelegate* delegate,
diff --git a/pw_bluetooth/public/pw_bluetooth/host.h b/pw_bluetooth/public/pw_bluetooth/host.h
index 6fa0ad2..d5f3f30 100644
--- a/pw_bluetooth/public/pw_bluetooth/host.h
+++ b/pw_bluetooth/public/pw_bluetooth/host.h
@@ -32,162 +32,162 @@
namespace pw::bluetooth {
-// Host is the entrypoint API for interacting with a Bluetooth host stack. Host
-// is an abstract class that is implemented by a host stack implementation.
+/// Host is the entrypoint API for interacting with a Bluetooth host stack. Host
+/// is an abstract class that is implemented by a host stack implementation.
class Host {
public:
- // Represents the persistent configuration of a single Host instance. This is
- // used for identity representation in advertisements & bonding secrets
- // recall.
+ /// Represents the persistent configuration of a single Host instance. This is
+ /// used for identity representation in advertisements & bonding secrets
+ /// recall.
struct PersistentData {
- // The local Identity Resolving Key used by a Host to generate Resolvable
- // Private Addresses when privacy is enabled. May be absent for hosts that
- // do not use LE privacy, or that only use Non-Resolvable Private Addresses.
- //
- // NOTE: This key is distributed to LE peers during pairing procedures. The
- // client must take care to assign an IRK that consistent with the local
- // Host identity.
+ /// The local Identity Resolving Key used by a Host to generate Resolvable
+ /// Private Addresses when privacy is enabled. May be absent for hosts that
+ /// do not use LE privacy, or that only use Non-Resolvable Private
+ /// Addresses.
+ ///
+ /// NOTE: This key is distributed to LE peers during pairing procedures. The
+ /// client must take care to assign an IRK that consistent with the local
+ /// Host identity.
std::optional<Key> identity_resolving_key;
- // All bonds that use a public identity address must contain the same local
- // address.
+ /// All bonds that use a public identity address must contain the same local
+ /// address.
span<const low_energy::BondData> bonds;
};
- // The security level required for this pairing. This corresponds to the
- // security levels defined in the Security Manager Protocol in Core spec v5.3,
- // Vol 3, Part H, Section 2.3.1
+ /// The security level required for this pairing. This corresponds to the
+ /// security levels defined in the Security Manager Protocol in Core spec
+ /// v5.3, Vol 3, Part H, Section 2.3.1
enum class PairingSecurityLevel : uint8_t {
- // Encrypted without person-in-the-middle protection (unauthenticated)
+ /// Encrypted without person-in-the-middle protection (unauthenticated)
kEncrypted,
- // Encrypted with person-in-the-middle protection (authenticated), although
- // this level of security does not fully protect against passive
- // eavesdroppers
+ /// Encrypted with person-in-the-middle protection (authenticated), although
+ /// this level of security does not fully protect against passive
+ /// eavesdroppers
kAuthenticated,
- // Encrypted with person-in-the-middle protection (authenticated).
- // This level of security fully protects against eavesdroppers.
+ /// Encrypted with person-in-the-middle protection (authenticated).
+ /// This level of security fully protects against eavesdroppers.
kLeSecureConnections,
};
- // Whether or not the device should form a bluetooth bond during the pairing
- // prodecure. As described in Core Spec v5.2, Vol 3, Part C, Sec 4.3
+ /// Whether or not the device should form a bluetooth bond during the pairing
+ /// prodecure. As described in Core Spec v5.2, Vol 3, Part C, Sec 4.3
enum class BondableMode : uint8_t {
- // The device will form a bond during pairing with peers
+ /// The device will form a bond during pairing with peers
kBondable,
- // The device will not form a bond during pairing with peers
+ /// The device will not form a bond during pairing with peers
kNonBondable,
};
- // Parameters that give a caller more fine-grained control over the pairing
- // process.
+ /// Parameters that give a caller more fine-grained control over the pairing
+ /// process.
struct PairingOptions {
- // Determines the Security Manager security level to pair with.
+ /// Determines the Security Manager security level to pair with.
PairingSecurityLevel security_level = PairingSecurityLevel::kAuthenticated;
- // Indicated whether the device should form a bond or not during pairing. If
- // not present, interpreted as bondable mode.
+ /// Indicated whether the device should form a bond or not during pairing.
+ /// If not present, interpreted as bondable mode.
BondableMode bondable_mode = BondableMode::kBondable;
};
- // `Close` should complete before `Host` is destroyed.
+ /// `Close()` should complete before `Host` is destroyed.
virtual ~Host() = default;
- // Initializes the host stack. Vendor specific controller initialization (e.g.
- // loading firmware) must be done before initializing `Host`.
- //
- // Parameters:
- // `controller` - Pointer to a concrete `Controller` that the host stack
- // should use to communicate with the controller.
- // `data` - Data to persist from a previous instance of `Host`.
- // `on_initialization_complete` - Called when initialization is complete.
- // Other methods should not be called until initialization completes.
+ /// Initializes the host stack. Vendor specific controller initialization
+ /// (e.g. loading firmware) must be done before initializing `Host`.
+ ///
+ /// @param controller Pointer to a concrete `Controller` that the host stack
+ /// should use to communicate with the controller.
+ /// @param data Data to persist from a previous instance of `Host`.
+ /// @param on_initialization_complete Called when initialization is complete.
+ /// Other methods should not be called until initialization completes.
virtual void Initialize(
Controller* controller,
PersistentData data,
Function<void(Status)>&& on_initialization_complete) = 0;
- // Safely shuts down the host, ending all active Bluetooth procedures:
- // - All objects/pointers associated with this host are destroyed/invalidated
- // and all connections disconnected.
- // - All scanning and advertising procedures are stopped.
- //
- // The Host may send events or call callbacks as procedures get terminated.
- // `callback` will be called once all procedures have terminated.
+ /// Safely shuts down the host, ending all active Bluetooth procedures:
+ /// - All objects/pointers associated with this host are destroyed/invalidated
+ /// and all connections disconnected.
+ /// - All scanning and advertising procedures are stopped.
+ ///
+ /// The Host may send events or call callbacks as procedures get terminated.
+ /// @param callback Will be called once all procedures have terminated.
virtual void Close(Closure callback) = 0;
- // Returns a pointer to the Central API, which is used to scan and connect to
- // peers.
+ /// Returns a pointer to the Central API, which is used to scan and connect to
+ /// peers.
virtual low_energy::Central* Central() = 0;
- // Returns a pointer to the Peripheral API, which is used to advertise and
- // accept connections from peers.
+ /// Returns a pointer to the Peripheral API, which is used to advertise and
+ /// accept connections from peers.
virtual low_energy::Peripheral* Peripheral() = 0;
- // Returns a pointer to the GATT Server API, which is used to publish GATT
- // services.
+ /// Returns a pointer to the GATT Server API, which is used to publish GATT
+ /// services.
virtual gatt::Server* GattServer() = 0;
- // Deletes a peer from the Bluetooth host. If the peer is connected, it will
- // be disconnected. `peer_id` will no longer refer to any peer.
- //
- // Returns `OK` after no peer exists that's identified by `peer_id` (even
- // if it didn't exist), `ABORTED` if the peer could not be disconnected or
- // deleted and still exists.
+ /// Deletes a peer from the Bluetooth host. If the peer is connected, it will
+ /// be disconnected. `peer_id` will no longer refer to any peer.
+ ///
+ /// Returns `OK` after no peer exists that's identified by `peer_id` (even
+ /// if it didn't exist), `ABORTED` if the peer could not be disconnected or
+ /// deleted and still exists.
virtual Status ForgetPeer(PeerId peer_id) = 0;
- // Enable or disable the LE privacy feature. When enabled, the host will use a
- // private device address in all LE procedures. When disabled, the public
- // identity address will be used instead (which is the default).
+ /// Enable or disable the LE privacy feature. When enabled, the host will use
+ /// a private device address in all LE procedures. When disabled, the public
+ /// identity address will be used instead (which is the default).
virtual void EnablePrivacy(bool enabled) = 0;
- // Set the GAP LE Security Mode of the host. Only encrypted,
- // connection-based security modes are supported, i.e. Mode 1 and Secure
- // Connections Only mode. If the security mode is set to Secure Connections
- // Only, any existing encrypted connections which do not meet the security
- // requirements of Secure Connections Only mode will be disconnected.
+ /// Set the GAP LE Security Mode of the host. Only encrypted,
+ /// connection-based security modes are supported, i.e. Mode 1 and Secure
+ /// Connections Only mode. If the security mode is set to Secure Connections
+ /// Only, any existing encrypted connections which do not meet the security
+ /// requirements of Secure Connections Only mode will be disconnected.
virtual void SetSecurityMode(low_energy::SecurityMode security_mode) = 0;
- // Assigns the pairing delegate that will respond to authentication challenges
- // using the given I/O capabilities. Calling this method cancels any on-going
- // pairing procedure started using a previous delegate. Pairing requests will
- // be rejected if no PairingDelegate has been assigned.
+ /// Assigns the pairing delegate that will respond to authentication
+ /// challenges using the given I/O capabilities. Calling this method cancels
+ /// any on-going pairing procedure started using a previous delegate. Pairing
+ /// requests will be rejected if no PairingDelegate has been assigned.
virtual void SetPairingDelegate(InputCapability input,
OutputCapability output,
PairingDelegate* pairing_delegate) = 0;
- // NOTE: This is intended to satisfy test scenarios that require pairing
- // procedures to be initiated without relying on service access. In normal
- // operation, Bluetooth security is enforced during service access.
- //
- // Initiates pairing to the peer with the supplied `peer_id` and `options`.
- // Returns an error if no connected peer with `peer_id` is found or the
- // pairing procedure fails.
- //
- // If `options` specifies a higher security level than the current pairing,
- // this method attempts to raise the security level. Otherwise this method has
- // no effect and returns success.
- //
- // Returns the following errors via `callback`:
- // `NOT_FOUND` - The peer `peer_id` was not found.
- // `ABORTED` - The pairing procedure failed.
+ /// NOTE: This is intended to satisfy test scenarios that require pairing
+ /// procedures to be initiated without relying on service access. In normal
+ /// operation, Bluetooth security is enforced during service access.
+ ///
+ /// Initiates pairing to the peer with the supplied `peer_id` and `options`.
+ /// Returns an error if no connected peer with `peer_id` is found or the
+ /// pairing procedure fails.
+ ///
+ /// If `options` specifies a higher security level than the current pairing,
+ /// this method attempts to raise the security level. Otherwise this method
+ /// has no effect and returns success.
+ ///
+ /// Returns the following errors via `callback`:
+ /// `NOT_FOUND` - The peer `peer_id` was not found.
+ /// `ABORTED` - The pairing procedure failed.
virtual void Pair(PeerId peer_id,
PairingOptions options,
Function<void(Status)>&& callback) = 0;
- // Configures a callback to be called when new bond data for a peer has been
- // created. This data should be persisted and used to initialize Host in the
- // future. New bond data may be received for an already bonded peer, in which
- // case the new data should overwrite the old data.
+ /// Configures a callback to be called when new bond data for a peer has been
+ /// created. This data should be persisted and used to initialize Host in the
+ /// future. New bond data may be received for an already bonded peer, in which
+ /// case the new data should overwrite the old data.
virtual void SetBondDataCallback(
Function<void(low_energy::BondData)>&& callback) = 0;
- // Looks up the `PeerId` corresponding to `address`. If `address` does not
- // correspond to a known peer, a new `PeerId` will be generated for the
- // address. If a `PeerId` cannot be generated, std::nullopt will be returned.
+ /// Looks up the `PeerId` corresponding to `address`. If `address` does not
+ /// correspond to a known peer, a new `PeerId` will be generated for the
+ /// address. If a `PeerId` cannot be generated, std::nullopt will be returned.
virtual std::optional<PeerId> PeerIdFromAddress(Address address) = 0;
- // Looks up the Address corresponding to `peer_id`. Returns null if `peer_id`
- // does not correspond to a known peer.
+ /// Looks up the Address corresponding to `peer_id`. Returns null if `peer_id`
+ /// does not correspond to a known peer.
virtual std::optional<Address> DeviceAddressFromPeerId(PeerId peer_id) = 0;
};
diff --git a/pw_bluetooth/public/pw_bluetooth/low_energy/central.h b/pw_bluetooth/public/pw_bluetooth/low_energy/central.h
index 2753feb..391e691 100644
--- a/pw_bluetooth/public/pw_bluetooth/low_energy/central.h
+++ b/pw_bluetooth/public/pw_bluetooth/low_energy/central.h
@@ -27,104 +27,105 @@
namespace pw::bluetooth::low_energy {
-// Represents the LE central role. Used to scan and connect to peripherals.
+/// Represents the LE central role. Used to scan and connect to peripherals.
class Central {
public:
- // Represents an ongoing LE scan.
- class Scan {
+ /// Represents an ongoing LE scan.
+ class ScanHandle {
public:
+ /// Possible errors that can cause a scan to stop prematurely.
enum class ScanError : uint8_t { kCanceled = 0 };
- virtual ~Scan() = 0;
+ virtual ~ScanHandle() = 0;
- // Set a callback that will be called if the scan is stopped due to an error
- // in the BLE stack.
+ /// Set a callback that will be called if the scan is stopped due to an
+ /// error in the BLE stack.
virtual void SetErrorCallback(Function<void(ScanError)>&& callback) = 0;
private:
- // Stop the current scan. This method is called by the ~Scan::Ptr() when it
- // goes out of scope, the API client should never call this method.
+ /// Stop the current scan. This method is called by the ~ScanHandle::Ptr()
+ /// when it goes out of scope, the API client should never call this method.
virtual void StopScan() = 0;
public:
- // Movable Scan smart pointer. The controller will continue scanning until
- // the returned Scan::Ptr is destroyed.
- using Ptr = internal::RaiiPtr<Scan, &Scan::StopScan>;
+ /// Movable ScanHandle smart pointer. The controller will continue scanning
+ /// until the ScanHandle::Ptr is destroyed.
+ using Ptr = internal::RaiiPtr<ScanHandle, &ScanHandle::StopScan>;
};
- // Filter parameters for use during a scan. A discovered peer only matches the
- // filter if it satisfies all of the present filter parameters.
+ /// Filter parameters for use during a scan. A discovered peer only matches
+ /// the filter if it satisfies all of the present filter parameters.
struct ScanFilter {
- // Filter based on advertised service UUID.
+ /// Filter based on advertised service UUID.
std::optional<Uuid> service_uuid;
- // Filter based on service data containing the given UUID.
+ /// Filter based on service data containing the given UUID.
std::optional<Uuid> service_data_uuid;
- // 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
- // https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/
+ /// 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
+ /// https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/
std::optional<uint16_t> manufacturer_id;
- // 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.
+ /// 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.
std::optional<bool> connectable;
- // 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.
+ /// 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.
std::optional<std::string_view> name;
- // Filter results based on the path loss of the radio wave. A device that
- // matches this filter must satisfy the following:
- // 1. Radio transmission power level and received signal strength must be
- // available for the path loss calculation.
- // 2. 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.
+ /// Filter results based on the path loss of the radio wave. A device that
+ /// matches this filter must satisfy the following:
+ /// 1. Radio transmission power level and received signal strength must be
+ /// available for the path loss calculation.
+ /// 2. 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.
std::optional<uint8_t> max_path_loss;
};
- // Parameters used during a scan.
+ /// Parameters used during a scan.
struct ScanOptions {
- // 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.
+ /// 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.
Vector<ScanFilter> filters;
- // The time interval between scans.
- // Time = N * 0.625ms
- // Range: 0x0004 (2.5ms) - 10.24ms (0x4000)
- // Default: 10ms
+ /// The time interval between scans.
+ /// - Time = N * 0.625ms
+ /// - Range: 0x0004 (2.5ms) - 10.24ms (0x4000)
+ /// - Default: 10ms
uint16_t interval = 0x0010;
- // 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.24ms (0x4000)
- // Default: 10ms
+ /// 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.24ms (0x4000)
+ /// - Default: 10ms
uint16_t window = 0x0010;
};
- // Information obtained from advertising and scan response data broadcast by a
- // peer.
+ /// Information obtained from advertising and scan response data broadcast by
+ /// a peer.
struct ScanData {
- // The radio transmit power level.
- // NOTE: This field should NOT be confused with the "connection TX Power
- // Level" of a peer that is currently connected to the system obtained via
- // the "Transmit Power reporting" feature.
+ /// The radio transmit power level.
+ /// @note This field should NOT be confused with the "connection TX Power
+ /// Level" of a peer that is currently connected to the system obtained via
+ /// the "Transmit Power reporting" feature.
std::optional<uint8_t> tx_power;
- // The appearance of the device.
+ /// The appearance of the device.
std::optional<Appearance> appearance;
Vector<Uuid> service_uuids;
@@ -133,122 +134,121 @@
Vector<ManufacturerData> manufacturer_data;
- // String representing a URI to be advertised, as defined in IETF STD
- // 66: https://tools.ietf.org/html/std66. Each entry should be a UTF-8
- // string including the scheme. For more information, see
- // https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml for
- // allowed schemes; NOTE: Bluetooth advertising compresses schemas over the
- // air to save space. See
- // https://www.bluetooth.com/specifications/assigned-numbers/uri-scheme-name-string-mapping.
+ /// String representing a URI to be advertised, as defined in IETF STD 66:
+ /// https://tools.ietf.org/html/std66. Each entry should be a UTF-8 string
+ /// including the scheme. For more information, see
+ /// https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml for
+ /// allowed schemes;
+ /// @note Bluetooth advertising compresses schemas over the air to save
+ /// space. See
+ /// https://www.bluetooth.com/specifications/assigned-numbers/uri-scheme-name-string-mapping.
Vector<std::string_view> uris;
- // The time when this scan data was received.
+ /// The time when this scan data was received.
chrono::SystemClock::time_point timestamp;
};
struct ScanResult {
- // ScanResult is non-copyable becuase strings are only valid in the
- // result callback.
+ /// ScanResult is non-copyable because strings are only valid in the result
+ /// callback.
ScanResult(const ScanResult&) = delete;
ScanResult& operator=(const ScanResult&) = delete;
- // Uniquely identifies this peer on the current system.
+ /// Uniquely identifies this peer on the current system.
PeerId peer_id;
- // Whether or not this peer is connectable. Non-connectable peers are
- // typically in the LE broadcaster role.
+ /// Whether or not this peer is connectable. Non-connectable peers are
+ /// typically in the LE broadcaster role.
bool connectable;
- // 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.
+ /// 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.
std::optional<uint8_t> rssi;
- // Information from advertising and scan response data broadcast by this
- // peer. This contains the advertising data last received from the peer.
+ /// Information from advertising and scan response data broadcast by this
+ /// peer. This contains the advertising data last received from the peer.
ScanData scan_data;
- // 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.
+ /// 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.
std::optional<std::string_view> name;
- // Timestamp of when the information in this `ScanResult` was last updated.
+ /// Timestamp of when the information in this `ScanResult` was last updated.
chrono::SystemClock::time_point last_updated;
};
- // Possible errors returned by `Connect`.
+ /// Possible errors returned by `Connect`.
enum class ConnectError : uint8_t {
- // The peer ID is unknown.
+ /// The peer ID is unknown.
kUnknownPeer,
- // The `ConnectionOptions` were invalid.
+ /// The `ConnectionOptions` were invalid.
kInvalidOptions,
- // A connection to the peer already exists.
+ /// A connection to the peer already exists.
kAlreadyExists,
- // A connection could not be established.
+ /// A connection could not be established.
kCouldNotBeEstablished,
};
enum class StartScanError : uint8_t {
- // A scan is already in progress. Only 1 scan may be active at a time.
+ /// A scan is already in progress. Only 1 scan may be active at a time.
kScanInProgress,
- // Some of the scan options are invalid.
+ /// Some of the scan options are invalid.
kInvalidParameters,
- // An internal error occurred and a scan could not be started.
+ /// An internal error occurred and a scan could not be started.
kInternal,
};
- // The Result type returned by Connect() via the passed callback.
+ /// The Result type returned by Connect() via the passed callback.
using ConnectResult = Result<ConnectError, Connection::Ptr>;
virtual ~Central() = default;
- // Connect to the peer with the given identifier.
- //
- // The requested `Connection` represents the client's interest in the LE
- // connection to the peer. Destroying the `Connection` will disconnect from
- // the peer. Only 1 connection per peer may exist at a time.
- //
- // 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:
- // `id` - Identifier of the peer to initiate a connection to.
- // `options` - Options used to configure the connection.
- // `callback` - Called when a connection is successfully established, or an
- // error occurs.
- //
- // Possible errors are documented in `ConnectError`.
+ /// Connect to the peer with the given identifier.
+ ///
+ /// The requested `Connection` represents the client's interest in the LE
+ /// connection to the peer. Destroying the `Connection` will disconnect from
+ /// the peer. Only 1 connection per peer may exist at a time.
+ ///
+ /// 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`.
+ ///
+ /// @param peer_id Identifier of the peer to initiate a connection to.
+ /// @param options Options used to configure the connection.
+ /// @param callback Called when a connection is successfully established, or
+ /// an error occurs.
+ ///
+ /// Possible errors are documented in `ConnectError`.
virtual void Connect(PeerId peer_id,
ConnectionOptions options,
Function<void(ConnectResult)>&& callback) = 0;
- // Scans for nearby LE peripherals and broadcasters. The lifetime of the scan
- // session is tied to the returned `Scan` object. Once a scan is started,
- // `scan_result_callback` will be called with scan results. Only 1 scan may be
- // active at a time. It is OK to destroy the `Scan::Ptr` object in
- // `scan_result_callback` to stop scanning (no more results will be returned).
- //
- // Parameters:
- // `options` - Options used to configure the scan session.
- // `scan_result_callback` - If scanning starts successfully,called for LE
- // peers that satisfy the filters indicated in `options`. The initial
- // calls may report recently discovered peers. Subsequent calls will
- // be made only when peers have been scanned or updated since the last
- // call.
- // `scan_started_callback` - Called with a `Scan` object if the
- // scan successfully starts, or a `ScanError` otherwise.
+ /// Scans for nearby LE peripherals and broadcasters. The lifetime of the scan
+ /// session is tied to the returned `ScanHandle` object. Once a scan is
+ /// started, `scan_result_callback` will be called with scan results. Only 1
+ /// scan may be active at a time. It is OK to destroy the `ScanHandle::Ptr`
+ /// object in `scan_result_callback` to stop scanning (no more results will be
+ /// returned).
+ ///
+ /// @param options Options used to configure the scan session.
+ /// @param scan_result_callback If scanning starts successfully,called for LE
+ /// peers that satisfy the filters indicated in `options`. The initial calls
+ /// may report recently discovered peers. Subsequent calls will be made only
+ /// when peers have been scanned or updated since the last call.
+ /// @param scan_started_callback Called with a `ScanHandle` object if the scan
+ /// successfully starts, or a `ScanError` otherwise.
virtual void Scan(ScanOptions options,
Function<void(ScanResult)>&& scan_result_callback,
- Function<void(Result<StartScanError, Scan::Ptr>)>&&
+ Function<void(Result<StartScanError, ScanHandle::Ptr>)>&&
scan_started_callback) = 0;
};
diff --git a/pw_bluetooth/public/pw_bluetooth/low_energy/connection.h b/pw_bluetooth/public/pw_bluetooth/low_energy/connection.h
index e7d823f..d310953 100644
--- a/pw_bluetooth/public/pw_bluetooth/low_energy/connection.h
+++ b/pw_bluetooth/public/pw_bluetooth/low_energy/connection.h
@@ -19,84 +19,84 @@
namespace pw::bluetooth::low_energy {
-// Actual connection parameters returned by the controller.
+/// Actual connection parameters returned by the controller.
struct ConnectionParameters {
- // The connection interval indicates the frequency of link layer connection
- // events over which data channel PDUs can be transmitted. See Core Spec v5.3,
- // 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.
+ /// The connection interval indicates the frequency of link layer connection
+ /// events over which data channel PDUs can be transmitted. See Core Spec
+ /// v5.3, 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.
uint16_t interval;
- // The maximum allowed peripheral connection latency in number of connection
- // events. See Core Spec v5.3, Vol 6, Part B, Section 4.5.2.
- // Range: 0x0000 to 0x01F3
+ /// The maximum allowed peripheral connection latency in number of connection
+ /// events. See Core Spec v5.3, Vol 6, Part B, Section 4.5.2.
+ /// - Range: 0x0000 to 0x01F3
uint16_t latency;
- // This defines the maximum time between two received data packet PDUs
- // before the connection is considered lost. See Core Spec v5.3, Vol 6, Part
- // B, Section 4.5.2.
- // Range: 0x000A to 0x0C80
- // Time: N * 10 ms
- // Time Range: 100 ms to 32 s
+ /// This defines the maximum time between two received data packet PDUs
+ /// before the connection is considered lost. See Core Spec v5.3, Vol 6, Part
+ /// B, Section 4.5.2.
+ /// - Range: 0x000A to 0x0C80
+ /// - Time: N * 10 ms
+ /// - Time Range: 100 ms to 32 s
uint16_t supervision_timeout;
};
-// Connection parameters that either the local device or a peer device are
-// requesting.
+/// Connection parameters that either the local device or a peer device are
+/// requesting.
struct RequestedConnectionParameters {
- // 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 v5.3, 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.
+ /// 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 v5.3, 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.
uint16_t min_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 v5.3, 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.
+ /// 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 v5.3, 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.
uint16_t max_interval;
- // Maximum peripheral latency for the connection in number of connection
- // events. See Core Spec v5.3, Vol 6, Part B, Section 4.5.2.
- // Range: 0x0000 to 0x01F3
+ /// Maximum peripheral latency for the connection in number of connection
+ /// events. See Core Spec v5.3, Vol 6, Part B, Section 4.5.2.
+ /// - Range: 0x0000 to 0x01F3
uint16_t max_latency;
- // This defines the maximum time between two received data packet PDUs
- // before the connection is considered lost. See Core Spec v5.3, Vol 6, Part
- // B, Section 4.5.2.
- // Range: 0x000A to 0x0C80
- // Time: N * 10 ms
- // Time Range: 100 ms to 32 s
+ /// This defines the maximum time between two received data packet PDUs
+ /// before the connection is considered lost. See Core Spec v5.3, Vol 6, Part
+ /// B, Section 4.5.2.
+ /// - Range: 0x000A to 0x0C80
+ /// - Time: N * 10 ms
+ /// - Time Range: 100 ms to 32 s
uint16_t supervision_timeout;
};
-// Represents parameters that are set on a per-connection basis.
+/// Represents parameters that are set on a per-connection basis.
struct ConnectionOptions {
- // 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.
+ /// 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.
bool bondable_mode = true;
- // 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.
+ /// 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.
std::optional<Uuid> service_filter;
- // When present, specifies the initial connection parameters. Otherwise, the
- // connection parameters will be selected by the implementation.
+ /// When present, specifies the initial connection parameters. Otherwise, the
+ /// connection parameters will be selected by the implementation.
std::optional<RequestedConnectionParameters> parameters;
};
@@ -107,66 +107,66 @@
/// represents. Destroying the object results in a disconnection.
class Connection {
public:
- // Possible errors when updating the connection parameters.
+ /// Possible errors when updating the connection parameters.
enum class ConnectionParameterUpdateError : uint8_t {
kFailure,
kInvalidParameters,
kRejected,
};
- // Possible reasons a connection was disconnected.
+ /// Possible reasons a connection was disconnected.
enum class DisconnectReason : uint8_t {
kFailure,
kRemoteUserTerminatedConnection,
- // This usually indicates that the link supervision timeout expired.
+ /// This usually indicates that the link supervision timeout expired.
kConnectionTimeout,
};
- // If a disconnection has not occurred, destroying this object will result in
- // disconnection.
+ /// If a disconnection has not occurred, destroying this object will result in
+ /// disconnection.
virtual ~Connection() = default;
- // Sets a callback that will be called when the peer disconnects or there is a
- // connection error that causes a disconnection. This should be configured by
- // the client immediately after establishing the connection. `callback` will
- // not be called for disconnections initiated by the client (e.g. by
- // destroying `Connection`). It is OK to destroy this object from within
- // `callback`.
+ /// Sets a callback that will be called when the peer disconnects or there is
+ /// a connection error that causes a disconnection. This should be configured
+ /// by the client immediately after establishing the connection. `callback`
+ /// will not be called for disconnections initiated by the client (e.g. by
+ /// destroying `Connection`). It is OK to destroy this object from within
+ /// `callback`.
virtual void SetDisconnectCallback(
Function<void(DisconnectReason)>&& callback) = 0;
- // Returns a GATT client to the connected peer that is valid for the lifetime
- // of this connection. The client is valid for the lifetime of this
- // connection.
+ /// Returns a GATT client to the connected peer that is valid for the lifetime
+ /// of this connection. The client is valid for the lifetime of this
+ /// connection.
virtual gatt::Client* GattClient() = 0;
- // Returns the current ATT Maximum Transmission Unit. By subtracting ATT
- // headers from the MTU, the maximum payload size of messages can be
- // calculated.
+ /// Returns the current ATT Maximum Transmission Unit. By subtracting ATT
+ /// headers from the MTU, the maximum payload size of messages can be
+ /// calculated.
virtual uint16_t AttMtu() = 0;
- // Sets a callback that will be called with the new ATT MTU whenever it is
- // updated.
+ /// Sets a callback that will be called with the new ATT MTU whenever it is
+ /// updated.
virtual void SetAttMtuChangeCallback(Function<void(uint16_t)> callback) = 0;
- // Returns the current connection parameters.
+ /// Returns the current connection parameters.
virtual ConnectionParameters Parameters() = 0;
- // Requests an update to the connection parameters. `callback` will be called
- // with the result of the request.
+ /// Requests an update to the connection parameters. `callback` will be called
+ /// with the result of the request.
virtual void RequestConnectionParameterUpdate(
RequestedConnectionParameters parameters,
Function<void(Result<ConnectionParameterUpdateError>)>&& callback) = 0;
private:
- // Request to disconnect this connection. This method is called by the
- // ~Connection::Ptr() when it goes out of scope, the API client should never
- // call this method.
+ /// Request to disconnect this connection. This method is called by the
+ /// ~Connection::Ptr() when it goes out of scope, the API client should never
+ /// call this method.
virtual void Disconnect() = 0;
public:
- // Movable Connection smart pointer. When Connection::Ptr is destroyed the
- // Connection will disconnect automatically.
+ /// Movable Connection smart pointer. When Connection::Ptr is destroyed the
+ /// Connection will disconnect automatically.
using Ptr = internal::RaiiPtr<Connection, &Connection::Disconnect>;
};
diff --git a/pw_bluetooth/public/pw_bluetooth/low_energy/peripheral.h b/pw_bluetooth/public/pw_bluetooth/low_energy/peripheral.h
index 23c56d1..34c88fc 100644
--- a/pw_bluetooth/public/pw_bluetooth/low_energy/peripheral.h
+++ b/pw_bluetooth/public/pw_bluetooth/low_energy/peripheral.h
@@ -26,130 +26,133 @@
namespace pw::bluetooth::low_energy {
-// `AdvertisedPeripheral` instances are valid for the duration of advertising.
+/// `AdvertisedPeripheral` instances are valid for the duration of advertising.
class AdvertisedPeripheral {
public:
virtual ~AdvertisedPeripheral() = default;
- // Set a callback that will be called when an error occurs and advertising
- // has been stopped (invalidating this object). It is OK to destroy the
- // `AdvertisedPeripheral::Ptr` object from within `callback`.
+ /// Set a callback that will be called when an error occurs and advertising
+ /// has been stopped (invalidating this object). It is OK to destroy the
+ /// `AdvertisedPeripheral::Ptr` object from within `callback`.
virtual void SetErrorCallback(Closure callback) = 0;
- // For connectable advertisements, this callback will be called when an LE
- // central connects to the advertisement. It is recommended to set this
- // callback immediately after advertising starts to avoid dropping
- // connections.
- //
- // The returned Connection 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 Connection
- // 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.
- //
- // If advertising is not stopped, this callback may be called with multiple
- // connections over the lifetime of an advertisement. It is OK to destroy
- // the `AdvertisedPeripheral::Ptr` object from within `callback` in order to
- // stop advertising.
+ /// For connectable advertisements, this callback will be called when an LE
+ /// central connects to the advertisement. It is recommended to set this
+ /// callback immediately after advertising starts to avoid dropping
+ /// connections.
+ ///
+ /// The returned Connection 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 Connection
+ /// 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.
+ ///
+ /// If advertising is not stopped, this callback may be called with multiple
+ /// connections over the lifetime of an advertisement. It is OK to destroy
+ /// the `AdvertisedPeripheral::Ptr` object from within `callback` in order to
+ /// stop advertising.
virtual void SetConnectionCallback(
Function<void(Connection::Ptr)>&& callback) = 0;
private:
- // Stop advertising. This method is called by the ~AdvertisedPeripheral::Ptr()
- // when it goes out of scope, the API client should never call this method.
+ /// Stop advertising. This method is called by the
+ /// ~AdvertisedPeripheral::Ptr() when it goes out of scope, the API client
+ /// should never call this method.
virtual void StopAdvertising() = 0;
public:
- // Movable AdvertisedPeripheral smart pointer. The peripheral will continue
- // advertising until the returned AdvertisedPeripheral::Ptr is destroyed.
+ /// Movable AdvertisedPeripheral smart pointer. The peripheral will continue
+ /// advertising until the returned AdvertisedPeripheral::Ptr is destroyed.
using Ptr = internal::RaiiPtr<AdvertisedPeripheral,
&AdvertisedPeripheral::StopAdvertising>;
};
-// Represents the LE Peripheral role, which advertises and is connected to.
+/// Represents the LE Peripheral role, which advertises and is connected to.
class Peripheral {
public:
- // The range of the time interval between advertisements. Shorter intervals
- // result in faster discovery at the cost of higher power consumption. The
- // exact interval used is determined by the Bluetooth controller.
- // Time = N * 0.625ms.
- // Time range: 0x0020 (20ms) - 0x4000 (10.24s)
+ /// The range of the time interval between advertisements. Shorter intervals
+ /// result in faster discovery at the cost of higher power consumption. The
+ /// exact interval used is determined by the Bluetooth controller.
+ /// - Time = N * 0.625ms.
+ /// - Time range: 0x0020 (20ms) - 0x4000 (10.24s)
struct AdvertisingIntervalRange {
- uint16_t min = 0x0800; // 1.28s
- uint16_t max = 0x0800; // 1.28s
+ /// Default: 1.28s
+ uint16_t min = 0x0800;
+ /// Default: 1.28s
+ uint16_t max = 0x0800;
};
- // Represents the parameters for configuring advertisements.
+ /// Represents the parameters for configuring advertisements.
struct AdvertisingParameters {
- // The fields that will be encoded in the data section of advertising
- // packets.
+ /// The fields that will be encoded in the data section of advertising
+ /// packets.
AdvertisingData data;
- // 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.
+ /// 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.
std::optional<AdvertisingData> scan_response;
- // See `AdvertisingIntervalRange` documentation.
+ /// See `AdvertisingIntervalRange` documentation.
AdvertisingIntervalRange interval_range;
- // 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.
+ /// 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.
std::optional<ConnectionOptions> connection_options;
};
- // Errors returned by `Advertise`.
+ /// Errors returned by `Advertise`.
enum class AdvertiseError {
- // The operation or parameters requested are not supported on the current
- // hardware.
+ /// The operation or parameters requested are not supported on the current
+ /// hardware.
kNotSupported = 1,
- // The provided advertising data exceeds the maximum allowed length when
- // encoded.
+ /// The provided advertising data exceeds the maximum allowed length when
+ /// encoded.
kAdvertisingDataTooLong = 2,
- // The provided scan response data exceeds the maximum allowed length when
- // encoded.
+ /// The provided scan response data exceeds the maximum allowed length when
+ /// encoded.
kScanResponseDataTooLong = 3,
- // The requested parameters are invalid.
+ /// The requested parameters are invalid.
kInvalidParameters = 4,
- // This may be called if the maximum number of simultaneous advertisements
- // has already been reached.
+ /// This may be called if the maximum number of simultaneous advertisements
+ /// has already been reached.
kNotEnoughAdvertisingSlots = 5,
- // Advertising could not be initiated due to a hardware or system error.
+ /// Advertising could not be initiated due to a hardware or system error.
kFailed = 6,
};
+ /// Callback for `Advertise()` method.
using AdvertiseCallback =
Function<void(Result<AdvertiseError, AdvertisedPeripheral::Ptr>)>;
virtual ~Peripheral() = default;
- // 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.
- // `result_callback` - Called once advertising has started or failed. On
- // success, called with an `AdvertisedPeripheral` that models the lifetime
- // of the advertisement. Destroying it will stop advertising.
+ /// 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.
+ ///
+ /// @param parameters Parameters used while configuring the advertising
+ /// instance.
+ /// @param result_callback Called once advertising has started or failed. On
+ /// success, called with an `AdvertisedPeripheral` that models the lifetime of
+ /// the advertisement. Destroying it will stop advertising.
virtual void Advertise(const AdvertisingParameters& parameters,
AdvertiseCallback&& result_callback) = 0;
};
diff --git a/pw_bluetooth/public/pw_bluetooth/types.h b/pw_bluetooth/public/pw_bluetooth/types.h
index 3639bbf..d969b62 100644
--- a/pw_bluetooth/public/pw_bluetooth/types.h
+++ b/pw_bluetooth/public/pw_bluetooth/types.h
@@ -98,4 +98,4 @@
kSportsActivityLocationAndNavPod = 5188,
};
-} // namespace pw::bluetooth
\ No newline at end of file
+} // namespace pw::bluetooth
