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 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.

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

Header file: include/bluetooth/services/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.

Param bas:

BAS Client object.

Param 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.

Param bas:

BAS Client object.

Param battery_level:

The battery level value that was read.

Param 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 values:

  • 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 values:

  • 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 values:

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.

Return values:

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.

Return values:

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 values:

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 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.