GATT Battery Service (BAS) Client¶

Usage
Periodic reading of the battery level
API documentation

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 ¶

Header file: include/bas_client.h

Source file: 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.

Return Value

0: If the operation was successful. Otherwise, a (negative) error code is returned.
(-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.

Return Value

0: If the operation was successful. Otherwise, a (negative) error code is returned.
-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.

Return Value

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.

Return

Connection object.

Parameters

bas: BAS Client 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.

Return Value

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.

Return

Battery level or negative error code.

Parameters

bas: BAS Client object.

bool bt_bas_notify_supported(struct bt_bas_client *bas)¶

Check whether notification is supported by the service.

Parameters

bas: BAS Client object.

Return Value

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.

Return Value

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_delayed_work read_work¶: Work queue used to measure the read interval.

struct bt_gatt_read_params params¶: Read parameters.

atomic_t interval¶: Read value interval.

atomic_t process¶: Active processing flag.

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.

GATT Battery Service (BAS) Client¶

Usage¶

Periodic reading of the battery level¶

API documentation¶

Usage ¶

Periodic reading of the battery level ¶

API documentation ¶