This tutorial is aimed to guide you in using the IEC 61850 control facilities with libIEC61850. The client and server control APIs are designed to be simple to use while providing access to all aspects of the different IEC 61850 control models. A very short general overview of the control functions of IEC 61850 can also be found here.

The library supports the following control operations: select, select-with-value, operate, time-activated-operate and cancel. These control operations can be applied to controllable data objects that have their control model (ctlModel attribute) set to other values than status-only (0). Depending on the selected control model also only a subset of these operations are allowed. E.g. in direct-control only the operate, time-activated-operate and cancel operations are allowed.

Using control server side

For using the control model server side you have to install callback handlers for the controllable data object for which you want to enable control support.

iedServer = IedServer_create(&iedModel);

IedServer_setControlHandler(iedServer, 
   IEDMODEL_GenericIO_GGIO1_SPCSO1, 
   (ControlHandler) controlHandler,
   IEDMODEL_GenericIO_GGIO1_SPCSO1);

LibIEC61850 knows three different types of control related callback functions. They will be invoked by the server stack in the different states of the IEC 61850 control model (see figure 1 for the basic control states and the related callback functions).

Figure 1: The basic state machine of IEC 61850 control models and related callback functions.

If not operated the control state machine is in the ready state. Once operated (after receiving an operate request from a client the state machine switches to the PerformCheck state. In this state the server application can perform “static” tests to check if the process state allows an operation of the control. In case of an error the server sends a negative response and switches back to the ready state. In case of success the control state machine switches to the WaitForExecution state. In this state “dynamic” tests can be performed.

In most cases only one callback function (of type ControlHandler) is required. If only this callback handler is present the server stack assumes that the “PerformTest” and “WaitForExecution” states were successfully finished.

Here you can see the definitions of the control callback functions (from iec61850_server.h):

typedef CheckHandlerResult (*ControlPerformCheckHandler) (void* parameter, MmsValue* ctlVal, bool test, bool interlockCheck,
        ClientConnection connection);

typedef ControlHandlerResult (*ControlWaitForExecutionHandler) (void* parameter, MmsValue* ctlVal, bool test, bool synchroCheck);

typedef ControlHandlerResult (*ControlHandler) (void* parameter, MmsValue* ctlVal, bool test);

The callback functions are shown in the order they are executed by the server stack. Each of the functions has a user provided parameter as the first argument. This can e.g. be used to distinguish between different control objects (here you can simply pass the reference to the control object node when installing the callback function). The second parameter (ctlVal) is the control value (set point value) of the operate or select-with-value request from the client. This is of course the most important parameter. The third parameter (test) indicates if the client indicates that this control operation is for test purposes only and should not be applied to the controlled process.

The ControlPerformCheckHandler and ControlWaitForExecutionHandler both have an additional parameter. The first has the interlockCheck parameter that is intended to indicate that the server should check the interlocking conditions for this control object prior to performing the control action. Interlock check means that the server has to check the state of other control objects to decide if the control operation is allowed. The latter has the synchroCheck parameter. This parameter indicates that some synchronization conditions have to be met prior to switching a circuit.

Note: The control handler is always executed inside the thread context of the server. This means the callback handlers should always return immediately. Otherwise important stack functions like report and GOOSE processing will not work properly. If the control handlers have to perform long running tasks they have to return CONTROL_RESULT_WAITING. Then the handler will be called again later until the control task is completed. This behavior is different to library versions prior to 0.8!

The control handler is responsible to inform the server if a timeout or other error condition happens. In this case the handler has to return with CONTROL_RESULT_FAILED.

Client side control functions

The usage of control client side is illustrated by the iec61850_client_example3 in the source distribution. Here is a code snippet:

IedClientError error;

IedConnection con = IedConnection_create();

IedConnection_connect(con, &error, hostname, tcpPort);

ControlObjectClient control
 = ControlObjectClient_create("simpleIOGenericIO/GGIO1.SPCSO1", con);

The first step is to create and open a connection to the server. In the next step a ControlObjectClient instance has to be created. The first argument is the object reference of the control object. The second parameter is the connection object of the server connection.

If the control object’s control model is set to direct-control (this can be checked by inspecting the ctlModel attribute value, 1 = direct-control) an operate command can be issued. This is done by creating an MmsValue instance that represents the control value (ctlVal is the target or set point value of the control operation). This instance has to be passed to the operate method:

        
MmsValue* ctlVal = MmsValue_newBoolean(true);

ControlObjectClient_operate(control, ctlVal, 0)

The last parameter of the ControlObjectClient_operate method is the execution time. This parameter is used to specify the time of execution as milliseconds since 01/01/1970 UTC. If set to 0 this will cause an immediate execution. If set to a value in the future the execution is performed later. The latter is called “time activated control”.

Figure 2: The state machine of IEC 61850 select-before-operate control model.

If the control object is configured for select-before-operate (ctlModel = 2) a select command has to be sent to the server prior to the operate command. After a successful select command the server side control object is reserved (selected) for the client that issued the select command. Other clients are not allowed to operate the control if it is selected.

control = ControlObjectClient_create(
     "simpleIOGenericIO/GGIO1.SPCSO2", con);

if (ControlObjectClient_select(control)) {
  ctlVal = MmsValue_newBoolean(true);

  ControlObjectClient_operate(control, ctlVal, 0);
    
  MmsValue_delete(ctlVal);
}

The select state can timeout after a defined time if the sboTimeout attribute is present in the control object and set to a value different from 0. After performing the operation the select state is either leaved if the sboClass attribute is set to operate-once (0) or maintained if sboClass is set to operate-many (1).

The selected state will also be left if the clients sends a cancel request:

ControlObjectClient_cancel(control);

The cancel request can also be used to cancel time activated control tasks at the server.

Control objects and properties

IEC 61850-7-3 defines different types of controllable objects. These types are called controllable common data classes (CDC). An overview over these object types and some basic properties can be found in table 1. The most important properties for the user are the types of the stVal and ctlVal attributes. It should be noted that the IEC 61850 ENUM types are mapped to MMS_INTEGER variables in libIEC61850.

The AnalogueValue type is mapped to an MMS_STRUCTURE with a single element being either an MMS_INTEGER or an MMS_FLOAT variable. Note: In the case that the status of a CDC is of type AnalogueValue the status attribute is named mxVal instead of stVal and has the functional constraint MX instead of ST!

The ValWithTrans type is mapped to an MMS_STRUCTURE with one or two members. The first is the position indication and is an MMS_INTEGER variable in the range -64 to 63. The second is an MMS_BOOLEAN indicating that the position is in a transient state. Note: In the case that the status of a CDC is of type ValWithTrans the status attribute is named valWTr instead of stVal!

Abbreviation	Name	Description	stVal	ctlVal
SPC	Controllable Single Point	A simple boolean control (e.g. a simple switch or a LED)	BOOLEAN	BOOLEAN
DPC	Controllable Double Point	A boolean control with intermediate states (e.g. a slow moving switch)	ENUM	BOOLEAN
INC	Controllable Integer Status	An integer type control	INT32	INT32
ENC	Controllable Enumerated Status		ENUM	ENUM
BSC	Binary Controlled Step Position Information		ValWithTrans	ENUM (stop | lower | higher | reserved)
ISC	Integer Controlled Step Position Information		ValWithTrans	INT8 (-64 ... 63)
APC	Controllable Analog Process Value	A control for analog values.	AnalogueValue	AnalogueValue
BAC	Binary Controlled Analog Process Value		AnalogueValue	ENUM (stop | lower | higher | reserved)

Table 1: The controllable common data classes in IEC 61850-7-3.

Table 2 gives an overview of the data attributes that are relevant for control operations. Some of the attributes are mandatory for every controllable data object (M), some are only mandatory for specific CDCs (C) and some are optional (O). Some attributes have to be handled by the user (API client) when the control handlers are invoked. Other attributes are handles automatically by the libIEC61850 server stack.

Name	O/M/C	handled by user	handled by stack	Description
stVal / valWTr / mxVal	O	X	-	status or measurement value of the controlled process value
sboTimeout	O	-	X	timeout of the select operation. The value is in milliseconds. There is no timeout if set to 0.
ctlModel	M	-	X	The control model of the controllable object. Either status-only, direct-control, select-before-operate, direct control with enhanced security, select-before-operate with enhanced security
sboClass	O	-	X	either operate-once or operate-many. Indicates if the select state is leaved after an operation
operTimeout	O	X	-	timeout of the operate state in ms.

Table 2: The attributes of controllable data objects.