mirror of https://github.com/ARMmbed/mbed-os.git
133 lines
4.4 KiB
C++
133 lines
4.4 KiB
C++
/* mbed Microcontroller Library
|
|
* Copyright (c) 2006-2013 ARM Limited
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
#ifndef MBED_BLE_BATTERY_SERVICE_H__
|
|
#define MBED_BLE_BATTERY_SERVICE_H__
|
|
|
|
#include "platform/mbed_assert.h"
|
|
#include "ble/BLE.h"
|
|
|
|
/**
|
|
* 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, 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.
|
|
*
|
|
* @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 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.
|
|
*/
|
|
class BatteryService {
|
|
public:
|
|
/**
|
|
* 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
|
|
)
|
|
{
|
|
MBED_ASSERT(level <= 100);
|
|
GattCharacteristic *charTable[] = { &batteryLevelCharacteristic };
|
|
GattService batteryService(
|
|
GattService::UUID_BATTERY_SERVICE,
|
|
charTable,
|
|
sizeof(charTable) / sizeof(GattCharacteristic *)
|
|
);
|
|
|
|
ble.addService(batteryService);
|
|
}
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param 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.
|
|
*/
|
|
void updateBatteryLevel(uint8_t newLevel)
|
|
{
|
|
MBED_ASSERT(newLevel <= 100);
|
|
batteryLevel = newLevel;
|
|
ble.gattServer().write(
|
|
batteryLevelCharacteristic.getValueHandle(),
|
|
&batteryLevel,
|
|
1
|
|
);
|
|
}
|
|
|
|
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.
|
|
*/
|
|
BLE &ble;
|
|
|
|
/**
|
|
* The current battery level represented as an integer from 0% to 100%.
|
|
*/
|
|
uint8_t batteryLevel;
|
|
|
|
/**
|
|
* The GATT characteristic, which exposes the charge level.
|
|
*/
|
|
ReadOnlyGattCharacteristic<uint8_t> batteryLevelCharacteristic;
|
|
};
|
|
|
|
#endif /* #ifndef MBED_BLE_BATTERY_SERVICE_H__*/
|