Class SerialPort

Represents a serial port resource.

Inheritance

object

SerialPort

Implements

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Namespace: System.IO.Ports

Assembly: System.IO.Ports.dll

Syntax

public sealed class SerialPort : IDisposable

Constructors

SerialPort(string, int, Parity, int, StopBits)

Initializes a new instance of the SerialPort class using the specified port name, baud rate, parity bit, data bits, and stop bit.

Declaration

public SerialPort(string portName, int baudRate = 9600, Parity parity = Parity.None, int dataBits = 8, StopBits stopBits = StopBits.One)

Parameters

Type	Name	Description
string	portName	The port to use (for example, COM1).
int	baudRate	The baud rate.
Parity	parity	One of the Parity values.
int	dataBits	The data bits value.
StopBits	stopBits	One of the StopBits values.

Exceptions

Type	Condition
IOException	The specified port could not be found or opened.
ArgumentException	The specified port is already opened.

Properties

BaseStream

Gets the underlying Stream object for a SerialPort object.

Declaration

public Stream BaseStream { get; }

Property Value

Type	Description
Stream

Exceptions

Type	Condition
InvalidOperationException	The stream is closed. This can occur because the Open() method has not been called or the Close() method has been called.

BaudRate

Gets or sets the serial baud rate.

Declaration

public int BaudRate { get; set; }

Property Value

Type	Description
int

Exceptions

Type	Condition
ArgumentOutOfRangeException	The baud rate specified is less than or equal to zero, or is greater than the maximum allowable baud rate for the device.
IOException	The port is in an invalid state. -or- An attempt to set the state of the underlying port failed. For example, the parameters passed from this SerialPort object were invalid.

BytesToRead

Gets the number of bytes of data in the receive buffer.

Declaration

public int BytesToRead { get; }

Property Value

Type	Description
int	The number of bytes of data in the receive buffer.

Exceptions

Type	Condition
InvalidOperationException	The port is not open.

DataBits

Gets or sets the standard length of data bits per byte.

Declaration

public int DataBits { get; set; }

Property Value

Type	Description
int

Exceptions

Type	Condition
IOException	The port is in an invalid state. -or- An attempt to set the state of the underlying port failed. For example, the parameters passed from this SerialPort object were invalid.
ArgumentOutOfRangeException	The data bits value is less than 5 or more than 8.

Handshake

Gets or sets the handshaking protocol for serial port transmission of data using a value from Handshake.

Declaration

public Handshake Handshake { get; set; }

Property Value

Type	Description
Handshake

Exceptions

Type	Condition
IOException	The port is in an invalid state. -or- An attempt to set the state of the underlying port failed. For example, the parameters passed from this SerialPort object were invalid.
ArgumentOutOfRangeException	The value passed is not a valid value in the Handshake enumeration.

InvertSignalLevels

Gets or sets a value indicating whether the logic level of the RX and TX signals are inverted.

Declaration

public bool InvertSignalLevels { get; set; }

Property Value

Type	Description
bool

Remarks

When the signal levels are not inverted (reads false) the RX, TX pins use the standard logic levels (VDD = 1/idle, GND = 0/mark). Setting this property to true, will invert those signal levels, which will become inverted (VDD = 0/mark, GND= 1/idle). Some targets may not support this setting and accessing it will throw a NotSupportedException exception. This is a .NET nanoFramework property only. Doesn't exist on other .NET platforms.

Exceptions

Type	Condition
InvalidOperationException	Trying to set this property when the SerialPort is already opened and the driver doesn't support it.
NotSupportedException	Trying to set this property on a target that does not support signal inversion.

IsOpen

Gets a value indicating whether the SerialPort is open or closed.

Declaration

public bool IsOpen { get; }

Property Value

Type	Description
bool

Exceptions

Type	Condition
ArgumentNullException	The IsOpen value passed is null.
ArgumentException	The IsOpen value passed is an empty string ("").

Mode

Gets or sets the Serial Mode.

Declaration

public SerialMode Mode { get; set; }

Property Value

Type	Description
SerialMode

Remarks

This is a .NET nanoFramework property only.

NewLine

Gets or sets the value used to interpret the end of a call to the ReadLine() and WriteLine(string)(System.String) methods.

Declaration

public string NewLine { get; set; }

Property Value

Type	Description
string

Exceptions

Type	Condition
ArgumentException	The property value is empty or the property value is null.

Parity

Gets or sets the parity-checking protocol.

