@fa_yoshinobu/node-red-contrib-plc-comm-slmp 0.2.1 → 0.2.12

package/CHANGELOG.md

@@ -1,13 +1,80 @@
-# Changelog
+# Changelog
+
+## Unreleased
 
-## 0.2.1 - 2026-03-28
+## 0.2.12 - 2026-05-02
 
-- 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
+- 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.0 - 2026-03-28
+## 0.2.11 - 2026-05-02
 
-- 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
+- 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/README.md

@@ -1,295 +1,228 @@
-# Node-RED SLMP Nodes for Mitsubishi PLCs
-
-[![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 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`
-
-## 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
-
-## Release information
-
+[![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.1`
+- 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
-```
-
+
+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
 
-## Documentation
-
-- [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)
-- [Future Device Support](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/TODO.md)
-- [Maintainer Notes](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/maintainer/ARCHITECTURE.md)
-- [Validation Reports Directory](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/tree/main/docsrc/validation/reports)
-- [Documentation Index](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/index.md)
-
-## Current scope
-
-- Binary 3E and 4E frames
-- TCP and UDP transport
-- Reusable `slmp-connection` config node
-- `slmp-read` node powered by `readNamed`
-- `slmp-write` node powered by `writeNamed`
-- 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`: `full` / `minimal` / `off`
-- configurable error handling with throw / `msg.error` / second output
-- connection control via `connect` / `disconnect` / `reinitialize` messages
-- editor-side validation for connection ranges, literal addresses, literal updates, and route JSON
-- importable example flow under `examples/flows/`
-- Local tests for codec and high-level helpers
-
-Set `frame type` and `PLC series` explicitly for each connection.
-
-Validated PLC models:
-
-- `FX5UC-32MT/D`
-- `Q06UDVCPU`
-- `R08CPU`
-
-## Supported devices
-
-Supported bit devices:
-
-- `SM`, `X`, `Y`, `M`, `L`, `F`, `V`, `B`
-- `TS`, `TC`, `STS`, `STC`
-- `CS`, `CC`
-- `SB`, `DX`, `DY`
-
-Supported word devices:
-
-- `SD`, `D`, `W`
-- `TN`, `LTN`, `STN`, `LSTN`
-- `CN`, `LCN`
-- `SW`
-- `Z`
-- `R`, `ZR`, `RD`
-
-Address notes:
-
-- `X`, `Y`, `B`, `W`, `SB`, `SW`, `DX`, and `DY` use hexadecimal device numbers
-- most other devices use decimal numbers
-- word devices support `.bit`, for example `D50.3`
-- count and string forms work on supported devices, for example `D300,10`, `M1000,8`, and `DSTR320,10`
-- `LTN`, `LSTN`, and `LCN` default to 32-bit current-value access in the high-level nodes
-- future device support candidates such as `LTS`, `LTC`, `LSTS`, `LSTC`, `LCS`, `LCC`, `LZ`, `G`, and `HG` are tracked in the [Future Device Support list](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/TODO.md)
-
-## Nodes
-
-### `slmp-connection`
-
-Holds the transport and SLMP profile settings:
-
-- host / port
-- transport: `tcp` or `udp`
-- timeout in milliseconds
-- PLC series: `ql` or `iqr`
-- frame type: `3e` or `4e`
-- target routing fields
-
-### `slmp-read`
-
-Reads one or more addresses and writes the result to `msg.payload`.
-
-Configured addresses can be overridden by:
-
-- `msg.addresses` as an array or string
-- `msg.payload` as an array or string
-
-Configured source modes:
-
-- literal editor text
-- `msg`
-- `flow`
-- `global`
-- `env`
-
-Examples:
-
-```text
-D100
-D100,10
-D200:F
-D200:F,4
-D50.3
-M1000
-M1000,8
-D100:STR,10
-DSTR100,10
-```
-
-Notes:
-
-- `,count` returns an array for numeric and direct-bit reads
-- `:STR,<length>` reads or writes a UTF-8 byte string packed two bytes per word
-- `DSTR100,10` is accepted as a compatibility alias for `D100:STR,10`
-- `LTN`, `LSTN`, and `LCN` use high-level 32-bit current values by default
-- when you send multiple addresses as a string, newline-separated input is the clearest form
-- per-request routing can be supplied as `msg.target`, `msg.slmp.target`, or a configured route source
-- metadata mode can keep full `msg.slmp`, emit only `target` plus `itemCount`, or leave `msg.slmp` unchanged
-- read errors can throw, attach to `msg.error`, or go to a second output
-- output can be object, array, or single value when one address is requested
-- send `msg.connect`, `msg.disconnect`, or `msg.reinitialize` as `true`, or use `msg.topic`, to control the shared connection
-
-### `slmp-write`
-
-Writes one or more addresses.
-
-Preferred dynamic input:
-
-```json
-{
-  "D100": 42,
-  "D100,3": [10, 11, 12],
-  "D200:F": 3.14,
-  "D200:F,2": [1.25, -2.5],
-  "D50.3": true,
-  "D100:STR,10": "HELLO"
-}
-```
-
-Accepted sources:
-
-- `msg.updates`
-- `msg.payload`
-- `msg.address` + optional `msg.dtype` + `msg.value`
-- static JSON or `address=value` lines in the editor
-- configured `msg` / `flow` / `global` / `env` sources
-
-Write errors can throw, attach to `msg.error`, or go to a second output.
-Send `msg.connect`, `msg.disconnect`, or `msg.reinitialize` to control the shared connection from the write node too.
-Route overrides use the same `target` object shape as reads.
-Metadata mode can keep full `msg.slmp`, emit only `target` plus `itemCount`, or leave `msg.slmp` unchanged.
-
-## Route overrides
-
-Use a `target` object when one request needs a different route than the shared connection default:
-
-```json
-{
-  "addresses": ["D300,4", "DSTR320,10"],
-  "target": {
-    "network": 0,
-    "station": 255,
-    "moduleIO": "03FF",
-    "multidrop": 0
-  }
-}
-```
-
-The editor validates connection ranges, literal address lists, literal update payloads, and literal route JSON before save.
-
-## Example flows
-
-Read:
-
-```json
-{
-  "addresses": ["D100", "D100,3", "D200:F", "D200:F,2", "D50.3", "D100:STR,10"]
-}
-```
-
-Write:
-
-```json
-{
-  "payload": {
-    "D100": 42,
-    "D100,3": [10, 11, 12],
-    "D50.3": true,
-    "D100:STR,10": "HELLO"
-  }
-}
-```
-
-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):
-
-- [`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`
+### 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
 
-Recommended first import:
-
-- start with [`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) if you only need to confirm a single PLC over TCP
-- use [`slmp-array-string.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-array-string.json) when you want to validate `,count` and string handling immediately
-- use [`slmp-device-matrix.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-device-matrix.json) when you need to step through the matrix catalog one by one from the high-level nodes and keep a persistent verification log
-- use [`slmp-control-error.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-control-error.json) when you need `msg`-driven addresses, control messages, or second-output error routing
-
-## 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
-- Future high-level device support candidates are tracked in the [Future Device Support list](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/TODO.md)
-
-## 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
+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