lib60870 - IEC 60870-5-101/104 C Source Code Library User Guide - Version 2.3.0

CS101_ASDU newAsdu = CS101_ASDU_create(alParams, false, CS101_COT_INTERROGATED_BY_STATION,
      0, 1, false, false);

bool isTest = CS101_ASDU_isTest(newAsdu);

CS101_ASDU_destroy(newAsdu);

Since an IEC 60870-5-104 connection is based on a TCP client/server connection the connection will be established by the client(master). The server(slave or outstation) is usually passively waiting for connections.

A new connection is simple created by calling a the CS104_Connection_create function of the CS104_Connection type:

This creates a new CS104_Connection object that is ready to connect to the server. The parameters are the hostname or IP address of the server and the TCP/IP port (usually 2404). For the port parameter you can also set -1 to use the default port.

After the connection object is created you can now simply call the CS104_Connection_connect function to connect to the server:

The parameter con is the reference to the connection object created above.

When the connection has been established correctly you can use the connection object to send commands and receive data.

When you finished using the connection object you have to call

To release all resources allocated by the object. After using the destroy function you cannot use any functions with the con reference!

CS 101 provides two link layer modes for master/slave connections.

Balanced mode supports communication between a single master and a single slave using a dedicated serial line. This mode is "balanced" in the sense that both ends can spontaneously send messages at any time.

Unbalanced mode supports communication between a single master and multiple slaves on a serial bus. Each slave is addressed by its unique link layer address. Slaves are not allowed to send messages spontaneously. They only respond following a request from the master. The master can address multiple slaves at once by using a broadcast address.

Configuring the serial port

  SerialPort port = SerialPort_create("/dev/ttsS0", 9600, 8, 'E', 1);

Create and use a new unbalanced master instances

CS101_Master master = CS101_Master_create(port, NULL, NULL, IEC60870_LINK_LAYER_UNBALANCED);

CS101_Master_setASDUReceivedHandler(master, asduReceivedHandler, NULL);

CS101_Master_addSlave(master, 1);

CS101_Master_useSlaveAddress(master, 1);
CS101_Master_sendProcessCommand(master, CS101_COT_ACTIVATION, 1, sc);

Balanced master

CS101_Master master = CS101_Master_create(port, NULL, NULL, IEC60870_LINK_LAYER_BALANCED);

CS101_Master_useSlaveAddress(master, 3);
CS101_Master_setASDUReceivedHandler(master, asduReceivedHandler, NULL);

Setting the link layer parameters

LinkLayerParameters llParams = CS101_Master_getLinkLayerParameters(master);
llParams->useSingleCharACK = false;

In general an application is concerned with sending application layer messages (ASDUs) to the slave. The master side API supports generic and specialized functions to send messages to the slave. When sending system commands or process commands it is recommended to use the specialized functions because they help to create ASDUs that comply to the standards. These specialized functions are explained in the following sections. They exist generally in two variants for CS101 and CS104.

For the general case it is possible to send arbitrary ASDUs by using the CS101_Master_sendASDU or CS104_Connection_sendASDU functions.

For receiving application layer messages the application has to implement the CS101_ASDUReceivedHandler callback.

This callback handler has to be installed with the CS104_Connection_setASDUReceivedHandler or CS101_Master_setASDUReceivedHandler function.

All callback handler have a generic reference parameter with the name "parameter" in its function signatures. This parameter can be used by the user to provide application specific context information to the callback handler. This parameter will be set with the install function of the callback handler (like CS101_Master_setASDUReceivedHandler in the example above). If not used this parameter can be set to NULL.

The IEC 60870 documents don’t recommend this service (cyclical data requests or polling) but it is an easy way to get the required data. You just need to know the common address (CA) and the information object address (IOA) to create the proper request.

This call is non-blocking. You have to evaluate the response in the CS101_ASDUReceivedHandler callback function.

