Bluetooth LE Mode API Reference

Header File

#include <hw/bluetooth_le.h>

Functions

int ble_client_setcallback(ble_client_cb_f cb)

Setup BLE client event callback.

Parameters:: cb – Callback function to set, see ble_client_cb_f
Returns:: For return value see bterr_e

int ble_client_start_scan(int duration, ble_scan_cb_f cb)

Start BLE device scan.

Parameters:

duration – duration of scan in seconds, default 10s
cb – scan callback function see ble_scan_cb_f

Returns:

For return value see bterr_e

int ble_client_stop_scan(void)

Stop BLE scanning.

Returns:: For return value see bterr_e

int ble_client_get_scancount(void)

Get count of devices found during scanning.

Returns:: device count

int ble_client_get_scanresult(int idx, ble_scan_result_t *res)

Get scanned device information.

Parameters:

idx – index value from 0 to scan count - 1
res – pointer to ble_scan_result_t structure

Returns:

For return value see bterr_e

int ble_client_connect(uint8_t addr_type, uint8_t *bd_addr)

Connect to BLE device. Once connection is initiated, A client callback event is generated with BLE_CLIENT_LINK_CONNECTED or BLE_CLIENT_LINK_DISCONNECT for connection and disconnection respectively.

Parameters:

addr_type – The type of peer device address, from scan result or ble_addr_type_e
bd_addr – Address of BLE device

Returns:

For return value see bterr_e

int ble_client_connect_cancel(uint8_t *bd_addr)

Cancel and ongoing BLE connection initiated by ble_client_connect()

Parameters:: bd_addr – Address of BLE device
Returns:: For return value see bterr_e

uint16_t ble_client_get_connhandle(uint8_t *bd_addr)

Get BLE client connection handle using address.

Parameters:: bd_addr – BLE device address
Returns:: connection handle on success or -1 for error

int ble_client_disconnect(uint16_t handle)

Disconnect from BLE device.

Parameters:: handle – connection handle
Returns:: For return value see bterr_e

int ble_client_refresh_service(uint16_t handle)

Refresh or discover BLE client services.

Parameters:: handle – connection handle
Returns:: For return value see bterr_e

int ble_client_search_service(uint16_t handle, ble_uuid_t *svc_uuid)

Search BLE service by UUID.

Parameters:

handle – connection handle
svc_uuid – service UUID to search for

Returns:

For return value see bterr_e

int ble_client_get_characteristic_count(uint16_t handle, ble_uuid_t *svc_uuid, int *count)

Get characteristic count for a BLE service pointed by svc_uuid.

Parameters:

handle – connection handle
svc_uuid – service UUID
count – returns characteristic count in this pointer

Returns:

For return value see bterr_e

int ble_client_get_characteristics(uint16_t handle, ble_uuid_t *svc_uuid, struct ble_char_t *char_list)

Get BLE service characteristics list.

Parameters:

handle – connection handle
svc_uuid – service UUID
char_list – buffer to store characteristics list (must be >= count * sizeof(struct ble_char_t))

Returns:

For return value see bterr_e

int ble_client_get_characteristic_count_by_handle(uint16_t handle, ble_uuid_t *svc_uuid, uint16_t start_handle, uint16_t end_handle, int *count)

Get BLE service characteristic count by characteristic handle.

Parameters:

handle – connection handle
svc_uuid – service UUID
start_handle – start handle value
end_handle – end handle value
count – total count of characteristics found is returned in this buffer

Returns:

For return value see bterr_e

int ble_client_get_characteristic_by_handle(uint16_t handle, ble_uuid_t *svc_uuid, uint16_t start_handle, uint16_t end_handle, struct ble_char_t *char_list)

Get BLE service characteristics list by handle.

Parameters:

handle – service handle
svc_uuid – service UUID
start_handle – start handle value
end_handle – end handle value
char_list – buffer to store characteristics list (must be >= count * sizeof(struct ble_char_t))

Returns:

For return value see bterr_e

int ble_client_get_characteristic_by_uuid(uint16_t handle, ble_uuid_t *svc_uuid, ble_uuid_t *char_uuid, struct ble_char_t *char_buffer)

