c7222::Ble Class Reference

Singleton entry point for BLE configuration and events. More...

#include <ble.hpp>

Inheritance diagram for c7222::Ble:

Collaboration diagram for c7222::Ble:

Public Member Functions
Subsystem Access
Gap *	GetGap ()
	Access the underlying GAP instance.
const Gap *	GetGap () const
	Access the underlying GAP instance (const).
SecurityManager *	GetSecurityManager ()
	Access the underlying Security Manager instance.
const SecurityManager *	GetSecurityManager () const
	Access the underlying Security Manager instance (const).
SecurityManager *	EnableSecurityManager (const SecurityManager::SecurityParameters &params)
	Enable and access the Security Manager instance.
AttributeServer *	EnableAttributeServer (const void *context)
	Enable and access the Attribute Server instance.
Attribute Server Access
AttributeServer *	GetAttributeServer ()
	Access the Attribute Server instance.
const AttributeServer *	GetAttributeServer () const
	Access the Attribute Server instance (const).
Stack State Callbacks
void	SetOnBleStackOnCallback (std::function< void()> handler)
	Register BLE stack-on callback (HCI_STATE_WORKING).
void	SetOnBleStackOnCallback (void(*handler)())
	Register BLE stack-on callback from a function pointer.
template<typename T >
void	SetOnBleStackOnCallback (T *object, void(T::*method)())
	Register BLE stack-on callback from an object/member function.
template<typename T >
void	SetOnBleStackOnCallback (const T *object, void(T::*method)() const)
	Register BLE stack-on callback from a const object/member function.
void	SetOnBleStackOffCallback (std::function< void()> handler)
	Register BLE stack-off callback (non-working state).
void	SetOnBleStackOffCallback (void(*handler)())
	Register BLE stack-off callback from a function pointer.
template<typename T >
void	SetOnBleStackOffCallback (T *object, void(T::*method)())
	Register BLE stack-off callback from an object/member function.
template<typename T >
void	SetOnBleStackOffCallback (const T *object, void(T::*method)() const)
	Register BLE stack-off callback from a const object/member function.
Stack Control and Event Routing
BleError	TurnOn ()
	Power on the BLE stack and controller.
void	TurnOff ()
	Power off the BLE stack and controller.
bool	IsTurnedOn () const
	Check whether BLE stack is marked as working.
GAP Configuration Helpers
void	SetDeviceName (const std::string &name)
	Set the GAP device name.
void	SetAdvertisementFlags (uint8_t flags)
	Set the advertising flags (e.g., general discoverable).
void	AddGapEventHandler (const Gap::EventHandler &handler)
	Add a GAP event handler.
void	RemoveGapEventHandler (const Gap::EventHandler &handler)
	Remove a GAP event handler.
void	ClearGapEventHandlers ()
	Remove all GAP event handlers.
void	SetRandomAddress (const BleAddress &address)
	Set the random device address.
void	SetAdvertisingParameters (const Gap::AdvertisementParameters &params)
	Set advertising parameters.
void	SetAdvertisingData (const uint8_t *data, size_t size)
	Set raw advertising data.
void	SetAdvertisingData (const std::vector< uint8_t > &data)
	Set advertising data from a vector.
void	SetAdvertisingData (const AdvertisementDataBuilder &data_builder)
	Set advertising data from a builder.
void	SetAdvertisingData ()
	Set advertising data from the current builder state.
void	SetScanResponseData (uint8_t length, const uint8_t *data)
	Set scan response data.
void	EnableAdvertising (bool enabled)
	Enable or disable advertising.
void	StartAdvertising ()
	Start advertising.
void	StopAdvertising ()
	Stop advertising.
bool	IsAdvertisingEnabled () const
	Check whether advertising is enabled.
bool	IsConnected () const
	Check whether a GAP connection is active.
BleError	RequestConnectionParameterUpdate (ConnectionHandle con_handle, const Gap::PreferredConnectionParameters &params)
	Request a connection parameter update.
BleError	UpdateConnectionParameters (ConnectionHandle con_handle, const Gap::PreferredConnectionParameters &params)
	Apply new connection parameters.
BleError	ReadRssi (ConnectionHandle con_handle)
	Read RSSI for an active connection.
