modbus

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 18, 2025 License: BSD-3-Clause Imports: 12 Imported by: 0

README

go modbus Build Status GoDoc

Fault-tolerant, fail-fast implementation of Modbus protocol in Go.

Supported functions

Bit access:

  • Read Discrete Inputs
  • Read Coils
  • Write Single Coil
  • Write Multiple Coils

16-bit access:

  • Read Input Registers
  • Read Holding Registers
  • Write Single Register
  • Write Multiple Registers
  • Read/Write Multiple Registers
  • Mask Write Register
  • Read FIFO Queue

Supported formats

  • Modbus TCP/UDP
  • Modbus RTU/ASCII (Serial)
  • Modbus RTU/ASCII over TCP
  • Modbus RTU/ASCII over UDP

Example

// Modbus TCP
handler := modbus.NewTCPClientHandler("localhost:502")
handler.SlaveId = 0xFF
handler.Logger = log.New(os.Stdout, "test: ", log.LstdFlags)
err := handler.Connect()
defer handler.Close()

client := modbus.NewClient(handler)

// Modbus UDP
handler := modbus.NewUDPClientHandler("localhost:502")
handler.SlaveId = 0xFF
handler.Logger = log.New(os.Stdout, "test: ", log.LstdFlags)
err := handler.Connect()
defer handler.Close()

// Modbus RTU Serial
handler := modbus.NewRTUClientSerialHandler("/dev/ttyUSB0")
handler.BaudRate = 115200
handler.DataBits = 8
handler.Parity = "N"
handler.StopBits = 1
handler.SlaveId = 1
handler.Timeout = 5 * time.Second

err := handler.Connect()
defer handler.Close()

client := modbus.NewClient(handler)

// Modbus RTU over TCP
handler := modbus.NewTCPClientHandler("localhost:502")
handler.SlaveId = 0xFF
handler.Logger = log.New(os.Stdout, "test: ", log.LstdFlags)
// Connect manually so that multiple requests are handled in one connection session
err := handler.Connect()
defer handler.Close()

client := modbus.NewClient(handler)

// Modbus ASCII Serial
handler := modbus.NewASCIIClientSerialHandler("/dev/ttyUSB0")
handler.BaudRate = 115200
handler.DataBits = 8
handler.Parity = "N"
handler.StopBits = 1
handler.SlaveId = 1
handler.Timeout = 5 * time.Second

err := handler.Connect()
defer handler.Close()

client := modbus.NewClient(handler)

// Modbus ASCII over TCP
handler := modbus.NewASCIIClientTcpHandler("/dev/ttyUSB0")
handler.BaudRate = 115200
handler.DataBits = 8
handler.Parity = "N"
handler.StopBits = 1
handler.SlaveId = 1
handler.Timeout = 5 * time.Second

err := handler.Connect()
defer handler.Close()

client := modbus.NewClient(handler)

References

Documentation

Overview

Package modbus provides a client for MODBUS TCP and RTU/ASCII.

Index

Constants

