GATT Battery Service (BAS) Client
You can use the Battery Service Client to retrieve information about the battery level from a device that provides a Battery Service Server.
The library supports a simple Battery Service with one characteristic. The Battery Level Characteristic holds the battery level in percentage units.
The Battery Service Client is used in the Bluetooth: Central BAS sample.
Usage
Note
Do not access any of the values in the bt_bas_client object structure directly.
All values that should be accessed have accessor functions.
The reason that the structure is fully defined is to allow the application to allocate the memory for it.
There are different ways to retrieve the battery level:
- Notifications
Use the
bt_bas_subscribe_battery_level()function to receive notifications from the connected Battery Service. The notifications are passed to the provided callback function.The Battery Level Characteristic does not need to support notifications. If the server does not support notifications, read the current value as described below instead.
- Reading the current value
Use the
bt_bas_read_battery_level()function to read the battery level. When subscribing to notifications, you can call this function to retrieve the current value even when there is no change.- Periodically reading the current value with time interval
Use the
bt_bas_start_per_read_battery_level()function to periodically read the battery level with a given time interval. You can call this function only when notification support is not enabled in BAS. See Periodic reading of the battery level for more details.- Getting the last known value
The BAS Client stores the last known battery level information internally. Use the
bt_bas_get_last_battery_level()function to access it.Note
The internally stored value is updated every time a notification or read response is received. If no value is received from the server, the
getfunction returnsBT_BAS_VAL_INVALID.
Periodic reading of the battery level
You can use the bt_bas_start_per_read_battery_level() function to periodically read the battery level with a specific time interval.
This function sends a read request to the connected device periodically.
It can be used only when support for notifications is not enabled in BAS.
For many devices, the battery level value does not change frequently. Depending on the type of connected device, you can decide how often to read the battery level value. For example, if the expected battery life is in the order of years, reading the battery level value more frequently than once a week is not recommended.
You can change the periodic read interval while the periodic read is active. In such case, the next read period is started with the new interval.
Note
Providing the K_NO_WAIT and K_FOREVER arguments as the time interval causes reading of the characteristic value as soon and as often as possible.
API documentation
include/bluetooth/services/bas_client.hsubsys/bluetooth/services/bas_client.c