BleError	Disconnect (ConnectionHandle con_handle)
	Disconnect an active connection.
AdvertisementDataBuilder &	GetAdvertisementDataBuilder ()
	Access the advertising data builder.
const AdvertisementDataBuilder &	GetAdvertisementDataBuilder () const
	Access the advertising data builder (const).
Security Manager Convenience Wrappers
void	AddSecurityEventHandler (const SecurityManager::EventHandler &handler)
	Add a Security Manager event handler.
bool	RemoveSecurityEventHandler (const SecurityManager::EventHandler &handler)
	Remove a Security Manager event handler.
void	AddSecurityEventHandler (const SecurityManager::EventHandler *handler)
	Add a Security Manager event handler pointer.
bool	RemoveSecurityEventHandler (const SecurityManager::EventHandler *handler)
	Remove a Security Manager event handler pointer.
void	ClearSecurityEventHandlers ()
	Remove all Security Manager event handlers.
BleError	ConfigureSecurity (const SecurityManager::SecurityParameters &params)
	Configure the Security Manager parameters.
BleError	SetSecurityIoCapability (SecurityManager::IoCapability capability)
	Set Security Manager IO capability.
BleError	SetSecurityAuthenticationRequirements (SecurityManager::AuthenticationRequirement auth)
	Set Security Manager authentication requirements.
BleError	SetSecurityKeySizeRange (uint8_t min_key_size, uint8_t max_key_size)
	Set Security Manager encryption key size range.
BleError	SetSecurityBondable (bool bondable)
	Enable or disable bonding in the Security Manager.
BleError	SetSecuritySecureConnectionsOnly (bool enabled)
	Enable or disable Secure Connections only mode.
BleError	ConfirmJustWorks (ConnectionHandle con_handle)
	Confirm "Just Works" pairing.
BleError	ConfirmNumericComparison (ConnectionHandle con_handle, bool accept)
	Confirm numeric comparison pairing.
BleError	ProvidePasskey (ConnectionHandle con_handle, uint32_t passkey)
	Provide passkey for keyboard input role.
BleError	RequestPairing (ConnectionHandle con_handle)
	Request pairing with the peer device.
BleError	SetAuthorization (ConnectionHandle con_handle, SecurityManager::AuthorizationResult result)
	Provide an authorization decision.
Event Routing
virtual BleError	DispatchBleHciPacket (uint8_t packet_type, uint8_t channel, const uint8_t *packet_data, uint16_t packet_data_size)
	Dispatch raw HCI packets to GAP/AttributeServer/SecurityManager.
Public Member Functions inherited from c7222::NonCopyable
	NonCopyable (const NonCopyable &)=delete
NonCopyable &	operator= (const NonCopyable &)=delete
	NonCopyable (NonCopyable &&)=default
NonCopyable &	operator= (NonCopyable &&)=default
Public Member Functions inherited from c7222::NonMovable
	NonMovable (const NonMovable &)=default
NonMovable &	operator= (const NonMovable &)=default
	NonMovable (NonMovable &&)=delete
NonMovable &	operator= (NonMovable &&)=delete

Static Public Member Functions
Singleton and Lifecycle
static Ble *	GetInstance (bool enable_hci_logging=false)
	Get the singleton instance.

Logging and Diagnostics
static void	DumpAttributeServerContext ()
	Dump the platform attribute server context (platform-dependent).
void	EnableHCILoggingToStdout ()
	Enable HCI event logging to stdout (platform-dependent).
void	DisableHCILoggingToStdout ()
	Disable HCI event logging to stdout (platform-dependent).
bool	IsHCILoggingEnabled () const
	Check whether HCI logging is enabled.

Additional Inherited Members
Protected Member Functions inherited from c7222::NonCopyableNonMovable
	NonCopyableNonMovable ()=default
	~NonCopyableNonMovable ()=default
Protected Member Functions inherited from c7222::NonCopyable
	NonCopyable ()=default
	~NonCopyable ()=default
Protected Member Functions inherited from c7222::NonMovable
	NonMovable ()=default
	~NonMovable ()=default

Detailed Description

Singleton entry point for BLE configuration and events.

This class is the primary facade for BLE stack initialization, configuration, and event routing. It aggregates references to other singleton components (GAP, AttributeServer, SecurityManager) and coordinates their lifecycle.

