Documentation
¶
Overview ¶
Package iec60870 is the module root of a pure Go implementation of the IEC 60870-5 telecontrol protocol family.
Applications import the subpackages:
- github.com/otfabric/go-iec60870-5/asdu: the application service data unit of IEC 60870-5-101 and IEC 60870-5-104 (the telecontrol companion standards), with configurable field sizes
- github.com/otfabric/go-iec60870-5/cp: the time tags of IEC 60870-5-4 (CP24Time2a, CP32Time2a, CP56Time2a), shared by the companion standards that use them
- github.com/otfabric/go-iec60870-5/ft12: the FT 1.2 frame format of IEC 60870-5-1/-2, the serial framing of IEC 60870-5-101, -102 and -103
- github.com/otfabric/go-iec60870-5/iec104: IEC 60870-5-104 over TCP/IP: APCI framing (github.com/otfabric/go-iec60870-5/iec104/apci), the controlling station (github.com/otfabric/go-iec60870-5/iec104/client) and the controlled station (github.com/otfabric/go-iec60870-5/iec104/server)
- github.com/otfabric/go-iec60870-5/sec: IEC 62351-5 application layer security as profiled by IEC TS 60870-5-7
This package holds what every companion standard shares: the Logger interfaces.
Docs: README.md, docs/ARCHITECTURE.md, docs/STANDARDS.md, docs/ROADMAP.md.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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 client or server also implements FieldLogger, the library logs through it: every entry is a constant message plus fields such as "component", "remote", "state", "type", "cause" 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 client or server. 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 the client and the server. 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 ¶
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 ¶
NewStdLogger wraps a standard library logger. Each message is prefixed with its level. A nil l logs to os.Stderr with the standard flags.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package asdu implements the Application Service Data Unit of the IEC 60870-5 companion standards: the data unit identifier, the information objects and elements of IEC 60870-5-101 clause 7, and their binary codec.
|
Package asdu implements the Application Service Data Unit of the IEC 60870-5 companion standards: the data unit identifier, the information objects and elements of IEC 60870-5-101 clause 7, and their binary codec. |
|
Package cp encodes and decodes the binary time tags of IEC 60870-5-4 (subclause 6.8): CP16Time2a (elapsed milliseconds), CP24Time2a (minute, second, millisecond), CP32Time2a (adds the hour) and CP56Time2a (a full date and time).
|
Package cp encodes and decodes the binary time tags of IEC 60870-5-4 (subclause 6.8): CP16Time2a (elapsed milliseconds), CP24Time2a (minute, second, millisecond), CP32Time2a (adds the hour) and CP56Time2a (a full date and time). |
|
Package ft12 encodes and decodes the FT 1.2 frame format of IEC 60870-5-1 (subclause 6.2.4.2), the serial framing shared by IEC 60870-5-101, -102 and -103:
|
Package ft12 encodes and decodes the FT 1.2 frame format of IEC 60870-5-1 (subclause 6.2.4.2), the serial framing shared by IEC 60870-5-101, -102 and -103: |
|
Package iec101 holds what the controlling and the controlled station of IEC 60870-5-101 share: the system parameters, the link State and the sentinel errors.
|
Package iec101 holds what the controlling and the controlled station of IEC 60870-5-101 share: the system parameters, the link State and the sentinel errors. |
|
client
Package client is the controlling station of IEC 60870-5-101: it brings up the link, polls the controlled station (unbalanced transmission) or exchanges messages with it (balanced transmission), runs requests (interrogation, counter interrogation, read, commands, clock synchronization, test, reset process, delay acquisition) and delivers monitor-direction ASDUs to a handler.
|
Package client is the controlling station of IEC 60870-5-101: it brings up the link, polls the controlled station (unbalanced transmission) or exchanges messages with it (balanced transmission), runs requests (interrogation, counter interrogation, read, commands, clock synchronization, test, reset process, delay acquisition) and delivers monitor-direction ASDUs to a handler. |
|
e2e
Package e2e runs the IEC 60870-5-101 client against the server over in-memory and lossy transports, in unbalanced and balanced mode.
|
Package e2e runs the IEC 60870-5-101 client against the server over in-memory and lossy transports, in unbalanced and balanced mode. |
|
examples/quickstart
command
Command quickstart runs an IEC 60870-5-101 controlling and controlled station against each other over an in-memory line, in unbalanced mode: link initialization, end of initialization, a general interrogation and a select-before-operate command.
|
Command quickstart runs an IEC 60870-5-101 controlling and controlled station against each other over an in-memory line, in unbalanced mode: link initialization, end of initialization, a general interrogation and a select-before-operate command. |
|
examples/serial
command
Command serial is an IEC 60870-5-101 controlling station on a byte stream: a TCP connection to a serial device server (terminal server) that passes the line through unchanged, or a local serial port opened by any io.ReadWriteCloser implementation (for example github.com/otfabric/go-serial).
|
Command serial is an IEC 60870-5-101 controlling station on a byte stream: a TCP connection to a serial device server (terminal server) that passes the line through unchanged, or a local serial port opened by any io.ReadWriteCloser implementation (for example github.com/otfabric/go-serial). |
|
server
Package server is the controlled station of IEC 60870-5-101: it answers the link procedures of the controlling station, hands control-direction ASDUs to a Handler and transmits monitor-direction ASDUs: as class 1 or class 2 data when polled (unbalanced transmission), or on its own initiative (balanced transmission).
|
Package server is the controlled station of IEC 60870-5-101: it answers the link procedures of the controlling station, hands control-direction ASDUs to a Handler and transmits monitor-direction ASDUs: as class 1 or class 2 data when polled (unbalanced transmission), or on its own initiative (balanced transmission). |
|
Package iec103 implements the application layer of IEC 60870-5-103, the companion standard for the informative interface of protection equipment: its own ASDU model (clause 7.1 to 7.3), the information elements of clause 7.2.6, the function type and information number semantics of clause 7.2.5 as data, and what the controlling and the controlled station share (State, the sentinel errors).
|
Package iec103 implements the application layer of IEC 60870-5-103, the companion standard for the informative interface of protection equipment: its own ASDU model (clause 7.1 to 7.3), the information elements of clause 7.2.6, the function type and information number semantics of clause 7.2.5 as data, and what the controlling and the controlled station share (State, the sentinel errors). |
|
client
Package client is the controlling system of IEC 60870-5-103: the primary station of unbalanced transmission (clause 6.2.3) that polls one item of protection equipment, runs the application functions of clause 7.4 (station initialization, time synchronization, general interrogation, general commands, generic services, disturbance data transfer) and delivers every monitor-direction ASDU to a handler.
|
Package client is the controlling system of IEC 60870-5-103: the primary station of unbalanced transmission (clause 6.2.3) that polls one item of protection equipment, runs the application functions of clause 7.4 (station initialization, time synchronization, general interrogation, general commands, generic services, disturbance data transfer) and delivers every monitor-direction ASDU to a handler. |
|
e2e
Package e2e runs the IEC 60870-5-103 controlling system (iec103/client) against the protection equipment (iec103/server) over in-memory and lossy lines.
|
Package e2e runs the IEC 60870-5-103 controlling system (iec103/client) against the protection equipment (iec103/server) over in-memory and lossy lines. |
|
examples/quickstart
command
Command quickstart runs an IEC 60870-5-103 controlling system and an item of protection equipment against each other over an in-memory line: link initialization with identification, time synchronization, general interrogation, a general command and a generic read.
|
Command quickstart runs an IEC 60870-5-103 controlling system and an item of protection equipment against each other over an in-memory line: link initialization with identification, time synchronization, general interrogation, a general command and a generic read. |
|
server
Package server is the protection equipment of IEC 60870-5-103: the secondary station of unbalanced transmission (clause 6.2.3).
|
Package server is the protection equipment of IEC 60870-5-103: the secondary station of unbalanced transmission (clause 6.2.3). |
|
apci
Package apci implements the IEC 60870-5-104 Application Protocol Control Information: APDU framing, the I/S/U control field formats, 15-bit sequence number arithmetic and the protocol parameters (k, w, t0..t3).
|
Package apci implements the IEC 60870-5-104 Application Protocol Control Information: APDU framing, the I/S/U control field formats, 15-bit sequence number arithmetic and the protocol parameters (k, w, t0..t3). |
|
client
Package client implements the controlling station (master) of IEC 60870-5-104.
|
Package client implements the controlling station (master) of IEC 60870-5-104. |
|
e2e
Package e2e holds end-to-end tests of go-iec60870-5 against itself: the client of this module as controlling station and the server of this module as controlled station, over real TCP (and TLS) connections on loopback.
|
Package e2e holds end-to-end tests of go-iec60870-5 against itself: the client of this module as controlling station and the server of this module as controlled station, over real TCP (and TLS) connections on loopback. |
|
examples/client
command
Command client is a small IEC 60870-5-104 controlling station: it connects, runs a general interrogation, synchronizes the clock, optionally operates a switch and then prints whatever the station reports until interrupted.
|
Command client is a small IEC 60870-5-104 controlling station: it connects, runs a general interrogation, synchronizes the clock, optionally operates a switch and then prints whatever the station reports until interrupted. |
|
examples/commands
command
Command commands shows command transmission from both sides: direct execution, select-before-operate, cancelling a selection, a set point with a time tag, and what a refusal looks like.
|
Command commands shows command transmission from both sides: direct execution, select-before-operate, cancelling a selection, a set point with a time tag, and what a refusal looks like. |
|
examples/events
command
Command events shows how a station reports on its own: an event queue that keeps events while no control centre is connected and repeats what was not acknowledged, next to data that is simply sent to whoever listens.
|
Command events shows how a station reports on its own: an event queue that keeps events while no control centre is connected and repeats what was not acknowledged, next to data that is simply sent to whoever listens. |
|
examples/files
command
Command files shows file transfer: a station that offers files, takes files and has a directory, and a controlling station that lists, fetches and delivers.
|
Command files shows file transfer: a station that offers files, takes files and has a directory, and a controlling station that lists, fetches and delivers. |
|
examples/observability
command
Command observability shows what the library tells its application: structured logs, connection states and metrics, on both sides, and the options that make a client resilient (reconnect, retries, a start handler).
|
Command observability shows what the library tells its application: structured logs, connection states and metrics, on both sides, and the options that make a client resilient (reconnect, retries, a start handler). |
|
examples/quickstart
command
Command quickstart is the smallest complete program: a controlled station with two points and a controlling station that interrogates it, in one process, over a real TCP connection on loopback.
|
Command quickstart is the smallest complete program: a controlled station with two points and a controlling station that interrogates it, in one process, over a real TCP connection on loopback. |
|
examples/redundancy
command
Command redundancy shows a redundancy group: two connections to a station (here: two stations standing in for two paths), exactly one with data transfer started, failover when the active one is lost and a manual switchover.
|
Command redundancy shows a redundancy group: two connections to a station (here: two stations standing in for two paths), exactly one with data transfer started, failover when the active one is lost and a manual switchover. |
|
examples/secure
command
Command secure shows the application-layer security of IEC 62351-5 as IEC TS 60870-5-7 applies it to IEC 60870-5-104: a Station Association with certificates of a plant authority, session keys, every ASDU as Secure Data, and role-based access control at the station.
|
Command secure shows the application-layer security of IEC 62351-5 as IEC TS 60870-5-7 applies it to IEC 60870-5-104: a Station Association with certificates of a plant authority, session keys, every ASDU as Secure Data, and role-based access control at the station. |
|
examples/server
command
Command server is a small IEC 60870-5-104 controlled station: a handful of points, a switch that accepts single commands, and a measurement that changes every second and is reported spontaneously.
|
Command server is a small IEC 60870-5-104 controlled station: a handful of points, a switch that accepts single commands, and a measurement that changes every second and is reported spontaneously. |
|
examples/tls
command
Command tls shows IEC 60870-5-104 over TLS (IEC 62351-3) with certificates on both sides: the station only accepts control centres whose certificate its authority signed, and tells them apart by it.
|
Command tls shows IEC 60870-5-104 over TLS (IEC 62351-3) with certificates on both sides: the station only accepts control centres whose certificate its authority signed, and tells them apart by it. |
|
internal/capture
Package capture reads recorded IEC 60870-5-104 traffic for tests: classic pcap and pcapng files, gzip-compressed or not, with Ethernet, BSD loopback, Linux cooked or raw IPv4 frames.
|
Package capture reads recorded IEC 60870-5-104 traffic for tests: classic pcap and pcapng files, gzip-compressed or not, with Ethernet, BSD loopback, Linux cooked or raw IPv4 frames. |
|
internal/link
Package link implements the IEC 60870-5-104 connection state machine that the client and the server share: send and receive sequence numbers, the k/w flow control windows, the t1/t2/t3 timers and the STARTDT/STOPDT/ TESTFR procedures.
|
Package link implements the IEC 60870-5-104 connection state machine that the client and the server share: send and receive sequence numbers, the k/w flow control windows, the t1/t2/t3 timers and the STARTDT/STOPDT/ TESTFR procedures. |
|
internal/testutil
Package testutil holds helpers shared by the client and server tests.
|
Package testutil holds helpers shared by the client and server tests. |
|
server
Package server implements the controlled station (outstation, slave) of IEC 60870-5-104.
|
Package server implements the controlled station (outstation, slave) of IEC 60870-5-104. |
|
internal
|
|
|
logx
Package logx is how the library writes its log entries: a constant message plus key-value fields.
|
Package logx is how the library writes its log entries: a constant message plus key-value fields. |
|
Package link implements the link transmission procedures of IEC 60870-5-2 over FT 1.2 frames (package ft12): the control field, unbalanced transmission with a Primary (controlling) station polling one or more Secondary (controlled) stations, and Balanced transmission between two combined stations.
|
Package link implements the link transmission procedures of IEC 60870-5-2 over FT 1.2 frames (package ft12): the control field, unbalanced transmission with a Primary (controlling) station polling one or more Secondary (controlled) stations, and Balanced transmission between two combined stations. |
|
Package sec is the application-layer security of IEC 60870-5-104: the A-Profile of IEC 62351-5:2023 as IEC TS 60870-5-7:2025 maps it onto IEC 60870-5-101 and -104.
|
Package sec is the application-layer security of IEC 60870-5-104: the A-Profile of IEC 62351-5:2023 as IEC TS 60870-5-7:2025 maps it onto IEC 60870-5-101 and -104. |
|
Package telecontrol holds the application procedures that IEC 60870-5-101 and IEC 60870-5-104 share (IEC 60870-5-5 as profiled by the two companion standards): how a controlling station recognises the answers to its requests, and how it runs the request kinds that are answered with a confirmation (commands, clock synchronization), with data and a termination (interrogation, counter interrogation) or with the data itself (read).
|
Package telecontrol holds the application procedures that IEC 60870-5-101 and IEC 60870-5-104 share (IEC 60870-5-5 as profiled by the two companion standards): how a controlling station recognises the answers to its requests, and how it runs the request kinds that are answered with a confirmation (commands, clock synchronization), with data and a termination (interrogation, counter interrogation) or with the data itself (read). |