nanoFramework.System.IO.Ports 1.0.3-preview.14

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
This is a prerelease version of nanoFramework.System.IO.Ports.
There is a newer version of this package available.
See the version list below for details.
dotnet add package nanoFramework.System.IO.Ports --version 1.0.3-preview.14
NuGet\Install-Package nanoFramework.System.IO.Ports -Version 1.0.3-preview.14
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="nanoFramework.System.IO.Ports" Version="1.0.3-preview.14" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add nanoFramework.System.IO.Ports --version 1.0.3-preview.14
#r "nuget: nanoFramework.System.IO.Ports, 1.0.3-preview.14"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install nanoFramework.System.IO.Ports as a Cake Addin
#addin nuget:?package=nanoFramework.System.IO.Ports&version=1.0.3-preview.14&prerelease

// Install nanoFramework.System.IO.Ports as a Cake Tool
#tool nuget:?package=nanoFramework.System.IO.Ports&version=1.0.3-preview.14&prerelease

Quality Gate Status Reliability Rating License NuGet #yourfirstpr Discord

nanoFramework logo


Welcome to the .NET nanoFramework System.IO.Ports Library repository

Build status

Component Build Status NuGet Package
System.IO.Ports Build Status NuGet
System.IO.Ports (preview) Build Status NuGet

Usage

You will find detailed examples in the Tests.

Creating the SerialPort

You can create the SerialPort like this:

var port = new SerialPort("COM2");

Note that the port name must be COMx where x is a number.

The GetPortNames method will gi you a list of available ports:

var ports = SerialPort.GetPortNames();

You can as well directly specify the baud rate and other elements in the constructor:

var port = new SerialPort("COM2", 115200);

Each property can be adjusted, including while the port is open. Be aware that this can generate hazardous behaviors. It is always recommended to change the properties once the port is closed.

Important: you should setup a timeout for the read and write operations. If you have none, while operating a read or a write, you will wait indefinitely to read or write that everything is received or sent.

port.WriteTimeout = 1000;
port.ReadTimeout = 1000;

Note: some MCU do not support Hankshake or specific bit parity even if you can set them up in the constructor.

Opening and Closing the port

The port can only be in operation once open and will finish his operations when closed. If you dispose the SerialPort, it will close it before.

var port = new SerialPort("COM2");
port.Open();
// Do a lot of things here, write, read
port.Close();

Read and Write

You have multiple functions to read and write, some are byte related, others string related. Note that the string one will use the Enconding charset that you will define. By default, this is UTF8.

Sending and receiving bytes

Example of sending and reading byte arrays:

byte[] toSend = new byte[] { 0x42, 0xAA, 0x11, 0x00 };
byte[] toReceive = new byte[50];
// this will send the 4 bytes:
port.Write(toSend, 0, toSend.Length);
// This will only send the bytes AA and 11:
port.Write(toSend, 1, 2);
// This will check then number of available bytes to read
var numBytesToRead = port.BytesToRead;
// This will read 50 characters:
port.Read(toReceive, 0, toReceive.Length);
// this will read 10 characters and place them at the offset position 3:
port.Read(toReceive, 3, 10);
// Note: in case of time out while reading or writing, you will receive a TimeoutException
// And you can as well read a single byte:
byte oneByte = port.ReadByte();
Sending and receiving string

You can as well write and read strings:

string toSend = "I ❤ nanoFramework";
port.WriteLine(toSend);
// this will send the string encoded finishing by a new line, by default \r\n
// You can change the new line by anything:
port.NewLine = "❤❤";
// Now it will send the 2 hearts as the end of line while operating a ReadLine or WriteLine
// You can ad anytime change it back:
port.NewLine = SerialPort.DefaultNewLine; // default is "\r\n"
// This will read the existing buffer:
string existingString = port.ReadExisting();
// Note that if it can't properly convert the bytes to a string, you'll get an exception
// This will read a full line, it has to be terminated by the NewLine string.
// If nothing is found ending by the NewLine in the ReadTimeout time frame, a TimeoutException will be raised.
string aFullLine = port.ReadLine();

Events

SerialPort supports events when characters are received.

    // Subscribe to the event
    port.DataReceived += DataReceivedNormalEvent;

    // When you're done, you can as well unsubscribe
    port.DataReceived -= DataReceivedNormalEvent;

private void DataReceivedNormalEvent(object sender, SerialDataReceivedEventArgs e)
{
    var ser = (SerialPort)sender;
    // Now you can check how many characters are available, read a line for example
    var numBytesToRead = port.BytesToRead;
    string aFullLine = ser.ReadLine();
}
Case of WatchChar

.NET nanoFramework has a specific API to watch for a specific character if present at the end of the transmission.

    port.WatchChar = '\r';
    // Subscribe to the event
    port.DataReceived += DataReceivedNormalEvent;

private void DataReceivedNormalEvent(object sender, SerialDataReceivedEventArgs e)
{
    if (e.EventType == SerialData.WatchChar)
    {
        // We have our special character at the end of the transmission
    }
}

Feedback and documentation

For documentation, providing feedback, issues and finding out how to contribute please refer to the Home repo.

Join our Discord community here.

Credits

The list of contributors to this project can be found at CONTRIBUTORS.

License

The nanoFramework Class Libraries are licensed under the MIT license.

