modbus-skills / site

# Modbus Skills

Read-only Modbus engineering workflows for Codex, Claude Code, Cursor, and other Agent Plugins 1.0 clients.

Turn a vendor manual, spreadsheet, or register map into a usable engineering file. The generated work is read-only.

## When to use

Use these skills when an engineer needs a user map, a byte-order comparison, a firmware-map diff, or a bounded read-only tool pack from vendor documentation. Register writes, network discovery, unbounded polling, and invented byte orders are out of scope.

Details: [when-to-use.md](when-to-use.md)

## Start here

1. [Compile User Map](skills/compile-user-map.html): OEM PDF or structured map to Markdown, JSON, and CSV.
2. [Check Byte Order](skills/check-byte-order.html): every supported layout from one raw sample.
3. [Build Tool Pack](skills/build-tool-pack.html): disabled read-only Node-RED, Modpoll (BETA), or ModScan (BETA) files.

If the next step is unclear, use [Modbus Help](skills/modbus-help.html).

## Worked example

[Compile a synthetic OEM table](examples/compile-user-map.html)

## Skills

- [Analyze Capture](skills/analyze-capture.html): Analyze bounded Modbus samples and report communication, timing, signal, and raw-word evidence. Use when the user has capture data, JSON/CSV samples, or asks about stale, missing, flatline, or signal-quality problems.
- [Apply Review](skills/apply-review.html): Apply a batch of explicit Modbus map decisions while preserving evidence, exclusions, holds, and audit history. Use when the user confirms layout, exclusion, or field decisions and wants them applied to a new reviewed map.
- [Build Custom Export](skills/build-custom-export.html): Build a deterministic declarative text or CSV export from a documented example and canonical Modbus map. Use when the user needs a reusable text or CSV exporter and not a Node-RED, Modpoll (BETA), or ModScan (BETA) adapter.
- [Build Modpoll (BETA)](skills/build-modpoll.html): Build deterministic read-only BETA artifacts for gavinying/modpoll or supported Witte Modbus Poll profiles. Use when the user asks for Modpoll, Witte Modbus Poll, gavinying CSV, or a Modpoll probe/final setup.
- [Build ModScan (BETA)](skills/build-modscan.html): Build deterministic read-only BETA ModScan setup, poll-plan, point-map, and protocol test-message artifacts. Use when the user asks for ModScan files, a ModScan read plan, or ModScan probe/final setup.
- [Build Node-RED](skills/build-node-red.html): Build deterministic read-only Node-RED Modbus flow JSON from a canonical map and compiled read plan. Use when the user asks for a Node-RED flow, Modbus flex-getter setup, or Node-RED probe/final capture path.
- [Build Tool Pack](skills/build-tool-pack.html): Build any selected combination of Node-RED, Modpoll (BETA), and ModScan (BETA) from one validated map and read plan. Use when the user wants multiple target tools, an undecided target set, or one combined probe/final pack.
- [Capture Sample](skills/capture-sample.html): Generate a bounded read-only probe pack and stop before the live Modbus read. Use when the user needs an operator-controlled sample, raw words for byte-order work, or a manual probe before decoding; the operator or enabled target tool creates capture.json only after confirmation.
- [Check Byte Order](skills/check-byte-order.html): Evaluate every supported byte and word layout from one immutable raw Modbus sample without choosing a winner. Use when byte order, word order, or multi-register decoding is unknown and raw words or a capture already exist.
- [Check Map](skills/check-map.html): Check a normalized Modbus map for identity, range, overlap, width, access, function, and byte-order problems. Use when the user wants deterministic lint/validation findings on a normalized or reviewed register map.
- [Compare Maps](skills/compare-maps.html): Compare two reviewed Modbus maps and report added, removed, moved, changed, and unresolved points. Use when the user compares firmware/map revisions or asks what changed between two validated maps.
- [Compile User Map](skills/compile-user-map.html): Compile an OEM Modbus PDF or structured register map plus measurement intent into an organized user map, JSON, CSV, and optional target outputs in one resumable run. Use when the user wants an organized user map or offline outputs from an OEM source rather than a specialist review chain.
- [Extract PDF Map](skills/extract-pdf-map.html): Extract traceable Modbus register candidates, source coverage, and page evidence from a PDF manual or bounded page range. Use when the source is a PDF register manual and the user wants extraction evidence before normalization or compilation.
- [Modbus Help](skills/modbus-help.html): Choose the next Modbus skill or short workflow from the user's goal and current artifact. Use when the user is unsure which Modbus skill to run, asks what to do next, or needs a safe path from their current artifact.
- [Normalize Map](skills/normalize-map.html): Normalize Modbus candidates into explicit offsets, areas, units, datatypes, widths, access, and byte-order states. Use when candidate rows exist and need canonical engineering fields, holds, and source-preserving normalization.
- [Parse Map](skills/parse-map.html): Parse structured Modbus register maps into candidate rows with source values, rejected rows, assumptions, and holds. Use when the source is CSV, JSON, XML, XLSX, or structured text and needs traceable candidate rows.
- [Plan Reads](skills/plan-reads.html): Compile validated Modbus points into deterministic, bounded read blocks for function codes 01 through 04. Use when a validated map is ready and the user needs a read plan before building Node-RED, Modpoll (BETA), ModScan (BETA), or a tool pack.
- [Remap Addresses](skills/remap-addresses.html): Preview and apply a known map-wide conversion between Modbus offsets and Modicon reference notation. Use when the user asks to convert 40001-style references, protocol offsets, or another known address convention across a map.
- [Review Evidence](skills/review-evidence.html): Review Modbus source evidence with automated checks and a grouped exception queue, avoiding page-by-page or row-by-row approval. Use when source evidence needs status grouping, exception decisions, or confirmation of a bounded extraction scope.
- [Review Map](skills/review-map.html): Review a raw or messy Modbus register map through parsing, normalization, linting, and grouped evidence exceptions when source review itself is the requested outcome. Use when the user wants end-to-end source-map review rather than an organized user-map compile.