Get BLE service characteristic by UUID pointed by char_uuid.

Parameters:

handle – connection handle
svc_uuid – service UUID
char_uuid – characteristic UUID
char_buffer – buffer to store characteristic

Returns:

For return value see bterr_e

int ble_client_get_descriptors(uint16_t handle, uint16_t char_handle, struct ble_chardesc_t *desc_list)

Get BLE characteristic descriptors.

Parameters:

handle – connection handle
char_handle – characteristic handle
desc_list – buffer to store descriptor list, must be >= desc_count * sizeof(ble_chardesc_t)

Returns:

For return value see bterr_e

int ble_client_get_descriptor_handle(uint16_t handle, uint16_t char_handle, ble_uuid_t *desc_uuid, uint16_t *out_handle)

Get BLE characteristic descriptors handle.

Parameters:

handle – connection handle
char_handle – characteristic handle
desc_uuid – characteristic descriptor UUID
out_handle – buffer to store descriptor handle

Returns:

For return value see bterr_e

int ble_client_read_char_by_handle(uint16_t handle, uint16_t char_handle)

Read BLE device characteristic by handle. This will generate event callback with BLE_CLIENT_READ_EVENT event ID.

Parameters:

handle – connection handle
char_handle – characteristic handle

Returns:

For return value see bterr_e

int ble_client_read_char_by_uuid(uint16_t handle, uint16_t start_handle, uint16_t end_handle, ble_uuid_t *uuid)

Read BLE device characteristic by handle. This will generate event callback with BLE_CLIENT_READ_EVENT event ID.

Parameters:

handle – connection handle
start_handle – start handle
end_handle – end handle
uuid – characteristic UUID to read

Returns:

For return value see bterr_e

int ble_client_read_multiple_char(uint16_t handle, uint16_t *handles, int count)

Read multiple BLE device characteristics by handle. This will generate event callback with BLE_CLIENT_READ_MULTI_EVENT event ID.

Parameters:

handle – connection handle
handles – list of characteristic handles
count – handle count

Returns:

For return value see bterr_e

int ble_client_write_char(uint16_t handle, uint16_t char_handle, void *value, uint16_t len, uint8_t type)

Write BLE device characteristic by handle. On success, this function will generate event callback with BLE_CLIENT_WRITE_EVENT or BLE_CLIENT_WRITE_WITH_RESP_EVENT event ID.

Parameters:

handle – connection handle
char_handle – characteristic handle
value – buffer to write
len – lenth of data to write
type – write type see ble_write_type_e

Returns:

For return value see bterr_e

int ble_client_write_char_descr(uint16_t handle, uint16_t desc_handle, void *value, uint16_t len)

Write BLE device characteristic descriptor by handle. On success, this function will generate event callback with BLE_CLIENT_WRITE_EVENT.

Parameters:

handle – connection handle
desc_handle – characteristic descriptor handle
value – buffer to write
len – lenth of data to write

Returns:

For return value see bterr_e

int ble_client_prepare_write(uint16_t handle, uint16_t char_handle, uint16_t offset, void *value, uint16_t value_len)

Do prepare write for BLE device characteristic.

Parameters:

handle – connection handle
char_handle – characteristic handle
offset – offset of write value
value – buffer to write
value_len – length of data to write

Returns:

For return value see bterr_e

int ble_client_execute_write(uint16_t handle, uint16_t offset)

Execute a prepare write sequence.

Parameters:

handle – connection handle
offset – offset of write value

Returns:

For return value see bterr_e

int ble_client_configure_notify(uint16_t handle, uint16_t char_handle, uint16_t notify_indicate)

Enable/disable notification or indication.

Parameters:

handle – connection handle
char_handle – service characteristic handle
notify_indicate – 1 for notify, 2 for indicate

Returns:

For return value see bterr_e

int ble_client_set_scan_params(struct ble_scan_params_t *scan_params)

Set scan parameters.

Parameters:: scan_params – scan parameter structure, see ble_scan_params_t
Returns:: For return value see bterr_e

int ble_client_print_devinfo_byaddr(uint8_t *addr)

