Main Content

serial Properties

(To be removed) Access serial properties

expand all in page

serial and its object properties are not recommended. Use serialport and its properties instead. See Version History.

Serial properties are used to configure communications using the serial object and to configure read and write behavior.

Some properties can be set during object creation with the serial function. See the serial reference page for information about those properties, which include Port, BaudRate, ByteOrder, DataBits, Parity, StopBits, and Terminator.

Communication properties are used to set data bit transfer settings. Read and write properties are used to configure factors involved in the reading and writing of data, such as setting a timeout for completing the operation. Use callback properties to execute callback functions from events. Use control pin properties to configure the state of control pins and data flow control. Use recording properties to set up and control recording information to disk.

Note

This sample syntax for all the properties assumes you have created a serial object, s. Many of the properties can only be set before calling fopen on the object. Some can be changed while the object is open.

Properties can be set after you create the serial object. A read-only property is called as follows:

s = serial('COM1');
s.TransferStatus
ans = 
     idle

A property you can configure is set as follows:

s = serial('COM1');
s.Timeout = 30;

General Purpose Properties

expand all

Descriptive name for the serial port object, specified as a character vector or string. When you create a serial port object, a descriptive name is automatically generated and stored in Name. This name is given by concatenating the word “Serial” with the serial port specified in the serial function. However, you can change the value of Name at any time.

The serial port is given by the Port property. If you modify this property value, then Name is automatically updated to reflect that change.

Example: s.Name = 'MySerialDevice';

Data Types: char | string

This property is read-only.

Serial port name, specified as a character vector or string. The seriallist function provides a list of available serial ports. You must specify the port to create a serial port object.

The port name depends on the platform that the serial port is on. This list is an example of serial constructors on different platforms:

PlatformSerial Port Constructor
Linux® 64s = serial('/dev/ttyS0')
macOS 64s = serial('/dev/tty.KeySerial1')
Windows® 64s = serial('COM1')

Example: s.Port

Data Types: char | string

Label to associate with a serial port object, specified as a character vector or string. Tag uniquely identifies a serial port object. Tag is particularly useful when constructing programs that would otherwise need to define the serial port object as a global variable, or pass the object as an argument between callback routines.

You can return the serial port object with the instrfind function by specifying the Tag property value.

Example: s.Tag = 'MySerialObj';

Data Types: char | string

This property is read-only.

Object type, specified as serial. Type is automatically defined after the serial port object is created with the serial function. The Type value is always serial.

Example: s.Type

Data Types: char | string

Data you want to associate with a serial port object, specified as a MATLAB array. Configure UserData to store data that you want to associate with a serial port object. The object does not use this data directly, but you can access it using the get function or the dot notation.

Control access to serial port object, specified as 'on' or 'off'. It provides a way for application developers to prevent end-user access to the serial port objects created by their applications. When an object's ObjectVisibility property is set to 'off', instrfind does not return or delete that object.

Objects that are not visible are still valid. If you have access to the object (for example, from within the file that creates it), you can set and get its properties and pass it to any function that operates on serial port objects.

Example: s.ObjectVisibility = 'off';

Data Types: char | string

Communications Properties

expand all

Byte order of the device, specified as littleEndian or bigEndian. If ByteOrder is littleEndian, the device stores the first byte in the first memory address. If ByteOrder is bigEndian, the device stores the last byte in the first memory address.

For example, suppose the hexadecimal value 4F52 is to be stored in device memory. Because this value consists of two bytes, 4F and 52, two memory locations are used. Using big-endian format, 4F is stored first in the lower storage address. Using little-endian format, 52 is stored first in the lower storage address.

The byte order of littleEndian is the default and is used in read and write operations if you do not specify the property. You need to specify the property only to change the byte order to bigEndian.

You can also set the ByteOrder property after creating the serial object using this syntax:

s.ByteOrder = 'bigEndian';

Note