## Analyze Capture

Analyze bounded Modbus samples and report communication, timing, signal, and raw-word evidence. Use when the user has capture data, JSON/CSV samples, or asks about stale, missing, flatline, or signal-quality problems.

Example: Use $analyze-capture to inspect this bounded Modbus capture.
## Apply Review

Apply a batch of explicit Modbus map decisions while preserving evidence, exclusions, holds, and audit history. Use when the user confirms layout, exclusion, or field decisions and wants them applied to a new reviewed map.

Example: Use $apply-review to apply this batch of confirmed map decisions.
## Build Custom Export

Build a deterministic declarative text or CSV export from a documented example and canonical Modbus map. Use when the user needs a reusable text or CSV exporter and not a Node-RED, Modpoll (BETA), or ModScan (BETA) adapter.

Example: Use $build-custom-export to reproduce this documented export format.
## Build Modpoll (BETA)

Build deterministic read-only BETA artifacts for gavinying/modpoll or supported Witte Modbus Poll profiles. Use when the user asks for Modpoll, Witte Modbus Poll, gavinying CSV, or a Modpoll probe/final setup.

Example: Use $build-modpoll to build artifacts for this Modpoll profile.
## Build ModScan (BETA)

Build deterministic read-only BETA ModScan setup, poll-plan, point-map, and protocol test-message artifacts. Use when the user asks for ModScan files, a ModScan read plan, or ModScan probe/final setup.

Example: Use $build-modscan to build a read-only ModScan setup.
## Build Node-RED

Build deterministic read-only Node-RED Modbus flow JSON from a canonical map and compiled read plan. Use when the user asks for a Node-RED flow, Modbus flex-getter setup, or Node-RED probe/final capture path.

Example: Use $build-node-red to build a disabled read-only Node-RED flow.
## Build Tool Pack

Build any selected combination of Node-RED, Modpoll (BETA), and ModScan (BETA) from one validated map and read plan. Use when the user wants multiple target tools, an undecided target set, or one combined probe/final pack.

Example: Use $build-tool-pack to build these selected target outputs.
## Capture Sample

Generate a bounded read-only probe pack and stop before the live Modbus read. Use when the user needs an operator-controlled sample, raw words for byte-order work, or a manual probe before decoding; the operator or enabled target tool creates capture.json only after confirmation.

Example: Use $capture-sample to build a one-read probe for this point.
## Check Byte Order

Evaluate every supported byte and word layout from one immutable raw Modbus sample without choosing a winner. Use when byte order, word order, or multi-register decoding is unknown and raw words or a capture already exist.

Example: Use $check-byte-order to evaluate every layout for these raw words.
## Check Map

Check a normalized Modbus map for identity, range, overlap, width, access, function, and byte-order problems. Use when the user wants deterministic lint/validation findings on a normalized or reviewed register map.

Example: Use $check-map to validate this normalized Modbus map.
## Compare Maps

Compare two reviewed Modbus maps and report added, removed, moved, changed, and unresolved points. Use when the user compares firmware/map revisions or asks what changed between two validated maps.

Example: Use $compare-maps to compare these reviewed register maps.
## Compile User Map

Compile an OEM Modbus PDF or structured register map plus measurement intent into an organized user map, JSON, CSV, and optional target outputs in one resumable run. Use when the user wants an organized user map or offline outputs from an OEM source rather than a specialist review chain.

Example: Use $compile-user-map to turn this OEM map and measurement intent into organized user-map outputs.
## Extract PDF Map

Extract traceable Modbus register candidates, source coverage, and page evidence from a PDF manual or bounded page range. Use when the source is a PDF register manual and the user wants extraction evidence before normalization or compilation.

Example: Use $extract-pdf-map to extract register rows from these PDF pages.
## Modbus Help

Choose the next Modbus skill or short workflow from the user's goal and current artifact. Use when the user is unsure which Modbus skill to run, asks what to do next, or needs a safe path from their current artifact.

Example: Use $modbus-help to choose the next skill for my goal.
## Normalize Map

Normalize Modbus candidates into explicit offsets, areas, units, datatypes, widths, access, and byte-order states. Use when candidate rows exist and need canonical engineering fields, holds, and source-preserving normalization.

Example: Use $normalize-map to normalize these candidate register rows.
## Parse Map

Parse structured Modbus register maps into candidate rows with source values, rejected rows, assumptions, and holds. Use when the source is CSV, JSON, XML, XLSX, or structured text and needs traceable candidate rows.

Example: Use $parse-map to parse this register list into traceable candidates.
## Plan Reads

Compile validated Modbus points into deterministic, bounded read blocks for function codes 01 through 04. Use when a validated map is ready and the user needs a read plan before building Node-RED, Modpoll (BETA), ModScan (BETA), or a tool pack.

Example: Use $plan-reads to compile safe reads for this validated map.
## Remap Addresses

Preview and apply a known map-wide conversion between Modbus offsets and Modicon reference notation. Use when the user asks to convert 40001-style references, protocol offsets, or another known address convention across a map.

Example: Use $remap-addresses to preview this address-convention change.
## Review Evidence

Review Modbus source evidence with automated checks and a grouped exception queue, avoiding page-by-page or row-by-row approval. Use when source evidence needs status grouping, exception decisions, or confirmation of a bounded extraction scope.

Example: Use $review-evidence to automate checks and group these source exceptions.
## Review Map

Review a raw or messy Modbus register map through parsing, normalization, linting, and grouped evidence exceptions when source review itself is the requested outcome. Use when the user wants end-to-end source-map review rather than an organized user-map compile.

Example: Use $review-map to review this raw register map without guessing.

## Workflow: Compile an OEM map into user outputs

Produce an organized user map and requested offline outputs in one resumable outcome run.

1. compile-user-map: modbus-compile-request/v1 -> modbus-compile-result/v1

