Mbed OS Reference | BatteryService.h Source File

 /* mbed Microcontroller Library
  * Copyright (c) 2006-2020 ARM Limited
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * 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__
 
 #if BLE_FEATURE_GATT_SERVER
 
 #include "platform/mbed_assert.h"
 
 #include "ble/BLE.h"
 #include "ble/Gap.h"
 #include "ble/GattServer.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(charTable[0])
         );
 
         ble.gattServer().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 // BLE_FEATURE_GATT_SERVER
 
 #endif /* #ifndef MBED_BLE_BATTERY_SERVICE_H__*/
Important Information for this Arm website
