interface-test-kit 0.1.0__py3-none-any.whl

interface_test_kit/__init__.py

@@ -0,0 +1,3 @@
+"""interface-test-kit: operator-guided interface test for Linux embedded PCs."""
+
+__version__ = "0.1.0"

interface_test_kit/checks/__init__.py

@@ -0,0 +1,47 @@
+"""Registry of step types. Each check module registers itself on import."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from ..context import Context
+    from ..model import Attempt
+    from ..ui import UI
+
+
+def _no_preflight(config: Any, ctx: "Context") -> list[str]:
+    return []
+
+
+@dataclass(frozen=True)
+class CheckType:
+    parse: Callable[[dict], Any]
+    run: Callable[[Any, "Context", "UI"], "Attempt"]
+    preflight: Callable[[Any, "Context"], list[str]] = _no_preflight
+
+
+STEP_TYPES: dict[str, CheckType] = {}
+
+
+def register(name: str, check: CheckType) -> None:
+    STEP_TYPES[name] = check
+
+
+def fields(raw: dict, required: set[str], optional: dict[str, Any]) -> dict:
+    """Check the keys of a step's type-specific fields and fill in defaults.
+
+    The step's ``name`` is always passed along, so checks can use it in messages.
+    """
+    optional = {"name": "", **optional}
+    for key in raw:
+        if key not in required and key not in optional:
+            raise ValueError(f"unknown field '{key}'")
+    for key in sorted(required):
+        if key not in raw:
+            raise ValueError(f"{key}: missing")
+    return {**optional, **raw}
+
+
+from . import can, confirm, ethernet, serial, usb  # noqa: E402,F401  (register themselves)

interface_test_kit/checks/can.py

@@ -0,0 +1,186 @@
+"""CAN check in pair mode: two CAN ports wired together exchange test frames both ways."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import struct
+from dataclasses import dataclass
+from typing import Protocol
+
+from ..model import Attempt
+from . import CheckType, fields, register
+
+# (id, data, extended): empty, short and full standard frames, one extended frame
+TEST_FRAMES = [(0x123, b"", False), (0x123, bytes([0x55]), False),
+               (0x7FF, bytes(range(8)), False), (0x1ABCDE0, bytes([0xAA] * 8), True)]
+
+# ERROR-WARNING is fine: after a failed attempt (cable missing) the TX error counter
+# only counts down by one per good frame, so it stays above 96 for a while.
+GOOD_STATES = ("ERROR-ACTIVE", "ERROR-WARNING")
+
+_FRAME = struct.Struct("=IB3x8s")
+_EFF_FLAG = 0x80000000
+_RTR_FLAG = 0x40000000
+_ERR_FLAG = 0x20000000
+
+
+class CanBus(Protocol):
+    def send(self, arb_id: int, data: bytes, extended: bool) -> None: ...
+    def recv(self, timeout: float) -> tuple[int, bytes, bool] | None: ...
+    def close(self) -> None: ...
+
+
+class SocketCanBus:
+    def __init__(self, iface: str):
+        self._sock = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
+        self._sock.bind((iface,))
+
+    def send(self, arb_id: int, data: bytes, extended: bool) -> None:
+        can_id = arb_id | _EFF_FLAG if extended else arb_id
+        self._sock.send(_FRAME.pack(can_id, len(data), data.ljust(8, b"\0")))
+
+    def recv(self, timeout: float) -> tuple[int, bytes, bool] | None:
+        self._sock.settimeout(timeout)
+        while True:
+            try:
+                raw = self._sock.recv(_FRAME.size)
+            except socket.timeout:
+                return None
+            can_id, length, data = _FRAME.unpack(raw)
+            if can_id & (_ERR_FLAG | _RTR_FLAG):
+                continue
+            extended = bool(can_id & _EFF_FLAG)
+            return can_id & (0x1FFFFFFF if extended else 0x7FF), data[:length], extended
+
+    def close(self) -> None:
+        self._sock.close()
+
+
+def open_socketcan(iface: str) -> CanBus:
+    return SocketCanBus(iface)
+
+
+@dataclass(frozen=True)
+class CanConfig:
+    name: str
+    pair: tuple[str, str]
+    bitrate: int | None = None
+    timeout_s: float = 1.0
+
+
+def parse(raw: dict) -> CanConfig:
+    f = fields(raw, {"pair"}, {"bitrate": None, "timeout_s": 1.0})
+    pair = f["pair"]
+    if not isinstance(pair, list) or len(pair) != 2:
+        raise ValueError("pair: must list exactly two CAN interfaces, e.g. [can0, can1]")
+    if pair[0] == pair[1]:
+        # one interface talking to itself passes through the kernel's local loopback, no cable needed
+        raise ValueError("pair: must name two different CAN interfaces")
+    rate = f["bitrate"]
+    if rate is not None and (isinstance(rate, bool) or not isinstance(rate, int) or rate <= 0):
+        raise ValueError("bitrate: must be a positive whole number, e.g. 500000")
+    t = f["timeout_s"]
+    if isinstance(t, bool) or not isinstance(t, (int, float)) or t <= 0:
+        raise ValueError("timeout_s: must be a positive number")
+    return CanConfig(str(f["name"]), (str(pair[0]), str(pair[1])), rate, float(t))
+
+
+def _is_hardware(ctx, iface: str) -> bool:
+    return ctx.path(f"/sys/class/net/{iface}/device").exists()
+
+
+def _ifaces(config: CanConfig) -> list[str]:
+    return list(dict.fromkeys(config.pair))
+
+
+def preflight(config: CanConfig, ctx) -> list[str]:
+    problems = [f"CAN: network interface {i} not found" for i in _ifaces(config)
+                if not ctx.path(f"/sys/class/net/{i}").is_dir()]
+    if not problems and config.bitrate and os.geteuid() != 0 and \
+            any(_is_hardware(ctx, i) for i in _ifaces(config)):
+        problems.append("CAN: setting the bitrate needs root")
+    return problems
+
+
+def _set_bitrate(ctx, iface: str, bitrate: int, details: list[str]) -> bool:
+    for args in (["ip", "link", "set", iface, "down"],
+                 ["ip", "link", "set", iface, "type", "can", "bitrate", str(bitrate)],
+                 ["ip", "link", "set", iface, "up"]):
+        result = ctx.run(args)
+        if result.returncode != 0:
+            details.append(f"{' '.join(args)}: {result.stderr.strip()}")
+            return False
+    details.append(f"{iface}: bitrate {bitrate}")
+    return True
+
+
+def _state(ctx, iface: str) -> str | None:
+    result = ctx.run(["ip", "-d", "-j", "link", "show", iface])
+    try:
+        return json.loads(result.stdout)[0]["linkinfo"]["info_data"]["state"]
+    except (ValueError, LookupError, TypeError):
+        return None
+
+
+def _drain(bus: CanBus) -> None:
+    """Drop frames still queued from an earlier attempt."""
+    for _ in range(100):
+        if bus.recv(0.05) is None:
+            return
+
+
+def _exchange(tx: CanBus, rx: CanBus, timeout: float) -> str | None:
+    """Send every test frame from tx to rx. Returns 'missing', 'corrupt' or None."""
+    for frame in TEST_FRAMES:
+        tx.send(*frame)
+        got = rx.recv(timeout)
+        if got is None:
+            return "missing"
+        if got != frame:
+            return "corrupt"
+    return None
+
+
+def run(config: CanConfig, ctx, ui) -> Attempt:
+    a, b = config.pair
+    details: list[str] = []
+    cable = f"CAN cable between {a} and {b} faulty"
+    hardware = [i for i in _ifaces(config) if _is_hardware(ctx, i)]
+    if config.bitrate:
+        for iface in hardware:
+            if not _set_bitrate(ctx, iface, config.bitrate, details):
+                return Attempt.fail(f"CAN: could not set up {iface}. Tell the test engineer.",
+                                    details=details)
+    bus_a = ctx.open_can(a)
+    try:
+        bus_b = ctx.open_can(b)
+        try:
+            _drain(bus_a)
+            _drain(bus_b)
+            for tx_name, tx, rx_name, rx in ((a, bus_a, b, bus_b), (b, bus_b, a, bus_a)):
+                problem = _exchange(tx, rx, config.timeout_s)
+                if problem == "missing":
+                    details.append(f"{tx_name} -> {rx_name}: frame not received within {config.timeout_s:g} s")
+                    return Attempt.fail(ctx.say(f"CAN: no frames from {tx_name} to {rx_name}. "
+                                                "Check the CAN cable and termination.", cable), details=details)
+                if problem == "corrupt":
+                    details.append(f"{tx_name} -> {rx_name}: frame received with wrong id or data")
+                    return Attempt.fail(ctx.say(f"CAN: frames from {tx_name} to {rx_name} corrupted", cable),
+                                        details=details)
+                details.append(f"{tx_name} -> {rx_name}: {len(TEST_FRAMES)} frames ok")
+        finally:
+            bus_b.close()
+    finally:
+        bus_a.close()
+    for iface in hardware:
+        state = _state(ctx, iface)
+        details.append(f"{iface}: state {state}")
+        if state not in GOOD_STATES:
+            return Attempt.fail(f"CAN: {iface} in error state {state}. "
+                                "Check the CAN cable and termination, then retry.", details=details)
+    return Attempt.ok(details=details)
+
+
+register("can", CheckType(parse=parse, run=run, preflight=preflight))

