Read-only map tools for commissioning work
Turn a vendor Modbus manual into a usable map
For controls, commissioning, and integration engineers. Give it a PDF or spreadsheet. Get a readable map plus JSON and CSV. If the manual is unclear, you get a short list of questions.
Install See the worked example When to use this
First 10 minutes
- Add the project once. The install steps are below.
- Ask for a user map from your local manual or spreadsheet, and name the measurements you actually need.
- Open the three files it writes: the readable map, the JSON, and the CSV.
You can say this in plain language:
Use this manual to make a user map for temperatures, operating status, alarms, and power. Give me a readable map plus JSON and CSV.
What it does with a messy table
This is a fictional commissioning table. 40001 becomes holding-register offset 0. 30001 becomes input-register offset 0. The read map keeps the readable points. Level Setpoint is recorded as write-only.
Source table
| Address | Name | Data Type | Byte Order | Access |
|---|---|---|---|---|
| 40001 | Tank Level | UINT16 | read-only | |
| 40003 | Flow Rate | FLOAT32 | CDAB | read-only |
| 30001 | Energy Total | UINT32 | ABCD | read-only |
| 40010 | Level Setpoint | UINT16 | write-only |
Finished user map
| Point | Name | Manual address | Area | Offset | Type |
|---|---|---|---|---|---|
| tank_level | Tank Level | 40001 | holding-register | 0 | uint16 |
| flow_rate | Flow Rate | 40003 | holding-register | 2 | float32 |
| energy_total | Energy Total | 30001 | input-register | 0 | uint32 |
Readable three points in the map Write-only Level Setpoint recorded as an exclusion
See the full example, including a separate table that pauses for a byte-order choice
Three jobs
Vendor file to user map
Turn a PDF or spreadsheet into a readable map, JSON, and CSV.
A 32-bit value that looks wrong
See every supported byte and word layout from one sample. You choose the layout that matches the device.
A polling setup from a checked map
Build a read-only Node-RED, Modpoll (BETA), or ModScan (BETA) setup. You enable it when you are ready to poll.
Install in Codex
These commands install the plugin in Codex:
git clone https://github.com/studioxvii/modbus-skills.git cd modbus-skills codex plugin marketplace add "$PWD" codex plugin add modbus-skills@modbus-skills
Other clients use a generated package:
- Cursor: use
dist/plugins/cursoras the local marketplace package. - Claude Code: use
dist/plugins/claude, then invoke a skill as/modbus-skills:check-map.
Build the client packages from the README.
Safety
These tools produce read-only maps, bounded poll plans, and a short question list when a manual is unclear.
Longer jobs
- Compile an OEM map into user outputs
- Extract PDF register evidence
- Review a raw source map end to end
- Confirm byte order from one sample
- Determine byte order from a one-read probe
- Remap address notation
- Build a declarative custom export
- Probe, resolve byte order, and finalize a tool pack
- Build a multi-target tool pack
- Analyze bounded read data
- Compare map revisions
Problems these cover
- Address offset vs. reference number
- Register area defines address identity
- Word and byte order
- Bit order is not byte order
- Serial requests need one queue
- Configured and observed poll rates can differ
- Unit identifier 0 is ambiguous
- Invalid read block boundaries
- Malformed or short responses
- Reusable Modpoll configuration
- Repeatable ModScan tests
- Versioned Modbus Poll projects
Everything it can do
| Task | What you get |
|---|---|
| Analyze Capture | Find problems in Modbus sample data |
| Apply Review | Apply batched map decisions safely |
| Build Custom Export | Build a declarative text or CSV export |
| Build Modpoll (BETA) | Build BETA Modpoll artifacts |
| Build ModScan (BETA) | Build a BETA ModScan read plan |
| Build Node-RED | Build a disabled Modbus read flow |
| Build Tool Pack | Build several Modbus tool outputs |
| Capture Sample | Build a bounded one-read probe |
| Check Byte Order | Compare every supported byte layout |
| Check Map | Run deterministic register-map checks |
| Compare Maps | Compare Modbus map revisions |
| Compile User Map | Compile an OEM map into ready user outputs |
| Extract PDF Map | Extract traceable rows from a PDF |
| Modbus Help | Choose the next Modbus skill or path |
| Normalize Map | Make Modbus map fields explicit |
| Parse Map | Parse a structured Modbus register map |
| Plan Reads | Compile bounded Modbus read blocks |
| Remap Addresses | Convert known Modbus address notation |
| Review Evidence | Group map evidence into exceptions |
| Review Map | Review a raw Modbus map end to end |