Typically it is expected that the server response contains only the basic data type without timestamps (that is using the message types for a specific data type that does not contain the timestamps)!

It is also possible to request a group of data items from a slave with a single request. On the master (client) side you can simply use the sendInterrogationCommand function of the Connection object:

The client/master side method signature looks like this:

The parameter ca is the common address (CA) as in the other methods. The parameter qoi is the "Qualifier of interrogation" (QOI). The value "20" (indicating "station interrogation") for the QOI indicates that it is an request for all data points. Other values for QOI will indicate that the client (master) only wants to receive data from a specific interrogation group.

For the clock synchronization procedure the controlling station (master) sends a C_CS_NA_1 ACT message to the controlled station (slave) containing the current valid time information as a CP56Time2a typed time value. The controlled station has to update its internal time and respond with a C_CS_NA_1 ACT_CON message after all queued time-tagged PDUs have been sent.

Clock synchronization of the controlled station can be done with the CS104_Connection_sendClockSyncCommand function for CS104 or the CS101_Master_sendClockSyncCommand for CS101.

First a CP56Time2a timestamp has to be created and initialized:

Or when using dynamic memory allocation and CS 101:

NOTE: The Hal_getTimeInMs function is platform independent way to get the current time as milliseconds since 00:00:00 1. January 1970 UTC. You can also use your own function to get the time.

Commands are used to set set points, parameters or trigger some actions at the controlled station.

The following command types (data types are available for commands):

• C_SC (single command) - to control binary data (switch…​)

• C_DC (double command) - to control binary data with transition state (moving switch…​)

• S_RC (step position command) - to control a step position

• S_SE (setpoint command) - to control a set point (scaled value, normalized value, floating point values) - may also be used to set parameters, alarm limits etc.

These command types are also available in a version with a time tag (CP56TIme2a).

There are two different command procedures available. The direct operate command procedure and the select before operate command procedure.

To send a command for the direct operate command procedure you have to send an ACTIVATION APDU to the controlled station.

The constructor of SingleCommand data type has the following signature:

In order to send a direct operate command the selectCommand parameter should be false. The qualifier (qu) should in general be set to 0.

For select before operate the command has to be sent with the selectCommand parameter set to true to select the control output. In the next step an additional command with selectCommand set to false has to be sent to cause the actual command execution.

If the command has been successful the outstation will answer with an ACT_CON response message with the negative flag not set. In case the outstation cannot execute the command it will also answer with an ACT_CON response but with the negative flag set. You can check if this flag is set with the CS101_ASDU_isNegative function used with the received CS101_ASDU instance.

For a CS 104 master a command can be sent the same way by using the CS104_Master_sendProcessCommandEx function.

To configure and setup an IEC 60870-5-104 server/slave an instance of the CS104_Slave data type is required.

After the server instance is created it can be configured

The server provides three different modes concerning the support of redundant connections and event queue handling:

The default mode (CS104_MODE_SINGLE_REDUNDANCY_GROUP) allows only a single active client connection. An active client connection is a connection where ASDUs (application data units) are sent. All other connections are only standby connections that don’t send application layer data. There is a single queue for events. Events are also stored when no client is connected or when no connection is active.

The second mode (CS104_MODE_CONNECTION_IS_REDUNDANCY_GROUP) allows multiple active client connections. Every connection has its own event queue. The event queue will be deleted when the client connection is closed. This mode can be used when more than one client has to access the application data. This mode is easy to use. But the drawback of this mode is that events are lost when no client is connected.

The third mode (CS104_MODE_MULTIPLE_REDUNDANCY_GROUPS) allows multiple active client connections while preserving events when no client is connected. In this mode clients can be assigned to specific redundancy groups. The assignment is based on the IP address of the client. A redundancy group can have multiple simultaneous connections but only one of these connections can be active. The number of activated connections is restricted by the number of redundancy groups. Each redundancy group has a dedicated event queue.

The server mode can be set with the CS104_Slave_setServerMode function:

