C# e .NET Novo

Biblioteca C# Modbus TCP e RTU para .NET

Leia e grave CLPs, inversores e medidores a partir de C#, ou sirva seus próprios dados como escravo Modbus, via Ethernet ou RS-485.

Modbus TCP e Modbus RTU
Cliente e servidor
Float32, Int32 e strings em qualquer ordem de palavras
Chamadas bloqueantes thread-safe

Incluído no sgcWebSockets Enterprise (Delphi e .NET) e All-Access, ou no pacote independente sgcIndustrial.

Leia e grave um dispositivo em C# → · FAQ de Modbus →

Cliente Modbus TCP para C#
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

Clientes e servidores Modbus para .NET

Quatro componentes, uma única API para TCP e RTU, um modelo de dados thread safe por trás dos servidores.

A biblioteca C# Modbus do sgcWebSockets .NET fica no pacote esegece.sgcIndustrial, namespace esegece.sgcWebSockets. TsgcModbusTCPClient e TsgcModbusRTUClient são mestres Modbus que consultam dispositivos; TsgcModbusTCPServer e TsgcModbusRTUServer são escravos Modbus que respondem a sistemas SCADA, IHMs e outros mestres a partir de um TsgcModbusDataModel. A linha serial é um TsgcSerialPort do mesmo pacote, construído sobre System.IO.Ports.

Os dois clientes compartilham TsgcModbusClient_Base, então um método que lê um registrador via Ethernet também o lê via RS-485. Cada chamada bloqueia até a resposta chegar ou Timeout expirar, retorna arrays .NET simples (ushort[] para registradores, bool[] para coils) e lança uma exceção tipada quando o dispositivo informa um erro. O pacote tem como alvo .NET 8, .NET 9, .NET 10 e .NET Standard 2.0.

Códigos de função

01 a 08, 15, 16, 22, 23 e 43/14, um método para cada.

Valores tipados

ReadFloat32, ReadInt32, ReadUInt32, ReadString e seus equivalentes de gravação, com WordOrder para os quatro layouts de registradores.

Modbus TCP

Porta 502 por padrão, com TLS opcional, proxy HTTP ou SOCKS e reconexão automática.

Modbus RTU

RS-232 e RS-485 com enquadramento de 3,5 caracteres, verificação de CRC e gravações broadcast.

Modbus em C#, passo a passo

Referencie o pacote esegece.sgcIndustrial e escolha o transporte. Todos os exemplos desta página compilam com .NET 8.

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();

As chamadas são síncronas. Em uma aplicação WinForms, WPF ou ASP.NET, execute um loop de consulta em uma thread de trabalho ou dentro de Task.Run; o cliente é thread safe, então várias tasks podem compartilhar uma conexão.

Códigos de função Modbus suportados

O cliente verifica as quantidades conforme a especificação antes de enviar qualquer coisa; os servidores respondem a todos os códigos desta tabela.

FCFunçãoMétodo C#
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 (linha serial)ReadExceptionStatus no cliente RTU
08Diagnostics (linha serial)Diagnostics no cliente RTU
15Write Multiple CoilsWriteMultipleCoils
16Write Multiple RegistersWriteMultipleRegisters, WriteInt32, WriteUInt32, WriteFloat32, WriteString
22Mask Write RegisterMaskWriteRegister
23Read/Write Multiple RegistersReadWriteMultipleRegisters
43/14Read Device IdentificationReadDeviceIdentification com TsgcModbusDeviceIdCode basic, regular, extended ou specific

Um mestre Modbus feito para produção

Ordem de palavras

TsgcModbusWordOrder.mwoABCD é big endian, o padrão do Modbus. mwoCDAB coloca a palavra baixa primeiro, mwoBADC troca os bytes de cada registrador e mwoDCBA é totalmente little endian. As strings empacotam dois caracteres por registrador.

Thread safe

Uma transação é executada por vez em cada cliente, sob um lock que cobre todas as suas tentativas. No TCP a resposta é associada pela thread de recepção e entregue à chamada em espera, então uma chamada feita a partir de uma thread de UI não causa deadlock.

Timeouts e novas tentativas

Timeout é a espera por tentativa e Retries as tentativas extras. Uma nova tentativa TCP usa um novo id de transação, e respostas antigas ou duplicadas são descartadas.

Exceções tipadas

EsgcModbusException traz ExceptionCode e FunctionCode, EsgcModbusTimeout informa uma resposta ausente, e EsgcModbusError cobre conexões fechadas, problemas de porta e erros de CRC no RTU.

Gateways e ids de unidade

Todo método tem uma sobrecarga com um byte aUnitId inicial, de modo que uma única conexão TCP com um gateway alcança todos os dispositivos atrás dele.

TLS, proxy e reconexão

TLS, TLSOptions, Proxy e WatchDog são repassados ao cliente TCP do sgcWebSockets por baixo, de modo que o Modbus TCP recebe a mesma pilha TLS, o mesmo suporte a proxy e a mesma reconexão automática do restante da biblioteca.

Enquadramento RTU

O cliente RTU espera o silêncio de 3,5 caracteres antes de enviar, lê a resposta pelo comprimento esperado, verifica o CRC de cada quadro e ignora quadros de outros endereços de escravo. O unit id 0 envia uma gravação broadcast e espera TurnaroundDelay em vez de uma resposta.

Direção do RS-485