View Source 
const (
	// Bit access
	FuncCodeReadDiscreteInputs = 2
	FuncCodeReadCoils          = 1
	FuncCodeWriteSingleCoil    = 5
	FuncCodeWriteMultipleCoils = 15

	// 16-bit access
	FuncCodeReadInputRegisters         = 4
	FuncCodeReadHoldingRegisters       = 3
	FuncCodeWriteSingleRegister        = 6
	FuncCodeWriteMultipleRegisters     = 16
	FuncCodeReadWriteMultipleRegisters = 23
	FuncCodeMaskWriteRegister          = 22
	FuncCodeReadFIFOQueue              = 24
)
View Source 
const (
	ExceptionCodeIllegalFunction                    = 1
	ExceptionCodeIllegalDataAddress                 = 2
	ExceptionCodeIllegalDataValue                   = 3
	ExceptionCodeServerDeviceFailure                = 4
	ExceptionCodeAcknowledge                        = 5
	ExceptionCodeServerDeviceBusy                   = 6
	ExceptionCodeMemoryParityError                  = 8
	ExceptionCodeGatewayPathUnavailable             = 10
	ExceptionCodeGatewayTargetDeviceFailedToRespond = 11
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ASCIIClientSerialHandler 

type ASCIIClientSerialHandler struct {
	// contains filtered or unexported fields
}

ASCIIClientSerialHandler implements Packager and Transporter interface.

func NewASCIIClientSerialHandler 

func NewASCIIClientSerialHandler(address string) *ASCIIClientSerialHandler

func (*ASCIIClientSerialHandler) Decode 

func (mb *ASCIIClientSerialHandler) Decode(adu []byte) (pdu *ProtocolDataUnit, err error)

Decode extracts PDU from ASCII frame and verify LRC.

func (*ASCIIClientSerialHandler) Encode 

func (mb *ASCIIClientSerialHandler) Encode(pdu *ProtocolDataUnit) (adu []byte, err error)

Encode encodes PDU in a ASCII frame: 

Start           : 1 char
Address         : 2 chars
Function        : 2 chars
Data            : 0 up to 2x252 chars
LRC             : 2 chars
End             : 2 chars

func (*ASCIIClientSerialHandler) Send 

func (mb *ASCIIClientSerialHandler) Send(aduRequest []byte) (aduResponse []byte, err error)

func (*ASCIIClientSerialHandler) Verify 

func (mb *ASCIIClientSerialHandler) Verify(aduRequest []byte, aduResponse []byte) (err error)

Verify verifies response length, frame boundary and slave id.

type ASCIIClientTcpHandler 

type ASCIIClientTcpHandler struct {
	// contains filtered or unexported fields
}

ASCIIClientTcpHandler 用来增加tcp ASCII

func NewASCIIClientTcpHandler 

func NewASCIIClientTcpHandler(address string) *ASCIIClientTcpHandler

NewASCIIClientTcpHandler allocates and initializes a ASCIIClientHandler.

func (*ASCIIClientTcpHandler) Decode 

func (mb *ASCIIClientTcpHandler) Decode(adu []byte) (pdu *ProtocolDataUnit, err error)

Decode extracts PDU from ASCII frame and verify LRC.

func (*ASCIIClientTcpHandler) Encode 

func (mb *ASCIIClientTcpHandler) Encode(pdu *ProtocolDataUnit) (adu []byte, err error)

Encode encodes PDU in a ASCII frame: 

Start           : 1 char
Address         : 2 chars
Function        : 2 chars
Data            : 0 up to 2x252 chars
LRC             : 2 chars
End             : 2 chars

func (*ASCIIClientTcpHandler) Send 

func (mb *ASCIIClientTcpHandler) Send(aduRequest []byte) (aduResponse []byte, err error)

func (*ASCIIClientTcpHandler) Verify 

func (mb *ASCIIClientTcpHandler) Verify(aduRequest []byte, aduResponse []byte) (err error)

Verify verifies response length, frame boundary and slave id.

type ASCIIClientUdpHandler added in v1.1.0 

type ASCIIClientUdpHandler struct {
	// contains filtered or unexported fields
}

ASCIIClientUdpHandler implements Packager and Transporter interface.

func NewASCIIClientUdpHandler added in v1.1.0 

func NewASCIIClientUdpHandler(address string) *ASCIIClientUdpHandler

NewASCIIClientUdpHandler allocates and initializes a ASCIIClientUdpHandler.

func (*ASCIIClientUdpHandler) Decode added in v1.1.0 

func (mb *ASCIIClientUdpHandler) Decode(adu []byte) (pdu *ProtocolDataUnit, err error)

Decode extracts PDU from ASCII frame and verify LRC.

func (*ASCIIClientUdpHandler) Encode added in v1.1.0 

func (mb *ASCIIClientUdpHandler) Encode(pdu *ProtocolDataUnit) (adu []byte, err error)

Encode encodes PDU in a ASCII frame: 

Start           : 1 char
Address         : 2 chars
Function        : 2 chars
Data            : 0 up to 2x252 chars
LRC             : 2 chars
End             : 2 chars

func (*ASCIIClientUdpHandler) Send added in v1.1.0 

func (mb *ASCIIClientUdpHandler) Send(aduRequest []byte) (aduResponse []byte, err error)

func (*ASCIIClientUdpHandler) Verify added in v1.1.0 

func (mb *ASCIIClientUdpHandler) Verify(aduRequest []byte, aduResponse []byte) (err error)

Verify verifies response length, frame boundary and slave id.

type Client 

type Client interface {

	// ReadCoils reads from 1 to 2000 contiguous status of coils in a
	// remote device and returns coil status.
	ReadCoils(address, quantity uint16) (results []byte, err error)
	// ReadDiscreteInputs reads from 1 to 2000 contiguous status of
	// discrete inputs in a remote device and returns input status.
	ReadDiscreteInputs(address, quantity uint16) (results []byte, err error)
	// WriteSingleCoil write a single output to either ON or OFF in a
	// remote device and returns output value.
	WriteSingleCoil(address, value uint16) (results []byte, err error)
	// WriteMultipleCoils forces each coil in a sequence of coils to either
	// ON or OFF in a remote device and returns quantity of outputs.
	WriteMultipleCoils(address, quantity uint16, value []byte) (results []byte, err error)

	// ReadInputRegisters reads from 1 to 125 contiguous input registers in
	// a remote device and returns input registers.
	ReadInputRegisters(address, quantity uint16) (results []byte, err error)
	// ReadHoldingRegisters reads the contents of a contiguous block of
	// holding registers in a remote device and returns register value.
	ReadHoldingRegisters(address, quantity uint16) (results []byte, err error)
	// WriteSingleRegister writes a single holding register in a remote
	// device and returns register value.
	WriteSingleRegister(address, value uint16) (results []byte, err error)
	// WriteMultipleRegisters writes a block of contiguous registers
	// (1 to 123 registers) in a remote device and returns quantity of
	// registers.
	WriteMultipleRegisters(address, quantity uint16, value []byte) (results []byte, err error)
	// ReadWriteMultipleRegisters performs a combination of one read
	// operation and one write operation. It returns read registers value.
	ReadWriteMultipleRegisters(readAddress, readQuantity, writeAddress, writeQuantity uint16, value []byte) (results []byte, err error)
	// MaskWriteRegister modify the contents of a specified holding
	// register using a combination of an AND mask, an OR mask, and the
	// register's current contents. The function returns
	// AND-mask and OR-mask.
	MaskWriteRegister(address, andMask, orMask uint16) (results []byte, err error)
	//ReadFIFOQueue reads the contents of a First-In-First-Out (FIFO) queue
	// of register in a remote device and returns FIFO value register.
	ReadFIFOQueue(address uint16) (results []byte, err error)
}

func ASCIIClient 

func ASCIIClient(address, network string) Client

ASCIIClient creates ASCII client with default handler and given connect string.

func NewClient 

func NewClient(handler ClientHandler) Client

NewClient creates a new modbus client with given backend handler.

func NewClient2 

func NewClient2(packager Packager, transporter Transporter) Client

NewClient2 creates a new modbus client with given backend packager and transporter.

func RTUClient 

func RTUClient(address, network string) Client

RTUClient creates RTU client with default handler and given connect string.

func TCPClient 

func TCPClient(address string) Client

TCPClient creates TCP client with default handler and given connect string.

type ClientHandler 

type ClientHandler interface {
	Packager
	Transporter
}

ClientHandler is the interface that groups the Packager and Transporter methods.

type ModbusError 

type ModbusError struct {
	FunctionCode  byte
	ExceptionCode byte
}

ModbusError implements error interface.

func (*ModbusError) Error 

func (e *ModbusError) Error() string

Error converts known modbus exception code to error message.

type Packager 

type Packager interface {
	Encode(pdu *ProtocolDataUnit) (adu []byte, err error)
	Decode(adu []byte) (pdu *ProtocolDataUnit, err error)
	Verify(aduRequest []byte, aduResponse []byte) (err error)
}

Packager specifies the communication layer.

type ProtocolDataUnit 

type ProtocolDataUnit struct {
	FunctionCode byte
	Data         []byte
}

ProtocolDataUnit (PDU) is independent of underlying communication layers.

type RTUClientSerialHandler 

type RTUClientSerialHandler struct {
	// contains filtered or unexported fields
}

func NewRTUClientSerialHandler 

func NewRTUClientSerialHandler(address string) *RTUClientSerialHandler

NewRTUClientSerialHandler allocates and initializes a RTUClientSerialHandler.

func (*RTUClientSerialHandler) Decode 

func (mb *RTUClientSerialHandler) Decode(adu []byte) (pdu *ProtocolDataUnit, err error)

Decode extracts PDU from RTU frame and verify CRC.

func (*RTUClientSerialHandler) Encode 

func (mb *RTUClientSerialHandler) Encode(pdu *ProtocolDataUnit) (adu []byte, err error)

Encode encodes PDU in a RTU frame: 

Slave Address   : 1 byte
Function        : 1 byte
Data            : 0 up to 252 bytes
CRC             : 2 byte

func (*RTUClientSerialHandler) Send 

func (mb *RTUClientSerialHandler) Send(aduRequest []byte) (aduResponse []byte, err error)

func (*RTUClientSerialHandler) Verify 

func (mb *RTUClientSerialHandler) Verify(aduRequest []byte, aduResponse []byte) (err error)

Verify verifies response length and slave id.

type RTUClientTcpHandler 

type RTUClientTcpHandler struct {
	// contains filtered or unexported fields
}

RTUClientTcpHandler implements Packager and Transporter interface.

func NewRTUClientTcpHandler 

func NewRTUClientTcpHandler(address string) *RTUClientTcpHandler

NewRTUClientTcpHandler allocates and initializes a RTUClientTcpHandler.

func (*RTUClientTcpHandler) Decode 

func (mb *RTUClientTcpHandler) Decode(adu []byte) (pdu *ProtocolDataUnit, err error)

Decode extracts PDU from RTU frame and verify CRC.

func (*RTUClientTcpHandler) Encode 

func (mb *RTUClientTcpHandler) Encode(pdu *ProtocolDataUnit) (adu []byte, err error)

Encode encodes PDU in a RTU frame: 

Slave Address   : 1 byte
Function        : 1 byte
Data            : 0 up to 252 bytes
CRC             : 2 byte

func (*RTUClientTcpHandler) Send 

func (mb *RTUClientTcpHandler) Send(aduRequest []byte) (aduResponse []byte, err error)

func (*RTUClientTcpHandler) Verify 

func (mb *RTUClientTcpHandler) Verify(aduRequest []byte, aduResponse []byte) (err error)

Verify verifies response length and slave id.

type RTUClientUdpHandler added in v1.1.0 

type RTUClientUdpHandler struct {
	// contains filtered or unexported fields
}

RTUClientUdpHandler implements Packager and Transporter interface.

func NewRTUClientUdpHandler added in v1.1.0 

func NewRTUClientUdpHandler(address string) *RTUClientUdpHandler

NewRTUClientUdpHandler allocates and initializes a RTUClientUdpHandler.

func (*RTUClientUdpHandler) Decode added in v1.1.0 

func (mb *RTUClientUdpHandler) Decode(adu []byte) (pdu *ProtocolDataUnit, err error)

Decode extracts PDU from RTU frame and verify CRC.

func (*RTUClientUdpHandler) Encode added in v1.1.0 

func (mb *RTUClientUdpHandler) Encode(pdu *ProtocolDataUnit) (adu []byte, err error)

Encode encodes PDU in a RTU frame: 

Slave Address   : 1 byte
Function        : 1 byte
Data            : 0 up to 252 bytes
CRC             : 2 byte

func (*RTUClientUdpHandler) Send added in v1.1.0 

func (mb *RTUClientUdpHandler) Send(aduRequest []byte) ([]byte, error)

Send 发送RTU请求，并等待响应（UDP协议版）

func (*RTUClientUdpHandler) Verify added in v1.1.0 

func (mb *RTUClientUdpHandler) Verify(aduRequest []byte, aduResponse []byte) (err error)

Verify verifies response length and slave id.

type TCPClientHandler 

type TCPClientHandler struct {
	// contains filtered or unexported fields
}

TCPClientHandler implements Packager and Transporter interface.

func NewTCPClientHandler 

func NewTCPClientHandler(address string) *TCPClientHandler

NewTCPClientHandler allocates a new TCPClientHandler.

func (*TCPClientHandler) Close 

func (mb *TCPClientHandler) Close() error

Close closes current connection.

func (*TCPClientHandler) Connect 

func (mb *TCPClientHandler) Connect() error

Connect establishes a new connection to the address in Address. Connect and Close are exported so that multiple requests can be done with one session

func (*TCPClientHandler) Decode 

func (mb *TCPClientHandler) Decode(adu []byte) (pdu *ProtocolDataUnit, err error)

Decode extracts PDU from TCP frame: 

Transaction identifier: 2 bytes
Protocol identifier: 2 bytes
Length: 2 bytes
Unit identifier: 1 byte

func (*TCPClientHandler) Encode 

func (mb *TCPClientHandler) Encode(pdu *ProtocolDataUnit) (adu []byte, err error)

Encode adds modbus application protocol header: 

Transaction identifier: 2 bytes
Protocol identifier: 2 bytes
Length: 2 bytes
Unit identifier: 1 byte
Function code: 1 byte
Data: n bytes

func (*TCPClientHandler) Send 

func (mb *TCPClientHandler) Send(aduRequest []byte) (aduResponse []byte, err error)

Send sends data to server and ensures response length is greater than header length.

func (*TCPClientHandler) Verify 

func (mb *TCPClientHandler) Verify(aduRequest []byte, aduResponse []byte) (err error)

Verify confirms transaction, protocol and unit id.

type Transporter 

type Transporter interface {
	Send(aduRequest []byte) (aduResponse []byte, err error)
}

Transporter specifies the transport layer.

type UDPClientHandler added in v1.1.0 

type UDPClientHandler struct {
	// contains filtered or unexported fields
}

UDPClientHandler 实现了类似tcpClientHandler的功能，但基于UDP无连接协议

func NewUDPClientHandler added in v1.1.0 

func NewUDPClientHandler(address string) *UDPClientHandler

NewUDPClientHandler 创建udp客户端处理器

func (*UDPClientHandler) Close added in v1.1.0 

func (mb *UDPClientHandler) Close() error

Close 关闭UDP连接

func (*UDPClientHandler) Connect added in v1.1.0 

func (mb *UDPClientHandler) Connect() error

Connect 建立UDP连接

func (*UDPClientHandler) Decode added in v1.1.0 

func (p *UDPClientHandler) Decode(adu []byte) (*ProtocolDataUnit, error)

Decode 解析Modbus UDP响应，提取PDU

func (*UDPClientHandler) Encode added in v1.1.0 

func (p *UDPClientHandler) Encode(pdu *ProtocolDataUnit) ([]byte, error)

Encode 构造Modbus UDP ADU(包括应用头和PDU)

func (*UDPClientHandler) Send added in v1.1.0 

func (mb *UDPClientHandler) Send(aduRequest []byte) (aduResponse []byte, err error)

Send 发送数据包并读取响应，实现Transporter接口

func (*UDPClientHandler) Verify added in v1.1.0 

func (p *UDPClientHandler) Verify(aduRequest []byte, aduResponse []byte) (err error)

Verify 确认请求和响应的事务ID、协议ID和单元 ID 是否匹配

Source Files

View all Source files

Directories

Path Synopsis
commw32 command
Port of commw32.c To generate go types: go tool cgo commw32.go
 Port of commw32.c To generate go types: go tool cgo commw32.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.