Main Content

bluetooth

Connect to Bluetooth Classic device

Since R2020b

expand all in page

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.

example

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

expand all

Object Creation Properties

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

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

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

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

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

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

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 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

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

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

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

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

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

readRead data from Bluetooth device
readlineRead line of ASCII string data from Bluetooth device
writeWrite data to Bluetooth device
writelineWrite line of ASCII data to Bluetooth device
configureTerminatorSet terminator for ASCII string communication with Bluetooth device
configureCallbackSet callback function and trigger condition for communication with Bluetooth device
flushClear Bluetooth device buffers

Examples

collapse all

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

See Also