IEC 60870-5-101/104 Master Driver

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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    qualitynumberValue of the quality descriptor field as an unsigned integer.Yes
    changednumberValue of the changed field encoded as an unsigned integer.Yes

Example

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

  • C_SC_NA_1

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    qualifiernumberValue of the qualifier field encoded as an unsigned integer.Yes

Example

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

  • M_SP_TB_1

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampstringTimestamp encoded as an ISO 8601 date time.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    timestampSummerTimebooleanValue of the summer time flag of the timestamp. It will be present only if the bit is set.No
    qualitynumberValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    qualitynumberValue of the quality descriptor field as an unsigned integer.Yes

Example

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

  • M_SP_NA_1

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    qualitynumberValue of the quality descriptor field as an unsigned integer.Yes

Example

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

  • M_ST_TA_1

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampnumberTimestamp encoded as a millisecond value.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    qualitynumberValue of the quality descriptor field as an unsigned integer.Yes
    isTransientbooleanValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampstringTimestamp encoded as an ISO 8601 date time.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    timestampSummerTimebooleanValue of the summer time flag of the timestamp. It will be present only if the bit is set.No
    qualitynumberValue of the quality descriptor field as an unsigned integer.Yes
    elapsedTimenumberValue 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

    NameTypeDescriptionMandatory
    qualitynumberValue of the quality descriptor field as an unsigned integer.Yes

Example

{
  "quality": 0,
}

  • C_TS_NA_1

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes

Example

{
  "value": true,
}

  • C_CS_NA_1

    NameTypeDescriptionMandatory
    timestampstringTimestamp encoded as an ISO 8601 date time.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    timestampSummerTimebooleanValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampnumberTimestamp encoded as a millisecond value.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    qualitynumberValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    qualifiernumberValue 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

    NameTypeDescriptionMandatory
    valuenumberThe 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampstringTimestamp encoded as an ISO 8601 date time.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    timestampSummerTimebooleanValue of the summer time flag of the timestamp. It will be present only if the bit is set.No
    qualifiernumberValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampnumberTimestamp encoded as a millisecond value.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    qualitynumberValue of the quality descriptor field as an unsigned integer.Yes
    elapsedTimenumberValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    sequenceNumbernumberValue of the sequence number field.Yes
    isAdjustedbooleanValue of the is adjusted flag of the BCR field. It will be present only if the bit is set.No
    isInvalidbooleanValue of the is invalid flag of the BCR field. It will be present only if the bit is set.No
    hasCarrybooleanValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampnumberTimestamp encoded as a millisecond value.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    sequenceNumbernumberValue of the sequence number field.Yes
    isAdjustedbooleanValue of the is adjusted flag of the BCR field. It will be present only if the bit is set.No
    isInvalidbooleanValue of the is invalid flag of the BCR field. It will be present only if the bit is set.No
    hasCarrybooleanValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampstringTimestamp encoded as an ISO 8601 date time.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    timestampSummerTimebooleanValue of the summer time flag of the timestamp. It will be present only if the bit is set.No
    sequenceNumbernumberValue of the sequence number field.Yes
    isAdjustedbooleanValue of the is adjusted flag of the BCR field. It will be present only if the bit is set.No
    isInvalidbooleanValue of the is invalid flag of the BCR field. It will be present only if the bit is set.No
    hasCarrybooleanValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampnumberTimestamp encoded as a millisecond value.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    qualitynumberValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampstringTimestamp encoded as an ISO 8601 date time.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    timestampSummerTimebooleanValue of the summer time flag of the timestamp. It will be present only if the bit is set.No
    qualitynumberValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampstringTimestamp encoded as an ISO 8601 date time.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    timestampSummerTimebooleanValue of the summer time flag of the timestamp. It will be present only if the bit is set.No
    qualitynumberValue of the quality descriptor field as an unsigned integer.Yes
    isTransientbooleanValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    qualitynumberValue of the quality descriptor field as an unsigned integer.Yes
    isTransientbooleanValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampstringTimestamp encoded as an ISO 8601 date time.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    timestampSummerTimebooleanValue 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

    NameTypeDescriptionMandatory
    valuenumberThe information object main value.Yes
    timestampstringTimestamp encoded as an ISO 8601 date time.Yes
    timestampInvalidbooleanValue of the invalid flag of the timestamp. It will be present only if the bit is set.No
    timestampSubstitutedbooleanValue of the substituted flag of the timestamp. It will be present only if the bit is set.No
    timestampSummerTimebooleanValue of the summer time flag of the timestamp. It will be present only if the bit is set.No
    qualifiernumberValue 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

    NameTypeDescriptionMandatory
    qualifiernumberValue 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:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode
  • Object Address
  • Qualifier
  • Select

Write input format:

  • Preferred value type: FLOAT
  • Needs timestamp: Yes

  • C_DC_TA_1:
  • C_RC_TA_1:
  • C_SE_TB_1:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode
  • Object Address
  • Qualifier
  • Select

Write input format:

  • Preferred value type: INTEGER
  • Needs timestamp: Yes

  • C_SC_NA_1:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode
  • Object Address
  • Qualifier
  • Select

Write input format:

  • Preferred value type: BOOLEAN
  • Needs timestamp: No

  • C_CS_NA_1:

Timestamp can be provided either using a numeric value.type reporting the milliseconds since EPOCH or using the JSON representation and setting the timestamp field and flags.

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode

Write input format:

  • Preferred value type: LONG
  • Needs timestamp: Yes

  • C_BO_TA_1:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode
  • Object Address

Write input format:

  • Preferred value type: LONG
  • Needs timestamp: Yes

  • C_CD_NA_1:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode

Write input format:

  • Preferred value type: INTEGER
  • Needs timestamp: No

  • C_SC_TA_1:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode
  • Object Address
  • Qualifier
  • Select

Write input format:

  • Preferred value type: BOOLEAN
  • Needs timestamp: Yes

  • C_DC_NA_1:
  • C_RC_NA_1:
  • C_SE_NB_1:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode
  • Object Address
  • Qualifier
  • Select

Write input format:

  • Preferred value type: INTEGER
  • Needs timestamp: No

  • C_SE_NA_1:
  • C_SE_NC_1:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode
  • Object Address
  • Qualifier
  • Select

Write input format:

  • Preferred value type: FLOAT
  • Needs timestamp: No

  • C_BO_NA_1:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode
  • Object Address

Write input format:

  • Preferred value type: LONG
  • Needs timestamp: No

  • C_TS_NA_1:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode

Write input format:

  • Preferred value type: BOOLEAN
  • Needs timestamp: No

  • C_RP_NA_1:

Mandatory configuration parameters:

  • Common Address
  • Link Layer Adddress mandatory only in 101 unbalanced mode
  • Qualifier

Write input format:

  • Preferred value type: any
  • Needs timestamp: No

Listen channels

Channels in listen mode can be used to receive unsolicited messages. Listen channels produce the same output as channels in READ mode, in this case the channel configuration parameters allow to filter spontaneous message data points.