yrcom 0.2.0__py3-none-any.whl

yrcom/hses_errors.py

@@ -0,0 +1,190 @@
+"""
+HSES response-code plaintext lookup (HW1483358 Section 3.4).
+
+The YRC1000 answers every request with a one-byte *status* code and, when the
+status is non-zero, an *added-status* word carrying the real reason. Both are
+otherwise opaque hex numbers; this module maps them to the descriptions from
+the official manual so HsesError messages read like
+``... status=0x1F (Vendor-specific error) added=0x2080 (Incorrect mode)``.
+
+Descriptions are kept in English to match the codebase standard and the
+Yaskawa manual terminology.
+"""
+
+# 4.1 Status-Code (3.4.1)
+STATUS_CODES: dict[int, str] = {
+    0x00: "Success",
+    # 0x01 is not in the 3.4.1 table but is what a live YRC1000 (YAS5.40) returns
+    # for almost every rejected/unavailable request — with added-status 0x0000
+    # instead of the documented specific codes. Observed for: undefined position
+    # variable (P/BP/EX not created), empty file-list filter, missing file,
+    # write_file/delete_file in PLAY mode, and move commands in the wrong state
+    # (TEACH / servo-off / robot+station together — no 0xB008). Treat as a generic
+    # "request not executable in the current state / resource does not exist".
+    0x01: "Request not executable in current state / data not present",
+    0x08: "Requested command is undefined",
+    0x09: "Invalid element number detected",
+    0x1F: "Vendor-specific error (see added status)",
+    0x28: "Instance of the requested data does not exist in the command",
+}
+
+# 4.2 Added-Status-Code (3.4.2) — WORD values, hex.
+ADDED_STATUS_CODES: dict[int, str] = {
+    0x1010: "Command error",
+    0x1011: "Error in number of command operands",
+    0x1012: "Command operand value out of range",
+    0x1013: "Command operand length error",
+    0x1020: "Disk full",
+    0x2010: "Manipulator is moving",
+    0x2020: "Hold by programming pendant",
+    0x2030: "Hold by playback panel",
+    0x2040: "External hold",
+    0x2050: "Command hold",
+    0x2060: "Error/alarm active",
+    0x2070: "Servo OFF",
+    0x2080: "Incorrect mode",
+    0x2090: "File is used by another function",
+    0x2100: "Command remote not set",
+    0x2110: "This data cannot be accessed",
+    0x2120: "This data cannot be loaded",
+    0x2130: "Editing",
+    0x2150: "Coordinate conversion in progress",
+    0x3010: "Turn on the servo",
+    0x3040: "Perform home positioning",
+    0x3050: "Confirm positions",
+    0x3070: "Current value not created",
+    0x3220: "Panel lock; mode/cycle prohibit signal ON",
+    0x3230: "Panel lock; start prohibit signal ON",
+    0x3350: "User coordinate not taught",
+    0x3360: "User coordinate destroyed",
+    0x3370: "Incorrect control group",
+    0x3380: "Incorrect base axis data",
+    0x3390: "Relative job conversion prohibited (CVTRJ)",
+    0x3400: "Master job call prohibited (parameter)",
+    0x3410: "Master job call prohibited (lamp ON during operation)",
+    0x3420: "Master job call prohibited (teach lock)",
+    0x3430: "Robot calibration data undefined",
+    0x3450: "Servo cannot be turned on",
+    0x3460: "Coordinate system cannot be set",
+    0x4010: "Insufficient memory (job registration memory)",
+    0x4012: "Insufficient memory (position data memory)",
+    0x4020: "Job editing prohibited",
+    0x4030: "Job with same name exists",
+    0x4040: "No specified job",
+    0x4060: "Set an execution job",
+    0x4120: "Position data destroyed",
+    0x4130: "Position data does not exist",
+    0x4140: "Incorrect position variable type",
+    0x4150: "END instruction for a non-master job",
+    0x4170: "Instruction data destroyed",
+    0x4190: "Invalid character in job name",
+    0x4200: "Invalid character in label name",
+    0x4230: "Invalid instruction in this system",
+    0x4420: "No step in the job to convert",
+    0x4430: "Already converted",
+    0x4480: "Teach the user coordinate",
+    0x4490: "Relative job / independent control function not allowed",
+    0x5110: "Syntax error (instruction syntax)",
+    0x5120: "Position data error",
+    0x5130: "No NOP or END",
+    0x5170: "Format error",
+    0x5180: "Incorrect data count",
+    0x5200: "Data range exceeded",
+    0x5310: "Syntax error (other than instruction)",
+    0x5340: "Error in pseudo-instruction specification",
+    0x5370: "Error in condition-file record",
+    0x5390: "Error in JOB record",
+    0x5430: "System data not identical",
+    0x5480: "Incorrect welding-function type",
+    0x6010: "Robot/station in operation",
+    0x6020: "Insufficient memory in the specified device",
+    0x6030: "Cannot access the specified device",
+    0x6040: "Unexpected auto-backup request",
+    0x6050: "CMOS size exceeds RAM area",
+    0x6060: "No memory allocation at power-on",
+    0x6070: "Backup-file info access error",
+    0x6080: "Backup-file sorting failed (remove)",
+    0x6090: "Backup-file sorting failed (rename)",
+    0x6100: "Drive name exceeds limit",
+    0x6110: "Incorrect device",
+    0x6120: "System error",
+    0x6130: "Auto-backup not available",
+    0x6140: "Cannot back up during auto-backup",
+    0xA000: "Undefined command",
+    0xA001: "Instance error",
+    0xA002: "Attribute error",
+    0xA100: "Response data-part size error (hardware limit)",
+    0xA101: "Response data-part size error (software limit)",
+    0xB001: "Undefined position variable",
+    0xB002: "Data use prohibited",
+    0xB003: "Requested data size incorrect",
+    0xB004: "Out of data range",
+    0xB005: "Data undefined",
+    0xB006: "Specified application not registered",
+    0xB007: "Specified type not registered",
+    0xB008: "Control-group setting error",
+    0xB009: "Speed setting error",
+    0xB00A: "Operation speed not set",
+    0xB00B: "Operation coordinate-system setting error",
+    0xB00C: "Type setting error",
+    0xB00D: "Tool-No setting error",
+    0xB00E: "User-No setting error",
+    0xC001: "System error (data-area setting)",
+    0xC002: "System error (over response data area)",
+    0xC003: "System error (data-element size mismatch)",
+    0xC800: "System error (customize API)",
+    0xCFFF: "Other error",
+    0xD8FA: "Transmission exclusive error (busy or semaphore)",
+    0xD8F1: "Processing another command (busy)",
+    0xE24F: "Incorrect parameter setting for system backup",
+    0xE250: "System-backup file creation error (check remote mode)",
+    0xE289: "System error",
+    0xE28A: "System error",
+    0xE28B: "Communication disconnected due to receive timeout",
+    0xE28C: "Target file cannot be overwritten",
+    0xE29C: "Requested file does not exist or size is 0",
+    0xE29D: "System error",
+    0xE29E: "System error",
+    0xE29F: "System error",
+    0xE2A0: "Incorrect requested path",
+    0xE2A7: "Relevant file not in the requested file list",
+    0xE2AA: "System error",
+    0xE2AF: "Delete request for a non-deletable file",
+    0xE2B0: "System error",
+    0xE2B1: "Directory cannot be deleted",
+    0xE2B2: "Send/receive request while remote is OFF",
+    0xE2B3: "File not found",
+    0xE2B4: "Requested path too long",
+    0xE444: "Processing another command (busy)",
+    0xE49D: "Format error (data size 0)",
+    0xE49E: "Format error (frame size over)",
+    0xE49F: "Format error (frame size 0)",
+    0xE4A1: "Format error (block-number error)",
+    0xE4A2: "Format error (ACK error)",
+    0xE4A3: "Format error (processing-category error)",
+    0xE4A4: "Format error (access-level error)",
+    0xE4A5: "Format error (header-size error)",
+    0xE4A6: "Format error (identifier error)",
+    0xE4A7: "Format error (command and frame size differ)",
+    0xE4A8: "System error",
+    0xE4A9: "System error",
+    0xFFF0: "System error",
+    0xFFF2: "System error",
+    0xFFF3: "System error",
+    0xFFF4: "System error",
+    0xFFF5: "System error",
+    0xFFF6: "Too many requests, cannot process (busy)",
+    0xFFF7: "System error",
+    0xFFF8: "System error",
+    0xFFFE: "Remote mode detected, communication disconnected",
+}
+
+
+def status_text(status: int) -> str:
+    """Description for a status code, or 'Unknown status' if not listed."""
+    return STATUS_CODES.get(status, "Unknown status")
+
+
+def added_status_text(added: int) -> str:
+    """Description for an added-status word, or 'Unknown added status'."""
+    return ADDED_STATUS_CODES.get(added, "Unknown added status")

