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
| 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
- 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.
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".
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.
- Pass the retrieved string to FindAllAsync. The call retrieves a DeviceInformationCollection object.
- Loop through the collection. Each iteration gets a DeviceInformation object.
- 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.
- 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.
- Obtain a reference to the input stream by getting the SerialDevice.InputStream property.
Create a DataReader object by specifying the input stream in the DataReader constructor.
Obtain a reference to the output stream by getting the SerialDevice.OutputStream property.
- 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.
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.
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.
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.
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.
One of the values defined in the SerialStopBitCount enumeration.
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.
- deviceId
- PlatForm::String String String String
The device instance path of the device. To obtain that value, get the DeviceInformation.Id property value.
Returns an IAsyncOperation(SerialDevice) object that returns the results of the operation.
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.
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.
- portName
- PlatForm::String String String String
The serial port name. For example, "COM1".
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.
- 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.
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.