interface_test_kit/checks/confirm.py

@@ -0,0 +1,30 @@
+"""Manual check: the operator looks at something and answers Y/N."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..model import Attempt
+from . import CheckType, fields, register
+
+
+@dataclass(frozen=True)
+class ConfirmConfig:
+    prompt: str
+
+
+def parse(raw: dict) -> ConfirmConfig:
+    f = fields(raw, {"prompt"}, {})
+    if not isinstance(f["prompt"], str) or not f["prompt"].strip():
+        raise ValueError("prompt: must be a non-empty text")
+    return ConfirmConfig(f["prompt"])
+
+
+def run(config: ConfirmConfig, ctx, ui) -> Attempt:
+    if ui.ask_yes_no(config.prompt):
+        return Attempt.ok()
+    text = f"Operator answered No: {config.prompt}"
+    return Attempt.fail(ctx.say(text, text))
+
+
+register("confirm", CheckType(parse=parse, run=run))

interface_test_kit/checks/ethernet.py

@@ -0,0 +1,97 @@
+"""Ethernet check: link, negotiated speed and duplex from sysfs, then ping a counterpart."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..model import Attempt, Measurement
+from . import CheckType, fields, register
+
+_LOSS = re.compile(r"(\d+(?:\.\d+)?)% packet loss")
+
+
+@dataclass(frozen=True)
+class EthernetConfig:
+    name: str
+    iface: str
+    speed: int | None = None
+    duplex: str | None = None
+    ping: str | None = None
+    ping_count: int = 5
+    max_loss_pct: float = 0.0
+
+
+def parse(raw: dict) -> EthernetConfig:
+    f = fields(raw, {"iface"}, {"speed": None, "duplex": None, "ping": None,
+                                "ping_count": 5, "max_loss_pct": 0.0})
+    if f["speed"] is not None and (not isinstance(f["speed"], int) or f["speed"] <= 0):
+        raise ValueError("speed: must be a positive whole number (Mbit/s)")
+    if f["duplex"] is not None and f["duplex"] not in ("full", "half"):
+        raise ValueError("duplex: must be full or half")
+    if not isinstance(f["ping_count"], int) or not 1 <= f["ping_count"] <= 100:
+        raise ValueError("ping_count: must be a whole number from 1 to 100")
+    loss = f["max_loss_pct"]
+    if isinstance(loss, bool) or not isinstance(loss, (int, float)) or not 0 <= loss <= 100:
+        raise ValueError("max_loss_pct: must be a number from 0 to 100")
+    return EthernetConfig(str(f["name"]), str(f["iface"]), f["speed"], f["duplex"],
+                          str(f["ping"]) if f["ping"] is not None else None, f["ping_count"], float(loss))
+
+
+def preflight(config: EthernetConfig, ctx) -> list[str]:
+    if not ctx.path(f"/sys/class/net/{config.iface}").is_dir():
+        return [f"{config.name}: network interface {config.iface} not found"]
+    return []
+
+
+def _read(ctx, iface: str, attr: str) -> str | None:
+    try:
+        return ctx.path(f"/sys/class/net/{iface}/{attr}").read_text().strip()
+    except OSError:  # reading speed/duplex of a link that is down fails with EINVAL
+        return None
+
+
+def run(config: EthernetConfig, ctx, ui) -> Attempt:
+    name = config.name
+    faulty_equipment = f"{name}: network cable or test network faulty"
+    details: list[str] = []
+    measurements: list[Measurement] = []
+    if _read(ctx, config.iface, "carrier") != "1":
+        details.append(f"{config.iface}: no carrier")
+        return Attempt.fail(ctx.say(f"{name}: no network link. Check the cable.", faulty_equipment),
+                            details=details)
+    speed_text = _read(ctx, config.iface, "speed")
+    duplex = _read(ctx, config.iface, "duplex")
+    details.append(f"{config.iface}: link up, speed {speed_text} Mbit/s, duplex {duplex}")
+    if config.speed is not None:
+        try:
+            speed = int(speed_text or "")
+        except ValueError:
+            speed = -1
+        measurements.append(Measurement("link speed", speed, "Mbit/s", low=config.speed))
+        if speed != config.speed:
+            return Attempt.fail(f"{name}: link at {speed_text} Mbit/s, expected {config.speed}",
+                                details=details, measurements=measurements)
+    if config.duplex is not None and duplex != config.duplex:
+        return Attempt.fail(f"{name}: {duplex} duplex, expected {config.duplex}",
+                            details=details, measurements=measurements)
+    if config.ping:
+        result = ctx.run(["ping", "-c", str(config.ping_count), "-W", "1", "-I", config.iface, config.ping])
+        match = _LOSS.search(result.stdout)
+        if not match:
+            details += [f"ping exit {result.returncode}", result.stdout.strip(), result.stderr.strip()]
+            return Attempt.fail(ctx.say(f"{name}: no answer from {config.ping}", faulty_equipment),
+                                details=[d for d in details if d], measurements=measurements)
+        loss = float(match.group(1))
+        measurements.append(Measurement("packet loss", loss, "%", high=config.max_loss_pct))
+        details.append(f"ping {config.ping}: {loss:g}% loss")
+        if loss >= 100:
+            return Attempt.fail(ctx.say(f"{name}: no answer from {config.ping}", faulty_equipment),
+                                details=details, measurements=measurements)
+        if loss > config.max_loss_pct:
+            return Attempt.fail(ctx.say(f"{name}: {loss:g}% packet loss to {config.ping}", faulty_equipment),
+                                details=details, measurements=measurements)
+    return Attempt.ok(measurements=measurements, details=details)
+
+
+register("ethernet", CheckType(parse=parse, run=run, preflight=preflight))

