@fa_yoshinobu/node-red-contrib-plc-comm-slmp 0.2.3 → 0.2.13

package/CHANGELOG.md

@@ -1,24 +1,80 @@
-# Changelog
-
-## Unreleased
-
-## 0.2.3 - 2026-04-13
-
-- CI now checks out `plc-comm-slmp-cross-verify/specs/shared` before running the shared-vector tests, so the Node package validates against the canonical cross-library parity vectors.
-
-## 0.2.2 - 2026-04-01
-
-- add an optional `npm run smoke:editor` script that installs the local package into an isolated userDir, starts a temporary Node-RED runtime, imports `slmp-basic-read-write.json`, and verifies the flow starts cleanly
-- refresh README, user guide, and example-flow docs with the editor-smoke command and the current canonical-address helper exports
-
-## 0.2.1 - 2026-03-28
-
-- move npm package publishing to the scoped name `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`
-- refresh README and user documentation for Flow Library submission, npm badges, and scoped install commands
-
-## 0.2.0 - 2026-03-28
-
-- add `slmp-connection`, `slmp-read`, and `slmp-write` nodes for binary 3E/4E over TCP and UDP
-- add named address helpers including `,count`, string access, route overrides, and connection control messages
-- add editor validation, example flows, README improvements, and user/maintainer documentation
-- add local test coverage and package dry-run validation
+# Changelog
+
+## Unreleased
+
+## 0.2.12 - 2026-05-02
+
+- bump the release revision for npm and Node-RED Flow Library publishing; the Flow Library currently shows `0.2.3` as the public baseline
+- refresh README, user-guide, latest-verification, and example-flow docs with compatibility notes from the published Flow Library version
+- document the public compatibility change from separate `PLC series` / `frame type` fields to one `PLC type` selector
+- document the public device-scope changes since Flow Library `0.2.3`: `LTS`, `LTC`, `LSTS`, `LSTC`, `LCS`, `LCC`, and `LZ` are now in the high-level surface where the selected PLC type supports them
+- document the current device-matrix flow behavior: one-click run-all read/write buttons, status-lamp feedback, JSONL result logging, `plcFamily` records, and skip/error summary counts
+
+## 0.2.11 - 2026-05-02
+
+- remove the interim device-range catalog helper from the Node-RED package
+- keep ordinary Node-RED read/write validation to address format and protocol constraints, leaving actual device-range errors to the PLC response
+- reject device codes that the selected `plcFamily` does not expose in the public high-level table, aligned with the .NET `DEVICE_RANGES.md` support matrix
+
+- remove stale user-guide and TODO wording that still described `LCS` and `LCC`
+  as future support; the high-level helpers route reads through direct bit read
+  and writes through random bit write (`0x1402`)
+- keep `G` and `HG` out of the default public device-matrix flow while they
+  remain routed-device follow-up items
+
+## 0.2.10 - 2026-04-27
+
+- tighten SLMP device-name parsing to split by known device code instead of a greedy letter regex, so hexadecimal addresses such as `XFF` and `SWFF` parse correctly
+- fail matched-device invalid numbers as that device code instead of treating them as a different unknown code shape
+
+## 0.2.9 - 2026-04-27
+
+- add packaged helper support for remote control, memory read/write, extend-unit read/write, and label array/random read/write commands
+- add low-level tests for the new helper payloads and response parsing
+- expand Node-RED wrapper participation in the shared cross-library parity suite
+
+## 0.2.8 - 2026-04-27
+
+- tighten long-device route guards so `LTN/LSTN/LCN/LZ` avoid unsupported direct/raw word and dword paths, while supported random/named dword paths remain available
+- align `LCS/LCC` writes with the random/named bit route policy
+
+## 0.2.7 - 2026-04-14
+
+- require explicit `plcFamily` on the standard packaged client and connection-node route, while keeping manual frame/profile selection only for internal diagnostic paths
+- switch the standard device-range example to the interim catalog helper so the high-level Node surface consistently derives frame, profile, address, and range handling from one family selection
+
+## 0.2.6 - 2026-04-14
+
+- replace connection-node `plcSeries` / `frameType` selection with one explicit `plcFamily` that derives the fixed frame, access profile, address-family, and range-family defaults
+- make high-level `X/Y` string addresses require explicit `plcFamily`, treat `iq-f` `X/Y` as octal, and refresh tests, docs, and example flows for the stricter family-driven model
+
+## 0.2.5 - 2026-04-14
+
+- add interim device-range catalog helpers and CPU operation-state support to the packaged SLMP client surface
+- add regression tests and README coverage for the new device-range and CPU-state helpers
+
+## 0.2.4 - 2026-04-13
+
+- add client-side guard logic for unsupported long-timer direct reads and unsupported `LCS/LCC` random, block, and monitor-registration commands
+- align long-counter helper behavior and core tests with the shared cross-library consistency rules
+
+## 0.2.3 - 2026-04-13
+
+- CI now checks out `plc-comm-slmp-cross-verify/specs/shared` before running the shared-vector tests, so the Node package validates against the canonical cross-library parity vectors.
+
+## 0.2.2 - 2026-04-01
+
+- add an optional `npm run smoke:editor` script that installs the local package into an isolated userDir, starts a temporary Node-RED runtime, imports `slmp-basic-read-write.json`, and verifies the flow starts cleanly
+- refresh README, user guide, and example-flow docs with the editor-smoke command and the current canonical-address helper exports
+
+## 0.2.1 - 2026-03-28
+
+- move npm package publishing to the scoped name `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`
+- refresh README and user documentation for Flow Library submission, npm badges, and scoped install commands
+
+## 0.2.0 - 2026-03-28
+
+- add `slmp-connection`, `slmp-read`, and `slmp-write` nodes for binary 3E/4E over TCP and UDP
+- add named address helpers including `,count`, string access, route overrides, and connection control messages
+- add editor validation, example flows, README improvements, and user/maintainer documentation
+- add local test coverage and package dry-run validation

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 yoshinobu
-
-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.
+MIT License
+
+Copyright (c) 2026 yoshinobu
+
+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.

