masterk-cnet 1.0.0__py3-none-any.whl

masterk_cnet/__init__.py

@@ -0,0 +1,38 @@
+"""K200S CNET communication library.
+
+Example:
+    >>> from masterk_cnet import CnetConfig
+    >>> CnetConfig(station=1).station
+    1
+"""
+
+from .client import CnetClient
+from .config import CnetConfig
+from .errors import (
+    ChecksumError,
+    CnetError,
+    CnetNakError,
+    CnetTimeoutError,
+    MalformedFrameError,
+    MalformedPayloadError,
+    UnexpectedResponseError,
+)
+from .serial_transport import SerialTransport
+from .socket_transport import SocketTransport
+from .transport import FakeTransport, Transport
+
+__all__ = [
+    "ChecksumError",
+    "CnetClient",
+    "CnetConfig",
+    "CnetError",
+    "CnetNakError",
+    "CnetTimeoutError",
+    "FakeTransport",
+    "MalformedFrameError",
+    "MalformedPayloadError",
+    "SerialTransport",
+    "SocketTransport",
+    "Transport",
+    "UnexpectedResponseError",
+]

masterk_cnet/address.py

@@ -0,0 +1,203 @@
+"""Device address parsing and validation.
+
+Example:
+    >>> from masterk_cnet.address import parse_address
+    >>> parse_address("%MW0001").word_index
+    1
+"""
+
+from __future__ import annotations
+
+import re
+
+from .models import DataType, DeviceAddress, DeviceArea
+
+ADDRESS_RE = re.compile(r"^%([A-Za-z])([A-Za-z])([0-9A-Fa-f]+)$")
+MIN_DEVICE_DIGITS = 2
+MAX_DEVICE_DIGITS = 8
+
+WORD_RANGES: dict[DeviceArea, tuple[int, int]] = {
+    DeviceArea.P: (0, 31),
+    DeviceArea.M: (0, 191),
+    DeviceArea.K: (0, 31),
+    DeviceArea.L: (0, 63),
+    DeviceArea.F: (0, 63),
+    DeviceArea.S: (0, 99),
+    DeviceArea.D: (0, 4999),
+    DeviceArea.T: (0, 255),
+    DeviceArea.C: (0, 255),
+}
+
+BIT_WORD_RANGES: dict[DeviceArea, tuple[int, int]] = {
+    DeviceArea.P: (0, 31),
+    DeviceArea.M: (0, 191),
+    DeviceArea.K: (0, 31),
+    DeviceArea.L: (0, 63),
+    DeviceArea.F: (0, 63),
+}
+
+BIT_POINT_RANGES: dict[DeviceArea, tuple[int, int]] = {
+    DeviceArea.T: (0, 255),
+    DeviceArea.C: (0, 255),
+}
+
+
+def parse_address(address: str) -> DeviceAddress:
+    """Parse a CNET device address.
+
+    Args:
+        address: Device address text such as ``"%MW0001"`` or ``"%MX001F"``.
+
+    Returns:
+        Parsed device address.
+
+    Raises:
+        ValueError: If the address format, area, type, or range is invalid.
+
+    Example:
+        >>> parse_address("%MW0001").to_protocol_string()
+        '%MW0001'
+    """
+    match = ADDRESS_RE.match(address.strip())
+    if not match:
+        raise ValueError(f"invalid device address format: {address!r}")
+
+    area_text, type_text, digits = match.groups()
+    try:
+        # Operators often type area/type letters in mixed case; normalize those
+        # structural fields while leaving the device digits available for
+        # stricter checks below.
+        area = DeviceArea(area_text.upper())
+        data_type = DataType(type_text.upper())
+    except ValueError as exc:
+        raise ValueError(f"unsupported device address: {address!r}") from exc
+
+    if data_type is DataType.WORD:
+        return _parse_word_address(address, area, digits)
+    return _parse_bit_address(address, area, digits)
+
+
+def ensure_readable(address: DeviceAddress) -> None:
+    """Validate that an address can be read.
+
+    Args:
+        address: Parsed device address to validate.
+
+    Raises:
+        ValueError: If the address is not readable.
+
+    Example:
+        >>> ensure_readable(parse_address("%MW0001"))
+    """
+    # Every supported area in this CNET subset is readable.
+    _ = address
+
+
+def ensure_writable(address: DeviceAddress) -> None:
+    """Validate that an address can be written.
+
+    Args:
+        address: Parsed device address to validate.
+
+    Raises:
+        ValueError: If the address belongs to a read-only area.
+
+    Example:
+        >>> ensure_writable(parse_address("%MW0001"))
+    """
+    # The F area exposes flags/status and is treated as read-only by the PLC.
+    # Reject it before frame construction so callers get a local validation
+    # error instead of a device-side NAK.
+    if address.area is DeviceArea.F:
+        raise ValueError("F area is read-only")
+
+
+def ensure_word(address: DeviceAddress) -> None:
+    """Validate that an address uses Word data.
+
+    Args:
+        address: Parsed device address to validate.
+
+    Raises:
+        ValueError: If the address is not a Word address.
+
+    Example:
+        >>> ensure_word(parse_address("%MW0001"))
+    """
+    if address.data_type is not DataType.WORD:
+        raise ValueError("operation requires a Word address")
+
+
+def ensure_same_data_type(addresses: list[DeviceAddress]) -> None:
+    """Validate that all addresses use the same data type.
+
+    Args:
+        addresses: Parsed device addresses to compare.
+
+    Raises:
+        ValueError: If the list is empty or mixes Bit and Word addresses.
+
+    Example:
+        >>> ensure_same_data_type([parse_address("%MW0001"), parse_address("%MW0002")])
+    """
+    if not addresses:
+        raise ValueError("at least one address is required")
+    first_type = addresses[0].data_type
+    if any(address.data_type is not first_type for address in addresses):
+        raise ValueError("all addresses in one block command must use the same data type")
+
+
+def _parse_word_address(raw: str, area: DeviceArea, digits: str) -> DeviceAddress:
+    if area not in WORD_RANGES:
+        raise ValueError(f"{area.value} area does not support Word access")
+    _check_digit_count(digits, raw)
+    if not digits.isdecimal():
+        raise ValueError("Word address digits must be decimal")
+
+    word_index = int(digits, 10)
+    _check_range(word_index, WORD_RANGES[area], raw)
+    return DeviceAddress(area, DataType.WORD, word_index, None, digits, raw)
+
+
+def _parse_bit_address(raw: str, area: DeviceArea, digits: str) -> DeviceAddress:
+    _check_digit_count(digits, raw)
+    if area in BIT_POINT_RANGES:
+        # Timer and counter bit addresses are point-based in this protocol
+        # subset, not word-plus-nibble like P/M/K/L/F bit addresses.
+        if not digits.isdecimal():
+            raise ValueError("T/C bit address digits must be decimal")
+        point_index = int(digits, 10)
+        _check_range(point_index, BIT_POINT_RANGES[area], raw)
+        return DeviceAddress(area, DataType.BIT, point_index, None, digits, raw)
+
+    if area not in BIT_WORD_RANGES:
+        raise ValueError(f"{area.value} area does not support Bit access")
+    if len(digits) < 2:
+        raise ValueError("Bit address must include word digits and a bit nibble")
+
+    word_digits = digits[:-1]
+    bit_digit = digits[-1]
+    if not word_digits.isdecimal():
+        raise ValueError("Bit address word digits must be decimal")
+    # Hex bit nibbles are kept uppercase because the Master-K notation examples
+    # use uppercase A-F, and silently normalizing a lowercase nibble could hide
+    # a user input mistake in addresses that are later echoed in diagnostics.
+    if bit_digit.isalpha() and not bit_digit.isupper():
+        raise ValueError("Bit address nibble must be uppercase")
+    bit_index = int(bit_digit, 16)
+    word_index = int(word_digits, 10)
+    _check_range(word_index, BIT_WORD_RANGES[area], raw)
+    return DeviceAddress(area, DataType.BIT, word_index, bit_index, digits.upper(), raw)
+
+
+def _check_range(value: int, allowed: tuple[int, int], raw: str) -> None:
+    start, end = allowed
+    if not start <= value <= end:
+        raise ValueError(f"address out of range for {raw!r}: {value}")
+
+
+def _check_digit_count(digits: str, raw: str) -> None:
+    if not MIN_DEVICE_DIGITS <= len(digits) <= MAX_DEVICE_DIGITS:
+        raise ValueError(
+            f"device number must be {MIN_DEVICE_DIGITS} to {MAX_DEVICE_DIGITS} digits: {raw!r}"
+        )

masterk_cnet/ascii_hex.py

@@ -0,0 +1,185 @@
+"""ASCII Hex conversion helpers for CNET frames.
+
+Example:
+    >>> from masterk_cnet.ascii_hex import encode_word
+    >>> encode_word(4660)
+    b'1234'
+"""
+
+from __future__ import annotations
+
+HEX_CHARS = set("0123456789ABCDEFabcdef")
+
+
+def int_to_ascii_hex(value: int, width: int) -> bytes:
+    """Encode an integer as zero-padded uppercase ASCII hex.
+
+    Args:
+        value: Non-negative integer to encode.
+        width: Number of ASCII hex digits to produce.
+
+    Returns:
+        Uppercase ASCII hex bytes.
+
+    Raises:
+        ValueError: If width is not positive, value is negative, or value does
+            not fit in the requested width.
+
+    Example:
+        >>> int_to_ascii_hex(10, 2)
+        b'0A'
+    """
+    if width <= 0:
+        raise ValueError("width must be positive")
+    if value < 0:
+        raise ValueError("value must be non-negative")
+    max_value = (16**width) - 1
+    if value > max_value:
+        raise ValueError(f"value {value} does not fit in {width} hex digits")
+    return f"{value:0{width}X}".encode("ascii")
+
+
+def ascii_hex_to_int(data: bytes | str) -> int:
+    """Decode ASCII hex bytes or text to an integer.
+
+    Args:
+        data: ASCII hex bytes or text.
+
+    Returns:
+        Decoded integer value.
+
+    Raises:
+        ValueError: If data is empty or contains non-hex characters.
+
+    Example:
+        >>> ascii_hex_to_int(b'0A')
+        10
+    """
+    text = data.decode("ascii") if isinstance(data, bytes) else data
+    if not text:
+        raise ValueError("hex data is empty")
+    if any(char not in HEX_CHARS for char in text):
+        raise ValueError(f"invalid hex data: {text!r}")
+    return int(text, 16)
+
+
+def encode_byte(value: int) -> bytes:
+    """Encode an integer as a one-byte ASCII hex field.
+
+    Args:
+        value: Integer in the byte range.
+
+    Returns:
+        Two uppercase ASCII hex bytes.
+
+    Raises:
+        ValueError: If value cannot fit in one byte.
+
+    Example:
+        >>> encode_byte(255)
+        b'FF'
+    """
+    return int_to_ascii_hex(value, 2)
+
+
+def encode_word(value: int) -> bytes:
+    """Encode an integer as a one-word ASCII hex field.
+
+    Args:
+        value: Integer in the word range.
+
+    Returns:
+        Four uppercase ASCII hex bytes.
+
+    Raises:
+        ValueError: If value cannot fit in one word.
+
+    Example:
+        >>> encode_word(4660)
+        b'1234'
+    """
+    return int_to_ascii_hex(value, 4)
+
+
+def decode_byte(data: bytes | str) -> int:
+    """Decode a one-byte ASCII hex field.
+
+    Args:
+        data: Two ASCII hex characters as bytes or text.
+
+    Returns:
+        Decoded byte value.
+
+    Raises:
+        ValueError: If data is not exactly two ASCII hex characters.
+
+    Example:
+        >>> decode_byte('FF')
+        255
+    """
+    text = data.decode("ascii") if isinstance(data, bytes) else data
+    if len(text) != 2:
+        raise ValueError("byte data must be 2 ASCII hex characters")
+    return ascii_hex_to_int(text)
+
+
+def decode_word(data: bytes | str) -> int:
+    """Decode a one-word ASCII hex field.
+
+    Args:
+        data: Four ASCII hex characters as bytes or text.
+
+    Returns:
+        Decoded word value.
+
+    Raises:
+        ValueError: If data is not exactly four ASCII hex characters.
+
+    Example:
+        >>> decode_word('1234')
+        4660
+    """
+    text = data.decode("ascii") if isinstance(data, bytes) else data
+    if len(text) != 4:
+        raise ValueError("word data must be 4 ASCII hex characters")
+    return ascii_hex_to_int(text)
+
+
+def decode_ascii_hex_bytes(data: bytes | str) -> bytes:
+    """Decode ASCII hex text into raw bytes.
+
+    Args:
+        data: Even-length ASCII hex bytes or text.
+
+    Returns:
+        Raw bytes represented by the input.
+
+    Raises:
+        ValueError: If data has an odd length or contains non-hex characters.
+
+    Example:
+        >>> decode_ascii_hex_bytes('4142')
+        b'AB'
+    """
+    text = data.decode("ascii") if isinstance(data, bytes) else data
+    if len(text) % 2 != 0:
+        raise ValueError("hex byte data must have an even length")
+    if any(char not in HEX_CHARS for char in text):
+        raise ValueError(f"invalid hex data: {text!r}")
+    return bytes.fromhex(text)
+
+
+def spaced_hex(data: bytes) -> str:
+    """Format bytes as uppercase hex pairs separated by spaces.
+
+    Args:
+        data: Raw bytes to format.
+
+    Returns:
+        Space-separated uppercase hex text.
+
+    Example:
+        >>> spaced_hex(b'\\x05\\x06')
+        '05 06'
+    """
+    return " ".join(f"{byte:02X}" for byte in data)