---

Singleton Composition

The BLE stack is represented by several singletons:

• Gap manages advertising, connections, and GAP-level events.
• AttributeServer parses the ATT database and routes GATT operations.
• SecurityManager configures pairing and handles security events.

Ble owns pointers to these instances and ensures they are enabled in the correct order. This keeps a single, global view of BLE state in the system.

---

Context Pointer (Platform-Specific)

EnableAttributeServer(const void* context) accepts a platform-specific context pointer. On Pico W, this is the compiled ATT database blob (att_db.h/att_db.c) generated by BTstack. The context is cached so the ATT database remains valid for the lifetime of the server.

This allows Ble to remain platform-agnostic while the platform layer interprets the context appropriately.

---

Profile Databases (ATT/GATT)

BLE profiles are represented as an ATT/GATT database (services, characteristics, and descriptors). On the Pico W, this database is required by the Pico BTstack stack and is generated outside of this library (e.g., by the BTstack tooling that produces att_db.h/att_db.c). The database is passed into EnableAttributeServer() as the context pointer. The AttributeServer parses this database into Service and Characteristic objects for routing and event callbacks.

The database blob is treated as immutable and must remain valid for the lifetime of the server because many static attributes reference data inside that blob.

---

Typical Workflow

1. Configure security (optional):
   • Prepare SecurityManager::SecurityParameters.
   • Call EnableSecurityManager(params) if security is required.
2. Enable Attribute Server:
   • Call EnableAttributeServer(att_db) with the compiled ATT database.
3. Register handlers:
   • Install attribute/characteristic handlers.
   • Register SecurityManager event handlers if needed.
   • Do this after EnableAttributeServer() (so characteristics exist), and before TurnOn() or before initiating any connections.
   • Register GAP event handlers immediately after obtaining the Gap instance, also before TurnOn(), so early connection/state events are not missed.

---

Handler Registration Timing

• GAP handlers: register as soon as you get Gap* (before TurnOn()), because connection and state events can arrive immediately after the controller powers on.
• Characteristic handlers: register after EnableAttributeServer() so the parsed Service/Characteristic objects exist, and before TurnOn() or any connection attempts.
• SecurityManager handlers: register after enabling SecurityManager and before pairing can be triggered (typically before TurnOn()).

---

TurnOn/TurnOff Callbacks

SetOnBleStackOnCallback() is invoked when the stack transitions to HCI_STATE_WORKING after TurnOn() succeeds. This is the earliest safe moment to start advertising or initiating connections.

SetOnBleStackOffCallback() is invoked when the stack leaves the working state (e.g., controller power-off or reset). Use it to stop application activity that depends on an active controller.

1. Turn on BLE:
   • Call TurnOn() to initialize the stack and power on the controller.
2. Dispatch events:
   • The platform layer forwards HCI events into DispatchBleHciPacket().

---

Example

auto* ble = c7222::Ble::GetInstance();
 
// Enable Security Manager (optional)
c7222::SecurityManager::SecurityParameters params;
params.io_capability = c7222::SecurityManager::IoCapability::kNoInputNoOutput;
params.authentication =
    c7222::SecurityManager::AuthenticationRequirement::kMitmProtection;
ble->EnableSecurityManager(params);
 
// Enable the Attribute Server using the compiled ATT DB (BTstack)
ble->EnableAttributeServer(att_db);
 
// Start BLE
ble->TurnOn();

---

BLE Standard Concepts (High-Level)

• GAP handles discovery, advertising, and connections.
• GATT/ATT define services, characteristics, and attribute access.
• SM (Security Manager) handles pairing, authentication, and encryption.

Ble sits above these roles and routes HCI events to the appropriate subsystem based on their responsibility.

---

Raspberry Pi Pico (BTstack) Port

On Pico W, the platform implementation in libs/elec_c7222/ble/platform/rpi_pico/:

• Initializes L2CAP and SM as needed.
• Registers BTstack HCI event handlers.
• Powers on the controller via hci_power_control(HCI_POWER_ON).
• Routes HCI events into GAP, AttributeServer, and SecurityManager.
• Updates the AttributeServer security cache on GAP_EVENT_SECURITY_LEVEL.

