BLE BAS

This section manages the read/write events of Battery Level Characteristic from a peer device and provides API to send notification to the peer device when the battery state changes. More...

Overview

This section manages the read/write events of Battery Level Characteristic from a peer device and provides API to send notification to the peer device when the battery state changes.

Terms and Acronyms

Terms	Details
BAS	Battery Service. This service exposes the battery state and battery level to the peer device.

How to use this module

• Step 1. Add BAS service to the application's GATT service database. And then return the bt_gatts_service_t pointer to GATTS stack by implementing the user-defined callback bt_get_gatt_server().
  • Sample Code:

    // The GATTS collects all services.
    const bt_gatts_service_t * ble_gatt_server[] = {
        &ble_gap_service,  // handle range: 0x0001 to 0x0009.
        &ble_gatt_service, // handle range: 0x0011 to 0x0015.
        &ble_bas_service,  // handle range: 0x0031 to 0x0034.
        NULL
     };
     const bt_gatts_service_t** bt_get_gatt_server()
     { 
         return ble_gatt_server;
     }

• Step 2. Implement the user-defined callback ble_bas_read_callback() to listen to the read event of Battery Level Characteristic and Client Configuration Characteristic Descriptor from the peer device.
  • Sample Code:

    uint8_t ble_bas_read_callback(ble_bas_event_t event, uint16_t conn_handle)
    {
        if (conn_handle) {
            switch (event) {
                case BLE_BAS_EVENT_BATTRY_LEVEL_READ:
                    uint8_t battery_level = 100;
                    return battery_level;
                case BLE_BAS_EVENT_CCCD_READ:
                    uint8_t notify_enabled = 1;
                    return notify_enabled;
                default :
                    break;
            }
        }
        return 0;
    }

• Step 3. Implement the user-defined callback ble_bas_write_callback() to listen to the write event of Client Configuration Characteristic Descriptor from the peer device.
  • Sample Code:

    void ble_bas_write_callback(ble_bas_event_t event, bt_handle_t conn_handle, void *data)
    {
        uint16_t cccd_value = 0;
        cccd_value = *(uint16_t *)data;
        if ((conn_handle) && (BLE_BAS_EVENT_CCCD_WRITE == event)) {
            //Save the data;
        }
    }

• Step 4. Notify the Battery State of the device to the peer device.
  • Sample code:

    uint8_t battery_level = get_current_battery_api();
    ble_bas_notify_battery_level(conn_handle, battery_level);

Functions
bt_status_t	ble_bas_notify_battery_level (bt_handle_t conn_handle, uint8_t battery_level)
	This function sends a notification to a peer device about the current battery level. More...
uint8_t	ble_bas_read_callback (ble_bas_event_t event, bt_handle_t conn_handle)
	This function is a user-defined callback for the application to listen to the read event of Battery Level Characteristic and Client Configuration Characteristic Descriptor. More...
void	ble_bas_write_callback (ble_bas_event_t event, bt_handle_t conn_handle, void *data)
	This function is a user-defined callback for the application to listen to the write event of Client Configuration Characteristic Descriptor. More...

Variables
const bt_gatts_service_t	ble_bas_service

Modules
	Define
	This section defines the BAS event types.

Function Documentation

bt_status_t ble_bas_notify_battery_level	(	bt_handle_t	conn_handle,
		uint8_t	battery_level
	)

This function sends a notification to a peer device about the current battery level.

Parameters

[in]	conn_handle	is the connection handle.
[in]	battery_level	is the current battery level.

Returns

BT_STATUS_SUCCESS, the notification is sent successfully. BT_STATUS_FAIL, the notification failed to send.

uint8_t ble_bas_read_callback	(	ble_bas_event_t	event,
		bt_handle_t	conn_handle
	)

This function is a user-defined callback for the application to listen to the read event of Battery Level Characteristic and Client Configuration Characteristic Descriptor.

Parameters

[in]	event	is the event of type ble_bas_event_t.
[in]	conn_handle	is the connection handle.

Returns

the response to the read event of Battery Level Characteristic or Client Configuration Characteristic Descriptor. If the read event type is BLE_BAS_EVENT_BATTRY_LEVEL_READ, the return value is the corresponding battery level. If the read event type is BLE_BAS_EVENT_CCCD_READ, the return value is either 0 or 1.

void ble_bas_write_callback	(	ble_bas_event_t	event,
		bt_handle_t	conn_handle,
		void *	data
	)

This function is a user-defined callback for the application to listen to the write event of Client Configuration Characteristic Descriptor.

Parameters

[in]	event	is the event of type ble_bas_event_t.
[in]	conn_handle	is the connection handle.
[in]	data	is the data of write event from a remote device.

Returns

void.