|
33 | 33 |
|
34 | 34 | These types are used internally by the unpacking and packing mechanisms |
35 | 35 | when parsing or constructing DNP3 Application Layer objects. |
36 | | -
|
37 | | -
|
38 | 36 | """ |
39 | 37 |
|
40 | 38 | # 11.3 Primitive data types |
| 39 | +import datetime |
| 40 | +from io import BytesIO, StringIO |
41 | 41 | import math |
42 | 42 | import bitarray |
| 43 | +from caterpillar.byteorder import LittleEndian |
43 | 44 | from caterpillar.context import CTX_STREAM |
44 | 45 | from caterpillar.fields import ( |
45 | 46 | Bytes, |
46 | 47 | String, |
| 48 | + Transformer, |
47 | 49 | UInt, |
48 | 50 | float32, |
49 | 51 | float64, |
50 | 52 | int16, |
51 | 53 | int32, |
| 54 | + singleton, |
52 | 55 | uint16, |
53 | 56 | uint24, |
54 | 57 | uint32, |
|
78 | 81 | VSTR = String |
79 | 82 | """Variable-length string.""" |
80 | 83 |
|
81 | | -DNP3TIME = UInt(48) |
82 | | -"""48-bit DNP3 timestamp type.""" |
83 | | - |
84 | 84 | OSTR = Bytes |
85 | 85 | """Octet string (arbitrary-length byte sequence).""" |
86 | 86 |
|
|
91 | 91 | """64-bit IEEE-754 floating point.""" |
92 | 92 |
|
93 | 93 |
|
| 94 | +@singleton |
| 95 | +class DNP3TIME(Transformer): |
| 96 | + """48-bit DNP3 timestamp type. |
| 97 | +
|
| 98 | + This type represents a DNP3-compliant timestamp using a 48-bit unsigned |
| 99 | + integer. The timestamp is encoded as the number of **milliseconds since |
| 100 | + the Unix epoch (1970-01-01 00:00:00 UTC)**. |
| 101 | +
|
| 102 | + It provides automatic conversion between the raw integer form and a |
| 103 | + :class:`datetime.datetime` object when decoding, while encoding supports |
| 104 | + either integer millisecond values or datetime objects. |
| 105 | + """ |
| 106 | + |
| 107 | + def __init__(self) -> None: |
| 108 | + super().__init__(LittleEndian + UInt(48)) |
| 109 | + |
| 110 | + def decode(self, parsed: int, context) -> datetime.datetime | int: |
| 111 | + """Decode a 48-bit integer timestamp into a datetime object. |
| 112 | +
|
| 113 | + :param parsed: The parsed integer value representing milliseconds |
| 114 | + since the Unix epoch. |
| 115 | + :type parsed: int |
| 116 | + :param context: Transformation context (unused in this implementation). |
| 117 | + :type context: Any |
| 118 | + :return: A :class:`datetime.datetime` object if the value is within |
| 119 | + the valid timestamp range, otherwise the raw integer value. |
| 120 | + :rtype: datetime.datetime | int |
| 121 | + """ |
| 122 | + try: |
| 123 | + return datetime.datetime.fromtimestamp(parsed / 1000) |
| 124 | + except ValueError: |
| 125 | + return parsed |
| 126 | + |
| 127 | + def encode(self, obj: int | datetime.datetime, context) -> int: |
| 128 | + """Encode a datetime object or integer into a 48-bit millisecond value. |
| 129 | +
|
| 130 | + :param obj: The timestamp to encode, either as a datetime or an integer |
| 131 | + number of milliseconds since the Unix epoch. |
| 132 | + :type obj: int | datetime.datetime |
| 133 | + :param context: Transformation context (unused in this implementation). |
| 134 | + :type context: Any |
| 135 | + :return: The encoded timestamp as an integer in milliseconds. |
| 136 | + :rtype: int |
| 137 | + """ |
| 138 | + if isinstance(obj, datetime.datetime): |
| 139 | + obj = int(obj.timestamp()) * 1000 |
| 140 | + return int(obj) |
| 141 | + |
| 142 | + |
| 143 | +class BCD(Transformer): |
| 144 | + """Binary-coded decimal (BCD) type. |
| 145 | +
|
| 146 | + Implements DNP3 section 11.3.6: *Binary-coded decimal values use the notation |
| 147 | + BCDn, where ``n`` represents the number of BCD characters. For example, |
| 148 | + ``BCD8`` requires 8 BCD characters.* |
| 149 | +
|
| 150 | + Each BCD character is stored in 4 bits (a nibble). Two characters are packed |
| 151 | + into a single byte in little-endian order. |
| 152 | + """ |
| 153 | + |
| 154 | + def __init__(self, count: int) -> None: |
| 155 | + """Decode BCD bytes into a string of decimal digits. |
| 156 | +
|
| 157 | + :param parsed: Encoded binary-coded decimal bytes. |
| 158 | + :type parsed: bytes |
| 159 | + :param context: Transformation context (unused in this implementation). |
| 160 | + :type context: Any |
| 161 | + :return: The decoded decimal string, e.g. "1234". |
| 162 | + :rtype: str |
| 163 | + """ |
| 164 | + # Each BCD character requires 4 bits |
| 165 | + super().__init__(Bytes(count / 2)) |
| 166 | + |
| 167 | + def decode(self, parsed: bytes, context) -> str: |
| 168 | + """Encode a string of decimal digits into BCD bytes. |
| 169 | +
|
| 170 | + :param obj: The decimal string to encode. A '-' character may be used |
| 171 | + to represent a nibble value of 10. |
| 172 | + :type obj: str |
| 173 | + :param context: Transformation context (unused in this implementation). |
| 174 | + :type context: Any |
| 175 | + :return: Encoded BCD bytes. |
| 176 | + :rtype: bytes |
| 177 | + """ |
| 178 | + string = StringIO() |
| 179 | + for byte in parsed: |
| 180 | + # because of little endian encoding |
| 181 | + low_number = (byte & 0b11110000) >> 4 |
| 182 | + high_number = byte & 0b00001111 |
| 183 | + if high_number >= 10: |
| 184 | + _ = string.write("-") |
| 185 | + else: |
| 186 | + _ = string.write(str(high_number)) |
| 187 | + _ = string.write(str(low_number)) |
| 188 | + return string.getvalue() |
| 189 | + |
| 190 | + def encode(self, obj: str, context) -> bytes: |
| 191 | + packed = BytesIO() |
| 192 | + for i in range(0, len(obj), 2): |
| 193 | + low_number_str = obj[i] |
| 194 | + high_number_str = obj[i + 1] |
| 195 | + if high_number_str == "-": |
| 196 | + high_number = 10 |
| 197 | + else: |
| 198 | + high_number = int(high_number_str) |
| 199 | + low_number = int(low_number_str) |
| 200 | + _ = packed.write(high_number | low_number << 4) |
| 201 | + |
| 202 | + return packed.getvalue() |
| 203 | + |
| 204 | + |
94 | 205 | class BSTRn: |
95 | 206 | """Packed bit string (BSTRn) representation. |
96 | 207 |
|
|
0 commit comments