BatteryService Class Reference

BLE Battery service. More...

#include <BatteryService.h>

Public Member Functions
	BatteryService (BLE &_ble, uint8_t level=100)
	Instantiate a battery service. More...
void	updateBatteryLevel (uint8_t newLevel)
	Update the battery charge level that the service exposes. More...

Protected Attributes
BLE &	ble
	Reference to the underlying BLE instance that this object is attached to. More...
uint8_t	batteryLevel
	The current battery level represented as an integer from 0% to 100%. More...
ReadOnlyGattCharacteristic< uint8_t >	batteryLevelCharacteristic
	The GATT characteristic, which exposes the charge level. More...

Detailed Description

BLE Battery service.

purpose

The battery service exposes the charge level of the battery of the device. This information is exposed as a percentage from 0% to 100%; a value of 0% represents a fully discharged battery, and a value of 100% represents a fully charged battery.

Clients can read the current charge level and subscribe to server initiated updates of the charge level. The server delivers these updates to the subscribed client in a notification packet.

The subscription mechanism is useful to save power; it avoids unecessary data traffic between the client and the server, which may be induced by polling the battery level characteristic value.

usage

When this class is instantiated, it adds a battery service in the GattServer.

The application code can use the function updateBatteryLevel() to update the charge level that the service exposes and to notify the subscribed client that the value changed.

Note

You can find specification of the battery service here: https://www.bluetooth.com/specifications/gatt

Attention

Multiple instances of this battery service are not supported.

Definition at line 64 of file BatteryService.h.

Constructor & Destructor Documentation

BatteryService()

BatteryService	(	BLE &	_ble,
		uint8_t	level = 100
	)

Instantiate a battery service.

The construction of a BatteryService adds a GATT battery service in _ble GattServer and sets the initial charge level of the battery to level.

Parameters

[in]	_ble	BLE device which will host the battery service.
[in]	level	Initial charge level of the battery. It is a percentage where 0% means that the battery is fully discharged and 100% means that the battery is fully charged.

Definition at line 78 of file BatteryService.h.

Member Function Documentation

updateBatteryLevel()

void updateBatteryLevel

(

uint8_t

newLevel

)

Update the battery charge level that the service exposes.

The server sends a notification of the new value to clients that have subscribed to the battery level characteristic updates, and clients reading the charge level after the update obtain the updated value.

Parameters

newLevel

Charge level of the battery. It is a percentage of the remaining charge between 0% and 100%.

Attention

This function must be called in the execution context of the BLE stack.

Definition at line 111 of file BatteryService.h.

Field Documentation

ble

BLE& ble

protected

Reference to the underlying BLE instance that this object is attached to.

The services and characteristics are registered in the GattServer of this BLE instance.

Definition at line 129 of file BatteryService.h.

batteryLevel

uint8_t batteryLevel

protected

The current battery level represented as an integer from 0% to 100%.

Definition at line 134 of file BatteryService.h.

batteryLevelCharacteristic

ReadOnlyGattCharacteristic<uint8_t> batteryLevelCharacteristic

protected

The GATT characteristic, which exposes the charge level.

Definition at line 139 of file BatteryService.h.