The DumpAttributeServerContext() helper can dump the ATT database using BTstack when HCI logging is enabled.

Member Function Documentation

AddGapEventHandler()

void c7222::Ble::AddGapEventHandler ( const Gap::EventHandler &  handler )

inline

Add a GAP event handler.

Here is the call graph for this function:

AddSecurityEventHandler() [1/2]

void c7222::Ble::AddSecurityEventHandler ( const SecurityManager::EventHandler &  handler )

inline

Add a Security Manager event handler.

Here is the call graph for this function:

AddSecurityEventHandler() [2/2]

void c7222::Ble::AddSecurityEventHandler ( const SecurityManager::EventHandler *  handler )

inline

Add a Security Manager event handler pointer.

Here is the call graph for this function:

ClearGapEventHandlers()

void c7222::Ble::ClearGapEventHandlers ( )

inline

Remove all GAP event handlers.

Here is the call graph for this function:

ClearSecurityEventHandlers()

void c7222::Ble::ClearSecurityEventHandlers ( )

inline

Remove all Security Manager event handlers.

Here is the call graph for this function:

ConfigureSecurity()

BleError c7222::Ble::ConfigureSecurity ( const SecurityManager::SecurityParameters &  params )

inline

Configure the Security Manager parameters.

Here is the call graph for this function:

ConfirmJustWorks()

BleError c7222::Ble::ConfirmJustWorks ( ConnectionHandle  con_handle )

inline

Confirm "Just Works" pairing.

Here is the call graph for this function:

ConfirmNumericComparison()

BleError c7222::Ble::ConfirmNumericComparison ( ConnectionHandle  con_handle, bool  accept  )

inline

Confirm numeric comparison pairing.

Here is the call graph for this function:

DisableHCILoggingToStdout()

void c7222::Ble::DisableHCILoggingToStdout

(

)

Disable HCI event logging to stdout (platform-dependent).

Disconnect()

BleError c7222::Ble::Disconnect ( ConnectionHandle  con_handle )

inline

Disconnect an active connection.

Here is the call graph for this function:

DispatchBleHciPacket()

virtual BleError c7222::Ble::DispatchBleHciPacket ( uint8_t  packet_type, uint8_t  channel, const uint8_t *  packet_data, uint16_t  packet_data_size  )

virtual

Dispatch raw HCI packets to GAP/AttributeServer/SecurityManager.

DumpAttributeServerContext()

static void c7222::Ble::DumpAttributeServerContext ( )

static

Dump the platform attribute server context (platform-dependent).

On Pico W, this dumps the ATT database attributes via BTstack when HCI logging is enabled.

EnableAdvertising()

void c7222::Ble::EnableAdvertising ( bool  enabled )

inline

Enable or disable advertising.

Here is the call graph for this function:

EnableAttributeServer()

AttributeServer * c7222::Ble::EnableAttributeServer

(

const void *

context

)

Enable and access the Attribute Server instance.

The context is platform-specific. On Pico W it is the BTstack ATT database blob (att_db).

EnableHCILoggingToStdout()

void c7222::Ble::EnableHCILoggingToStdout

(

)

Enable HCI event logging to stdout (platform-dependent).

On the Pico W platform, this initializes the BTstack HCI dump target when logging is enabled in btstack_config.h.

EnableSecurityManager()

SecurityManager * c7222::Ble::EnableSecurityManager

(

const SecurityManager::SecurityParameters &

params

)

Enable and access the Security Manager instance.

This mirrors the Attribute Server enable pattern and allows the SM to be opt-in rather than constructed eagerly.

GetAdvertisementDataBuilder() [1/2]

AdvertisementDataBuilder & c7222::Ble::GetAdvertisementDataBuilder ( )

inline

Access the advertising data builder.

Here is the call graph for this function:

GetAdvertisementDataBuilder() [2/2]

const AdvertisementDataBuilder & c7222::Ble::GetAdvertisementDataBuilder ( ) const

inline

Access the advertising data builder (const).

Here is the call graph for this function:

GetAttributeServer() [1/2]

AttributeServer * c7222::Ble::GetAttributeServer ( )

inline

Access the Attribute Server instance.

GetAttributeServer() [2/2]

const AttributeServer * c7222::Ble::GetAttributeServer ( ) const

inline

Access the Attribute Server instance (const).

