Transition Your Code to serialport Interface

Transition Your Code to `serialport` Interface

The serial function, its object functions, and its properties will be removed. Use serialport instead.

`serial` Interface	`serialport` Interface	Example
`seriallist`	`serialportlist`	Discover Serial Port Devices
`instrfind` and `instrfindall`	`serialportfind`	Find Existing Serial Port Connections
`serial` and `fopen`	`serialport`	Connect to Serial Port Device
`fwrite`	`write`	Read and Write
`fread`	`read`	Read and Write
`fprintf`	`writeline`	Send a Command
`fscanf`	`readline`	Read a Terminated String
`fgetl`
`fgets`
`flushinput` and `flushoutput`	`flush`	Flush Data from Memory
`Terminator`	`configureTerminator`	Set Terminator
`BytesAvailableFcnCount`, `BytesAvailableFcnMode`, `BytesAvailableFcn`, and `BytesAvailable`	`configureCallback` and NumBytesAvailable	Set Up a Callback Function
`PinStatus`	`getpinstatus`	Read Serial Pin Status
`DataTerminalReady` and `RequestToSend`	`setDTR` and `setRTS`	Set Serial DTR and RTS Pin States
`ErrorFcn`	ErrorOccurredFcn
`fclose`	`clear` and `delete`	Disconnect Serial Port Connections

Removed Functionality

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 BreakInterruptFcn, OutputEmptyFcn, and PinStatusFcn properties will be removed. You can set callback functions using configureCallback in the updated interface, but not for these properties.

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

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

The Name, Type, ObjectVisibility, and Status properties will be removed.

Discover Serial Port Devices

seriallist will be removed. Use serialportlist instead.

Find Existing Serial Port Connections

instrfind and instrfindall will be removed. Use serialportfind instead. (since R2024a)

Connect to Serial Port Device

This table shows how to connect to a serial port device using the recommended functionality.

Functionality	Use This Instead
s = serial("COM1"); s.BaudRate = 115200; fopen(s)	s = serialport("COM1",115200);

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

For more information, see serialport.

Read and Write

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

Functionality	Use This Instead
% s is a serial object fwrite(s,1:5,"uint32") data = fread(s,5,"uint32") data = 1 2 3 4 5	% s is a serialport object write(s,1:5,"uint32") data = read(s,5,"uint32") data = 1 2 3 4 5
% s is a serial object command = "start"; fwrite(s,command,"char")	% s is a serialport object command = "start"; write(s,command,"char")
	% s is a serialport object command = "start"; write(s,command,"string")
% s is a serial object length = 5; resp = fread(s,length,"char") resp = 115 116 97 114 116 resp = char(resp)' resp = 'start'	% s is a serialport object length = 5; resp = read(s,length,"string") resp = "start"

For more information, see write or read.

Send a Command

This example shows how to write a terminated SCPI command using the recommended functionality.

Functionality Use This Instead

Functionality	Use This Instead
% s is a serial object s.Terminator = "CR/LF" channel = 1; level = 3.44; fprintf(s,"TRIGGER%d:LEVEL2 %1.2f",[channel,level]);	% s is a serialport object configureTerminator(s,"CR/LF") channel = 1; level = 3.44; cmd = sprintf("TRIGGER%d:LEVEL2 %1.2f",[channel,level]); writeline(s,cmd) `writeline` automatically appends the write terminator.

% s is a serial object
s.Terminator = "CR/LF"
channel = 1;
level = 3.44;
fprintf(s,"TRIGGER%d:LEVEL2 %1.2f",[channel,level]);

% s is a serialport object
configureTerminator(s,"CR/LF")
channel = 1;
level = 3.44;
cmd = sprintf("TRIGGER%d:LEVEL2 %1.2f",[channel,level]);
writeline(s,cmd)

writeline automatically appends the write terminator.

For more information, see configureTerminator or writeline.

Read a Terminated String

This example shows how to perform a terminated string read using the recommended functionality.

Functionality Use This Instead

Functionality	Use This Instead
% s is a serial object fprintf(s,"MEASUREMENT:IMMED:TYPE PK2PK") a = fscanf(s,"%e",6) a = 2.0200 For the format specifier `"%e"`, `fscanf` returns the terminator and the user must remove it from the string.	% s is a serialport object writeline(s,"MEASUREMENT:IMMED:TYPE PK2PK") a = readline(s) a = "2.0200" sscanf(a,"%e") a = 2.0200
% s is a serial object fprintf(s,"*IDN?") a = fgetl(s) a = 'TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16' `fgetl` reads until the specified terminator is reached and then discards the terminator.	% s is a serialport object writeline(s,"*IDN?") a = readline(s) a = "TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04" `readline` reads until the specified terminator is reached and then discards the terminator. There is no option to include the terminator.
% s is a serial object fprintf(s,"*IDN?") a = fgets(s) a = 'TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04 ' `fgets` reads until the specified terminator is reached and then returns the terminator.

% s is a serial object
fprintf(s,"MEASUREMENT:IMMED:TYPE PK2PK")
a = fscanf(s,"%e",6)

a =

    2.0200

For the format specifier "%e", fscanf returns the terminator and the user must remove it from the string.

% s is a serialport object
writeline(s,"MEASUREMENT:IMMED:TYPE PK2PK")
a = readline(s)

a = 

    "2.0200"

sscanf(a,"%e")

a =

    2.0200

% s is a serial object
fprintf(s,"*IDN?")
a = fgetl(s)

a =

    'TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16'

fgetl reads until the specified terminator is reached and then discards the terminator.

% s is a serialport object
writeline(s,"*IDN?")
a = readline(s)

a = 

    "TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04"

readline reads until the specified terminator is reached and then discards the terminator. There is no option to include the terminator.

% s is a serial object
fprintf(s,"*IDN?")
a = fgets(s)

a =

    'TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04
     '

fgets reads until the specified terminator is reached and then returns the terminator.

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
% s is a serial object flushinput(s)	% s is a serialport object flush(s,"input")
% s is a serial object flushoutput(s)	% s is a serialport object flush(s,"output")
% s is a serial object flushinput(s) flushoutput(s)	% s is a serialport object flush(s)

Functionality

Use This Instead

% s is a serial object
flushinput(s)

% s is a serialport object
flush(s,"input")

% s is a serial object
flushoutput(s)

% s is a serialport object
flush(s,"output")

% s is a serial object
flushinput(s)
flushoutput(s)

% s is a serialport object
flush(s)

For more information, see flush.

Set Terminator

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

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

Functionality

Use This Instead

% s is a serial object
s.Terminator = "CR/LF";

% s is a serialport object
configureTerminator(s,"CR/LF")

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

% s is a serialport object
configureTerminator(s,"CR/LF",10)

For more information, see configureTerminator.

Set Up a 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
s = serial("COM5","BaudRate",115200) s.BytesAvailableFcnCount = 5 s.BytesAvailableFcnMode = "byte" s.BytesAvailableFcn = @instrcallback fopen(s) function instrcallback(src,evt) data = fread(src,src.BytesAvailable) disp(evt) disp(evt.Data) end data = 1 2 3 4 5 Type: 'BytesAvailable' Data: [1×1 struct] AbsTime: [2019 5 2 16 35 9.6710]	s = serialport("COM5",115200) configureCallback(s,"byte",5,@instrcallback); function instrcallback(src,evt) data = read(src,src.NumBytesAvailable,"uint8") disp(evt) end data = 1 2 3 4 5 DataAvailableInfo with properties: BytesAvailableFcnCount: 5 AbsTime: 02-May-2019 15:54:09

Functionality

Use This Instead

s = serial("COM5","BaudRate",115200)
s.BytesAvailableFcnCount = 5
s.BytesAvailableFcnMode = "byte"
s.BytesAvailableFcn = @instrcallback

fopen(s)

function instrcallback(src,evt)
   data = fread(src,src.BytesAvailable)
   disp(evt)
   disp(evt.Data)
end

data =

     1
     2
     3
     4
     5

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

    AbsTime: [2019 5 2 16 35 9.6710]

s = serialport("COM5",115200)
configureCallback(s,"byte",5,@instrcallback);

function instrcallback(src,evt)
   data = read(src,src.NumBytesAvailable,"uint8")
   disp(evt)
end

data =

     1     2     3     4     5

  DataAvailableInfo with properties:

    BytesAvailableFcnCount: 5
                   AbsTime: 02-May-2019 15:54:09

For more information, see configureCallback.

Read Serial Pin Status

This example shows how to read serial pin status using the recommended functionality.

Functionality	Use This Instead
% s is a serial object s.PinStatus ans = struct with fields: CarrierDetect: 'on' ClearToSend: 'on' DataSetReady: 'on' RingIndicator: 'on'	% s is a serialport object status = getpinstatus(s) status = struct with fields: ClearToSend: 1 DataSetReady: 1 CarrierDetect: 1 RingIndicator: 1

Functionality

Use This Instead

% s is a serial object
s.PinStatus

ans = 

  struct with fields:

    CarrierDetect: 'on'
      ClearToSend: 'on'
     DataSetReady: 'on'
    RingIndicator: 'on'

% s is a serialport object
status = getpinstatus(s)

status = 

  struct with fields:

      ClearToSend: 1
     DataSetReady: 1
    CarrierDetect: 1
    RingIndicator: 1

For more information, see getpinstatus.

Set Serial DTR and RTS Pin States

This example shows how to set serial DTR and RTS pin states using the recommended functionality.

Functionality	Use This Instead
% s is a serial object s.DataTerminalReady = "on";	% s is a serialport object setDTR(s,true)
% s is a serial object s.RequestToSend = "off";	% s is a serialport object setRTS(s,false)

For more information, see setDTR or setRTS.

Disconnect Serial Port Connections

The fclose function is not available in the updated interface. To disconnect serial port connections, use clear or delete instead, depending upon whether you are working in a single workspace or multiple workspaces. For details, see the following examples on the serialport reference page: