hat.drivers.iec60870.encodings.iec104

8class AsduTypeError(Exception):
9    pass

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)

21class AsduType(enum.Enum):
22    M_SP_NA = iec101.AsduType.M_SP_NA.value
23    M_DP_NA = iec101.AsduType.M_DP_NA.value
24    M_ST_NA = iec101.AsduType.M_ST_NA.value
25    M_BO_NA = iec101.AsduType.M_BO_NA.value
26    M_ME_NA = iec101.AsduType.M_ME_NA.value
27    M_ME_NB = iec101.AsduType.M_ME_NB.value
28    M_ME_NC = iec101.AsduType.M_ME_NC.value
29    M_IT_NA = iec101.AsduType.M_IT_NA.value
30    M_PS_NA = iec101.AsduType.M_PS_NA.value
31    M_ME_ND = iec101.AsduType.M_ME_ND.value
32    M_SP_TB = iec101.AsduType.M_SP_TB.value
33    M_DP_TB = iec101.AsduType.M_DP_TB.value
34    M_ST_TB = iec101.AsduType.M_ST_TB.value
35    M_BO_TB = iec101.AsduType.M_BO_TB.value
36    M_ME_TD = iec101.AsduType.M_ME_TD.value
37    M_ME_TE = iec101.AsduType.M_ME_TE.value
38    M_ME_TF = iec101.AsduType.M_ME_TF.value
39    M_IT_TB = iec101.AsduType.M_IT_TB.value
40    M_EP_TD = iec101.AsduType.M_EP_TD.value
41    M_EP_TE = iec101.AsduType.M_EP_TE.value
42    M_EP_TF = iec101.AsduType.M_EP_TF.value
43    C_SC_NA = iec101.AsduType.C_SC_NA.value
44    C_DC_NA = iec101.AsduType.C_DC_NA.value
45    C_RC_NA = iec101.AsduType.C_RC_NA.value
46    C_SE_NA = iec101.AsduType.C_SE_NA.value
47    C_SE_NB = iec101.AsduType.C_SE_NB.value
48    C_SE_NC = iec101.AsduType.C_SE_NC.value
49    C_BO_NA = iec101.AsduType.C_BO_NA.value
50    C_SC_TA = 58
51    C_DC_TA = 59
52    C_RC_TA = 60
53    C_SE_TA = 61
54    C_SE_TB = 62
55    C_SE_TC = 63
56    C_BO_TA = 64
57    M_EI_NA = iec101.AsduType.M_EI_NA.value
58    C_IC_NA = iec101.AsduType.C_IC_NA.value
59    C_CI_NA = iec101.AsduType.C_CI_NA.value
60    C_RD_NA = iec101.AsduType.C_RD_NA.value
61    C_CS_NA = iec101.AsduType.C_CS_NA.value
62    C_RP_NA = iec101.AsduType.C_RP_NA.value
63    C_TS_TA = 107
64    P_ME_NA = iec101.AsduType.P_ME_NA.value
65    P_ME_NB = iec101.AsduType.P_ME_NB.value
66    P_ME_NC = iec101.AsduType.P_ME_NC.value
67    P_AC_NA = iec101.AsduType.P_AC_NA.value
68    F_FR_NA = iec101.AsduType.F_FR_NA.value
69    F_SR_NA = iec101.AsduType.F_SR_NA.value
70    F_SC_NA = iec101.AsduType.F_SC_NA.value
71    F_LS_NA = iec101.AsduType.F_LS_NA.value
72    F_AF_NA = iec101.AsduType.F_AF_NA.value
73    F_SG_NA = iec101.AsduType.F_SG_NA.value
74    F_DR_TA = iec101.AsduType.F_DR_TA.value

 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

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

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

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

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

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

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

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

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]"""

453class IoElement_C_RC_NA(typing.NamedTuple):
454    value: RegulatingValue
455    select: bool
456    qualifier: int
457    """qualifier in range [0, 31]"""

460class IoElement_C_SE_NA(typing.NamedTuple):
461    value: NormalizedValue
462    select: bool

465class IoElement_C_SE_NB(typing.NamedTuple):
466    value: ScaledValue
467    select: bool

470class IoElement_C_SE_NC(typing.NamedTuple):
471    value: FloatingValue
472    select: bool

475class IoElement_C_BO_NA(typing.NamedTuple):
476    value: BitstringValue

479class IoElement_M_EI_NA(typing.NamedTuple):
480    param_change: bool
481    cause: int
482    """cause in range [0, 127]"""

485class IoElement_C_IC_NA(typing.NamedTuple):
486    qualifier: int
487    """qualifier in range [0, 255]"""

490class IoElement_C_CI_NA(typing.NamedTuple):
491    request: int
492    """request in range [0, 63]"""
493    freeze: FreezeCode

496class IoElement_C_RD_NA(typing.NamedTuple):
497    pass

500class IoElement_C_CS_NA(typing.NamedTuple):
501    time: Time
502    """time size is SEVEN"""

509class IoElement_C_RP_NA(typing.NamedTuple):
510    qualifier: int
511    """qualifier in range [0, 255]"""

519class IoElement_P_ME_NA(typing.NamedTuple):
520    value: NormalizedValue
521    qualifier: int
522    """qualifier in range [0, 255]"""

525class IoElement_P_ME_NB(typing.NamedTuple):
526    value: ScaledValue
527    qualifier: int
528    """qualifier in range [0, 255]"""

531class IoElement_P_ME_NC(typing.NamedTuple):
532    value: FloatingValue
533    qualifier: int
534    """qualifier in range [0, 255]"""

537class IoElement_P_AC_NA(typing.NamedTuple):
538    qualifier: int
539    """qualifier in range [0, 255]"""

542class IoElement_F_FR_NA(typing.NamedTuple):
543    file_name: int
544    """file_name in range [0, 65535]"""
545    file_length: int
546    """file_length in range [0, 16777215]"""
547    ready: bool

550class IoElement_F_SR_NA(typing.NamedTuple):
551    file_name: int
552    """file_name in range [0, 65535]"""
553    section_name: int
554    """section_name in range [0, 255]"""
555    section_length: int
556    """section_length in range [0, 16777215]"""
557    ready: bool