Configure ByteOrder to the appropriate value for your device before performing a read or write operation. Refer to your device documentation for information about the order in which it stores bytes.

Example: s.ByteOrder = 'bigEndian';

Data Types: char | string

Rate at which bits are transmitted, specified as a double. You configure baud rate as bits per second. The transferred bits include the start bit, the data bits, the parity bit (if used), and the stop bits. However, only the data bits are stored.

The baud rate is the rate at which information is transferred in a communication channel. In the serial port context, 9600 baud means that the serial port is capable of transferring a maximum of 9600 bits per second. If the information unit is one baud (one bit), the bit rate and the baud rate are identical. If one baud is given as 10 bits, (for example, eight data bits plus two framing bits), the bit rate is still 9600 but the baud rate is 9600/10, or 960. You always configure BaudRate as bits per second.

Note

Both the computer and the peripheral device must be configured to the same baud rate before you can successfully read or write data.

Standard baud rates include 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200, 128000, and 256000 bits per second.

You can also set the BaudRate property after creating the serial object using this syntax:

s.BaudRate = 4800;

Example: s.BaudRate = 4800;

Data Types: double

Number of data bits to transmit, specified as 5, 6, 7, or 8. Data is transmitted as a series of five, six, seven, or eight bits with the least significant bit sent first. At least seven data bits are required to transmit ASCII characters. Eight bits are required to transmit binary data. Five-bit and six-bit data formats are used for specialized communications equipment.

Note

Both the computer and the peripheral device must be configured to transmit the same number of data bits.

In addition to the data bits, the serial data format consists of a start bit, one or two stop bits, and possibly a parity bit. You specify the number of stop bits with the StopBits property, and the type of parity checking with the Parity property.

You can also set the DataBits property after creating the serial object using this syntax:

s.DataBits = 7;

Example: s.DataBits = 7;

Data Types: double

Type of parity checking, specified as none, odd, even, mark, or space.

'none'

Default. No parity checking. Parity checking is not performed and the parity bit is not transmitted.

'odd'

Odd parity checking. The number of mark bits (1s) in the data is counted, and the parity bit is asserted or unasserted to obtain an odd number of mark bits.

'even'

Even parity checking. The number of mark bits in the data is counted, and the parity bit is asserted or unasserted to obtain an even number of mark bits.

'mark'

Mark parity checking. The parity bit is asserted.

'space'

Space parity checking. The parity bit is unasserted.

Parity checking can detect errors of one bit only. An error in two bits might cause the data to have a seemingly valid parity, when in fact it is incorrect.

In addition to the parity bit, the serial data format consists of a start bit, between five and eight data bits, and one or two stop bits. You specify the number of data bits with the DataBits property, and the number of stop bits with the StopBits property.

You can also set the Parity property after creating the serial object using this syntax:

s.Parity = 'even';

Example: s.Parity = 'even';

Data Types: char | string

Number of bits used to indicate the end of a byte, specified as 1, 1.5, or 2. If StopBits is 1, one stop bit is used to indicate the end of data transmission. If StopBits is 2, two stop bits are used to indicate the end of data transmission. If StopBits is 1.5, the stop bit is transferred for 150% of the normal time used to transfer one bit.

Note

Both the computer and the peripheral device must be configured to transmit the same number of stop bits.

Summary of the possible values:

1

Default. One stop bit is transmitted to indicate the end of a byte.

1.5

The stop bit is transferred for 150% of the normal time used to transfer one bit.

2

Two stop bits are transmitted to indicate the end of a byte.

In addition to the stop bits, the serial data format consists of a start bit, between five and eight data bits, and possibly a parity bit. You specify the number of data bits with the DataBits property, and the type of parity checking with the Parity property.

You can also set the StopBits property after creating the serial object using this syntax:

s.StopBits = 2;

Example: s.StopBits = 2;

Data Types: double

Terminator character, specified as a string or cell array. You can configure Terminator to an integer value ranging from 0 to 127, which represents the ASCII code for the character, or you can configure Terminator to the ASCII character. For example, to configure Terminator to a carriage return, specify the value to be CR or 13. To configure Terminator to a linefeed, specify the value to be LF or 10. You can also set Terminator to CR/LF or LF/CR. If Terminator is CR/LF, the terminator is a carriage return followed by a line feed. If Terminator is LF/CR, the terminator is a linefeed followed by a carriage return. Note that there are no integer equivalents for these two values.

Additionally, you can set Terminator to a 1-by-2 cell array. The first element of the cell is the read terminator and the second element of the cell array is the write terminator.

When performing a write operation using the fprintf function, all occurrences of \n are replaced with the Terminator property value. Note that %s\n is the default format for fprintf. A read operation with fgetl, fgets, or fscanf completes when the Terminator value is read. The terminator is ignored for binary operations.

You can also use the terminator to generate a bytes-available event when the BytesAvailableFcnMode is set to terminator.

You can also set the Terminator property after creating the serial object, using this syntax:

s.Terminator = 'CR';

Example: s.Terminator = 'CR';

Data Types: char | string | cell

Read and Write Properties

expand all

This property is read-only.

Number of bytes available in the input buffer, specified as a double. This read-only property indicates the number of bytes currently available to be read from the input buffer. The property value is continuously updated as the input buffer is filled, and is set to 0 after the fopen function is issued.

You can make use of BytesAvailable only when reading data asynchronously. This is because when reading data synchronously, control is returned to the MATLAB® command line only after the input buffer is empty. Therefore, the BytesAvailable value is always 0.

The BytesAvailable value can range from zero to the size of the input buffer. Use the InputBufferSize property to specify the size of the input buffer. Use the ValuesReceived property to return the total number of values read.

Example: s.BytesAvailable

Data Types: double

Size of the input buffer in bytes, specified as a double. You configure InputBufferSize as the total number of bytes that can be stored in the input buffer during a read operation.

A read operation is terminated if the amount of data stored in the input buffer equals the InputBufferSize value. You can read text data with the fgetl, fget, or fscanf functions. You can read binary data with the fread function.

You can configure InputBufferSize only when the serial port object is disconnected from the device. You can configure it before calling the fopen function. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

If you configure InputBufferSize while there is data in the input buffer, that data is purged.

Example: s.InputBufferSize = 768;

Data Types: double

Specify whether an asynchronous read operation is continuous or manual, specified as 'manual' or 'continuous'. If ReadAsyncMode is continuous, the serial port object continuously queries the device to determine if data is available to be read. If data is available, it is automatically read and stored in the input buffer. If issued, the readasync function is ignored.

If ReadAsyncMode is manual, the object does not query the device to determine if data is available to be read. Instead, you must manually issue the readasync function to perform an asynchronous read operation. Because readasync checks for the terminator, this function can be slow. To increase speed, configure ReadAsyncMode to continuous.

Note

If the device is ready to transmit data, it will do so regardless of the ReadAsyncMode value. Therefore, if ReadAsyncMode is manual and a read operation is not in progress, data might be lost. To guarantee that all transmitted data is stored in the input buffer, you should configure ReadAsyncMode to continuous.

To determine the amount of data available in the input buffer, use the BytesAvailable property. For either ReadAsyncMode value, you can bring data into the MATLAB workspace with one of the synchronous read functions such as fscanf, fgetl, fgets, or fread.

Example: s.ReadAsyncMode = 'manual';

Data Types: char | string

Waiting time to complete a read or write operation, specified as a double. You configure Timeout to be the maximum time (in seconds) to wait to complete a read or write operation. The default value of 10 seconds is used if you do not specify a different value. Timeouts are rounded upwards to full seconds.

If a timeout occurs, the read or write operation aborts. Additionally, if a timeout occurs during an asynchronous read or write operation, then:

  • An error event is generated.

  • The callback function specified for ErrorFcn is executed.

Example: s.Timeout = 30;

Data Types: double

This property is read-only.

Status of asynchronous read or write operation, specified as idle, read, write, or read&write. This read-only property indicates if an asynchronous read or write operation is in progress. If TransferStatus is idle, no asynchronous read or write operations are in progress. If it is read, an asynchronous read operation is in progress. If it is write, an asynchronous write operation is in progress. If TransferStatus is read&write, both an asynchronous read and an asynchronous write operation are in progress.

You can write data asynchronously using the fprintf or fwrite functions. You can read data asynchronously using the readasync function, or by configuring the ReadAsyncMode property to continuous. While readasync is executing, TransferStatus might indicate that data is being read even though data is not filling the input buffer. If ReadAsyncMode is continuous, TransferStatus indicates that data is being read only when data is filling the input buffer.

You can execute an asynchronous read and an asynchronous write operation simultaneously because serial ports have separate read and write pins.

Summary the possible values:

{idle}

No asynchronous operations are in progress.

read

An asynchronous read operation is in progress.

write

An asynchronous write operation is in progress.

read&write

Asynchronous read and write operations are in progress.

Example: s.TransferStatus

Data Types: char | string

This property is read-only.

Total number of values read from the device, specified as a double. This is a read-only property, and the value is updated after each successful read operation and set to 0 after the fopen function is issued. If the terminator is read from the device, then this value is reflected by ValuesReceived.

If you are reading data asynchronously, use the BytesAvailable property to return the number of bytes currently available in the input buffer.

When performing a read operation, the received data is represented by values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

For example, create a serial port object associated with the serial port COM1, and open the connection.

s = serial('COM1');
fopen(s)

If you write the RS232? command, and read back the response using fscanf, ValuesReceived is 17 because the instrument is configured to send the LF terminator.

fprintf(s,'RS232?')
out = fscanf(s)
out =
9600;0;0;NONE;LF
s.ValuesReceived
ans =
    17

Example: s.ValuesReceived

Data Types: double

This property is read-only.

Number of bytes currently in the output buffer, specified as a double. This read-only property indicates the number of bytes currently in the output buffer waiting to be written to the device. The property value is continuously updated as the output buffer is filled and emptied, and is set to 0 after the fopen function is issued.

You can make use of BytesToOutput only when writing data asynchronously. This is because when writing data synchronously, control is returned to the MATLAB command line only after the output buffer is empty. Therefore, the BytesToOutput value is always 0.

Use the ValuesSent property to return the total number of values written to the device.

Note

If you attempt to write out more data than can fit in the output buffer, an error is returned and BytesToOutput is 0. Specify the size of the output buffer with the OutputBufferSize property.

Example: s.BytesToOutput

Data Types: double

Size of the output buffer in bytes, specified as a double. You configure OutputBufferSize as the total number of bytes that can be stored in the output buffer during a write operation.

You can configure OutputBufferSize only when the serial port object is disconnected from the device. You can configure it before calling the fopen function. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

An error occurs if the output buffer cannot hold all the data to be written. You write text data with the fprintf function. You write binary data with the fwrite function.

Example: s.OutputBufferSize = 256;

Data Types: double

This property is read-only.

Total number of values written to the device, specified as a double. This is a read-only property, and the value is updated after each successful write operation and set to 0 after the fopen function is issued. If you are writing the terminator, ValuesSent reflects this value.

If you are writing data asynchronously, use the BytesToOutput property to return the number of bytes currently in the output buffer.

When performing a write operation, the transmitted data is represented by values rather than bytes. A value consists of one or more bytes. For example, one uint32 value consists of four bytes.

For example, create a serial port object associated with the serial port COM1 and open the connection.

s = serial('COM1');
fopen(s)

If you write the *IDN? command using the fprintf function, ValuesSent is 6 because the default data format is %s\n, and the terminator was written.

fprintf(s,'*IDN?')
s.ValuesSent
ans =
    6

Example: s.ValuesSent

Data Types: double

This property is read-only.

Status of serial port device connection, returned as closed or open. This read-only property indicates whether the serial port object is connected to the device. If Status is closed, the serial port object is not connected to the device. If Status is open, the serial port object is connected to the device.

Before you can write or read data, you must connect the serial port object to the device with the fopen function. Use the fclose function to disconnect a serial port object from the device.

Example: s.Status

Data Types: char | string

Callback Properties

expand all

Callback function to run when break-interrupt event occurs, specified as a function handle. A break-interrupt event is generated by the serial port when the received data is in an off (space) state longer than the transmission time for one byte.

Note

A break-interrupt event can be generated at any time during the serial port session.

If the RecordStatus property value is on, and a break-interrupt event occurs, the record file records this information:

  • The event type as BreakInterrupt

  • The time the event occurred using the format day-month-year hour:minute:second:millisecond

Data Types: function_handle

Callback function to run when bytes-available event occurs, specified as a function handle. A bytes-available event occurs when the number of bytes specified by the BytesAvailableFcnCount property is available in the input buffer, or after a terminator is read, as determined by the BytesAvailableFcnMode property.

Note

A bytes-available event can be generated only for asynchronous read operations.

If the RecordStatus property value is on, and a bytes-available event occurs, the record file records this information:

  • The event type as BytesAvailable

  • The time the event occurred using the format day-month-year hour:minute:second:millisecond

Note

You cannot use ASCII values larger than 127 characters. The function is limited to 127 binary characters.

Example: s.BytesAvailableFcn = @instrcallback;

Data Types: function_handle

Number of bytes that must be available in the input buffer to generate a bytes-available event, specified as a number.

Use the BytesAvailableFcnMode property to specify whether the bytes-available event occurs after a certain number of bytes are available or after a terminator is read.

The bytes-available event executes the callback function specified for the BytesAvailableFcn property.

You can configure BytesAvailableFcnCount only when the object is disconnected from the device. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

Example: s.BytesAvailableFcnCount = 40;

Data Types: double

Type of bytes-available function to generate a bytes-available event, specified as 'terminator' or 'byte'. If BytesAvailableFcnMode is 'terminator', a bytes-available event occurs when the terminator specified by the Terminator property is reached. If BytesAvailableFcnMode is 'byte', a bytes-available event occurs when the number of bytes specified by the BytesAvailableFcnCount property is available.

The bytes-available event executes the callback function specified for the BytesAvailableFcn property.

You can configure BytesAvailableFcnMode only when the object is disconnected from the device. You disconnect an object with the fclose function. A disconnected object has a Status property value of closed.

Example: s.BytesAvailableFcnMode = 'byte';

Data Types: char | string

Callback function to run when an error event occurs, specified as a function handle.

Note

An error event is generated only for asynchronous read and write operations.

An error event is generated when a time-out occurs. A time-out occurs if a read or write operation does not successfully complete within the time specified by the Timeout property. An error event is not generated for configuration errors such as setting an invalid property value.

If the RecordStatus property value is on, and an error event occurs, the record file records this information:

  • The event type as Error

  • The error message

  • The time the event occurred using the format day-month-year hour:minute:second:millisecond

Data Types: function_handle

Callback function to execute when an output-empty event occurs, specified as a function handle. An output-empty event occurs when the last byte is sent from the output buffer to the device.

Note

An output-empty event can be generated only for asynchronous write operations.

If the RecordStatus property value is on, and an output-empty event occurs, the record file records this information:

  • The event type as OutputEmpty

  • The time the event occurred using the format day-month-year hour:minute:second:millisecond

Data Types: function_handle

Callback function to run when a pin status event occurs, specified as a function handle. A pin status event occurs when the Carrier Detect (CD), Clear to Send (CTS), Data Set Ready (DSR), or Ring Indicator (RI) pin changes state. A serial port pin changes state when it is asserted or unasserted. Information about the state of these pins is recorded in the PinStatus property.

Note

A pin status event can be generated at any time during the serial port session.

If the RecordStatus property value is on, and a pin status event occurs, the record file records this information:

  • The event type as PinStatus

  • The pin that changed its state, and the pin state as either on or off

  • The time the event occurred using the format day-month-year hour:minute:second:millisecond

Data Types: function_handle

Callback function to run when a timer event occurs, specified as a function handle. A timer event occurs when the time specified by the TimerPeriod property passes. Time is measured relative to when the serial port object is connected to the device with fopen.

Note

A timer event can be generated at any time during the serial port session.

If the RecordStatus property value is on, and a timer event occurs, the record file records this information:

  • The event type as Timer

  • The time the event occurred using the format day-month-year hour:minute:second:millisecond

Some timer events might not be processed if your system is significantly slowed or if the TimerPeriod value is too small.

Data Types: function_handle

Period of time between timer events, specified as a number in seconds. It is the time that must pass before the callback function specified for TimerFcn is called. Time is measured relative to when the serial port object is connected to the device with fopen.

Some timer events might not be processed if your system is significantly slowed or if the TimerPeriod value is too small.

Data Types: double

Control Pin Properties

expand all

State of the DTR pin, specified as on or off. If DataTerminalReady is on, the Data Terminal Ready (DTR) pin is asserted. If DataTerminalReady is off, the DTR pin is unasserted.

In normal usage, the DTR and Data Set Ready (DSR) pins work together, and are used to signal if devices are connected and powered. However, there is nothing in the RS-232 standard that states the DTR pin must be used in any specific way. For example, DTR and DSR might be used for handshaking. You should refer to your device documentation to determine its specific pin behavior.

You can return the value of the DSR pin with the PinStatus property.

Example: s.DataTerminalReady = 'off';

Data Types: char | string

Data flow control method, specified as none, hardware, or software. If FlowControl is none, data flow control (handshaking) is not used. If FlowControl is hardware, hardware handshaking is used to control data flow. If FlowControl is software, software handshaking is used to control data flow.

Hardware handshaking typically utilizes the Request to Send (RTS) and Clear to Send (CTS) pins to control data flow. Software handshaking uses control characters (Xon and Xoff) to control data flow.

You can return the value of the CTS pin with the PinStatus property. You can specify the value of the RTS pin with the RequestToSend property. However, if FlowControl is hardware, and you specify a value for RequestToSend, that value might not be honored.

Note

Although you might be able to configure your device for both hardware handshaking and software handshaking at the same time, MATLAB does not support this behavior.

Example: s.FlowControl = 'hardware';

Data Types: char | string

This property is read-only.

State of the CD, CTS, DSR, and RI pins, returned as a structure. This read-only property returns a structure array that contains the fields CarrierDetect, ClearToSend, DataSetReady and RingIndicator. These fields indicate the state of the Carrier Detect (CD), Clear to Send (CTS), Data Set Ready (DSR) and Ring Indicator (RI) pins, respectively.

PinStatus can be on or off for any of these fields. A value of on indicates the associated pin is asserted. A value of off indicates the associated pin is unasserted. A pin status event occurs when any of these pins changes its state. A pin status event executes the call back function specified by PinStatusFcn.

In normal usage, the Data Terminal Ready (DTR) and DSR pins work together, while the Request to Send (RTS) and CTS pins work together. You can specify the state of the DTR pin with the DataTerminalReady property. You can specify the state of the RTS pin with the RequestToSend property.

Example: s.PinStatus

Data Types: struct

State of the RTS pin, specified as on or off. If RequestToSend is on, the Request to Send (RTS) pin is asserted. If RequestToSend is off, the RTS pin is unasserted.

