profinet

README

go-profinet - PROFINET IO Controller, Device, DCP, LLDP and GSDML Library for Go

A pure Go implementation of PROFINET IO (IEC 61158-5-10/6-10, IEC 61784-2), the industrial Ethernet of PLCs, remote IO, drives and field devices. No cgo, no dependencies outside the standard library.

The library provides:

• An IO-Controller (controller): finds its devices by station name with DCP, optionally assigns their IP address, establishes an application relationship (AR) in legacy (RT_CLASS_1) or advanced (RT_CLASS_2) startup, writes the parameters, exchanges cyclic IO data, acknowledges alarms, reads and writes records and re-establishes the AR after a failure, one lifecycle per device; device access (supervisor) ARs and ReadImplicit for engineering tools
• An IO-Device (device): DCP responder, LLDP, the RPC server for Connect, Read, Write, Control and Release, the AR state machine (IOCAR and IOSAR, several ARs), cyclic input production and output consumption with watchdogs, process, diagnosis and plug alarms, diagnosis records, I&M0–4, RealIdentificationData, ModuleDiff, port data for the topology, port checks (CheckPeers) and adjustments (LLDP and DCP boundaries), shared device (several controllers, one owner per submodule), multiport devices on a software switch (l2/bridge), media redundancy (MRP client, manager and automatic manager), an opt-in read-only SNMP agent (MIB-II, LLDP-MIB), an opt-in DCP policy (read-only, rate limits, audit) and, as an experiment off by default, system redundancy S2
• DCP (dcp): Identify with filters and response delay, Get, Set (station name, IP suite, temporary or permanent), Signal, ResetToFactory, Hello (sent by the device, used by the controller to connect without Identify); requester and responder
• LLDP (lldp) with the PROFINET TLVs, an agent and a neighbor table
• Connectionless DCE/RPC (rpc) over any net.PacketConn: activities, fragmentation and reassembly, at-most-once execution, idempotent calls
• The PNIO codecs (pnio): every block of Connect, Control, Read, Write, alarms, diagnosis, identification, I&M, ModuleDiff and PDPortDataReal; NDR headers and PNIO status
• RT cyclic data (rt): frames, the C_SDU layout of IOCRs, provider, consumer with cycle counter and watchdog, a scheduler with jitter statistics; alarms (alarm): the RTA protocol with sequence numbers, acknowledgement, retransmission and window
• GSDML (gsdml): parsing, validation, encoding and conversion between GSDML files and device models, from a schema catalog by code generation
• Layer 2 backends: Linux AF_PACKET, macOS/BSD BPF, Windows Npcap (l2/osport picks the one of the platform) and an in-memory virtual Ethernet (vnet) with seeded faults, plus a small ARP/IPv4/UDP stack (netstack), so that a controller and devices run in one process without privileges
• Verified against independent implementations: rt-labs p-net, pnio-rs, profinet-py and pnio-dcp (PROFINET), umrp and microchip-ung/mrp on the Linux kernel's bridge MRP (MRP rings), Net-SNMP (the SNMP agent), with every capture decoded by Wireshark and scapy, in the containers of otfabric/profinet-interop (see INTEROPERABILITY.md and the support, feature and interop matrix, docs/FEATURE-STATUS.md)
• Observability: a profinet.Metrics callback interface (state changes, connects, aborts, record accesses with durations, alarms, retries), structured logging through log/slog, counters on every component, typed errors with sentinels (ERRORS.md, OBSERVABILITY.md); reconnection with exponential backoff and jitter
• Persistence and re-parameterization: an optional store keeps a device's permanent name, address and I&M records across restarts (store, device.Config.Store); a controller re-parameterizes a running device (Reparameterize)

A command-line tool on top of it is otfabric/profinetctl.

go-profinet is not certified by PROFIBUS & PROFINET International (PI) and claims no conformance. PROFINET has no security of its own: run it on isolated networks. See SECURITY.md.

Comparison: go-profinet vs other stacks

