C# und .NET Neu

C# Modbus TCP und RTU Bibliothek für .NET

Lies und schreibe SPS-Steuerungen, Antriebe und Zähler aus C# oder stelle deine eigenen Daten als Modbus-Slave bereit, über Ethernet oder RS-485.

Modbus TCP und Modbus RTU
Client und Server
Float32, Int32 und Strings in beliebiger Wortreihenfolge
Threadsichere blockierende Aufrufe

Enthalten in sgcWebSockets Enterprise (Delphi und .NET) und All-Access oder im eigenständigen Paket sgcIndustrial.

Ein Gerät in C# lesen und schreiben → · Modbus-FAQ →

C# Modbus TCP Client
using esegece.sgcWebSockets;

var modbus = new TsgcModbusTCPClient();
modbus.Host = "192.168.1.50";
modbus.Port = 502;
modbus.Active = true;

ushort[] registers = modbus.ReadHoldingRegisters(0, 10);  // FC 03
float temperature = modbus.ReadFloat32(200);               // 2 registers
modbus.WriteSingleCoil(5, true);                           // FC 05

Modbus-Clients und -Server für .NET

Vier Komponenten, eine API für TCP und RTU, ein threadsicheres Datenmodell hinter den Servern.

Die C# Modbus Bibliothek in sgcWebSockets .NET befindet sich im Paket esegece.sgcIndustrial, Namespace esegece.sgcWebSockets. TsgcModbusTCPClient und TsgcModbusRTUClient sind Modbus-Master, die Geräte abfragen; TsgcModbusTCPServer und TsgcModbusRTUServer sind Modbus-Slaves, die SCADA-Systemen, HMIs und anderen Mastern aus einem TsgcModbusDataModel antworten. Die serielle Leitung ist ein TsgcSerialPort aus demselben Paket, aufgebaut auf System.IO.Ports.

Beide Clients teilen sich TsgcModbusClient_Base, sodass eine Methode, die ein Register über Ethernet liest, es auch über RS-485 liest. Jeder Aufruf blockiert, bis die Antwort eintrifft oder Timeout abläuft, liefert einfache .NET-Arrays (ushort[] für Register, bool[] für Coils) und löst eine typisierte Exception aus, wenn das Gerät einen Fehler meldet. Das Paket zielt auf .NET 8, .NET 9, .NET 10 und .NET Standard 2.0.

Funktionscodes

01 bis 08, 15, 16, 22, 23 und 43/14, je eine Methode.

Typisierte Werte

ReadFloat32, ReadInt32, ReadUInt32, ReadString und ihre Schreib-Gegenstücke, mit WordOrder für die vier Registerlayouts.

Modbus TCP

Standardmäßig Port 502, mit optionalem TLS, einem HTTP- oder SOCKS-Proxy und automatischer Wiederverbindung.

Modbus RTU

RS-232 und RS-485 mit 3,5-Zeichen-Framing, CRC-Prüfung und Broadcast-Schreibzugriffen.

Modbus in C#, Schritt für Schritt

Referenziere das Paket esegece.sgcIndustrial und wähle dann den Transport. Jedes Beispiel auf dieser Seite lässt sich gegen .NET 8 kompilieren.

using esegece.sgcWebSockets;

var modbus = new TsgcModbusTCPClient();
modbus.Host = "192.168.1.50";
modbus.Port = 502;
modbus.UnitId = 1;
modbus.Timeout = 2000;            // ms per attempt
modbus.Retries = 2;               // extra attempts after a timeout
modbus.WatchDog.Enabled = true;   // reconnect after a network drop
modbus.OnError += (sender, error) => Console.WriteLine("#error: " + error);
modbus.Active = true;

ushort[] registers = modbus.ReadHoldingRegisters(0, 10);       // FC 03
bool[] coils = modbus.ReadCoils(0, 8);                         // FC 01
Console.WriteLine("HR0 = " + registers[0] + ", coil 0 = " + coils[0]);

modbus.WriteSingleRegister(100, 1234);                         // FC 06
modbus.WriteMultipleRegisters(110, new ushort[] { 1, 2, 3 });  // FC 16
modbus.WriteSingleCoil(5, true);                               // FC 05
modbus.WordOrder = TsgcModbusWordOrder.mwoCDAB;   // low word first
float temperature = modbus.ReadFloat32(200);       // 2 holding registers
int counter = modbus.ReadInt32(202);
string name = modbus.ReadString(300, 8);           // 8 registers, 16 characters
Console.WriteLine($"{name}: {temperature:F1} C, {counter} cycles");

