characteristic - Access a characteristic on Bluetooth Low Energy peripheral device - MATLAB (original) (raw)

Access a characteristic on Bluetooth Low Energy peripheral device

Description

A characteristic object represents a characteristic of a Bluetooth® Low Energy peripheral device. If read or write are supported in the object[Attributes](matlabshared.blelib.characteristic.html#mw%5Fcee8631e-5668-476a-8f18-9798f7a0da54) property, you can read characteristic values usingread or you can write characteristic values using write. If the characteristic has any descriptors, you can also access them using descriptor.

Creation

Syntax

Description

`c` = characteristic([b](#mw%5F50b3e63e-9f58-4ba0-853c-f60f87c00313),[serviceName](#mw%5F6d4ce31d-a643-46dd-ba38-8058e58ba2aa),[characteristicName](#mw%5F1fc83ac7-380a-4dea-8a16-0597d7aac5f5)) creates an object that represents a characteristic on the peripheral deviceb using the service name and characteristic name. IdentifyserviceName and characteristicName by viewing the Characteristics property of the ble objectb.

example

`c` = characteristic([b](#mw%5F50b3e63e-9f58-4ba0-853c-f60f87c00313),[serviceUUID](#mw%5F2b337cce-17c2-4e27-8e35-c6c681edac53),[characteristicUUID](#mw%5Fee1b83cb-6442-418b-a468-c7ebf3b8a987)) creates an object for a characteristic using its UUID and the service UUID. IdentifyserviceUUID and characteristicUUID by viewing the Characteristics property of the ble objectb.

example

Input Arguments

expand all

b — Bluetooth Low Energy peripheral device connection

ble object

Bluetooth Low Energy peripheral device connection, specified as a ble object.

serviceName — Service name

character vector | string scalar

Service name of the characteristic, specified as a character vector or string scalar. Identify serviceName in theCharacteristics table of the ble object that represents your peripheral device. The ServiceName column lists the valid values.

For a full list of standard services and how to interpret them, see the Bluetooth SIG website. All custom services in theCharacteristics table have the name "Custom" and are differentiated by their UUID values. If the service name is"Custom", then use the service UUID to access it.

Example: c = characteristic(b,"Current Time Service","Current Time") creates an object that represents the "Current Time" characteristic on the "Current Time Service".

Data Types: char | string

characteristicName — Characteristic name

character vector | string scalar

Characteristic name, specified as a character vector or string scalar. IdentifycharacteristicName in the Characteristics table of the ble object that represents your peripheral device. TheCharacteristicName column lists the valid values.

For a full list of standard characteristics and how to interpret them, see theBluetooth SIG website. All custom characteristics in theCharacteristics table have the name "Custom" and are differentiated by their UUID values. If the characteristic name is"Custom", then use the characteristic UUID to access it.

Example: c = characteristic(b,"Current Time Service","Current Time") creates an object that represents the "Current Time" characteristic on the "Current Time Service".

Data Types: char | string

serviceUUID — Service UUID

character vector | string scalar

Service UUID of the characteristic, specified as a character vector or string scalar. Identify serviceUUID in theCharacteristics table of the ble object that represents your peripheral device. The ServiceUUID column lists the valid values.

For a full list of standard services and how to interpret them, see the Bluetooth SIG website. If the service name is"Custom", then use the service UUID to access it.

Example: c = characteristic(b,"1805","2A2B") creates an object that represents the characteristic with UUID "2A2B" on the service with UUID "1805".

Data Types: char | string

characteristicUUID — Characteristic UUID

character vector | string scalar

Characteristic UUID, specified as a character vector or scalar string. IdentifycharacteristicUUID in the Characteristics table of the ble object that represents your peripheral device. Valid values are those listed under theCharacteristicUUID column.

For a full list of standard characteristics and how to interpret them, see theBluetooth SIG website. If the characteristic name is"Custom", then use the characteristic UUID to access it.

Example: c = characteristic(b,"1805","2A2B") creates an object that represents the characteristic with UUID "2A2B" on the service with UUID "1805".

Data Types: char | string

Properties

expand all

Name — Characteristic name

string scalar

This property is read-only.

Characteristic name, returned as a string scalar.

Data Types: string

UUID — Characteristic UUID

string scalar

This property is read-only.

Characteristic UUID, returned as a string scalar. This value is specific to each characteristic.

Data Types: string

Attributes — Characteristic attributes

string array

This property is read-only.

Characteristic attributes, returned as a string array. The value of this property determines the behavior of the read,write,subscribe, and unsubscribe functions. Possible values follow.

Data Types: string

DataAvailableFcn — Data available function

function handle

Data available function, returned as a function handle. This property is an empty array until you assign a function handle. Use this property for characteristics that support notification and/or indication.

For an example showing how to assign a callback to this property, see Read Characteristic Data from a Bluetooth Low Energy Peripheral Device Using a Callback Function.

Example:

Write a function displayHeartRate that reads and displays data from a characteristic, create a handle, and assign the handle to this property.

c.DataAvailableFcn = @displayHeartRate;

The function is called whenever a new notification or indication is received. Stop notification or indication using unsubscribe.

Data Types: function_handle

Descriptors — Characteristic descriptors

table

Characteristic descriptors, returned as a table. To access a specific descriptor listed in the table, create an object using descriptor. The table contains the following columns.

Data Types: table

Object Functions

Examples

collapse all

Access a Characteristic on a Bluetooth Low Energy Peripheral Device

Connect 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

List the available characteristics on this device.

ans=10×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"    ]}
"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 list shows all characteristics and their respective services. Some services have multiple characteristics. The list also shows the attributes for each characteristic.

Create a characteristic object that represents the "Battery Level" characteristic.

c = characteristic(b,"Battery Service","Battery Level")

c = Characteristic with properties:

         Name: "Battery Level"
         UUID: "2A19"
   Attributes: "Read"
  Descriptors: []

Alternatively, you can use the UUIDs instead of the names to create the object.

c = characteristic(b,"180F","2A19")

c = Characteristic with properties:

         Name: "Battery Level"
         UUID: "2A19"
   Attributes: "Read"
  Descriptors: []

This object represents the "Battery Level" characteristic. Since it has the Read attribute, you can use read to get the characteristic value.

Version History

Introduced in R2019b