IEC 60870-5-101 devices#

Together with IEC101 specific events, generic enable and running events are also supported.

Supported data types (<data_type>):

  • ‘single’

  • ‘double’

  • ‘step_position’

  • ‘bitstring’

  • ‘normalized’

  • ‘scaled’

  • ‘floating’

  • ‘binary_counter’

  • ‘protection’

  • ‘protection_start’

  • ‘protection_command’

  • ‘status’

Supported command types (<command_type>):

  • ‘single’

  • ‘double’

  • ‘regulating’

  • ‘normalized’

  • ‘scaled’

  • ‘floating’

  • ‘bitstring’

Master device#

IEC101 master device configuration is specified by hat-gateway://iec101.yaml#/definitions/master.

According to gateway specification, all IEC101 master device event types have prefix:

'gateway', <gateway_name>, 'iec101_master', <device_name>, <source>, ...

Todo

  • create master loop (open serial endpoint) (serial port reconnect delay)

  • enable/disable remote device (query last state on enable device and listen for changes)

  • reconnect procedure when serial endpoint available and remote device is enabled (remote device reconnect delay)

  • iec101 messages are sent to device only as reaction to system events

  • only “automatic” driver action is reconnect loop

  • new gateway events are generated only as reaction to:
    • receiving iec101 messages

    • change of connection state

  • messages with test flag are ignored

  • time sync loop for each enabled remote device

Gateway events#

Events registered by gateway have event type starting with:

'gateway', <gateway_name>, 'iec101_master', <device_name>, 'gateway', ...

Available gateway events are:

  • …, ‘status’

    Represents change in serial endpoint status. Upon enabling device, new CONNECTING status should be registered, and CONNECTED once serial endpoint is opened. Once device is disabled, DISCONNECTED status should be assumed regardless of last registered status event (registration of DISCONNECTED status event during device disabling is mandatory but should not be relied upon).

    Source timestamp is None.

    Payload is specified by hat-gateway://iec101.yaml#/definitions/events/master/gateway/status.

  • …, ‘remote_device’, <device_address>, ‘status’

    Represents change in remote device connection status. Once serial endpoint is opened and remote device enabled, new CONNECTING status should be registered. Once device is disabled or remote device is disabled, DISCONNECTED status should be assumed regardless of last registered status event (registration of DISCONNECTED status event during device disabling or remote device disabling is mandatory but should not be relied upon).

    Source timestamp is None.

    Payload is specified by hat-gateway://iec101.yaml#/definitions/events/master/gateway/status.

  • …, ‘remote_device’, <device_address>, ‘data’, <data_type>, <asdu_address>, <io_address>

    Represents received IEC101 data message.

    Source timestamp is dependent on existence of IEC101 time. If IEC101 time is not available, source timestamp is None.

    Payload is specified by hat-gateway://iec101.yaml#/definitions/events/master/gateway/data.

  • …, ‘remote_device’, <device_address>, ‘command’, <command_type>, <asdu_address>, <io_address>

    Represents received IEC101 command message.

    Source timestamp is None.

    Payload is specified by hat-gateway://iec101.yaml#/definitions/events/master/gateway/command.

  • …, ‘remote_device’, <device_address>, ‘interrogation’, <asdu_address>

    Represents received IEC101 interrogation message.

    Source timestamp is None.

    Payload is specified by hat-gateway://iec101.yaml#/definitions/events/master/gateway/interrogation.

  • …, ‘remote_device’, <device_address>, ‘counter_interrogation’, <asdu_address>

    Represents received IEC101 counter interrogation message.

    Source timestamp is None.

    Payload is specified by hat-gateway://iec101.yaml#/definitions/events/master/gateway/counter_interrogation.

System events#

Events registered by other Hat components, which are consumed by gateway, have event type starting with:

'gateway', <gateway_name>, 'iec101_master', <device_name>, 'system', ...