modbus.WriteFloat32(210, 21.5f);
modbus.WriteUInt32(212, 3000000000);

// explicit unit id, for a gateway with several devices behind it
float flow = modbus.ReadInputFloat32(7, 0);        // unit 7, FC 04
Console.WriteLine("flow = " + flow);

try
{
    modbus.ReadHoldingRegisters(9000, 4);
}
catch (EsgcModbusException e)   // the device answered with an exception
{
    Console.WriteLine($"exception {e.ExceptionCode}, function {e.FunctionCode}");
}
catch (EsgcModbusTimeout e)     // no answer after Retries + 1 attempts
{
    Console.WriteLine(e.Message);
}
using esegece.sgcWebSockets;

var port = new TsgcSerialPort();
port.Port = "COM3";                              // "/dev/ttyUSB0" on Linux
port.BaudRate = 19200;
port.Parity = TsgcSerialParity.spEven;           // 8E1, the Modbus RTU default
port.Open();

var rtu = new TsgcModbusRTUClient();
rtu.SerialPort = port;
rtu.UnitId = 17;                                 // slave address
rtu.Timeout = 500;
rtu.Retries = 1;

ushort[] values = rtu.ReadInputRegisters(0, 4);  // FC 04
byte status = rtu.ReadExceptionStatus();         // FC 07
Console.WriteLine($"IR0 = {values[0]}, status = {status}");

rtu.WriteSingleRegister(0, 10, 500);             // unit 0: broadcast, no reply
using esegece.sgcWebSockets;

var server = new TsgcModbusTCPServer();
server.Port = 502;
server.UnitId = 0;                                  // answer every unit id
server.DataModel.HoldingRegisterCount = 1000;
server.DataModel.SetHoldingRegister(0, 42);
server.DataModel.SetCoil(0, true);
server.DataModel.VendorName = "My Company";         // FC 43/14 identification
server.DataModel.ProductCode = "GW-100";

var random = new Random();

// runs on the connection thread, before the table is read
server.OnReadRequest += (object sender, byte unitId, byte functionCode,
    ushort address, ushort count, ref byte exceptionCode) =>
{
    if (functionCode == sgcModbus_Classes.CS_MODBUS_FC_READ_INPUT_REGISTERS)
        server.DataModel.SetInputRegister(0, (ushort)random.Next(1000));
};

// registers 0..9 are read only
server.OnWriteRequest += (object sender, byte unitId, byte functionCode,
    ushort address, ushort count, ref bool[] bits, ref ushort[] registers,
    ref byte exceptionCode) =>
{
    if (registers.Length > 0 && address < 10)
        exceptionCode = sgcModbus_Classes.CS_MODBUS_EX_ILLEGAL_DATA_ADDRESS;
};

server.Active = true;
Console.ReadLine();

Die Aufrufe sind synchron. Führe in einer WinForms-, WPF- oder ASP.NET-Anwendung eine Abfrageschleife in einem Worker-Thread oder innerhalb von Task.Run aus; der Client ist threadsicher, sodass mehrere Tasks eine Verbindung gemeinsam nutzen können.

Unterstützte Modbus-Funktionscodes

Der Client prüft die Mengen gegen die Spezifikation, bevor etwas gesendet wird; die Server beantworten jeden Code dieser Tabelle.

FCFunktionC#-Methode
01Read CoilsReadCoils
02Read Discrete InputsReadDiscreteInputs
03Read Holding RegistersReadHoldingRegisters, ReadInt32, ReadUInt32, ReadFloat32, ReadString
04Read Input RegistersReadInputRegisters, ReadInputInt32, ReadInputUInt32, ReadInputFloat32
05Write Single CoilWriteSingleCoil
06Write Single RegisterWriteSingleRegister
07Read Exception Status (serielle Leitung)ReadExceptionStatus am RTU Client
08Diagnostics (serielle Leitung)Diagnostics am RTU Client
15Write Multiple CoilsWriteMultipleCoils
16Write Multiple RegistersWriteMultipleRegisters, WriteInt32, WriteUInt32, WriteFloat32, WriteString
22Mask Write RegisterMaskWriteRegister
23Read/Write Multiple RegistersReadWriteMultipleRegisters
43/14Read Device IdentificationReadDeviceIdentification mit TsgcModbusDeviceIdCode basic, regular, extended oder specific

