Guide

IEC 61850

Reads and writes MMS objects on IEDs, addressed by IED name plus object reference — reports preferred over polling.

This is the protocol reference for the IEC 61850 agent. For everything else in the config format, see Agent configuration.

Driver address

ied and reference together are the join key (ied::reference), so the same MMS path on two different IEDs doesn't collide. ied is a name you choose — it must match a key in the agent's own IED map (its docker image config, below), which is what actually holds the connection. reference is the MMS object reference including its functional constraint, e.g. LD0/MMXU1$MX$TotW$mag$f.

acquisition picks how the value is read, defaulting to report_only:

report_only — only accept values pushed by an enabled report dataset on the IED.
poll_if_unreported — prefer reports; poll (GetDataValues) for points not covered by any subscribed dataset.
poll — always poll, even when the point is also covered by a report.

{
  "name": "total_watts",
  "equipment": "bay7",
  "type": "analogical",
  "store": true,
  "driver": {
    "type": "analogical",
    "ied": "bay7",
    "reference": "LD0/MMXU1$MX$TotW$mag$f",
    "acquisition": "report_only"
  }
}

Commands

Same ied and reference, this time to a control object (e.g. CTRL/CSWI1$CO$Pos). control_model is direct (Operate only) or sbo (Select-before-operate — Select, then Operate with the same value). test optionally sets the IEC 61850 Test flag on the control; check optionally requests synchrocheck and/or interlock_check from the IED before it allows the operate:

{
  "name": "pos.open",
  "equipment": "bay7",
  "driver": {
    "type": "discrete",
    "value": 1,
    "ied": "bay7",
    "reference": "CTRL/CSWI1$CO$Pos",
    "control_model": "sbo",
    "check": { "synchrocheck": true, "interlock_check": true }
  }
}

Docker image

Image: khorde/iec61850-agent:latest. It doesn't serve an API — the only thing on 9090 is a liveness check, GET /health (returns Healthy!) — same compose shape as every agent (see Agent configuration). Save the agent's service account key next to it, renamed to service-user.json. Its own config.yaml:

iec61850:
  bay7:
    address: <bay7-ied-ip>
    port: 102
  bay8:
    address: <bay8-ied-ip>
    port: 102
use_buffered_reports: false
gi_interval: 60s
poll_interval: 5s
agent:
  broker:
    ip: host.docker.internal
    port: "4222"
    tls: false
  credentials:
    url: http://auth.localhost:9310
    service_account_path: service-user.json
  command_timeout: 10s

iec61850 is the agent's own IED map, keyed by the ied name used in every driver above — one entry per substation device, each with its own connection. The agent opens a connection to every IED listed here on startup, whether or not a measurement or command references it yet.

use_buffered_reports — false (the default) uses only unbuffered report control blocks (URCBs): you see changes as they happen while connected, but nothing is replayed after a drop. Set it true to use buffered report control blocks (BRCBs) instead, so the IED queues events while the agent is disconnected and replays them on reconnect — if the IED supports it.
gi_interval — how often to re-run a full General Interrogation on every enabled report dataset, independent of whatever reports already arrived. It's a periodic resync against drift, not how new values normally arrive. Omit to disable it — a single GI still runs once when a dataset is first enabled.
poll_interval — how often poll and uncovered poll_if_unreported measurements are read with GetDataValues. Omit it only if every measurement uses report_only (the default) — a poll measurement never updates without a poll_interval to drive it.

A few more advanced settings — reconnect backoff, exclusive RCB reservation — are optional too; the defaults work for a first connection.

Agent configuration

The full schema shared by every protocol. Agent configuration.

Other protocols

REST and IEC 60870-5-104 agents work the same way.

Taking this past your laptop?

Talk to us