mirror of https://github.com/ARMmbed/mbed-os.git
BLE: Update BatteryService documentation.
Vincent Coubard
parent
0d1dc83eb1
commit
423cd23ec0
|
|
@ -14,64 +14,119 @@
|
|||
* limitations under the License.
|
||||
*/
|
||||
|
||||
#ifndef __BLE_BATTERY_SERVICE_H__
|
||||
#define __BLE_BATTERY_SERVICE_H__
|
||||
#ifndef MBED_BLE_BATTERY_SERVICE_H__
|
||||
#define MBED_BLE_BATTERY_SERVICE_H__
|
||||
|
||||
#include "platform/mbed_assert.h"
|
||||
#include "ble/BLE.h"
|
||||
|
||||
/**
|
||||
* @class BatteryService
|
||||
* @brief BLE Battery Service. This service displays the battery level from 0% to 100%, represented as an 8bit number.
|
||||
* Service: https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.battery_service.xml
|
||||
* Battery Level Char: https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.battery_level.xml
|
||||
*/
|
||||
* BLE Battery service.
|
||||
*
|
||||
* @par 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 while a value of 100% represents a
|
||||
* fully charged battery.
|
||||
*
|
||||
* Clients can read the current charge level and subscribe for server initiated
|
||||
* updates of the charge level. The server delivers these updates to subscribed
|
||||
* client in a notification packet.
|
||||
*
|
||||
* The subscription mechanism is usefull 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.
|
||||
*
|
||||
* @par 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 exposed by the service and notify subscribed client that the
|
||||
* value changed.
|
||||
*
|
||||
* @note Specification of the Battery service can be found here:
|
||||
* https://www.bluetooth.com/specifications/gatt
|
||||
*
|
||||
* @important Multiple instances of this Battery service are not supported.
|
||||
*/
|
||||
class BatteryService {
|
||||
public:
|
||||
/**
|
||||
* @param[in] _ble
|
||||
* BLE object for the underlying controller.
|
||||
* @param[in] level
|
||||
* 8bit batterly level. Usually used to represent percentage of batterly charge remaining.
|
||||
* Instantiate a battery service.
|
||||
*
|
||||
* The construction of a BatteryService adds a GATT battery service in @p
|
||||
* _ble GattServer and sets the initial charge level of the battery to @p
|
||||
* level.
|
||||
*
|
||||
* @param[in] _ble BLE device which will host the battery service.
|
||||
* @param[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.
|
||||
*/
|
||||
BatteryService(BLE &_ble, uint8_t level = 100) :
|
||||
ble(_ble),
|
||||
batteryLevel(level),
|
||||
batteryLevelCharacteristic(GattCharacteristic::UUID_BATTERY_LEVEL_CHAR, &batteryLevel, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY) {
|
||||
|
||||
GattCharacteristic *charTable[] = {&batteryLevelCharacteristic};
|
||||
GattService batteryService(GattService::UUID_BATTERY_SERVICE, charTable, sizeof(charTable) / sizeof(GattCharacteristic *));
|
||||
batteryLevelCharacteristic(
|
||||
GattCharacteristic::UUID_BATTERY_LEVEL_CHAR,
|
||||
&batteryLevel,
|
||||
GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY
|
||||
)
|
||||
{
|
||||
MBED_ASSERT(level <= 100);
|
||||
GattCharacteristic *charTable[] = { &batteryLevelCharacteristic };
|
||||
GattService batteryService(
|
||||
GattService::UUID_BATTERY_SERVICE,
|
||||
charTable,
|
||||
sizeof(charTable) / sizeof(GattCharacteristic *)
|
||||
);
|
||||
|
||||
ble.addService(batteryService);
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Update the battery level with a new value. Valid values lie between 0 and 100,
|
||||
* anything outside this range will be ignored.
|
||||
* Update the battery charge level exposed by the service.
|
||||
*
|
||||
* @param newLevel
|
||||
* Update to battery level.
|
||||
* The server will send 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 will obtain the updated value.
|
||||
*
|
||||
* @param newLevel Charge level of the battery. It is a percentage of the
|
||||
* remaining charge between 0% and 100%.
|
||||
*
|
||||
* @important This function must be called in the execution context of the
|
||||
* BLE stack.
|
||||
*/
|
||||
void updateBatteryLevel(uint8_t newLevel) {
|
||||
void updateBatteryLevel(uint8_t newLevel)
|
||||
{
|
||||
MBED_ASSERT(level <= 100);
|
||||
batteryLevel = newLevel;
|
||||
ble.gattServer().write(batteryLevelCharacteristic.getValueHandle(), &batteryLevel, 1);
|
||||
ble.gattServer().write(
|
||||
batteryLevelCharacteristic.getValueHandle(),
|
||||
&batteryLevel,
|
||||
1
|
||||
);
|
||||
}
|
||||
|
||||
protected:
|
||||
/**
|
||||
* A reference to the underlying BLE instance that this object is attached to.
|
||||
* The services and characteristics will be registered in this BLE instance.
|
||||
* Reference to the underlying BLE instance that this object is attached to.
|
||||
*
|
||||
* The services and characteristics will be registered in the GattServer of
|
||||
* this BLE instance.
|
||||
*/
|
||||
BLE &ble;
|
||||
|
||||
/**
|
||||
* The current battery level represented as an integer from 0% to 100%.
|
||||
*/
|
||||
uint8_t batteryLevel;
|
||||
uint8_t batteryLevel;
|
||||
|
||||
/**
|
||||
* A ReadOnlyGattCharacteristic that allows access to the peer device to the
|
||||
* batteryLevel value through BLE.
|
||||
* The GATT characteristic which expose the charge level.
|
||||
*/
|
||||
ReadOnlyGattCharacteristic<uint8_t> batteryLevelCharacteristic;
|
||||
};
|
||||
|
||||
#endif /* #ifndef __BLE_BATTERY_SERVICE_H__*/
|
||||
#endif /* #ifndef MBED_BLE_BATTERY_SERVICE_H__*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue