SerialDevice SerialDevice SerialDevice SerialDevice Class

Definition

Represents a serial port. The object provides methods and properties that an app can use to find the port (in the system).

public : sealed class SerialDevice : ISerialDevice, IClosablepublic sealed class SerialDevice : ISerialDevice, IDisposablePublic NotInheritable Class SerialDevice Implements ISerialDevice, IDisposable// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The serial device capability, <DeviceCapability>, is required to use the SerialDevice class. For more info, see Windows.Devices.SerialCommunication.

Create a SerialDevice object

  1. Get this information about the serial port.+ The COM port name that represents the serial port, such as "COM1". In Device Manager, open Ports (COM & LPT), the device node string indicates the port number.
  2. If you are using a Serial-to-USB converter, the virtual COM port name such as "COM1" or the vendor and product identifiers of the converter. You can derive the identifiers from the Hardware Ids property in Device Manager. For example, if Hardware Id is "USB\VID_045E&PID_078E", vendor ID is "0x045E" and product Id is "0x078E".

  3. Generate an Advanced Query Syntax (AQS) string that contains search criteria for finding the device in the enumerated device collection. If you have the vendor and product identifiers, call GetDeviceSelectorFromUsbVidPid.

  4. Pass the retrieved string to FindAllAsync. The call retrieves a DeviceInformationCollection object.
  5. Loop through the collection. Each iteration gets a DeviceInformation object.
  6. Get the DeviceInformation.Id property value. The string value is the device instance path. For example, PCI#VEN_9710&DEV_9835&SUBSYS_00011000&REV_01\5&338FDA70&0&20F0#CHILD0000.
  7. Call FromIdAsync by passing the device instance string and get the SerialDevice object.

Read and write data

You can then use the SerialDevice object to read from or write to the serial port by using the Windows.Storage.Streams namespace.

  1. Obtain a reference to the input stream by getting the SerialDevice.InputStream property.
  2. Create a DataReader object by specifying the input stream in the DataReader constructor.

  3. Obtain a reference to the output stream by getting the SerialDevice.OutputStream property.

  4. Create a DataWriter object by specifying the output stream in the DataWriter constructor.

Release the SerialDevice object

After you are finished using the SerialDevice object, release it.

C++ apps must release the reference by using the delete keyword. C#/VB apps must call the SerialDevice.Dispose method. JavaScript apps must call SerialDevice.Close.

Properties

BaudRate BaudRate BaudRate BaudRate

Gets or sets the baud rate.

public : unsigned int BaudRate { get; set; }public uint BaudRate { get; set; }Public ReadWrite Property BaudRate As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The baud rate of the serial port.

Remarks

The property is set on the SerialDevice object that represents the serial port. The baud rate must be supported by the serial port. To see the possible values, in Device Manager, open the Port Settings tab of the COM port.

BreakSignalState BreakSignalState BreakSignalState BreakSignalState

Gets or sets the break signal state.

public : PlatForm::Boolean BreakSignalState { get; set; }public bool BreakSignalState { get; set; }Public ReadWrite Property BreakSignalState As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

Toggles the TX line to enable or disable data transmission.

Remarks

In serial communication, the break signal state is used to toggle the TX line. To suspend data transmission, set the property value to true. In that state, you cannot write to the serial port. To resume transmission, set to false.

BytesReceived BytesReceived BytesReceived BytesReceived

Represents the number of bytes received by the last read operation of the input stream.

public : unsigned int BytesReceived { get; }public uint BytesReceived { get; }Public ReadOnly Property BytesReceived As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The number of bytes received by the last read operation of the input stream.

CarrierDetectState CarrierDetectState CarrierDetectState CarrierDetectState

Gets the state of the Carrier Detect (CD) line.

public : PlatForm::Boolean CarrierDetectState { get; }public bool CarrierDetectState { get; }Public ReadOnly Property CarrierDetectState As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

Detects the state of Carrier Detect line. If the line is detected, value is true; otherwise, false.

ClearToSendState ClearToSendState ClearToSendState ClearToSendState

Gets the state of the Clear-to-Send (CTS) line.

public : PlatForm::Boolean ClearToSendState { get; }public bool ClearToSendState { get; }Public ReadOnly Property ClearToSendState As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

Detects the state of Clear-to-Send line. If the line is detected, value is true; otherwise, false.

DataBits DataBits DataBits DataBits

The number of data bits in each character value that is transmitted or received, and does not include parity bits or stop bits.

public : ushort DataBits { get; set; }public ushort DataBits { get; set; }Public ReadWrite Property DataBits As ushort// You can use this property in JavaScript.
Value
ushort ushort ushort ushort

The number of data bits in each character value that is transmitted or received.

Remarks

DataBits corresponds to the WordLength member of the SERIAL_LINE_CONTROL structure.

DataSetReadyState DataSetReadyState DataSetReadyState DataSetReadyState

Gets the state of the Data Set Ready (DSR) signal.

public : PlatForm::Boolean DataSetReadyState { get; }public bool DataSetReadyState { get; }Public ReadOnly Property DataSetReadyState As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

Indicates whether DSR has been sent to the serial port. If the signal was sent, value is true; otherwise, false.

Handshake Handshake Handshake Handshake

Gets or sets the handshaking protocol for flow control.

public : SerialHandshake Handshake { get; set; }public SerialHandshake Handshake { get; set; }Public ReadWrite Property Handshake As SerialHandshake// You can use this property in JavaScript.
Value
SerialHandshake SerialHandshake SerialHandshake SerialHandshake

One of the values defined in SerialHandshake enumeration.

Remarks

The handshaking protocol is used by the serial port to establish flow control between the port and the connected device. There are two types of control protocol.

  • Hardware control: The Request-to-Send (RTS) line is set to false when the receiver's buffer is full. This indicates to the sender that it must stop sending data. When the buffer is able to hold data, the RTS line is set to true that indicates to the send that it is now ready to receive data again.
  • Software control: The receiver sends an Xoff control code to the sender to stop transmission of data. When the receiver is ready, it sends the Xon code and the sender resumes data transmission. The SerialHandshake enumeration defines the preceding control type values.

You can set hardware, software, or both types of control protocol.

InputStream InputStream InputStream InputStream

Input stream that contains the data received on the serial port.

public : IInputStream InputStream { get; }public IInputStream InputStream { get; }Public ReadOnly Property InputStream As IInputStream// You can use this property in JavaScript.
Value
IInputStream IInputStream IInputStream IInputStream

Input stream that contains the data received

Remarks

To access data received on the port, get the input stream from SerialDevice object, and then use the DataReader to read data.

IsDataTerminalReadyEnabled IsDataTerminalReadyEnabled IsDataTerminalReadyEnabled IsDataTerminalReadyEnabled

Gets or sets a value that enables the Data Terminal Ready (DTR) signal.

public : PlatForm::Boolean IsDataTerminalReadyEnabled { get; set; }public bool IsDataTerminalReadyEnabled { get; set; }Public ReadWrite Property IsDataTerminalReadyEnabled As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

Enables or disables the Data Terminal Ready (DTR) signal. true enables DTR; Otherwise, false.

IsRequestToSendEnabled IsRequestToSendEnabled IsRequestToSendEnabled IsRequestToSendEnabled

Gets or sets a value that enables the Request to Send (RTS) signal.

public : PlatForm::Boolean IsRequestToSendEnabled { get; set; }public bool IsRequestToSendEnabled { get; set; }Public ReadWrite Property IsRequestToSendEnabled As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

Enables or disables the Request to Send (RTS) signal. true enables DTR; Otherwise, false.

OutputStream OutputStream OutputStream OutputStream

Gets an output stream to which the app can write data to transmit through the serial port.

public : IOutputStream OutputStream { get; }public IOutputStream OutputStream { get; }Public ReadOnly Property OutputStream As IOutputStream// You can use this property in JavaScript.
Value
IOutputStream IOutputStream IOutputStream IOutputStream

The output steam that contains the transfer data.

Remarks

To write data, first get the output stream from the SerialDevice object by using OutputStream property and then use the DataWriter object to write the actual buffer.

Parity Parity Parity Parity

Gets or sets the parity bit for error-checking.

public : SerialParity Parity { get; set; }public SerialParity Parity { get; set; }Public ReadWrite Property Parity As SerialParity// You can use this property in JavaScript.
Value
SerialParity SerialParity SerialParity SerialParity

One of the values defined in SerialParity enumeration.

Remarks

In serial communication, the parity bit is used as an error-checking procedure. In data transmission that uses parity checking, the bit format is 7 data bits-x-1 stop bit, where x is the parity bit. That bit indicates whether the number of 1s in the data byte is even or odd. The parity bit can be E (even), O (odd), M (mark), or S (space). Those values are defined in the SerialParity enumeration.

For example, if the format is 7-E-1 and the data bits are 0001000, the parity bit is set to 1 to make sure there are even number of 1s.

PortName PortName PortName PortName

Gets the port name for serial communications.

public : PlatForm::String PortName { get; }public string PortName { get; }Public ReadOnly Property PortName As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The communication port name. For example "COM1".

ReadTimeout ReadTimeout ReadTimeout ReadTimeout

Gets or sets the time-out value for a read operation.

public : TimeSpan ReadTimeout { get; set; }public TimeSpan ReadTimeout { get; set; }Public ReadWrite Property ReadTimeout As TimeSpan// You can use this property in JavaScript.
Value
TimeSpan TimeSpan TimeSpan TimeSpan

The span of time before a time-out occurs when a read operation does not finish.

StopBits StopBits StopBits StopBits

Gets or sets the standard number of stop bits per byte.

public : SerialStopBitCount StopBits { get; set; }public SerialStopBitCount StopBits { get; set; }Public ReadWrite Property StopBits As SerialStopBitCount// You can use this property in JavaScript.

Remarks

In serial communication, a transmission begins with a start bit, followed by 8 bits of data, and ends with a stop bit. The purpose of the stop bit is to separate each unit of data or to indicate that no data is available for transmission.

UsbProductId UsbProductId UsbProductId UsbProductId

Gets the idProduct field of the USB device descriptor. This value indicates the device-specific product identifier and is assigned by the manufacturer.

public : ushort UsbProductId { get; }public ushort UsbProductId { get; }Public ReadOnly Property UsbProductId As ushort// You can use this property in JavaScript.
Value
ushort ushort ushort ushort

The device-defined product identifier.

UsbVendorId UsbVendorId UsbVendorId UsbVendorId

Gets the idVendor field of the USB device descriptor. The value indicates the vendor identifier for the device as assigned by the USB specification committee.

public : ushort UsbVendorId { get; }public ushort UsbVendorId { get; }Public ReadOnly Property UsbVendorId As ushort// You can use this property in JavaScript.
Value
ushort ushort ushort ushort

The vendor identifier for the device as assigned by the USB specification committee.

WriteTimeout WriteTimeout WriteTimeout WriteTimeout

Gets or sets the time-out value for a write operation.

public : TimeSpan WriteTimeout { get; set; }public TimeSpan WriteTimeout { get; set; }Public ReadWrite Property WriteTimeout As TimeSpan// You can use this property in JavaScript.
Value
TimeSpan TimeSpan TimeSpan TimeSpan

The span of time before a time-out occurs when a write operation does not finish.

Methods

Close() Close() Close() Close()

Releases the reference to the SerialDevice object that was previously obtained by calling FromIdAsync.

public : void Close()This member is not implemented in C#This member is not implemented in VB.Net// You can use this method in JavaScript.

Dispose() Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

This member is not implemented in C++void Dispose()Sub Disposevoid Dispose()

FromIdAsync(String) FromIdAsync(String) FromIdAsync(String) FromIdAsync(String)

Starts an asynchronous operation that creates a SerialDevice object.

public : static IAsyncOperation<SerialDevice> FromIdAsync(PlatForm::String deviceId)public static IAsyncOperation<SerialDevice> FromIdAsync(String deviceId)Public Static Function FromIdAsync(deviceId As String) As IAsyncOperation( Of SerialDevice )// You can use this method in JavaScript.
Parameters
deviceId
PlatForm::String String String String

The device instance path of the device. To obtain that value, get the DeviceInformation.Id property value.

Returns

GetDeviceSelector() GetDeviceSelector() GetDeviceSelector() GetDeviceSelector()

Gets an Advanced Query Syntax (AQS) string that the app can pass to DeviceInformation.FindAllAsync in order to find all serial devices on the system.

public : static PlatForm::String GetDeviceSelector()public static string GetDeviceSelector()Public Static Function GetDeviceSelector() As string// You can use this method in JavaScript.
Returns
PlatForm::String string string string

String formatted as an AQS query.

See Also

GetDeviceSelector(String) GetDeviceSelector(String) GetDeviceSelector(String) GetDeviceSelector(String)

Gets an Advanced Query Syntax (AQS) string that the app can pass to DeviceInformation.FindAllAsync in order to find a serial device by specifying its port name.

public : static PlatForm::String GetDeviceSelector(PlatForm::String portName)public static string GetDeviceSelector(String portName)Public Static Function GetDeviceSelector(portName As String) As string// You can use this method in JavaScript.
Parameters
portName
PlatForm::String String String String

The serial port name. For example, "COM1".

Returns
PlatForm::String string string string

String formatted as an AQS query.

See Also

GetDeviceSelectorFromUsbVidPid(UInt16, UInt16) GetDeviceSelectorFromUsbVidPid(UInt16, UInt16) GetDeviceSelectorFromUsbVidPid(UInt16, UInt16) GetDeviceSelectorFromUsbVidPid(UInt16, UInt16)

Gets an Advanced Query Syntax (AQS) string that the app can pass to DeviceInformation.FindAllAsync in order to find a specific Serial-to-USB device by specifying it's VID and PID.

public : static PlatForm::String GetDeviceSelectorFromUsbVidPid(unsigned short vendorId, unsigned short productId)public static string GetDeviceSelectorFromUsbVidPid(UInt16 vendorId, UInt16 productId)Public Static Function GetDeviceSelectorFromUsbVidPid(vendorId As UInt16, productId As UInt16) As string// You can use this method in JavaScript.
Parameters
vendorId
unsigned short UInt16 UInt16 UInt16

Specifies the vendor identifier for the device as assigned by the USB specification committee. Possible values are 0 through 0xffff.

productId
unsigned short UInt16 UInt16 UInt16

Specifies the product identifier. This value is assigned by the manufacturer and is device-specific. Possible values are 0 through 0xffff.

Returns
PlatForm::String string string string

String formatted as an AQS query.

Examples

This example code shows how to get the SerialDevice object by specifying the vendor/product Id of the Serial-to-USB device.



protected override async void OnLaunched1(LaunchActivatedEventArgs args)
{
    UInt32 vid = 0x045E;
    UInt32 pid = 0x078F;

    string aqs = SerialDevice.GetDeviceSelectorFromUsbVidPid(vid, pid);

    var myDevices = await Windows.Devices.Enumeration.DeviceInformation.FindAllAsync(aqs, null);

    if (myDevices.Count == 0)
    {
        ShowError("Device not found!");
        return;
    }

    SerialDevice device = await SerialDevice.FromIdAsync(myDevices[0].Id);

}

Events

ErrorReceived ErrorReceived ErrorReceived ErrorReceived

Event handler that is invoked when error occurs on the serial port.

public : event TypedEventHandler ErrorReceived<SerialDevice,  ErrorReceivedEventArgs>public event TypedEventHandler ErrorReceived<SerialDevice,  ErrorReceivedEventArgs>Public Event ErrorReceived<SerialDevice,  ErrorReceivedEventArgs>// You can use this event in JavaScript.

Remarks

This event is used to detect and respond to errors when communicating data through a serial port. When an error condition occurs, the ErrorReceived event handler is invoked and error information is received in an ErrorReceivedEventArgs object. Determine the type of error by retrieving the Error property of the ErrorReceivedEventArgs class. Those property values are defined in the SerialError enumeration.

PinChanged PinChanged PinChanged PinChanged

Event handler that is invoked when the state of a signal or line changes on the serial port.

public : event TypedEventHandler PinChanged<SerialDevice,  PinChangedEventArgs>public event TypedEventHandler PinChanged<SerialDevice,  PinChangedEventArgs>Public Event PinChanged<SerialDevice,  PinChangedEventArgs>// You can use this event in JavaScript.

Remarks

This event is used to detect and respond to changes in the signal state of the serial port. When state changes, the PinChanged event handler is invoked and information is received in a PinChangedEventArgs object. Determine the type of signal by retrieving the PinChange property. Those property values are defined in the SerialPinChange enumeration.