GetGap() [1/2]

Gap * c7222::Ble::GetGap ( )

inline

Access the underlying GAP instance.

GetGap() [2/2]

const Gap * c7222::Ble::GetGap ( ) const

inline

Access the underlying GAP instance (const).

GetInstance()

static Ble * c7222::Ble::GetInstance ( bool  enable_hci_logging = false )

static

Get the singleton instance.

Here is the caller graph for this function:

GetSecurityManager() [1/2]

SecurityManager * c7222::Ble::GetSecurityManager ( )

inline

Access the underlying Security Manager instance.

GetSecurityManager() [2/2]

const SecurityManager * c7222::Ble::GetSecurityManager ( ) const

inline

Access the underlying Security Manager instance (const).

IsAdvertisingEnabled()

bool c7222::Ble::IsAdvertisingEnabled ( ) const

inline

Check whether advertising is enabled.

Here is the call graph for this function:

IsConnected()

bool c7222::Ble::IsConnected ( ) const

inline

Check whether a GAP connection is active.

Here is the call graph for this function:

IsHCILoggingEnabled()

bool c7222::Ble::IsHCILoggingEnabled ( ) const

inline

Check whether HCI logging is enabled.

IsTurnedOn()

bool c7222::Ble::IsTurnedOn ( ) const

inline

Check whether BLE stack is marked as working.

ProvidePasskey()

BleError c7222::Ble::ProvidePasskey ( ConnectionHandle  con_handle, uint32_t  passkey  )

inline

Provide passkey for keyboard input role.

Here is the call graph for this function:

ReadRssi()

BleError c7222::Ble::ReadRssi ( ConnectionHandle  con_handle )

inline

Read RSSI for an active connection.

Here is the call graph for this function:

RemoveGapEventHandler()

void c7222::Ble::RemoveGapEventHandler ( const Gap::EventHandler &  handler )

inline

Remove a GAP event handler.

Here is the call graph for this function:

RemoveSecurityEventHandler() [1/2]

bool c7222::Ble::RemoveSecurityEventHandler ( const SecurityManager::EventHandler &  handler )

inline

Remove a Security Manager event handler.

Here is the call graph for this function:

RemoveSecurityEventHandler() [2/2]

bool c7222::Ble::RemoveSecurityEventHandler ( const SecurityManager::EventHandler *  handler )

inline

Remove a Security Manager event handler pointer.

Here is the call graph for this function:

RequestConnectionParameterUpdate()

BleError c7222::Ble::RequestConnectionParameterUpdate ( ConnectionHandle  con_handle, const Gap::PreferredConnectionParameters &  params  )

inline

Request a connection parameter update.

Here is the call graph for this function:

RequestPairing()

BleError c7222::Ble::RequestPairing ( ConnectionHandle  con_handle )

inline

Request pairing with the peer device.

Here is the call graph for this function:

SetAdvertisementFlags()

void c7222::Ble::SetAdvertisementFlags

(

uint8_t

flags

)

Set the advertising flags (e.g., general discoverable).

SetAdvertisingData() [1/4]

void c7222::Ble::SetAdvertisingData ( )

inline

Set advertising data from the current builder state.

Here is the call graph for this function:

SetAdvertisingData() [2/4]

void c7222::Ble::SetAdvertisingData ( const AdvertisementDataBuilder &  data_builder )

inline

Set advertising data from a builder.

Here is the call graph for this function:

SetAdvertisingData() [3/4]

void c7222::Ble::SetAdvertisingData ( const std::vector< uint8_t > &  data )

inline

Set advertising data from a vector.

Here is the call graph for this function:

SetAdvertisingData() [4/4]

void c7222::Ble::SetAdvertisingData ( const uint8_t *  data, size_t  size  )

inline

Set raw advertising data.

Here is the call graph for this function:

SetAdvertisingParameters()

void c7222::Ble::SetAdvertisingParameters ( const Gap::AdvertisementParameters &  params )

inline

Set advertising parameters.

Here is the call graph for this function:

SetAuthorization()

BleError c7222::Ble::SetAuthorization ( ConnectionHandle  con_handle, SecurityManager::AuthorizationResult  result  )

inline

Provide an authorization decision.

Here is the call graph for this function:

SetDeviceName()