Docs: API.md (public API) · ARCHITECTURE.md (packages, goroutines, state machines) · INTEROPERABILITY.md (implemented services, conformance and interop matrices) · ERRORS.md · OBSERVABILITY.md · SECURITY.md · LIMITATIONS.md · CONTRIBUTING.md · RELEASE.md · guides in docs/ (controller, device, DCP, LLDP, RPC, cyclic data, diagnostics, GSDML, code generation, testing, coverage, benchmarks)

go-profinet vs p-net, pnio-rs, profinet-py and the PI Community Stack

go-profinet is tested against three of these stacks (see INTEROPERABILITY.md). Each suits different needs; the table shows where they differ, from their public sources, so that you can pick the right one. The PI Community Stack is members-only; its column is from PI's public pages.

Capability	otfabric/go-profinet	rt-labs p-net	pnio-rs	profinet-py	PI Community Stack
Language	Go	C	Rust	Python	C
Licence	MIT	GPL-3.0-only or commercial	MIT OR Apache-2.0	GPL-3.0-only or commercial	PNO Community Source Code License (members only; no combination with copyleft)
Status	pre-1.0 (v0.6.0)	maintained privately; public tree is an evaluation snapshot without ports (v1.0.2, 2025)	young, single author (v0.1.0, 2026)	active, one maintainer (0.6.6, 2026)	maintained by PI
IO-Controller	✅	—	—	✅ minimal (cyclic marked experimental)	not documented publicly
IO-Device	✅	✅	✅	—	✅
DCP requester	✅ Identify (all filters), Get, Set, Signal, Reset	—	—	✅	—
DCP responder	✅ incl. filters, response delay, requester lock, Hello	✅ incl. Hello	◐ Identify by name or all; no Get, Set name, Signal or Reset	—	✅
LLDP	✅ agent and neighbor table	✅	—	— (reads PDRealData only)	✅
RT_CLASS_1 / RT_CLASS_2 (unsynchronized)	✅ / ✅	✅ / ✅	◐ RT_CLASS_2 FrameIDs only	✅ / —	✅
IRT (RT_CLASS_3)	—	—	—	—	✅ with a hardware driver
Alarms	✅ both priorities, all types	✅	◐ low priority, diagnosis only	✅ receive and acknowledge	✅
Diagnosis records	✅ serve and read	✅	— (invalid index)	✅ read	✅
I&M	✅ I&M0–4	✅ I&M0–4 (device only)	◐ I&M0–3	✅ read I&M0–15, write I&M1–3	✅
Several ARs on a device	✅ IOCARs + IOSAR	◐ 2 IOCARs	— single AR	n/a	✅
Shared device (one owner per submodule, hand-over)	✅ device and controller	✅	—	—	✅
Device access AR (IOSAR)	✅ both roles	—	—	✅	not documented
ModuleDiffBlock	✅ both roles	✅ (plugs expected modules)	— (mismatch rejects Connect)	✅ read	✅
ReadImplicit, WriteMultiple	✅ / ✅	✅ / ✅	✅ / ✅	✅ / ✅	✅
PDPortDataReal / PDRealData (topology)	✅ serve and decode	✅	—	✅ read	✅
PDPortDataCheck (CheckPeers) / PDPortDataAdjust (boundaries)	✅ device and controller	◐ CheckPeers, PeerToPeerBoundary bit 0	—	—	✅
Re-parameterization in Data (PrmBegin)	✅ device and controller	— (refuses PrmBegin)	— (refuses PrmBegin)	✅ controller	✅
Media redundancy (MRP)	✅ client, manager, automatic manager (multiport device)	—	—	n/a	not documented
SNMP agent	✅ v1/v2c, MIB-II, LLDP-MIB	◐ optional, through Net-SNMP	—	n/a	not documented
GSDML	✅ parse, validate (catalog), generate, model conversion	— (static file)	◐ generate	◐ parse for cyclic	—
Platforms	Linux, macOS/BSD, Windows (Npcap)	Linux, RTOS ports (not in the public tree)	Linux	Linux	Linux (Raspberry Pi demo)
Runs without privileges in tests	✅ virtual Ethernet in process	—	—	—	—
Tested against other stacks in CI	✅ p-net, pnio-rs, profinet-py, pnio-dcp; umrp and microchip-ung/mrp (MRP); Net-SNMP; scapy and Wireshark decode every capture	not documented	golden frames from p-net and an S7-1500	p-net (integration tests)	not documented
PI certification	— (not certified)	v1.0.2 release notes: "PROFINET Test Bundle 2.45.0.2 PASS"	—	—	basis for certified products

✅ = available · ◐ = partly (the cell says what) · — = not available. For p-net ea5e554 (the last complete public tree; current release v1.0.2), pnio-rs v0.1.0 and profinet-py 0.6.6, from their source and documentation (docs/research/STACKS.md) and the interop tests, as of October 2026. If you spot an inaccuracy, please open an issue.

Install

go get github.com/otfabric/go-profinet

Requires Go 1.23 or later.

Project structure

Package	Contents
profinet (root)	sentinel errors, logger interfaces
controller	IO-Controller, record client, supervisor AR
device	IO-Device
model	the device model: identity, DAP, slots, modules, submodules, records
gsdml	GSDML documents (generated types), validation with severities, model conversion
gsdml/gsdx	a safe inspector of GSDX (OPC) containers
dcp	DCP codec, requester (Client), responder
lldp	LLDP codec and agent
rpc	connectionless DCE/RPC client and server
pnio	PNIO blocks, NDR, status, identifiers
rt	cyclic frames, layout, provider, consumer, scheduler
alarm	RTA alarm transport
mrp	MRP frame codec and the ring client, manager and automatic manager (mrp.New) on a switch
snmp	read-only SNMPv1/v2c agent: MIB-II system, interfaces, snmp group, LLDP-MIB
ptcp	PTCP delay frame codec (DelayReq, DelayRes); no line delay measurement
ethernet	Ethernet and VLAN frame codec, MAC addresses
l2	the Port interface and the frame demultiplexer Mux
l2/bridge	the learning switch of a multiport device
l2/afpacket, l2/bpf, l2/npcap, l2/osport	the operating systems' raw Ethernet backends
vnet	virtual Ethernet switch with loss, duplication, corruption, reordering, delay and jitter
netstack	ARP, IPv4 and UDP over a l2.Mux
pcap	pcap reader and writer
examples/	quickstart, discovery, DCP Hello, alarms, records, topology, observability (slog and metrics), an MRP ring, chaos, GSDML generation and import, GSDX inspection, a device and a controller on a real interface (outputs)
e2e/	end-to-end and chaos tests on vnet; real Layer 2 tests
interop/	the interop suite against profinet-interop (build tag interop)

Quickstart: controller and device in one process

network := vnet.New(1)
dn, _ := vnetenv.NewNode(network, 10, "192.168.0.10") // an endpoint with an IP stack
dev, _ := device.New(device.Config{
	Model: model, Mux: dn.Mux, StationName: "io-1",
	IP: suite("192.168.0.10"), ListenPacket: dn.Stack.ListenPacket,
})
cn, _ := vnetenv.NewNode(network, 1, "192.168.0.1")
ctrl, _ := controller.New(controller.Config{Mux: cn.Mux, ListenPacket: cn.Stack.ListenPacket, StationName: "plc-1"})
io1, _ := ctrl.AddDevice(controller.DeviceConfig{StationName: "io-1", Model: model})
_ = io1.WaitState(ctx, controller.StateRunning)

dev.SetInput(1, 1, []byte("PROFINET"), pnio.IOxSGood)
io1.SetOutput(2, 1, []byte{1, 2, 3, 4}, pnio.IOxSGood)
in, iops, _ := io1.Input(1, 1)

The full program is examples/quickstart (all examples with their output): go run ./examples/quickstart. It needs no privileges.

On a real network

port, err := osport.Open("eth0", osport.Options{}) // AF_PACKET, BPF or Npcap
if err != nil {
	return err // needs CAP_NET_RAW, /dev/bpf* or Npcap
}
defer port.Close()
mux := l2.NewMux(port)
defer mux.Close()

ctrl, err := controller.New(controller.Config{Mux: mux, StationName: "plc-1"}) // the OS's UDP stack
...
dcpc := ctrl.DCP()
devices, err := dcpc.Identify(ctx, dcp.FilterAll(), dcp.IdentifyOptions{Wait: 2 * time.Second})

The expected configuration of a device usually comes from its GSDML file:

doc, err := gsdml.Parse(f)
m, err := gsdml.ToModel(doc, "") // the first device access point
d, err := ctrl.AddDevice(controller.DeviceConfig{StationName: "io-rack-1", Model: m})

and a device built with go-profinet describes itself with one:

doc, err := gsdml.FromModel(m, gsdml.GenerateOptions{SupervisorAR: true})
b, err := gsdml.Marshal(doc)
os.WriteFile(gsdml.FileName(m, "", time.Now()), b, 0o644)

See the guides: controller, device, DCP, GSDML.

Production features

• context.Context on every blocking call; bounded queues and concurrency everywhere; malformed network input is dropped and counted, never a panic (every decoder is fuzzed)
• One goroutine per device lifecycle on the controller; reconnect with backoff; watchdogs, data hold and CM activity timeouts as configured
• Typed errors that match the sentinels of the root package (ERRORS.md); PNIO and DCP status codes preserved
• Structured logging through a small Logger interface with log/slog and log adapters; counters on every component (OBSERVABILITY.md)
• Raw Ethernet on Linux, macOS and Windows; cross-compiles for every GOOS/GOARCH of the release targets

Development

make check        # generate-check, fmt, lint, vet, vuln, test (race), coverage ≥ 90 %, examples
make test-e2e     # end-to-end and chaos tests on vnet
make fuzz         # every fuzz target for FUZZTIME (30 s)
make bench        # codec and cyclic benchmarks
make l2-test      # real AF_PACKET tests on a veth pair in a privileged container (Docker)
make interop-images && make interop   # the interop suite (Docker), see INTEROPERABILITY.md

docs/TESTING.md describes the test strategy, docs/COVERAGE.md the coverage per package and docs/BENCHMARKS.md the measured performance.

Limitations

The features of conformance class A as controller and device (RT_CLASS_1 and RT_CLASS_2 without synchronization), shared device, multiport devices, MRP (client, manager and automatic manager; no MRPD, no interconnection) and a read-only SNMP agent; system redundancy S2 is an experiment that is not interoperable. This is feature coverage, not conformance: go-profinet is not certified for any class, and no time measured on the virtual network is a real-time claim. No IRT, PROFIsafe or PROFINET security classes. What was built without PI membership or hardware, how it was verified and what it does not do is in docs/FEATURE-STATUS.md (the support, feature and interop matrix), LIMITATIONS.md, the release notes (RELEASE.md), docs/research/NEXT-PROGRAM-REPORT.md and, for the previous round, docs/research/FEATURE-COMPLETION-REPORT.md. OT Fabric is not a PI member: what that costs (official XSD validation, GSDX, MRCD, signing, certification) is listed in docs/PI-MEMBERSHIP.md. GSDML validation follows an independent catalog, not PI's licensed schemas; GSDX and MRCD are not implemented (their formats are not public), beyond a generic inspector of the public OPC container (gsdml/gsdx, signatures not verified). The full list is in LIMITATIONS.md.

License

MIT, see LICENSE. The interop suite runs GPL-licensed reference implementations in separate containers; none of their code is part of go-profinet.

Documentation

Index

• Variables
• type Backoff
  • func (b Backoff) Delay(attempt int, r float64) time.Duration
• type ContextLogger
• type FieldLogger
  • func NewSlogFieldLogger(h slog.Handler) FieldLogger
• type Logger
  • func NewSlogLogger(h slog.Handler) Logger
  • func NewStdLogger(l *log.Logger) Logger
  • func NopLogger() Logger
• type Metrics
• type NopMetrics
  • func (NopMetrics) OnAbort(string, error)
  • func (NopMetrics) OnAlarm(string, string, bool)
  • func (NopMetrics) OnConnect(string, time.Duration, error)
  • func (NopMetrics) OnRecord(string, string, uint16, time.Duration, error)
  • func (NopMetrics) OnRetry(string, int, time.Duration, error)
  • func (NopMetrics) OnStateChange(string, string, string, error)

Variables

var (
	// ErrClosed reports an operation on a controller, device, connection
	// or port that was closed by the application.
	ErrClosed = errors.New("profinet: closed")

	// ErrTimeout reports that the peer did not answer within the
	// configured time: a DCP request, an RPC call, an alarm that was not
	// acknowledged, or a cyclic consumer whose watchdog expired.
	ErrTimeout = errors.New("profinet: timeout")

	// ErrMalformed reports input that cannot be decoded: a frame, a block
	// or a document that is truncated, has an invalid length, an invalid
	// field value or trailing data where none is allowed. Network input
	// that fails to decode is dropped and counted; it never panics.
	ErrMalformed = errors.New("profinet: malformed")

	// ErrUnsupported reports a request for a service, option, block type
	// or feature this implementation (or, for a remote error, the peer)
	// does not provide.
	ErrUnsupported = errors.New("profinet: unsupported")

	// ErrInvalidConfig reports a configuration value that a controller,
	// device, port or codec cannot be constructed or used with.
	ErrInvalidConfig = errors.New("profinet: invalid configuration")

	// ErrInvalidState reports an operation that is not allowed in the
	// current state of a state machine, for example a record write on an
	// application relationship that is not established.
	ErrInvalidState = errors.New("profinet: invalid state")

	// ErrRejected reports that the peer answered with an error: a PNIO
	// status other than OK, a DCP block error or an RPC fault or reject.
	// The typed error that carries the code wraps or matches it.
	ErrRejected = errors.New("profinet: rejected by peer")

	// ErrAborted reports that an application relationship ended without
	// a release: a watchdog expired, the peer sent an abort, the CM
	// activity timeout elapsed or the link went down.
	ErrAborted = errors.New("profinet: application relationship aborted")

	// ErrNotFound reports that no device answered a DCP request for a
	// station name or MAC address, or that a slot, subslot, record index
	// or application relationship does not exist.
	ErrNotFound = errors.New("profinet: not found")

	// ErrResourceExhausted reports that a bounded resource is used up:
	// the number of application relationships, a queue, a reassembly
	// buffer or the number of concurrent requests.
	ErrResourceExhausted = errors.New("profinet: resource exhausted")

	// ErrLinkDown reports that the Ethernet link of a port is down.
	ErrLinkDown = errors.New("profinet: link down")
)

Sentinel errors shared by every package of the module. They are usually wrapped with detail; test with errors.Is. Typed errors that carry a PROFINET error code (a PNIO status, a DCP block error, an RPC fault) match one of these as well, so that a caller can test for the class of a failure without knowing the code.

Types

type Backoff

type Backoff struct {
	Min, Max time.Duration
	Jitter   float64
}

Backoff is an exponential backoff: the wait doubles from Min up to Max, and Jitter (0 to 1) spreads it randomly downward by up to that fraction, so that devices that failed together do not retry together.

func (Backoff) Delay

func (b Backoff) Delay(attempt int, r float64) time.Duration

Delay returns the wait before the given attempt (1 for the first retry) with r, a random number in [0, 1), applied to the jitter.

type ContextLogger

type ContextLogger interface {
	Logger

	DebugContext(ctx context.Context, msg string, keysAndValues ...any)
	InfoContext(ctx context.Context, msg string, keysAndValues ...any)
	WarnContext(ctx context.Context, msg string, keysAndValues ...any)
	ErrorContext(ctx context.Context, msg string, keysAndValues ...any)
}

ContextLogger extends Logger with context-aware structured logging, so that a handler can pick trace and span identifiers out of the context. When the Logger also implements ContextLogger, entries that belong to a request are logged with the context the request was called with.

type FieldLogger

type FieldLogger interface {
	Logger

	// With returns a logger that adds the given fields to every entry.
	With(keysAndValues ...any) FieldLogger

	DebugKV(msg string, keysAndValues ...any)
	InfoKV(msg string, keysAndValues ...any)
	WarnKV(msg string, keysAndValues ...any)
	ErrorKV(msg string, keysAndValues ...any)
}

FieldLogger extends Logger with structured key-value logging. When the Logger given to a controller or device also implements FieldLogger, the library logs through it: every entry is a constant message plus fields such as "component", "station", "ar" and "error", instead of one formatted string. NewSlogLogger returns such a logger.

keysAndValues alternate string keys and values, as in log/slog.

func NewSlogFieldLogger

func NewSlogFieldLogger(h slog.Handler) FieldLogger

NewSlogFieldLogger is NewSlogLogger with the result typed as a FieldLogger, for callers that want to add fields with With before handing the logger to a controller or device. A nil handler returns a no-op logger.

type Logger

type Logger interface {
	Debugf(format string, args ...any)
	Infof(format string, args ...any)
	Warnf(format string, args ...any)
	Errorf(format string, args ...any)
}

Logger is the logging interface accepted by controllers, devices and the protocol engines. Implement it to integrate any logging library.

Logging is silent by default. Methods are invoked synchronously on the protocol path and must not block.

func NewSlogLogger

func NewSlogLogger(h slog.Handler) Logger

NewSlogLogger wraps a slog.Handler. The result implements FieldLogger and ContextLogger, so the library logs structured fields through it; messages are only built when the handler is enabled for their level. A nil handler returns a no-op logger.

func NewStdLogger

func NewStdLogger(l *log.Logger) Logger

NewStdLogger wraps a standard library logger. Each message is prefixed with its level. A nil l logs to os.Stderr with the standard flags.

func NopLogger

func NopLogger() Logger

NopLogger returns a Logger that discards everything.

type Metrics

type Metrics interface {
	// OnStateChange is called for every state change of a controller's
	// device lifecycle or of a device's AR. err is the failure that
	// caused it, if any.
	OnStateChange(station, from, to string, err error)

	// OnConnect is called when a Connect completed: on a controller when
	// the device answered (or the call failed), on a device when it
	// answered a controller. d is the time the Connect took; err is nil
	// when the AR was established.
	OnConnect(station string, d time.Duration, err error)

	// OnAbort is called when an AR ended without a release: a watchdog,
	// an abort by the peer, a CM activity timeout, a lost link. err
	// matches [ErrAborted] or [ErrTimeout].
	OnAbort(station string, err error)

	// OnRecord is called after a record access: on a controller a
	// ReadRecord, WriteRecord or WriteMultiple call, on a device a request
	// it served. op is "read" or "write"; d the time it took; err nil when
	// it succeeded.
	OnRecord(station, op string, index uint16, d time.Duration, err error)

	// OnAlarm is called for every alarm a controller received or a device
	// sent; typ is the alarm type's name, high its priority.
	OnAlarm(station, typ string, high bool)

	// OnRetry is called when a controller schedules the next connection
	// attempt to a device after a failure: attempt counts the attempts
	// since the device last ran, wait is the backoff before it.
	OnRetry(station string, attempt int, wait time.Duration, err error)
}

Metrics is an optional callback interface for observing the application relationships of a controller or a device: their state changes, connects, aborts, record accesses, alarms and reconnection attempts. A nil Metrics disables collection. The counters of each component (OBSERVABILITY.md) complement it.

station names the peer: on a controller the device's NameOfStation, on a device the controller's (CMInitiatorStationName). States are the names the controller's State and the device's ARState print.

The methods are called synchronously on the protocol path, possibly from several goroutines at once; implementations must be safe for concurrent use and must not block (increment a counter, send on a buffered channel). Embed NopMetrics to implement only the callbacks you need and to stay compatible when methods are added.

type NopMetrics

type NopMetrics struct{}

NopMetrics is a Metrics that does nothing. Embed it in your own type.

func (NopMetrics) OnAbort

func (NopMetrics) OnAbort(string, error)

OnAbort does nothing.

func (NopMetrics) OnAlarm

func (NopMetrics) OnAlarm(string, string, bool)

OnAlarm does nothing.

func (NopMetrics) OnConnect

func (NopMetrics) OnConnect(string, time.Duration, error)

OnConnect does nothing.

func (NopMetrics) OnRecord

func (NopMetrics) OnRecord(string, string, uint16, time.Duration, error)

OnRecord does nothing.

func (NopMetrics) OnRetry

func (NopMetrics) OnRetry(string, int, time.Duration, error)

OnRetry does nothing.

func (NopMetrics) OnStateChange

func (NopMetrics) OnStateChange(string, string, string, error)

OnStateChange does nothing.