iec103ctl
iec103ctl polls and simulates protection equipment that speaks IEC 60870-5-103. As a controlling system it runs a general interrogation, sends general commands, synchronizes the clock, reads the identification, reads and writes settings with the generic services, lists recorded faults and transfers their disturbance data, monitors what the relay sends and scans a line for link addresses. As protection equipment it simulates a relay from a model, so that a station controller or gateway has something to poll. It is one of the four tools of iec60870ctl and is built on go-iec60870-5. This page follows v0.9.0; the full reference is docs/iec103ctl/usage.md.
Install
Section titled “Install”curl -fsSL https://get.otfabric.io/iec103ctl | shirm https://get.otfabric.io/iec103ctl.ps1 | iexcurl -fsSL https://get.otfabric.io/iec103ctl | env OTF_UNMANAGED_INSTALL=/usr/local/bin shgo install github.com/otfabric/iec60870ctl/cmd/iec103ctl@latestBinaries for Linux (x86-64, ARM64, ARMv7), macOS (Intel, Apple silicon) and Windows (x86-64, ARM64). The installer checks the release's SHA-256 checksum, installs per user without sudo (~/.local/bin, on Windows %LOCALAPPDATA%\OTFabric\bin) and upgrades in place when you run it again. Pin a version with OTF_VERSION; the CI line installs into a fixed directory without touching PATH or shell profiles. All installer options, release archives for offline machines. Check the install with iec103ctl version.
Try it without a relay
Section titled “Try it without a relay”-
Start the built-in demo device (TCP port 2401):
Terminal window iec103ctl server start -
Poll it from another terminal:
Terminal window iec103ctl client identify --url tcp://127.0.0.1:2401iec103ctl client interrogate --url tcp://127.0.0.1:2401iec103ctl client command --url tcp://127.0.0.1:2401 --fun 160 --inf 16 --value off --wait-report 1000iec103ctl client generic group --url tcp://127.0.0.1:2401 --group 1 --format tableiec103ctl client disturbance list --url tcp://127.0.0.1:2401iec103ctl client disturbance get --url tcp://127.0.0.1:2401 --fan 1 --csv fault1.csv
Line and link flags
Section titled “Line and link flags”| Flag | Default | Meaning |
|---|---|---|
--url |
tcp://host[:port] (a terminal server, port 2401) or serial:///dev/ttyUSB0 (serial://COM3) |
|
--baud, --data-bits, --parity, --stop-bits |
9600, 8, even, 1 | The serial character format |
--link-address |
1 | The device’s link address, 0 to 254 |
--common-address |
the link address | Common address of ASDU |
--link-timeout, --retries |
1000 ms, 3 | How long a frame waits for its answer, and how often it is repeated |
--reset-fcb |
off | Initialize the link with reset FCB instead of reset CU |
--timezone |
utc | Zone of the time tags on the wire |
Unlike a full controlling system, iec103ctl never follows the link start-up with an automatic time synchronization and general interrogation: every command does only what it is asked.
Commands
Section titled “Commands”| Command | What it does |
|---|---|
client interrogate (gi) |
General interrogation: the state of every indication, until the termination with the same scan number |
client command |
General command with --fun, --inf and --value on|off; commands outside table 17 are refused before anything is sent. --wait-report waits for the change of state |
client clock |
Time synchronization, addressed and confirmed, or --broadcast to address 255 |
client identify |
The identification after a reset, and those of start-up and power on |
client generic headings|group|directory|entry|read|interrogate|write |
The generic services: read settings by group and entry with their descriptions, ranges and units; write one data set with execute or abort |
client disturbance list|get (fault) |
The list of recorded faults, and one record’s description, tags and channels, written as JSON (--output) or CSV (--csv) |
client monitor |
Poll and print every ASDU as it arrives, JSON Lines with --format json |
client scan |
Try every link address from --start to --end and list those that answer, with their identification |
server start |
Serve a simulated relay from --config (YAML or JSON) or the demo, on TCP or a serial port |
server generate-config |
Write the demo model |
iec103ctl client generic write --url tcp://10.0.0.20 --gin 1.2 --type float32 --value 1.25iec103ctl client generic write --url tcp://10.0.0.20 --gin 1.3 --type uint --size 2 --value 450 --mode abortiec103ctl client disturbance get --url tcp://10.0.0.20 --fan 7 --output fault7.json --csv fault7.csviec103ctl client scan --url serial:///dev/ttyUSB0 --start 1 --end 32There is no discover: a line has one controlling system and a terminal server’s port says nothing about the devices behind it. client scan finds the devices of a line.
Output and exit codes
Section titled “Output and exit codes”--format text, json or table, or IEC103CTL_FORMAT. A negative acknowledgement, a refused write or an aborted transfer is exit code 6; a read answered with invalid data (cause 43) is 7. iec103ctl adds the error codes link_down, transfer_aborted and no_identification. The rest are the codes shared by the four tools (exitcodes.md).