Transition Your Code to bluetooth Interface

Transition Your Code to `bluetooth` Interface

A new set of MATLAB^® functions and properties provides support for communicating with Bluetooth^® devices. The Bluetooth function, its object functions, and its properties will be removed. Use the bluetooth (case-sensitive) interface instead.

`Bluetooth` Interface	`bluetooth` Interface	Example
`instrhwinfo`	`bluetoothlist`	Discover Bluetooth Devices
`Bluetooth` and `fopen`	`bluetooth`	Connect to Bluetooth Device
`fwrite`	`write`	Write and Read
`fread`	`read`	Write and Read
`fprintf`	`writeline`	Send Command
`fprintf`	`writeline`	Write and Read Back Data
`fscanf`	`readline`	Read Terminated String
`fgetl`		Write and Read Back Data
`fgets`		Read and Parse String Data
`flushinput` and `flushoutput`	`flush`	Flush Data from Memory
`Terminator`	`configureTerminator`	Set Terminator
`BytesAvailableFcnCount`, `BytesAvailableFcnMode`, and `BytesAvailableFcn`	`configureCallback`	Set Up Callback Function
`BytesAvailable`	NumBytesAvailable
`RemoteName`	Name
`RemoteID`	Address
`ErrorFcn`	ErrorOccurredFcn

Removed Functionality

The binblockread and binblockwrite functions will be removed.

The ValuesReceived and ValuesSent properties will be removed. You can calculate the number of values sent using the NumBytesAvailable property and the data type of the data available. For example, if the NumBytesAvailable is 20 bytes of uint32 data, the number of values sent is five since each uint32 value is four bytes.

The readasync and stopasync functions and the ReadAsyncMode and TransferStatus properties will be removed. The updated interface reads data asynchronously.

The BytesToOutput, InputBufferSize, and OutputBufferSize properties will be removed. Buffer sizes are automatically managed and sized as needed.

The OutputEmptyFcn property is not available in the updated interface. You can set callback functions using configureCallback in the updated interface, but not for this property.

The RecordDetail, RecordMode, RecordName, and RecordStatus properties will be removed.

The TimerFcn and TimerPeriod properties will be removed. Use timer instead.

The Profile, ObjectVisibility, Status, and Tag properties will be removed.

Discover Bluetooth Devices

This example shows how to discover Bluetooth devices using the recommended functionality.

Functionality	Use This Instead
instrhwinfo('Bluetooth')	bluetoothlist

For more information, see bluetoothlist.

Connect to Bluetooth Device

These examples show how to connect to a Bluetooth device and disconnect from it using the recommended functionality.

Functionality	Use This Instead
b = Bluetooth('NXT',3) fopen(b)	b = bluetooth("NXT",3)
fclose(b) delete(b) clear b	clear b

The fopen function is not available in the updated interface. The object creation function bluetooth both creates the object and connects the object to the device.

The fclose function is not available in the updated interface. The clear function disconnects the object from the device when it removes the object from the workspace.

For more information, see bluetooth.

Write and Read

These examples use a loopback device to show how to perform a binary write and read, write nonterminated string data, and read fixed-length string data using the recommended functionality.

Functionality	Use This Instead
% b is a Bluetooth object fwrite(b,1:5) data = fread(b,5) data = 1 2 3 4 5	% b is a bluetooth object write(b,1:5) data = read(b,5) data = 1 2 3 4 5
% b is a Bluetooth object command = "start"; fwrite(b,command,"char")	% b is a bluetooth object command = "start"; write(b,command,"char")
	% b is a bluetooth object command = "start"; write(b,command,"string")
% b is a Bluetooth object length = 5; data = fread(b,length,"char") resp = 104 101 108 108 111 data = char(data)' resp = 'hello'	% b is a bluetooth object length = 5; data = read(b,length,"string") data = "hello"

For more information, see write or read.

Read Terminated String

These examples show how to perform a terminated string read using the recommended functionality.

Functionality	Use This Instead
% b is a Bluetooth object data = fscanf(b,"%e") data = 11.9000 For the format specifier `"%e"`, `fscanf` returns the terminator and the user must remove it from the string.	% b is a bluetooth object data = readline(b) data = "11.9" data = sscanf(data,"%e") data = 11.9000
% b is a Bluetooth object data = fgetl(b) data = 'hello' `fgetl` reads until the specified terminator is reached and then discards the terminator.	% b is a bluetooth object data = readline(b) data = "hello" `readline` reads until the specified terminator is reached and then discards the terminator. There is no option to include the terminator.
% b is a Bluetooth object data = fgets(b) data = 'hello ' `fgets` reads until the specified terminator is reached and then returns the terminator.

For more information, see readline.

Send Command

This example shows how to write terminated string data using the recommended functionality.

Functionality Use This Instead

Functionality	Use This Instead
% b is a Bluetooth object b.Terminator = "CR/LF" channel = 1; fprintf(b,"id is %d",channel);	% b is a bluetooth object configureTerminator(b,"CR/LF") channel = 1; str = sprintf("id is %d",channel); writeline(b,str) `writeline` automatically appends the write terminator.

% b is a Bluetooth object
b.Terminator = "CR/LF"
channel = 1;
fprintf(b,"id is %d",channel);

% b is a bluetooth object
configureTerminator(b,"CR/LF")
channel = 1;
str = sprintf("id is %d",channel);
writeline(b,str)

writeline automatically appends the write terminator.

For more information, see configureTerminator or writeline.

Write and Read Back Data

This example shows how to write text and read back data using the recommended functionality.

Functionality	Use This Instead
% b is a Bluetooth object data = query(b,'ctrlcmd') data = 'success'	% b is a bluetooth object writeline(b,"ctrlcmd") data = readline(b) data = "success"

For more information, see writeline or readline.

Read and Parse String Data

This example shows how to read and parse string data using the recommended functionality.

Functionality	Use This Instead
% b is a Bluetooth object data = scanstr(b,';') data = 3×1 cell array {'a'} {'b'} {'c'}	% b is a bluetooth object data = readline(b) data = "a;b;c" data = strsplit(data,";") data = 1×3 string array "a" "b" "c"

Functionality

Use This Instead

% b is a Bluetooth object
data = scanstr(b,';')

data =

  3×1 cell array

    {'a'}
    {'b'}
    {'c'}

% b is a bluetooth object
data = readline(b)

data = 

    "a;b;c"

data = strsplit(data,";")

data = 

  1×3 string array

    "a"    "b"    "c"

For more information, see readline.

Flush Data from Memory

This example shows how to flush data from the buffer using the recommended functionality.

Functionality	Use This Instead
% b is a Bluetooth object flushinput(b)	% b is a bluetooth object flush(b,"input")
% b is a Bluetooth object flushoutput(b)	% b is a bluetooth object flush(b,"output")
% b is a Bluetooth object flushinput(b) flushoutput(b)	% b is a bluetooth object flush(b)

Functionality

Use This Instead

% b is a Bluetooth object
flushinput(b)

% b is a bluetooth object
flush(b,"input")

% b is a Bluetooth object
flushoutput(b)

% b is a bluetooth object
flush(b,"output")

% b is a Bluetooth object
flushinput(b)
flushoutput(b)

% b is a bluetooth object
flush(b)

For more information, see flush.

Set Terminator

This example shows how to set the terminator using the recommended functionality.

Functionality	Use This Instead
% b is a Bluetooth object b.Terminator = "CR/LF";	% b is a bluetooth object configureTerminator(b,"CR/LF")
% b is a Bluetooth object b.Terminator = {"CR/LF" [10]};	% b is a bluetooth object configureTerminator(b,"CR/LF",10)

Functionality

Use This Instead

% b is a Bluetooth object
b.Terminator = "CR/LF";

% b is a bluetooth object
configureTerminator(b,"CR/LF")

% b is a Bluetooth object
b.Terminator = {"CR/LF" [10]};

% b is a bluetooth object
configureTerminator(b,"CR/LF",10)

For more information, see configureTerminator.

Set Up Callback Function

This example uses a loopback device to show how to set up a callback function using the recommended functionality.

Functionality	Use This Instead
% b is a Bluetooth object b.BytesAvailableFcnCount = 5 b.BytesAvailableFcnMode = "byte" b.BytesAvailableFcn = @mycallback function mycallback(src,evt) data = fread(src,src.BytesAvailableFcnCount); disp(evt) disp(evt.Data) end Type: 'BytesAvailable' Data: [1×1 struct] AbsTime: [2019 12 21 16 35 9.7032]	% b is a bluetooth object configureCallback(b,"byte",5,@mycallback); function mycallback(src,evt) data = read(src,src.BytesAvailableFcnCount); disp(evt) end ByteAvailableInfo with properties: BytesAvailableFcnCount: 5 AbsTime: 21-Dec-2019 12:23:01
% b is a Bluetooth object b.Terminator = "LF/CR" b.BytesAvailableFcnMode = "terminator" b.BytesAvailableFcn = @mycallback function mycallback(src,evt) data = fscanf(src,'%s'); disp(evt) disp(evt.Data) end Type: 'BytesAvailable' Data: [1×1 struct] AbsTime: [2019 12 21 16 35 9.7032]	% b is a bluetooth object configureTerminator(b,"LF/CR") configureCallback(b,"terminator",@mycallback); function mycallback(src,evt) data = readline(src); disp(evt) end TerminatorAvailableInfo with properties: AbsTime: 21-Dec-2019 12:23:01

Functionality

Use This Instead

% b is a Bluetooth object
b.BytesAvailableFcnCount = 5
b.BytesAvailableFcnMode = "byte"
b.BytesAvailableFcn = @mycallback

function mycallback(src,evt)
   data = fread(src,src.BytesAvailableFcnCount);
   disp(evt)
   disp(evt.Data)
end

    Type: 'BytesAvailable'
    Data: [1×1 struct]

    AbsTime: [2019 12 21 16 35 9.7032]

% b is a bluetooth object
configureCallback(b,"byte",5,@mycallback);

function mycallback(src,evt)
   data = read(src,src.BytesAvailableFcnCount);
   disp(evt)
end

  ByteAvailableInfo with properties:

    BytesAvailableFcnCount: 5
                   AbsTime: 21-Dec-2019 12:23:01

% b is a Bluetooth object
b.Terminator = "LF/CR"
b.BytesAvailableFcnMode = "terminator"
b.BytesAvailableFcn = @mycallback

function mycallback(src,evt)
   data = fscanf(src,'%s');
   disp(evt)
   disp(evt.Data)
end

    Type: 'BytesAvailable'
    Data: [1×1 struct]

    AbsTime: [2019 12 21 16 35 9.7032]

% b is a bluetooth object
configureTerminator(b,"LF/CR")
configureCallback(b,"terminator",@mycallback);

function mycallback(src,evt)
   data = readline(src);
   disp(evt)
end

  TerminatorAvailableInfo with properties:

                   AbsTime: 21-Dec-2019 12:23:01

For more information, see configureCallback.