gos7

gos7 is a pure Go implementation of the Siemens S7 protocol. It is designed for low-level communication with S7 family PLC devices. The library supports both AG (Access Group) and PG (Programming Group) functions, allowing for data manipulation and PLC management.

Requirements:

• Minimum Go version: 1.13

The gos7.Helper utility provides methods to convert between raw byte arrays and various Siemens S7 data types. This is essential for preparing buffers before writing or interpreting buffers after reading.

Supported types include:

• bit, int, word, dword, uint, etc.
• real (floating point)
• time
• counter

To communicate with a PLC over TCP, you must create a TCPClientHandler, configure its connection parameters (IP, rack, slot), and then initialize a Client using that handler. It is recommended to call handler.Connect() manually to maintain a single connection session for multiple requests.

const (
	tcpDevice = "127.0.0.1"
	rack      = 0
	slot      = 2
)

// Initialize the TCP handler
handler := gos7.NewTCPClientHandler(tcpDevice, rack, slot)
handler.Timeout = 200 * time.Second
handler.IdleTimeout = 200 * time.Second
handler.Logger = log.New(os.Stdout, "tcp: ", log.LstdFlags)

// Connect manually to reuse the connection for multiple requests
handler.Connect()
defer handler.Close()

// Initialize the client
client := gos7.NewClient(handler)

The Helper struct provides utility methods to read and write various Siemens S7 PLC data types (such as Real, DateTime, String, and Counter) to and from byte arrays. This is essential when communicating with PLCs via protocols like S7Comm, where data is transmitted in specific binary formats (BigEndian, BCD, etc.).

import "github.com/robinson/robinson/gos7"

helper := &gos7.Helper{}
// Use helper methods to manipulate byte buffers

A typical session follows this lifecycle:

1. Connect: Establishes the TCP connection and performs the S7 protocol handshake.
2. Send: Transmits a request byte slice and waits for the response. The Send method handles the TPKT and COTP headers automatically.
3. Close: Terminates the connection.

Idle Timeout: The handler includes an IdleTimeout mechanism. If no activity occurs within the configured duration, the connection is automatically closed to save resources.

These types represent the System Status List (SZL) data structures used for diagnostic communication with S7 systems.

SZLHeader contains the metadata for the SZL record:

• LengthHeader: Length of the header.
• NumberOfDataRecord: Number of data records present.

S7SZL is the container for the header and the raw data payload.

S7SZLList is a specialized version where the data is interpreted as a list of big-endian uint16 values.

type SZLHeader struct {
	LengthHeader       uint16
	NumberOfDataRecord uint16
}

type S7SZL struct {
	Header SZLHeader
	Data   []byte
}

type S7SZLList struct {
	Header SZLHeader
	Data   []uint16
}

To use the gos7 library, you must create a Client instance. You can do this using two different methods depending on whether you have a single object that implements both Packager and Transporter interfaces, or if you want to provide them separately.

• NewClient(handler ClientHandler): Use this if your backend handler implements the ClientHandler interface (which combines Packager and Transporter).
• NewClient2(packager Packager, transporter Transporter): Use this to provide distinct implementations for packaging and transporting data.

// Using a single handler
client := gos7.NewClient(myHandler)

// Using separate packager and transporter
client := gos7.NewClient2(myPackager, myTransporter)

Use AGWriteDB to write values to a Data Block and AGReadDB to read them. Because the protocol works with byte buffers, use gos7.Helper to encode values into a buffer before writing, or decode them from a buffer after reading.

// Setup
address := 2710
start := 8
size := 2
buffer := make([]byte, 255)
value := 100
var helper gos7.Helper

// 1. Write to DB
// Prepare the buffer with the value
helper.SetValueAt(buffer, 0, value)  
// Write to address DB2710, starting at position 8, size 2
err := client.AGWriteDB(address, start, size, buffer)

// 2. Read from DB
readBuf := make([]byte, 255)
err = client.AGReadDB(address, start, size, readBuf)

// 3. Interpret the result
var result uint16
var s7 gos7.Helper
s7.GetValueAt(readBuf, 0, &result)

The AG functions allow for reading and writing various memory areas in the PLC. The following operations are tested and supported:

• Read/Write Data Block (DB)
• Read/Write Merkers (MB)
• Read/Write IPI (EB)
• Read/Write IPU (AB)
• Read/Write Timer (TM)
• Read/Write Counter (CT)
• Multiple Read/Write Area
• Get Block Info

The PG functions are used for PLC management and system information. The following operations are tested and supported:

• Hot start / Cold start / Stop PLC
• Get CPU of PLC status
• List available blocks in PLC
• Set/Clear password for session
• Get CPU protection and CPU Order code
• Get CPU/CP Information
• Read/Write clock for the PLC

The ErrorText(err int) string function converts an integer error code into a descriptive string. This is useful for logging or displaying errors to users. It handles various error categories including TCP, ISO, and CLI/CPU errors. If an unknown error code is provided, it returns a default string containing the integer value.

import "gos7"

// Example usage
errCode := 1 // errTCPSocketCreation
message := gos7.ErrorText(errCode)
fmt.Println(message) // Output: SYS : Error creating the Socket