IEC 60870-5 Master Driver

This driver add support for IEC60870-5 protocol in both CS101 (serial master) and CS104 (TCP-IP client) for ESF.
Features:

Support for commands, interrogations, spontaneous/periodic ASDUs
Support for JSON encoding of Information Objects.
Support for both balanced and unbalanced CS101 mode.
Support for TLS encryption for CS104 mode.

Global driver configuration

The driver global configuration contains parameters related to the connection. The relevant parameters depend on the mode.

104 mode

For establishing a TCP connection, the transport.type global parameter must be set to IP.

The following parameters are mandatory for TCP mode:

ip.address: The IP address of remote IEC 104 server.
ip.port: The TCP port to be used.

In order to enable TLS encryption, the tls.enabled flag should be set to true.

In this case the other TLS related parameters must be provided as well.

Certificates and private keys must be provided in PEM format. If the private key is encrypted, the password can be specified using the tls.own.key.password field.

The app.cotsize, app.casize, app.ioasize parameters must be set to the appropriate values depending on server configuration.

101 mode

For establishing a serial connection, the transport.type global parameter must be set to Serial.

In this case the serial.* parameters must be configured to match network configuration.

In serial mode the serial.polladdresses and app.origaddr should be set properly.

For balanced mode, serial.polladdresses must contain the link layer address of the outstation.

For unbalanced mode, serial.polladdresses must be set to a comma separated list of the link layer addresses of the outstations to be polled.

In unbalanced mode, the Link Layer Address parameter in channel configuration is mandatory (see below).

Channel configuration

The driver allows to use READ to perform interrogations, counter interrogations and read requests; WRITE channels to send other commands and listen mode channels for receiving unsolicited messages.

In case of interrogations and commands, the channel configuration parameters allow to provide the parameters required for the request. For listen channels, channel parameters can be used to filter incoming data.

The available configuration parameters are the following:

ASDU Type: The information object type of the channel. It defines the request type for interrogations and commands and allows to filter on information object type for listen channels. The ANY value is only supported for listening channels, it disables filtering based on ASDU type.
Common Address: The common address to be used for requests and commands. If provided for a listening channel, this enables filtering basing on common address.
Object Address: The object address for commands and read requests. If provided for a listening channel, this enables filtering basing on object address.
Link Layer Address: The link layer address to be used for interrogations, read requests and commands, this parameter is mandatory only for 101 unbalanced mode. If provided for a listening channel, this enables filtering basing on link layer address.
Qualifier: The qualifier to be used for commands or interrogations. This parameter is ignored for listening channels.
Select: Defines whether the command is sent in operate (false) or select (true) mode. This parameter is ignored for interrogations, reads or listening channels.

Read channels

The following ASDU Type values can be used for read channels:

C_IC_NA_1:

Mandatory configuration parameters:
- Link Layer Address (mandatory only in 101 unbalanced mode)
- Common Address
- Qualifier

C_CI_NA_1:

Mandatory configuration parameters:
- Link Layer Address (mandatory only in 101 unbalanced mode)
- Common Address
- Qualifier

C_RD_NA_1:

Mandatory configuration parameters:
- Link Layer Address (mandatory only in 101 unbalanced mode)
- Common Address
- Object Address
- Qualifier

#### Response representation

Read channels should use STRING as value.type, in this case the driver will collect and return in JSON format all of the data points sent by the server in response ASDUs.

The response is a JSON object whose properties keys are the information object address of the data point, the value of each property is a JSON object describing the data point. The format of the value objects depends on the information object type. See the dedicated section below for more details.