Print BLE device information pointed by addr.

Parameters:: addr – BLE device address to print
Returns:: For return value see bterr_e

int ble_client_print_devinfo_byname(const char *name)

Print BLE device information identified by name.

Parameters:: name – Name of BLE device
Returns:: For return value see bterr_e

int ble_client_print_devinfo_byhandle(uint16_t handle)

Print BLE device information identified by connection handle.

Parameters:: handle – connection handle
Returns:: For return value see bterr_e

Unions

union ble_client_cb_param_t

#include <bluetooth_le.h>

Gatt client callback parameters union.

Public Members

struct ble_client_cb_param_t::ble_client_connect_evt_t connect

struct ble_client_cb_param_t::ble_client_disconnect_evt_t disconnect

struct ble_client_cb_param_t::gattc_search_cmpl_evt_param search_cmpl

struct ble_client_cb_param_t::gattc_search_res_evt_param search_res

struct ble_client_cb_param_t::gattc_read_char_evt_param read

struct ble_client_cb_param_t::gattc_write_evt_param write

struct ble_client_cb_param_t::gattc_notify_evt_param notify

struct ble_client_cb_param_t::gattc_dis_srvc_cmpl_evt_param refresh_cmpl

struct ble_client_connect_evt_t

#include <bluetooth_le.h>

Gatt client callback param of BLE_CLIENT_LINK_CONNECTED.

Public Members

char name[31]: Name of device

uint8_t addr[SIZE_OF_BDADDR]: Remote bluetooth device address

uint16_t handle: Connection id

uint16_t mtu: MTU size

struct ble_client_disconnect_evt_t

#include <bluetooth_le.h>

Gatt client callback param of BLE_CLIENT_LINK_DISCONNECT.

Public Members

char name[31]: Name of device

uint8_t addr[SIZE_OF_BDADDR]: Remote bluetooth device address

uint16_t handle: Connection id

uint16_t reason: The reason of gatt connection close

struct gattc_dis_srvc_cmpl_evt_param

#include <bluetooth_le.h>

Gatt client callback param of BLE_CLIENT_SVC_REFRESH_COMPLETE.

Public Members

uint8_t status: Operation status

uint16_t conn_id: Connection id

struct gattc_notify_evt_param

#include <bluetooth_le.h>

Gatt client callback param of BLE_CLIENT_NOTIFY_EVENT.

Public Members

uint16_t conn_id: Connection id

uint16_t handle: The Characteristic or descriptor handle

uint16_t value_len: Notify attribute value

uint8_t *value: Notify attribute value

uint8_t is_notify: True means notify, false means indicate

struct gattc_read_char_evt_param

#include <bluetooth_le.h>

Gatt client callback param of BLE_CLIENT_READ_EVENT, BLE_CLIENT_READ_MULTI_EVENT.

Public Members

uint8_t status: Operation status

uint16_t conn_id: Connection id

uint16_t handle: Characteristic handle

uint16_t value_len: Characteristic value length

uint8_t *value: Characteristic value

struct gattc_search_cmpl_evt_param

#include <bluetooth_le.h>

Gatt client callback param of BLE_CLIENT_SEARCH_SERVICE_COMPLETE.

Public Members

uint16_t conn_id: Connection id

uint8_t searched_service_source: The source of the service information

struct gattc_search_res_evt_param

#include <bluetooth_le.h>

Gatt client callback param of BLE_CLIENT_SEARCH_SERVICE.

Public Members

uint16_t conn_id: Connection id

uint16_t start_handle: Service start handle

uint16_t end_handle: Service end handle

ble_uuid_t uuid: Service id, include service uuid and other information

uint8_t is_primary: True if this is the primary service

struct gattc_write_evt_param

#include <bluetooth_le.h>

Gatt client callback param of BLE_CLIENT_WRITE_EVENT, BLE_CLIENT_WRITE_WITH_RESP_EVENT.

Public Members

uint8_t status: Operation status

uint16_t conn_id: Connection id

uint16_t handle: The Characteristic or descriptor handle

uint16_t offset: The prepare write offset, this value is valid only when prepare write

