The model of a BLE server. More...

#include <NimBLEServer.h>

Public Member Functions
void	start ()
	Start the GATT server.

uint8_t	getConnectedCount () const
	Return the number of connected clients.

bool	disconnect (uint16_t connHandle, uint8_t reason=BLE_ERR_REM_USER_CONN_TERM) const
	Disconnect the specified client with optional reason.

bool	disconnect (const NimBLEConnInfo &connInfo, uint8_t reason=BLE_ERR_REM_USER_CONN_TERM) const
	Disconnect the specified client with optional reason.

void	setCallbacks (NimBLEServerCallbacks *pCallbacks, bool deleteCallbacks=true)
	Set the server callbacks.

void	updateConnParams (uint16_t connHandle, uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout) const
	Request an Update the connection parameters:

NimBLEService *	createService (const char *uuid)
	Create a BLE Service.

NimBLEService *	createService (const NimBLEUUID &uuid)
	Create a BLE Service.

NimBLEService *	getServiceByUUID (const char *uuid, uint16_t instanceId=0) const
	Get a BLE Service by its UUID.

NimBLEService *	getServiceByUUID (const NimBLEUUID &uuid, uint16_t instanceId=0) const
	Get a BLE Service by its UUID.

NimBLEService *	getServiceByHandle (uint16_t handle) const
	Get a BLE Service by its handle.

void	removeService (NimBLEService *service, bool deleteSvc=false)
	Remove a service from the server.

void	addService (NimBLEService *service)
	Adds a service which was either already created but removed from availability, or created and later added to services list.

uint16_t	getPeerMTU (uint16_t connHandle) const
	Get the MTU value of a client connection.

std::vector< uint16_t >	getPeerDevices () const
	Get a vector of the connected client handles.

NimBLEConnInfo	getPeerInfo (uint8_t index) const
	Get the connection information of a connected peer by vector index.

NimBLEConnInfo	getPeerInfo (const NimBLEAddress &address) const
	Get the connection information of a connected peer by address.

NimBLEConnInfo	getPeerInfoByHandle (uint16_t connHandle) const
	Get the connection information of a connected peer by connection handle.

void	advertiseOnDisconnect (bool enable)
	Set the server to automatically start advertising when a client disconnects.

void	setDataLen (uint16_t connHandle, uint16_t tx_octets) const
	Request an update of the data packet length.

NimBLEClient *	getClient (uint16_t connHandle)
	Create a client instance from the connection handle.

NimBLEClient *	getClient (const NimBLEConnInfo &connInfo)
	Create a client instance from the NimBLEConnInfo reference.

void	deleteClient ()
	Delete the NimBLEClient instance that was created with `getClient()`

NimBLEExtAdvertising *	getAdvertising () const
	Retrieve the advertising object that can be used to advertise the existence of the server.

bool	startAdvertising (uint8_t instanceId, int duration=0, int maxEvents=0) const
	Start advertising.

bool	stopAdvertising (uint8_t instanceId) const
	Convenience function to stop advertising a data set.

bool	updatePhy (uint16_t connHandle, uint8_t txPhysMask, uint8_t rxPhysMask, uint16_t phyOptions)
	Request an update to the PHY used for a peer connection.

bool	getPhy (uint16_t connHandle, uint8_t txPhy, uint8_t rxPhy)
	Get the PHY used for a peer connection.

bool	startAdvertising (uint32_t duration=0) const
	Start advertising.

bool	stopAdvertising () const
	Stop advertising.

Detailed Description

The model of a BLE server.

Member Function Documentation

◆ addService()

void NimBLEServer::addService ( NimBLEService * service )

Adds a service which was either already created but removed from availability,
or created and later added to services list.

Parameters

[in] service The service object to add.

Note: If it is desired to advertise the service it must be added by calling NimBLEAdvertising::addServiceUUID.

◆ advertiseOnDisconnect()

void NimBLEServer::advertiseOnDisconnect ( bool enable )

