read
Read characteristic or descriptor data on a Bluetooth Low Energy peripheral device
Syntax
Description
Read Characteristic Values
reads the characteristic value from a Bluetooth® Low Energy peripheral device. The data read depends on the
characteristicData
= read(c
)Attributes
property of the input characteristic object
c
. For more information about all the possible behaviors of
read
, see characteristicData
.
specifies characteristicData
= read(c
,mode
)mode
as the read mode.
[
reads the timestamp for any of the previous syntaxes.characteristicData
,timestamp
] = read(___)
Read Descriptor Values
reads the descriptor value from a Bluetooth Low Energy peripheral device.descriptorData
= read(d
)
Examples
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("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
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("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)
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("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
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 object
d
.
Output Arguments
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.
c.Attributes | read(c) or read(c,'latest') | read(c,'oldest') |
---|---|---|
| Current data. | Not supported. |
| Latest notification or indication data.
| Oldest notification or indication data since last read.
|
|
|
|
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
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)