write

Write data to a characteristic or descriptor on a Bluetooth Low Energy peripheral device

Since R2019b

Syntax

write(c,data)

write(c,data,type)

write(c,data,precision)

write(c,data,precision,type)

write(d,data)

write(d,data,precision)

Description

Write Characteristic Values

write(c,data) writes the specified data to a characteristic of a Bluetooth^® Low Energy peripheral device. The Attributes property of the input characteristic object c must be "Write" and/or "WriteWithoutResponse".

write(c,data,type) specifies whether the device expects a response back using type.

write(c,data,precision) specifies the precision of the data written.

write(c,data,precision,type) specifies both the response type and the data precision.

Write Descriptor Values

write(d,data) writes the specified data to a descriptor of a Bluetooth Low Energy peripheral device. The descriptor d must have "Write" in its Attributes property.

write(d,data,precision) specifies the precision of the data written.

Examples

Write to a Characteristic on a Bluetooth Low Energy Peripheral Device

Write data to a characteristic on a Bluetooth Low Energy Peripheral Device.

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

b = ble("DemoDevice")

b = 
  ble with properties:

               Name: "DemoDevice"
            Address: "5A0B858BC07C"
          Connected: 1
           Services: [5×2 table]
    Characteristics: [12×5 table]

Show services and characteristics

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

c = characteristic(b,"User Data","Gender")

c = 
  Characteristic with properties:

             Name: "Gender"
             UUID: "2A8C"
       Attributes: "Read" "Write"
      Descriptors: []

Because this characteristic is readable and writable, you can write data to it and verify the change in values. Use read to get the latest data.

data = read(c)

data = 0

Interpret the data by referring to the specification for this characteristic found in the User Data Service on the Bluetooth SIG website. 0 represents male and 1 represents female. Write 1 to the characteristic to indicate female.

write(c,1)

You can read from the characteristic again to observe the change in the data.

data = read(c)

data = 1

Write to a Descriptor on a Bluetooth Low Energy Peripheral Device

Write data to a descriptor on a Bluetooth Low Energy Peripheral Device.

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 or 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, write to this value to enable notification for the "Heart Rate Measurement" characteristic. Then, observe the change in values by reading the descriptor again.

write(d,[1 0])
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.

data — Data to write

numeric

Data to write to the characteristic or descriptor, specified as a scalar or an array of numbers. Refer to your characteristic or descriptor specifications on the Bluetooth SIG website to determine what kind of data to write.

Example: write(c,[1 0]) writes an array of numbers to the characteristic c.

Data Types: double | uint8 | uint16 | uint32 | uint64

type — Response option type

"withresponse" | "withoutresponse"

Response option type for the characteristic, specified as "withresponse" or "withoutresponse". If you specify "withresponse", the peripheral device expects a response from the device indicating that the write is successful. If you specify "withoutresponse", the peripheral device expects no response. The default value depends on the Attributes property of the characteristic.

c.Attributes	Default type
"Write"	"withresponse"
"WriteWithoutResponse"	"withoutresponse"
"Write" and "WriteWithoutResponse"	"withresponse"

Example: write(c,5,"withoutresponse") writes data to the characteristic without receiving a response back.

precision — Data precision

"uint8" (default) | "uint16" | "uint32" | "uint64"

Data precision, specified as "uint8", "uint16", "uint32", or "uint64".

Example: write(d,300,"uint16") writes data to the characteristic as an unsigned 16-bit integer.

d — Descriptor of Bluetooth Low Energy peripheral device

descriptor object

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

Version History

Introduced in R2019b