Set the server to automatically start advertising when a client disconnects.

Parameters

[in] enable true == advertise, false == don't advertise.

◆ createService() [1/2]

NimBLEService * NimBLEServer::createService ( const char * uuid )

Create a BLE Service.

Parameters

[in] uuid The UUID of the new service.

Returns: A pointer to the new service object.

◆ createService() [2/2]

NimBLEService * NimBLEServer::createService ( const NimBLEUUID & uuid )

Create a BLE Service.

Parameters

[in] uuid The UUID of the new service.

Returns: A pointer to the new service object.

◆ disconnect() [1/2]

bool NimBLEServer::disconnect	(	const NimBLEConnInfo &	connInfo,
		uint8_t	reason = `BLE_ERR_REM_USER_CONN_TERM`
	)		const

Disconnect the specified client with optional reason.

Parameters

[in]	connInfo	Connection of the client to disconnect.
[in]	reason	code for disconnecting.

Returns: NimBLE host return code.

◆ disconnect() [2/2]

bool NimBLEServer::disconnect	(	uint16_t	connHandle,
		uint8_t	reason = `BLE_ERR_REM_USER_CONN_TERM`
	)		const

Disconnect the specified client with optional reason.

Parameters

[in]	connHandle	Connection handle of the client to disconnect.
[in]	reason	code for disconnecting.

Returns: True if successful.

◆ getAdvertising()

NimBLEAdvertising * NimBLEServer::getAdvertising ( ) const

Retrieve the advertising object that can be used to advertise the existence of the server.

Returns: A pinter to an advertising object.; A pointer to an advertising object.

◆ getClient() [1/2]

NimBLEClient * NimBLEServer::getClient ( const NimBLEConnInfo & connInfo )

Create a client instance from the NimBLEConnInfo reference.

Parameters

[in] connInfo The connection info to create a client instance from.

Returns: A pointer to the NimBLEClient instance or nullptr if there was an error.

Note: Only one instance is supported subsequent calls will overwrite the previous client connection information and data.

◆ getClient() [2/2]

NimBLEClient * NimBLEServer::getClient ( uint16_t connHandle )

Create a client instance from the connection handle.

Parameters

[in] connHandle The connection handle to create a client instance from.

Returns: A pointer to the NimBLEClient instance or nullptr if there was an error.

Note: Only one instance is supported subsequent calls will overwrite the previous client connection information and data.

◆ getConnectedCount()

uint8_t NimBLEServer::getConnectedCount ( ) const

Return the number of connected clients.

Returns: The number of connected clients.

◆ getPeerDevices()

std::vector< uint16_t > NimBLEServer::getPeerDevices ( ) const

Get a vector of the connected client handles.

Returns: A vector of the connected client handles.

◆ getPeerInfo() [1/2]

NimBLEConnInfo NimBLEServer::getPeerInfo ( const NimBLEAddress & address ) const

Get the connection information of a connected peer by address.

Parameters

[in] address The address of the peer.

Returns: A NimBLEConnInfo instance with the peer connection information, or an empty instance if not found.

◆ getPeerInfo() [2/2]

NimBLEConnInfo NimBLEServer::getPeerInfo ( uint8_t index ) const

Get the connection information of a connected peer by vector index.

Parameters

[in] index The vector index of the peer.

Returns: A NimBLEConnInfo instance with the peer connection information, or an empty instance if not found.

◆ getPeerInfoByHandle()

NimBLEConnInfo NimBLEServer::getPeerInfoByHandle ( uint16_t connHandle ) const

Get the connection information of a connected peer by connection handle.

Parameters

[in] connHandle The connection handle of the peer.

Returns: A NimBLEConnInfo instance with the peer connection information, or an empty instance if not found.

◆ getPeerMTU()

uint16_t NimBLEServer::getPeerMTU ( uint16_t connHandle ) const

Get the MTU value of a client connection.

Parameters