Declaration

public Parity Parity { get; set; }

Property Value

Type	Description
Parity

Exceptions

Type	Condition
IOException	The port is in an invalid state. -or- An attempt to set the state of the underlying port failed. For example, the parameters passed from this SerialPort object were invalid.

PortName

Gets the port for communications.

Declaration

public string PortName { get; }

Property Value

Type	Description
string

Remarks

.NET nanoFramework doesn't support changing the port.

ReadBufferSize

Gets or sets the size of the SerialPort input buffer.

Declaration

public int ReadBufferSize { get; set; }

Property Value

Type	Description
int	The size of the input buffer. The default is 256.

Remarks

Implementation of this property for .NET nanoFramework it's slightly different from .NET.

- There is only one work buffer which is used for transmission and reception.

- When the SerialPort is Open() the driver will try to allocate the requested memory for the buffer. On failure to do so, an OutOfMemoryException exception will be throw and the Open() operation will fail.

Exceptions

Type	Condition
ArgumentOutOfRangeException	The ReadBufferSize value is less than or equal to zero.
InvalidOperationException	The ReadBufferSize property was set while the stream was open.

ReadTimeout

Gets or sets the number of milliseconds before a time-out occurs when a read operation does not finish.

Declaration

public int ReadTimeout { get; set; }

Property Value

Type	Description
int

Exceptions

Type	Condition
IOException	The port is in an invalid state. -or- An attempt to set the state of the underlying port failed. For example, the parameters passed from this SerialPort object were invalid.
ArgumentOutOfRangeException	The read time-out value is less than zero and not equal to Infinite.

ReceivedBytesThreshold

Gets or sets the number of bytes in the internal input buffer before a DataReceived event occurs.

Declaration

public int ReceivedBytesThreshold { get; set; }

Property Value

Type	Description
int	The number of bytes in the internal input buffer before a DataReceived event is fired. The default is 1.

Exceptions

Type	Condition
ArgumentOutOfRangeException	The ReceivedBytesThreshold value is less than or equal to zero.

StopBits

Gets or sets the standard number of stopbits per byte.

Declaration

public StopBits StopBits { get; set; }

Property Value

Type	Description
StopBits

Exceptions

Type	Condition
IOException	The port is in an invalid state. -or- An attempt to set the state of the underlying port failed. For example, the parameters passed from this SerialPort object were invalid.

WatchChar

Sets a character to watch for in the incoming data stream.

Declaration

public char WatchChar { get; set; }

Property Value

Type	Description
char

Remarks

This property is specific to .NET nanoFramework. There is no equivalent in the System.IO.Ports API. When calling any of the Read function with a buffer, no matter if the requested quantity of bytes hasn't been read, only the specific amount of data will be returned up to the character. Also if this character is received in the incoming data stream, an event is fired with it's SerialData parameter set to WatchChar.

WriteBufferSize

Gets or sets the size of the serial port output buffer.

Declaration

public int WriteBufferSize { get; set; }

Property Value

Type	Description
int	The size of the output buffer. The default is 256.

Remarks

Implementation of this property for .NET nanoFramework it's slightly different from .NET.

- There is only one work buffer which is used for transmission and reception.

Exceptions

Type	Condition
ArgumentOutOfRangeException	The WriteBufferSize value is less than or equal to zero.
InvalidOperationException	The WriteBufferSize property was set while the stream was open.

WriteTimeout

Gets or sets the number of milliseconds before a time-out occurs when a write operation does not finish.

Declaration

public int WriteTimeout { get; set; }

Property Value

Type	Description
int

Exceptions

Type	Condition
IOException	The port is in an invalid state. -or- An attempt to set the state of the underlying port failed. For example, the parameters passed from this SerialPort object were invalid.
ArgumentOutOfRangeException	The read time-out value is less than zero and not equal to Infinite.

Methods

Close()

Closes the port connection, sets the IsOpen property to false, and disposes of the internal Stream object.

Declaration

public void Close()

Exceptions

Type	Condition
IOException	The port is in an invalid state. -or- An attempt to set the state of the underlying port failed. For example, the parameters passed from this SerialPort object were invalid.

Dispose()

Dispose the Serial Port.

Declaration

public void Dispose()

Finalize()

Destructor.

Declaration

protected override void Finalize()

GetPortNames()

Gets an array of serial port names for the current computer.

Declaration

public static string[] GetPortNames()

Returns

