README
¶
pcore
pcore is a lightweight, flexible framework for building industrial protocol clients and servers. It provides a minimalist set of interfaces and utilities to simplify the development of industrial communication protocols like Modbus, S7, OPC UA, and more.
Features
- Protocol-agnostic design with clear separation of concerns
- Simple, composable interfaces for different communication patterns
- Transport-agnostic design supporting TCP, UDP, serial, and more
- Extensible error handling with protocol-specific errors
- Context support for timeout and cancellation
- Clean, idiomatic Go API
Installation
go get github.com/jon-ski/pcore
Core Concepts
pcore is built around a few key abstractions:
- Frame: The basic unit of data in a protocol
- Protocol: Handles encoding/decoding of frames
- Conn: Manages the connection to a device
- Client: High-level API for protocol-specific operations
The design is intentionally minimal to provide flexibility while avoiding unnecessary abstraction.
Extending pcore
The framework is designed to be easily extended:
- Create your own Frame implementation for your protocol
- Implement the Protocol interface for encoding/decoding
- Create a client that uses these components
Adding a New Protocol
Here's how you might implement a simple S7 protocol client:
package s7
import (
"github.com/jon-ski/pcore"
)
// S7Frame implements pcore.Frame for S7 protocol
type S7Frame struct {
pcore.BaseFrame
// S7-specific fields
}
// S7Protocol implements pcore.Protocol for S7
type S7Protocol struct {
// Configuration fields
}
// Implement Encode, Decode, and Validate methods
// S7Client provides S7-specific functionality
type S7Client struct {
conn pcore.Conn
protocol *S7Protocol
}
// Implement S7-specific methods like ReadDB, WriteDB, etc.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Index ¶
- Variables
- func ReadUint16(data []byte) (uint16, error)
- func ReadUint32(data []byte) (uint32, error)
- func ReadUint64(data []byte) (uint64, error)
- func ReadUint8(data []byte, offset int) (uint8, error)
- type BaseFrame
- type Client
- type Conn
- type ConnError
- type Frame
- type Protocol
- type ProtocolError
- type StreamConn
- type TCPConn
- func (t *TCPConn) Close() error
- func (t *TCPConn) IsOpen() bool
- func (t *TCPConn) Open() error
- func (t *TCPConn) Read(p []byte) (n int, err error)
- func (t *TCPConn) Send(data []byte) ([]byte, error)
- func (t *TCPConn) SendWithTimeout(data []byte, timeout time.Duration) ([]byte, error)
- func (t *TCPConn) Write(p []byte) (n int, err error)
- type TCPProvider
- type TransportOptions
- type TransportProvider
Constants ¶
This section is empty.
Variables ¶
var ( ErrConnClosed = errors.New("connection is closed") ErrConnTimeout = errors.New("connection timed out") ErrInvalidMessage = errors.New("invalid message format") ErrInvalidResponse = errors.New("invalid response") ErrProtocolError = errors.New("protocol error") ErrFrameTooLarge = errors.New("frame exceeds maximum allowed size") ErrFrameTooSmall = errors.New("frame is too small to be valid") ErrInvalidChecksum = errors.New("invalid checksum") ErrDeviceError = errors.New("device reported an error") ErrBufferTooSmall = errors.New("buffer is too small") )
Common errors that may occur in protocol communications
Functions ¶
func ReadUint16 ¶
ReadUint16 reads a uint16 from the buffer at the given offset (big endian)
func ReadUint32 ¶
ReadUint32 reads a uint32 from the buffer at the given offset (big endian)
func ReadUint64 ¶
Types ¶
type BaseFrame ¶
type BaseFrame struct {
// contains filtered or unexported fields
}
BaseFrame implements the basic Frame interface
func NewBaseFrame ¶
NewBaseFrame creates a new base frame
func (*BaseFrame) MarshalBinary ¶
MarshalBinary returns the data portion of `BaseFrame` and nil.
type Client ¶
type Client interface {
// Connect establishes connection to the target
Connect() error
// Disconnect closes the connection
Disconnect() error
// IsConnected returns connection status
IsConnected() bool
}
Client defines a base client interface
type Conn ¶
type Conn interface {
io.ReadWriter
// Open establishes the connection
Open() error
// Close terminates the connection
Close() error
// IsOpen returns connection status
IsOpen() bool
// Send sends data and returns a response
Send(data []byte) ([]byte, error)
// SendWithTimeout sends data with a timeout
SendWithTimeout(data []byte, timeout time.Duration) ([]byte, error)
}
Conn represents a basic connection to a device or system
type ConnError ¶
ConnError represents a connection-related error
func NewConnError ¶
NewConnError creates a new connection error
type Frame ¶
type Frame interface {
encoding.BinaryMarshaler
encoding.BinaryUnmarshaler
// Size returns the size in bytes of the encoded frame. It calls
// `MarshalBinary()` and if it returns an error, Size will return
// -1.
Size() int
// Type returns the frame type/function identifier
Type() int
}
type ProtocolError ¶
ProtocolError represents a protocol-specific error
func NewProtocolError ¶
func NewProtocolError(code int, message string, inner error) *ProtocolError
NewProtocolError creates a new protocol error
func (*ProtocolError) Error ¶
func (e *ProtocolError) Error() string
func (*ProtocolError) Unwrap ¶
func (e *ProtocolError) Unwrap() error
Unwrap returns the unwrapped error
type StreamConn ¶
type TCPConn ¶
type TCPConn struct {
// contains filtered or unexported fields
}
TCPConn implements a TCP connection
func NewTCPConn ¶
NewTCPConn creates a new TCP connection
func (*TCPConn) SendWithTimeout ¶
SendWithTimeout sends data with a timeout
type TCPProvider ¶
type TCPProvider struct{}
TCPProvider implements TransportProvider for TCP
func (*TCPProvider) CreateConn ¶
func (p *TCPProvider) CreateConn(options TransportOptions) (Conn, error)
CreateConn creates a new TCP connection
type TransportOptions ¶
type TransportOptions struct {
// Address is the target address (e.g., IP:port, COM port)
Address string
// Timeout is the default I/O timeout
Timeout time.Duration
// RetryCount is the number of retries on failure
RetryCount int
// RetryDelay is the delay between retries
RetryDelay time.Duration
// MaxFrameSize is the maximum allowed frame size
MaxFrameSize int
}
TransportOptions defines common transport configuration
func DefaultTransportOptions ¶
func DefaultTransportOptions() TransportOptions
type TransportProvider ¶
type TransportProvider interface {
// CreateConn creates a new connection
CreateConn(options TransportOptions) (Conn, error)
}
TransportProvider creates transport-specific connections
Source Files