The example below shows a possible interrogation response.

	{
	  "100": {
	    "value": true,
	    "quality": 0,
	    "objectType": "M_SP_NA_1"
	  },
	  "200": {
	    "value": 1,
	    "quality": 0,
	    "objectType": "M_DP_NA_1"
	  },
	  "300": {
	    "value": 63,
	    "quality": 0,
	    "isTransient": false,
	    "objectType": "M_ST_NA_1"
	  },
	  "400": {
	    "value": 0.5999939,
	    "quality": 0,
	    "objectType": "M_ME_NA_1"
	  },
	  "500": {
	    "value": 2,
	    "quality": 0,
	    "objectType": "M_ME_NB_1"
	  },
	  "600": {
	    "value": 2,
	    "quality": 0,
	    "objectType": "M_ME_NC_1"
	  },
	  "800": {
	    "value": 123,
	    "quality": 0,
	    "objectType": "M_BO_NA_1"
	  },
	  "44": {
	    "value": 0,
	    "quality": 1,
	    "objectType": "P_ME_NA_1"
	  },
	  "55": {
	    "value": 0,
	    "quality": 1,
	    "objectType": "P_ME_NB_1"
	  },
	  "66": {
	    "value": 0,
	    "quality": 1,
	    "objectType": "P_ME_NC_1"
	  }
	}

The driver also support using other data types like booleans and numeric types for reads. In this case the request will succeed only if the response contains a single data point. The driver will try to convert the main value of the data point to the requested type, discarding all other fields.

The format of the JSON objects describing the data points is reported below:

M_PS_NA_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes
changed	`number`	Value of the changed field encoded as an unsigned integer.	Yes

Example

{
  "value": 1,
  "quality": 0,
  "changed": 0,
}

C_SC_NA_1

Name Type Description Mandatory
value number The information object main value. Yes
qualifier number Value of the qualifier field encoded as an unsigned integer. Yes

Example

{
  "value": true,
  "qualifier": 0,
}

M_SP_TB_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`string`	Timestamp encoded as an ISO 8601 date time.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
timestampSummerTime	`boolean`	Value of the summer time flag of the timestamp. It will be present only if the bit is set.	No
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes

Example

{
  "value": true,
  "timestamp": "2020-01-31T13:03:49.678",
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "timestampSummerTime": true,
  "quality": 0,
}

M_BO_NA_1
M_DP_NA_1
M_ME_NA_1
M_ME_NB_1
M_ME_NC_1
P_ME_NA_1
P_ME_NB_1
P_ME_NC_1

Name Type Description Mandatory
value number The information object main value. Yes
quality number Value of the quality descriptor field as an unsigned integer. Yes

Example

{
  "value": 1,
  "quality": 0,
}

M_SP_NA_1

Name Type Description Mandatory
value number The information object main value. Yes
quality number Value of the quality descriptor field as an unsigned integer. Yes

Example

{
  "value": true,
  "quality": 0,
}

M_ST_TA_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`number`	Timestamp encoded as a millisecond value.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes
isTransient	`boolean`	Value of the is transient flag. It will be present only if the bit is set.	No

Example

{
  "value": 1,
  "timestamp": 10000,
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "quality": 0,
  "isTransient": true,
}

C_RD_NA_1

No JSON fields

M_EP_TD_1
M_EP_TE_1

M_EP_TF_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`string`	Timestamp encoded as an ISO 8601 date time.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
timestampSummerTime	`boolean`	Value of the summer time flag of the timestamp. It will be present only if the bit is set.	No
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes
elapsedTime	`number`	Value of the elapsed time field in milliseconds.	Yes

Example

{
  "value": 1,
  "timestamp": "2020-01-31T13:03:49.678",
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "timestampSummerTime": true,
  "quality": 0,
  "elapsedTime": 10000,
}

P_AC_NA_1

Name Type Description Mandatory
quality number Value of the quality descriptor field as an unsigned integer. Yes

Name	Type	Description	Mandatory
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes

Example

{
  "quality": 0,
}

C_TS_NA_1

Name Type Description Mandatory
value number The information object main value. Yes

Example

{
  "value": true,
}

C_CS_NA_1

Name	Type	Description	Mandatory
timestamp	`string`	Timestamp encoded as an ISO 8601 date time.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
timestampSummerTime	`boolean`	Value of the summer time flag of the timestamp. It will be present only if the bit is set.	No