package/README.md

@@ -1,168 +1,228 @@
-[![CI](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/actions/workflows/ci.yml/badge.svg)](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/%40fa_yoshinobu%2Fnode-red-contrib-plc-comm-slmp?logo=npm&color=CB3837)](https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-slmp)
-[![npm downloads](https://img.shields.io/npm/dm/%40fa_yoshinobu%2Fnode-red-contrib-plc-comm-slmp?logo=npm&color=CB3837)](https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-slmp)
-![Node-RED version](https://img.shields.io/badge/Node--RED-%E2%89%A53.0-B41F27?logo=nodered&logoColor=white)
-![Node.js version](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?logo=node.js&logoColor=white)
-![SLMP frame](https://img.shields.io/badge/SLMP-Binary%203E%20%2F%204E-005BAC)
-![Transport](https://img.shields.io/badge/Transport-TCP%20%2F%20UDP-0A7D5C)
-![License](https://img.shields.io/badge/License-MIT-1F6FEB)
-
-# Node-RED SLMP Nodes for Mitsubishi PLCs
-
-![Node-RED SLMP hero](https://raw.githubusercontent.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/main/docsrc/assets/node-red-slmp.png)
-
-Node-RED nodes for Mitsubishi PLC communication over SLMP binary 3E/4E frames.
-
-This package uses the same named-device foundation as the SLMP libraries, extended here with Node-RED-friendly count and string forms:
-
-- `D100`
-- `D100,10`
-- `D200:F`
-- `D200:F,4`
-- `D300:L`
-- `D50.3`
-- `M1000`
-- `M1000,8`
-- `D100:STR,10`
-- `DSTR100,10`
-
-This package is documented for the high-level Node-RED workflow only:
-
-- `slmp-connection`
-- `slmp-read`
-- `slmp-write`
-
-## Quick Start
-
-1. Install the package into your Node-RED user directory and restart Node-RED.
-2. Add one `slmp-connection` config node and set `host`, `port`, `transport`, `PLC series`, and `frame type`.
-3. Add `slmp-read` for the first smoke test, using a safe address such as `D300`, `D300,4`, or `DSTR320,10`.
-4. When read works, add `slmp-write` and use known-safe test devices before moving to production addresses.
-
-If you are working from this repository, import one of the ready-to-run flows under [examples/flows](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/README.md) first. The safest first choices are:
-
-- [`slmp-basic-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-basic-read-write.json) for plain TCP scalar read/write
-- [`slmp-array-string.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-array-string.json) for `,count` and string access
-- [`slmp-device-matrix.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-device-matrix.json) for one-by-one high-level coverage across the matrix catalog
-- [`slmp-udp-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-udp-read-write.json) for UDP validation
-
-Start with `D` word devices for the first smoke test. Do not start with `slmp-device-matrix.json`.
-
-## Release Information
-
-- package name: `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`
-- package version: `0.2.3`
-- npm package: <https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-slmp>
-- Node-RED requirement: `>=3.0.0`
-- Node.js requirement: `>=18`
-- changelog: <https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/CHANGELOG.md>
-
-Install from npm:
-
-```bash
-cd ~/.node-red
-npm install @fa_yoshinobu/node-red-contrib-plc-comm-slmp
-```
-
-Install from this repository:
-
-```bash
-cd ~/.node-red
-npm install /path/to/node-red-contrib-plc-comm-slmp
-```
-
-Optional local editor smoke test from the repository root:
-
-```bash
-npm run smoke:editor
-```
-
-This command installs the local package into an isolated temporary userDir, starts a temporary Node-RED runtime, imports `slmp-basic-read-write.json`, verifies the flow starts, and then shuts the runtime down again.
-
-Legacy note:
-
-- the original unscoped `node-red-contrib-plc-comm-slmp@0.2.0` remains on npm, but new releases move to the scoped package name above
-
-## Supported PLC Registers
-
-Start with these register/device families first:
-
-- word devices: `D`, `SD`, `R`, `ZR`, `TN`, `CN`
-- bit devices: `M`, `X`, `Y`, `SM`, `B`
-- typed forms: `D200:F`, `D300:L`
-- special Node-RED forms: `D100,10`, `M1000,8`, `D100:STR,10`, `DSTR100,10`
-- bit-in-word form: `D50.3`
-
-See the full public table in [Supported PLC Registers](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/SUPPORTED_REGISTERS.md).
-
-## Documentation
-
-- [Getting Started](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/GETTING_STARTED.md)
-- [Supported PLC Registers](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/SUPPORTED_REGISTERS.md)
-- [Latest Communication Verification](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/LATEST_COMMUNICATION_VERIFICATION.md)
-- [User Guide](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/USER_GUIDE.md)
-- [Example Flows](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/README.md)
-- [Documentation Index](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/index.md)
-
-Maintainer-only notes and retained evidence live under `internal_docs/`.
-
-## What You Can Do
-
-- Binary 3E and 4E frames
-- TCP and UDP transport
-- reusable `slmp-connection`
-- high-level reads and writes through `slmp-read` and `slmp-write`
-- typed source selection for literal / `msg` / `flow` / `global` / `env`
-- per-request routing via `msg.target` or configured route sources
-- read output selection for object / array / single value
-- metadata emission selection for `msg.slmp`
-- configurable error handling with throw / `msg.error` / second output
-- connection control via `connect` / `disconnect` / `reinitialize` messages
-
-Set `frame type` and `PLC series` explicitly for each connection.
-
-## Current Public Register Scope
-
-- bit devices: `SM`, `X`, `Y`, `M`, `L`, `F`, `V`, `B`, `TS`, `TC`, `STS`, `STC`, `CS`, `CC`, `SB`, `DX`, `DY`
-- word devices: `SD`, `D`, `W`, `TN`, `LTN`, `STN`, `LSTN`, `CN`, `LCN`, `SW`, `Z`, `R`, `ZR`, `RD`
-- typed views: `:S`, `:D`, `:L`, `:F`
-- string/count views: `,count`, `:STR`, `DSTR`
-- word-bit view: `.bit`
-
-Validated public hardware summary:
-
-- `FX5UC-32MT/D`
-- `Q06UDVCPU`
-- `R08CPU`
-
-## Example Flows
-
-- [`slmp-demo.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-demo.json): combined demo
-- [`slmp-basic-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-basic-read-write.json): scalar, float, and bit read/write over TCP
-- [`slmp-array-string.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-array-string.json): array and string read/write over TCP
-- [`slmp-control-error.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-control-error.json): control messages, `msg` source, and second-output errors
-- [`slmp-device-matrix.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-device-matrix.json): one-by-one high-level read, write, and readback across the matrix catalog with completed-result history, run summary, and JSONL logging in `Node-RED userDir/logs/slmp-device-matrix-<session>.jsonl`
-- [`slmp-routing.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-routing.json): per-request routing with `msg.target`
-- [`slmp-udp-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-udp-read-write.json): basic UDP read/write
-
-## Known Limitations
-
-- set `frame type` and `PLC series` explicitly for each connection
-- `.bit,count` is not supported
-- a single client connection keeps requests serialized by default
-- the read and write nodes keep the caller-visible logical request shape and do not silently retry with a different fallback split semantics
-- `LTS`, `LTC`, `LSTS`, `LSTC`, `LCS`, `LCC`, `LZ`, `G`, and `HG` are not part of the current public high-level register table
-
-## Development
-
-Run the local test suite:
-
-```bash
-cmd /c npm.cmd test
-```
-
-## Notes
-
-- `.bit` notation is only valid for word devices such as `D50.3`
-- direct bit devices should be addressed directly as `M1000`, `X1F`, `Y20`
-- random read batching follows the Python helper layer for batchable word devices
+[![CI](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/actions/workflows/ci.yml/badge.svg)](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/%40fa_yoshinobu%2Fnode-red-contrib-plc-comm-slmp?logo=npm&color=CB3837)](https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-slmp)
+[![npm downloads](https://img.shields.io/npm/dm/%40fa_yoshinobu%2Fnode-red-contrib-plc-comm-slmp?logo=npm&color=CB3837)](https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-slmp)
+![Node-RED version](https://img.shields.io/badge/Node--RED-%E2%89%A53.0-B41F27?logo=nodered&logoColor=white)
+![Node.js version](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?logo=node.js&logoColor=white)
+![SLMP frame](https://img.shields.io/badge/SLMP-Binary%203E%20%2F%204E-005BAC)
+![Transport](https://img.shields.io/badge/Transport-TCP%20%2F%20UDP-0A7D5C)
+![License](https://img.shields.io/badge/License-MIT-1F6FEB)
+
+# Node-RED SLMP Nodes for Mitsubishi PLCs
+
+![Node-RED SLMP hero](https://raw.githubusercontent.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/main/docsrc/assets/node-red-slmp.png)
+
+Node-RED nodes for Mitsubishi PLC communication over SLMP binary 3E/4E frames.
+
+This package uses the same named-device foundation as the SLMP libraries, extended here with Node-RED-friendly count and string forms:
+
+- `D100`
+- `D100,10`
+- `D200:F`
+- `D200:F,4`
+- `D300:L`
+- `D50.3`
+- `M1000`
+- `M1000,8`
+- `D100:STR,10`
+- `DSTR100,10`
+
+This package is documented for the high-level Node-RED workflow only:
+
+- `slmp-connection`
+- `slmp-read`
+- `slmp-write`
+
+## Quick Start
+
+1. Install the package into your Node-RED user directory and restart Node-RED.
+2. Add one `slmp-connection` config node and set `host`, `port`, `transport`, and `PLC type`.
+3. Add `slmp-read` for the first smoke test, using a safe address such as `D300`, `D300,4`, or `DSTR320,10`.
+4. When read works, add `slmp-write` and use known-safe test devices before moving to production addresses.
+
+If you are working from this repository, import one of the ready-to-run flows under [examples/flows](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/README.md) first. The safest first choices are:
+
+- [`slmp-basic-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-basic-read-write.json) for plain TCP scalar read/write
+- [`slmp-array-string.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-array-string.json) for `,count` and string access
+- [`slmp-device-matrix.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-device-matrix.json) for one-by-one and run-all high-level coverage across the matrix catalog
+- [`slmp-udp-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-udp-read-write.json) for UDP validation
+
+Start with `D` word devices for the first smoke test. Do not start with `slmp-device-matrix.json`.
+
+## Release Information
+
+- package name: `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`
+- package version: `0.2.12`
+- npm package: <https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-slmp>
+- Node-RED requirement: `>=3.0.0`
+- Node.js requirement: `>=18`
+- changelog: <https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/CHANGELOG.md>
+
+Install from npm:
+
+```bash
+cd ~/.node-red
+npm install @fa_yoshinobu/node-red-contrib-plc-comm-slmp
+```
+
+Install from this repository:
+
+```bash
+cd ~/.node-red
+npm install /path/to/node-red-contrib-plc-comm-slmp
+```
+
+Optional local editor smoke test from the repository root:
+
+```bash
+npm run smoke:editor
+```
+
+This command installs the local package into an isolated temporary userDir, starts a temporary Node-RED runtime, imports `slmp-basic-read-write.json`, verifies the flow starts, and then shuts the runtime down again.
+
+Legacy note:
+
+- the original unscoped `node-red-contrib-plc-comm-slmp@0.2.0` remains on npm, but new releases move to the scoped package name above
+
+### Changes Since Flow Library 0.2.3
+
+The Node-RED Flow Library currently shows `0.2.3` as the published baseline for this scoped package. Check these changes before updating an existing flow:
+
+- `slmp-connection` now uses one `PLC type` selector. Older `PLC series` and `frame type` fields from Flow Library `0.2.3` flows must be reselected after import.
+- `X/Y` string addresses are PLC-type-specific: iQ-F uses octal `X/Y`, while the other supported PLC types use hexadecimal `X/Y`.
+- `LTS`, `LTC`, `LSTS`, `LSTC`, `LCS`, `LCC`, and `LZ` are now in the high-level surface where the selected PLC type supports them.
+- Device codes unsupported by the selected PLC type are errors by default. The `slmp-device-matrix.json` sample can instead log them as `SKIPPED` records when it sends `slmpSkipUnsupported`.
+
+## Supported PLC Registers
+
+Start with these register/device families first:
+
+- word devices: `D`, `SD`, `R`, `ZR`, `TN`, `CN`
+- bit devices: `M`, `X`, `Y`, `SM`, `B`
+- typed forms: `D100:S`, `D100:I`, `D200:F`, `D300:L`
+- special Node-RED forms: `D100,10`, `M1000,8`, `D100:STR,10`, `DSTR100,10`
+- bit-in-word form: `D50.3`
+
+See the full public table in [Supported PLC Registers](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/SUPPORTED_REGISTERS.md).
+
+## Documentation
+
+- [Getting Started](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/GETTING_STARTED.md)
+- [Supported PLC Registers](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/SUPPORTED_REGISTERS.md)
+- [Latest Communication Verification](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/LATEST_COMMUNICATION_VERIFICATION.md)
+- [User Guide](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/USER_GUIDE.md)
+- [Example Flows](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/README.md)
+- [Documentation Index](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/index.md)
+
+Maintainer-only notes and retained evidence live under `internal_docs/`.
+
+## What You Can Do
+
+- Binary 3E and 4E frames
+- TCP and UDP transport
+- reusable `slmp-connection`
+- high-level reads and writes through `slmp-read` and `slmp-write`
+- typed source selection for literal / `msg` / `flow` / `global` / `env`
+- per-request routing via `msg.target` or configured route sources
+- read output selection for object / array / single value
+- metadata emission selection for `msg.slmp`
+- configurable error handling with throw / `msg.error` / second output
+- connection control via `connect` / `disconnect` / `reinitialize` messages
+
+Set one explicit PLC type for each connection. The node stores it as `plcFamily` internally and derives `frameType`, access profile, and `X/Y` string-address rules from that selection.
+
+Supported canonical PLC type values:
+
+- `iq-f`
+- `iq-r`
+- `iq-l`
+- `mx-f`
+- `mx-r`
+- `qcpu`
+- `lcpu`
+- `qnu`
+- `qnudv`
+
+## Underlying JS Helper
+
+The package also exports the underlying SLMP helper library for the same read/write model used by the Node-RED nodes:
+
+```js
+const { SlmpClient, readNamed } = require("@fa_yoshinobu/node-red-contrib-plc-comm-slmp/lib/slmp");
+
+async function main() {
+  const client = new SlmpClient({
+    host: "192.168.250.100",
+    port: 1025,
+    plcFamily: "qnu",
+  });
+  const values = await readNamed(client, ["D300", "D300,4"]);
+  console.log(values);
+}
+```
+
+The helper validates address format, protocol constraints, and device-code support for the selected `plcFamily`, but does not pre-check PLC model-specific device ranges or upper bounds.
+If an address is outside the connected PLC's actual range, the PLC response is returned as the runtime error.
+
+## Current Public Register Scope
+
+- bit devices: `SM`, `X`, `Y`, `M`, `L`, `F`, `V`, `B`, `TS`, `TC`, `LTS`, `LTC`, `STS`, `STC`, `LSTS`, `LSTC`, `CS`, `CC`, `LCS`, `LCC`, `SB`, `DX`, `DY`
+- word devices: `SD`, `D`, `W`, `TN`, `LTN`, `STN`, `LSTN`, `CN`, `LCN`, `SW`, `Z`, `LZ`, `R`, `ZR`, `RD`
+- typed views: `:S`, `:I` (alias of `:S`), `:D`, `:L`, `:F`
+- string/count views: `,count`, `:STR`, `DSTR`
+- word-bit view: `.bit`
+
+Public device-code support by `plcFamily`:
+
+| PLC type | Public device codes accepted by the high-level API and Node-RED editor |
+| --- | --- |
+| `iq-r`, `iq-l`, `mx-f`, `mx-r` | `SM`, `SD`, `X`, `Y`, `M`, `L`, `F`, `V`, `B`, `D`, `W`, `TS`, `TC`, `TN`, `LTS`, `LTC`, `LTN`, `STS`, `STC`, `STN`, `LSTS`, `LSTC`, `LSTN`, `CS`, `CC`, `CN`, `LCS`, `LCC`, `LCN`, `SB`, `SW`, `DX`, `DY`, `Z`, `LZ`, `R`, `ZR`, `RD` |
+| `iq-f` | `SM`, `SD`, `X`, `Y`, `M`, `L`, `F`, `B`, `D`, `W`, `TS`, `TC`, `TN`, `STS`, `STC`, `STN`, `CS`, `CC`, `CN`, `LCS`, `LCC`, `LCN`, `SB`, `SW`, `Z`, `LZ`, `R` |
+| `qcpu` | `SM`, `SD`, `X`, `Y`, `M`, `L`, `F`, `V`, `B`, `D`, `W`, `TS`, `TC`, `TN`, `STS`, `STC`, `STN`, `CS`, `CC`, `CN`, `SB`, `SW`, `DX`, `DY`, `Z`, `R`, `ZR` |
+| `lcpu`, `qnu`, `qnudv` | `SM`, `SD`, `X`, `Y`, `M`, `L`, `F`, `V`, `B`, `D`, `W`, `TS`, `TC`, `TN`, `STS`, `STC`, `STN`, `CS`, `CC`, `CN`, `SB`, `SW`, `DX`, `DY`, `Z`, `R`, `ZR` |
+
+Validated public hardware summary:
+
+- `FX5UC-32MT/D`
+- `Q06UDVCPU`
+- `R08CPU`
+
+## Example Flows
+
+- [`slmp-demo.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-demo.json): combined demo
+- [`slmp-basic-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-basic-read-write.json): scalar, float, and bit read/write over TCP
+- [`slmp-array-string.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-array-string.json): array and string read/write over TCP
+- [`slmp-control-error.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-control-error.json): control messages, `msg` source, and second-output errors
+- [`slmp-device-matrix.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-device-matrix.json): one-by-one and run-all high-level read, write, and readback across the matrix catalog with one outstanding request at a time, status lamp feedback, completed-result history, run summary, unsupported-device skip records, and JSONL logging in `Node-RED userDir/logs/slmp-device-matrix-<session>.jsonl`
+- [`slmp-routing.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-routing.json): per-request routing with `msg.target`
+- [`slmp-udp-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-udp-read-write.json): basic UDP read/write
+
+The device-matrix flow records `plcFamily` in each JSONL result, keeps one outstanding request at a time, and summarizes `OK`, `SKIPPED`, `NG`, mismatch, timeout, and pending counts.
+
+## Known Limitations
+
+- the high-level Node-RED surface requires explicit PLC type selection
+- `.bit,count` is not supported
+- a single client connection keeps requests serialized by default
+- the read and write nodes keep the caller-visible logical request shape and do not silently retry with a different fallback split semantics
+- `G` and `HG` are not part of the current public high-level register table
+
+## Development
+
+Run the local test suite:
+
+```bash
+cmd /c npm.cmd test
+```
+
+## Notes
+
+- `.bit` notation is only valid for word devices such as `D50.3`
+- direct bit devices should be addressed directly as `M1000`, `X1F`, `Y20`
+- `LTN`, `LSTN`, `LCN`, and `LZ` default to 32-bit `:D` access in high-level helpers; iQ-F `LZ` samples should use `LZ0` or `LZ1`
+- `LCN` current-value reads and writes use random dword access in the high-level helpers
+- `LTS`, `LTC`, `LSTS`, and `LSTC` state reads use the long timer 4-word decode helpers
+- `LCS` and `LCC` state reads use direct bit read; high-level state writes use random bit write (`0x1402`)
+- low-level direct bit writes are guarded for `LTS`/`LTC`/`LSTS`/`LSTC`/`LCS`/`LCC`
+- `X/Y` string addresses require explicit PLC type selection
+- `iq-f` interprets `X/Y` string addresses in octal, while other supported families use hexadecimal `X/Y`
+- random read batching follows the Python helper layer for batchable word devices

package/docsrc/assets/README.md

@@ -1,10 +1,10 @@
-# Assets
-
-See also:
-
-- [Project README](../../README.md)
-- [Documentation Index](../index.md)
-
-Place shared documentation assets for `@fa_yoshinobu/node-red-contrib-plc-comm-slmp` here.
-
-- `node-red-slmp.png`: README hero image for the Node-RED SLMP package
+# Assets
+
+See also:
+
+- [Project README](../../README.md)
+- [Documentation Index](../index.md)
+
+Place shared documentation assets for `@fa_yoshinobu/node-red-contrib-plc-comm-slmp` here.
+
+- `node-red-slmp.png`: README hero image for the Node-RED SLMP package

package/docsrc/index.md

@@ -1,11 +1,11 @@
-# Documentation Index
-
-Documentation landing page for `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`.
-
-- [Project README](../README.md)
-- [Changelog](../CHANGELOG.md)
-- [Getting Started](user/GETTING_STARTED.md)
-- [Supported PLC Registers](user/SUPPORTED_REGISTERS.md)
-- [Latest Communication Verification](user/LATEST_COMMUNICATION_VERIFICATION.md)
-- [User Guide](user/USER_GUIDE.md)
-- [Example Flows](../examples/flows/README.md)
+# Documentation Index
+
+Documentation landing page for `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`.
+
+- [Project README](../README.md)
+- [Changelog](../CHANGELOG.md)
+- [Getting Started](user/GETTING_STARTED.md)
+- [Supported PLC Registers](user/SUPPORTED_REGISTERS.md)
+- [Latest Communication Verification](user/LATEST_COMMUNICATION_VERIFICATION.md)
+- [User Guide](user/USER_GUIDE.md)
+- [Example Flows](../examples/flows/README.md)