Ein Modbus-Master für den Produktiveinsatz

Wortreihenfolge

TsgcModbusWordOrder.mwoABCD ist Big Endian, der Modbus-Standard. mwoCDAB stellt das niederwertige Wort voran, mwoBADC vertauscht die Bytes in jedem Register und mwoDCBA ist vollständig Little Endian. Strings packen zwei Zeichen pro Register.

Threadsicher

Pro Client läuft jeweils eine Transaktion, unter einer Sperre, die alle Wiederholungen abdeckt. Bei TCP wird die Antwort vom Empfangs-Thread zugeordnet und an den wartenden Aufruf übergeben, sodass ein Aufruf aus einem UI-Thread keinen Deadlock auslösen kann.

Timeouts und Wiederholungen

Timeout ist die Wartezeit pro Versuch, Retries die zusätzlichen Versuche. Eine TCP-Wiederholung verwendet eine neue Transaktions-ID, und veraltete oder doppelte Antworten werden verworfen.

Typisierte Exceptions

EsgcModbusException enthält ExceptionCode und FunctionCode, EsgcModbusTimeout meldet eine fehlende Antwort, und EsgcModbusError deckt geschlossene Verbindungen, Portprobleme und RTU-CRC-Fehler ab.

Gateways und Unit-IDs

Jede Methode hat eine Überladung mit einem vorangestellten byte aUnitId, sodass eine TCP-Verbindung zu einem Gateway jedes dahinter liegende Gerät erreicht.

TLS, Proxy und Wiederverbindung

TLS, TLSOptions, Proxy und WatchDog werden an den darunterliegenden sgcWebSockets TCP-Client weitergereicht, sodass Modbus TCP denselben TLS-Stack, dieselbe Proxy-Unterstützung und dieselbe automatische Wiederverbindung erhält wie der Rest der Bibliothek.

RTU-Framing

Der RTU-Client wartet vor dem Senden auf die Stille von 3,5 Zeichen, liest die Antwort anhand ihrer erwarteten Länge, prüft die CRC jedes Frames und ignoriert Frames von anderen Slave-Adressen. Die Unit-ID 0 sendet einen Broadcast-Schreibzugriff und wartet TurnaroundDelay statt auf eine Antwort.

RS-485-Richtung

Mit RtsControl = TsgcSerialRtsControl.srcToggle setzt der serielle Port RTS bei jedem Schreibvorgang und nimmt es zurück, wenn der Ausgangspuffer geleert ist. In .NET wird das per Software getaktet, daher ist für ein striktes Bus-Timing ein Adapter mit automatischer Richtungssteuerung vorzuziehen.

Ereignisse

OnConnect, OnDisconnect und OnError werden über NotifyEvents ausgelöst, in der Reihenfolge, in der sie aufgetreten sind. Ein fehlgeschlagener Verbindungsaufbau wirft keine Exception: Er löst OnError aus, und Active bleibt false.

Modbus TCP und RTU Server in C#

Baue ein Gateway, das Datenbank- oder Cloud-Werte für ein SCADA-System bereitstellt, einen Simulator, um HMI-Bildschirme ohne Hardware zu testen, oder die Modbus-Schnittstelle deines eigenen Geräts. Jeder Server besitzt ein TsgcModbusDataModel mit den vier Tabellen (Coils, Discrete Inputs, Holding Registers und Input Registers, standardmäßig je 10.000 Einträge und bis zu 65.536), den Identifikationsstrings für FC 43/14 und dem Exception-Status für FC 07. Jedes Mitglied des Datenmodells ist threadsicher.

OnReadRequest läuft, bevor eine Tabelle gelesen wird, und kann so Werte aktualisieren oder mit einem Exception-Code antworten. OnWriteRequest erhält die Werte, bevor sie gespeichert werden, und kann sie ändern oder den Schreibzugriff ablehnen, wobei die Tabellen unberührt bleiben. Beide laufen in dem Server-Thread, der die Anfrage bearbeitet (die TCP-Verbindung oder der RTU-Frame-Reader), ohne gehaltene Sperre.

TsgcModbusTCPServer

Viele gleichzeitige Verbindungen, Anfragen werden in der Reihenfolge ihres Eintreffens beantwortet, aufgeteilte Anfragen werden wieder zusammengesetzt, und fehlerhafte Header schließen die Verbindung mit OnError. UnitId = 0 beantwortet jede Unit-ID. Bindings wählen die Endpunkte, Port = 0 wählt einen freien Port, und OnClientConnect und OnClientDisconnect melden Gegenstellen.

