SiLA2.SerialPort.Features 10.2.4

SiLA2.SerialPort.Features

A SiLA2 Feature package that exposes serial port communication capabilities via gRPC. This module provides a complete SiLA2 Feature Definition (FDL) and gRPC service implementation for serial port discovery, connection management, and data transfer.

Features

• SiLA2-Compliant Interface: Full FDL-defined feature with gRPC service implementation
• Port Discovery: Enumerate available serial ports with USB device metadata (VID/PID/Serial)
• Connection Management: Connect/disconnect to multiple ports simultaneously
• Text & Binary Transfer: Send text data with configurable encoding or raw binary data
• Observable Properties: Subscribe to real-time updates for available and connected ports
• USB Device Identification: Connect by VID/PID for reliable device identification
• Parameter Constraints: Validated parameters with Set constraints for enums and Unit constraints for timeouts
• Cross-Platform: Windows, Linux, and macOS support

Installation

dotnet add package SiLA2.SerialPort.Features

This package requires SiLA2.Core and SiLA2.SerialPort which will be installed automatically as dependencies.

Quick Start

Register Services

// Program.cs
builder.Services.AddSerialPortManager();
builder.Services.AddSingleton<SerialCommunicationService>();

var app = builder.Build();

// Initialize SiLA2 features
app.InitializeSiLA2Features(siLA2Server);

// Map gRPC service
app.MapGrpcService<SerialCommunicationService>();

Client Usage

// Create channel and client
var channel = GrpcChannel.ForAddress("https://localhost:5001");
var client = new SerialCommunication.SerialCommunicationClient(channel);

// Connect to a port
await client.ConnectAsync(new Connect_Parameters
{
    PortName = new String { Value = "COM3" },
    BaudRate = new Integer { Value = 9600 },
    DataBits = new Integer { Value = 8 },
    StopBits = new String { Value = "One" },
    Parity = new String { Value = "None" }
});

// Send text data with encoding
var textResponse = await client.SendTextDataAsync(new SendTextData_Parameters
{
    PortName = new String { Value = "COM3" },
    Data = new String { Value = "Hello, Device!" },
    Encoding = new String { Value = "UTF-8" }
});
Console.WriteLine($"Sent {textResponse.BytesSent.Value} bytes");

// Send binary data
var binaryResponse = await client.SendBinaryDataAsync(new SendBinaryData_Parameters
{
    PortName = new String { Value = "COM3" },
    Data = new Binary { Value = ByteString.CopyFrom(new byte[] { 0x01, 0x02, 0x03 }) }
});
Console.WriteLine($"Sent {binaryResponse.BytesSent.Value} bytes");

// Read binary data
var readResponse = await client.ReadBinaryDataAsync(new ReadBinaryData_Parameters
{
    PortName = new String { Value = "COM3" },
    MaxBytes = new Integer { Value = 1024 },
    Timeout = new Integer { Value = 5000 }  // 5000 ms
});
Console.WriteLine($"Received {readResponse.Data.Value.Length} bytes");

// Disconnect
await client.DisconnectAsync(new Disconnect_Parameters
{
    PortName = new String { Value = "COM3" }
});

Feature Definition

The SerialCommunication feature (FDL v1.0) provides:

Properties

Commands

Parameter Constraints

The feature uses SiLA2 constraints for input validation:

Defined Execution Errors

Data Types

SerialPortInfo - Structured information about a serial port:

• PortName - System port name (e.g., "COM3", "/dev/ttyUSB0")
• Description - Friendly name or description
• IsAvailable - Whether the port can be opened
• IsConnected - Whether this service has it connected
• VendorId - USB VID (hexadecimal, e.g., "0403")
• ProductId - USB PID (hexadecimal, e.g., "6001")
• SerialNumber - USB device serial number
• Manufacturer - Device manufacturer name

Observable Properties

Subscribe to real-time port updates:

// Subscribe to available ports
using var call = client.Subscribe_AvailablePorts(new Subscribe_AvailablePorts_Parameters());

await foreach (var response in call.ResponseStream.ReadAllAsync())
{
    foreach (var port in response.AvailablePorts)
    {
        Console.WriteLine($"{port.SerialPortInfo.PortName.Value}: " +
                          $"{port.SerialPortInfo.Description.Value}");
    }
}

USB Device Identification

Connect to devices by VID/PID for reliable identification regardless of port assignment:

// Find FTDI devices (VID=0403)
var ftdiPorts = await client.FindPortByUsbIdAsync(new FindPortByUsbId_Parameters
{
    VendorId = new String { Value = "0403" },
    ProductId = new String { Value = "6001" }
});

// Connect by USB ID
var result = await client.ConnectByUsbIdAsync(new ConnectByUsbId_Parameters
{
    VendorId = new String { Value = "0403" },
    ProductId = new String { Value = "6001" },
    SerialNumber = new String { Value = "" },  // Match any
    BaudRate = new Integer { Value = 115200 },
    DataBits = new Integer { Value = 8 },
    StopBits = new String { Value = "One" },
    Parity = new String { Value = "None" }
});

Console.WriteLine($"Connected to port: {result.PortName.Value}");

Text vs Binary Data Transfer

The feature provides two methods for sending data:

SendTextData

Use for string/text data that needs character encoding:

await client.SendTextDataAsync(new SendTextData_Parameters
{
    PortName = new String { Value = "COM3" },
    Data = new String { Value = "MEASURE?" },
    Encoding = new String { Value = "ASCII" }  // or UTF-8, UTF-16, UTF-32, ISO-8859-1
});

SendBinaryData

Use for raw byte transmission:

await client.SendBinaryDataAsync(new SendBinaryData_Parameters
{
    PortName = new String { Value = "COM3" },
    Data = new Binary { Value = ByteString.CopyFrom(new byte[] { 0x02, 0x00, 0x10, 0x03 }) }
});

Server Implementation

To implement the service in your SiLA2 server:

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        // Add SiLA2 services
        builder.Services.AddSingleton<ISiLA2Server, SiLA2Server>();
        builder.Services.AddSerialPortManager();
        builder.Services.AddSingleton<SerialCommunicationService>();
        builder.Services.AddGrpc();

        var app = builder.Build();

        // Initialize SiLA2
        var silaServer = app.Services.GetRequiredService<ISiLA2Server>();
        app.InitializeSiLA2Features(silaServer);

        // Map gRPC services
        app.MapGrpcService<SerialCommunicationService>();

        silaServer.Start();
        app.Run();
    }
}

Feature Definition Location

The SiLA2 Feature Definition XML file is embedded in the assembly:

• Features/SerialCommunication-v1_0.sila.xml

At runtime, copy this file to your output directory or include it as embedded resource.

Related Packages

• SiLA2.SerialPort: Core serial port library (non-gRPC)
• SiLA2.Core: Core SiLA2 server implementation
• SiLA2.AspNetCore: ASP.NET Core integration

Platform Support

• Windows: Full support with native COM port and WMI-based USB enumeration
• Linux: Supported via .NET (ports at /dev/ttyUSB*, /dev/ttyACM*)
• macOS: Supported via .NET (ports at /dev/tty.*)

License

MIT License - See LICENSE file for details.