read - Read characteristic or descriptor data on a Bluetooth Low Energy peripheral device - MATLAB (original) (raw)

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

Syntax

Description

Read Characteristic Values

[characteristicData](#mw%5F5dd7df22-4730-45a6-8af0-de6abd8b0bec) = read([c](#mw%5Fcd732b7f-3cb6-4ac6-99b1-b2c784a5562d)) reads the characteristic value from a Bluetooth® Low Energy peripheral device. The data read depends on theAttributes property of the input characteristic objectc. For more information about all the possible behaviors ofread, see characteristicData.

example

[characteristicData](#mw%5F5dd7df22-4730-45a6-8af0-de6abd8b0bec) = read([c](#mw%5Fcd732b7f-3cb6-4ac6-99b1-b2c784a5562d),[mode](#mw%5F4bef2e5d-0695-4573-a713-dd8734d590d5)) specifies mode as the read mode.

example

[[characteristicData](#mw%5F5dd7df22-4730-45a6-8af0-de6abd8b0bec),[timestamp](#mw%5Ff103ecab-eb97-484d-95f4-5348b3677eb1)] = read(___) reads the timestamp for any of the previous syntaxes.

example

Read Descriptor Values

[descriptorData](#mw%5Fc4d2e810-7a5e-4b54-8981-c72c47942c95) = read([d](#mw%5F5f198cd8-852c-44a2-8980-beb15a8ff3ba)) reads the descriptor value from a Bluetooth Low Energy peripheral device.

example

Examples

collapse all

Read Characteristic Data from a Bluetooth Low Energy Peripheral Device

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

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

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.

You can also return the timestamp of the latest data.

[data,timestamp] = read(c)

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

Read Characteristic Data from a Bluetooth Low Energy Peripheral Device Using a Callback Function

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 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.

Read Descriptor Data from a Bluetooth Low Energy Peripheral Device

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

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

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.

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)

Input Arguments

collapse all

c — Characteristic of Bluetooth Low Energy peripheral device

characteristic object

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.

mode — Read mode

'latest' (default) | 'oldest'

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

d — Descriptor of Bluetooth Low Energy peripheral device

descriptor object

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 objectd.

Output Arguments

collapse all

characteristicData — Characteristic data

numeric

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.

Data Types: double

timestamp — Timestamp

datetime

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

Data Types: datetime

descriptorData — Descriptor data

numeric

Descriptor data from peripheral device, returned as a number.

Data Types: double

Version History

Introduced in R2019b