pycomap 2.1.1__tar.gz → 2.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {pycomap-2.1.1 → pycomap-2.3.0}/PKG-INFO +1 -1
- {pycomap-2.1.1 → pycomap-2.3.0}/pyproject.toml +1 -1
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/configuration.py +75 -14
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/controller.py +27 -5
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/protocol/client.py +17 -5
- {pycomap-2.1.1 → pycomap-2.3.0}/README.md +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/__init__.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/alarms.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/datatypes.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/discovery.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/exceptions.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/history.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/protocol/__init__.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/protocol/commands.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/protocol/crc.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/protocol/crypto.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/protocol/framing.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/protocol/objects.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/protocol/transport.py +0 -0
- {pycomap-2.1.1 → pycomap-2.3.0}/src/pycomap/py.typed +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pycomap
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.3.0
|
|
4
4
|
Summary: Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol
|
|
5
5
|
Author: Igor Panteleyev
|
|
6
6
|
Author-email: Igor Panteleyev <panteleev.igor69@gmail.com>
|
|
@@ -53,6 +53,7 @@ _log = logging.getLogger(__name__)
|
|
|
53
53
|
|
|
54
54
|
__all__ = [
|
|
55
55
|
"ConfigurationTable",
|
|
56
|
+
"HistoryFieldDescription",
|
|
56
57
|
"NamesCategory",
|
|
57
58
|
"ProtectionState",
|
|
58
59
|
"SetpointCategory",
|
|
@@ -79,6 +80,11 @@ _STATE_INDEX_FOR_NO_STATE = 1023
|
|
|
79
80
|
_NUM_SETPOINTS_CAT_P_OFFSET = 98
|
|
80
81
|
_SETPOINT_RECORD_SIZE = 14
|
|
81
82
|
|
|
83
|
+
# History snapshot field layout (IL3, ConfigurationTableLoaderIL3.CreateConfigurationTableLoadInfo
|
|
84
|
+
# NumHistFieldsOffset=152, IsNumHistFieldsByte=false). Distinct from ValuesAll's data_index --
|
|
85
|
+
# see HistoryFieldDescription and _parse_history_description.
|
|
86
|
+
_NUM_HIST_FIELDS_OFFSET = 152
|
|
87
|
+
|
|
82
88
|
# Unified names heap (IL3-specific fixed offsets, see module docstring and
|
|
83
89
|
# docs/protocol.md section 4).
|
|
84
90
|
_DESCR_LANG_OFFSET = 169
|
|
@@ -261,6 +267,21 @@ class ValueState:
|
|
|
261
267
|
return bool((self.level1 & active) or (self.level2 & active) or (self.sensor_fail & active))
|
|
262
268
|
|
|
263
269
|
|
|
270
|
+
@dataclass(slots=True, frozen=True)
|
|
271
|
+
class HistoryFieldDescription:
|
|
272
|
+
"""One entry in the controller's history-snapshot field layout.
|
|
273
|
+
|
|
274
|
+
Describes where a single value's raw bytes sit within a ``HistoryRecord.data`` snapshot.
|
|
275
|
+
This is a **separate** layout from ``ValuesAll`` -- ``data_index`` here is the byte offset
|
|
276
|
+
within the 57-byte history snapshot, unrelated to ``value.data_index`` (which is the
|
|
277
|
+
offset within ``ValuesAll``/``ValueStatesAndDataAll``). See
|
|
278
|
+
[decode_history_snapshot][pycomap.configuration.decode_history_snapshot].
|
|
279
|
+
"""
|
|
280
|
+
|
|
281
|
+
data_index: int
|
|
282
|
+
value: ValueDescription
|
|
283
|
+
|
|
284
|
+
|
|
264
285
|
@dataclass(slots=True, frozen=True)
|
|
265
286
|
class ConfigurationTable:
|
|
266
287
|
"""Parsed ``ConfigurationTable`` (value and setpoint descriptions -- see module
|
|
@@ -269,6 +290,7 @@ class ConfigurationTable:
|
|
|
269
290
|
|
|
270
291
|
values: list[ValueDescription]
|
|
271
292
|
setpoints: list[SetpointDescription]
|
|
293
|
+
history_fields: list[HistoryFieldDescription]
|
|
272
294
|
|
|
273
295
|
|
|
274
296
|
def _as_int16(v: int) -> int:
|
|
@@ -330,6 +352,40 @@ def _parse_group_map(
|
|
|
330
352
|
return co_to_group
|
|
331
353
|
|
|
332
354
|
|
|
355
|
+
def _parse_history_description(
|
|
356
|
+
data: bytes, values: list[ValueDescription]
|
|
357
|
+
) -> list[HistoryFieldDescription]:
|
|
358
|
+
"""Parse the history-snapshot field layout section of the ``ConfigurationTable``.
|
|
359
|
+
|
|
360
|
+
Source: ``ConfigurationTableLoaderCommonExtensions.CommonLoadHistoryFromStream`` +
|
|
361
|
+
``ConfigurationTableLoaderIL3.LoadHistoryItemDescriptionFromStream`` in
|
|
362
|
+
``ComAp.Controller.dll`` (IL3, non-Format7 -- ``NumHistFieldsOffset=152``,
|
|
363
|
+
``IsNumHistFieldsByte=false``, ``AreAllAddresses32Bit=true``).
|
|
364
|
+
|
|
365
|
+
Layout at offset 152: ``uint16`` item count, ``uint16`` padding (read but discarded by
|
|
366
|
+
the non-byte-count branch), ``uint32`` absolute address of the item table. Each item is
|
|
367
|
+
one ``uint32`` LE: bits 0-10 = ``val_index`` (0-based index into ``values``, in the same
|
|
368
|
+
stream-load order used to build that list -- *not* a comm-object number or a
|
|
369
|
+
``ValuesAll`` ``data_index``), bits 11-19 = ``data_index`` (byte offset within the
|
|
370
|
+
history snapshot payload, stored directly per item), bits 20-31 = ``name_index`` (into
|
|
371
|
+
``NamesCategory.COMMON_NAMES`` -- not resolved here; each ``value.name`` already carries
|
|
372
|
+
a name).
|
|
373
|
+
"""
|
|
374
|
+
num_items = struct.unpack_from("<H", data, _NUM_HIST_FIELDS_OFFSET)[0]
|
|
375
|
+
table_addr = struct.unpack_from("<I", data, _NUM_HIST_FIELDS_OFFSET + 4)[0]
|
|
376
|
+
|
|
377
|
+
fields = []
|
|
378
|
+
offset = table_addr
|
|
379
|
+
for _ in range(num_items):
|
|
380
|
+
word = struct.unpack_from("<I", data, offset)[0]
|
|
381
|
+
offset += 4
|
|
382
|
+
val_index = get_bits(word, 0, 11)
|
|
383
|
+
data_index = get_bits(word, 11, 9)
|
|
384
|
+
if val_index < len(values):
|
|
385
|
+
fields.append(HistoryFieldDescription(data_index=data_index, value=values[val_index]))
|
|
386
|
+
return fields
|
|
387
|
+
|
|
388
|
+
|
|
333
389
|
def parse_configuration_table(data: bytes) -> ConfigurationTable:
|
|
334
390
|
"""Parse the value-description section of a raw ``ConfigurationTable`` blob."""
|
|
335
391
|
controller_type = data[_CONTROLLER_TYPE_OFFSET]
|
|
@@ -407,7 +463,9 @@ def parse_configuration_table(data: bytes) -> ConfigurationTable:
|
|
|
407
463
|
values = [dataclasses.replace(v, group=group_map.get(v.number)) for v in values]
|
|
408
464
|
setpoints = [dataclasses.replace(s, group=group_map.get(s.number)) for s in setpoints]
|
|
409
465
|
|
|
410
|
-
|
|
466
|
+
history_fields = _parse_history_description(data, values)
|
|
467
|
+
|
|
468
|
+
return ConfigurationTable(values=values, setpoints=setpoints, history_fields=history_fields)
|
|
411
469
|
|
|
412
470
|
|
|
413
471
|
def _parse_setpoints(
|
|
@@ -499,25 +557,28 @@ def decode_values_all(table: ConfigurationTable, data: bytes) -> dict[int, RawVa
|
|
|
499
557
|
def decode_history_snapshot(table: ConfigurationTable, snapshot: bytes) -> dict[int, RawValue]:
|
|
500
558
|
"""Decode the value snapshot from a ``HistoryRecord.data`` field.
|
|
501
559
|
|
|
502
|
-
Alarm/event history records carry a snapshot of
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
560
|
+
Alarm/event history records carry a fixed-format snapshot of a specific set of values
|
|
561
|
+
(RPM, voltages, frequencies, battery voltage, binary I/O, mode, ...), captured at the
|
|
562
|
+
moment the event occurred. This layout is defined by the controller's own
|
|
563
|
+
``HistoryDescriptionCollection`` (``table.history_fields`` -- a separate section of the
|
|
564
|
+
``ConfigurationTable``, unrelated to ``ValuesAll``'s per-value ``data_index``) rather than
|
|
565
|
+
being a truncated copy of ``ValuesAll``. Verified field-for-field against a live
|
|
566
|
+
controller's WebSupervisor history view.
|
|
567
|
+
|
|
568
|
+
Returns ``{number: decoded_value}`` for every history field that fits within
|
|
569
|
+
``len(snapshot)``, using the same type/decimal-places decoding as
|
|
570
|
+
[decode_values_all][pycomap.configuration.decode_values_all]. Returns an empty dict if
|
|
571
|
+
``snapshot`` is empty (text records).
|
|
512
572
|
"""
|
|
513
573
|
result: dict[int, RawValue] = {}
|
|
514
|
-
for
|
|
574
|
+
for field in table.history_fields:
|
|
575
|
+
value = field.value
|
|
515
576
|
if value.category is ValueCategory.ONE_TIME:
|
|
516
577
|
continue
|
|
517
|
-
end =
|
|
578
|
+
end = field.data_index + value.data_length
|
|
518
579
|
if end > len(snapshot):
|
|
519
580
|
continue
|
|
520
|
-
raw = snapshot[
|
|
581
|
+
raw = snapshot[field.data_index : end]
|
|
521
582
|
result[value.number] = decode_raw_value(value.data_type, raw, value.decimal_places)
|
|
522
583
|
return result
|
|
523
584
|
|
|
@@ -29,6 +29,7 @@ from __future__ import annotations
|
|
|
29
29
|
import datetime
|
|
30
30
|
import logging
|
|
31
31
|
import re
|
|
32
|
+
import struct
|
|
32
33
|
from collections.abc import Mapping
|
|
33
34
|
from types import MappingProxyType, TracebackType
|
|
34
35
|
from typing import Self
|
|
@@ -526,10 +527,29 @@ class Controller[TransportT: Transport]:
|
|
|
526
527
|
return parse_alarm_list(self._config_data, data)
|
|
527
528
|
|
|
528
529
|
async def read_history(self, count: int = 10) -> list[HistoryRecord]:
|
|
529
|
-
"""Read up to ``count`` of the most recent history records, newest first.
|
|
530
|
+
"""Read up to ``count`` of the most recent history records, newest first.
|
|
531
|
+
|
|
532
|
+
``count`` is transparently capped to the controller's own ring-buffer size —
|
|
533
|
+
read fresh each call from ``HistoryLength`` (C.O. 24538, number of currently valid
|
|
534
|
+
records — grows from 0 up to ``MaxHistoryRecords`` before the buffer first wraps,
|
|
535
|
+
then stays there) and ``MaxHistoryRecords`` (C.O. 24564, the buffer's fixed
|
|
536
|
+
capacity). Without this, requesting more records than the buffer holds would
|
|
537
|
+
silently wrap around and re-return the newest records a second time.
|
|
538
|
+
"""
|
|
530
539
|
if self._config_data is None:
|
|
531
540
|
raise ComApProtocolError("not connected — call connect() first")
|
|
541
|
+
|
|
542
|
+
history_length = struct.unpack(
|
|
543
|
+
"<H", await self._client.read_object(CommunicationObject.HISTORY_LENGTH)
|
|
544
|
+
)[0]
|
|
545
|
+
max_history_records = struct.unpack(
|
|
546
|
+
"<H", await self._client.read_object(CommunicationObject.MAX_HISTORY_RECORDS)
|
|
547
|
+
)[0]
|
|
548
|
+
count = min(count, history_length, max_history_records)
|
|
549
|
+
|
|
532
550
|
records: list[HistoryRecord] = []
|
|
551
|
+
if count <= 0:
|
|
552
|
+
return records
|
|
533
553
|
raw = await self._client.read_object(CommunicationObject.YOUNGEST_HISTORY_RECORD)
|
|
534
554
|
rec = parse_history_record(self._config_data, raw)
|
|
535
555
|
if rec:
|
|
@@ -546,10 +566,12 @@ class Controller[TransportT: Transport]:
|
|
|
546
566
|
def decode_history_snapshot(self, record: HistoryRecord) -> dict[int, Value]:
|
|
547
567
|
"""Decode the value snapshot embedded in an alarm ``HistoryRecord``.
|
|
548
568
|
|
|
549
|
-
Alarm/event records carry a snapshot of
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
569
|
+
Alarm/event records carry a fixed-format snapshot of a specific set of values (RPM,
|
|
570
|
+
voltages, frequencies, battery voltage, binary I/O, mode, ...) captured at the moment
|
|
571
|
+
of the event, per the controller's ``HistoryDescriptionCollection`` layout (see
|
|
572
|
+
[decode_history_snapshot][pycomap.configuration.decode_history_snapshot]). Returns
|
|
573
|
+
``{number: decoded_value}`` for every history field whose data fits within the
|
|
574
|
+
snapshot.
|
|
553
575
|
|
|
554
576
|
Returns an empty dict for text records (``record.is_text=True``) or records with
|
|
555
577
|
no embedded data.
|
|
@@ -82,12 +82,20 @@ class ComApClient[TransportT: Transport]:
|
|
|
82
82
|
await client.authenticate("0")
|
|
83
83
|
"""
|
|
84
84
|
|
|
85
|
-
def __init__(self, transport: TransportT) -> None:
|
|
85
|
+
def __init__(self, transport: TransportT, addr: int = 1) -> None:
|
|
86
86
|
"""
|
|
87
87
|
Args:
|
|
88
88
|
transport: Byte-stream transport to use (typically ``EthernetTransport``).
|
|
89
|
+
addr: Default controller unit address (``ControllerAddress`` setpoint, C.O.
|
|
90
|
+
24537; range 1-32, factory default ``1``) used for every ``read_object``/
|
|
91
|
+
``write_object`` call that doesn't override it explicitly. Only matters if
|
|
92
|
+
the target controller's ``ControllerAddress`` has been changed from the
|
|
93
|
+
default -- e.g. multiple units addressed through one gateway/party-line,
|
|
94
|
+
the same address you'd set in InteliMonitor/InteliConfig's connection
|
|
95
|
+
dialog.
|
|
89
96
|
"""
|
|
90
97
|
self._transport = transport
|
|
98
|
+
self._addr = addr
|
|
91
99
|
self._identifier = 0
|
|
92
100
|
self._mode = _Mode.NONE
|
|
93
101
|
self._cipher: ChainedAesCbc | None = None
|
|
@@ -215,12 +223,13 @@ class ComApClient[TransportT: Transport]:
|
|
|
215
223
|
|
|
216
224
|
# -- communication objects -------------------------------------------------
|
|
217
225
|
|
|
218
|
-
async def read_object(self, comm_obj: int, addr: int =
|
|
226
|
+
async def read_object(self, comm_obj: int, addr: int | None = None) -> bytes:
|
|
219
227
|
"""Read a communication object, handling ``SendToBlock`` continuation transparently.
|
|
220
228
|
|
|
221
229
|
Args:
|
|
222
230
|
comm_obj: Communication object number (C.O.).
|
|
223
|
-
addr: Controller unit address;
|
|
231
|
+
addr: Controller unit address; defaults to the address passed to
|
|
232
|
+
``ComApClient.__init__`` (``1`` unless overridden there).
|
|
224
233
|
|
|
225
234
|
Returns:
|
|
226
235
|
Raw payload bytes.
|
|
@@ -229,6 +238,7 @@ class ComApClient[TransportT: Transport]:
|
|
|
229
238
|
ComApControllerError: If the controller responds with an error code.
|
|
230
239
|
ComApProtocolError: If an unexpected message operation is received.
|
|
231
240
|
"""
|
|
241
|
+
addr = self._addr if addr is None else addr
|
|
232
242
|
ident = self._next_identifier()
|
|
233
243
|
await self._write_message(Operation.SEND_ME, addr, comm_obj, b"", ident)
|
|
234
244
|
|
|
@@ -251,13 +261,14 @@ class ComApClient[TransportT: Transport]:
|
|
|
251
261
|
f"unexpected operation {message.op!r} while reading {comm_obj}"
|
|
252
262
|
)
|
|
253
263
|
|
|
254
|
-
async def write_object(self, comm_obj: int, data: bytes, addr: int =
|
|
264
|
+
async def write_object(self, comm_obj: int, data: bytes, addr: int | None = None) -> bytes:
|
|
255
265
|
"""Write a communication object.
|
|
256
266
|
|
|
257
267
|
Args:
|
|
258
268
|
comm_obj: Communication object number (C.O.).
|
|
259
269
|
data: Raw payload bytes to write.
|
|
260
|
-
addr: Controller unit address;
|
|
270
|
+
addr: Controller unit address; defaults to the address passed to
|
|
271
|
+
``ComApClient.__init__`` (``1`` unless overridden there).
|
|
261
272
|
|
|
262
273
|
Returns:
|
|
263
274
|
Any data carried back on the ``NEXT`` acknowledgment (usually empty).
|
|
@@ -265,6 +276,7 @@ class ComApClient[TransportT: Transport]:
|
|
|
265
276
|
Raises:
|
|
266
277
|
ComApControllerError: If the controller responds with an error code.
|
|
267
278
|
"""
|
|
279
|
+
addr = self._addr if addr is None else addr
|
|
268
280
|
ident = self._next_identifier()
|
|
269
281
|
await self._write_message(Operation.SEND_TO, addr, comm_obj, data, ident)
|
|
270
282
|
message = await self._read_message()
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|