serial

(To be removed) Create serial port object

serial will be removed in a future release. Use serialport instead. For more information on updating your code, see Version History.

Syntax

s = serial('port')

s = serial('port',Name,Value)

Description

s = serial('port') creates a serial port object s associated with the serial port specified by 'port'. If 'port' does not exist, or if it is in use, you cannot connect the serial port object to the device.

s = serial('port',Name,Value) creates a serial port object with the specified property names and property values. If an invalid property name or property value is specified, an error is returned, and the serial port object is not created.

Examples

Create Serial Port Object

This example shows how to create a serial port object.

Use the seriallist function to find your available serial ports.

seriallist

Create the serial port object s and associate it with the serial port COM1. You must specify the port as the first argument to create a serial port object.

s = serial('COM1');

Create the serial port object s2, associated with the serial port COM3, and set properties. You can optionally set communication properties by specifying name-value pairs during object creation, after the port argument. This example sets the baud rate to 4800 and the terminator to CR. You can see these values in the object output.

s2 = serial('COM3','BaudRate',4800,'Terminator','CR')

Input Arguments

'port' — Serial port name

character vector | string

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:

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

Example: s = serial('COM1')

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: s = serial('COM2','BaudRate',1200,'DataBits',7);

For a list of serial port object properties that you can use with serial, refer to serial Properties.

Note

Port must be the first argument used to create the serial object. You can then follow port with any number of supported name-value pairs.

BaudRate — Rate at which bits are transmitted

9600 (default) | double

Rate at which bits are transmitted, specified as the comma-separated pair consisting of 'BaudRate' and 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 = serial('COM1','BaudRate',4800);

Data Types: double

ByteOrder — Byte order of the device

littleEndian (default) | bigEndian

Byte order of the device, specified as the comma-separated pair consisting of 'ByteOrder' and 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 = serial('COM1','ByteOrder','bigEndian');

Data Types: char | string

DataBits — Number of data bits to transmit

8 (default) | 5 | 6 | 7

Number of data bits to transmit, specified as the comma-separated pair consisting of 'DataBits' and 5, 6, 7, or 8, which is the default. 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 = serial('COM1','DataBits',7);

Data Types: double

Parity — Type of parity checking

none (default) | odd | even | mark | space

Type of parity checking, specified as the comma-separated pair consisting of 'Parity' and 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 = serial('COM1','Parity','even');

Data Types: char | string

StopBits — Number of bits used to indicate the end of a byte

1 (default) | 1.5 | 2

Number of bits used to indicate the end of a byte, specified as the comma-separated pair consisting of 'StopBits' and 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 = serial('COM1','StopBits',2);

Data Types: double

Terminator — Terminator character

string

Terminator character, specified as the comma-separated pair consisting of 'Terminator' and a string. 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 = serial('COM1','Terminator','CR');

Data Types: char | string

Tips

Refer to serial Properties for a list of serial port object properties that you can use with serial.

Before you can communicate with the device, it must be connected to obj with the fopen function. A connected serial port object has a Status property value of open. An error is returned if you attempt a read or write operation while the object is not connected to the device. You can connect only one serial port object to a given serial port.

Version History

Introduced before R2006a

R2022a: Warns

serial will be removed in a future release. Use serialport instead.

This example shows how to connect to a serial port using the recommended functionality.

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

R2021b: To be removed

The serial function runs without warning, but the Code Analyzer indicates that serial will be removed in a future release.