Class SerialPort
Represents a serial port resource.
Implements
Inherited Members
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.
- 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 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 |