rskibbe.IO.Ports – Async helper methods for SerialPort communication in .NET

What is this package about?

rskibbe.IO.Ports is a simple package to extend SerialPort communication by adding some async helper methods. It will also help you implementing some kind of „request<>response“-pattern and other small useful methods.

A word about wording – lol?

Okay, before we get started into the package, we first need to talk a bit about wording. The „NewLine“ property could bring to your mind, that you actually have to use some sort of newline, but this isn’t the case. It rather means some sort of „message terminator“, which should separate „messages“ from each other (inside the SerialPort stream). This doesn’t come from my package, it’s coming from the default implementation of the SerialPort itself. So I just picked up that property to make use of – as it felt more natural / better, without changes.

Quick example – Getting started

Without annoying your further with texts, we will instantly dive into a quick example. If you need more details, just skip specific sections and hop to the ones you need most.

Step 1 – Install the package

To get started, install the corresponding package, first. Open the NuGet Package Manager and execute the following commands. You could also use the NuGet-UI for this.

Install-Package rskibbe.IO.Ports

Step 2 – Importing the namespace

Next, you need to import the namespace where needed:

// somewhere up in your file
using rskibbe.IO.Ports;

' somewhere up in your file
Imports rskibbe.IO.Ports

Step 3 – Creating a SerialPort instance

As this package mainly extends the .NET SerialPort functionality, you first need to create an instance of a SerialPort. You can then use the added methods by just calling them (keep in mind, that you need the import/using statement!).

// create serial port instance
var serialPort = new SerialPort("COM3", 9600, Parity.None, 8, StopBits.One);

// setting (only) newline without carriage return as line / message terminator
serialPort.NewLine = "\n";

' create serial port instance
Dim serialPort = New SerialPort("COM3", 9600, Parity.None, 8, StopBits.One)

' setting (only) newline without carriage return as line / message terminator
serialPort.NewLine = vbLf

Ready to go

After setting up a general SerialPort in the previous step, you can now start using the following examples.

Reading a simple line async

// reading the data till newline terminator - but not inclusive!
var data = await serialPort.ReadLineAsync();
  
// do something with the data..

' reading the data till newline terminator - but not inclusive!
Dim data = Await serialPort.ReadLineAsync()
  
' do something with the data..

Writing a simple line async

// create some string-data to be sent
var myData = "A message to com device";
 
// sends the string data with ending NewLine terminator
await serialPort.WriteLineAsync(myData);

' create some string-data to be sent
Dim myData = "A message to com device"
    
' sends the string data with ending NewLine terminator
Await serialPort.WriteLineAsync(myData)

Doing a simple request <> response communication

// create some command to be sent
var cmd = "MOVE:30:30";

// send the command and retrieve the response in one step
var response = await serialPort.RequestResponseAsync(cmd);

// process the response somehow..

' create some command to be sent
Dim cmd = "MOVE:30:30"

' send the command and retrieve the response in one step
Dim response = Await serialPort.RequestResponseAsync(cmd)

' process the response somehow..

Functions / Methods overview

Installing this package and importing / using the corresponding namespace, will enable the following methods / functions. Keep in mind, to actually set a correct NewLine Property on the SerialPort instance itself. Otherwise the functions may not work as you would expect.

ReadLineAsync

Read all data bytewise as string, till a NewLine occurence is being found. This functions return value, does not include the NewLine String itself.

ReadLineAsync(CancellationToken)

Same as above, but with the possibility to provide a CancellationToken.

WriteLineAsync(String)

Writes the target String into the stream, followed by the specified SerialPorts instance NewLine property value as message terminator. This function will also Flush the Stream async.

RequestResponseAsync(String)

Many SerialPort devices are built to work with a Request->Response-alike mechanism. Use this function to send some string data and to get the response right afterwards. Is the same as using WriteLineAsync first and then getting the response by ReadLineAsync manually.

RequestResponseAsync(String, CancellationToken)

Same as above, but with the possibility to provide a CancellationToken.