Use the GATT service

The Bluetooth APIs provide easy access to the Generic Attribute Profile (GATT) capabilities on your device. All you need to do is to connect to the GATT service and retrieve the characteristics of the service.

To use the GATT service:
  1. Initialize the resources for GATT by calling bt_gatt_init(). If your application uses btdevice.h functions, also call bt_device_init() to initialize the device.
  2. Connect to the service you intend to use by calling bt_gatt_connect_service(). If you do not know the remote device address, see Search for remote devices.
  3. Retrieve the number of characteristics for that service by calling bt_gatt_characteristics_count().
  4. Retrieve the characteristics for the service by calling bt_gatt_characteristics().
  5. Exchange data with the service on the device according to the specification of the service you’ve connected to.
  6. Disconnect from the service by calling bt_gatt_disconnect_service().
  7. Free the allocated resources for this session by calling bt_gatt_deinit().
The following code sample demonstrates how to set up a GATT connection on the client side:
static const char* MY_SERVICE_UUID = "0x180D";
static const char* MY_CHARACTERISTIC_UUID = "0x2A37";

// To receive notifications, define the notification callback
void notifications_cb(int instance, 
                      uint16_t handle, 
                      const uint8_t *val, 
                      uint16_t len, 
                      void *userData) {
    // Notification received. Handle received data
    // (for example, log the received notification).

// Define the callbacks to pass in during initialization.
// Define the service connected callback. This callback is
// invoked when a service connection is established.
void gatt_service_connected( const char *bdaddr, 
                             const char *service, 
                             int instance, 
                             int err, 
                             uint16_t connInt, 
                             uint16_t latency, 
                             uint16_t superTimeout, 
                             void *userData ) {

    // register for notifications
    bt_gatt_reg_notifications(instance, notifications_cb);

    // get characteristics count
    int num_charisteristics = 

    // get the list of characteristics
    bt_gatt_characteristic_t  *characteristicList;
    characteristicList = (bt_characteristic_t*) 
            malloc(num_charisteristics * 

    // look for the characteristic we are interested in
    int characteristicListSize = 0;
    characteristicListSize = bt_gatt_characteristics(instance, 

    for (int i = 0; i < characteristicListSize; i++) {
        // look for a UUID match
        if (strcmp(characteristicList[i].uuid, 
                   MY_CHARACTERISTIC_UUID) == 0) {
            // store the characteristic

            // enable notifications for this characteristic
            rc = bt_gatt_enable_notify(instance,

    // Free resources
    characteristicList = NULL;

// Define the disconnect callback. This callback is called when
// a service disconnect occurs.
void gatt_service_disconnected(const char *bdaddr, 
                               const char *service, 
                               int instance, 
                               int reason, 
                               void *userData) {

    // Handle the data as desired,
    // for example, log the disconnect.

// Define the update callback. This callback is called when
// service parameters are updated.
void gatt_service_updated(const char *bdaddr, 
                          int instance, 
                          uint16_t connInt, 
                          uint16_t latency, 
                          uint16_t superTimeout, 
                          void *userData) {
    // Handle received data, for example, 
    // log the service update.

// Declare GATT callbacks
bt_gatt_callbacks_t gatt_callbacks = { gatt_service_connected, 
                                       gatt_service_updated };  

// Request to connect to a service.
// When the service is successfully connected, the
// service_connected callback will be called.
void request_to_connect() {
    char *device_addr; 
    // Get the remote device address.
    // request to connect to service
    if (bt_gatt_connect_service(device_addr, 
            MY_SERVICE_UUID, NULL, NULL, NULL) < 0) {
        // request failed; handle failure
    } else {
        // service connection request successful

// Disconnect the service. The service disconnect callback is
// called when service is successfully disconnected.
void disconnect_service() {
    if (bt_gatt_disconnect_service(device_addr, MY_SERVICE_UUID)
            < 0) {
        // disconnect failed; handle failure
    } else {
        // disconnect successful

void main() {

Last modified: 2014-05-14

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus