IEC 61850 Driver

dc3-driver-iec61850 acts as an IEC 61850 MMS client. It maintains one MMS association per IED device and reads/writes data attributes addressed by an object reference and functional constraint (e.g. S1MMXU1.TotW.actVal / MX).

Protocol background

IEC 61850 is the standard for substation automation. Data objects are organized in a server model by logical device, logical node, and data object; the MMS protocol retrieves their values. This driver resolves an object reference and functional constraint, fetches the data values, and returns the first basic data attribute value.

• Driver name / code: IEC 61850 Driver / Iec61850Driver
• Type: DRIVER_CLIENT (MMS client to an IED server)
• Underlying library: OpenMUC openiec61850

Attribute configuration

Driver attributes (device-level driver-attribute)

Attribute	code	Type	Default	Description
Host	host	STRING	(empty)	IEC 61850 server (IED) address
Port	port	INT	102	MMS service port

Point attributes (point-attribute)

Attribute	code	Type	Default	Description
Object Reference	objectReference	STRING	(empty)	Data object reference, e.g. S1MMXU1.TotW.actVal
Functional Constraint	functionalConstraint	STRING	MX	MX, ST, CO, SP, SE

Command attributes (command-attribute)

Attribute	code	Type	Default	Description
Object Reference	objectReference	STRING	(empty)	Data object reference for commands

Collection and health

• Collection cycle: default cron 0/30 * * * * ?.
• Health/online: device health defaults to cron 0/15 * * * * ?, lease timeout 45 seconds.

Capability matrix

Capability	Supported	Notes
Read	✓
Write	✓ (boolean/int/float/visible-string by data type)
Subscribe	—

Implementation status: complete

The server model is retrieved once per association and cached; reads call getDataValues and take the first BasicDataAttribute value via getValueString().

Troubleshooting

• Cannot associate with the IED; the log shows Failed to associate IEC 61850 server: <host>:<port> → Cause: a missing host first raises Required attribute 'host' is missing; with host set, an unreachable address or a closed MMS port (default 102) fails the association. Fix: verify host / port on the device, run telnet <host> 102 from the driver's environment, and confirm the IED accepts MMS clients.
• Read raises IEC 61850 object reference not found: <ref> → Cause: the reference does not resolve in the server model — spelling, hierarchy, or functional constraint mismatch. The model is fetched once per association and cached, so nodes added on the IED afterwards stay invisible until reconnect. Fix: check objectReference and functionalConstraint one by one against the IED model description (SCD/ICD); after a model change, reconnect — updating or deleting the device closes the association, or restart the driver.
• functionalConstraint set to a value outside the enum → Cause: the driver parses it with Fc.valueOf(name.toUpperCase()); an unknown name throws and surfaces wrapped as IEC 61850 read failed / write failed. Fix: use standard functional constraints such as MX / ST / CO / SP / SE.
• Write raises IEC 61850 node has no writable data attribute → Cause: the reference resolves to a structural node (a logical node or data object), not a writable data attribute. Fix: point objectReference at a leaf attribute such as S1MMXU1.TotW.actVal.
• Write raises Unsupported IEC 61850 data type, or the value never lands → Cause: the value string is parsed according to the target attribute's type; only boolean, 8/16/32/64-bit integers, 32/64-bit floats, and VisibleString are supported, and unparseable numerics or unsupported types throw. Booleans are the exception — they go through Boolean.parseBoolean, where only true means true and every other string is silently written as false. Fix: make sure the value parses for the target type — no non-numeric strings into a float attribute.
• Every read/write failure is followed by a reconnect, and the first round after it is slower → Cause: any exception from read() / write() invalidates the association — connection closed, cache entry removed — and the next access re-associates and re-fetches the server model. Fix: frequent reconnects usually mean an unstable network or an IED rejecting service; correlate the timestamps of the Driver connection established log lines.

How it lands in IoT DC3

One Device maps to one IED, with host / port set on the device. The driver caches one MMS association per deviceId: the first access — a read, a write, or a health check — establishes the connection and immediately calls retrieveModel() to cache the whole server model; every later read and write for that device reuses that association instead of reconnecting. Onboarding more IEDs means more devices, each holding its own independent association.

Both read and write consume only point attributes. read() locates the node in the cached model via objectReference + functionalConstraint (default MX), issues getDataValues, and takes the first basic data attribute's string value — when the node has no data attribute, it falls back to the node's toString(). write() locates the node with the same point attributes: it first issues getDataValues to learn the target attribute's current type, parses the command value into that type, then writes back with setDataValues. It writes only the first basic data attribute, so always point the reference at a leaf.

Integration with the rest of the platform: the health check is exactly client.isOpen(), and it establishes the association first when none exists; updating or deleting the device closes and removes the association through the metadata-event hook; a failed read or write likewise invalidates the association for the next access to rebuild. validate() / validatePoint() check that host and objectReference are present, reporting missing ones in the validation report.

Minimal onboarding example

1. Create a Device using IEC 61850 Driver, set host=<ied-address> and port=102.
2. Add a Point (READ_ONLY) with objectReference=S1MMXU1.TotW.actVal and functionalConstraint=MX.
3. Start the driver; the measurement is polled on the collection cycle.

Further reading

• Driver overview — entry point to all protocol drivers and selection
• Driver capability matrix — quick reference of read/write/subscribe capabilities
• Device onboarding — a complete onboarding walkthrough