Structures

struct __BLE_PACKED__

BLE UUID structure.

Public Members

uint16_t len: UUID length, 16bit, 32bit or 128bit

uint16_t uuid16: 16bit UUID

uint32_t uuid32: 32bit UUID

uint8_t uuid128[BLE_UUID_LEN_128]: 128bit UUID

union __BLE_PACKED__::[anonymous] uuid: UUID

struct ble_char_t

BLE service characteristic structure.

Public Members

uint16_t handle: characteristic handle

uint16_t value_handle: value handle

uint8_t property: property

ble_uuid_t uuid: UUID

uint8_t desc_count: descriptor count

struct ble_chardesc_t

BLE service characteristic descriptor structure.

Public Members

uint16_t handle: descriptor handle

ble_uuid_t uuid: descriotor UUID

struct ble_scan_params_t

BLE scanning parameter structure.

Public Members

uint8_t scan_type: Scan type

uint8_t own_addr_type: Owner address type

uint8_t scan_filter_policy: Scan filter policy

uint16_t scan_interval

Scan interval. This is defined as the time interval from when the Controller started its last LE scan until it begins the subsequent LE scan.

Range: 0x0004 to 0x4000 Default: 0x0010 (10 ms) Time = N * 0.625 msec Time Range: 2.5 msec to 10.24 seconds

uint16_t scan_window

Scan window. The duration of the LE scan. LE_Scan_Window shall be less than or equal to LE_Scan_Interval

Range: 0x0004 to 0x4000 Default: 0x0010 (10 ms) Time = N * 0.625 msec Time Range: 2.5 msec to 10240 msec

struct ble_scan_result_t

BLE Scan result structure.

Public Members

uint8_t bd_addr[SIZE_OF_BDADDR]: Bluetooth device address which has been searched

char name[30]: Name of Bluetooth device if found in ADV response

int rssi: Searched device’s RSSI

uint8_t adv_data[31]: Received advertisement data

uint8_t scan_rsp[31]: Received scan response data

uint8_t adv_data_len: Adv data length

uint8_t scan_rsp_len: Scan response length

uint8_t flag: Advertising data flag bit

uint8_t addr_type: Ble device address type

uint8_t event_type: BLE event type

int num_resps: Scan result number

uint8_t has_name: BLE device name is found and valid

Macros

__BLE_PACKED__

BLE_UUID_LEN_16: UUID16 lenth in bytes

BLE_UUID_LEN_32: UUID32 lenth in bytes

BLE_UUID_LEN_128: UUID128 lenth in bytes

SIZE_OF_BDADDR: Size of Dluetooth device address in bytes

Type Definitions

typedef void (*ble_scan_cb_f)(int event, ble_scan_result_t *arg)

BLE scan result callback type.

Enumerations

enum ble_addr_type_e

Values:

enumerator BLE_ADDR_TYPE_PUBLIC: Public Device Address

enumerator BLE_ADDR_TYPE_RANDOM: Random Device Address

enum scan_event_e

Scan event list.

Values:

enumerator BLE_CLIENT_SCAN_DONE

enumerator BLE_CLIENT_SCAN_EVENT

enum ble_client_event_e

BLE Client status callback events.

Values:

enumerator BLE_CLIENT_LINK_DISCONNECT

enumerator BLE_CLIENT_LINK_CONNECTED

enumerator BLE_CLIENT_SEARCH_SERVICE

enumerator BLE_CLIENT_SEARCH_SERVICE_COMPLETE

enumerator BLE_CLIENT_CFG_MTU

enumerator BLE_CLIENT_READ_EVENT

enumerator BLE_CLIENT_READ_BLOB_EVENT

enumerator BLE_CLIENT_READ_MULTI_EVENT

enumerator BLE_CLIENT_WRITE_EVENT

enumerator BLE_CLIENT_WRITE_WITH_RESP_EVENT

enumerator BLE_CLIENT_NOTIFY_EVENT

enumerator BLE_CLIENT_SVC_REFRESH_COMPLETE

enum ble_write_type_e

BLE device write types.

Values:

enumerator BLE_WRITE_TYPE_NO_RESP

enumerator BLE_WRITE_TYPE_WITH_RESP

enumerator BLE_WRITE_TYPE_SIGNED

enum ble_conn_status_e

BLE connection status error code.

Values:

enumerator BLE_CLIENT_CONN_UNKNOWN: Gatt connection unknown

enumerator BLE_CLIENT_CONN_L2C_FAILURE: General L2cap failure

enumerator BLE_CLIENT_CONN_TIMEOUT: Connection timeout

enumerator BLE_CLIENT_CONN_TERMINATE_PEER_USER: Connection terminate by peer user

enumerator BLE_CLIENT_CONN_TERMINATE_LOCAL_HOST: Connection terminated by local host

enumerator BLE_CLIENT_CONN_FAIL_ESTABLISH: Connection fail to establish

enumerator BLE_CLIENT_CONN_LMP_TIMEOUT: Connection fail for LMP response tout

enumerator BLE_CLIENT_CONN_CONN_CANCEL: L2CAP connection cancelled

enumerator BLE_CLIENT_CONN_NONE: No connection to cancel

enum [anonymous]

ATT success code and error codes.

Values:

enumerator BLE_ATT_OK

enumerator BLE_ATT_ERR_INVALID_HANDLE

enumerator BLE_ATT_ERR_READ_NOT_PERMIT

enumerator BLE_ATT_ERR_WRITE_NOT_PERMIT

enumerator BLE_ATT_ERR_INVALID_PDU

enumerator BLE_ATT_ERR_INSUF_AUTHENTICATION

enumerator BLE_ATT_ERR_REQ_NOT_SUPPORTED

enumerator BLE_ATT_ERR_INVALID_OFFSET

enumerator BLE_ATT_ERR_INSUF_AUTHORIZATION

enumerator BLE_ATT_ERR_PREPARE_Q_FULL

enumerator BLE_ATT_ERR_NOT_FOUND

enumerator BLE_ATT_ERR_NOT_LONG

enumerator BLE_ATT_ERR_INSUF_KEY_SIZE

enumerator BLE_ATT_ERR_INVALID_ATTR_LEN

enumerator BLE_ATT_ERR_ERR_UNLIKELY

enumerator BLE_ATT_ERR_INSUF_ENCRYPTION

enumerator BLE_ATT_ERR_UNSUPPORT_GRP_TYPE

enumerator BLE_ATT_ERR_INSUF_RESOURCE

enumerator BLE_ATT_ERR_NO_RESOURCES

enumerator BLE_ATT_ERR_INTERNAL_ERROR

enumerator BLE_ATT_ERR_WRONG_STATE

enumerator BLE_ATT_ERR_DB_FULL

enumerator BLE_ATT_ERR_BUSY

enumerator BLE_ATT_ERR_ERROR

enumerator BLE_ATT_ERR_CMD_STARTED

enumerator BLE_ATT_ERR_ILLEGAL_PARAMETER

enumerator BLE_ATT_ERR_PENDING

enumerator BLE_ATT_ERR_AUTH_FAIL

enumerator BLE_ATT_ERR_MORE

enumerator BLE_ATT_ERR_INVALID_CFG

enumerator BLE_ATT_ERR_SERVICE_STARTED

enumerator BLE_ATT_ERR_ENCRYPTED_MITM

enumerator BLE_ATT_ERR_ENCRYPTED_NO_MITM

enumerator BLE_ATT_ERR_NOT_ENCRYPTED

enumerator BLE_ATT_ERR_CONGESTED

enumerator BLE_ATT_ERR_DUP_REG

enumerator BLE_ATT_ERR_ALREADY_OPEN

enumerator BLE_ATT_ERR_CANCEL

enumerator BLE_ATT_ERR_STACK_RSP

enumerator BLE_ATT_ERR_APP_RSP

enumerator BLE_ATT_ERR_UNKNOWN_ERROR

enumerator BLE_ATT_ERR_CCC_CFG_ERR

enumerator BLE_ATT_ERR_PRC_IN_PROGRESS

enumerator BLE_ATT_ERR_OUT_OF_RANGE