Transition Your Code to serialport Interface

The serial function, its object functions, and its properties are not recommended. Use serialport instead.

serial Interfaceserialport InterfaceExample
seriallistserialportlistDiscover Serial Port Devices
serialserialportConnect to Serial Port Device
fwrite and freadwrite and readRead and Write
fprintfwritelineSend a Command
fscanf, fgetl, and fgetsreadlineRead a Terminated String
flushinput and flushoutputflushFlush Data from Memory
TerminatorconfigureTerminatorSet Terminator
BytesAvailableFcnCount, BytesAvailableFcnMode, BytesAvailableFcn, and BytesAvailableconfigureCallbackSet Up a Callback Function
PinStatusgetpinstatusRead Serial Pin Status
DataTerminalReady and RequestToSendsetDTR and setRTSSet Serial DTR and RTS Pin States

Discover Serial Port Devices

seriallist is not recommended. Use serialportlist instead.

Connect to Serial Port Device

This example 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);

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.

See Also

|