characteristic

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 property, you can read characteristic values using read or you can write characteristic values using write. If the characteristic has any descriptors, you can also access them using descriptor.

Creation

Syntax

c = characteristic(b,serviceName,characteristicName)

c = characteristic(b,serviceUUID,characteristicUUID)

Description

c = characteristic(b,serviceName,characteristicName) creates an object that represents a characteristic on the peripheral device b using the service name and characteristic name. Identify serviceName and characteristicName by viewing the Characteristics property of the ble object b.

c = characteristic(b,serviceUUID,characteristicUUID) creates an object for a characteristic using its UUID and the service UUID. Identify serviceUUID and characteristicUUID by viewing the Characteristics property of the ble object b.

Input Arguments

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 the Characteristics 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 the Characteristics 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. Identify characteristicName in the Characteristics table of the ble object that represents your peripheral device. The CharacteristicName column lists the valid values.

For a full list of standard characteristics and how to interpret them, see the Bluetooth SIG website. All custom characteristics in the Characteristics 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 the Characteristics 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. Identify characteristicUUID in the Characteristics table of the ble object that represents your peripheral device. Valid values are those listed under the CharacteristicUUID column.

For a full list of standard characteristics and how to interpret them, see the Bluetooth 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

Name — Characteristic name

Read-only: string scalar

This property is read-only.

Characteristic name, returned as a string scalar.

Data Types: string

UUID — Characteristic UUID

Read-only: 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

Read-only: 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.

Value	Description
"Read"	Characteristic is readable
"Write"	Characteristic is writable
"WriteWithoutResponse"	Characteristic is writable with unacknowledged packets
"AuthenticatedSignedWrites"	Characteristic supports signed writes
"Notify"	Characteristic supports notification
"Indicate"	Characteristic supports indication
"Broadcast"	Characteristic supports broadcasting with advertising packets
"ExtendedProperties"	Characteristic contains ExtendedProperties descriptor with additional attributes
"NotifyEncryptionRequired" (macOS only)	Characteristic supports notification only from trusted devices
"IndicateEncryptionRequired" (macOS only)	Characteristic supports indication only from trusted devices

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.

Column	Description
DescriptorName	Name of descriptor, returned as a string
DescriptorUUID	UUID of descriptor, returned as a string
Attributes	Read or write permissions on descriptor, returned as a cell array

Data Types: table

Object Functions

read	Read characteristic or descriptor data on a Bluetooth Low Energy peripheral device
write	Write data to a characteristic or descriptor on a Bluetooth Low Energy peripheral device
subscribe	Subscribe to characteristic notification or indication
unsubscribe	Unsubscribe from characteristic notification and indication
descriptor	Access a descriptor on Bluetooth Low Energy peripheral device

Examples

Access a Characteristic on a Bluetooth Low Energy Peripheral Device

Connect 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

List the available characteristics on this device.

b.Characteristics

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