Mbed OS Reference
Loading...
Searching...
No Matches
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

BLEble
 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]_bleBLE device which will host the battery service.
[in]levelInitial 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
newLevelCharge 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.