Work with Device Characteristics and Descriptors

Before working with characteristics or descriptors, scan for and create a connection to your Bluetooth^® Low Energy peripheral device. See Find Your Bluetooth Low Energy Peripheral Devices for more information and instructions. After connecting to your device, you can interface with it by reading or writing the device characteristics and descriptors.

b = ble("DemoDev");

Access Device Characteristics

View your device characteristics by looking at the Characteristics property of the ble object.

b.Characteristics

ans=11×5 table
        ServiceName                     ServiceUUID                               CharacteristicName                           CharacteristicUUID                Attributes  
    ___________________    ______________________________________    ____________________________________________    ______________________________________    ______________

    "Generic Access"       "1800"                                    "Device Name"                                   "2A00"                                    {1×2 string  }
    "Generic Access"       "1800"                                    "Appearance"                                    "2A01"                                    {["Read"    ]}
    "Generic Access"       "1800"                                    "Peripheral Preferred Connection Parameters"    "2A04"                                    {["Read"    ]}
    "Generic Access"       "1800"                                    "Central Address Resolution"                    "2AA6"                                    {["Read"    ]}
    "Generic Attribute"    "1801"                                    "Service Changed"                               "2A05"                                    {["Indicate"]}
    "Heart Rate"           "180D"                                    "Heart Rate Measurement"                        "2A37"                                    {["Notify"  ]}
    "Heart Rate"           "180D"                                    "Body Sensor Location"                          "2A38"                                    {["Read"    ]}
    "Battery Service"      "180F"                                    "Battery Level"                                 "2A19"                                    {["Read"    ]}
    "User Data"            "181C"                                    "Gender"                                        "2A8C"                                    {1×2 string  }
    "Custom"               "03B80E5A-EDE8-4B33-A751-6CE34EC4C700"    "Custom"                                        "7772E5DB-3868-4112-A1A9-F2669D106BF3"    {1×6 string  }
    "Custom"               "03B80E5A-EDE8-4B33-A751-6CE34EC4C700"    "Custom"                                        "7772E5DC-3868-4112-A1A9-F2669D106BF3"    {1×3 string  }

This table lists each characteristic and the service it is associated with. As the table shows, each service can contain multiple characteristics. If multiple characteristics have the same name, differentiate between them using the UUID. In this example, the device has both standard and custom characteristics. Standard characteristics are defined by the Bluetooth SIG, while custom characteristics are usually specific to the device or device manufacturer.

The Attributes field in this table tells you the read and write permissions for each characteristic. Select a characteristic you are interested in and view its properties using characteristic. For example, access the "Gender" characteristic using the service and characteristic names.

c = characteristic(b,"User Data","Gender")

c = 
  Characteristic with properties:

             Name: "Gender"
             UUID: "2A8C"
       Attributes: "Read" "Write"
      Descriptors: []

This characteristic is both readable and writable.

Read and Write Characteristic Data

Because the "Gender" characteristic is readable and writable, you can write data to it and verify the change in values.

Use read to get the current data. The full behavior of read for a characteristic depends on the Attributes property, as described in characteristicData.

data = read(c)

data = 0

Interpret the data by referring to the specification for this characteristic on the Bluetooth SIG website. 0 represents male and 1 represents female. Write 1 to the characteristic to indicate female using write.

write(c,1)

You can read from the characteristic again to observe the change in the data.

data = read(c)

data = 1

Subscribe to Characteristic

You can also subscribe to a characteristic to enable notification or indication on the characteristic. You can only subscribe to characteristics that contain "Notify", "Indicate", or both in the Attributes property. After you enable notification or indication for a characteristic, use read to get the updated data. See characteristicData for a description of the full behavior of read based on Attributes.

For this example, create a characteristic object that represents the "Heart Rate Measurement" characteristic.

c = characteristic(b,"Heart Rate","Heart Rate Measurement")

c = 
  Characteristic with properties:

             Name: "Heart Rate Measurement"
             UUID: "2A37"
       Attributes: "Notify"
      Descriptors: [1x3 table]
 DataAvailableFcn: []

Show descriptors

This characteristic supports "Notify".

Start receiving notifications by using subscribe. See type for a description of the full behavior of subscribe based on Attributes.

subscribe(c)

Read from the characteristic to check that you are receiving data.

read(c)

ans = 1×19

    23    14     1   187     1   186     1   185     1   184     1   183     1   182     1   181     1   180     1

Interpret the data by referring to the specification for this characteristic found in the Heart Rate Service on the Bluetooth SIG website.

After you finish working with the characteristic, disable notifications using unsubscribe.

unsubscribe(c)

Use Callback Function to Read Characteristic Data

You can also create a callback function to read characteristic data as it updates with new data from the device.

Because the "Heart Rate Measurement" characteristic supports "Notify", you can create a callback function called displayCharacteristicData. Specify the read mode as 'oldest' instead of 'latest'. Calling the 'latest' data can lead to errors in the callback function caused by the flushing of previous data.

function displayCharacteristicData(src,evt)
    [data,timestamp] = read(src,'oldest');
    disp(data);
    disp(timestamp);
end

Use the @ operator to assign the function handle to the DataAvailableFcn property of the characteristic. When a new notification is available, the callback is called.

c.DataAvailableFcn = @displayCharacteristicData

c = 
  Characteristic with properties:

             Name: "Heart Rate Measurement"
             UUID: "2A37"
       Attributes: "Notify"
      Descriptors: [1x3 table]
 DataAvailableFcn: displayCharacteristicData

Show descriptors

After you finish working with the characteristic, disable notifications and reset the callback using unsubscribe.

unsubscribe(c)
c.DataAvailableFcn = [];

Access Device Descriptors

If a characteristic has descriptors, you can access the descriptors to read from or write to them. View the descriptors for a characteristic by looking at the Descriptors property of the characteristic object.

For this example, show the Descriptors for the "Heart Rate Measurement" characteristic.

c.Descriptors

ans=1×3 table
               DescriptorName                DescriptorUUID     Attributes 
    _____________________________________    ______________    ____________

    "Client Characteristic Configuration"        "2902"        {1×2 string}

Access the "Client Characteristic Configuration" descriptor.

d = descriptor(c,"Client Characteristic Configuration")

d = 
  Descriptor with properties:

          Name: "Client Characteristic Configuration"
          UUID: "2902"
    Attributes: ["Read"    "Write"]

This descriptor is both readable and writable.

Read and Write Descriptor Data

The "Client Characteristic Configuration" descriptor contains information about whether notification or indication is enabled or disabled. You can use read to get the current data.

data = read(d)

data = 1×2

     0     0

Interpret this data by referring to the specification for this descriptor found in the Bluetooth Core Specification found on the Bluetooth SIG website.

This value changes when the notification or indication status changes. For example, write to this value to enable notification for the "Heart Rate Measurement" characteristic using write. Then, observe the change in values by reading the descriptor again.

write(d,[1 0])
data = read(d)

data = 1×2

     1     0