Main Content

Transition Your Code to serialport Interface

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

serial Interfaceserialport InterfaceExample
seriallistserialportlistDiscover Serial Port Devices
instrfind and instrfindallserialportfindFind Existing Serial Port Connections
serial and fopenserialportConnect to Serial Port Device
fwritewrite Read and Write
freadread
fprintfwritelineSend a Command
fscanfreadlineRead a Terminated String
fgetl
fgets
flushinput and flushoutputflushFlush Data from Memory
TerminatorconfigureTerminatorSet Terminator
BytesAvailableFcnCount, BytesAvailableFcnMode, BytesAvailableFcn, and BytesAvailableconfigureCallback and NumBytesAvailableSet Up a Callback Function
PinStatusgetpinstatusRead Serial Pin Status
DataTerminalReady and RequestToSendsetDTR and setRTSSet Serial DTR and RTS Pin States
ErrorFcnErrorOccurredFcn 
fcloseclear and deleteDisconnect 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.

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

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

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

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.

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

For more information, see readline.

Flush Data from Memory

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

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

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

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

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

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

See Also

| | (Instrument Control Toolbox) |

Related Topics