Write and Read Serial Port Data

Rules for Completing Write and Read Operations

Completing Write Operations

A write operation using write, writeline, or writebinblock completes when one of these conditions is satisfied:

The specified data is written.
The time specified by the Timeout property passes.

A text command is processed by the instrument only when it receives the required terminator. For serial port objects, each occurrence of \n in the ASCII command is replaced with the Terminator property value. The default value of Terminator is the line feed character. Refer to the documentation for your instrument to determine the terminator required by your instrument.

Completing Read Operations

A read operation with read, readline, or readbinblock completes when one of these conditions is satisfied:

The specified number of values is read.
The time specified by the Timeout property passes.
The terminator specified by the Terminator property is read.

Writing and Reading Text Data

This example illustrates how to communicate with a serial port instrument by writing and reading text data.

The instrument is a Tektronix^® TDS 210 two-channel oscilloscope connected to the serial port COM1. Therefore, many of the commands in the example are specific to this instrument. A sine wave is input into channel 2 of the oscilloscope, and you want to measure the peak-to-peak voltage of the input signal.

These functions and properties are used when reading and writing text.

Function	Purpose
`readline`	Read text data from the instrument.
`writeline`	Write text data to the instrument.
Terminator	Character used to terminate commands sent to the instrument.

Note

This example is Windows^® specific.

Create a serial port object — Create the serial port object s associated with the serial port COM1.
```
s = serialport("COM1",9600);
```
Write and read data — Write the *IDN? command to the instrument using writeline, and then read back the result of the command using readline.
```
writeline(s,"*IDN?")
s.NumBytesAvailable
```
```
ans =

     56
```
```
idn = readline(s)
```
```
idn =

     "TEKTRONIX,TDS 210,0,CF:91.1CT FV:v1.16 TDS2CM:CMV:v1.04"
```
You need to determine the measurement source. Possible measurement sources include channel 1 and channel 2 of the oscilloscope.
```
writeline(s,"MEASUREMENT:IMMED:SOURCE?")
source = readline(s)
```
```
source =

     "CH1"
```
The scope is configured to return a measurement from channel 1. Because the input signal is connected to channel 2, you must configure the instrument to return a measurement from this channel.
```
writeline(s,"MEASUREMENT:IMMED:SOURCE CH2")
writeline(s,"MEASUREMENT:IMMED:SOURCE?")
source = readline(s)
```
```
source =

     "CH2"
```
You can now configure the scope to return the peak-to-peak voltage, and then request the value of this measurement.
```
writeline(s,"MEASUREMENT:MEAS1:TYPE PK2PK")
writeline(s,"MEASUREMENT:MEAS1:VALUE?")
```
Read back the result using the readline function.
```
ptop = readline(s)
```
```
ptop =

     "2.0199999809E0"
```
Disconnect and clean up — Clear the serial port object s from the MATLAB^® workspace when you are done working with it.
```
clear s
```

Writing and Reading Binary Data

This example explores binary read and write operations with a serial port object. The instrument used is a Tektronix® TDS 210 oscilloscope.

Functions and Properties

These functions are used when reading and writing binary data.

Function	Purpose
`read`	Read binary data from the instrument.
`write`	Write binary data to the instrument.

Configure and Connect to the Serial Object

You need to create a serial object. In this example, create a serial port object associated with the COM1 port.

s = serialport("COM1",9600);

Write Binary Data

You use the write function to write binary data to the instrument. A binary write operation completes when one of these conditions is satisfied:

All the data is written.
A timeout occurs as specified by the Timeout property.

Note

When you perform a write operation, think of the transmitted data in terms of values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

Writing Int16 Binary Data

Write a waveform as an int16 array.

write(s,"Data:Destination RefB","string");
write(s,"Data:Encdg SRPbinary","string");
write(s,"Data:Width 2","string");
write(s,"Data:Start 1","string");

t = (0:499) .* 8 * pi / 500;
data = round(sin(t) * 90 + 127);
write(s,"CURVE #3500","string");

Note that one int16 value consists of two bytes. Therefore, the following command writes 1000 bytes.

write(s,data,"int16")

Reading Binary Data

You use the read function to read binary data from the instrument. A binary read operation completes when one of these conditions is satisfied:

A timeout occurs as specified by the Timeout property.
The specified number of values is read.

Note

When you perform a read operation, think of the received data in terms of values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

Reading int16 Binary Data

Read the same waveform on channel 1 as an int16 array.

write(s,"Data:Source CH1","string");
write(s,"Data:Encdg SRPbinary","string");
write(s,"Data:Width 2","string");
write(s,"Data:Start 1","string");
write(s,"Data:Stop 2500","string");
write(s,"Curve?","string")

Note that one int16 value consists of two bytes. Therefore, the following command reads 512 bytes.

data = read(s,256,"int16");

Disconnect and Clean Up

If you are finished with the serial port object, clear the object from the workspace.

clear s