pycomap 2.1.1__tar.gz → 2.2.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.2.0}/PKG-INFO +1 -1
- {pycomap-2.1.1 → pycomap-2.2.0}/pyproject.toml +1 -1
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/configuration.py +75 -14
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/controller.py +27 -5
- {pycomap-2.1.1 → pycomap-2.2.0}/README.md +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/__init__.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/alarms.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/datatypes.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/discovery.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/exceptions.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/history.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/protocol/__init__.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/protocol/client.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/protocol/commands.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/protocol/crc.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/protocol/crypto.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/protocol/framing.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/protocol/objects.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.0}/src/pycomap/protocol/transport.py +0 -0
- {pycomap-2.1.1 → pycomap-2.2.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.2.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.
|
|
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
|
|
File without changes
|