Redundancy groups only have to be created explicitly when using the servermode CS104_MODE_MULTIPLE_REDUNDANCY_GROUPS. You can assign multiple IP addresses to a redundancy group. Incoming connections from one of these IP addresses will then automatically be assigned to this specific redundancy group.

When a redundancy group has no assigned IP address it works as a "catch all" group. This means that all incoming connections that are not assigned to one of the other groups will end up in this group.

Similar to the master side the CS101 slave side can also be configured for one of the two link layer modes (balanced or unbalanced). A CS101 slave is represented by a CS101_SLave object.

Before a CS101_Slave object can be created a SerialPort object is required. The SerialPort object represents the serial interface and its configuration.

The created SerialPort object is required for the CS101_Slave_create function:

This function has the following signature:

Optionally the link layer parameters and application layer parameters can be specified. If the default values should be used these parameters can be skipped (set to NULL). The last parameter specifies if the balanced or unbalanced mode is used.

For the serial slave it is also required to set a link layer address:

Before starting or running the server it is recommended to set the callback functions to handle slave events. The following callback handler types are available (please the the API reference manual for function signature details). Some of them are only available for CS 104 servers and some only for CS101 slaves.

After the server is configured it can be started with the CS104_Slave_start function. This function starts a new background thread that is listening for incoming client connections.

To deactivate the IEC 60870-5-104 service the server can be stopped with the CS104_Slave_stop function.

For spontaneous or periodic message transmission on the server/slave side the API user has to allocate a CS101_ASDU object that represents a single ASDU, add Information Objects to the ASDU, and finally put the ASDU into the transmission queue. The transmission queue is a FIFO (first in first out) list. If the queue is full the oldest message will be deleted and replaced by the newly added message. Messages will only be sent if the there is an active client connection or working link layer connection. Otherwise the messages will remain in the queue until a connection is activated.

CS 104: In the CS 104 slave the queue size is determined by the maxLowPrioQueueSize parameter of the CS104_Slave_create function. If the maxLowPrioQueueSize parameter is set to zero the queue will always have the size defined with by CONFIG_SLAVE_MESSAGE_QUEUE_SIZE. The second parameter maxHighPrioQueueSize determines the size of the high priority data queue. Messages that are put into this queue bypass the messages of the low priority queue. The high priority queue is used for request responses in library callback handlers.

The following steps have to be done to send spontaneous or periodic messages:

1. Step: Create a new CS101_ASDU instance (use CS101_COT_PERIODIC for periodic data and CS101_COT_SPONTANEOUS for spontaneous data)

   CS101_ASDU newAsdu = CS101_ASDU_create(alParameters, false, CS101_COT_PERIODIC, 0, 1, false, false);

2. Step: Create a new information object instance containing the data to send

   InformationObject io = (InformationObject) MeasuredValueScaled_create(NULL, 110, scaledValue, IEC60870_QUALITY_GOOD);

3. Step: Add the new information object to the ASDU

   CS101_ASDU_addInformationObject(newAsdu, io);

4. Step: Release the information object memory

   InformationObject_destroy(io);

5. Step: Put the ASDU into the class 2 data queue for transmission

   CS101_Slave_enqueueUserDataClass2(slave, newAsdu);

6. Step: Release the ASDU memory

   CS101_ASDU_destroy(newAsdu);

NOTE: For CS 104 you have to use the CS104_Slave_enqueueASDU function in step 5:

On the server side you should use the InterrogationHandler callback function to handle the Interrogation request. Depending on the QOI (Qualifier of interrogation) value you can return different information objects. For a simple system it is enough to only handle station interrogation requests (QOI = 20). The QOI values 21-36 are used for the interrogation groups (1-16). It is up to the slave implementer to assign information objects to interrogation groups.

