Skip to main content

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; this tool lets the PLC programmer test the station side alone, at the desk or on site, days earlier.

Install

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.

Use

Try it without a PLC, in two terminals:

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/
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/), then:

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
--security-policy Basic256Sha256 --security-mode SignAndEncrypt secure channel
--cert-dir DIR --server-cert plc.der client certificate folder (created on first use); the PLC's certificate, so its identity is checked
--user NAME log in; the password comes from the OPCUA_PASSWORD environment variable, never the command line

Exit code 0 = no rule failed, 1 = at least one rule failed.

A PLC with security on rejects the tool's new certificate (pki/client_cert.der) until it is added to the PLC's trusted certificates; that is the PLC protecting itself.

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.

A second server accepts only Basic256Sha256 + SignAndEncrypt with a user login: the tool reaches it with certificate and login and is refused without them and with a wrong password.

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.
  • OPC UA security is tested against asyncua only, not yet against a Siemens or Beckhoff server.
  • 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), 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

Metadata

Release files for handover-check 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for handover-check 0.2.0
File Size Uploaded Provenance Actions
handover_check-0.2.0.tar.gz 20.3 kB With provenance Details for handover_check-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for handover-check 0.2.0
File Interpreter ABI Platform Actions
handover_check-0.2.0-py3-none-any.whl Python 3 none any Details for handover_check-0.2.0-py3-none-any.whl

Total release size: 37.2 kB

Release files / handover_check-0.2.0.tar.gz

Download URL handover_check-0.2.0.tar.gz
Size 20.3 kB
Tags Source
SHA-256 checksum
How to use checksums
00c9bf789105f8d91d885a76fb5b468beee686b5359a9303b60e055f07f54c37
BLAKE2b-256 checksum
How to use checksums
0ec64316c02f0615958487bd349235d7a876ad2d7f1f61d85e4a0ddb1c3608cb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / handover_check-0.2.0-py3-none-any.whl

Download URL handover_check-0.2.0-py3-none-any.whl
Size 16.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
70c87958741cd053f9ec458dfaa35d643128ed9b039672cbad1b4231fc8bf331
BLAKE2b-256 checksum
How to use checksums
bf123ae54f3cd19865f3aa7cc672414a355670650515bda38a35468e27532c6b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for handover-check 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for handover_check-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page