masterk_cnet/bcc.py

@@ -0,0 +1,44 @@
+"""BCC calculation for CNET frames.
+
+Example:
+    >>> from masterk_cnet.bcc import calculate_bcc
+    >>> calculate_bcc(b'ABC')
+    b'C6'
+"""
+
+from __future__ import annotations
+
+from .ascii_hex import encode_byte
+
+
+def calculate_bcc(data: bytes) -> bytes:
+    """Calculate the CNET BCC for a byte range.
+
+    Args:
+        data: Bytes included in the checksum calculation.
+
+    Returns:
+        Two uppercase ASCII hex bytes containing the low byte of the sum.
+
+    Example:
+        >>> calculate_bcc(b'ABC')
+        b'C6'
+    """
+    return encode_byte(sum(data) & 0xFF)
+
+
+def verify_bcc(data: bytes, expected: bytes) -> bool:
+    """Compare a calculated CNET BCC with an expected value.
+
+    Args:
+        data: Bytes included in the checksum calculation.
+        expected: Expected ASCII hex BCC bytes.
+
+    Returns:
+        True when the calculated checksum matches the expected value.
+
+    Example:
+        >>> verify_bcc(b'ABC', b'C6')
+        True
+    """
+    return calculate_bcc(data).upper() == expected.upper()