[in] connHandle The connection handle of the client to get the MTU value for.

Returns: The MTU or 0 if not found/connected.

◆ getPhy()

bool NimBLEServer::getPhy	(	uint16_t	connHandle,
		uint8_t *	txPhy,
		uint8_t *	rxPhy
	)

Get the PHY used for a peer connection.

Parameters

[in]	connHandle	the connection handle to the get the PHY for.
[out]	txPhy	The TX PHY.
[out]	rxPhy	The RX PHY.

Returns: True if successful.

◆ getServiceByHandle()

NimBLEService * NimBLEServer::getServiceByHandle ( uint16_t handle ) const

Get a BLE Service by its handle.

Parameters

handle The handle of the service.

Returns: A pointer to the service object or nullptr if not found.

◆ getServiceByUUID() [1/2]

NimBLEService * NimBLEServer::getServiceByUUID	(	const char *	uuid,
		uint16_t	instanceId = `0`
	)		const

Get a BLE Service by its UUID.

Parameters

[in]	uuid	The UUID of the service.
	instanceId	The index of the service to return (used when multiple services have the same UUID).

Returns: A pointer to the service object or nullptr if not found.

◆ getServiceByUUID() [2/2]

NimBLEService * NimBLEServer::getServiceByUUID	(	const NimBLEUUID &	uuid,
		uint16_t	instanceId = `0`
	)		const

Get a BLE Service by its UUID.

Parameters

[in]	uuid	The UUID of the service.
	instanceId	The index of the service to return (used when multiple services have the same UUID).

Returns: A pointer to the service object or nullptr if not found.

◆ removeService()

void NimBLEServer::removeService	(	NimBLEService *	service,
		bool	deleteSvc = `false`
	)

Remove a service from the server.

Immediately removes access to the service by clients, sends a service changed indication, and removes the service (if applicable) from the advertisements. The service is not deleted unless the deleteSvc parameter is true, otherwise the service remains available and can be re-added in the future. If desired a removed but not deleted service can be deleted later by calling this method with deleteSvc set to true.

Note: The service will not be removed from the database until all open connections are closed as it requires resetting the GATT server. In the interim the service will have it's visibility disabled.; Advertising will need to be restarted by the user after calling this as we must stop advertising in order to remove the service.

Parameters

[in]	service	The service object to remove.
[in]	deleteSvc	true if the service should be deleted.

◆ setCallbacks()

void NimBLEServer::setCallbacks	(	NimBLEServerCallbacks *	pCallbacks,
		bool	deleteCallbacks = `true`
	)

Set the server callbacks.

As a BLE server operates, it will generate server level events such as a new client connecting or a previous client disconnecting. This function can be called to register a callback handler that will be invoked when these events are detected.

Parameters

[in]	pCallbacks	The callbacks to be invoked.
[in]	deleteCallbacks	if true callback class will be deleted when server is destructed.

◆ setDataLen()

void NimBLEServer::setDataLen	(	uint16_t	connHandle,
		uint16_t	octets
	)		const

Request an update of the data packet length.

Can only be used after a connection has been established.

Sends a data length update request to the peer. The Data Length Extension (DLE) allows to increase the Data Channel Payload from 27 bytes to up to 251 bytes. The peer needs to support the Bluetooth 4.2 specifications, to be capable of DLE.
Parameters

[in] connHandle The connection handle of the peer to send the request to.

[in] octets The preferred number of payload octets to use (Range 0x001B-0x00FB).

◆ start()

void NimBLEServer::start ( )

Start the GATT server.

Required to be called after setup of all services and characteristics / descriptors for the NimBLE host to register them.

◆ startAdvertising() [1/2]

bool NimBLEServer::startAdvertising ( uint32_t duration = 0 ) const

Start advertising.

Parameters

[in] duration The duration in milliseconds to advertise for, default = forever.

Returns: True if advertising started successfully.

