virtual-plc 0.3.0__py3-none-any.whl

virtual_plc/__init__.py

@@ -0,0 +1,14 @@
+"""Local MC protocol simulator with optional response faults."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("virtual_plc")
+except PackageNotFoundError:
+    __version__ = "0.3.0"  # Source-tree use without an installed distribution.
+
+from .faults import FaultPlan
+from .memory import Memory
+from .server import Server
+
+__all__ = ["Server", "FaultPlan", "Memory", "__version__"]

virtual_plc/__main__.py

@@ -0,0 +1,161 @@
+"""Local simulator CLI: python -m virtual_plc."""
+
+import argparse
+import ipaddress
+import json
+import logging
+from pathlib import Path
+import re
+import signal
+import sys
+import threading
+
+from . import __version__, guide
+from .server import Server
+from .faults import FaultPlan
+from .memory import Memory
+from .profiles import PROFILES
+
+
+def text_pad(value):
+    try:
+        number = int(value, 0)
+        if 0 <= number <= 255:
+            return number
+    except ValueError:
+        pass
+    raise argparse.ArgumentTypeError("text pad must be an integer 0..255 (e.g. 0x00 or 0x20)")
+
+
+def device_range(value):
+    try:
+        device, span = value.split(":")
+        low, high = (int(part, 0) for part in span.split("-"))
+        if device and 0 <= low <= high:
+            return device, (low, high)
+    except ValueError:
+        pass
+    raise argparse.ArgumentTypeError("range must be DEV:LO-HI with 0 <= LO <= HI")
+
+
+def local_host(host):
+    if host.lower() == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+class GuideParser(argparse.ArgumentParser):
+    def error(self, message, topic=None):
+        if topic is None:
+            flags = re.findall(r"--[a-z][a-z-]*", message)
+            topic = guide.option_topic("/".join(flags))
+        # JSON errors and filenames can contain newlines; diagnostics stay one line.
+        self.exit(2, f"{self.prog}: error: {' '.join(message.split())}; see: virtual-plc guide {topic}\n")
+
+
+def build_parser():
+    parser = GuideParser(prog="virtual-plc", description="Virtual Mitsubishi MC protocol PLC (not for industrial use)")
+    parser.add_argument("--version", action="version", version=__version__, help="show installed version")
+    parser.add_argument("--host", default="127.0.0.1", help="bind address (local use only)")
+    parser.add_argument("--port", type=int, default=5000, help="TCP port 0..65535; 0 chooses a free port")
+    parser.add_argument("--profile", choices=PROFILES, default="Q", help="simulated CPU profile")
+    parser.add_argument("--password", help="simulated lock password (not authentication)")
+    parser.add_argument("--initial-state", choices=("RUN", "STOP", "PAUSE"), default="RUN", help="initial CPU state")
+    parser.add_argument("--max-points", type=int, default=4096, help="positive batch point limit")
+    parser.add_argument("--idle-timeout", type=float, default=None, help="seconds; default: no timeout")
+    parser.add_argument("--ascii-dword-order", choices=("swapped", "client"), default="swapped",
+                        help="ASCII dwords: low word first / client high word first")
+    parser.add_argument("--text-pad", type=text_pad, default=0x00, help="CPU name fill byte 0..255; 0x20 = space")
+    parser.add_argument("--fault-plan", metavar="FILE", help="response fault JSON")
+    parser.add_argument("--init", metavar="FILE", help="load memory JSON before listening")
+    parser.add_argument("--dump-on-exit", metavar="FILE", help="save memory JSON after shutdown")
+    parser.add_argument("--latch-range", action="append", type=device_range, default=[], metavar="DEV:LO-HI",
+                        help="retained span; repeatable; default all L")
+    parser.add_argument("--limit", action="append", type=device_range, default=[], metavar="DEV:LO-HI",
+                        help="inclusive device limit; repeatable; default profile ceiling")
+    parser.add_argument("-v", "--verbose", action="store_true", help="log requests and connection close reasons")
+    return parser
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else list(argv)
+    parser = build_parser()
+    if argv and argv[0] == "guide":
+        return guide.main(argv[1:], parser)
+    args = parser.parse_args(argv)
+    topic = "faults"
+    try:
+        plan = FaultPlan.from_file(args.fault_plan) if args.fault_plan else None
+        topic = "memory"
+        options = dict(profile=args.profile, password=args.password, initial_state=args.initial_state,
+                       max_points=args.max_points, idle_timeout=args.idle_timeout, fault_plan=plan,
+                       ascii_dword_order=args.ascii_dword_order, text_pad=args.text_pad, verbose=args.verbose)
+        if args.init or args.limit:
+            options["memory"] = Memory(args.profile, dict(args.limit))
+        if args.latch_range:
+            ranges = {}
+            for device, span in args.latch_range:
+                ranges.setdefault(device, []).append(span)
+            options["latch_ranges"] = ranges
+        topic = "options"
+        try:
+            server = Server(args.host, args.port, **options)
+        except ValueError as error:
+            parser.error(str(error), "memory" if "latch" in str(error) else topic)
+        topic = "memory"
+        if args.init:
+            options["memory"].load(json.loads(Path(args.init).read_text(encoding="utf-8")))
+    except (OSError, ValueError) as error:
+        parser.error(str(error), topic)
+    try:
+        server.start()
+    except (OSError, OverflowError) as error:
+        server.stop()
+        print(f"cannot listen on {args.host}:{args.port}: {error}", file=sys.stderr)
+        return 1
+    warning = "; WARNING: localhost-only simulator; do not expose to production networks" if not local_host(args.host) else ""
+    exit_code = 0
+    previous = {}
+    def terminate(signum, frame):
+        raise KeyboardInterrupt  # finally stops workers and writes the snapshot, then exits 0
+    handler = logging.StreamHandler(sys.stderr)
+    logger = logging.getLogger("virtual_plc")
+    old_level = logger.level
+    if args.verbose:
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    try:
+        for name in ("SIGTERM", "SIGBREAK"):
+            if hasattr(signal, name):
+                number = getattr(signal, name)
+                previous[number] = signal.signal(number, terminate)
+        print("listening on %s:%d (%s, %s) idle_timeout=%s text_pad=0x%02X ascii_dword_order=%s fault_plan=%s%s" %
+              (*server.address, args.profile, args.initial_state, args.idle_timeout, args.text_pad,
+               args.ascii_dword_order, args.fault_plan, warning), file=sys.stderr, flush=True)
+        event = threading.Event()
+        while not event.wait(0.5):
+            pass
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.stop()
+        for number, old in previous.items():
+            signal.signal(number, old)
+        if args.verbose:
+            logger.removeHandler(handler)
+            logger.setLevel(old_level)
+        if args.dump_on_exit:
+            try:
+                Path(args.dump_on_exit).write_text(json.dumps(server.memory.dump(), indent=2) + "\n", encoding="utf-8")
+            except OSError as error:
+                print(f"cannot dump memory: {error}", file=sys.stderr)
+                exit_code = 1
+    return exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

virtual_plc/codec.py

@@ -0,0 +1,235 @@
+"""MC 3E/4E framing and binary/ASCII conversion for both wire classes.
+
+ASCII uses the explicit compat numbering policy: fixed-width decimal addresses.
+Command handlers operate on canonical binary payloads for every transport.
+"""
+
+from dataclasses import dataclass, replace
+import struct
+
+HEADER_SIZE = 9  # subheader 2 + route 5 + length 2
+MIN_BODY = 6  # timer 2 + command 2 + subcommand 2 (binary bytes)
+FRAMES = ("3E", "4E")
+WIRES = ("binary", "ascii")
+
+
+@dataclass(frozen=True)
+class Layout:
+    frame: str
+    wire: str
+
+    @property
+    def scale(self):
+        return 2 if self.wire == "ascii" else 1
+
+    @property
+    def header_size(self):
+        return (HEADER_SIZE + (4 if self.frame == "4E" else 0)) * self.scale
+
+    def number(self, value, size):
+        binary = value.to_bytes(size, "little")  # also checks field overflow
+        return f"{value:0{size * 2}X}".encode() if self.wire == "ascii" else binary
+
+
+class LengthError(ValueError):
+    """A fixed-width field is truncated or a payload has extra bytes."""
+
+
+class Reader:
+    """Exact-width numeric fields; ASCII hex permits either case, no whitespace."""
+
+    def __init__(self, data, wire, offset=0):
+        self.data, self.wire, self.offset = data, wire, offset
+
+    def take(self, size):
+        result = self.data[self.offset:self.offset + size]
+        if len(result) != size:
+            raise LengthError("short field")
+        self.offset += size
+        return result
+
+    def number(self, size):
+        value = self.take(size * (2 if self.wire == "ascii" else 1))
+        if self.wire == "ascii":
+            if any(char not in b"0123456789abcdefABCDEF" for char in value):
+                raise ValueError("invalid hexadecimal field")
+            return int(value, 16)
+        return int.from_bytes(value, "little")
+
+
+def _layout(buffer):
+    if len(buffer) < 2:
+        return None
+    if buffer[:2] in (b"\x50\x00", b"\x54\x00"):
+        return Layout("4E" if buffer[0] == 0x54 else "3E", "binary")
+    if len(buffer) < 4 and buffer[:2] in (b"50", b"54"):
+        return None
+    if buffer[:4] in (b"5000", b"5400"):
+        return Layout("4E" if buffer[:4] == b"5400" else "3E", "ascii")
+    raise ValueError("unknown frame header")
+
+
+@dataclass(frozen=True)
+class Request:
+    route: tuple  # (network, pc, io, station)
+    timer: int
+    command: int
+    subcommand: int
+    data: bytes
+    frame: str = "3E"
+    wire: str = "binary"
+    serial: int = 0
+
+
+def frame_size(buffer):
+    """Total size of the frame starting at buffer, or None until its header is complete."""
+    layout = _layout(buffer)
+    if layout is None or len(buffer) < layout.header_size:
+        return None
+    reader = Reader(buffer, layout.wire, layout.header_size - 2 * layout.scale)
+    return layout.header_size + reader.number(2)
+
+
+def decode_request(frame):
+    layout = _layout(frame)
+    if layout is None or len(frame) < layout.header_size + MIN_BODY * layout.scale:
+        raise ValueError("short request")
+    if frame_size(frame) != len(frame):
+        raise ValueError("frame length mismatch")
+    reader = Reader(frame, layout.wire, 2 * layout.scale)
+    serial = 0
+    if layout.frame == "4E":
+        serial = reader.number(2)
+        if reader.number(2) != 0:
+            raise ValueError("nonzero 4E reserved field")
+    route = tuple(reader.number(size) for size in (1, 1, 2, 1))
+    reader.number(2)  # length checked above
+    timer, command, subcommand = (reader.number(2) for _ in range(3))
+    return Request(route, timer, command, subcommand, frame[reader.offset:], layout.frame, layout.wire, serial)
+
+
+def encode_response(request, end_code=0, data=b"", *, ascii_dword_order="swapped"):
+    layout = Layout(request.frame, request.wire)
+    if request.wire == "ascii" and data:
+        data = _ascii_response_data(request, data, ascii_dword_order)
+    body = layout.number(end_code, 2) + data
+    prefix = b"\xd4\x00" if request.frame == "4E" else b"\xd0\x00"
+    if request.wire == "ascii":
+        prefix = prefix.hex().upper().encode()
+    if request.frame == "4E":
+        prefix += layout.number(request.serial, 2) + layout.number(0, 2)
+    route = b"".join(layout.number(value, size) for value, size in zip(request.route, (1, 1, 2, 1)))
+    return prefix + route + layout.number(len(body), 2) + body
+
+
+def read_device(reader, profile, *, text_pad=0):
+    """Read a descriptor using only the selected profile, never guess its class."""
+    wire = profile.wire
+    if reader.wire == "ascii":
+        device = profile.device_by_ascii(reader.take(wire.ascii_code_size).decode("latin-1"), text_pad=text_pad)
+        digits = reader.take(wire.ascii_address_size)
+        if any(char not in b"0123456789" for char in digits):
+            raise ValueError("invalid compat decimal address")
+        head = int(digits, 10)
+    else:
+        head = reader.number(wire.address_size)
+        device = profile.device_by_code(reader.number(wire.code_size))
+    if device is None:
+        raise ValueError("unknown device")
+    return device, head
+
+
+def normalize_request(request, profile, *, ascii_dword_order="swapped", text_pad=0):
+    """Convert an ASCII command payload to the existing binary handler format.
+
+    A payload error is returned by dispatch as an end code, not a framing close.
+    Exact field widths reject overlong client addresses without truncating them.
+    """
+    if request.wire == "binary":
+        return request
+    reader = Reader(request.data, "ascii")
+    wire = profile.wire
+
+    def descriptor():
+        device, head = read_device(reader, profile, text_pad=text_pad)
+        return head.to_bytes(wire.address_size, "little") + device.code.to_bytes(wire.code_size, "little")
+
+    command, subcommand = request.command, request.subcommand
+    data = bytearray()
+    if command in (0x0401, 0x1401):
+        data += descriptor()
+        points = reader.number(2)
+        data += points.to_bytes(2, "little")
+        if command == 0x1401:
+            if subcommand == wire.bit_subcommand:
+                data += pack_bits([char - 48 for char in reader.take(points)])
+            else:
+                data += pack_words([reader.number(2) for _ in range(points)])
+    elif command in (0x0403, 0x1402):
+        bit = subcommand == wire.bit_subcommand
+        counts = [reader.number(1) for _ in range(1 if bit else 2)]
+        data += bytes(counts)
+        for count, width in zip(counts, (wire.bit_value_size,) if bit else (2, 4)):
+            for _ in range(count):
+                data += descriptor()
+                if command == 0x1402:
+                    value = _ascii_dword_value(reader.number(width), width, ascii_dword_order)
+                    data += value.to_bytes(width, "little")
+    elif command == 0x0619:
+        size = reader.number(2)
+        data += size.to_bytes(2, "little") + reader.take(size)
+    if reader.offset != len(reader.data):
+        raise ValueError("payload length mismatch or overwidth address")
+    return replace(request, data=bytes(data))
+
+
+def _ascii_dword_value(value, width, order):
+    """Exchange the two word halves only for an ASCII dword in swapped mode."""
+    return ((value & 0xFFFF) << 16) | (value >> 16) if width == 4 and order == "swapped" else value
+
+
+def _ascii_response_data(request, data, ascii_dword_order):
+    reader = Reader(data, "binary")
+    layout = Layout(request.frame, "ascii")
+    if request.command == 0x0101:
+        return reader.take(16) + layout.number(reader.number(2), 2)
+    if request.command == 0x0619:
+        return layout.number(reader.number(2), 2) + data[2:]
+    if request.command == 0x0401 and request.subcommand in (1, 3):
+        points = Reader(request.data, "ascii", len(request.data) - 4).number(2)
+        return bytes(48 + bit for bit in unpack_bits(data, points))
+    counts = ((len(data) // 2, 2),)
+    if request.command == 0x0403:
+        sizes = Reader(request.data, "ascii")
+        counts = ((sizes.number(1), 2), (sizes.number(1), 4))
+    return b"".join(layout.number(_ascii_dword_value(reader.number(width), width, ascii_dword_order), width)
+                    for count, width in counts for _ in range(count))
+
+
+def pack_words(values):
+    if not all(0 <= value <= 0xFFFF for value in values):
+        raise ValueError("word out of range")
+    return struct.pack(f"<{len(values)}H", *values)
+
+
+def unpack_words(data):
+    if len(data) % 2:
+        raise ValueError("odd word payload")
+    return list(struct.unpack(f"<{len(data) // 2}H", data))
+
+
+def pack_bits(values):
+    if not all(value in (0, 1) for value in values):
+        raise ValueError("bit must be 0 or 1")
+    padded = list(values) + [0] * (len(values) % 2)
+    return bytes(high << 4 | low for high, low in zip(padded[::2], padded[1::2]))
+
+
+def unpack_bits(data, count):
+    if len(data) != (count + 1) // 2:
+        raise ValueError("bit payload length mismatch")
+    nibbles = [nibble for byte in data for nibble in (byte >> 4, byte & 15)]
+    bits, padding = nibbles[:count], nibbles[count:]
+    if any(bit > 1 for bit in bits) or any(padding):
+        raise ValueError("bad bit nibble")
+    return bits

virtual_plc/commands.py

@@ -0,0 +1,221 @@
+"""Shared MC command handlers, parameterized by profile wire class."""
+
+from enum import IntEnum
+import struct
+
+from .codec import LengthError, Reader, normalize_request, pack_bits, pack_words, read_device, unpack_bits, unpack_words
+from .memory import OutOfRange
+from .profiles import WIRE_CLASSES
+
+ECHO_MAX = 960
+LOCK_GATED = {0x1001, 0x1002, 0x1003, 0x1005, 0x1006}
+CPU_STATES = {"STOP": 0, "RUN": 1, "PAUSE": 2}  # SD203 layout: design, unverified.
+
+
+class EndCode(IntEnum):
+    OK = 0x0000
+    POINTS_OUT_OF_RANGE = 0xC051
+    ADDRESS_OUT_OF_RANGE = 0xC056
+    UNSUPPORTED_COMMAND = 0xC059
+    REQUEST_DATA_ERROR = 0xC05C
+    DATA_LENGTH_MISMATCH = 0xC061
+    LOCKED = 0xC200
+    WRONG_PASSWORD = 0xC201
+    INVALID_STATE = 0xC202
+
+
+# DESIGN §7 rows: no manual cross-check yet.
+ERROR_CODES = {
+    code.value: {"name": code.name, "source": "memory" if code in (EndCode.LOCKED, EndCode.WRONG_PASSWORD) else "design",
+                 "status": "unverified"} for code in EndCode
+}
+
+
+class CommandError(Exception):
+    """A request rejected with the end code in args[0]."""
+
+
+def batch(request, memory, max_points, control=None):
+    """Batch read (0401) or write (1401); the subcommand selects bit or word units."""
+    wire = memory.profile.wire
+    if len(request.data) < wire.descriptor_size + 2:
+        raise CommandError(EndCode.REQUEST_DATA_ERROR)
+    reader = Reader(request.data, "binary")
+    device, head = read_device(reader, memory.profile)
+    points = reader.number(2)
+    payload = request.data[reader.offset:]
+    bit, write = request.subcommand == wire.bit_subcommand, request.command == 0x1401
+    if not 0 < points <= max_points:
+        raise CommandError(EndCode.POINTS_OUT_OF_RANGE)
+    expected = ((points + 1) // 2 if bit else 2 * points) if write else 0
+    if len(payload) != expected:
+        raise CommandError(EndCode.DATA_LENGTH_MISMATCH)
+    try:
+        if write:
+            values = unpack_bits(payload, points) if bit else unpack_words(payload)
+            (memory.write_bits if bit else memory.write_words)(device.name, head, values)
+            return b""
+        if bit:
+            return pack_bits(memory.read_bits(device.name, head, points))
+        return pack_words(memory.read_words(device.name, head, points))
+    except OutOfRange:
+        raise CommandError(EndCode.ADDRESS_OUT_OF_RANGE)
+    except ValueError:
+        raise CommandError(EndCode.REQUEST_DATA_ERROR)
+
+
+def random_access(request, memory, max_points, control=None):
+    """Random word/dword read/write or bit write; validate all entries first.
+
+    Counts are uint8, so a purported 256-entry list cannot match its payload.
+    Writes contain interleaved device/value entries, words before dwords.
+    The server holds its request lock through validation and application.
+    """
+    data = request.data
+    wire = memory.profile.wire
+    bit = request.subcommand == wire.bit_subcommand
+    write = request.command == 0x1402
+    count_size = 1 if bit else 2
+    if len(data) < count_size:
+        raise CommandError(EndCode.DATA_LENGTH_MISMATCH)
+    groups = ((data[0], wire.bit_value_size),) if bit else ((data[0], 2), (data[1], 4))
+    expected = count_size + sum(count * (wire.descriptor_size + (width if write else 0)) for count, width in groups)
+    if len(data) != expected:
+        raise CommandError(EndCode.DATA_LENGTH_MISMATCH)
+    entries = []
+    offset = count_size
+    try:
+        for count, width in groups:
+            for _ in range(count):
+                reader = Reader(data, "binary", offset)
+                device, head = read_device(reader, memory.profile)
+                offset = reader.offset
+                memory.check(device.name, head, 1 if bit else width // 2, "bit" if bit else "word")
+                values = None
+                if write:
+                    payload = data[offset:offset + width]
+                    offset += width
+                    if bit:
+                        value = int.from_bytes(payload, "little")
+                        if value not in (0, 1):
+                            raise ValueError("bit must be 0 or 1")
+                        values = [value]
+                    else:
+                        values = unpack_words(payload)
+                entries.append((device.name, head, width, values))
+        # Nothing above mutates storage. Overlaps are applied in wire order.
+        result = bytearray()
+        for device, head, width, values in entries:
+            if write:
+                (memory.write_bits if bit else memory.write_words)(device, head, values)
+            else:
+                result += pack_words(memory.read_words(device, head, width // 2))
+        return bytes(result)
+    except OutOfRange:
+        raise CommandError(EndCode.ADDRESS_OUT_OF_RANGE)
+    except ValueError:
+        raise CommandError(EndCode.REQUEST_DATA_ERROR)
+
+
+def echo(request, memory, max_points, control=None):
+    length, text = int.from_bytes(request.data[:2], "little"), request.data[2:]
+    if len(request.data) < 2 or length != len(text):
+        raise CommandError(EndCode.DATA_LENGTH_MISMATCH)
+    if not 0 < length <= ECHO_MAX or not text.isalnum():
+        raise CommandError(EndCode.REQUEST_DATA_ERROR)
+    return request.data
+
+
+def cputype(request, memory, max_points, control=None):
+    profile = memory.profile
+    pad = 0 if control is None else control.text_pad
+    return profile.cpu_name.encode("ascii").ljust(16, bytes([pad])) + struct.pack("<H", profile.cpu_code)
+
+
+def control_request(request, memory, max_points, control=None):
+    """Agreed M5 policies, using the same field reader for every transport."""
+    command = request.command
+    auth = command in (0x1630, 0x1631)
+    if control is None or (auth and control.password is None):
+        raise CommandError(EndCode.UNSUPPORTED_COMMAND)
+    if control.locked and command in LOCK_GATED:
+        raise CommandError(EndCode.LOCKED)
+    reader = Reader(request.data, request.wire)
+    mode = reader.number(2)  # password length for auth commands
+    clear, fixed = (reader.number(1), reader.number(1)) if command == 0x1001 else (0, 0)
+    password = reader.take(mode) if auth else b""
+    if reader.offset != len(reader.data):
+        raise LengthError("extra control data")
+    if auth:
+        wire = memory.profile.wire
+        if not wire.password_min <= len(password) <= wire.password_max or not password.isascii():
+            raise CommandError(EndCode.REQUEST_DATA_ERROR)
+        if password.decode("ascii") != control.password:
+            raise CommandError(EndCode.WRONG_PASSWORD)
+        control.locked = command == 0x1631
+        return b""
+    if mode not in ((1, 3) if command in (0x1001, 0x1003) else (1,)) or clear not in (0, 1, 2) or fixed:
+        raise CommandError(EndCode.REQUEST_DATA_ERROR)
+    if (command == 0x1003 and control.state == "STOP") or (command in (0x1005, 0x1006) and control.state != "STOP"):
+        raise CommandError(EndCode.INVALID_STATE)
+    if command == 0x1001 and clear:
+        memory.clear(control.latch_ranges, "non_latch" if clear == 1 else "all")
+    if command == 0x1005:
+        memory.clear(control.latch_ranges, "latch")
+    else:
+        if command == 0x1006:
+            control.reset_count += 1
+        control.set_state({0x1001: "RUN", 0x1003: "PAUSE"}.get(command, "STOP"))
+    return b""
+
+
+# Extension point: (command, subcommand) -> handler(request, memory, max_points, control).
+HANDLERS = {
+    (0x0619, 0): echo, (0x0101, 0): cputype,
+}
+# Data subcommands are selected by wire class, so mismatches cannot dispatch.
+DATA_HANDLERS = {}
+for wire_class, wire in WIRE_CLASSES.items():
+    handlers = {}
+    for command in (0x0401, 0x1401):
+        handlers[command, wire.word_subcommand] = batch
+        handlers[command, wire.bit_subcommand] = batch
+    handlers[0x0403, wire.word_subcommand] = random_access
+    handlers[0x1402, wire.word_subcommand] = random_access
+    handlers[0x1402, wire.bit_subcommand] = random_access
+    DATA_HANDLERS[wire_class] = handlers
+HANDLERS.update({(command, 0): control_request for command in LOCK_GATED | {0x1630, 0x1631}})
+
+# Human-readable names for `virtual-plc guide profiles`; a test keeps this equal to the dispatch tables.
+COMMAND_NAMES = {
+    0x0101: "cpu type", 0x0401: "batch read", 0x0403: "random read", 0x0619: "echo",
+    0x1001: "run", 0x1002: "stop", 0x1003: "pause", 0x1005: "latch clear", 0x1006: "reset",
+    0x1401: "batch write", 0x1402: "random write (word/dword/bit)",
+    0x1630: "unlock (needs --password)", 0x1631: "lock (needs --password)",
+}
+
+
+def supported_commands(profile):
+    """Command codes dispatch accepts on this profile, for any subcommand."""
+    return sorted({command for command, _ in HANDLERS} | {command for command, _ in DATA_HANDLERS[profile.wire_class]})
+
+
+def dispatch(request, memory, max_points, control=None):
+    """Return (end_code, data); a rejected request leaves memory unchanged."""
+    key = (request.command, request.subcommand)
+    handler = HANDLERS.get(key) or DATA_HANDLERS[memory.profile.wire_class].get(key)
+    try:
+        if handler is None:
+            raise CommandError(EndCode.UNSUPPORTED_COMMAND)
+        # Control uses the shared Reader directly; data handlers consume canonical binary.
+        parsed = request if handler is control_request else normalize_request(
+            request, memory.profile, ascii_dword_order=control.ascii_dword_order if control is not None else "swapped",
+            text_pad=control.text_pad if control is not None else 0)
+        return EndCode.OK, handler(parsed, memory, max_points, control)
+    except CommandError as error:
+        return error.args[0], b""
+    except LengthError:
+        code = EndCode.DATA_LENGTH_MISMATCH if handler is control_request else EndCode.REQUEST_DATA_ERROR
+        return code, b""
+    except ValueError:
+        return EndCode.REQUEST_DATA_ERROR, b""