Skip to content

Latest commit

 

History

History
158 lines (127 loc) · 10.5 KB

README.md

File metadata and controls

158 lines (127 loc) · 10.5 KB
Raw

IEC 60870-5-104 Client Protocol Driver

This driver implements a client for the IEC 104 protocol. It can have multiple connections to IEC-104 servers on multiple computers, if needed.

To configure the driver it is necessary to create one or more driver instances and at least one connection per instance. Also the tags intended to be updated should be configured appropriately.

Configure a driver instance

To create a new IEC 104 client instance, insert a new document in the protocolDriverInstances collection using a command like this:

use json_scada_db_name
db.protocolDriverInstances.insert({
        protocolDriver: "IEC60870-5-104",
        protocolDriverInstanceNumber: 1,
        enabled: true,
        logLevel: 1,
        nodeNames: ["mainNode"], 
        activeNodeName: "mainNode",
        activeNodeKeepAliveTimeTag: new Date(),
        keepProtocolRunningWhileInactive: false
    });
  • protocolDriver [String] - Name of the protocol driver, must be "IEC60870-5-104". Mandatory parameter.
  • protocolDriverInstanceNumber [Double] - Number of the instance. Use 1 to N to number instances. For the same driver instance numbers should be unique. The instance number makes possible to run use multiple processes of the driver, each one with a distinct configuration. Mandatory parameter.
  • enabled [Boolean] - Controls the enabling of the instance. Use false here to disable the instance. Mandatory parameter.
  • logLevel [Double] - Number code for log level (0=minimum,1=basic,2=detailed,3=debug). Too much logging (levels 2 and 3) can affect performance. Mandatory parameter.
  • nodeNames [Array of Strings]- Array of node names that can run the instance. Use more than one node for redundancy. Each redundant instance running on separate nodes will have the same connections and data enabled for scanning and update. Mandatory parameter.
  • activeNodeName [String] - Name of the protocol driver that is currently active. This is updated by the drivers for redundancy control.Optional.
  • activeNodeKeepAliveTimeTag [Date] - This is updated regularly by the active driver. Optional.
  • keepProtocolRunningWhileInactive [Boolean] - Define a driver will keep the protocol running while not the main active driver. Currently only the false value is supported. Optional.

Changes in the protocolDriverInstances config requires that the driver instances processes be restarted to be effective.

Configure client connections to IEC-104 servers

Each instance for this driver can have many client connection defined that must be described in the protocolConnections collection.

use json_scada_db_name
db.protocolConnections.insert({
    protocolDriver: "IEC60870-5-104",
    protocolDriverInstanceNumber: 1,
    protocolConnectionNumber: 61,
    name: "KAW2",
    description: "KAW2 Station IEC-104",
    enabled: true,
    commandsEnabled: true,
    ipAddressLocalBind: "", 
    ipAddresses: ["192.168.0.21:2404", "192.168.0.22:2404"],
    localLinkAddress: 1,
    remoteLinkAddress: 205,
    giInterval: 300,
    testCommandInterval: 5,
    timeSyncInterval: 650,
    sizeOfCOT: 2,
    sizeOfCA: 2,
    sizeOfIOA: 3,
    k: 12,
    w: 8,
    t0: 10,
    t1: 15,
    t2: 10,
    t3: 20,
    stats: null
});
  • protocolDriver [String] - Name of the protocol driver, must be "IEC60870-5-104". Mandatory parameter.
  • protocolDriverInstanceNumber [Double] - Number of the instance. Use 1 to N to number instances. For the same driver instance numbers should be unique. The instance number makes possible to run use multiple processes of the driver, each one with a distinct configuration. Mandatory parameter.
  • protocolConnectionNumber [Double] - Number code for the protocol connection. This must be unique for all connections over all drivers on a system. This number is be used to define the connection that can update a tag. Mandatory parameter.
  • name [String] - Name for a connection. Will be used for logging. Mandatory parameter.
  • description [String] - Description for the purpose of a connection. Just documental. Optional parameter.
  • enabled [Boolean] - Controls the enabling of the connection. Use false here to disable the connection. Mandatory parameter.
  • commandsEnabled [Boolean] - Allows to disable commands (messages in control direction) for a connection. Use false here to disable commands. Mandatory parameter.
  • ipAddressLocalBind [String] - Not used for this driver. Optional parameter.
  • ipAddresses [Array of Strings] - Array of IP addresses and ports for IEC-104 servers to be scanned (only the first 2 servers are currently supported). When there are 2 servers configured, only one is connected and scanned at each time, servers are swapped when disconnected. Mandatory parameter.
  • localLinkAddress [Double] - Local link address for the connection (originator address). Mandatory parameter.
  • remoteLinkAddress [Double] - Remote link address of the server (originator address). Optional parameter.
  • giInterval [Double] - General station interrogation period in seconds. Optional parameter.
  • testCommandInterval [Double] - Interval to send test command messages in seconds. Use zero to disable test command messages. Optional parameter.
  • timeSyncInterval [Double] - Time interval in seconds to send time sync messages. Use zero to disable. Mandatory parameter.
  • sizeOfCOT [Double] - Size of Cause Of Transmission protocol field in bytes (1 or 2). Mandatory parameter.
  • sizeOfCA [Double] - Size of Command Address protocol field in bytes (1 or 2). Mandatory parameter.
  • sizeOfIOA [Double] - Size of Information Object Address protocol field in bytes (1, 2, or 3). Mandatory parameter.
  • k [Double] - Protocol k parameter. Mandatory parameter.
  • w [Double] - Protocol w parameter. Mandatory parameter.
  • t0 [Double] - Protocol t0 timeout in seconds. Mandatory parameter.
  • t1 [Double] - Protocol t1 timeout in seconds. Mandatory parameter.
  • t2 [Double] - Protocol t2 timeout in seconds. Mandatory parameter.
  • t3 [Double] - Protocol t3 timeout in seconds. Mandatory parameter.
  • stats [Object] - Protocol statistics updated by the driver. Mandatory parameter.

