bluetooth

Connect to Bluetooth Classic device

Since R2020b

Description

A bluetooth object represents a connection to a Bluetooth^® Classic device from your computer using Bluetooth Serial Port Profile (SPP). Identify nearby devices to connect to by the "Ready to connect" status in the bluetoothlist output. You must pair the device with your computer first before connecting to it from MATLAB^®.

Creation

Syntax

device = bluetooth

device = bluetooth(name)

device = bluetooth(name,channel)

device = bluetooth(address)

device = bluetooth(address,channel)

device = bluetooth(address,channel,Name,Value)

Description

device = bluetooth creates a connection to the last successfully connected Bluetooth Classic device.

device = bluetooth(name) creates a connection to a Bluetooth Classic device using its name. The channel is the default SPP channel 1. The input name sets the Name property.

device = bluetooth(name,channel) creates a connection to the specified SPP channel channel of a Bluetooth Classic device. The input channel sets the Channel property.

device = bluetooth(address) creates a connection to a Bluetooth Classic device using its address. The input address sets the Address property.

device = bluetooth(address,channel) creates a connection to the specified SPP channel channel of a Bluetooth Classic device.

device = bluetooth(address,channel,Name,Value) creates a connection and sets additional Properties using one or more name-value pair arguments. Set the ByteOrder and Timeout properties using name-value pair arguments. Enclose each property name in quotes, followed by the desired property value.

Example: device = bluetooth("23E16522A7C0",2,"ByteOrder","little-endian","Timeout",10) connects to a Bluetooth device with little-endian byte order and a timeout period of 10 seconds.

Properties

Object Creation Properties

Name — Bluetooth device name

character vector | string scalar

Bluetooth device name, specified as a character vector or string scalar. Identify the name of the device you want to connect to using the information returned by bluetoothlist. This property can be set only at object creation.

Example: device = bluetooth("CO2 Sensor") connects to the Bluetooth device named CO2 Sensor.

Data Types: char | string

Address — Bluetooth device address

character vector | string scalar

Bluetooth device address, specified as a character vector or string scalar. Identify the address of the device you want to connect to using the information returned by bluetoothlist. This property can be set only at object creation.

Example: device = bluetooth("23E16522A7C0"), device = bluetooth("23:E1:65:22:A7:C0"), and device = bluetooth("23-E1-65-22-A7-C0") all connect to the Bluetooth device with the address 23E16522A7C0.

Data Types: char | string

Channel — Bluetooth device channel

1 (default) | numeric

Bluetooth device channel, specified as a positive number. Identify the channel of the device you want to connect to using the information returned by bluetoothlist. This property can be set only at object creation.

Example: device = bluetooth("CO2 Sensor",2) connects to channel 2 on the CO2 Sensor.

Data Types: double

ByteOrder — Sequential order of bytes

"little-endian" (default) | "big-endian"

Sequential order in which bytes are arranged into larger numerical values, specified as "little-endian" or "big-endian". Set this property at object creation using a name-value pair argument. You can also change it after object creation using dot notation.

Example: device = bluetooth("23E16522A7C0",2,"ByteOrder","little-endian") and device.ByteOrder = "little-endian" set the byte order to little-endian.

Data Types: char | string

Timeout — Allowed time to complete operations

10 (default) | numeric

Allowed time in seconds to complete read and write operations, specified as a numeric value. Set this property at object creation using a name-value pair argument. You can also change it after object creation using dot notation.

Example: device.Timeout = 60 sets the timeout period to 60 seconds.

Data Types: double

Read and Write Properties

NumBytesAvailable — Number of bytes available to read

numeric

This property is read-only.

Number of bytes available to read, returned as a numeric value.

Example: device.NumBytesAvailable returns the number of bytes available to read.

Data Types: double

NumBytesWritten — Total number of bytes written to device

numeric

This property is read-only.

Total number of bytes written to the device, returned as a numeric value.

Example: device.NumBytesWritten returns the number of bytes written.

Data Types: double

