pycomap 2.1.0__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.0 → pycomap-2.2.0}/PKG-INFO +2 -2
- {pycomap-2.1.0 → pycomap-2.2.0}/README.md +1 -1
- {pycomap-2.1.0 → pycomap-2.2.0}/pyproject.toml +5 -4
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/configuration.py +75 -14
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/controller.py +73 -15
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/__init__.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/alarms.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/datatypes.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/discovery.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/exceptions.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/history.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/protocol/__init__.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/protocol/client.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/protocol/commands.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/protocol/crc.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/protocol/crypto.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/protocol/framing.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/protocol/objects.py +0 -0
- {pycomap-2.1.0 → pycomap-2.2.0}/src/pycomap/protocol/transport.py +0 -0
- {pycomap-2.1.0 → 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>
|
|
@@ -50,7 +50,7 @@ async with Controller(
|
|
|
50
50
|
await ctrl.set_setpoint("Summer Time Mode", "Winter") # STRING_LIST by label
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference. `just docs-serve` to browse locally.
|
|
53
|
+
See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference, built with [Zensical](https://zensical.org/). `just docs-serve` to browse locally.
|
|
54
54
|
|
|
55
55
|
## Development
|
|
56
56
|
|
|
@@ -23,7 +23,7 @@ async with Controller(
|
|
|
23
23
|
await ctrl.set_setpoint("Summer Time Mode", "Winter") # STRING_LIST by label
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
-
See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference. `just docs-serve` to browse locally.
|
|
26
|
+
See the [API docs](https://igor-panteleev.github.io/pycomap/) for full reference, built with [Zensical](https://zensical.org/). `just docs-serve` to browse locally.
|
|
27
27
|
|
|
28
28
|
## Development
|
|
29
29
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "pycomap"
|
|
3
|
-
version = "2.
|
|
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"
|
|
@@ -38,10 +38,11 @@ build-backend = "uv_build"
|
|
|
38
38
|
|
|
39
39
|
[dependency-groups]
|
|
40
40
|
dev = [
|
|
41
|
+
"configargparse>=1.7.5",
|
|
41
42
|
"ifaddr>=0.2.0",
|
|
42
|
-
"
|
|
43
|
-
"
|
|
44
|
-
"mkdocstrings
|
|
43
|
+
"python-dotenv>=1.2.2",
|
|
44
|
+
"zensical>=0.0.50",
|
|
45
|
+
"mkdocstrings-python>=1.0",
|
|
45
46
|
"pre-commit>=4.6.0",
|
|
46
47
|
"pytest>=8",
|
|
47
48
|
"pytest-asyncio>=0.24",
|
|
@@ -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
|
|
@@ -319,6 +320,51 @@ class Controller[TransportT: Transport]:
|
|
|
319
320
|
except KeyError:
|
|
320
321
|
raise KeyError(f"no setpoint named {name_or_number!r}") from None
|
|
321
322
|
|
|
323
|
+
def _string_list_options(
|
|
324
|
+
self, desc: ValueDescription | SetpointDescription
|
|
325
|
+
) -> list[tuple[int, str]]:
|
|
326
|
+
"""Shared ``STRING_LIST`` option lookup for
|
|
327
|
+
[value_options][pycomap.Controller.value_options] and
|
|
328
|
+
[setpoint_options][pycomap.Controller.setpoint_options].
|
|
329
|
+
|
|
330
|
+
Options are stored in ``CommonNames`` at indices ``[low_limit .. high_limit]``.
|
|
331
|
+
"""
|
|
332
|
+
if desc.data_type is not DataType.STRING_LIST:
|
|
333
|
+
raise ComApProtocolError(
|
|
334
|
+
f"{desc.name!r} is DataType.{desc.data_type.name}, not STRING_LIST"
|
|
335
|
+
)
|
|
336
|
+
return [
|
|
337
|
+
(wire_value, self._common_names[desc.low_limit + wire_value])
|
|
338
|
+
for wire_value in range(desc.high_limit - desc.low_limit + 1)
|
|
339
|
+
if desc.low_limit + wire_value < len(self._common_names)
|
|
340
|
+
]
|
|
341
|
+
|
|
342
|
+
def value_options(self, name_or_number: str | int) -> list[tuple[int, str]]:
|
|
343
|
+
"""Return the available options for a ``STRING_LIST`` value.
|
|
344
|
+
|
|
345
|
+
Options are stored in ``CommonNames`` at indices ``[low_limit .. high_limit]``.
|
|
346
|
+
The wire value (0-based) is what the controller sends on the wire and what
|
|
347
|
+
[value_label][pycomap.Controller.value_label] expects; the label is the string
|
|
348
|
+
shown on the front panel and in InteliConfig. Note that
|
|
349
|
+
[read_values][pycomap.Controller.read_values] resolves ``STRING_LIST`` values to
|
|
350
|
+
their label automatically — this method is for enumerating all possible options
|
|
351
|
+
up front (e.g. to build a legend or validate against known states).
|
|
352
|
+
|
|
353
|
+
Args:
|
|
354
|
+
name_or_number: Value name or comm object number.
|
|
355
|
+
|
|
356
|
+
Returns:
|
|
357
|
+
``[(wire_value, label), ...]`` ordered by wire value.
|
|
358
|
+
|
|
359
|
+
Raises:
|
|
360
|
+
ComApProtocolError: If the value is not ``STRING_LIST`` type.
|
|
361
|
+
|
|
362
|
+
Examples:
|
|
363
|
+
>>> ctrl.value_options("Engine State")
|
|
364
|
+
[(0, 'Ready'), (1, 'Prestart'), (2, 'Cranking'), ...]
|
|
365
|
+
"""
|
|
366
|
+
return self._string_list_options(self.value_info(name_or_number))
|
|
367
|
+
|
|
322
368
|
def setpoint_options(self, name_or_number: str | int) -> list[tuple[int, str]]:
|
|
323
369
|
"""Return the available options for a ``STRING_LIST`` setpoint.
|
|
324
370
|
|
|
@@ -340,16 +386,7 @@ class Controller[TransportT: Transport]:
|
|
|
340
386
|
>>> ctrl.setpoint_options("Summer Time Mode")
|
|
341
387
|
[(0, 'Disabled'), (1, 'Winter'), (2, 'Summer'), (3, 'Winter-S'), (4, 'Summer-S')]
|
|
342
388
|
"""
|
|
343
|
-
|
|
344
|
-
if desc.data_type is not DataType.STRING_LIST:
|
|
345
|
-
raise ComApProtocolError(
|
|
346
|
-
f"setpoint {desc.name!r} is DataType.{desc.data_type.name}, not STRING_LIST"
|
|
347
|
-
)
|
|
348
|
-
return [
|
|
349
|
-
(wire_value, self._common_names[desc.low_limit + wire_value])
|
|
350
|
-
for wire_value in range(desc.high_limit - desc.low_limit + 1)
|
|
351
|
-
if desc.low_limit + wire_value < len(self._common_names)
|
|
352
|
-
]
|
|
389
|
+
return self._string_list_options(self.setpoint_info(name_or_number))
|
|
353
390
|
|
|
354
391
|
def value_label(self, name_or_number: str | int, wire_value: int) -> str:
|
|
355
392
|
"""Return the display label for a ``STRING_LIST`` value's wire integer.
|
|
@@ -490,10 +527,29 @@ class Controller[TransportT: Transport]:
|
|
|
490
527
|
return parse_alarm_list(self._config_data, data)
|
|
491
528
|
|
|
492
529
|
async def read_history(self, count: int = 10) -> list[HistoryRecord]:
|
|
493
|
-
"""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
|
+
"""
|
|
494
539
|
if self._config_data is None:
|
|
495
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
|
+
|
|
496
550
|
records: list[HistoryRecord] = []
|
|
551
|
+
if count <= 0:
|
|
552
|
+
return records
|
|
497
553
|
raw = await self._client.read_object(CommunicationObject.YOUNGEST_HISTORY_RECORD)
|
|
498
554
|
rec = parse_history_record(self._config_data, raw)
|
|
499
555
|
if rec:
|
|
@@ -510,10 +566,12 @@ class Controller[TransportT: Transport]:
|
|
|
510
566
|
def decode_history_snapshot(self, record: HistoryRecord) -> dict[int, Value]:
|
|
511
567
|
"""Decode the value snapshot embedded in an alarm ``HistoryRecord``.
|
|
512
568
|
|
|
513
|
-
Alarm/event records carry a snapshot of
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
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.
|
|
517
575
|
|
|
518
576
|
Returns an empty dict for text records (``record.is_text=True``) or records with
|
|
519
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
|