Start the server advertising its existence. This is a convenience function and is equivalent to retrieving the advertising object and invoking start upon it.

◆ startAdvertising() [2/2]

bool NimBLEServer::startAdvertising	(	uint8_t	instId,
		int	duration = `0`,
		int	maxEvents = `0`
	)		const

Start advertising.

Parameters

[in]	instId	The extended advertisement instance ID to start.
[in]	duration	How long to advertise for in milliseconds, 0 = forever (default).
[in]	maxEvents	Maximum number of advertisement events to send, 0 = no limit (default).

Returns: True if advertising started successfully.

Start the server advertising its existence. This is a convenience function and is equivalent to retrieving the advertising object and invoking start upon it.

◆ stopAdvertising() [1/2]

bool NimBLEServer::stopAdvertising ( ) const

Stop advertising.

Returns: True if advertising stopped successfully.

◆ stopAdvertising() [2/2]

bool NimBLEServer::stopAdvertising ( uint8_t instId ) const

Convenience function to stop advertising a data set.

Parameters

[in] instId The extended advertisement instance ID to stop advertising.

Returns: True if advertising stopped successfully.

◆ updateConnParams()

void NimBLEServer::updateConnParams	(	uint16_t	connHandle,
		uint16_t	minInterval,
		uint16_t	maxInterval,
		uint16_t	latency,
		uint16_t	timeout
	)		const

Request an Update the connection parameters:

Can only be used after a connection has been established.

Parameters

[in]	connHandle	The connection handle of the peer to send the request to.
[in]	minInterval	The minimum connection interval in 1.25ms units.
[in]	maxInterval	The maximum connection interval in 1.25ms units.
[in]	latency	The number of packets allowed to skip (extends max interval).
[in]	timeout	The timeout time in 10ms units before disconnecting.

◆ updatePhy()

bool NimBLEServer::updatePhy	(	uint16_t	connHandle,
		uint8_t	txPhyMask,
		uint8_t	rxPhyMask,
		uint16_t	phyOptions
	)

Request an update to the PHY used for a peer connection.

Parameters

[in]	connHandle	the connection handle to the update the PHY for.
[in]	txPhyMask	TX PHY. Can be mask of following: BLE_GAP_LE_PHY_1M_MASK BLE_GAP_LE_PHY_2M_MASK BLE_GAP_LE_PHY_CODED_MASK BLE_GAP_LE_PHY_ANY_MASK
[in]	rxPhyMask	RX PHY. Can be mask of following: BLE_GAP_LE_PHY_1M_MASK BLE_GAP_LE_PHY_2M_MASK BLE_GAP_LE_PHY_CODED_MASK BLE_GAP_LE_PHY_ANY_MASK
	phyOptions	Additional PHY options. Valid values are: BLE_GAP_LE_PHY_CODED_ANY (default) BLE_GAP_LE_PHY_CODED_S2 BLE_GAP_LE_PHY_CODED_S8

Returns: True if successful.

Public Member Functions

Detailed Description

Member Function Documentation

◆ addService()

◆ advertiseOnDisconnect()

◆ createService() [1/2]

◆ createService() [2/2]

◆ disconnect() [1/2]

◆ disconnect() [2/2]

◆ getAdvertising()

◆ getClient() [1/2]

◆ getClient() [2/2]

◆ getConnectedCount()

◆ getPeerDevices()

◆ getPeerInfo() [1/2]

◆ getPeerInfo() [2/2]

◆ getPeerInfoByHandle()

◆ getPeerMTU()

◆ getPhy()

◆ getServiceByHandle()

◆ getServiceByUUID() [1/2]

◆ getServiceByUUID() [2/2]

◆ removeService()

◆ setCallbacks()

◆ setDataLen()

◆ start()

◆ startAdvertising() [1/2]

◆ startAdvertising() [2/2]

◆ stopAdvertising() [1/2]

◆ stopAdvertising() [2/2]

◆ updateConnParams()

◆ updatePhy()