In normal usage, the RTS and Clear to Send (CTS) pins work together, and are used as standard handshaking pins for data transfer. In this case, RTS and CTS are automatically managed by the DTE and DCE. However, there is nothing in the RS-232 standard that requires the RTS pin must be used in any specific way. Therefore, if you manually configure the RequestToSend value, it is probably for nonstandard operations.

If your device does not use hardware handshaking in the standard way, and you need to manually configure RequestToSend, configure the FlowControl property to none. Otherwise, the RequestToSend value that you specify might not be honored. Refer to your device documentation to determine its specific pin behavior.

You can return the value of the CTS pin with the PinStatus property.

Example: s.RequestToSend = 'off';

Data Types: char | string

Recording Properties

expand all

Detail level of information saved to a record file, specified as compact or verbose. If RecordDetail is compact, the number of values written to the device, the number of values read from the device, the data type of the values, and event information are saved to the record file. If RecordDetail is verbose, the data written to the device and the data read from the device are also saved to the record file.

Summary of the possible values:

{compact}

The number of values written to the device, the number of values read from the device, the data type of the values, and event information are saved to the record file.

verbose

The data written to the device, and the data read from the device are also saved to the record file.

Example: s.RecordDetail = 'verbose';

Data Types: char | string

Method for saving data and event information in record files, specified as overwrite, append, or index. If RecordMode is overwrite, the record file is overwritten each time recording is initiated. If RecordMode is append, data is appended to the record file each time recording is initiated. If RecordMode is index, a different record file is created each time recording is initiated, each with an indexed filename.

You can configure RecordMode only when the object is not recording. You terminate recording with the record function. An object that is not recording has a RecordStatus property value of off.

You specify the record filename with the RecordName property. The indexed filename follows a prescribed set of rules.

Summary of the possible values:

{overwrite}

The record file is overwritten.

append

Data is appended to an existing record file.

index

A different record file is created, each with an indexed filename.

For example, record serial data using the record properties. Create the serial port object and open the connection.

s = serial('COM1');
fopen(s)

Specify the record filename with the RecordName property, configure RecordMode to index, and initiate recording.

s.RecordName = 'MyRecord.txt';
s.RecordMode = 'index';
record(s)

The record filename is automatically updated with an indexed filename after recording is turned off.

record(s,'off')
s.RecordName
ans =
MyRecord01.txt

Disconnect s from the peripheral device, remove s from memory, and remove s from the MATLAB workspace.

fclose(s)
delete(s)
clear s

Example: s.RecordMode = 'index';

Data Types: char | string

Name of the record file, specified as a string. You can specify any value for RecordName - including a directory path - provided the file name is supported by your operating system.

The default record filename is record.txt, which is used if you record a data file and do not specify a different name.

MATLAB supports any file name supported by your operating system. You can access the file using the type function. For example, if you name the record file MyRecord.txt, to type this file at the MATLAB command line, enter:

type('MyRecord.txt')

You can specify whether data and event information are saved to one disk file or to multiple disk files with the RecordMode property. If RecordMode is index, the filename follows a prescribed set of rules.

You can configure RecordName only when the object is not recording. You terminate recording with the record function. An object that is not recording has a RecordStatus property value of off.

Example: s.RecordName = 'MonthlyDataFile_April';

Data Types: char | string

This property is read-only.

Status of recording serial data and event information, returned as on or off. This read-only property indicates whether recording is on or off, which is controlled by the record function. If RecordStatus is off, then data and event information are not saved to a record file. If RecordStatus is on, then data and event information are saved to the record file specified by RecordName.

Use the record function to initiate or complete recording. RecordStatus is automatically configured to reflect the recording state.

Example: s.RecordStatus

Data Types: char | string

Version History

Introduced before R2006a

collapse all

R2021a: serial object interface will be removed

serial and its object properties are not recommended. Use serialport and its properties instead.

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

The recommended interface has additional capabilities and improved performance. See Transition Your Code to serialport Interface for more information about using the recommended functionality.