Com RtsControl = TsgcSerialRtsControl.srcToggle a porta serial sobe o RTS a cada gravação e o derruba quando o buffer de saída é esvaziado. No .NET isso é temporizado por software, então para uma temporização rigorosa do barramento prefira um adaptador com controle automático de direção.

Eventos

OnConnect, OnDisconnect e OnError são disparados por meio de NotifyEvents, na ordem em que ocorreram. Uma conexão que falha não levanta exceção: ela dispara OnError e Active continua false.

Servidores Modbus TCP e RTU em C#

Construa um gateway que expõe valores de banco de dados ou da nuvem a um sistema SCADA, um simulador para testar telas de IHM sem hardware, ou a interface Modbus do seu próprio dispositivo. Cada servidor possui um TsgcModbusDataModel com as quatro tabelas (coils, discrete inputs, holding registers e input registers, 10.000 entradas cada por padrão e até 65.536), as strings de identificação para o FC 43/14 e o status de exceção para o FC 07. Todo membro do modelo de dados é thread safe.

OnReadRequest é executado antes da leitura de uma tabela, então pode atualizar valores ou responder com um código de exceção. OnWriteRequest recebe os valores antes de serem armazenados e pode alterá-los ou rejeitar a gravação, deixando as tabelas intactas. Os dois são executados na thread do servidor que trata a requisição (a conexão TCP ou o leitor de quadros RTU), sem nenhum lock mantido.

TsgcModbusTCPServer

Muitas conexões simultâneas, requisições respondidas na ordem de chegada, requisições fragmentadas remontadas e cabeçalhos malformados fechando a conexão com OnError. UnitId = 0 responde a qualquer unit id. Bindings seleciona os endpoints, Port = 0 escolhe uma porta livre, e OnClientConnect e OnClientDisconnect informam os pares conectados.

TsgcModbusRTUServer

Responde como escravo UnitId (1 a 247) em um TsgcSerialPort, delimita requisições pelo comprimento e pelo silêncio de 3,5 caracteres, ignora CRCs inválidos e outros endereços, e executa gravações broadcast sem responder.

Testado nos dois sentidos

O cliente e o servidor .NET passam nas mesmas verificações de interoperabilidade contra o pymodbus via TCP e contra os componentes Modbus Delphi do sgcWebSockets, 35 de 35 em cada direção.

Parte do sgcWebSockets Enterprise

Os componentes Modbus e de porta serial estão incluídos no sgcWebSockets Enterprise (Delphi e .NET) e All-Access, como o pacote esegece.sgcIndustrial ao lado dos demais pacotes do sgcWebSockets .NET. Compare as edições na página de preços (aba .NET) ou na matriz de recursos .NET.

Perguntas sobre C# Modbus

Crie um TsgcModbusTCPClient, defina Host, Port e UnitId, defina Active = true e chame ReadHoldingRegisters(address, count). Ele retorna um ushort[] com um valor por registrador. Os endereços começam em zero, como trafegam no fio.

Chame ReadFloat32(address) para holding registers ou ReadInputFloat32(address) para input registers. Se o número parecer errado, o dispositivo armazena os dois registradores em outra ordem: defina WordOrder como mwoCDAB, mwoBADC ou mwoDCBA.

Sim. Abra um TsgcSerialPort no adaptador RS-485 e atribua-o a TsgcModbusRTUClient.SerialPort ou TsgcModbusRTUServer.SerialPort. Use um adaptador com controle automático de direção, ou defina RtsControl como srcToggle para adaptadores comutados por RTS.

Sim. Crie um TsgcModbusTCPServer, preencha DataModel com SetHoldingRegister, SetCoil e os demais setters, e defina Active = true. Trate OnReadRequest e OnWriteRequest para calcular valores sob demanda ou rejeitar gravações com um código de exceção Modbus.

Não, os métodos do cliente são síncronos e thread safe. Chame-os de uma thread de trabalho ou envolva-os em Task.Run; várias threads ou tasks podem compartilhar um cliente, e cada chamada espera pela sua própria resposta.

O pacote esegece.sgcIndustrial tem como alvo .NET 8, .NET 9, .NET 10 e .NET Standard 2.0. A porta serial usa System.IO.Ports, então o Modbus RTU exige uma plataforma onde esse pacote consiga abrir portas seriais.

Os componentes Modbus e de porta serial estão incluídos no sgcWebSockets Enterprise (Delphi e .NET) e All-Access, ou no pacote independente sgcIndustrial.

Mais sobre o sgcWebSockets .NET

Componentes industriais

Porta serial, Modbus e OPC UA, com a referência completa dos componentes.

Cliente OPC UA para C#

Leia, grave e assine servidores OPC UA a partir da mesma aplicação .NET, ao lado dos dispositivos Modbus.

Cliente MQTT para C#

Publique leituras Modbus em um broker MQTT a partir da mesma aplicação.

Biblioteca WebSocket para C#

Cliente e servidor WebSocket para dashboards que mostram dados de dispositivos em tempo real.

Também para Delphi e C++Builder

Os mesmos componentes Modbus, com os mesmos nomes de classes e métodos, para Delphi 7 a Delphi 13.

Melhor custo-benefício: All-AccessTodos os produtos da eSeGeCe, com Suporte Premium incluído, a partir de €1,059/ano.
Ver preços do All-Access

Leia seu primeiro registrador Modbus a partir de C#

Incluído no sgcWebSockets Enterprise (Delphi e .NET) e All-Access, ou no pacote independente sgcIndustrial.