Main Content

Transition Your Code to serialport Interface

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

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, Status, and Tag properties will be removed.

Discover Serial Port Devices

seriallist will be removed. Use serialportlist instead.

Connect to Serial Port Device

This example shows how to connect to a serial port device and disconnect from it using the recommended functionality.

FunctionalityUse This Instead
s = serial("COM1");
s.BaudRate = 115200;
fopen(s)
s = serialport("COM1",115200);
fclose(s)
delete(s)
clear s
clear s

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.

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

Write Data with the Binary Block Protocol

This example shows how to write data with the IEEE standard binary block protocol using the recommended functionality.

FunctionalityUse This Instead
% s is a serial object
waveform = sin(2*pi*60*0:.16:60);
fprintf(s,"WLIS:WAV:DATA")
binblockwrite(s,waveform,"double")
% s is a serialport object
waveform = sin(2*pi*60*0:.16:60);
writeline(s,"WLIS:WAV:DATA")
writebinblock(s,waveform,"double")

For more information, see writebinblock.

Read Data with the Binary Block Protocol

This example uses a loopback device to show how to read data with the IEEE standard binary block protocol using the recommended functionality.

FunctionalityUse This Instead
% s is a serial object
fprintf(s,"CURVe?")
data = binblockread(s,"double")
data =

     1
     2
     3
     4
     5
% s is a serialport object
writeline(s,"CURVe?")
data = readbinblock(s,"double")
data =

     1     2     3     4     5

For more information, see readbinblock.

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

|