lib60870.NET 2.2 User Guide

Since an IEC 60870-5-104 (CS 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 passively waiting for connections.

In C# a connection is simply created by calling a Constructor of the Connection class:

This creates a new Connection object that is ready to connect to the server. If you can go with the default connection parameters (TCP port 2404 and a common set of the IEC 60870-5-104 parameters) you can now simply call the Connect method:

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

To use the Connection class you have to import the lib60870.CS104 namespace into your application:

CS101 provides two kind of serial connection modes for master/slave communication.

Balanced mode supports communication between a single master and a single slave using a dedicated serial line. 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 do not send spontaneously. They only respond after a request form the master. The master can address multiple slaves by using a broadcast address.

Configuring the serial port

SerialPort port = new SerialPort ();
port.PortName = "/dev/ttyUSB1";
port.BaudRate = 9600;
port.Parity = Parity.Even;
port.Handshake = Handshake.None;
port.Open ();

Setting the link layer parameters

LinkLayerParameters llParameters = new LinkLayerParameters();
llParameters.AddressLength = 2;
llParameters.UseSingleCharACK = false;

Create and use a new unbalanced master instance

CS101Master master = new CS101Master(port, LinkLayerMode.UNBALANCED, llParameters);
master.SetASDUReceivedHandler (asduReceivedHandler, null);
master.AddSlave (1);

master.SlaveAddress = 1;
master.GetFile (1, 30000, NameOfFile.TRANSPARENT_FILE, new Receiver ());

The balanced master is created the same way. Just the link layer mode parameter is different.

In balanced mode the slave address has only to be set one time, because there is only one client.

The LinkLayerStateChangedHandler can be used to track changes of the link layer state. This way it can be detected when there is an error or the other side’s link layer is no longer available.

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.

The call is non-blocking. You have to evaluate the response in the 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)!

You can also request a group of data items from a slave with a single request. On the master (client) side you can simply use the SendInterrogationCommand method 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 a with the SendClockSyncCommand method of the Connection class.

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

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 and operate command procedure.

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

To issue a single command you have to provide the proper TypeID (C_SC_NA_1) and pass a SingleCommand instance to the SendControlCommand method.

The constructor of SingleCommand 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.

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 IsNegative property of the received ASDU instance.

To configure and setup an IEC 60870-5-104 server/slave an instance of the Server class is required.

After the server instance is created it can be configured

The server provides three different modes.

The default 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 (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 (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 ServerMode property of the Server class.

Redundancy groups only have to be created explicitly when using the servermode 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 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.

The number of clients can be restricted with the MaxOpenConnections property of the Server class.

In this case the server will only allow two concurrent client connections.

The default TCP port for IEC 60870-5-104 is 2404. The port can be changed with the SetLocalPort method of the Server class.

Per default the server listens to all local IP addresses. With the SetLocalAddress method of the Server class it is possible to restrict the server to a single local IP address.

The maximum size of the event queue(s) can be set with the MaxQueueSize property of the Server class. The default size is 1000. Each queue entry needs approximately 260 bytes.

The ConnectionRequestHandler can be used to restrict the access to the server. With the return value the application can allow or deny the connection attempt of a client.

A ConnectionRequestHandler can be set with the SetConnectionRequestHandler method of the Server class. The second parameter is an arbitrary user provided object that will be passed to the handler when it is called. If not needed it can be set to null.

In the handler you can optionally check the client IP address against a whitelist of allowed clients or implement a blacklist.

After the server is configured it can be started with the Start method

To deactivate the IEC 60870-5-104 service the server can be stopped with the Stop method.

On the server side you should use the InterrogationHandler delegate to handle the Interrogation request. Depending on the QOI value your should return different information objects. For a simple system it is enough to only handle station interrogation requests (QOI = 20).

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 the COT = INTERROGATED_BY_STATION. After sending all information objects the server has to send the initial interrogation command message with COT = ACT_TERM to indicate that the transmission of the interrogation data is finished.

For spontaneous message transmission on the server side the API user has to allocate an ASDU object, add Information Objects to the ASDU and 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. Otherwise the messages will remain in the queue until a connection is activated.

CS104 The size of the queue is controlled by the property MaxQueueSize of the Server object..

These are the required steps:

1. Step: Create a new ASDU instance

   ASDU newAsdu = new ASDU (TypeID.M_ME_NB_1, CauseOfTransmission.PERIODIC, false, false, 2, 1, false);

2. Step: Add an information object to the ASDU

   newAsdu.AddInformationObject (new MeasuredValueScaled (110, -1, new QualityDescriptor ()));

3. Step: Add the ASDU to the transmission queue

   server.EnqueueASDU (newAsdu);

Multiple information objects can be included in the same ASDU when the information objects are all of the same type.

The return value of the AddInformationObject method indicates if the information object has been added successfully. When the ASDU capacity is already reached the return value is false and the InformationObject instance has not been added.

For lib60870.NET you should derive a new class from the InformationObject class.

The CS 101 master or slave protocols can also be used over a TCP/IP connection with the TcpServerVirtualSerialPort and TcpClientVirtualSerialPort classes. These classes can be used to configure the CS 101 master or slave as a TCP/IP client or server.

NOTE: This is a non-standard extension! According to the IEC 60870-5 standard TCP/IP has to be used according to IEC 60870-5-104 (CS 104).

To use TCP/IP instead of a serial connection you have to create an instance of the TcpServerVirtualSerialPort or TcpClientVirtualSerialPort class and handle the instance to the constructor of the CS101Master or CS101Slave class.

The Start and Stop methods are used to start and stop the TCP/IP client and server. The server class allows only a single client connection.

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

The following parameters are for the CS101/CS104 application layer and are stored in the lib60870.CS101.ApplicationLayerParameters class.

The LinkLayerParameters class stored the configuration parameters for the CS 101 link layer.

The following parameters are stored in APCIParameters objects.