void c7222::Ble::SetDeviceName

(

const std::string &

name

)

Set the GAP device name.

SetOnBleStackOffCallback() [1/4]

template<typename T >

void c7222::Ble::SetOnBleStackOffCallback ( const T *  object, void(T::*)() const  method  )

inline

Register BLE stack-off callback from a const object/member function.

SetOnBleStackOffCallback() [2/4]

void c7222::Ble::SetOnBleStackOffCallback ( std::function< void()>  handler )

inline

Register BLE stack-off callback (non-working state).

SetOnBleStackOffCallback() [3/4]

template<typename T >

void c7222::Ble::SetOnBleStackOffCallback ( T *  object, void(T::*)()  method  )

inline

Register BLE stack-off callback from an object/member function.

SetOnBleStackOffCallback() [4/4]

void c7222::Ble::SetOnBleStackOffCallback ( void(*)()  handler )

inline

Register BLE stack-off callback from a function pointer.

SetOnBleStackOnCallback() [1/4]

template<typename T >

void c7222::Ble::SetOnBleStackOnCallback ( const T *  object, void(T::*)() const  method  )

inline

Register BLE stack-on callback from a const object/member function.

SetOnBleStackOnCallback() [2/4]

void c7222::Ble::SetOnBleStackOnCallback ( std::function< void()>  handler )

inline

Register BLE stack-on callback (HCI_STATE_WORKING).

Note

The callback is invoked when the BLE stack transitions to the working state, indicating that BLE operations can proceed.

SetOnBleStackOnCallback() [3/4]

template<typename T >

void c7222::Ble::SetOnBleStackOnCallback ( T *  object, void(T::*)()  method  )

inline

Register BLE stack-on callback from an object/member function.

SetOnBleStackOnCallback() [4/4]

void c7222::Ble::SetOnBleStackOnCallback ( void(*)()  handler )

inline

Register BLE stack-on callback from a function pointer.

SetRandomAddress()

void c7222::Ble::SetRandomAddress ( const BleAddress &  address )

inline

Set the random device address.

Here is the call graph for this function:

SetScanResponseData()

void c7222::Ble::SetScanResponseData ( uint8_t  length, const uint8_t *  data  )

inline

Set scan response data.

Here is the call graph for this function:

SetSecurityAuthenticationRequirements()

BleError c7222::Ble::SetSecurityAuthenticationRequirements ( SecurityManager::AuthenticationRequirement  auth )

inline

Set Security Manager authentication requirements.

Here is the call graph for this function:

SetSecurityBondable()

BleError c7222::Ble::SetSecurityBondable ( bool  bondable )

inline

Enable or disable bonding in the Security Manager.

Here is the call graph for this function:

SetSecurityIoCapability()

BleError c7222::Ble::SetSecurityIoCapability ( SecurityManager::IoCapability  capability )

inline

Set Security Manager IO capability.

Here is the call graph for this function:

SetSecurityKeySizeRange()

BleError c7222::Ble::SetSecurityKeySizeRange ( uint8_t  min_key_size, uint8_t  max_key_size  )

inline

Set Security Manager encryption key size range.

Here is the call graph for this function:

SetSecuritySecureConnectionsOnly()

BleError c7222::Ble::SetSecuritySecureConnectionsOnly ( bool  enabled )

inline

Enable or disable Secure Connections only mode.

Here is the call graph for this function:

StartAdvertising()

void c7222::Ble::StartAdvertising ( )

inline

Start advertising.

Here is the call graph for this function:

StopAdvertising()

void c7222::Ble::StopAdvertising ( )

inline

Stop advertising.

Here is the call graph for this function:

TurnOff()

void c7222::Ble::TurnOff

(

)

Power off the BLE stack and controller.

TurnOn()

BleError c7222::Ble::TurnOn

(

)

Power on the BLE stack and controller.

Initializes L2CAP/SM as needed and registers event handlers.

UpdateConnectionParameters()

BleError c7222::Ble::UpdateConnectionParameters ( ConnectionHandle  con_handle, const Gap::PreferredConnectionParameters &  params  )

inline

Apply new connection parameters.

Here is the call graph for this function:

---

The documentation for this class was generated from the following file:

• libs/elec_c7222/ble/include/ble.hpp