tracerlab 0.1.5__py3-none-any.whl

tracerlab/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for Cisco Packet Tracer 9."""
+
+__version__ = "0.1.5"

tracerlab/bridge.py

@@ -0,0 +1,359 @@
+"""HTTP long-poll bridge to the PT script module.
+
+If another tracerlab already owns the port, jobs are relayed through it (POST /exec).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import itertools
+import json
+import logging
+import os
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from importlib import resources
+from typing import Any
+
+log = logging.getLogger("tracerlab.bridge")
+
+HOST = "127.0.0.1"
+PORT = int(os.environ.get("TRACERLAB_PORT") or os.environ.get("PTMCP_PORT") or "39150")
+POLL_HOLD_S = 20.0           # how long a /poll request is held open when idle
+STALE_AFTER_S = POLL_HOLD_S + 10.0
+PICKUP_S = 8.0                # a queued job must be picked up by a poll within this
+MAX_BODY = 64 * 1024 * 1024
+
+
+class PTError(RuntimeError):
+    """Raised for errors reported by Packet Tracer or the bridge."""
+
+
+class NotConnected(PTError):
+    pass
+
+
+@dataclass
+class _Job:
+    id: int
+    code: str
+    future: asyncio.Future
+    picked: asyncio.Event = field(default_factory=asyncio.Event)
+    created: float = field(default_factory=time.monotonic)
+
+
+def _bridge_js() -> str:
+    return resources.files("tracerlab").joinpath("js/bridge.js").read_text()
+
+
+def _bridge_build() -> str:
+    import hashlib
+    return hashlib.sha1(_bridge_js().encode()).hexdigest()[:10]
+
+
+def _runtime_js() -> str:
+    return resources.files("tracerlab").joinpath("js/runtime.js").read_text()
+
+
+def _runtime_version(js: str) -> str:
+    # include the hash so edits to runtime.js reload without a version bump
+    import hashlib
+    from . import __version__
+    return f"{__version__}+{hashlib.sha1(js.encode()).hexdigest()[:8]}"
+
+
+class Bridge:
+    def __init__(self, host: str = HOST, port: int = PORT) -> None:
+        self.host, self.port = host, port
+        self._queue: asyncio.Queue[_Job] = asyncio.Queue()
+        self._inflight: dict[int, _Job] = {}
+        self._ids = itertools.count(1)
+        self._chunks: dict[int, dict[int, str]] = {}
+        self._server: asyncio.base_events.Server | None = None
+        self._last_seen = 0.0
+        self._pt_info: dict[str, Any] = {}
+        self._runtime_loaded_for: str | None = None   # session token of the PT side
+        self._runtime_lock = asyncio.Lock()
+        self.mode = "stopped"                         # "owner" | "relay" | "stopped"
+
+    async def start(self) -> None:
+        # created here so they bind to the running loop
+        self._queue = asyncio.Queue()
+        self._inflight = {}
+        self._chunks: dict[int, dict[int, str]] = {}
+        self._runtime_lock = asyncio.Lock()
+        try:
+            self._server = await asyncio.start_server(self._handle, self.host, self.port)
+            self.mode = "owner"
+            log.info("bridge listening on http://%s:%d", self.host, self.port)
+        except OSError:
+            if await asyncio.to_thread(self._probe_owner):
+                self.mode = "relay"
+                log.info("port %d owned by another ptmcp; relaying", self.port)
+            else:
+                raise PTError(f"port {self.port} is in use by something that is not ptmcp "
+                              "(set PTMCP_PORT to another port and update the PT module)")
+
+    async def stop(self) -> None:
+        self._last_seen = 0.0
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+        for job in list(self._inflight.values()):
+            if not job.future.done():
+                job.future.set_exception(PTError("bridge stopped"))
+
+    def _probe_owner(self) -> bool:
+        try:
+            with urllib.request.urlopen(f"http://{self.host}:{self.port}/ping", timeout=2) as r:
+                return json.loads(r.read()).get("service") == "ptmcp"
+        except Exception:
+            return False
+
+    @property
+    def connected(self) -> bool:
+        return time.monotonic() - self._last_seen < STALE_AFTER_S
+
+    def status(self) -> dict[str, Any]:
+        if self.mode == "relay":
+            try:
+                with urllib.request.urlopen(f"http://{self.host}:{self.port}/ping", timeout=2) as r:
+                    d = json.loads(r.read())
+                    d["mode"] = "relay"
+                    return d
+            except Exception as e:  # pragma: no cover - network edge
+                return {"mode": "relay", "connected": False, "error": str(e)}
+        return {
+            "service": "ptmcp",
+            "mode": self.mode,
+            "connected": self.connected,
+            "seconds_since_poll": round(time.monotonic() - self._last_seen, 1) if self._last_seen else None,
+            "pt": self._pt_info,
+            "queued": self._queue.qsize(),
+            "inflight": len(self._inflight),
+        }
+
+    async def run(self, code: str, timeout: float = 60.0, *, raw: bool = False) -> Any:
+        """Run a JS function body in PT (PTM in scope) and return its JSON value."""
+        if not raw:
+            await self._ensure_runtime(timeout)
+        return await self._submit(code, timeout)
+
+    async def wait_connected(self, timeout: float) -> bool:
+        end = time.monotonic() + timeout
+        while time.monotonic() < end:
+            if self.mode == "relay" or self.connected:
+                return True
+            await asyncio.sleep(0.25)
+        return False
+
+    async def _ensure_runtime(self, timeout: float) -> None:
+        async with self._runtime_lock:
+            probe = "return (typeof PTM !== 'undefined' && PTM.VERSION) ? PTM.VERSION : null;"
+            v = await self._submit(probe, timeout)
+            js = _runtime_js()
+            want = _runtime_version(js)
+            if v != want:
+                await self._submit(js + f"\nPTM.VERSION = {json.dumps(want)};\nreturn PTM.VERSION;", timeout)
+
+    async def _submit(self, code: str, timeout: float) -> Any:
+        if self.mode == "relay":
+            return await asyncio.to_thread(self._relay, code, timeout)
+        if not self.connected:
+            raise NotConnected(
+                "Packet Tracer is not connected. Open Packet Tracer 9 with the PT-MCP script "
+                "module installed (Extensions > PT-MCP Bridge shows a green 'connected' pill). "
+                "See pt_setup_instructions.")
+        loop = asyncio.get_running_loop()
+        job = _Job(next(self._ids), code, loop.create_future())
+        self._inflight[job.id] = job
+        await self._queue.put(job)
+        try:
+            await asyncio.wait_for(job.picked.wait(), PICKUP_S)
+        except asyncio.TimeoutError:
+            self._inflight.pop(job.id, None)
+            job.future.cancel()
+            self._last_seen = 0.0
+            raise NotConnected("Packet Tracer stopped polling (PT closed, bridge window closed, or a modal "
+                               "dialog is blocking PT). Check the 'PT-MCP Bridge' window.") from None
+        try:
+            env = await asyncio.wait_for(job.future, timeout)
+        except asyncio.TimeoutError:
+            raise PTError(f"Packet Tracer did not answer within {timeout:.0f}s "
+                          "(a modal dialog open in PT blocks scripting)") from None
+        finally:
+            self._inflight.pop(job.id, None)
+        return _unwrap(env)
+
+    def _relay(self, code: str, timeout: float) -> Any:
+        req = urllib.request.Request(
+            f"http://{self.host}:{self.port}/exec",
+            data=json.dumps({"code": code, "timeout": timeout}).encode(),
+            headers={"Content-Type": "application/json"}, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=timeout + 5) as r:
+                env = json.loads(r.read())
+        except urllib.error.HTTPError as e:
+            env = json.loads(e.read() or b"{}")
+        if env.get("bridge_error"):
+            raise (NotConnected if env.get("not_connected") else PTError)(env["bridge_error"])
+        return _unwrap(env)
+
+    async def _handle(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            head = await reader.readuntil(b"\r\n\r\n")
+            lines = head.decode("latin-1").split("\r\n")
+            method, target, _ = lines[0].split(" ", 2)
+            headers = {k.strip().lower(): v.strip() for k, v in
+                       (l.split(":", 1) for l in lines[1:] if ":" in l)}
+            n = int(headers.get("content-length", "0") or 0)
+            if n > MAX_BODY:
+                return await self._send(writer, 413, {"error": "too large"})
+            if "chunked" in headers.get("transfer-encoding", "").lower():
+                body = await _read_chunked(reader)
+            else:
+                body = await reader.readexactly(n) if n else b""
+            path = target.split("?", 1)[0]
+            if method == "OPTIONS":
+                return await self._send(writer, 204, None)
+            if path == "/ping":
+                return await self._send(writer, 200, self.status())
+            if path == "/hello":
+                from urllib.parse import parse_qs
+                q = parse_qs(target.split("?", 1)[1]) if "?" in target else {}
+                self._pt_info["webview"] = {k: v[0] for k, v in q.items()}
+                log.info("PT web view hello: %s", self._pt_info["webview"])
+                return await self._send(writer, 200, {"ok": True})
+            if path == "/poll":
+                return await self._poll(writer, target)
+            if path == "/result" and method == "POST":
+                self._last_seen = time.monotonic()
+                self._on_result(json.loads(body))
+                return await self._send(writer, 200, {"ok": True})
+            if path == "/exec" and method == "POST":
+                return await self._exec_for_relay(writer, json.loads(body))
+            if path == "/r":           # chunked GET result from the PT web view
+                self._last_seen = time.monotonic()
+                self._on_chunk(target)
+                return await self._send_raw(writer, 200, "application/javascript", b"0;")
+            if path == "/bridge.js":
+                js = _bridge_js().replace("__PORT__", str(self.port)).replace("__BUILD__", _bridge_build())
+                return await self._send_raw(writer, 200, "application/javascript", js.encode())
+            if path == "/log":
+                log.info("PT web view: %s", target)
+                return await self._send(writer, 200, {"ok": True})
+            if path in ("/", "/bridge"):
+                return await self._send_raw(writer, 200, "text/html; charset=utf-8",
+                                            _bridge_page(self.port).encode())
+            await self._send(writer, 404, {"error": "not found"})
+        except (asyncio.IncompleteReadError, ConnectionError):
+            pass
+        except Exception as e:  # pragma: no cover - defensive
+            log.exception("http handler failed")
+            try:
+                await self._send(writer, 500, {"error": str(e)})
+            except Exception:
+                pass
+        finally:
+            try:
+                writer.close()
+            except Exception:
+                pass
+
+    async def _poll(self, writer: asyncio.StreamWriter, target: str) -> None:
+        self._last_seen = time.monotonic()
+        q: dict[str, str] = {}
+        if "?" in target:
+            from urllib.parse import parse_qs
+            q = {k: v[0] for k, v in parse_qs(target.split("?", 1)[1]).items()}
+            if q.get("pt"):
+                self._pt_info.update({"version": q.get("pt"), "session": q.get("s")})
+        try:
+            job = await asyncio.wait_for(self._queue.get(), POLL_HOLD_S)
+        except asyncio.TimeoutError:
+            self._last_seen = time.monotonic()
+            return await self._reply_poll(writer, q, {"id": 0})
+        if job.future.done():          # caller gave up while queued
+            return await self._reply_poll(writer, q, {"id": 0})
+        job.picked.set()
+        self._last_seen = time.monotonic()
+        try:
+            await self._reply_poll(writer, q, {"id": job.id, "code": job.code})
+        except ConnectionError:
+            await self._queue.put(job)  # web view vanished mid-poll; retry on next poll
+
+    async def _reply_poll(self, writer, q: dict, obj: dict) -> None:
+        cb = q.get("cb", "")
+        if cb and cb.replace("_", "").isalnum():   # JSONP for the PT web view
+            body = f"{cb}({json.dumps({**obj, 'build': _bridge_build()})});".encode()
+            return await self._send_raw(writer, 200, "application/javascript", body)
+        await self._send(writer, 200, obj)
+
+    def _on_chunk(self, target: str) -> None:
+        from urllib.parse import parse_qs
+        q = {k: v[0] for k, v in parse_qs(target.split("?", 1)[1], keep_blank_values=True).items()}
+        jid, i, n = int(q["id"]), int(q["i"]), int(q["n"])
+        parts = self._chunks.setdefault(jid, {})
+        parts[i] = q.get("d", "")
+        if len(parts) == n:
+            del self._chunks[jid]
+            self._on_result(json.loads("".join(parts[k] for k in range(n))))
+
+    def _on_result(self, msg: dict) -> None:
+        job = self._inflight.get(int(msg.get("id", 0)))
+        if job and not job.future.done():
+            job.future.set_result(msg)
+
+    async def _exec_for_relay(self, writer, req: dict) -> None:
+        try:
+            value = await self._submit(req["code"], float(req.get("timeout", 60)))
+            await self._send(writer, 200, {"ok": True, "value": value})
+        except NotConnected as e:
+            await self._send(writer, 200, {"bridge_error": str(e), "not_connected": True})
+        except PTError as e:
+            await self._send(writer, 200, {"bridge_error": str(e)})
+
+    async def _send(self, writer, status: int, obj: Any) -> None:
+        body = b"" if obj is None else json.dumps(obj).encode()
+        await self._send_raw(writer, status, "application/json", body)
+
+    async def _send_raw(self, writer, status: int, ctype: str, body: bytes) -> None:
+        reason = {200: "OK", 204: "No Content", 404: "Not Found", 413: "Too Large",
+                  500: "Error"}.get(status, "OK")
+        hdr = (f"HTTP/1.1 {status} {reason}\r\nContent-Type: {ctype}\r\n"
+               f"Content-Length: {len(body)}\r\nAccess-Control-Allow-Origin: *\r\n"
+               "Access-Control-Allow-Headers: *\r\nAccess-Control-Allow-Methods: GET, POST, OPTIONS\r\n"
+               "Cache-Control: no-store\r\nConnection: close\r\n\r\n")
+        writer.write(hdr.encode() + body)
+        await writer.drain()
+
+
+async def _read_chunked(reader: asyncio.StreamReader) -> bytes:
+    body = bytearray()
+    while True:
+        size = int((await reader.readline()).split(b";")[0].strip() or b"0", 16)
+        if size == 0:
+            await reader.readline()
+            return bytes(body)
+        if len(body) + size > MAX_BODY:
+            raise ConnectionError("body too large")
+        body += await reader.readexactly(size)
+        await reader.readline()
+
+
+def _unwrap(env: dict) -> Any:
+    """PT side replies {ok, value} or {ok:false, error, line}."""
+    if isinstance(env, str):
+        env = json.loads(env)
+    if env.get("ok"):
+        return env.get("value")
+    msg = env.get("error") or "unknown Packet Tracer error"
+    if env.get("line"):
+        msg += f" (line {env['line']})"
+    raise PTError(msg)
+
+
+def _bridge_page(port: int) -> str:
+    return resources.files("tracerlab").joinpath("js/bridge.html").read_text().replace("__PORT__", str(port))

tracerlab/catalog.py

@@ -0,0 +1,230 @@
+"""Device, module and cable catalog for PT 9. Type codes are the DeviceType enum."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# DeviceType enum (PT 8.2+/9.0)
+ROUTER, SWITCH, CLOUD, BRIDGE, HUB, REPEATER, SPLITTER, ACCESS_POINT, PC, SERVER, PRINTER = range(11)
+WIRELESS_ROUTER, IP_PHONE, DSL_MODEM, CABLE_MODEM, REMOTE_NET, L3_SWITCH = 11, 12, 13, 14, 15, 16
+SWITCH_3650, LAPTOP, TABLET, PDA, WIRELESS_END, WIRED_END, TV, HOME_VOIP, ANALOG_PHONE = 17, 18, 19, 20, 21, 22, 23, 24, 25
+ASA, IOE, HOME_GATEWAY, CELL_TOWER, CO_SERVER, SNIFFER, MCU, SBC, THING = 27, 28, 29, 31, 32, 35, 36, 37, 38
+EMBEDDED_SERVER, WLC, LAP, MERAKI_MX, MERAKI_SERVER, NET_CONTROLLER = 40, 41, 44, 48, 49, 50
+
+TYPE_NAMES = {
+    0: "router", 1: "switch", 2: "cloud", 3: "bridge", 4: "hub", 5: "repeater", 6: "coax-splitter",
+    7: "access-point", 8: "pc", 9: "server", 10: "printer", 11: "wireless-router", 12: "ip-phone",
+    13: "dsl-modem", 14: "cable-modem", 15: "remote-network", 16: "l3-switch", 17: "l3-switch",
+    18: "laptop", 19: "tablet", 20: "smartphone", 21: "wireless-end-device", 22: "wired-end-device",
+    23: "tv", 24: "home-voip", 25: "analog-phone", 26: "multiuser", 27: "asa", 28: "iot",
+    29: "home-gateway", 30: "home-router", 31: "cell-tower", 32: "central-office-server",
+    33: "cisco-ap", 34: "embedded-ap", 35: "sniffer", 36: "mcu", 37: "sbc", 38: "thing",
+    40: "embedded-server", 41: "wlc", 44: "lightweight-ap", 45: "power-distribution",
+    46: "patch-panel", 47: "wall-mount", 48: "meraki-mx", 49: "meraki-server", 50: "network-controller",
+}
+
+CLI_TYPES = {0, 1, 16, 17, 27}            # devices with an IOS/ASA CLI
+HOST_TYPES = {8, 9, 10, 18, 19, 20, 21, 22, 12}  # devices configured through IP settings
+L2_TYPES = {1, 4, 3, 5, 7, 33, 44}        # forward frames without routing (switch-like)
+L3_SWITCH_TYPES = {16, 17}
+
+
+def _r(n):
+    return [f"GigabitEthernet0/{i}" for i in range(n)]
+
+
+@dataclass(frozen=True)
+class Model:
+    model: str
+    types: tuple[int, ...]
+    role: str
+    ports: tuple[str, ...] = ()
+    slots: str = ""
+    notes: str = ""
+    aliases: tuple[str, ...] = field(default=())
+
+
+def _fa(prefix, a, b):
+    return tuple(f"{prefix}{i}" for i in range(a, b + 1))
+
+
+MODELS: dict[str, Model] = {m.model.lower(): m for m in [
+    # routers
+    Model("1941", (ROUTER,), "router", ("GigabitEthernet0/0", "GigabitEthernet0/1"),
+          "2x EHWIC: slot 0/0 and 0/1 (HWIC-2T serial, HWIC-4ESW, EHWIC-...)", "Classic CCNA lab router; IOS 15.1.", ("r1941",)),
+    Model("2901", (ROUTER,), "router", ("GigabitEthernet0/0", "GigabitEthernet0/1"),
+          "4x EHWIC (0/0..0/3)", "Like 1941 with more slots."),
+    Model("2911", (ROUTER,), "router", ("GigabitEthernet0/0", "GigabitEthernet0/1", "GigabitEthernet0/2"),
+          "4x EHWIC (0/0..0/3), 1x SM", "Best default router: 3 gig ports, security + voice licenses.", ("router", "r2911")),
+    Model("ISR4321", (ROUTER,), "router", ("GigabitEthernet0/0/0", "GigabitEthernet0/0/1"),
+          "2x NIM (0/1, 0/2) e.g. NIM-2T", "IOS-XE; port names have three parts.", ("4321",)),
+    Model("ISR4331", (ROUTER,), "router", ("GigabitEthernet0/0/0", "GigabitEthernet0/0/1", "GigabitEthernet0/0/2"),
+          "3x NIM (0/1..0/3)", "IOS-XE; current CCNA curriculum router.", ("4331",)),
+    Model("1841", (ROUTER,), "router", ("FastEthernet0/0", "FastEthernet0/1"), "2x HWIC/WIC (0/0, 0/1)",
+          "Old 12.4 router; FastEthernet only."),
+    Model("2811", (ROUTER,), "router", ("FastEthernet0/0", "FastEthernet0/1"), "4x HWIC, 1x NM",
+          "Old 12.4 router."),
+    Model("2620XM", (ROUTER,), "router", ("FastEthernet0/0",), "1x NM, 2x WIC", "Legacy."),
+    Model("2621XM", (ROUTER,), "router", ("FastEthernet0/0", "FastEthernet0/1"), "1x NM, 2x WIC", "Legacy."),
+    Model("819HGW", (ROUTER,), "router", (), "", "Integrated 4G/wifi router."),
+    Model("829", (ROUTER,), "router", (), "", "Industrial ISR."),
+    Model("CGR1240", (ROUTER,), "router", (), "", "Connected grid router."),
+    Model("IR8340", (ROUTER,), "router", (), "", "Industrial router (PT 9)."),
+    Model("PT8200", (ROUTER,), "router", (), "", "PT 9 generic modern router."),
+    Model("Router-PT", (ROUTER,), "router",
+          ("FastEthernet0/0", "FastEthernet1/0", "Serial2/0", "Serial3/0", "FastEthernet4/0", "FastEthernet5/0"),
+          "10 PT-ROUTER-NM slots", "Generic router with built-in serial ports: quickest for serial WAN labs."),
+    Model("Router-PT-Empty", (ROUTER,), "router", (), "10 empty PT-ROUTER-NM slots", "Generic, no interfaces."),
+    # switches
+    Model("2960-24TT", (SWITCH,), "switch", _fa("FastEthernet0/", 1, 24) + ("GigabitEthernet0/1", "GigabitEthernet0/2"),
+          "", "Default access switch: 24 Fa + 2 Gi uplinks.", ("switch", "2960")),
+    Model("2950-24", (SWITCH,), "switch", _fa("FastEthernet0/", 1, 24), "", "Legacy L2."),
+    Model("2950T-24", (SWITCH,), "switch", _fa("FastEthernet0/", 1, 24) + ("GigabitEthernet0/1", "GigabitEthernet0/2"), "", "Legacy L2."),
+    Model("Switch-PT", (SWITCH,), "switch", ("FastEthernet0/1", "FastEthernet1/1", "FastEthernet2/1", "FastEthernet3/1",
+                                               "FastEthernet4/1", "FastEthernet5/1"), "10 PT-SWITCH-NM slots", "Generic."),
+    Model("Switch-PT-Empty", (SWITCH,), "switch", (), "", "Generic, no interfaces."),
+    Model("IE-2000", (L3_SWITCH, SWITCH), "switch", (), "", "Industrial Ethernet switch."),
+    Model("3560-24PS", (L3_SWITCH,), "l3-switch", _fa("FastEthernet0/", 1, 24) + ("GigabitEthernet0/1", "GigabitEthernet0/2"),
+          "", "Layer-3 switch: SVIs, ip routing, EtherChannel, HSRP. Use for inter-VLAN routing.", ("multilayer", "l3switch", "3560")),
+    Model("3650-24PS", (SWITCH_3650, L3_SWITCH), "l3-switch",
+          tuple(f"GigabitEthernet1/0/{i}" for i in range(1, 25)) + tuple(f"GigabitEthernet1/1/{i}" for i in range(1, 5)),
+          "1 uplink module slot", "IOS-XE L3 switch. Ships WITHOUT a power supply in PT: add AC-POWER-SUPPLY.", ("3650",)),
+    # end devices
+    Model("PC-PT", (PC,), "host", ("FastEthernet0",), "1 host NM slot", "Desktop PC.", ("pc",)),
+    Model("Laptop-PT", (LAPTOP,), "host", ("FastEthernet0",), "1 laptop NM slot (swap for WPC300N for wifi)", "", ("laptop",)),
+    Model("Server-PT", (SERVER,), "host", ("FastEthernet0",), "", "DHCP/DNS/HTTP/FTP/Email/AAA/NTP/Syslog services.", ("server",)),
+    Model("Printer-PT", (PRINTER,), "host", ("FastEthernet0",), "", "", ("printer",)),
+    Model("TabletPC-PT", (TABLET,), "host", ("Wireless0",), "", "Wireless by default.", ("tablet",)),
+    Model("SMARTPHONE-PT", (PDA,), "host", ("Wireless0",), "", "Wireless + 3G/4G.", ("smartphone", "phone-pt")),
+    Model("7960", (IP_PHONE,), "host", ("Switch", "PC"), "", "Cisco IP phone; needs power adapter or PoE + voice VLAN.", ("ipphone",)),
+    Model("TV-PT", (TV,), "host", (), "", ""),
+    Model("WirelessEndDevice-PT", (WIRELESS_END,), "host", (), "", ""),
+    Model("WiredEndDevice-PT", (WIRED_END,), "host", (), "", ""),
+    Model("Sniffer", (SNIFFER,), "host", (), "", "Captures traffic on a link."),
+    # other
+    Model("Hub-PT", (HUB,), "hub", (), "", "", ("hub",)),
+    Model("Repeater-PT", (REPEATER,), "hub", (), "", ""),
+    Model("Bridge-PT", (BRIDGE,), "switch", (), "", ""),
+    Model("AccessPoint-PT", (ACCESS_POINT,), "ap", (), "", "Autonomous AP (802.11g)."),
+    Model("AccessPoint-PT-N", (ACCESS_POINT,), "ap", (), "", "802.11n AP."),
+    Model("AccessPoint-PT-AC", (ACCESS_POINT,), "ap", (), "", "802.11ac AP."),
+    Model("Linksys-WRT300N", (WIRELESS_ROUTER,), "wireless-router", (), "", "Home wireless router with GUI config."),
+    Model("HomeRouter-PT-AC", (30,), "wireless-router", (), "", ""),
+    Model("WLC-2504", (WLC,), "wlc", (), "", "Wireless LAN controller."),
+    Model("WLC-3504", (WLC,), "wlc", (), "", ""),
+    Model("LAP-PT", (LAP,), "ap", (), "", "Lightweight AP (needs WLC)."),
+    Model("3702i", (LAP,), "ap", (), "", "Lightweight AP."),
+    Model("5506-X", (ASA,), "firewall", tuple(f"GigabitEthernet1/{i}" for i in range(1, 9)), "",
+          "ASA firewall (ASA OS CLI, not IOS).", ("asa",)),
+    Model("5505", (ASA,), "firewall", tuple(f"Ethernet0/{i}" for i in range(0, 8)), "", "Legacy ASA with switch ports."),
+    Model("Cloud-PT", (CLOUD,), "cloud", (), "", "WAN cloud (frame relay / DSL / cable)."),
+    Model("DSL-Modem-PT", (DSL_MODEM,), "modem", (), "", ""),
+    Model("Cable-Modem-PT", (CABLE_MODEM,), "modem", (), "", ""),
+    Model("Cell-Tower", (CELL_TOWER,), "cellular", (), "", ""),
+    Model("Central-Office-Server", (CO_SERVER,), "cellular", (), "", ""),
+    Model("Meraki-MX65W", (MERAKI_MX,), "firewall", (), "", ""),
+    Model("NetworkController", (NET_CONTROLLER,), "controller", (), "", "SDN controller with REST API."),
+    Model("MCU-PT", (MCU,), "iot", (), "", "Microcontroller (programmable)."),
+    Model("SBC-PT", (SBC,), "iot", (), "", "Single-board computer (programmable)."),
+]}
+
+ALIASES = {a.lower(): m for m in MODELS.values() for a in m.aliases}
+
+
+def resolve_model(name: str) -> Model:
+    key = name.strip().lower()
+    if key in MODELS:
+        return MODELS[key]
+    if key in ALIASES:
+        return ALIASES[key]
+    # anything else: try it as an IoE thing
+    raise KeyError(name)
+
+
+def model_or_passthrough(name: str) -> tuple[str, list[int]]:
+    """Return (exact PT model name, type codes to try)."""
+    try:
+        m = resolve_model(name)
+        return m.model, list(m.types)
+    except KeyError:
+        return name, [THING, IOE, 39]
+
+
+# module type codes (PT ModuleType enum)
+MODULE_TYPES: dict[str, int] = {}
+for _names, _code in [
+    ("NM-1E NM-1E2W NM-1FE-FX NM-1FE-TX NM-1FE2W NM-2E2W NM-2FE2W NM-2W NM-4A/S NM-4E NM-8A/S NM-8AM NM-Cover NM-ESW-161", 1),
+    ("1240-Cellular 1240-Cover HWIC-1GE-SFP HWIC-2T HWIC-4ESW HWIC-8A HWIC-AP-AG-B NIM-2T NIM-Cover NIM-ES2-4 "
+     "WIC-1AM WIC-1ENET WIC-1T WIC-2AM WIC-2T WIC-Cover", 2),
+    ("PT-ROUTER-NM-1AM PT-ROUTER-NM-1CE PT-ROUTER-NM-1CFE PT-ROUTER-NM-1CGE PT-ROUTER-NM-1FFE PT-ROUTER-NM-1FGE "
+     "PT-ROUTER-NM-1S PT-ROUTER-NM-1SS PT-ROUTER-NM-COVER", 3),
+    ("AC-POWER-SUPPLY POWER-COVER-PLATE PT-SWITCH-NM-1CE PT-SWITCH-NM-1CFE PT-SWITCH-NM-1CGE PT-SWITCH-NM-1FFE "
+     "PT-SWITCH-NM-1FGE PT-SWITCH-NM-COVER", 4),
+    ("PT-CLOUD-NM-1AM PT-CLOUD-NM-1CE PT-CLOUD-NM-1CFE PT-CLOUD-NM-1CGE PT-CLOUD-NM-1FFE PT-CLOUD-NM-1FGE PT-CLOUD-NM-1S", 5),
+    ("PT-REPEATER-NM-1CE PT-REPEATER-NM-1CFE PT-REPEATER-NM-1CGE PT-REPEATER-NM-1FFE PT-REPEATER-NM-1FGE PT-REPEATER-NM-COVER", 6),
+    ("Linksys-WMP300N PT-HOST-NM-1AM PT-HOST-NM-1CE PT-HOST-NM-1CFE PT-HOST-NM-1CGE PT-HOST-NM-1FFE PT-HOST-NM-1FGE "
+     "PT-HOST-NM-1W PT-HOST-NM-1W-A PT-HOST-NM-1W-AC PT-HOST-NM-3G/4G PT-HOST-NM-COVER", 7),
+    ("PT-MODEM-NM-1CE PT-MODEM-NM-1CFE PT-MODEM-NM-1CGE", 8),
+    ("Linksys-WPC300N PT-LAPTOP-NM-1AM PT-LAPTOP-NM-1CE PT-LAPTOP-NM-1CFE PT-LAPTOP-NM-1CGE PT-LAPTOP-NM-1FFE "
+     "PT-LAPTOP-NM-1FGE PT-LAPTOP-NM-1W PT-LAPTOP-NM-1W-A PT-LAPTOP-NM-1W-AC PT-LAPTOP-NM-3G/4G", 9),
+    ("IP_PHONE_POWER_ADAPTER", 11),
+    ("PT-HEADPHONE PT-MICROPHONE", 16),
+    ("ASA-Cover", 19),
+    ("PT-CELL-NM-1CX PT-CELL-NM-3G/4G", 21),
+    ("PT-IOT-CUSTOM-IO", 26),
+    ("PT-IOT-POWER-ADAPTER", 27),
+    ("PT-UNV-PWR-ADAPTER", 28),
+    ("ROUTER-ADAPTER", 29),
+    ("GLC-FE-100FX-RGD GLC-GE-100FX GLC-LH-SMD GLC-T GLC-TE", 30),
+    ("ACCESS_POINT_POWER_ADAPTER", 31),
+    ("C3650-BUILTIN C3650-SFP-BUILTIN ISR4321-BUILTIN ISR4331-BUILTIN PT-CONTROLLER-BUILTIN", 32),
+    ("MERAKI-POWER-ADAPTER", 34),
+]:
+    for _n in _names.split():
+        MODULE_TYPES.setdefault(_n, _code)
+
+MODULE_NOTES = {
+    "HWIC-2T": "2 smart-serial WAN ports for 1941/2901/2911 (slot 0/0..0/3) -> Serial0/0/0, Serial0/0/1",
+    "WIC-2T": "2 serial ports for 1841/2811 -> Serial0/0/0, Serial0/0/1",
+    "NIM-2T": "2 serial ports for ISR4321/4331 (slot 0/1, 0/2) -> Serial0/1/0, Serial0/1/1",
+    "HWIC-4ESW": "4-port switch module (VLAN-capable) for ISR G2",
+    "NIM-ES2-4": "4-port switch module for ISR4K",
+    "HWIC-1GE-SFP": "1 SFP gigabit port",
+    "NM-1FE-TX": "1 FastEthernet for 2811/2620",
+    "PT-ROUTER-NM-1S": "1 serial port for Router-PT",
+    "PT-ROUTER-NM-1CGE": "1 copper gig for Router-PT",
+    "AC-POWER-SUPPLY": "power supply for 3650-24PS (slot is the PSU bay)",
+    "Linksys-WPC300N": "wireless NIC for Laptop-PT/PC-PT (replace the wired NM)",
+    "PT-HOST-NM-1W-AC": "802.11ac NIC for PC/Laptop",
+}
+
+CABLES = {
+    "auto": "PT picks the right copper/serial cable (default)",
+    "straight": "copper straight-through: unlike devices (PC-switch, router-switch)",
+    "cross": "copper crossover: like devices (switch-switch, router-router, PC-PC, router-PC)",
+    "serial": "serial DCE/DTE (first device is DCE -> set clock rate there)",
+    "fiber": "fiber between fiber/SFP ports",
+    "console": "rollover console cable PC RS232 -> device Console",
+    "roll": "rollover", "phone": "RJ11 phone", "coaxial": "coax", "usb": "usb", "wireless": "wireless",
+    "octal": "octal", "cellular": "cellular", "cable": "cable modem",
+}
+
+
+def catalog_text(category: str | None = None) -> str:
+    rows = []
+    for m in MODELS.values():
+        if category and category.lower() not in (m.role, TYPE_NAMES.get(m.types[0], "")):
+            continue
+        ports = ""
+        if m.ports:
+            ports = (", ".join(m.ports) if len(m.ports) <= 6
+                     else f"{m.ports[0]}..{m.ports[-1]} ({len(m.ports)} ports)")
+        line = f"{m.model} [{m.role}]"
+        if ports:
+            line += f" ports: {ports}"
+        if m.slots:
+            line += f" | slots: {m.slots}"
+        if m.notes:
+            line += f" | {m.notes}"
+        rows.append(line)
+    return "\n".join(rows)