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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pycomap
3
- Version: 2.1.1
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>
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pycomap"
3
- version = "2.1.1"
3
+ version = "2.2.0"
4
4
  description = "Async Python client for ComAp controllers: LAN discovery and the native ECDH/AES-encrypted control protocol"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -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
- return ConfigurationTable(values=values, setpoints=setpoints)
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 the first N bytes of the
503
- ``ValuesAll`` blob captured at the moment the event occurred. The layout is
504
- identical to ``ValuesAll`` (each value at its ``data_index`` byte offset) but
505
- truncated to ``len(snapshot)`` — values whose data would extend beyond the
506
- snapshot are silently omitted.
507
-
508
- Returns ``{number: decoded_value}`` for every value that fits, using the same
509
- type/decimal-places decoding as
510
- [decode_values_all][pycomap.configuration.decode_values_all]. ``ONE_TIME`` values
511
- are never included. Returns an empty dict if ``snapshot`` is empty (text records).
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 value in table.values:
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 = value.data_index + value.data_length
578
+ end = field.data_index + value.data_length
518
579
  if end > len(snapshot):
519
580
  continue
520
- raw = snapshot[value.data_index : end]
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 the ``ValuesAll`` blob captured at the
550
- moment of the event. Returns ``{number: decoded_value}`` for every value whose
551
- data fits within the snapshot; the set of values is typically the first ~31 entries
552
- from the controller's value table (those with small ``data_index`` values).
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