portdic 1.1.77

PortDic

PortDic is a comprehensive .NET library for industrial automation and communication systems. It provides standardized methods for interacting with industrial automation systems, equipment control, and data acquisition with support for multiple communication protocols.

About

PortDic package provides a complete framework for building industrial automation applications with:

• Annotation-Based Package System: Declarative programming model using attributes for package registration, API generation, and dependency injection
• Workflow and Flow Control: Sequential and parallel workflow execution with timing control
• Protocol Integration: Support for SECS/GEM, MQTT, RTSP, and OPC UA protocols
• Real-time Data Management: Type-safe data setting and retrieval with event-driven architecture
• Broadcasting System: Multi-protocol communication management
• REST API Generation: Automatic endpoint creation from annotations
• Simple Communication Classes: High-performance asynchronous serial port and TCP communication with automatic reconnection

All features are designed for production use with comprehensive error handling, validation, and thread-safe operations.

Key Features

Annotation System

PortDic uses a comprehensive annotation system for declarative programming:

Core Capabilities

• Real-time Data Exchange: Type-safe data setting and retrieval with automatic type conversion
• Event-Driven Architecture: Comprehensive event handling for status changes and system occurrences
• Package Injection: Automatic dependency resolution and inter-package communication
• Flow Control: Complex workflow management with sequential and parallel execution
• Protocol Support: Industrial communication protocols (SECS/GEM, OPC UA, MQTT, RTSP)
• Configuration Builder: Fluent interface for protocol configuration
• Performance Monitoring: Built-in profiling and monitoring capabilities

Simple Communication Classes

• AsyncSerial: Abstract base class for asynchronous serial port communication with automatic reconnection
• AsyncTCPServer: Production-ready asynchronous TCP server with client management and 24/7 stability
• AsyncTCPClient: High-availability asynchronous TCP client with automatic reconnection
• RingBuffer<T>: Lock-free, zero-allocation ring buffer for high-performance scenarios

How to Use

Initialization and Setup

using portdic;

private static IPortDic port = Port.GetDictionary("sample");

public Form()
{
    InitializeComponent();

    // Event handlers
    port.OnOccurred += Port_OnOccurred;
    port.OnStatusChanged += Port_OnStatusChanged;

    // Start the Port system
    port.Run();
}

Event Handling

Status Change Events

private void Port_OnStatusChanged(object sender, PortStatusArgs e)
{
    switch (e.Status)
    {
        case PortStauts.Initializing:
            break;
        case PortStauts.Running: 
            break;
        case PortStauts.Stopped:
            break;
        case PortStauts.Shutdown:
            break;
        case PortStauts.Failed:
            break;
    }
}

Occurrence Events

private void Port_OnOccurred(object sender, PortEventArgs e)
{
    switch (e.EventType)
    {
        default:
            Console.WriteLine(e.Message);
            break;
    }
}

Package Development with Annotations

Basic Package Example

using portpackage;
using portdatatype;

[Package(typeof(Heater))]
public class Heater
{
    [API(EntryDataType.String, "OnOff")]
    [Comment("Heater power state")]
    public string BulbOnOff { get; set; } = "Off";

    [API(EntryDataType.Float, "Celsius")]
    [Comment("Current temperature")]
    public float RoomTemp1 { get; set; }

    [Valid("Invalid heater state")]
    public bool Valid()
    {
        return BulbOnOff == "On" || BulbOnOff == "Off";
    }
}

Workflow with Flow Control

[Flow(typeof(ProcessFlow))]
public class ProcessFlow
{
    [FlowControl]
    public IFlowControl Flow { get; set; }

    [StepTimer]
    public IStepTimer Timer { get; set; }

    [Step(1, "StartProcess")]
    public void Initialize()
    {
        // Initialization logic
        Flow.Next();
    }

    [Step(2, "ProcessData")]
    public void Process()
    {
        // Processing logic
        Timer.Wait(1000); // Wait 1 second
        Flow.Next();
    }

    [Step(3, "CompleteProcess")]
    public void Complete()
    {
        // Completion logic
    }
}

SET/GET Operations

// Setting values
var ok = port.Set("room1", "BulbOnOff", "On");
if (ok)
{
    Console.WriteLine("ok");
}

// Getting values - returns 'On'
Console.WriteLine(port.Get("room1", "BulbOnOff").Text());

// Alternative syntax
port["room1"].Set("BulbOnOff", "Off");

// Getting values - returns 'Off'
Console.WriteLine(port.Get("room1", "BulbOnOff").Text());

Protocol Integration

GEM (SECS/GEM) Integration

var gem = portdic.BroadCast<GEM>(Port.CreateBuilder(BroadcastType.GEM)
    .Mode(Mode.Active)
    .Listen("127.0.0.1:5000")
    .DeviceID("EQ001")
    .T1(10).T2(5).T3(10)
    .Build());

MQTT Integration

var mqtt = portdic.BroadCast<MQTT>(Port.CreateBuilder(BroadcastType.MQTT)
    .Listen("127.0.0.1:1883")
    .Users(new User("admin", "admin"))
    .AllowRemotes("127.0.0.1")
    .ClientId("PortClient")
    .QoS(1)
    .Build());

OPC UA Integration