interface_test_kit/checks/serial.py

@@ -0,0 +1,172 @@
+"""Serial port check through a loopback plug: data at each baud rate, then handshake lines."""
+
+from __future__ import annotations
+
+import os
+import random
+from dataclasses import dataclass
+from typing import Protocol
+
+from ..model import Attempt
+from . import CheckType, fields, register
+
+# Which output line drives which input lines on each kind of loopback plug.
+LOOPBACK_TYPES: dict[str, dict[str, tuple[str, ...]]] = {
+    "9pin-full": {"RTS": ("CTS",), "DTR": ("DSR", "CD", "RI")},
+    "9pin": {"RTS": ("CTS",), "DTR": ("DSR", "CD")},
+    "data-only": {},
+}
+
+# USB-serial adapters report modem line changes over USB, several ms late.
+LINE_SETTLE_S = 0.05
+
+_REPAIR = ". Check the loopback plug; if it is fine, send the unit to repair."
+
+
+class SerialLink(Protocol):
+    def set_baud(self, baud: int) -> None: ...
+    def write(self, data: bytes) -> None: ...
+    def read(self, n: int, timeout: float) -> bytes: ...
+    def reset_input(self) -> None: ...
+    def set_line(self, name: str, state: bool) -> None: ...
+    def get_line(self, name: str) -> bool: ...
+    def close(self) -> None: ...
+
+
+class PySerialLink:
+    def __init__(self, port: str, baud: int):
+        import serial
+        self._ser = serial.Serial(port, baud, timeout=1.0)
+
+    def set_baud(self, baud: int) -> None:
+        self._ser.baudrate = baud
+
+    def write(self, data: bytes) -> None:
+        self._ser.write(data)
+        self._ser.flush()
+
+    def read(self, n: int, timeout: float) -> bytes:
+        self._ser.timeout = timeout
+        return self._ser.read(n)
+
+    def reset_input(self) -> None:
+        self._ser.reset_input_buffer()
+
+    def set_line(self, name: str, state: bool) -> None:
+        setattr(self._ser, name.lower(), state)
+
+    def get_line(self, name: str) -> bool:
+        return bool(getattr(self._ser, name.lower()))
+
+    def close(self) -> None:
+        self._ser.close()
+
+
+def open_pyserial(port: str, baud: int) -> SerialLink:
+    return PySerialLink(port, baud)
+
+
+@dataclass(frozen=True)
+class SerialConfig:
+    name: str
+    port: str
+    loopback: str = "9pin"
+    bauds: tuple[int, ...] = (9600, 115200)
+    pattern_bytes: int = 512
+
+
+def parse(raw: dict) -> SerialConfig:
+    f = fields(raw, {"port"}, {"loopback": "9pin", "bauds": [9600, 115200], "pattern_bytes": 512})
+    if f["loopback"] not in LOOPBACK_TYPES:
+        raise ValueError(f"loopback: unknown type '{f['loopback']}' "
+                         f"(known: {', '.join(LOOPBACK_TYPES)})")
+    bauds = f["bauds"]
+    if not isinstance(bauds, list) or not bauds or \
+            not all(isinstance(b, int) and not isinstance(b, bool) and b > 0 for b in bauds):
+        raise ValueError("bauds: must be a list of positive whole numbers")
+    pb = f["pattern_bytes"]
+    if not isinstance(pb, int) or pb < 256:
+        raise ValueError("pattern_bytes: must be a whole number of at least 256")
+    return SerialConfig(str(f["name"]), str(f["port"]), f["loopback"], tuple(bauds), pb)
+
+
+def preflight(config: SerialConfig, ctx) -> list[str]:
+    path = ctx.path(config.port)
+    if not path.exists():
+        return [f"{config.name}: port {config.port} not found"]
+    if not os.access(path, os.R_OK | os.W_OK):
+        return [f"{config.name}: no access to port {config.port} (add the user to group dialout)"]
+    return []
+
+
+def _pattern(baud: int, size: int) -> bytes:
+    return bytes(range(256)) + random.Random(baud).randbytes(size - 256)
+
+
+def _check_data(link: SerialLink, config: SerialConfig, details: list[str]) -> tuple[str, int] | None:
+    """Returns (problem, baud) for the first failing baud rate, or None."""
+    for baud in config.bauds:
+        link.set_baud(baud)
+        link.reset_input()
+        sent = _pattern(baud, config.pattern_bytes)
+        link.write(sent)
+        got = link.read(len(sent), max(1.0, 20 * len(sent) * 10 / baud))
+        if not got:
+            details.append(f"{baud} baud: nothing received")
+            return "no_data", baud
+        if got != sent:
+            offset = next((i for i, (a, b) in enumerate(zip(sent, got)) if a != b), len(got))
+            details.append(f"{baud} baud: received {len(got)} of {len(sent)} bytes, "
+                           f"first difference at offset {offset}")
+            return "corrupt", baud
+        details.append(f"{baud} baud: {len(sent)} bytes ok")
+    return None
+
+
+def _check_lines(link: SerialLink, wiring: dict[str, tuple[str, ...]], details: list[str],
+                 sleep) -> list[str]:
+    broken: list[str] = []
+    for out, inputs in wiring.items():
+        for state in (True, False):
+            link.set_line(out, state)
+            for other in wiring:
+                if other != out:
+                    link.set_line(other, not state)
+            sleep(LINE_SETTLE_S)
+            for inp in inputs:
+                if link.get_line(inp) != state:
+                    pair = f"{out}->{inp}"
+                    details.append(f"{pair}: input did not follow output set {'high' if state else 'low'}")
+                    if pair not in broken:
+                        broken.append(pair)
+    if wiring and not broken:
+        details.append("handshake lines ok: " + ", ".join(
+            f"{o}->{i}" for o, ins in wiring.items() for i in ins))
+    return broken
+
+
+def run(config: SerialConfig, ctx, ui) -> Attempt:
+    details: list[str] = []
+    link = ctx.open_serial(config.port, config.bauds[0])
+    try:
+        problem = _check_data(link, config, details)
+        if problem:
+            kind, baud = problem
+            if kind == "no_data":
+                unit = f"{config.name}: no data received back{_REPAIR}"
+            else:
+                unit = f"{config.name}: data corrupted at {baud} baud{_REPAIR}"
+            return Attempt.fail(ctx.say(unit, f"Loopback plug on {config.name} faulty or not plugged in"),
+                                details=details)
+        broken = _check_lines(link, LOOPBACK_TYPES[config.loopback], details, ctx.sleep)
+    finally:
+        link.close()
+    if broken:
+        pairs = ", ".join(broken)
+        return Attempt.fail(ctx.say(f"{config.name}: handshake line faulty ({pairs}){_REPAIR}",
+                                    f"Loopback plug on {config.name} faulty ({pairs} not connected)"),
+                            details=details)
+    return Attempt.ok(details=details)
+
+
+register("serial", CheckType(parse=parse, run=run, preflight=preflight))