Show / Hide Table of Contents

    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()
    Object.MemberwiseClone()
    Namespace: System.IO.Ports
    Assembly: System.IO.Ports.dll
    Syntax
    public sealed class SerialPort : IDisposable

    Constructors

    | Improve this Doc View Source

    SerialPort(String, Int32, Parity, Int32, 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).

    Int32 baudRate

    The baud rate.

    Parity parity

    One of the Parity values.

    Int32 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

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    BaudRate

    Gets or sets the serial baud rate.

    Declaration
    public int BaudRate { get; set; }
    Property Value
    Type Description
    Int32
    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
    Int32

    The number of bytes of data in the receive buffer.

    Exceptions
    Type Condition
    InvalidOperationException

    The port is not open.

    | Improve this Doc View Source

    DataBits

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

    Declaration
    public int DataBits { get; set; }
    Property Value
    Type Description
    Int32
    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.

    | Improve this Doc View Source

    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
    Boolean
    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.

    | Improve this Doc View Source

    IsOpen

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

    Declaration
    public bool IsOpen { get; }
    Property Value
    Type Description
    Boolean
    Exceptions
    Type Condition
    ArgumentNullException

    The IsOpen value passed is null.

    ArgumentException

    The IsOpen value passed is an empty string ("").

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    ReadBufferSize

    Gets or sets the size of the SerialPort input buffer.

    Declaration
    public int ReadBufferSize { get; set; }
    Property Value
    Type Description
    Int32

    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.

    | Improve this Doc View Source

    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
    Int32
    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.

    | Improve this Doc View Source

    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
    Int32

    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.

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    WriteBufferSize

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

    Declaration
    public int WriteBufferSize { get; set; }
    Property Value
    Type Description
    Int32

    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.

    | Improve this Doc View Source

    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
    Int32
    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

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    Dispose()

    Dispose the Serial Port.

    Declaration
    public void Dispose()
    | Improve this Doc View Source

    Finalize()

    Destructor.

    Declaration
    protected void Finalize()
    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    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[], Int32, Int32)

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

    Declaration
    public extern int Read(byte[] buffer, int offset, int count)
    Parameters
    Type Name Description
    Byte[] buffer

    The byte array to write the input to.

    Int32 offset

    The offset in buffer at which to write the bytes.

    Int32 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
    Int32

    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.

    | Improve this Doc View Source

    ReadByte()

    Synchronously reads one byte from the SerialPort input buffer.

    Declaration
    public int ReadByte()
    Returns
    Type Description
    Int32

    The byte, cast to an Int32, 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 extern 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 extern 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[], Int32, Int32)

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

    Declaration
    public extern 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.

    Int32 offset

    The zero-based byte offset in the buffer parameter at which to begin copying bytes to the port.

    Int32 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.

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    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

    | Improve this Doc View Source

    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)
    • Improve this Doc
    • View Source
    Back to top Copyright © 2018 nanoFramework Contributors
    Generated by DocFX