CLI toolsiec101ctl
Interrogate, monitor and command IEC 101 stations on a serial port or behind a terminal server, unbalanced or balanced, with any field sizes; measure the line delay, scan a line for stations, or simulate an RTU. Part of iec60870ctl.
Install
Linux and macOS
curl -fsSL https://get.otfabric.io/iec101ctl | sh
Windows (PowerShell)
irm https://get.otfabric.io/iec101ctl.ps1 | iex
CI, containers and device images
curl -fsSL https://get.otfabric.io/iec101ctl | env OTF_UNMANAGED_INSTALL=/usr/local/bin sh
One static binary for Linux (x86-64, ARM64, ARMv7), macOS (Intel, Apple silicon) and Windows (x86-64, ARM64), with no runtime to install. The installer checks the release's SHA-256 checksum, installs per user without sudo, and upgrades in place when you run it again. Pin a release withOTF_VERSION. All install options. To build from source: go install github.com/otfabric/iec60870ctl/cmd/iec101ctl@latest.
First commands
# No station at hand: start the built-in demo station on port 2401
iec101ctl server start
# What does this station hold? General interrogation over a terminal server
iec101ctl client interrogate --url tcp://127.0.0.1:2401
# The same on a serial port, 9600 8E1
iec101ctl client interrogate --url serial:///dev/ttyUSB0 --link-address 3 --ca 3
# Watch events and measured values as they arrive
iec101ctl client monitor --url tcp://127.0.0.1:2401 --interrogate
# Operate a disconnector with select-before-operate
iec101ctl client command --url tcp://127.0.0.1:2401 --type double --ioa 5001 --value off --mode sbo
# Which stations answer on this multidrop line?
iec101ctl client scan --url serial:///dev/ttyUSB0 --method link --start 1 --end 30
The iec101ctl guide walks through every command group, connection option and safety rule.
For scripts, CI and containers
iec101ctl is as easy to read for a pipeline as for a person. It follows the same conventions as every OT Fabric tool, so a script written for one protocol carries over to the next.
- JSON output.
--format json, or IEC101CTL_FORMAT=json for a whole job. One JSON document per command, JSON Lines for streams, and a single {"error": {"kind", "code", "message"}} object on failure. Field names are a documented contract: json-output.md. - Clean streams. The result goes to stdout; progress, connection state and debug traces go to stderr.
- Stable exit codes from the shared OT Fabric table, so a script can tell a missing connection (4) from a timeout (5) or a refusal by the device (6). Which command returns what: exitcodes.md.
- Aligned version reporting.
iec101ctl version --json prints name, version,tag, commit, built, libraries (the OT Fabric stacks inside the binary), go andplatform, with the same keys in every tool. - Pinned installs with
OTF_VERSION, and OTF_UNMANAGED_INSTALL for images that must not touch PATH or shell profiles.
The exit-code table
| Code | Meaning |
|---|
0 | Success |
1 | Findings: the command completed and its result reports problems, such as a file that does not validate or a diagnosis with a failing check |
2 | Usage: unknown command or flag, a missing argument |
3 | Invalid input: a flag value, a file or a combination that does not make sense. Nothing was sent |
4 | Transport: the connection could not be made, or was lost |
5 | Timeout: the device did not answer in time |
6 | Protocol: the device refused the request, or broke the protocol |
7 | Partial success: a valid result was written, and it holds failures |
8 | Unsupported: the device, or this platform, does not support what was asked |
9 | Permission: the device or the operating system refused, such as raw-socket access without the capability |
10 | Output or internal error |
130 | Interrupted by Ctrl-C or SIGTERM before a result |
Each tool uses the codes that apply to it; a code never changes meaning between tools.
In a Dockerfile
FROM debian:bookworm-slim
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates curl \
&& curl -fsSL https://get.otfabric.io/iec101ctl \
| env OTF_UNMANAGED_INSTALL=/usr/local/bin sh \
&& rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["iec101ctl"]
Scripts, CI and containers has GitHub Actions and GitLab CI examples and shows how to use a simulator as a test fixture.
Protocols
- IEC 60870-5-101: Serial telecontrol between control centres and RTUs: the same data model as IEC 104, on point-to-point and multidrop lines, radio and modem links.
The README on GitHub has the full feature list, examples and changelog.