GATT Battery Service (BAS) Client¶
The Battery Service Client can be used to retrieve information about the battery level from a device that provides a Battery Service Server.
The client 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
bt_bas_subscribe_battery_level()
to receive notifications from the connected Battery Service. The notifications are passed to the provided callback function.Note that it is not mandatory for the Battery Level Characteristic to support notifications. If the server does not support notifications, read the current value as described below instead.
- Reading the current value
Use
bt_bas_read_battery_level()
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
bt_bas_start_per_read_battery_level()
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
bt_bas_get_last_battery_level()
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 get function returns
BT_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.
Periodic read interval can be changed 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/bas_client.h
subsys/bluetooth/services/bas_client.c
-
group
bt_bas_client_api
API for the Bluetooth LE GATT Battery Service (BAS) Client.
Defines
-
BT_BAS_VAL_INVALID
¶ Value that shows that the battery level is invalid.
This value is stored in the BAS Client object when the battery level information is unknown.
The same value is used to mark the fact that a notification has been aborted (see bt_bas_notify_cb).
-
BT_BAS_VAL_MAX
¶ Maximum allowed value for battery level.
Any value above that limit is treated as invalid.
Typedefs
-
typedef void (*
bt_bas_notify_cb
)(struct bt_bas_client *bas, uint8_t battery_level)¶ Value notification callback.
This function is called every time the server sends a notification for a changed value.
- Parameters
bas – BAS Client object.
battery_level – The notified battery level value, or BT_BAS_VAL_INVALID if the notification was interrupted by the server (NULL received from the stack).
-
typedef void (*
bt_bas_read_cb
)(struct bt_bas_client *bas, uint8_t battery_level, int err)¶ Read complete callback.
This function is called when the read operation finishes.
- Parameters
bas – BAS Client object.
battery_level – The battery level value that was read.
err – ATT error code or 0.
Functions
-
void
bt_bas_client_init
(struct bt_bas_client *bas)¶ Initialize the BAS Client instance.
You must call this function on the BAS Client object before any other function.
- Parameters
bas – BAS Client object.
-
int
bt_bas_handles_assign
(struct bt_gatt_dm *dm, struct bt_bas_client *bas)¶ Assign handles to the BAS Client instance.
This function should be called when a connection with a peer has been established, to associate the connection to this instance of the module. This makes it possible to handle multiple connections and associate each connection to a particular instance of this module. The GATT attribute handles are provided by the GATT Discovery Manager.
- Parameters
dm – Discovery object.
bas – BAS Client object.
- Returns 0
If the operation was successful. Otherwise, a (negative) error code is returned.
- Returns (-ENOTSUP)
Special error code used when the UUID of the service does not match the expected UUID.
-
int
bt_bas_subscribe_battery_level
(struct bt_bas_client *bas, bt_bas_notify_cb func)¶ Subscribe to the battery level value change notification.
- Parameters
bas – BAS Client object.
func – Callback function handler.
- Returns 0
If the operation was successful. Otherwise, a (negative) error code is returned.
- Returns -ENOTSUP
Special error code used if the connected server does not support notifications.
-
int
bt_bas_unsubscribe_battery_level
(struct bt_bas_client *bas)¶ Remove the subscription.
- Parameters
bas – BAS Client object.
- Returns 0
If the operation was successful. Otherwise, a (negative) error code is returned.
-
struct bt_conn *
bt_bas_conn
(const struct bt_bas_client *bas)¶ Get the connection object that is used with a given BAS Client.
- Parameters
bas – BAS Client object.
- Returns
Connection object.
-
int
bt_bas_read_battery_level
(struct bt_bas_client *bas, bt_bas_read_cb func)¶ Read the battery level value from the device.
This function sends a read request to the connected device.
- Parameters
bas – BAS Client object.
func – The callback function.
- Returns 0
If the operation was successful. Otherwise, a (negative) error code is returned.
-
int
bt_bas_get_last_battery_level
(struct bt_bas_client *bas)¶ Get the last known battery level.
This function returns the last known battery level value. The battery level is stored when a notification or read response is received.
- Parameters
bas – BAS Client object.
- Returns
Battery level or negative error code.
-
static inline bool
bt_bas_notify_supported
(struct bt_bas_client *bas)¶ Check whether notification is supported by the service.
- Parameters
bas – BAS Client object.
- Returns true
If notifications are supported. Otherwise,
false
is returned.
-
int
bt_bas_start_per_read_battery_level
(struct bt_bas_client *bas, int32_t interval, bt_bas_notify_cb func)¶ Periodically read the battery level value from the device with specific time interval.
- Parameters
bas – BAS Client object.
interval – Characteristic Read interval in milliseconds.
func – The callback function.
- Returns 0
If the operation was successful. Otherwise, a (negative) error code is returned.
-
void
bt_bas_stop_per_read_battery_level
(struct bt_bas_client *bas)¶ Stop periodic reading of the battery value from the device.
- Parameters
bas – BAS Client object.
-
struct
bt_bas_periodic_read
¶ - #include <bas_client.h>
Public Members
-
struct k_work_delayable
read_work
¶ Work queue used to measure the read interval.
-
struct bt_gatt_read_params
params
¶ Read parameters.
-
atomic_t
interval
¶ Read value interval.
-
struct k_work_delayable
-
struct
bt_bas_client
¶ - #include <bas_client.h>
Battery Service Client instance.
Public Members
-
struct bt_conn *
conn
¶ Connection handle.
-
struct bt_gatt_subscribe_params
notify_params
¶ Notification parameters.
-
struct bt_gatt_read_params
read_params
¶ Read parameters.
-
struct bt_bas_periodic_read
periodic_read
¶ Read characteristic value timing. Used when characteristic do not have a CCCD descriptor.
-
bt_bas_notify_cb
notify_cb
¶ Notification callback.
-
bt_bas_read_cb
read_cb
¶ Read value callback.
-
uint16_t
val_handle
¶ Handle of the Battery Level Characteristic.
-
uint16_t
ccc_handle
¶ Handle of the CCCD of the Battery Level Characteristic.
-
uint8_t
battery_level
¶ Current battery value.
-
uint8_t
properties
¶ Properties of the service.
-
bool
notify
¶ Notification supported.
-
struct bt_conn *
-