hat.drivers.iec60870.encodings.iec101

8class AsduTypeError(Exception):
9    pass

12class CauseSize(enum.Enum):
13    ONE = 1
14    TWO = 2

17class AsduAddressSize(enum.Enum):
18    ONE = 1
19    TWO = 2

22class IoAddressSize(enum.Enum):
23    ONE = 1
24    TWO = 2
25    THREE = 3

28class TimeSize(enum.Enum):
29    TWO = 2
30    THREE = 3
31    FOUR = 4
32    SEVEN = 7

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

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

 95def time_to_datetime(t: Time
 96                     ) -> datetime.datetime:
 97    """Convert Time to datetime.datetime"""
 98    # TODO document edge cases (local time, os implementation, ...)
 99    # TODO support TimeSize.FOUR
100    if t.size == TimeSize.TWO:
101        local_now = datetime.datetime.now()
102        local_dt = local_now.replace(
103            second=int(t.milliseconds / 1000),
104            microsecond=(t.milliseconds % 1000) * 1000)
105
106        local_seconds = local_now.second + local_now.microsecond / 1_000_000
107        t_seconds = t.milliseconds / 1_000
108
109        if abs(local_seconds - t_seconds) > 30:
110            if local_seconds < t_seconds:
111                local_dt = local_dt - datetime.timedelta(minutes=1)
112
113            else:
114                local_dt = local_dt + datetime.timedelta(minutes=1)
115
116    elif t.size == TimeSize.THREE:
117        local_now = datetime.datetime.now()
118        local_dt = local_now.replace(
119            minute=t.minutes,
120            second=int(t.milliseconds / 1000),
121            microsecond=(t.milliseconds % 1000) * 1000)
122
123        local_minutes = (local_now.minute +
124                         local_now.second / 60 +
125                         local_now.microsecond / 60_000_000)
126        t_minutes = t.minutes + t.milliseconds / 60_000
127
128        if abs(local_minutes - t_minutes) > 30:
129            if local_minutes < t_minutes:
130                local_dt = local_dt - datetime.timedelta(hours=1)
131
132            else:
133                local_dt = local_dt + datetime.timedelta(hours=1)
134
135    elif t.size == TimeSize.SEVEN:
136        local_dt = datetime.datetime(
137            year=2000 + t.years if t.years < 70 else 1900 + t.years,
138            month=t.months,
139            day=t.day_of_month,
140            hour=t.hours,
141            minute=t.minutes,
142            second=int(t.milliseconds / 1000),
143            microsecond=(t.milliseconds % 1000) * 1000,
144            fold=not t.summer_time)
145
146    else:
147        raise ValueError('unsupported time size')
148
149    return local_dt.astimezone(tz=datetime.timezone.utc)

25class AsduType(enum.Enum):
26    M_SP_NA = 1
27    M_SP_TA = 2
28    M_DP_NA = 3
29    M_DP_TA = 4
30    M_ST_NA = 5
31    M_ST_TA = 6
32    M_BO_NA = 7
33    M_BO_TA = 8
34    M_ME_NA = 9
35    M_ME_TA = 10
36    M_ME_NB = 11
37    M_ME_TB = 12
38    M_ME_NC = 13
39    M_ME_TC = 14
40    M_IT_NA = 15
41    M_IT_TA = 16
42    M_EP_TA = 17
43    M_EP_TB = 18
44    M_EP_TC = 19
45    M_PS_NA = 20
46    M_ME_ND = 21
47    M_SP_TB = 30
48    M_DP_TB = 31
49    M_ST_TB = 32
50    M_BO_TB = 33
51    M_ME_TD = 34
52    M_ME_TE = 35
53    M_ME_TF = 36
54    M_IT_TB = 37
55    M_EP_TD = 38
56    M_EP_TE = 39
57    M_EP_TF = 40
58    C_SC_NA = 45
59    C_DC_NA = 46
60    C_RC_NA = 47
61    C_SE_NA = 48
62    C_SE_NB = 49
63    C_SE_NC = 50
64    C_BO_NA = 51
65    M_EI_NA = 70
66    C_IC_NA = 100
67    C_CI_NA = 101
68    C_RD_NA = 102
69    C_CS_NA = 103
70    C_TS_NA = 104
71    C_RP_NA = 105
72    C_CD_NA = 106
73    P_ME_NA = 110
74    P_ME_NB = 111
75    P_ME_NC = 112
76    P_AC_NA = 113
77    F_FR_NA = 120
78    F_SR_NA = 121
79    F_SC_NA = 122
80    F_LS_NA = 123
81    F_AF_NA = 124
82    F_SG_NA = 125
83    F_DR_TA = 126

 86class CauseType(enum.Enum):
 87    UNDEFINED = 0
 88    PERIODIC = 1
 89    BACKGROUND_SCAN = 2
 90    SPONTANEOUS = 3
 91    INITIALIZED = 4
 92    REQUEST = 5
 93    ACTIVATION = 6
 94    ACTIVATION_CONFIRMATION = 7
 95    DEACTIVATION = 8
 96    DEACTIVATION_CONFIRMATION = 9
 97    ACTIVATION_TERMINATION = 10
 98    REMOTE_COMMAND = 11
 99    LOCAL_COMMAND = 12
100    FILE_TRANSFER = 13
101    INTERROGATED_STATION = 20
102    INTERROGATED_GROUP01 = 21
103    INTERROGATED_GROUP02 = 22
104    INTERROGATED_GROUP03 = 23
105    INTERROGATED_GROUP04 = 24
106    INTERROGATED_GROUP05 = 25
107    INTERROGATED_GROUP06 = 26
108    INTERROGATED_GROUP07 = 27
109    INTERROGATED_GROUP08 = 28
110    INTERROGATED_GROUP09 = 29
111    INTERROGATED_GROUP10 = 30
112    INTERROGATED_GROUP11 = 31
113    INTERROGATED_GROUP12 = 32
114    INTERROGATED_GROUP13 = 33
115    INTERROGATED_GROUP14 = 34
116    INTERROGATED_GROUP15 = 35
117    INTERROGATED_GROUP16 = 36
118    INTERROGATED_COUNTER = 37
119    INTERROGATED_COUNTER01 = 38
120    INTERROGATED_COUNTER02 = 39
121    INTERROGATED_COUNTER03 = 40
122    INTERROGATED_COUNTER04 = 41
123    UNKNOWN_TYPE = 44
124    UNKNOWN_CAUSE = 45
125    UNKNOWN_ASDU_ADDRESS = 46
126    UNKNOWN_IO_ADDRESS = 47

129class Cause(typing.NamedTuple):
130    type: CauseType | OtherCauseType
131    is_negative_confirm: bool
132    is_test: bool
133    originator_address: OriginatorAddress

136class QualityType(enum.Enum):
137    INDICATION = 0
138    MEASUREMENT = 1
139    COUNTER = 2
140    PROTECTION = 3

143class IndicationQuality(typing.NamedTuple):
144    invalid: bool
145    not_topical: bool
146    substituted: bool
147    blocked: bool

150class MeasurementQuality(typing.NamedTuple):
151    invalid: bool
152    not_topical: bool
153    substituted: bool
154    blocked: bool
155    overflow: bool

158class CounterQuality(typing.NamedTuple):
159    invalid: bool
160    adjusted: bool
161    overflow: bool
162    sequence: int
163    """sequence in range [0, 31]"""

166class ProtectionQuality(typing.NamedTuple):
167    invalid: bool
168    not_topical: bool
169    substituted: bool
170    blocked: bool
171    time_invalid: bool

180class FreezeCode(enum.Enum):
181    READ = 0
182    FREEZE = 1
183    FREEZE_AND_RESET = 2
184    RESET = 3

187class SingleValue(enum.Enum):
188    OFF = 0
189    ON = 1

192class DoubleValue(enum.Enum):
193    """DoubleDataValue
194
195    `FAULT` stands for value 3, defined in the protocol as *INDETERMINATE*.
196    This is in order to make it more distinguishable from ``INTERMEDIATE``.
197
198    """
199    INTERMEDIATE = 0
200    OFF = 1
201    ON = 2
202    FAULT = 3

205class RegulatingValue(enum.Enum):
206    LOWER = 1
207    HIGHER = 2

210class StepPositionValue(typing.NamedTuple):
211    value: int
212    """value in range [-64, 63]"""
213    transient: bool

216class BitstringValue(typing.NamedTuple):
217    value: util.Bytes
218    """bitstring encoded as 4 bytes"""

221class NormalizedValue(typing.NamedTuple):
222    value: float
223    """value in range [-1.0, 1.0)"""

226class ScaledValue(typing.NamedTuple):
227    value: int
228    """value in range [-2^15, 2^15-1]"""

231class FloatingValue(typing.NamedTuple):
232    value: float

235class BinaryCounterValue(typing.NamedTuple):
236    value: int
237    """value in range [-2^31, 2^31-1]"""

240class ProtectionValue(enum.Enum):
241    OFF = 1
242    ON = 2

245class ProtectionStartValue(typing.NamedTuple):
246    general: bool
247    l1: bool
248    l2: bool
249    l3: bool
250    ie: bool
251    reverse: bool

254class ProtectionCommandValue(typing.NamedTuple):
255    general: bool
256    l1: bool
257    l2: bool
258    l3: bool

261class StatusValue(typing.NamedTuple):
262    value: list[bool]
263    """value length is 16"""
264    change: list[bool]
265    """change length is 16"""

268class IoElement_M_SP_NA(typing.NamedTuple):
269    value: SingleValue
270    quality: IndicationQuality

273class IoElement_M_SP_TA(typing.NamedTuple):
274    value: SingleValue
275    quality: IndicationQuality

278class IoElement_M_DP_NA(typing.NamedTuple):
279    value: DoubleValue
280    quality: IndicationQuality

283class IoElement_M_DP_TA(typing.NamedTuple):
284    value: DoubleValue
285    quality: IndicationQuality

288class IoElement_M_ST_NA(typing.NamedTuple):
289    value: StepPositionValue
290    quality: MeasurementQuality

293class IoElement_M_ST_TA(typing.NamedTuple):
294    value: StepPositionValue
295    quality: MeasurementQuality

298class IoElement_M_BO_NA(typing.NamedTuple):
299    value: BitstringValue
300    quality: MeasurementQuality

303class IoElement_M_BO_TA(typing.NamedTuple):
304    value: BitstringValue
305    quality: MeasurementQuality

308class IoElement_M_ME_NA(typing.NamedTuple):
309    value: NormalizedValue
310    quality: MeasurementQuality

313class IoElement_M_ME_TA(typing.NamedTuple):
314    value: NormalizedValue
315    quality: MeasurementQuality

318class IoElement_M_ME_NB(typing.NamedTuple):
319    value: ScaledValue
320    quality: MeasurementQuality

323class IoElement_M_ME_TB(typing.NamedTuple):
324    value: ScaledValue
325    quality: MeasurementQuality

328class IoElement_M_ME_NC(typing.NamedTuple):
329    value: FloatingValue
330    quality: MeasurementQuality

333class IoElement_M_ME_TC(typing.NamedTuple):
334    value: FloatingValue
335    quality: MeasurementQuality

338class IoElement_M_IT_NA(typing.NamedTuple):
339    value: BinaryCounterValue
340    quality: CounterQuality

343class IoElement_M_IT_TA(typing.NamedTuple):
344    value: BinaryCounterValue
345    quality: CounterQuality

348class IoElement_M_EP_TA(typing.NamedTuple):
349    value: ProtectionValue
350    quality: ProtectionQuality
351    elapsed_time: int
352    """elapsed_time in range [0, 65535]"""

355class IoElement_M_EP_TB(typing.NamedTuple):
356    value: ProtectionStartValue
357    quality: ProtectionQuality
358    duration_time: int
359    """duration_time in range [0, 65535]"""

362class IoElement_M_EP_TC(typing.NamedTuple):
363    value: ProtectionCommandValue
364    quality: ProtectionQuality
365    operating_time: int
366    """operating_time in range [0, 65535]"""

369class IoElement_M_PS_NA(typing.NamedTuple):
370    value: StatusValue
371    quality: MeasurementQuality

374class IoElement_M_ME_ND(typing.NamedTuple):
375    value: NormalizedValue

378class IoElement_M_SP_TB(typing.NamedTuple):
379    value: SingleValue
380    quality: IndicationQuality

383class IoElement_M_DP_TB(typing.NamedTuple):
384    value: DoubleValue
385    quality: IndicationQuality

388class IoElement_M_ST_TB(typing.NamedTuple):
389    value: StepPositionValue
390    quality: MeasurementQuality

393class IoElement_M_BO_TB(typing.NamedTuple):
394    value: BitstringValue
395    quality: MeasurementQuality

398class IoElement_M_ME_TD(typing.NamedTuple):
399    value: NormalizedValue
400    quality: MeasurementQuality

403class IoElement_M_ME_TE(typing.NamedTuple):
404    value: ScaledValue
405    quality: MeasurementQuality

408class IoElement_M_ME_TF(typing.NamedTuple):
409    value: FloatingValue
410    quality: MeasurementQuality

413class IoElement_M_IT_TB(typing.NamedTuple):
414    value: BinaryCounterValue
415    quality: CounterQuality

418class IoElement_M_EP_TD(typing.NamedTuple):
419    value: ProtectionValue
420    quality: ProtectionQuality
421    elapsed_time: int
422    """elapsed_time in range [0, 65535]"""

425class IoElement_M_EP_TE(typing.NamedTuple):
426    value: ProtectionStartValue
427    quality: ProtectionQuality
428    duration_time: int
429    """duration_time in range [0, 65535]"""

432class IoElement_M_EP_TF(typing.NamedTuple):
433    value: ProtectionCommandValue
434    quality: ProtectionQuality
435    operating_time: int
436    """operating_time in range [0, 65535]"""

439class IoElement_C_SC_NA(typing.NamedTuple):
440    value: SingleValue
441    select: bool
442    qualifier: int
443    """qualifier in range [0, 31]"""

446class IoElement_C_DC_NA(typing.NamedTuple):
447    value: DoubleValue
448    select: bool
449    qualifier: int
450    """qualifier in range [0, 31]"""