Terminator — Terminator character for data

"LF" (default) | "CR" | "CR/LF" | 0 to 255

Terminator character for reading and writing ASCII-terminated data, returned as "LF", "CR", or "CR/LF", or a number from 0 to 255, inclusive. If the read and write terminators are different, Terminator is returned as a 1x2 cell array of these values. Set this property with the configureTerminator function.

Example: configureTerminator(device,"CR") sets both the read and write terminators to CR.

Example: configureTerminator(device,"CR",10) sets the read terminator to CR and the write terminator to 10.

Data Types: double | char | string | cell

Callback Properties

BytesAvailableFcnMode — Bytes available callback trigger mode

"off" (default) | "byte" | "terminator"

Bytes available callback trigger mode, returned as "off", "byte", or "terminator". This setting determines if the callback is off, triggered by the number of bytes specified by BytesAvailableFcnCount, or triggered by the terminator specified by Terminator. Set this property with the configureCallback function.

Example: configureCallback(device,"byte",50,@callbackFcn) sets the callbackFcn callback to trigger each time 50 bytes of new data are available to be read.

Example: configureCallback(device,"terminator",@callbackFcn) sets the callbackFcn callback to trigger when a terminator is available to be read.

Example: configureCallback(device,"off") turns off callbacks.

Data Types: char | string

BytesAvailableFcnCount — Number of bytes of data to trigger callback

64 (default) | numeric

Number of bytes of data to trigger the callback specified by BytesAvailableFcn, returned as a double. This value is used only when the BytesAvailableFcnMode property is "byte". Set these properties with the configureCallback function.

Example: configureCallback(device,"byte",50,@callbackFcn) sets the callbackFcn callback to trigger each time 50 bytes of new data are available to be read.

Data Types: double

BytesAvailableFcn — Callback function triggered by bytes available event

function handle

Callback function triggered by a bytes available event, returned as a function handle. A bytes available event is generated by receiving a certain number of bytes or a terminator. This property is empty until you assign a function handle. Set this property with the configureCallback function.

Example: configureCallback(device,"byte",50,@callbackFcn) sets the callbackFcn callback to trigger each time 50 bytes of new data are available to be read.

Data Types: function_handle

ErrorOccurredFcn — Callback function triggered by error event

function handle

Callback function triggered by an error event, returned as a function handle. An error event is generated when an asynchronous read or write error occurs. This property is empty until you assign a function handle.

Example: device.ErrorOccurredFcn = @myErrorFcn

Data Types: function_handle

UserData — General purpose property for user data

any type

General purpose property for user data, returned as any MATLAB data type. For example, you can use this property to store data when an event is triggered from a callback function.

Example: device.UserData

Object Functions

read	Read data from Bluetooth device
readline	Read line of ASCII string data from Bluetooth device
write	Write data to Bluetooth device
writeline	Write line of ASCII data to Bluetooth device
configureTerminator	Set terminator for ASCII string communication with Bluetooth device
configureCallback	Set callback function and trigger condition for communication with Bluetooth device
flush	Clear Bluetooth device buffers

Examples

Connect to Bluetooth Classic Device Using Name

Search for and establish a connection to your Bluetooth Classic device.

Scan for nearby devices.

bluetoothlist

list=5×4 table
        Name            Address        Channel          Status      
    _____________    ______________    _______    __________________

    "Pixel 3"        "3C286DD533CA"    8          "Ready to connect"         
    "HC-06"          "98D331FB3B77"    1          "Requires pairing"
    "mjin-maci"      "A886DDA44062"    3          "Requires pairing"
    "DMTDevice"      "B0B448F47A4C"    Unknown    "Unknown"         

Create a connection to the Pixel 3 device at channel 8.

device = bluetooth("Pixel 3",8)

device = 
  bluetooth with properties:

                 Name: "Pixel 3"
              Address: "3C286DD533CA"
              Channel: 8
    NumBytesAvailable: 0
      NumBytesWritten: 0

  Show all properties

Version History

Introduced in R2020b