## Workflow: Extract PDF register evidence

Turn a PDF manual or bounded page range into traceable candidates and grouped extraction exceptions without performing source-map review.

1. extract-pdf-map: pdf-source/v1 -> candidate-map/v1
2. review-evidence: candidate-map/v1 -> modbus-map-evidence-review/v1
3. human-gate: candidate-map/v1, modbus-map-evidence-review/v1 -> modbus-review-decisions/v1

## Workflow: Review a raw source map end to end

Produce a reviewed draft and compact exception queue when source-map review itself is the requested outcome.

1. review-map: source-bundle/v1 -> modbus-map-evidence-review/v1
2. human-gate: modbus-map/v1, modbus-map-evidence-review/v1 -> modbus-review-decisions/v1
3. apply-review: modbus-map/v1, modbus-review-decisions/v1 -> modbus-map/v1

## Workflow: Confirm byte order from one sample

Evaluate every supported layout from one immutable sample, record one human confirmation, and apply it.

1. check-byte-order: capture/v1 -> modbus-byte-order-evidence/v1
2. human-gate: modbus-map/v1, modbus-byte-order-evidence/v1 -> modbus-review-decisions/v1
3. apply-review: modbus-map/v1, modbus-review-decisions/v1, modbus-byte-order-evidence/v1 -> modbus-map/v1

## Workflow: Determine byte order from a one-read probe

Build a bounded probe with capture-sample when raw words are missing. After live-read confirmation, an operator or enabled target tool runs the gated read. Byte-order confirmation follows.

1. capture-sample: probe-request/v1 -> modbus-tool-pack/v1
2. external-gate: modbus-tool-pack/v1 -> capture/v1
3. confirm-byte-order: modbus-map/v1, capture/v1 -> modbus-map/v1

## Workflow: Remap address notation

Preview and apply a known map-wide conversion between protocol offsets and Modicon-style references, then lint the converted map.

1. remap-addresses: modbus-map/v1, address-convention-request/v1 -> modbus-address-remap/v1
2. check-map: modbus-address-remap/v1 -> modbus-map-lint/v1

## Workflow: Build a declarative custom export

Reproduce a documented text or CSV export from a reviewed map without executing supplied code.

1. check-map: modbus-map/v1 -> modbus-map-lint/v1
2. build-custom-export: modbus-map/v1, export-example/v1 -> custom-export/v1

## Workflow: Probe, resolve byte order, and finalize a tool pack

Use a selected tool target to collect one raw sample, confirm byte order, then regenerate all selected targets with the confirmed layout.

1. plan-reads: modbus-map/v1 -> modbus-read-plan/v1
2. build-tool-pack: modbus-map/v1, modbus-read-plan/v1, probe-tool-pack-request/v1 -> modbus-tool-pack/v1
3. external-gate: modbus-tool-pack/v1 -> capture/v1
4. confirm-byte-order: modbus-map/v1, capture/v1 -> modbus-map/v1
5. plan-reads: modbus-map/v1 -> modbus-read-plan/v1
6. build-tool-pack: modbus-map/v1, modbus-read-plan/v1, final-tool-pack-request/v1 -> modbus-tool-pack/v1

## Workflow: Build a multi-target tool pack

Generate any selected combination of Node-RED, Modpoll (BETA), and ModScan (BETA) from one validated map and one read plan.

1. check-map: modbus-map/v1 -> modbus-map-lint/v1
2. plan-reads: modbus-map/v1 -> modbus-read-plan/v1
3. build-tool-pack: modbus-map/v1, modbus-read-plan/v1, tool-pack-request/v1 -> modbus-tool-pack/v1

## Workflow: Analyze bounded read data

Find communication and signal-quality problems without issuing control commands.

1. analyze-capture: capture/v1 -> modbus-capture-analysis/v1
2. human-gate: modbus-capture-analysis/v1 -> review-disposition/v1

## Workflow: Compare map revisions

