handover-check 0.1.0__tar.gz

handover_check-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleman Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

handover_check-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: handover-check
+Version: 0.1.0
+Summary: Test a conveyor station's AMR/AGV load-handover handshake over OPC UA before the robot arrives: plays the vehicle side, also the ways a vehicle fails, and reports rule by rule.
+Author: Suleman Ali
+License: MIT
+Project-URL: Repository, https://github.com/sulemanali5760/amr-station-handshake
+Keywords: agv,amr,plc,opc-ua,handshake,commissioning,conveyor,vda5050,intralogistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncua<3,>=1.1
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+# handover-check
+
+Test a conveyor station's **AMR/AGV load-handover handshake** before the robot arrives.
+
+The tool connects to the station PLC over OPC UA and plays the vehicle side: it requests a handover,
+docks, releases, and also does what vehicles do when things go wrong (goes silent, leaves mid-transfer,
+changes its mind). It checks the station's answers and response times against ten rules and reports
+rule by rule.
+
+```
+$ handover-check run opc.tcp://192.168.0.10:4840 --map station.yaml --station-is-safe
+
+[PASS] R1  Idle at rest: no output is on without a request
+           all outputs off for 1 s without a request
+[PASS] R2  StationReady follows AmrDockRequest in time, and nothing moves yet
+           StationReady 0.53 s after the request (limit 5 s)
+[PASS] R3  No transfer before AmrInPosition
+           no transfer for 1 s while the vehicle was not in position
+[PASS] R4  Transfer starts after AmrInPosition and completes; TransferActive is off when TransferDone is on
+           transfer started after 0.02 s and finished after 4.02 s
+[PASS] R5  Station returns to idle after the vehicle releases
+           station idle 0.03 s after the release (limit 3 s)
+[PASS] R6  A second handover works straight after the first
+           two handovers in a row completed
+[PASS] R7  A withdrawn request returns the station to idle without a transfer
+           station back to idle 0.02 s after the request was withdrawn
+[FAIL] R8  Heartbeat watchdog: a silent vehicle stops the transfer with a fault code
+           the vehicle went silent for 2 s during the transfer and the station carried on: Ready, TransferActive
+[SKIP] R9  Dropping the request acknowledges and clears a fault
+           could not bring the station into a fault to acknowledge (see R8): Ready, TransferActive
+[PASS] R10 The conveyor stops when the vehicle leaves its position
+           conveyor stopped 0.02 s after the vehicle left its position (limit 1 s; station: Fault(code 3))
+
+Station does NOT conform. 8 passed, 1 failed, 1 not testable.
+```
+
+*Real output, against the bundled reference station with its watchdog switched off; address changed.*
+
+## Why
+
+VDA 5050 covers fleet controller to vehicle and expressly leaves out "interfaces to peripheral
+equipment". The handshake between vehicle and conveyor is therefore written again in every project,
+by two teams, and its mistakes show up at commissioning with the robot standing in front of the
+station. The rules are written down in [docs/SPEC.md](../../docs/SPEC.md); this tool lets the PLC
+programmer test the station side alone, at the desk or on site, days earlier.
+
+## Install
+
+```bash
+pip install handover-check
+```
+
+Python 3.11 or newer; Windows or Linux. No ROS and no robot needed.
+Offline bundles for machines without internet are attached to each
+[release](https://github.com/sulemanali5760/amr-station-handshake/releases).
+
+## Use
+
+Try it without a PLC, in two terminals:
+
+```bash
+handover-check station                        # reference station on opc.tcp://127.0.0.1:4860/station/
+handover-check run opc.tcp://127.0.0.1:4860/station/
+```
+
+```bash
+handover-check station --defect no_watchdog   # a station with one rule switched off
+```
+
+Against your PLC: describe where the eight signals live in a signal map (examples for the reference
+station, Siemens S7-1500 and Beckhoff TwinCAT 3 are in [`maps/`](maps)), then:
+
+```bash
+handover-check run opc.tcp://192.168.0.10:4840 --map my_station.yaml --station-is-safe
+```
+
+| Option | Purpose |
+|---|---|
+| `--t-ready 5` `--t-start 3` `--t-transfer 15` `--t-release 3` `--t-watchdog 2` `--t-stop 1` | the time limits of your plant specification, in seconds |
+| `--only R2 R8` | run selected rules |
+| `--report record.md` | Markdown report for the commissioning record |
+| `--json` | machine-readable output |
+| `--strict` | exit code 2 if a rule could not be tested |
+
+Exit code 0 = no rule failed, 1 = at least one rule failed.
+
+## It moves your conveyor
+
+The tool writes the request signals. On a real station that starts the conveyor.
+
+- For any endpoint that is not this computer it refuses to run without `--station-is-safe`.
+- Run it with the station in a test state, clear of people and loads.
+- It always writes both request bits back to FALSE when it ends, also after an error.
+- It is a commissioning aid. It is **not** a safety function and no substitute for the safety
+  validation of the station.
+
+## Tested
+
+The test suite starts the reference station over real OPC UA, once conforming and once for each of
+eight built-in defects, and expects the tester to report exactly the broken rule:
+
+| Defect in the station | Reported under |
+|---|---|
+| Ready on without a request | R1 |
+| Ready far too late | R2 |
+| conveyor starts before the vehicle is in position | R3 |
+| TransferActive still on with TransferDone | R4 |
+| outputs not cleared after release | R5 |
+| no heartbeat watchdog | R8 |
+| fault not cleared by the acknowledge | R9 |
+| conveyor keeps running when the vehicle leaves | R10 |
+
+A transfer that is too short to judge R8 or R10 is reported as "not testable", not as a pass.
+
+## Limits
+
+- **Not tested against a real PLC.** Only against the bundled reference station. The S7-1500 and
+  TwinCAT maps are examples; node ids depend on the project.
+- **No OPC UA security.** The tool connects anonymously without encryption. A PLC that demands
+  certificates or a login cannot be tested yet.
+- **Polling.** Signals are read every 25 ms by default, so measured times are accurate to a few
+  tens of milliseconds plus the network. It cannot see events shorter than that.
+- **The rules are this project's own** ([SPEC](../../docs/SPEC.md)), shaped after SEMI E84. They
+  are not a standard of any body, and a station built to another handshake will fail them.
+- **One vehicle, one station.** No carrier identification, no multi-lane stations.
+
+## Licence
+
+MIT

handover_check-0.1.0/README.md

@@ -0,0 +1,129 @@
+# handover-check
+
+Test a conveyor station's **AMR/AGV load-handover handshake** before the robot arrives.
+
+The tool connects to the station PLC over OPC UA and plays the vehicle side: it requests a handover,
+docks, releases, and also does what vehicles do when things go wrong (goes silent, leaves mid-transfer,
+changes its mind). It checks the station's answers and response times against ten rules and reports
+rule by rule.
+
+```
+$ handover-check run opc.tcp://192.168.0.10:4840 --map station.yaml --station-is-safe
+
+[PASS] R1  Idle at rest: no output is on without a request
+           all outputs off for 1 s without a request
+[PASS] R2  StationReady follows AmrDockRequest in time, and nothing moves yet
+           StationReady 0.53 s after the request (limit 5 s)
+[PASS] R3  No transfer before AmrInPosition
+           no transfer for 1 s while the vehicle was not in position
+[PASS] R4  Transfer starts after AmrInPosition and completes; TransferActive is off when TransferDone is on
+           transfer started after 0.02 s and finished after 4.02 s
+[PASS] R5  Station returns to idle after the vehicle releases
+           station idle 0.03 s after the release (limit 3 s)
+[PASS] R6  A second handover works straight after the first
+           two handovers in a row completed
+[PASS] R7  A withdrawn request returns the station to idle without a transfer
+           station back to idle 0.02 s after the request was withdrawn
+[FAIL] R8  Heartbeat watchdog: a silent vehicle stops the transfer with a fault code
+           the vehicle went silent for 2 s during the transfer and the station carried on: Ready, TransferActive
+[SKIP] R9  Dropping the request acknowledges and clears a fault
+           could not bring the station into a fault to acknowledge (see R8): Ready, TransferActive
+[PASS] R10 The conveyor stops when the vehicle leaves its position
+           conveyor stopped 0.02 s after the vehicle left its position (limit 1 s; station: Fault(code 3))
+
+Station does NOT conform. 8 passed, 1 failed, 1 not testable.
+```
+
+*Real output, against the bundled reference station with its watchdog switched off; address changed.*
+
+## Why
+
+VDA 5050 covers fleet controller to vehicle and expressly leaves out "interfaces to peripheral
+equipment". The handshake between vehicle and conveyor is therefore written again in every project,
+by two teams, and its mistakes show up at commissioning with the robot standing in front of the
+station. The rules are written down in [docs/SPEC.md](../../docs/SPEC.md); this tool lets the PLC
+programmer test the station side alone, at the desk or on site, days earlier.
+
+## Install
+
+```bash
+pip install handover-check
+```
+
+Python 3.11 or newer; Windows or Linux. No ROS and no robot needed.
+Offline bundles for machines without internet are attached to each
+[release](https://github.com/sulemanali5760/amr-station-handshake/releases).
+
+## Use
+
+Try it without a PLC, in two terminals:
+
+```bash
+handover-check station                        # reference station on opc.tcp://127.0.0.1:4860/station/
+handover-check run opc.tcp://127.0.0.1:4860/station/
+```
+
+```bash
+handover-check station --defect no_watchdog   # a station with one rule switched off
+```
+
+Against your PLC: describe where the eight signals live in a signal map (examples for the reference
+station, Siemens S7-1500 and Beckhoff TwinCAT 3 are in [`maps/`](maps)), then:
+
+```bash
+handover-check run opc.tcp://192.168.0.10:4840 --map my_station.yaml --station-is-safe
+```
+
+| Option | Purpose |
+|---|---|
+| `--t-ready 5` `--t-start 3` `--t-transfer 15` `--t-release 3` `--t-watchdog 2` `--t-stop 1` | the time limits of your plant specification, in seconds |
+| `--only R2 R8` | run selected rules |
+| `--report record.md` | Markdown report for the commissioning record |
+| `--json` | machine-readable output |
+| `--strict` | exit code 2 if a rule could not be tested |
+
+Exit code 0 = no rule failed, 1 = at least one rule failed.
+
+## It moves your conveyor
+
+The tool writes the request signals. On a real station that starts the conveyor.
+
+- For any endpoint that is not this computer it refuses to run without `--station-is-safe`.
+- Run it with the station in a test state, clear of people and loads.
+- It always writes both request bits back to FALSE when it ends, also after an error.
+- It is a commissioning aid. It is **not** a safety function and no substitute for the safety
+  validation of the station.
+
+## Tested
+
+The test suite starts the reference station over real OPC UA, once conforming and once for each of
+eight built-in defects, and expects the tester to report exactly the broken rule:
+
+| Defect in the station | Reported under |
+|---|---|
+| Ready on without a request | R1 |
+| Ready far too late | R2 |
+| conveyor starts before the vehicle is in position | R3 |
+| TransferActive still on with TransferDone | R4 |
+| outputs not cleared after release | R5 |
+| no heartbeat watchdog | R8 |
+| fault not cleared by the acknowledge | R9 |
+| conveyor keeps running when the vehicle leaves | R10 |
+
+A transfer that is too short to judge R8 or R10 is reported as "not testable", not as a pass.
+
+## Limits
+
+- **Not tested against a real PLC.** Only against the bundled reference station. The S7-1500 and
+  TwinCAT maps are examples; node ids depend on the project.
+- **No OPC UA security.** The tool connects anonymously without encryption. A PLC that demands
+  certificates or a login cannot be tested yet.
+- **Polling.** Signals are read every 25 ms by default, so measured times are accurate to a few
+  tens of milliseconds plus the network. It cannot see events shorter than that.
+- **The rules are this project's own** ([SPEC](../../docs/SPEC.md)), shaped after SEMI E84. They
+  are not a standard of any body, and a station built to another handshake will fail them.
+- **One vehicle, one station.** No carrier identification, no multi-lane stations.
+
+## Licence
+
+MIT

handover_check-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "handover-check"
+version = "0.1.0"
+description = "Test a conveyor station's AMR/AGV load-handover handshake over OPC UA before the robot arrives: plays the vehicle side, also the ways a vehicle fails, and reports rule by rule."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Suleman Ali" }]
+keywords = ["agv", "amr", "plc", "opc-ua", "handshake", "commissioning", "conveyor", "vda5050", "intralogistics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Manufacturing",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = ["asyncua>=1.1,<3", "pyyaml>=6.0"]
+
+[project.urls]
+Repository = "https://github.com/sulemanali5760/amr-station-handshake"
+
+[project.scripts]
+handover-check = "handover_check.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

handover_check-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

handover_check-0.1.0/src/handover_check/__init__.py

@@ -0,0 +1,7 @@
+"""handover-check: test a conveyor station's AMR handover handshake against rules R1-R10."""
+__version__ = "0.1.0"
+
+from handover_check.checks import RULES, Limits, Result, run_checks  # noqa: E402
+from handover_check.station import DEFECTS, StationLogic, serve  # noqa: E402
+
+__all__ = ["DEFECTS", "Limits", "RULES", "Result", "StationLogic", "run_checks", "serve"]

handover_check-0.1.0/src/handover_check/__main__.py

@@ -0,0 +1,100 @@
+"""handover-check run opc.tcp://plc:4840 --map station.yaml   |   handover-check station"""
+import argparse
+import asyncio
+import json
+import sys
+import urllib.parse
+
+from handover_check import __version__
+from handover_check.checks import FAIL, PASS, SIM_MAP, SKIP, Limits, as_dicts, load_signal_map, run_checks
+from handover_check.station import DEFECTS, StationLogic, serve
+
+MARK = {PASS: "[PASS]", FAIL: "[FAIL]", SKIP: "[SKIP]"}
+
+
+def render(results, endpoint: str) -> str:
+    lines = [f"Station handover check, {endpoint}", ""]
+    for r in results:
+        lines += [f"{MARK[r.status]} {r.rule:<3} {r.title}", f"           {r.detail}"]
+    n = {s: sum(r.status == s for r in results) for s in (PASS, FAIL, SKIP)}
+    verdict = "Station conforms." if not n[FAIL] and not n[SKIP] else \
+        "Station does NOT conform." if n[FAIL] else "No rule failed, but not every rule could be tested."
+    lines += ["", f"{verdict} {n[PASS]} passed, {n[FAIL]} failed, {n[SKIP]} not testable."]
+    return "\n".join(lines)
+
+
+def markdown(results, endpoint: str) -> str:
+    rows = "\n".join(f"| {r.rule} | {r.title} | **{r.status}** | {r.detail} |" for r in results)
+    return (f"# Station handover check\n\nStation: `{endpoint}`  \nTool: handover-check {__version__}\n\n"
+            f"| Rule | Requirement | Result | Observed |\n|---|---|---|---|\n{rows}\n")
+
+
+def _run(a) -> int:
+    host = urllib.parse.urlparse(a.endpoint).hostname or ""
+    if host not in ("127.0.0.1", "localhost", "::1") and not a.station_is_safe:
+        print("handover-check writes request signals to the station. On a real station this can start a conveyor.\n"
+              "Make sure the station is in a test state and clear of people and loads, then repeat the command "
+              "with --station-is-safe.", file=sys.stderr)
+        return 64
+    signal_map = load_signal_map(a.map) if a.map else SIM_MAP
+    limits = Limits(a.t_ready, a.t_start, a.t_transfer, a.t_release, a.t_watchdog, a.t_stop, a.t_hold)
+    results = asyncio.run(run_checks(a.endpoint, signal_map, limits, a.only))
+    print(json.dumps(as_dicts(results), indent=2) if a.json else render(results, a.endpoint))
+    if a.report:
+        with open(a.report, "w", encoding="utf-8") as f:
+            f.write(markdown(results, a.endpoint))
+    failed = any(r.status == FAIL for r in results)
+    skipped = any(r.status == SKIP for r in results)
+    return 1 if failed else 2 if skipped and a.strict else 0
+
+
+def _station(a) -> int:
+    logic = StationLogic(a.ready_delay, a.transfer_time, a.watchdog, frozenset(a.defect or ()))
+    endpoint = f"opc.tcp://{a.host}:{a.port}/station/"
+    print(f"reference station on {endpoint}" + (f", defects: {', '.join(a.defect)}" if a.defect else ""), flush=True)
+    try:
+        asyncio.run(serve(endpoint, logic))
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="handover-check", description="Check a conveyor station's AMR handover "
+                                 "handshake against rules R1-R10, before the robot arrives.")
+    ap.add_argument("--version", action="version", version=__version__)
+    sub = ap.add_subparsers(dest="command", required=True)
+    r = sub.add_parser("run", help="play the vehicle side against a station and report rule by rule")
+    r.add_argument("endpoint", help="OPC UA endpoint of the station PLC, e.g. opc.tcp://192.168.0.10:4840")
+    r.add_argument("--map", help="signal map YAML (namespace_uri, node_ids); default: the reference station")
+    r.add_argument("--station-is-safe", action="store_true",
+                   help="confirm the station is in a test state, clear of people and loads (needed for any "
+                        "endpoint that is not this computer)")
+    r.add_argument("--only", nargs="+", metavar="RULE", help="run only these rules, e.g. --only R2 R8")
+    for name, default, text in (("ready", 5.0, "request -> StationReady"), ("start", 3.0, "in position -> TransferActive"),
+                                ("transfer", 15.0, "TransferActive -> TransferDone"), ("release", 3.0, "release -> idle"),
+                                ("watchdog", 2.0, "heartbeat stopped -> fault"), ("stop", 1.0, "vehicle left -> conveyor stopped"),
+                                ("hold", 1.0, "how long 'must stay off' is observed")):
+        r.add_argument(f"--t-{name}", type=float, default=default, metavar="S", help=f"limit in seconds: {text} (default {default:g})")
+    r.add_argument("--json", action="store_true", help="machine-readable output")
+    r.add_argument("--report", metavar="FILE.md", help="also write a Markdown report (for the commissioning record)")
+    r.add_argument("--strict", action="store_true", help="exit code 2 when a rule could not be tested")
+    r.set_defaults(func=_run)
+    s = sub.add_parser("station", help="run the reference station (no PLC needed), optionally with a defect")
+    s.add_argument("--host", default="127.0.0.1")
+    s.add_argument("--port", type=int, default=4860)
+    s.add_argument("--ready-delay", type=float, default=0.5)
+    s.add_argument("--transfer-time", type=float, default=4.0)
+    s.add_argument("--watchdog", type=float, default=1.0)
+    s.add_argument("--defect", action="append", choices=DEFECTS, help="switch one rule off (repeatable)")
+    s.set_defaults(func=_station)
+    a = ap.parse_args(argv)
+    try:
+        return a.func(a)
+    except (ValueError, OSError, asyncio.TimeoutError) as e:
+        print(f"handover-check: {e or type(e).__name__}", file=sys.stderr)
+        return 64
+
+
+if __name__ == "__main__":
+    sys.exit(main())

handover_check-0.1.0/src/handover_check/checks.py

@@ -0,0 +1,342 @@
+"""Play the vehicle side of the handover against a station PLC and check the station against rules R1-R10.
+
+The tester only needs the eight handshake signals over OPC UA (docs/SPEC.md). It does not need a robot,
+ROS or the load: it sets the two request bits and the heartbeat like a vehicle would, also in the ways a
+vehicle fails (goes silent, leaves, changes its mind), and watches what the station answers and how fast.
+
+It WRITES to the station. On a real station that can start a conveyor. Run it with the station in a
+test state, clear of people and loads.
+"""
+import asyncio
+from dataclasses import asdict, dataclass
+
+import yaml
+from asyncua import Client, ua
+
+SIGNALS = ("AmrDockRequest", "AmrInPosition", "AmrHeartbeat",
+           "StationReady", "TransferActive", "TransferDone", "Fault", "FaultCode")
+SIM_MAP = {"namespace_uri": "urn:amr-station-handshake:station",
+           "node_ids": {name: f"Station.{name}" for name in SIGNALS}}
+PASS, FAIL, SKIP = "PASS", "FAIL", "SKIP"
+
+
+@dataclass(frozen=True)
+class Limits:
+    """Longest time the station may take, in seconds. Set them to what the plant specification says."""
+    ready: float = 5.0        # request -> StationReady
+    start: float = 3.0        # in position -> TransferActive
+    transfer: float = 15.0    # TransferActive -> TransferDone
+    release: float = 3.0      # request dropped -> station idle
+    watchdog: float = 2.0     # heartbeat stopped -> Fault, conveyor stopped
+    stop: float = 1.0         # vehicle left position -> conveyor stopped
+    hold: float = 1.0         # how long "must stay off" conditions are observed
+
+
+@dataclass
+class Result:
+    rule: str
+    title: str
+    status: str
+    detail: str = ""
+    seconds: float | None = None      # the measured response time, where the rule has one
+
+
+@dataclass(frozen=True)
+class State:
+    ready: bool
+    active: bool
+    done: bool
+    fault: bool
+    code: int
+
+    @property
+    def idle(self) -> bool:
+        return not (self.ready or self.active or self.done or self.fault)
+
+    def __str__(self) -> str:
+        on = [n for n, v in (("Ready", self.ready), ("TransferActive", self.active),
+                             ("TransferDone", self.done), (f"Fault(code {self.code})", self.fault)) if v]
+        return ", ".join(on) or "all outputs off"
+
+
+def load_signal_map(path) -> dict:
+    with open(path, encoding="utf-8") as f:
+        signal_map = yaml.safe_load(f)
+    missing = [n for n in SIGNALS if n not in (signal_map or {}).get("node_ids", {})]
+    if not signal_map or "namespace_uri" not in signal_map or missing:
+        raise ValueError(f"{path}: needs namespace_uri and node_ids for {', '.join(missing or SIGNALS)}")
+    return signal_map
+
+
+class Rig:
+    """The vehicle side: two request bits, a heartbeat, and eyes on the station's five outputs."""
+
+    def __init__(self, endpoint: str, signal_map: dict, period: float = 0.05, timeout: float = 4.0):
+        self.endpoint, self.signal_map, self.period = endpoint, signal_map, period
+        self._client = Client(endpoint, timeout=timeout)
+        self._beating = True
+        self._beat = 0
+        self._task = None
+        self._n = {}
+
+    async def __aenter__(self) -> "Rig":
+        await self._client.connect()
+        try:
+            ns = await self._client.get_namespace_index(self.signal_map["namespace_uri"])
+        except ValueError:
+            await self._client.disconnect()
+            raise ValueError(f"namespace {self.signal_map['namespace_uri']} not found on {self.endpoint}") from None
+        self._n = {name: self._client.get_node(ua.NodeId(self.signal_map["node_ids"][name], ns)) for name in SIGNALS}
+        self._outputs = [self._n[k] for k in SIGNALS[3:]]
+        await self.read()                                   # fails here if a node id is wrong
+        self._task = asyncio.create_task(self._heartbeat())
+        await asyncio.sleep(self.period * 4)                 # heartbeat is running before the first request
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        if self._task:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+        try:                                                # never leave a request latched on the PLC
+            await self.set(False, False)
+        finally:
+            await self._client.disconnect()
+
+    async def _heartbeat(self) -> None:
+        while True:
+            if self._beating:
+                self._beat = (self._beat + 1) % 32768       # PLC INT
+                await self._n["AmrHeartbeat"].write_value(self._beat, ua.VariantType.Int16)
+            await asyncio.sleep(self.period)
+
+    def heartbeat(self, on: bool) -> None:
+        self._beating = on
+
+    async def set(self, request: bool, in_position: bool) -> None:
+        await self._n["AmrDockRequest"].write_value(request, ua.VariantType.Boolean)
+        await self._n["AmrInPosition"].write_value(in_position, ua.VariantType.Boolean)
+
+    async def read(self) -> State:
+        ready, active, done, fault, code = await self._client.read_values(self._outputs)   # one consistent snapshot
+        return State(bool(ready), bool(active), bool(done), bool(fault), int(code or 0))
+
+    async def wait(self, wanted, limit: float, forbidden=None):
+        """Poll until wanted(state). Returns (reached, seconds, state, violation): violation is the first
+        state in which forbidden(state) was true while waiting."""
+        loop = asyncio.get_running_loop()
+        start = loop.time()
+        violation = None
+        while True:
+            s = await self.read()
+            t = loop.time() - start
+            if forbidden and violation is None and forbidden(s):
+                violation = s
+            if wanted(s):
+                return True, t, s, violation
+            if t > limit:
+                return False, t, s, violation
+            await asyncio.sleep(self.period / 2)
+
+    async def observe(self, seconds: float, forbidden):
+        """Watch for `seconds`; returns the first state that broke the rule, or None."""
+        _, _, _, violation = await self.wait(lambda s: False, seconds, forbidden)
+        return violation
+
+    async def to_idle(self, limit: float) -> bool:
+        self.heartbeat(True)
+        await self.set(False, False)
+        reached, *_ = await self.wait(lambda s: s.idle, limit)
+        # A vehicle is alive before it asks. Give the station a few fresh heartbeats first, otherwise the
+        # next request can meet a stale counter and a correct watchdog trips at once.
+        await asyncio.sleep(self.period * 4)
+        return reached
+
+
+# ---------------------------------------------------------------- building blocks
+async def _to_ready(rig: Rig, lim: Limits):
+    await rig.set(True, False)
+    return await rig.wait(lambda s: s.ready, lim.ready, forbidden=lambda s: s.active or s.done)
+
+
+async def _to_transfer(rig: Rig, lim: Limits):
+    reached, t, s, _ = await _to_ready(rig, lim)
+    if not reached:
+        return False, t, s
+    await rig.set(True, True)
+    reached, t, s, _ = await rig.wait(lambda s: s.active or s.done or s.fault, lim.start)
+    return reached and s.active, t, s
+
+
+# ---------------------------------------------------------------- the rules
+async def r1_idle_at_rest(rig, lim):
+    bad = await rig.observe(lim.hold, lambda s: not s.idle)
+    if bad:
+        return Result("R1", "", FAIL, f"with no request the station shows: {bad}")
+    return Result("R1", "", PASS, f"all outputs off for {lim.hold:g} s without a request")
+
+
+async def r2_ready_follows_request(rig, lim):
+    reached, t, s, early = await _to_ready(rig, lim)
+    if early:
+        return Result("R2", "", FAIL, f"before the vehicle was in position the station showed: {early}", t)
+    if not reached:
+        return Result("R2", "", FAIL, f"no StationReady within {lim.ready:g} s of the request (station: {s})", t)
+    return Result("R2", "", PASS, f"StationReady {t:.2f} s after the request (limit {lim.ready:g} s)", t)
+
+
+async def r3_no_transfer_before_in_position(rig, lim):
+    reached, _, s, _ = await _to_ready(rig, lim)
+    if not reached:
+        return Result("R3", "", SKIP, f"station never became ready (see R2), so this could not be tested: {s}")
+    bad = await rig.observe(lim.hold, lambda s: s.active or s.done)
+    if bad:
+        return Result("R3", "", FAIL, f"the vehicle was NOT in position, but the station showed: {bad}")
+    return Result("R3", "", PASS, f"no transfer for {lim.hold:g} s while the vehicle was not in position")
+
+
+async def r4_transfer_completes(rig, lim):
+    ok, t_start, s = await _to_transfer(rig, lim)
+    if not ok:
+        return Result("R4", "", FAIL, f"no TransferActive within {lim.start:g} s of AmrInPosition (station: {s})", t_start)
+    reached, t, s, _ = await rig.wait(lambda s: s.done or s.fault, lim.transfer)
+    if not reached or s.fault:
+        return Result("R4", "", FAIL, f"no TransferDone within {lim.transfer:g} s (station: {s})", t)
+    s = await rig.read()
+    if s.active:
+        return Result("R4", "", FAIL, "TransferDone is set but TransferActive is still on: the vehicle cannot tell "
+                                      "whether the conveyor has stopped", t)
+    return Result("R4", "", PASS, f"transfer started after {t_start:.2f} s and finished after {t:.2f} s", t)
+
+
+async def r5_release(rig, lim):
+    ok, _, s = await _to_transfer(rig, lim)
+    reached, _, s, _ = await rig.wait(lambda s: s.done or s.fault, lim.transfer) if ok else (False, 0, s, None)
+    if not reached or s.fault:
+        return Result("R5", "", SKIP, f"no completed transfer to release from (see R4): {s}")
+    await rig.set(False, False)
+    reached, t, s, _ = await rig.wait(lambda s: s.idle, lim.release)
+    if not reached:
+        return Result("R5", "", FAIL, f"{lim.release:g} s after the vehicle released, the station still shows: {s}", t)
+    return Result("R5", "", PASS, f"station idle {t:.2f} s after the release (limit {lim.release:g} s)", t)
+
+
+async def r6_second_handover(rig, lim):
+    for n in (1, 2):
+        ok, _, s = await _to_transfer(rig, lim)
+        reached, _, s, _ = await rig.wait(lambda s: s.done or s.fault, lim.transfer) if ok else (False, 0, s, None)
+        if not reached or s.fault:
+            return Result("R6", "", FAIL if n == 2 else SKIP, f"handover {n} did not complete: {s}")
+        if not await rig.to_idle(lim.release):
+            return Result("R6", "", FAIL if n == 2 else SKIP, f"station not idle after handover {n}: {await rig.read()}")
+    return Result("R6", "", PASS, "two handovers in a row completed")
+
+
+async def r7_withdrawn_request(rig, lim):
+    reached, _, s, _ = await _to_ready(rig, lim)
+    if not reached:
+        return Result("R7", "", SKIP, f"station never became ready (see R2): {s}")
+    await rig.set(False, False)
+    reached, t, s, moved = await rig.wait(lambda s: s.idle, lim.release, forbidden=lambda s: s.active or s.done)
+    if moved:
+        return Result("R7", "", FAIL, f"the vehicle withdrew its request, yet the station showed: {moved}", t)
+    if not reached:
+        return Result("R7", "", FAIL, f"{lim.release:g} s after the request was withdrawn the station still shows: {s}", t)
+    return Result("R7", "", PASS, f"station back to idle {t:.2f} s after the request was withdrawn", t)
+
+
+async def r8_heartbeat_loss(rig, lim):
+    ok, _, s = await _to_transfer(rig, lim)
+    if not ok:
+        return Result("R8", "", SKIP, f"no running transfer to interrupt (see R4): {s}")
+    rig.heartbeat(False)
+    reached, t, s, _ = await rig.wait(lambda s: s.fault or s.done, lim.watchdog)
+    if s.done and not s.fault:
+        return Result("R8", "", SKIP, f"the transfer finished {t:.2f} s after the heartbeat stopped, before a watchdog "
+                                      "could show. Test with a longer transfer.", t)
+    if not reached:
+        return Result("R8", "", FAIL, f"the vehicle went silent for {lim.watchdog:g} s during the transfer and the "
+                                      f"station carried on: {s}", t)
+    if s.active:
+        return Result("R8", "", FAIL, f"Fault is set but TransferActive is still on: {s}", t)
+    if s.code == 0:
+        return Result("R8", "", FAIL, "Fault is set but FaultCode is 0: nobody can tell what happened", t)
+    return Result("R8", "", PASS, f"fault code {s.code} and conveyor stopped {t:.2f} s after the heartbeat stopped "
+                                  f"(limit {lim.watchdog:g} s)", t)
+
+
+async def r9_fault_acknowledge(rig, lim):
+    ok, _, s = await _to_transfer(rig, lim)
+    if ok:
+        rig.heartbeat(False)
+        ok, _, s, _ = await rig.wait(lambda s: s.fault or s.done, lim.watchdog)
+    if not ok or not s.fault:
+        return Result("R9", "", SKIP, f"could not bring the station into a fault to acknowledge (see R8): {s}")
+    await rig.set(False, False)                             # the acknowledge; the heartbeat may still be dead
+    reached, t, s, _ = await rig.wait(lambda s: s.idle, lim.release)
+    if not reached:
+        return Result("R9", "", FAIL, f"{lim.release:g} s after the request was dropped (the acknowledge) the station "
+                                      f"still shows: {s}", t)
+    return Result("R9", "", PASS, f"fault cleared {t:.2f} s after the acknowledge", t)
+
+
+async def r10_vehicle_leaves(rig, lim):
+    ok, _, s = await _to_transfer(rig, lim)
+    if not ok:
+        return Result("R10", "", SKIP, f"no running transfer to interrupt (see R4): {s}")
+    await rig.set(True, False)                              # still requesting, but no longer in position
+    reached, t, s, _ = await rig.wait(lambda s: not s.active, lim.stop)
+    if not reached:
+        return Result("R10", "", FAIL, f"the vehicle left its position and {lim.stop:g} s later the conveyor is "
+                                       f"still running: {s}", t)
+    if s.done and not s.fault:
+        return Result("R10", "", SKIP, f"the transfer finished {t:.2f} s after the vehicle left, too fast to judge. "
+                                       "Test with a longer transfer.", t)
+    return Result("R10", "", PASS, f"conveyor stopped {t:.2f} s after the vehicle left its position "
+                                   f"(limit {lim.stop:g} s; station: {s})", t)
+
+
+RULES = {
+    "R1": ("Idle at rest: no output is on without a request", r1_idle_at_rest),
+    "R2": ("StationReady follows AmrDockRequest in time, and nothing moves yet", r2_ready_follows_request),
+    "R3": ("No transfer before AmrInPosition", r3_no_transfer_before_in_position),
+    "R4": ("Transfer starts after AmrInPosition and completes; TransferActive is off when TransferDone is on", r4_transfer_completes),
+    "R5": ("Station returns to idle after the vehicle releases", r5_release),
+    "R6": ("A second handover works straight after the first", r6_second_handover),
+    "R7": ("A withdrawn request returns the station to idle without a transfer", r7_withdrawn_request),
+    "R8": ("Heartbeat watchdog: a silent vehicle stops the transfer with a fault code", r8_heartbeat_loss),
+    "R9": ("Dropping the request acknowledges and clears a fault", r9_fault_acknowledge),
+    "R10": ("The conveyor stops when the vehicle leaves its position", r10_vehicle_leaves),
+}
+
+
+async def run_checks(endpoint: str, signal_map: dict = SIM_MAP, limits: Limits = Limits(),
+                     only: list[str] | None = None, period: float = 0.05) -> list[Result]:
+    """Run the rules in order against the station. Before each rule the station is brought back to idle;
+    a rule that cannot start from idle is reported as SKIP with the reason."""
+    results = []
+    stuck = False
+    async with Rig(endpoint, signal_map, period) as rig:
+        for rule, (title, check) in RULES.items():
+            if only and rule not in only:
+                continue
+            if rule != "R1" and not await rig.to_idle(limits.release * 2):
+                # A station that keeps outputs on after the vehicle dropped both request bits has broken
+                # the release rule. Say so once as a failure; the rules after it cannot be judged.
+                detail = (f"the vehicle dropped its request and {limits.release * 2:g} s later the station still "
+                          f"shows: {await rig.read()}")
+                r = Result(rule, title, SKIP if stuck else FAIL,
+                           ("not testable, " if stuck else "station does not return to idle (rule R5): ") + detail)
+                stuck = True
+            else:
+                try:
+                    r = await check(rig, limits)
+                finally:
+                    rig.heartbeat(True)
+                r.title = title
+            results.append(r)
+        await rig.to_idle(limits.release)
+    return results
+
+
+def as_dicts(results: list[Result]) -> list[dict]:
+    return [asdict(r) for r in results]

handover_check-0.1.0/src/handover_check/station.py

@@ -0,0 +1,120 @@
+"""Reference station: the station side of the handover as a pure, PLC-style step function, plus an
+OPC UA server around it.
+
+Two uses:
+- a station to develop against when no PLC is at hand (`handover-check station`);
+- the yardstick for the tester's own tests: each DEFECT switches one rule off, and the tester must
+  report exactly that rule as broken.
+
+The logic is written the way a PLC task works: read inputs, decide, write outputs, once per cycle.
+"""
+import asyncio
+from dataclasses import dataclass, field
+
+from asyncua import Server, ua
+
+NAMESPACE = "urn:amr-station-handshake:station"
+FAULT_CONVEYOR_BLOCKED, FAULT_HEARTBEAT_LOST, FAULT_AMR_LEFT = 1, 2, 3
+DEFECTS = (
+    "ready_without_request",      # R1: Ready is on although nobody asked
+    "slow_ready",                 # R2: Ready comes far too late
+    "transfer_before_docked",     # R3: conveyor starts before the vehicle is in position
+    "active_stays_on",            # R4: TransferActive still on when TransferDone is set
+    "ready_stuck",                # R5: Ready/Done not cleared after the vehicle released
+    "no_watchdog",                # R8: a dead vehicle is not noticed
+    "fault_not_cleared",          # R9: fault stays latched after the acknowledge
+    "ignores_undock",             # R10: conveyor keeps running when the vehicle leaves
+)
+
+
+@dataclass
+class Outputs:
+    ready: bool = False
+    transfer_active: bool = False
+    transfer_done: bool = False
+    fault: bool = False
+    fault_code: int = 0
+
+
+@dataclass
+class StationLogic:
+    ready_delay: float = 0.5      # s from request to Ready
+    transfer_time: float = 2.0    # s the conveyor runs
+    watchdog: float = 1.0         # s without a new heartbeat value before the station faults
+    defects: frozenset = field(default_factory=frozenset)
+    phase: str = "idle"
+    code: int = 0
+    _due: float = 0.0
+    _last_beat: int | None = None
+    _beat_seen: float = 0.0
+
+    def step(self, request: bool, docked: bool, beat: int, now: float) -> Outputs:
+        d = self.defects
+        if beat != self._last_beat:
+            self._last_beat, self._beat_seen = beat, now
+
+        if not request:
+            if self.phase == "fault" and "fault_not_cleared" in d:
+                pass
+            elif self.phase in ("ready", "done") and "ready_stuck" in d:
+                pass
+            else:
+                self.phase, self.code = "idle", 0      # dropping the request also acknowledges a fault
+        elif self.phase == "fault":
+            pass                                         # latched until the request drops
+        elif now - self._beat_seen > self.watchdog and "no_watchdog" not in d:
+            self.phase, self.code = "fault", FAULT_HEARTBEAT_LOST
+        elif self.phase == "idle":
+            self.phase = "preparing"
+            self._due = now + (self.ready_delay * 20 if "slow_ready" in d else self.ready_delay)
+        elif self.phase == "preparing" and now >= self._due:
+            self.phase = "ready"
+        elif self.phase == "ready" and (docked or "transfer_before_docked" in d):
+            self.phase, self._due = "transferring", now + self.transfer_time
+        elif self.phase == "transferring":
+            if not docked and not d & {"ignores_undock", "transfer_before_docked"}:
+                self.phase, self.code = "fault", FAULT_AMR_LEFT
+            elif now >= self._due:
+                self.phase = "done"
+
+        return Outputs(
+            ready=self.phase in ("ready", "transferring", "done") or "ready_without_request" in d,
+            transfer_active=self.phase == "transferring" or (self.phase == "done" and "active_stays_on" in d),
+            transfer_done=self.phase == "done",
+            fault=self.phase == "fault",
+            fault_code=self.code,
+        )
+
+
+async def serve(endpoint: str, logic: StationLogic, ready: asyncio.Event | None = None,
+                stop: asyncio.Event | None = None, cycle: float = 0.02) -> None:
+    """Run the station as an OPC UA server (no security: a development aid, bind it to localhost)."""
+    server = Server()
+    await server.init()
+    server.set_endpoint(endpoint)
+    server.set_server_name("Reference conveyor station (handover-check)")
+    server.set_security_policy([ua.SecurityPolicyType.NoSecurity])
+    idx = await server.register_namespace(NAMESPACE)
+    station = await server.nodes.objects.add_object(ua.NodeId("Station", idx), "Station")
+
+    async def signal(name, value, vt):
+        node = await station.add_variable(ua.NodeId(f"Station.{name}", idx), name, value, vt)
+        await node.set_writable()
+        return node
+    boolean, int16 = ua.VariantType.Boolean, ua.VariantType.Int16
+    inputs = [await signal(n, v, t) for n, v, t in (("AmrDockRequest", False, boolean),
+                                                    ("AmrInPosition", False, boolean), ("AmrHeartbeat", 0, int16))]
+    outs = [await signal(n, v, t) for n, v, t in (("StationReady", False, boolean), ("TransferActive", False, boolean),
+                                                  ("TransferDone", False, boolean), ("Fault", False, boolean),
+                                                  ("FaultCode", 0, int16))]
+    loop = asyncio.get_running_loop()
+    async with server:
+        if ready:
+            ready.set()
+        while not (stop and stop.is_set()):
+            request, docked, beat = [await n.read_value() for n in inputs]
+            o = logic.step(bool(request), bool(docked), int(beat), loop.time())
+            for node, value, vt in zip(outs, (o.ready, o.transfer_active, o.transfer_done, o.fault, o.fault_code),
+                                       (boolean, boolean, boolean, boolean, int16)):
+                await node.write_value(value, vt)
+            await asyncio.sleep(cycle)

handover_check-0.1.0/src/handover_check.egg-info/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: handover-check
+Version: 0.1.0
+Summary: Test a conveyor station's AMR/AGV load-handover handshake over OPC UA before the robot arrives: plays the vehicle side, also the ways a vehicle fails, and reports rule by rule.
+Author: Suleman Ali
+License: MIT
+Project-URL: Repository, https://github.com/sulemanali5760/amr-station-handshake
+Keywords: agv,amr,plc,opc-ua,handshake,commissioning,conveyor,vda5050,intralogistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncua<3,>=1.1
+Requires-Dist: pyyaml>=6.0
+Dynamic: license-file
+
+# handover-check
+
+Test a conveyor station's **AMR/AGV load-handover handshake** before the robot arrives.
+
+The tool connects to the station PLC over OPC UA and plays the vehicle side: it requests a handover,
+docks, releases, and also does what vehicles do when things go wrong (goes silent, leaves mid-transfer,
+changes its mind). It checks the station's answers and response times against ten rules and reports
+rule by rule.
+
+```
+$ handover-check run opc.tcp://192.168.0.10:4840 --map station.yaml --station-is-safe
+
+[PASS] R1  Idle at rest: no output is on without a request
+           all outputs off for 1 s without a request
+[PASS] R2  StationReady follows AmrDockRequest in time, and nothing moves yet
+           StationReady 0.53 s after the request (limit 5 s)
+[PASS] R3  No transfer before AmrInPosition
+           no transfer for 1 s while the vehicle was not in position
+[PASS] R4  Transfer starts after AmrInPosition and completes; TransferActive is off when TransferDone is on
+           transfer started after 0.02 s and finished after 4.02 s
+[PASS] R5  Station returns to idle after the vehicle releases
+           station idle 0.03 s after the release (limit 3 s)
+[PASS] R6  A second handover works straight after the first
+           two handovers in a row completed
+[PASS] R7  A withdrawn request returns the station to idle without a transfer
+           station back to idle 0.02 s after the request was withdrawn
+[FAIL] R8  Heartbeat watchdog: a silent vehicle stops the transfer with a fault code
+           the vehicle went silent for 2 s during the transfer and the station carried on: Ready, TransferActive
+[SKIP] R9  Dropping the request acknowledges and clears a fault
+           could not bring the station into a fault to acknowledge (see R8): Ready, TransferActive
+[PASS] R10 The conveyor stops when the vehicle leaves its position
+           conveyor stopped 0.02 s after the vehicle left its position (limit 1 s; station: Fault(code 3))
+
+Station does NOT conform. 8 passed, 1 failed, 1 not testable.
+```
+
+*Real output, against the bundled reference station with its watchdog switched off; address changed.*
+
+## Why
+
+VDA 5050 covers fleet controller to vehicle and expressly leaves out "interfaces to peripheral
+equipment". The handshake between vehicle and conveyor is therefore written again in every project,
+by two teams, and its mistakes show up at commissioning with the robot standing in front of the
+station. The rules are written down in [docs/SPEC.md](../../docs/SPEC.md); this tool lets the PLC
+programmer test the station side alone, at the desk or on site, days earlier.
+
+## Install
+
+```bash
+pip install handover-check
+```
+
+Python 3.11 or newer; Windows or Linux. No ROS and no robot needed.
+Offline bundles for machines without internet are attached to each
+[release](https://github.com/sulemanali5760/amr-station-handshake/releases).
+
+## Use
+
+Try it without a PLC, in two terminals:
+
+```bash
+handover-check station                        # reference station on opc.tcp://127.0.0.1:4860/station/
+handover-check run opc.tcp://127.0.0.1:4860/station/
+```
+
+```bash
+handover-check station --defect no_watchdog   # a station with one rule switched off
+```
+
+Against your PLC: describe where the eight signals live in a signal map (examples for the reference
+station, Siemens S7-1500 and Beckhoff TwinCAT 3 are in [`maps/`](maps)), then:
+
+```bash
+handover-check run opc.tcp://192.168.0.10:4840 --map my_station.yaml --station-is-safe
+```
+
+| Option | Purpose |
+|---|---|
+| `--t-ready 5` `--t-start 3` `--t-transfer 15` `--t-release 3` `--t-watchdog 2` `--t-stop 1` | the time limits of your plant specification, in seconds |
+| `--only R2 R8` | run selected rules |
+| `--report record.md` | Markdown report for the commissioning record |
+| `--json` | machine-readable output |
+| `--strict` | exit code 2 if a rule could not be tested |
+
+Exit code 0 = no rule failed, 1 = at least one rule failed.
+
+## It moves your conveyor
+
+The tool writes the request signals. On a real station that starts the conveyor.
+
+- For any endpoint that is not this computer it refuses to run without `--station-is-safe`.
+- Run it with the station in a test state, clear of people and loads.
+- It always writes both request bits back to FALSE when it ends, also after an error.
+- It is a commissioning aid. It is **not** a safety function and no substitute for the safety
+  validation of the station.
+
+## Tested
+
+The test suite starts the reference station over real OPC UA, once conforming and once for each of
+eight built-in defects, and expects the tester to report exactly the broken rule:
+
+| Defect in the station | Reported under |
+|---|---|
+| Ready on without a request | R1 |
+| Ready far too late | R2 |
+| conveyor starts before the vehicle is in position | R3 |
+| TransferActive still on with TransferDone | R4 |
+| outputs not cleared after release | R5 |
+| no heartbeat watchdog | R8 |
+| fault not cleared by the acknowledge | R9 |
+| conveyor keeps running when the vehicle leaves | R10 |
+
+A transfer that is too short to judge R8 or R10 is reported as "not testable", not as a pass.
+
+## Limits
+
+- **Not tested against a real PLC.** Only against the bundled reference station. The S7-1500 and
+  TwinCAT maps are examples; node ids depend on the project.
+- **No OPC UA security.** The tool connects anonymously without encryption. A PLC that demands
+  certificates or a login cannot be tested yet.
+- **Polling.** Signals are read every 25 ms by default, so measured times are accurate to a few
+  tens of milliseconds plus the network. It cannot see events shorter than that.
+- **The rules are this project's own** ([SPEC](../../docs/SPEC.md)), shaped after SEMI E84. They
+  are not a standard of any body, and a station built to another handshake will fail them.
+- **One vehicle, one station.** No carrier identification, no multi-lane stations.
+
+## Licence
+
+MIT

handover_check-0.1.0/src/handover_check.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/handover_check/__init__.py
+src/handover_check/__main__.py
+src/handover_check/checks.py
+src/handover_check/station.py
+src/handover_check.egg-info/PKG-INFO
+src/handover_check.egg-info/SOURCES.txt
+src/handover_check.egg-info/dependency_links.txt
+src/handover_check.egg-info/entry_points.txt
+src/handover_check.egg-info/requires.txt
+src/handover_check.egg-info/top_level.txt
+tests/test_checks.py

handover_check-0.1.0/src/handover_check.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

handover_check-0.1.0/src/handover_check.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+handover-check = handover_check.__main__:main

handover_check-0.1.0/src/handover_check.egg-info/requires.txt

@@ -0,0 +1,2 @@
+asyncua<3,>=1.1
+pyyaml>=6.0

handover_check-0.1.0/src/handover_check.egg-info/top_level.txt

@@ -0,0 +1 @@
+handover_check

handover_check-0.1.0/tests/test_checks.py

@@ -0,0 +1,135 @@
+"""The tester is only worth something if it catches a station that breaks a rule, and stays quiet on one
+that does not. Every test here runs it against the reference station over real OPC UA."""
+import asyncio
+import json
+
+import pytest
+
+from handover_check.__main__ import main, markdown, render
+from handover_check.checks import FAIL, PASS, RULES, SKIP, Limits, load_signal_map, run_checks
+from handover_check.station import DEFECTS, FAULT_AMR_LEFT, FAULT_HEARTBEAT_LOST, StationLogic, serve
+
+# Short times so the suite stays fast; the ratios are those of a real station.
+LIMITS = Limits(ready=1.0, start=0.6, transfer=3.0, release=0.8, watchdog=0.9, stop=0.5, hold=0.4)
+PORT = [48480]
+
+
+def check(defects=(), only=None, limits=LIMITS, **station):
+    PORT[0] += 1
+    endpoint = f"opc.tcp://127.0.0.1:{PORT[0]}/station/"
+    logic = StationLogic(ready_delay=0.15, transfer_time=station.pop("transfer_time", 1.6), watchdog=0.4,
+                         defects=frozenset(defects), **station)
+
+    async def go():
+        ready, stop = asyncio.Event(), asyncio.Event()
+        task = asyncio.create_task(serve(endpoint, logic, ready, stop))
+        await asyncio.wait_for(ready.wait(), 20)
+        try:
+            return await run_checks(endpoint, limits=limits, only=only, period=0.03)
+        finally:
+            stop.set()
+            await task
+    return {r.rule: r for r in asyncio.run(go())}
+
+
+def test_conforming_station_passes_every_rule():
+    results = check()
+    assert list(results) == list(RULES)
+    assert {r.status for r in results.values()} == {PASS}, render(list(results.values()), "x")
+    assert 0.1 < results["R2"].seconds < 0.6                 # the ready delay of 0.15 s is measured, not assumed
+    assert f"fault code {FAULT_HEARTBEAT_LOST}" in results["R8"].detail
+    assert f"code {FAULT_AMR_LEFT}" in results["R10"].detail
+
+
+@pytest.mark.parametrize("defect, rule, words", [
+    ("ready_without_request", "R1", "with no request"),
+    ("slow_ready", "R2", "no StationReady within"),
+    ("transfer_before_docked", "R3", "NOT in position"),
+    ("active_stays_on", "R4", "TransferActive is still on"),
+    ("ready_stuck", "R5", "still shows"),
+    ("no_watchdog", "R8", "went silent"),
+    ("fault_not_cleared", "R9", "still shows"),
+    ("ignores_undock", "R10", "still running"),
+])
+def test_each_defect_is_reported_under_its_rule(defect, rule, words):
+    only = [rule] if rule != "R2" else ["R2"]
+    r = check([defect], only=only)[rule]
+    assert r.status == FAIL, r
+    assert words in r.detail, r.detail
+
+
+def test_every_defect_has_a_test():
+    assert len(DEFECTS) == 8
+
+
+def test_a_broken_station_never_passes_everything():
+    """Whatever single defect the station has, the full run reports at least one FAIL."""
+    for defect in ("transfer_before_docked", "no_watchdog", "ready_stuck"):
+        statuses = [r.status for r in check([defect]).values()]
+        assert FAIL in statuses, (defect, statuses)
+
+
+def test_too_fast_transfer_is_reported_as_not_testable_not_as_pass():
+    """With a 0.2 s transfer the watchdog cannot show before the transfer ends: say so."""
+    r = check(only=["R8"], transfer_time=0.2)["R8"]
+    assert r.status == SKIP and "longer transfer" in r.detail
+
+
+def test_second_handover_fails_when_the_station_stays_latched():
+    r = check(["ready_stuck"], only=["R6"])["R6"]
+    assert r.status in (FAIL, SKIP) and "idle" in r.detail
+
+
+# ---------------------------------------------------------------- pure station logic, no network
+def test_station_logic_walks_the_normal_sequence():
+    s = StationLogic(ready_delay=1.0, transfer_time=2.0, watchdog=1.0)
+    assert not s.step(False, False, 0, 0.0).ready
+    s.step(True, False, 1, 0.1)
+    assert not s.step(True, False, 2, 0.5).ready
+    assert s.step(True, False, 3, 1.2).ready
+    assert s.step(True, True, 4, 1.3).transfer_active
+    out = s.step(True, True, 5, 3.4)
+    assert out.transfer_done and not out.transfer_active and out.ready
+    assert s.step(False, False, 6, 3.5) == type(out)()      # all off again
+
+
+def test_station_logic_faults_on_a_frozen_heartbeat():
+    s = StationLogic(ready_delay=0.0, transfer_time=10.0, watchdog=1.0)
+    for t in (0.0, 0.1, 0.2):
+        s.step(True, True, int(t * 10) + 1, t)
+    assert s.step(True, True, 3, 0.9).transfer_active        # same counter value, still inside the watchdog time
+    out = s.step(True, True, 3, 1.3)
+    assert out.fault and out.fault_code == FAULT_HEARTBEAT_LOST and not out.transfer_active
+
+
+# ---------------------------------------------------------------- command line and files
+def test_refuses_a_remote_station_without_the_safety_confirmation(capsys):
+    assert main(["run", "opc.tcp://192.168.0.10:4840"]) == 64
+    assert "--station-is-safe" in capsys.readouterr().err
+
+
+def test_unreachable_station_is_an_error_not_a_traceback(capsys):
+    assert main(["run", "opc.tcp://127.0.0.1:48479"]) == 64
+    assert "handover-check:" in capsys.readouterr().err
+
+
+def test_signal_map_must_name_all_eight_signals(tmp_path):
+    p = tmp_path / "map.yaml"
+    p.write_text("namespace_uri: urn:x\nnode_ids:\n  AmrDockRequest: a\n", encoding="utf-8")
+    with pytest.raises(ValueError, match="AmrInPosition"):
+        load_signal_map(p)
+
+
+def test_shipped_maps_load():
+    import pathlib
+    maps = sorted((pathlib.Path(__file__).parents[1] / "maps").glob("*.yaml"))
+    assert len(maps) == 3
+    for m in maps:
+        assert len(load_signal_map(m)["node_ids"]) == 8
+
+
+def test_reports():
+    results = list(check(only=["R1", "R2"]).values())
+    assert "[PASS] R1" in render(results, "opc.tcp://x") and "Station conforms." in render(results, "opc.tcp://x")
+    assert "| R2 |" in markdown(results, "opc.tcp://x")
+    assert json.dumps([r.__dict__ for r in results])