Transition Your Code to serialport Interface

Transition Your Code to `serialport` Interface

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

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

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.

Functionality	Use 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.

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.

Documentation