GATT Client

This section introduces the GATT Client driver APIs including terms and acronyms, supported features, details on how to use this driver, GATT Client function groups, enums, GATT Client request and response structures and functions, API prototypes to discover primary services, included services, characteristics and descriptors and to read or write characteristics or descriptors. More...

Overview

This section introduces the GATT Client driver APIs including terms and acronyms, supported features, details on how to use this driver, GATT Client function groups, enums, GATT Client request and response structures and functions, API prototypes to discover primary services, included services, characteristics and descriptors and to read or write characteristics or descriptors.

Terms and Acronyms

Terms	Details
GATTC	GATT Client is the device that initiates commands and requests to the server.
MTU	Maximum Transmission Unit, specifies the maximum size of a packet to send.
ATT	Attribute Protocol. For more information, please refer to Wikipedia.

How to use this module

Each GATTC operation starts with sending a request to the server, then processing the corresponding response from the server in the callback function bt_app_event_callback().

• Step 1: GATT Client sends a read by group type request to the GATT Server, as shown in the figure of Primary service discovery event sequence in the Bluetooth developer's guide under [sdk_root]/doc folder.
  • Sample code:

    BT_GATTC_NEW_DISCOVER_PRIMARY_SERVICE_REQ(req);
    bt_gattc_discover_primary_service(conn_handle, &req);

• Step 2: GATT Client processes the response from the GATT Server, as shown in the figure of Primary service discovery event sequence in the Bluetooth developer's guide under [sdk_root]/doc folder.
  • Sample code:

    bt_status_t bt_app_event_callback(bt_msg_type_t msg, bt_status_t status, void *buff)
    {
        switch (msg) {
            case BT_GATTC_DISCOVER_PRIMARY_SERVICE:
            {
                printf("[GATT]BT_GATTC_DISCOVER_PRIMARY_SERVICE status = %d\n", status);
                if (status != BT_STATUS_SUCCESS && status != BT_ATT_ERRCODE_CONTINUE) {
                    // Any other status means there is no more primary service to discover.
                    printf("BT_GATTC_DISCOVER_PRIMARY_SERVICE FINISHED!!\n");
                    return BT_STATUS_SUCCESS;
                }
                // Exact starting handle, ending handle and UUID according to read by group type response and service declaration.
                bt_gattc_read_by_group_type_rsp_t *rsp = (bt_gattc_read_by_group_type_rsp_t *)buff;
                uint16_t end_group_handle = 0, starting_handle = 0, uuid = 0;
                bt_uuid_t uuid128;
                uint8_t *attribute_data_list = rsp->att_rsp->attribute_data_list;
                uint8_t num_of_data = (rsp->length - 2) / rsp->att_rsp->length;
                int i;
    
                for (i = 0; i < num_of_data; i++){
                    memcpy(&starting_handle, attribute_data_list + i * rsp->att_rsp->length, 2);
                    memcpy(&end_group_handle, attribute_data_list + i * rsp->att_rsp->length + 2, 2);
                    printf("[GATT]data : %d\n", i);
                    printf("[GATT]starting_handle = 0x%04x, end_group_handle = 0x%04x\n", starting_handle, end_group_handle);
                    if (rsp->att_rsp->length == 6) {
                        memcpy(&uuid, attribute_data_list + i * rsp->att_rsp->length + 4, rsp->att_rsp->length - 4);
                        printf("[GATT]uuid = 0x%04x\n", uuid);
                    } else {
                        memcpy(&uuid128.uuid, attribute_data_list + i * rsp->att_rsp->length + 4, rsp->att_rsp->length - 4);
                    }
                }
                if (status == BT_STATUS_SUCCESS) {
                    printf("BT_GATTC_DISCOVER_PRIMARY_SERVICE FINISHED!!\n");
                    return BT_STATUS_SUCCESS;
                }
            }
            break;
            default:
            break;
        }
        return BT_STATUS_SUCCESS;
    }

Functions
bt_status_t	bt_gattc_exchange_mtu (bt_handle_t connection_handle, const bt_gattc_exchange_mtu_req_t *req)
	This function sends an exchange MTU request to the GATT Server. More...
uint32_t	bt_gattc_get_mtu (bt_handle_t connection_handle)
	This function gets the MTU of this connection. More...
bt_status_t	bt_gattc_discover_primary_service (bt_handle_t connection_handle, const bt_gattc_discover_primary_service_req_t *req)
	This function discovers the primary service of the GATT Server. More...
bt_status_t	bt_gattc_discover_primary_service_by_uuid (bt_handle_t connection_handle, const bt_gattc_discover_primary_service_by_uuid_req_t *req)
	This function discovers the primary service of the GATT Server by the UUID. More...
bt_status_t	bt_gattc_find_included_services (bt_handle_t connection_handle, const bt_gattc_find_included_services_req_t *req)
	This function finds the included service on the GATT Server. More...
bt_status_t	bt_gattc_discover_charc (bt_handle_t connection_handle, const bt_gattc_discover_charc_req_t *req)
	This function discovers all characteristics or a specific characteristic by UUID of the GATT Server. More...
bt_status_t	bt_gattc_discover_charc_descriptor (bt_handle_t connection_handle, const bt_gattc_discover_charc_descriptor_req_t *req)
	This function discovers characteristic descriptors. More...
bt_status_t	bt_gattc_read_charc (bt_handle_t connection_handle, const bt_gattc_read_charc_req_t *req)
	This function reads the value or the descriptor of a characteristic of the GATT Server. More...