var opcua = portdic.BroadCast<OPCUA>(Port.CreateBuilder(BroadcastType.OPCUA)
    .Listen("opc.tcp://localhost:4840")
    .ApplicationInfo("PortApp", "urn:PortApp", "urn:PortApp")
    .SecurityConfig(SecurityMode.SignAndEncrypt, SecurityPolicy.Basic256Sha256)
    .Credentials("admin", "password")
    .Build());

Simple Communication Classes

Serial Port Communication

using portdic.simple;

public class MySerial : AsyncSerial
{
    public MySerial()
    {
        portName = "COM3";
        baudRate = 9600;
        delimiter = "\n";

        this.DataReceived += (sender, message) => 
        {
            Console.WriteLine($"Received: {message}");
        };
        this.ReconnectSuccess += (sender, e) => 
        {
            Console.WriteLine("Reconnected successfully");
        };
    }

    public override void LogWrite(string log)
    {
        Console.WriteLine(log);
    }
}

// Usage
var serial = new MySerial();
await serial.ConnectAsync();
await serial.SendAsync("Hello World!");

TCP Server

using portdic.simple;

public class MyTCPServer : AsyncTCPServer
{
    public MyTCPServer()
    {
        this.port = "5000";
        this.ClientConnected += (sender, client) => 
        {
            Console.WriteLine($"Client connected: {client.RemoteEndPoint}");
        };
        this.DataReceived += async (sender, data) => 
        {
            Console.WriteLine($"Received from {data.Client.Id}: {data.Message}");
            await this.SendToClientAsync(data.Client, "Echo: " + data.Message);
        }; 
        // Usage
        await server.StartAsync();

        // Broadcast to all clients
        await server.BroadcastAsync("Server message");
    }

    public override void LogWrite(string log)
    {
        Console.WriteLine(log);
    }
}

TCP Client

using portdic.simple;

public class MyTCPClient : AsyncTCPClient
{
    public MyTCPClient() 
    {
        this.host = "127.0.0.1";
        this.port = "5000";

        await client.ConnectAsync();
        await client.SendAsync("Hello Server!");
        this.Connected += (sender, e) => 
        {
            Console.WriteLine("Connected to server");
        };
        this.DataReceived += (sender, message) => 
        {
            Console.WriteLine($"Received: {message}");
        };
        this.ReconnectSuccess += (sender, e) => 
        {
            Console.WriteLine("Reconnected successfully");
        };
    }

    public override void LogWrite(string log)
    {
        Console.WriteLine(log);
    }
}

 

Ring Buffer

using portdic.simple;
using System.Text;

// Create a ring buffer with capacity (must be power of 2)
var buffer = new RingBuffer<byte>(1024);

// Producer: Write data
byte[] data = Encoding.UTF8.GetBytes("Hello");
int written = buffer.Write(data);

// Consumer: Read data
byte[] output = new byte[1024];
int bytesRead = buffer.Read(output);
string message = Encoding.UTF8.GetString(output, 0, bytesRead);

// Single item operations
if (buffer.TryWrite(0x42))
{
    if (buffer.TryRead(out byte value))
    {
        Console.WriteLine($"Read: {value}");
    }
}

// Peek without consuming
if (buffer.TryPeek(out byte peekValue))
{
    Console.WriteLine($"Peeked: {peekValue}");
}

Main Types

The main types provided by this library are:

Core Types

• IPortDic: Main interface for port dictionary communication, real-time data exchange, and protocol management
• Port: Factory class for creating port dictionary instances
• PortDic: Core implementation of the port dictionary system

Annotation Attributes

• [Package]: Attribute for marking classes as Port-managed packages
• [Flow]: Attribute for defining workflow classes
• [API]: Attribute for automatic REST API endpoint generation
• [Step]: Attribute for marking workflow steps
• [Import]: Attribute for dependency injection
• [Property]: Attribute for mapping properties to Entry Properties
• [Valid]: Attribute for data validation and business rules
• [Command]: Attribute for marking methods as command endpoints

Interfaces

• IFlowControl: Interface for workflow control and navigation
• IStepTimer: Interface for timing and scheduling workflow steps
• IReference: Interface for function references and collections

Simple Communication Classes

• AsyncSerial: Abstract base class for asynchronous serial port communication with automatic reconnection
• AsyncTCPServer: Production-ready asynchronous TCP server with client management and 24/7 stability
• AsyncTCPClient: High-availability asynchronous TCP client with automatic reconnection
• ClientContext: Represents the context for a connected TCP client, including connection information and message buffering
• RingBuffer<T>: Lock-free, zero-allocation ring buffer for high-performance scenarios. Thread-safe for single producer and single consumer operations

Additional Documentation

• PortDic .NET Integration Guide - Comprehensive documentation with examples
• System.IO.Ports Documentation
• System.Net.Sockets Documentation

Requirements

• .NET Standard 2.0 or higher
• System.IO.Ports package (for serial port functionality)

Related Packages

• System.IO.Ports - Required for serial port functionality

Feedback & Contributing

PortDic is released as open source. Bug reports and contributions are welcome. Please report issues and submit pull requests through the project repository.

For additional support and examples, refer to the PortDic Documentation.

License

Please refer to the license file included with this package for license information.