Parameters needed only for TLS encrypted connections (when there are redundant servers, the same set of certificates is applied to connections to both servers).

  • localCertFilePath [String] - Path to file that contains the local certificate (*.pfx) that will be presented to the remote side of the connection. Optional parameter.
  • passphrase [String] - Password to the local certificate file (*.pfx). Optional parameter.
  • peerCertFilePath [String] - Path to certificate file used to verify the peer (server) (*.cer). Optional parameter.
  • rootCertFilePath [String] - Path to CA certificate file to check the certificate provided by the server - not required when chainValidation=false. Optional parameter.
  • allowOnlySpecificCertificates [bool] - Indicates whether the driver allows only specific certificates. Default: false. Optional parameter.
  • chainValidation [bool] - Indicates whether the drivers performs a X509 chain validation against the registered CA certificates. Default: false. Optional parameter.

Usage of TLS on RHEL8 Linux

Errors on TLS connections may be encountered when using TLS on Linux.

To solve this problem on client side edit the following file.

/etc/pki/tls/openssl.cnf

Change the section below to

[ crypto_policy ]

.include /etc/crypto-policies/back-ends/opensslcnf.config
MinProtocol = TLSv1
CipherString = DEFAULT:@SECLEVEL=2

The file name and section can be different on other Linux distros.

Configure tags for update

Each tag to be update on a connection must have a protocol source set configured. Only one source connection can update a tag.

Select a tag for a update on a connection as below.

use json_scada_db_name
db.realtimeData.updateOne({"tag":"A_TAG_NAME"}, {
    $set: {
        protocolSourceConnectionNumber: 61,
        protocolSourceCommonAddress: 205,
        protocolSourceObjectAddress: 1000,
        protocolSourceASDU: 13,
        protocolSourceCommandDuration: 0,
        protocolSourceCommandUseSBO: false,
        kconv1: 1,
        kconv2: 0
        }
});
  • protocolConnectionNumber [Double] - Number code for the protocol connection. Only this protocol connection can update the tag. Mandatory parameter.
  • protocolSourceCommonAddress [Double] - Common Address of ASDU. There can be more than one common address in the same connection. Mandatory parameter.
  • protocolSourceObjectAddress [Double] - Object address. This address combined with protocolSourceCommonAddress must be unique for the connection. Mandatory parameter.
  • protocolSourceASDU [Double] - Source ASDU TI type. This is documental for supervised points, the protocol driver will update the tag using any supported ASDU type. This parameter is important for command points. Mandatory parameter.
  • protocolSourceCommandDuration [Double] - Command options, IEC-104 QU field: 0=Unspecified, 1=Short Pulse, 2=Long Pulse, 3=Persistent. Just meaningful for commands. Mandatory parameter.
  • protocolSourceCommandUseSBO [Boolean] - Use Select-Before-Operate control sequence. Just meaningful for commands. Mandatory parameter.
  • kconv1 [Double] - Analog conversion factor: multiplier. Use -1 to invert digital values. Mandatory parameter.
  • kconv2 [Double] - Analog conversion factor: adder. Mandatory parameter.

Command Line Arguments

This driver has the following command line arguments.

  • 1st arg. - Instance Number [Integer] - Instance number to be executed. Optional argument, default=1.
  • 2nd arg. - Log. Level [Integer] - Log level (0=minimum,1=basic,2=detailed,3=debug). Optional argument, default=1.
  • 3rd arg. - Config File Path/Name [String] - Complete path/name of the JSON-SCADA config file. Optional argument, default="../conf/json-scada.json".

Example of JSON-SCADA Protocol Driver Instances and Connections Numbering

Driver instances and connections