Main Content

read

Read characteristic or descriptor data on a Bluetooth Low Energy peripheral device

collapse all in page

Syntax

characteristicData = read(c)
characteristicData = read(c,mode)
[characteristicData,timestamp] = read(___)
descriptorData = read(d)

Description

Read Characteristic Values

characteristicData = read(c) reads the characteristic value from a Bluetooth® Low Energy peripheral device. The data read depends on the Attributes property of the input characteristic object c. For more information about all the possible behaviors of read, see characteristicData.

example

characteristicData = read(c,mode) specifies mode as the read mode.

example

[characteristicData,timestamp] = read(___) reads the timestamp for any of the previous syntaxes.

example

Read Descriptor Values

descriptorData = read(d) reads the descriptor value from a Bluetooth Low Energy peripheral device.

example

Examples

collapse all

Open Live Script

Access a characteristic on your peripheral device and read its data.

Create a connection to a nearby Bluetooth Low Energy peripheral device.

b = ble("Thingy")
b = 
  ble with properties:

               Name: "Thingy"
            Address: "F2DF635320F6"
          Connected: 1
           Services: [9×2 table]
    Characteristics: [38×5 table]

Show services and characteristics

Create a characteristic object that represents the "Temperature" characteristic.

c = characteristic(b,"Weather Station Service","Temperature")
c = 
  Characteristic with properties:

             Name: "Temperature"
             UUID: "EF680201-9B35-4933-9B10-52FFA9740042"
       Attributes: "Notify"
      Descriptors: [1x3 table]
 DataAvailableFcn: []

Show descriptors

Because this characteristic supports "Notify", you can use read to get the latest data.

data = read(c)
data = 1×2

    23    75

You can also return the timestamp of the latest data.

[data,timestamp] = read(c)
data = 1×2

    23    73


timestamp = datetime
   16-May-2019 16:20:00

Interpret the data in Celsius. The first byte represents the integer part of the temperature and the second byte represents the decimal part with a resolution of 0.01.

temperature = data(1) + data(2)*0.01
temperature = 23.7300
Open Live Script

Access a characteristic on your peripheral device and create a callback function to read its data.

Create a connection to a nearby Bluetooth Low Energy peripheral device.

b = ble("Thingy")
b = 
  ble with properties:

               Name: "Thingy"
            Address: "F2DF635320F6"
          Connected: 1
           Services: [9×2 table]
    Characteristics: [38×5 table]

Show services and characteristics

Create a characteristic object that represents the "Temperature" characteristic.

c = characteristic(b,"Weather Station Service","Temperature")
c = 
  Characteristic with properties:

             Name: "Temperature"
             UUID: "EF680201-9B35-4933-9B10-52FFA9740042"
       Attributes: "Notify"
      Descriptors: [1x3 table]
 DataAvailableFcn: []

Show descriptors

Because this characteristic supports "Notify", you can create a callback function. Name the function displayCharacteristicData and define it as follows. Specify the read mode as 'oldest' instead of 'latest'. Calling the 'latest' data may 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 data appears in your command window.

c.DataAvailableFcn = @displayCharacteristicData
c = 
  Characteristic with properties:

             Name: "Temperature"
             UUID: "EF680201-9B35-4933-9B10-52FFA9740042"
       Attributes: "Notify"
      Descriptors: [1x3 table]
 DataAvailableFcn: displayCharacteristicData

Show descriptors

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

unsubscribe(c)
Open Live Script

Access a descriptor on your peripheral device and read its data.

Create a connection to a nearby Bluetooth Low Energy peripheral device.

b = ble("DemoDev")
b = 
  ble with properties:

               Name: "DemoDev"
            Address: "FF548EA5658F"
          Connected: 1
           Services: [5×2 table]
    Characteristics: [10×5 table]

Show services and characteristics

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

Create a descriptor object that represents 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 contains information about whether notification and indication are 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 on the Bluetooth SIG website.

This value changes when the notification or indication status changes. For example, subscribe to notification using subscribe. Then, observe the change in the value by reading the descriptor again.

subscribe(c,'notification');
data = read(d)
data = 1×2

     1     0

Input Arguments

collapse all

Characteristic of Bluetooth Low Energy peripheral device, specified as a characteristic object.

The Attributes property of the characteristic object must include "Read", "Notify", or "Indicate" to read data.

Example: data = read(c) reads the value of the characteristic object c.

Read mode, specified as 'latest' or 'oldest'. Using 'latest' returns the most recent data and flushes the previous data. Using 'oldest' returns the oldest data since the last read.

Note

Use 'oldest' inside the DataAvailableFcn callback function to avoid errors caused by the flushing of previous data.

Example: data = read(c,'oldest') reads the oldest value since the last read on the characteristic object c.

Data Types: char | string

Descriptor of Bluetooth Low Energy peripheral device, specified as a descriptor object.

The Attributes property of the descriptor object must include "Read" to read data.

Example: read(d) reads the value of the descriptor object d.

Output Arguments

collapse all

Characteristic data from peripheral device, returned as a number or array of numbers.

The data read depends on the Attributes property of the characteristic object and the specified read mode.

c.Attributesread(c) or read(c,'latest')read(c,'oldest')

  • "Read"

Current data.Not supported.

  • "Notify", "Indicate", or both

Latest notification or indication data.

  • If notification or indication is not enabled and this is the first time calling read, then notification or indication automatically starts.

  • Previous data is flushed.

Oldest notification or indication data since last read.

  • If notification or indication is not enabled and this is the first time calling read, then notification or indication automatically starts.

  • "Read"

    and

  • "Notify", "Indicate", or both

  • If notification or indication is not enabled, then characteristicData is current data.

  • If notification or indication is enabled, then characteristicData is the latest notification or indication.

  • If notification or indication is not enabled, then read(c,'oldest') is not supported.

  • If notification or indication is enabled, then characteristicData is the oldest notification or indication data since the last read and previous data is flushed.

Data Types: double

Timestamp indicating the receipt of characteristic or descriptor data on the computer, returned as a datetime array.

Data Types: datetime

Descriptor data from peripheral device, returned as a number.

Data Types: double

Version History

Introduced in R2019b

See Also

| | | |

Topics