hat.drivers.iec60870.encodings.iec103

24class TimeSize(enum.Enum):
25    TWO = 2
26    THREE = 3
27    FOUR = 4
28    SEVEN = 7

31class Time(typing.NamedTuple):
32    size: TimeSize
33    milliseconds: int
34    """milliseconds in range [0, 59999]"""
35    invalid: bool | None
36    """available for size THREE, FOUR, SEVEN"""
37    minutes: int | None
38    """available for size THREE, FOUR, SEVEN (minutes in range [0, 59])"""
39    summer_time: bool | None
40    """available for size FOUR, SEVEN"""
41    hours: int | None
42    """available for size FOUR, SEVEN (hours in range [0, 23])"""
43    day_of_week: int | None
44    """available for size SEVEN (day_of_week in range [1, 7])"""
45    day_of_month: int | None
46    """available for size SEVEN (day_of_month in range [1, 31])"""
47    months: int | None
48    """available for size SEVEN (months in range [1, 12])"""
49    years: int | None
50    """available for size SEVEN (years in range [0, 99])"""

66def time_from_datetime(dt: datetime.datetime,
67                       invalid: bool = False
68                       ) -> Time:
69    """Create Time from datetime.datetime"""
70    # TODO document edge cases (local time, os implementation, ...)
71    #  rounding microseconds to the nearest millisecond
72    dt_rounded = (
73        dt.replace(microsecond=0) +
74        datetime.timedelta(milliseconds=round(dt.microsecond / 1000)))
75    local_time = time.localtime(dt_rounded.timestamp())
76
77    return Time(
78        size=TimeSize.SEVEN,
79        milliseconds=(local_time.tm_sec * 1000 +
80                      dt_rounded.microsecond // 1000),
81        invalid=invalid,
82        minutes=local_time.tm_min,
83        summer_time=bool(local_time.tm_isdst),
84        hours=local_time.tm_hour,
85        day_of_week=local_time.tm_wday + 1,
86        day_of_month=local_time.tm_mday,
87        months=local_time.tm_mon,
88        years=local_time.tm_year % 100)

 91def time_to_datetime(t: Time
 92                     ) -> datetime.datetime:
 93    """Convert Time to datetime.datetime"""
 94    # TODO document edge cases (local time, os implementation, ...)
 95    # TODO maybe allow diferent time size (use now for time)
 96    if t.size != TimeSize.SEVEN:
 97        raise ValueError('unsupported time size')
 98
 99    local_dt = datetime.datetime(
100        year=2000 + t.years if t.years < 70 else 1900 + t.years,
101        month=t.months,
102        day=t.day_of_month,
103        hour=t.hours,
104        minute=t.minutes,
105        second=int(t.milliseconds / 1000),
106        microsecond=(t.milliseconds % 1000) * 1000,
107        fold=not t.summer_time)
108
109    return local_dt.astimezone(tz=datetime.timezone.utc)

19class AsduType(enum.Enum):
20    TIME_TAGGED_MESSAGE = 1
21    TIME_TAGGED_MESSAGE_WITH_RELATIVE_TIME = 2
22    MEASURANDS_1 = 3
23    TIME_TAGGED_MEASURANDS_WITH_RELATIVE_TIME = 4
24    IDENTIFICATION = 5
25    TIME_SYNCHRONIZATION = 6
26    GENERAL_INTERROGATION = 7
27    GENERAL_INTERROGATION_TERMINATION = 8
28    MEASURANDS_2 = 9
29    GENERIC_DATA = 10
30    GENERIC_IDENTIFICATION = 11
31    GENERAL_COMMAND = 20
32    GENERIC_COMMAND = 21
33    LIST_OF_RECORDED_DISTURBANCES = 23
34    ORDER_FOR_DISTURBANCE_DATA_TRANSMISSION = 24
35    ACKNOWLEDGEMENT_FOR_DISTURBANCE_DATA_TRANSMISSION = 25
36    READY_FOR_TRANSMISSION_OF_DISTURBANCE_DATA = 26
37    READY_FOR_TRANSMISSION_OF_A_CHANNEL = 27
38    READY_FOR_TRANSMISSION_OF_TAGS = 28
39    TRANSMISSION_OF_TAGS = 29
40    TRANSMISSION_OF_DISTURBANCE_VALUES = 30
41    END_OF_TRANSMISSION = 31

44class Cause(enum.Enum):
45    SPONTANEOUS = 1
46    CYCLIC = 2
47    RESET_FRAME_COUNT_BIT = 3
48    RESET_COMMUNICATION_UNIT = 4
49    START_RESTART = 5
50    POWER_ON = 6
51    TEST_MODE = 7
52    TIME_SYNCHRONIZATION = 8
53    GENERAL_INTERROGATION = 9
54    TERMINATION_OF_GENERAL_INTERROGATION = 10
55    LOCAL_OPERATION = 11
56    REMOTE_OPERATION = 12
57    GENERAL_COMMAND = 20
58    GENERAL_COMMAND_NACK = 21
59    TRANSMISSION_OF_DISTURBANCE_DATA = 31
60    GENERIC_WRITE_COMMAND = 40
61    GENERIC_WRITE_COMMAND_NACK = 41
62    GENERIC_READ_COMMAND = 42
63    GENERIC_READ_COMMAND_NACK = 43
64    GENERIC_WRITE_CONFIRMATION = 44

67class Description(enum.Enum):
68    NOT_SPECIFIED = 0
69    ACTUAL_VALUE = 1
70    DEFAULT_VALUE = 2
71    RANGE = 3
72    PRECISION = 5
73    FACTOR = 6
74    REFERENCE = 7
75    ENUMERATION = 8
76    DIMENSION = 9
77    DESCRIPTION = 10
78    PASSWORD = 12
79    READ_ONLY = 13
80    WRITE_ONLY = 14
81    IO_ADDRESS = 19
82    EVENT = 20
83    TEXT_ARRAY = 21
84    VALUE_ARRAY = 22
85    RELATED = 23

 88class OrderType(enum.Enum):
 89    SELECTION_OF_FAULT = 1
 90    REQUEST_FOR_DISTURBANCE_DATA = 2
 91    ABORTION_OF_DISTURBANCE_DATA = 3
 92    REQUEST_FOR_CHANNEL = 8
 93    ABORTION_OF_CHANNEL = 9
 94    REQUEST_FOR_TAGS = 16
 95    ABORTION_OF_TAGS = 17
 96    REQUEST_FOR_LIST_OF_RECORDED_DISTURBANCES = 24
 97    END_OF_DISTURBANCE_DATA_TRANSMISSION_WITHOUT_ABORTION = 32
 98    END_OF_DISTURBANCE_DATA_TRANSMISSION_WITH_ABORTION_BY_CONTROL_SYSTEM = 33
 99    END_OF_DISTURBANCE_DATA_TRANSMISSION_WITH_ABORTION_BY_THE_PROTECTION_EQUIPMENT = 34  # NOQA
100    END_OF_CHANNEL_TRANSMISSION_WITHOUT_ABORTION = 35
101    END_OF_CHANNEL_TRANSMISSION_WITH_ABORTION_BY_CONTROL_SYSTEM = 36
102    END_OF_CHANNEL_TRANSMISSION_WITH_ABORTION_BY_THE_PROTECTION_EQUIPMENT = 37
103    END_OF_TAG_TRANSMISSION_WITHOUT_ABORTION = 38
104    END_OF_TAG_TRANSMISSION_WITH_ABORTION_BY_CONTROL_SYSTEM = 39
105    END_OF_TAG_TRANSMISSION_WITH_ABORTION_BY_THE_PROTECTION_EQUIPMENT = 40
106    DISTURBANCE_DATA_TRANSMITTED_SUCCESSFULLY = 64
107    DISTURBANCE_DATA_TRANSMITTED_NOT_SUCCESSFULLY = 65
108    CHANNEL_TRANSMITTED_SUCCESSFULLY = 66
109    CHANNEL_TRANSMITTED_NOT_SUCCESSFULLY = 67
110    TAGS_TRANSMITTED_SUCCESSFULLY = 68
111    TAGS_TRANSMITTED_NOT_SUCCESSFULLY = 69

114class Channel(enum.Enum):
115    GLOBAL = 0
116    I_L1 = 1
117    I_L2 = 2
118    I_L3 = 3
119    I_N = 4
120    V_L1E = 5
121    V_L2E = 6
122    V_L3E = 7
123    V_EN = 8

126class IoAddress(typing.NamedTuple):
127    function_type: int
128    """function_type is in range [0, 255]"""
129    information_number: int
130    """information_number is in range [0, 255]"""

133class Identification(typing.NamedTuple):
134    group_id: int
135    """group_id in range [0, 255]"""
136    entry_id: int
137    """entry_id in range [0, 255]"""

140class ValueType(enum.Enum):
141    NONE = 0
142    TEXT = 1
143    BITSTRING = 2
144    UINT = 3
145    INT = 4
146    UFIXED = 5
147    FIXED = 6
148    REAL32 = 7
149    REAL64 = 8
150    DOUBLE = 9
151    SINGLE = 10
152    EXTENDED_DOUBLE = 11
153    MEASURAND = 12
154    TIME = 14
155    IDENTIFICATION = 15
156    RELATIVE_TIME = 16
157    IO_ADDRESS = 17
158    DOUBLE_WITH_TIME = 18
159    DOUBLE_WITH_RELATIVE_TIME = 19
160    MEASURAND_WITH_RELATIVE_TIME = 20
161    TEXT_NUMBER = 21
162    REPLY = 22
163    ARRAY = 23
164    INDEX = 24

167class NoneValue(typing.NamedTuple):
168    pass

171class TextValue(typing.NamedTuple):
172    value: util.Bytes

175class BitstringValue(typing.NamedTuple):
176    value: list[bool]

179class UIntValue(typing.NamedTuple):
180    value: int

183class IntValue(typing.NamedTuple):
184    value: int

187class UFixedValue(typing.NamedTuple):
188    value: float
189    """value in range [0, 1.0]"""

192class FixedValue(typing.NamedTuple):
193    value: float
194    """value in range [-1.0, 1.0)"""

197class Real32Value(typing.NamedTuple):
198    value: float

201class Real64Value(typing.NamedTuple):
202    value: float

205class DoubleValue(enum.Enum):
206    TRANSIENT = 0
207    OFF = 1
208    ON = 2
209    ERROR = 3

212class SingleValue(enum.Enum):
213    OFF = 0
214    ON = 1

217class ExtendedDoubleValue(enum.Enum):
218    TRANSIENT = 0
219    OFF = 1
220    ON = 2
221    ERROR = 3

224class MeasurandValue(typing.NamedTuple):
225    overflow: bool
226    invalid: bool
227    value: float
228    """value in range [-1.0, 1.0)"""

231class TimeValue(typing.NamedTuple):
232    value: Time
233    """time size is SEVEN"""

236class IdentificationValue(typing.NamedTuple):
237    value: Identification

240class RelativeTimeValue(typing.NamedTuple):
241    value: int
242    """value in range [0, 65535]"""

245class IoAddressValue(typing.NamedTuple):
246    value: IoAddress

249class DoubleWithTimeValue(typing.NamedTuple):
250    value: DoubleValue
251    time: Time
252    """time size is FOUR"""
253    supplementary: int
254    """supplementary in range [0, 255]"""

257class DoubleWithRelativeTimeValue(typing.NamedTuple):
258    value: DoubleValue
259    relative_time: int
260    """relative_time in range [0, 65535]"""
261    fault_number: int
262    """fault_number in range [0, 65535]"""
263    time: Time
264    """time size is FOUR"""
265    supplementary: int
266    """supplementary in range [0, 255]"""

269class MeasurandWithRelativeTimeValue(typing.NamedTuple):
270    value: float
271    relative_time: int
272    """relative_time in range [0, 65535]"""
273    fault_number: int
274    """fault_number in range [0, 65535]"""
275    time: Time
276    """time size is FOUR"""

279class TextNumberValue(typing.NamedTuple):
280    value: int

283class ReplyValue(enum.Enum):
284    ACK = 0
285    INVALID_IDENTIFICATION = 1
286    DATA_NOT_EXISTS = 2
287    DATA_NOT_AVAILABLE = 3
288    VERIFY_ERROR = 4
289    OUT_OF_RANGE = 5
290    ENTRY_TO_LARGE = 6
291    TOO_MANY_COMMANDS = 7
292    ENTRY_READ_ONLY = 8
293    PASSWORD_PROTECTED = 9
294    IN_PROGRESS = 10
295    FOLLOWING_DESCRIPTION = 11

298class ArrayValue(typing.NamedTuple):
299    value_type: ValueType
300    more_follows: bool
301    values: typing.List['Value']

304class IndexValue(typing.NamedTuple):
305    value: int

334class DescriptiveData(typing.NamedTuple):
335    description: Description
336    value: ArrayValue

339class IoElement_TIME_TAGGED_MESSAGE(typing.NamedTuple):
340    value: DoubleWithTimeValue

343class IoElement_TIME_TAGGED_MESSAGE_WITH_RELATIVE_TIME(typing.NamedTuple):
344    value: DoubleWithRelativeTimeValue

347class IoElement_MEASURANDS_1(typing.NamedTuple):
348    value: MeasurandValue

351class IoElement_TIME_TAGGED_MEASURANDS_WITH_RELATIVE_TIME(typing.NamedTuple):
352    value: MeasurandWithRelativeTimeValue

355class IoElement_IDENTIFICATION(typing.NamedTuple):
356    compatibility: int
357    """compatibility in range [0, 255]"""
358    value: util.Bytes
359    """value length is 8"""
360    software: util.Bytes
361    """software length is 4"""

364class IoElement_TIME_SYNCHRONIZATION(typing.NamedTuple):
365    time: Time
366    """time size is SEVEN"""

369class IoElement_GENERAL_INTERROGATION(typing.NamedTuple):
370    scan_number: int
371    """scan_number in range [0, 255]"""

374class IoElement_GENERAL_INTERROGATION_TERMINATION(typing.NamedTuple):
375    scan_number: int
376    """scan_number in range [0, 255]"""

379class IoElement_MEASURANDS_2(typing.NamedTuple):
380    value: MeasurandValue

383class IoElement_GENERIC_DATA(typing.NamedTuple):
384    return_identifier: int
385    """return_identifier in range [0, 255]"""
386    counter: bool
387    more_follows: bool
388    data: list[tuple[Identification, DescriptiveData]]

391class IoElement_GENERIC_IDENTIFICATION(typing.NamedTuple):
392    return_identifier: int
393    """return_identifier in range [0, 255]"""
394    identification: Identification
395    counter: bool
396    more_follows: bool
397    data: list[DescriptiveData]

400class IoElement_GENERAL_COMMAND(typing.NamedTuple):
401    value: DoubleValue
402    return_identifier: int
403    """return_identifier in range [0, 255]"""

406class IoElement_GENERIC_COMMAND(typing.NamedTuple):
407    return_identifier: int
408    """return_identifier in range [0, 255]"""
409    data: list[tuple[Identification, Description]]

412class IoElement_LIST_OF_RECORDED_DISTURBANCES(typing.NamedTuple):
413    fault_number: int
414    """fault_number in range [0, 65535]"""
415    trip: bool
416    transmitted: bool
417    test: bool
418    other: bool
419    time: Time
420    """time size is SEVEN"""

423class IoElement_ORDER_FOR_DISTURBANCE_DATA_TRANSMISSION(typing.NamedTuple):
424    order_type: OrderType
425    fault_number: int
426    """fault_number in range [0, 65535]"""
427    channel: Channel

430class IoElement_ACKNOWLEDGEMENT_FOR_DISTURBANCE_DATA_TRANSMISSION(typing.NamedTuple):  # NOQA
431    order_type: OrderType
432    fault_number: int
433    """fault_number in range [0, 65535]"""
434    channel: Channel

437class IoElement_READY_FOR_TRANSMISSION_OF_DISTURBANCE_DATA(typing.NamedTuple):
438    fault_number: int
439    """fault_number in range [0, 65535]"""
440    number_of_faults: int
441    """number_of_faults in range [0, 65535]"""
442    number_of_channels: int
443    """number_of_channels in range [0, 255]"""
444    number_of_elements: int
445    """number_of_elements in range [1, 65535]"""
446    interval: int
447    """interval in range [1, 65535]"""
448    time: Time
449    """time size is FOUR"""

452class IoElement_READY_FOR_TRANSMISSION_OF_A_CHANNEL(typing.NamedTuple):
453    fault_number: int
454    """fault_number in range [0, 65535]"""
455    channel: Channel
456    primary: Real32Value
457    secondary: Real32Value
458    reference: Real32Value

461class IoElement_READY_FOR_TRANSMISSION_OF_TAGS(typing.NamedTuple):
462    fault_number: int
463    """fault_number in range [0, 65535]"""

466class IoElement_TRANSMISSION_OF_TAGS(typing.NamedTuple):
467    fault_number: int
468    """fault_number in range [0, 65535]"""
469    tag_position: int
470    """tag_position in range [0, 65535]"""
471    values: list[tuple[IoAddress, DoubleValue]]

474class IoElement_TRANSMISSION_OF_DISTURBANCE_VALUES(typing.NamedTuple):
475    fault_number: int
476    """fault_number in range [0, 65535]"""
477    channel: Channel
478    element_number: int
479    """element_number in range [0, 65535]"""
480    values: list[float]
481    """values are in range [-1.0, 1.0)"""

484class IoElement_END_OF_TRANSMISSION(typing.NamedTuple):
485    order_type: OrderType
486    fault_number: int
487    """fault_number in range [0, 65535]"""
488    channel: Channel

516class IO(typing.NamedTuple):
517    address: IoAddress
518    elements: list[IoElement]

521class ASDU(typing.NamedTuple):
522    type: AsduType
523    cause: Cause | OtherCause
524    address: AsduAddress
525    ios: list[IO]

14class Encoder:
15
16    def __init__(self):
17        self._encoder = encoder.Encoder(
18            cause_size=common.CauseSize.ONE,
19            asdu_address_size=common.AsduAddressSize.ONE,
20            io_address_size=common.IoAddressSize.TWO,
21            asdu_type_time_sizes={},
22            inverted_sequence_bit=True,
23            decode_io_element_cb=_decode_io_element,
24            encode_io_element_cb=_encode_io_element)
25
26    def decode_asdu(self,
27                    asdu_bytes: util.Bytes
28                    ) -> tuple[common.ASDU, util.Bytes]:
29        asdu, rest = self._encoder.decode_asdu(asdu_bytes)
30
31        asdu_type = common.AsduType(asdu.type)
32        cause = _decode_cause(asdu.cause)
33        address = asdu.address
34        ios = [common.IO(address=_decode_io_address(io.address),
35                         elements=io.elements)
36               for io in asdu.ios]
37
38        # TODO assert len(asdu.ios) == 1
39
40        asdu = common.ASDU(type=asdu_type,
41                           cause=cause,
42                           address=address,
43                           ios=ios)
44        return asdu, rest
45
46    def encode_asdu(self, asdu: common.ASDU) -> util.Bytes:
47        asdu_type = asdu.type.value
48        cause = _encode_cause(asdu.cause)
49        address = asdu.address
50        ios = [encoder.common.IO(address=_encode_io_address(io.address),
51                                 elements=io.elements,
52                                 time=None)
53               for io in asdu.ios]
54
55        asdu = encoder.common.ASDU(type=asdu_type,
56                                   cause=cause,
57                                   address=address,
58                                   ios=ios)
59
60        return self._encoder.encode_asdu(asdu)