mapcan 0.21.0__py3-none-any.whl

mapcan/__init__.py

@@ -0,0 +1,9 @@
+"""mapcan: a YAML signal map as the single source of truth."""
+
+__version__ = "0.21.0"
+
+from .loader import load, loads  # noqa: E402
+from .model import MapCan  # noqa: E402
+from .validate import check, validate_file, validate_text  # noqa: E402
+
+__all__ = ["MapCan", "check", "load", "loads", "validate_file", "validate_text", "__version__"]

mapcan/bits.py

@@ -0,0 +1,85 @@
+"""Bit layout of signals and packing/unpacking of the payload.
+
+Positions are in lsb0 numbering: absolute bit ``p`` is bit ``p % 8`` of byte ``p // 8``.
+``start_bit`` of a signal is the position of its least significant bit (LSB).
+
+* little-endian: the value takes bits ``start .. start+len-1`` in a row;
+* big-endian (Motorola): from the LSB the bits go up to the end of the byte, then
+  continue at bit 0 of the *previous* byte.
+"""
+
+from __future__ import annotations
+
+
+def chunks(start: int, length: int, big_endian: bool) -> list[tuple[int, int, int]]:
+    """Split a field into pieces within bytes: (byte, shift in the byte, number of bits).
+
+    The pieces go from the low bits of the value to the high ones. A byte can be
+    negative if a big-endian field sticks out before the start of the frame.
+    """
+    out = []
+    pos, left = start, length
+    while left > 0:
+        byte, shift = divmod(pos, 8)
+        n = min(8 - shift, left)
+        out.append((byte, shift, n))
+        left -= n
+        pos = (byte - 1) * 8 if big_endian else (byte + 1) * 8
+    return out
+
+
+def occupied_bits(start: int, length: int, big_endian: bool) -> list[int]:
+    """Absolute positions of the field's bits, from the value's least significant bit to the most significant."""
+    bits = []
+    for byte, shift, n in chunks(start, length, big_endian):
+        base = byte * 8 + shift
+        bits.extend(range(base, base + n))
+    return bits
+
+
+def byte_span(start: int, length: int, big_endian: bool) -> tuple[int, int]:
+    """First and last byte of the field (ascending)."""
+    bs = [c[0] for c in chunks(start, length, big_endian)]
+    return min(bs), max(bs)
+
+
+def msb_position(start: int, length: int, big_endian: bool) -> int:
+    """Position of the value's most significant bit (needed for DBC/Motorola)."""
+    return occupied_bits(start, length, big_endian)[-1]
+
+
+def lsb_from_msb(msb: int, length: int) -> int:
+    """start_bit (LSB position) of a big-endian field from the position of its MSB, as in DBC/Motorola.
+
+    From the MSB the value goes down the byte, and from bit 0 on to bit 7 of the *next* byte."""
+    pos = msb
+    for _ in range(length - 1):
+        pos = pos + 15 if pos % 8 == 0 else pos - 1
+    return pos
+
+
+def extract(data: bytes, start: int, length: int, big_endian: bool, signed: bool = False) -> int:
+    value, i = 0, 0
+    for byte, shift, n in chunks(start, length, big_endian):
+        value |= ((data[byte] >> shift) & ((1 << n) - 1)) << i
+        i += n
+    if signed and value & (1 << (length - 1)):
+        value -= 1 << length
+    return value
+
+
+def insert(buf: bytearray, value: int, start: int, length: int, big_endian: bool) -> None:
+    value &= (1 << length) - 1
+    i = 0
+    for byte, shift, n in chunks(start, length, big_endian):
+        mask = ((1 << n) - 1) << shift
+        buf[byte] = (buf[byte] & ~mask & 0xFF) | (((value >> i) << shift) & mask)
+        i += n
+
+
+def raw_range(length: int, signed: bool, code: str | None = None) -> tuple[int, int]:
+    """Range of the raw value; in ones' complement and sign-magnitude it is symmetric (zero has two forms)."""
+    if signed:
+        lo = -(1 << (length - 1)) + (code in ("ones_complement", "sign_magnitude"))
+        return lo, (1 << (length - 1)) - 1
+    return 0, (1 << length) - 1

mapcan/canopen.py

@@ -0,0 +1,64 @@
+"""CANopen function codes (CiA 301, predefined connection set)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class FunctionCode:
+    type: str
+    base: int
+    per_node: bool          # ID = base + node_id
+    direction: str | None   # default direction relative to the device
+    label_ru: str
+    label_en: str
+    purpose_ru: str
+    purpose_en: str
+
+
+FUNCTION_CODES: dict[str, FunctionCode] = {
+    fc.type: fc
+    for fc in [
+        FunctionCode("nmt", 0x000, False, "rx", "NMT", "NMT", "управление сетью", "network management"),
+        FunctionCode("sync", 0x080, False, None, "SYNC", "SYNC", "синхронизация", "synchronization"),
+        FunctionCode("emcy", 0x080, True, "tx", "EMCY", "EMCY", "события", "emergency"),
+        FunctionCode("time", 0x100, False, None, "TIME", "TIME", "дата и время", "time stamp"),
+        FunctionCode("pdo_tx1", 0x180, True, "tx", "PDO TX 1", "TPDO1", "состояния", "states"),
+        FunctionCode("pdo_rx1", 0x200, True, "rx", "PDO RX 1", "RPDO1", "установки", "settings"),
+        FunctionCode("pdo_tx2", 0x280, True, "tx", "PDO TX 2", "TPDO2", "данные", "data"),
+        FunctionCode("pdo_rx2", 0x300, True, "rx", "PDO RX 2", "RPDO2", "", ""),
+        FunctionCode("pdo_tx3", 0x380, True, "tx", "PDO TX 3", "TPDO3", "", ""),
+        FunctionCode("pdo_rx3", 0x400, True, "rx", "PDO RX 3", "RPDO3", "", ""),
+        FunctionCode("pdo_tx4", 0x480, True, "tx", "PDO TX 4", "TPDO4", "", ""),
+        FunctionCode("pdo_rx4", 0x500, True, "rx", "PDO RX 4", "RPDO4", "", ""),
+        FunctionCode("sdo_tx", 0x580, True, "tx", "SDO TX", "SDO TX", "настройка (ответ)", "SDO response"),
+        FunctionCode("sdo_rx", 0x600, True, "rx", "SDO RX", "SDO RX", "настройка (приказ)", "SDO request"),
+        FunctionCode("heartbeat", 0x700, True, "tx", "Heartbeat", "Heartbeat", "контроль связи", "node guarding"),
+    ]
+}
+
+# Allowed lengths of service frames by CiA 301; a frame without an explicit length gets the smallest.
+CANOPEN_DLC: dict[str, set[int]] = {
+    "nmt": {2}, "sync": {0, 1}, "time": {6}, "heartbeat": {1}, "sdo_tx": {8}, "sdo_rx": {8},
+}
+
+# Order of the rows in the addressing table.
+ADDRESSING_ORDER = list(FUNCTION_CODES)
+
+
+def compute_id(frame_type: str, node_id: int | None) -> int | None:
+    """CAN ID from the function code and node_id; None if it cannot be computed."""
+    fc = FUNCTION_CODES.get(frame_type)
+    if fc is None:
+        return None
+    if not fc.per_node:
+        return fc.base
+    if node_id is None:
+        return None
+    return fc.base + node_id
+
+
+def default_direction(frame_type: str) -> str | None:
+    fc = FUNCTION_CODES.get(frame_type)
+    return fc.direction if fc else None