bt_status_t	bt_gattc_read_long_charc (bt_handle_t connection_handle, const bt_gattc_read_long_charc_value_req_t *req)
	This function reads a long characteristic value or a descriptor of the GATT Server. More...
bt_status_t	bt_gattc_read_using_charc_uuid (bt_handle_t connection_handle, const bt_gattc_read_using_charc_uuid_req_t *req)
	This function reads the characteristics of the GATT Server by UUID. More...
bt_status_t	bt_gattc_read_multi_charc_values (bt_handle_t connection_handle, const bt_gattc_read_multi_charc_values_req_t *req)
	This function reads multiple characteristic values from the GATT Server. More...
bt_status_t	bt_gattc_write_without_rsp (bt_handle_t connection_handle, uint8_t is_signed, const bt_gattc_write_without_rsp_req_t *req)
	This function writes characteristic values without a response from the GATT Server. More...
bt_status_t	bt_gattc_write_charc (bt_handle_t connection_handle, const bt_gattc_write_charc_req_t *req)
	This function writes values or descriptors of a characteristic on the GATT Server. More...
bt_status_t	bt_gattc_prepare_write_charc (bt_handle_t connection_handle, uint8_t is_reliable, uint16_t offset, const bt_gattc_prepare_write_charc_req_t *req)
	This function prepares to write characteristic values to the GATT Server. More...
bt_status_t	bt_gattc_send_execute_write_req (bt_handle_t connection_handle, const bt_gattc_execute_write_req_t *req)
	This function sends an execute write request to the GATT Server. More...

Modules
	Define
	This section defines macros for the GATT Client.
	Struct
	Basic data structures for the GATT Client.

Function Documentation

bt_status_t bt_gattc_discover_charc	(	bt_handle_t	connection_handle,
		const bt_gattc_discover_charc_req_t *	req
	)

This function discovers all characteristics or a specific characteristic by UUID of the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the discover characteristic request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_discover_charc_descriptor	(	bt_handle_t	connection_handle,
		const bt_gattc_discover_charc_descriptor_req_t *	req
	)

This function discovers characteristic descriptors.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the discover characteristic descriptors request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_discover_primary_service	(	bt_handle_t	connection_handle,
		const bt_gattc_discover_primary_service_req_t *	req
	)

This function discovers the primary service of the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is the pointer to the GATT discover primary service request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_discover_primary_service_by_uuid	(	bt_handle_t	connection_handle,
		const bt_gattc_discover_primary_service_by_uuid_req_t *	req
	)

This function discovers the primary service of the GATT Server by the UUID.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the GATT discover primary service by UUID request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_exchange_mtu	(	bt_handle_t	connection_handle,
		const bt_gattc_exchange_mtu_req_t *	req
	)

This function sends an exchange MTU request to the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the GATT exchange MTU request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_find_included_services	(	bt_handle_t	connection_handle,
		const bt_gattc_find_included_services_req_t *	req
	)

This function finds the included service on the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the GATT find included service request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

uint32_t bt_gattc_get_mtu

(

bt_handle_t

connection_handle

)

This function gets the MTU of this connection.

Parameters

[in]

connection_handle

The connection handle.

Returns

MTU of this connection if connection exists, otherwise return the default MTU.

bt_status_t bt_gattc_prepare_write_charc	(	bt_handle_t	connection_handle,
		uint8_t	is_reliable,
		uint16_t	offset,
		const bt_gattc_prepare_write_charc_req_t *	req
	)

This function prepares to write characteristic values to the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	is_reliable	is a flag to decide whether it is a reliable prepare write request.
[in]	offset	is the offset to write.
[in]	req	is a pointer to the prepare write request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_read_charc	(	bt_handle_t	connection_handle,
		const bt_gattc_read_charc_req_t *	req
	)

This function reads the value or the descriptor of a characteristic of the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the read characteristic request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_read_long_charc	(	bt_handle_t	connection_handle,
		const bt_gattc_read_long_charc_value_req_t *	req
	)

This function reads a long characteristic value or a descriptor of the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the read long characteristic request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_read_multi_charc_values	(	bt_handle_t	connection_handle,
		const bt_gattc_read_multi_charc_values_req_t *	req
	)

This function reads multiple characteristic values from the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the read multiple characteristic values request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_read_using_charc_uuid	(	bt_handle_t	connection_handle,
		const bt_gattc_read_using_charc_uuid_req_t *	req
	)

This function reads the characteristics of the GATT Server by UUID.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the read using characteristic UUID request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_send_execute_write_req	(	bt_handle_t	connection_handle,
		const bt_gattc_execute_write_req_t *	req
	)

This function sends an execute write request to the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the execute write request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_write_charc	(	bt_handle_t	connection_handle,
		const bt_gattc_write_charc_req_t *	req
	)

This function writes values or descriptors of a characteristic on the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	req	is a pointer to the write characteristic request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.

bt_status_t bt_gattc_write_without_rsp	(	bt_handle_t	connection_handle,
		uint8_t	is_signed,
		const bt_gattc_write_without_rsp_req_t *	req
	)

This function writes characteristic values without a response from the GATT Server.

Parameters

[in]	connection_handle	is the connection handle.
[in]	is_signed	is a flag to decide whether to use signed write. True , use signed write, False , use unsigned write.
[in]	req	is a pointer to the write without response request structure.

Returns

BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.