yrcom/hses_file.py

@@ -0,0 +1,234 @@
+"""
+Yaskawa YRC1000 — HSES File Control client.
+
+A separate transport from the telemetry client (`hses_client.HsesClient`):
+different UDP port (10041), Processing Division 2, and a multi-packet Data/ACK
+handshake instead of a single request/response. The sub-header carries a fixed
+Command/Instance/Attribute of 0 — the operation is chosen by the Service byte
+alone (0x09 delete, 0x15 load, 0x16 save, 0x32 list). See manual HW1483358
+(File Control Function).
+
+File transfers are chunked into <=479-byte data parts. Each data packet's Block
+No. increments; the final packet is flagged with bit 0x8000_0000. The receiving
+side acknowledges every data packet with an empty ACK (echoing the block number)
+before the next one is sent.
+
+Command Remote (RS 005 = 1) is required for write/delete/transfer access.
+"""
+from __future__ import annotations
+
+import logging
+import struct
+from typing import Optional
+
+from .hses_client import _MAGIC, _HDR_SIZE, HsesError, _HsesSocket
+
+# Diagnostic trace of the file-control layer (Roadmap I convention); the library
+# only emits, the app configures handlers. Requests/ACKs → DEBUG, file operations
+# → INFO, robot errors / malformed replies → ERROR.
+log = logging.getLogger(__name__)
+
+HSES_FILE_PORT = 10041
+_PROC_FILE     = 2         # processing division: file control
+
+# Service bytes (the sub-header Command/Instance/Attribute are all 0)
+_SVC_DELETE = 0x09         # File Deleting        (no transfer)
+_SVC_LOAD   = 0x15         # File Loading         PC  -> YRC (write a file)
+_SVC_SAVE   = 0x16         # File Saving          YRC -> PC (read a file)
+_SVC_LIST   = 0x32         # File List            YRC -> PC
+
+_ACK_REQUEST = 0x00        # header offset 10: this packet is a request
+_ACK_ANSWER  = 0x01        # this packet is an answer / acknowledgement
+_LAST_BLOCK  = 0x8000_0000 # block-no bit marking the final packet
+_MAX_DATA    = 479         # max data-part size per packet
+
+_CMOS_PATH = "/SPDRV/CMOSBK.BIN"   # batch CMOS backup (Device = RAMDISK, ~10 min)
+
+
+class HsesFileClient(_HsesSocket):
+    """
+    UDP client for the Yaskawa YRC1000 HSES File Control port (10041).
+
+    Usage:
+        with HsesFileClient("192.0.2.10") as f:
+            for name in f.list_files("*.JBI"):
+                print(name)
+            data = f.read_file("TESTJOB.JBI")
+    """
+
+    def __init__(self, host: str, port: int = HSES_FILE_PORT, timeout: float = 5.0,
+                 bind_host: Optional[str] = None) -> None:
+        super().__init__(host, port, timeout, bind_host)
+
+    # ── packet building / parsing ─────────────────────────────────────────────
+
+    @staticmethod
+    def _build(service: int, req_id: int, block_no: int, ack: int,
+               payload: bytes = b"") -> bytes:
+        """Build a 32-byte File Control header (Command/Instance/Attribute = 0)."""
+        hdr = bytearray(_HDR_SIZE)
+        hdr[0:4] = _MAGIC
+        struct.pack_into("<H", hdr,  4, _HDR_SIZE)
+        struct.pack_into("<H", hdr,  6, len(payload))
+        hdr[8]  = 0x03                                  # Reserve1  FIXED
+        hdr[9]  = _PROC_FILE
+        hdr[10] = ack
+        hdr[11] = req_id
+        struct.pack_into("<I", hdr, 12, block_no & 0xFFFF_FFFF)
+        hdr[16:24] = b"99999999"                        # Reserve2  FIXED
+        struct.pack_into("<H", hdr, 24, 0)             # Command No. = 0
+        struct.pack_into("<H", hdr, 26, 0)             # Instance    = 0
+        hdr[28] = 0                                     # Attribute   = 0
+        hdr[29] = service
+        struct.pack_into("<H", hdr, 30, 0)             # Padding
+        return bytes(hdr) + payload
+
+    def _recv(self, req_service: int) -> tuple:
+        """
+        Receive one packet and parse it. Returns (block_no, data, added).
+        Raises HsesError on a non-zero status, IOError on a malformed reply.
+        The answer's status/added fields sit at the same offsets as the robot
+        control response (status raw[26], added-size raw[28], added raw[30]).
+        """
+        raw = self._sock.recv(4096)
+        if len(raw) < _HDR_SIZE:
+            log.error("malformed file reply svc=0x%02X: too short (%d B)",
+                      req_service, len(raw))
+            raise IOError(f"Response too short: {len(raw)} B")
+        if raw[0:4] != _MAGIC:
+            log.error("malformed file reply svc=0x%02X: bad magic %r",
+                      req_service, raw[0:4])
+            raise IOError(f"Bad magic: {raw[0:4]!r}")
+
+        dat_size    = struct.unpack_from("<H", raw,  6)[0]
+        block_no    = struct.unpack_from("<I", raw, 12)[0]
+        resp_status = raw[26]
+        added_size  = raw[28]
+        added       = struct.unpack_from("<H", raw, 30)[0] if added_size >= 1 else 0
+        data        = raw[_HDR_SIZE: _HDR_SIZE + dat_size]
+
+        if resp_status != 0x00:
+            log.error("file reply svc=0x%02X status=0x%02X added=0x%04X",
+                      req_service, resp_status, added)
+            raise HsesError(_PROC_FILE, resp_status, added)
+
+        return block_no, data, added
+
+    # ── receive transfer (File List 0x32, File Saving 0x16) ────────────────────
+
+    def _read_transfer(self, service: int, request_payload: bytes) -> bytes:
+        """
+        Run a YRC → PC transfer: send the request, then receive data packets,
+        acknowledging each, until the packet flagged with _LAST_BLOCK arrives.
+        Returns the concatenated data parts.
+
+        A status-0 reply carrying an added status (e.g. 0xE2A7 file not found,
+        0xE29C size 0) is treated as an empty result, not an error.
+        """
+        if self._sock is None:
+            raise RuntimeError("Call open() first")
+        rid = self._bump_req_id()
+        log.debug("file tx svc=0x%02X id=%d payload=%dB",
+                  service, rid, len(request_payload))
+        self._sock.sendto(self._build(service, rid, 0, _ACK_REQUEST, request_payload),
+                          (self._host, self._port))
+
+        chunks: list[bytes] = []
+        while True:
+            block_no, data, added = self._recv(service)
+            if added and not data:
+                log.warning("file svc=0x%02X id=%d empty (added=0x%04X)",
+                            service, rid, added)
+                return b""
+            chunks.append(data)
+            # Acknowledge this packet (empty data part, echo the block number).
+            self._sock.sendto(self._build(service, rid, block_no, _ACK_ANSWER),
+                              (self._host, self._port))
+            if block_no & _LAST_BLOCK:
+                break
+        out = b"".join(chunks)
+        log.debug("file rx svc=0x%02X id=%d total=%dB", service, rid, len(out))
+        return out
+
+    # ── send transfer (File Loading 0x15) ──────────────────────────────────────
+
+    def _write_transfer(self, service: int, request_payload: bytes,
+                        content: bytes) -> None:
+        """
+        Run a PC → YRC transfer: send the request, wait for the robot's ACK, then
+        send `content` as _MAX_DATA-sized data packets, waiting for an ACK after
+        each. The final packet is flagged with _LAST_BLOCK.
+        """
+        if self._sock is None:
+            raise RuntimeError("Call open() first")
+        rid = self._bump_req_id()
+        log.debug("file tx svc=0x%02X id=%d payload=%dB content=%dB",
+                  service, rid, len(request_payload), len(content))
+        self._sock.sendto(self._build(service, rid, 0, _ACK_REQUEST, request_payload),
+                          (self._host, self._port))
+        self._recv(service)   # robot acknowledges the request (raises on error)
+
+        parts = [content[i:i + _MAX_DATA] for i in range(0, len(content), _MAX_DATA)] or [b""]
+        for i, part in enumerate(parts):
+            last = i == len(parts) - 1
+            block_no = (i + 1) | (_LAST_BLOCK if last else 0)
+            self._sock.sendto(self._build(service, rid, block_no, _ACK_ANSWER, part),
+                              (self._host, self._port))
+            self._recv(service)   # robot acknowledges each data packet
+        log.debug("file tx svc=0x%02X id=%d done (%d packets)", service, rid, len(parts))
+
+    # ── public operations ──────────────────────────────────────────────────────
+
+    def list_files(self, pattern: str = "*.JBI") -> "list[str]":
+        """
+        File List (service 0x32). `pattern` filters by extension — e.g. *.JBI,
+        *.DAT, *.CND, *.PRM, *.SYS, *.LST; an empty/`*.*` filter lists jobs.
+        Returns the file names as a list (blank lines dropped).
+        """
+        log.info("file: list %r", pattern)
+        raw = self._read_transfer(_SVC_LIST, pattern.encode("ascii", errors="replace"))
+        text = raw.decode("latin-1", errors="replace")
+        return [line.strip() for line in text.split("\r\n") if line.strip()]
+
+    def read_file(self, name: str) -> bytes:
+        """
+        File Saving (service 0x16) — read a file from the controller (YRC → PC).
+        `name` is the file name as shown on the pendant (e.g. "TESTJOB.JBI").
+        Returns the raw file bytes (ASCII content with <CR><LF> line breaks).
+        """
+        log.info("file: read %r", name)
+        return self._read_transfer(_SVC_SAVE, name.encode("ascii", errors="replace"))
+
+    def write_file(self, name: str, content: bytes) -> None:
+        """
+        File Loading (service 0x15) — send a file to the controller (PC → YRC).
+        `name` is the target file name; `content` the raw file bytes (ASCII,
+        <CR><LF> line breaks). Requires Command Remote (RS 005 = 1).
+        """
+        log.info("file: write %r (%d B)", name, len(content))
+        self._write_transfer(_SVC_LOAD, name.encode("ascii", errors="replace"), content)
+
+    def delete_file(self, name: str) -> None:
+        """
+        File Deleting (service 0x09). Deletes `name` on the controller — a single
+        request/response, no transfer. Requires Command Remote (RS 005 = 1).
+        """
+        if self._sock is None:
+            raise RuntimeError("Call open() first")
+        log.info("file: delete %r", name)
+        rid = self._bump_req_id()
+        self._sock.sendto(
+            self._build(_SVC_DELETE, rid, 0, _ACK_REQUEST,
+                        name.encode("ascii", errors="replace")),
+            (self._host, self._port),
+        )
+        self._recv(_SVC_DELETE)   # raises HsesError on a non-zero status
+
+    def backup_cmos(self) -> bytes:
+        """
+        Batch CMOS backup — read the complete CMOSBK.BIN via File Saving (0x16).
+        The controller's Device must be RAMDISK and the transfer takes ~10 min,
+        so use a generous timeout. Returns the raw backup bytes.
+        """
+        log.info("file: CMOS batch backup %s", _CMOS_PATH)
+        return self._read_transfer(_SVC_SAVE, _CMOS_PATH.encode("ascii"))

yrcom/hses_sim.py

@@ -0,0 +1,173 @@
+"""
+HSES simulator — replays a recorded robot session (tx/rx wire pairs) as a
+UDP server so the **real** HsesClient can work against it offline.
+
+The server indexes the recorded request→response byte pairs. It ignores the
+request ID (header byte 11), which increments per call, and patches it back
+into the response — so the response matches any request regardless of the
+order in which the client asks. The exact wire bytes of the real controller
+are sent back, so the real parser in HsesClient runs unchanged.
+
+Usage:
+
+    # as a context manager (thread, ephemeral or fixed port)
+    from yrcom import HsesReplayServer, HsesClient
+    with HsesReplayServer.from_capture("captures/latest.json") as srv:
+        c = HsesClient("127.0.0.1", srv.port, 2.0); c.open()
+        print(c.read_status())        # real recorded response, offline
+
+    # or standalone on the default port 10040:
+    #   python -m yrcom.hses_sim captures/latest.json --port 10040
+
+Limits: this is a replay, not a state machine. A request not present in the
+capture is answered with HSES status 0x01 ("not executable") — the same reply
+the real controller gives for unknown/invalid reads. Writes change nothing; a
+subsequent read still returns the recorded value.
+"""
+from __future__ import annotations
+
+import json
+import socket
+import struct
+import threading
+from pathlib import Path
+from typing import Optional
+
+_HDR_SIZE = 0x0020
+_REQ_ID_OFF = 11        # header byte that increments per request
+_MAGIC = b"YERC"
+
+
+def _req_key(pkt: bytes) -> bytes:
+    """Canonical key of a request: request ID masked out."""
+    b = bytearray(pkt)
+    if len(b) > _REQ_ID_OFF:
+        b[_REQ_ID_OFF] = 0
+    return bytes(b)
+
+
+def _error_response(req: bytes, status: int = 0x01) -> bytes:
+    """Build a valid HSES error response (status != 0) to a request.
+
+    Mirrors the header, sets the ACK flag, status and empty data length —
+    exactly the shape the real controller sends for a non-executable read.
+    """
+    resp = bytearray(_HDR_SIZE)
+    if len(req) >= _HDR_SIZE:
+        resp[:] = req[:_HDR_SIZE]
+    else:
+        resp[0:4] = _MAGIC
+        struct.pack_into("<H", resp, 4, _HDR_SIZE)
+    struct.pack_into("<H", resp, 6, 0)   # data size = 0
+    resp[10] = 0x01                        # ACK = answer
+    resp[26] = status                      # status byte
+    resp[27] = 0
+    resp[28] = 0                           # added-status size
+    struct.pack_into("<H", resp, 30, 0)
+    return bytes(resp)
+
+
+class HsesReplayServer:
+    """UDP server that replays recorded HSES responses."""
+
+    def __init__(self, table: dict[bytes, bytes], host: str = "127.0.0.1",
+                 port: int = 0) -> None:
+        self._table = table
+        self._sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self._sock.bind((host, port))
+        self.host, self.port = self._sock.getsockname()
+        self._thread: Optional[threading.Thread] = None
+        self._running = False
+        self.hits = 0
+        self.misses = 0
+
+    # ── construction from a capture file ──────────────────────────────────────
+    @classmethod
+    def from_capture(cls, path: str | Path, host: str = "127.0.0.1",
+                     port: int = 0) -> "HsesReplayServer":
+        data = json.loads(Path(path).read_text())
+        table: dict[bytes, bytes] = {}
+        hses = data.get("hses", {})
+        for op in hses.get("ops", []):
+            for ex in op.get("wire", []):
+                tx, rx = ex.get("tx"), ex.get("rx")
+                if not tx or not rx:
+                    continue
+                table[_req_key(bytes.fromhex(tx))] = bytes.fromhex(rx)
+        if not table:
+            raise ValueError(f"no HSES wire data in {path}")
+        return cls(table, host, port)
+
+    # ── server loop ───────────────────────────────────────────────────────────
+    def _serve(self) -> None:
+        self._sock.settimeout(0.25)
+        while self._running:
+            try:
+                req, addr = self._sock.recvfrom(4096)
+            except socket.timeout:
+                continue
+            except OSError:
+                break
+            resp = self._table.get(_req_key(req))
+            if resp is None:
+                self.misses += 1
+                out = _error_response(req)
+            else:
+                self.hits += 1
+                out = bytearray(resp)
+                # patch the caller's request ID into the response
+                if len(req) > _REQ_ID_OFF and len(out) > _REQ_ID_OFF:
+                    out[_REQ_ID_OFF] = req[_REQ_ID_OFF]
+                out = bytes(out)
+            try:
+                self._sock.sendto(out, addr)
+            except OSError:
+                break
+
+    def start(self) -> "HsesReplayServer":
+        if self._running:
+            return self
+        self._running = True
+        self._thread = threading.Thread(target=self._serve, daemon=True)
+        self._thread.start()
+        return self
+
+    def stop(self) -> None:
+        self._running = False
+        if self._thread:
+            self._thread.join(timeout=1.0)
+        try:
+            self._sock.close()
+        except OSError:
+            pass
+
+    def __enter__(self) -> "HsesReplayServer":
+        return self.start()
+
+    def __exit__(self, *_exc) -> None:
+        self.stop()
+
+
+def _main() -> None:
+    import argparse
+
+    ap = argparse.ArgumentParser(description="HSES replay server from a capture file")
+    ap.add_argument("capture", nargs="?", default="captures/latest.json")
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--port", type=int, default=10040)
+    args = ap.parse_args()
+
+    srv = HsesReplayServer.from_capture(args.capture, args.host, args.port).start()
+    print(f"HSES simulator listening on {srv.host}:{srv.port} "
+          f"({len(srv._table)} responses from {args.capture})")
+    print("Stop with Ctrl-C")
+    try:
+        while True:
+            srv._thread.join(1.0)
+    except KeyboardInterrupt:
+        print(f"\nhits={srv.hits} misses={srv.misses}")
+        srv.stop()
+
+
+if __name__ == "__main__":
+    _main()