Available system events are:

  • …, ‘remote_device’, <device_address>, ‘enable’

    Represents request for enable/disable remote device.

    Source timestamp is None.

    Payload is specified by hat-gateway://iec101.yaml#/definitions/events/master/system/enable.

  • …, ‘remote_device’, <device_address>, ‘command’, <command_type>, <asdu_address>, <io_address>

    Represents request for command execution.

    Source timestamp is None.

    Payload is specified by hat-gateway://iec101.yaml#/definitions/events/master/system/command.

  • …, ‘remote_device’, <device_address>, ‘interrogation’, <asdu_address>

    Represents request for interrogation (interrogation activation).

    Source timestamp is None.

    Payload is specified by hat-gateway://iec101.yaml#/definitions/events/master/system/interrogation.

  • …, ‘remote_device’, <device_address>, ‘counter_interrogation’, <asdu_address>

    Represents request for counter interrogation (interrogation activation).

    Source timestamp is None.

    Payload is specified by hat-gateway://iec101.yaml#/definitions/events/master/system/counter_interrogation.

Configurations and event payloads#

---
"$schema": "http://json-schema.org/schema#"
id: "hat-gateway://iec101.yaml#"
definitions:
    master:
        type: object
        required:
            - port
            - baudrate
            - bytesize
            - parity
            - stopbits
            - flow_control
            - silent_interval
            - device_address_size
            - cause_size
            - asdu_address_size
            - io_address_size
            - reconnect_delay
            - remote_devices
        properties:
            port:
                type: string
            baudrate:
                type: integer
            bytesize:
                enum:
                    - FIVEBITS
                    - SIXBITS
                    - SEVENBITS
                    - EIGHTBITS
            parity:
                enum:
                    - NONE
                    - EVEN
                    - ODD
                    - MARK
                    - SPACE
            stopbits:
                enum:
                    - ONE
                    - ONE_POINT_FIVE
                    - TWO
            flow_control:
                type: object
                required:
                    - xonxoff
                    - rtscts
                    - dsrdtr
                properties:
                    xonxoff:
                        type: boolean
                    rtscts:
                        type: boolean
                    dsrdtr:
                        type: boolean
            silent_interval:
                type: number
            device_address_size:
                enum:
                    - ONE
                    - TWO
            cause_size:
                enum:
                    - ONE
                    - TWO
            asdu_address_size:
                enum:
                    - ONE
                    - TWO
            io_address_size:
                enum:
                    - ONE
                    - TWO
                    - THREE
            reconnect_delay:
                type: number
            remote_devices:
                type: array
                items:
                    type: object
                    required:
                        - address
                        - response_timeout
                        - send_retry_count
                        - poll_class1_delay
                        - poll_class2_delay
                        - reconnect_delay
                        - time_sync_delay
                    properties:
                        address:
                            type: integer
                        response_timeout:
                            type: number
                        send_retry_count:
                            type: integer
                        poll_class1_delay:
                            type:
                                - "null"
                                - number
                        poll_class2_delay:
                            type:
                                - "null"
                                - number
                        reconnect_delay:
                            type: number
                        time_sync_delay:
                            type:
                                - "null"
                                - number
    events:
        master:
            gateway:
                status:
                    enum:
                        - CONNECTING
                        - CONNECTED
                        - DISCONNECTED
                data:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/messages/data/res"
                command:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/messages/command/res"
                interrogation:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/messages/interrogation/res"
                counter_interrogation:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/messages/counter_interrogation/res"
            system:
                enable:
                    type: boolean
                command:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/messages/command/req"
                interrogation:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/messages/interrogation/req"
                counter_interrogation:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/messages/counter_interrogation/req"
    messages:
        data:
            res:
                type: object
                required:
                    - cause
                    - test
                properties:
                    cause:
                        oneOf:
                          - enum:
                                - PERIODIC
                                - BACKGROUND_SCAN
                                - SPONTANEOUS
                                - REQUEST
                                - REMOTE_COMMAND
                                - LOCAL_COMMAND
                                - INTERROGATED
                          - type: integer
                            description: |
                                other cause in range [0, 63]
                    test:
                        type: boolean
                oneOf:
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/single"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/double"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/step_position"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/bitstring"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/normalized"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/scaled"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/floating"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/binary_counter"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/protection"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/protection_start"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/protection_command"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/data_types/status"
        command:
            req:
                type: object
                required:
                    - cause
                properties:
                    cause:
                        oneOf:
                          - enum:
                                - ACTIVATION
                                - DEACTIVATION
                          - type: integer
                            description: |
                                other cause in range [0, 63]
                oneOf:
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/single"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/double"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/regulating"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/normalized"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/scaled"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/floating"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/bitstring"
            res:
                type: object
                required:
                    - cause
                    - success
                properties:
                    cause:
                        oneOf:
                          - enum:
                                - ACTIVATION_CONFIRMATION
                                - DEACTIVATION_CONFIRMATION
                                - ACTIVATION_TERMINATION
                                - UNKNOWN_TYPE
                                - UNKNOWN_CAUSE
                                - UNKNOWN_ASDU_ADDRESS
                                - UNKNOWN_IO_ADDRESS
                          - type: integer
                            description: |
                                other cause in range [0, 63]
                    success:
                        type: boolean
                oneOf:
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/single"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/double"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/regulating"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/normalized"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/scaled"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/floating"
                    - "$ref": "hat-gateway://iec101.yaml#/definitions/command_types/bitstring"
        interrogation:
            req:
                type: object
                required:
                    - request
                properties:
                    request:
                        type: integer
                        description: |
                            request in range [0, 255]
            res:
                type: object
                required:
                    - status
                    - request
                properties:
                    status:
                        enum:
                            - START
                            - STOP
                            - ERROR
                    request:
                        type: integer
                        description: |
                            request in range [0, 255]
        counter_interrogation:
            req:
                type: object
                required:
                    - request
                    - freeze
                properties:
                    request:
                        type: integer
                        description: |
                            request in range [0, 255]
                    freeze:
                        enum:
                            - READ
                            - FREEZE
                            - FREEZE_AND_RESET
                            - RESET
            res:
                type: object
                required:
                    - status
                    - request
                    - freeze
                properties:
                    status:
                        enum:
                            - START
                            - STOP
                            - ERROR
                    request:
                        type: integer
                        description: |
                            request in range [0, 255]
                    freeze:
                        enum:
                            - READ
                            - FREEZE
                            - FREEZE_AND_RESET
                            - RESET
    data_types:
        single:
            type: object
            required:
                - value
                - quality
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/single"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/indication"
        double:
            type: object
            required:
                - value
                - quality
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/double"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/indication"
        step_position:
            type: object
            required:
                - value
                - quality
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/step_position"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/measurement"
        bitstring:
            type: object
            required:
                - value
                - quality
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/bitstring"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/measurement"
        normalized:
            type: object
            required:
                - value
                - quality
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/normalized"
                quality:
                    oneOf:
                      - type: "null"
                      - "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/measurement"
        scaled:
            type: object
            required:
                - value
                - quality
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/scaled"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/measurement"
        floating:
            type: object
            required:
                - value
                - quality
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/floating"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/measurement"
        binary_counter:
            type: object
            required:
                - value
                - quality
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/binary_counter"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/counter"
        protection:
            type: object
            required:
                - value
                - quality
                - elapsed_time
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/protection"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/protection"
                elapsed_time:
                    type: integer
                    description: |
                        elapsed_time in range [0, 65535]
        protection_start:
            type: object
            required:
                - value
                - quality
                - duration_time
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/protection_start"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/protection"
                duration_time:
                    type: integer
                    description: |
                        duration_time in range [0, 65535]
        protection_command:
            type: object
            required:
                - value
                - quality
                - operating_time
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/protection_command"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/protection"
                operating_time:
                    type: integer
                    description: |
                        operating_time in range [0, 65535]
        status:
            type: object
            required:
                - value
                - quality
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/status"
                quality:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/qualities/measurement"
    command_types:
        single:
            type: object
            required:
                - value
                - select
                - qualifier
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/single"
                select:
                    type: boolean
                qualifier:
                    type: integer
                    description: |
                        qualifier in range [0, 31]
        double:
            type: object
            required:
                - value
                - select
                - qualifier
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/double"
                select:
                    type: boolean
                qualifier:
                    type: integer
                    description: |
                        qualifier in range [0, 31]
        regulating:
            type: object
            required:
                - value
                - select
                - qualifier
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/regulating"
                select:
                    type: boolean
                qualifier:
                    type: integer
                    description: |
                        qualifier in range [0, 31]
        normalized:
            type: object
            required:
                - value
                - select
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/normalized"
                select:
                    type: boolean
        scaled:
            type: object
            required:
                - value
                - select
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/scaled"
                select:
                    type: boolean
        floating:
            type: object
            required:
                - value
                - select
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/floating"
                select:
                    type: boolean
        bitstring:
            type: object
            required:
                - value
            properties:
                value:
                    "$ref": "hat-gateway://iec101.yaml#/definitions/values/bitstring"
    values:
        single:
            enum:
                - "OFF"
                - "ON"
        double:
            enum:
                - "INTERMEDIATE"
                - "OFF"
                - "ON"
                - "FAULT"
        regulating:
            enum:
                - LOWER
                - HIGHER
        step_position:
            type: object
            required:
                - value
                - transient
            properties:
                value:
                    type: integer
                    description: |
                        value in range [-64, 63]
                transient:
                    type: boolean
        bitstring:
            type: array
            description: |
                bitstring encoded as 4 bytes
            items:
                type: integer
        normalized:
            type: number
            description: |
                value in range [-1.0, 1.0)
        scaled:
            type: integer
            description: |
                value in range [-2^15, 2^15-1]
        floating:
            type: number
        binary_counter:
            type: integer
            description: |
                value in range [-2^31, 2^31-1]
        protection:
            enum:
                - "OFF"
                - "ON"
        protection_start:
            type: object
            required:
                - general
                - l1
                - l2
                - l3
                - ie
                - reverse
            properties:
                general:
                    type: boolean
                l1:
                    type: boolean
                l2:
                    type: boolean
                l3:
                    type: boolean
                ie:
                    type: boolean
                reverse:
                    type: boolean
        protection_command:
            type: object
            required:
                - general
                - l1
                - l2
                - l3
            properties:
                general:
                    type: boolean
                l1:
                    type: boolean
                l2:
                    type: boolean
                l3:
                    type: boolean
        status:
            type: object
            required:
                - value
                - change
            properties:
                value:
                    type: array
                    description: |
                        value length is 16
                    items:
                        type: boolean
                change:
                    type: array
                    description: |
                        change length is 16
                    items:
                        type: boolean
    qualities:
        indication:
            type: object
            required:
                - invalid
                - not_topical
                - substituted
                - blocked
            properties:
                invalid:
                    type: boolean
                not_topical:
                    type: boolean
                substituted:
                    type: boolean
                blocked:
                    type: boolean
        measurement:
            type: object
            required:
                - invalid
                - not_topical
                - substituted
                - blocked
                - overflow
            properties:
                invalid:
                    type: boolean
                not_topical:
                    type: boolean
                substituted:
                    type: boolean
                blocked:
                    type: boolean
                overflow:
                    type: boolean
        counter:
            type: object
            required:
                - invalid
                - adjusted
                - overflow
                - sequence
            properties:
                invalid:
                    type: boolean
                adjusted:
                    type: boolean
                overflow:
                    type: boolean
                sequence:
                    type: boolean
        protection:
            type: object
            required:
                - invalid
                - not_topical
                - substituted
                - blocked
                - time_invalid
            properties:
                invalid:
                    type: boolean
                not_topical:
                    type: boolean
                substituted:
                    type: boolean
                blocked:
                    type: boolean
                time_invalid:
                    type: boolean
...