bt_gatt_client_attr_get()

Description

Function requests and gets discovered attribute by handle.

Syntax

bt_gatt_client_attr_get(connection_id, handle, discovery_array[]);

Parameters

Variable	Input

Variable	Input
`connection_id`	Connection id which was described in `bt_gatt_client_connect` function. Could be either 0 or 1.
`handle`	Attribute handle to fetch. Please note that valid attribute handles range from 1 up to either the final attribute handle defined by the GATT server or the maximum permissible value of 90, whichever is lower.
`discovery_array[]`	An array designated to store the discovery data of the requested handle. Must be at least 20 bytes in size; 21 bytes is recommended to allow space for a null terminator at the end.

Returns

Return value	Return explanation
SCRIPT_OPERATION_SUCCESS	Successfully fetched attribute data.
SCRIPT_OPERATION_FAILED	Failed to fetch attribute data. This usually happens when: Discovery data is missing for this connection and bt_gatt_client_attr_discover(); function should be called. Requested handle is out of discovery capabilities bounds. Maximum value is 90. Connection with peer device no longer exists.
SCRIPT_NO_ACCESS	Bluetooth gatt client is not initialized.
SCRIPT_PARAM_INVALID	Passed array is too small to fit discovery data.

Discovery data will follow this format:

Example 1:

Discovery data: 02 6E 40 00 03 B5 A3 F3 93 E0 A9 E5 0E 24 DC CA 9E 03 00 10

______ - UUID Type (0x00 - 16 bit UUID, 0x01 - 32 bit UUID, 0x02 - 128 bit UUID)

______ - UUID

______ - Attribute type (0x00 - Service, 0x03 - Characteristic, 0x04 - Descriptor)

______ - Attribute properties

Example 2:

Discovery data: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 18 01 00 00 0A

______ - UUID Type (0x00 - 16 bit UUID, 0x01 - 32 bit UUID, 0x02 - 128 bit UUID)

______ - UUID

______ - Attribute type (0x00 - Service, 0x03 - Characteristic, 0x04 - Descriptor)

______ - Attribute properties

Possible attribute properties:

Property Name	Bit Mask	Description

Property Name	Bit Mask	Description
`Broadcast`	0x01	Allows broadcasting of the value without connection.
`Read`	0x02	Allows reading the characteristic value.
`Write Without Response`	0x04	Allows writing to the characteristic without requiring a response.
`Write`	0x08	Allows writing to the characteristic with response (acknowledgement).
`Notify`	0x10	Allows the server to send notifications to the client.
`Indicate`	0x20	Allows the server to send indications to the client (with acknowledgment).
`Authenticated Signed Writes`	0x40	Allows signed write commands.
`Extended Properties`	0x80	Indicates that additional properties are defined in a separate descriptor (Characteristic Extended Properties Descriptor).

Function call example

#include <io>
#include <read>
#include <float>
#include <string>
#include <core>
#include <write>
#include <define>
#include <socket>
#include <bluetooth>

#define FIRST_CONNECTION       0
#define SECOND_CONNECTION      1

new peer_mac_address[] = [0xFF, 0x48, 0x80, 0x33, 0xE3, 0xA8];
new number_of_attributes = 0;
new attributes[21]; //this array size fits one attribute

main()
{   
    bt_init();
    bt_gatt_client_init();
    while (bt_gatt_client_connect(FIRST_CONNECTION, BT_ADDR_RANDOM, peer_mac_address) != SCRIPT_OPERATION_SUCCESS)
    {
        Delay(100);
    }
    bt_gatt_client_attr_discover(FIRST_CONNECTION);
    bt_gatt_client_attr_count_get(FIRST_CONNECTION, number_of_attributes);
    for (new handle = 1; handle <= number_of_attributes; handle++)
    {
        bt_gatt_client_attr_get(FIRST_CONNECTION, handle, attributes);
    }
    for (;;)
    {
        Delay(100);
    }
}

Debug example

This example initializes BLE, then initializes GATT Client module, connects to peer device, calls for attribute discovery, gets discovered attribute count prints out all discovered attributes and disconnects from peer device. Example uses debug_print function to print information log to Initialized peripheral.

#include <io>
#include <read>
#include <float>
#include <string>
#include <core>
#include <write>
#include <define>
#include <socket>
#include <bluetooth>
#include <debug>

#define RS232_SPEED         115200
#define WORD_LENGTH         WORDLENGTH_8
#define STOP_BITS           STOPBITS_1
#define PARITY              PARITY_NONE

#define FIRST_CONNECTION       0
#define SECOND_CONNECTION      1

new peer_mac_address[] = [0xD2, 0xF4, 0x9D, 0xCF, 0x6C, 0xD1];
new return_code = SCRIPT_OPERATION_SUCCESS;
new number_of_attributes = 0;
new attributes[21]; //this array size fits one attribute

main()
{
    Init(RS232, RS232_SPEED, WORD_LENGTH, STOP_BITS, PARITY);
    debug_init(RS232);
    
    return_code = bt_init();
    if (return_code != SCRIPT_OPERATION_SUCCESS)
    {
        // Handle failed bt_init here
        debug_print("bt_gatt_client_init failed\r\n");
    }
    else 
    {
        debug_print("bt_init succeeded\r\n");
    }
    
    return_code = bt_gatt_client_init();
    if (return_code != SCRIPT_OPERATION_SUCCESS)
    {
        // Handle failed bt_gatt_client_init here
        debug_print("bt_gatt_client_init failed\r\n");
    }
    else 
    {
        debug_print("bt_gatt_client_init succeeded\r\n");
    }
    debug_print("Connecting to a device with this MAC address: %X:%X:%X:%X:%X:%X\r\n", peer_mac_address[0], 
                peer_mac_address[1], peer_mac_address[2], peer_mac_address[3], peer_mac_address[4], peer_mac_address[5]);
    while (bt_gatt_client_connect(FIRST_CONNECTION, BT_ADDR_PUBLIC, peer_mac_address) != SCRIPT_OPERATION_SUCCESS)
    {
        debug_print("bt_gatt_client_connect time-out\r\n");
        Delay(100);
    }
    debug_print("Connected successfully\r\n");
    Delay(100);
    return_code = bt_gatt_client_attr_discover(FIRST_CONNECTION);
    if (return_code != SCRIPT_OPERATION_SUCCESS)
    {
        // Handle failed bt_gatt_client_attr_discover here
        debug_print("bt_gatt_client_attr_discover failed\r\n");
    }
    else 
    {
        debug_print("bt_gatt_client_attr_discover succeeded\r\n");
    }
    return_code = bt_gatt_client_attr_count_get(FIRST_CONNECTION, number_of_attributes);
    if (return_code != SCRIPT_OPERATION_SUCCESS)
    {
        // Handle failed bt_gatt_client_attr_count_get here
        debug_print("bt_gatt_client_attr_count_get failed\r\n");
    }
    else 
    {
        debug_print("bt_gatt_client_attr_count_get succeeded\r\n");
        debug_print("Number of attributes: %i\r\n", number_of_attributes);
    }
    for (new handle = 1; handle <= number_of_attributes; handle++)
    {
        return_code = bt_gatt_client_attr_get(FIRST_CONNECTION, handle, attributes);
        if (return_code != SCRIPT_OPERATION_SUCCESS)
        {
            // Handle failed bt_gatt_client_attr_get here
            debug_print("bt_gatt_client_attr_get failed, handle: 0x%02X\r\n", handle);
        }
        else 
        {
            debug_print("bt_gatt_client_attr_count_get succeeded\r\n");
        }
        debug_print("RAW Handle 0x%02X:", handle);
        for (new j = 0; j < sizeof(attributes); j++)
        {
            debug_print(" %02X", attributes[j]);
        }
        debug_print("\r\n");
        Delay(20);
    }
    return_code = bt_gatt_client_disconnect(FIRST_CONNECTION);
    if (return_code != SCRIPT_OPERATION_SUCCESS)
    {
        // Handle failed bt_gatt_client_disconnect here
        debug_print("bt_gatt_client_disconnect failed\r\n");
    }
    else 
    {
        debug_print("bt_gatt_client_disconnect succeeded\r\n");
    }
    
    for(;;)
    {   
        Delay(1000);
    }
}