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#/$defs/master.
According to gateway specification, all IEC101 master device event types have prefix:
gateway/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/iec101_master/<device_name>/gateway/...
Available gateway events are:
…/status
Represents change in serial endpoint status. Upon enabling device, new
CONNECTINGstatus should be registered, andCONNECTEDonce serial endpoint is opened. Once device is disabled,DISCONNECTEDstatus should be assumed regardless of last registered status event (registration ofDISCONNECTEDstatus event during device disabling is mandatory but should not be relied upon).Source timestamp is
None.Payload is specified by
hat-gateway://iec101.yaml#/$defs/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
CONNECTINGstatus should be registered. Once device is disabled or remote device is disabled,DISCONNECTEDstatus should be assumed regardless of last registered status event (registration ofDISCONNECTEDstatus 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#/$defs/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#/$defs/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#/$defs/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#/$defs/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#/$defs/events/master/gateway/counter_interrogation.
System events¶
Events registered by other Hat components, which are consumed by gateway, have event type starting with:
gateway/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#/$defs/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#/$defs/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#/$defs/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#/$defs/events/master/system/counter_interrogation.
Slave device¶
IEC101 slave device configuration is specified by
hat-gateway://iec101.yaml#/$defs/slave.
According to gateway specification, all IEC101 slave device event types have prefix:
gateway/iec101_slave/<device_name>/<source>/...
IEC101 slave device provides implementation of IEC101 slave which accepts multiple parallel remote master connections, one for each configured device address. Change of active master connections list is trigger for registration of new gateway ‘connection’ event containing current list’s state.
IEC101 slave device is configured with list of available data. Once device is enabled, device will query last system ‘data’ events corresponding to configured data. This local cache is continuously updated with latest data states based on received system ‘data’ events. All remote masters are notified with IEC101 data messages each time locally cached data state is changed. When slave receives IEC101 interrogation or counter interrogation message, it will immediately respond with IEC101 interrogation/data messages based on current state of local data cache. Interrogation deactivation is not supported (slave responds with negative confirmation).
In addition to local cache of last data states, IEC101 slave device can be configured with arbitrary number of circular data buffers, each configured with limited size. Each data can be associated with single buffer. When system ‘data’ event, associated with configured data, is received, together with local cache update, data change is appended to the end of configured data buffer. Once buffer is full, new changes will overwrite oldest changes. Data change is removed from buffer when at least one remote master is notified with data change (slave sends data poll response with data change). When remote master connect to slave and new connection is established, slave will immediately schedule sending of IEC101 data messages for each buffered data change. Slave’s initial query of system ‘data’ events is not buffered.
In addition to sending IEC101 data messages and processing IEC101 interrogation and counter interrogation requests, slave supports IEC101 command messages. Command messages are transparently bidirectionally mapped to ‘command’ events. Each time slave receives IEC101 command request, it will register new gateway ‘command’ event which contains unique identification of master connection which sent command request. When new system ‘command’ event is received, it must contain identification of master connection which will be used for sending associated IEC101 command response.
Gateway events¶
Events registered by gateway have event type starting with:
gateway/iec101_slave/<device_name>/gateway/...
Available gateway events are:
…/connections
Represents change in list of all active connections. When device is disabled, empty list of connections is assumed (when device is disabled, new connections event should be registered but user should not depend on this behaviour).
Source timestamp is
None.Payload is specified by
hat-gateway://iec101.yaml#/$defs/events/slave/gateway/connections.…/command/<command_type>/<asdu_address>/<io_address>
Represents received IEC101 command 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#/$defs/events/slave/gateway/command.
System events¶
Events registered by other Hat components, which are consumed by gateway, have event type starting with:
gateway/iec101_slave/<device_name>/system/...
Available system events are:
…/data/<data_type>/<asdu_address>/<io_address>
Represents data change.
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#/$defs/events/slave/system/data.…/command/<command_type>/<asdu_address>/<io_address>
Represents command response.
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#/$defs/events/slave/system/command.
Configurations and event payloads¶
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "hat-gateway://iec101.yaml"
$defs:
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
slave:
type: object
required:
- port
- addresses
- baudrate
- bytesize
- parity
- stopbits
- flow_control
- silent_interval
- device_address_size
- keep_alive_timeout
- cause_size
- asdu_address_size
- io_address_size
- buffers
- data
properties:
port:
type: string
addresses:
type: array
items:
type: integer
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
keep_alive_timeout:
type: number
cause_size:
enum:
- ONE
- TWO
asdu_address_size:
enum:
- ONE
- TWO
io_address_size:
enum:
- ONE
- TWO
- THREE
buffers:
type: array
items:
type: object
required:
- name
- size
properties:
name:
type: string
size:
type: integer
data:
type: array
items:
type: object
required:
- data_type
- asdu_address
- io_address
- buffer
properties:
data_type:
enum:
- SINGLE
- DOUBLE
- STEP_POSITION
- BITSTRING
- NORMALIZED
- SCALED
- FLOATING
- BINARY_COUNTER
- PROTECTION
- PROTECTION_START
- PROTECTION_COMMAND
- STATUS
asdu_address:
type: integer
io_address:
type: integer
buffer:
type:
- "null"
- string
events:
master:
gateway:
status:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/status"
data:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/data/res"
command:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/command/res"
interrogation:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/interrogation/res"
counter_interrogation:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/counter_interrogation/res"
system:
enable:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/enable"
command:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/command/req"
interrogation:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/interrogation/req"
counter_interrogation:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/counter_interrogation/req"
slave:
gateway:
connections:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/connections"
command:
allOf:
- type: object
required:
- connection_id
properties:
connection_id:
type: integer
- $ref: "hat-gateway://iec101.yaml#/$defs/messages/command/req"
system:
data:
$ref: "hat-gateway://iec101.yaml#/$defs/messages/data/res"
command:
allOf:
- type: object
required:
- connection_id
properties:
connection_id:
type: integer
- $ref: "hat-gateway://iec101.yaml#/$defs/messages/command/res"
messages:
enable:
type: boolean
status:
enum:
- CONNECTING
- CONNECTED
- DISCONNECTED
connections:
type: array
items:
type: object
required:
- connection_id
- address
properties:
connection_id:
type: integer
address:
type: integer
data:
res:
type: object
required:
- is_test
- cause
- data
properties:
is_test:
type: boolean
cause:
$ref: "hat-gateway://iec101.yaml#/$defs/causes/data/res"
data:
oneOf:
- $ref: "hat-gateway://iec101.yaml#/$defs/data/single"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/double"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/step_position"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/bitstring"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/normalized"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/scaled"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/floating"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/binary_counter"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/protection"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/protection_start"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/protection_command"
- $ref: "hat-gateway://iec101.yaml#/$defs/data/status"
command:
req:
type: object
required:
- is_test
- cause
- command
properties:
is_test:
type: boolean
cause:
$ref: "hat-gateway://iec101.yaml#/$defs/causes/command/req"
command:
oneOf:
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/single"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/double"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/regulating"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/normalized"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/scaled"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/floating"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/bitstring"
res:
type: object
required:
- is_test
- is_negative_confirm
- cause
- command
properties:
is_test:
type: boolean
is_negative_confirm:
type: boolean
cause:
$ref: "hat-gateway://iec101.yaml#/$defs/causes/command/res"
command:
oneOf:
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/single"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/double"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/regulating"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/normalized"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/scaled"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/floating"
- $ref: "hat-gateway://iec101.yaml#/$defs/commands/bitstring"
interrogation:
req:
type: object
required:
- is_test
- request
- cause
properties:
is_test:
type: boolean
request:
type: integer
description: |
request in range [0, 255]
cause:
$ref: "hat-gateway://iec101.yaml#/$defs/causes/command/req"
res:
type: object
required:
- is_test
- is_negative_confirm
- request
- cause
properties:
is_test:
type: boolean
is_negative_confirm:
type: boolean
request:
type: integer
description: |
request in range [0, 255]
cause:
$ref: "hat-gateway://iec101.yaml#/$defs/causes/command/res"
counter_interrogation:
req:
allOf:
- type: object
required:
- freeze
properties:
freeze:
enum:
- READ
- FREEZE
- FREEZE_AND_RESET
- RESET
- $ref: "hat-gateway://iec101.yaml#/$defs/messages/interrogation/req"
res:
allOf:
- type: object
required:
- freeze
properties:
freeze:
enum:
- READ
- FREEZE
- FREEZE_AND_RESET
- RESET
- $ref: "hat-gateway://iec101.yaml#/$defs/messages/interrogation/res"
data:
single:
type: object
required:
- value
- quality
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/single"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/qualities/indication"
double:
type: object
required:
- value
- quality
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/double"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/qualities/indication"
step_position:
type: object
required:
- value
- quality
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/step_position"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/qualities/measurement"
bitstring:
type: object
required:
- value
- quality
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/bitstring"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/qualities/measurement"
normalized:
type: object
required:
- value
- quality
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/normalized"
quality:
oneOf:
- type: "null"
- $ref: "hat-gateway://iec101.yaml#/$defs/qualities/measurement"
scaled:
type: object
required:
- value
- quality
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/scaled"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/qualities/measurement"
floating:
type: object
required:
- value
- quality
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/floating"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/qualities/measurement"
binary_counter:
type: object
required:
- value
- quality
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/binary_counter"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/qualities/counter"
protection:
type: object
required:
- value
- quality
- elapsed_time
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/protection"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/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#/$defs/values/protection_start"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/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#/$defs/values/protection_command"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/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#/$defs/values/status"
quality:
$ref: "hat-gateway://iec101.yaml#/$defs/qualities/measurement"
commands:
single:
type: object
required:
- value
- select
- qualifier
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/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#/$defs/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#/$defs/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#/$defs/values/normalized"
select:
type: boolean
scaled:
type: object
required:
- value
- select
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/scaled"
select:
type: boolean
floating:
type: object
required:
- value
- select
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/values/floating"
select:
type: boolean
bitstring:
type: object
required:
- value
properties:
value:
$ref: "hat-gateway://iec101.yaml#/$defs/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:
oneOf:
- type: number
- enum:
- nan
- inf
- -inf
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
causes:
data:
res:
oneOf:
- enum:
- PERIODIC
- BACKGROUND_SCAN
- SPONTANEOUS
- REQUEST
- REMOTE_COMMAND
- LOCAL_COMMAND
- INTERROGATED_STATION
- INTERROGATED_GROUP01
- INTERROGATED_GROUP02
- INTERROGATED_GROUP03
- INTERROGATED_GROUP04
- INTERROGATED_GROUP05
- INTERROGATED_GROUP06
- INTERROGATED_GROUP07
- INTERROGATED_GROUP08
- INTERROGATED_GROUP09
- INTERROGATED_GROUP10
- INTERROGATED_GROUP11
- INTERROGATED_GROUP12
- INTERROGATED_GROUP13
- INTERROGATED_GROUP14
- INTERROGATED_GROUP15
- INTERROGATED_GROUP16
- INTERROGATED_COUNTER
- INTERROGATED_COUNTER01
- INTERROGATED_COUNTER02
- INTERROGATED_COUNTER03
- INTERROGATED_COUNTER04
- type: integer
description: |
other cause in range [0, 63]
command:
req:
oneOf:
- enum:
- ACTIVATION
- DEACTIVATION
- type: integer
description: |
other cause in range [0, 63]
res:
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]