According to the specification the server has to respond the ACTIVATION request from the client with the ACT_CON response followed by ASDUs containing the information objects with CS101_COT_INTERROGATED_BY_STATION for a station interrogation or COT that represent the respective interrogation group (e.g. CS101_COT_INTERROGATED_BY_GROUP_1 for interrogation group 1). After sending all information objects the server has to send the initial interrogation command message with COT = CS101_COT_ACTIVATION_TERMINATION to indicate that the transmission of the interrogation data is finished.

Inside of the interrogation handler the IMasterConnection interface can be used to send the interrogated data back to the client/master. The CS101_ASDU and InformationObject instances created inside the interrogation handler are in the responsibility of the user and have to be released with the appropriate functions (CS101_ASDU_destroy and InformationObject_destroy) when they have been allocated dynamically before.

The read command C_RD_NA_1(102) can be used by the client/master to read the value of a particular data point in monitoring direction.

The most convenient way to handle read commands at the server/slave side is to implement the callback function type CS101_ReadHandler. The read handler can be installed by the CS104_Slave_setReadHandler or CS101_Slave_setReadHandler functions for a CS 104 server or CS 101 slave.

In the read handler you have either to send the same read command but with a COT that indicates an error. Or you have to create the ASDU of the proper type for the data point and send this back to the client/master. When doing the latter you have to use the COT CS101_COT_REQUEST to indicate that the message was caused by a read request.

Server mode

CS104_Slave_setServerMode(slave, CS104_MODE_CONNECTION_IS_REDUNDANCY_GROUP);

Restrict the number of client connections

CS104_Slave_setMaxOpenConnections(slave, 2);

Setting local port and IP address

CS104_Slave_setLocalPort(slave, 2405);

CS104_Slave_setLocalAddress(slave, "192.168.1.50");

Set a connection request handler to restrict the access and track connections

CS104_Slave_setConnectionRequestHandler(slave, connectionRequestHandler, NULL);

static bool connectionRequestHandler(void* parameter, const char* ipAddress)
{
  /* Allow only known IP addresses! */
  /* You can implement your allowed client whitelist here */
  if (strcmp(ipAddress, "127.0.0.1") == 0) {
    return true;
  else
    return false;
}

Create a secure connection with TLS

TLSConfiguration tlsConfig = TLSConfiguration_create();

TLSConfiguration_setChainValidation(tlsConfig, false);
TLSConfiguration_setAllowOnlyKnownCertificates(tlsConfig, true);

TLSConfiguration_setOwnKeyFromFile(tlsConfig, "server-key.pem", NULL);
TLSConfiguration_setOwnCertificateFromFile(tlsConfig, "server.cer");
TLSConfiguration_addCACertificateFromFile(tlsConfig, "root.cer");

TLSConfiguration_addAllowedCertificateFromFile(tlsConfig, "client1.cer");

/* create a new slave/server instance */
CS104_Slave slave = CS104_Slave_createSecure(100, 100, tlsConfig);

The debug output to the console can be enabled by setting CONFIG_DEBUG_OUTPUT to 1. This will enable the debug output by default. The debug output can be disabled my using the function Lib60870_enableDebugOutput. The default implementation of the debug output function will print to the console (using printf). If you need to redirect the output the most easy way would be to change the implementation of the debug output lib60870_debug_print function in lib60870_common.c.

The library contains a C header file to determine the platform byte order (src/inc/internal/platform_endian.h) when using the GCC compiler. This depends on defines that are provided by the C compiler. On some older big endian platforms like PowerPC or Coldfire depending on the compiler this may fail. You may have to define

when compiling the library code.

E.g. put

on the GCC command line when the platform byte order is big endian.

Some configuration options are fixed at compile time of the library code. These options can be found in the file lib60870_config.h.

Compile time options include the support for specific CS 104 redundancy modes, support for threads and semaphores (required when the library uses threads), maximum number of TCP connections for CS 104 slave, and others.

The library supports the following ASDU (application service data unit) types.

The following parameters are stored in CS104_ConnectionParameters objects.