Report stable field changes without collapsing points from different routes, areas, or unit identifiers.

1. review-source-map: before-source-bundle/v1 -> before-modbus-map/v1
2. review-source-map: after-source-bundle/v1 -> after-modbus-map/v1
3. compare-maps: before-modbus-map/v1, after-modbus-map/v1 -> modbus-map-diff/v1
4. human-gate: modbus-map-diff/v1 -> review-disposition/v1

## Problem: Users and tools can mix zero-based protocol offsets with one-based or 3xxxx/4xxxx reference notation.

The Modbus application protocol defines PDU starting addresses from zero. A Pymodbus issue also shows a user explicitly mapping 30001 to address 0.

Sources: https://modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf, https://github.com/pymodbus-dev/pymodbus/issues/2565
## Problem: The same numeric offset can exist in coils, discrete inputs, input registers, and holding registers.

A Pymodbus simulator discussion documents user confusion when holding and input register blocks appear to share numeric positions.

Sources: https://github.com/pymodbus-dev/pymodbus/discussions/2531
## Problem: Values wider than 16 bits can require different word and byte layouts.

A FluentModbus issue records a request for big-endian, little-endian, and byte-swapped variants. The Witte Modbus Poll manual also documents arbitrary word and byte order for wider types.

Sources: https://github.com/Apollo3zehn/FluentModbus/issues/27, https://www.modbustools.com/mbpoll-user-manual.html
## Problem: Coil and packed-bit order can be confused with multi-register byte order.

A Pymodbus issue reports reversed bit interpretation while explicitly distinguishing it from byte and word endian concerns.

Sources: https://github.com/pymodbus-dev/pymodbus/issues/2311
## Problem: Several independent polls on one serial route can contend and fail when requests are not queued.

A node-red-contrib-modbus issue reports failures with multiple RTU unit identifiers on one serial port and requests per-route queuing.

Sources: https://github.com/BiancoRoyal/node-red-contrib-modbus/issues/161, https://github.com/BiancoRoyal/node-red-contrib-modbus
## Problem: A configured polling interval can differ from observed request frequency.

A Home Assistant issue reports Modbus sensors polling more often than the configured scan interval.

Sources: https://github.com/home-assistant/core/issues/146246
## Problem: Unit identifier zero has transport and tool-specific behavior and can represent broadcast behavior in serial contexts.

A node-red-contrib-modbus issue records inconsistent Unit ID 0 validation. Tool documentation also exposes Unit ID 0 behavior, so generated read workflows must not silently choose it.

Sources: https://github.com/BiancoRoyal/node-red-contrib-modbus/issues/274, https://www.modbustools.com/modbus_poll.html
## Problem: A read block can become invalid when its start and quantity cross the server's defined data range.

The official protocol defines exception 02 for an invalid address and transfer-length combination. A Pymodbus discussion shows users working to restrict undefined register ranges.

Sources: https://www.modbus.org/file/secure/modbusprotocolspecification.pdf, https://github.com/pymodbus-dev/pymodbus/discussions/2268
## Problem: A device can return a byte count or frame length that does not match the received payload.

A Pymodbus issue documents a response whose declared length and received bytes disagree.

Sources: https://github.com/pymodbus-dev/pymodbus/issues/2303
## Problem: Site work benefits from a reusable configuration that defines poll blocks and named references.

The gavinying/modpoll project documents device, poll, and ref CSV records and describes configuration reuse for device polling.

Sources: https://github.com/gavinying/modpoll
## Problem: Production and commissioning tests need repeatable request and expected-response sequences.

WinTECH documents ModScan test scripts as editable message sequences that can run in a loop and log results.

Sources: https://www.win-tech.com/html/modscan32.htm
## Problem: A reusable Modbus Poll setup needs a documented and versioned file contract.

Witte documents OLE automation and publishes a Modbus Poll version 12 human-readable XML example.

Sources: https://www.modbustools.com/mbpoll-user-manual.html, https://www.modbustools.com/pollxml.html