Type	Description
string[]	An array of serial port names for the current computer.

Open()

Opens a new serial port connection.

Declaration

public void Open()

Exceptions

Type	Condition
InvalidOperationException	The specified port on the current instance of the SerialPort. is already open.
ArgumentException	One (or more) of the properties set to configure this SerialPort are invalid.
OutOfMemoryException	Failed to allocate the request amount of memory for the work buffer.

Read(byte[], int, int)

Reads a number of bytes from the SerialPort input buffer and writes those bytes into a byte array at the specified offset.

Declaration

public int Read(byte[] buffer, int offset, int count)

Parameters

Type	Name	Description
byte[]	buffer	The byte array to write the input to.
int	offset	The offset in buffer at which to write the bytes.
int	count	The maximum number of bytes to read. Fewer bytes are read if count is greater than the number of bytes in the input buffer.

Returns

Type	Description
int	The number of bytes read.

Exceptions

Type	Condition
ArgumentNullException	The buffer passed is null.
InvalidOperationException	The specified port is not open.
ArgumentOutOfRangeException	The offset or count parameters are outside a valid region of the buffer being passed. Either offset or count is less than zero.
ArgumentException	Offset plus count is greater than the length of the buffer.
TimeoutException	No bytes were available to read.

ReadByte()

Synchronously reads one byte from the SerialPort input buffer.

Declaration

public int ReadByte()

Returns

Type	Description
int	The byte, cast to an int, or -1 if the end of the stream has been read.

Exceptions

Type	Condition
InvalidOperationException	The specified port is not open.
TimeoutException	The operation did not complete before the time-out period ended. -or- No byte was read.

ReadExisting()

Reads all immediately available bytes, based on the encoding, in both the stream and the input buffer of the SerialPort object.

Declaration

public string ReadExisting()

Returns

Type	Description
string	The contents of the stream and the input buffer of the SerialPort object.

Exceptions

Type	Condition
InvalidOperationException	The specified port is not open.

ReadLine()

Reads up to the NewLine value in the input buffer.

Declaration

public string ReadLine()

Returns

Type	Description
string	The contents of the input buffer up to the first occurrence of a NewLine value.

Exceptions

Type	Condition
InvalidOperationException	The specified port is not open.
TimeoutException	The operation did not complete before the time-out period ended. -or- No bytes were read.

Write(byte[], int, int)

Writes a specified number of bytes to the serial port using data from a buffer.

Declaration

public void Write(byte[] buffer, int offset, int count)

Parameters

Type	Name	Description
byte[]	buffer	The byte array that contains the data to write to the port.
int	offset	The zero-based byte offset in the buffer parameter at which to begin copying bytes to the port.
int	count	The number of characters to write.

Exceptions

Type	Condition
ArgumentNullException	The buffer passed is null.
InvalidOperationException	The specified port is not open.
ArgumentOutOfRangeException	The offset or count parameters are outside a valid region of the buffer being passed. Either offset or count is less than zero.
ArgumentException	Offset plus count is greater than the length of the buffer.
TimeoutException	The operation did not complete before the time-out period ended.

Write(string)

Writes the specified string to the serial port.

Declaration

public void Write(string text)

Parameters

Type	Name	Description
string	text	The string for output.

Exceptions

Type	Condition
InvalidOperationException	The specified port is not open.
ArgumentNullException	Text is null.
TimeoutException	The operation did not complete before the time-out period ended.

WriteByte(byte)

Writes a byte to the serial port.

Declaration

public void WriteByte(byte value)

Parameters

Type	Name	Description
byte	value	The byte to write to the port.

Exceptions

Type	Condition
InvalidOperationException	The specified port is not open.
TimeoutException	The operation did not complete before the time-out period ended.

WriteLine(string)

Writes the specified string and the NewLine value to the output buffer.

Declaration

public void WriteLine(string text)

Parameters

Type	Name	Description
string	text	The string to write to the output buffer.

Exceptions

Type	Condition
ArgumentNullException	The text parameter is null.
InvalidOperationException	The specified port is not open.
TimeoutException	The WriteLine(string)(System.String) method could not write to the stream.

Events

DataReceived

Indicates that data has been received through a port represented by the SerialPort object.

Declaration

public event SerialDataReceivedEventHandler DataReceived

Event Type

Type	Description
SerialDataReceivedEventHandler

Implements

IDisposable

Extension Methods

LogDispatcher.GetCurrentClassLogger(object)