TsgcModbusRTUServer

Antwortet als Slave UnitId (1 bis 247) an einem TsgcSerialPort, rahmt Anfragen anhand der Länge und der Stille von 3,5 Zeichen, ignoriert fehlerhafte CRCs und andere Adressen und führt Broadcast-Schreibzugriffe ohne Antwort aus.

In beide Richtungen getestet

Der .NET-Client und -Server bestehen dieselben Interoperabilitätsprüfungen gegen pymodbus über TCP und gegen die Delphi Modbus Komponenten von sgcWebSockets, in jeder Richtung 35 von 35.

Teil von sgcWebSockets Enterprise

Die Modbus- und Serial-Port-Komponenten sind in sgcWebSockets Enterprise (Delphi und .NET) und All-Access enthalten, als Paket esegece.sgcIndustrial neben den anderen sgcWebSockets .NET Paketen. Vergleiche die Editionen auf der Preisseite (Registerkarte .NET) oder in der .NET-Funktionsmatrix.

Fragen zu C# Modbus

Erstelle einen TsgcModbusTCPClient, setze Host, Port und UnitId, setze Active = true und rufe ReadHoldingRegisters(address, count) auf. Es liefert ein ushort[] mit einem Wert pro Register. Adressen sind nullbasiert, so wie sie über die Leitung gehen.

Rufe ReadFloat32(address) für Holding Registers oder ReadInputFloat32(address) für Input Registers auf. Sieht die Zahl falsch aus, speichert das Gerät die beiden Register in einer anderen Reihenfolge: Setze WordOrder auf mwoCDAB, mwoBADC oder mwoDCBA.

Ja. Öffne einen TsgcSerialPort am RS-485-Adapter und weise ihn TsgcModbusRTUClient.SerialPort oder TsgcModbusRTUServer.SerialPort zu. Verwende einen Adapter mit automatischer Richtungssteuerung oder setze RtsControl auf srcToggle für Adapter, die per RTS umgeschaltet werden.

Ja. Erstelle einen TsgcModbusTCPServer, fülle DataModel mit SetHoldingRegister, SetCoil und den anderen Settern und setze Active = true. Behandle OnReadRequest und OnWriteRequest, um Werte bei Bedarf zu berechnen oder Schreibzugriffe mit einem Modbus-Exception-Code abzulehnen.

Nein, die Client-Methoden sind synchron und threadsicher. Rufe sie aus einem Worker-Thread auf oder verpacke sie in Task.Run; mehrere Threads oder Tasks können einen Client gemeinsam nutzen, und jeder Aufruf wartet auf seine eigene Antwort.

Das Paket esegece.sgcIndustrial zielt auf .NET 8, .NET 9, .NET 10 und .NET Standard 2.0. Der serielle Port verwendet System.IO.Ports, daher benötigt Modbus RTU eine Plattform, auf der dieses Paket serielle Ports öffnen kann.

Die Modbus- und Serial-Port-Komponenten sind in sgcWebSockets Enterprise (Delphi und .NET) und All-Access oder im eigenständigen Paket sgcIndustrial enthalten.

Mehr zu sgcWebSockets .NET

Industrielle Komponenten

Serial Port, Modbus und OPC UA, mit der vollständigen Komponentenreferenz.

C# OPC UA Client

Lies, schreibe und abonniere OPC UA Server aus derselben .NET-Anwendung, neben den Modbus-Geräten.

C# MQTT Client

Veröffentliche Modbus-Messwerte aus derselben Anwendung an einen MQTT-Broker.

C# WebSocket Bibliothek

WebSocket-Client und -Server für Dashboards, die Live-Gerätedaten anzeigen.

Auch für Delphi und C++Builder

Dieselben Modbus-Komponenten mit denselben Klassennamen und Methoden, für Delphi 7 bis Delphi 13.

Bestes Preis-Leistungs-Verhältnis: All-AccessAlle eSeGeCe-Produkte, inklusive Premium-Support, ab €1,059 pro Jahr.
All-Access-Preise ansehen

Lies dein erstes Modbus-Register aus C#

Enthalten in sgcWebSockets Enterprise (Delphi und .NET) und All-Access oder im eigenständigen Paket sgcIndustrial.