Code of Conduct

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behaviour in our community. For more information see the .NET Foundation Code of Conduct.

.NET Foundation

This project is supported by the .NET Foundation.

Product Compatible and additional computed target framework versions.
.NET Framework net is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (20)

Showing the top 5 NuGet packages that depend on nanoFramework.System.IO.Ports:

Package Downloads
nanoFramework.M5Core2 The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

This package includes the nanoFramework.M5Core2 assembly for .NET nanoFramework C# projects.

nanoFramework.M5Core The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

This package includes the nanoFramework.M5Core assembly for .NET nanoFramework C# projects.

nanoFramework.Fire The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

This package includes the nanoFramework.Fire assembly for .NET nanoFramework C# projects.

nanoFramework.Logging.Serial The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

This package includes the nanoFramework.Logging.Serial assembly (Serial Logging only) for .NET nanoFramework C# projects. There is also a package with the Stream Logging only and another with the basic Debug Logging.

nanoFramework.Tough The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

This package includes the nanoFramework.Tough assembly for .NET nanoFramework C# projects.

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on nanoFramework.System.IO.Ports:

Repository Stars
nanoframework/Samples
🍬 Code samples from the nanoFramework team used in testing, proof of concepts and other explorational endeavours
nanoframework/nanoFramework.IoT.Device
📦 This repo includes .NET nanoFramework implementations for various sensors, chips, displays, hats and drivers
Version Downloads Last updated
1.1.78 4,027 11/9/2023
1.1.75 118 11/9/2023
1.1.60 23,901 12/28/2022
1.1.57 303 12/28/2022
1.1.54 295 12/27/2022
1.1.46 12,338 10/26/2022
1.1.44 3,040 10/25/2022
1.1.42 675 10/25/2022
1.1.40 911 10/24/2022
1.1.38 718 10/24/2022
1.1.36 972 10/23/2022
1.1.34 2,941 10/22/2022
1.1.31 6,208 10/9/2022
1.1.29 2,737 10/8/2022
1.1.25 12,084 9/15/2022
1.1.22 737 9/15/2022
1.1.18 415 9/15/2022
1.1.16 740 9/15/2022
1.1.6 17,385 8/4/2022
1.1.4 398 8/3/2022
1.1.2 406 8/3/2022
1.0.7.12 384 8/3/2022
1.0.7.10 33,218 6/16/2022
1.0.7.8 6,543 6/13/2022
1.0.7.6 1,059 6/8/2022
1.0.7.1 11,390 5/26/2022
1.0.6.1 410 5/26/2022
1.0.4 32,245 3/29/2022
1.0.4-preview.3 135 3/29/2022
1.0.3 775 3/28/2022
1.0.3-preview.46 121 3/28/2022
1.0.3-preview.44 130 3/28/2022
1.0.3-preview.42 124 3/28/2022
1.0.3-preview.39 291 3/17/2022
1.0.3-preview.37 220 3/14/2022
1.0.3-preview.35 134 3/14/2022
1.0.3-preview.33 380 2/24/2022
1.0.3-preview.29 213 2/17/2022
1.0.3-preview.25 240 2/8/2022
1.0.3-preview.23 332 2/5/2022
1.0.3-preview.21 137 2/4/2022
1.0.3-preview.18 317 1/28/2022
1.0.3-preview.16 177 1/28/2022
1.0.3-preview.14 145 1/28/2022
1.0.3-preview.12 310 1/21/2022
1.0.3-preview.10 152 1/21/2022
1.0.3-preview.8 145 1/21/2022
1.0.3-preview.6 270 1/12/2022
1.0.3-preview.4 262 12/29/2021
1.0.3-preview.3 143 12/28/2021
1.0.2 1,859 12/3/2021
1.0.2-preview.3 152 12/3/2021
1.0.1 295 12/2/2021
1.0.1-preview.31 151 12/2/2021
1.0.1-preview.29 147 12/2/2021
1.0.1-preview.27 141 12/2/2021
1.0.1-preview.25 154 12/2/2021
1.0.1-preview.21 216 11/4/2021
1.0.1-preview.19 256 11/2/2021
1.0.1-preview.17 192 10/23/2021
1.0.1-preview.15 150 10/22/2021
1.0.1-preview.13 442 10/18/2021
1.0.1-preview.11 373 9/29/2021
1.0.1-preview.9 292 9/26/2021
1.0.1-preview.3 1,126 7/17/2021
1.0.0 8,270 7/16/2021
1.0.0-preview.54 158 7/16/2021
1.0.0-preview.52 173 7/15/2021
1.0.0-preview.50 185 7/14/2021
1.0.0-preview.44 620 6/26/2021
1.0.0-preview.42 213 6/20/2021
1.0.0-preview.40 186 6/18/2021
1.0.0-preview.35 213 6/8/2021
1.0.0-preview.33 209 6/7/2021
1.0.0-preview.31 289 6/5/2021
1.0.0-preview.29 174 6/4/2021
1.0.0-preview.27 407 6/2/2021
1.0.0-preview.25 197 6/1/2021
1.0.0-preview.23 212 5/31/2021
1.0.0-preview.21 210 5/30/2021
1.0.0-preview.19 165 5/29/2021
1.0.0-preview.17 171 5/27/2021
1.0.0-preview.15 161 5/26/2021
1.0.0-preview.12 163 5/24/2021