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_gatt_bas_c 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_gatt_bas_c_subscribe() 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_gatt_bas_c_read() 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_gatt_bas_c_periodic_read_start() 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_gatt_bas_c_get() 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_GATT_BAS_VAL_INVALID.

Periodic reading of the battery level

You can use the bt_gatt_bas_c_periodic_read_start() 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 charasteristic value as soon and as often as possible.

API documentation

Header file: include/bas_c.h
Source file: subsys/bluetooth/services/bas_c.c
group bt_gatt_bas_c_api

API for the BLE GATT Battery Service (BAS) Client.

Defines

BT_GATT_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_gatt_bas_c_notify_cb).

BT_GATT_BAS_VAL_MAX

Maximum allowed value for battery level.

Any value above that limit is treated as invalid.

Typedefs

typedef void (*bt_gatt_bas_c_notify_cb)(struct bt_gatt_bas_c *bas_c, u8_t battery_level)

Value notification callback.

This function is called every time the server sends a notification for a changed value.

Parameters
  • bas_c: BAS Client object.

  • battery_level: The notified battery level value, or BT_GATT_BAS_VAL_INVALID if the notification was interrupted by the server (NULL received from the stack).

typedef void (*bt_gatt_bas_c_read_cb)(struct bt_gatt_bas_c *bas_c, u8_t battery_level, int err)

Read complete callback.

This function is called when the read operation finishes.

Parameters
  • bas_c: BAS Client object.

  • battery_level: The battery level value that was read.

  • err: ATT error code or 0.

Functions

void bt_gatt_bas_c_init(struct bt_gatt_bas_c *bas_c)

Initialize the BAS Client instance.

You must call this function on the BAS Client object before any other function.

Parameters
  • bas_c: BAS Client object.

int bt_gatt_bas_c_handles_assign(struct bt_gatt_dm *dm, struct bt_gatt_bas_c *bas_c)

Assign handles to the BAS Client instance.

This function should be called when a link with a peer has been established, to associate the link to this instance of the module. This makes it possible to handle several links and associate each link to a particular instance of this module. The GATT attribute handles are provided by the GATT Discovery Manager.

Note

This function starts the report discovery process. Wait for one of the functions in bt_gatt_hids_c_init_params before using the BAS Client object.

Parameters
  • dm: Discovery object.

  • bas_c: 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_gatt_bas_c_subscribe(struct bt_gatt_bas_c *bas_c, bt_gatt_bas_c_notify_cb func)

Subscribe to the battery level value change notification.

Parameters
  • bas_c: 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_gatt_bas_c_unsubscribe(struct bt_gatt_bas_c *bas_c)

Remove the subscription.

Parameters
  • bas_c: BAS Client object.

Return Value
  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

struct bt_conn *bt_gatt_bas_c_conn(const struct bt_gatt_bas_c *bas_c)

Get the connection object that is used with a given BAS Client.

Return

Connection object.

Parameters
  • bas_c: BAS Client object.

int bt_gatt_bas_c_read(struct bt_gatt_bas_c *bas_c, bt_gatt_bas_c_read_cb func)

Read the battery level value from the device.

This function sends a read request to the connected device.

Parameters
  • bas_c: BAS Client object.

  • func: The callback function.

Return Value
  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int bt_gatt_bas_c_get(struct bt_gatt_bas_c *bas_c)

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

static bool bt_gatt_bas_c_notify_supported(struct bt_gatt_bas_c *bas_c)

Check whether notification is supported by the service.

Parameters
  • bas_c: BAS Client object.

Return Value
  • true: If notifications are supported. Otherwise, false is returned.

int bt_gatt_bas_c_periodic_read_start(struct bt_gatt_bas_c *bas_c, s32_t interval, bt_gatt_bas_c_notify_cb func)

Periodically read the battery level value from the device with specific time interval.

Parameters
  • bas_c: 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_gatt_bas_c_periodic_read_stop(struct bt_gatt_bas_c *bas_c)

Stop periodic reading of the battery value from the device.

Parameters
  • bas_c: BAS Client object.

struct bt_gatt_bas_c_periodic_read
#include <bas_c.h>

Battery Service Client characteristic periodic read.

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_gatt_bas_c
#include <bas_c.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_gatt_bas_c_periodic_read periodic_read

Read characteristic value timing. Used when characteristic do not have a CCCD descriptor.

bt_gatt_bas_c_notify_cb notify_cb

Notification callback.

bt_gatt_bas_c_read_cb read_cb

Read value callback.

u16_t val_handle

Handle of the Battery Level Characteristic.

u16_t ccc_handle

Handle of the CCCD of the Battery Level Characteristic.

u8_t battery_level

Current battery value.

u8_t properties

Properties of the service.

bool notify

Notification supported.