Example

{
  "timestamp": "2020-01-31T13:03:49.678",
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "timestampSummerTime": true,
}

M_BO_TA_1
M_DP_TA_1
M_ME_TA_1
M_ME_TB_1

M_ME_TC_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`number`	Timestamp encoded as a millisecond value.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes

Example

{
  "value": 1,
  "timestamp": 10000,
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "quality": 0,
}

C_DC_NA_1
C_RC_NA_1
C_SE_NA_1
C_SE_NB_1
C_SE_NC_1

Name Type Description Mandatory
value number The information object main value. Yes
qualifier number Value of the qualifier field encoded as an unsigned integer. Yes

Example

{
  "value": 1,
  "qualifier": 0,
}

C_BO_NA_1
C_CD_NA_1
M_EI_NA_1
M_ME_ND_1

Name Type Description Mandatory
value number The information object main value. Yes

Example

{
  "value": 1,
}

C_DC_TA_1
C_RC_TA_1
C_SE_TA_1
C_SE_TB_1

C_SE_TC_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`string`	Timestamp encoded as an ISO 8601 date time.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
timestampSummerTime	`boolean`	Value of the summer time flag of the timestamp. It will be present only if the bit is set.	No
qualifier	`number`	Value of the qualifier field encoded as an unsigned integer.	Yes

Example

{
  "value": 1,
  "timestamp": "2020-01-31T13:03:49.678",
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "timestampSummerTime": true,
  "qualifier": 0,
}

M_EP_TA_1
M_EP_TB_1

M_EP_TC_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`number`	Timestamp encoded as a millisecond value.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes
elapsedTime	`number`	Value of the elapsed time field in milliseconds.	Yes

Example

{
  "value": 1,
  "timestamp": 10000,
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "quality": 0,
  "elapsedTime": 10000,
}

M_IT_NA_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
sequenceNumber	`number`	Value of the sequence number field.	Yes
isAdjusted	`boolean`	Value of the is adjusted flag of the BCR field. It will be present only if the bit is set.	No
isInvalid	`boolean`	Value of the is invalid flag of the BCR field. It will be present only if the bit is set.	No
hasCarry	`boolean`	Value of the has carry flag of the BCR field. It will be present only if the bit is set.	No

Example

{
  "value": 1,
  "sequenceNumber": 1234,
  "isAdjusted": true,
  "isInvalid": true,
  "hasCarry": true,
}

M_IT_TA_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`number`	Timestamp encoded as a millisecond value.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
sequenceNumber	`number`	Value of the sequence number field.	Yes
isAdjusted	`boolean`	Value of the is adjusted flag of the BCR field. It will be present only if the bit is set.	No
isInvalid	`boolean`	Value of the is invalid flag of the BCR field. It will be present only if the bit is set.	No
hasCarry	`boolean`	Value of the has carry flag of the BCR field. It will be present only if the bit is set.	No

Example

{
  "value": 1,
  "timestamp": 10000,
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "sequenceNumber": 1234,
  "isAdjusted": true,
  "isInvalid": true,
  "hasCarry": true,
}

M_IT_TB_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`string`	Timestamp encoded as an ISO 8601 date time.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
timestampSummerTime	`boolean`	Value of the summer time flag of the timestamp. It will be present only if the bit is set.	No
sequenceNumber	`number`	Value of the sequence number field.	Yes
isAdjusted	`boolean`	Value of the is adjusted flag of the BCR field. It will be present only if the bit is set.	No
isInvalid	`boolean`	Value of the is invalid flag of the BCR field. It will be present only if the bit is set.	No
hasCarry	`boolean`	Value of the has carry flag of the BCR field. It will be present only if the bit is set.	No

Example

{
  "value": 1,
  "timestamp": "2020-01-31T13:03:49.678",
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "timestampSummerTime": true,
  "sequenceNumber": 1234,
  "isAdjusted": true,
  "isInvalid": true,
  "hasCarry": true,
}

M_SP_TA_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`number`	Timestamp encoded as a millisecond value.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes

Example

{
  "value": true,
  "timestamp": 10000,
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "quality": 0,
}

M_BO_TB_1
M_DP_TB_1
M_ME_TD_1
M_ME_TE_1

M_ME_TF_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`string`	Timestamp encoded as an ISO 8601 date time.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
timestampSummerTime	`boolean`	Value of the summer time flag of the timestamp. It will be present only if the bit is set.	No
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes

Example

{
  "value": 1,
  "timestamp": "2020-01-31T13:03:49.678",
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "timestampSummerTime": true,
  "quality": 0,
}

M_ST_TB_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`string`	Timestamp encoded as an ISO 8601 date time.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
timestampSummerTime	`boolean`	Value of the summer time flag of the timestamp. It will be present only if the bit is set.	No
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes
isTransient	`boolean`	Value of the is transient flag. It will be present only if the bit is set.	No

Example

{
  "value": 1,
  "timestamp": "2020-01-31T13:03:49.678",
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "timestampSummerTime": true,
  "quality": 0,
  "isTransient": true,
}

M_ST_NA_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
quality	`number`	Value of the quality descriptor field as an unsigned integer.	Yes
isTransient	`boolean`	Value of the is transient flag. It will be present only if the bit is set.	No

Example

{
  "value": 1,
  "quality": 0,
  "isTransient": true,
}

C_BO_TA_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`string`	Timestamp encoded as an ISO 8601 date time.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
timestampSummerTime	`boolean`	Value of the summer time flag of the timestamp. It will be present only if the bit is set.	No

Example

{
  "value": 1,
  "timestamp": "2020-01-31T13:03:49.678",
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "timestampSummerTime": true,
}

C_SC_TA_1

Name	Type	Description	Mandatory
value	`number`	The information object main value.	Yes
timestamp	`string`	Timestamp encoded as an ISO 8601 date time.	Yes
timestampInvalid	`boolean`	Value of the invalid flag of the timestamp. It will be present only if the bit is set.	No
timestampSubstituted	`boolean`	Value of the substituted flag of the timestamp. It will be present only if the bit is set.	No
timestampSummerTime	`boolean`	Value of the summer time flag of the timestamp. It will be present only if the bit is set.	No
qualifier	`number`	Value of the qualifier field encoded as an unsigned integer.	Yes

Example

{
  "value": true,
  "timestamp": "2020-01-31T13:03:49.678",
  "timestampInvalid": true,
  "timestampSubstituted": true,
  "timestampSummerTime": true,
  "qualifier": 0,
}

C_CI_NA_1
C_IC_NA_1
C_RP_NA_1

Name Type Description Mandatory
qualifier number Value of the qualifier field encoded as an unsigned integer. Yes

Name	Type	Description	Mandatory
qualifier	`number`	Value of the qualifier field encoded as an unsigned integer.	Yes

Example

{
  "qualifier": 0,
}

Write channels

The driver supports two input formats for write commands, that can be selected using the value.type channel configuration parameter:

STRING:

The driver expects a string containing a JSON object that can be used to encode the main value and a CP56Time2a timestamp, for the ASDU types that require it. The JSON object is composed by the following fields:
- value: The main information object value, can be a boolean or a number, depending on ASDU Type.
- timestamp: Timestamp encoded as an ISO 8601 date time. The current date time will be used if not provided.
- timestampInvalid: The value of the is invalid timestamp flag. Defaults to false if not provided.
- timestampSubstituted: The value of the is substituted timestamp flag. Defaults to false if not provided.
- timestampSummerTime: The value of the summer time timestamp flag. Defaults to false if not provided.
BOOLEAN, INTEGER, LONG, FLOAT, DOUBLE:

The provided value will be used as the command main value. If the command requires a CP56Time2a timestamp, the current date time will be used with no flags set.

The ASDU Type configuration parameter values supported for write commands are reported below:

C_SE_TA_1:
C_SE_TC_1: