velbus-spec-check

name	velbus-spec-check
description	Cross-check velbusaio/module_spec/*.json against the published Velbus protocol manuals from github.com/velbus/moduleprotocol. Fetches the protocol PDFs, extracts their text, and reports module-id/name mismatches and transmitted command bytes that are missing from a module's CommandToClass. Use when asked to verify the module specs against the Velbus module protocol, check for bugs in module_spec, or build/compare specs from the moduleprotocol repo.
disable-model-invocation	true

Velbus module_spec protocol check

Compares the repo's velbusaio/module_spec/*.json against the module protocol Velbus publishes at https://github.com/velbus/moduleprotocol, to surface likely bugs in the specs.

What it checks

The ground truth is the protocol repo: its README.md (module id -> name table, one PDF per module) and the command tables inside each PDF. Command bytes are written as H'NN', and each is preceded by a DLC ... = N databytes to send (module transmits -> must be decodable) or ... received (module receives -> the library sends it, no decoding needed) line.

• module-id byte: the COMMAND_MODULE_TYPE frame in the PDF must include the spec's hex id. Authoritative for single-module PDFs; ambiguous (review only) for manuals that cover several modules.
• transmit coverage: every byte the module transmits must appear in the merged CommandToClass (global.json + the module spec). A transmitted frame with no mapping is an undecodable message.
• name: spec Type vs the README name (the README has known typos, so this is review-only).

Only transmitted frames need a CommandToClass entry. Received/config frames (clock, memory, sensor-settings such as AB, AE, C0-C8, ...) are commonly absent by design and are not bugs.

Workflow

- [ ] Step 0: Choose the Python venv (VELBUS_VENV)
- [ ] Step 1: Fetch + extract the protocol (scripts/fetch_protocol.sh)
- [ ] Step 2: Run the checker (scripts/check_specs.py)
- [ ] Step 3: Confirm each finding against the PDF before changing a spec

Step 0: Choose the Python venv

The venv is not hardcoded. Ask the user for it (or reuse an already-activated one) and pass its root via the VELBUS_VENV environment variable. fetch_protocol.sh resolves the interpreter in this order: VELBUS_VENV/bin/python → VELBUS_PY → VIRTUAL_ENV/bin/python → python3. The check_specs.py / extract_pdf.py commands below run with "$VELBUS_VENV/bin/python", so export it once for the session.

Step 1: Fetch and extract

VELBUS_VENV="/path/to/venv" skills/velbus-spec-check/scripts/fetch_protocol.sh

This shallow-clones (or refreshes) the repo into /tmp/velbus_proto, ensures pypdf is in the chosen venv, and extracts every PDF to /tmp/velbus_proto/text/<stem>.txt. Extracting ~80 PDFs is slow on this host (~15 min) — background it with a generous block_until_ms (e.g. 900000) or poll /tmp/velbus_proto/text. Re-running reuses the clone; the text files are cached, so Step 2 is instant afterwards.

Step 2: Check the specs

"$VELBUS_VENV/bin/python" skills/velbus-spec-check/scripts/check_specs.py

Options: --module 1D (one module only), --proto DIR (protocol dir, default /tmp/velbus_proto), --repo DIR (repo root; auto-detected from the script location otherwise).

Output has two sections:

• ERRORS — a missing spec file, or a single-module PDF whose module-type byte does not match the spec id. Exit code is non-zero when any error is present.
• REVIEW — candidate bugs to confirm against the PDF: transmitted bytes absent from CommandToClass, name diffs, shared-PDF ambiguities, and modules with no published PDF.

Step 3: Confirm before editing

REVIEW items are candidates, not confirmed bugs. For each one, read the relevant PDF text and decide:

"$VELBUS_VENV/bin/python" skills/velbus-spec-check/scripts/extract_pdf.py \
    /tmp/velbus_proto/protocol_<module>.pdf | less

A transmit byte is a real bug only if it is a frame the library should decode (e.g. a status message) but has no CommandToClass entry. Ignore programming, memory, clock and sensor-configuration frames. When a spec is genuinely wrong, fix velbusaio/module_spec/<hex>.json and re-run Step 2 to confirm it clears.

Notes

• Combined manuals (e.g. vmbgp1_2_4.pdf covers GP1/GP2/GP4) only spell out one module's type byte and mix every sibling's commands, so those findings are flagged (shared PDF) and reported as review, not errors.
• Some modules (e.g. VMB1RYS-20, VMB6PBB, VMB1BLE) have no published PDF; they are reported as "not listed in README" and cannot be command-checked.
• The README has real quirks the checker reports verbatim: a duplicated 0x5C row and a VMBBEL1PIR-20 typo (spec Type is VMBEL1PIR-20).